1. Preamble
Copyright 2014-2022 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 Specification has been created under the Khronos Intellectual Property Rights Policy, which is Attachment A of the Khronos Group Membership Agreement available at https://www.khronos.org/files/member_agreement.pdf, and which defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'. Parties desiring to implement the Specification and make use of Khronos trademarks in relation to that implementation, and receive reciprocal patent license protection under the Khronos Intellectual Property Rights Policy must become Adopters and confirm the implementation as conformant under the process defined by Khronos for this Specification; see https://www.khronos.org/adopters.
This Specification contains substantially unmodified functionality from, and is a successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL.
Some parts of this Specification are purely informative and so are EXCLUDED from 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 includes normative references to external documents, only the specifically identified sections of those external documents are INCLUDED in the Scope of this Specification. If not created by Khronos, those external documents may contain contributions from non-members of Khronos not covered by the Khronos Intellectual Property Rights Policy.
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://www.khronos.org/registry/vulkan/specs/1.2/html/vkspec.html (core only) and https://www.khronos.org/registry/vulkan/specs/1.2-khr-extensions/html/vkspec.html (core with KHR extensions).
Vulkan and Khronos are registered trademarks of The Khronos Group Inc. ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of Apple Inc.; and OpenGL and OpenGL ES are registered trademarks of Hewlett Packard Enterprise, all used under license by Khronos. 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://www.khronos.org/registry/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://www.khronos.org/registry/DataFormat/specs/1.3/dataformat.1.3.html .
John Kessenich. SPIR-V Extended Instructions for GLSL, Version 1.00 (February 10, 2016). https://www.khronos.org/registry/spir-v/ .
John Kessenich, Boaz Ouriel, and Raun Krisch. SPIR-V Specification, Version 1.5, Revision 3, Unified (April 24, 2020). https://www.khronos.org/registry/spir-v/ .
Jon Leech. The Khronos Vulkan API Registry. https://www.khronos.org/registry/vulkan/specs/1.2/registry.html .
Jon Leech and Tobias Hector. Vulkan Documentation and Extensions: Procedures and Conventions. https://www.khronos.org/registry/vulkan/specs/1.2/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: video decode, video encode, graphics, compute, transfer and sparse memory management.
|
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 either perform actions (draw, dispatch, clear, copy, query/timestamp operations, begin/end subpass operations), set state (bind pipelines, descriptor sets, and buffers, set dynamic state, push constants, set render pass/subpass state), or perform synchronization (set/wait events, pipeline barrier, render pass/subpass dependencies). Some commands perform more than one of these tasks. 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, so that the application can alter or free this memory as soon as all the commands that acquired it have returned.
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
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:
-
VkQueueobjects cannot be explicitly destroyed. Instead, they are implicitly destroyed when theVkDeviceobject they are retrieved from is destroyed. -
Destroying a pool object implicitly frees all objects allocated from that pool. Specifically, destroying
VkCommandPoolfrees allVkCommandBufferobjects that were allocated from it, and destroyingVkDescriptorPoolfrees allVkDescriptorSetobjects that were allocated from it. -
VkDeviceobjects can be destroyed when allVkQueueobjects 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
-
-
VkPhysicalDeviceobjects cannot be explicitly destroyed. Instead, they are implicitly destroyed when theVkInstanceobject they are retrieved from is destroyed. -
VkInstanceobjects can be destroyed once allVkDeviceobjects created from any of itsVkPhysicalDeviceobjects 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, all commandBuffer parameters that need to be externally
synchronized imply that the commandPool that was passed in when
creating that command buffer 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. A enumerant is valid if:
-
The enumerant is defined as part of the enumerated type.
-
The enumerant is not the special value (suffixed with
_MAX_ENUM1) defined for the enumerated type.- 1
-
This special value exists only to ensure that C
enumtypes are 32 bits in size. It is not part of the API, and should not be used by applications.
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
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.
A bit flag is valid if:
-
The bit flag is defined as part of the
Vk*FlagBitstype, where the bits type is obtained by taking the flag type and replacing the trailingFlagswithFlagBits. For example, a flag value of type VkColorComponentFlags must contain only bit flags defined by VkColorComponentFlagBits. -
The flag is allowed in the context in which it is being used. For example, in some cases, certain bit flags or combinations of bit flags are mutually exclusive.
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.
A bit flag is valid if:
-
The bit flag is defined as part of the
Vk*FlagBits2type, where the bits type is obtained by taking the flag type and replacing the trailingFlags2withFlagBits2. For example, a flag value of type VkAccessFlags2KHR must contain only bit flags defined by VkAccessFlagBits2KHR. -
The flag is allowed in the context in which it is being used. For example, in some cases, certain bit flags or combinations of bit flags are mutually exclusive.
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;
-
sTypeis the structure type of the structure being iterated through. -
pNextisNULLor 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;
-
sTypeis the structure type of the structure being iterated through. -
pNextisNULLor 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 functionality or behavior added by a device extension to the API 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR = -1000023000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_PICTURE_LAYOUT_NOT_SUPPORTED_KHR = -1000023001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_PROFILE_OPERATION_NOT_SUPPORTED_KHR = -1000023002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHR = -1000023003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHR = -1000023004,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHR = -1000023005,
#endif
// Provided by VK_EXT_image_drm_format_modifier
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT = -1000158000,
// Provided by VK_KHR_global_priority
VK_ERROR_NOT_PERMITTED_KHR = -1000174001,
// Provided by VK_EXT_full_screen_exclusive
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT = -1000255000,
// Provided by VK_KHR_deferred_host_operations
VK_THREAD_IDLE_KHR = 1000268000,
// Provided by VK_KHR_deferred_host_operations
VK_THREAD_DONE_KHR = 1000268001,
// Provided by VK_KHR_deferred_host_operations
VK_OPERATION_DEFERRED_KHR = 1000268002,
// Provided by VK_KHR_deferred_host_operations
VK_OPERATION_NOT_DEFERRED_KHR = 1000268003,
// Provided by VK_EXT_image_compression_control
VK_ERROR_COMPRESSION_EXHAUSTED_EXT = -1000338000,
// 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_SUCCESSCommand successfully completed -
VK_NOT_READYA fence or query has not yet completed -
VK_TIMEOUTA wait operation has not completed in the specified time -
VK_EVENT_SETAn event is signaled -
VK_EVENT_RESETAn event is unsignaled -
VK_INCOMPLETEA return array was too small for the result -
VK_SUBOPTIMAL_KHRA swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully. -
VK_THREAD_IDLE_KHRA 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_KHRA deferred operation is not complete but there is no work remaining to assign to additional threads. -
VK_OPERATION_DEFERRED_KHRA deferred operation was requested and at least some of the work was deferred. -
VK_OPERATION_NOT_DEFERRED_KHRA deferred operation was requested and no operations were deferred. -
VK_PIPELINE_COMPILE_REQUIREDA requested pipeline creation would have required compilation, but the application requested compilation to not be performed.
-
VK_ERROR_OUT_OF_HOST_MEMORYA host memory allocation has failed. -
VK_ERROR_OUT_OF_DEVICE_MEMORYA device memory allocation has failed. -
VK_ERROR_INITIALIZATION_FAILEDInitialization of an object could not be completed for implementation-specific reasons. -
VK_ERROR_DEVICE_LOSTThe logical or physical device has been lost. See Lost Device -
VK_ERROR_MEMORY_MAP_FAILEDMapping of a memory object has failed. -
VK_ERROR_LAYER_NOT_PRESENTA requested layer is not present or could not be loaded. -
VK_ERROR_EXTENSION_NOT_PRESENTA requested extension is not supported. -
VK_ERROR_FEATURE_NOT_PRESENTA requested feature is not supported. -
VK_ERROR_INCOMPATIBLE_DRIVERThe requested version of Vulkan is not supported by the driver or is otherwise incompatible for implementation-specific reasons. -
VK_ERROR_TOO_MANY_OBJECTSToo many objects of the type have already been created. -
VK_ERROR_FORMAT_NOT_SUPPORTEDA requested format is not supported on this device. -
VK_ERROR_FRAGMENTED_POOLA 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_KHRA surface is no longer available. -
VK_ERROR_NATIVE_WINDOW_IN_USE_KHRThe 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_KHRA 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_KHRThe 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_NVOne or more shaders failed to compile or link. More details are reported back to the application viaVK_EXT_debug_reportif enabled. -
VK_ERROR_OUT_OF_POOL_MEMORYA 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_POOLshould be returned instead. -
VK_ERROR_INVALID_EXTERNAL_HANDLEAn external handle is not a valid handle of the specified type. -
VK_ERROR_FRAGMENTATIONA descriptor pool creation has failed due to fragmentation. -
VK_ERROR_INVALID_DEVICE_ADDRESS_EXTA buffer creation failed because the requested address is not available. -
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESSA 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_EXTAn operation on a swapchain created withVK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXTfailed as it did not have exlusive full-screen access. This may occur due to implementation-dependent reasons, outside of the application’s control. -
VK_ERROR_COMPRESSION_EXHAUSTED_EXTAn 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_KHRThe requested VkImageUsageFlags are not supported. -
VK_ERROR_VIDEO_PICTURE_LAYOUT_NOT_SUPPORTED_KHRThe requested video picture layout is not supported. -
VK_ERROR_VIDEO_PROFILE_OPERATION_NOT_SUPPORTED_KHRA video profile operation specified via VkVideoProfileKHR::videoCodecOperationis not supported. -
VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHRFormat parameters in a requested VkVideoProfileKHR chain are not supported. -
VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHRCodec-specific parameters in a requested VkVideoProfileKHR chain are not supported. -
VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHRThe specified video Std header version is not supported. -
VK_ERROR_UNKNOWNAn 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
|
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.
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;
-
xis the x offset. -
yis 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;
-
xis the x offset. -
yis the y offset. -
zis 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;
-
widthis the width of the extent. -
heightis 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;
-
widthis the width of the extent. -
heightis the height of the extent. -
depthis 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;
-
offsetis a VkOffset2D specifying the rectangle offset. -
extentis 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 of VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, and thus
its sType member must equal that when 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_PROFILE_KHR = 1000023000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_CAPABILITIES_KHR = 1000023001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_PICTURE_RESOURCE_KHR = 1000023002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_GET_MEMORY_PROPERTIES_KHR = 1000023003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_BIND_MEMORY_KHR = 1000023004,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_SESSION_CREATE_INFO_KHR = 1000023005,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000023006,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_UPDATE_INFO_KHR = 1000023007,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_BEGIN_CODING_INFO_KHR = 1000023008,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_END_CODING_INFO_KHR = 1000023009,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_CODING_CONTROL_INFO_KHR = 1000023010,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_KHR = 1000023011,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_QUEUE_FAMILY_PROPERTIES_2_KHR = 1000023012,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_PROFILES_KHR = 1000023013,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_FORMAT_INFO_KHR = 1000023014,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_FORMAT_PROPERTIES_KHR = 1000023015,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_QUEUE_FAMILY_QUERY_RESULT_STATUS_PROPERTIES_2_KHR = 1000023016,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR = 1000024000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_STRUCTURE_TYPE_VIDEO_DECODE_CAPABILITIES_KHR = 1000024001,
#endif
// 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_VCL_FRAME_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_EXT = 1000038005,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_EMIT_PICTURE_PARAMETERS_EXT = 1000038006,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PROFILE_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_REFERENCE_LISTS_EXT = 1000038010,
#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_VCL_FRAME_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_EXT = 1000039005,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_EMIT_PICTURE_PARAMETERS_EXT = 1000039006,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PROFILE_EXT = 1000039007,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_REFERENCE_LISTS_EXT = 1000039008,
#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_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_CAPABILITIES_EXT = 1000040000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PICTURE_INFO_EXT = 1000040001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_MVC_EXT = 1000040002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PROFILE_EXT = 1000040003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_CREATE_INFO_EXT = 1000040004,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_ADD_INFO_EXT = 1000040005,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_DPB_SLOT_INFO_EXT = 1000040006,
#endif
// 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,
// 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_CAPABILITIES_EXT = 1000187000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_CREATE_INFO_EXT = 1000187001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_ADD_INFO_EXT = 1000187002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PROFILE_EXT = 1000187003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PICTURE_INFO_EXT = 1000187004,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_DPB_SLOT_INFO_EXT = 1000187005,
#endif
// 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_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_shader_atomic_float2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_2_FEATURES_EXT = 1000273000,
// 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_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_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
// 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_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_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_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_SUBRESOURCE_LAYOUT_2_EXT = 1000338002,
// Provided by VK_EXT_image_compression_control
VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_EXT = 1000338003,
// Provided by VK_EXT_image_compression_control
VK_STRUCTURE_TYPE_IMAGE_COMPRESSION_PROPERTIES_EXT = 1000338004,
// Provided by VK_EXT_4444_formats
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_4444_FORMATS_FEATURES_EXT = 1000340000,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_FEATURES_ARM = 1000342000,
// 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_VALVE_mutable_descriptor_type
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MUTABLE_DESCRIPTOR_TYPE_FEATURES_VALVE = 1000351000,
// Provided by VK_VALVE_mutable_descriptor_type
VK_STRUCTURE_TYPE_MUTABLE_DESCRIPTOR_TYPE_CREATE_INFO_VALVE = 1000351002,
// Provided by VK_EXT_vertex_input_dynamic_state
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_INPUT_DYNAMIC_STATE_FEATURES_EXT = 1000352000,
// Provided by VK_EXT_vertex_input_dynamic_state
VK_STRUCTURE_TYPE_VERTEX_INPUT_BINDING_DESCRIPTION_2_EXT = 1000352001,
// Provided by 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_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_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_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_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_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_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_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_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_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_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,
} 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);
-
instanceis the instance that the function pointer will be compatible with, orNULLfor commands not dependent on any instance. -
pNameis 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
instanceor 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,
vkGetInstanceProcAddrcan resolve itself with aNULLinstance 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::
apiVersionwhen creating the instance will always return a valid function pointer. Core commands beyond that version which are supported by the implementation may either returnNULLor a function pointer, though the function pointer 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
deviceor a child ofdevicee.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);
-
pApiVersionis 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);
-
pCreateInfois a pointer to a VkInstanceCreateInfo structure controlling creation of the instance. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pInstancepoints 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkInstanceCreateFlagBits indicating the behavior of the instance. -
pApplicationInfoisNULLor a pointer to aVkApplicationInfostructure. If notNULL, this information helps implementations recognize behavior inherent to classes of applications. VkApplicationInfo is defined in detail below. -
enabledLayerCountis the number of global layers to enable. -
ppEnabledLayerNamesis a pointer to an array ofenabledLayerCountnull-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. -
enabledExtensionCountis the number of global extensions to enable. -
ppEnabledExtensionNamesis a pointer to an array ofenabledExtensionCountnull-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.
// 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_KHRspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
disabledValidationCheckCountis the number of checks to disable. -
pDisabledValidationChecksis 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_EXTspecifies that all validation checks are disabled. -
VK_VALIDATION_CHECK_SHADERS_EXTspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
enabledValidationFeatureCountis the number of features to enable. -
pEnabledValidationFeaturesis a pointer to an array of VkValidationFeatureEnableEXT values specifying the validation features to be enabled. -
disabledValidationFeatureCountis the number of features to disable. -
pDisabledValidationFeaturesis 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_EXTspecifies 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_EXTspecifies that the validation layers reserve a descriptor set binding slot for their own use. The layer reports a value for VkPhysicalDeviceLimits::maxBoundDescriptorSetsthat 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_EXTspecifies 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_EXTspecifies that the layers will processdebugPrintfEXToperations in shaders and send the resulting output to the debug callback. This feature is disabled by default. -
VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXTspecifies 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_EXTspecifies that all validation checks are disabled. -
VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXTspecifies that shader validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXTspecifies that thread safety validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXTspecifies that stateless parameter validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXTspecifies that object lifetime validation is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXTspecifies 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_EXTspecifies that protection against duplicate non-dispatchable object handles is disabled. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_SHADER_VALIDATION_CACHE_EXTspecifies 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 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pApplicationNameisNULLor is a pointer to a null-terminated UTF-8 string containing the name of the application. -
applicationVersionis an unsigned integer variable containing the developer-supplied version number of the application. -
pEngineNameisNULLor is a pointer to a null-terminated UTF-8 string containing the name of the engine (if any) used to create the application. -
engineVersionis an unsigned integer variable containing the developer-supplied version number of the engine used to create the application. -
apiVersionmust be the highest version of Vulkan that the application is designed to use, encoded as described in Version Numbers. The patch version number specified inapiVersionis ignored when creating an instance object. Only the major and minor versions of the instance must match those 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 |
Implicit layers must be disabled if they do not support a version at least
as high as apiVersion.
See the “Architecture of the Vulkan Loader
Interfaces” document for additional information.
|
Note
Providing a |
To destroy an instance, call:
// Provided by VK_VERSION_1_0
void vkDestroyInstance(
VkInstance instance,
const VkAllocationCallbacks* pAllocator);
-
instanceis the handle of the instance to destroy. -
pAllocatorcontrols 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);
-
instanceis a handle to a Vulkan instance previously created with vkCreateInstance. -
pPhysicalDeviceCountis a pointer to an integer related to the number of physical devices available or queried, as described below. -
pPhysicalDevicesis eitherNULLor a pointer to an array ofVkPhysicalDevicehandles.
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);
-
physicalDeviceis the handle to the physical device whose properties will be queried. -
pPropertiesis 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;
-
apiVersionis the version of Vulkan supported by the device, encoded as described in Version Numbers. -
driverVersionis the vendor-specified version of the driver. -
vendorIDis a unique identifier for the vendor (see below) of the physical device. -
deviceIDis a unique identifier for the physical device among devices available from the vendor. -
deviceTypeis a VkPhysicalDeviceType specifying the type of device. -
deviceNameis an array ofVK_MAX_PHYSICAL_DEVICE_NAME_SIZEcharcontaining a null-terminated UTF-8 string which is the name of the device. -
pipelineCacheUUIDis an array ofVK_UUID_SIZEuint8_tvalues representing a universally unique identifier for the device. -
limitsis the VkPhysicalDeviceLimits structure specifying device-specific limits of the physical device. See Limits for details. -
sparsePropertiesis 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,
} 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);
-
physicalDeviceis the handle to the physical device whose properties will be queried. -
pPropertiesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
propertiesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
deviceUUIDis an array ofVK_UUID_SIZEuint8_tvalues representing a universally unique identifier for the device. -
driverUUIDis an array ofVK_UUID_SIZEuint8_tvalues representing a universally unique identifier for the driver build in use by the device. -
deviceLUIDis an array ofVK_LUID_SIZEuint8_tvalues representing a locally unique identifier for the device. -
deviceNodeMaskis auint32_tbitfield identifying the node within a linked device adapter corresponding to the device. -
deviceLUIDValidis a boolean value that will beVK_TRUEifdeviceLUIDcontains a valid LUID anddeviceNodeMaskcontains a valid node mask, andVK_FALSEif they do not. -
subgroupSizeis the default number of invocations in each subgroup.subgroupSizeis at least 1 if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BIT.subgroupSizeis a power-of-two. -
subgroupSupportedStagesis a bitfield of VkShaderStageFlagBits describing the shader stages that group operations with subgroup scope are supported in.subgroupSupportedStageswill have theVK_SHADER_STAGE_COMPUTE_BITbit set if any of the physical device’s queues supportVK_QUEUE_COMPUTE_BIT. -
subgroupSupportedOperationsis a bitmask of VkSubgroupFeatureFlagBits specifying the sets of group operations with subgroup scope supported on this device.subgroupSupportedOperationswill have theVK_SUBGROUP_FEATURE_BASIC_BITbit set if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BIT. -
subgroupQuadOperationsInAllStagesis a boolean specifying whether quad group operations are available in all stages, or are restricted to fragment and compute stages. -
pointClippingBehavioris a VkPointClippingBehavior value specifying the point clipping behavior supported by the implementation. -
maxMultiviewViewCountis one greater than the maximum view index that can be used in a subpass. -
maxMultiviewInstanceIndexis 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. -
protectedNoFaultspecifies 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. -
maxPerSetDescriptorsis 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. -
maxMemoryAllocationSizeis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
driverIDis a unique identifier for the driver of the physical device. -
driverNameis an array ofVK_MAX_DRIVER_NAME_SIZEcharcontaining a null-terminated UTF-8 string which is the name of the driver. -
driverInfois an array ofVK_MAX_DRIVER_INFO_SIZEcharcontaining a null-terminated UTF-8 string with additional information about the driver. -
conformanceVersionis the version of the Vulkan conformance test this driver is conformant against (see VkConformanceVersion). -
denormBehaviorIndependenceis a VkShaderFloatControlsIndependence value indicating whether, and how, denorm behavior can be set independently for different bit widths. -
roundingModeIndependenceis a VkShaderFloatControlsIndependence value indicating whether, and how, rounding modes can be set independently for different bit widths. -
shaderSignedZeroInfNanPreserveFloat16is a boolean value indicating whether sign of a zero, Nans and can be preserved in 16-bit floating-point computations. It also indicates whether theSignedZeroInfNanPreserveexecution mode can be used for 16-bit floating-point types. -
shaderSignedZeroInfNanPreserveFloat32is a boolean value indicating whether sign of a zero, Nans and can be preserved in 32-bit floating-point computations. It also indicates whether theSignedZeroInfNanPreserveexecution mode can be used for 32-bit floating-point types. -
shaderSignedZeroInfNanPreserveFloat64is a boolean value indicating whether sign of a zero, Nans and can be preserved in 64-bit floating-point computations. It also indicates whether theSignedZeroInfNanPreserveexecution mode can be used for 64-bit floating-point types. -
shaderDenormPreserveFloat16is a boolean value indicating whether denormals can be preserved in 16-bit floating-point computations. It also indicates whether theDenormPreserveexecution mode can be used for 16-bit floating-point types. -
shaderDenormPreserveFloat32is a boolean value indicating whether denormals can be preserved in 32-bit floating-point computations. It also indicates whether theDenormPreserveexecution mode can be used for 32-bit floating-point types. -
shaderDenormPreserveFloat64is a boolean value indicating whether denormals can be preserved in 64-bit floating-point computations. It also indicates whether theDenormPreserveexecution mode can be used for 64-bit floating-point types. -
shaderDenormFlushToZeroFloat16is a boolean value indicating whether denormals can be flushed to zero in 16-bit floating-point computations. It also indicates whether theDenormFlushToZeroexecution mode can be used for 16-bit floating-point types. -
shaderDenormFlushToZeroFloat32is a boolean value indicating whether denormals can be flushed to zero in 32-bit floating-point computations. It also indicates whether theDenormFlushToZeroexecution mode can be used for 32-bit floating-point types. -
shaderDenormFlushToZeroFloat64is a boolean value indicating whether denormals can be flushed to zero in 64-bit floating-point computations. It also indicates whether theDenormFlushToZeroexecution mode can be used for 64-bit floating-point types. -
shaderRoundingModeRTEFloat16is 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 theRoundingModeRTEexecution mode can be used for 16-bit floating-point types. -
shaderRoundingModeRTEFloat32is 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 theRoundingModeRTEexecution mode can be used for 32-bit floating-point types. -
shaderRoundingModeRTEFloat64is 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 theRoundingModeRTEexecution mode can be used for 64-bit floating-point types. -
shaderRoundingModeRTZFloat16is 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 theRoundingModeRTZexecution mode can be used for 16-bit floating-point types. -
shaderRoundingModeRTZFloat32is 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 theRoundingModeRTZexecution mode can be used for 32-bit floating-point types. -
shaderRoundingModeRTZFloat64is 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 theRoundingModeRTZexecution mode can be used for 64-bit floating-point types. -
maxUpdateAfterBindDescriptorsInAllPoolsis 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_BITbit 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. -
shaderUniformBufferArrayNonUniformIndexingNativeis 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. -
shaderSampledImageArrayNonUniformIndexingNativeis 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. -
shaderStorageBufferArrayNonUniformIndexingNativeis 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. -
shaderStorageImageArrayNonUniformIndexingNativeis 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. -
shaderInputAttachmentArrayNonUniformIndexingNativeis 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. -
robustBufferAccessUpdateAfterBindis a boolean value indicating whetherrobustBufferAccesscan be enabled in a device simultaneously withdescriptorBindingUniformBufferUpdateAfterBind,descriptorBindingStorageBufferUpdateAfterBind,descriptorBindingUniformTexelBufferUpdateAfterBind, and/ordescriptorBindingStorageTexelBufferUpdateAfterBind. If this isVK_FALSE, then eitherrobustBufferAccessmust be disabled or all of these update-after-bind features must be disabled. -
quadDivergentImplicitLodis a boolean value indicating whether implicit level of detail 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. -
maxPerStageDescriptorUpdateAfterBindSamplersis similar tomaxPerStageDescriptorSamplersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindUniformBuffersis similar tomaxPerStageDescriptorUniformBuffersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindStorageBuffersis similar tomaxPerStageDescriptorStorageBuffersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindSampledImagesis similar tomaxPerStageDescriptorSampledImagesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindStorageImagesis similar tomaxPerStageDescriptorStorageImagesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindInputAttachmentsis similar tomaxPerStageDescriptorInputAttachmentsbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageUpdateAfterBindResourcesis similar tomaxPerStageResourcesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindSamplersis similar tomaxDescriptorSetSamplersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindUniformBuffersis similar tomaxDescriptorSetUniformBuffersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindUniformBuffersDynamicis similar tomaxDescriptorSetUniformBuffersDynamicbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit 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. -
maxDescriptorSetUpdateAfterBindStorageBuffersis similar tomaxDescriptorSetStorageBuffersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindStorageBuffersDynamicis similar tomaxDescriptorSetStorageBuffersDynamicbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit 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. -
maxDescriptorSetUpdateAfterBindSampledImagesis similar tomaxDescriptorSetSampledImagesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindStorageImagesis similar tomaxDescriptorSetStorageImagesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindInputAttachmentsis similar tomaxDescriptorSetInputAttachmentsbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
supportedDepthResolveModesis a bitmask of VkResolveModeFlagBits indicating the set of supported depth resolve modes.VK_RESOLVE_MODE_SAMPLE_ZERO_BITmust be included in the set but implementations may support additional modes. -
supportedStencilResolveModesis a bitmask of VkResolveModeFlagBits indicating the set of supported stencil resolve modes.VK_RESOLVE_MODE_SAMPLE_ZERO_BITmust be included in the set but implementations may support additional modes.VK_RESOLVE_MODE_AVERAGE_BITmust not be included in the set. -
independentResolveNoneisVK_TRUEif 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. -
independentResolveisVK_TRUEif 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 supportsindependentResolvemust also supportindependentResolveNone. -
filterMinmaxSingleComponentFormatsis a boolean value indicating whether a minimum set of required formats support min/max filtering. -
filterMinmaxImageComponentMappingis a boolean value indicating whether the implementation supports non-identity component mapping of the image when doing min/max filtering. -
maxTimelineSemaphoreValueDifferenceindicates the maximum difference allowed by the implementation between the current value of a timeline semaphore and any pending signal or wait operations. -
framebufferIntegerColorSampleCountsis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
minSubgroupSizeis the minimum subgroup size supported by this device.minSubgroupSizeis at least one if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BIT.minSubgroupSizeis a power-of-two.minSubgroupSizeis less than or equal tomaxSubgroupSize.minSubgroupSizeis less than or equal tosubgroupSize. -
maxSubgroupSizeis the maximum subgroup size supported by this device.maxSubgroupSizeis at least one if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BIT.maxSubgroupSizeis a power-of-two.maxSubgroupSizeis greater than or equal tominSubgroupSize.maxSubgroupSizeis greater than or equal tosubgroupSize. -
maxComputeWorkgroupSubgroupsis the maximum number of subgroups supported by the implementation within a workgroup. -
requiredSubgroupSizeStagesis a bitfield of what shader stages support having a required subgroup size specified. -
maxInlineUniformBlockSizeis the maximum size in bytes of an inline uniform block binding. -
maxPerStageDescriptorInlineUniformBlockis 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_BLOCKcount against this limit. Only descriptor bindings in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. -
maxPerStageDescriptorUpdateAfterBindInlineUniformBlocksis similar tomaxPerStageDescriptorInlineUniformBlocksbut counts descriptor bindings from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetInlineUniformBlocksis 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_BLOCKcount against this limit. Only descriptor bindings in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. -
maxDescriptorSetUpdateAfterBindInlineUniformBlocksis similar tomaxDescriptorSetInlineUniformBlocksbut counts descriptor bindings from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxInlineUniformTotalSizeis 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_BLOCKcount against this limit. -
integerDotProduct8BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit unsigned dot product operations using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct8BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit signed dot product operations using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct8BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit mixed signedness dot product operations using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit unsigned dot product operations from operands packed into 32-bit integers using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedSignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit signed dot product operations from operands packed into 32-bit integers using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit mixed signedness dot product operations from operands packed into 32-bit integers using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit unsigned dot product operations using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit signed dot product operations using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit mixed signedness dot product operations using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit unsigned dot product operations using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit signed dot product operations using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit mixed signedness dot product operations using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit unsigned dot product operations using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit signed dot product operations using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit mixed signedness dot product operations using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit unsigned accumulating saturating dot product operations from operands packed into 32-bit integers using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedSignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit signed accumulating saturating dot product operations from operands packed into 32-bit integers using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit mixed signedness accumulating saturating dot product operations from operands packed into 32-bit integers using theOpSUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
storageTexelBufferOffsetAlignmentBytesis a byte alignment that is sufficient for a storage texel buffer of any format. The value must be a power of two. -
storageTexelBufferOffsetSingleTexelAlignmentindicates whether single texel alignment is sufficient for a storage texel buffer of any format. -
uniformTexelBufferOffsetAlignmentBytesis a byte alignment that is sufficient for a uniform texel buffer of any format. The value must be a power of two. -
uniformTexelBufferOffsetSingleTexelAlignmentindicates whether single texel alignment is sufficient for a uniform texel buffer of any format. -
maxBufferSizeis the maximum sizeVkBufferthat 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
deviceUUIDis an array ofVK_UUID_SIZEuint8_tvalues representing a universally unique identifier for the device. -
driverUUIDis an array ofVK_UUID_SIZEuint8_tvalues representing a universally unique identifier for the driver build in use by the device. -
deviceLUIDis an array ofVK_LUID_SIZEuint8_tvalues representing a locally unique identifier for the device. -
deviceNodeMaskis auint32_tbitfield identifying the node within a linked device adapter corresponding to the device. -
deviceLUIDValidis a boolean value that will beVK_TRUEifdeviceLUIDcontains a valid LUID anddeviceNodeMaskcontains a valid node mask, andVK_FALSEif 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 can not 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
driverIDis a unique identifier for the driver of the physical device. -
driverNameis an array ofVK_MAX_DRIVER_NAME_SIZEcharcontaining a null-terminated UTF-8 string which is the name of the driver. -
driverInfois an array ofVK_MAX_DRIVER_INFO_SIZEcharcontaining a null-terminated UTF-8 string with additional information about the driver. -
conformanceVersionis 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,
// 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;
-
majoris the major version number of the conformance test suite. -
minoris the minor version number of the conformance test suite. -
subminoris the subminor version number of the conformance test suite. -
patchis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pciDomainis the PCI bus domain. -
pciBusis the PCI bus identifier. -
pciDeviceis the PCI device identifier. -
pciFunctionis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
hasPrimaryis a boolean indicating whether the physical device has a DRM primary node. -
hasRenderis a boolean indicating whether the physical device has a DRM render node. -
primaryMajoris the DRM primary node major number, if any. -
primaryMinoris the DRM primary node minor number, if any. -
renderMajoris the DRM render node major number, if any. -
renderMinoris 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
integerDotProduct8BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit unsigned dot product operations using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct8BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit signed dot product operations using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct8BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit mixed signedness dot product operations using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit unsigned dot product operations from operands packed into 32-bit integers using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedSignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit signed dot product operations from operands packed into 32-bit integers using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct4x8BitPackedMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit mixed signedness dot product operations from operands packed into 32-bit integers using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit unsigned dot product operations using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit signed dot product operations using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct16BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit mixed signedness dot product operations using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit unsigned dot product operations using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit signed dot product operations using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct32BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit mixed signedness dot product operations using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit unsigned dot product operations using theOpUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit signed dot product operations using theOpSDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProduct64BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit mixed signedness dot product operations using theOpSUDotKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating8BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit unsigned accumulating saturating dot product operations from operands packed into 32-bit integers using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedSignedAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit signed accumulating saturating dot product operations from operands packed into 32-bit integers using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 8-bit mixed signedness accumulating saturating dot product operations from operands packed into 32-bit integers using theOpSUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating16BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 16-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating32BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 32-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitUnsignedAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit unsigned accumulating saturating dot product operations using theOpUDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitSignedAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit signed accumulating saturating dot product operations using theOpSDotAccSatKHRSPIR-V instruction is accelerated as defined below. -
integerDotProductAccumulatingSaturating64BitMixedSignednessAcceleratedis a boolean that will beVK_TRUEif the support for 64-bit mixed signedness accumulating saturating dot product operations using theOpSUDotAccSatKHRSPIR-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. |
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);
-
physicalDeviceis the handle to the physical device whose properties will be queried. -
pQueueFamilyPropertyCountis a pointer to an integer related to the number of queue families available or queried, as described below. -
pQueueFamilyPropertiesis eitherNULLor 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;
-
queueFlagsis a bitmask of VkQueueFlagBits indicating capabilities of the queues in this queue family. -
queueCountis the unsigned integer count of queues in this queue family. Each queue family must support at least one queue. -
timestampValidBitsis the unsigned integer count of meaningful bits in the timestamps written via vkCmdWriteTimestamp2 or vkCmdWriteTimestamp. The valid range for the count is 36..64 bits, or a value of 0, indicating no support for timestamps. Bits outside the valid range are guaranteed to be zeros. -
minImageTransferGranularityis 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, andzmembers of a VkOffset3D parameter must always be zero. -
The
width,height, anddepthmembers 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, andzof a VkOffset3D parameter must be integer multiples of Ax, Ay, and Az, respectively. -
widthof a VkExtent3D parameter must be an integer multiple of Ax, or elsex+widthmust equal the width of the image subresource corresponding to the parameter. -
heightof a VkExtent3D parameter must be an integer multiple of Ay, or elsey+heightmust equal the height of the image subresource corresponding to the parameter. -
depthof a VkExtent3D parameter must be an integer multiple of Az, or elsez+depthmust 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_QUEUE_VIDEO_DECODE_BIT_KHR = 0x00000020,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_encode_queue
VK_QUEUE_VIDEO_ENCODE_BIT_KHR = 0x00000040,
#endif
} VkQueueFlagBits;
-
VK_QUEUE_GRAPHICS_BITspecifies that queues in this queue family support graphics operations. -
VK_QUEUE_COMPUTE_BITspecifies that queues in this queue family support compute operations. -
VK_QUEUE_TRANSFER_BITspecifies that queues in this queue family support transfer operations. -
VK_QUEUE_SPARSE_BINDING_BITspecifies 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_KHRspecifies that queues in this queue family support Video Decode operations. -
VK_QUEUE_VIDEO_ENCODE_BIT_KHRspecifies that queues in this queue family support Video Encode operations. -
VK_QUEUE_PROTECTED_BITspecifies that queues in this queue family support theVK_DEVICE_QUEUE_CREATE_PROTECTED_BITbit. (see Protected Memory). If the physical device supports theprotectedMemoryfeature, 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 protected memory 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);
-
physicalDeviceis the handle to the physical device whose properties will be queried. -
pQueueFamilyPropertyCountis a pointer to an integer related to the number of queue families available or queried, as described in vkGetPhysicalDeviceQueueFamilyProperties. -
pQueueFamilyPropertiesis eitherNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queueFamilyPropertiesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
priorityCountis the number of supported global queue priorities in this queue family, and it must be greater than 0. -
prioritiesis an array ofVK_MAX_GLOBAL_PRIORITY_SIZE_EXTVkQueueGlobalPriorityEXT enums representing all supported global queue priorities in this queue family. The firstpriorityCountelements 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
checkpointExecutionStageMaskis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
checkpointExecutionStageMaskis 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.
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);
-
physicalDeviceis the handle to the physical device whose queue family performance query counter properties will be queried. -
queueFamilyIndexis the index into the queue family of the physical device we want to get properties for. -
pCounterCountis a pointer to an integer related to the number of counters available or queried, as described below. -
pCountersis eitherNULLor a pointer to an array of VkPerformanceCounterKHR structures. -
pCounterDescriptionsis eitherNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
unitis a VkPerformanceCounterUnitKHR specifying the unit that the counter data will record. -
scopeis a VkPerformanceCounterScopeKHR specifying the scope that the counter belongs to. -
storageis a VkPerformanceCounterStorageKHR specifying the storage type that the counter’s data uses. -
uuidis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPerformanceCounterDescriptionFlagBitsKHR indicating the usage behavior for the counter. -
nameis an array of sizeVK_MAX_DESCRIPTION_SIZE, containing a null-terminated UTF-8 string specifying the name of the counter. -
categoryis an array of sizeVK_MAX_DESCRIPTION_SIZE, containing a null-terminated UTF-8 string specifying the category of the counter. -
descriptionis 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 for 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_KHRspecifies that recording the counter may have a noticeable performance impact. -
VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHRspecifies 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);
-
instanceis a handle to a Vulkan instance previously created with vkCreateInstance. -
pPhysicalDeviceGroupCountis a pointer to an integer related to the number of device groups available or queried, as described below. -
pPhysicalDeviceGroupPropertiesis eitherNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
physicalDeviceCountis the number of physical devices in the group. -
physicalDevicesis an array ofVK_MAX_DEVICE_GROUP_SIZEVkPhysicalDevice handles representing all physical devices in the group. The firstphysicalDeviceCountelements of the array will be valid. -
subsetAllocationspecifies whether logical devices created from the group support allocating device memory on a subset of devices, via thedeviceMaskmember of the VkMemoryAllocateFlagsInfo. If this isVK_FALSE, then all device memory allocations are made across all physical devices in the group. IfphysicalDeviceCountis1, thensubsetAllocationmust 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);
-
physicalDevicemust be one of the device handles returned from a call tovkEnumeratePhysicalDevices(see Physical Device Enumeration). -
pCreateInfois a pointer to a VkDeviceCreateInfo structure containing information about how to create the device. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pDeviceis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
queueCreateInfoCountis the unsigned integer size of thepQueueCreateInfosarray. Refer to the Queue Creation section below for further details. -
pQueueCreateInfosis 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. -
enabledLayerCountis deprecated and ignored. -
ppEnabledLayerNamesis deprecated and ignored. See Device Layer Deprecation. -
enabledExtensionCountis the number of device extensions to enable. -
ppEnabledExtensionNamesis a pointer to an array ofenabledExtensionCountnull-terminated UTF-8 strings containing the names of extensions to enable for the created device. See the Extensions section for further details. -
pEnabledFeaturesisNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
physicalDeviceCountis the number of elements in thepPhysicalDevicesarray. -
pPhysicalDevicesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
overallocationBehavioris 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_AMDlets the implementation decide if overallocation is allowed. -
VK_MEMORY_OVERALLOCATION_BEHAVIOR_ALLOWED_AMDspecifies overallocation is allowed if platform permits. -
VK_MEMORY_OVERALLOCATION_BEHAVIOR_DISALLOWED_AMDspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkDeviceDiagnosticsConfigFlagBitsNV specifying addtional 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_NVenables the generation of debug information for shaders. -
VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_RESOURCE_TRACKING_BIT_NVenables driver side tracking of resources (images, buffers, etc.) used to augment the device fault information. -
VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_AUTOMATIC_CHECKPOINTS_BIT_NVenables 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_NVenables 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis 0 and reserved for future use. -
pfnUserCallbackis the application callback function to call. -
pUserDatais 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);
-
pCallbackDatacontains all the callback related data in the VkDeviceMemoryReportCallbackDataEXT structure. -
pUserDatais 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis 0 and reserved for future use. -
typeis a VkDeviceMemoryReportEventTypeEXT type specifying the type of event reported in thisVkDeviceMemoryReportCallbackDataEXTstructure. -
memoryObjectIdis the unique id for the underlying memory object as described below. -
sizeis the size of the memory object in bytes. IftypeisVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT,VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXTorVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT,sizeis a validVkDeviceSizevalue. Otherwise,sizeis undefined. -
objectTypeis a VkObjectType value specifying the type of the object associated with this device memory report event. IftypeisVK_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_EXTorVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT,objectTypeis a valid VkObjectType enum. Otherwise,objectTypeis undefined. -
objectHandleis the object this device memory report event is attributed to. IftypeisVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT,VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT,VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXTorVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT,objectHandleis a valid Vulkan handle of the type associated withobjectTypeas defined in theVkObjectTypeand Vulkan Handle Relationship table. Otherwise,objectHandleis undefined. -
heapIndexdescribes which memory heap this device memory allocation is made from. IftypeisVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXTorVK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT,heapIndexcorresponds to one of the valid heaps from the VkPhysicalDeviceMemoryProperties structure. Otherwise,heapIndexis 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_EXTspecifies this event corresponds to the allocation of an internal device memory object or a VkDeviceMemory. -
VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXTspecifies this event corresponds to the deallocation of an internally-allocated device memory object or a VkDeviceMemory. -
VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXTspecifies this event corresponds to the import of an external memory object. -
VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXTspecifies this event is the release of an imported external memory object. -
VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXTspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
privateDataSlotRequestCountis 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 commands that return
a VkResult may return VK_ERROR_DEVICE_LOST.
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);
-
deviceis the logical device to destroy. -
pAllocatorcontrols 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask indicating behavior of the queues. -
queueFamilyIndexis 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 thepQueueFamilyPropertiesarray that was returned byvkGetPhysicalDeviceQueueFamilyProperties. -
queueCountis an unsigned integer specifying the number of queues to create in the queue family indicated byqueueFamilyIndex, and with the behavior specified byflags. -
pQueuePrioritiesis a pointer to an array ofqueueCountnormalized 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_BITspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
globalPriorityis 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_KHRis below the system default. Useful for non-interactive tasks. -
VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHRis the system default priority. -
VK_QUEUE_GLOBAL_PRIORITY_HIGH_KHRis above the system default. -
VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHRis 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);
-
deviceis the logical device that owns the queue. -
queueFamilyIndexis the index of the queue family to which the queue belongs. -
queueIndexis the index within this queue family of the queue to retrieve. -
pQueueis 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);
-
deviceis the logical device that owns the queue. -
pQueueInfois a pointer to a VkDeviceQueueInfo2 structure, describing parameters of the device queue to be retrieved. -
pQueueis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. ThepNextchain ofVkDeviceQueueInfo2can be used to provide additional device queue parameters tovkGetDeviceQueue2. -
flagsis a VkDeviceQueueCreateFlags value indicating the flags used to create the device queue. -
queueFamilyIndexis the index of the queue family to which the queue belongs. -
queueIndexis 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);
-
deviceis the logical device that creates the command pool. -
pCreateInfois a pointer to a VkCommandPoolCreateInfo structure specifying the state of the command pool object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pCommandPoolis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkCommandPoolCreateFlagBits indicating usage behavior for the pool and command buffers allocated from it. -
queueFamilyIndexdesignates 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_BITspecifies 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_BITallows 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, thenvkResetCommandBuffermust not be called for any command buffer allocated from that pool. -
VK_COMMAND_POOL_CREATE_PROTECTED_BITspecifies 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);
-
deviceis the logical device that owns the command pool. -
commandPoolis the command pool to trim. -
flagsis 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 re-use 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);
-
deviceis the logical device that owns the command pool. -
commandPoolis the command pool to reset. -
flagsis 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_BITspecifies 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);
-
deviceis the logical device that destroys the command pool. -
commandPoolis the handle of the command pool to destroy. -
pAllocatorcontrols 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);
-
deviceis the logical device that owns the command pool. -
pAllocateInfois a pointer to aVkCommandBufferAllocateInfostructure describing parameters of the allocation. -
pCommandBuffersis 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 thecommandBufferCountmember 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
commandPoolis the command pool from which the command buffers are allocated. -
levelis a VkCommandBufferLevel value specifying the command buffer level. -
commandBufferCountis 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_PRIMARYspecifies a primary command buffer. -
VK_COMMAND_BUFFER_LEVEL_SECONDARYspecifies a secondary command buffer.
To reset a command buffer, call:
// Provided by VK_VERSION_1_0
VkResult vkResetCommandBuffer(
VkCommandBuffer commandBuffer,
VkCommandBufferResetFlags flags);
-
commandBufferis the command buffer to reset. The command buffer can be in any state other than pending, and is moved into the initial state. -
flagsis 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_BITspecifies 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.commandBufferis 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);
-
deviceis the logical device that owns the command pool. -
commandPoolis the command pool from which the command buffers were allocated. -
commandBufferCountis the length of thepCommandBuffersarray. -
pCommandBuffersis 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);
-
commandBufferis the handle of the command buffer which is to be put in the recording state. -
pBeginInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkCommandBufferUsageFlagBits specifying usage behavior for the command buffer. -
pInheritanceInfois a pointer to aVkCommandBufferInheritanceInfostructure, used ifcommandBufferis 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_BITspecifies 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_BITspecifies 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_BITspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
renderPassis a VkRenderPass object defining which render passes theVkCommandBufferwill be compatible with and can be executed within. -
subpassis the index of the subpass within the render pass instance that theVkCommandBufferwill be executed within. -
framebuffercan refer to the VkFramebuffer object that theVkCommandBufferwill 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.
-
occlusionQueryEnablespecifies 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. -
queryFlagsspecifies 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_BITbit, 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_BITbit. -
pipelineStatisticsis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
conditionalRenderingEnablespecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
transformis a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to the render pass. -
renderAreais 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
viewportScissor2Dspecifies whether the listed dynamic state is inherited. -
viewportDepthCountspecifies the maximum number of viewports to inherit. WhenviewportScissor2DisVK_FALSE, the behavior is as if this value is zero. -
pViewportDepthsis 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
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
pCommandBuffersarray 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::minDepthor VkViewport::maxDepthare 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;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
flagsis a bitmask of VkRenderingFlagBits used by the render pass instance. -
viewMaskis the view mask used for rendering. -
colorAttachmentCountis the number of color attachments specified in the render pass instance. -
pColorAttachmentFormatsis a pointer to an array of VkFormat values defining the format of color attachments. -
depthAttachmentFormatis a VkFormat value defining the format of the depth attachment. -
stencilAttachmentFormatis a VkFormat value defining the format of the stencil attachment. -
rasterizationSamplesis 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.
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;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
colorAttachmentCountis the number of color attachments specified in a render pass instance. -
pColorAttachmentSamplesis a pointer to an array of VkSampleCountFlagBits values defining the sample count of color attachments. -
depthStencilAttachmentSamplesis 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 present 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);
-
commandBufferis the command buffer to complete recording.
If there was an error during recording, the application will be notified by
an unsuccessful return code returned by vkEndCommandBuffer.
If the application wishes to further use the command buffer, the command
buffer must be reset.
The command buffer must have been in the recording state, and is moved to the executable state.
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);
-
queueis the queue that the command buffers will be submitted to. -
submitCountis the number of elements in thepSubmitsarray. -
pSubmitsis a pointer to an array of VkSubmitInfo2 structures, each specifying a command buffer submission batch. -
fenceis an optional handle to a fence to be signaled once all submitted command buffers have completed execution. Iffenceis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkSubmitFlagBits. -
waitSemaphoreInfoCountis the number of elements inpWaitSemaphoreInfos. -
pWaitSemaphoreInfosis a pointer to an array of VkSemaphoreSubmitInfo structures defining semaphore wait operations. -
commandBufferInfoCountis the number of elements inpCommandBufferInfosand the number of command buffers to execute in the batch. -
pCommandBufferInfosis a pointer to an array of VkCommandBufferSubmitInfo structures describing command buffers to execute in the batch. -
signalSemaphoreInfoCountis the number of elements inpSignalSemaphoreInfos. -
pSignalSemaphoreInfosis 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_BITspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreis a VkSemaphore affected by this operation. -
valueis either the value used to signalsemaphoreor the value waited on bysemaphore, ifsemaphoreis a timeline semaphore. Otherwise it is ignored. -
stageMaskis 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. -
deviceIndexis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
commandBufferis a VkCommandBuffer to be submitted for execution. -
deviceMaskis a bitmask indicating which devices in a device group execute the command buffer. AdeviceMaskof0is 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);
-
queueis the queue that the command buffers will be submitted to. -
submitCountis the number of elements in thepSubmitsarray. -
pSubmitsis a pointer to an array of VkSubmitInfo structures, each specifying a command buffer submission batch. -
fenceis an optional handle to a fence to be signaled once all submitted command buffers have completed execution. Iffenceis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
waitSemaphoreCountis the number of semaphores upon which to wait before executing the command buffers for the batch. -
pWaitSemaphoresis 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. -
pWaitDstStageMaskis a pointer to an array of pipeline stages at which each corresponding semaphore wait will occur. -
commandBufferCountis the number of command buffers to execute in the batch. -
pCommandBuffersis a pointer to an array of VkCommandBuffer handles to execute in the batch. -
signalSemaphoreCountis the number of semaphores to be signaled once the commands specified inpCommandBuffershave completed execution. -
pSignalSemaphoresis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
waitSemaphoreValueCountis the number of semaphore wait values specified inpWaitSemaphoreValues. -
pWaitSemaphoreValuesis a pointer to an array ofwaitSemaphoreValueCountvalues for the corresponding semaphores in VkSubmitInfo::pWaitSemaphoresto wait for. -
signalSemaphoreValueCountis the number of semaphore signal values specified inpSignalSemaphoreValues. -
pSignalSemaphoreValuesis a pointer to an arraysignalSemaphoreValueCountvalues for the corresponding semaphores in VkSubmitInfo::pSignalSemaphoresto 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
waitSemaphoreValuesCountis the number of semaphore wait values specified inpWaitSemaphoreValues. -
pWaitSemaphoreValuesis a pointer to an array ofwaitSemaphoreValuesCountvalues for the corresponding semaphores in VkSubmitInfo::pWaitSemaphoresto wait for. -
signalSemaphoreValuesCountis the number of semaphore signal values specified inpSignalSemaphoreValues. -
pSignalSemaphoreValuesis a pointer to an array ofsignalSemaphoreValuesCountvalues for the corresponding semaphores in VkSubmitInfo::pSignalSemaphoresto 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
acquireCountis the number of entries in thepAcquireSyncs,pAcquireKeys, andpAcquireTimeoutsarrays. -
pAcquireSyncsis a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources. -
pAcquireKeysis 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. -
pAcquireTimeoutsis a pointer to an array of timeout values, in millisecond units, for each acquire specified inpAcquireKeys. -
releaseCountis the number of entries in thepReleaseSyncsandpReleaseKeysarrays. -
pReleaseSyncsis a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources. -
pReleaseKeysis 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;
-
acquireCountis the number of entries in thepAcquireSyncs,pAcquireKeys, andpAcquireTimeoutMillisecondsarrays. -
pAcquireSyncsis a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources. -
pAcquireKeysis 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. -
pAcquireTimeoutMillisecondsis a pointer to an array of timeout values, in millisecond units, for each acquire specified inpAcquireKeys. -
releaseCountis the number of entries in thepReleaseSyncsandpReleaseKeysarrays. -
pReleaseSyncsis a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources. -
pReleaseKeysis 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;
-
protectedSubmitspecifies whether the batch is protected. IfprotectedSubmitisVK_TRUE, the batch is protected. IfprotectedSubmitisVK_FALSE, the batch is unprotected. If theVkSubmitInfo::pNextchain 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
waitSemaphoreCountis the number of elements in thepWaitSemaphoreDeviceIndicesarray. -
pWaitSemaphoreDeviceIndicesis a pointer to an array ofwaitSemaphoreCountdevice indices indicating which physical device executes the semaphore wait operation in the corresponding element of VkSubmitInfo::pWaitSemaphores. -
commandBufferCountis the number of elements in thepCommandBufferDeviceMasksarray. -
pCommandBufferDeviceMasksis a pointer to an array ofcommandBufferCountdevice 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. -
signalSemaphoreCountis the number of elements in thepSignalSemaphoreDeviceIndicesarray. -
pSignalSemaphoreDeviceIndicesis a pointer to an array ofsignalSemaphoreCountdevice 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
counterPassIndexspecifies 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.
Command buffers in the submission can include vkCmdWaitEvents
commands that wait on events that will not be signaled by earlier commands
in the queue.
Such events must be signaled by the application using vkSetEvent, and
the vkCmdWaitEvents commands that wait upon them must not be inside a
render pass instance.
The event must be set before the vkCmdWaitEvents command is executed.
|
Note
Implementations may have some tolerance for waiting on events to be set, but this is defined outside of the scope of Vulkan. |
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);
-
commandBufferis a handle to a primary command buffer that the secondary command buffers are executed in. -
commandBufferCountis the length of thepCommandBuffersarray. -
pCommandBuffersis a pointer to an array ofcommandBufferCountsecondary 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceMaskis 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);
-
commandBufferis command buffer whose current device mask is modified. -
deviceMaskis 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.
- 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.
- 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.
- 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.
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.
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 or synchronization 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. Drawing commands, dispatching commands, copy commands, clear commands, and synchronization commands all execute in different sets of pipeline stages. Synchronization commands do not execute in a defined pipeline stage.
|
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;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR = 0x04000000ULL;
#endif
#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_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;
or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkPipelineStageFlagBits2 VkPipelineStageFlagBits2KHR;
-
VK_PIPELINE_STAGE_2_NONEspecifies no stages of execution. -
VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BITspecifies 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_NVspecifies the task shader stage. -
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NVspecifies the mesh shader stage. -
VK_PIPELINE_STAGE_2_INDEX_INPUT_BITspecifies the stage of the pipeline where index buffers are consumed. -
VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BITspecifies the stage of the pipeline where vertex buffers are consumed. -
VK_PIPELINE_STAGE_2_VERTEX_INPUT_BITis 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_BITspecifies the vertex shader stage. -
VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BITspecifies the tessellation control shader stage. -
VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BITspecifies the tessellation evaluation shader stage. -
VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BITspecifies the geometry shader stage. -
VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BITis 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_NV -
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV
-
-
VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BITspecifies the fragment shader stage. -
VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BITspecifies the stage of the pipeline where early fragment tests (depth and stencil tests before fragment shading) are performed. This stage also includes subpass load operations for framebuffer attachments with a depth/stencil format. -
VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BITspecifies the stage of the pipeline where late fragment tests (depth and stencil tests after fragment shading) are performed. This stage also includes subpass store operations for framebuffer attachments with a depth/stencil format. -
VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BITspecifies the stage of the pipeline after blending where the final color values are output from the pipeline. This stage also includes subpass load and store operations, multisample resolve operations for framebuffer attachments with a color or depth/stencil format, and vkCmdClearAttachments. -
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BITspecifies the compute shader stage. -
VK_PIPELINE_STAGE_2_HOST_BITspecifies 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_BITspecifies the execution of all copy commands, including vkCmdCopyQueryPoolResults. -
VK_PIPELINE_STAGE_2_BLIT_BITspecifies the execution of vkCmdBlitImage. -
VK_PIPELINE_STAGE_2_RESOLVE_BITspecifies the execution of vkCmdResolveImage. -
VK_PIPELINE_STAGE_2_CLEAR_BITspecifies the execution of clear commands, with the exception of vkCmdClearAttachments. -
VK_PIPELINE_STAGE_2_ALL_TRANSFER_BITis 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_KHRspecifies the execution of the ray tracing shader stages. -
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHRspecifies the execution of acceleration structure commands. -
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHRspecifies the execution of acceleration structure copy commands. -
VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BITspecifies 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_NV -
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV -
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_INVOCATION_MASK_BIT_HUAWEI
-
-
VK_PIPELINE_STAGE_2_ALL_COMMANDS_BITspecifies all operations performed by all commands supported on the queue it is used with. -
VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXTspecifies the stage of the pipeline where the predicate of conditional rendering is consumed. -
VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXTspecifies the stage of the pipeline where vertex attribute output values are written to the transform feedback buffers. -
VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NVspecifies the stage of the pipeline where device-side generation of commands via vkCmdPreprocessGeneratedCommandsNV is handled. -
VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies 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_EXTspecifies the stage of the pipeline where the fragment density map is read to generate the fragment areas. -
VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEIspecifies 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_KHRspecifies the stage of the pipeline where video decode operation are performed. -
VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHRspecifies the stage of the pipeline where video encode operation are performed. -
VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEIspecifies the subpass shading shader stage. -
VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BITis equivalent toVK_PIPELINE_STAGE_2_ALL_COMMANDS_BITwith VkAccessFlags2 set to0when specified in the second synchronization scope, but equivalent toVK_PIPELINE_STAGE_2_NONEin the first scope. -
VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BITis equivalent toVK_PIPELINE_STAGE_2_ALL_COMMANDS_BITwith VkAccessFlags2 set to0when specified in the first synchronization scope, but equivalent toVK_PIPELINE_STAGE_2_NONEin 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_NV_mesh_shader
VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV = 0x00080000,
// Provided by VK_NV_mesh_shader
VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV = 0x00100000,
// 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_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_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_NONEspecifies no stages of execution. -
VK_PIPELINE_STAGE_DRAW_INDIRECT_BITspecifies 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_NVspecifies the task shader stage. -
VK_PIPELINE_STAGE_MESH_SHADER_BIT_NVspecifies the mesh shader stage. -
VK_PIPELINE_STAGE_VERTEX_INPUT_BITspecifies the stage of the pipeline where vertex and index buffers are consumed. -
VK_PIPELINE_STAGE_VERTEX_SHADER_BITspecifies the vertex shader stage. -
VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BITspecifies the tessellation control shader stage. -
VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BITspecifies the tessellation evaluation shader stage. -
VK_PIPELINE_STAGE_GEOMETRY_SHADER_BITspecifies the geometry shader stage. -
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BITspecifies the fragment shader stage. -
VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BITspecifies the stage of the pipeline where early fragment tests (depth and stencil tests before fragment shading) are performed. This stage also includes subpass load operations for framebuffer attachments with a depth/stencil format. -
VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BITspecifies the stage of the pipeline where late fragment tests (depth and stencil tests after fragment shading) are performed. This stage also includes subpass store operations for framebuffer attachments with a depth/stencil format. -
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BITspecifies the stage of the pipeline after blending where the final color values are output from the pipeline. This stage also includes subpass load and store operations, multisample resolve operations for framebuffer attachments with a color or depth/stencil format, and vkCmdClearAttachments. -
VK_PIPELINE_STAGE_COMPUTE_SHADER_BITspecifies the execution of a compute shader. -
VK_PIPELINE_STAGE_TRANSFER_BITspecifies the following commands:-
All copy commands, including vkCmdCopyQueryPoolResults
-
All clear commands, with the exception of vkCmdClearAttachments
-
-
VK_PIPELINE_STAGE_HOST_BITspecifies 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_KHRspecifies the execution of vkCmdBuildAccelerationStructureNV, vkCmdCopyAccelerationStructureNV, vkCmdWriteAccelerationStructuresPropertiesNV , vkCmdBuildAccelerationStructuresKHR, vkCmdBuildAccelerationStructuresIndirectKHR, vkCmdCopyAccelerationStructureKHR, vkCmdCopyAccelerationStructureToMemoryKHR, vkCmdCopyMemoryToAccelerationStructureKHR, and vkCmdWriteAccelerationStructuresPropertiesKHR. -
VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHRspecifies the execution of the ray tracing shader stages, via vkCmdTraceRaysNV , vkCmdTraceRaysKHR, or vkCmdTraceRaysIndirectKHR -
VK_PIPELINE_STAGE_ALL_GRAPHICS_BITspecifies 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_NV -
VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV -
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_BITspecifies all operations performed by all commands supported on the queue it is used with. -
VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXTspecifies the stage of the pipeline where the predicate of conditional rendering is consumed. -
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXTspecifies the stage of the pipeline where vertex attribute output values are written to the transform feedback buffers. -
VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NVspecifies the stage of the pipeline where device-side preprocessing for generated commands via vkCmdPreprocessGeneratedCommandsNV is handled. -
VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies 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_EXTspecifies the stage of the pipeline where the fragment density map is read to generate the fragment areas. -
VK_PIPELINE_STAGE_TOP_OF_PIPE_BITis equivalent toVK_PIPELINE_STAGE_ALL_COMMANDS_BITwith VkAccessFlags set to0when specified in the second synchronization scope, but specifies no stage of execution when specified in the first scope. -
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BITis equivalent toVK_PIPELINE_STAGE_ALL_COMMANDS_BITwith VkAccessFlags set to0when 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 its first access scope only includes memory accesses performed by pipeline stages specified in that 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 its second access scope only includes memory access performed by pipeline stages specified in that mask.
|
Note
Including a particular pipeline stage in the first synchronization scope of a command implicitly includes logically earlier pipeline stages in the synchronization scope. Similarly, the second synchronization scope includes logically later pipeline stages. However, note that access scopes are not affected in this way - only the precise stages specified 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_DRAW_INDIRECT_BIT -
VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT -
VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_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_TRANSFORM_FEEDBACK_BIT_EXT -
VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT -
VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_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_DRAW_INDIRECT_BIT -
VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV -
VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV -
VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT -
VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
For the compute pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT -
VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT
For the subpass shading pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_2_SUBPASS_SHADING_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_TRANSFER_BIT
For host operations, only one pipeline stage occurs, so no order is guaranteed:
-
VK_PIPELINE_STAGE_HOST_BIT
For the command preprocessing pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV
For acceleration structure operations, only one pipeline stage occurs, so no order is guaranteed:
-
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
For the ray tracing pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT -
VK_PIPELINE_STAGE_RAY_TRACING_SHADER_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;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR = 0x800000000ULL;
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR = 0x1000000000ULL;
#endif
#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_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,VK_KHR_ray_tracing_pipeline
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR = 0x10000000000ULL;
or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkAccessFlagBits2 VkAccessFlagBits2KHR;
-
VK_ACCESS_2_NONEspecifies no accesses. -
VK_ACCESS_2_MEMORY_READ_BITspecifies all read accesses. It is always valid in any access mask, and is treated as equivalent to setting allREADaccess flags that are valid where it is used. -
VK_ACCESS_2_MEMORY_WRITE_BITspecifies all write accesses. It is always valid in any access mask, and is treated as equivalent to setting allWRITEaccess flags that are valid where it is used. -
VK_ACCESS_2_INDIRECT_COMMAND_READ_BITspecifies 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_BITpipeline stage. -
VK_ACCESS_2_INDEX_READ_BITspecifies 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_BITpipeline stage. -
VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BITspecifies 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_BITpipeline stage. -
VK_ACCESS_2_UNIFORM_READ_BITspecifies read access to a uniform buffer in any shader pipeline stage. -
VK_ACCESS_2_INPUT_ATTACHMENT_READ_BITspecifies 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_SHADING_BIT_HUAWEIorVK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BITpipeline stage. -
VK_ACCESS_2_SHADER_SAMPLED_READ_BITspecifies read access to a uniform texel buffer or sampled image in any shader pipeline stage. -
VK_ACCESS_2_SHADER_STORAGE_READ_BITspecifies 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_KHRspecifies read access to a shader binding table in any shader pipeline stage. -
VK_ACCESS_2_SHADER_READ_BITis equivalent to the logical OR of:-
VK_ACCESS_2_UNIFORM_READ_BIT -
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_BITspecifies 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_BITis equivalent toVK_ACCESS_2_SHADER_STORAGE_WRITE_BIT. -
VK_ACCESS_2_COLOR_ATTACHMENT_READ_BITspecifies read access to a color attachment, such as via blending, logic operations, or via certain subpass load operations. It does not include advanced blend operations. Such access occurs in theVK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage. -
VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BITspecifies write access to a color, resolve, or depth/stencil resolve attachment during a render pass or via certain subpass load and store operations. Such access occurs in theVK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage. -
VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BITspecifies read access to a depth/stencil attachment, via depth or stencil operations or via certain subpass load operations. Such access occurs in theVK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BITorVK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BITpipeline stages. -
VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BITspecifies write access to a depth/stencil attachment, via depth or stencil operations or via certain subpass load and store operations. Such access occurs in theVK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BITorVK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BITpipeline stages. -
VK_ACCESS_2_TRANSFER_READ_BITspecifies 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_BITpipeline stages. -
VK_ACCESS_2_TRANSFER_WRITE_BITspecifies 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_BITpipeline stages. -
VK_ACCESS_2_HOST_READ_BITspecifies 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_BITpipeline stage. -
VK_ACCESS_2_HOST_WRITE_BITspecifies 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_BITpipeline stage. -
VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXTspecifies read access to a predicate as part of conditional rendering. Such access occurs in theVK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXTpipeline stage. -
VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXTspecifies write access to a transform feedback buffer made when transform feedback is active. Such access occurs in theVK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXTpipeline stage. -
VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXTspecifies 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_EXTpipeline stage. -
VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXTspecifies 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_EXTpipeline stage. -
VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NVspecifies reads from buffer inputs to vkCmdPreprocessGeneratedCommandsNV. Such access occurs in theVK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NVpipeline stage. -
VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NVspecifies writes to the target command buffer preprocess outputs. Such access occurs in theVK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NVpipeline stage. -
VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXTspecifies read access to color attachments, including advanced blend operations. Such access occurs in theVK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage. -
VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEIspecifies read access to a invocation mask image in theVK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEIpipeline stage. -
VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHRspecifies 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_KHRpipeline stage orVK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHRpipeline stage. -
VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHRspecifies 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_KHRpipeline stage. -
VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXTspecifies 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_EXTpipeline stage. -
VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHRspecifies read access to a fragment shading rate attachment during rasterization. Such access occurs in theVK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRpipeline stage. -
VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NVspecifies read access to a shading rate image during rasterization. Such access occurs in theVK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NVpipeline stage. It is equivalent toVK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR. -
VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHRspecifies read access to an image or buffer resource as part of a video decode operation. Such access occurs in theVK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHRpipeline stage. -
VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHRspecifies write access to an image or buffer resource as part of a video decode operation. Such access occurs in theVK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHRpipeline stage. -
VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHRspecifies read access to an image or buffer resource as part of a video encode operation. Such access occurs in theVK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHRpipeline stage. -
VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHRspecifies write access to an image or buffer resource as part of a video encode operation. Such access occurs in theVK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHRpipeline stage.
|
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_NONEspecifies no accesses. -
VK_ACCESS_MEMORY_READ_BITspecifies all read accesses. It is always valid in any access mask, and is treated as equivalent to setting allREADaccess flags that are valid where it is used. -
VK_ACCESS_MEMORY_WRITE_BITspecifies all write accesses. It is always valid in any access mask, and is treated as equivalent to setting allWRITEaccess flags that are valid where it is used. -
VK_ACCESS_INDIRECT_COMMAND_READ_BITspecifies 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_BITpipeline stage. -
VK_ACCESS_INDEX_READ_BITspecifies 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_BITpipeline stage. -
VK_ACCESS_VERTEX_ATTRIBUTE_READ_BITspecifies read access to a vertex buffer as part of a drawing command, bound by vkCmdBindVertexBuffers. Such access occurs in theVK_PIPELINE_STAGE_VERTEX_INPUT_BITpipeline stage. -
VK_ACCESS_UNIFORM_READ_BITspecifies read access to a uniform buffer in any shader pipeline stage. -
VK_ACCESS_INPUT_ATTACHMENT_READ_BITspecifies 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_SHADING_BIT_HUAWEIorVK_PIPELINE_STAGE_FRAGMENT_SHADER_BITpipeline stage. -
VK_ACCESS_SHADER_READ_BITspecifies read access to a uniform buffer, 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_BITspecifies 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_BITspecifies read access to a color attachment, such as via blending, logic operations, or via certain subpass load operations. It does not include advanced blend operations. Such access occurs in theVK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage. -
VK_ACCESS_COLOR_ATTACHMENT_WRITE_BITspecifies write access to a color, resolve, or depth/stencil resolve attachment during a render pass or via certain subpass load and store operations. Such access occurs in theVK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage. -
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BITspecifies read access to a depth/stencil attachment, via depth or stencil operations or via certain subpass load operations. Such access occurs in theVK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BITorVK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BITpipeline stages. -
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BITspecifies write access to a depth/stencil attachment, via depth or stencil operations or via certain subpass load and store operations. Such access occurs in theVK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BITorVK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BITpipeline stages. -
VK_ACCESS_TRANSFER_READ_BITspecifies read access to an image or buffer in a copy operation. Such access occurs in theVK_PIPELINE_STAGE_2_ALL_TRANSFER_BITpipeline stage. -
VK_ACCESS_TRANSFER_WRITE_BITspecifies write access to an image or buffer in a clear or copy operation. Such access occurs in theVK_PIPELINE_STAGE_2_ALL_TRANSFER_BITpipeline stage. -
VK_ACCESS_HOST_READ_BITspecifies 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_BITpipeline stage. -
VK_ACCESS_HOST_WRITE_BITspecifies 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_BITpipeline stage. -
VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXTspecifies read access to a predicate as part of conditional rendering. Such access occurs in theVK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXTpipeline stage. -
VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXTspecifies write access to a transform feedback buffer made when transform feedback is active. Such access occurs in theVK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXTpipeline stage. -
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXTspecifies read access to a transform feedback counter buffer which is read whenvkCmdBeginTransformFeedbackEXTexecutes. Such access occurs in theVK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXTpipeline stage. -
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXTspecifies write access to a transform feedback counter buffer which is written whenvkCmdEndTransformFeedbackEXTexecutes. Such access occurs in theVK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXTpipeline stage. -
VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NVspecifies reads from buffer inputs to vkCmdPreprocessGeneratedCommandsNV. Such access occurs in theVK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NVpipeline stage. -
VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NVspecifies writes to the target command buffer:VkBuffer preprocess outputs in vkCmdPreprocessGeneratedCommandsNV. Such access occurs in theVK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NVpipeline stage. -
VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXTspecifies read access to color attachments, including advanced blend operations. Such access occurs in theVK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage. -
VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEIspecifies read access to a invocation mask image in theVK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEIpipeline stage. -
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHRspecifies 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_KHRpipeline stage orVK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHRpipeline stage. -
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHRspecifies 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_KHRpipeline stage. -
VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXTspecifies 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_EXTpipeline stage. -
VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHRspecifies read access to a fragment shading rate attachment during rasterization. Such access occurs in theVK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRpipeline stage. -
VK_ACCESS_SHADING_RATE_IMAGE_READ_BIT_NVspecifies read access to a shading rate image during rasterization. Such access occurs in theVK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NVpipeline 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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// 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_ARM,
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM,
or
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM,
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
pSubmitsparameter of vkQueueSubmit, or in which VkSubmitInfo2 structures are specified in thepSubmitsparameter of vkQueueSubmit2, from lowest index to highest. -
The order in which command buffers are specified in the
pCommandBuffersmember 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
pSubmitsparameter of vkQueueSubmit, or in which VkSubmitInfo2 structures are specified in thepSubmitsparameter of vkQueueSubmit2, from lowest index to highest. -
The fence signal operation defined by the
fenceparameter of a vkQueueSubmit, vkQueueSubmit2, or vkQueueBindSparse command is ordered after all semaphore signal operations defined by that command.
Semaphore signal operations defined by a single VkSubmitInfo, 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);
-
deviceis the logical device that creates the fence. -
pCreateInfois a pointer to a VkFenceCreateInfo structure containing information about how the fence is to be created. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pFenceis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis 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_BITspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pAttributesis a pointer to a WindowsSECURITY_ATTRIBUTESstructure specifying security attributes of the handle. -
dwAccessis aDWORDspecifying access rights of the handle. -
nameis 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 inluded 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 if it is 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);
-
deviceis the logical device that created the fence being exported. -
pGetWin32HandleInfois a pointer to a VkFenceGetWin32HandleInfoKHR structure containing parameters of the export operation. -
pHandlewill 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fenceis the fence from which state will be exported. -
handleTypeis 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);
-
deviceis the logical device that created the fence being exported. -
pGetFdInfois a pointer to a VkFenceGetFdInfoKHR structure containing parameters of the export operation. -
pFdwill 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fenceis the fence from which state will be exported. -
handleTypeis 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);
-
deviceis the logical device that destroys the fence. -
fenceis the handle of the fence to destroy. -
pAllocatorcontrols 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);
-
deviceis the logical device that owns the fence. -
fenceis 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);
-
deviceis the logical device that owns the fences. -
fenceCountis the number of fences to reset. -
pFencesis 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 , 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);
-
deviceis the logical device that owns the fences. -
fenceCountis the number of fences to wait on. -
pFencesis a pointer to an array offenceCountfence handles. -
waitAllis the condition that must be satisfied to successfully unblock the wait. IfwaitAllisVK_TRUE, then the condition is that all fences inpFencesare signaled. Otherwise, the condition is that at least one fence inpFencesis signaled. -
timeoutis the timeout period in units of nanoseconds.timeoutis 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);
-
deviceis a logical device on which the event may occur. -
pDeviceEventInfois a pointer to a VkDeviceEventInfoEXT structure describing the event of interest to the application. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pFenceis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceis 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_EXTspecifies 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);
-
deviceis a logical device associated withdisplay -
displayis the display on which the event may occur. -
pDisplayEventInfois a pointer to a VkDisplayEventInfoEXT structure describing the event of interest to the application. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pFenceis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
displayEventis 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_EXTspecifies 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);
-
deviceis the logical device that created the fence. -
pImportFenceWin32HandleInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fenceis the fence into which the state will be imported. -
flagsis a bitmask of VkFenceImportFlagBits specifying additional parameters for the fence payload import operation. -
handleTypeis a VkExternalFenceHandleTypeFlagBits value specifying the type ofhandle. -
handleisNULLor the external handle to import. -
nameisNULLor 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);
-
deviceis the logical device that created the fence. -
pImportFenceFdInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fenceis the fence into which the payload will be imported. -
flagsis a bitmask of VkFenceImportFlagBits specifying additional parameters for the fence payload import operation. -
handleTypeis a VkExternalFenceHandleTypeFlagBits value specifying the type offd. -
fdis 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_BITspecifies 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);
-
deviceis the logical device that creates the semaphore. -
pCreateInfois a pointer to a VkSemaphoreCreateInfo structure containing information about how the semaphore is to be created. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pSemaphoreis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreTypeis a VkSemaphoreType value specifying the type of the semaphore. -
initialValueis the initial payload value ifsemaphoreTypeisVK_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_BINARYspecifies 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_TIMELINEspecifies 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 theinitialValuefield 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pAttributesis a pointer to a WindowsSECURITY_ATTRIBUTESstructure specifying security attributes of the handle. -
dwAccessis aDWORDspecifying access rights of the handle. -
nameis 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 if it is 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);
-
deviceis the logical device that created the semaphore being exported. -
pGetWin32HandleInfois a pointer to a VkSemaphoreGetWin32HandleInfoKHR structure containing parameters of the export operation. -
pHandlewill 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreis the semaphore from which state will be exported. -
handleTypeis 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.
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);
-
deviceis the logical device that created the semaphore being exported. -
pGetFdInfois a pointer to a VkSemaphoreGetFdInfoKHR structure containing parameters of the export operation. -
pFdwill 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreis the semaphore from which state will be exported. -
handleTypeis 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);
-
deviceis the logical device that created the semaphore being exported. -
pGetZirconHandleInfois a pointer to a VkSemaphoreGetZirconHandleInfoFUCHSIA structure containing parameters of the export operation. -
pZirconHandlewill 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreis the semaphore from which state will be exported. -
handleTypeis 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);
-
deviceis the logical device that destroys the semaphore. -
semaphoreis the handle of the semaphore to destroy. -
pAllocatorcontrols 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
, 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);
-
deviceis the logical device that owns the semaphore. -
semaphoreis the handle of the semaphore to query. -
pValueis 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);
-
deviceis the logical device that owns the semaphores. -
pWaitInfois a pointer to a VkSemaphoreWaitInfo structure containing information about the wait condition. -
timeoutis the timeout period in units of nanoseconds.timeoutis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkSemaphoreWaitFlagBits specifying additional parameters for the semaphore wait operation. -
semaphoreCountis the number of semaphores to wait on. -
pSemaphoresis a pointer to an array ofsemaphoreCountsemaphore handles to wait on. -
pValuesis a pointer to an array ofsemaphoreCounttimeline 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_BITspecifies that the semaphore wait condition is that at least one of the semaphores inVkSemaphoreWaitInfo::pSemaphoreshas reached the value specified by the corresponding element ofVkSemaphoreWaitInfo::pValues. IfVK_SEMAPHORE_WAIT_ANY_BITis not set, the semaphore wait condition is that all of the semaphores inVkSemaphoreWaitInfo::pSemaphoreshave 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);
-
deviceis the logical device that owns the semaphore. -
pSignalInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreis the handle of the semaphore to signal. -
valueis 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_FAILEDfrom 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_LOSTerror 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);
-
deviceis the logical device that created the semaphore. -
pImportSemaphoreWin32HandleInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreis the semaphore into which the payload will be imported. -
flagsis a bitmask of VkSemaphoreImportFlagBits specifying additional parameters for the semaphore payload import operation. -
handleTypeis a VkExternalSemaphoreHandleTypeFlagBits value specifying the type ofhandle. -
handleisNULLor the external handle to import. -
nameisNULLor 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);
-
deviceis the logical device that created the semaphore. -
pImportSemaphoreFdInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreis the semaphore into which the payload will be imported. -
flagsis a bitmask of VkSemaphoreImportFlagBits specifying additional parameters for the semaphore payload import operation. -
handleTypeis a VkExternalSemaphoreHandleTypeFlagBits value specifying the type offd. -
fdis 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);
-
deviceis the logical device that created the semaphore. -
pImportSemaphoreZirconHandleInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreis the semaphore into which the payload will be imported. -
flagsis a bitmask of VkSemaphoreImportFlagBits specifying additional parameters for the semaphore payload import operation. -
handleTypeis a VkExternalSemaphoreHandleTypeFlagBits value specifying the type ofzirconHandle. -
zirconHandleis 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_BITspecifies 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);
-
deviceis the logical device that creates the event. -
pCreateInfois a pointer to a VkEventCreateInfo structure containing information about how the event is to be created. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pEventis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis 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_BITspecifies 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);
-
deviceis the logical device that destroys the event. -
eventis the handle of the event to destroy. -
pAllocatorcontrols 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);
-
deviceis the logical device that owns the event. -
eventis 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);
-
deviceis the logical device that owns the event. -
eventis 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.
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);
-
deviceis the logical device that owns the event. -
eventis 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);
-
commandBufferis the command buffer into which the command is recorded. -
eventis the event that will be signaled. -
pDependencyInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dependencyFlagsis a bitmask of VkDependencyFlagBits specifying how execution and memory dependencies are formed. -
memoryBarrierCountis the length of thepMemoryBarriersarray. -
pMemoryBarriersis a pointer to an array of VkMemoryBarrier2 structures defining memory dependencies between any memory accesses. -
bufferMemoryBarrierCountis the length of thepBufferMemoryBarriersarray. -
pBufferMemoryBarriersis a pointer to an array of VkBufferMemoryBarrier2 structures defining memory dependencies between buffer ranges. -
imageMemoryBarrierCountis the length of thepImageMemoryBarriersarray. -
pImageMemoryBarriersis 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);
-
commandBufferis the command buffer into which the command is recorded. -
eventis the event that will be signaled. -
stageMaskspecifies 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);
-
commandBufferis the command buffer into which the command is recorded. -
eventis the event that will be unsignaled. -
stageMaskis 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);
-
commandBufferis the command buffer into which the command is recorded. -
eventis the event that will be unsignaled. -
stageMaskis a bitmask of VkPipelineStageFlagBits specifying the source stage mask used to determine when theeventis 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);
-
commandBufferis the command buffer into which the command is recorded. -
eventCountis the length of thepEventsarray. -
pEventsis a pointer to an array ofeventCountevents to wait on. -
pDependencyInfosis a pointer to an array ofeventCountVkDependencyInfo 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
dependencyInfoparameter exactly equal to the element ofpDependencyInfosat index i ; or -
The event was created without
VK_EVENT_CREATE_DEVICE_ONLY_BIT, and the first synchronization scope defined by the element ofpDependencyInfosat 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);
-
commandBufferis the command buffer into which the command is recorded. -
eventCountis the length of thepEventsarray. -
pEventsis a pointer to an array of event object handles to wait on. -
srcStageMaskis a bitmask of VkPipelineStageFlagBits specifying the source stage mask. -
dstStageMaskis a bitmask of VkPipelineStageFlagBits specifying the destination stage mask. -
memoryBarrierCountis the length of thepMemoryBarriersarray. -
pMemoryBarriersis a pointer to an array of VkMemoryBarrier structures. -
bufferMemoryBarrierCountis the length of thepBufferMemoryBarriersarray. -
pBufferMemoryBarriersis a pointer to an array of VkBufferMemoryBarrier structures. -
imageMemoryBarrierCountis the length of thepImageMemoryBarriersarray. -
pImageMemoryBarriersis 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);
-
commandBufferis the command buffer into which the command is recorded. -
pDependencyInfois 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 before it, and those submitted 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);
-
commandBufferis the command buffer into which the command is recorded. -
srcStageMaskis a bitmask of VkPipelineStageFlagBits specifying the source stages. -
dstStageMaskis a bitmask of VkPipelineStageFlagBits specifying the destination stages. -
dependencyFlagsis a bitmask of VkDependencyFlagBits specifying how execution and memory dependencies are formed. -
memoryBarrierCountis the length of thepMemoryBarriersarray. -
pMemoryBarriersis a pointer to an array of VkMemoryBarrier structures. -
bufferMemoryBarrierCountis the length of thepBufferMemoryBarriersarray. -
pBufferMemoryBarriersis a pointer to an array of VkBufferMemoryBarrier structures. -
imageMemoryBarrierCountis the length of thepImageMemoryBarriersarray. -
pImageMemoryBarriersis 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 before it, and those submitted 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_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_BITspecifies that dependencies will be framebuffer-local. -
VK_DEPENDENCY_VIEW_LOCAL_BITspecifies that a subpass has more than one view. -
VK_DEPENDENCY_DEVICE_GROUP_BITspecifies that dependencies are non-device-local.
// Provided by VK_VERSION_1_0
typedef VkFlags VkDependencyFlags;
VkDependencyFlags is a bitmask type for setting a mask of zero or more
VkDependencyFlagBits.
7.6.1. Subpass Self-dependency
vkCmdPipelineBarrier or vkCmdPipelineBarrier2 must not be called within a render pass instance started with vkCmdBeginRendering.
If vkCmdPipelineBarrier
or vkCmdPipelineBarrier2
is called inside a render pass instance, the following restrictions apply.
For a given subpass to allow a pipeline barrier, the render pass must
declare a self-dependency from that subpass to itself.
That is, there must exist a subpass dependency with srcSubpass and
dstSubpass both equal to that subpass index.
More than one self-dependency can be declared for each subpass.
Self-dependencies must only include pipeline stage bits that are graphics
stages.
If any of the stages in srcStageMask are
framebuffer-space stages,
dstStageMask must only contain
framebuffer-space stages.
This means that pseudo-stages like VK_PIPELINE_STAGE_ALL_COMMANDS_BIT
which include the execution of both framebuffer-space stages and
non-framebuffer-space stages must not be used.
If the source and destination stage masks both include framebuffer-space
stages, then dependencyFlags must include
VK_DEPENDENCY_BY_REGION_BIT.
If the subpass has more than one view, then dependencyFlags must
include VK_DEPENDENCY_VIEW_LOCAL_BIT.
Each of the synchronization scopes and access scopes of a vkCmdPipelineBarrier2 or vkCmdPipelineBarrier command inside a render pass instance must be a subset of the scopes of one of the self-dependencies for the current subpass.
If the self-dependency has VK_DEPENDENCY_BY_REGION_BIT
or VK_DEPENDENCY_VIEW_LOCAL_BIT
set, then so must the pipeline barrier.
Pipeline barriers within a render pass instance must not include buffer
memory barriers.
Image memory barriers must only specify image subresources that are used as
attachments within the subpass, and must not define an
image layout transition or
queue family ownership transfer.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcStageMaskis a VkPipelineStageFlags2 mask of pipeline stages to be included in the first synchronization scope. -
srcAccessMaskis a VkAccessFlags2 mask of access flags to be included in the first access scope. -
dstStageMaskis a VkPipelineStageFlags2 mask of pipeline stages to be included in the second synchronization scope. -
dstAccessMaskis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcAccessMaskis a bitmask of VkAccessFlagBits specifying a source access mask. -
dstAccessMaskis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcStageMaskis a VkPipelineStageFlags2 mask of pipeline stages to be included in the first synchronization scope. -
srcAccessMaskis a VkAccessFlags2 mask of access flags to be included in the first access scope. -
dstStageMaskis a VkPipelineStageFlags2 mask of pipeline stages to be included in the second synchronization scope. -
dstAccessMaskis a VkAccessFlags2 mask of access flags to be included in the second access scope. -
srcQueueFamilyIndexis the source queue family for a queue family ownership transfer. -
dstQueueFamilyIndexis the destination queue family for a queue family ownership transfer. -
bufferis a handle to the buffer whose backing memory is affected by the barrier. -
offsetis an offset in bytes into the backing memory forbuffer; this is relative to the base offset as bound to the buffer (see vkBindBufferMemory). -
sizeis a size in bytes of the affected area of backing memory forbuffer, orVK_WHOLE_SIZEto use the range fromoffsetto 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcAccessMaskis a bitmask of VkAccessFlagBits specifying a source access mask. -
dstAccessMaskis a bitmask of VkAccessFlagBits specifying a destination access mask. -
srcQueueFamilyIndexis the source queue family for a queue family ownership transfer. -
dstQueueFamilyIndexis the destination queue family for a queue family ownership transfer. -
bufferis a handle to the buffer whose backing memory is affected by the barrier. -
offsetis an offset in bytes into the backing memory forbuffer; this is relative to the base offset as bound to the buffer (see vkBindBufferMemory). -
sizeis a size in bytes of the affected area of backing memory forbuffer, orVK_WHOLE_SIZEto use the range fromoffsetto 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, 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 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, 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 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcStageMaskis a VkPipelineStageFlags2 mask of pipeline stages to be included in the first synchronization scope. -
srcAccessMaskis a VkAccessFlags2 mask of access flags to be included in the first access scope. -
dstStageMaskis a VkPipelineStageFlags2 mask of pipeline stages to be included in the second synchronization scope. -
dstAccessMaskis a VkAccessFlags2 mask of access flags to be included in the second access scope. -
oldLayoutis the old layout in an image layout transition. -
newLayoutis the new layout in an image layout transition. -
srcQueueFamilyIndexis the source queue family for a queue family ownership transfer. -
dstQueueFamilyIndexis the destination queue family for a queue family ownership transfer. -
imageis a handle to the image affected by this barrier. -
subresourceRangedescribes the image subresource range withinimagethat 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcAccessMaskis a bitmask of VkAccessFlagBits specifying a source access mask. -
dstAccessMaskis a bitmask of VkAccessFlagBits specifying a destination access mask. -
oldLayoutis the old layout in an image layout transition. -
newLayoutis the new layout in an image layout transition. -
srcQueueFamilyIndexis the source queue family for a queue family ownership transfer. -
dstQueueFamilyIndexis the destination queue family for a queue family ownership transfer. -
imageis a handle to the image affected by this barrier. -
subresourceRangedescribes the image subresource range withinimagethat 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);
-
queueis 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);
-
deviceis 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 is defined by the host execution model, but includes execution of vkQueueSubmit on the host and anything that happened-before it.
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);
-
deviceis the logical device used to perform the query. -
timestampCountis the number of timestamps to query. -
pTimestampInfosis a pointer to an array oftimestampCountVkCalibratedTimestampInfoEXT structures, describing the time domains the calibrated timestamps should be captured from. -
pTimestampsis a pointer to an array oftimestampCount64-bit unsigned integer values in which the requested calibrated timestamp values are returned. -
pMaxDeviationis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
timeDomainis 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,
} VkTimeDomainEXT;
-
VK_TIME_DOMAIN_DEVICE_EXTspecifies 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 thetimestampPeriodof the device. -
VK_TIME_DOMAIN_CLOCK_MONOTONIC_EXTspecifies 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_EXTspecifies 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_EXTspecifies the performance counter (QPC) time domain available on Windows. Timestamp values in this time domain are in the same units as those provided by the Windows QueryPerformanceCounter API and are comparable with platform timestamp values captured using that API as computed by this example:
LARGE_INTEGER counter;
QueryPerformanceCounter(&counter);
return counter.QuadPart;
8. Render Pass
Draw commands must be recorded within a render pass instance. Each render pass instance defines a set of image resources, referred to as attachments, used during rendering.
To begin a render pass instance, call:
// Provided by VK_VERSION_1_3
void vkCmdBeginRendering(
VkCommandBuffer commandBuffer,
const VkRenderingInfo* pRenderingInfo);
or the equivalent command
// Provided by VK_KHR_dynamic_rendering
void vkCmdBeginRenderingKHR(
VkCommandBuffer commandBuffer,
const VkRenderingInfo* pRenderingInfo);
-
commandBufferis the command buffer in which to record the command. -
pRenderingInfois 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
typedef VkRenderingInfo VkRenderingInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkRenderingFlagBits. -
renderAreais the render area that is affected by the render pass instance. -
layerCountis the number of layers rendered to in each attachment whenviewMaskis0. -
viewMaskis the view mask indicating the indices of attachment layers that will be rendered when it is not0. -
colorAttachmentCountis the number of elements inpColorAttachments. -
pColorAttachmentsis a pointer to an array ofcolorAttachmentCountVkRenderingAttachmentInfo structures describing any color attachments used. -
pDepthAttachmentis a pointer to a VkRenderingAttachmentInfo structure describing a depth attachment. -
pStencilAttachmentis 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 deviceCount member is not 0, then
renderArea is ignored, and the render area is defined per-device by
that structure.
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,
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_BITspecifies that draw calls for the render pass instance will be recorded in secondary command buffers. -
VK_RENDERING_RESUMING_BITspecifies that the render pass instance is resuming an earlier suspended render pass instance. -
VK_RENDERING_SUSPENDING_BITspecifies that the render pass instance will be suspended.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis the image view that will be used for rendering. -
imageLayoutis the layout thatimageViewwill be in during rendering. -
resolveModeis a VkResolveModeFlagBits value defining how multisampled data written toimageViewwill be resolved. -
resolveImageViewis an image view used to write resolved multisample data at the end of rendering. -
resolveImageLayoutis the layout thatresolveImageViewwill be in during rendering. -
loadOpis a VkAttachmentLoadOp value specifying how the contents ofimageVieware treated at the start of the render pass instance. -
storeOpis a VkAttachmentStoreOp value specifying how the contents ofimageVieware treated at the end of the render pass instance. -
clearValueis a VkClearValue structure defining values used to clearimageViewwhenloadOpisVK_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 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, values in
resolveImageView within the render area become undefined once
rendering begins.
At the end of rendering, the color values written to each pixel location in
imageView will be resolved according to resolveMode and stored
into the the same location in resolveImageView.
|
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis the image view that will be used as a fragment shading rate attachment. -
imageLayoutis the layout thatimageViewwill be in during rendering. -
shadingRateAttachmentTexelSizespecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis the image view that will be used as a fragment shading rate attachment. -
imageLayoutis the layout thatimageViewwill 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);
-
commandBufferis 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. |
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.1. 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);
-
deviceis the logical device that creates the render pass. -
pCreateInfois a pointer to a VkRenderPassCreateInfo structure describing the parameters of the render pass. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pRenderPassis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkRenderPassCreateFlagBits -
attachmentCountis the number of attachments used by this render pass. -
pAttachmentsis a pointer to an array ofattachmentCountVkAttachmentDescription structures describing the attachments used by the render pass. -
subpassCountis the number of subpasses to create. -
pSubpassesis a pointer to an array ofsubpassCountVkSubpassDescription structures describing each subpass. -
dependencyCountis the number of memory dependencies between pairs of subpasses. -
pDependenciesis a pointer to an array ofdependencyCountVkSubpassDependency 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_QCOMspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
subpassCountis zero or the number of subpasses in the render pass. -
pViewMasksis a pointer to an array ofsubpassCountview masks, where each mask is a bitfield of view indices describing which views rendering is broadcast to in each subpass, when multiview is enabled. IfsubpassCountis zero, each view mask is treated as zero. -
dependencyCountis zero or the number of dependencies in the render pass. -
pViewOffsetsis a pointer to an array ofdependencyCountview offsets, one for each dependency. IfdependencyCountis 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. -
correlationMaskCountis zero or the number of correlation masks. -
pCorrelationMasksis a pointer to an array ofcorrelationMaskCountview 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 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
perViewAttributesspecifies 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. -
perViewAttributesPositionXOnlyspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityMapAttachmentis 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_EXTspecifies 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_EXTspecifies 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;
-
flagsis a bitmask of VkAttachmentDescriptionFlagBits specifying additional properties of the attachment. -
formatis a VkFormat value specifying the format of the image view that will be used for the attachment. -
samplesis a VkSampleCountFlagBits value specifying the number of samples of the image. -
loadOpis 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. -
storeOpis 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. -
stencilLoadOpis 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. -
stencilStoreOpis 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. -
initialLayoutis the layout the attachment image subresource will be in when a render pass instance begins. -
finalLayoutis 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 that
execute as part of the first subpass that uses the attachment.
storeOp and stencilStoreOp define the store operations that
execute as part of the last subpass that uses the attachment.
The load operation for each sample in an attachment happens-before any
recorded command which accesses the sample in the first subpass where the
attachment is used.
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 store operation for each sample in an attachment happens-after any
recorded command which accesses the sample in the last subpass where the
attachment is used.
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.
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.
The load and store operations apply on the first and last use of each view in the render pass, respectively. If a view index of an attachment is not included in the view mask in any subpass that uses it, then the load and store operations are ignored, and the attachment’s memory contents will not be modified by execution of a render pass instance.
During a render pass instance, input/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.
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. The precise set of valid scenarios is described in more detail below.
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_BITspecifies 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.
Possible values of VkAttachmentDescription::loadOp and
stencilLoadOp, specifying how the contents of the attachment are
treated, 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_LOADspecifies that the previous contents of the image within the render area will be preserved. 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_CLEARspecifies 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_CAREspecifies 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_EXTspecifies that the previous contents of the image within the render area will be preserved, but the contents of the attachment will be undefined inside the render pass. No access type is used as the image is not accessed.
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_STOREspecifies 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_CAREspecifies 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_NONEspecifies the contents within the render area are not accessed by the store operation. However, if the attachment was written to during the render pass, the contents of the attachment will be undefined inside the render area.
|
Note
|
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
aspectReferenceCountis the number of elements in thepAspectReferencesarray. -
pAspectReferencesis a pointer to an array ofaspectReferenceCountVkInputAttachmentAspectReference 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;
-
subpassis an index into thepSubpassesarray of the parentVkRenderPassCreateInfostructure. -
inputAttachmentIndexis an index into thepInputAttachmentsof the specified subpass. -
aspectMaskis 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;
-
flagsis a bitmask of VkSubpassDescriptionFlagBits specifying usage of the subpass. -
pipelineBindPointis a VkPipelineBindPoint value specifying the pipeline type supported for this subpass. -
inputAttachmentCountis the number of input attachments. -
pInputAttachmentsis a pointer to an array of VkAttachmentReference structures defining the input attachments for this subpass and their layouts. -
colorAttachmentCountis the number of color attachments. -
pColorAttachmentsis a pointer to an array ofcolorAttachmentCountVkAttachmentReference structures defining the color attachments for this subpass and their layouts. -
pResolveAttachmentsisNULLor a pointer to an array ofcolorAttachmentCountVkAttachmentReference structures defining the resolve attachments for this subpass and their layouts. -
pDepthStencilAttachmentis a pointer to a VkAttachmentReference structure specifying the depth/stencil attachment for this subpass and its layout. -
preserveAttachmentCountis the number of preserved attachments. -
pPreserveAttachmentsis a pointer to an array ofpreserveAttachmentCountrender 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.
At the end of each subpass, multisample resolve operations read the
subpass’s color attachments, and resolve the samples for each pixel within
the render area to the same pixel location in the corresponding resolve
attachments, 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 operations for depth
and stencil are defined by
VkSubpassDescriptionDepthStencilResolve::depthResolveMode and
VkSubpassDescriptionDepthStencilResolve::stencilResolveMode,
respectively.
At the end of each subpass, multisample resolve operations read the
subpass’s depth/stencil attachment, and resolve the samples for each pixel
to the same pixel location in the corresponding resolve attachment.
If VkSubpassDescriptionDepthStencilResolve::depthResolveMode is
VK_RESOLVE_MODE_NONE, then the depth component of the resolve
attachment is not written to and its contents are preserved.
Similarly, if
VkSubpassDescriptionDepthStencilResolve::stencilResolveMode is
VK_RESOLVE_MODE_NONE, then the stencil component of the resolve
attachment is not written to and its contents are preserved.
VkSubpassDescriptionDepthStencilResolve::depthResolveMode is
ignored if the VkFormat of the pDepthStencilResolveAttachment
does not have a depth component.
Similarly,
VkSubpassDescriptionDepthStencilResolve::stencilResolveMode is
ignored if the VkFormat of the pDepthStencilResolveAttachment
does not have a stencil component.
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_QCOMis 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_ARM_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARM = 0x00000010,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM = 0x00000020,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM = 0x00000040,
} VkSubpassDescriptionFlagBits;
-
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVXspecifies 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_NVXspecifies 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_QCOMspecifies 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_QCOMspecifies that the subpass performs shader resolve operations. -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARMspecifies that this subpass supports pipelines created withVK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM. -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARMspecifies that this subpass supports pipelines created withVK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM. -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARMspecifies that this subpass supports pipelines created withVK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM.
|
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 begining 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;
-
attachmentis either an integer value identifying an attachment at the corresponding index in VkRenderPassCreateInfo::pAttachments, orVK_ATTACHMENT_UNUSEDto signify that this attachment is not used. -
layoutis 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;
-
srcSubpassis the subpass index of the first subpass in the dependency, orVK_SUBPASS_EXTERNAL. -
dstSubpassis the subpass index of the second subpass in the dependency, orVK_SUBPASS_EXTERNAL. -
srcStageMaskis a bitmask of VkPipelineStageFlagBits specifying the source stage mask. -
dstStageMaskis a bitmask of VkPipelineStageFlagBits specifying the destination stage mask -
srcAccessMaskis a bitmask of VkAccessFlagBits specifying a source access mask. -
dstAccessMaskis a bitmask of VkAccessFlagBits specifying a destination access mask. -
dependencyFlagsis a bitmask of VkDependencyFlagBits.
If srcSubpass is equal to dstSubpass then the
VkSubpassDependency describes a
subpass
self-dependency, and only constrains the pipeline barriers allowed within
a subpass instance.
Otherwise, when a render pass instance which includes a subpass dependency
is submitted to a queue, it defines a memory 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 or 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. |
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;
};
If a subpass uses the same attachment as both an input attachment and either a color attachment or a depth/stencil attachment, writes via the color or depth/stencil attachment are not automatically made visible to reads via the input attachment, causing a feedback loop, except in any of the following conditions:
-
If the color components or depth/stencil components read by the input attachment are mutually exclusive with the components written by the color or depth/stencil attachments, then there is no feedback loop. This requires the graphics pipelines used by the subpass to disable writes to color components that are read as inputs via the
colorWriteEnableorcolorWriteMask, and to disable writes to depth/stencil components that are read as inputs viadepthWriteEnableorstencilTestEnable. -
If the attachment is used as an input attachment and depth/stencil attachment only, and the depth/stencil attachment is not written to.
Rendering within a subpass containing a feedback loop creates a data race, except in the following cases:
-
If a memory dependency is inserted between when the attachment is written and when it is subsequently read by later fragments. Pipeline barriers expressing a subpass self-dependency are the only way to achieve this, and one must be inserted every time a fragment will read values at a particular sample (x, y, layer, sample) coordinate, if those values have been written since the most recent pipeline barrier; or since the start of the subpass, if there have been no pipeline barriers since the start of the subpass.
-
If the attachment is used as color and input attachment, and the pipeline performing the read was created with
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARMincluded in theflagsmember of thepColorBlendStatemember of its VkGraphicsPipelineCreateInfo. This creates a framebuffer-local memory dependency for each fragment generated by draw commands using this pipeline with the following properties:-
The first synchronization scope includes the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage executed by all previous fragments (as defined by primitive order) in the corresponding framebuffer regions including those generated by the same draw command. -
The second synchronization scope includes the
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BITpipeline stage executed by the generated fragment. -
The first access scope includes all writes to color attachments.
-
The second access scope includes all reads from input attachments.
-
-
If the attachment is used as depth/stencil and input attachment, and the pipeline performs a read of the depth aspect and was created with
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARMincluded in theflagsmember of thepDepthStencilStatemember of its VkGraphicsPipelineCreateInfo. This creates a memory dependency for each fragment generated by draw commands using this pipeline with the following properties:-
The first synchronization scope includes
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BITVK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BITpipeline stages executed by all previous fragments (as defined by primitive order) in the corresponding framebuffer regions including those generated by the same draw command. -
The second synchronization scope includes
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BITandVK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BITpipeline stages executed by the generated fragment. -
The first access scope includes all writes to the depth aspect of depth/stencil attachments.
-
The second access scope includes all reads from the depth aspect of input attachments.
-
-
If the attachment is used as depth/stencil and input attachment, and the pipeline performs a read of the stencil aspect and was created with
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARMincluded in theflagsmember of thepDepthStencilStatemember of its VkGraphicsPipelineCreateInfo. This creates a memory dependency for each fragment generated by draw commands using this pipeline with the following properties:-
The first synchronization scope includes
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BITVK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BITpipeline stages executed by all previous fragments (as defined by primitive order) in the corresponding framebuffer regions including those generated by the same draw command. -
The second synchronization scope includes
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BITandVK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BITpipeline stages executed by the generated fragment. -
The first access scope includes all writes to the stencil aspect of depth/stencil attachments.
-
The second access scope includes all reads from the stencil aspect of input attachments.
-
An attachment must not be used as both a depth/stencil attachment and a color attachment.
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);
-
deviceis the logical device that creates the render pass. -
pCreateInfois a pointer to a VkRenderPassCreateInfo2 structure describing the parameters of the render pass. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pRenderPassis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
attachmentCountis the number of attachments used by this render pass. -
pAttachmentsis a pointer to an array ofattachmentCountVkAttachmentDescription2 structures describing the attachments used by the render pass. -
subpassCountis the number of subpasses to create. -
pSubpassesis a pointer to an array ofsubpassCountVkSubpassDescription2 structures describing each subpass. -
dependencyCountis the number of dependencies between pairs of subpasses. -
pDependenciesis a pointer to an array ofdependencyCountVkSubpassDependency2 structures describing dependencies between pairs of subpasses. -
correlatedViewMaskCountis the number of correlation masks. -
pCorrelatedViewMasksis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkAttachmentDescriptionFlagBits specifying additional properties of the attachment. -
formatis a VkFormat value specifying the format of the image that will be used for the attachment. -
samplesis a VkSampleCountFlagBits value specifying the number of samples of the image. -
loadOpis 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. -
storeOpis 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. -
stencilLoadOpis 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. -
stencilStoreOpis 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. -
initialLayoutis the layout the attachment image subresource will be in when a render pass instance begins. -
finalLayoutis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stencilInitialLayoutis the layout the stencil aspect of the attachment image subresource will be in when a render pass instance begins. -
stencilFinalLayoutis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkSubpassDescriptionFlagBits specifying usage of the subpass. -
pipelineBindPointis a VkPipelineBindPoint value specifying the pipeline type supported for this subpass. -
viewMaskis a bitfield of view indices describing which views rendering is broadcast to in this subpass, when multiview is enabled. -
inputAttachmentCountis the number of input attachments. -
pInputAttachmentsis a pointer to an array of VkAttachmentReference2 structures defining the input attachments for this subpass and their layouts. -
colorAttachmentCountis the number of color attachments. -
pColorAttachmentsis a pointer to an array ofcolorAttachmentCountVkAttachmentReference2 structures defining the color attachments for this subpass and their layouts. -
pResolveAttachmentsisNULLor a pointer to an array ofcolorAttachmentCountVkAttachmentReference2 structures defining the resolve attachments for this subpass and their layouts. -
pDepthStencilAttachmentis a pointer to a VkAttachmentReference2 structure specifying the depth/stencil attachment for this subpass and its layout. -
preserveAttachmentCountis the number of preserved attachments. -
pPreserveAttachmentsis a pointer to an array ofpreserveAttachmentCountrender pass attachment indices identifying attachments that are not used by this subpass, but whose contents must be preserved throughout the subpass.
Parameters defined by this structure with the same name as those in VkSubpassDescription have the identical effect to those parameters.
viewMask has the same effect for the described subpass as
VkRenderPassMultiviewCreateInfo::pViewMasks has on each
corresponding subpass.
If a VkFragmentShadingRateAttachmentInfoKHR structure is included in
the pNext chain, pFragmentShadingRateAttachment is not NULL,
and its attachment member is not VK_ATTACHMENT_UNUSED, the
identified attachment defines a fragment shading rate attachment for that
subpass.
If the pNext chain of VkSubpassDescription2 includes a
VkSubpassDescriptionDepthStencilResolve structure, then that structure
describes multisample resolve operations for the depth/stencil attachment in
a 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
depthResolveModeis a VkResolveModeFlagBits value describing the depth resolve mode. -
stencilResolveModeis a VkResolveModeFlagBits value describing the stencil resolve mode. -
pDepthStencilResolveAttachmentisNULLor a pointer to a VkAttachmentReference2 structure defining the depth/stencil resolve attachment for this subpass and its layout.
If pDepthStencilResolveAttachment is NULL, or if its attachment
index is VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil
resolve attachment will be used in the subpass.
Possible values of
VkSubpassDescriptionDepthStencilResolve::depthResolveMode and
stencilResolveMode, specifying the depth and stencil resolve modes,
are:
// 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_NONEindicates that no resolve operation is done. -
VK_RESOLVE_MODE_SAMPLE_ZERO_BITindicates that result of the resolve operation is equal to the value of sample 0. -
VK_RESOLVE_MODE_AVERAGE_BITindicates that result of the resolve operation is the average of the sample values. -
VK_RESOLVE_MODE_MIN_BITindicates that result of the resolve operation is the minimum of the sample values. -
VK_RESOLVE_MODE_MAX_BITindicates that result of the resolve operation is the maximum of the sample values.
// 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.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pFragmentShadingRateAttachmentisNULLor a pointer to a VkAttachmentReference2 structure defining the fragment shading rate attachment for this subpass. -
shadingRateAttachmentTexelSizespecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
multisampledRenderToSingleSampledEnablecontrols whether multisampled rendering to single-sampled attachments is performed as described below. -
rasterizationSamplesis 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
loadOpequals toVK_ATTACHMENT_LOAD_OP_LOAD, samples of the implicit image are initialized by replicating the value from the corresponding pixel in the attachment. -
If
storeOporstencilStoreOpis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentis either an integer value identifying an attachment at the corresponding index in VkRenderPassCreateInfo2::pAttachments, orVK_ATTACHMENT_UNUSEDto signify that this attachment is not used. -
layoutis a VkImageLayout value specifying the layout the attachment uses during the subpass. -
aspectMaskis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stencilLayoutis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSubpassis the subpass index of the first subpass in the dependency, orVK_SUBPASS_EXTERNAL. -
dstSubpassis the subpass index of the second subpass in the dependency, orVK_SUBPASS_EXTERNAL. -
srcStageMaskis a bitmask of VkPipelineStageFlagBits specifying the source stage mask. -
dstStageMaskis a bitmask of VkPipelineStageFlagBits specifying the destination stage mask -
srcAccessMaskis a bitmask of VkAccessFlagBits specifying a source access mask. -
dstAccessMaskis a bitmask of VkAccessFlagBits specifying a destination access mask. -
dependencyFlagsis a bitmask of VkDependencyFlagBits. -
viewOffsetcontrols 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);
-
deviceis the logical device that destroys the render pass. -
renderPassis the handle of the render pass to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
8.2. 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.3. 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);
-
deviceis the logical device that creates the framebuffer. -
pCreateInfois a pointer to a VkFramebufferCreateInfo structure describing additional information about framebuffer creation. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pFramebufferis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkFramebufferCreateFlagBits -
renderPassis a render pass defining what render passes the framebuffer will be compatible with. See Render Pass Compatibility for details. -
attachmentCountis the number of attachments. -
pAttachmentsis a pointer to an array of VkImageView handles, each of which will be used as the corresponding attachment in a render pass instance. IfflagsincludesVK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, this parameter is ignored. -
width,heightandlayersdefine the dimensions of the framebuffer. If the render pass uses multiview, thenlayersmust 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.
Applications must ensure that all non-attachment writes to memory backing image subresources that are used as attachments in a render pass instance happen-before or happen-after the render pass instance. If an image subresource is written during a render pass instance by anything other than load operations, store operations, and layout transitions, applications must ensure that all non-attachment reads from memory backing that image subresource happen-before or happen-after the render pass instance. For depth/stencil images, the aspects are not treated independently for the above guarantees - writes to either aspect must be synchronized with accesses to the other aspect.
|
Note
An image subresource can be used as read-only as both an attachment and a non-attachment during a render pass instance, but care must still be taken to avoid data races with load/store operations and layout transitions. The simplest way to achieve this is to keep the non-attachment and attachment accesses within the same subpass, or to avoid layout transitions and load/store operations that perform writes. |
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.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentImageInfoCountis the number of attachments being described. -
pAttachmentImageInfosis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkImageCreateFlagBits, matching the value of VkImageCreateInfo::flagsused to create an image that will be used with this framebuffer. -
usageis a bitmask of VkImageUsageFlagBits, matching the value of VkImageCreateInfo::usageused to create an image used with this framebuffer. -
widthis the width of the image view used for rendering. -
heightis the height of the image view used for rendering. -
layerCountis the number of array layers of the image view used for rendering. -
viewFormatCountis the number of entries in thepViewFormatsarray, matching the value of VkImageFormatListCreateInfo::viewFormatCountused to create an image used with this framebuffer. -
pViewFormatsis 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::pViewFormatsused 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_BITspecifies 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);
-
deviceis the logical device that destroys the framebuffer. -
framebufferis the handle of the framebuffer to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
8.4. 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);
-
commandBufferis the command buffer in which to record the command. -
pRenderPassBeginis a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses. -
contentsis 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);
-
commandBufferis the command buffer in which to record the command. -
pRenderPassBeginis a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses. -
pSubpassBeginInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
renderPassis the render pass to begin an instance of. -
framebufferis the framebuffer containing the attachments that are used with the render pass. -
renderAreais the render area that is affected by the render pass instance, and is described in more detail below. -
clearValueCountis the number of elements inpClearValues. -
pClearValuesis a pointer to an array ofclearValueCountVkClearValue structures containing clear values for each attachment, if the attachment uses aloadOpvalue ofVK_ATTACHMENT_LOAD_OP_CLEARor if the attachment has a depth/stencil format and uses astencilLoadOpvalue ofVK_ATTACHMENT_LOAD_OP_CLEAR. The array is indexed by attachment number. Only elements corresponding to cleared attachments are used. Other elements ofpClearValuesare 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 the subpassShading feature is enabled,
then renderArea must equal the framebuffer dimensions.
When multiview is enabled, the resolve operation at the end of a subpass applies to all views in the view mask.
|
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentInitialSampleLocationsCountis the number of elements in thepAttachmentInitialSampleLocationsarray. -
pAttachmentInitialSampleLocationsis a pointer to an array ofattachmentInitialSampleLocationsCountVkAttachmentSampleLocationsEXT structures specifying the attachment indices and their corresponding sample location state. Each element ofpAttachmentInitialSampleLocationscan 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. -
postSubpassSampleLocationsCountis the number of elements in thepPostSubpassSampleLocationsarray. -
pPostSubpassSampleLocationsis a pointer to an array ofpostSubpassSampleLocationsCountVkSubpassSampleLocationsEXT structures specifying the subpass indices and their corresponding sample location state. Each element ofpPostSubpassSampleLocationscan 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::variableSampleLocationsisVK_FALSE, each element ofpPostSubpassSampleLocationsmust 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. IfvariableSampleLocationsisVK_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;
-
attachmentIndexis the index of the attachment for which the sample locations state is provided. -
sampleLocationsInfois 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;
-
subpassIndexis the index of the subpass for which the sample locations state is provided. -
sampleLocationsInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
transformis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
contentsis 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_INLINEspecifies 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_BUFFERSspecifies 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 on 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceMaskis the device mask for the render pass instance. -
deviceRenderAreaCountis the number of elements in thepDeviceRenderAreasarray. -
pDeviceRenderAreasis 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 attachment load, store, and 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentCountis the number of attachments. -
pAttachmentsis a pointer to an array ofVkImageViewhandles, each of which will be used as the corresponding attachment in the render pass instance.
To query the render area granularity, call:
// Provided by VK_VERSION_1_0
void vkGetRenderAreaGranularity(
VkDevice device,
VkRenderPass renderPass,
VkExtent2D* pGranularity);
-
deviceis the logical device that owns the render pass. -
renderPassis a handle to a render pass. -
pGranularityis a pointer to a VkExtent2D structure in which the granularity is returned.
The conditions leading to an optimal renderArea are:
-
the
offset.xmember inrenderAreais a multiple of thewidthmember of the returned VkExtent2D (the horizontal granularity). -
the
offset.ymember inrenderAreais a multiple of theheightmember of the returned VkExtent2D (the vertical granularity). -
either the
extent.widthmember inrenderAreais a multiple of the horizontal granularity oroffset.x+extent.widthis equal to thewidthof theframebufferin the VkRenderPassBeginInfo. -
either the
extent.heightmember inrenderAreais a multiple of the vertical granularity oroffset.y+extent.heightis equal to theheightof theframebufferin 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);
-
commandBufferis the command buffer in which to record the command. -
contentsspecifies 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.
Moving to the next subpass automatically performs any multisample resolve
operations in the subpass being ended.
End-of-subpass multisample resolves are treated as color attachment writes
for the purposes of synchronization.
This applies to resolve operations for both color and depth/stencil
attachments.
That is, they are considered to execute in the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their
writes are synchronized with VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
Synchronization between rendering within a subpass and any resolve
operations at the end of the subpass occurs automatically, without need for
explicit dependencies or pipeline barriers.
However, if the resolve attachment is also used in a different subpass, an
explicit dependency is needed.
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);
-
commandBufferis the command buffer in which to record the command. -
pSubpassBeginInfois a pointer to a VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering. -
pSubpassEndInfois 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);
-
commandBufferis 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);
-
commandBufferis the command buffer in which to end the current render pass instance. -
pSubpassEndInfois a pointer to a VkSubpassEndInfo structure containing information about how the previous 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;
-
sTypeis the type of this structure. -
pNextisNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityOffsetCountis the number of offsets being specified. -
pFragmentDensityOffsetsis 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
renderpass does not include
VkSubpassFragmentDensityMapOffsetEndInfoQCOM, or if
fragmentDensityOffsetCount is zero, then the offset (0,0) is
used for Fetch Density Value.
8.5. 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to an extension-specific structure. -
disallowMergingis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to an extension-specific structure. -
pRenderPassFeedbackis 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;
-
postMergeSubpassCountis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to an extension-specific structure. -
pSubpassFeedbackis 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;
-
subpassMergeStatusis aVkSubpassMergeStatusEXTvalue specifying information about whether the subpass is merged with previous subpass and the reason why it is not merged. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which provides additional details. -
postMergeIndexis 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_EXTspecifies the subpass is merged with a previous subpass. -
VK_SUBPASS_MERGE_STATUS_DISALLOWED_EXTspecifies 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_EXTspecifies the subpass is not merged because it contains side effects. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SAMPLES_MISMATCH_EXTspecifies the subpass is not merged because sample count is not compatible with previous subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_VIEWS_MISMATCH_EXTspecifies the subpass is not merged because view masks do not match with previous subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_ALIASING_EXTspecifies the subpass is not merged because of attachments aliasing between them. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPENDENCIES_EXTspecifies the subpass is not merged because subpass dependencies do not allow merging. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INCOMPATIBLE_INPUT_ATTACHMENT_EXTspecifies 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_EXTspecifies the subpass is not merged because of too many attachments. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INSUFFICIENT_STORAGE_EXTspecifies the subpass is not merged because of insufficient memory. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPTH_STENCIL_COUNT_EXTspecifies the subpass is not merged because of too many depth/stencil attachments. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_RESOLVE_ATTACHMENT_REUSE_EXTspecifies 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_EXTspecifies the subpass is not merged because the render pass has only one subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_UNSPECIFIED_EXTspecifies 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.
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);
-
deviceis the logical device that creates the shader module. -
pCreateInfois a pointer to a VkShaderModuleCreateInfo structure. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pShaderModuleis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
codeSizeis the size, in bytes, of the code pointed to bypCode. -
pCodeis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
validationCacheis 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);
-
deviceis the logical device that destroys the shader module. -
shaderModuleis the handle of the shader module to destroy. -
pAllocatorcontrols 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);
-
deviceis the logical device that created the shader module. -
shaderModuleis the handle of the shader module. -
pIdentifieris 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);
-
deviceis the logical device that can create a VkShaderModule frompCreateInfo. -
pCreateInfois a pointer to a VkShaderModuleCreateInfo structure. -
pIdentifieris 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
identifierSizeis the size, in bytes, of valid data returned inidentifier. -
identifieris 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.
9.3. 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. 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.5. 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.6. 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. The only fixed output of the task shader is a task count, identifying the number of mesh shader workgroups to create. The task shader can write additional outputs to task memory, which can be read by all of the mesh shader workgroups it created.
9.6.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.
9.7. 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.7.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 explcitly via the API, or implicitly through the task shader’s work creation mechanism.
9.8. 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.8.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.9. 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
void vkCmdSetPatchControlPointsEXT(
VkCommandBuffer commandBuffer,
uint32_t patchControlPoints);
-
commandBufferis the command buffer into which the command will be recorded. -
patchControlPointsspecifies 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.9.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.10. 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.11. 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.11.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.12. 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.13. 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.14. 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.14.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.15. 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.15.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.16. 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.16.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.17. 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.18. 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.19. Callable Shaders
Callable shaders can access a callable payload that works similarly to ray payloads to do subroutine work.
9.20. 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.
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
Centroiddecoration is used, the interpolation position used for the variable must also fall within the bounds of the primitive being rasterized. -
If the
Sampledecoration 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.21. 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.
Static use is not used to control the behavior of variables with Input
and Output storage.
The effects of those variables are applied based only on whether they are
present in a shader entry point’s interface.
9.22. 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.22.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.22.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.22.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.22.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.22.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.22.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.22.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.
9.22.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.
9.22.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.22.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
SampleInterlockOrderedEXTorSampleInterlockUnorderedEXTexecution modes are used, only invocations with identical framebuffer locations (x,y,layer,sample) are included. -
If the
PixelInterlockOrderedEXTorPixelInterlockUnorderedEXTexecution modes are used, fragments with different sample ids are also included. -
If the
ShadingRateInterlockOrderedEXTorShadingRateInterlockUnorderedEXTexecution modes are used, fragments from neighbouring framebuffer locations are also included, as determined by the shading rate.
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.22.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.23. 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.23.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.23.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.23.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.23.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.23.5. Shuffle Group Operations
The shuffle group operations allow invocations to read values from other invocations within a group.
9.23.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.23.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.24. 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.25. 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 level of detail 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.26. 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, and values returned by atomic instructions in helper invocations
are undefined.
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.27. 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);
-
physicalDeviceis the physical device. -
pPropertyCountis a pointer to an integer related to the number of cooperative matrix properties available or queried. -
pPropertiesis eitherNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
MSizeis the number of rows in matrices A, C, and D. -
KSizeis the number of columns in matrix A and rows in matrix B. -
NSizeis the number of columns in matrices B, C, D. -
ATypeis the component type of matrix A, of type VkComponentTypeNV. -
BTypeis the component type of matrix B, of type VkComponentTypeNV. -
CTypeis the component type of matrix C, of type VkComponentTypeNV. -
DTypeis the component type of matrix D, of type VkComponentTypeNV. -
scopeis 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 VkScopeNV include:
// Provided by VK_NV_cooperative_matrix
typedef enum VkScopeNV {
VK_SCOPE_DEVICE_NV = 1,
VK_SCOPE_WORKGROUP_NV = 2,
VK_SCOPE_SUBGROUP_NV = 3,
VK_SCOPE_QUEUE_FAMILY_NV = 5,
} VkScopeNV;
-
VK_SCOPE_DEVICE_NVcorresponds to SPIR-VDevicescope. -
VK_SCOPE_WORKGROUP_NVcorresponds to SPIR-VWorkgroupscope. -
VK_SCOPE_SUBGROUP_NVcorresponds to SPIR-VSubgroupscope. -
VK_SCOPE_QUEUE_FAMILY_NVcorresponds to SPIR-VQueueFamilyscope.
All enum values match the corresponding SPIR-V value.
Possible values for VkComponentTypeNV include:
// Provided by VK_NV_cooperative_matrix
typedef enum VkComponentTypeNV {
VK_COMPONENT_TYPE_FLOAT16_NV = 0,
VK_COMPONENT_TYPE_FLOAT32_NV = 1,
VK_COMPONENT_TYPE_FLOAT64_NV = 2,
VK_COMPONENT_TYPE_SINT8_NV = 3,
VK_COMPONENT_TYPE_SINT16_NV = 4,
VK_COMPONENT_TYPE_SINT32_NV = 5,
VK_COMPONENT_TYPE_SINT64_NV = 6,
VK_COMPONENT_TYPE_UINT8_NV = 7,
VK_COMPONENT_TYPE_UINT16_NV = 8,
VK_COMPONENT_TYPE_UINT32_NV = 9,
VK_COMPONENT_TYPE_UINT64_NV = 10,
} VkComponentTypeNV;
-
VK_COMPONENT_TYPE_FLOAT16_NVcorresponds to SPIR-VOpTypeFloat16. -
VK_COMPONENT_TYPE_FLOAT32_NVcorresponds to SPIR-VOpTypeFloat32. -
VK_COMPONENT_TYPE_FLOAT64_NVcorresponds to SPIR-VOpTypeFloat64. -
VK_COMPONENT_TYPE_SINT8_NVcorresponds to SPIR-VOpTypeInt8 1. -
VK_COMPONENT_TYPE_SINT16_NVcorresponds to SPIR-VOpTypeInt16 1. -
VK_COMPONENT_TYPE_SINT32_NVcorresponds to SPIR-VOpTypeInt32 1. -
VK_COMPONENT_TYPE_SINT64_NVcorresponds to SPIR-VOpTypeInt64 1. -
VK_COMPONENT_TYPE_UINT8_NVcorresponds to SPIR-VOpTypeInt8 0. -
VK_COMPONENT_TYPE_UINT16_NVcorresponds to SPIR-VOpTypeInt16 0. -
VK_COMPONENT_TYPE_UINT32_NVcorresponds to SPIR-VOpTypeInt32 0. -
VK_COMPONENT_TYPE_UINT64_NVcorresponds to SPIR-VOpTypeInt64 0.
9.28. 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);
-
deviceis the logical device that creates the validation cache object. -
pCreateInfois a pointer to a VkValidationCacheCreateInfoEXT structure containing the initial parameters for the validation cache object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pValidationCacheis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
initialDataSizeis the number of bytes inpInitialData. IfinitialDataSizeis zero, the validation cache will initially be empty. -
pInitialDatais 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. IfinitialDataSizeis zero,pInitialDatais 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);
-
deviceis the logical device that owns the validation cache objects. -
dstCacheis the handle of the validation cache to merge results into. -
srcCacheCountis the length of thepSrcCachesarray. -
pSrcCachesis a pointer to an array of validation cache handles, which will be merged intodstCache. The previous contents ofdstCacheare 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);
-
deviceis the logical device that owns the validation cache. -
validationCacheis the validation cache to retrieve data from. -
pDataSizeis a pointer to a value related to the amount of data in the validation cache, as described below. -
pDatais eitherNULLor 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_EXTspecifies 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);
-
deviceis the logical device that destroys the validation cache object. -
validationCacheis the handle of the validation cache to destroy. -
pAllocatorcontrols 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.
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);
-
deviceis the logical device that creates the compute pipelines. -
pipelineCacheis 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. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkComputePipelineCreateInfo structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis 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
pPipelinesarray is created based on the corresponding element of thepCreateInfosarray”? 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageis a VkPipelineShaderStageCreateInfo structure describing the compute shader. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandleis a pipeline to derive from -
basePipelineIndexis an index into thepCreateInfosparameter 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineShaderStageCreateFlagBits specifying how the pipeline shader stage will be generated. -
stageis a VkShaderStageFlagBits value specifying a single pipeline stage. -
moduleis optionally a VkShaderModule object containing the shader code for this stage. -
pNameis a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage. -
pSpecializationInfois a pointer to a VkSpecializationInfo structure, as described in Specialization Constants, orNULL.
If the graphicsPipelineLibrary
feature is enabled and an instance of VkShaderModuleCreateInfo is
included in the pNext chain, module can be
VK_NULL_HANDLE.
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_BITspecifies that theSubgroupSizemay vary in the shader stage. -
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BITspecifies that the subgroup sizes must be launched with all invocations active in the 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_NV_mesh_shader
VK_SHADER_STAGE_TASK_BIT_NV = 0x00000040,
// Provided by VK_NV_mesh_shader
VK_SHADER_STAGE_MESH_BIT_NV = 0x00000080,
// Provided by VK_HUAWEI_subpass_shading
VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI = 0x00004000,
// 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,
} VkShaderStageFlagBits;
-
VK_SHADER_STAGE_VERTEX_BITspecifies the vertex stage. -
VK_SHADER_STAGE_TESSELLATION_CONTROL_BITspecifies the tessellation control stage. -
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BITspecifies the tessellation evaluation stage. -
VK_SHADER_STAGE_GEOMETRY_BITspecifies the geometry stage. -
VK_SHADER_STAGE_FRAGMENT_BITspecifies the fragment stage. -
VK_SHADER_STAGE_COMPUTE_BITspecifies the compute stage. -
VK_SHADER_STAGE_ALL_GRAPHICSis a combination of bits used as shorthand to specify all graphics stages defined above (excluding the compute stage). -
VK_SHADER_STAGE_ALLis 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_NVspecifies the task stage. -
VK_SHADER_STAGE_MESH_BIT_NVspecifies the mesh stage. -
VK_SHADER_STAGE_RAYGEN_BIT_KHRspecifies the ray generation stage. -
VK_SHADER_STAGE_ANY_HIT_BIT_KHRspecifies the any-hit stage. -
VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHRspecifies the closest hit stage. -
VK_SHADER_STAGE_MISS_BIT_KHRspecifies the miss stage. -
VK_SHADER_STAGE_INTERSECTION_BIT_KHRspecifies the intersection stage. -
VK_SHADER_STAGE_CALLABLE_BIT_KHRspecifies 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;
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
renderPassis 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. -
subpassis 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);
-
deviceis a handle to a local device object that was used to create the given render pass. -
renderPassis 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. -
pMaxWorkgroupSizeis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
storageBufferssets 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
-
-
uniformBuffersdescribes 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
-
-
vertexInputsdescribes the behaviour of out of bounds accesses made to vertex input attributes -
imagesdescribes 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_VALVE 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,VkComputePipelineCreateInfo,VkRayTracingPipelineCreateInfoKHR
The robustness behavior described byVkPipelineRobustnessCreateInfoEXTapplies to all accesses through this pipeline -
VkPipelineShaderStageCreateInfo
The robustness behavior described byVkPipelineRobustnessCreateInfoEXTapplies 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.
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_EXTspecifies that this pipeline stage follows the robustness behavior of the logical device that created this pipeline -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED_EXTspecifies 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_EXTspecifies that out of bounds accesses by this pipeline stage to the relevant resource types behave as if therobustBufferAccessfeature is enabled -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXTspecifies that out of bounds accesses by this pipeline stage to the relevant resource types behave as if therobustBufferAccessfeature 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_EXTspecifies that this pipeline stage follows the robustness behavior of the logical device that created this pipeline -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED_EXTspecifies 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_EXTspecifies that out of bounds accesses by this pipeline stage to images behave as if therobustImageAccessfeature is enabled -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2_EXTspecifies that out of bounds accesses by this pipeline stage to images behave as if therobustImageAccess2feature 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
identifierSizeis the size, in bytes, of the buffer pointed to bypIdentifier. -
pIdentifierpoints 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);
-
deviceis the logical device that creates the graphics pipelines. -
pipelineCacheis 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. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkGraphicsPipelineCreateInfo structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array ofstageCountVkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the graphics pipeline. -
pVertexInputStateis a pointer to a VkPipelineVertexInputStateCreateInfo structure defining vertex input state for use with vertex shading. -
pInputAssemblyStateis a pointer to a VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior for vertex shading, as described in Drawing Commands. -
pTessellationStateis a pointer to a VkPipelineTessellationStateCreateInfo structure defining tessellation state used by tessellation shaders. -
pViewportStateis a pointer to a VkPipelineViewportStateCreateInfo structure defining viewport state used when rasterization is enabled. -
pRasterizationStateis a pointer to a VkPipelineRasterizationStateCreateInfo structure defining rasterization state. -
pMultisampleStateis a pointer to a VkPipelineMultisampleStateCreateInfo structure defining multisample state used when rasterization is enabled. -
pDepthStencilStateis a pointer to a VkPipelineDepthStencilStateCreateInfo structure defining depth/stencil state used when rasterization is enabled for depth or stencil attachments accessed during rendering. -
pColorBlendStateis a pointer to a VkPipelineColorBlendStateCreateInfo structure defining color blend state used when rasterization is enabled for any color attachments accessed during rendering. -
pDynamicStateis 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. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
renderPassis 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. -
subpassis the index of the subpass in the render pass where this pipeline will be used. -
basePipelineHandleis a pipeline to derive from. -
basePipelineIndexis an index into thepCreateInfosparameter 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.
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:
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_EXTwas specified.-
If
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXTwas not specified, the full pipeline layout must be specified.
-
-
VkRenderPass and
subpassparameter -
The
viewMaskparameter of VkPipelineRenderingCreateInfo (formats are ignored)
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_EXTwas specified.-
If
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXTwas not specified, the full pipeline layout must be specified.
-
-
VkPipelineMultisampleStateCreateInfo if sample shading is enabled or
renderpassis not VK_NULL_HANDLE -
VkRenderPass and
subpassparameter -
The
viewMaskparameter of VkPipelineRenderingCreateInfo (formats are ignored) -
Inclusion/omission of the
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRflag -
Inclusion/omission of the
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXTflag
Fragment output state is defined by:
A complete graphics pipeline always includes
pre-rasterization shader
state, with other subsets included depending on that state.
If the pre-rasterization
shader state includes a vertex shader, then
vertex input state is included
in a complete graphics pipeline.
If the value of
VkPipelineRasterizationStateCreateInfo::rasterizerDiscardEnable
in the pre-rasterization
shader state is VK_FALSE
or the VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE dynamic state is
enabled
fragment shader state and
fragment output interface
state is included in a complete graphics pipeline.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
viewMaskis the viewMask used for rendering. -
colorAttachmentCountis the number of entries inpColorAttachmentFormats -
pColorAttachmentFormatsis a pointer to an array of VkFormat values defining the format of color attachments used in this pipeline. -
depthAttachmentFormatis a VkFormat value defining the format of the depth attachment used in this pipeline. -
stencilAttachmentFormatis a VkFormat value defining the format of the stencil attachment used in this pipeline.
When a pipeline is created without a VkRenderPass, if this structure
is present in the pNext chain of VkGraphicsPipelineCreateInfo,
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_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_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_BITspecifies 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_BITspecifies 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_BITspecifies that the pipeline to be created will be a child of a previously created parent pipeline. -
VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BITspecifies that any shader input variables decorated asViewIndexwill be assigned values as if they were decorated asDeviceIndex. -
VK_PIPELINE_CREATE_DISPATCH_BASEspecifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup. -
VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NVspecifies 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_KHRspecifies 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_KHRspecifies 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_KHRspecifies 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_KHRspecifies 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_KHRspecifies 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_KHRspecifies 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_KHRspecifies 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_KHRspecifies that triangle primitives will be skipped during traversal usingOpTraceRayKHR. -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHRspecifies that AABB primitives will be skipped during traversal usingOpTraceRayKHR. -
VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHRspecifies 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_NVspecifies that the pipeline can be used in combination with Device-Generated Commands. -
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BITspecifies that pipeline creation will fail if a compile is required for creation of a valid VkPipeline object;VK_PIPELINE_COMPILE_REQUIREDwill 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_BITspecifies that control will be returned to the application on failure of the corresponding pipeline rather than continuing to create additional pipelines. -
VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NVspecifies that the pipeline is allowed to useOpTraceRayMotionNV. -
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies that the pipeline will be used with a fragment shading rate attachment. -
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXTspecifies that the pipeline will be used with a fragment density map attachment. -
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXTspecifies 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_EXTspecifies that pipeline libraries should retain any information necessary to later perform an optimal link withVK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT.
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;
void* pNext;
VkGraphicsPipelineLibraryFlagsEXT flags;
} VkGraphicsPipelineLibraryCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis 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.
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_EXTspecifies that a pipeline will include vertex input interface state. -
VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXTspecifies that a pipeline will include pre-rasterization shader state. -
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXTspecifies that a pipeline will include fragment shader state. -
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXTspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
dynamicStateCountis the number of elements in thepDynamicStatesarray. -
pDynamicStatesis 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_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_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_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_VIEWPORTspecifies that thepViewportsstate 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 theviewportCountmember of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_SCISSORspecifies that thepScissorsstate 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 thescissorCountmember of VkPipelineViewportStateCreateInfo. -
VK_DYNAMIC_STATE_LINE_WIDTHspecifies that thelineWidthstate 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_BIASspecifies that thedepthBiasConstantFactor,depthBiasClampanddepthBiasSlopeFactorstates in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBias before any draws are performed withdepthBiasEnablein VkPipelineRasterizationStateCreateInfo set toVK_TRUE. -
VK_DYNAMIC_STATE_BLEND_CONSTANTSspecifies that theblendConstantsstate in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetBlendConstants before any draws are performed with a pipeline state withVkPipelineColorBlendAttachmentStatememberblendEnableset toVK_TRUEand any of the blend functions using a constant blend color. -
VK_DYNAMIC_STATE_DEPTH_BOUNDSspecifies that theminDepthBoundsandmaxDepthBoundsstates of VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBounds before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberdepthBoundsTestEnableset toVK_TRUE. -
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASKspecifies that thecompareMaskstate in VkPipelineDepthStencilStateCreateInfo for bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilCompareMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_STENCIL_WRITE_MASKspecifies that thewriteMaskstate in VkPipelineDepthStencilStateCreateInfo for bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilWriteMask before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_STENCIL_REFERENCEspecifies that thereferencestate in VkPipelineDepthStencilStateCreateInfo for bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilReference before any draws are performed with a pipeline state with VkPipelineDepthStencilStateCreateInfo memberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NVspecifies that thepViewportScalingsstate in VkPipelineViewportWScalingStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportWScalingNV before any draws are performed with a pipeline state with VkPipelineViewportWScalingStateCreateInfoNV memberviewportScalingEnableset toVK_TRUE -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXTspecifies that thepDiscardRectanglesstate in VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDiscardRectangleEXT before any draw or clear commands. The VkDiscardRectangleModeEXT and the number of active discard rectangles is still specified by thediscardRectangleModeanddiscardRectangleCountmembers of VkPipelineDiscardRectangleStateCreateInfoEXT. -
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXTspecifies that thesampleLocationsInfostate 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 thesampleLocationsEnablemember of VkPipelineSampleLocationsStateCreateInfoEXT. -
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NVspecifies that thepExclusiveScissorsstate in VkPipelineViewportExclusiveScissorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetExclusiveScissorNV before any drawing commands. The number of exclusive scissor rectangles used by a pipeline is still specified by theexclusiveScissorCountmember of VkPipelineViewportExclusiveScissorStateCreateInfoNV. -
VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NVspecifies that thepShadingRatePalettesstate in VkPipelineViewportShadingRateImageStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportShadingRatePaletteNV before any drawing commands. -
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NVspecifies 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_EXTspecifies that thelineStippleFactorandlineStipplePatternstate in VkPipelineRasterizationLineStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetLineStippleEXT before any draws are performed with a pipeline state with VkPipelineRasterizationLineStateCreateInfoEXT memberstippledLineEnableset toVK_TRUE. -
VK_DYNAMIC_STATE_CULL_MODEspecifies that thecullModestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetCullMode before any drawing commands. -
VK_DYNAMIC_STATE_FRONT_FACEspecifies that thefrontFacestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetFrontFace before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGYspecifies that thetopologystate 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_COUNTspecifies that theviewportCountandpViewportsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetViewportWithCount before any draw call. -
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNTspecifies that thescissorCountandpScissorsstate in VkPipelineViewportStateCreateInfo will be ignored and must be set dynamically with vkCmdSetScissorWithCount before any draw call. -
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDEspecifies that thestridestate in VkVertexInputBindingDescription will be ignored and must be set dynamically with vkCmdBindVertexBuffers2 before any draw call. -
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLEspecifies that thedepthTestEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthTestEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLEspecifies that thedepthWriteEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthWriteEnable before any draw call. -
VK_DYNAMIC_STATE_DEPTH_COMPARE_OPspecifies that thedepthCompareOpstate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthCompareOp before any draw call. -
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLEspecifies that thedepthBoundsTestEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBoundsTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLEspecifies that thestencilTestEnablestate in VkPipelineDepthStencilStateCreateInfo will be ignored and must be set dynamically with vkCmdSetStencilTestEnable before any draw call. -
VK_DYNAMIC_STATE_STENCIL_OPspecifies that thefailOp,passOp,depthFailOp, andcompareOpstates inVkPipelineDepthStencilStateCreateInfofor bothfrontandbackwill be ignored and must be set dynamically with vkCmdSetStencilOp before any draws are performed with a pipeline state withVkPipelineDepthStencilStateCreateInfomemberstencilTestEnableset toVK_TRUE -
VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXTspecifies that thepatchControlPointsstate in VkPipelineTessellationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPatchControlPointsEXT before any drawing commands. -
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLEspecifies that therasterizerDiscardEnablestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetRasterizerDiscardEnable before any drawing commands. -
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLEspecifies that thedepthBiasEnablestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBiasEnable before any drawing commands. -
VK_DYNAMIC_STATE_LOGIC_OP_EXTspecifies that thelogicOpstate in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLogicOpEXT before any drawing commands. -
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLEspecifies that theprimitiveRestartEnablestate in VkPipelineInputAssemblyStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPrimitiveRestartEnable before any drawing commands. -
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHRspecifies 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_KHRspecifies 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_EXTspecifies that thepVertexInputStatestate will be ignored and must be set dynamically with vkCmdSetVertexInputEXT before any drawing commands -
VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXTspecifies that thepColorWriteEnablesstate in VkPipelineColorWriteCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetColorWriteEnableEXT before any draw call.
10.2.1. 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
invidual 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
groupCountis the number of elements in thepGroupsarray. -
pGroupsis a pointer to an array of VkGraphicsShaderGroupCreateInfoNV structures specifying which state of the original VkGraphicsPipelineCreateInfo each shader group overrides. -
pipelineCountis the number of elements in thepPipelinesarray. -
pPipelinesis a pointer to an array of graphicsVkPipelinestructures 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array VkPipelineShaderStageCreateInfo structures specifying the set of the shader stages to be included in this shader group. -
pVertexInputStateis a pointer to a VkPipelineVertexInputStateCreateInfo structure. -
pTessellationStateis 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);
-
deviceis the logical device that creates the ray tracing pipelines. -
pipelineCacheis 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. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkRayTracingPipelineCreateInfoNV structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis 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);
-
deviceis the logical device that creates the ray tracing pipelines. -
deferredOperationis VK_NULL_HANDLE or the handle of a valid VkDeferredOperationKHR request deferral object for this command. -
pipelineCacheis 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. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkRayTracingPipelineCreateInfoKHR structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelinesis 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 re-use 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array of VkPipelineShaderStageCreateInfo structures specifying the set of the shader stages to be included in the ray tracing pipeline. -
groupCountis the number of entries in thepGroupsarray. -
pGroupsis 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. -
maxRecursionDepthis the maximum recursion depth of shaders executed by this pipeline. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandleis a pipeline to derive from. -
basePipelineIndexis an index into thepCreateInfosparameter 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated. -
stageCountis the number of entries in thepStagesarray. -
pStagesis a pointer to an array ofstageCountVkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the ray tracing pipeline. -
groupCountis the number of entries in thepGroupsarray. -
pGroupsis a pointer to an array ofgroupCountVkRayTracingShaderGroupCreateInfoKHR structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline. -
maxPipelineRayRecursionDepthis the maximum recursion depth of shaders executed by this pipeline. -
pLibraryInfois a pointer to a VkPipelineLibraryCreateInfoKHR structure defining pipeline libraries to include. -
pLibraryInterfaceis a pointer to a VkRayTracingPipelineInterfaceCreateInfoKHR structure defining additional information when using pipeline libraries. -
pDynamicStateis 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. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
basePipelineHandleis a pipeline to derive from. -
basePipelineIndexis an index into thepCreateInfosparameter 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis the type of hit group specified in this structure. -
generalShaderis the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoNV::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV, andVK_SHADER_UNUSED_NVotherwise. -
closestHitShaderis the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoNV::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NVorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, andVK_SHADER_UNUSED_NVotherwise. -
anyHitShaderis the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoNV::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NVorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, andVK_SHADER_UNUSED_NVotherwise. -
intersectionShaderis the index of the intersection shader from VkRayTracingPipelineCreateInfoNV::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, andVK_SHADER_UNUSED_NVotherwise.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis the type of hit group specified in this structure. -
generalShaderis the index of the ray generation, miss, or callable shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
closestHitShaderis the optional index of the closest hit shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHRorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
anyHitShaderis the optional index of the any-hit shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHRorVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
intersectionShaderis the index of the intersection shader from VkRayTracingPipelineCreateInfoKHR::pStagesin the group if the shader group hastypeofVK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, andVK_SHADER_UNUSED_KHRotherwise. -
pShaderGroupCaptureReplayHandleisNULLor a pointer to replay information for this shader group. Ignored if VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayisVK_FALSE.
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_KHRindicates a shader group with a singleVK_SHADER_STAGE_RAYGEN_BIT_KHR,VK_SHADER_STAGE_MISS_BIT_KHR, orVK_SHADER_STAGE_CALLABLE_BIT_KHRshader in it. -
VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHRspecifies 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_KHRspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxPipelineRayPayloadSizeis the maximum payload size in bytes used by any shader in the pipeline. -
maxPipelineRayHitAttributeSizeis 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);
-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders. -
firstGroupis the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroupsor VkRayTracingPipelineCreateInfoNV::pGroupsarray. -
groupCountis the number of shader handles to retrieve. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to a user-allocated buffer where the results will be written.
To query the optional capture handle information of shaders in the 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);
-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders. -
firstGroupis the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::pGroupsarray. -
groupCountis the number of shader handles to retrieve. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to a user-allocated buffer where the results will be written.
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);
-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders. -
shaderis 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);
-
deviceis the logical device containing the ray tracing pipeline. -
pipelineis the ray tracing pipeline object containing the shaders groups. -
groupis the index of the shader group to query. -
groupShaderis 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_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::generalShader -
VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::closestHitShader -
VK_SHADER_GROUP_SHADER_ANY_HIT_KHRuses the shader specified in the group with VkRayTracingShaderGroupCreateInfoKHR::anyHitShader -
VK_SHADER_GROUP_SHADER_INTERSECTION_KHRuses 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);
-
commandBufferis the command buffer into which the command will be recorded. -
pipelineStackSizeis 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);
-
deviceis the logical device that destroys the pipeline. -
pipelineis the handle of the pipeline to destroy. -
pAllocatorcontrols 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.
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);
-
deviceis the logical device that creates the pipeline cache object. -
pCreateInfois a pointer to a VkPipelineCacheCreateInfo structure containing initial parameters for the pipeline cache object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelineCacheis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCacheCreateFlagBits specifying the behavior of the pipeline cache. -
initialDataSizeis the number of bytes inpInitialData. IfinitialDataSizeis zero, the pipeline cache will initially be empty. -
pInitialDatais 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. IfinitialDataSizeis zero,pInitialDatais 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_BITspecifies 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);
-
deviceis the logical device that owns the pipeline cache objects. -
dstCacheis the handle of the pipeline cache to merge results into. -
srcCacheCountis the length of thepSrcCachesarray. -
pSrcCachesis a pointer to an array of pipeline cache handles, which will be merged intodstCache. The previous contents ofdstCacheare 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);
-
deviceis the logical device that owns the pipeline cache. -
pipelineCacheis the pipeline cache to retrieve data from. -
pDataSizeis a pointer to asize_tvalue related to the amount of data in the pipeline cache, as described below. -
pDatais eitherNULLor 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.
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;
-
headerSizeis the length in bytes of the pipeline cache header. -
headerVersionis 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. -
vendorIDis theVkPhysicalDeviceProperties::vendorIDof the implementation. -
deviceIDis theVkPhysicalDeviceProperties::deviceIDof the implementation. -
pipelineCacheUUIDis theVkPhysicalDeviceProperties::pipelineCacheUUIDof 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_ONEspecifies version one of the pipeline cache.
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);
-
deviceis the logical device that destroys the pipeline cache object. -
pipelineCacheis the handle of the pipeline cache to destroy. -
pAllocatorcontrols 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;
-
mapEntryCountis the number of entries in thepMapEntriesarray. -
pMapEntriesis a pointer to an array ofVkSpecializationMapEntrystructures which map constant IDs to offsets inpData. -
dataSizeis the byte size of thepDatabuffer. -
pDatacontains 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;
-
constantIDis the ID of the specialization constant in SPIR-V. -
offsetis the byte offset of the specialization constant value within the supplied data buffer. -
sizeis 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[] =
{
{
13, // constantID
0 * sizeof(uint32_t), // offset
sizeof(uint32_t) // size
},
{
42, // constantID
1 * sizeof(uint32_t), // offset
sizeof(uint32_t) // size
},
{
3, // constantID
2 * sizeof(uint32_t), // offset
sizeof(uint32_t) // size
}
};
const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4
const VkSpecializationInfo info =
{
3, // mapEntryCount
entries, // pMapEntries
3 * sizeof(uint32_t), // dataSize
data, // pData
};
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[] =
{
{
0, // constantID
offsetof(SpecializationData, data0), // offset
sizeof(SpecializationData::data0) // size
},
{
12, // constantID
offsetof(SpecializationData, data1), // offset
sizeof(SpecializationData::data1) // size
}
};
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 =
{
2, // mapEntryCount
entries, // pMapEntries
sizeof(data), // dataSize
&data, // pData
};
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
libraryCountis the number of pipeline libraries inpLibraries. -
pLibrariesis 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);
-
commandBufferis the command buffer that the pipeline will be bound to. -
pipelineBindPointis a VkPipelineBindPoint value specifying to which bind point the pipeline is bound. Binding one does not disturb the others. -
pipelineis 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.
-
The pipeline bound to
VK_PIPELINE_BIND_POINT_COMPUTEcontrols the behavior of all dispatching commands. -
The pipeline bound to
VK_PIPELINE_BIND_POINT_GRAPHICScontrols the behavior of all drawing commands. -
The pipeline bound to
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHRcontrols the behavior of vkCmdTraceRaysKHR and vkCmdTraceRaysIndirectKHR. -
The pipeline bound to
VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEIcontrols the behavior of vkCmdSubpassShadingHUAWEI.
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,
// 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_COMPUTEspecifies binding as a compute pipeline. -
VK_PIPELINE_BIND_POINT_GRAPHICSspecifies binding as a graphics pipeline. -
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHRspecifies binding as a ray tracing pipeline. -
VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEIspecifies 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);
-
commandBufferis the command buffer that the pipeline will be bound to. -
pipelineBindPointis a VkPipelineBindPoint value specifying the bind point to which the pipeline will be bound. -
pipelineis the pipeline to be bound. -
groupIndexis 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.
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);
-
deviceis the device that created the pipeline. -
pPipelineInfodescribes the pipeline being queried. -
pExecutableCountis a pointer to an integer related to the number of pipeline executables available or queried, as described below. -
pPropertiesis eitherNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stagesis a bitmask of zero or more VkShaderStageFlagBits indicating which shader stages (if any) were principally used as inputs to compile this pipeline executable. -
nameis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a short human readable name for this pipeline executable. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description for this pipeline executable. -
subgroupSizeis 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);
-
deviceis the logical device that created the pipeline. -
pPipelineInfois a pointer to a VkPipelineInfoEXT structure which describes the pipeline being queried. -
pPipelinePropertiesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to an extension-specific structure. -
pipelineIdentifieris an array ofVK_UUID_SIZEuint8_tvalues 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineis aVkPipelinehandle.
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);
-
deviceis the device that created the pipeline. -
pExecutableInfodescribes the pipeline executable being queried. -
pStatisticCountis a pointer to an integer related to the number of statistics available or queried, as described below. -
pStatisticsis eitherNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineis the pipeline to query. -
executableIndexis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nameis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a short human readable name for this statistic. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description for this statistic. -
formatis a VkPipelineExecutableStatisticFormatKHR value specifying the format of the data found invalue. -
valueis 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_KHRspecifies that the statistic is returned as a 32-bit boolean value which must be eitherVK_TRUEorVK_FALSEand should be read from theb32field ofVkPipelineExecutableStatisticValueKHR. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHRspecifies that the statistic is returned as a signed 64-bit integer and should be read from thei64field ofVkPipelineExecutableStatisticValueKHR. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHRspecifies that the statistic is returned as an unsigned 64-bit integer and should be read from theu64field ofVkPipelineExecutableStatisticValueKHR. -
VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHRspecifies that the statistic is returned as a 64-bit floating-point value and should be read from thef64field 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;
-
b32is the 32-bit boolean value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR. -
i64is the signed 64-bit integer value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR. -
u64is the unsigned 64-bit integer value if theVkPipelineExecutableStatisticFormatKHRisVK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR. -
f64is the 64-bit floating-point value if theVkPipelineExecutableStatisticFormatKHRisVK_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);
-
deviceis the device that created the pipeline. -
pExecutableInfodescribes the pipeline executable being queried. -
pInternalRepresentationCountis a pointer to an integer related to the number of internal representations available or queried, as described below. -
pInternalRepresentationsis eitherNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nameis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a short human readable name for this internal representation. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description for this internal representation. -
isTextspecifies whether the returned data is text or opaque data. IfisTextisVK_TRUEthen the data returned inpDatais text and is guaranteed to be a null-terminated UTF-8 string. -
dataSizeis an integer related to the size, in bytes, of the internal representation’s data, as described below. -
pDatais eitherNULLor 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);
-
deviceis the device that createdpipeline. -
pipelineis the target of the query. -
shaderStageis a VkShaderStageFlagBits specifying the particular shader within the pipeline about which information is being queried. -
infoTypedescribes what kind of information is being queried. -
pInfoSizeis a pointer to a value related to the amount of data the query returns, as described below. -
pInfois eitherNULLor 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_AMDspecifies that device resources used by a shader will be queried. -
VK_SHADER_INFO_TYPE_BINARY_AMDspecifies that implementation-specific information will be queried. -
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMDspecifies that human-readable dissassembly 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;
-
shaderStageMaskare the combination of logical shader stages contained within this shader. -
resourceUsageis a VkShaderResourceUsageAMD structure describing internal physical device resources used by this shader. -
numPhysicalVgprsis the maximum number of vector instruction general-purpose registers (VGPRs) available to the physical device. -
numPhysicalSgprsis the maximum number of scalar instruction general-purpose registers (SGPRs) available to the physical device. -
numAvailableVgprsis the maximum limit of VGPRs made available to the shader compiler. -
numAvailableSgprsis the maximum limit of SGPRs made available to the shader compiler. -
computeWorkGroupSizeis 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;
-
numUsedVgprsis the number of vector instruction general-purpose registers used by this shader. -
numUsedSgprsis the number of scalar instruction general-purpose registers used by this shader. -
ldsSizePerLocalWorkGroupis the maximum local data store size per work group in bytes. -
ldsUsageSizeInBytesis the LDS usage size in bytes per work group by this shader. -
scratchMemUsageInBytesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
compilerControlFlagsis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pPipelineCreationFeedbackis a pointer to a VkPipelineCreationFeedback structure. -
pipelineStageCreationFeedbackCountis the number of elements inpPipelineStageCreationFeedbacks. -
pPipelineStageCreationFeedbacksis a pointer to an array ofpipelineStageCreationFeedbackCountVkPipelineCreationFeedback 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;
-
flagsis a bitmask of VkPipelineCreationFeedbackFlagBits providing feedback about the creation of a pipeline or of a pipeline stage. -
durationis 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_BITindicates that the feedback information is valid. -
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BITindicates that a readily usable pipeline or pipeline stage was found in thepipelineCachespecified by the application in the pipeline creation command.An implementation should set the
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BITbit if it was able to avoid the large majority of pipeline or pipeline stage creation work by using thepipelineCacheparameter 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_BITindicates that the base pipeline specified by thebasePipelineHandleorbasePipelineIndexmember of theVk*PipelineCreateInfostructure was used to accelerate the creation of the pipeline.An implementation should set the
VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BITbit 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;
-
pUserDatais a value to be interpreted by the implementation of the callbacks. When any of the callbacks inVkAllocationCallbacksare 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. -
pfnAllocationis a PFN_vkAllocationFunction pointer to an application-defined memory allocation function. -
pfnReallocationis a PFN_vkReallocationFunction pointer to an application-defined memory reallocation function. -
pfnFreeis a PFN_vkFreeFunction pointer to an application-defined memory free function. -
pfnInternalAllocationis a PFN_vkInternalAllocationNotification pointer to an application-defined function that is called by the implementation when the implementation makes internal allocations. -
pfnInternalFreeis 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);
-
pUserDatais the value specified for VkAllocationCallbacks::pUserDatain the allocator specified by the application. -
sizeis the size in bytes of the requested allocation. -
alignmentis the requested alignment of the allocation in bytes and must be a power of two. -
allocationScopeis 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);
-
pUserDatais the value specified for VkAllocationCallbacks::pUserDatain the allocator specified by the application. -
pOriginalmust be eitherNULLor a pointer previously returned bypfnReallocationorpfnAllocationof a compatible allocator. -
sizeis the size in bytes of the requested allocation. -
alignmentis the requested alignment of the allocation in bytes and must be a power of two. -
allocationScopeis a VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described here.
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);
-
pUserDatais the value specified for VkAllocationCallbacks::pUserDatain the allocator specified by the application. -
pMemoryis 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);
-
pUserDatais the value specified for VkAllocationCallbacks::pUserDatain the allocator specified by the application. -
sizeis the requested size of an allocation. -
allocationTypeis a VkInternalAllocationType value specifying the requested type of an allocation. -
allocationScopeis 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);
-
pUserDatais the value specified for VkAllocationCallbacks::pUserDatain the allocator specified by the application. -
sizeis the requested size of an allocation. -
allocationTypeis a VkInternalAllocationType value specifying the requested type of an allocation. -
allocationScopeis 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_COMMANDspecifies that the allocation is scoped to the duration of the Vulkan command. -
VK_SYSTEM_ALLOCATION_SCOPE_OBJECTspecifies that the allocation is scoped to the lifetime of the Vulkan object that is being created or used. -
VK_SYSTEM_ALLOCATION_SCOPE_CACHEspecifies that the allocation is scoped to the lifetime of aVkPipelineCacheorVkValidationCacheEXTobject. -
VK_SYSTEM_ALLOCATION_SCOPE_DEVICEspecifies that the allocation is scoped to the lifetime of the Vulkan device. -
VK_SYSTEM_ALLOCATION_SCOPE_INSTANCEspecifies 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_COMMANDallocation 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 parentVkDevicehas an allocator it will be used, else if the parentVkInstancehas an allocator it will be used. Else, -
If an allocation is associated with a
VkValidationCacheEXTorVkPipelineCacheobject, the allocator will use theVK_SYSTEM_ALLOCATION_SCOPE_CACHEallocation 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
VkDeviceorVkInstance, 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_EXECUTABLEspecifies 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
VkDeviceorVkInstancemay be allocated from any API command. -
Allocations scoped to a command may be allocated from any API command.
-
Allocations scoped to a
VkPipelineCachemay only be allocated from:-
vkCreatePipelineCache -
vkMergePipelineCachesfordstCache -
vkCreateGraphicsPipelinesforpipelineCache -
vkCreateComputePipelinesforpipelineCache
-
-
Allocations scoped to a
VkValidationCacheEXTmay only be allocated from:-
vkCreateValidationCacheEXT -
vkMergeValidationCachesEXTfordstCache -
vkCreateShaderModuleforvalidationCachein VkShaderModuleValidationCacheCreateInfoEXT
-
-
Allocations scoped to a
VkDescriptorPoolmay only be allocated from:-
any command that takes the pool as a direct argument
-
vkAllocateDescriptorSetsfor thedescriptorPoolmember of itspAllocateInfoparameter -
vkCreateDescriptorPool
-
-
Allocations scoped to a
VkCommandPoolmay only be allocated from:-
any command that takes the pool as a direct argument
-
vkCreateCommandPool -
vkAllocateCommandBuffersfor thecommandPoolmember of itspAllocateInfoparameter -
any
vkCmd*command whosecommandBufferwas 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
VkDeviceorVkInstancemay 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
VkPipelineCachemay be freed fromvkDestroyPipelineCache. -
Allocations scoped to a
VkValidationCacheEXTmay be freed fromvkDestroyValidationCacheEXT. -
Allocations scoped to a
VkDescriptorPoolmay be freed from-
any command that takes the pool as a direct argument
-
-
Allocations scoped to a
VkCommandPoolmay be freed from:-
any command that takes the pool as a direct argument
-
vkResetCommandBufferwhosecommandBufferwas 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);
-
physicalDeviceis the handle to the device to query. -
pMemoryPropertiesis 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;
-
memoryTypeCountis the number of valid elements in thememoryTypesarray. -
memoryTypesis an array ofVK_MAX_MEMORY_TYPESVkMemoryType structures describing the memory types that can be used to access memory allocated from the heaps specified bymemoryHeaps. -
memoryHeapCountis the number of valid elements in thememoryHeapsarray. -
memoryHeapsis an array ofVK_MAX_MEMORY_HEAPSVkMemoryHeap 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
propertyFlagsmember of X is a strict subset of the set of bit flags returned in thepropertyFlagsmember of Y; or -
the
propertyFlagsmembers 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
propertyFlagsmembers of Y includesVK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMDorVK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMDand 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);
-
physicalDeviceis the handle to the device to query. -
pMemoryPropertiesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryPropertiesis 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;
-
sizeis the total memory size in bytes in the heap. -
flagsis 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_BITspecifies 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_BITspecifies 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;
-
heapIndexdescribes which memory heap this memory type corresponds to, and must be less thanmemoryHeapCountfrom the VkPhysicalDeviceMemoryProperties structure. -
propertyFlagsis a bitmask of VkMemoryPropertyFlagBits of properties for this memory type.
Bits which may be set in VkMemoryType::propertyFlags,
indicating properties of a memory heap, 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_BITbit 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_BITset. -
VK_MEMORY_PROPERTY_HOST_VISIBLE_BITbit specifies that memory allocated with this type can be mapped for host access using vkMapMemory. -
VK_MEMORY_PROPERTY_HOST_COHERENT_BITbit 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_BITbit 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_BITbit specifies that the memory type only allows device access to the memory. Memory types must not have bothVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BITandVK_MEMORY_PROPERTY_HOST_VISIBLE_BITset. Additionally, the object’s backing memory may be provided by the implementation lazily as specified in Lazily Allocated Memory. -
VK_MEMORY_PROPERTY_PROTECTED_BITbit 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_BITset and any ofVK_MEMORY_PROPERTY_HOST_VISIBLE_BITset, orVK_MEMORY_PROPERTY_HOST_COHERENT_BITset, orVK_MEMORY_PROPERTY_HOST_CACHED_BITset. -
VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMDbit specifies that device accesses to allocations of this memory type are automatically made available and visible. -
VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMDbit 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_NVbit 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
heapBudgetis an array ofVK_MAX_MEMORY_HEAPSVkDeviceSizevalues 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. -
heapUsageis an array ofVK_MAX_MEMORY_HEAPSVkDeviceSizevalues 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);
-
deviceis the logical device that owns the memory. -
pAllocateInfois 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. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pMemoryis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
allocationSizeis the size of the allocation in bytes. -
memoryTypeIndexis an index identifying a memory type from thememoryTypesarray 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
handleTypevalue -
VkImportMemoryFdInfoKHR with a non-zero
handleTypevalue -
VkImportMemoryHostPointerInfoEXT with a non-zero
handleTypevalue -
VkImportAndroidHardwareBufferInfoANDROID with a non-
NULLbuffervalue -
VkImportMemoryZirconHandleInfoFUCHSIA with a non-zero
handleTypevalue
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis VK_NULL_HANDLE or a handle of an image which this memory will be bound to. -
bufferis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis VK_NULL_HANDLE or a handle of an image which this memory will be bound to. -
bufferis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
priorityis a floating-point value between0and1, 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);
-
deviceis the logical device that owns the memory. -
memoryis the VkDeviceMemory object to which the new priority will be applied. -
priorityis a floating-point value between0and1, 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pAttributesis a pointer to a WindowsSECURITY_ATTRIBUTESstructure specifying security attributes of the handle. -
dwAccessis aDWORDspecifying access rights of the handle. -
nameis 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 if it is 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the type ofhandleorname. -
handleisNULLor the external handle to import. -
nameisNULLor 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);
-
deviceis the logical device that created the device memory being exported. -
pGetWin32HandleInfois a pointer to a VkMemoryGetWin32HandleInfoKHR structure containing parameters of the export operation. -
pHandlewill 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryis the memory object from which the handle will be exported. -
handleTypeis 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);
-
deviceis the logical device that will be importinghandle. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handlehandle. -
handleis the handle which will be imported. -
pMemoryWin32HandlePropertiesis a pointer to a VkMemoryWin32HandlePropertiesKHR structure in which properties ofhandleare 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryTypeBitsis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pAttributesis a pointer to a WindowsSECURITY_ATTRIBUTESstructure specifying security attributes of the handle. -
dwAccessis aDWORDspecifying 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis0or a VkExternalMemoryHandleTypeFlagBitsNV value specifying the type of memory handle inhandle. -
handleis a WindowsHANDLEreferring 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_NVspecifies a handle to memory returned by vkGetMemoryWin32HandleNV. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NVspecifies a handle to memory returned by vkGetMemoryWin32HandleNV, or one duplicated from such a handle usingDuplicateHandle(). -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NVspecifies 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_NVspecifies 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);
-
deviceis the logical device that owns the memory. -
memoryis the VkDeviceMemory object. -
handleTypeis a bitmask of VkExternalMemoryHandleTypeFlagBitsNV containing a single bit specifying the type of handle requested. -
handleis a pointer to a WindowsHANDLEin 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the handle type offd. -
fdis 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);
-
deviceis the logical device that created the device memory being exported. -
pGetFdInfois a pointer to a VkMemoryGetFdInfoKHR structure containing parameters of the export operation. -
pFdwill 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryis the memory object from which the handle will be exported. -
handleTypeis 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);
-
deviceis the logical device that will be importingfd. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handlefd. -
fdis the handle which will be imported. -
pMemoryFdPropertiesis a pointer to a VkMemoryFdPropertiesKHR structure in which the properties of the handlefdare 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryTypeBitsis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the handle type. -
pHostPointeris 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);
-
deviceis the logical device that will be importingpHostPointer. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handlepHostPointer. -
pHostPointeris the host pointer to import from. -
pMemoryHostPointerPropertiesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryTypeBitsis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferis 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);
-
deviceis the logical device that created the device memory being exported. -
pInfois a pointer to a VkMemoryGetAndroidHardwareBufferInfoANDROID structure containing parameters of the export operation. -
pBufferwill 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryis 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);
-
deviceis the logical device that will be importingbuffer. -
bufferis the Android hardware buffer which will be imported. -
pPropertiesis a pointer to a VkAndroidHardwareBufferPropertiesANDROID structure in which the properties ofbufferare 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
allocationSizeis the size of the external memory -
memoryTypeBitsis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatis the Vulkan format corresponding to the Android hardware buffer’s format, orVK_FORMAT_UNDEFINEDif there is not an equivalent Vulkan format. -
externalFormatis an implementation-defined external format identifier for use with VkExternalFormatANDROID. It must not be zero. -
formatFeaturesdescribes the capabilities of this external format when used with an image bound to memory imported frombuffer. -
samplerYcbcrConversionComponentsis the component swizzle that should be used in VkSamplerYcbcrConversionCreateInfo. -
suggestedYcbcrModelis a suggested color model to use in the VkSamplerYcbcrConversionCreateInfo. -
suggestedYcbcrRangeis a suggested numerical value range to use in VkSamplerYcbcrConversionCreateInfo. -
suggestedXChromaOffsetis a suggested X chroma offset to use in VkSamplerYcbcrConversionCreateInfo. -
suggestedYChromaOffsetis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatis the Vulkan format corresponding to the Android hardware buffer’s format, orVK_FORMAT_UNDEFINEDif there is not an equivalent Vulkan format. -
externalFormatis an implementation-defined external format identifier for use with VkExternalFormatANDROID. It must not be zero. -
formatFeaturesdescribes the capabilities of this external format when used with an image bound to memory imported frombuffer. -
samplerYcbcrConversionComponentsis the component swizzle that should be used in VkSamplerYcbcrConversionCreateInfo. -
suggestedYcbcrModelis a suggested color model to use in the VkSamplerYcbcrConversionCreateInfo. -
suggestedYcbcrRangeis a suggested numerical value range to use in VkSamplerYcbcrConversionCreateInfo. -
suggestedXChromaOffsetis a suggested X chroma offset to use in VkSamplerYcbcrConversionCreateInfo. -
suggestedYChromaOffsetis 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);
-
deviceis the logical device that created the device memory being exported. -
pMemoryGetRemoteAddressInfois a pointer to a VkMemoryGetRemoteAddressInfoNV structure containing parameters of the export operation. -
pAddresswill return the address representing the payload of the device memory object.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryis the memory object from which the remote accessible address will be exported. -
handleTypeis the type of handle requested.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the type ofhandle. -
handleis 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);
-
deviceis the VkDevice. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the type ofzirconHandle -
zirconHandleis azx_handle_t(Zircon) handle to the external resource. -
pMemoryZirconHandlePropertiesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryTypeBitsa 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);
-
deviceis the VkDevice. -
pGetZirconHandleInfois a pointer to a VkMemoryGetZirconHandleInfoFUCHSIA structure. -
pZirconHandleis a pointer to azx_handle_twhich 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memorythe VkDeviceMemory being exported. -
handleTypeis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
exportObjectTypeis 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_EXTindicates a MetalMTLDevicemay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_COMMAND_QUEUE_BIT_EXTindicates a MetalMTLCommandQueuemay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXTindicates a MetalMTLBuffermay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXTindicates a MetalMTLTexturemay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_IOSURFACE_BIT_EXTindicates a MetalIOSurfacemay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXTindicates a MetalMTLSharedEventmay 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);
-
deviceis the device that created the Vulkan objects. -
pMetalObjectsInfois a pointer to a VkExportMetalObjectsInfoEXT structure whosepNextchain 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;
-
sTypeis the type of this structure. -
pNextisNULLor 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
mtlDeviceis the Metalid<MTLDevice>object underlying the VkPhysicalDevice associated with the VkDevice object identified in the call. The implementation will return theMTLDevicein this member, or it will returnNULLif noMTLDevicecould 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queueis a VkQueue. -
mtlCommandQueueis the Metalid<MTLCommandQueue>object underlying the VkQueue object inqueue. The implementation will return theMTLCommandQueuein this member, or it will returnNULLif noMTLCommandQueuecould 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryis a VkDeviceMemory. -
mtlBufferis the Metalid<MTLBuffer>object underlying the VkDeviceMemory object inmemory. The implementation will return theMTLBufferin this member, or it will returnNULLif noMTLBuffercould 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
mtlBufferis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageisVK_NULL_HANDLEor a VkImage. -
imageViewisVK_NULL_HANDLEor a VkImageView. -
bufferViewisVK_NULL_HANDLEor a VkBufferView. -
planeindicates the plane of a multi-planar VkImage or VkImageView. -
mtlTextureis the Metalid<MTLTexture>object underlying the VkImage, VkImageView, or VkBufferView object inimage,imageView, orbufferView, respectively, at the plane indicated inaspectMask. The implementation will return theMTLTexturein this member, or it will returnNULLif noMTLTexturecould 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;
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis a VkImage. -
ioSurfaceis the MetalIOSurfaceRefobject underlying the VkImage object inimage. The implementation will return theIOSurfaceRefin this member, or it will returnNULLif noIOSurfaceRefcould 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
ioSurfaceisVK_NULL_HANDLEor the MetalIOSurfaceRefobject 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:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreisVK_NULL_HANDLEor a VkSemaphore. -
eventisVK_NULL_HANDLEor a VkEvent. -
mtlSharedEventis the Metalid<MTLSharedEvent>object underlying the VkSemaphore or VkEvent object insemaphoreorevent, respectively. The implementation will return theMTLSharedEventin this member, or it will returnNULLif noMTLSharedEventcould be found underlying the VkSemaphore or VkEvent object.
To import a Metal 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:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
mtlSharedEventis 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 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkMemoryAllocateFlagBits controlling the allocation. -
deviceMaskis 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_BITis 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_BITspecifies that memory will be allocated for the devices in VkMemoryAllocateFlagsInfo::deviceMask. -
VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BITspecifies that the memory can be attached to a buffer object created with theVK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BITbit set inusage, and that the memory handle can be used to retrieve an opaque address via vkGetDeviceMemoryOpaqueCaptureAddress. -
VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BITspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
opaqueCaptureAddressis 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);
-
deviceis the logical device that owns the memory. -
memoryis the VkDeviceMemory object to be freed. -
pAllocatorcontrols 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);
-
deviceis the logical device that owns the memory. -
memoryis the VkDeviceMemory object to be mapped. -
offsetis a zero-based byte offset from the beginning of the memory object. -
sizeis the size of the memory range to map, orVK_WHOLE_SIZEto map fromoffsetto the end of the allocation. -
flagsis reserved for future use. -
ppDatais a pointer to avoid *variable in which is returned a host-accessible pointer to the beginning of the mapped range. This pointer minusoffsetmust 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
|
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);
-
deviceis the logical device that owns the memory ranges. -
memoryRangeCountis the length of thepMemoryRangesarray. -
pMemoryRangesis 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);
-
deviceis the logical device that owns the memory ranges. -
memoryRangeCountis the length of thepMemoryRangesarray. -
pMemoryRangesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryis the memory object to which this range belongs. -
offsetis the zero-based byte offset from the beginning of the memory object. -
sizeis either the size of range, orVK_WHOLE_SIZEto affect the range fromoffsetto 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);
-
deviceis the logical device that owns the memory. -
memoryis 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);
-
deviceis the logical device that owns the memory. -
memoryis the memory object being queried. -
pCommittedMemoryInBytesis a pointer to aVkDeviceSizevalue 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
-
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 |
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
widthandheightmembers ofAHardwareBuffer_Descmust be the same as thewidthandheightmembers of VkImageCreateInfo::extent, respectively. -
The
layersmember ofAHardwareBuffer_Descmust be the same as thearrayLayersmember of VkImageCreateInfo. -
The
formatmember ofAHardwareBuffer_Descmust be equivalent to VkImageCreateInfo::formatas defined by AHardwareBuffer Format Equivalence. -
The
usagemember ofAHardwareBuffer_Descmust include bits corresponding to bits included in VkImageCreateInfo::usageand VkImageCreateInfo::flagswhere 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_UNORMandAHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM: they both behave asVK_FORMAT_R8G8B8A8_UNORM. After an external entity writes to aAHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORMAndroid 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_ONEin image view component mappings andVK_BLEND_FACTOR_ONEin 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_COMPLETEflag 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_UNORMthat has aAHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFERusage 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);
-
deviceis the logical device that owns the memory. -
heapIndexis the index of the memory heap from which the memory is allocated. -
localDeviceIndexis the device index of the physical device that performs the memory access. -
remoteDeviceIndexis the device index of the physical device that the memory is allocated for. -
pPeerMemoryFeaturesis 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_BITspecifies that the memory can be accessed as the source of anyvkCmdCopy*command. -
VK_PEER_MEMORY_FEATURE_COPY_DST_BITspecifies that the memory can be accessed as the destination of anyvkCmdCopy*command. -
VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BITspecifies that the memory can be read as any memory access type. -
VK_PEER_MEMORY_FEATURE_GENERIC_DST_BITspecifies 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);
-
deviceis the logical device that the memory object was allocated on. -
pInfois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryspecifies 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.
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 via 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);
-
deviceis the logical device that creates the buffer object. -
pCreateInfois a pointer to a VkBufferCreateInfo structure containing parameters affecting creation of the buffer. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pBufferis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkBufferCreateFlagBits specifying additional parameters of the buffer. -
sizeis the size in bytes of the buffer to be created. -
usageis a bitmask of VkBufferUsageFlagBits specifying allowed usages of the buffer. -
sharingModeis a VkSharingMode value specifying the sharing mode of the buffer when it will be accessed by multiple queue families. -
queueFamilyIndexCountis the number of entries in thepQueueFamilyIndicesarray. -
pQueueFamilyIndicesis a pointer to an array of queue families that will access this buffer. It is ignored ifsharingModeis 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00002000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00004000,
#endif
// 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,
// 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_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_BITspecifies 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_BITspecifies that the buffer can be used as the destination of a transfer command. -
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BITspecifies that the buffer can be used to create aVkBufferViewsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER. -
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BITspecifies that the buffer can be used to create aVkBufferViewsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER. -
VK_BUFFER_USAGE_UNIFORM_BUFFER_BITspecifies that the buffer can be used in aVkDescriptorBufferInfosuitable for occupying aVkDescriptorSetslot either of typeVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC. -
VK_BUFFER_USAGE_STORAGE_BUFFER_BITspecifies that the buffer can be used in aVkDescriptorBufferInfosuitable for occupying aVkDescriptorSetslot either of typeVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC. -
VK_BUFFER_USAGE_INDEX_BUFFER_BITspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdBindIndexBuffer. -
VK_BUFFER_USAGE_VERTEX_BUFFER_BITspecifies that the buffer is suitable for passing as an element of thepBuffersarray to vkCmdBindVertexBuffers. -
VK_BUFFER_USAGE_INDIRECT_BUFFER_BITspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV, or vkCmdDispatchIndirect. It is also suitable for passing as thebuffermember ofVkIndirectCommandsStreamNV, orsequencesCountBufferorsequencesIndexBufferorpreprocessedBuffermember ofVkGeneratedCommandsInfoNV -
VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXTspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdBeginConditionalRenderingEXT. -
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXTspecifies that the buffer is suitable for using for binding as a transform feedback buffer with vkCmdBindTransformFeedbackBuffersEXT. -
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXTspecifies that the buffer is suitable for using as a counter buffer with vkCmdBeginTransformFeedbackEXT and vkCmdEndTransformFeedbackEXT. -
VK_BUFFER_USAGE_RAY_TRACING_BIT_NVspecifies that the buffer is suitable for use in vkCmdTraceRaysNV. -
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHRspecifies that the buffer is suitable for use as a Shader Binding Table. -
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHRspecifies that the buffer is suitable for use as a read-only input to an acceleration structure build. -
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHRspecifies that the buffer is suitable for storage space for a VkAccelerationStructureKHR. -
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BITspecifies 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_KHRspecifies that the buffer can be used as the source bitstream buffer in a video decode operation. -
VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHRspecifies that the buffer can be used as the destination status buffer in a video decode operation. -
VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHRspecifies that the buffer can be used as the destination bitstream buffer in a video encode operation. -
VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHRspecifies that the buffer can be used as the destination status buffer in a video encode operation.
// 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_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_BITspecifies that the buffer will be backed using sparse memory binding. -
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BITspecifies 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_BITflag. -
VK_BUFFER_CREATE_SPARSE_ALIASED_BITspecifies 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_BITflag. -
VK_BUFFER_CREATE_PROTECTED_BITspecifies that the buffer is a protected buffer. -
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BITspecifies 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.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dedicatedAllocationspecifies 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 |
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
opaqueCaptureAddressis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceAddressis 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;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
collectionis the VkBufferCollectionFUCHSIA handle -
indexis 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);
-
deviceis the logical device that destroys the buffer. -
bufferis the buffer to destroy. -
pAllocatorcontrols 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);
-
deviceis the logical device that creates the buffer view. -
pCreateInfois a pointer to a VkBufferViewCreateInfo structure containing parameters to be used to create the buffer view. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pViewis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
bufferis a VkBuffer on which the view will be created. -
formatis a VkFormat describing the format of the data elements in the buffer. -
offsetis 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. -
rangeis a size in bytes of the buffer view. Ifrangeis equal toVK_WHOLE_SIZE, the range fromoffsetto the end of the buffer is used. IfVK_WHOLE_SIZEis used and the remaining size of the buffer is not a multiple of the texel block size offormat, the nearest smaller multiple is used.
// 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);
-
deviceis the logical device that destroys the buffer view. -
bufferViewis the buffer view to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
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);
-
deviceis the logical device that creates the image. -
pCreateInfois a pointer to a VkImageCreateInfo structure containing parameters to be used to create the image. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pImageis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkImageCreateFlagBits describing additional parameters of the image. -
imageTypeis 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. -
formatis a VkFormat describing the format and type of the texel blocks that will be contained in the image. -
extentis a VkExtent3D describing the number of data elements in each dimension of the base level. -
mipLevelsdescribes the number of levels of detail available for minified sampling of the image. -
arrayLayersis the number of layers in the image. -
samplesis a VkSampleCountFlagBits value specifying the number of samples per texel. -
tilingis a VkImageTiling value specifying the tiling arrangement of the texel blocks in memory. -
usageis a bitmask of VkImageUsageFlagBits describing the intended usage of the image. -
sharingModeis a VkSharingMode value specifying the sharing mode of the image when it will be accessed by multiple queue families. -
queueFamilyIndexCountis the number of entries in thepQueueFamilyIndicesarray. -
pQueueFamilyIndicesis a pointer to an array of queue families that will access this image. It is ignored ifsharingModeis notVK_SHARING_MODE_CONCURRENT. -
initialLayoutis 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:
-
imageTypeisVK_IMAGE_TYPE_2D -
formatis not a depth/stencil format -
mipLevelsis 1 -
arrayLayersis 1 -
samplesisVK_SAMPLE_COUNT_1_BIT -
usageonly includesVK_IMAGE_USAGE_TRANSFER_SRC_BITand/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:
-
imageTypeisVK_IMAGE_TYPE_2D -
mipLevelsis 1 -
arrayLayersis 1 -
samplesisVK_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;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
collectionis the VkBufferCollectionFUCHSIA handle -
indexis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stencilUsageis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dedicatedAllocationspecifies 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 |
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalFormatis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
viewFormatCountis the number of entries in thepViewFormatsarray. -
pViewFormatsis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifierCountis the length of thepDrmFormatModifiersarray. -
pDrmFormatModifiersis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifieris the Linux DRM format modifier with which the image will be created. -
drmFormatModifierPlaneCountis the number of memory planes in the image (as reported by VkDrmFormatModifierPropertiesEXT) as well as the length of thepPlaneLayoutsarray. -
pPlaneLayoutsis a pointer to an array of VkSubresourceLayout structures describing the image’s memory planes.
The ith member of pPlaneLayouts describes the layout of the
image’s ith memory plane (that is,
VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT).
In each element of pPlaneLayouts, the implementation must ignore
size.
The implementation calculates the size of each plane, which the application
can query with vkGetImageSubresourceLayout.
When creating an image with
VkImageDrmFormatModifierExplicitCreateInfoEXT, it is the application’s
responsibility to satisfy all valid usage requirements.
However, the implementation must validate that the provided
pPlaneLayouts, when combined with the provided drmFormatModifier
and other creation parameters in VkImageCreateInfo and its pNext
chain, produce a valid image.
(This validation is necessarily implementation-dependent and outside the
scope of Vulkan, and therefore not described by valid usage requirements).
If this validation fails, then vkCreateImage returns
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkImageCompressionFlagBitsEXT describing compression controls for the image. -
compressionControlPlaneCountis the number of entries in thepFixedRateFlagsarray. -
pFixedRateFlagsisNULLor a pointer to an array of VkImageCompressionFixedRateFlagsEXT bitfields describing allowed fixed-rate compression rates of each image plane. It is ignored ifflagsdoes 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_EXTspecifies that the default image compression setting is used. Implementations must not apply fixed-rate compression. -
VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXTspecifies 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_EXTspecifies that fixed-rate compression may be used and that the allowed compression rates are specified by VkImageCompressionControlEXT::pFixedRateFlags. -
VK_IMAGE_COMPRESSION_DISABLED_EXTspecifies that all lossless and fixed-rate compression should be disabled.
If VkImageCompressionControlEXT::flags is
VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then the ith
member of the pFixedRateFlags array specifies the allowed compression
rates for the image’s ith plane.
|
Note
If |
// 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_EXTspecifies that fixed-rate compression must not be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_1BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [1,2) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [2,3) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_3BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [3,4) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [4,5) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [5,6) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_6BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [6,7) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_7BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [7,8) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_8BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [8,9) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_9BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [9,10) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_10BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [10,11) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_11BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [11,12) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_12BPC_BIT_EXTspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageCompressionFlagsreturns a value describing the compression controls that apply to the image. The value will be eitherVK_IMAGE_COMPRESSION_DEFAULT_EXTto indicate no fixed-rate compression,VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXTto indicate fixed-rate compression, orVK_IMAGE_COMPRESSION_DISABLED_EXTto indicate no compression. -
imageCompressionFixedRateFlagsreturns 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00000400,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00000800,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR = 0x00001000,
#endif
// 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,
#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_HUAWEI_invocation_mask
VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI = 0x00040000,
// 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_BITspecifies that the image can be used as the source of a transfer command. -
VK_IMAGE_USAGE_TRANSFER_DST_BITspecifies that the image can be used as the destination of a transfer command. -
VK_IMAGE_USAGE_SAMPLED_BITspecifies that the image can be used to create aVkImageViewsuitable for occupying aVkDescriptorSetslot either of typeVK_DESCRIPTOR_TYPE_SAMPLED_IMAGEorVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and be sampled by a shader. -
VK_IMAGE_USAGE_STORAGE_BITspecifies that the image can be used to create aVkImageViewsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_STORAGE_IMAGE. -
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BITspecifies that the image can be used to create aVkImageViewsuitable for use as a color or resolve attachment in aVkFramebuffer. -
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BITspecifies that the image can be used to create aVkImageViewsuitable for use as a depth/stencil or depth/stencil resolve attachment in aVkFramebuffer. -
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BITspecifies that implementations may support using memory allocations with theVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BITto back an image with this usage. This bit can be set for any image that can be used to create aVkImageViewsuitable for use as a color, resolve, depth/stencil, or input attachment. -
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BITspecifies that the image can be used to create aVkImageViewsuitable for occupyingVkDescriptorSetslot 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_EXTspecifies that the image can be used to create aVkImageViewsuitable for use as a fragment density map image. -
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies that the image can be used to create aVkImageViewsuitable for use as a fragment shading rate attachment or shading rate image -
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHRspecifies that video decode operations can use the image as an output picture for video decode operations. -
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHRis reserved for future use. -
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHRspecifies that video decode operations can use the image as a DPB Video Picture Resource, representing a reference picture. If an implementation requires separate allocations for DPB and decode output, indicating this by returningVK_ERROR_FORMAT_NOT_SUPPORTEDto any vkGetPhysicalDeviceVideoFormatPropertiesKHR call with bothVK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHRandVK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHRusage bits, thenVK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHRmust not be combined with any other VK_IMAGE_USAGE_* flags. Otherwise,VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHRmust be combined withVK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, if the DPB image is required to coincide with the decoded output picture. In the case where DPB coincides with the decoded output picture, image resources can be used as reference pictures only after acting as targets for video decode operations, where its image view must be set to both VkVideoDecodeInfoKHR::pSetupReferenceSlot->pPictureResource->imageViewBindingand VkVideoDecodeInfoKHR::dstPictureResource.imageViewBinding. -
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHRspecifies that the image can be used as an input picture for video encode operations. -
VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHRis reserved for future use. -
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHRspecifies that video encode operations can use the image as an output to hold a reconstructed picture that can subsequently act as an input reference picture.
// 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
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_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_BITspecifies that the image will be backed using sparse memory binding. -
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BITspecifies 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_BITflag. -
VK_IMAGE_CREATE_SPARSE_ALIASED_BITspecifies 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_BITflag. -
VK_IMAGE_CREATE_MUTABLE_FORMAT_BITspecifies that the image can be used to create aVkImageViewwith a different format from the image. For multi-planar formats,VK_IMAGE_CREATE_MUTABLE_FORMAT_BITspecifies that aVkImageViewcan be created of a plane of the image. -
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BITspecifies that the image can be used to create aVkImageViewof typeVK_IMAGE_VIEW_TYPE_CUBEorVK_IMAGE_VIEW_TYPE_CUBE_ARRAY. -
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BITspecifies that the image can be used to create aVkImageViewof typeVK_IMAGE_VIEW_TYPE_2DorVK_IMAGE_VIEW_TYPE_2D_ARRAY. -
VK_IMAGE_CREATE_PROTECTED_BITspecifies that the image is a protected image. -
VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BITspecifies that the image can be used with a non-zero value of thesplitInstanceBindRegionCountmember 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_BITspecifies that the image having a compressed format can be used to create aVkImageViewwith an uncompressed format where each texel in the image view corresponds to a compressed texel block of the image. -
VK_IMAGE_CREATE_EXTENDED_USAGE_BITspecifies 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 aVkImageViewcreated from the image can have. -
VK_IMAGE_CREATE_DISJOINT_BITspecifies 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_BITspecifies 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 thepNextchain includes a VkExternalMemoryImageCreateInfo or VkExternalMemoryImageCreateInfoNV structure whosehandleTypesmember is not0, it is as ifVK_IMAGE_CREATE_ALIAS_BITis set. -
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXTspecifies 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_NVspecifies that the image is a corner-sampled image. -
VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXTspecifies 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
flagscontainingVK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXTor 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_BITifVkPhysicalDeviceFragmentDensityMap2PropertiesEXT::subsampledCoarseReconstructionEarlyAccessisVK_TRUEand the sampler was created withflagscontainingVK_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::subsampledLoadsisVK_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_QCOMspecifies that an image can be used in a render pass with non-zero fragment density map offsets. In a renderpass with non-zero offsets, fragment density map attachments, input attachments, color attachments, depth/stencil attachment, resolve attachments, and preserve attachments must be created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM. -
VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXTspecifies 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_1Dspecifies a one-dimensional image. -
VK_IMAGE_TYPE_2Dspecifies a two-dimensional image. -
VK_IMAGE_TYPE_3Dspecifies 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_OPTIMALspecifies optimal tiling (texels are laid out in an implementation-dependent arrangement, for more efficient memory access). -
VK_IMAGE_TILING_LINEARspecifies 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_EXTindicates 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);
-
deviceis the logical device that owns the image. -
imageis the image whose layout is being queried. -
pSubresourceis a pointer to a VkImageSubresource structure selecting a specific image subresource from the image. -
pLayoutis 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
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;
-
aspectMaskis a VkImageAspectFlags value selecting the image aspect. -
mipLevelselects the mipmap level. -
arrayLayerselects 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;
-
offsetis the byte offset from the start of the image or the plane where the image subresource begins. -
sizeis the size in bytes of the image subresource.sizeincludes any extra memory that is required based onrowPitch. -
rowPitchdescribes the number of bytes between each row of texels in an image. -
arrayPitchdescribes the number of bytes between each array layer of an image. -
depthPitchdescribes 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_image_compression_control
void vkGetImageSubresourceLayout2EXT(
VkDevice device,
VkImage image,
const VkImageSubresource2EXT* pSubresource,
VkSubresourceLayout2EXT* pLayout);
-
deviceis the logical device that owns the image. -
imageis the image whose layout is being queried. -
pSubresourceis a pointer to a VkImageSubresource2EXT structure selecting a specific image for the image subresource. -
pLayoutis a pointer to a VkSubresourceLayout2EXT structure in which the layout is returned.
vkGetImageSubresourceLayout2EXT behaves similarly to
vkGetImageSubresourceLayout, with the ability to specify extended
inputs via chained input structures, and to return extended information via
chained output structures.
The VkImageSubresource2EXT structure is defined as:
// Provided by VK_EXT_image_compression_control
typedef struct VkImageSubresource2EXT {
VkStructureType sType;
void* pNext;
VkImageSubresource imageSubresource;
} VkImageSubresource2EXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageSubresourceis a VkImageSubresource structure.
Information about the layout of the image subresource is returned in a
VkSubresourceLayout2EXT structure:
// Provided by VK_EXT_image_compression_control
typedef struct VkSubresourceLayout2EXT {
VkStructureType sType;
void* pNext;
VkSubresourceLayout subresourceLayout;
} VkSubresourceLayout2EXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
subresourceLayoutis 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);
-
deviceis the logical device that owns the image. -
imageis the queried image. -
pPropertiesis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifierreturns 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);
-
deviceis the logical device that destroys the image. -
imageis the image to destroy. -
pAllocatorcontrols 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::linearTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties on the sameformatas 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::optimalTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties on the sameformatas 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::
formatFeaturesfound 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::
drmFormatModifierfound by calling vkGetImageDrmFormatModifierPropertiesEXT. -
Let VkDrmFormatModifierPropertiesListEXT::
pDrmFormatModifierPropertiesbe the array found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkImageCreateInfo::format. -
Let
VkDrmFormatModifierPropertiesEXT propbe the array element whosedrmFormatModifiermember 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 Miplevel Sizing.
-
The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. See Image Miplevel 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 Miplevel Sizing
A complete mipmap chain is the full set of miplevels, from the largest miplevel provided, down to the minimum miplevel size.
Conventional Images
For conventional images, the dimensions of each successive miplevel, n+1, are:
-
widthn+1 = max(⌊widthn/2⌋, 1) -
heightn+1 = max(⌊heightn/2⌋, 1) -
depthn+1 = max(⌊depthn/2⌋, 1)
where widthn, heightn, and depthn
are the dimensions of the next larger miplevel, n.
The minimum miplevel size is:
-
1 for one-dimensional images,
-
1x1 for two-dimensional images, and
-
1x1x1 for three-dimensional images.
The number of levels in a complete mipmap chain is:
-
⌊log2(max(
width0,height0,depth0))⌋ + 1
where width0, height0, and depth0
are the dimensions of the largest (most detailed) miplevel, 0.
Corner-Sampled Images
For corner-sampled images, the dimensions of each successive miplevel, n+1, are:
-
widthn+1 = max(⌈widthn/2⌉, 2) -
heightn+1 = max(⌈heightn/2⌉, 2) -
depthn+1 = max(⌈depthn/2⌉, 2)
where widthn, heightn, and depthn
are the dimensions of the next larger miplevel, n.
The minimum miplevel size is:
-
2x2 for two-dimensional images, and
-
2x2x2 for three-dimensional images.
The number of levels in a complete mipmap chain is:
-
⌈log2(max(
width0,height0,depth0))⌉
where width0, height0, and depth0
are the dimensions of the largest (most detailed) miplevel, 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR = 1000024000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR = 1000024001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR = 1000024002,
#endif
// 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_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_UNDEFINEDspecifies that the layout is unknown. Image memory cannot be transitioned into this layout. This layout can be used as theinitialLayoutmember 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_PREINITIALIZEDspecifies 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 theinitialLayoutmember 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_PREINITIALIZEDis only useful with linear images because there is not a standard layout defined forVK_IMAGE_TILING_OPTIMALimages. -
VK_IMAGE_LAYOUT_GENERALsupports all types of device access. -
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMALspecifies a layout that must only be used with attachment accesses in the graphics pipeline. -
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMALspecifies 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_OPTIMALmust 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_BITusage bit enabled. -
VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMALspecifies 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_OPTIMALandVK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. -
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMALspecifies 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_OPTIMALandVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMALspecifies 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_OPTIMALandVK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMALspecifies 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_OPTIMALandVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMALspecifies 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_OPTIMALspecifies 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_OPTIMALspecifies 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_OPTIMALspecifies 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_OPTIMALspecifies 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_BITorVK_IMAGE_USAGE_INPUT_ATTACHMENT_BITusage bits enabled. -
VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMALmust 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_BITusage bit enabled. -
VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMALmust 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_BITusage bit enabled. -
VK_IMAGE_LAYOUT_PRESENT_SRC_KHRmust only be used for presenting a presentable image for display. A swapchain’s image must be transitioned to this layout before calling vkQueuePresentKHR, and must be transitioned away from this layout after calling vkAcquireNextImageKHR. -
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHRis valid only for shared presentable images, and must be used for any usage the image supports. -
VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHRmust 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_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXTmust 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_EXTusage bit enabled. -
VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHRmust only be used as a decode output image of a video decode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHRis reserved for future use. -
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHRmust only be used as a decode source or destination image of a video decode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHRis reserved for future use. -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHRmust only be used as a encode source image of a video encode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHRmust only be used as a encode source or destination image of a video encode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHRusage bit 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_OPTIMALandVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMALare 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_OPTIMALandVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMALare 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);
-
deviceis the logical device that creates the image view. -
pCreateInfois a pointer to aVkImageViewCreateInfostructure containing parameters to be used to create the image view. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pViewis 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkImageViewCreateFlagBits describing additional parameters of the image view. -
imageis a VkImage on which the view will be created. -
viewTypeis a VkImageViewType value specifying the type of the image view. -
formatis a VkFormat describing the format and type used to interpret texel blocks in the image. -
componentsis a VkComponentMapping structure specifying a remapping of color components (or of depth or stencil components after they have been converted into color components). -
subresourceRangeis 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 overriden 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
aspectMaskincludes onlyVK_IMAGE_ASPECT_STENCIL_BIT, the implicitusageis equal to VkImageStencilUsageCreateInfo::stencilUsage. -
If
aspectMaskincludes onlyVK_IMAGE_ASPECT_DEPTH_BIT, the implicitusageis equal to VkImageCreateInfo::usage. -
If both aspects are included in
aspectMask, the implicitusageis equal to the intersection of VkImageCreateInfo::usageand VkImageStencilUsageCreateInfo::stencilUsage.
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.
|
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, as defined for
copying data between images.
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 and
subresourceRange.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT,
and it was created with usage value containing flags other than
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,
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.
If the image has a
multi-planar format and
the image has been created with a usage value containing any of
the VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR,
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, and
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR flags, then all of the
video decode operations would ignore the
VkSamplerYcbcrConversionInfo structure and/or
sampler Y′CBCR conversion object, associated
with the image view.
If the image has a
multi-planar format and
the image has been created with a usage value containing any of
the VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR,
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, and
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR flags, then all of the
video encode operations would ignore the
VkSamplerYcbcrConversionInfo structure and/or
sampler Y′CBCR conversion object, associated
with the image view.
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_fragment_density_map2
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT = 0x00000002,
} VkImageViewCreateFlagBits;
-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXTspecifies 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_EXTspecifies 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
// 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
usageis 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 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;
-
aspectMaskis a bitmask of VkImageAspectFlagBits specifying which aspect(s) of the image are included in the view. -
baseMipLevelis the first mipmap level accessible to the view. -
levelCountis the number of mipmap levels (starting frombaseMipLevel) accessible to the view. -
baseArrayLayeris the first array layer accessible to the view. -
layerCountis 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_NONEspecifies no image aspect, or the image aspect is not applicable. -
VK_IMAGE_ASPECT_COLOR_BITspecifies the color aspect. -
VK_IMAGE_ASPECT_DEPTH_BITspecifies the depth aspect. -
VK_IMAGE_ASPECT_STENCIL_BITspecifies the stencil aspect. -
VK_IMAGE_ASPECT_METADATA_BITspecifies the metadata aspect, used for sparse resource operations. -
VK_IMAGE_ASPECT_PLANE_0_BITspecifies plane 0 of a multi-planar image format. -
VK_IMAGE_ASPECT_PLANE_1_BITspecifies plane 1 of a multi-planar image format. -
VK_IMAGE_ASPECT_PLANE_2_BITspecifies plane 2 of a multi-planar image format. -
VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXTspecifies memory plane 0. -
VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXTspecifies memory plane 1. -
VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXTspecifies memory plane 2. -
VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXTspecifies 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;
-
ris a VkComponentSwizzle specifying the component value placed in the R component of the output vector. -
gis a VkComponentSwizzle specifying the component value placed in the G component of the output vector. -
bis a VkComponentSwizzle specifying the component value placed in the B component of the output vector. -
ais 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_IDENTITYspecifies that the component is set to the identity swizzle. -
VK_COMPONENT_SWIZZLE_ZEROspecifies that the component is set to zero. -
VK_COMPONENT_SWIZZLE_ONEspecifies 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_Rspecifies that the component is set to the value of the R component of the image. -
VK_COMPONENT_SWIZZLE_Gspecifies that the component is set to the value of the G component of the image. -
VK_COMPONENT_SWIZZLE_Bspecifies that the component is set to the value of the B component of the image. -
VK_COMPONENT_SWIZZLE_Aspecifies 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
decodeModeis the intermediate format used to decode ASTC compressed formats.
If format uses sRGB encoding then the decodeMode has no effect.
To destroy an image view, call:
// Provided by VK_VERSION_1_0
void vkDestroyImageView(
VkDevice device,
VkImageView imageView,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the image view. -
imageViewis the image view to destroy. -
pAllocatorcontrols 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);
-
deviceis the logical device that owns the image view. -
pInfodescribes 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis the image view to query. -
descriptorTypeis the type of descriptor for which to query a handle. -
sampleris 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);
-
deviceis the logical device that owns the image view. -
imageViewis a handle to the image view. -
pPropertiescontains 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceAddressis the device address of the image view. -
sizeis 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_flags2extension is enabled, and VkImageViewCreateInfo::imagewas created withVK_IMAGE_TILING_LINEAR, then the image view’s set of format features is the value of VkFormatProperties3::linearTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkImageViewCreateInfo::format. -
If Vulkan 1.3 is not supported and the
VK_KHR_format_feature_flags2extension is not enabled, and VkImageViewCreateInfo::imagewas created withVK_IMAGE_TILING_LINEAR, then the image view’s set of format features is the union of the value of VkFormatProperties::linearTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties on the sameformatas VkImageViewCreateInfo::format, with:-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BITif 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_BITif the format is one of the extended storage formats andshaderStorageImageReadWithoutFormatis enabled on the device. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITif the format is one of the extended storage formats andshaderStorageImageWriteWithoutFormatis enabled on the device.
-
-
If Vulkan 1.3 is supported or the
VK_KHR_format_feature_flags2extension is enabled, and VkImageViewCreateInfo::imagewas 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::optimalTilingFeaturesor VkFormatProperties3::optimalTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties or vkGetPhysicalDeviceImageFormatProperties2 on the sameformatas VkImageViewCreateInfo::format. -
If Vulkan 1.3 is not supported and the
VK_KHR_format_feature_flags2extension is not enabled, and VkImageViewCreateInfo::imagewas 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::optimalTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties on the sameformatas VkImageViewCreateInfo::format, with:-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BITif 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_BITif the format is one of the extended storage formats andshaderStorageImageReadWithoutFormatis enabled on the device. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITif the format is one of the extended storage formats andshaderStorageImageWriteWithoutFormatis enabled on the device.
-
-
If VkImageViewCreateInfo::
imagewas created with an Android hardware buffer external format, then the image views’s set of format features is the value of VkAndroidHardwareBufferFormatPropertiesANDROID::formatFeaturesfound by calling vkGetAndroidHardwareBufferPropertiesANDROID on the Android hardware buffer that was imported to the VkDeviceMemory to which the VkImageViewCreateInfo::imageis bound. -
If VkImageViewCreateInfo::
imagewas created with a chained VkBufferCollectionImageCreateInfoFUCHSIA, then the image view’s set of format features is the value of VkBufferCollectionPropertiesFUCHSIA::formatFeaturesfound by calling vkGetBufferCollectionPropertiesFUCHSIA on the buffer collection passed as VkBufferCollectionImageCreateInfoFUCHSIA::collectionwhen the image was created. -
If VkImageViewCreateInfo::
imagewas created withVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then:-
The image’s DRM format modifier is the value of VkImageDrmFormatModifierPropertiesEXT::
drmFormatModifierfound by calling vkGetImageDrmFormatModifierPropertiesEXT. -
Let VkDrmFormatModifierPropertiesListEXT::
pDrmFormatModifierPropertiesbe the array found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkImageViewCreateInfo::format. -
Let
VkDrmFormatModifierPropertiesEXT propbe the array element whosedrmFormatModifiermember is the value of the image’s DRM format modifier. -
Then the image view’s set of format features is
prop::drmFormatModifierTilingFeatures.
-
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 and Integer
Texel Coordinate Operations.
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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minLodis the value to clamp the minimum LOD accessible by this VkImageView.
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);
-
deviceis the logical device that creates the buffer object. -
pCreateInfois a pointer to a VkAccelerationStructureCreateInfoNV structure containing parameters affecting creation of the acceleration structure. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pAccelerationStructureis 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.
Populating the data in the object after allocating and binding memory is
done with 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
compactedSizeis the size from the result of vkCmdWriteAccelerationStructuresPropertiesNV if this acceleration structure is going to be the target of a compacting copy. -
infois 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;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis a VkAccelerationStructureTypeNV value specifying the type of acceleration structure that will be created. -
flagsis a bitmask of VkBuildAccelerationStructureFlagBitsNV specifying additional parameters of the acceleration structure. -
instanceCountspecifies the number of instances that will be in the new acceleration structure. -
geometryCountspecifies the number of geometries that will be in the new acceleration structure. -
pGeometriesis a pointer to an array ofgeometryCountVkGeometryNV 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.
To create an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkCreateAccelerationStructureKHR(
VkDevice device,
const VkAccelerationStructureCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkAccelerationStructureKHR* pAccelerationStructure);
-
deviceis the logical device that creates the acceleration structure object. -
pCreateInfois a pointer to a VkAccelerationStructureCreateInfoKHR structure containing parameters affecting creation of the acceleration structure. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pAccelerationStructureis a pointer to aVkAccelerationStructureKHRhandle in which the resulting acceleration structure object is returned.
Similar to other objects in Vulkan, the acceleration structure creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into an acceleration structure is determined by the parameters of VkAccelerationStructureCreateInfoKHR.
Populating the data in the object after allocating and binding memory is done with commands such as vkCmdBuildAccelerationStructuresKHR, vkBuildAccelerationStructuresKHR, vkCmdCopyAccelerationStructureKHR, and vkCopyAccelerationStructureKHR.
The input buffers passed to acceleration structure build commands will be referenced by the implementation for the duration of the command. After the command completes, the acceleration structure may hold a reference to any acceleration structure specified by an active instance contained therein. Apart from this referencing, acceleration structures must be fully self-contained. The application may re-use or free any memory which was used by the command as an input or as scratch without affecting the results of ray traversal.
The VkAccelerationStructureCreateInfoKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureCreateFlagsKHR createFlags;
VkBuffer buffer;
VkDeviceSize offset;
VkDeviceSize size;
VkAccelerationStructureTypeKHR type;
VkDeviceAddress deviceAddress;
} VkAccelerationStructureCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
createFlagsis a bitmask of VkAccelerationStructureCreateFlagBitsKHR specifying additional creation parameters of the acceleration structure. -
bufferis the buffer on which the acceleration structure will be stored. -
offsetis an offset in bytes from the base address of the buffer at which the acceleration structure will be stored, and must be a multiple of256. -
sizeis the size required for the acceleration structure. -
typeis a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure that will be created. -
deviceAddressis the device address requested for the acceleration structure if theaccelerationStructureCaptureReplayfeature is being used.
If deviceAddress is zero, no specific address is requested.
If deviceAddress is not zero, deviceAddress must be an address
retrieved from an identically created acceleration structure on the same
implementation.
The acceleration structure must also be placed on an identically created
buffer and at the same offset.
Applications should avoid creating acceleration structures with
application-provided addresses and implementation-provided addresses in the
same process, to reduce the likelihood of
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR 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
|
Applications should create an acceleration structure with a specific
VkAccelerationStructureTypeKHR other than
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR.
If the acceleration structure will be the target of a build operation, the required size for an acceleration structure can be queried with vkGetAccelerationStructureBuildSizesKHR. If the acceleration structure is going to be the target of a compacting copy, vkCmdWriteAccelerationStructuresPropertiesKHR or vkWriteAccelerationStructuresPropertiesKHR can be used to obtain the compacted size required.
If the acceleration structure will be the target of a build operation with
VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV it must include
VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV in flags and
include VkAccelerationStructureMotionInfoNV as an extension structure
in pNext with the number of instances as metadata for the object.
The VkAccelerationStructureMotionInfoNV structure is defined as:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureMotionInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t maxInstances;
VkAccelerationStructureMotionInfoFlagsNV flags;
} VkAccelerationStructureMotionInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxInstancesis the maximum number of instances that may be used in the motion top-level acceleration structure. -
flagsis 0 and reserved for future use.
// Provided by VK_NV_ray_tracing_motion_blur
typedef VkFlags VkAccelerationStructureMotionInfoFlagsNV;
VkAccelerationStructureMotionInfoFlagsNV is a bitmask type for setting
a mask, but is currently reserved for future use.
To get the build sizes for an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
void vkGetAccelerationStructureBuildSizesKHR(
VkDevice device,
VkAccelerationStructureBuildTypeKHR buildType,
const VkAccelerationStructureBuildGeometryInfoKHR* pBuildInfo,
const uint32_t* pMaxPrimitiveCounts,
VkAccelerationStructureBuildSizesInfoKHR* pSizeInfo);
-
deviceis the logical device that will be used for creating the acceleration structure. -
buildTypedefines whether host or device operations (or both) are being queried for. -
pBuildInfois a pointer to a VkAccelerationStructureBuildGeometryInfoKHR structure describing parameters of a build operation. -
pMaxPrimitiveCountsis a pointer to an array ofpBuildInfo->geometryCountuint32_tvalues defining the number of primitives built into each geometry. -
pSizeInfois a pointer to a VkAccelerationStructureBuildSizesInfoKHR structure which returns the size required for an acceleration structure and the sizes required for the scratch buffers, given the build parameters.
The srcAccelerationStructure, dstAccelerationStructure, and
mode members of pBuildInfo are ignored.
Any VkDeviceOrHostAddressKHR members of pBuildInfo are ignored
by this command, except that the hostAddress member of
VkAccelerationStructureGeometryTrianglesDataKHR::transformData
will be examined to check if it is NULL.
An acceleration structure created with the accelerationStructureSize
returned by this command supports any build or update with a
VkAccelerationStructureBuildGeometryInfoKHR structure and array of
VkAccelerationStructureBuildRangeInfoKHR structures subject to the
following properties:
-
The build command is a host build command, and
buildTypeisVK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHRorVK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR -
The build command is a device build command, and
buildTypeisVK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHRorVK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR -
For VkAccelerationStructureBuildGeometryInfoKHR:
-
Its
type, andflagsmembers are equal topBuildInfo->typeandpBuildInfo->flags, respectively. -
geometryCountis less than or equal topBuildInfo->geometryCount. -
For each element of either
pGeometriesorppGeometriesat a given index, itsgeometryTypemember is equal topBuildInfo->geometryType. -
For each element of either
pGeometriesorppGeometriesat a given index, itsflagsmember is equal to the corresponding member of the same element inpBuildInfo. -
For each element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, thevertexFormatandindexTypemembers ofgeometry.trianglesare equal to the corresponding members of the same element inpBuildInfo. -
For each element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, themaxVertexmember ofgeometry.trianglesis less than or equal to the corresponding member of the same element inpBuildInfo. -
For each element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, if the applicable address in thetransformDatamember ofgeometry.trianglesis notNULL, the correspondingtransformData.hostAddressparameter inpBuildInfois notNULL.
-
-
For each VkAccelerationStructureBuildRangeInfoKHR corresponding to the VkAccelerationStructureBuildGeometryInfoKHR:
-
Its
primitiveCountmember is less than or equal to the corresponding element ofpMaxPrimitiveCounts.
-
Similarly, the updateScratchSize value will support any build command
specifying the VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR
mode under the above conditions, and the buildScratchSize value
will support any build command specifying the
VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR mode under the
above conditions.
The VkAccelerationStructureBuildSizesInfoKHR structure describes the
required build sizes for an acceleration structure and scratch buffers and
is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureBuildSizesInfoKHR {
VkStructureType sType;
const void* pNext;
VkDeviceSize accelerationStructureSize;
VkDeviceSize updateScratchSize;
VkDeviceSize buildScratchSize;
} VkAccelerationStructureBuildSizesInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructureSizeis the size in bytes required in a VkAccelerationStructureKHR for a build or update operation. -
updateScratchSizeis the size in bytes required in a scratch buffer for an update operation. -
buildScratchSizeis the size in bytes required in a scratch buffer for a build operation.
Values which can be set in
VkAccelerationStructureCreateInfoKHR::type
or
VkAccelerationStructureInfoNV::type
specifying the type of acceleration structure, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureTypeKHR {
VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR = 0,
VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR = 1,
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR = 2,
// Provided by VK_NV_ray_tracing
VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV = VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR,
// Provided by VK_NV_ray_tracing
VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV = VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR,
} VkAccelerationStructureTypeKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkAccelerationStructureTypeKHR VkAccelerationStructureTypeNV;
-
VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHRis a top-level acceleration structure containing instance data referring to bottom-level acceleration structures. -
VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHRis a bottom-level acceleration structure containing the AABBs or geometry to be intersected. -
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHRis an acceleration structure whose type is determined at build time used for special circumstances.
Bits which can be set in
VkAccelerationStructureCreateInfoKHR::createFlags, specifying
additional creation parameters for acceleration structures, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureCreateFlagBitsKHR {
VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR = 0x00000001,
// Provided by VK_NV_ray_tracing_motion_blur
VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV = 0x00000004,
} VkAccelerationStructureCreateFlagBitsKHR;
-
VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHRspecifies that the acceleration structure’s address can be saved and reused on a subsequent run.
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkAccelerationStructureCreateFlagsKHR;
VkAccelerationStructureCreateFlagsKHR is a bitmask type for setting a
mask of zero or more VkAccelerationStructureCreateFlagBitsKHR.
Bits which can be set in
VkAccelerationStructureBuildGeometryInfoKHR::flags
or
VkAccelerationStructureInfoNV::flags
specifying additional parameters for acceleration structure builds, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkBuildAccelerationStructureFlagBitsKHR {
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR = 0x00000001,
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR = 0x00000002,
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR = 0x00000004,
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR = 0x00000008,
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR = 0x00000010,
// Provided by VK_NV_ray_tracing_motion_blur
VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV = 0x00000020,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR,
} VkBuildAccelerationStructureFlagBitsKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkBuildAccelerationStructureFlagBitsKHR VkBuildAccelerationStructureFlagBitsNV;
-
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHRindicates that the specified acceleration structure can be updated with amodeofVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHRin VkAccelerationStructureBuildGeometryInfoKHR or anupdateofVK_TRUEin vkCmdBuildAccelerationStructureNV . -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHRindicates that the specified acceleration structure can act as the source for a copy acceleration structure command withmodeofVK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHRto produce a compacted acceleration structure. -
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHRindicates that the given acceleration structure build should prioritize trace performance over build time. -
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHRindicates that the given acceleration structure build should prioritize build time over trace performance. -
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHRindicates that this acceleration structure should minimize the size of the scratch memory and the final result acceleration structure, potentially at the expense of build time or trace performance.
|
Note
|
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkBuildAccelerationStructureFlagsKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkBuildAccelerationStructureFlagsKHR VkBuildAccelerationStructureFlagsNV;
VkBuildAccelerationStructureFlagsKHR is a bitmask type for setting a
mask of zero or more VkBuildAccelerationStructureFlagBitsKHR.
The VkGeometryNV structure describes geometry in a bottom-level
acceleration structure and is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkGeometryNV {
VkStructureType sType;
const void* pNext;
VkGeometryTypeKHR geometryType;
VkGeometryDataNV geometry;
VkGeometryFlagsKHR flags;
} VkGeometryNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
geometryTypespecifies the VkGeometryTypeKHR which this geometry refers to. -
geometrycontains the geometry data as described in VkGeometryDataNV. -
flagshas VkGeometryFlagBitsKHR describing options for this geometry.
Geometry types are specified by VkGeometryTypeKHR, which takes values:
// Provided by VK_KHR_acceleration_structure
typedef enum VkGeometryTypeKHR {
VK_GEOMETRY_TYPE_TRIANGLES_KHR = 0,
VK_GEOMETRY_TYPE_AABBS_KHR = 1,
VK_GEOMETRY_TYPE_INSTANCES_KHR = 2,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_TYPE_TRIANGLES_NV = VK_GEOMETRY_TYPE_TRIANGLES_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_TYPE_AABBS_NV = VK_GEOMETRY_TYPE_AABBS_KHR,
} VkGeometryTypeKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryTypeKHR VkGeometryTypeNV;
-
VK_GEOMETRY_TYPE_TRIANGLES_KHRspecifies a geometry type consisting of triangles. -
VK_GEOMETRY_TYPE_AABBS_KHRspecifies a geometry type consisting of axis-aligned bounding boxes. -
VK_GEOMETRY_TYPE_INSTANCES_KHRspecifies a geometry type consisting of acceleration structure instances.
Bits specifying additional parameters for geometries in acceleration structure builds, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkGeometryFlagBitsKHR {
VK_GEOMETRY_OPAQUE_BIT_KHR = 0x00000001,
VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR = 0x00000002,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_OPAQUE_BIT_NV = VK_GEOMETRY_OPAQUE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_NV = VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR,
} VkGeometryFlagBitsKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryFlagBitsKHR VkGeometryFlagBitsNV;
-
VK_GEOMETRY_OPAQUE_BIT_KHRindicates that this geometry does not invoke the any-hit shaders even if present in a hit group. -
VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHRindicates that the implementation must only call the any-hit shader a single time for each primitive in this geometry. If this bit is absent an implementation may invoke the any-hit shader more than once for this geometry.
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkGeometryFlagsKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryFlagsKHR VkGeometryFlagsNV;
VkGeometryFlagsKHR is a bitmask type for setting a mask of zero or
more VkGeometryFlagBitsKHR.
The VkGeometryDataNV structure specifes geometry in a bottom-level
acceleration structure and is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkGeometryDataNV {
VkGeometryTrianglesNV triangles;
VkGeometryAABBNV aabbs;
} VkGeometryDataNV;
-
trianglescontains triangle data if VkGeometryNV::geometryTypeisVK_GEOMETRY_TYPE_TRIANGLES_NV. -
aabbscontains axis-aligned bounding box data if VkGeometryNV::geometryTypeisVK_GEOMETRY_TYPE_AABBS_NV.
The VkGeometryTrianglesNV structure specifies triangle geometry in a
bottom-level acceleration structure and is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkGeometryTrianglesNV {
VkStructureType sType;
const void* pNext;
VkBuffer vertexData;
VkDeviceSize vertexOffset;
uint32_t vertexCount;
VkDeviceSize vertexStride;
VkFormat vertexFormat;
VkBuffer indexData;
VkDeviceSize indexOffset;
uint32_t indexCount;
VkIndexType indexType;
VkBuffer transformData;
VkDeviceSize transformOffset;
} VkGeometryTrianglesNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexDatais the buffer containing vertex data for this geometry. -
vertexOffsetis the offset in bytes withinvertexDatacontaining vertex data for this geometry. -
vertexCountis the number of valid vertices. -
vertexStrideis the stride in bytes between each vertex. -
vertexFormatis a VkFormat describing the format of each vertex element. -
indexDatais the buffer containing index data for this geometry. -
indexOffsetis the offset in bytes withinindexDatacontaining index data for this geometry. -
indexCountis the number of indices to include in this geometry. -
indexTypeis a VkIndexType describing the format of each index. -
transformDatais an optional buffer containing an VkTransformMatrixNV structure defining a transformation to be applied to this geometry. -
transformOffsetis the offset in bytes intransformDataof the transform information described above.
If indexType is VK_INDEX_TYPE_NONE_NV, then this structure
describes a set of triangles determined by vertexCount.
Otherwise, this structure describes a set of indexed triangles determined by
indexCount.
The VkGeometryAABBNV structure specifies axis-aligned bounding box
geometry in a bottom-level acceleration structure, and is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkGeometryAABBNV {
VkStructureType sType;
const void* pNext;
VkBuffer aabbData;
uint32_t numAABBs;
uint32_t stride;
VkDeviceSize offset;
} VkGeometryAABBNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
aabbDatais the buffer containing axis-aligned bounding box data. -
numAABBsis the number of AABBs in this geometry. -
strideis the stride in bytes between AABBs inaabbData. -
offsetis the offset in bytes of the first AABB inaabbData.
The AABB data in memory is six 32-bit floats consisting of the minimum x, y, and z values followed by the maximum x, y, and z values.
To destroy an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
void vkDestroyAccelerationStructureKHR(
VkDevice device,
VkAccelerationStructureKHR accelerationStructure,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the acceleration structure. -
accelerationStructureis the acceleration structure to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
To destroy an acceleration structure, call:
// Provided by VK_NV_ray_tracing
void vkDestroyAccelerationStructureNV(
VkDevice device,
VkAccelerationStructureNV accelerationStructure,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the buffer. -
accelerationStructureis the acceleration structure to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
An acceleration structure has memory requirements for the structure object itself, scratch space for the build, and scratch space for the update.
Scratch space is allocated as a VkBuffer, so for
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV
and
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV
the pMemoryRequirements->alignment and
pMemoryRequirements->memoryTypeBits values returned by this call must
be filled with zero, and should be ignored by the application.
To query the memory requirements, call:
// Provided by VK_NV_ray_tracing
void vkGetAccelerationStructureMemoryRequirementsNV(
VkDevice device,
const VkAccelerationStructureMemoryRequirementsInfoNV* pInfo,
VkMemoryRequirements2KHR* pMemoryRequirements);
-
deviceis the logical device on which the acceleration structure was created. -
pInfois a pointer to a VkAccelerationStructureMemoryRequirementsInfoNV structure specifying the acceleration structure to get memory requirements for. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2KHR structure in which the requested acceleration structure memory requirements are returned.
The VkAccelerationStructureMemoryRequirementsInfoNV structure is
defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureMemoryRequirementsInfoNV {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureMemoryRequirementsTypeNV type;
VkAccelerationStructureNV accelerationStructure;
} VkAccelerationStructureMemoryRequirementsInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeselects the type of memory requirement being queried.VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NVreturns the memory requirements for the object itself.VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NVreturns the memory requirements for the scratch memory when doing a build.VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NVreturns the memory requirements for the scratch memory when doing an update. -
accelerationStructureis the acceleration structure to be queried for memory requirements.
Possible values of type in
VkAccelerationStructureMemoryRequirementsInfoNV are:,
// Provided by VK_NV_ray_tracing
typedef enum VkAccelerationStructureMemoryRequirementsTypeNV {
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV = 0,
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV = 1,
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV = 2,
} VkAccelerationStructureMemoryRequirementsTypeNV;
-
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NVrequests the memory requirement for theVkAccelerationStructureNVbacking store. -
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NVrequests the memory requirement for scratch space during the initial build. -
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NVrequests the memory requirement for scratch space during an update.
Possible values of buildType in
vkGetAccelerationStructureBuildSizesKHR are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureBuildTypeKHR {
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR = 0,
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR = 1,
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR = 2,
} VkAccelerationStructureBuildTypeKHR;
-
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHRrequests the memory requirement for operations performed by the host. -
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHRrequests the memory requirement for operations performed by the device. -
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHRrequests the memory requirement for operations performed by either the host, or the device.
To attach memory to one or more acceleration structures at a time, call:
// Provided by VK_NV_ray_tracing
VkResult vkBindAccelerationStructureMemoryNV(
VkDevice device,
uint32_t bindInfoCount,
const VkBindAccelerationStructureMemoryInfoNV* pBindInfos);
-
deviceis the logical device that owns the acceleration structures and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array of VkBindAccelerationStructureMemoryInfoNV structures describing acceleration structures and memory to bind.
The VkBindAccelerationStructureMemoryInfoNV structure is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkBindAccelerationStructureMemoryInfoNV {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureNV accelerationStructure;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
uint32_t deviceIndexCount;
const uint32_t* pDeviceIndices;
} VkBindAccelerationStructureMemoryInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructureis the acceleration structure to be attached to memory. -
memoryis aVkDeviceMemoryobject describing the device memory to attach. -
memoryOffsetis the start offset of the region of memory that is to be bound to the acceleration structure. The number of bytes returned in the VkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified acceleration structure. -
deviceIndexCountis the number of elements inpDeviceIndices. -
pDeviceIndicesis a pointer to an array of device indices.
To allow constructing geometry instances with device code if desired, we need to be able to query a opaque handle for an acceleration structure. This handle is a value of 8 bytes. To get this handle, call:
// Provided by VK_NV_ray_tracing
VkResult vkGetAccelerationStructureHandleNV(
VkDevice device,
VkAccelerationStructureNV accelerationStructure,
size_t dataSize,
void* pData);
-
deviceis the logical device that owns the acceleration structures. -
accelerationStructureis the acceleration structure. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to a user-allocated buffer where the results will be written.
To query the 64-bit device address for an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
VkDeviceAddress vkGetAccelerationStructureDeviceAddressKHR(
VkDevice device,
const VkAccelerationStructureDeviceAddressInfoKHR* pInfo);
-
deviceis the logical device that the acceleration structure was created on. -
pInfois a pointer to a VkAccelerationStructureDeviceAddressInfoKHR structure specifying the acceleration structure to retrieve an address for.
The 64-bit return value is an address of the acceleration structure, which can be used for device and shader operations that involve acceleration structures, such as ray traversal and acceleration structure building.
If the acceleration structure was created with a non-zero value of
VkAccelerationStructureCreateInfoKHR::deviceAddress, the return
value will be the same address.
If the acceleration structure was created with a type of
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR, the returned address must
be consistent with the relative offset to other acceleration structures with
type VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR allocated with
the same VkBuffer.
That is, the difference in returned addresses between the two must be the
same as the difference in offsets provided at acceleration structure
creation.
|
Note
The acceleration structure device address may be different from the buffer
device address corresponding to the acceleration structure’s start offset in
its storage buffer for acceleration structure types other than
|
The VkAccelerationStructureDeviceAddressInfoKHR structure is defined
as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureDeviceAddressInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureKHR accelerationStructure;
} VkAccelerationStructureDeviceAddressInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructurespecifies the acceleration structure whose address is being queried.
12.7. Resource Memory Association
Resources are initially created as virtual allocations with no backing memory. Device memory is allocated separately (see Device Memory) and then associated with the resource. This association is done differently for sparse and non-sparse resources.
Resources created with any of the sparse creation flags are considered sparse resources. Resources created without these flags are non-sparse. The details on resource memory association for sparse resources is described in Sparse Resources.
Non-sparse resources must be bound completely and contiguously to a single
VkDeviceMemory object before the resource is passed as a parameter to
any of the following operations:
-
creating image or buffer views
-
updating descriptor sets
-
recording commands in a command buffer
Once bound, the memory binding is immutable for the lifetime of the resource.
In a logical device representing more than one physical device, buffer and image resources exist on all physical devices but can be bound to memory differently on each. Each such replicated resource is an instance of the resource. For sparse resources, each instance can be bound to memory arbitrarily differently. For non-sparse resources, each instance can either be bound to the local or a peer instance of the memory, or for images can be bound to rectangular regions from the local and/or peer instances. When a resource is used in a descriptor set, each physical device interprets the descriptor according to its own instance’s binding to memory.
|
Note
There are no new copy commands to transfer data between physical devices. Instead, an application can create a resource with a peer mapping and use it as the source or destination of a transfer command executed by a single physical device to copy the data from one physical device to another. |
To determine the memory requirements for a buffer resource, call:
// Provided by VK_VERSION_1_0
void vkGetBufferMemoryRequirements(
VkDevice device,
VkBuffer buffer,
VkMemoryRequirements* pMemoryRequirements);
-
deviceis the logical device that owns the buffer. -
bufferis the buffer to query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements structure in which the memory requirements of the buffer object are returned.
To determine the memory requirements for an image resource which is not
created with the VK_IMAGE_CREATE_DISJOINT_BIT flag set, call:
// Provided by VK_VERSION_1_0
void vkGetImageMemoryRequirements(
VkDevice device,
VkImage image,
VkMemoryRequirements* pMemoryRequirements);
-
deviceis the logical device that owns the image. -
imageis the image to query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements structure in which the memory requirements of the image object are returned.
The VkMemoryRequirements structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkMemoryRequirements {
VkDeviceSize size;
VkDeviceSize alignment;
uint32_t memoryTypeBits;
} VkMemoryRequirements;
-
sizeis the size, in bytes, of the memory allocation required for the resource. -
alignmentis the alignment, in bytes, of the offset within the allocation required for the resource. -
memoryTypeBitsis a bitmask and contains one bit set for every supported memory type for the resource. Bitiis set if and only if the memory typeiin theVkPhysicalDeviceMemoryPropertiesstructure for the physical device is supported for the resource.
The precise size of images that will be bound to external Android hardware
buffer memory is unknown until the memory has been imported or allocated, so
applications must not call vkGetImageMemoryRequirements or
vkGetImageMemoryRequirements2 with such an VkImage before it has
been bound to memory.
For this reason, applications also must not call
vkGetDeviceImageMemoryRequirements with a VkImageCreateInfo
describing an external Android hardware buffer.
When importing Android hardware buffer memory, the allocationSize can
be determined by calling vkGetAndroidHardwareBufferPropertiesANDROID.
When allocating new memory for a VkImage that can be exported to an
Android hardware buffer, the memory’s allocationSize must be zero;
the actual size will be determined by the dedicated image’s parameters.
After the memory has been allocated, the amount of space allocated from the
memory’s heap can be obtained by getting the image’s memory requirements or
by calling vkGetAndroidHardwareBufferPropertiesANDROID with the
Android hardware buffer exported from the memory.
When allocating new memory for a VkBuffer that can be exported to an Android hardware buffer an application may still call vkGetBufferMemoryRequirements or vkGetBufferMemoryRequirements2 with VkBuffer before it has been bound to memory.
If the resource being queried was created with the
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 external memory
handle type, the value of size has no meaning and should be ignored.
The implementation guarantees certain properties about the memory requirements returned by vkGetBufferMemoryRequirements2, vkGetImageMemoryRequirements2, vkGetDeviceBufferMemoryRequirements, vkGetDeviceImageMemoryRequirements, vkGetBufferMemoryRequirements and vkGetImageMemoryRequirements:
-
The
memoryTypeBitsmember always contains at least one bit set. -
If
bufferis aVkBuffernot created with theVK_BUFFER_CREATE_SPARSE_BINDING_BITbit set, or ifimageis linear image, then thememoryTypeBitsmember always contains at least one bit set corresponding to aVkMemoryTypewith apropertyFlagsthat has both theVK_MEMORY_PROPERTY_HOST_VISIBLE_BITbit and theVK_MEMORY_PROPERTY_HOST_COHERENT_BITbit set. In other words, mappable coherent memory can always be attached to these objects. -
If
bufferwas created with VkExternalMemoryBufferCreateInfo::handleTypesset to0orimagewas created with VkExternalMemoryImageCreateInfo::handleTypesset to0, thememoryTypeBitsmember always contains at least one bit set corresponding to aVkMemoryTypewith apropertyFlagsthat has theVK_MEMORY_PROPERTY_DEVICE_LOCAL_BITbit set. -
The
memoryTypeBitsmember is identical for allVkBufferobjects created with the same value for theflagsandusagemembers in the VkBufferCreateInfo structure and thehandleTypesmember of the VkExternalMemoryBufferCreateInfo structure passed to vkCreateBuffer. Further, ifusage1andusage2of type VkBufferUsageFlags are such that the bits set inusage2are a subset of the bits set inusage1, and they have the sameflagsand VkExternalMemoryBufferCreateInfo::handleTypes, then the bits set inmemoryTypeBitsreturned forusage1must be a subset of the bits set inmemoryTypeBitsreturned forusage2, for all values offlags. -
The
alignmentmember is a power of two. -
The
alignmentmember is identical for allVkBufferobjects created with the same combination of values for theusageandflagsmembers in the VkBufferCreateInfo structure passed to vkCreateBuffer. -
If the
maintenance4feature is enabled, then thealignmentmember is identical for allVkImageobjects created with the same combination of values for theflags,imageType,format,extent,mipLevels,arrayLayers,samples,tilingandusagemembers in the VkImageCreateInfo structure passed to vkCreateImage. -
The
alignmentmember satisfies the buffer descriptor offset alignment requirements associated with theVkBuffer’susage:-
If
usageincludedVK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BITorVK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT,alignmentmust be an integer multiple ofVkPhysicalDeviceLimits::minTexelBufferOffsetAlignment. -
If
usageincludedVK_BUFFER_USAGE_UNIFORM_BUFFER_BIT,alignmentmust be an integer multiple ofVkPhysicalDeviceLimits::minUniformBufferOffsetAlignment. -
If
usageincludedVK_BUFFER_USAGE_STORAGE_BUFFER_BIT,alignmentmust be an integer multiple ofVkPhysicalDeviceLimits::minStorageBufferOffsetAlignment.
-
-
For images created with a color format, the
memoryTypeBitsmember is identical for allVkImageobjects created with the same combination of values for thetilingmember, theVK_IMAGE_CREATE_SPARSE_BINDING_BITbit of theflagsmember, theVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BITbit of theflagsmember,handleTypesmember of VkExternalMemoryImageCreateInfo, and theVK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BITof theusagemember in the VkImageCreateInfo structure passed to vkCreateImage. -
For images created with a depth/stencil format, the
memoryTypeBitsmember is identical for allVkImageobjects created with the same combination of values for theformatmember, thetilingmember, theVK_IMAGE_CREATE_SPARSE_BINDING_BITbit of theflagsmember, theVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BITbit of theflagsmember,handleTypesmember of VkExternalMemoryImageCreateInfo, and theVK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BITof theusagemember in the VkImageCreateInfo structure passed to vkCreateImage. -
If the memory requirements are for a
VkImage, thememoryTypeBitsmember must not refer to aVkMemoryTypewith apropertyFlagsthat has theVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BITbit set if theimagedid not haveVK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BITbit set in theusagemember of the VkImageCreateInfo structure passed to vkCreateImage. -
If the memory requirements are for a
VkBuffer, thememoryTypeBitsmember must not refer to aVkMemoryTypewith apropertyFlagsthat has theVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BITbit set.NoteThe implication of this requirement is that lazily allocated memory is disallowed for buffers in all cases.
-
The
sizemember is identical for allVkBufferobjects created with the same combination of creation parameters specified in VkBufferCreateInfo and itspNextchain. -
The
sizemember is identical for allVkImageobjects created with the same combination of creation parameters specified in VkImageCreateInfo and itspNextchain.NoteThis, however, does not imply that they interpret the contents of the bound memory identically with each other. That additional guarantee, however, can be explicitly requested using
VK_IMAGE_CREATE_ALIAS_BIT. -
If the
maintenance4feature is enabled, these additional guarantees apply:-
For a
VkBuffer, thesizememory requirement is never greater than that of anotherVkBuffercreated with a greater or equalsizespecified in VkBufferCreateInfo, all other creation parameters being identical. -
For a
VkBuffer, thesizememory requirement is never greater than the result of aligning VkBufferCreateInfo::sizewith thealignmentmemory requirement. -
For a VkImage, the
sizememory requirement is never greater than that of another VkImage created with a greater or equal value in each ofextent.width,extent.height, andextent.depth; all other creation parameters being identical. -
The memory requirements returned by vkGetDeviceBufferMemoryRequirements are identical to those that would be returned by vkGetBufferMemoryRequirements2 if it were called with a
VkBuffercreated with the same VkBufferCreateInfo values. -
The memory requirements returned by vkGetDeviceImageMemoryRequirements are identical to those that would be returned by vkGetImageMemoryRequirements2 if it were called with a
VkImagecreated with the same VkImageCreateInfo values.
-
To determine the memory requirements for a buffer resource, call:
// Provided by VK_VERSION_1_1
void vkGetBufferMemoryRequirements2(
VkDevice device,
const VkBufferMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
or the equivalent command
// Provided by VK_KHR_get_memory_requirements2
void vkGetBufferMemoryRequirements2KHR(
VkDevice device,
const VkBufferMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device that owns the buffer. -
pInfois a pointer to a VkBufferMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.
To determine the memory requirements for a buffer resource without creating an object, call:
// Provided by VK_VERSION_1_3
void vkGetDeviceBufferMemoryRequirements(
VkDevice device,
const VkDeviceBufferMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
or the equivalent command
// Provided by VK_KHR_maintenance4
void vkGetDeviceBufferMemoryRequirementsKHR(
VkDevice device,
const VkDeviceBufferMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device intended to own the buffer. -
pInfois a pointer to a VkDeviceBufferMemoryRequirements structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.
The VkBufferMemoryRequirementsInfo2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBufferMemoryRequirementsInfo2 {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
} VkBufferMemoryRequirementsInfo2;
or the equivalent
// Provided by VK_KHR_get_memory_requirements2
typedef VkBufferMemoryRequirementsInfo2 VkBufferMemoryRequirementsInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferis the buffer to query.
The VkDeviceBufferMemoryRequirements structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkDeviceBufferMemoryRequirements {
VkStructureType sType;
const void* pNext;
const VkBufferCreateInfo* pCreateInfo;
} VkDeviceBufferMemoryRequirements;
or the equivalent
// Provided by VK_KHR_maintenance4
typedef VkDeviceBufferMemoryRequirements VkDeviceBufferMemoryRequirementsKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pCreateInfois a pointer to a VkBufferCreateInfo structure containing parameters affecting creation of the buffer to query.
To determine the memory requirements for an image resource, call:
// Provided by VK_VERSION_1_1
void vkGetImageMemoryRequirements2(
VkDevice device,
const VkImageMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
or the equivalent command
// Provided by VK_KHR_get_memory_requirements2
void vkGetImageMemoryRequirements2KHR(
VkDevice device,
const VkImageMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device that owns the image. -
pInfois a pointer to a VkImageMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the image object are returned.
To determine the memory requirements for an image resource without creating an object, call:
// Provided by VK_VERSION_1_3
void vkGetDeviceImageMemoryRequirements(
VkDevice device,
const VkDeviceImageMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
or the equivalent command
// Provided by VK_KHR_maintenance4
void vkGetDeviceImageMemoryRequirementsKHR(
VkDevice device,
const VkDeviceImageMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device intended to own the image. -
pInfois a pointer to a VkDeviceImageMemoryRequirements structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the image object are returned.
The VkImageMemoryRequirementsInfo2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImageMemoryRequirementsInfo2 {
VkStructureType sType;
const void* pNext;
VkImage image;
} VkImageMemoryRequirementsInfo2;
or the equivalent
// Provided by VK_KHR_get_memory_requirements2
typedef VkImageMemoryRequirementsInfo2 VkImageMemoryRequirementsInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis the image to query.
The VkDeviceImageMemoryRequirements structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkDeviceImageMemoryRequirements {
VkStructureType sType;
const void* pNext;
const VkImageCreateInfo* pCreateInfo;
VkImageAspectFlagBits planeAspect;
} VkDeviceImageMemoryRequirements;
or the equivalent
// Provided by VK_KHR_maintenance4
typedef VkDeviceImageMemoryRequirements VkDeviceImageMemoryRequirementsKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pCreateInfois a pointer to a VkImageCreateInfo structure containing parameters affecting creation of the image to query. -
planeAspectis a VkImageAspectFlagBits value specifying the aspect corresponding to the image plane to query. This parameter is ignored unlesspCreateInfo::tilingisVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, orpCreateInfo::flagshasVK_IMAGE_CREATE_DISJOINT_BITset.
To determine the memory requirements for a plane of a disjoint image, add a
VkImagePlaneMemoryRequirementsInfo structure to the pNext chain
of the VkImageMemoryRequirementsInfo2 structure.
The VkImagePlaneMemoryRequirementsInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImagePlaneMemoryRequirementsInfo {
VkStructureType sType;
const void* pNext;
VkImageAspectFlagBits planeAspect;
} VkImagePlaneMemoryRequirementsInfo;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkImagePlaneMemoryRequirementsInfo VkImagePlaneMemoryRequirementsInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
planeAspectis a VkImageAspectFlagBits value specifying the aspect corresponding to the image plane to query.
The VkMemoryRequirements2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkMemoryRequirements2 {
VkStructureType sType;
void* pNext;
VkMemoryRequirements memoryRequirements;
} VkMemoryRequirements2;
or the equivalent
// Provided by VK_KHR_get_memory_requirements2, VK_NV_ray_tracing
typedef VkMemoryRequirements2 VkMemoryRequirements2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryRequirementsis a VkMemoryRequirements structure describing the memory requirements of the resource.
The VkMemoryDedicatedRequirements structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkMemoryDedicatedRequirements {
VkStructureType sType;
void* pNext;
VkBool32 prefersDedicatedAllocation;
VkBool32 requiresDedicatedAllocation;
} VkMemoryDedicatedRequirements;
or the equivalent
// Provided by VK_KHR_dedicated_allocation
typedef VkMemoryDedicatedRequirements VkMemoryDedicatedRequirementsKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
prefersDedicatedAllocationspecifies that the implementation would prefer a dedicated allocation for this resource. The application is still free to suballocate the resource but it may get better performance if a dedicated allocation is used. -
requiresDedicatedAllocationspecifies that a dedicated allocation is required for this resource.
To determine the dedicated allocation requirements of a buffer or image
resource, add a VkMemoryDedicatedRequirements structure to the
pNext chain of the VkMemoryRequirements2 structure passed as the
pMemoryRequirements parameter of vkGetBufferMemoryRequirements2
or vkGetImageMemoryRequirements2, respectively.
Constraints on the values returned for buffer resources are:
-
requiresDedicatedAllocationmay beVK_TRUEif thepNextchain of VkBufferCreateInfo for the call tovkCreateBufferused to create the buffer being queried included a VkExternalMemoryBufferCreateInfo structure, and any of the handle types specified in VkExternalMemoryBufferCreateInfo::handleTypesrequires dedicated allocation, as reported by vkGetPhysicalDeviceExternalBufferProperties inVkExternalBufferProperties::externalMemoryProperties.externalMemoryFeatures. Otherwise,requiresDedicatedAllocationwill beVK_FALSE. -
When the implementation sets
requiresDedicatedAllocationtoVK_TRUE, it must also setprefersDedicatedAllocationtoVK_TRUE. -
If
VK_BUFFER_CREATE_SPARSE_BINDING_BITwas set in VkBufferCreateInfo::flagswhenbufferwas created, then bothprefersDedicatedAllocationandrequiresDedicatedAllocationwill beVK_FALSE.
Constraints on the values returned for image resources are:
-
requiresDedicatedAllocationmay beVK_TRUEif thepNextchain of VkImageCreateInfo for the call to vkCreateImage used to create the image being queried included a VkExternalMemoryImageCreateInfo structure, and any of the handle types specified in VkExternalMemoryImageCreateInfo::handleTypesrequires dedicated allocation, as reported by vkGetPhysicalDeviceImageFormatProperties2 inVkExternalImageFormatProperties::externalMemoryProperties.externalMemoryFeatures. Otherwise,requiresDedicatedAllocationwill beVK_FALSE. -
If
VK_IMAGE_CREATE_SPARSE_BINDING_BITwas set in VkImageCreateInfo::flagswhenimagewas created, then bothprefersDedicatedAllocationandrequiresDedicatedAllocationwill beVK_FALSE.
To attach memory to a buffer object, call:
// Provided by VK_VERSION_1_0
VkResult vkBindBufferMemory(
VkDevice device,
VkBuffer buffer,
VkDeviceMemory memory,
VkDeviceSize memoryOffset);
-
deviceis the logical device that owns the buffer and memory. -
bufferis the buffer to be attached to memory. -
memoryis a VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the buffer. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified buffer.
vkBindBufferMemory is equivalent to passing the same parameters
through VkBindBufferMemoryInfo to vkBindBufferMemory2.
To attach memory to buffer objects for one or more buffers at a time, call:
// Provided by VK_VERSION_1_1
VkResult vkBindBufferMemory2(
VkDevice device,
uint32_t bindInfoCount,
const VkBindBufferMemoryInfo* pBindInfos);
or the equivalent command
// Provided by VK_KHR_bind_memory2
VkResult vkBindBufferMemory2KHR(
VkDevice device,
uint32_t bindInfoCount,
const VkBindBufferMemoryInfo* pBindInfos);
-
deviceis the logical device that owns the buffers and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array ofbindInfoCountVkBindBufferMemoryInfo structures describing buffers and memory to bind.
On some implementations, it may be more efficient to batch memory bindings into a single command.
VkBindBufferMemoryInfo contains members corresponding to the
parameters of vkBindBufferMemory.
The VkBindBufferMemoryInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindBufferMemoryInfo {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
} VkBindBufferMemoryInfo;
or the equivalent
// Provided by VK_KHR_bind_memory2
typedef VkBindBufferMemoryInfo VkBindBufferMemoryInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferis the buffer to be attached to memory. -
memoryis a VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the buffer. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified buffer.
The VkBindBufferMemoryDeviceGroupInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindBufferMemoryDeviceGroupInfo {
VkStructureType sType;
const void* pNext;
uint32_t deviceIndexCount;
const uint32_t* pDeviceIndices;
} VkBindBufferMemoryDeviceGroupInfo;
or the equivalent
// Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
typedef VkBindBufferMemoryDeviceGroupInfo VkBindBufferMemoryDeviceGroupInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceIndexCountis the number of elements inpDeviceIndices. -
pDeviceIndicesis a pointer to an array of device indices.
If the pNext chain of VkBindBufferMemoryInfo includes a
VkBindBufferMemoryDeviceGroupInfo structure, then that structure
determines how memory is bound to buffers across multiple devices in a
device group.
If deviceIndexCount is greater than zero, then on device index i
the buffer is attached to the instance of memory on the physical
device with device index pDeviceIndices[i].
If deviceIndexCount is zero and memory comes from a memory heap
with the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if
pDeviceIndices contains consecutive indices from zero to the number of
physical devices in the logical device, minus one.
In other words, by default each physical device attaches to its own instance
of memory.
If deviceIndexCount is zero and memory comes from a memory heap
without the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as
if pDeviceIndices contains an array of zeros.
In other words, by default each physical device attaches to instance zero.
To attach memory to a VkImage object created without the
VK_IMAGE_CREATE_DISJOINT_BIT set, call:
// Provided by VK_VERSION_1_0
VkResult vkBindImageMemory(
VkDevice device,
VkImage image,
VkDeviceMemory memory,
VkDeviceSize memoryOffset);
-
deviceis the logical device that owns the image and memory. -
imageis the image. -
memoryis the VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the image. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified image.
vkBindImageMemory is equivalent to passing the same parameters through
VkBindImageMemoryInfo to vkBindImageMemory2.
To attach memory to image objects for one or more images at a time, call:
// Provided by VK_VERSION_1_1
VkResult vkBindImageMemory2(
VkDevice device,
uint32_t bindInfoCount,
const VkBindImageMemoryInfo* pBindInfos);
or the equivalent command
// Provided by VK_KHR_bind_memory2
VkResult vkBindImageMemory2KHR(
VkDevice device,
uint32_t bindInfoCount,
const VkBindImageMemoryInfo* pBindInfos);
-
deviceis the logical device that owns the images and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array of VkBindImageMemoryInfo structures, describing images and memory to bind.
On some implementations, it may be more efficient to batch memory bindings into a single command.
VkBindImageMemoryInfo contains members corresponding to the parameters
of vkBindImageMemory.
The VkBindImageMemoryInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindImageMemoryInfo {
VkStructureType sType;
const void* pNext;
VkImage image;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
} VkBindImageMemoryInfo;
or the equivalent
// Provided by VK_KHR_bind_memory2
typedef VkBindImageMemoryInfo VkBindImageMemoryInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis the image to be attached to memory. -
memoryis a VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the image. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified image.
The VkBindImageMemoryDeviceGroupInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindImageMemoryDeviceGroupInfo {
VkStructureType sType;
const void* pNext;
uint32_t deviceIndexCount;
const uint32_t* pDeviceIndices;
uint32_t splitInstanceBindRegionCount;
const VkRect2D* pSplitInstanceBindRegions;
} VkBindImageMemoryDeviceGroupInfo;
or the equivalent
// Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
typedef VkBindImageMemoryDeviceGroupInfo VkBindImageMemoryDeviceGroupInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceIndexCountis the number of elements inpDeviceIndices. -
pDeviceIndicesis a pointer to an array of device indices. -
splitInstanceBindRegionCountis the number of elements inpSplitInstanceBindRegions. -
pSplitInstanceBindRegionsis a pointer to an array of VkRect2D structures describing which regions of the image are attached to each instance of memory.
If the pNext chain of VkBindImageMemoryInfo includes a
VkBindImageMemoryDeviceGroupInfo structure, then that structure
determines how memory is bound to images across multiple devices in a device
group.
If deviceIndexCount is greater than zero, then on device index i
image is attached to the instance of the memory on the physical device
with device index pDeviceIndices[i].
Let N be the number of physical devices in the logical device.
If splitInstanceBindRegionCount is greater than zero, then
pSplitInstanceBindRegions is a pointer to an array of N2
rectangles, where the image region specified by the rectangle at element
i*N+j in resource instance i is bound to the memory instance
j.
The blocks of the memory that are bound to each sparse image block region
use an offset in memory, relative to memoryOffset, computed as if the
whole image was being bound to a contiguous range of memory.
In other words, horizontally adjacent image blocks use consecutive blocks of
memory, vertically adjacent image blocks are separated by the number of
bytes per block multiplied by the width in blocks of image, and the
block at (0,0) corresponds to memory starting at memoryOffset.
If splitInstanceBindRegionCount and deviceIndexCount are zero
and the memory comes from a memory heap with the
VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if
pDeviceIndices contains consecutive indices from zero to the number of
physical devices in the logical device, minus one.
In other words, by default each physical device attaches to its own instance
of the memory.
If splitInstanceBindRegionCount and deviceIndexCount are zero
and the memory comes from a memory heap without the
VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if
pDeviceIndices contains an array of zeros.
In other words, by default each physical device attaches to instance zero.
If the pNext chain of VkBindImageMemoryInfo includes a
VkBindImageMemorySwapchainInfoKHR structure, then that structure
includes a swapchain handle and image index indicating that the image will
be bound to memory from that swapchain.
The VkBindImageMemorySwapchainInfoKHR structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkBindImageMemorySwapchainInfoKHR {
VkStructureType sType;
const void* pNext;
VkSwapchainKHR swapchain;
uint32_t imageIndex;
} VkBindImageMemorySwapchainInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainis VK_NULL_HANDLE or a swapchain handle. -
imageIndexis an image index withinswapchain.
If swapchain is not NULL, the swapchain and imageIndex
are used to determine the memory that the image is bound to, instead of
memory and memoryOffset.
Memory can be bound to a swapchain and use the pDeviceIndices or
pSplitInstanceBindRegions members of
VkBindImageMemoryDeviceGroupInfo.
In order to bind planes of a disjoint image, add a
VkBindImagePlaneMemoryInfo structure to the pNext chain of
VkBindImageMemoryInfo.
The VkBindImagePlaneMemoryInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindImagePlaneMemoryInfo {
VkStructureType sType;
const void* pNext;
VkImageAspectFlagBits planeAspect;
} VkBindImagePlaneMemoryInfo;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkBindImagePlaneMemoryInfo VkBindImagePlaneMemoryInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
planeAspectis aVkImageAspectFlagBitsvalue specifying the aspect of the disjoint image plane to bind.
The implementation-dependent limit bufferImageGranularity specifies a page-like granularity at which
linear and non-linear resources must be placed in adjacent memory locations
to avoid aliasing.
Two resources which do not satisfy this granularity requirement are said to
alias.
bufferImageGranularity is specified in bytes, and must be a power of
two.
Implementations which do not impose a granularity restriction may report a
bufferImageGranularity value of one.
|
Note
Despite its name, |
Given resourceA at the lower memory offset and resourceB at the higher
memory offset in the same VkDeviceMemory object, where one resource is
linear and the other is non-linear (as defined in the
Glossary), and the following:
resourceA.end = resourceA.memoryOffset + resourceA.size - 1
resourceA.endPage = resourceA.end & ~(bufferImageGranularity-1)
resourceB.start = resourceB.memoryOffset
resourceB.startPage = resourceB.start & ~(bufferImageGranularity-1)
The following property must hold:
resourceA.endPage < resourceB.startPage
That is, the end of the first resource (A) and the beginning of the second
resource (B) must be on separate “pages” of size
bufferImageGranularity.
bufferImageGranularity may be different than the physical page size
of the memory heap.
This restriction is only needed when a linear resource and a non-linear
resource are adjacent in memory and will be used simultaneously.
The memory ranges of adjacent resources can be closer than
bufferImageGranularity, provided they meet the alignment
requirement for the objects in question.
Sparse block size in bytes and sparse image and buffer memory alignments
must all be multiples of the bufferImageGranularity.
Therefore, memory bound to sparse resources naturally satisfies the
bufferImageGranularity.
12.8. Resource Sharing Mode
Buffer and image objects are created with a sharing mode controlling how they can be accessed from queues. The supported sharing modes are:
// Provided by VK_VERSION_1_0
typedef enum VkSharingMode {
VK_SHARING_MODE_EXCLUSIVE = 0,
VK_SHARING_MODE_CONCURRENT = 1,
} VkSharingMode;
-
VK_SHARING_MODE_EXCLUSIVEspecifies that access to any range or image subresource of the object will be exclusive to a single queue family at a time. -
VK_SHARING_MODE_CONCURRENTspecifies that concurrent access to any range or image subresource of the object from multiple queue families is supported.
|
Note
|
Ranges of buffers and image subresources of image objects created using
VK_SHARING_MODE_EXCLUSIVE must only be accessed by queues in the
queue family that has ownership of the resource.
Upon creation, such resources are not owned by any queue family; ownership
is implicitly acquired upon first use within a queue.
Once a resource using VK_SHARING_MODE_EXCLUSIVE is owned by some queue
family, the application must perform a
queue family ownership transfer to make
the memory contents of a range or image subresource accessible to a
different queue family.
|
Note
Images still require a layout transition from
|
A queue family can take ownership of an image subresource or buffer range
of a resource created with VK_SHARING_MODE_EXCLUSIVE, without an
ownership transfer, in the same way as for a resource that was just created;
however, taking ownership in this way has the effect that the contents of
the image subresource or buffer range are undefined.
Ranges of buffers and image subresources of image objects created using
VK_SHARING_MODE_CONCURRENT must only be accessed by queues from the
queue families specified through the queueFamilyIndexCount and
pQueueFamilyIndices members of the corresponding create info
structures.
12.8.1. External Resource Sharing
Resources should only be accessed in the Vulkan instance that has exclusive
ownership of their underlying memory.
Only one Vulkan instance has exclusive ownership of a resource’s underlying
memory at a given time, regardless of whether the resource was created using
VK_SHARING_MODE_EXCLUSIVE or VK_SHARING_MODE_CONCURRENT.
Applications can transfer ownership of a resource’s underlying memory only
if the memory has been imported from or exported to another instance or
external API using external memory handles.
The semantics for transferring ownership outside of the instance are similar
to those used for transferring ownership of VK_SHARING_MODE_EXCLUSIVE
resources between queues, and is also accomplished using
VkBufferMemoryBarrier or VkImageMemoryBarrier operations.
To make the contents of the underlying memory accessible in the destination
instance or API, applications must
-
Release exclusive ownership from the source instance or API.
-
Ensure the release operation has completed using semaphores or fences.
-
Acquire exclusive ownership in the destination instance or API
Unlike queue ownership transfers, the destination instance or API is not
specified explicitly when releasing ownership, nor is the source instance or
API specified when acquiring ownership.
Instead, the image or memory barrier’s dstQueueFamilyIndex or
srcQueueFamilyIndex parameters are set to the reserved queue family
index VK_QUEUE_FAMILY_EXTERNAL
or VK_QUEUE_FAMILY_FOREIGN_EXT
to represent the external destination or source respectively.
Binding a resource to a memory object shared between multiple Vulkan instances or other APIs does not change the ownership of the underlying memory. The first entity to access the resource implicitly acquires ownership. An entity can also implicitly take ownership from another entity in the same way without an explicit ownership transfer. However, taking ownership in this way has the effect that the contents of the underlying memory are undefined.
Accessing a resource backed by memory that is owned by a particular instance
or API has the same semantics as accessing a VK_SHARING_MODE_EXCLUSIVE
resource, with one exception: Implementations must ensure layout
transitions performed on one member of a set of identical subresources of
identical images that alias the same range of an underlying memory object
affect the layout of all the subresources in the set.
As a corollary, writes to any image subresources in such a set must not
make the contents of memory used by other subresources in the set
undefined.
An application can define the content of a subresource of one image by
performing device writes to an identical subresource of another image
provided both images are bound to the same region of external memory.
Applications may also add resources to such a set after the content of the
existing set members has been defined without making the content undefined
by creating a new image with the initial layout
VK_IMAGE_LAYOUT_UNDEFINED and binding it to the same region of
external memory as the existing images.
|
Note
Because layout transitions apply to all identical images aliasing the same region of external memory, the actual layout of the memory backing a new image as well as an existing image with defined content will not be undefined. Such an image is not usable until it acquires ownership of its memory from the existing owner. Therefore, the layout specified as part of this transition will be the true initial layout of the image. The undefined layout specified when creating it is a placeholder to simplify valid usage requirements. |
12.9. Memory Aliasing
A range of a VkDeviceMemory allocation is aliased if it is bound to
multiple resources simultaneously, as described below, via
vkBindImageMemory, vkBindBufferMemory,
vkBindAccelerationStructureMemoryNV,
via sparse memory bindings, or by binding
the memory to resources in multiple Vulkan instances or external APIs using
external memory handle export and import mechanisms.
Consider two resources, resourceA and resourceB, bound respectively to
memory rangeA and rangeB.
Let paddedRangeA and paddedRangeB be, respectively, rangeA and
rangeB aligned to bufferImageGranularity.
If the resources are both linear or both non-linear (as defined in the
Glossary), then the resources alias the
memory in the intersection of rangeA and rangeB.
If one resource is linear and the other is non-linear, then the resources
alias the memory in the intersection of paddedRangeA and paddedRangeB.
Applications can alias memory, but use of multiple aliases is subject to several constraints.
|
Note
Memory aliasing can be useful to reduce the total device memory footprint of an application, if some large resources are used for disjoint periods of time. |
When a non-linear,
non-VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image is bound to an aliased
range, all image subresources of the image overlap the range.
When a linear image is bound to an aliased range, the image subresources
that (according to the image’s advertised layout) include bytes from the
aliased range overlap the range.
When a VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image has sparse image
blocks bound to an aliased range, only image subresources including those
sparse image blocks overlap the range, and when the memory bound to the
image’s mip tail overlaps an aliased range all image subresources in the mip
tail overlap the range.
Buffers, and linear image subresources in either the
VK_IMAGE_LAYOUT_PREINITIALIZED or VK_IMAGE_LAYOUT_GENERAL
layouts, are host-accessible subresources.
That is, the host has a well-defined addressing scheme to interpret the
contents, and thus the layout of the data in memory can be consistently
interpreted across aliases if each of those aliases is a host-accessible
subresource.
Non-linear images, and linear image subresources in other layouts, are not
host-accessible.
If two aliases are both host-accessible, then they interpret the contents of the memory in consistent ways, and data written to one alias can be read by the other alias.
If two aliases are both images that were created with identical creation
parameters, both were created with the VK_IMAGE_CREATE_ALIAS_BIT flag
set, and both are bound identically to memory
except for VkBindImageMemoryDeviceGroupInfo::pDeviceIndices and
VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions,
then they interpret the contents of the memory in consistent ways, and data
written to one alias can be read by the other alias.
Additionally, if an individual plane of a multi-planar image and a single-plane image alias the same memory, then they also interpret the contents of the memory in consistent ways under the same conditions, but with the following modifications:
-
Both must have been created with the
VK_IMAGE_CREATE_DISJOINT_BITflag. -
The single-plane image must have a VkFormat that is equivalent to that of the multi-planar image’s individual plane.
-
The single-plane image and the individual plane of the multi-planar image must be bound identically to memory except for VkBindImageMemoryDeviceGroupInfo::
pDeviceIndicesand VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions. -
The
widthandheightof the single-plane image are derived from the multi-planar image’s dimensions in the manner listed for plane compatibility for the aliased plane. -
If either image’s
tilingisVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then both images must be linear. -
All other creation parameters must be identical
Aliases created by binding the same memory to resources in multiple Vulkan instances or external APIs using external memory handle export and import mechanisms interpret the contents of the memory in consistent ways, and data written to one alias can be read by the other alias.
Otherwise, the aliases interpret the contents of the memory differently, and writes via one alias make the contents of memory partially or completely undefined to the other alias. If the first alias is a host-accessible subresource, then the bytes affected are those written by the memory operations according to its addressing scheme. If the first alias is not host-accessible, then the bytes affected are those overlapped by the image subresources that were written. If the second alias is a host-accessible subresource, the affected bytes become undefined. If the second alias is not host-accessible, all sparse image blocks (for sparse partially-resident images) or all image subresources (for non-sparse image and fully resident sparse images) that overlap the affected bytes become undefined.
If any image subresources are made undefined due to writes to an alias,
then each of those image subresources must have its layout transitioned
from VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, or
from VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by
the host.
If any sparse blocks of a sparse image have been made undefined, then only
the image subresources containing them must be transitioned.
Use of an overlapping range by two aliases must be separated by a memory dependency using the appropriate access types if at least one of those uses performs writes, whether the aliases interpret memory consistently or not. If buffer or image memory barriers are used, the scope of the barrier must contain the entire range and/or set of image subresources that overlap.
If two aliasing image views are used in the same framebuffer, then the
render pass must declare the attachments using the
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, and
follow the other rules listed in that section.
|
Note
Memory recycled via an application suballocator (i.e. without freeing and reallocating the memory objects) is not substantially different from memory aliasing. However, a suballocator usually waits on a fence before recycling a region of memory, and signaling a fence involves sufficient implicit dependencies to satisfy all the above requirements. |
12.10. Buffer Collections
Fuchsia’s FIDL-based Sysmem service interoperates with Vulkan via the
VK_FUCHSIA_buffer_collection extension.
A buffer collection is a set of one or more buffers which were allocated together as a group and which all have the same properties. These properties describe the buffers' internal representation, such as its dimensions and memory layout. This ensures that all of the buffers can be used interchangeably by tasks that require swapping among multiple buffers, such as double-buffered graphics rendering.
On Fuchsia, the Sysmem service uses buffer collections as a core construct in its design.
Buffer collections are represented by VkBufferCollectionFUCHSIA
handles:
// Provided by VK_FUCHSIA_buffer_collection
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBufferCollectionFUCHSIA)
12.10.1. Definitions
-
FIDL - Fuchsia Interface Definition Language. The declarative language used to define FIDL interprocess communication interfaces on Fuchsia. FIDL files use the
fidlextension. FIDL is also used to refer to the services defined by interfaces declared in the FIDL language -
Sysmem - The FIDL service that facilitates optimal buffer sharing and reuse on Fuchsia
-
client - Any participant of the buffer collection e.g. the Vulkan application
-
token - A
zx_handle_tZircon channel object that allows participation in the buffer collection
12.10.2. Platform initialization for buffer collections
To initialize a buffer collection on Fuchsia:
-
Connect to the Sysmem service to initialize a Sysmem allocator
-
Create an initial buffer collection token using the Sysmem allocator
-
Duplicate the token for each participant beyond the initiator
-
See the Sysmem Overview and fuchsia.sysmem FIDL documentation on fuchsia.dev for more detailed information
12.10.3. Create the buffer collection
To create an VkBufferCollectionFUCHSIA for Vulkan to participate in the buffer collection:
// Provided by VK_FUCHSIA_buffer_collection
VkResult vkCreateBufferCollectionFUCHSIA(
VkDevice device,
const VkBufferCollectionCreateInfoFUCHSIA* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkBufferCollectionFUCHSIA* pCollection);
-
deviceis the logical device that creates theVkBufferCollectionFUCHSIA -
pCreateInfois a pointer to a VkBufferCollectionCreateInfoFUCHSIA structure containing parameters affecting creation of the buffer collection -
pAllocatoris a pointer to a VkAllocationCallbacks structure controlling host memory allocation as described in the Memory Allocation chapter -
pBufferCollectionis a pointer to a VkBufferCollectionFUCHSIA handle in which the resulting buffer collection object is returned
The VkBufferCollectionCreateInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionCreateInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
zx_handle_t collectionToken;
} VkBufferCollectionCreateInfoFUCHSIA;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
collectionTokenis azx_handle_tcontaining the Sysmem client’s buffer collection token
12.10.4. Set the constraints
Set image-based buffer collection constraints
Setting the constraints on the buffer collection initiates the format negotiation and allocation of the buffer collection. To set the constraints on a VkImage buffer collection, call:
// Provided by VK_FUCHSIA_buffer_collection
VkResult vkSetBufferCollectionImageConstraintsFUCHSIA(
VkDevice device,
VkBufferCollectionFUCHSIA collection,
const VkImageConstraintsInfoFUCHSIA* pImageConstraintsInfo);
-
deviceis the logical device -
collectionis the VkBufferCollectionFUCHSIA handle -
pImageConstraintsInfois a pointer to a VkImageConstraintsInfoFUCHSIA structure
vkSetBufferCollectionImageConstraintsFUCHSIA may fail if
pImageConstraintsInfo::formatConstraintsCount is larger than the
implementation-defined limit.
If that occurs, vkSetBufferCollectionImageConstraintsFUCHSIA will
return VK_ERROR_INITIALIZATION_FAILED.
vkSetBufferCollectionImageConstraintsFUCHSIA may fail if the
implementation does not support any of the formats described by the
pImageConstraintsInfo structure.
If that occurs, vkSetBufferCollectionImageConstraintsFUCHSIA will
return VK_ERROR_FORMAT_NOT_SUPPORTED.
The VkImageConstraintsInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkImageConstraintsInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
uint32_t formatConstraintsCount;
const VkImageFormatConstraintsInfoFUCHSIA* pFormatConstraints;
VkBufferCollectionConstraintsInfoFUCHSIA bufferCollectionConstraints;
VkImageConstraintsInfoFlagsFUCHSIA flags;
} VkImageConstraintsInfoFUCHSIA;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatConstraintsCountis the number of elements inpFormatConstraints. -
pFormatConstraintsis a pointer to an array of VkImageFormatConstraintsInfoFUCHSIA structures of sizeformatConstraintsCountthat is used to further constrain buffer collection format selection for image-based buffer collections. -
bufferCollectionConstraintsis a VkBufferCollectionConstraintsInfoFUCHSIA structure used to supply parameters for the negotiation and allocation for buffer-based buffer collections. -
flagsis a VkImageConstraintsInfoFlagBitsFUCHSIA value specifying hints about the type of memory Sysmem should allocate for the buffer collection.
// Provided by VK_FUCHSIA_buffer_collection
typedef VkFlags VkImageConstraintsInfoFlagsFUCHSIA;
VkImageConstraintsInfoFlagsFUCHSIA is a bitmask type for setting a
mask of zero or more VkImageConstraintsInfoFlagBitsFUCHSIA bits.
Bits which can be set in
VkImageConstraintsInfoFlagBitsFUCHSIA::flags include:
// Provided by VK_FUCHSIA_buffer_collection
typedef enum VkImageConstraintsInfoFlagBitsFUCHSIA {
VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_RARELY_FUCHSIA = 0x00000001,
VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_OFTEN_FUCHSIA = 0x00000002,
VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_RARELY_FUCHSIA = 0x00000004,
VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_OFTEN_FUCHSIA = 0x00000008,
VK_IMAGE_CONSTRAINTS_INFO_PROTECTED_OPTIONAL_FUCHSIA = 0x00000010,
} VkImageConstraintsInfoFlagBitsFUCHSIA;
General hints about the type of memory that should be allocated by Sysmem based on the expected usage of the images in the buffer collection include:
-
VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_RARELY_FUCHSIA -
VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_OFTEN_FUCHSIA -
VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_RARELY_FUCHSIA -
VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_OFTEN_FUCHSIA
For protected memory:
-
VK_IMAGE_CONSTRAINTS_INFO_PROTECTED_OPTIONAL_FUCHSIAspecifies that protected memory is optional for the buffer collection.
Note that if all participants in the buffer collection (Vulkan or otherwise) specify that protected memory is optional, Sysmem will not allocate protected memory.
The VkImageFormatConstraintsInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkImageFormatConstraintsInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkImageCreateInfo imageCreateInfo;
VkFormatFeatureFlags requiredFormatFeatures;
VkImageFormatConstraintsFlagsFUCHSIA flags;
uint64_t sysmemPixelFormat;
uint32_t colorSpaceCount;
const VkSysmemColorSpaceFUCHSIA* pColorSpaces;
} VkImageFormatConstraintsInfoFUCHSIA;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
imageCreateInfois the VkImageCreateInfo used to create a VkImage that is to use memory from the VkBufferCollectionFUCHSIA -
requiredFormatFeaturesis a bitmask ofVkFormatFeatureFlagBitsspecifying required features of the buffers in the buffer collection -
flagsis reserved for future use -
sysmemPixelFormatis aPixelFormatTypevalue from thefuchsia.sysmem/image_formats.fidlFIDL interface -
colorSpaceCountthe element count ofpColorSpaces -
pColorSpacesis a pointer to an array of VkSysmemColorSpaceFUCHSIA structs of sizecolorSpaceCount
// Provided by VK_FUCHSIA_buffer_collection
typedef VkFlags VkImageFormatConstraintsFlagsFUCHSIA;
VkImageFormatConstraintsFlagsFUCHSIA is a bitmask type for setting a
mask, but is currently reserved for future use.
The VkBufferCollectionConstraintsInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionConstraintsInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
uint32_t minBufferCount;
uint32_t maxBufferCount;
uint32_t minBufferCountForCamping;
uint32_t minBufferCountForDedicatedSlack;
uint32_t minBufferCountForSharedSlack;
} VkBufferCollectionConstraintsInfoFUCHSIA;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
minBufferCountis the minimum number of buffers available in the collection -
maxBufferCountis the maximum number of buffers allowed in the collection -
minBufferCountForCampingis the per-participant minimum buffers for camping -
minBufferCountForDedicatedSlackis the per-participant minimum buffers for dedicated slack -
minBufferCountForSharedSlackis the per-participant minimum buffers for shared slack
Sysmem uses all buffer count parameters in combination to determine the
number of buffers it will allocate.
Sysmem defines buffer count constraints in
fuchsia.sysmem/constraints.fidl.
Camping as referred to by minBufferCountForCamping, is the number of
buffers that should be available for the participant that are not for
transient use.
This number of buffers is required for the participant to logically operate.
Slack as referred to by minBufferCountForDedicatedSlack and
minBufferCountForSharedSlack, refers to the number of buffers desired
by participants for optimal performance.
minBufferCountForDedicatedSlack refers to the current participant.
minBufferCountForSharedSlack refers to buffer slack for all
participants in the collection.
The VkSysmemColorSpaceFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkSysmemColorSpaceFUCHSIA {
VkStructureType sType;
const void* pNext;
uint32_t colorSpace;
} VkSysmemColorSpaceFUCHSIA;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
colorSpacevalue of the SysmemColorSpaceType
Set buffer-based buffer collection constraints
To set the constraints on a VkBuffer buffer collection, call:
// Provided by VK_FUCHSIA_buffer_collection
VkResult vkSetBufferCollectionBufferConstraintsFUCHSIA(
VkDevice device,
VkBufferCollectionFUCHSIA collection,
const VkBufferConstraintsInfoFUCHSIA* pBufferConstraintsInfo);
-
deviceis the logical device -
collectionis the VkBufferCollectionFUCHSIA handle -
pBufferConstraintsInfois a pointer to a VkBufferConstraintsInfoFUCHSIA structure
vkSetBufferCollectionBufferConstraintsFUCHSIA may fail if the
implementation does not support the constraints specified in the
bufferCollectionConstraints structure.
If that occurs, vkSetBufferCollectionBufferConstraintsFUCHSIA will
return VK_ERROR_FORMAT_NOT_SUPPORTED.
The VkBufferConstraintsInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferConstraintsInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkBufferCreateInfo createInfo;
VkFormatFeatureFlags requiredFormatFeatures;
VkBufferCollectionConstraintsInfoFUCHSIA bufferCollectionConstraints;
} VkBufferConstraintsInfoFUCHSIA;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
pBufferCreateInfoa pointer to a VkBufferCreateInfo struct describing the buffer attributes for the buffer collection -
requiredFormatFeaturesbitmask ofVkFormatFeatureFlagBitsrequired features of the buffers in the buffer collection -
bufferCollectionConstraintsis used to supply parameters for the negotiation and allocation of the buffer collection
12.10.5. Retrieve buffer collection properties
After constraints have been set on the buffer collection by calling
vkSetBufferCollectionImageConstraintsFUCHSIA or
vkSetBufferCollectionBufferConstraintsFUCHSIA, call
vkGetBufferCollectionPropertiesFUCHSIA to retrieve the negotiated and
finalized properties of the buffer collection.
The call to vkGetBufferCollectionPropertiesFUCHSIA is synchronous.
It waits for the Sysmem format negotiation and buffer collection allocation
to complete before returning.
// Provided by VK_FUCHSIA_buffer_collection
VkResult vkGetBufferCollectionPropertiesFUCHSIA(
VkDevice device,
VkBufferCollectionFUCHSIA collection,
VkBufferCollectionPropertiesFUCHSIA* pProperties);
-
deviceis the logical device handle -
collectionis the VkBufferCollectionFUCHSIA handle -
pPropertiesis a pointer to the retrieved VkBufferCollectionPropertiesFUCHSIA struct
For image-based buffer collections, upon calling
vkGetBufferCollectionPropertiesFUCHSIA, Sysmem will choose an element
of the VkImageConstraintsInfoFUCHSIA::pImageCreateInfos
established by the preceding call to
vkSetBufferCollectionImageConstraintsFUCHSIA.
The index of the element chosen is stored in and can be retrieved from
VkBufferCollectionPropertiesFUCHSIA::createInfoIndex.
For buffer-based buffer collections, a single VkBufferCreateInfo is
specified as VkBufferConstraintsInfoFUCHSIA::createInfo.
VkBufferCollectionPropertiesFUCHSIA::createInfoIndex will
therefore always be zero.
vkGetBufferCollectionPropertiesFUCHSIA may fail if Sysmem is unable
to resolve the constraints of all of the participants in the buffer
collection.
If that occurs, vkGetBufferCollectionPropertiesFUCHSIA will return
VK_ERROR_INITIALIZATION_FAILED.
The VkBufferCollectionPropertiesFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionPropertiesFUCHSIA {
VkStructureType sType;
void* pNext;
uint32_t memoryTypeBits;
uint32_t bufferCount;
uint32_t createInfoIndex;
uint64_t sysmemPixelFormat;
VkFormatFeatureFlags formatFeatures;
VkSysmemColorSpaceFUCHSIA sysmemColorSpaceIndex;
VkComponentMapping samplerYcbcrConversionComponents;
VkSamplerYcbcrModelConversion suggestedYcbcrModel;
VkSamplerYcbcrRange suggestedYcbcrRange;
VkChromaLocation suggestedXChromaOffset;
VkChromaLocation suggestedYChromaOffset;
} VkBufferCollectionPropertiesFUCHSIA;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
memoryTypeBitsis a bitmask containing one bit set for every memory type which the buffer collection can be imported as buffer collection -
bufferCountis the number of buffers in the collection -
createInfoIndexas described in Sysmem chosen create infos -
sysmemPixelFormatis the SysmemPixelFormatTypeas defined infuchsia.sysmem/image_formats.fidl -
formatFeaturesis a bitmask of VkFormatFeatureFlagBits shared by the buffer collection -
sysmemColorSpaceIndexis a VkSysmemColorSpaceFUCHSIA struct specifying the color space -
samplerYcbcrConversionComponentsis a VkComponentMapping struct specifying the component mapping -
suggestedYcbcrModelis a VkSamplerYcbcrModelConversion value specifying the suggested Y′CBCR model -
suggestedYcbcrRangeis a VkSamplerYcbcrRange value specifying the suggested Y′CBCR range -
suggestedXChromaOffsetis a VkChromaLocation value specifying the suggested X chroma offset -
suggestedYChromaOffsetis a VkChromaLocation value specifying the suggested Y chroma offset
sysmemColorSpace is only set for image-based buffer collections where
the constraints were specified using VkImageConstraintsInfoFUCHSIA in
a call to vkSetBufferCollectionImageConstraintsFUCHSIA.
For image-based buffer collections, createInfoIndex will identify both
the VkImageConstraintsInfoFUCHSIA::pImageCreateInfos element and
the VkImageConstraintsInfoFUCHSIA::pFormatConstraints element
chosen by Sysmem when vkSetBufferCollectionImageConstraintsFUCHSIA was
called.
The value of sysmemColorSpaceIndex will be an index to one of the
color spaces provided in the
VkImageFormatConstraintsInfoFUCHSIA::pColorSpaces array.
The implementation must have formatFeatures with all bits set that
were set in
VkImageFormatConstraintsInfoFUCHSIA::requiredFormatFeatures, by
the call to vkSetBufferCollectionImageConstraintsFUCHSIA, at
createInfoIndex (other bits could be set as well).
12.10.6. Memory allocation
To import memory from a buffer collection into a VkImage or a
VkBuffer, chain a VkImportMemoryBufferCollectionFUCHSIA
structure to the pNext member of the VkMemoryAllocateInfo in the
call to vkAllocateMemory.
The VkImportMemoryBufferCollectionFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkImportMemoryBufferCollectionFUCHSIA {
VkStructureType sType;
const void* pNext;
VkBufferCollectionFUCHSIA collection;
uint32_t index;
} VkImportMemoryBufferCollectionFUCHSIA;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure -
collectionis the VkBufferCollectionFUCHSIA handle -
indexthe index of the buffer to import fromcollection
To release a VkBufferCollectionFUCHSIA:
// Provided by VK_FUCHSIA_buffer_collection
void vkDestroyBufferCollectionFUCHSIA(
VkDevice device,
VkBufferCollectionFUCHSIA collection,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that creates theVkBufferCollectionFUCHSIA -
collectionis the VkBufferCollectionFUCHSIA handle -
pAllocatoris a pointer to a VkAllocationCallbacks structure controlling host memory allocation as described in the Memory Allocation chapter
13. Samplers
VkSampler objects represent the state of an image sampler which is
used by the implementation to read image data and apply filtering and other
transformations for the shader.
Samplers are represented by VkSampler handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSampler)
To create a sampler object, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateSampler(
VkDevice device,
const VkSamplerCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSampler* pSampler);
-
deviceis the logical device that creates the sampler. -
pCreateInfois a pointer to a VkSamplerCreateInfo structure specifying the state of the sampler object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pSampleris a pointer to a VkSampler handle in which the resulting sampler object is returned.
The VkSamplerCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSamplerCreateInfo {
VkStructureType sType;
const void* pNext;
VkSamplerCreateFlags flags;
VkFilter magFilter;
VkFilter minFilter;
VkSamplerMipmapMode mipmapMode;
VkSamplerAddressMode addressModeU;
VkSamplerAddressMode addressModeV;
VkSamplerAddressMode addressModeW;
float mipLodBias;
VkBool32 anisotropyEnable;
float maxAnisotropy;
VkBool32 compareEnable;
VkCompareOp compareOp;
float minLod;
float maxLod;
VkBorderColor borderColor;
VkBool32 unnormalizedCoordinates;
} VkSamplerCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkSamplerCreateFlagBits describing additional parameters of the sampler. -
magFilteris a VkFilter value specifying the magnification filter to apply to lookups. -
minFilteris a VkFilter value specifying the minification filter to apply to lookups. -
mipmapModeis a VkSamplerMipmapMode value specifying the mipmap filter to apply to lookups. -
addressModeUis a VkSamplerAddressMode value specifying the addressing mode for U coordinates outside [0,1). -
addressModeVis a VkSamplerAddressMode value specifying the addressing mode for V coordinates outside [0,1). -
addressModeWis a VkSamplerAddressMode value specifying the addressing mode for W coordinates outside [0,1). -
mipLodBiasis the bias to be added to mipmap LOD (level-of-detail) calculation and bias provided by image sampling functions in SPIR-V, as described in the Level-of-Detail Operation section. -
anisotropyEnableisVK_TRUEto enable anisotropic filtering, as described in the Texel Anisotropic Filtering section, orVK_FALSEotherwise. -
maxAnisotropyis the anisotropy value clamp used by the sampler whenanisotropyEnableisVK_TRUE. IfanisotropyEnableisVK_FALSE,maxAnisotropyis ignored. -
compareEnableisVK_TRUEto enable comparison against a reference value during lookups, orVK_FALSEotherwise.-
Note: Some implementations will default to shader state if this member does not match.
-
-
compareOpis a VkCompareOp value specifying the comparison operator to apply to fetched data before filtering as described in the Depth Compare Operation section. -
minLodis used to clamp the minimum of the computed LOD value. -
maxLodis used to clamp the maximum of the computed LOD value. To avoid clamping the maximum value, setmaxLodto the constantVK_LOD_CLAMP_NONE. -
borderColoris a VkBorderColor value specifying the predefined border color to use. -
unnormalizedCoordinatescontrols whether to use unnormalized or normalized texel coordinates to address texels of the image. When set toVK_TRUE, the range of the image coordinates used to lookup the texel is in the range of zero to the image size in each dimension. When set toVK_FALSEthe range of image coordinates is zero to one.When
unnormalizedCoordinatesisVK_TRUE, images the sampler is used with in the shader have the following requirements:-
The
viewTypemust be eitherVK_IMAGE_VIEW_TYPE_1DorVK_IMAGE_VIEW_TYPE_2D. -
The image view must have a single layer and a single mip level.
When
unnormalizedCoordinatesisVK_TRUE, image built-in functions in the shader that use the sampler have the following requirements:-
The functions must not use projection.
-
The functions must not use offsets.
-
|
Mapping of OpenGL to Vulkan filter modes
There are no Vulkan filter modes that directly correspond to OpenGL
minification filters of Note that using a |
The maximum number of sampler objects which can be simultaneously created
on a device is implementation-dependent and specified by the
maxSamplerAllocationCount member
of the VkPhysicalDeviceLimits structure.
|
Note
For historical reasons, if |
Since VkSampler is a non-dispatchable handle type, implementations
may return the same handle for sampler state vectors that are identical.
In such cases, all such objects would only count once against the
maxSamplerAllocationCount limit.
VK_LOD_CLAMP_NONE is a special constant value used for
VkSamplerCreateInfo::maxLod to indicate that maximum LOD
clamping should not be performed.
#define VK_LOD_CLAMP_NONE 1000.0F
Bits which can be set in VkSamplerCreateInfo::flags, specifying
additional parameters of a sampler, are:
// Provided by VK_VERSION_1_0
typedef enum VkSamplerCreateFlagBits {
// Provided by VK_EXT_fragment_density_map
VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT = 0x00000001,
// Provided by VK_EXT_fragment_density_map
VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT = 0x00000002,
// Provided by VK_EXT_non_seamless_cube_map
VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT = 0x00000004,
} VkSamplerCreateFlagBits;
-
VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXTspecifies that the sampler will read from an image created withflagscontainingVK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT. -
VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXTspecifies that the implementation may use approximations when reconstructing a full color value for texture access from a subsampled image. -
VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXTspecifies that cube map edge handling is not performed.
|
Note
The approximations used when
|
// Provided by VK_VERSION_1_0
typedef VkFlags VkSamplerCreateFlags;
VkSamplerCreateFlags is a bitmask type for setting a mask of zero or
more VkSamplerCreateFlagBits.
The VkSamplerReductionModeCreateInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkSamplerReductionModeCreateInfo {
VkStructureType sType;
const void* pNext;
VkSamplerReductionMode reductionMode;
} VkSamplerReductionModeCreateInfo;
or the equivalent
// Provided by VK_EXT_sampler_filter_minmax
typedef VkSamplerReductionModeCreateInfo VkSamplerReductionModeCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
reductionModeis a VkSamplerReductionMode value controlling how texture filtering combines texel values.
If the pNext chain of VkSamplerCreateInfo includes a
VkSamplerReductionModeCreateInfo structure, then that structure
includes a mode controlling how texture filtering combines texel values.
If this structure is not present, reductionMode is considered to be
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE.
Reduction modes are specified by VkSamplerReductionMode, which takes values:
// Provided by VK_VERSION_1_2
typedef enum VkSamplerReductionMode {
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE = 0,
VK_SAMPLER_REDUCTION_MODE_MIN = 1,
VK_SAMPLER_REDUCTION_MODE_MAX = 2,
// Provided by VK_EXT_sampler_filter_minmax
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT = VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE,
// Provided by VK_EXT_sampler_filter_minmax
VK_SAMPLER_REDUCTION_MODE_MIN_EXT = VK_SAMPLER_REDUCTION_MODE_MIN,
// Provided by VK_EXT_sampler_filter_minmax
VK_SAMPLER_REDUCTION_MODE_MAX_EXT = VK_SAMPLER_REDUCTION_MODE_MAX,
} VkSamplerReductionMode;
or the equivalent
// Provided by VK_EXT_sampler_filter_minmax
typedef VkSamplerReductionMode VkSamplerReductionModeEXT;
-
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGEspecifies that texel values are combined by computing a weighted average of values in the footprint, using weights as specified in the image operations chapter. -
VK_SAMPLER_REDUCTION_MODE_MINspecifies that texel values are combined by taking the component-wise minimum of values in the footprint with non-zero weights. -
VK_SAMPLER_REDUCTION_MODE_MAXspecifies that texel values are combined by taking the component-wise maximum of values in the footprint with non-zero weights.
Possible values of the VkSamplerCreateInfo::magFilter and
minFilter parameters, specifying filters used for texture lookups,
are:
// Provided by VK_VERSION_1_0
typedef enum VkFilter {
VK_FILTER_NEAREST = 0,
VK_FILTER_LINEAR = 1,
// Provided by VK_EXT_filter_cubic
VK_FILTER_CUBIC_EXT = 1000015000,
// Provided by VK_IMG_filter_cubic
VK_FILTER_CUBIC_IMG = VK_FILTER_CUBIC_EXT,
} VkFilter;
-
VK_FILTER_NEARESTspecifies nearest filtering. -
VK_FILTER_LINEARspecifies linear filtering. -
VK_FILTER_CUBIC_EXTspecifies cubic filtering.
These filters are described in detail in Texel Filtering.
Possible values of the VkSamplerCreateInfo::mipmapMode,
specifying the mipmap mode used for texture lookups, are:
// Provided by VK_VERSION_1_0
typedef enum VkSamplerMipmapMode {
VK_SAMPLER_MIPMAP_MODE_NEAREST = 0,
VK_SAMPLER_MIPMAP_MODE_LINEAR = 1,
} VkSamplerMipmapMode;
-
VK_SAMPLER_MIPMAP_MODE_NEARESTspecifies nearest filtering. -
VK_SAMPLER_MIPMAP_MODE_LINEARspecifies linear filtering.
These modes are described in detail in Texel Filtering.
Possible values of the VkSamplerCreateInfo::addressMode*
parameters, specifying the behavior of sampling with coordinates outside the
range [0,1] for the respective u, v, or w coordinate
as defined in the Wrapping Operation
section, are:
// Provided by VK_VERSION_1_0
typedef enum VkSamplerAddressMode {
VK_SAMPLER_ADDRESS_MODE_REPEAT = 0,
VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT = 1,
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE = 2,
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER = 3,
// Provided by VK_VERSION_1_2, VK_KHR_sampler_mirror_clamp_to_edge
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE = 4,
// Provided by VK_KHR_sampler_mirror_clamp_to_edge
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE_KHR = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE,
} VkSamplerAddressMode;
-
VK_SAMPLER_ADDRESS_MODE_REPEATspecifies that the repeat wrap mode will be used. -
VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEATspecifies that the mirrored repeat wrap mode will be used. -
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGEspecifies that the clamp to edge wrap mode will be used. -
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDERspecifies that the clamp to border wrap mode will be used. -
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGEspecifies that the mirror clamp to edge wrap mode will be used. This is only valid ifsamplerMirrorClampToEdgeis enabled, or if theVK_KHR_sampler_mirror_clamp_to_edgeextension is enabled.
Comparison operators compare a reference and a test value, and return a true (“passed”) or false (“failed”) value depending on the comparison operator chosen. The supported operators are:
// Provided by VK_VERSION_1_0
typedef enum VkCompareOp {
VK_COMPARE_OP_NEVER = 0,
VK_COMPARE_OP_LESS = 1,
VK_COMPARE_OP_EQUAL = 2,
VK_COMPARE_OP_LESS_OR_EQUAL = 3,
VK_COMPARE_OP_GREATER = 4,
VK_COMPARE_OP_NOT_EQUAL = 5,
VK_COMPARE_OP_GREATER_OR_EQUAL = 6,
VK_COMPARE_OP_ALWAYS = 7,
} VkCompareOp;
-
VK_COMPARE_OP_NEVERspecifies that the comparison always evaluates false. -
VK_COMPARE_OP_LESSspecifies that the comparison evaluates reference < test. -
VK_COMPARE_OP_EQUALspecifies that the comparison evaluates reference = test. -
VK_COMPARE_OP_LESS_OR_EQUALspecifies that the comparison evaluates reference ≤ test. -
VK_COMPARE_OP_GREATERspecifies that the comparison evaluates reference > test. -
VK_COMPARE_OP_NOT_EQUALspecifies that the comparison evaluates reference ≠ test. -
VK_COMPARE_OP_GREATER_OR_EQUALspecifies that the comparison evaluates reference ≥ test. -
VK_COMPARE_OP_ALWAYSspecifies that the comparison always evaluates true.
Comparison operators are used for:
-
The Depth Compare Operation operator for a sampler, specified by VkSamplerCreateInfo::
compareOp. -
The stencil comparison operator for the stencil test, specified by vkCmdSetStencilOp::
compareOpor VkStencilOpState::compareOp. -
The Depth Comparison operator for the depth test, specified by vkCmdSetDepthCompareOp::
depthCompareOpor VkPipelineDepthStencilStateCreateInfo::depthCompareOp.
Each such use describes how the reference and test values for that comparison are determined.
Possible values of VkSamplerCreateInfo::borderColor, specifying
the border color used for texture lookups, are:
// Provided by VK_VERSION_1_0
typedef enum VkBorderColor {
VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK = 0,
VK_BORDER_COLOR_INT_TRANSPARENT_BLACK = 1,
VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK = 2,
VK_BORDER_COLOR_INT_OPAQUE_BLACK = 3,
VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE = 4,
VK_BORDER_COLOR_INT_OPAQUE_WHITE = 5,
// Provided by VK_EXT_custom_border_color
VK_BORDER_COLOR_FLOAT_CUSTOM_EXT = 1000287003,
// Provided by VK_EXT_custom_border_color
VK_BORDER_COLOR_INT_CUSTOM_EXT = 1000287004,
} VkBorderColor;
-
VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACKspecifies a transparent, floating-point format, black color. -
VK_BORDER_COLOR_INT_TRANSPARENT_BLACKspecifies a transparent, integer format, black color. -
VK_BORDER_COLOR_FLOAT_OPAQUE_BLACKspecifies an opaque, floating-point format, black color. -
VK_BORDER_COLOR_INT_OPAQUE_BLACKspecifies an opaque, integer format, black color. -
VK_BORDER_COLOR_FLOAT_OPAQUE_WHITEspecifies an opaque, floating-point format, white color. -
VK_BORDER_COLOR_INT_OPAQUE_WHITEspecifies an opaque, integer format, white color. -
VK_BORDER_COLOR_FLOAT_CUSTOM_EXTindicates that a VkSamplerCustomBorderColorCreateInfoEXT structure is included in the VkSamplerCreateInfo::pNextchain containing the color data in floating-point format. -
VK_BORDER_COLOR_INT_CUSTOM_EXTindicates that a VkSamplerCustomBorderColorCreateInfoEXT structure is included in the VkSamplerCreateInfo::pNextchain containing the color data in integer format.
These colors are described in detail in Texel Replacement.
To destroy a sampler, call:
// Provided by VK_VERSION_1_0
void vkDestroySampler(
VkDevice device,
VkSampler sampler,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the sampler. -
sampleris the sampler to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
13.1. Sampler Y′CBCR conversion
To create a sampler with Y′CBCR conversion enabled, add a
VkSamplerYcbcrConversionInfo structure to the pNext chain of the
VkSamplerCreateInfo structure.
To create a sampler Y′CBCR conversion, the
samplerYcbcrConversion feature
must be enabled.
Conversion must be fixed at pipeline creation time, through use of a
combined image sampler with an immutable sampler in
VkDescriptorSetLayoutBinding.
A VkSamplerYcbcrConversionInfo must be provided for samplers to be
used with image views that access VK_IMAGE_ASPECT_COLOR_BIT if the
format is one of the formats
that require a sampler Y′CBCR conversion
, or if the image view has an
external format
.
The VkSamplerYcbcrConversionInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkSamplerYcbcrConversionInfo {
VkStructureType sType;
const void* pNext;
VkSamplerYcbcrConversion conversion;
} VkSamplerYcbcrConversionInfo;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkSamplerYcbcrConversionInfo VkSamplerYcbcrConversionInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
conversionis a VkSamplerYcbcrConversion handle created with vkCreateSamplerYcbcrConversion.
A sampler Y′CBCR conversion is an opaque representation of a
device-specific sampler Y′CBCR conversion description, represented as a
VkSamplerYcbcrConversion handle:
// Provided by VK_VERSION_1_1
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSamplerYcbcrConversion)
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkSamplerYcbcrConversion VkSamplerYcbcrConversionKHR;
To create a VkSamplerYcbcrConversion, call:
// Provided by VK_VERSION_1_1
VkResult vkCreateSamplerYcbcrConversion(
VkDevice device,
const VkSamplerYcbcrConversionCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSamplerYcbcrConversion* pYcbcrConversion);
or the equivalent command
// Provided by VK_KHR_sampler_ycbcr_conversion
VkResult vkCreateSamplerYcbcrConversionKHR(
VkDevice device,
const VkSamplerYcbcrConversionCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSamplerYcbcrConversion* pYcbcrConversion);
-
deviceis the logical device that creates the sampler Y′CBCR conversion. -
pCreateInfois a pointer to a VkSamplerYcbcrConversionCreateInfo structure specifying the requested sampler Y′CBCR conversion. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pYcbcrConversionis a pointer to a VkSamplerYcbcrConversion handle in which the resulting sampler Y′CBCR conversion is returned.
The interpretation of the configured sampler Y′CBCR conversion is described in more detail in the description of sampler Y′CBCR conversion in the Image Operations chapter.
The VkSamplerYcbcrConversionCreateInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkSamplerYcbcrConversionCreateInfo {
VkStructureType sType;
const void* pNext;
VkFormat format;
VkSamplerYcbcrModelConversion ycbcrModel;
VkSamplerYcbcrRange ycbcrRange;
VkComponentMapping components;
VkChromaLocation xChromaOffset;
VkChromaLocation yChromaOffset;
VkFilter chromaFilter;
VkBool32 forceExplicitReconstruction;
} VkSamplerYcbcrConversionCreateInfo;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkSamplerYcbcrConversionCreateInfo VkSamplerYcbcrConversionCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatis the format of the image from which color information will be retrieved. -
ycbcrModeldescribes the color matrix for conversion between color models. -
ycbcrRangedescribes whether the encoded values have headroom and foot room, or whether the encoding uses the full numerical range. -
componentsapplies a swizzle based on VkComponentSwizzle enums prior to range expansion and color model conversion. -
xChromaOffsetdescribes the sample location associated with downsampled chroma components in the x dimension.xChromaOffsethas no effect for formats in which chroma components are not downsampled horizontally. -
yChromaOffsetdescribes the sample location associated with downsampled chroma components in the y dimension.yChromaOffsethas no effect for formats in which the chroma components are not downsampled vertically. -
chromaFilteris the filter for chroma reconstruction. -
forceExplicitReconstructioncan be used to ensure that reconstruction is done explicitly, if supported.
|
Note
Setting If |
If the pNext chain includes a VkExternalFormatANDROID structure
with non-zero externalFormat member, the sampler Y′CBCR conversion
object represents an external format conversion, and format must be
VK_FORMAT_UNDEFINED.
Such conversions must only be used to sample image views with a matching
external
format.
When creating an external format conversion, the value of components
is ignored.
If chromaFilter is VK_FILTER_NEAREST, chroma samples are
reconstructed to luma component resolution using nearest-neighbour sampling.
Otherwise, chroma samples are reconstructed using interpolation.
More details can be found in the
description of sampler Y′CBCR conversion in the Image
Operations chapter.
VkSamplerYcbcrModelConversion defines the conversion from the source color model to the shader color model. Possible values are:
// Provided by VK_VERSION_1_1
typedef enum VkSamplerYcbcrModelConversion {
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY = 0,
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY = 1,
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 = 2,
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 = 3,
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 = 4,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020,
} VkSamplerYcbcrModelConversion;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkSamplerYcbcrModelConversion VkSamplerYcbcrModelConversionKHR;
-
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITYspecifies that the input values to the conversion are unmodified. -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITYspecifies no model conversion but the inputs are range expanded as for Y′CBCR. -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709specifies the color model conversion from Y′CBCR to R′G′B′ defined in BT.709 and described in the “BT.709 Y′CBCR conversion” section of the Khronos Data Format Specification. -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601specifies the color model conversion from Y′CBCR to R′G′B′ defined in BT.601 and described in the “BT.601 Y′CBCR conversion” section of the Khronos Data Format Specification. -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020specifies the color model conversion from Y′CBCR to R′G′B′ defined in BT.2020 and described in the “BT.2020 Y′CBCR conversion” section of the Khronos Data Format Specification.
In the VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_* color models, for the
input to the sampler Y′CBCR range expansion and model conversion:
-
the Y (Y′ luma) component corresponds to the G component of an RGB image.
-
the CB (CB or “U” blue color difference) component corresponds to the B component of an RGB image.
-
the CR (CR or “V” red color difference) component corresponds to the R component of an RGB image.
-
the alpha component, if present, is not modified by color model conversion.
These rules reflect the mapping of components after the component swizzle
operation (controlled by
VkSamplerYcbcrConversionCreateInfo::components).
|
Note
For example, an “YUVA” 32-bit format comprising four 8-bit components can
be implemented as
|
The VkSamplerYcbcrRange enum describes whether color components are encoded using the full range of numerical values or whether values are reserved for headroom and foot room. VkSamplerYcbcrRange is defined as:
// Provided by VK_VERSION_1_1
typedef enum VkSamplerYcbcrRange {
VK_SAMPLER_YCBCR_RANGE_ITU_FULL = 0,
VK_SAMPLER_YCBCR_RANGE_ITU_NARROW = 1,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_SAMPLER_YCBCR_RANGE_ITU_FULL_KHR = VK_SAMPLER_YCBCR_RANGE_ITU_FULL,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_SAMPLER_YCBCR_RANGE_ITU_NARROW_KHR = VK_SAMPLER_YCBCR_RANGE_ITU_NARROW,
} VkSamplerYcbcrRange;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkSamplerYcbcrRange VkSamplerYcbcrRangeKHR;
-
VK_SAMPLER_YCBCR_RANGE_ITU_FULLspecifies that the full range of the encoded values are valid and interpreted according to the ITU “full range” quantization rules. -
VK_SAMPLER_YCBCR_RANGE_ITU_NARROWspecifies that headroom and foot room are reserved in the numerical range of encoded values, and the remaining values are expanded according to the ITU “narrow range” quantization rules.
The formulae for these conversions is described in the Sampler Y′CBCR Range Expansion section of the Image Operations chapter.
No range modification takes place if ycbcrModel is
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY; the ycbcrRange
field of VkSamplerYcbcrConversionCreateInfo is ignored in this case.
The VkChromaLocation enum defines the location of downsampled chroma component samples relative to the luma samples, and is defined as:
// Provided by VK_VERSION_1_1
typedef enum VkChromaLocation {
VK_CHROMA_LOCATION_COSITED_EVEN = 0,
VK_CHROMA_LOCATION_MIDPOINT = 1,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_CHROMA_LOCATION_COSITED_EVEN_KHR = VK_CHROMA_LOCATION_COSITED_EVEN,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_CHROMA_LOCATION_MIDPOINT_KHR = VK_CHROMA_LOCATION_MIDPOINT,
} VkChromaLocation;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkChromaLocation VkChromaLocationKHR;
-
VK_CHROMA_LOCATION_COSITED_EVENspecifies that downsampled chroma samples are aligned with luma samples with even coordinates. -
VK_CHROMA_LOCATION_MIDPOINTspecifies that downsampled chroma samples are located half way between each even luma sample and the nearest higher odd luma sample.
To destroy a sampler Y′CBCR conversion, call:
// Provided by VK_VERSION_1_1
void vkDestroySamplerYcbcrConversion(
VkDevice device,
VkSamplerYcbcrConversion ycbcrConversion,
const VkAllocationCallbacks* pAllocator);
or the equivalent command
// Provided by VK_KHR_sampler_ycbcr_conversion
void vkDestroySamplerYcbcrConversionKHR(
VkDevice device,
VkSamplerYcbcrConversion ycbcrConversion,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the Y′CBCR conversion. -
ycbcrConversionis the conversion to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
In addition to the predefined border color values, applications can provide
a custom border color value by including the
VkSamplerCustomBorderColorCreateInfoEXT structure in the
VkSamplerCreateInfo::pNext chain.
The VkSamplerCustomBorderColorCreateInfoEXT structure is defined as:
// Provided by VK_EXT_custom_border_color
typedef struct VkSamplerCustomBorderColorCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkClearColorValue customBorderColor;
VkFormat format;
} VkSamplerCustomBorderColorCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
customBorderColoris a VkClearColorValue representing the desired custom sampler border color. -
formatis a VkFormat representing the format of the sampled image view(s). This field may beVK_FORMAT_UNDEFINEDif thecustomBorderColorWithoutFormatfeature is enabled.
If the sampler is created with VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK,
VK_BORDER_COLOR_INT_OPAQUE_BLACK,
VK_BORDER_COLOR_FLOAT_CUSTOM_EXT, or
VK_BORDER_COLOR_INT_CUSTOM_EXT borderColor, and that sampler
will be combined with an image view that does not have an
identity swizzle, and
VkPhysicalDeviceBorderColorSwizzleFeaturesEXT::borderColorSwizzleFromImage
is not enabled, then it is necessary to specify the component mapping of the
border color, by including the
VkSamplerBorderColorComponentMappingCreateInfoEXT structure in the
VkSamplerCreateInfo::pNext chain, to get defined results.
The VkSamplerBorderColorComponentMappingCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_border_color_swizzle
typedef struct VkSamplerBorderColorComponentMappingCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkComponentMapping components;
VkBool32 srgb;
} VkSamplerBorderColorComponentMappingCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
componentsis a VkComponentMapping structure specifying a remapping of the border color components. -
srgbindicates that the sampler will be combined with an image view that has an image format which is sRGB encoded.
The VkComponentMapping components member describes a remapping
from components of the border color to components of the vector returned by
shader image instructions when the border color is used.
14. Resource Descriptors
A descriptor is an opaque data structure representing a shader resource
such as a buffer, buffer view, image view, sampler, or combined image
sampler.
Descriptors are organized into descriptor sets, which are bound during
command recording for use in subsequent drawing commands.
The arrangement of content in each descriptor set is determined by a
descriptor set layout, which determines what descriptors can be stored
within it.
The sequence of descriptor set layouts that can be used by a pipeline is
specified in a pipeline layout.
Each pipeline object can use up to maxBoundDescriptorSets (see
Limits) descriptor sets.
Shaders access resources via variables decorated with a descriptor set and binding number that link them to a descriptor in a descriptor set. The shader interface mapping to bound descriptor sets is described in the Shader Resource Interface section.
Shaders can also access buffers without going through descriptors by using Physical Storage Buffer Access to access them through 64-bit addresses.
14.1. Descriptor Types
There are a number of different types of descriptor supported by Vulkan, corresponding to different resources or usage. The following sections describe the API definitions of each descriptor type. The mapping of each type to SPIR-V is listed in the Shader Resource and Descriptor Type Correspondence and Shader Resource and Storage Class Correspondence tables in the Shader Interfaces chapter.
14.1.1. Storage Image
A storage image (VK_DESCRIPTOR_TYPE_STORAGE_IMAGE) is a descriptor
type associated with an image resource via an
image view that load, store, and atomic
operations can be performed on.
Storage image loads are supported in all shader stages for image views whose
format features contain
VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT.
Stores to storage images are supported in compute shaders for image views
whose format features contain
VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT.
Atomic operations on storage images are supported in compute shaders for
image views whose format features
contain
VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT.
When the fragmentStoresAndAtomics feature is enabled, stores and atomic
operations are also supported for storage images in fragment shaders with
the same set of image formats as supported in compute shaders.
When the vertexPipelineStoresAndAtomics feature is enabled, stores and atomic
operations are also supported in vertex, tessellation, and geometry shaders
with the same set of image formats as supported in compute shaders.
The image subresources for a storage image must be in the
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or
VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a
shader.
14.1.2. Sampler
A sampler descriptor (VK_DESCRIPTOR_TYPE_SAMPLER) is a descriptor
type associated with a sampler object, used to control the
behavior of sampling operations performed on a
sampled image.
14.1.3. Sampled Image
A sampled image (VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE) is a descriptor
type associated with an image resource via an
image view that sampling operations
can be performed on.
Shaders combine a sampled image variable and a sampler variable to perform sampling operations.
Sampled images are supported in all shader stages for image views whose
format features contain
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT.
An image subresources for a sampled image must be in one of the following layouts:
-
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_GENERAL -
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
14.1.4. Combined Image Sampler
A combined image sampler (VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER)
is a single descriptor type associated with both a sampler and
an image resource, combining both a
sampler and sampled image descriptor into a single descriptor.
If the descriptor refers to a sampler that performs Y′CBCR conversion or samples a subsampled image, the sampler must only be used to sample the image in the same descriptor. Otherwise, the sampler and image in this type of descriptor can be used freely with any other samplers and images.
An image subresources for a combined image sampler must be in one of the following layouts:
-
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_GENERAL -
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
|
Note
On some implementations, it may be more efficient to sample from an image using a combination of sampler and sampled image that are stored together in the descriptor set in a combined descriptor. |
14.1.5. Uniform Texel Buffer
A uniform texel buffer (VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER) is
a descriptor type associated with a buffer resource
via a buffer view that image sampling
operations can be performed on.
Uniform texel buffers define a tightly-packed 1-dimensional linear array of texels, with texels going through format conversion when read in a shader in the same way as they are for an image.
Load operations from uniform texel buffers are supported in all shader
stages for image formats which report support for the
VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT
feature bit via vkGetPhysicalDeviceFormatProperties in
VkFormatProperties::bufferFeatures.
14.1.6. Storage Texel Buffer
A storage texel buffer (VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER) is
a descriptor type associated with a buffer resource
via a buffer view that image load,
store, and atomic operations can be performed on.
Storage texel buffers define a tightly-packed 1-dimensional linear array of texels, with texels going through format conversion when read in a shader in the same way as they are for an image. Unlike uniform texel buffers, these buffers can also be written to in the same way as for storage images.
Storage texel buffer loads are supported in all shader stages for texel
buffer formats which report support for the
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT
feature bit via vkGetPhysicalDeviceFormatProperties in
VkFormatProperties::bufferFeatures.
Stores to storage texel buffers are supported in compute shaders for texel
buffer formats which report support for the
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT feature via
vkGetPhysicalDeviceFormatProperties in
VkFormatProperties::bufferFeatures.
Atomic operations on storage texel buffers are supported in compute shaders
for texel buffer formats which report support for the
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT
feature via vkGetPhysicalDeviceFormatProperties in
VkFormatProperties::bufferFeatures.
When the fragmentStoresAndAtomics feature is enabled, stores and atomic
operations are also supported for storage texel buffers in fragment shaders
with the same set of texel buffer formats as supported in compute shaders.
When the vertexPipelineStoresAndAtomics feature is enabled, stores and atomic
operations are also supported in vertex, tessellation, and geometry shaders
with the same set of texel buffer formats as supported in compute shaders.
14.1.7. Storage Buffer
A storage buffer (VK_DESCRIPTOR_TYPE_STORAGE_BUFFER) is a descriptor
type associated with a buffer resource directly,
described in a shader as a structure with various members that load, store,
and atomic operations can be performed on.
|
Note
Atomic operations can only be performed on members of certain types as defined in the SPIR-V environment appendix. |
14.1.8. Uniform Buffer
A uniform buffer (VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER) is a descriptor
type associated with a buffer resource directly,
described in a shader as a structure with various members that load
operations can be performed on.
14.1.9. Dynamic Uniform Buffer
A dynamic uniform buffer (VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC)
is almost identical to a uniform buffer,
and differs only in how the offset into the buffer is specified.
The base offset calculated by the VkDescriptorBufferInfo when
initially updating the descriptor set is added
to a dynamic offset when binding
the descriptor set.
14.1.10. Dynamic Storage Buffer
A dynamic storage buffer (VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC)
is almost identical to a storage buffer,
and differs only in how the offset into the buffer is specified.
The base offset calculated by the VkDescriptorBufferInfo when
initially updating the descriptor set is added
to a dynamic offset when binding
the descriptor set.
14.1.11. Inline Uniform Block
An inline uniform block (VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK) is
almost identical to a uniform buffer, and
differs only in taking its storage directly from the encompassing descriptor
set instead of being backed by buffer memory.
It is typically used to access a small set of constant data that does not
require the additional flexibility provided by the indirection enabled when
using a uniform buffer where the descriptor and the referenced buffer memory
are decoupled.
Compared to push constants, they allow reusing the same set of constant data
across multiple disjoint sets of drawing and dispatching commands.
Inline uniform block descriptors cannot be aggregated into arrays. Instead, the array size specified for an inline uniform block descriptor binding specifies the binding’s capacity in bytes.
14.1.12. Input Attachment
An input attachment (VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT) is a
descriptor type associated with an image resource via
an image view that can be used for
framebuffer local load operations in
fragment shaders.
All image formats that are supported for color attachments
(VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT
or VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV
)
or depth/stencil attachments
(VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT) for a given image
tiling mode are also supported for input attachments.
An image view used as an input attachment must be in one of the following layouts:
-
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_GENERAL -
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
14.1.13. Acceleration Structure
An acceleration structure (
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR
or
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV
) is a descriptor type that is used to retrieve scene geometry from within
shaders that are used for ray traversal.
Shaders have read-only access to the memory.
14.1.14. Mutable
A descriptor of mutable (VK_DESCRIPTOR_TYPE_MUTABLE_VALVE) type
indicates that this descriptor can mutate to any of the descriptor types
given in the
VkMutableDescriptorTypeCreateInfoVALVE::pDescriptorTypes list of
descriptor types in the pNext chain of
VkDescriptorSetLayoutCreateInfo for this binding.
At any point, each individual descriptor of mutable type has an active
descriptor type.
The active descriptor type can be any one of the declared types in
pDescriptorTypes.
Additionally, a mutable descriptor’s active descriptor type can be of the
VK_DESCRIPTOR_TYPE_MUTABLE_VALVE type, which is the initial active
descriptor type.
The active descriptor type can change when the descriptor is updated.
When a descriptor is consumed by binding a descriptor set, the active
descriptor type is considered, not VK_DESCRIPTOR_TYPE_MUTABLE_VALVE.
An active descriptor type of VK_DESCRIPTOR_TYPE_MUTABLE_VALVE is
considered an undefined descriptor.
If a descriptor is consumed where the active descriptor type does not match
what the shader expects, the descriptor is considered an undefined
descriptor.
|
Note
To find which descriptor types are supported as
|
|
Note
The intention of a mutable descriptor type is that implementations allocate N bytes per descriptor, where N is determined by the maximum descriptor size for a given descriptor binding. Implementations are not expected to keep track of the active descriptor type, and it should be considered a C-like union type. A mutable descriptor type is not considered as efficient in terms of runtime performance as using a non-mutable descriptor type, and applications are not encouraged to use them outside API layering efforts. Mutable descriptor types can be more efficient if the alternative is using many different descriptors to emulate mutable descriptor types. |
14.2. Descriptor Sets
Descriptors are grouped together into descriptor set objects. A descriptor set object is an opaque object containing storage for a set of descriptors, where the types and number of descriptors is defined by a descriptor set layout. The layout object may be used to define the association of each descriptor binding with memory or other implementation resources. The layout is used both for determining the resources that need to be associated with the descriptor set, and determining the interface between shader stages and shader resources.
14.2.1. Descriptor Set Layout
A descriptor set layout object is defined by an array of zero or more descriptor bindings. Each individual descriptor binding is specified by a descriptor type, a count (array size) of the number of descriptors in the binding, a set of shader stages that can access the binding, and (if using immutable samplers) an array of sampler descriptors.
Descriptor set layout objects are represented by VkDescriptorSetLayout
handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDescriptorSetLayout)
To create descriptor set layout objects, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateDescriptorSetLayout(
VkDevice device,
const VkDescriptorSetLayoutCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDescriptorSetLayout* pSetLayout);
-
deviceis the logical device that creates the descriptor set layout. -
pCreateInfois a pointer to a VkDescriptorSetLayoutCreateInfo structure specifying the state of the descriptor set layout object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pSetLayoutis a pointer to a VkDescriptorSetLayout handle in which the resulting descriptor set layout object is returned.
Information about the descriptor set layout is passed in a
VkDescriptorSetLayoutCreateInfo structure:
// Provided by VK_VERSION_1_0
typedef struct VkDescriptorSetLayoutCreateInfo {
VkStructureType sType;
const void* pNext;
VkDescriptorSetLayoutCreateFlags flags;
uint32_t bindingCount;
const VkDescriptorSetLayoutBinding* pBindings;
} VkDescriptorSetLayoutCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkDescriptorSetLayoutCreateFlagBits specifying options for descriptor set layout creation. -
bindingCountis the number of elements inpBindings. -
pBindingsis a pointer to an array of VkDescriptorSetLayoutBinding structures.
Information about the possible descriptor types for mutable descriptor types
is passed in a VkMutableDescriptorTypeCreateInfoVALVE structure as a
pNext to a VkDescriptorSetLayoutCreateInfo structure or a
VkDescriptorPoolCreateInfo structure.
The VkMutableDescriptorTypeCreateInfoVALVE structure is defined as:
// Provided by VK_VALVE_mutable_descriptor_type
typedef struct VkMutableDescriptorTypeCreateInfoVALVE {
VkStructureType sType;
const void* pNext;
uint32_t mutableDescriptorTypeListCount;
const VkMutableDescriptorTypeListVALVE* pMutableDescriptorTypeLists;
} VkMutableDescriptorTypeCreateInfoVALVE;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
mutableDescriptorTypeListCountis the number of elements inpMutableDescriptorTypeLists. -
pMutableDescriptorTypeListsis a pointer to an array ofVkMutableDescriptorTypeListVALVEstructures.
If mutableDescriptorTypeListCount is zero or if this structure is not
included in the pNext chain, the
VkMutableDescriptorTypeListVALVE for each element is considered to be
zero or NULL for each member.
Otherwise, the descriptor set layout binding at
VkDescriptorSetLayoutCreateInfo::pBindings[i] uses the
descriptor type lists in
VkMutableDescriptorTypeCreateInfoVALVE::pMutableDescriptorTypeLists[i].
The list of potential descriptor types a given mutable descriptor can
mutate to is passed in a VkMutableDescriptorTypeListVALVE structure.
The VkMutableDescriptorTypeListVALVE structure is defined as:
// Provided by VK_VALVE_mutable_descriptor_type
typedef struct VkMutableDescriptorTypeListVALVE {
uint32_t descriptorTypeCount;
const VkDescriptorType* pDescriptorTypes;
} VkMutableDescriptorTypeListVALVE;
-
descriptorTypeCountis the number of elements inpDescriptorTypes. -
pDescriptorTypesisNULLor a pointer to an array ofdescriptorTypeCountVkDescriptorType values defining which descriptor types a given binding may mutate to.
Bits which can be set in
VkDescriptorSetLayoutCreateInfo::flags, specifying options for
descriptor set layout, are:
// Provided by VK_VERSION_1_0
typedef enum VkDescriptorSetLayoutCreateFlagBits {
// Provided by VK_VERSION_1_2
VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT = 0x00000002,
// Provided by VK_KHR_push_descriptor
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR = 0x00000001,
// Provided by VK_VALVE_mutable_descriptor_type
VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE = 0x00000004,
// Provided by VK_EXT_descriptor_indexing
VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT = VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT,
} VkDescriptorSetLayoutCreateFlagBits;
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHRspecifies that descriptor sets must not be allocated using this layout, and descriptors are instead pushed by vkCmdPushDescriptorSetKHR. -
VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITspecifies that descriptor sets using this layout must be allocated from a descriptor pool created with theVK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BITbit set. Descriptor set layouts created with this bit set have alternate limits for the maximum number of descriptors per-stage and per-pipeline layout. The non-UpdateAfterBind limits only count descriptors in sets created without this flag. The UpdateAfterBind limits count all descriptors, but the limits may be higher than the non-UpdateAfterBind limits. -
VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVEspecifies that descriptor sets using this layout must be allocated from a descriptor pool created with theVK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVEbit set. Descriptor set layouts created with this bit have no expressable limit for maximum number of descriptors per-stage. Host descriptor sets are limited only by available host memory, but may be limited for implementation specific reasons. Implementations may limit the number of supported descriptors to UpdateAfterBind limits or non-UpdateAfterBind limits, whichever is larger.
// Provided by VK_VERSION_1_0
typedef VkFlags VkDescriptorSetLayoutCreateFlags;
VkDescriptorSetLayoutCreateFlags is a bitmask type for setting a mask
of zero or more VkDescriptorSetLayoutCreateFlagBits.
The VkDescriptorSetLayoutBinding structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkDescriptorSetLayoutBinding {
uint32_t binding;
VkDescriptorType descriptorType;
uint32_t descriptorCount;
VkShaderStageFlags stageFlags;
const VkSampler* pImmutableSamplers;
} VkDescriptorSetLayoutBinding;
-
bindingis the binding number of this entry and corresponds to a resource of the same binding number in the shader stages. -
descriptorTypeis a VkDescriptorType specifying which type of resource descriptors are used for this binding. -
descriptorCountis the number of descriptors contained in the binding, accessed in a shader as an array, except ifdescriptorTypeisVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKin which casedescriptorCountis the size in bytes of the inline uniform block. IfdescriptorCountis zero this binding entry is reserved and the resource must not be accessed from any stage via this binding within any pipeline using the set layout. -
stageFlagsmember is a bitmask of VkShaderStageFlagBits specifying which pipeline shader stages can access a resource for this binding.VK_SHADER_STAGE_ALLis a shorthand specifying that all defined shader stages, including any additional stages defined by extensions, can access the resource.If a shader stage is not included in
stageFlags, then a resource must not be accessed from that stage via this binding within any pipeline using the set layout. Other than input attachments which are limited to the fragment shader, there are no limitations on what combinations of stages can use a descriptor binding, and in particular a binding can be used by both graphics stages and the compute stage. -
pImmutableSamplersaffects initialization of samplers. IfdescriptorTypespecifies aVK_DESCRIPTOR_TYPE_SAMPLERorVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERtype descriptor, thenpImmutableSamplerscan be used to initialize a set of immutable samplers. Immutable samplers are permanently bound into the set layout and must not be changed; updating aVK_DESCRIPTOR_TYPE_SAMPLERdescriptor with immutable samplers is not allowed and updates to aVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERdescriptor with immutable samplers does not modify the samplers (the image views are updated, but the sampler updates are ignored). IfpImmutableSamplersis notNULL, then it is a pointer to an array of sampler handles that will be copied into the set layout and used for the corresponding binding. Only the sampler handles are copied; the sampler objects must not be destroyed before the final use of the set layout and any descriptor pools and sets created using it. IfpImmutableSamplersisNULL, then the sampler slots are dynamic and sampler handles must be bound into descriptor sets using this layout. IfdescriptorTypeis not one of these descriptor types, thenpImmutableSamplersis ignored.
The above layout definition allows the descriptor bindings to be specified
sparsely such that not all binding numbers between 0 and the maximum binding
number need to be specified in the pBindings array.
Bindings that are not specified have a descriptorCount and
stageFlags of zero, and the value of descriptorType is
undefined.
However, all binding numbers between 0 and the maximum binding number in the
VkDescriptorSetLayoutCreateInfo::pBindings array may consume
memory in the descriptor set layout even if not all descriptor bindings are
used, though it should not consume additional memory from the descriptor
pool.
|
Note
The maximum binding number specified should be as compact as possible to avoid wasted memory. |
If the pNext chain of a VkDescriptorSetLayoutCreateInfo
structure includes a VkDescriptorSetLayoutBindingFlagsCreateInfo
structure, then that structure includes an array of flags, one for each
descriptor set layout binding.
The VkDescriptorSetLayoutBindingFlagsCreateInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkDescriptorSetLayoutBindingFlagsCreateInfo {
VkStructureType sType;
const void* pNext;
uint32_t bindingCount;
const VkDescriptorBindingFlags* pBindingFlags;
} VkDescriptorSetLayoutBindingFlagsCreateInfo;
or the equivalent
// Provided by VK_EXT_descriptor_indexing
typedef VkDescriptorSetLayoutBindingFlagsCreateInfo VkDescriptorSetLayoutBindingFlagsCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bindingCountis zero or the number of elements inpBindingFlags. -
pBindingFlagsis a pointer to an array of VkDescriptorBindingFlags bitfields, one for each descriptor set layout binding.
If bindingCount is zero or if this structure is not included in the
pNext chain, the VkDescriptorBindingFlags for each descriptor
set layout binding is considered to be zero.
Otherwise, the descriptor set layout binding at
VkDescriptorSetLayoutCreateInfo::pBindings[i] uses the flags in
pBindingFlags[i].
Bits which can be set in each element of
VkDescriptorSetLayoutBindingFlagsCreateInfo::pBindingFlags,
specifying options for the corresponding descriptor set layout binding, are:
// Provided by VK_VERSION_1_2
typedef enum VkDescriptorBindingFlagBits {
VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT = 0x00000001,
VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT = 0x00000002,
VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT = 0x00000004,
VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT = 0x00000008,
// Provided by VK_EXT_descriptor_indexing
VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT = VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT,
// Provided by VK_EXT_descriptor_indexing
VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT = VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT,
// Provided by VK_EXT_descriptor_indexing
VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT = VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT,
// Provided by VK_EXT_descriptor_indexing
VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT_EXT = VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT,
} VkDescriptorBindingFlagBits;
or the equivalent
// Provided by VK_EXT_descriptor_indexing
typedef VkDescriptorBindingFlagBits VkDescriptorBindingFlagBitsEXT;
-
VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITindicates that if descriptors in this binding are updated between when the descriptor set is bound in a command buffer and when that command buffer is submitted to a queue, then the submission will use the most recently set descriptors for this binding and the updates do not invalidate the command buffer. Descriptor bindings created with this flag are also partially exempt from the external synchronization requirement in vkUpdateDescriptorSetWithTemplateKHR and vkUpdateDescriptorSets. Multiple descriptors with this flag set can be updated concurrently in different threads, though the same descriptor must not be updated concurrently by two threads. Descriptors with this flag set can be updated concurrently with the set being bound to a command buffer in another thread, but not concurrently with the set being reset or freed. -
VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BITindicates that descriptors in this binding that are not dynamically used need not contain valid descriptors at the time the descriptors are consumed. A descriptor is dynamically used if any shader invocation executes an instruction that performs any memory access using the descriptor. If a descriptor is not dynamically used, any resource referenced by the descriptor is not considered to be referenced during command execution. -
VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BITindicates that descriptors in this binding can be updated after a command buffer has bound this descriptor set, or while a command buffer that uses this descriptor set is pending execution, as long as the descriptors that are updated are not used by those command buffers. IfVK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BITis also set, then descriptors can be updated as long as they are not dynamically used by any shader invocations. IfVK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BITis not set, then descriptors can be updated as long as they are not statically used by any shader invocations. -
VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BITindicates that this is a variable-sized descriptor binding whose size will be specified when a descriptor set is allocated using this layout. The value ofdescriptorCountis treated as an upper bound on the size of the binding. This must only be used for the last binding in the descriptor set layout (i.e. the binding with the largest value ofbinding). For the purposes of counting against limits such asmaxDescriptorSet* andmaxPerStageDescriptor*, the full value ofdescriptorCountis counted, except for descriptor bindings with a descriptor type ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK. In this case,descriptorCountspecifies the upper bound on the byte size of the binding; thus it counts against themaxInlineUniformBlockSizeandmaxInlineUniformTotalSizelimits instead.
|
Note
Note that while |
// Provided by VK_VERSION_1_2
typedef VkFlags VkDescriptorBindingFlags;
or the equivalent
// Provided by VK_EXT_descriptor_indexing
typedef VkDescriptorBindingFlags VkDescriptorBindingFlagsEXT;
VkDescriptorBindingFlags is a bitmask type for setting a mask of zero
or more VkDescriptorBindingFlagBits.
To query information about whether a descriptor set layout can be created, call:
// Provided by VK_VERSION_1_1
void vkGetDescriptorSetLayoutSupport(
VkDevice device,
const VkDescriptorSetLayoutCreateInfo* pCreateInfo,
VkDescriptorSetLayoutSupport* pSupport);
or the equivalent command
// Provided by VK_KHR_maintenance3
void vkGetDescriptorSetLayoutSupportKHR(
VkDevice device,
const VkDescriptorSetLayoutCreateInfo* pCreateInfo,
VkDescriptorSetLayoutSupport* pSupport);
-
deviceis the logical device that would create the descriptor set layout. -
pCreateInfois a pointer to a VkDescriptorSetLayoutCreateInfo structure specifying the state of the descriptor set layout object. -
pSupportis a pointer to a VkDescriptorSetLayoutSupport structure, in which information about support for the descriptor set layout object is returned.
Some implementations have limitations on what fits in a descriptor set which
are not easily expressible in terms of existing limits like
maxDescriptorSet*, for example if all descriptor types share a limited
space in memory but each descriptor is a different size or alignment.
This command returns information about whether a descriptor set satisfies
this limit.
If the descriptor set layout satisfies the
VkPhysicalDeviceMaintenance3Properties::maxPerSetDescriptors
limit, this command is guaranteed to return VK_TRUE in
VkDescriptorSetLayoutSupport::supported.
If the descriptor set layout exceeds the
VkPhysicalDeviceMaintenance3Properties::maxPerSetDescriptors
limit, whether the descriptor set layout is supported is
implementation-dependent and may depend on whether the descriptor sizes and
alignments cause the layout to exceed an internal limit.
This command does not consider other limits such as
maxPerStageDescriptor*, and so a descriptor set layout that is
supported according to this command must still satisfy the pipeline layout
limits such as maxPerStageDescriptor* in order to be used in a
pipeline layout.
|
Note
This is a |
Information about support for the descriptor set layout is returned in a
VkDescriptorSetLayoutSupport structure:
// Provided by VK_VERSION_1_1
typedef struct VkDescriptorSetLayoutSupport {
VkStructureType sType;
void* pNext;
VkBool32 supported;
} VkDescriptorSetLayoutSupport;
or the equivalent
// Provided by VK_KHR_maintenance3
typedef VkDescriptorSetLayoutSupport VkDescriptorSetLayoutSupportKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
supportedspecifies whether the descriptor set layout can be created.
supported is set to VK_TRUE if the descriptor set can be
created, or else is set to VK_FALSE.
If the pNext chain of a VkDescriptorSetLayoutSupport structure
includes a VkDescriptorSetVariableDescriptorCountLayoutSupport
structure, then that structure returns additional information about whether
the descriptor set layout is supported.
// Provided by VK_VERSION_1_2
typedef struct VkDescriptorSetVariableDescriptorCountLayoutSupport {
VkStructureType sType;
void* pNext;
uint32_t maxVariableDescriptorCount;
} VkDescriptorSetVariableDescriptorCountLayoutSupport;
or the equivalent
// Provided by VK_EXT_descriptor_indexing
typedef VkDescriptorSetVariableDescriptorCountLayoutSupport VkDescriptorSetVariableDescriptorCountLayoutSupportEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxVariableDescriptorCountindicates the maximum number of descriptors supported in the highest numbered binding of the layout, if that binding is variable-sized. If the highest numbered binding of the layout has a descriptor type ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKthenmaxVariableDescriptorCountindicates the maximum byte size supported for the binding, if that binding is variable-sized.
If the VkDescriptorSetLayoutCreateInfo structure specified in
vkGetDescriptorSetLayoutSupport::pCreateInfo includes a
variable-sized descriptor, then supported is determined assuming the
requested size of the variable-sized descriptor, and
maxVariableDescriptorCount is set to the maximum size of that
descriptor that can be successfully created (which is greater than or equal
to the requested size passed in).
If the VkDescriptorSetLayoutCreateInfo structure does not include a
variable-sized descriptor, or if the
VkPhysicalDeviceDescriptorIndexingFeatures::descriptorBindingVariableDescriptorCount
feature is not enabled, then maxVariableDescriptorCount is set to
zero.
For the purposes of this command, a variable-sized descriptor binding with a
descriptorCount of zero is treated as if the descriptorCount is
one, and thus the binding is not ignored and the maximum descriptor count
will be returned.
If the layout is not supported, then the value written to
maxVariableDescriptorCount is undefined.
The following examples show a shader snippet using two descriptor sets, and application code that creates corresponding descriptor set layouts.
//
// binding to a single sampled image descriptor in set 0
//
layout (set=0, binding=0) uniform texture2D mySampledImage;
//
// binding to an array of sampled image descriptors in set 0
//
layout (set=0, binding=1) uniform texture2D myArrayOfSampledImages[12];
//
// binding to a single uniform buffer descriptor in set 1
//
layout (set=1, binding=0) uniform myUniformBuffer
{
vec4 myElement[32];
};
...
%1 = OpExtInstImport "GLSL.std.450"
...
OpName %9 "mySampledImage"
OpName %14 "myArrayOfSampledImages"
OpName %18 "myUniformBuffer"
OpMemberName %18 0 "myElement"
OpName %20 ""
OpDecorate %9 DescriptorSet 0
OpDecorate %9 Binding 0
OpDecorate %14 DescriptorSet 0
OpDecorate %14 Binding 1
OpDecorate %17 ArrayStride 16
OpMemberDecorate %18 0 Offset 0
OpDecorate %18 Block
OpDecorate %20 DescriptorSet 1
OpDecorate %20 Binding 0
%2 = OpTypeVoid
%3 = OpTypeFunction %2
%6 = OpTypeFloat 32
%7 = OpTypeImage %6 2D 0 0 0 1 Unknown
%8 = OpTypePointer UniformConstant %7
%9 = OpVariable %8 UniformConstant
%10 = OpTypeInt 32 0
%11 = OpConstant %10 12
%12 = OpTypeArray %7 %11
%13 = OpTypePointer UniformConstant %12
%14 = OpVariable %13 UniformConstant
%15 = OpTypeVector %6 4
%16 = OpConstant %10 32
%17 = OpTypeArray %15 %16
%18 = OpTypeStruct %17
%19 = OpTypePointer Uniform %18
%20 = OpVariable %19 Uniform
...
VkResult myResult;
const VkDescriptorSetLayoutBinding myDescriptorSetLayoutBinding[] =
{
// binding to a single image descriptor
{
0, // binding
VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, // descriptorType
1, // descriptorCount
VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags
NULL // pImmutableSamplers
},
// binding to an array of image descriptors
{
1, // binding
VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, // descriptorType
12, // descriptorCount
VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags
NULL // pImmutableSamplers
},
// binding to a single uniform buffer descriptor
{
0, // binding
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, // descriptorType
1, // descriptorCount
VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags
NULL // pImmutableSamplers
}
};
const VkDescriptorSetLayoutCreateInfo myDescriptorSetLayoutCreateInfo[] =
{
// Information for first descriptor set with two descriptor bindings
{
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO, // sType
NULL, // pNext
0, // flags
2, // bindingCount
&myDescriptorSetLayoutBinding[0] // pBindings
},
// Information for second descriptor set with one descriptor binding
{
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO, // sType
NULL, // pNext
0, // flags
1, // bindingCount
&myDescriptorSetLayoutBinding[2] // pBindings
}
};
VkDescriptorSetLayout myDescriptorSetLayout[2];
//
// Create first descriptor set layout
//
myResult = vkCreateDescriptorSetLayout(
myDevice,
&myDescriptorSetLayoutCreateInfo[0],
NULL,
&myDescriptorSetLayout[0]);
//
// Create second descriptor set layout
//
myResult = vkCreateDescriptorSetLayout(
myDevice,
&myDescriptorSetLayoutCreateInfo[1],
NULL,
&myDescriptorSetLayout[1]);
To destroy a descriptor set layout, call:
// Provided by VK_VERSION_1_0
void vkDestroyDescriptorSetLayout(
VkDevice device,
VkDescriptorSetLayout descriptorSetLayout,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the descriptor set layout. -
descriptorSetLayoutis the descriptor set layout to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
14.2.2. Pipeline Layouts
Access to descriptor sets from a pipeline is accomplished through a pipeline layout. Zero or more descriptor set layouts and zero or more push constant ranges are combined to form a pipeline layout object describing the complete set of resources that can be accessed by a pipeline. The pipeline layout represents a sequence of descriptor sets with each having a specific layout. This sequence of layouts is used to determine the interface between shader stages and shader resources. Each pipeline is created using a pipeline layout.
Pipeline layout objects are represented by VkPipelineLayout handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineLayout)
To create a pipeline layout, call:
// Provided by VK_VERSION_1_0
VkResult vkCreatePipelineLayout(
VkDevice device,
const VkPipelineLayoutCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkPipelineLayout* pPipelineLayout);
-
deviceis the logical device that creates the pipeline layout. -
pCreateInfois a pointer to a VkPipelineLayoutCreateInfo structure specifying the state of the pipeline layout object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPipelineLayoutis a pointer to a VkPipelineLayout handle in which the resulting pipeline layout object is returned.
The VkPipelineLayoutCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineLayoutCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineLayoutCreateFlags flags;
uint32_t setLayoutCount;
const VkDescriptorSetLayout* pSetLayouts;
uint32_t pushConstantRangeCount;
const VkPushConstantRange* pPushConstantRanges;
} VkPipelineLayoutCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineLayoutCreateFlagBits specifying options for pipeline layout creation. -
setLayoutCountis the number of descriptor sets included in the pipeline layout. -
pSetLayoutsis a pointer to an array ofVkDescriptorSetLayoutobjects. -
pushConstantRangeCountis the number of push constant ranges included in the pipeline layout. -
pPushConstantRangesis a pointer to an array ofVkPushConstantRangestructures defining a set of push constant ranges for use in a single pipeline layout. In addition to descriptor set layouts, a pipeline layout also describes how many push constants can be accessed by each stage of the pipeline.NotePush constants represent a high speed path to modify constant data in pipelines that is expected to outperform memory-backed resource updates.
// Provided by VK_EXT_graphics_pipeline_library
typedef enum VkPipelineLayoutCreateFlagBits {
// Provided by VK_EXT_graphics_pipeline_library
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT = 0x00000002,
} VkPipelineLayoutCreateFlagBits;
-
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT specifies that implementations must ensure that the properties and/or absence of a particular descriptor set do not influence any other properties of the pipeline layout. This allows pipelines libraries linked without
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXTto be created with a subset of the total descriptor sets.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineLayoutCreateFlags;
VkPipelineLayoutCreateFlags is a bitmask type for setting a mask of
VkPipelineLayoutCreateFlagBits.
The VkPushConstantRange structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPushConstantRange {
VkShaderStageFlags stageFlags;
uint32_t offset;
uint32_t size;
} VkPushConstantRange;
-
stageFlagsis a set of stage flags describing the shader stages that will access a range of push constants. If a particular stage is not included in the range, then accessing members of that range of push constants from the corresponding shader stage will return undefined values. -
offsetandsizeare the start offset and size, respectively, consumed by the range. Bothoffsetandsizeare in units of bytes and must be a multiple of 4. The layout of the push constant variables is specified in the shader.
Once created, pipeline layouts are used as part of pipeline creation (see Pipelines), as part of binding descriptor sets (see Descriptor Set Binding), and as part of setting push constants (see Push Constant Updates). Pipeline creation accepts a pipeline layout as input, and the layout may be used to map (set, binding, arrayElement) tuples to implementation resources or memory locations within a descriptor set. The assignment of implementation resources depends only on the bindings defined in the descriptor sets that comprise the pipeline layout, and not on any shader source.
All resource variables statically used in all shaders
in a pipeline must be declared with a (set, binding, arrayElement) that
exists in the corresponding descriptor set layout and is of an appropriate
descriptor type and includes the set of shader stages it is used by in
stageFlags.
The pipeline layout can include entries that are not used by a particular
pipeline, or that are dead-code eliminated from any of the shaders.
The pipeline layout allows the application to provide a consistent set of
bindings across multiple pipeline compiles, which enables those pipelines to
be compiled in a way that the implementation may cheaply switch pipelines
without reprogramming the bindings.
Similarly, the push constant block declared in each shader (if present)
must only place variables at offsets that are each included in a push
constant range with stageFlags including the bit corresponding to the
shader stage that uses it.
The pipeline layout can include ranges or portions of ranges that are not
used by a particular pipeline, or for which the variables have been
dead-code eliminated from any of the shaders.
There is a limit on the total number of resources of each type that can be included in bindings in all descriptor set layouts in a pipeline layout as shown in Pipeline Layout Resource Limits. The “Total Resources Available” column gives the limit on the number of each type of resource that can be included in bindings in all descriptor sets in the pipeline layout. Some resource types count against multiple limits. Additionally, there are limits on the total number of each type of resource that can be used in any pipeline stage as described in Shader Resource Limits.
| Total Resources Available | Resource Types |
|---|---|
|
sampler |
combined image sampler |
|
|
sampled image |
combined image sampler |
|
uniform texel buffer |
|
|
storage image |
storage texel buffer |
|
|
uniform buffer |
uniform buffer dynamic |
|
|
uniform buffer dynamic |
|
storage buffer |
storage buffer dynamic |
|
|
storage buffer dynamic |
|
input attachment |
|
inline uniform block |
|
acceleration structure |
To destroy a pipeline layout, call:
// Provided by VK_VERSION_1_0
void vkDestroyPipelineLayout(
VkDevice device,
VkPipelineLayout pipelineLayout,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the pipeline layout. -
pipelineLayoutis the pipeline layout to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
Pipeline Layout Compatibility
Two pipeline layouts are defined to be “compatible for
push constants” if they were created
with identical push constant ranges.
Two pipeline layouts are defined to be “compatible for set N” if they were
created with identically defined descriptor set layouts for sets zero
through N,
if both of them either were or were not created with
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT,
and if they were created with identical push constant ranges.
When binding a descriptor set (see Descriptor Set Binding) to set number N, if the previously bound descriptor sets for sets zero through N-1 were all bound using compatible pipeline layouts, then performing this binding does not disturb any of the lower numbered sets. If, additionally, the previously bound descriptor set for set N was bound using a pipeline layout compatible for set N, then the bindings in sets numbered greater than N are also not disturbed.
Similarly, when binding a pipeline, the pipeline can correctly access any previously bound descriptor sets which were bound with compatible pipeline layouts, as long as all lower numbered sets were also bound with compatible layouts.
Layout compatibility means that descriptor sets can be bound to a command buffer for use by any pipeline created with a compatible pipeline layout, and without having bound a particular pipeline first. It also means that descriptor sets can remain valid across a pipeline change, and the same resources will be accessible to the newly bound pipeline.
|
Note
Place the least frequently changing descriptor sets near the start of the pipeline layout, and place the descriptor sets representing the most frequently changing resources near the end. When pipelines are switched, only the descriptor set bindings that have been invalidated will need to be updated and the remainder of the descriptor set bindings will remain in place. |
The maximum number of descriptor sets that can be bound to a pipeline
layout is queried from physical device properties (see
maxBoundDescriptorSets in Limits).
const VkDescriptorSetLayout layouts[] = { layout1, layout2 };
const VkPushConstantRange ranges[] =
{
{
VK_SHADER_STAGE_VERTEX_BIT, // stageFlags
0, // offset
4 // size
},
{
VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags
4, // offset
4 // size
},
};
const VkPipelineLayoutCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO, // sType
NULL, // pNext
0, // flags
2, // setLayoutCount
layouts, // pSetLayouts
2, // pushConstantRangeCount
ranges // pPushConstantRanges
};
VkPipelineLayout myPipelineLayout;
myResult = vkCreatePipelineLayout(
myDevice,
&createInfo,
NULL,
&myPipelineLayout);
14.2.3. Allocation of Descriptor Sets
A descriptor pool maintains a pool of descriptors, from which descriptor sets are allocated. Descriptor pools are externally synchronized, meaning that the application must not allocate and/or free descriptor sets from the same pool in multiple threads simultaneously.
Descriptor pools are represented by VkDescriptorPool handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDescriptorPool)
To create a descriptor pool object, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateDescriptorPool(
VkDevice device,
const VkDescriptorPoolCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDescriptorPool* pDescriptorPool);
-
deviceis the logical device that creates the descriptor pool. -
pCreateInfois a pointer to a VkDescriptorPoolCreateInfo structure specifying the state of the descriptor pool object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pDescriptorPoolis a pointer to a VkDescriptorPool handle in which the resulting descriptor pool object is returned.
The created descriptor pool is returned in pDescriptorPool.
Additional information about the pool is passed in a
VkDescriptorPoolCreateInfo structure:
// Provided by VK_VERSION_1_0
typedef struct VkDescriptorPoolCreateInfo {
VkStructureType sType;
const void* pNext;
VkDescriptorPoolCreateFlags flags;
uint32_t maxSets;
uint32_t poolSizeCount;
const VkDescriptorPoolSize* pPoolSizes;
} VkDescriptorPoolCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkDescriptorPoolCreateFlagBits specifying certain supported operations on the pool. -
maxSetsis the maximum number of descriptor sets that can be allocated from the pool. -
poolSizeCountis the number of elements inpPoolSizes. -
pPoolSizesis a pointer to an array of VkDescriptorPoolSize structures, each containing a descriptor type and number of descriptors of that type to be allocated in the pool.
If multiple VkDescriptorPoolSize structures containing the same
descriptor type appear in the pPoolSizes array then the pool will be
created with enough storage for the total number of descriptors of each
type.
Fragmentation of a descriptor pool is possible and may lead to descriptor set allocation failures. A failure due to fragmentation is defined as failing a descriptor set allocation despite the sum of all outstanding descriptor set allocations from the pool plus the requested allocation requiring no more than the total number of descriptors requested at pool creation. Implementations provide certain guarantees of when fragmentation must not cause allocation failure, as described below.
If a descriptor pool has not had any descriptor sets freed since it was
created or most recently reset then fragmentation must not cause an
allocation failure (note that this is always the case for a pool created
without the VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT bit
set).
Additionally, if all sets allocated from the pool since it was created or
most recently reset use the same number of descriptors (of each type) and
the requested allocation also uses that same number of descriptors (of each
type), then fragmentation must not cause an allocation failure.
If an allocation failure occurs due to fragmentation, an application can create an additional descriptor pool to perform further descriptor set allocations.
If flags has the VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT
bit set, descriptor pool creation may fail with the error
VK_ERROR_FRAGMENTATION if the total number of descriptors across all
pools (including this one) created with this bit set exceeds
maxUpdateAfterBindDescriptorsInAllPools, or if fragmentation of the
underlying hardware resources occurs.
If a pPoolSizes[i]::type is
VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, a
VkMutableDescriptorTypeCreateInfoVALVE struct in the pNext chain
can be used to specify which mutable descriptor types can be allocated
from the pool.
If present in the pNext chain,
VkMutableDescriptorTypeCreateInfoVALVE::pMutableDescriptorTypeLists[i]
specifies which kind of VK_DESCRIPTOR_TYPE_MUTABLE_VALVE descriptors
can be allocated from this pool entry.
If VkMutableDescriptorTypeCreateInfoVALVE does not exist in the
pNext chain, or
VkMutableDescriptorTypeCreateInfoVALVE::pMutableDescriptorTypeLists[i]
is out of range, the descriptor pool allocates enough memory to be able to
allocate a VK_DESCRIPTOR_TYPE_MUTABLE_VALVE descriptor with any
supported VkDescriptorType as a mutable descriptor.
A mutable descriptor can be allocated from a pool entry if the type list in
VkDescriptorSetLayoutCreateInfo is a subset of the type list declared
in the descriptor pool, or if the pool entry is created without a descriptor
type list.
Multiple pPoolSizes entries with
VK_DESCRIPTOR_TYPE_MUTABLE_VALVE can be declared.
When multiple such pool entries are present in pPoolSizes, they
specify sets of supported descriptor types which either fully overlap,
partially overlap, or are disjoint.
Two sets fully overlap if the sets of supported descriptor types are equal.
If the sets are not disjoint they partially overlap.
A pool entry without a VkMutableDescriptorTypeListVALVE assigned to it
is considered to partially overlap any other pool entry which has a
VkMutableDescriptorTypeListVALVE assigned to it.
The application must ensure that partial overlap does not exist in
pPoolSizes.
|
Note
The requirement of no partial overlap is intended to resolve ambiguity for
validation as there is no confusion which |
In order to be able to allocate descriptor sets having
inline uniform block bindings the
descriptor pool must be created with specifying the inline uniform block
binding capacity of the descriptor pool, in addition to the total inline
uniform data capacity in bytes which is specified through a
VkDescriptorPoolSize structure with a descriptorType value of
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK.
This can be done by adding a
VkDescriptorPoolInlineUniformBlockCreateInfo structure to the
pNext chain of VkDescriptorPoolCreateInfo.
The VkDescriptorPoolInlineUniformBlockCreateInfo structure is defined
as:
// Provided by VK_VERSION_1_3
typedef struct VkDescriptorPoolInlineUniformBlockCreateInfo {
VkStructureType sType;
const void* pNext;
uint32_t maxInlineUniformBlockBindings;
} VkDescriptorPoolInlineUniformBlockCreateInfo;
or the equivalent
// Provided by VK_EXT_inline_uniform_block
typedef VkDescriptorPoolInlineUniformBlockCreateInfo VkDescriptorPoolInlineUniformBlockCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxInlineUniformBlockBindingsis the number of inline uniform block bindings to allocate.
Bits which can be set in VkDescriptorPoolCreateInfo::flags,
enabling operations on a descriptor pool, are:
// Provided by VK_VERSION_1_0
typedef enum VkDescriptorPoolCreateFlagBits {
VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT = 0x00000001,
// Provided by VK_VERSION_1_2
VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT = 0x00000002,
// Provided by VK_VALVE_mutable_descriptor_type
VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE = 0x00000004,
// Provided by VK_EXT_descriptor_indexing
VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT = VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT,
} VkDescriptorPoolCreateFlagBits;
-
VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BITspecifies that descriptor sets can return their individual allocations to the pool, i.e. all of vkAllocateDescriptorSets, vkFreeDescriptorSets, and vkResetDescriptorPool are allowed. Otherwise, descriptor sets allocated from the pool must not be individually freed back to the pool, i.e. only vkAllocateDescriptorSets and vkResetDescriptorPool are allowed. -
VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BITspecifies that descriptor sets allocated from this pool can include bindings with theVK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITbit set. It is valid to allocate descriptor sets that have bindings that do not set theVK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITbit from a pool that hasVK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BITset. -
VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVEspecifies that this descriptor pool and the descriptor sets allocated from it reside entirely in host memory and cannot be bound. Descriptor sets allocated from this pool are partially exempt from the external synchronization requirement in vkUpdateDescriptorSetWithTemplateKHR and vkUpdateDescriptorSets. Descriptor sets and their descriptors can be updated concurrently in different threads, though the same descriptor must not be updated concurrently by two threads.
// Provided by VK_VERSION_1_0
typedef VkFlags VkDescriptorPoolCreateFlags;
VkDescriptorPoolCreateFlags is a bitmask type for setting a mask of
zero or more VkDescriptorPoolCreateFlagBits.
The VkDescriptorPoolSize structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkDescriptorPoolSize {
VkDescriptorType type;
uint32_t descriptorCount;
} VkDescriptorPoolSize;
-
typeis the type of descriptor. -
descriptorCountis the number of descriptors of that type to allocate. IftypeisVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKthendescriptorCountis the number of bytes to allocate for descriptors of this type.
|
Note
When creating a descriptor pool that will contain descriptors for combined
image samplers of multi-planar formats, an application needs to account for
non-trivial descriptor consumption when choosing the |
To destroy a descriptor pool, call:
// Provided by VK_VERSION_1_0
void vkDestroyDescriptorPool(
VkDevice device,
VkDescriptorPool descriptorPool,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the descriptor pool. -
descriptorPoolis the descriptor pool to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
When a pool is destroyed, all descriptor sets allocated from the pool are implicitly freed and become invalid. Descriptor sets allocated from a given pool do not need to be freed before destroying that descriptor pool.
Descriptor sets are allocated from descriptor pool objects, and are
represented by VkDescriptorSet handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDescriptorSet)
To allocate descriptor sets from a descriptor pool, call:
// Provided by VK_VERSION_1_0
VkResult vkAllocateDescriptorSets(
VkDevice device,
const VkDescriptorSetAllocateInfo* pAllocateInfo,
VkDescriptorSet* pDescriptorSets);
-
deviceis the logical device that owns the descriptor pool. -
pAllocateInfois a pointer to a VkDescriptorSetAllocateInfo structure describing parameters of the allocation. -
pDescriptorSetsis a pointer to an array of VkDescriptorSet handles in which the resulting descriptor set objects are returned.
The allocated descriptor sets are returned in pDescriptorSets.
When a descriptor set is allocated, the initial state is largely uninitialized and all descriptors are undefined. Descriptors also become undefined if the underlying resource is destroyed. Descriptor sets containing undefined descriptors can still be bound and used, subject to the following conditions:
-
For descriptor set bindings created with the
VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BITbit set, all descriptors in that binding that are dynamically used must have been populated before the descriptor set is consumed. -
For descriptor set bindings created without the
VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BITbit set, all descriptors in that binding that are statically used must have been populated before the descriptor set is consumed. -
Descriptor bindings with descriptor type of
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKcan be undefined when the descriptor set is consumed; though values in that block will be undefined. -
Entries that are not used by a pipeline can have undefined descriptors.
If a call to vkAllocateDescriptorSets would cause the total number of
descriptor sets allocated from the pool to exceed the value of
VkDescriptorPoolCreateInfo::maxSets used to create
pAllocateInfo->descriptorPool, then the allocation may fail due to
lack of space in the descriptor pool.
Similarly, the allocation may fail due to lack of space if the call to
vkAllocateDescriptorSets would cause the number of any given
descriptor type to exceed the sum of all the descriptorCount members
of each element of VkDescriptorPoolCreateInfo::pPoolSizes with a
type equal to that type.
Additionally, the allocation may also fail if a call to
vkAllocateDescriptorSets would cause the total number of inline
uniform block bindings allocated from the pool to exceed the value of
VkDescriptorPoolInlineUniformBlockCreateInfo::maxInlineUniformBlockBindings
used to create the descriptor pool.
If the allocation fails due to no more space in the descriptor pool, and not
because of system or device memory exhaustion, then
VK_ERROR_OUT_OF_POOL_MEMORY must be returned.
vkAllocateDescriptorSets can be used to create multiple descriptor
sets.
If the creation of any of those descriptor sets fails, then the
implementation must destroy all successfully created descriptor set objects
from this command, set all entries of the pDescriptorSets array to
VK_NULL_HANDLE and return the error.
The VkDescriptorSetAllocateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkDescriptorSetAllocateInfo {
VkStructureType sType;
const void* pNext;
VkDescriptorPool descriptorPool;
uint32_t descriptorSetCount;
const VkDescriptorSetLayout* pSetLayouts;
} VkDescriptorSetAllocateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
descriptorPoolis the pool which the sets will be allocated from. -
descriptorSetCountdetermines the number of descriptor sets to be allocated from the pool. -
pSetLayoutsis a pointer to an array of descriptor set layouts, with each member specifying how the corresponding descriptor set is allocated.
If the pNext chain of a VkDescriptorSetAllocateInfo structure
includes a VkDescriptorSetVariableDescriptorCountAllocateInfo
structure, then that structure includes an array of descriptor counts for
variable-sized descriptor bindings, one for each descriptor set being
allocated.
The VkDescriptorSetVariableDescriptorCountAllocateInfo structure is
defined as:
// Provided by VK_VERSION_1_2
typedef struct VkDescriptorSetVariableDescriptorCountAllocateInfo {
VkStructureType sType;
const void* pNext;
uint32_t descriptorSetCount;
const uint32_t* pDescriptorCounts;
} VkDescriptorSetVariableDescriptorCountAllocateInfo;
or the equivalent
// Provided by VK_EXT_descriptor_indexing
typedef VkDescriptorSetVariableDescriptorCountAllocateInfo VkDescriptorSetVariableDescriptorCountAllocateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
descriptorSetCountis zero or the number of elements inpDescriptorCounts. -
pDescriptorCountsis a pointer to an array of descriptor counts, with each member specifying the number of descriptors in a variable-sized descriptor binding in the corresponding descriptor set being allocated.
If descriptorSetCount is zero or this structure is not included in the
pNext chain, then the variable lengths are considered to be zero.
Otherwise, pDescriptorCounts[i] is the number of descriptors in the
variable-sized descriptor binding in the corresponding descriptor set
layout.
If the variable-sized descriptor binding in the corresponding descriptor set
layout has a descriptor type of
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then
pDescriptorCounts[i] specifies the binding’s capacity in bytes.
If VkDescriptorSetAllocateInfo::pSetLayouts[i] does not include
a variable-sized descriptor binding, then pDescriptorCounts[i] is
ignored.
To free allocated descriptor sets, call:
// Provided by VK_VERSION_1_0
VkResult vkFreeDescriptorSets(
VkDevice device,
VkDescriptorPool descriptorPool,
uint32_t descriptorSetCount,
const VkDescriptorSet* pDescriptorSets);
-
deviceis the logical device that owns the descriptor pool. -
descriptorPoolis the descriptor pool from which the descriptor sets were allocated. -
descriptorSetCountis the number of elements in thepDescriptorSetsarray. -
pDescriptorSetsis a pointer to an array of handles to VkDescriptorSet objects.
After calling vkFreeDescriptorSets, all descriptor sets in
pDescriptorSets are invalid.
To return all descriptor sets allocated from a given pool to the pool, rather than freeing individual descriptor sets, call:
// Provided by VK_VERSION_1_0
VkResult vkResetDescriptorPool(
VkDevice device,
VkDescriptorPool descriptorPool,
VkDescriptorPoolResetFlags flags);
-
deviceis the logical device that owns the descriptor pool. -
descriptorPoolis the descriptor pool to be reset. -
flagsis reserved for future use.
Resetting a descriptor pool recycles all of the resources from all of the descriptor sets allocated from the descriptor pool back to the descriptor pool, and the descriptor sets are implicitly freed.
// Provided by VK_VERSION_1_0
typedef VkFlags VkDescriptorPoolResetFlags;
VkDescriptorPoolResetFlags is a bitmask type for setting a mask, but
is currently reserved for future use.
14.2.4. Descriptor Set Updates
Once allocated, descriptor sets can be updated with a combination of write and copy operations. To update descriptor sets, call:
// Provided by VK_VERSION_1_0
void vkUpdateDescriptorSets(
VkDevice device,
uint32_t descriptorWriteCount,
const VkWriteDescriptorSet* pDescriptorWrites,
uint32_t descriptorCopyCount,
const VkCopyDescriptorSet* pDescriptorCopies);
-
deviceis the logical device that updates the descriptor sets. -
descriptorWriteCountis the number of elements in thepDescriptorWritesarray. -
pDescriptorWritesis a pointer to an array of VkWriteDescriptorSet structures describing the descriptor sets to write to. -
descriptorCopyCountis the number of elements in thepDescriptorCopiesarray. -
pDescriptorCopiesis a pointer to an array of VkCopyDescriptorSet structures describing the descriptor sets to copy between.
The operations described by pDescriptorWrites are performed first,
followed by the operations described by pDescriptorCopies.
Within each array, the operations are performed in the order they appear in
the array.
Each element in the pDescriptorWrites array describes an operation
updating the descriptor set using descriptors for resources specified in the
structure.
Each element in the pDescriptorCopies array is a
VkCopyDescriptorSet structure describing an operation copying
descriptors between sets.
If the dstSet member of any element of pDescriptorWrites or
pDescriptorCopies is bound, accessed, or modified by any command that
was recorded to a command buffer which is currently in the
recording or executable state,
and any of the descriptor bindings that are updated were not created with
the VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT or
VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT bits set,
that command buffer becomes invalid.
The VkWriteDescriptorSet structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkWriteDescriptorSet {
VkStructureType sType;
const void* pNext;
VkDescriptorSet dstSet;
uint32_t dstBinding;
uint32_t dstArrayElement;
uint32_t descriptorCount;
VkDescriptorType descriptorType;
const VkDescriptorImageInfo* pImageInfo;
const VkDescriptorBufferInfo* pBufferInfo;
const VkBufferView* pTexelBufferView;
} VkWriteDescriptorSet;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dstSetis the destination descriptor set to update. -
dstBindingis the descriptor binding within that set. -
dstArrayElementis the starting element in that array. If the descriptor binding identified bydstSetanddstBindinghas a descriptor type ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKthendstArrayElementspecifies the starting byte offset within the binding. -
descriptorCountis the number of descriptors to update. If the descriptor binding identified bydstSetanddstBindinghas a descriptor type ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, thendescriptorCountspecifies the number of bytes to update. Otherwise,descriptorCountis one of-
the number of elements in
pImageInfo -
the number of elements in
pBufferInfo -
the number of elements in
pTexelBufferView -
a value matching the
dataSizemember of a VkWriteDescriptorSetInlineUniformBlock structure in thepNextchain -
a value matching the
accelerationStructureCountof a VkWriteDescriptorSetAccelerationStructureKHR structure in thepNextchain
-
-
descriptorTypeis a VkDescriptorType specifying the type of each descriptor inpImageInfo,pBufferInfo, orpTexelBufferView, as described below. IfVkDescriptorSetLayoutBindingfordstSetatdstBindingis not equal toVK_DESCRIPTOR_TYPE_MUTABLE_VALVE,descriptorTypemust be the same type as thedescriptorTypespecified inVkDescriptorSetLayoutBindingfordstSetatdstBinding. The type of the descriptor also controls which array the descriptors are taken from. -
pImageInfois a pointer to an array of VkDescriptorImageInfo structures or is ignored, as described below. -
pBufferInfois a pointer to an array of VkDescriptorBufferInfo structures or is ignored, as described below. -
pTexelBufferViewis a pointer to an array of VkBufferView handles as described in the Buffer Views section or is ignored, as described below.
Only one of pImageInfo, pBufferInfo, or pTexelBufferView
members is used according to the descriptor type specified in the
descriptorType member of the containing VkWriteDescriptorSet
structure,
or none of them in case descriptorType is
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, in which case the source data
for the descriptor writes is taken from the
VkWriteDescriptorSetInlineUniformBlock structure included in the
pNext chain of VkWriteDescriptorSet,
or if descriptorType is
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, in which case the
source data for the descriptor writes is taken from the
VkWriteDescriptorSetAccelerationStructureKHR structure in the
pNext chain of VkWriteDescriptorSet,
or if descriptorType is
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, in which case the source
data for the descriptor writes is taken from the
VkWriteDescriptorSetAccelerationStructureNV structure in the
pNext chain of VkWriteDescriptorSet,
as specified below.
If the nullDescriptor feature is enabled,
the buffer,
acceleration structure,
imageView, or bufferView can be VK_NULL_HANDLE.
Loads from a null descriptor return zero values and stores and atomics to a
null descriptor are discarded.
A null acceleration structure descriptor results in the miss shader being
invoked.
If the destination descriptor is a mutable descriptor, the active descriptor
type for the destination descriptor becomes descriptorType.
If the dstBinding has fewer than descriptorCount array elements
remaining starting from dstArrayElement, then the remainder will be
used to update the subsequent binding - dstBinding+1 starting at
array element zero.
If a binding has a descriptorCount of zero, it is skipped.
This behavior applies recursively, with the update affecting consecutive
bindings as needed to update all descriptorCount descriptors.
Consecutive bindings must have identical VkDescriptorType,
VkShaderStageFlags,
VkDescriptorBindingFlagBits,
and immutable samplers references.
In addition, if the VkDescriptorType is
VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the supported descriptor types in
VkMutableDescriptorTypeCreateInfoVALVE must be equally defined.
|
Note
The same behavior applies to bindings with a descriptor type of
|
The type of descriptors in a descriptor set is specified by
VkWriteDescriptorSet::descriptorType, which must be one of the
values:
// Provided by VK_VERSION_1_0
typedef enum VkDescriptorType {
VK_DESCRIPTOR_TYPE_SAMPLER = 0,
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER = 1,
VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE = 2,
VK_DESCRIPTOR_TYPE_STORAGE_IMAGE = 3,
VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER = 4,
VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER = 5,
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER = 6,
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER = 7,
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC = 8,
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC = 9,
VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT = 10,
// Provided by VK_VERSION_1_3
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK = 1000138000,
// Provided by VK_KHR_acceleration_structure
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR = 1000150000,
// Provided by VK_NV_ray_tracing
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV = 1000165000,
// Provided by VK_VALVE_mutable_descriptor_type
VK_DESCRIPTOR_TYPE_MUTABLE_VALVE = 1000351000,
// Provided by VK_EXT_inline_uniform_block
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT = VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK,
} VkDescriptorType;
-
VK_DESCRIPTOR_TYPE_SAMPLERspecifies a sampler descriptor. -
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERspecifies a combined image sampler descriptor. -
VK_DESCRIPTOR_TYPE_SAMPLED_IMAGEspecifies a sampled image descriptor. -
VK_DESCRIPTOR_TYPE_STORAGE_IMAGEspecifies a storage image descriptor. -
VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERspecifies a uniform texel buffer descriptor. -
VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERspecifies a storage texel buffer descriptor. -
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFERspecifies a uniform buffer descriptor. -
VK_DESCRIPTOR_TYPE_STORAGE_BUFFERspecifies a storage buffer descriptor. -
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMICspecifies a dynamic uniform buffer descriptor. -
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMICspecifies a dynamic storage buffer descriptor. -
VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTspecifies an input attachment descriptor. -
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKspecifies an inline uniform block. -
VK_DESCRIPTOR_TYPE_MUTABLE_VALVEspecifies a descriptor of mutable type.
When a descriptor set is updated via elements of VkWriteDescriptorSet,
members of pImageInfo, pBufferInfo and pTexelBufferView
are only accessed by the implementation when they correspond to descriptor
type being defined - otherwise they are ignored.
The members accessed are as follows for each descriptor type:
-
For
VK_DESCRIPTOR_TYPE_SAMPLER, only thesamplermember of each element of VkWriteDescriptorSet::pImageInfois accessed. -
For
VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, orVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, only theimageViewandimageLayoutmembers of each element of VkWriteDescriptorSet::pImageInfoare accessed. -
For
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, all members of each element of VkWriteDescriptorSet::pImageInfoare accessed. -
For
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER,VK_DESCRIPTOR_TYPE_STORAGE_BUFFER,VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, orVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, all members of each element of VkWriteDescriptorSet::pBufferInfoare accessed. -
For
VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of VkWriteDescriptorSet::pTexelBufferViewis accessed.
When updating descriptors with a descriptorType of
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, none of the pImageInfo,
pBufferInfo, or pTexelBufferView members are accessed, instead
the source data of the descriptor update operation is taken from the
VkWriteDescriptorSetInlineUniformBlock structure in the pNext
chain of VkWriteDescriptorSet.
When updating descriptors with a descriptorType of
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, none of the
pImageInfo, pBufferInfo, or pTexelBufferView members are
accessed, instead the source data of the descriptor update operation is
taken from the VkWriteDescriptorSetAccelerationStructureKHR structure
in the pNext chain of VkWriteDescriptorSet.
When updating descriptors with a descriptorType of
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, none of the
pImageInfo, pBufferInfo, or pTexelBufferView members are
accessed, instead the source data of the descriptor update operation is
taken from the VkWriteDescriptorSetAccelerationStructureNV structure
in the pNext chain of VkWriteDescriptorSet.
The VkDescriptorBufferInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkDescriptorBufferInfo {
VkBuffer buffer;
VkDeviceSize offset;
VkDeviceSize range;
} VkDescriptorBufferInfo;
-
bufferis VK_NULL_HANDLE or the buffer resource. -
offsetis the offset in bytes from the start ofbuffer. Access to buffer memory via this descriptor uses addressing that is relative to this starting offset. -
rangeis the size in bytes that is used for this descriptor update, orVK_WHOLE_SIZEto use the range fromoffsetto the end of the buffer.
When setting range to VK_WHOLE_SIZE, the
effective range must not be larger than
the maximum range for the descriptor type (maxUniformBufferRange or maxStorageBufferRange).
This means that VK_WHOLE_SIZE is not typically useful in the common
case where uniform buffer descriptors are suballocated from a buffer that is
much larger than maxUniformBufferRange.
For VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC and
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC descriptor types,
offset is the base offset from which the dynamic offset is applied and
range is the static size used for all dynamic offsets.
When range is VK_WHOLE_SIZE the effective range is calculated at
vkUpdateDescriptorSets is by taking the size of buffer minus the
offset.
The VkDescriptorImageInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkDescriptorImageInfo {
VkSampler sampler;
VkImageView imageView;
VkImageLayout imageLayout;
} VkDescriptorImageInfo;
-
sampleris a sampler handle, and is used in descriptor updates for typesVK_DESCRIPTOR_TYPE_SAMPLERandVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERif the binding being updated does not use immutable samplers. -
imageViewis VK_NULL_HANDLE or an image view handle, and is used in descriptor updates for typesVK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,VK_DESCRIPTOR_TYPE_STORAGE_IMAGE,VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, andVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. -
imageLayoutis the layout that the image subresources accessible fromimageViewwill be in at the time this descriptor is accessed.imageLayoutis used in descriptor updates for typesVK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,VK_DESCRIPTOR_TYPE_STORAGE_IMAGE,VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, andVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT.
Members of VkDescriptorImageInfo that are not used in an update (as
described above) are ignored.
If the descriptorType member of VkWriteDescriptorSet is
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then the data to write to the
descriptor set is specified through a
VkWriteDescriptorSetInlineUniformBlock structure included in the
pNext chain of VkWriteDescriptorSet.
The VkWriteDescriptorSetInlineUniformBlock structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkWriteDescriptorSetInlineUniformBlock {
VkStructureType sType;
const void* pNext;
uint32_t dataSize;
const void* pData;
} VkWriteDescriptorSetInlineUniformBlock;
or the equivalent
// Provided by VK_EXT_inline_uniform_block
typedef VkWriteDescriptorSetInlineUniformBlock VkWriteDescriptorSetInlineUniformBlockEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dataSizeis the number of bytes of inline uniform block data pointed to bypData. -
pDatais a pointer todataSizenumber of bytes of data to write to the inline uniform block.
The VkWriteDescriptorSetAccelerationStructureKHR structure is defined
as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkWriteDescriptorSetAccelerationStructureKHR {
VkStructureType sType;
const void* pNext;
uint32_t accelerationStructureCount;
const VkAccelerationStructureKHR* pAccelerationStructures;
} VkWriteDescriptorSetAccelerationStructureKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructureCountis the number of elements inpAccelerationStructures. -
pAccelerationStructuresis a pointer to an array of VkAccelerationStructureKHR structures specifying the acceleration structures to update.
The VkWriteDescriptorSetAccelerationStructureNV structure is defined
as:
// Provided by VK_NV_ray_tracing
typedef struct VkWriteDescriptorSetAccelerationStructureNV {
VkStructureType sType;
const void* pNext;
uint32_t accelerationStructureCount;
const VkAccelerationStructureNV* pAccelerationStructures;
} VkWriteDescriptorSetAccelerationStructureNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructureCountis the number of elements inpAccelerationStructures. -
pAccelerationStructuresis a pointer to an array of VkAccelerationStructureNV structures specifying the acceleration structures to update.
The VkCopyDescriptorSet structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkCopyDescriptorSet {
VkStructureType sType;
const void* pNext;
VkDescriptorSet srcSet;
uint32_t srcBinding;
uint32_t srcArrayElement;
VkDescriptorSet dstSet;
uint32_t dstBinding;
uint32_t dstArrayElement;
uint32_t descriptorCount;
} VkCopyDescriptorSet;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSet,srcBinding, andsrcArrayElementare the source set, binding, and array element, respectively. If the descriptor binding identified bysrcSetandsrcBindinghas a descriptor type ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKthensrcArrayElementspecifies the starting byte offset within the binding to copy from. -
dstSet,dstBinding, anddstArrayElementare the destination set, binding, and array element, respectively. If the descriptor binding identified bydstSetanddstBindinghas a descriptor type ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKthendstArrayElementspecifies the starting byte offset within the binding to copy to. -
descriptorCountis the number of descriptors to copy from the source to destination. IfdescriptorCountis greater than the number of remaining array elements in the source or destination binding, those affect consecutive bindings in a manner similar to VkWriteDescriptorSet above. If the descriptor binding identified bysrcSetandsrcBindinghas a descriptor type ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKthendescriptorCountspecifies the number of bytes to copy and the remaining array elements in the source or destination binding refer to the remaining number of bytes in those.
If the VkDescriptorSetLayoutBinding for dstBinding is
VK_DESCRIPTOR_TYPE_MUTABLE_VALVE and srcBinding is not
VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the new active descriptor type
becomes the descriptor type of srcBinding.
If both VkDescriptorSetLayoutBinding for srcBinding and
dstBinding are VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the active
descriptor type in each source descriptor is copied into the corresponding
destination descriptor.
The active descriptor type can be different for each source descriptor.
|
Note
The intention is that copies to and from mutable descriptors is a simple
memcpy.
Copies between non-mutable and mutable descriptors are expected to require
one memcpy per descriptor to handle the difference in size, but this use
case with more than one |
14.2.5. Descriptor Update Templates
A descriptor update template specifies a mapping from descriptor update information in host memory to descriptors in a descriptor set. It is designed to avoid passing redundant information to the driver when frequently updating the same set of descriptors in descriptor sets.
Descriptor update template objects are represented by
VkDescriptorUpdateTemplate handles:
// Provided by VK_VERSION_1_1
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDescriptorUpdateTemplate)
or the equivalent
// Provided by VK_KHR_descriptor_update_template
typedef VkDescriptorUpdateTemplate VkDescriptorUpdateTemplateKHR;
14.2.6. Descriptor Set Updates with Templates
Updating a large VkDescriptorSet array can be an expensive operation
since an application must specify one VkWriteDescriptorSet structure
for each descriptor or descriptor array to update, each of which
re-specifies the same state when updating the same descriptor in multiple
descriptor sets.
For cases when an application wishes to update the same set of descriptors
in multiple descriptor sets allocated using the same
VkDescriptorSetLayout, vkUpdateDescriptorSetWithTemplate can be
used as a replacement for vkUpdateDescriptorSets.
VkDescriptorUpdateTemplate allows implementations to convert a set of
descriptor update operations on a single descriptor set to an internal
format that, in conjunction with vkUpdateDescriptorSetWithTemplate
or vkCmdPushDescriptorSetWithTemplateKHR
, can be more efficient compared to calling vkUpdateDescriptorSets
or vkCmdPushDescriptorSetKHR
.
The descriptors themselves are not specified in the
VkDescriptorUpdateTemplate, rather, offsets into an application
provided pointer to host memory are specified, which are combined with a
pointer passed to vkUpdateDescriptorSetWithTemplate
or vkCmdPushDescriptorSetWithTemplateKHR
.
This allows large batches of updates to be executed without having to
convert application data structures into a strictly-defined Vulkan data
structure.
To create a descriptor update template, call:
// Provided by VK_VERSION_1_1
VkResult vkCreateDescriptorUpdateTemplate(
VkDevice device,
const VkDescriptorUpdateTemplateCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDescriptorUpdateTemplate* pDescriptorUpdateTemplate);
or the equivalent command
// Provided by VK_KHR_descriptor_update_template
VkResult vkCreateDescriptorUpdateTemplateKHR(
VkDevice device,
const VkDescriptorUpdateTemplateCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDescriptorUpdateTemplate* pDescriptorUpdateTemplate);
-
deviceis the logical device that creates the descriptor update template. -
pCreateInfois a pointer to a VkDescriptorUpdateTemplateCreateInfo structure specifying the set of descriptors to update with a single call to vkCmdPushDescriptorSetWithTemplateKHR or vkUpdateDescriptorSetWithTemplate. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pDescriptorUpdateTemplateis a pointer to aVkDescriptorUpdateTemplatehandle in which the resulting descriptor update template object is returned.
The VkDescriptorUpdateTemplateCreateInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkDescriptorUpdateTemplateCreateInfo {
VkStructureType sType;
const void* pNext;
VkDescriptorUpdateTemplateCreateFlags flags;
uint32_t descriptorUpdateEntryCount;
const VkDescriptorUpdateTemplateEntry* pDescriptorUpdateEntries;
VkDescriptorUpdateTemplateType templateType;
VkDescriptorSetLayout descriptorSetLayout;
VkPipelineBindPoint pipelineBindPoint;
VkPipelineLayout pipelineLayout;
uint32_t set;
} VkDescriptorUpdateTemplateCreateInfo;
or the equivalent
// Provided by VK_KHR_descriptor_update_template
typedef VkDescriptorUpdateTemplateCreateInfo VkDescriptorUpdateTemplateCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
descriptorUpdateEntryCountis the number of elements in thepDescriptorUpdateEntriesarray. -
pDescriptorUpdateEntriesis a pointer to an array of VkDescriptorUpdateTemplateEntry structures describing the descriptors to be updated by the descriptor update template. -
templateTypeSpecifies the type of the descriptor update template. If set toVK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SETit can only be used to update descriptor sets with a fixeddescriptorSetLayout. If set toVK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHRit can only be used to push descriptor sets using the providedpipelineBindPoint,pipelineLayout, andsetnumber. -
descriptorSetLayoutis the descriptor set layout used to build the descriptor update template. All descriptor sets which are going to be updated through the newly created descriptor update template must be created with a layout that matches (is the same as, or defined identically to) this layout. This parameter is ignored iftemplateTypeis notVK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET. -
pipelineBindPointis a VkPipelineBindPoint indicating the type of the pipeline that will use the descriptors. This parameter is ignored iftemplateTypeis notVK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR -
pipelineLayoutis a VkPipelineLayout object used to program the bindings. This parameter is ignored iftemplateTypeis notVK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR -
setis the set number of the descriptor set in the pipeline layout that will be updated. This parameter is ignored iftemplateTypeis notVK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
// Provided by VK_VERSION_1_1
typedef VkFlags VkDescriptorUpdateTemplateCreateFlags;
or the equivalent
// Provided by VK_KHR_descriptor_update_template
typedef VkDescriptorUpdateTemplateCreateFlags VkDescriptorUpdateTemplateCreateFlagsKHR;
VkDescriptorUpdateTemplateCreateFlags is a bitmask type for setting a
mask, but is currently reserved for future use.
The descriptor update template type is determined by the
VkDescriptorUpdateTemplateCreateInfo::templateType property,
which takes the following values:
// Provided by VK_VERSION_1_1
typedef enum VkDescriptorUpdateTemplateType {
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET = 0,
// Provided by VK_VERSION_1_1 with VK_KHR_push_descriptor, VK_KHR_descriptor_update_template with VK_KHR_push_descriptor
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR = 1,
// Provided by VK_KHR_descriptor_update_template
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR = VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET,
} VkDescriptorUpdateTemplateType;
or the equivalent
// Provided by VK_KHR_descriptor_update_template
typedef VkDescriptorUpdateTemplateType VkDescriptorUpdateTemplateTypeKHR;
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SETspecifies that the descriptor update template will be used for descriptor set updates only. -
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHRspecifies that the descriptor update template will be used for push descriptor updates only.
The VkDescriptorUpdateTemplateEntry structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkDescriptorUpdateTemplateEntry {
uint32_t dstBinding;
uint32_t dstArrayElement;
uint32_t descriptorCount;
VkDescriptorType descriptorType;
size_t offset;
size_t stride;
} VkDescriptorUpdateTemplateEntry;
or the equivalent
// Provided by VK_KHR_descriptor_update_template
typedef VkDescriptorUpdateTemplateEntry VkDescriptorUpdateTemplateEntryKHR;
-
dstBindingis the descriptor binding to update when using this descriptor update template. -
dstArrayElementis the starting element in the array belonging todstBinding. If the descriptor binding identified bydstBindinghas a descriptor type ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKthendstArrayElementspecifies the starting byte offset to update. -
descriptorCountis the number of descriptors to update. IfdescriptorCountis greater than the number of remaining array elements in the destination binding, those affect consecutive bindings in a manner similar to VkWriteDescriptorSet above. If the descriptor binding identified bydstBindinghas a descriptor type ofVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKthendescriptorCountspecifies the number of bytes to update and the remaining array elements in the destination binding refer to the remaining number of bytes in it. -
descriptorTypeis a VkDescriptorType specifying the type of the descriptor. -
offsetis the offset in bytes of the first binding in the raw data structure. -
strideis the stride in bytes between two consecutive array elements of the descriptor update informations in the raw data structure. The actual pointer ptr for each array element j of update entry i is computed using the following formula:const char *ptr = (const char *)pData + pDescriptorUpdateEntries[i].offset + j * pDescriptorUpdateEntries[i].strideThe stride is useful in case the bindings are stored in structs along with other data. If
descriptorTypeisVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKthen the value ofstrideis ignored and the stride is assumed to be1, i.e. the descriptor update information for them is always specified as a contiguous range.
To destroy a descriptor update template, call:
// Provided by VK_VERSION_1_1
void vkDestroyDescriptorUpdateTemplate(
VkDevice device,
VkDescriptorUpdateTemplate descriptorUpdateTemplate,
const VkAllocationCallbacks* pAllocator);
or the equivalent command
// Provided by VK_KHR_descriptor_update_template
void vkDestroyDescriptorUpdateTemplateKHR(
VkDevice device,
VkDescriptorUpdateTemplate descriptorUpdateTemplate,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that has been used to create the descriptor update template -
descriptorUpdateTemplateis the descriptor update template to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
Once a VkDescriptorUpdateTemplate has been created, descriptor sets
can be updated by calling:
// Provided by VK_VERSION_1_1
void vkUpdateDescriptorSetWithTemplate(
VkDevice device,
VkDescriptorSet descriptorSet,
VkDescriptorUpdateTemplate descriptorUpdateTemplate,
const void* pData);
or the equivalent command
// Provided by VK_KHR_descriptor_update_template
void vkUpdateDescriptorSetWithTemplateKHR(
VkDevice device,
VkDescriptorSet descriptorSet,
VkDescriptorUpdateTemplate descriptorUpdateTemplate,
const void* pData);
-
deviceis the logical device that updates the descriptor set. -
descriptorSetis the descriptor set to update -
descriptorUpdateTemplateis a VkDescriptorUpdateTemplate object specifying the update mapping betweenpDataand the descriptor set to update. -
pDatais a pointer to memory containing one or more VkDescriptorImageInfo, VkDescriptorBufferInfo, or VkBufferView structures or VkAccelerationStructureKHR or VkAccelerationStructureNV handles used to write the descriptors.
struct AppBufferView {
VkBufferView bufferView;
uint32_t applicationRelatedInformation;
};
struct AppDataStructure
{
VkDescriptorImageInfo imageInfo; // a single image info
VkDescriptorBufferInfo bufferInfoArray[3]; // 3 buffer infos in an array
AppBufferView bufferView[2]; // An application defined structure containing a bufferView
// ... some more application related data
};
const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] =
{
// binding to a single image descriptor
{
0, // binding
0, // dstArrayElement
1, // descriptorCount
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType
offsetof(AppDataStructure, imageInfo), // offset
0 // stride is not required if descriptorCount is 1
},
// binding to an array of buffer descriptors
{
1, // binding
0, // dstArrayElement
3, // descriptorCount
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, // descriptorType
offsetof(AppDataStructure, bufferInfoArray), // offset
sizeof(VkDescriptorBufferInfo) // stride, descriptor buffer infos are compact
},
// binding to an array of buffer views
{
2, // binding
0, // dstArrayElement
2, // descriptorCount
VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, // descriptorType
offsetof(AppDataStructure, bufferView) +
offsetof(AppBufferView, bufferView), // offset
sizeof(AppBufferView) // stride, bufferViews do not have to be compact
},
};
// create a descriptor update template for descriptor set updates
const VkDescriptorUpdateTemplateCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, // sType
NULL, // pNext
0, // flags
3, // descriptorUpdateEntryCount
descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, // templateType
myLayout, // descriptorSetLayout
0, // pipelineBindPoint, ignored by given templateType
0, // pipelineLayout, ignored by given templateType
0, // set, ignored by given templateType
};
VkDescriptorUpdateTemplate myDescriptorUpdateTemplate;
myResult = vkCreateDescriptorUpdateTemplate(
myDevice,
&createInfo,
NULL,
&myDescriptorUpdateTemplate);
AppDataStructure appData;
// fill appData here or cache it in your engine
vkUpdateDescriptorSetWithTemplate(myDevice, myDescriptorSet, myDescriptorUpdateTemplate, &appData);
14.2.7. Descriptor Set Binding
To bind one or more descriptor sets to a command buffer, call:
// Provided by VK_VERSION_1_0
void vkCmdBindDescriptorSets(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipelineLayout layout,
uint32_t firstSet,
uint32_t descriptorSetCount,
const VkDescriptorSet* pDescriptorSets,
uint32_t dynamicOffsetCount,
const uint32_t* pDynamicOffsets);
-
commandBufferis the command buffer that the descriptor sets will be bound to. -
pipelineBindPointis a VkPipelineBindPoint indicating the type of the pipeline that will use the descriptors. There is a separate set of bind points for each pipeline type, so binding one does not disturb the others. -
layoutis a VkPipelineLayout object used to program the bindings. -
firstSetis the set number of the first descriptor set to be bound. -
descriptorSetCountis the number of elements in thepDescriptorSetsarray. -
pDescriptorSetsis a pointer to an array of handles to VkDescriptorSet objects describing the descriptor sets to bind to. -
dynamicOffsetCountis the number of dynamic offsets in thepDynamicOffsetsarray. -
pDynamicOffsetsis a pointer to an array ofuint32_tvalues specifying dynamic offsets.
vkCmdBindDescriptorSets binds descriptor sets
pDescriptorSets[0..descriptorSetCount-1] to set numbers
[firstSet..firstSet+descriptorSetCount-1] for subsequent
bound pipeline commands set by
pipelineBindPoint.
Any bindings that were previously applied via these sets are no longer
valid.
Once bound, a descriptor set affects rendering of subsequent commands that interact with the given pipeline type in the command buffer until either a different set is bound to the same set number, or the set is disturbed as described in Pipeline Layout Compatibility.
A compatible descriptor set must be bound for all set numbers that any shaders in a pipeline access, at the time that a drawing or dispatching command is recorded to execute using that pipeline. However, if none of the shaders in a pipeline statically use any bindings with a particular set number, then no descriptor set need be bound for that set number, even if the pipeline layout includes a non-trivial descriptor set layout for that set number.
If any of the sets being bound include dynamic uniform or storage buffers,
then pDynamicOffsets includes one element for each array element in
each dynamic descriptor type binding in each set.
Values are taken from pDynamicOffsets in an order such that all
entries for set N come before set N+1; within a set, entries are ordered by
the binding numbers in the descriptor set layouts; and within a binding
array, elements are in order.
dynamicOffsetCount must equal the total number of dynamic descriptors
in the sets being bound.
The effective offset used for dynamic uniform and storage buffer bindings is
the sum of the relative offset taken from pDynamicOffsets, and the
base address of the buffer plus base offset in the descriptor set.
The range of the dynamic uniform and storage buffer bindings is the buffer
range as specified in the descriptor set.
Each of the pDescriptorSets must be compatible with the pipeline
layout specified by layout.
The layout used to program the bindings must also be compatible with the
pipeline used in subsequent bound pipeline
commands with that pipeline type, as defined in the
Pipeline Layout Compatibility section.
The descriptor set contents bound by a call to vkCmdBindDescriptorSets
may be consumed at the following times:
-
For descriptor bindings created with the
VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITbit set, the contents may be consumed when the command buffer is submitted to a queue, or during shader execution of the resulting draws and dispatches, or any time in between. Otherwise, -
during host execution of the command, or during shader execution of the resulting draws and dispatches, or any time in between.
Thus, the contents of a descriptor set binding must not be altered (overwritten by an update command, or freed) between the first point in time that it may be consumed, and when the command completes executing on the queue.
The contents of pDynamicOffsets are consumed immediately during
execution of vkCmdBindDescriptorSets.
Once all pending uses have completed, it is legal to update and reuse a
descriptor set.
14.2.8. Push Descriptor Updates
In addition to allocating descriptor sets and binding them to a command buffer, an application can record descriptor updates into the command buffer.
To push descriptor updates into a command buffer, call:
// Provided by VK_KHR_push_descriptor
void vkCmdPushDescriptorSetKHR(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipelineLayout layout,
uint32_t set,
uint32_t descriptorWriteCount,
const VkWriteDescriptorSet* pDescriptorWrites);
-
commandBufferis the command buffer that the descriptors will be recorded in. -
pipelineBindPointis a VkPipelineBindPoint indicating the type of the pipeline that will use the descriptors. There is a separate set of push descriptor bindings for each pipeline type, so binding one does not disturb the others. -
layoutis a VkPipelineLayout object used to program the bindings. -
setis the set number of the descriptor set in the pipeline layout that will be updated. -
descriptorWriteCountis the number of elements in thepDescriptorWritesarray. -
pDescriptorWritesis a pointer to an array of VkWriteDescriptorSet structures describing the descriptors to be updated.
Push descriptors are a small bank of descriptors whose storage is internally managed by the command buffer rather than being written into a descriptor set and later bound to a command buffer. Push descriptors allow for incremental updates of descriptors without managing the lifetime of descriptor sets.
When a command buffer begins recording, all push descriptors are undefined.
Push descriptors can be updated incrementally and cause shaders to use the
updated descriptors for subsequent bound
pipeline commands with the pipeline type set by pipelineBindPoint
until the descriptor is overwritten, or else until the set is disturbed as
described in Pipeline Layout
Compatibility.
When the set is disturbed or push descriptors with a different descriptor
set layout are set, all push descriptors are undefined.
Push descriptors that are statically used by a
pipeline must not be undefined at the time that a drawing or dispatching
command is recorded to execute using that pipeline.
This includes immutable sampler descriptors, which must be pushed before
they are accessed by a pipeline (the immutable samplers are pushed, rather
than the samplers in pDescriptorWrites).
Push descriptors that are not statically used can remain undefined.
Push descriptors do not use dynamic offsets.
Instead, the corresponding non-dynamic descriptor types can be used and the
offset member of VkDescriptorBufferInfo can be changed each
time the descriptor is written.
Each element of pDescriptorWrites is interpreted as in
VkWriteDescriptorSet, except the dstSet member is ignored.
To push an immutable sampler, use a VkWriteDescriptorSet with
dstBinding and dstArrayElement selecting the immutable sampler’s
binding.
If the descriptor type is VK_DESCRIPTOR_TYPE_SAMPLER, the
pImageInfo parameter is ignored and the immutable sampler is taken
from the push descriptor set layout in the pipeline layout.
If the descriptor type is VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
the sampler member of the pImageInfo parameter is ignored and
the immutable sampler is taken from the push descriptor set layout in the
pipeline layout.
14.2.9. Push Descriptor Updates with Descriptor Update Templates
It is also possible to use a descriptor update template to specify the push descriptors to update. To do so, call:
// Provided by VK_VERSION_1_1 with VK_KHR_push_descriptor, VK_KHR_descriptor_update_template with VK_KHR_push_descriptor
void vkCmdPushDescriptorSetWithTemplateKHR(
VkCommandBuffer commandBuffer,
VkDescriptorUpdateTemplate descriptorUpdateTemplate,
VkPipelineLayout layout,
uint32_t set,
const void* pData);
-
commandBufferis the command buffer that the descriptors will be recorded in. -
descriptorUpdateTemplateis a descriptor update template defining how to interpret the descriptor information inpData. -
layoutis a VkPipelineLayout object used to program the bindings. It must be compatible with the layout used to create thedescriptorUpdateTemplatehandle. -
setis the set number of the descriptor set in the pipeline layout that will be updated. This must be the same number used to create thedescriptorUpdateTemplatehandle. -
pDatais a pointer to memory containing descriptors for the templated update.
struct AppDataStructure
{
VkDescriptorImageInfo imageInfo; // a single image info
// ... some more application related data
};
const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] =
{
// binding to a single image descriptor
{
0, // binding
0, // dstArrayElement
1, // descriptorCount
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType
offsetof(AppDataStructure, imageInfo), // offset
0 // stride is not required if descriptorCount is 1
}
};
// create a descriptor update template for push descriptor set updates
const VkDescriptorUpdateTemplateCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, // sType
NULL, // pNext
0, // flags
1, // descriptorUpdateEntryCount
descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, // templateType
0, // descriptorSetLayout, ignored by given templateType
VK_PIPELINE_BIND_POINT_GRAPHICS, // pipelineBindPoint
myPipelineLayout, // pipelineLayout
0, // set
};
VkDescriptorUpdateTemplate myDescriptorUpdateTemplate;
myResult = vkCreateDescriptorUpdateTemplate(
myDevice,
&createInfo,
NULL,
&myDescriptorUpdateTemplate);
AppDataStructure appData;
// fill appData here or cache it in your engine
vkCmdPushDescriptorSetWithTemplateKHR(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData);
14.2.10. Push Constant Updates
As described above in section Pipeline Layouts, the pipeline layout defines shader push constants which are updated via Vulkan commands rather than via writes to memory or copy commands.
|
Note
Push constants represent a high speed path to modify constant data in pipelines that is expected to outperform memory-backed resource updates. |
To update push constants, call:
// Provided by VK_VERSION_1_0
void vkCmdPushConstants(
VkCommandBuffer commandBuffer,
VkPipelineLayout layout,
VkShaderStageFlags stageFlags,
uint32_t offset,
uint32_t size,
const void* pValues);
-
commandBufferis the command buffer in which the push constant update will be recorded. -
layoutis the pipeline layout used to program the push constant updates. -
stageFlagsis a bitmask of VkShaderStageFlagBits specifying the shader stages that will use the push constants in the updated range. -
offsetis the start offset of the push constant range to update, in units of bytes. -
sizeis the size of the push constant range to update, in units of bytes. -
pValuesis a pointer to an array ofsizebytes containing the new push constant values.
When a command buffer begins recording, all push constant values are undefined. Reads of undefined push constant values by the executing shader return undefined values.
Push constant values can be updated incrementally, causing shader stages in
stageFlags to read the new data from pValues for push constants
modified by this command, while still reading the previous data for push
constants not modified by this command.
When a bound pipeline command is issued,
the bound pipeline’s layout must be compatible with the layouts used to set
the values of all push constants in the pipeline layout’s push constant
ranges, as described in Pipeline Layout
Compatibility.
Binding a pipeline with a layout that is not compatible with the push
constant layout does not disturb the push constant values.
|
Note
As |
14.3. Physical Storage Buffer Access
To query a 64-bit buffer device address value through which buffer memory can be accessed in a shader, call:
// Provided by VK_VERSION_1_2
VkDeviceAddress vkGetBufferDeviceAddress(
VkDevice device,
const VkBufferDeviceAddressInfo* pInfo);
or the equivalent command
// Provided by VK_KHR_buffer_device_address
VkDeviceAddress vkGetBufferDeviceAddressKHR(
VkDevice device,
const VkBufferDeviceAddressInfo* pInfo);
or the equivalent command
// Provided by VK_EXT_buffer_device_address
VkDeviceAddress vkGetBufferDeviceAddressEXT(
VkDevice device,
const VkBufferDeviceAddressInfo* pInfo);
-
deviceis the logical device that the buffer was created on. -
pInfois a pointer to a VkBufferDeviceAddressInfo structure specifying the buffer to retrieve an address for.
The 64-bit return value is an address of the start of pInfo->buffer.
The address range starting at this value and whose size is the size of the
buffer can be used in a shader to access the memory bound to that buffer,
using the
SPV_KHR_physical_storage_buffer extension
or the equivalent
SPV_EXT_physical_storage_buffer extension
and the PhysicalStorageBuffer storage class.
For example, this value can be stored in a uniform buffer, and the shader
can read the value from the uniform buffer and use it to do a dependent
read/write to this buffer.
A value of zero is reserved as a “null” pointer and must not be returned
as a valid buffer device address.
All loads, stores, and atomics in a shader through
PhysicalStorageBuffer pointers must access addresses in the address
range of some buffer.
If the buffer was created with a non-zero value of
VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress or
VkBufferDeviceAddressCreateInfoEXT::deviceAddress,
the return value will be the same address that was returned at capture time.
The VkBufferDeviceAddressInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkBufferDeviceAddressInfo {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
} VkBufferDeviceAddressInfo;
or the equivalent
// Provided by VK_KHR_buffer_device_address
typedef VkBufferDeviceAddressInfo VkBufferDeviceAddressInfoKHR;
or the equivalent
// Provided by VK_EXT_buffer_device_address
typedef VkBufferDeviceAddressInfo VkBufferDeviceAddressInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferspecifies the buffer whose address is being queried.
To query a 64-bit buffer opaque capture address, call:
// Provided by VK_VERSION_1_2
uint64_t vkGetBufferOpaqueCaptureAddress(
VkDevice device,
const VkBufferDeviceAddressInfo* pInfo);
or the equivalent command
// Provided by VK_KHR_buffer_device_address
uint64_t vkGetBufferOpaqueCaptureAddressKHR(
VkDevice device,
const VkBufferDeviceAddressInfo* pInfo);
-
deviceis the logical device that the buffer was created on. -
pInfois a pointer to a VkBufferDeviceAddressInfo structure specifying the buffer to retrieve an address for.
The 64-bit return value is an opaque capture address of the start of
pInfo->buffer.
If the buffer was created with a non-zero value of
VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress the
return value must be the same address.
15. Shader Interfaces
When a pipeline is created, the set of shaders specified in the
corresponding Vk*PipelineCreateInfo structure are implicitly linked at
a number of different interfaces.
This chapter describes valid uses for a set of SPIR-V decorations.
Any other use of one of these decorations is invalid, with the exception
that, when using SPIR-V versions 1.4 and earlier: Block,
BufferBlock, Offset, ArrayStride, and MatrixStride can
also decorate types and type members used by variables in the Private
and Function storage classes.
|
Note
In this chapter, there are references to SPIR-V terms such as the
|
15.1. Shader Input and Output Interfaces
When multiple stages are present in a pipeline, the outputs of one stage form an interface with the inputs of the next stage. When such an interface involves a shader, shader outputs are matched against the inputs of the next stage, and shader inputs are matched against the outputs of the previous stage.
All the variables forming the shader input and output interfaces are
listed as operands to the OpEntryPoint instruction and are declared
with the Input or Output storage classes, respectively, in the
SPIR-V module.
These generally form the interfaces between consecutive shader stages,
regardless of any non-shader stages between the consecutive shader stages.
There are two classes of variables that can be matched between shader stages, built-in variables and user-defined variables. Each class has a different set of matching criteria.
Output variables of a shader stage have undefined values until the
shader writes to them or uses the Initializer operand when declaring
the variable.
15.1.1. Built-in Interface Block
Shader built-in variables meeting the following requirements define the built-in interface block. They must
-
be explicitly declared (there are no implicit built-ins),
-
be identified with a
BuiltIndecoration, -
form object types as described in the Built-in Variables section, and
-
be declared in a block whose top-level members are the built-ins.
There must be no more than one built-in interface block per shader per interface.
Built-ins must not have any Location or Component decorations.
15.1.2. User-defined Variable Interface
The non-built-in variables listed by OpEntryPoint with the Input
or Output storage class form the user-defined variable interface.
These must have SPIR-V numerical types or, recursively, composite types of
such types.
By default, the components of such types have a width of 32 or 64 bits.
If an implementation supports storageInputOutput16, components can also have a width of 16 bits.
These variables must be identified with a Location decoration and can
also be identified with a Component decoration.
15.1.3. Interface Matching
An output variable, block, or structure member in a given shader stage has an interface match with an input variable, block, or structure member in a subsequent shader stage if they both adhere to the following conditions:
-
They have equivalent decorations, other than:
-
XfbBuffer,XfbStride,Offset, andStream -
one is not decorated with
Componentand the other is declared with aComponentof0 -
RelaxedPrecisionif one is an input variable and the other an output variable
-
-
Their types match as follows:
-
if the input is declared in a tessellation control or geometry shader as an
OpTypeArraywith anElementTypeequivalent to theOpType*declaration of the output, and neither is a structure member; or -
if the
maintenance4feature is enabled, they are declared asOpTypeVectorvariables, and the output has aComponentCountvalue higher than that of the input but the sameComponentType; or -
if the output is declared in a mesh shader as an
OpTypeArraywith anElementTypeequivalent to theOpType*declaration of the input, and neither is a structure member; or -
if the input is decorated with
PerVertexKHR, and is declared in a fragment shader as anOpTypeArraywith anElementTypeequivalent to theOpType*declaration of the output, and neither the input nor the output is a structure member; or -
if in any other case they are declared with an equivalent
OpType*declaration.
-
-
If both are structures and every member has an interface match.
|
Note
The word “structure” above refers to both variables that have an
|
If the pipeline is compiled as separate graphics pipeline libraries and the
graphicsPipelineLibraryIndependentInterpolationDecoration limit is
not supported, matches are not found if the
interpolation decorations differ
between the last pre-rasterization shader stage and the fragment shader stage.
All input variables and blocks must have an interface match in the preceding shader stage, except for built-in variables in fragment shaders. Shaders can declare and write to output variables that are not declared or read by the subsequent stage.
Matching rules for passthrough geometry shaders are slightly different and are described in the Passthrough Interface Matching section.
The value of an input variable is undefined if the preceding stage does not write to a matching output variable, as described above.
15.1.4. Location Assignment
This section describes location assignments for user-defined variables and how many locations are consumed by a given user-variable type. As mentioned above, some inputs and outputs have an additional level of arrayness relative to other shader inputs and outputs. This outer array level is removed from the type before considering how many locations the type consumes.
The Location value specifies an interface slot comprised of a 32-bit
four-component vector conveyed between stages.
The Component specifies
components within these vector
locations.
Only types with widths of
16,
32 or 64 are supported in shader interfaces.
Inputs and outputs of the following types consume a single interface location:
-
16-bit scalar and vector types, and
-
32-bit scalar and vector types, and
-
64-bit scalar and 2-component vector types.
64-bit three- and four-component vectors consume two consecutive locations.
If a declared input or output is an array of size n and each element takes m locations, it will be assigned m × n consecutive locations starting with the location specified.
If the declared input or output is an n × m 16-, 32- or 64-bit matrix, it will be assigned multiple locations starting with the location specified. The number of locations assigned for each matrix will be the same as for an n-element array of m-component vectors.
An OpVariable with a structure type that is not a block must be
decorated with a Location.
When an OpVariable with a structure type (either block or non-block) is
decorated with a Location, the members in the structure type must not
be decorated with a Location.
The OpVariable’s members are assigned consecutive locations in
declaration order, starting from the first member, which is assigned the
location decoration from the OpVariable.
When a block-type OpVariable is declared without a Location
decoration, each member in its structure type must be decorated with a
Location.
Types nested deeper than the top-level members must not have Location
decorations.
The locations consumed by block and structure members are determined by applying the rules above in a depth-first traversal of the instantiated members as though the structure or block member were declared as an input or output variable of the same type.
Any two inputs listed as operands on the same OpEntryPoint must not be
assigned the same location, either explicitly or implicitly.
Any two outputs listed as operands on the same OpEntryPoint must not
be assigned the same location, either explicitly or implicitly.
The number of input and output locations available for a shader input or
output interface are limited, and dependent on the shader stage as described
in Shader Input and Output Locations.
All variables in both the built-in interface
block and the user-defined variable
interface count against these limits.
Each effective Location must have a value less than the number of
locations available for the given interface, as specified in the “Locations
Available” column in Shader Input and Output Locations.
| Shader Interface | Locations Available |
|---|---|
vertex input |
|
vertex output |
|
tessellation control input |
|
tessellation control output |
|
tessellation evaluation input |
|
tessellation evaluation output |
|
geometry input |
|
geometry output |
|
fragment input |
|
fragment output |
|
mesh output |
|
15.1.5. Component Assignment
The Component decoration allows the Location to be more finely
specified for scalars and vectors, down to the individual components within
a location that are consumed.
The components within a location are 0, 1, 2, and 3.
A variable or block member starting at component N will consume components
N, N+1, N+2, …
up through its size.
For 16-, and 32-bit types,
it is invalid if this sequence of components gets larger than 3.
A scalar 64-bit type will consume two of these components in sequence, and a
two-component 64-bit vector type will consume all four components available
within a location.
A three- or four-component 64-bit vector type must not specify a
Component decoration.
A three-component 64-bit vector type will consume all four components of the
first location and components 0 and 1 of the second location.
This leaves components 2 and 3 available for other component-qualified
declarations.
A scalar or two-component 64-bit data type must not specify a
Component decoration of 1 or 3.
A Component decoration must not be specified for any type that is not
a scalar or vector.
15.2. Vertex Input Interface
When the vertex stage is present in a pipeline, the vertex shader input
variables form an interface with the vertex input attributes.
The vertex shader input variables are matched by the Location and
Component decorations to the vertex input attributes specified in the
pVertexInputState member of the VkGraphicsPipelineCreateInfo
structure.
The vertex shader input variables listed by OpEntryPoint with the
Input storage class form the vertex input interface.
These variables must be identified with a Location decoration and can
also be identified with a Component decoration.
For the purposes of interface matching: variables declared without a
Component decoration are considered to have a Component decoration
of zero.
The number of available vertex input locations is given by the
maxVertexInputAttributes member of the VkPhysicalDeviceLimits
structure.
See Attribute Location and Component Assignment for details.
All vertex shader inputs declared as above must have a corresponding attribute and binding in the pipeline.
15.3. Fragment Output Interface
When the fragment stage is present in a pipeline, the fragment shader
outputs form an interface with the output attachments defined by a
render pass instance.
The fragment shader output variables are matched by the Location and
Component decorations to specified color attachments.
The fragment shader output variables listed by OpEntryPoint with the
Output storage class form the fragment output interface.
These variables must be identified with a Location decoration.
They can also be identified with a Component decoration and/or an
Index decoration.
For the purposes of interface matching: variables declared without a
Component decoration are considered to have a Component decoration
of zero, and variables declared without an Index decoration are
considered to have an Index decoration of zero.
A fragment shader output variable identified with a Location decoration
of i is associated with
the element of VkRenderingInfo::pColorAttachments with a
location equal to i.
When using render pass objects, it is associated with
the color attachment indicated by pColorAttachments[i].
Values are written to those attachments after passing through the blending
unit as described in Blending, if enabled.
Locations are consumed as described in
Location Assignment.
The number of available fragment output locations is given by the
maxFragmentOutputAttachments member of the
VkPhysicalDeviceLimits structure.
Components of the output variables are assigned as described in Component Assignment. Output components identified as 0, 1, 2, and 3 will be directed to the R, G, B, and A inputs to the blending unit, respectively, or to the output attachment if blending is disabled. If two variables are placed within the same location, they must have the same underlying type (floating-point or integer). The input values to blending or color attachment writes are undefined for components which do not correspond to a fragment shader output.
Fragment outputs identified with an Index of zero are directed to the
first input of the blending unit associated with the corresponding
Location.
Outputs identified with an Index of one are directed to the second
input of the corresponding blending unit.
No component aliasing of output variables is allowed, that is there must not be two output variables which have the same location, component, and index, either explicitly declared or implied.
Output values written by a fragment shader must be declared with either
OpTypeFloat or OpTypeInt, and a Width of 32.
If storageInputOutput16 is supported, output values written by a
fragment shader can be also declared with either OpTypeFloat or
OpTypeInt and a Width of 16.
Composites of these types are also permitted.
If the color attachment has a signed or unsigned normalized fixed-point
format, color values are assumed to be floating-point and are converted to
fixed-point as described in Conversion from Floating-Point to Normalized Fixed-Point; If the color
attachment has an integer format, color values are assumed to be integers
and converted to the bit-depth of the target.
Any value that cannot be represented in the attachment’s format is
undefined.
For any other attachment format no conversion is performed.
If the type of the values written by the fragment shader do not match the
format of the corresponding color attachment, the resulting values are
undefined for those components.
15.4. Fragment Input Attachment Interface
When a fragment stage is present in a pipeline, the fragment shader subpass
inputs form an interface with the input attachments of the current subpass.
The fragment shader subpass input variables are matched by
InputAttachmentIndex decorations to the input attachments specified in
the pInputAttachments array of the VkSubpassDescription
structure describing the subpass that the fragment shader is executed in.
The fragment shader subpass input variables with the UniformConstant
storage class and a decoration of InputAttachmentIndex that are
statically used by OpEntryPoint form the fragment input attachment
interface.
These variables must be declared with a type of OpTypeImage, a
Dim operand of SubpassData, an Arrayed operand of 0, and a
Sampled operand of 2.
The MS operand of the OpTypeImage must be 0 if the samples
field of the corresponding VkAttachmentDescription is
VK_SAMPLE_COUNT_1_BIT and 1 otherwise.
A subpass input variable identified with an InputAttachmentIndex
decoration of i reads from the input attachment indicated by
pInputAttachments[i] member of VkSubpassDescription.
If the subpass input variable is declared as an array of size N, it consumes
N consecutive input attachments, starting with the index specified.
There must not be more than one input variable with the same
InputAttachmentIndex whether explicitly declared or implied by an array
declaration.
The number of available input attachment indices is given by the
maxPerStageDescriptorInputAttachments member of the
VkPhysicalDeviceLimits structure.
Variables identified with the InputAttachmentIndex must only be used
by a fragment stage.
The basic data type (floating-point, integer, unsigned integer) of the
subpass input must match the basic format of the corresponding input
attachment, or the values of subpass loads from these variables are
undefined.
See Input Attachment for more details.
15.5. Ray Tracing Pipeline Interface
Ray tracing pipelines may have more stages than other pipelines with multiple instances of each stage and more dynamic interactions between the stages, but still have interface structures that obey the same general rules as interfaces between shader stages in other pipelines. The three types of inter-stage interface variables for ray tracing pipelines are:
-
Ray payloads containing data tracked for the entire lifetime of the ray.
-
Hit attributes containing data about a specific hit for the duration of its processing.
-
Callable data for passing data into and out of a callable shader.
Ray payloads and callable data are used in explicit shader call instructions, so they have an incoming variant to distinguish the parameter passed to the invocation from any other payloads or data being used by subsequent shader call instructions.
An interface structure used between stages must match between the stages using it. Specifically:
-
The hit attribute structure read in an any-hit or closest hit shader must be the same structure as the hit attribute structure written in the corresponding intersection shader in the same hit group.
-
The incoming callable data for a callable shader must be the same structure as the callable data referenced by the execute callable instruction in the calling shader.
-
The ray payload for a shader invoked by a ray tracing command must be the same structure for all shader stages using the payload for that ray.
Any shader with an incoming ray payload, incoming callable data, or hit attribute must only declare one variable of that type.
| Shader Stage | Ray Payload | Incoming Ray Payload | Hit Attribute | Callable Data | Incoming Callable Data |
|---|---|---|---|---|---|
Ray Generation |
r/w |
r/w |
|||
Intersection |
r/w |
||||
Any-Hit |
r/w |
r |
|||
Closest Hit |
r/w |
r/w |
r |
r/w |
|
Miss |
r/w |
r/w |
r/w |
||
Callable |
r/w |
r/w |
15.6. Shader Resource Interface
When a shader stage accesses buffer or image resources, as described in the Resource Descriptors section, the shader resource variables must be matched with the pipeline layout that is provided at pipeline creation time.
The set of shader variables that form the shader resource interface for a
stage are the variables statically used by that stage’s OpEntryPoint
with a storage class of Uniform, UniformConstant,
StorageBuffer,
or PushConstant.
For the fragment shader, this includes the fragment input attachment interface.
The shader resource interface consists of two sub-interfaces: the push constant interface and the descriptor set interface.
15.6.1. Push Constant Interface
The shader variables defined with a storage class of PushConstant that
are statically used by the shader entry points for the pipeline define the
push constant interface.
They must be:
-
typed as
OpTypeStruct, -
identified with a
Blockdecoration, and -
laid out explicitly using the
Offset,ArrayStride, andMatrixStridedecorations as specified in Offset and Stride Assignment.
There must be no more than one push constant block statically used per shader entry point.
Each statically used member of a push constant block must be placed at an
Offset such that the entire member is entirely contained within the
VkPushConstantRange for each OpEntryPoint that uses it, and the
stageFlags for that range must specify the appropriate
VkShaderStageFlagBits for that stage.
The Offset decoration for any member of a push constant block must not
cause the space required for that member to extend outside the range
[0, maxPushConstantsSize).
Any member of a push constant block that is declared as an array must only be accessed with dynamically uniform indices.
15.6.2. Descriptor Set Interface
The descriptor set interface is comprised of the shader variables with the
storage class of
StorageBuffer,
Uniform or UniformConstant (including the variables in the
fragment input attachment interface) that are
statically used by the shader entry points for the pipeline.
These variables must have DescriptorSet and Binding decorations
specified, which are assigned and matched with the
VkDescriptorSetLayout objects in the pipeline layout as described in
DescriptorSet and Binding Assignment.
The Image Format of an OpTypeImage declaration must not be
Unknown, for variables which are used for OpImageRead,
OpImageSparseRead, or OpImageWrite operations, except under the
following conditions:
-
For
OpImageWrite, if the image format is listed in the storage without format list and if theshaderStorageImageWriteWithoutFormatfeature is enabled and the shader module declares theStorageImageWriteWithoutFormatcapability. -
For
OpImageWrite, if the image format supportsVK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITand the shader module declares theStorageImageWriteWithoutFormatcapability. -
For
OpImageReadorOpImageSparseRead, if the image format is listed in the storage without format list and if theshaderStorageImageReadWithoutFormatfeature is enabled and the shader module declares theStorageImageReadWithoutFormatcapability. -
For
OpImageReadorOpImageSparseRead, if the image format supportsVK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BITand the shader module declares theStorageImageReadWithoutFormatcapability. -
For
OpImageRead, ifDimisSubpassData(indicating a read from an input attachment).
The Image Format of an OpTypeImage declaration must not be
Unknown, for variables which are used for OpAtomic* operations.
Variables identified with the Uniform storage class are used to access
transparent buffer backed resources.
Such variables must be:
-
typed as
OpTypeStruct, or an array of this type, -
identified with a
BlockorBufferBlockdecoration, and -
laid out explicitly using the
Offset,ArrayStride, andMatrixStridedecorations as specified in Offset and Stride Assignment.
Variables identified with the StorageBuffer storage class are used to
access transparent buffer backed resources.
Such variables must be:
-
typed as
OpTypeStruct, or an array of this type, -
identified with a
Blockdecoration, and -
laid out explicitly using the
Offset,ArrayStride, andMatrixStridedecorations as specified in Offset and Stride Assignment.
The Offset decoration for any member of a Block-decorated variable
in the Uniform storage class must not cause the space required for
that variable to extend outside the range [0,
maxUniformBufferRange).
The Offset decoration for any member of a Block-decorated variable
in the StorageBuffer storage class must not cause the space required
for that variable to extend outside the range [0,
maxStorageBufferRange).
Variables identified with the Uniform storage class can also be used
to access transparent descriptor set backed resources when the variable is
assigned to a descriptor set layout binding with a descriptorType of
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK.
In this case the variable must be typed as OpTypeStruct and cannot be
aggregated into arrays of that type.
Further, the Offset decoration for any member of such a variable must
not cause the space required for that variable to extend outside the range
[0,maxInlineUniformBlockSize).
Variables identified with a storage class of UniformConstant and a
decoration of InputAttachmentIndex must be declared as described in
Fragment Input Attachment Interface.
SPIR-V variables decorated with a descriptor set and binding that identify a
combined image sampler descriptor
can have a type of OpTypeImage, OpTypeSampler (Sampled=1),
or OpTypeSampledImage.
Arrays of any of these types can be indexed with constant integral expressions. The following features must be enabled and capabilities must be declared in order to index such arrays with dynamically uniform or non-uniform indices:
-
Storage images (except storage texel buffers and input attachments):
-
Dynamically uniform:
shaderStorageImageArrayDynamicIndexingandStorageImageArrayDynamicIndexing -
Non-uniform:
shaderStorageImageArrayNonUniformIndexingandStorageImageArrayNonUniformIndexing
-
-
Storage texel buffers:
-
Dynamically uniform:
shaderStorageTexelBufferArrayDynamicIndexingandStorageTexelBufferArrayDynamicIndexing -
Non-uniform:
shaderStorageTexelBufferArrayNonUniformIndexingandStorageTexelBufferArrayNonUniformIndexing
-
-
Input attachments:
-
Dynamically uniform:
shaderInputAttachmentArrayDynamicIndexingandInputAttachmentArrayDynamicIndexing -
Non-uniform:
shaderInputAttachmentArrayNonUniformIndexingandInputAttachmentArrayNonUniformIndexing
-
-
Sampled images (except uniform texel buffers), samplers and combined image samplers:
-
Dynamically uniform:
shaderSampledImageArrayDynamicIndexingandSampledImageArrayDynamicIndexing -
Non-uniform:
shaderSampledImageArrayNonUniformIndexingandSampledImageArrayNonUniformIndexing
-
-
Uniform texel buffers:
-
Dynamically uniform:
shaderUniformTexelBufferArrayDynamicIndexingandUniformTexelBufferArrayDynamicIndexing -
Non-uniform:
shaderUniformTexelBufferArrayNonUniformIndexingandUniformTexelBufferArrayNonUniformIndexing
-
-
Uniform buffers:
-
Dynamically uniform:
shaderUniformBufferArrayDynamicIndexingandUniformBufferArrayDynamicIndexing -
Non-uniform:
shaderUniformBufferArrayNonUniformIndexingandUniformBufferArrayNonUniformIndexing
-
-
Storage buffers:
-
Dynamically uniform:
shaderStorageBufferArrayDynamicIndexingandStorageBufferArrayDynamicIndexing -
Non-uniform:
shaderStorageBufferArrayNonUniformIndexingandStorageBufferArrayNonUniformIndexing
-
-
Acceleration structures:
-
Dynamically uniform: Always supported.
-
Non-uniform: Always supported.
-
If an instruction loads from or stores to a resource (including atomics and image instructions) and the resource descriptor being accessed is not dynamically uniform, then the corresponding non-uniform indexing feature must be enabled and the capability must be declared. If an instruction loads from or stores to a resource (including atomics and image instructions) and the resource descriptor being accessed is loaded from an array element with a non-constant index, then the corresponding dynamic or non-uniform indexing feature must be enabled and the capability must be declared.
If the combined image sampler enables sampler Y′CBCR
conversion or samples a subsampled image,
it must be indexed only by constant integral expressions when aggregated
into arrays in shader code, irrespective of the
shaderSampledImageArrayDynamicIndexing feature.
| Resource type | Descriptor Type |
|---|---|
sampler |
|
sampled image |
|
storage image |
|
combined image sampler |
|
uniform texel buffer |
|
storage texel buffer |
|
uniform buffer |
|
storage buffer |
|
input attachment |
|
inline uniform block |
|
acceleration structure |
|
| Resource type | Storage Class | Type1 | Decoration(s)2 |
|---|---|---|---|
sampler |
|
|
|
sampled image |
|
|
|
storage image |
|
|
|
combined image sampler |
|
|
|
uniform texel buffer |
|
|
|
storage texel buffer |
|
|
|
uniform buffer |
|
|
|
storage buffer |
|
|
|
|
|
||
input attachment |
|
|
|
inline uniform block |
|
|
|
acceleration structure |
|
|
- 1
-
Where
OpTypeImageis referenced, theDimvaluesBufferandSubpassdataare only accepted where they are specifically referenced. They do not correspond to resource types where a genericOpTypeImageis specified. - 2
-
In addition to
DescriptorSetandBinding.
15.6.3. DescriptorSet and Binding Assignment
A variable decorated with a DescriptorSet decoration of s and a
Binding decoration of b indicates that this variable is
associated with the VkDescriptorSetLayoutBinding that has a
binding equal to b in pSetLayouts[s] that was specified
in VkPipelineLayoutCreateInfo.
DescriptorSet decoration values must be between zero and
maxBoundDescriptorSets minus one, inclusive.
Binding decoration values can be any 32-bit unsigned integer value, as
described in Descriptor Set Layout.
Each descriptor set has its own binding name space.
If the Binding decoration is used with an array, the entire array is
assigned that binding value.
The array must be a single-dimensional array and size of the array must be
no larger than the number of descriptors in the binding.
If the array is runtime-sized, then array elements greater than or equal to
the size of that binding in the bound descriptor set must not be used.
If the array is runtime-sized, the runtimeDescriptorArray feature
must be enabled and the RuntimeDescriptorArray capability must be
declared.
The index of each element of the array is referred to as the arrayElement.
For the purposes of interface matching and descriptor set
operations, if a resource variable is not an
array, it is treated as if it has an arrayElement of zero.
There is a limit on the number of resources of each type that can be
accessed by a pipeline stage as shown in
Shader Resource Limits.
The “Resources Per Stage” column gives the limit on the number each type
of resource that can be statically used for an entry point in any given
stage in a pipeline.
The “Resource Types” column lists which resource types are counted against
the limit.
Some resource types count against multiple limits.
The VK_DESCRIPTOR_TYPE_MUTABLE_VALVE descriptor type counts as one
individual resource and one for every unique resource limit per descriptor
set type that is present in the associated binding’s
VkMutableDescriptorTypeListVALVE.
If multiple descriptor types in VkMutableDescriptorTypeListVALVE map
to the same resource limit, only one descriptor is consumed for purposes of
computing resource limits.
The pipeline layout may include descriptor sets and bindings which are not
referenced by any variables statically used by the entry points for the
shader stages in the binding’s stageFlags.
However, if a variable assigned to a given DescriptorSet and
Binding is statically used by the entry point for a shader stage, the
pipeline layout must contain a descriptor set layout binding in that
descriptor set layout and for that binding number, and that binding’s
stageFlags must include the appropriate VkShaderStageFlagBits
for that stage.
The variable must be of a valid resource type determined by its SPIR-V type
and storage class, as defined in
Shader Resource and
Storage Class Correspondence.
The descriptor set layout binding must be of a corresponding descriptor
type, as defined in Shader Resource
and Descriptor Type Correspondence.
|
Note
There are no limits on the number of shader variables that can have overlapping set and binding values in a shader; but which resources are statically used has an impact. If any shader variable identifying a resource is statically used in a shader, then the underlying descriptor bound at the declared set and binding must support the declared type in the shader when the shader executes. If multiple shader variables are declared with the same set and binding
values, and with the same underlying descriptor type, they can all be
statically used within the same shader.
However, accesses are not automatically synchronized, and If multiple shader variables with the same set and binding values are declared in a single shader, but with different declared types, where any of those are not supported by the relevant bound descriptor, that shader can only be executed if the variables with the unsupported type are not statically used. A noteworthy example of using multiple statically-used shader variables
sharing the same descriptor set and binding values is a descriptor of type
|
| Resources per Stage | Resource Types |
|---|---|
|
sampler |
combined image sampler |
|
|
sampled image |
combined image sampler |
|
uniform texel buffer |
|
|
storage image |
storage texel buffer |
|
|
uniform buffer |
uniform buffer dynamic |
|
|
storage buffer |
storage buffer dynamic |
|
|
input attachment1 |
|
inline uniform block |
|
acceleration structure |
- 1
-
Input attachments can only be used in the fragment shader stage
15.6.4. Offset and Stride Assignment
Certain objects must be explicitly laid out using the Offset,
ArrayStride, and MatrixStride, as described in
SPIR-V
explicit layout validation rules.
All such layouts also must conform to the following requirements.
|
Note
The numeric order of |
Alignment Requirements
There are different alignment requirements depending on the specific resources and on the features enabled on the device.
Matrix types are defined in terms of arrays as follows:
-
A column-major matrix with C columns and R rows is equivalent to a C element array of vectors with R components.
-
A row-major matrix with C columns and R rows is equivalent to an R element array of vectors with C components.
The scalar alignment of the type of an OpTypeStruct member is defined
recursively as follows:
-
A scalar of size N has a scalar alignment of N.
-
A vector type has a scalar alignment equal to that of its component type.
-
An array type has a scalar alignment equal to that of its element type.
-
A structure has a scalar alignment equal to the largest scalar alignment of any of its members.
-
A matrix type inherits scalar alignment from the equivalent array declaration.
The base alignment of the type of an OpTypeStruct member is defined
recursively as follows:
-
A scalar has a base alignment equal to its scalar alignment.
-
A two-component vector has a base alignment equal to twice its scalar alignment.
-
A three- or four-component vector has a base alignment equal to four times its scalar alignment.
-
An array has a base alignment equal to the base alignment of its element type.
-
A structure has a base alignment equal to the largest base alignment of any of its members. An empty structure has a base alignment equal to the size of the smallest scalar type permitted by the capabilities declared in the SPIR-V module. (e.g., for a 1 byte aligned empty struct in the
StorageBufferstorage class,StorageBuffer8BitAccessorUniformAndStorageBuffer8BitAccessmust be declared in the SPIR-V module.) -
A matrix type inherits base alignment from the equivalent array declaration.
The extended alignment of the type of an OpTypeStruct member is
similarly defined as follows:
-
A scalar or vector type has an extended alignment equal to its base alignment.
-
An array or structure type has an extended alignment equal to the largest extended alignment of any of its members, rounded up to a multiple of 16.
-
A matrix type inherits extended alignment from the equivalent array declaration.
A member is defined to improperly straddle if either of the following are true:
-
It is a vector with total size less than or equal to 16 bytes, and has
Offsetdecorations placing its first byte at F and its last byte at L, where floor(F / 16) != floor(L / 16). -
It is a vector with total size greater than 16 bytes and has its
Offsetdecorations placing its first byte at a non-integer multiple of 16.
Standard Buffer Layout
Every member of an OpTypeStruct that is required to be explicitly laid
out must be aligned according to the first matching rule as follows.
If the struct is contained in pointer types of multiple storage classes, it
must satisfy the requirements for every storage class used to reference it.
-
If the
scalarBlockLayoutfeature is enabled on the device and the storage class isUniform,StorageBuffer,PhysicalStorageBuffer,ShaderRecordBufferKHR, orPushConstantthen every member must be aligned according to its scalar alignment. -
If the
workgroupMemoryExplicitLayoutScalarBlockLayoutfeature is enabled on the device and the storage class isWorkgroupthen every member must be aligned according to its scalar alignment. -
All vectors must be aligned according to their scalar alignment.
-
If the
uniformBufferStandardLayoutfeature is not enabled on the device, then any member of anOpTypeStructwith a storage class ofUniformand a decoration ofBlockmust be aligned according to its extended alignment. -
Every other member must be aligned according to its base alignment.
|
Note
Even if scalar alignment is supported, it is generally more performant to use the base alignment. |
The memory layout must obey the following rules:
-
The
Offsetdecoration of any member must be a multiple of its alignment. -
Any
ArrayStrideorMatrixStridedecoration must be a multiple of the alignment of the array or matrix as defined above.
If one of the conditions below applies
-
The storage class is
Uniform,StorageBuffer,PhysicalStorageBuffer,ShaderRecordBufferKHR, orPushConstant, and thescalarBlockLayoutfeature is not enabled on the device. -
The storage class is
Workgroup, and either the struct member is not part of aBlockor theworkgroupMemoryExplicitLayoutScalarBlockLayoutfeature is not enabled on the device. -
The storage class is any other storage class.
the memory layout must also obey the following rules:
-
Vectors must not improperly straddle, as defined above.
-
The
Offsetdecoration of a member must not place it between the end of a structure, an array or a matrix and the next multiple of the alignment of that structure, array or matrix.
|
Note
The std430 layout in GLSL satisfies these rules for types using the base alignment. The std140 layout satisfies the rules for types using the extended alignment. |
15.7. Built-In Variables
Built-in variables are accessed in shaders by declaring a variable decorated
with a BuiltIn SPIR-V decoration.
The meaning of each BuiltIn decoration is as follows.
In the remainder of this section, the name of a built-in is used
interchangeably with a term equivalent to a variable decorated with that
particular built-in.
Built-ins that represent integer values can be declared as either signed or
unsigned 32-bit integers.
As mentioned above, some inputs and outputs have an additional level of arrayness relative to other shader inputs and outputs. This level of arrayness is not included in the type descriptions below, but must be included when declaring the built-in.
BaryCoordKHR-
The
BaryCoordKHRdecoration can be used to decorate a fragment shader input variable. This variable will contain a three-component floating-point vector with barycentric weights that indicate the location of the fragment relative to the screen-space locations of vertices of its primitive, obtained using perspective interpolation.
BaryCoordNoPerspAMD-
The
BaryCoordNoPerspAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using linear interpolation at the fragment’s center. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordNoPerspKHR-
The
BaryCoordNoPerspKHRdecoration can be used to decorate a fragment shader input variable. This variable will contain a three-component floating-point vector with barycentric weights that indicate the location of the fragment relative to the screen-space locations of vertices of its primitive, obtained using linear interpolation.
BaryCoordNoPerspCentroidAMD-
The
BaryCoordNoPerspCentroidAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using linear interpolation at the centroid. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordNoPerspSampleAMD-
The
BaryCoordNoPerspSampleAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using linear interpolation at each covered sample. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordPullModelAMD-
The
BaryCoordPullModelAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain (1/W, 1/I, 1/J) evaluated at the fragment center and can be used to calculate gradients and then interpolate I, J, and W at any desired sample location.
BaryCoordSmoothAMD-
The
BaryCoordSmoothAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using perspective interpolation at the fragment’s center. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordSmoothCentroidAMD-
The
BaryCoordSmoothCentroidAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using perspective interpolation at the centroid. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaryCoordSmoothSampleAMD-
The
BaryCoordSmoothSampleAMDdecoration can be used to decorate a fragment shader input variable. This variable will contain the (I,J) pair of the barycentric coordinates corresponding to the fragment evaluated using perspective interpolation at each covered sample. The K coordinate of the barycentric coordinates can be derived given the identity I + J + K = 1.0.
BaseInstance-
Decorating a variable with the
BaseInstancebuilt-in will make that variable contain the integer value corresponding to the first instance that was passed to the command that invoked the current vertex shader invocation.BaseInstanceis thefirstInstanceparameter to a direct drawing command or thefirstInstancemember of a structure consumed by an indirect drawing command.
BaseVertex-
Decorating a variable with the
BaseVertexbuilt-in will make that variable contain the integer value corresponding to the first vertex or vertex offset that was passed to the command that invoked the current vertex shader invocation. For non-indexed drawing commands, this variable is thefirstVertexparameter to a direct drawing command or thefirstVertexmember of the structure consumed by an indirect drawing command. For indexed drawing commands, this variable is thevertexOffsetparameter to a direct drawing command or thevertexOffsetmember of the structure consumed by an indirect drawing command.
ClipDistance-
Decorating a variable with the
ClipDistancebuilt-in decoration will make that variable contain the mechanism for controlling user clipping.ClipDistanceis an array such that the ith element of the array specifies the clip distance for plane i. A clip distance of 0 means the vertex is on the plane, a positive distance means the vertex is inside the clip half-space, and a negative distance means the vertex is outside the clip half-space.
|
Note
The array variable decorated with |
|
Note
In the last pre-rasterization
shader stage, these values will be linearly interpolated across the
primitive and the portion of the primitive with interpolated distances less
than 0 will be considered outside the clip volume.
If |
ClipDistancePerViewNV-
Decorating a variable with the
ClipDistancePerViewNVbuilt-in decoration will make that variable contain the per-view clip distances. The per-view clip distances have the same semantics asClipDistance.
CullDistance-
Decorating a variable with the
CullDistancebuilt-in decoration will make that variable contain the mechanism for controlling user culling. If any member of this array is assigned a negative value for all vertices belonging to a primitive, then the primitive is discarded before rasterization.
|
Note
In fragment shaders, the values of the |
|
Note
If |
CullDistancePerViewNV-
Decorating a variable with the
CullDistancePerViewNVbuilt-in decoration will make that variable contain the per-view cull distances. The per-view cull distances have the same semantics asCullDistance.
CullMaskKHR-
A variable decorated with the
CullMaskKHRdecoration will specify the cull mask of the ray being processed. The value is given by theCull Maskparameter passed into one of theOpTrace*instructions.
CurrentRayTimeNV-
A variable decorated with the
CurrentRayTimeNVdecoration contains the time value passed in toOpTraceRayMotionNVwhich called this shader.
DeviceIndex-
The
DeviceIndexdecoration can be applied to a shader input which will be filled with the device index of the physical device that is executing the current shader invocation. This value will be in the range , where physicalDeviceCount is thephysicalDeviceCountmember of VkDeviceGroupDeviceCreateInfo.
DrawIndex-
Decorating a variable with the
DrawIndexbuilt-in will make that variable contain the integer value corresponding to the zero-based index of the drawing command that invoked the current task, mesh, or vertex shader invocation. For indirect drawing commands,DrawIndexbegins at zero and increments by one for each drawing command executed. The number of drawing commands is given by thedrawCountparameter. For direct drawing commands, if vkCmdDrawMultiEXT or vkCmdDrawMultiIndexedEXT is used, this variable contains the integer value corresponding to the zero-based index of the draw command. OtherwiseDrawIndexis always zero.DrawIndexis dynamically uniform.
When task or mesh shaders are used, only the first active stage will have proper access to the variable. The value read by other stages is undefined.
FragCoord-
Decorating a variable with the
FragCoordbuilt-in decoration will make that variable contain the framebuffer coordinate of the fragment being processed. The (x,y) coordinate (0,0) is the upper left corner of the upper left pixel in the framebuffer.When Sample Shading is enabled, the x and y components of
FragCoordreflect the location of one of the samples corresponding to the shader invocation.Otherwise, the x and y components of
FragCoordreflect the location of the center of the fragment.The z component of
FragCoordis the interpolated depth value of the primitive.The w component is the interpolated .
The
Centroidinterpolation decoration is ignored, but allowed, onFragCoord.
FragDepth-
To have a shader supply a fragment-depth value, the shader must declare the
DepthReplacingexecution mode. Such a shader’s fragment-depth value will come from the variable decorated with theFragDepthbuilt-in decoration.This value will be used for any subsequent depth testing performed by the implementation or writes to the depth attachment. See fragment shader depth replacement for details.
FragInvocationCountEXT-
Decorating a variable with the
FragInvocationCountEXTbuilt-in decoration will make that variable contain the maximum number of fragment shader invocations for the fragment, as determined byminSampleShading.If Sample Shading is not enabled,
FragInvocationCountEXTwill be filled with a value of 1.
FragSizeEXT-
Decorating a variable with the
FragSizeEXTbuilt-in decoration will make that variable contain the dimensions in pixels of the area that the fragment covers for that invocation.If fragment density map is not enabled,
FragSizeEXTwill be filled with a value of (1,1).
FragStencilRefEXT-
Decorating a variable with the
FragStencilRefEXTbuilt-in decoration will make that variable contain the new stencil reference value for all samples covered by the fragment. This value will be used as the stencil reference value used in stencil testing.To write to
FragStencilRefEXT, a shader must declare theStencilRefReplacingEXTexecution mode. If a shader declares theStencilRefReplacingEXTexecution mode and there is an execution path through the shader that does not setFragStencilRefEXT, then the fragment’s stencil reference value is undefined for executions of the shader that take that path.Only the least significant s bits of the integer value of the variable decorated with
FragStencilRefEXTare considered for stencil testing, where s is the number of bits in the stencil framebuffer attachment, and higher order bits are discarded.See fragment shader stencil reference replacement for more details.
FragmentSizeNV-
Decorating a variable with the
FragmentSizeNVbuilt-in decoration will make that variable contain the width and height of the fragment.
FrontFacing-
Decorating a variable with the
FrontFacingbuilt-in decoration will make that variable contain whether the fragment is front or back facing. This variable is non-zero if the current fragment is considered to be part of a front-facing polygon primitive or of a non-polygon primitive and is zero if the fragment is considered to be part of a back-facing polygon primitive.
FullyCoveredEXT-
Decorating a variable with the
FullyCoveredEXTbuilt-in decoration will make that variable indicate whether the fragment area is fully covered by the generating primitive. This variable is non-zero if conservative rasterization is enabled and the current fragment area is fully covered by the generating primitive, and is zero if the fragment is not covered or partially covered, or conservative rasterization is disabled.
GlobalInvocationId-
Decorating a variable with the
GlobalInvocationIdbuilt-in decoration will make that variable contain the location of the current invocation within the global workgroup. Each component is equal to the index of the local workgroup multiplied by the size of the local workgroup plusLocalInvocationId.
HelperInvocation-
Decorating a variable with the
HelperInvocationbuilt-in decoration will make that variable contain whether the current invocation is a helper invocation. This variable is non-zero if the current fragment being shaded is a helper invocation and zero otherwise. A helper invocation is an invocation of the shader that is produced to satisfy internal requirements such as the generation of derivatives.
|
Note
It is very likely that a helper invocation will have a value of
|
HitKindKHR-
A variable decorated with the
HitKindKHRdecoration will describe the intersection that triggered the execution of the current shader. The values are determined by the intersection shader. For user-defined intersection shaders this is the value that was passed to the “Hit Kind” operand ofOpReportIntersectionKHR. For triangle intersection candidates, this will be one ofHitKindFrontFacingTriangleKHRorHitKindBackFacingTriangleKHR.
HitTNV-
A variable decorated with the
HitTNVdecoration is equivalent to a variable decorated with theRayTmaxKHRdecoration.
IncomingRayFlagsKHR-
A variable with the
IncomingRayFlagsKHRdecoration will contain the ray flags passed in to the trace call that invoked this particular shader. Setting pipeline flags on the raytracing pipeline must not cause any corresponding flags to be set in variables with this decoration.
InstanceCustomIndexKHR-
A variable decorated with the
InstanceCustomIndexKHRdecoration will contain the application-defined value of the instance that intersects the current ray. This variable contains the value that was specified in VkAccelerationStructureInstanceKHR::instanceCustomIndexfor the current acceleration structure instance in the lower 24 bits and the upper 8 bits will be zero.
InstanceId-
Decorating a variable in an intersection, any-hit, or closest hit shader with the
InstanceIddecoration will make that variable contain the index of the instance that intersects the current ray.
InvocationId-
Decorating a variable with the
InvocationIdbuilt-in decoration will make that variable contain the index of the current shader invocation in a geometry shader, or the index of the output patch vertex in a tessellation control shader.In a geometry shader, the index of the current shader invocation ranges from zero to the number of instances declared in the shader minus one. If the instance count of the geometry shader is one or is not specified, then
InvocationIdwill be zero.
InvocationsPerPixelNV-
Decorating a variable with the
InvocationsPerPixelNVbuilt-in decoration will make that variable contain the maximum number of fragment shader invocations per pixel, as derived from the effective shading rate for the fragment. If a primitive does not fully cover a pixel, the number of fragment shader invocations for that pixel may be less than the value ofInvocationsPerPixelNV. If the shading rate indicates a fragment covering multiple pixels, thenInvocationsPerPixelNVwill be one.
InstanceIndex-
Decorating a variable in a vertex shader with the
InstanceIndexbuilt-in decoration will make that variable contain the index of the instance that is being processed by the current vertex shader invocation.InstanceIndexbegins at thefirstInstanceparameter to vkCmdDraw or vkCmdDrawIndexed or at thefirstInstancemember of a structure consumed by vkCmdDrawIndirect or vkCmdDrawIndexedIndirect.
LaunchIdKHR-
A variable decorated with the
LaunchIdKHRdecoration will specify the index of the work item being processed. One work item is generated for each of thewidth×height×depthitems dispatched by a vkCmdTraceRaysKHR command. All shader invocations inherit the same value for variables decorated withLaunchIdKHR.
LaunchSizeKHR-
A variable decorated with the
LaunchSizeKHRdecoration will contain thewidth,height, anddepthdimensions passed to the vkCmdTraceRaysKHR command that initiated this shader execution. Thewidthis in the first component, theheightis in the second component, and thedepthis in the third component.
Layer-
Decorating a variable with the
Layerbuilt-in decoration will make that variable contain the select layer of a multi-layer framebuffer attachment.In a mesh, vertex, tessellation evaluation, or geometry shader, any variable decorated with
Layercan be written with the framebuffer layer index to which the primitive produced by that shader will be directed.The last active pre-rasterization shader stage (in pipeline order) controls the
Layerthat is used. Outputs in previous shader stages are not used, even if the last stage fails to write theLayer.If the last active pre-rasterization shader stage shader entry point’s interface does not include a variable decorated with
Layer, then the first layer is used. If a pre-rasterization shader stage shader entry point’s interface includes a variable decorated withLayer, it must write the same value toLayerfor all output vertices of a given primitive. If theLayervalue is less than 0 or greater than or equal to the number of layers in the framebuffer, then primitives may still be rasterized, fragment shaders may be executed, and the framebuffer values for all layers are undefined.If a variable with the
Layerdecoration is also decorated withViewportRelativeNV, then theViewportIndexis added to the layer that is used for rendering and that is made available in the fragment shader. If the shader writes to a variable decoratedViewportMaskNV, then the layer selected has a different value for each viewport a primitive is rendered to.In a fragment shader, a variable decorated with
Layercontains the layer index of the primitive that the fragment invocation belongs to.
LayerPerViewNV-
Decorating a variable with the
LayerPerViewNVbuilt-in decoration will make that variable contain the per-view layer information. The per-view layer has the same semantics asLayer, for each view.
LocalInvocationId-
Decorating a variable with the
LocalInvocationIdbuilt-in decoration will make that variable contain the location of the current task, mesh, or compute shader invocation within the local workgroup. Each component ranges from zero through to the size of the workgroup in that dimension minus one.
|
Note
If the size of the workgroup in a particular dimension is one, then the
|
LocalInvocationIndex-
Decorating a variable with the
LocalInvocationIndexbuilt-in decoration will make that variable contain a one-dimensional representation ofLocalInvocationId. This is computed as:LocalInvocationIndex = LocalInvocationId.z * WorkgroupSize.x * WorkgroupSize.y + LocalInvocationId.y * WorkgroupSize.x + LocalInvocationId.x;
MeshViewCountNV-
Decorating a variable with the
MeshViewCountNVbuilt-in decoration will make that variable contain the number of views processed by the current mesh or task shader invocations.
MeshViewIndicesNV-
Decorating a variable with the
MeshViewIndicesNVbuilt-in decoration will make that variable contain the mesh view indices. The mesh view indices is an array of values where each element holds the view number of one of the views being processed by the current mesh or task shader invocations. The values of array elements with indices greater than or equal toMeshViewCountNVare undefined. If the value ofMeshViewIndicesNV[i] is j, then any outputs decorated withPerViewNVwill take on the value of array element i when processing primitives for view index j.
NumSubgroups-
Decorating a variable with the
NumSubgroupsbuilt-in decoration will make that variable contain the number of subgroups in the local workgroup.
NumWorkgroups-
Decorating a variable with the
NumWorkgroupsbuilt-in decoration will make that variable contain the number of local workgroups that are part of the dispatch that the invocation belongs to. Each component is equal to the values of the workgroup count parameters passed into the dispatching commands.
ObjectRayDirectionKHR-
A variable decorated with the
ObjectRayDirectionKHRdecoration will specify the direction of the ray being processed, in object space.
ObjectRayOriginKHR-
A variable decorated with the
ObjectRayOriginKHRdecoration will specify the origin of the ray being processed, in object space.
ObjectToWorldKHR-
A variable decorated with the
ObjectToWorldKHRdecoration will contain the current object-to-world transformation matrix, which is determined by the instance of the current intersection.
PatchVertices-
Decorating a variable with the
PatchVerticesbuilt-in decoration will make that variable contain the number of vertices in the input patch being processed by the shader. In a Tessellation Control Shader, this is the same as the name:patchControlPoints member of VkPipelineTessellationStateCreateInfo. In a Tessellation Evaluation Shader,PatchVerticesis equal to the tessellation control output patch size. When the same shader is used in different pipelines where the patch sizes are configured differently, the value of thePatchVerticesvariable will also differ.
PointCoord-
Decorating a variable with the
PointCoordbuilt-in decoration will make that variable contain the coordinate of the current fragment within the point being rasterized, normalized to the size of the point with origin in the upper left corner of the point, as described in Basic Point Rasterization. If the primitive the fragment shader invocation belongs to is not a point, then the variable decorated withPointCoordcontains an undefined value.
|
Note
Depending on how the point is rasterized, |
PointSize-
Decorating a variable with the
PointSizebuilt-in decoration will make that variable contain the size of point primitives. The value written to the variable decorated withPointSizeby the last pre-rasterization shader stage in the pipeline is used as the framebuffer-space size of points produced by rasterization.
|
Note
When |
Position-
Decorating a variable with the
Positionbuilt-in decoration will make that variable contain the position of the current vertex. In the last pre-rasterization shader stage, the value of the variable decorated withPositionis used in subsequent primitive assembly, clipping, and rasterization operations.
|
Note
When |
PositionPerViewNV-
Decorating a variable with the
PositionPerViewNVbuilt-in decoration will make that variable contain the position of the current vertex, for each view.Elements of the array correspond to views in a multiview subpass, and those elements corresponding to views in the view mask of the subpass the shader is compiled against will be used as the position value for those views. For the final pre-rasterization shader stage in the pipeline, values written to an output variable decorated with
PositionPerViewNVare used in subsequent primitive assembly, clipping, and rasterization operations, as withPosition.PositionPerViewNVoutput in an earlier pre-rasterization shader stage is available as an input in the subsequent pre-rasterization shader stage.If a shader is compiled against a subpass that has the
VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVXbit set, then the position values for each view must not differ in any component other than the X component. If the values do differ, one will be chosen in an implementation-dependent manner.
PrimitiveCountNV-
Decorating a variable with the
PrimitiveCountNVdecoration will make that variable contain the primitive count. The primitive count specifies the number of primitives in the output mesh produced by the mesh shader that will be processed by subsequent pipeline stages.
PrimitiveId-
Decorating a variable with the
PrimitiveIdbuilt-in decoration will make that variable contain the index of the current primitive.The index of the first primitive generated by a drawing command is zero, and the index is incremented after every individual point, line, or triangle primitive is processed.
For triangles drawn as points or line segments (see Polygon Mode), the primitive index is incremented only once, even if multiple points or lines are eventually drawn.
Variables decorated with
PrimitiveIdare reset to zero between each instance drawn.Restarting a primitive topology using primitive restart has no effect on the value of variables decorated with
PrimitiveId.In tessellation control and tessellation evaluation shaders, it will contain the index of the patch within the current set of rendering primitives that corresponds to the shader invocation.
In a geometry shader, it will contain the number of primitives presented as input to the shader since the current set of rendering primitives was started.
In a fragment shader, it will contain the primitive index written by the mesh shader if a mesh shader is present, or the primitive index written by the geometry shader if a geometry shader is present, or with the value that would have been presented as input to the geometry shader had it been present.
In an intersection, any-hit, or closest hit shader, it will contain the index within the geometry of the triangle or bounding box being processed.
|
Note
When the The fragment shader using |
PrimitiveIndicesNV-
Decorating a variable with the
PrimitiveIndicesNVdecoration will make that variable contain the output array of vertex index values. Depending on the output primitive type declared using the execution mode, the indices are split into groups of one (OutputPoints), two (OutputLinesNV), or three (OutputTriangles) indices and each group generates a primitive.
PrimitiveShadingRateKHR-
Decorating a variable with the
PrimitiveShadingRateKHRbuilt-in decoration will make that variable contain the primitive fragment shading rate.The value written to the variable decorated with
PrimitiveShadingRateKHRby the last pre-rasterization shader stage in the pipeline is used as the primitive fragment shading rate. Outputs in previous shader stages are ignored.If the last active pre-rasterization shader stage shader entry point’s interface does not include a variable decorated with
PrimitiveShadingRateKHR, then it is as if the shader specified a fragment shading rate value of 0, indicating a horizontal and vertical rate of 1 pixel.If a shader has
PrimitiveShadingRateKHRin the output interface and there is an execution path through the shader that does not write to it, its value is undefined for executions of the shader that take that path.
RayGeometryIndexKHR-
A variable decorated with the
RayGeometryIndexKHRdecoration will contain the geometry index for the acceleration structure geometry currently being shaded.
RayTmaxKHR-
A variable decorated with the
RayTmaxKHRdecoration will contain the parametric tmax value of the ray being processed. The value is independent of the space in which the ray origin and direction exist. The value is initialized to the parameter passed intoOpTraceRayKHR.The tmax value changes throughout the lifetime of the ray that produced the intersection. In the closest hit shader, the value reflects the closest distance to the intersected primitive. In the any-hit shader, it reflects the distance to the primitive currently being intersected. In the intersection shader, it reflects the distance to the closest primitive intersected so far or the initial value. The value can change in the intersection shader after calling
OpReportIntersectionKHRif the corresponding any-hit shader does not ignore the intersection. In a miss shader, the value is identical to the parameter passed intoOpTraceRayKHR.
RayTminKHR-
A variable decorated with the
RayTminKHRdecoration will contain the parametric tmin value of the ray being processed. The value is independent of the space in which the ray origin and direction exist. The value is the parameter passed intoOpTraceRayKHR.The tmin value remains constant for the duration of the ray query.
SampleId-
Decorating a variable with the
SampleIdbuilt-in decoration will make that variable contain the coverage index for the current fragment shader invocation.SampleIdranges from zero to the number of samples in the framebuffer minus one. If a fragment shader entry point’s interface includes an input variable decorated withSampleId, Sample Shading is considered enabled with aminSampleShadingvalue of 1.0.
SampleMask-
Decorating a variable with the
SampleMaskbuilt-in decoration will make any variable contain the sample mask for the current fragment shader invocation.A variable in the
Inputstorage class decorated withSampleMaskwill contain a bitmask of the set of samples covered by the primitive generating the fragment during rasterization. It has a sample bit set if and only if the sample is considered covered for this fragment shader invocation.SampleMask[] is an array of integers. Bits are mapped to samples in a manner where bit B of mask M (SampleMask[M]) corresponds to sample 32 × M + B.A variable in the
Outputstorage class decorated withSampleMaskis an array of integers forming a bit array in a manner similar to an input variable decorated withSampleMask, but where each bit represents coverage as computed by the shader. This computedSampleMaskis combined with the generated coverage mask in the multisample coverage operation.Variables decorated with
SampleMaskmust be either an unsized array, or explicitly sized to be no larger than the implementation-dependent maximum sample-mask (as an array of 32-bit elements), determined by the maximum number of samples.If a fragment shader entry point’s interface includes an output variable decorated with
SampleMask, the sample mask will be undefined for any array elements of any fragment shader invocations that fail to assign a value. If a fragment shader entry point’s interface does not include an output variable decorated withSampleMask, the sample mask has no effect on the processing of a fragment.
SamplePosition-
Decorating a variable with the
SamplePositionbuilt-in decoration will make that variable contain the sub-pixel position of the sample being shaded. The top left of the pixel is considered to be at coordinate (0,0) and the bottom right of the pixel is considered to be at coordinate (1,1).If the render pass has a fragment density map attachment, the variable will instead contain the sub-fragment position of the sample being shaded. The top left of the fragment is considered to be at coordinate (0,0) and the bottom right of the fragment is considered to be at coordinate (1,1) for any fragment area.
If a fragment shader entry point’s interface includes an input variable decorated with
SamplePosition, Sample Shading is considered enabled with aminSampleShadingvalue of 1.0.If the current pipeline uses custom sample locations the value of any variable decorated with the
SamplePositionbuilt-in decoration is undefined.
ShadingRateKHR-
Decorating a variable with the
ShadingRateKHRbuilt-in decoration will make that variable contain the fragment shading rate for the current fragment invocation.
SMCountNV-
Decorating a variable with the
SMCountNVbuilt-in decoration will make that variable contain the number of SMs on the device.
SMIDNV-
Decorating a variable with the
SMIDNVbuilt-in decoration will make that variable contain the ID of the SM on which the current shader invocation is running. This variable is in the range [0,SMCountNV-1].
SubgroupId-
Decorating a variable with the
SubgroupIdbuilt-in decoration will make that variable contain the index of the subgroup within the local workgroup. This variable is in range [0,NumSubgroups-1].
SubgroupEqMask-
Decorating a variable with the
SubgroupEqMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bit corresponding to theSubgroupLocalInvocationIdis set in the variable decorated withSubgroupEqMask. All other bits are set to zero.SubgroupEqMaskKHRis an alias ofSubgroupEqMask.
SubgroupGeMask-
Decorating a variable with the
SubgroupGeMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations greater than or equal toSubgroupLocalInvocationIdthroughSubgroupSize-1 are set in the variable decorated withSubgroupGeMask. All other bits are set to zero.SubgroupGeMaskKHRis an alias ofSubgroupGeMask.
SubgroupGtMask-
Decorating a variable with the
SubgroupGtMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations greater thanSubgroupLocalInvocationIdthroughSubgroupSize-1 are set in the variable decorated withSubgroupGtMask. All other bits are set to zero.SubgroupGtMaskKHRis an alias ofSubgroupGtMask.
SubgroupLeMask-
Decorating a variable with the
SubgroupLeMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations less than or equal toSubgroupLocalInvocationIdare set in the variable decorated withSubgroupLeMask. All other bits are set to zero.SubgroupLeMaskKHRis an alias ofSubgroupLeMask.
SubgroupLtMask-
Decorating a variable with the
SubgroupLtMaskbuiltin decoration will make that variable contain the subgroup mask of the current subgroup invocation. The bits corresponding to the invocations less thanSubgroupLocalInvocationIdare set in the variable decorated withSubgroupLtMask. All other bits are set to zero.SubgroupLtMaskKHRis an alias ofSubgroupLtMask.
SubgroupLocalInvocationId-
Decorating a variable with the
SubgroupLocalInvocationIdbuiltin decoration will make that variable contain the index of the invocation within the subgroup. This variable is in range [0,SubgroupSize-1].If
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BITis specified, or ifmoduledeclares SPIR-V version 1.6 or higher, and the local workgroup size in the X dimension of thestageis a multiple ofSubgroupSize, full subgroups are enabled for that pipeline stage. When full subgroups are enabled, subgroups must be launched with all invocations active, i.e., there is an active invocation withSubgroupLocalInvocationIdfor each value in range [0,SubgroupSize-1].
|
Note
There is no direct relationship between index = If full subgroups are not enabled, some subgroups may be dispatched with inactive invocations that do not correspond to a local workgroup invocation, making the value of index unreliable. |
|
Note
|
SubgroupSize-
Decorating a variable with the
SubgroupSizebuiltin decoration will make that variable contain the implementation-dependent number of invocations in a subgroup. This value must be a power-of-two integer.If the pipeline was created with the
VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BITflag set, or the SPIR-Vmoduleis at least version 1.6, theSubgroupSizedecorated variable will contain the subgroup size for each subgroup that gets dispatched. This value must be betweenminSubgroupSizeandmaxSubgroupSizeand must be uniform with subgroup scope. The value may vary across a single draw call, and for fragment shaders may vary across a single primitive. In compute dispatches,SubgroupSizemust be uniform with command scope.If the pipeline was created with a chained VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure, the
SubgroupSizedecorated variable will matchrequiredSubgroupSize.If the pipeline stage SPIR-V
moduleis less than version 1.6 and was not created with theVK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BITflag set and no VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure was chained, the variable decorated withSubgroupSizewill matchsubgroupSize.The maximum number of invocations that an implementation can support per subgroup is 128.
|
Note
The old behavior for |
TaskCountNV-
Decorating a variable with the
TaskCountNVdecoration will make that variable contain the task count. The task count specifies the number of subsequent mesh shader workgroups that get generated upon completion of the task shader.
TessCoord-
Decorating a variable with the
TessCoordbuilt-in decoration will make that variable contain the three-dimensional (u,v,w) barycentric coordinate of the tessellated vertex within the patch. u, v, and w are in the range [0,1] and vary linearly across the primitive being subdivided. For the tessellation modes ofQuadsorIsoLines, the third component is always zero.
TessLevelOuter-
Decorating a variable with the
TessLevelOuterbuilt-in decoration will make that variable contain the outer tessellation levels for the current patch.In tessellation control shaders, the variable decorated with
TessLevelOutercan be written to, controlling the tessellation factors for the resulting patch. These values are used by the tessellator to control primitive tessellation and can be read by tessellation evaluation shaders.In tessellation evaluation shaders, the variable decorated with
TessLevelOutercan read the values written by the tessellation control shader.
TessLevelInner-
Decorating a variable with the
TessLevelInnerbuilt-in decoration will make that variable contain the inner tessellation levels for the current patch.In tessellation control shaders, the variable decorated with
TessLevelInnercan be written to, controlling the tessellation factors for the resulting patch. These values are used by the tessellator to control primitive tessellation and can be read by tessellation evaluation shaders.In tessellation evaluation shaders, the variable decorated with
TessLevelInnercan read the values written by the tessellation control shader.
VertexIndex-
Decorating a variable with the
VertexIndexbuilt-in decoration will make that variable contain the index of the vertex that is being processed by the current vertex shader invocation. For non-indexed draws, this variable begins at thefirstVertexparameter to vkCmdDraw or thefirstVertexmember of a structure consumed by vkCmdDrawIndirect and increments by one for each vertex in the draw. For indexed draws, its value is the content of the index buffer for the vertex plus thevertexOffsetparameter to vkCmdDrawIndexed or thevertexOffsetmember of the structure consumed by vkCmdDrawIndexedIndirect.
|
Note
|
ViewIndex-
The
ViewIndexdecoration can be applied to a shader input which will be filled with the index of the view that is being processed by the current shader invocation.If multiview is enabled in the render pass, this value will be one of the bits set in the view mask of the subpass the pipeline is compiled against. If multiview is not enabled in the render pass, this value will be zero.
ViewportIndex-
Decorating a variable with the
ViewportIndexbuilt-in decoration will make that variable contain the index of the viewport.In a mesh, vertex, tessellation evaluation, or geometry shader, the variable decorated with
ViewportIndexcan be written to with the viewport index to which the primitive produced by that shader will be directed.The selected viewport index is used to select the viewport transform, scissor rectangle, and exclusive scissor rectangle.
The last active pre-rasterization shader stage (in pipeline order) controls the
ViewportIndexthat is used. Outputs in previous shader stages are not used, even if the last stage fails to write theViewportIndex.If the last active pre-rasterization shader stage shader entry point’s interface does not include a variable decorated with
ViewportIndex, then the first viewport is used. If a pre-rasterization shader stage shader entry point’s interface includes a variable decorated withViewportIndex, it must write the same value toViewportIndexfor all output vertices of a given primitive.In a fragment shader, the variable decorated with
ViewportIndexcontains the viewport index of the primitive that the fragment invocation belongs to.
ViewportMaskNV-
Decorating a variable with the
ViewportMaskNVbuilt-in decoration will make that variable contain the viewport mask.In a mesh, vertex, tessellation evaluation, or geometry shader, the variable decorated with
ViewportMaskNVcan be written to with the mask of which viewports the primitive produced by that shader will directed.The
ViewportMaskNVvariable must be an array that has ⌈(VkPhysicalDeviceLimits::maxViewports/ 32)⌉ elements. When a shader writes to this variable, bit B of element M controls whether a primitive is emitted to viewport 32 × M + B. The viewports indicated by the mask are used to select the viewport transform, scissor rectangle, and exclusive scissor rectangle that a primitive will be transformed by.The last active pre-rasterization shader stage (in pipeline order) controls the
ViewportMaskNVthat is used. Outputs in previous shader stages are not used, even if the last stage fails to write theViewportMaskNV. WhenViewportMaskNVis written by the final pre-rasterization shader stage, any variable decorated withViewportIndexin the fragment shader will have the index of the viewport that was used in generating that fragment.If a pre-rasterization shader stage shader entry point’s interface includes a variable decorated with
ViewportMaskNV, it must write the same value toViewportMaskNVfor all output vertices of a given primitive.
ViewportMaskPerViewNV-
Decorating a variable with the
ViewportMaskPerViewNVbuilt-in decoration will make that variable contain the mask of viewports primitives are broadcast to, for each view.The value written to an element of
ViewportMaskPerViewNVin the last pre-rasterization shader stage is a bitmask indicating which viewports the primitive will be directed to. The primitive will be broadcast to the viewport corresponding to each non-zero bit of the bitmask, and that viewport index is used to select the viewport transform, scissor rectangle, and exclusive scissor rectangle, for each view. The same values must be written to all vertices in a given primitive, or else the set of viewports used for that primitive is undefined.Elements of the array correspond to views in a multiview subpass, and those elements corresponding to views in the view mask of the subpass the shader is compiled against will be used as the viewport mask value for those views.
ViewportMaskPerViewNVoutput in an earlier pre-rasterization shader stage is not available as an input in the subsequent pre-rasterization shader stage.Although
ViewportMaskNVis an array,ViewportMaskPerViewNVis not a two-dimensional array. Instead,ViewportMaskPerViewNVis limited to 32 viewports.
WarpsPerSMNV-
Decorating a variable with the
WarpsPerSMNVbuilt-in decoration will make that variable contain the maximum number of warps executing on a SM.
WarpIDNV-
Decorating a variable with the
WarpIDNVbuilt-in decoration will make that variable contain the ID of the warp on a SM on which the current shader invocation is running. This variable is in the range [0,WarpsPerSMNV-1].
WorkgroupId-
Decorating a variable with the
WorkgroupIdbuilt-in decoration will make that variable contain the global workgroup that the current invocation is a member of. Each component ranges from a base value to a base + count value, based on the parameters passed into the dispatching commands.
WorkgroupSize
|
Note
SPIR-V 1.6 deprecated |
Decorating an object with the WorkgroupSize built-in decoration will
make that object contain the dimensions of a local workgroup.
If an object is decorated with the WorkgroupSize decoration, this takes
precedence over any LocalSize
or LocalSizeId
execution mode.
WorldRayDirectionKHR-
A variable decorated with the
WorldRayDirectionKHRdecoration will specify the direction of the ray being processed, in world space. The value is the parameter passed intoOpTraceRayKHR.
WorldRayOriginKHR-
A variable decorated with the
WorldRayOriginKHRdecoration will specify the origin of the ray being processed, in world space. The value is the parameter passed intoOpTraceRayKHR.
WorldToObjectKHR-
A variable decorated with the
WorldToObjectKHRdecoration will contain the current world-to-object transformation matrix, which is determined by the instance of the current intersection.
16. Image Operations
16.1. Image Operations Overview
Vulkan Image Operations are operations performed by those SPIR-V Image
Instructions which take an OpTypeImage (representing a
VkImageView) or OpTypeSampledImage (representing a
(VkImageView, VkSampler) pair).
Read, write, and atomic operations also take texel coordinates as operands,
and return a value based on a neighborhood of texture elements (texels)
within the image.
Query operations return properties of the bound image or of the lookup
itself.
The “Depth” operand of OpTypeImage is ignored.
|
Note
Texel is a term which is a combination of the words texture and element. Early interactive computer graphics supported texture operations on textures, a small subset of the image operations on images described here. The discrete samples remain essentially equivalent, however, so we retain the historical term texel to refer to them. |
Image Operations include the functionality of the following SPIR-V Image Instructions:
-
OpImageSample*andOpImageSparseSample*read one or more neighboring texels of the image, and filter the texel values based on the state of the sampler.-
Instructions with
ImplicitLodin the name determine the LOD used in the sampling operation based on the coordinates used in neighboring fragments. -
Instructions with
ExplicitLodin the name determine the LOD used in the sampling operation based on additional coordinates. -
Instructions with
Projin the name apply homogeneous projection to the coordinates.
-
-
OpImageFetchandOpImageSparseFetchreturn a single texel of the image. No sampler is used. -
OpImage*GatherandOpImageSparse*Gatherread neighboring texels and return a single component of each. -
OpImageRead(andOpImageSparseRead) andOpImageWriteread and write, respectively, a texel in the image. No sampler is used. -
OpImageSampleFootprintNVidentifies and returns information about the set of texels in the image that would be accessed by an equivalentOpImageSample*instruction. -
OpImage*Dref*instructions apply depth comparison on the texel values. -
OpImageSparse*instructions additionally return a sparse residency code. -
OpImageQuerySize,OpImageQuerySizeLod,OpImageQueryLevels, andOpImageQuerySamplesreturn properties of the image descriptor that would be accessed. The image itself is not accessed. -
OpImageQueryLodreturns the lod parameters that would be used in a sample operation. The actual operation is not performed.
16.1.1. Texel Coordinate Systems
Images are addressed by texel coordinates. There are three texel coordinate systems:
-
normalized texel coordinates [0.0, 1.0]
-
unnormalized texel coordinates [0.0, width / height / depth)
-
integer texel coordinates [0, width / height / depth)
SPIR-V OpImageFetch, OpImageSparseFetch, OpImageRead,
OpImageSparseRead, and OpImageWrite instructions use integer texel
coordinates.
Other image instructions can use either normalized or unnormalized texel
coordinates (selected by the unnormalizedCoordinates state of the
sampler used in the instruction), but there are
limitations on what operations, image
state, and sampler state is supported.
Normalized coordinates are logically
converted to unnormalized as part of
image operations, and certain steps are
only performed on normalized coordinates.
The array layer coordinate is always treated as unnormalized even when other
coordinates are normalized.
Normalized texel coordinates are referred to as (s,t,r,q,a), with the coordinates having the following meanings:
-
s: Coordinate in the first dimension of an image.
-
t: Coordinate in the second dimension of an image.
-
r: Coordinate in the third dimension of an image.
-
(s,t,r) are interpreted as a direction vector for Cube images.
-
-
q: Fourth coordinate, for homogeneous (projective) coordinates.
-
a: Coordinate for array layer.
The coordinates are extracted from the SPIR-V operand based on the
dimensionality of the image variable and type of instruction.
For Proj instructions, the components are in order (s, [t,] [r,]
q), with t and r being conditionally present based on the
Dim of the image.
For non-Proj instructions, the coordinates are (s [,t] [,r]
[,a]), with t and r being conditionally present based on the
Dim of the image and a being conditionally present based on the
Arrayed property of the image.
Projective image instructions are not supported on Arrayed images.
Unnormalized texel coordinates are referred to as (u,v,w,a), with the coordinates having the following meanings:
-
u: Coordinate in the first dimension of an image.
-
v: Coordinate in the second dimension of an image.
-
w: Coordinate in the third dimension of an image.
-
a: Coordinate for array layer.
Only the u and v coordinates are directly extracted from the
SPIR-V operand, because only 1D and 2D (non-Arrayed) dimensionalities
support unnormalized coordinates.
The components are in order (u [,v]), with v being conditionally
present when the dimensionality is 2D.
When normalized coordinates are converted to unnormalized coordinates, all
four coordinates are used.
Integer texel coordinates are referred to as (i,j,k,l,n), with the coordinates having the following meanings:
-
i: Coordinate in the first dimension of an image.
-
j: Coordinate in the second dimension of an image.
-
k: Coordinate in the third dimension of an image.
-
l: Coordinate for array layer.
-
n: Index of the sample within the texel.
They are extracted from the SPIR-V operand in order (i [,j] [,k] [,l]
[,n]), with j and k conditionally present based on the Dim
of the image, and l conditionally present based on the Arrayed
property of the image.
n is conditionally present and is taken from the Sample image
operand.
For all coordinate types, unused coordinates are assigned a value of zero.
The Texel Coordinate Systems - For the example shown of an 8×4 texel two dimensional image.
-
Normalized texel coordinates:
-
The s coordinate goes from 0.0 to 1.0.
-
The t coordinate goes from 0.0 to 1.0.
-
-
Unnormalized texel coordinates:
-
The u coordinate within the range 0.0 to 8.0 is within the image, otherwise it is outside the image.
-
The v coordinate within the range 0.0 to 4.0 is within the image, otherwise it is outside the image.
-
-
Integer texel coordinates:
-
The i coordinate within the range 0 to 7 addresses texels within the image, otherwise it is outside the image.
-
The j coordinate within the range 0 to 3 addresses texels within the image, otherwise it is outside the image.
-
-
Also shown for linear filtering:
-
Given the unnormalized coordinates (u,v), the four texels selected are i0j0, i1j0, i0j1, and i1j1.
-
The fractions α and β.
-
Given the offset Δi and Δj, the four texels selected by the offset are i0j'0, i1j'0, i0j'1, and i1j'1.
-
|
Note
For formats with reduced-resolution components, Δi and Δj are relative to the resolution of the highest-resolution component, and therefore may be divided by two relative to the unnormalized coordinate space of the lower-resolution components. |
The Texel Coordinate Systems - For the example shown of an 8×4 texel two dimensional image.
-
Texel coordinates as above. Also shown for nearest filtering:
-
Given the unnormalized coordinates (u,v), the texel selected is ij.
-
Given the offset Δi and Δj, the texel selected by the offset is ij'.
-
For corner-sampled images, the texel samples are located at the grid intersections instead of the texel centers.
16.2. Conversion Formulas
|
editing-note
(Bill) These Conversion Formulas will likely move to Section 2.7 Fixed-Point Data Conversions (RGB to sRGB and sRGB to RGB) and section 2.6 Numeric Representation and Computation (RGB to Shared Exponent and Shared Exponent to RGB) |
16.2.1. RGB to Shared Exponent Conversion
An RGB color (red, green, blue) is transformed to a shared exponent color (redshared, greenshared, blueshared, expshared) as follows:
First, the components (red, green, blue) are clamped to (redclamped, greenclamped, blueclamped) as:
-
redclamped = max(0, min(sharedexpmax, red))
-
greenclamped = max(0, min(sharedexpmax, green))
-
blueclamped = max(0, min(sharedexpmax, blue))
where:
|
Note
NaN, if supported, is handled as in IEEE 754-2008
|
The largest clamped component, maxclamped is determined:
-
maxclamped = max(redclamped, greenclamped, blueclamped)
A preliminary shared exponent exp' is computed:
The shared exponent expshared is computed:
Finally, three integer values in the range 0 to 2N are computed:
16.3. Texel Input Operations
Texel input instructions are SPIR-V image instructions that read from an image. Texel input operations are a set of steps that are performed on state, coordinates, and texel values while processing a texel input instruction, and which are common to some or all texel input instructions. They include the following steps, which are performed in the listed order:
For texel input instructions involving multiple texels (for sampling or gathering), these steps are applied for each texel that is used in the instruction. Depending on the type of image instruction, other steps are conditionally performed between these steps or involving multiple coordinate or texel values.
If Chroma Reconstruction is implicit, Texel Filtering instead takes place during chroma reconstruction, before sampler Y′CBCR conversion occurs.
16.3.1. Texel Input Validation Operations
Texel input validation operations inspect instruction/image/sampler state or coordinates, and in certain circumstances cause the texel value to be replaced or become undefined. There are a series of validations that the texel undergoes.
Instruction/Sampler/Image View Validation
There are a number of cases where a SPIR-V instruction can mismatch with the sampler, the image view, or both, and a number of further cases where the sampler can mismatch with the image view. In such cases the value of the texel returned is undefined.
These cases include:
-
The sampler
borderColoris an integer type and the image viewformatis not one of the VkFormat integer types or a stencil component of a depth/stencil format. -
The sampler
borderColoris a float type and the image viewformatis not one of the VkFormat float types or a depth component of a depth/stencil format. -
The sampler
borderColoris one of the opaque black colors (VK_BORDER_COLOR_FLOAT_OPAQUE_BLACKorVK_BORDER_COLOR_INT_OPAQUE_BLACK) and the image view VkComponentSwizzle for any of the VkComponentMapping components is not the identity swizzle, and VkPhysicalDeviceBorderColorSwizzleFeaturesEXT::borderColorSwizzleFromImagefeature is not enabled, and VkSamplerBorderColorComponentMappingCreateInfoEXT is not specified. -
VkSamplerBorderColorComponentMappingCreateInfoEXT::
components, if specified, has a component swizzle that does not match the component swizzle of the image view, and either component swizzle is not a form of identity swizzle. -
VkSamplerBorderColorComponentMappingCreateInfoEXT::
srgb, if specified, does not match the sRGB encoding of the image view. -
The sampler
borderColoris a custom color (VK_BORDER_COLOR_FLOAT_CUSTOM_EXTorVK_BORDER_COLOR_INT_CUSTOM_EXT) and the supplied VkSamplerCustomBorderColorCreateInfoEXT::customBorderColoris outside the bounds of the values representable in the image view’sformat. -
The sampler
borderColoris a custom color (VK_BORDER_COLOR_FLOAT_CUSTOM_EXTorVK_BORDER_COLOR_INT_CUSTOM_EXT) and the image view VkComponentSwizzle for any of the VkComponentMapping components is not the identity swizzle, and VkPhysicalDeviceBorderColorSwizzleFeaturesEXT::borderColorSwizzleFromImagefeature is not enabled, and VkSamplerBorderColorComponentMappingCreateInfoEXT is not specified. -
The VkImageLayout of any subresource in the image view does not match the VkDescriptorImageInfo::
imageLayoutused to write the image descriptor. -
The SPIR-V Image Format is not compatible with the image view’s
format. -
The sampler
unnormalizedCoordinatesisVK_TRUEand any of the limitations of unnormalized coordinates are violated. -
The sampler was created with
flagscontainingVK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXTand the image was not created withflagscontainingVK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT. -
The sampler was not created with
flagscontainingVK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXTand the image was created withflagscontainingVK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT. -
The sampler was created with
flagscontainingVK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXTand is used with a function that is notOpImageSampleImplicitLodorOpImageSampleExplicitLod, or is used with operandsOffsetorConstOffsets. -
The SPIR-V instruction is one of the
OpImage*Dref*instructions and the samplercompareEnableisVK_FALSE -
The SPIR-V instruction is not one of the
OpImage*Dref*instructions and the samplercompareEnableisVK_TRUE -
The SPIR-V instruction is one of the
OpImage*Dref*instructions, the image viewformatis one of the depth/stencil formats, and the image view aspect is notVK_IMAGE_ASPECT_DEPTH_BIT. -
The SPIR-V instruction’s image variable’s properties are not compatible with the image view:
-
Rules for
viewType:-
VK_IMAGE_VIEW_TYPE_1Dmust haveDim= 1D,Arrayed= 0,MS= 0. -
VK_IMAGE_VIEW_TYPE_2Dmust haveDim= 2D,Arrayed= 0. -
VK_IMAGE_VIEW_TYPE_3Dmust haveDim= 3D,Arrayed= 0,MS= 0. -
VK_IMAGE_VIEW_TYPE_CUBEmust haveDim= Cube,Arrayed= 0,MS= 0. -
VK_IMAGE_VIEW_TYPE_1D_ARRAYmust haveDim= 1D,Arrayed= 1,MS= 0. -
VK_IMAGE_VIEW_TYPE_2D_ARRAYmust haveDim= 2D,Arrayed= 1. -
VK_IMAGE_VIEW_TYPE_CUBE_ARRAYmust haveDim= Cube,Arrayed= 1,MS= 0.
-
-
If the image was created with VkImageCreateInfo::
samplesequal toVK_SAMPLE_COUNT_1_BIT, the instruction must haveMS= 0. -
If the image was created with VkImageCreateInfo::
samplesnot equal toVK_SAMPLE_COUNT_1_BIT, the instruction must haveMS= 1. -
If the
SampledTypeof theOpTypeImagedoes not match the numeric format of the image, as shown in the SPIR-V Sampled Type column of the Interpretation of Numeric Format table. -
If the signedness of any read or sample operation does not match the signedness of the image’s format.
-
-
If the image was created with VkImageCreateInfo::
flagscontainingVK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, the sampler addressing modes must only use a VkSamplerAddressMode ofVK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. -
The SPIR-V instruction is
OpImageSampleFootprintNVwithDim= 2D andaddressModeUoraddressModeVin the sampler is notVK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. -
The SPIR-V instruction is
OpImageSampleFootprintNVwithDim= 3D andaddressModeU,addressModeV, oraddressModeWin the sampler is notVK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. -
The sampler was created with a specified VkSamplerCustomBorderColorCreateInfoEXT::
formatwhich does not match the VkFormat of the image view(s) it is sampling. -
The sampler is sampling an image view of
VK_FORMAT_B4G4R4A4_UNORM_PACK16,VK_FORMAT_B5G6R5_UNORM_PACK16, orVK_FORMAT_B5G5R5A1_UNORM_PACK16format without a specified VkSamplerCustomBorderColorCreateInfoEXT::format.
Only OpImageSample* and OpImageSparseSample* can be used with a
sampler or image view that enables sampler
Y′CBCR conversion.
OpImageFetch, OpImageSparseFetch, OpImage*Gather, and
OpImageSparse*Gather must not be used with a sampler or image view
that enables sampler Y′CBCR conversion.
The ConstOffset and Offset operands must not be used with a
sampler or image view that enables sampler
Y′CBCR conversion.
Integer Texel Coordinate Validation
Integer texel coordinates are validated against the size of the image level, and the number of layers and number of samples in the image. For SPIR-V instructions that use integer texel coordinates, this is performed directly on the integer coordinates. For instructions that use normalized or unnormalized texel coordinates, this is performed on the coordinates that result after conversion to integer texel coordinates.
If the integer texel coordinates do not satisfy all of the conditions
-
0 ≤ i < ws
-
0 ≤ j < hs
-
0 ≤ k < ds
-
0 ≤ l < layers
-
0 ≤ n < samples
where:
-
ws = width of the image level
-
hs = height of the image level
-
ds = depth of the image level
-
layers = number of layers in the image
-
samples = number of samples per texel in the image
then the texel fails integer texel coordinate validation.
There are four cases to consider:
-
Valid Texel Coordinates
-
If the texel coordinates pass validation (that is, the coordinates lie within the image),
then the texel value comes from the value in image memory.
-
-
Border Texel
-
If the texel coordinates fail validation, and
-
If the read is the result of an image sample instruction or image gather instruction, and
-
If the image is not a cube image, or if a sampler created with
VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXTis used,
then the texel is a border texel and texel replacement is performed.
-
-
Invalid Texel
-
If the texel coordinates fail validation, and
-
If the read is the result of an image fetch instruction, image read instruction, or atomic instruction,
then the texel is an invalid texel and texel replacement is performed.
-
-
Cube Map Edge or Corner
Otherwise the texel coordinates lie beyond the edges or corners of the selected cube map face, and Cube map edge handling is performed.
Cube Map Edge Handling
If the texel coordinates lie beyond the edges or corners of the selected
cube map face (as described in the prior section), the following steps are
performed.
Note that this does not occur when using VK_FILTER_NEAREST filtering
within a mip level, since VK_FILTER_NEAREST is treated as using
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
-
Cube Map Edge Texel
-
If the texel lies beyond the selected cube map face in either only i or only j, then the coordinates (i,j) and the array layer l are transformed to select the adjacent texel from the appropriate neighboring face.
-
-
Cube Map Corner Texel
-
If the texel lies beyond the selected cube map face in both i and j, then there is no unique neighboring face from which to read that texel. The texel should be replaced by the average of the three values of the adjacent texels in each incident face. However, implementations may replace the cube map corner texel by other methods. The methods are subject to the constraint that for linear filtering if the three available texels have the same value, the resulting filtered texel must have that value, and for cubic filtering if the twelve available samples have the same value, the resulting filtered texel must have that value.
-
Sparse Validation
If the texel reads from an unbound region of a sparse image, the texel is a sparse unbound texel, and processing continues with texel replacement.
Layout Validation
If all planes of a disjoint multi-planar image are not in the same image layout, the image must not be sampled with sampler Y′CBCR conversion enabled.
16.3.2. Format Conversion
Texels undergo a format conversion from the VkFormat of the image view to a vector of either floating point or signed or unsigned integer components, with the number of components based on the number of components present in the format.
-
Color formats have one, two, three, or four components, according to the format.
-
Depth/stencil formats are one component. The depth or stencil component is selected by the
aspectMaskof the image view.
Each component is converted based on its type and size (as defined in the Format Definition section for each VkFormat), using the appropriate equations in 16-Bit Floating-Point Numbers, Unsigned 11-Bit Floating-Point Numbers, Unsigned 10-Bit Floating-Point Numbers, Fixed-Point Data Conversion, and Shared Exponent to RGB. Signed integer components smaller than 32 bits are sign-extended.
If the image view format is sRGB, the color components are first converted as if they are UNORM, and then sRGB to linear conversion is applied to the R, G, and B components as described in the “sRGB EOTF” section of the Khronos Data Format Specification. The A component, if present, is unchanged.
If the image view format is block-compressed, then the texel value is first decoded, then converted based on the type and number of components defined by the compressed format.
16.3.3. Texel Replacement
A texel is replaced if it is one (and only one) of:
-
a border texel,
-
an invalid texel, or
-
a sparse unbound texel.
Border texels are replaced with a value based on the image format and the
borderColor of the sampler.
The border color is:
Sampler borderColor |
Corresponding Border Color |
|---|---|
|
[Br, Bg, Bb, Ba] = [0.0, 0.0, 0.0, 0.0] |
|
[Br, Bg, Bb, Ba] = [0.0, 0.0, 0.0, 1.0] |
|
[Br, Bg, Bb, Ba] = [1.0, 1.0, 1.0, 1.0] |
|
[Br, Bg, Bb, Ba] = [0, 0, 0, 0] |
|
[Br, Bg, Bb, Ba] = [0, 0, 0, 1] |
|
[Br, Bg, Bb, Ba] = [1, 1, 1, 1] |
|
[Br, Bg, Bb, Ba] = [Ur, Ug, Ub, Ua] |
|
[Br, Bg, Bb, Ba] = [Ur, Ug, Ub, Ua] |
The custom border color (U) may be rounded by implementations prior
to texel replacement, but the error introduced by such a rounding must not
exceed one ULP of the image’s format.
|
Note
The names |
This is substituted for the texel value by replacing the number of components in the image format
| Texel Aspect or Format | Component Assignment |
|---|---|
Depth aspect |
D = Br |
Stencil aspect |
S = Br |
One component color format |
Colorr = Br |
Two component color format |
[Colorr,Colorg] = [Br,Bg] |
Three component color format |
[Colorr,Colorg,Colorb] = [Br,Bg,Bb] |
Four component color format |
[Colorr,Colorg,Colorb,Colora] = [Br,Bg,Bb,Ba] |
The value returned by a read of an invalid texel is undefined, unless that
read operation is from a buffer resource and the robustBufferAccess
feature is enabled.
In that case, an invalid texel is replaced as described by the
robustBufferAccess feature.
If the access is to an image resource and the x, y, z, or layer coordinate
validation fails and
the robustImageAccess feature is
enabled, then zero must be returned for the R, G, and B components, if
present.
Either zero or one must be returned for the A component, if present.
If
If the robustImageAccess2 feature is
enabled, zero values must be returned.
If only the sample index was invalid, the values returned are undefined.
Additionally, if the robustImageAccess
feature is enabled,
but the robustImageAccess2 feature is
not,
any invalid texels may be expanded to four components prior to texel
replacement.
This means that components not present in the image format may be replaced
with 0 or may undergo conversion to RGBA as
normal.
Loads from a null descriptor return a four component color value of all zeros. However, for storage images and storage texel buffers using an explicit SPIR-V Image Format, loads from a null descriptor may return an alpha value of 1 (float or integer, depending on format) if the format does not include alpha.
If the
VkPhysicalDeviceSparseProperties::residencyNonResidentStrict
property is VK_TRUE, a sparse unbound texel is replaced with 0 or 0.0
values for integer and floating-point components of the image format,
respectively.
If residencyNonResidentStrict is VK_FALSE, the value of the
sparse unbound texel is undefined.
16.3.4. Depth Compare Operation
If the image view has a depth/stencil format, the depth component is
selected by the aspectMask, and the operation is an OpImage*Dref*
instruction, a depth comparison is performed.
The result is 1.0 if the comparison evaluates to true, and
0.0 otherwise.
This value replaces the depth component D.
The compare operation is selected by the VkCompareOp value set by
VkSamplerCreateInfo::compareOp.
The reference value from the SPIR-V operand Dref and the texel depth
value Dtex are used as the reference and test values,
respectively, in that operation.
If the image being sampled has an unsigned normalized fixed-point format, then Dref is clamped to [0,1] before the compare operation.
16.3.5. Conversion to RGBA
The texel is expanded from one, two, or three components to four components based on the image base color:
| Texel Aspect or Format | RGBA Color |
|---|---|
Depth aspect |
[Colorr,Colorg,Colorb, Colora] = [D,0,0,one] |
Stencil aspect |
[Colorr,Colorg,Colorb, Colora] = [S,0,0,one] |
One component color format |
[Colorr,Colorg,Colorb, Colora] = [Colorr,0,0,one] |
Two component color format |
[Colorr,Colorg,Colorb, Colora] = [Colorr,Colorg,0,one] |
Three component color format |
[Colorr,Colorg,Colorb, Colora] = [Colorr,Colorg,Colorb,one] |
Four component color format |
[Colorr,Colorg,Colorb, Colora] = [Colorr,Colorg,Colorb,Colora] |
where one = 1.0f for floating-point formats and depth aspects, and one = 1 for integer formats and stencil aspects.
16.3.6. Component Swizzle
All texel input instructions apply a swizzle based on:
-
the VkComponentSwizzle enums in the
componentsmember of the VkImageViewCreateInfo structure for the image being read if sampler Y′CBCR conversion is not enabled, and -
the VkComponentSwizzle enums in the
componentsmember of the VkSamplerYcbcrConversionCreateInfo structure for the sampler Y′CBCR conversion if sampler Y′CBCR conversion is enabled.
The swizzle can rearrange the components of the texel, or substitute zero or one for any components. It is defined as follows for each color component:
where:
If the border color is one of the VK_BORDER_COLOR_*_OPAQUE_BLACK enums
and the VkComponentSwizzle is not the
identity swizzle for all
components, the value of the texel after swizzle is undefined.
16.3.7. Sparse Residency
OpImageSparse* instructions return a structure which includes a
residency code indicating whether any texels accessed by the instruction
are sparse unbound texels.
This code can be interpreted by the OpImageSparseTexelsResident
instruction which converts the residency code to a boolean value.
16.3.8. Chroma Reconstruction
In some color models, the color representation is defined in terms of monochromatic light intensity (often called “luma”) and color differences relative to this intensity, often called “chroma”. It is common for color models other than RGB to represent the chroma components at lower spatial resolution than the luma component. This approach is used to take advantage of the eye’s lower spatial sensitivity to color compared with its sensitivity to brightness. Less commonly, the same approach is used with additive color, since the green component dominates the eye’s sensitivity to light intensity and the spatial sensitivity to color introduced by red and blue is lower.
Lower-resolution components are “downsampled” by resizing them to a lower spatial resolution than the component representing luminance. This process is also commonly known as “chroma subsampling”. There is one luminance sample in each texture texel, but each chrominance sample may be shared among several texels in one or both texture dimensions.
-
“
_444” formats do not spatially downsample chroma values compared with luma: there are unique chroma samples for each texel. -
“
_422” formats have downsampling in the x dimension (corresponding to u or s coordinates): they are sampled at half the resolution of luma in that dimension. -
“
_420” formats have downsampling in the x dimension (corresponding to u or s coordinates) and the y dimension (corresponding to v or t coordinates): they are sampled at half the resolution of luma in both dimensions.
The process of reconstructing a full color value for texture access involves accessing both chroma and luma values at the same location. To generate the color accurately, the values of the lower-resolution components at the location of the luma samples must be reconstructed from the lower-resolution sample locations, an operation known here as “chroma reconstruction” irrespective of the actual color model.
The location of the chroma samples relative to the luma coordinates is
determined by the xChromaOffset and yChromaOffset members of the
VkSamplerYcbcrConversionCreateInfo structure used to create the
sampler Y′CBCR conversion.
The following diagrams show the relationship between unnormalized (u,v) coordinates and (i,j) integer texel positions in the luma component (shown in black, with circles showing integer sample positions) and the texel coordinates of reduced-resolution chroma components, shown as crosses in red.
|
Note
If the chroma values are reconstructed at the locations of the luma samples
by means of interpolation, chroma samples from outside the image bounds are
needed; these are determined according to Wrapping Operation.
These diagrams represent this by showing the bounds of the “chroma texel”
extending beyond the image bounds, and including additional chroma sample
positions where required for interpolation.
The limits of a sample for |
Reconstruction is implemented in one of two ways:
If the format of the image that is to be sampled sets
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT,
or the VkSamplerYcbcrConversionCreateInfo’s
forceExplicitReconstruction is set to VK_TRUE, reconstruction is
performed as an explicit step independent of filtering, described in the
Explicit Reconstruction section.
If the format of the image that is to be sampled does not set
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT
and if the VkSamplerYcbcrConversionCreateInfo’s
forceExplicitReconstruction is set to VK_FALSE, reconstruction
is performed as an implicit part of filtering prior to color model
conversion, with no separate post-conversion texel filtering step, as
described in the Implicit Reconstruction
section.
Explicit Reconstruction
-
If the
chromaFiltermember of the VkSamplerYcbcrConversionCreateInfo structure isVK_FILTER_NEAREST:-
If the format’s R and B components are reduced in resolution in just width by a factor of two relative to the G component (i.e. this is a “
_422” format), the values accessed by texel filtering are reconstructed as follows: -
If the format’s R and B components are reduced in resolution in width and height by a factor of two relative to the G component (i.e. this is a “
_420” format), the values accessed by texel filtering are reconstructed as follows:NotexChromaOffsetandyChromaOffsethave no effect ifchromaFilterisVK_FILTER_NEARESTfor explicit reconstruction.
-
-
If the
chromaFiltermember of the VkSamplerYcbcrConversionCreateInfo structure isVK_FILTER_LINEAR:-
If the format’s R and B components are reduced in resolution in just width by a factor of two relative to the G component (i.e. this is a “
_422” format):-
If
xChromaOffsetisVK_CHROMA_LOCATION_COSITED_EVEN: -
If
xChromaOffsetisVK_CHROMA_LOCATION_MIDPOINT:
-
-
If the format’s R and B components are reduced in resolution in width and height by a factor of two relative to the G component (i.e. this is a “
_420” format), a similar relationship applies. Due to the number of options, these formulae are expressed more concisely as follows:
-
|
Note
In the case where the texture itself is bilinearly interpolated as described
in Texel Filtering, thus requiring four
full-color samples for the filtering operation, and where the reconstruction
of these samples uses bilinear interpolation in the chroma components due to
|
Implicit Reconstruction
Implicit reconstruction takes place by the samples being interpolated, as
required by the filter settings of the sampler, except that
chromaFilter takes precedence for the chroma samples.
If chromaFilter is VK_FILTER_NEAREST, an implementation may
behave as if xChromaOffset and yChromaOffset were both
VK_CHROMA_LOCATION_MIDPOINT, irrespective of the values set.
|
Note
This will not have any visible effect if the locations of the luma samples coincide with the location of the samples used for rasterization. |
The sample coordinates are adjusted by the downsample factor of the component (such that, for example, the sample coordinates are divided by two if the component has a downsample factor of two relative to the luma component):
16.3.9. Sampler Y′CBCR Conversion
Sampler Y′CBCR conversion performs the following operations, which an implementation may combine into a single mathematical operation:
Sampler Y′CBCR Range Expansion
Sampler Y′CBCR range expansion is applied to color component values after all texel input operations which are not specific to sampler Y′CBCR conversion. For example, the input values to this stage have been converted using the normal format conversion rules.
Sampler Y′CBCR range expansion is not applied if ycbcrModel is
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY.
That is, the shader receives the vector C'rgba as output by the Component
Swizzle stage without further modification.
For other values of ycbcrModel, range expansion is applied to the
texel component values output by the Component
Swizzle defined by the components member of
VkSamplerYcbcrConversionCreateInfo.
Range expansion applies independently to each component of the image.
For the purposes of range expansion and Y′CBCR model conversion, the R and
B components contain color difference (chroma) values and the G component
contains luma.
The A component is not modified by sampler Y′CBCR range expansion.
The range expansion to be applied is defined by the ycbcrRange member
of the VkSamplerYcbcrConversionCreateInfo structure:
-
If
ycbcrRangeisVK_SAMPLER_YCBCR_RANGE_ITU_FULL, the following transformations are applied:NoteThese formulae correspond to the “full range” encoding in the “Quantization schemes” chapter of the Khronos Data Format Specification.
Should any future amendments be made to the ITU specifications from which these equations are derived, the formulae used by Vulkan may also be updated to maintain parity.
-
If
ycbcrRangeisVK_SAMPLER_YCBCR_RANGE_ITU_NARROW, the following transformations are applied:NoteThese formulae correspond to the “narrow range” encoding in the “Quantization schemes” chapter of the Khronos Data Format Specification.
-
n is the bit-depth of the components in the format.
The precision of the operations performed during range expansion must be at least that of the source format.
An implementation may clamp the results of these range expansion operations such that Y′ falls in the range [0,1], and/or such that CB and CR fall in the range [-0.5,0.5].
Sampler Y′CBCR Model Conversion
The range-expanded values are converted between color models, according to
the color model conversion specified in the ycbcrModel member:
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY-
The color components are not modified by the color model conversion since they are assumed already to represent the desired color model in which the shader is operating; Y′CBCR range expansion is also ignored.
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY-
The color components are not modified by the color model conversion and are assumed to be treated as though in Y′CBCR form both in memory and in the shader; Y′CBCR range expansion is applied to the components as for other Y′CBCR models, with the vector (CR,Y′,CB,A) provided to the shader.
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709-
The color components are transformed from a Y′CBCR representation to an R′G′B′ representation as described in the “BT.709 Y′CBCR conversion” section of the Khronos Data Format Specification.
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601-
The color components are transformed from a Y′CBCR representation to an R′G′B′ representation as described in the “BT.601 Y′CBCR conversion” section of the Khronos Data Format Specification.
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020-
The color components are transformed from a Y′CBCR representation to an R′G′B′ representation as described in the “BT.2020 Y′CBCR conversion” section of the Khronos Data Format Specification.
In this operation, each output component is dependent on each input component.
An implementation may clamp the R′G′B′ results of these conversions to the range [0,1].
The precision of the operations performed during model conversion must be at least that of the source format.
The alpha component is not modified by these model conversions.
|
Note
Sampling operations in a non-linear color space can introduce color and intensity shifts at sharp transition boundaries. To avoid this issue, the technically precise color correction sequence described in the “Introduction to Color Conversions” chapter of the Khronos Data Format Specification may be performed as follows:
The additional calculations and, especially, additional number of sampling
operations in the If |
16.4. Texel Output Operations
Texel output instructions are SPIR-V image instructions that write to an image. Texel output operations are a set of steps that are performed on state, coordinates, and texel values while processing a texel output instruction, and which are common to some or all texel output instructions. They include the following steps, which are performed in the listed order:
16.4.1. Texel Output Validation Operations
Texel output validation operations inspect instruction/image state or coordinates, and in certain circumstances cause the write to have no effect. There are a series of validations that the texel undergoes.
Texel Format Validation
If the image format of the OpTypeImage is not
compatible with the VkImageView’s
format, the write causes the contents of the image’s memory to become
undefined.
Texel Type Validation
If the Sampled Type of the OpTypeImage does not match the
type defined for the format, as specified in the SPIR-V Sampled Type
column of the Interpretation of Numeric Format table, the write causes the value of
the texel to become undefined.
For integer types, if the signedness of the
access does not match the signedness of the accessed resource, the write
causes the value of the texel to become undefined.
16.4.2. Integer Texel Coordinate Validation
The integer texel coordinates are validated according to the same rules as for texel input coordinate validation.
If the texel fails integer texel coordinate validation, then the write has no effect.
16.4.3. Sparse Texel Operation
If the texel attempts to write to an unbound region of a sparse image, the
texel is a sparse unbound texel.
In such a case, if the
VkPhysicalDeviceSparseProperties::residencyNonResidentStrict
property is VK_TRUE, the sparse unbound texel write has no effect.
If residencyNonResidentStrict is VK_FALSE, the write may have a
side effect that becomes visible to other accesses to unbound texels in any
resource, but will not be visible to any device memory allocated by the
application.
16.4.4. Texel Output Format Conversion
If the image format is sRGB, a linear to sRGB conversion is applied to the R, G, and B components as described in the “sRGB EOTF” section of the Khronos Data Format Specification. The A component, if present, is unchanged.
Texels then undergo a format conversion from the floating point, signed, or unsigned integer type of the texel data to the VkFormat of the image view. If the number of components in the texel data is larger than the number of components in the format, additional components are discarded.
Each component is converted based on its type and size (as defined in the Format Definition section for each VkFormat). Floating-point outputs are converted as described in Floating-Point Format Conversions and Fixed-Point Data Conversion. Integer outputs are converted such that their value is preserved. The converted value of any integer that cannot be represented in the target format is undefined.
16.5. Normalized Texel Coordinate Operations
If the image sampler instruction provides normalized texel coordinates, some of the following operations are performed.
16.5.1. Projection Operation
For Proj image operations, the normalized texel coordinates
(s,t,r,q,a) and (if present) the Dref coordinate are
transformed as follows:
16.5.2. Derivative Image Operations
Derivatives are used for LOD selection.
These derivatives are either implicit (in an ImplicitLod image
instruction in a fragment shader) or explicit (provided explicitly by shader
to the image instruction in any shader).
For implicit derivatives image instructions, the derivatives of texel coordinates are calculated in the same manner as derivative operations. That is:
Partial derivatives not defined above for certain image dimensionalities are set to zero.
For explicit LOD image instructions, if the optional SPIR-V operand
Grad is provided, then the operand values are used for the derivatives.
The number of components present in each derivative for a given image
dimensionality matches the number of partial derivatives computed above.
If the optional SPIR-V operand Lod is provided, then derivatives are
set to zero, the cube map derivative transformation is skipped, and the
scale factor operation is skipped.
Instead, the floating point scalar coordinate is directly assigned to
λbase as described in Level-of-Detail Operation.
If the image or sampler object used by an implicit derivative image
instruction is not uniform across the quad and
quadDivergentImplicitLod is not
supported, then the derivative and LOD values are undefined.
Implicit derivatives are well-defined when the image and sampler and control
flow are uniform across the quad, even if they diverge between different
quads.
If quadDivergentImplicitLod is
supported, then derivatives and implicit LOD values are well-defined even if
the image or sampler object are not uniform within a quad.
The derivatives are computed as specified above, and the implicit LOD
calculation proceeds for each shader invocation using its respective image
and sampler object.
16.5.3. Cube Map Face Selection and Transformations
For cube map image instructions, the (s,t,r) coordinates are treated as a direction vector (rx,ry,rz). The direction vector is used to select a cube map face. The direction vector is transformed to a per-face texel coordinate system (sface,tface), The direction vector is also used to transform the derivatives to per-face derivatives.
16.5.4. Cube Map Face Selection
The direction vector selects one of the cube map’s faces based on the largest magnitude coordinate direction (the major axis direction). Since two or more coordinates can have identical magnitude, the implementation must have rules to disambiguate this situation.
The rules should have as the first rule that rz wins over ry and rx, and the second rule that ry wins over rx. An implementation may choose other rules, but the rules must be deterministic and depend only on (rx,ry,rz).
The layer number (corresponding to a cube map face), the coordinate selections for sc, tc, rc, and the selection of derivatives, are determined by the major axis direction as specified in the following two tables.
| Major Axis Direction | Layer Number | Cube Map Face | sc | tc | rc |
|---|---|---|---|---|---|
+rx |
0 |
Positive X |
-rz |
-ry |
rx |
-rx |
1 |
Negative X |
+rz |
-ry |
rx |
+ry |
2 |
Positive Y |
+rx |
+rz |
ry |
-ry |
3 |
Negative Y |
+rx |
-rz |
ry |
+rz |
4 |
Positive Z |
+rx |
-ry |
rz |
-rz |
5 |
Negative Z |
-rx |
-ry |
rz |
| Major Axis Direction | ∂sc / ∂x | ∂sc / ∂y | ∂tc / ∂x | ∂tc / ∂y | ∂rc / ∂x | ∂rc / ∂y |
|---|---|---|---|---|---|---|
+rx |
-∂rz / ∂x |
-∂rz / ∂y |
-∂ry / ∂x |
-∂ry / ∂y |
+∂rx / ∂x |
+∂rx / ∂y |
-rx |
+∂rz / ∂x |
+∂rz / ∂y |
-∂ry / ∂x |
-∂ry / ∂y |
-∂rx / ∂x |
-∂rx / ∂y |
+ry |
+∂rx / ∂x |
+∂rx / ∂y |
+∂rz / ∂x |
+∂rz / ∂y |
+∂ry / ∂x |
+∂ry / ∂y |
-ry |
+∂rx / ∂x |
+∂rx / ∂y |
-∂rz / ∂x |
-∂rz / ∂y |
-∂ry / ∂x |
-∂ry / ∂y |
+rz |
+∂rx / ∂x |
+∂rx / ∂y |
-∂ry / ∂x |
-∂ry / ∂y |
+∂rz / ∂x |
+∂rz / ∂y |
-rz |
-∂rx / ∂x |
-∂rx / ∂y |
-∂ry / ∂x |
-∂ry / ∂y |
-∂rz / ∂x |
-∂rz / ∂y |
16.5.6. Cube Map Derivative Transformation
|
editing-note
(Bill) Note that we never revisited ARB_texture_cubemap after we introduced dependent texture fetches (ARB_fragment_program and ARB_fragment_shader). The derivatives of sface and tface are only valid for non-dependent texture fetches (pre OpenGL 2.0). |
16.5.7. Scale Factor Operation, Level-of-Detail Operation and Image Level(s) Selection
LOD selection can be either explicit (provided explicitly by the image
instruction) or implicit (determined from a scale factor calculated from the
derivatives).
The LOD must be computed with mipmapPrecisionBits of accuracy.
Scale Factor Operation
The magnitude of the derivatives are calculated by:
-
mux = |∂s/∂x| × wbase
-
mvx = |∂t/∂x| × hbase
-
mwx = |∂r/∂x| × dbase
-
muy = |∂s/∂y| × wbase
-
mvy = |∂t/∂y| × hbase
-
mwy = |∂r/∂y| × dbase
where:
-
∂t/∂x = ∂t/∂y = 0 (for 1D images)
-
∂r/∂x = ∂r/∂y = 0 (for 1D, 2D or Cube images)
and:
-
wbase = image.w
-
hbase = image.h
-
dbase = image.d
(for the baseMipLevel, from the image descriptor).
For corner-sampled images, the wbase, hbase, and dbase are instead:
-
wbase = image.w - 1
-
hbase = image.h - 1
-
dbase = image.d - 1
A point sampled in screen space has an elliptical footprint in texture space. The minimum and maximum scale factors (ρmin, ρmax) should be the minor and major axes of this ellipse.
The scale factors ρx and ρy, calculated from the magnitude of the derivatives in x and y, are used to compute the minimum and maximum scale factors.
ρx and ρy may be approximated with functions fx and fy, subject to the following constraints:
|
editing-note
(Bill) For reviewers only - anticipating questions. We only support implicit derivatives for normalized texel coordinates. So we are documenting the derivatives in s,t,r (normalized texel coordinates) rather than u,v,w (unnormalized texel coordinates) as in OpenGL and OpenGL ES specifications. (I know, u,v,w is the way it has been documented since OpenGL V1.0.) Also there is no reason to have conditional application of wbase, hbase, dbase for rectangle textures either, since they do not support implicit derivatives. |
The minimum and maximum scale factors (ρmin,ρmax) are determined by:
-
ρmax = max(ρx, ρy)
-
ρmin = min(ρx, ρy)
The ratio of anisotropy is determined by:
-
η = min(ρmax/ρmin, maxAniso)
where:
-
sampler.maxAniso =
maxAnisotropy(from sampler descriptor) -
limits.maxAniso =
maxSamplerAnisotropy(from physical device limits) -
maxAniso = min(sampler.maxAniso, limits.maxAniso)
If ρmax = ρmin = 0, then all the partial derivatives are
zero, the fragment’s footprint in texel space is a point, and η
should be treated as 1.
If ρmax ≠ 0 and ρmin = 0 then all partial
derivatives along one axis are zero, the fragment’s footprint in texel space
is a line segment, and η should be treated as maxAniso.
However, anytime the footprint is small in texel space the implementation
may use a smaller value of η, even when ρmin is zero
or close to zero.
If either VkPhysicalDeviceFeatures::samplerAnisotropy or
VkSamplerCreateInfo::anisotropyEnable are VK_FALSE,
maxAniso is set to 1.
If η = 1, sampling is isotropic. If η > 1, sampling is anisotropic.
The sampling rate (N) is derived as:
-
N = ⌈η⌉
An implementation may round N up to the nearest supported sampling rate. An implementation may use the value of N as an approximation of η.
Level-of-Detail Operation
The LOD parameter λ is computed as follows:
where:
and maxSamplerLodBias is the value of the VkPhysicalDeviceLimits
feature maxSamplerLodBias.
Image Level(s) Selection
The image level(s) d, dhi, and dlo which texels are read from are determined by an image-level parameter dl, which is computed based on the LOD parameter, as follows:
where:
and:
baseMipLevel and levelCount are taken from the
subresourceRange of the image view.
minLod is taken from the
VkImageViewMinLodCreateInfoEXT::minLod of the image view if
present and the selection is part of the result of a sampling operation,
otherwise it is 0.0.
minLod must be less or equal to levelbase + q.
If the sampler’s mipmapMode is VK_SAMPLER_MIPMAP_MODE_NEAREST,
then the level selected is d = dl.
If the sampler’s mipmapMode is VK_SAMPLER_MIPMAP_MODE_LINEAR,
two neighboring levels are selected:
δ is the fractional value, quantized to the number of mipmap precision bits, used for linear filtering between levels.
16.5.8. (s,t,r,q,a) to (u,v,w,a) Transformation
The normalized texel coordinates are scaled by the image level dimensions and the array layer is selected.
This transformation is performed once for each level used in filtering (either d, or dhi and dlo).
where:
-
widthscale = widthlevel
-
heightscale = heightlevel
-
depthscale = depthlevel
for conventional images, and:
-
widthscale = widthlevel - 1
-
heightscale = heightlevel - 1
-
depthscale = depthlevel - 1
for corner-sampled images.
and where (Δi, Δj, Δk) are
taken from the image instruction if it includes a ConstOffset or
Offset operand, otherwise they are taken to be zero.
Operations then proceed to Unnormalized Texel Coordinate Operations.
16.6. Unnormalized Texel Coordinate Operations
16.6.1. (u,v,w,a) to (i,j,k,l,n) Transformation And Array Layer Selection
The unnormalized texel coordinates are transformed to integer texel coordinates relative to the selected mipmap level.
The layer index l is computed as:
-
l = clamp(RNE(a), 0,
layerCount- 1) +baseArrayLayer
where layerCount is the number of layers in the image subresource
range of the image view, baseArrayLayer is the first layer from the
subresource range, and where:
The sample index n is assigned the value 0.
Nearest filtering (VK_FILTER_NEAREST) computes the integer texel
coordinates that the unnormalized coordinates lie within:
where:
-
shift = 0.0
for conventional images, and:
-
shift = 0.5
for corner-sampled images.
Linear filtering (VK_FILTER_LINEAR) computes a set of neighboring
coordinates which bound the unnormalized coordinates.
The integer texel coordinates are combinations of i0 or i1,
j0 or j1, k0 or k1, as well as weights
α, β, and γ.
where:
-
shift = 0.5
for conventional images, and:
-
shift = 0.0
for corner-sampled images, and where:
where the number of fraction bits retained is specified by
VkPhysicalDeviceLimits::subTexelPrecisionBits.
Cubic filtering (VK_FILTER_CUBIC_EXT) computes a set of neighboring
coordinates which bound the unnormalized coordinates.
The integer texel coordinates are combinations of i0, i1,
i2 or i3, j0, j1, j2 or j3,
k0, k1, k2 or k3, as well as weights
α, β, and γ.
where:
where the number of fraction bits retained is specified by
VkPhysicalDeviceLimits::subTexelPrecisionBits.
16.7. Integer Texel Coordinate Operations
Integer texel coordinate operations may supply a LOD which texels are to be
read from or written to using the optional SPIR-V operand Lod.
If the Lod is provided then it must be an integer.
The image level selected is:
If d does not lie in the range [baseMipLevel,
baseMipLevel + levelCount)
or d is less than minLodIntegerimageView,
then any values fetched are
zero if the robustImageAccess2
feature is enabled, otherwise are
undefined, and any writes (if supported) are discarded.
where:
minLodIntegerimageView = ⌊minLod⌋
minLod is taken from the
VkImageViewMinLodCreateInfoEXT::minLod of the image view if
present and the selection is part of the result of a sampling operation,
otherwise it is 0.0.
If the integer texel operation is not a sampling operation, the image view
parameter is ignored, and minLod is 0.0.
16.8. Image Sample Operations
16.8.1. Wrapping Operation
If the used sampler was created without
VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT,
Cube images ignore the wrap modes specified in the sampler.
Instead, if VK_FILTER_NEAREST is used within a mip level then
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE is used, and if
VK_FILTER_LINEAR is used within a mip level then sampling at the edges
is performed as described earlier in the Cube map
edge handling section.
The first integer texel coordinate i is transformed based on the
addressModeU parameter of the sampler.
where:
j (for 2D and Cube image) and k (for 3D image) are similarly
transformed based on the addressModeV and addressModeW
parameters of the sampler, respectively.
16.8.2. Texel Gathering
SPIR-V instructions with Gather in the name return a vector derived
from 4 texels in the base level of the image view.
The rules for the VK_FILTER_LINEAR minification filter are applied to
identify the four selected texels.
Each texel is then converted to an RGBA value according to
conversion to RGBA and then
swizzled.
A four-component vector is then assembled by taking the component indicated
by the Component value in the instruction from the swizzled color value
of the four texels.
If the operation does not use the ConstOffsets image operand then the
four texels form the 2 × 2 rectangle used for texture filtering:
If the operation does use the ConstOffsets image operand then the
offsets allow a custom filter to be defined:
where:
OpImage*Gather must not be used on a sampled image with
sampler Y′CBCR conversion enabled.
16.8.3. Texel Filtering
Texel filtering is first performed for each level (either d or dhi and dlo).
If λ is less than or equal to zero, the texture is said to be
magnified, and the filter mode within a mip level is selected by the
magFilter in the sampler.
If λ is greater than zero, the texture is said to be
minified, and the filter mode within a mip level is selected by the
minFilter in the sampler.
Texel Nearest Filtering
Within a mip level, VK_FILTER_NEAREST filtering selects a single value
using the (i, j, k) texel coordinates, with all texels taken from
layer l.
Texel Linear Filtering
Within a mip level, VK_FILTER_LINEAR filtering combines 8 (for 3D), 4
(for 2D or Cube), or 2 (for 1D) texel values, together with their linear
weights.
The linear weights are derived from the fractions computed earlier:
The values of multiple texels, together with their weights, are combined to produce a filtered value.
The VkSamplerReductionModeCreateInfo::reductionMode can control
the process by which multiple texels, together with their weights, are
combined to produce a filtered texture value.
When the reductionMode is set (explicitly or implicitly) to
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE, a weighted average is
computed:
However, if the reduction mode is VK_SAMPLER_REDUCTION_MODE_MIN or
VK_SAMPLER_REDUCTION_MODE_MAX, the process operates on the above set
of multiple texels, together with their weights, computing a component-wise
minimum or maximum, respectively, of the components of the set of texels
with non-zero weights.
Texel Cubic Filtering
Within a mip level, VK_FILTER_CUBIC_EXT, filtering computes a weighted
average of
64 (for 3D),
16 (for 2D), or 4 (for 1D) texel values, together with their Catmull-Rom
weights.
Catmull-Rom weights are derived from the fractions computed earlier.
The values of multiple texels, together with their weights, are combined to produce a filtered value.
The VkSamplerReductionModeCreateInfo::reductionMode can control
the process by which multiple texels, together with their weights, are
combined to produce a filtered texture value.
When the reductionMode is set (explicitly or implicitly) to
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE, a weighted average is
computed:
However, if the reduction mode is VK_SAMPLER_REDUCTION_MODE_MIN or
VK_SAMPLER_REDUCTION_MODE_MAX, the process operates on the above set
of multiple texels, together with their weights, computing a component-wise
minimum or maximum, respectively, of the components of the set of texels
with non-zero weights.
Texel Mipmap Filtering
VK_SAMPLER_MIPMAP_MODE_NEAREST filtering returns the value of a single
mipmap level,
τ = τ[d].
VK_SAMPLER_MIPMAP_MODE_LINEAR filtering combines the values of
multiple mipmap levels (τ[hi] and τ[lo]), together with their linear
weights.
The linear weights are derived from the fraction computed earlier:
The values of multiple mipmap levels, together with their weights, are combined to produce a final filtered value.
The VkSamplerReductionModeCreateInfo::reductionMode can control
the process by which multiple texels, together with their weights, are
combined to produce a filtered texture value.
When the reductionMode is set (explicitly or implicitly) to
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE, a weighted average is
computed:
Texel Anisotropic Filtering
Anisotropic filtering is enabled by the anisotropyEnable in the
sampler.
When enabled, the image filtering scheme accounts for a degree of
anisotropy.
The particular scheme for anisotropic texture filtering is
implementation-dependent.
Implementations should consider the magFilter, minFilter and
mipmapMode of the sampler to control the specifics of the anisotropic
filtering scheme used.
In addition, implementations should consider minLod and maxLod
of the sampler.
The following describes one particular approach to implementing anisotropic filtering for the 2D Image case, implementations may choose other methods:
Given a magFilter, minFilter of VK_FILTER_LINEAR and a
mipmapMode of VK_SAMPLER_MIPMAP_MODE_NEAREST:
Instead of a single isotropic sample, N isotropic samples are sampled within the image footprint of the image level d to approximate an anisotropic filter. The sum τ2Daniso is defined using the single isotropic τ2D(u,v) at level d.
When VkSamplerReductionModeCreateInfo::reductionMode is set to
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE, the above summation is
used.
However, if the reduction mode is VK_SAMPLER_REDUCTION_MODE_MIN or
VK_SAMPLER_REDUCTION_MODE_MAX, the process operates on the above
values, together with their weights, computing a component-wise minimum or
maximum, respectively, of the components of the values with non-zero
weights.
16.9. Texel Footprint Evaluation
The SPIR-V instruction OpImageSampleFootprintNV evaluates the set of
texels from a single mip level that would be accessed during a
texel filtering operation.
In addition to the inputs that would be accepted by an equivalent
OpImageSample* instruction, OpImageSampleFootprintNV accepts two
additional inputs.
The Granularity input is an integer identifying the size of texel
groups used to evaluate the footprint.
Each bit in the returned footprint mask corresponds to an aligned block of
texels whose size is given by the following table:
Granularity |
Dim = 2D |
Dim = 3D |
|---|---|---|
0 |
unsupported |
unsupported |
1 |
2x2 |
2x2x2 |
2 |
4x2 |
unsupported |
3 |
4x4 |
4x4x2 |
4 |
8x4 |
unsupported |
5 |
8x8 |
unsupported |
6 |
16x8 |
unsupported |
7 |
16x16 |
unsupported |
8 |
unsupported |
unsupported |
9 |
unsupported |
unsupported |
10 |
unsupported |
16x16x16 |
11 |
64x64 |
32x16x16 |
12 |
128x64 |
32x32x16 |
13 |
128x128 |
32x32x32 |
14 |
256x128 |
64x32x32 |
15 |
256x256 |
unsupported |
The Coarse input is used to select between the two mip levels that may
be accessed during texel filtering when using a mipmapMode of
VK_SAMPLER_MIPMAP_MODE_LINEAR.
When filtering between two mip levels, a Coarse value of true
requests the footprint in the lower-resolution mip level (higher level
number), while false requests the footprint in the higher-resolution
mip level.
If texel filtering would access only a single mip level, the footprint in
that level would be returned when Coarse is set to false; an empty
footprint would be returned when Coarse is set to true.
The footprint for OpImageSampleFootprintNV is returned in a structure
with six members:
-
The first member is a boolean value that is true if the texel filtering operation would access only a single mip level.
-
The second member is a two- or three-component integer vector holding the footprint anchor location. For two-dimensional images, the returned components are in units of eight texel groups. For three-dimensional images, the returned components are in units of four texel groups.
-
The third member is a two- or three-component integer vector holding a footprint offset relative to the anchor. All returned components are in units of texel groups.
-
The fourth member is a two-component integer vector mask, which holds a bitfield identifying the set of texel groups in an 8x8 or 4x4x4 neighborhood relative to the anchor and offset.
-
The fifth member is an integer identifying the mip level containing the footprint identified by the anchor, offset, and mask.
-
The sixth member is an integer identifying the granularity of the returned footprint.
For footprints in two-dimensional images (Dim2D), the mask returned by
OpImageSampleFootprintNV indicates whether each texel group in a 8x8
local neighborhood of texel groups would have one or more texels accessed
during texel filtering.
In the mask, the texel group with local group coordinates
is considered covered if and only if
where:
-
and ; and
-
is the returned two-component mask.
The local group with coordinates in the mask is considered covered if and only if the texel filtering operation would access one or more texels in the returned miplevel where:
and
-
and ;
-
is a two-component vector holding the width and height of the texel group identified by the granularity;
-
is the returned two-component anchor vector; and
-
is the returned two-component offset vector.
For footprints in three-dimensional images (Dim3D), the mask returned
by OpImageSampleFootprintNV indicates whether each texel group in a
4x4x4 local neighborhood of texel groups would have one or more texels
accessed during texel filtering.
In the mask, the texel group with local group coordinates
, is considered covered if and only if:
where:
-
, , and ; and
-
is the returned two-component mask.
The local group with coordinates in the mask is considered covered if and only if the texel filtering operation would access one or more texels in the returned miplevel where:
and
-
, , ;
-
is a three-component vector holding the width, height, and depth of the texel group identified by the granularity;
-
is the returned three-component anchor vector; and
-
is the returned three-component offset vector.
If the sampler used by OpImageSampleFootprintNV enables anisotropic
texel filtering via anisotropyEnable, it is possible that the set of
texel groups accessed in a mip level may be too large to be expressed using
an 8x8 or 4x4x4 mask using the granularity requested in the instruction.
In this case, the implementation uses a texel group larger than the
requested granularity.
When a larger texel group size is used, OpImageSampleFootprintNV
returns an integer granularity value that can be interpreted in the same
manner as the granularity value provided to the instruction to determine the
texel group size used.
If anisotropic texel filtering is disabled in the sampler, or if an
anisotropic footprint can be represented as an 8x8 or 4x4x4 mask with the
requested granularity, OpImageSampleFootprintNV will use the requested
granularity as-is and return a granularity value of zero.
OpImageSampleFootprintNV supports only two- and three-dimensional image
accesses (Dim2D and Dim3D), and the footprint returned is
undefined if a sampler uses an addressing mode other than
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
16.10. Image Operation Steps
Each step described in this chapter is performed by a subset of the image instructions:
-
Texel Input Validation Operations, Format Conversion, Texel Replacement, Conversion to RGBA, and Component Swizzle: Performed by all instructions except
OpImageWrite. -
Depth Comparison: Performed by
OpImage*Drefinstructions. -
All Texel output operations: Performed by
OpImageWrite. -
Projection: Performed by all
OpImage*Projinstructions. -
Derivative Image Operations, Cube Map Operations, Scale Factor Operation, Level-of-Detail Operation and Image Level(s) Selection, and Texel Anisotropic Filtering: Performed by all
OpImageSample*andOpImageSparseSample*instructions. -
(s,t,r,q,a) to (u,v,w,a) Transformation, Wrapping, and (u,v,w,a) to (i,j,k,l,n) Transformation And Array Layer Selection: Performed by all
OpImageSample,OpImageSparseSample, andOpImage*Gatherinstructions. -
Texel Gathering: Performed by
OpImage*Gatherinstructions. -
Texel Footprint Evaluation: Performed by
OpImageSampleFootprintinstructions. -
Texel Filtering: Performed by all
OpImageSample*andOpImageSparseSample*instructions. -
Sparse Residency: Performed by all
OpImageSparse*instructions.
16.11. Image Query Instructions
16.11.1. Image Property Queries
OpImageQuerySize, OpImageQuerySizeLod, OpImageQueryLevels,
and OpImageQuerySamples query properties of the image descriptor that
would be accessed by a shader image operation.
They return 0 if the bound descriptor is a null descriptor.
OpImageQuerySizeLod returns the size of the image level identified by
the Level of Detail operand.
If that level does not exist in the image,
and the descriptor is not null,
then the value returned is undefined.
16.11.2. Lod Query
OpImageQueryLod returns the Lod parameters that would be used in an
image operation with the given image and coordinates.
If the descriptor that would be accessed is a null descriptor then (0, 0) is
returned.
Otherwise, the
steps described in this chapter are performed as if for
OpImageSampleImplicitLod, up to Scale Factor Operation, Level-of-Detail Operation and Image Level(s) Selection.
The return value is the vector (λ', dl).
These values may be subject to implementation-specific maxima and minima
for very large, out-of-range values.
17. Fragment Density Map Operations
17.1. Fragment Density Map Operations Overview
When a fragment is generated in a render pass that has a fragment density map attachment, its area is determined by the properties of the local framebuffer region that the fragment occupies. The framebuffer is divided into a uniform grid of these local regions, and their fragment area property is derived from the density map with the following operations:
17.2. Fetch Density Value
Each local framebuffer region at center coordinate (x,y) fetches a texel from the fragment density map.
First, the local framebuffer region center coordinate (x,y) is offset by the value specified in VkSubpassFragmentDensityMapOffsetEndInfoQCOM. If no offset is specified, then the default offset (0,0) is used. The offsetted coordinate (x',y') is computed as follows:
The offsetted coordinate (x',y') fetches a texel from the fragment density map at integer coordinates:
Where the size of each region in the framebuffer is:
This region is subject to the limits in
VkPhysicalDeviceFragmentDensityMapPropertiesEXT and therefore the
final region size is clamped:
When multiview is enabled for the render pass and the fragment density map
attachment view was created with layerCount greater than 1, the
layer used for offsets and for fetching from the fragment density map is:
Otherwise:
The texel fetched from the density map at (i,j,layer) is next converted to density with the following operations.
17.2.1. Component Swizzle
The components member of VkImageViewCreateInfo is applied to the
fetched texel as defined in Image component
swizzle.
17.3. Fragment Area Conversion
Fragment area for the framebuffer region is undefined if the density
fetched is not a normalized floating-point value greater than 0.0.
Otherwise, the fetched fragment area for that region is derived as:
17.3.1. Fragment Area Filter
Optionally, the implementation may fetch additional density map texels in an implementation defined window around (i,j). The texels follow the standard conversion steps up to and including fragment area conversion.
A single fetched fragment area for the framebuffer region is chosen by the implementation and must have an area between the min and max areas of the fetched set.
17.3.2. Fragment Area Clamp
The implementation may clamp the fetched fragment area to one that it supports. The clamped fragment area must have a size less than or equal to the original fetched value. Implementations may vary the supported set of fragment areas per framebuffer region. Fragment area (1,1) must always be in the supported set.
|
Note
For example, if the fetched fragment area is (1,4) but the implementation only supports areas of {(1,1),(2,2)}, it could choose to clamp the area to (2,2) since it has the same size as (1,4). While this would produce fragments that have lower quality strictly in the x-axis, the overall density is maintained. |
The clamped fragment area is assigned to the corresponding framebuffer region.
18. Queries
Queries provide a mechanism to return information about the processing of a sequence of Vulkan commands. Query operations are asynchronous, and as such, their results are not returned immediately. Instead, their results, and their availability status are stored in a Query Pool. The state of these queries can be read back on the host, or copied to a buffer object on the device.
The supported query types are Occlusion Queries, Pipeline Statistics Queries, Result Status Queries, Video Encode Bitstream Queries, and Timestamp Queries. Performance Queries are supported if the associated extension is available. Transform Feedback Queries are supported if the associated extension is available. Intel performance queries are supported if the associated extension is available.
Several additional queries with specific purposes associated with ray tracing are available if the corresponding extensions are supported, as described for VkQueryType.
18.1. Query Pools
Queries are managed using query pool objects. Each query pool is a collection of a specific number of queries of a particular type.
Query pools are represented by VkQueryPool handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkQueryPool)
To create a query pool, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateQueryPool(
VkDevice device,
const VkQueryPoolCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkQueryPool* pQueryPool);
-
deviceis the logical device that creates the query pool. -
pCreateInfois a pointer to a VkQueryPoolCreateInfo structure containing the number and type of queries to be managed by the pool. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pQueryPoolis a pointer to a VkQueryPool handle in which the resulting query pool object is returned.
The VkQueryPoolCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkQueryPoolCreateInfo {
VkStructureType sType;
const void* pNext;
VkQueryPoolCreateFlags flags;
VkQueryType queryType;
uint32_t queryCount;
VkQueryPipelineStatisticFlags pipelineStatistics;
} VkQueryPoolCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
queryTypeis a VkQueryType value specifying the type of queries managed by the pool. -
queryCountis the number of queries managed by the pool. -
pipelineStatisticsis a bitmask of VkQueryPipelineStatisticFlagBits specifying which counters will be returned in queries on the new pool, as described below in Pipeline Statistics Queries.
pipelineStatistics is ignored if queryType is not
VK_QUERY_TYPE_PIPELINE_STATISTICS.
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueryPoolCreateFlags;
VkQueryPoolCreateFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
The VkQueryPoolPerformanceCreateInfoKHR structure is defined as:
// Provided by VK_KHR_performance_query
typedef struct VkQueryPoolPerformanceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t queueFamilyIndex;
uint32_t counterIndexCount;
const uint32_t* pCounterIndices;
} VkQueryPoolPerformanceCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queueFamilyIndexis the queue family index to create this performance query pool for. -
counterIndexCountis the length of thepCounterIndicesarray. -
pCounterIndicesis a pointer to an array of indices into the vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR::pCountersto enable in this performance query pool.
To query the number of passes required to query a performance query pool on a physical device, call:
// Provided by VK_KHR_performance_query
void vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(
VkPhysicalDevice physicalDevice,
const VkQueryPoolPerformanceCreateInfoKHR* pPerformanceQueryCreateInfo,
uint32_t* pNumPasses);
-
physicalDeviceis the handle to the physical device whose queue family performance query counter properties will be queried. -
pPerformanceQueryCreateInfois a pointer to aVkQueryPoolPerformanceCreateInfoKHRof the performance query that is to be created. -
pNumPassesis a pointer to an integer related to the number of passes required to query the performance query pool, as described below.
The pPerformanceQueryCreateInfo member
VkQueryPoolPerformanceCreateInfoKHR::queueFamilyIndex must be a
queue family of physicalDevice.
The number of passes required to capture the counters specified in the
pPerformanceQueryCreateInfo member
VkQueryPoolPerformanceCreateInfoKHR::pCounters is returned in
pNumPasses.
To destroy a query pool, call:
// Provided by VK_VERSION_1_0
void vkDestroyQueryPool(
VkDevice device,
VkQueryPool queryPool,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the query pool. -
queryPoolis the query pool to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
|
Note
Applications can verify that |
Possible values of VkQueryPoolCreateInfo::queryType, specifying
the type of queries managed by the pool, are:
// Provided by VK_VERSION_1_0
typedef enum VkQueryType {
VK_QUERY_TYPE_OCCLUSION = 0,
VK_QUERY_TYPE_PIPELINE_STATISTICS = 1,
VK_QUERY_TYPE_TIMESTAMP = 2,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR = 1000023000,
#endif
// Provided by VK_EXT_transform_feedback
VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT = 1000028004,
// Provided by VK_KHR_performance_query
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR = 1000116000,
// Provided by VK_KHR_acceleration_structure
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR = 1000150000,
// Provided by VK_KHR_acceleration_structure
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR = 1000150001,
// Provided by VK_NV_ray_tracing
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV = 1000165000,
// Provided by VK_INTEL_performance_query
VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL = 1000210000,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_encode_queue
VK_QUERY_TYPE_VIDEO_ENCODE_BITSTREAM_BUFFER_RANGE_KHR = 1000299000,
#endif
// Provided by VK_EXT_primitives_generated_query
VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT = 1000382000,
// Provided by VK_KHR_ray_tracing_maintenance1
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR = 1000386000,
// Provided by VK_KHR_ray_tracing_maintenance1
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR = 1000386001,
} VkQueryType;
-
VK_QUERY_TYPE_OCCLUSIONspecifies an occlusion query. -
VK_QUERY_TYPE_PIPELINE_STATISTICSspecifies a pipeline statistics query. -
VK_QUERY_TYPE_TIMESTAMPspecifies a timestamp query. -
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHRspecifies a performance query. -
VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXTspecifies a transform feedback query. -
VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXTspecifies a primitives generated query. -
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHRspecifies a acceleration structure size query for use with vkCmdWriteAccelerationStructuresPropertiesKHR or vkWriteAccelerationStructuresPropertiesKHR. -
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHRspecifies a serialization acceleration structure size query. -
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHRspecifies an acceleration structure size query for use with vkCmdWriteAccelerationStructuresPropertiesKHR or vkWriteAccelerationStructuresPropertiesKHR. -
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHRspecifies a serialization acceleration structure pointer count query. -
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NVspecifies an acceleration structure size query for use with vkCmdWriteAccelerationStructuresPropertiesNV. -
VK_QUERY_TYPE_PERFORMANCE_QUERY_INTELspecifies a Intel performance query. -
VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHRspecifies a result status query. -
VK_QUERY_TYPE_VIDEO_ENCODE_BITSTREAM_BUFFER_RANGE_KHRspecifies a video encode bitstream range query.
18.2. Query Operation
The operation of queries is controlled by the commands vkCmdBeginQuery, vkCmdEndQuery, vkCmdBeginQueryIndexedEXT, vkCmdEndQueryIndexedEXT, vkCmdResetQueryPool, vkCmdCopyQueryPoolResults, vkCmdWriteTimestamp2, and vkCmdWriteTimestamp.
In order for a VkCommandBuffer to record query management commands,
the queue family for which its VkCommandPool was created must support
the appropriate type of operations (graphics, compute) suitable for the
query type of a given query pool.
Each query in a query pool has a status that is either unavailable or available, and also has state to store the numerical results of a query operation of the type requested when the query pool was created. Resetting a query via vkCmdResetQueryPool or vkResetQueryPool sets the status to unavailable and makes the numerical results undefined. A query is made available by the operation of vkCmdEndQuery, vkCmdEndQueryIndexedEXT, vkCmdWriteTimestamp2, or vkCmdWriteTimestamp. Both the availability status and numerical results can be retrieved by calling either vkGetQueryPoolResults or vkCmdCopyQueryPoolResults.
After query pool creation, each query must be reset before it is used. Queries must also be reset between uses.
If a logical device includes multiple physical devices, then each command that writes a query must execute on a single physical device, and any call to vkCmdBeginQuery must execute the corresponding vkCmdEndQuery command on the same physical device.
To reset a range of queries in a query pool on a queue, call:
// Provided by VK_VERSION_1_0
void vkCmdResetQueryPool(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount);
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the handle of the query pool managing the queries being reset. -
firstQueryis the initial query index to reset. -
queryCountis the number of queries to reset.
When executed on a queue, this command sets the status of query indices
[firstQuery, firstQuery + queryCount - 1] to
unavailable.
This command defines an execution dependency between other query commands that reference the same query.
The first synchronization scope
includes all commands which reference the queries in queryPool
indicated by firstQuery and queryCount that occur earlier in
submission order.
The second synchronization scope
includes all commands which reference the queries in queryPool
indicated by firstQuery and queryCount that occur later in
submission order.
The operation of this command happens after the first scope and happens before the second scope.
If the queryType used to create queryPool was
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, this command sets the status of
query indices [firstQuery, firstQuery +
queryCount - 1] to unavailable for each pass of queryPool, as
indicated by a call to
vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR.
|
Note
Because |
To reset a range of queries in a query pool on the host, call:
// Provided by VK_VERSION_1_2
void vkResetQueryPool(
VkDevice device,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount);
or the equivalent command
// Provided by VK_EXT_host_query_reset
void vkResetQueryPoolEXT(
VkDevice device,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount);
-
deviceis the logical device that owns the query pool. -
queryPoolis the handle of the query pool managing the queries being reset. -
firstQueryis the initial query index to reset. -
queryCountis the number of queries to reset.
This command sets the status of query indices [firstQuery,
firstQuery + queryCount - 1] to unavailable.
If queryPool is VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR this command
sets the status of query indices [firstQuery, firstQuery
+ queryCount - 1] to unavailable for each pass.
Once queries are reset and ready for use, query commands can be issued to a command buffer. Occlusion queries and pipeline statistics queries count events - drawn samples and pipeline stage invocations, respectively - resulting from commands that are recorded between a vkCmdBeginQuery command and a vkCmdEndQuery command within a specified command buffer, effectively scoping a set of drawing and/or dispatching commands. Timestamp queries write timestamps to a query pool. Performance queries record performance counters to a query pool.
A query must begin and end in the same command buffer, although if it is a
primary command buffer, and the inheritedQueries feature is enabled, it can execute secondary
command buffers during the query operation.
For a secondary command buffer to be executed while a query is active, it
must set the occlusionQueryEnable, queryFlags, and/or
pipelineStatistics members of VkCommandBufferInheritanceInfo to
conservative values, as described in the Command
Buffer Recording section.
A query must either begin and end inside the same subpass of a render pass
instance, or must both begin and end outside of a render pass instance
(i.e. contain entire render pass instances).
If queries are used while executing a render pass instance that has
multiview enabled, the query uses N consecutive query indices in the
query pool (starting at query) where N is the number of bits set
in the view mask in the subpass the query is used in.
How the numerical results of the query are distributed among the queries is
implementation-dependent.
For example, some implementations may write each view’s results to a
distinct query, while other implementations may write the total result to
the first query and write zero to the other queries.
However, the sum of the results in all the queries must accurately reflect
the total result of the query summed over all views.
Applications can sum the results from all the queries to compute the total
result.
Queries used with multiview rendering must not span subpasses, i.e. they must begin and end in the same subpass.
To begin a query, call:
// Provided by VK_VERSION_1_0
void vkCmdBeginQuery(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query,
VkQueryControlFlags flags);
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool that will manage the results of the query. -
queryis the query index within the query pool that will contain the results. -
flagsis a bitmask of VkQueryControlFlagBits specifying constraints on the types of queries that can be performed.
If the queryType of the pool is VK_QUERY_TYPE_OCCLUSION and
flags contains VK_QUERY_CONTROL_PRECISE_BIT, an implementation
must return a result that matches the actual number of samples passed.
This is described in more detail in Occlusion Queries.
Calling vkCmdBeginQuery is equivalent to calling
vkCmdBeginQueryIndexedEXT with the index parameter set to zero.
After beginning a query, that query is considered active within the command buffer it was called in until that same query is ended. Queries active in a primary command buffer when secondary command buffers are executed are considered active for those secondary command buffers.
This command defines an execution dependency between other query commands that reference the same query.
The first synchronization scope
includes all commands which reference the queries in queryPool
indicated by query that occur earlier in
submission order.
The second synchronization scope
includes all commands which reference the queries in queryPool
indicated by query that occur later in
submission order.
The operation of this command happens after the first scope and happens before the second scope.
To begin an indexed query, call:
// Provided by VK_EXT_transform_feedback
void vkCmdBeginQueryIndexedEXT(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query,
VkQueryControlFlags flags,
uint32_t index);
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool that will manage the results of the query. -
queryis the query index within the query pool that will contain the results. -
flagsis a bitmask of VkQueryControlFlagBits specifying constraints on the types of queries that can be performed. -
indexis the query type specific index. When the query type isVK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXTorVK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT, the index represents the vertex stream.
The vkCmdBeginQueryIndexedEXT command operates the same as the
vkCmdBeginQuery command, except that it also accepts a query type
specific index parameter.
This command defines an execution dependency between other query commands that reference the same query index.
The first synchronization scope
includes all commands which reference the queries in queryPool
indicated by query and index that occur earlier in
submission order.
The second synchronization scope
includes all commands which reference the queries in queryPool
indicated by query and index that occur later in
submission order.
The operation of this command happens after the first scope and happens before the second scope.
Bits which can be set in vkCmdBeginQuery::flags, specifying
constraints on the types of queries that can be performed, are:
// Provided by VK_VERSION_1_0
typedef enum VkQueryControlFlagBits {
VK_QUERY_CONTROL_PRECISE_BIT = 0x00000001,
} VkQueryControlFlagBits;
-
VK_QUERY_CONTROL_PRECISE_BITspecifies the precision of occlusion queries.
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueryControlFlags;
VkQueryControlFlags is a bitmask type for setting a mask of zero or
more VkQueryControlFlagBits.
To end a query after the set of desired drawing or dispatching commands is executed, call:
// Provided by VK_VERSION_1_0
void vkCmdEndQuery(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query);
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool that is managing the results of the query. -
queryis the query index within the query pool where the result is stored.
The command completes the query in queryPool identified by
query, and marks it as available.
This command defines an execution dependency between other query commands that reference the same query.
The first synchronization scope
includes all commands which reference the queries in queryPool
indicated by query that occur earlier in
submission order.
The second synchronization scope includes only the operation of this command.
Calling vkCmdEndQuery is equivalent to calling
vkCmdEndQueryIndexedEXT with the index parameter set to zero.
To end an indexed query after the set of desired drawing or dispatching commands is recorded, call:
// Provided by VK_EXT_transform_feedback
void vkCmdEndQueryIndexedEXT(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query,
uint32_t index);
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool that is managing the results of the query. -
queryis the query index within the query pool where the result is stored. -
indexis the query type specific index.
The command completes the query in queryPool identified by query
and index, and marks it as available.
The vkCmdEndQueryIndexedEXT command operates the same as the
vkCmdEndQuery command, except that it also accepts a query type
specific index parameter.
This command defines an execution dependency between other query commands that reference the same query index.
The first synchronization scope
includes all commands which reference the queries in queryPool
indicated by query that occur earlier in
submission order.
The second synchronization scope includes only the operation of this command.
An application can retrieve results either by requesting they be written
into application-provided memory, or by requesting they be copied into a
VkBuffer.
In either case, the layout in memory is defined as follows:
-
The first query’s result is written starting at the first byte requested by the command, and each subsequent query’s result begins
stridebytes later. -
Occlusion queries, pipeline statistics queries, transform feedback queries, primitives generated queries, and timestamp queries store results in a tightly packed array of unsigned integers, either 32- or 64-bits as requested by the command, storing the numerical results and, if requested, the availability status.
-
Performance queries store results in a tightly packed array whose type is determined by the
unitmember of the corresponding VkPerformanceCounterKHR. -
If
VK_QUERY_RESULT_WITH_AVAILABILITY_BITis used, the final element of each query’s result is an integer indicating whether the query’s result is available, with any non-zero value indicating that it is available. -
If
VK_QUERY_RESULT_WITH_STATUS_BIT_KHRis used, the final element of each query’s result is an integer value indicating that status of the query result. Positive values indicate success, negative values indicate failure, and 0 indicates that the result is not yet available. Specific error codes are encoded in the VkQueryResultStatusKHR enumeration. -
Occlusion queries write one integer value - the number of samples passed. Pipeline statistics queries write one integer value for each bit that is enabled in the
pipelineStatisticswhen the pool is created, and the statistics values are written in bit order starting from the least significant bit. Timestamp queries write one integer value. Performance queries write one VkPerformanceCounterResultKHR value for each VkPerformanceCounterKHR in the query. Transform feedback queries write two integers; the first integer is the number of primitives successfully written to the corresponding transform feedback buffer and the second is the number of primitives output to the vertex stream, regardless of whether they were successfully captured or not. In other words, if the transform feedback buffer was sized too small for the number of primitives output by the vertex stream, the first integer represents the number of primitives actually written and the second is the number that would have been written if all the transform feedback buffers associated with that vertex stream were large enough. Primitives generated queries write the number of primitives output to the vertex stream, regardless of whether transform feedback is active or not, or whether they were successfully captured by transform feedback or not. This is identical to the second integer of the transform feedback queries if transform feedback is active. -
If more than one query is retrieved and
strideis not at least as large as the size of the array of values corresponding to a single query, the values written to memory are undefined.
To retrieve status and results for a set of queries, call:
// Provided by VK_VERSION_1_0
VkResult vkGetQueryPoolResults(
VkDevice device,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount,
size_t dataSize,
void* pData,
VkDeviceSize stride,
VkQueryResultFlags flags);
-
deviceis the logical device that owns the query pool. -
queryPoolis the query pool managing the queries containing the desired results. -
firstQueryis the initial query index. -
queryCountis the number of queries to read. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to a user-allocated buffer where the results will be written -
strideis the stride in bytes between results for individual queries withinpData. -
flagsis a bitmask of VkQueryResultFlagBits specifying how and when results are returned.
Any results written for a query are written according to a layout dependent on the query type.
Results for any query in queryPool identified by firstQuery and
queryCount that is available are copied to pData.
If VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, results for all
queries in queryPool identified by firstQuery and
queryCount are copied to pData, along with an extra availability
value written directly after the results of each query and interpreted as an
unsigned integer.
A value of zero indicates that the results are not yet available, otherwise
the query is complete and results are available.
If VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set, results for all queries
in queryPool identified by firstQuery and queryCount are
copied to pData, along with an extra status value written directly
after the results of each query and interpreted as a signed integer.
A value of zero indicates that the results are not yet available.
Positive values indicate that the operations within the query completed
successfully, and the query results are valid.
Negative values indicate that the operations within the query completed
unsuccessfully.
VkQueryResultStatusKHR defines specific meaning for values returned here, though implementations are free to return other values.
Results for any available query written by this command are final and
represent the final result of the query.
If VK_QUERY_RESULT_PARTIAL_BIT is set, then for any query that is
unavailable, an intermediate result between zero and the final result value
is written for that query.
Otherwise, any result written by this command is undefined.
If VK_QUERY_RESULT_64_BIT is set, results and availability
or status
values for all queries are written as an array of 64-bit values.
If the queryPool was created with
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, results for each query are
written as an array of the type indicated by
VkPerformanceCounterKHR::storage for the counter being queried.
Otherwise, results and availability
or status
values are written as an array of 32-bit values.
If an unsigned integer query’s value overflows the result type, the value
may either wrap or saturate.
If a signed integer query’s value overflows the result type, the value is
undefined.
If a floating point query’s value is not representable as the result type,
the value is undefined.
If VK_QUERY_RESULT_WAIT_BIT is set, this command defines an execution
dependency with any earlier commands that writes one of the identified
queries.
The first synchronization scope
includes all instances of vkCmdEndQuery,
vkCmdEndQueryIndexedEXT,
vkCmdWriteTimestamp2,
and vkCmdWriteTimestamp that reference any query in queryPool
indicated by firstQuery and queryCount.
The second synchronization scope
includes the host operations of this command.
|
Note
Applications must take care to ensure that use of the
For example, if a query has been used previously and a command buffer
records the commands The above also applies when A similar situation can arise with the
|
|
Note
Applications can double-buffer query pool usage, with a pool per frame, and reset queries at the end of the frame in which they are read. |
Bits which can be set in vkGetQueryPoolResults::flags and
vkCmdCopyQueryPoolResults::flags, specifying how and when
results are returned, are:
// Provided by VK_VERSION_1_0
typedef enum VkQueryResultFlagBits {
VK_QUERY_RESULT_64_BIT = 0x00000001,
VK_QUERY_RESULT_WAIT_BIT = 0x00000002,
VK_QUERY_RESULT_WITH_AVAILABILITY_BIT = 0x00000004,
VK_QUERY_RESULT_PARTIAL_BIT = 0x00000008,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_QUERY_RESULT_WITH_STATUS_BIT_KHR = 0x00000010,
#endif
} VkQueryResultFlagBits;
-
VK_QUERY_RESULT_64_BITspecifies the results will be written as an array of 64-bit unsigned integer values. If this bit is not set, the results will be written as an array of 32-bit unsigned integer values. -
VK_QUERY_RESULT_WAIT_BITspecifies that Vulkan will wait for each query’s status to become available before retrieving its results. -
VK_QUERY_RESULT_WITH_AVAILABILITY_BITspecifies that the availability status accompanies the results. -
VK_QUERY_RESULT_PARTIAL_BITspecifies that returning partial results is acceptable. -
VK_QUERY_RESULT_WITH_STATUS_BIT_KHRspecifies that the last value returned in the query is a VkQueryResultStatusKHR value. See result status query for information on how an application can determine whether the use of this flag bit is supported.
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueryResultFlags;
VkQueryResultFlags is a bitmask type for setting a mask of zero or
more VkQueryResultFlagBits.
Specific status codes that can be returned from a query are:
// Provided by VK_KHR_video_queue
typedef enum VkQueryResultStatusKHR {
VK_QUERY_RESULT_STATUS_ERROR_KHR = -1,
VK_QUERY_RESULT_STATUS_NOT_READY_KHR = 0,
VK_QUERY_RESULT_STATUS_COMPLETE_KHR = 1,
} VkQueryResultStatusKHR;
-
VK_QUERY_RESULT_STATUS_NOT_READY_KHRspecifies that the query result is not yet available. -
VK_QUERY_RESULT_STATUS_ERROR_KHRspecifies that operations did not complete successfully. -
VK_QUERY_RESULT_STATUS_COMPLETE_KHRspecifies that operations completed successfully and the query result is available.
To copy query statuses and numerical results directly to buffer memory, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyQueryPoolResults(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
VkDeviceSize stride,
VkQueryResultFlags flags);
-
commandBufferis the command buffer into which this command will be recorded. -
queryPoolis the query pool managing the queries containing the desired results. -
firstQueryis the initial query index. -
queryCountis the number of queries.firstQueryandqueryCounttogether define a range of queries. -
dstBufferis a VkBuffer object that will receive the results of the copy command. -
dstOffsetis an offset intodstBuffer. -
strideis the stride in bytes between results for individual queries withindstBuffer. The required size of the backing memory fordstBufferis determined as described above for vkGetQueryPoolResults. -
flagsis a bitmask of VkQueryResultFlagBits specifying how and when results are returned.
Any results written for a query are written according to a layout dependent on the query type.
Results for any query in queryPool identified by firstQuery and
queryCount that is available are copied to dstBuffer.
If VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, results for all
queries in queryPool identified by firstQuery and
queryCount are copied to dstBuffer, along with an extra
availability value written directly after the results of each query and
interpreted as an unsigned integer.
A value of zero indicates that the results are not yet available, otherwise
the query is complete and results are available.
If VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is set, results for all queries
in queryPool identified by firstQuery and queryCount are
copied to dstBuffer, along with an extra status value written directly
after the results of each query and interpreted as a signed integer.
A value of zero indicates that the results are not yet available.
Positive values indicate that the operations within the query completed
successfully, and the query results are valid.
Negative values indicate that the operations within the query completed
unsuccessfully.
VkQueryResultStatusKHR defines specific meaning for values returned here, though implementations are free to return other values.
Results for any available query written by this command are final and
represent the final result of the query.
If VK_QUERY_RESULT_PARTIAL_BIT is set, then for any query that is
unavailable, an intermediate result between zero and the final result value
is written for that query.
Otherwise, any result written by this command is undefined.
If VK_QUERY_RESULT_64_BIT is set, results and availability
or status
values for all queries are written as an array of 64-bit values.
If the queryPool was created with
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, results for each query are
written as an array of the type indicated by
VkPerformanceCounterKHR::storage for the counter being queried.
Otherwise, results and availability
or status
values are written as an array of 32-bit values.
If an unsigned integer query’s value overflows the result type, the value
may either wrap or saturate.
If a signed integer query’s value overflows the result type, the value is
undefined.
If a floating point query’s value is not representable as the result type,
the value is undefined.
This command defines an execution dependency between other query commands that reference the same query.
The first synchronization scope
includes all commands which reference the queries in queryPool
indicated by query that occur earlier in
submission order.
If flags does not include VK_QUERY_RESULT_WAIT_BIT,
vkCmdEndQueryIndexedEXT,
vkCmdWriteTimestamp2,
vkCmdEndQuery, and vkCmdWriteTimestamp are excluded from this
scope.
The second synchronization scope
includes all commands which reference the queries in queryPool
indicated by query that occur later in
submission order.
The operation of this command happens after the first scope and happens before the second scope.
vkCmdCopyQueryPoolResults is considered to be a transfer operation,
and its writes to buffer memory must be synchronized using
VK_PIPELINE_STAGE_TRANSFER_BIT and VK_ACCESS_TRANSFER_WRITE_BIT
before using the results.
Rendering operations such as clears, MSAA resolves, attachment load/store operations, and blits may count towards the results of queries. This behavior is implementation-dependent and may vary depending on the path used within an implementation. For example, some implementations have several types of clears, some of which may include vertices and some not.
18.3. Occlusion Queries
Occlusion queries track the number of samples that pass the per-fragment
tests for a set of drawing commands.
As such, occlusion queries are only available on queue families supporting
graphics operations.
The application can then use these results to inform future rendering
decisions.
An occlusion query is begun and ended by calling vkCmdBeginQuery and
vkCmdEndQuery, respectively.
When an occlusion query begins, the count of passing samples always starts
at zero.
For each drawing command, the count is incremented as described in
Sample Counting.
If flags does not contain VK_QUERY_CONTROL_PRECISE_BIT an
implementation may generate any non-zero result value for the query if the
count of passing samples is non-zero.
|
Note
Not setting |
When an occlusion query finishes, the result for that query is marked as
available.
The application can then either copy the result to a buffer (via
vkCmdCopyQueryPoolResults) or request it be put into host memory (via
vkGetQueryPoolResults).
|
Note
If occluding geometry is not drawn first, samples can pass the depth test, but still not be visible in a final image. |
18.4. Pipeline Statistics Queries
Pipeline statistics queries allow the application to sample a specified set
of VkPipeline counters.
These counters are accumulated by Vulkan for a set of either drawing or
dispatching commands while a pipeline statistics query is active.
As such, pipeline statistics queries are available on queue families
supporting either graphics or compute operations.
The availability of pipeline statistics queries is indicated by the
pipelineStatisticsQuery member of the VkPhysicalDeviceFeatures
object (see vkGetPhysicalDeviceFeatures and vkCreateDevice for
detecting and requesting this query type on a VkDevice).
A pipeline statistics query is begun and ended by calling
vkCmdBeginQuery and vkCmdEndQuery, respectively.
When a pipeline statistics query begins, all statistics counters are set to
zero.
While the query is active, the pipeline type determines which set of
statistics are available, but these must be configured on the query pool
when it is created.
If a statistic counter is issued on a command buffer that does not support
the corresponding operation, the value of that counter is undefined after
the query has been made available.
At least one statistic counter relevant to the operations supported on the
recording command buffer must be enabled.
Bits which can be set in
VkQueryPoolCreateInfo::pipelineStatistics for query pools and in
VkCommandBufferInheritanceInfo::pipelineStatistics for secondary
command buffers, individually enabling pipeline statistics counters, are:
// Provided by VK_VERSION_1_0
typedef enum VkQueryPipelineStatisticFlagBits {
VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT = 0x00000001,
VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BIT = 0x00000002,
VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BIT = 0x00000004,
VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BIT = 0x00000008,
VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BIT = 0x00000010,
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT = 0x00000020,
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT = 0x00000040,
VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT = 0x00000080,
VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BIT = 0x00000100,
VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT = 0x00000200,
VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BIT = 0x00000400,
} VkQueryPipelineStatisticFlagBits;
-
VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BITspecifies that queries managed by the pool will count the number of vertices processed by the input assembly stage. Vertices corresponding to incomplete primitives may contribute to the count. -
VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BITspecifies that queries managed by the pool will count the number of primitives processed by the input assembly stage. If primitive restart is enabled, restarting the primitive topology has no effect on the count. Incomplete primitives may be counted. -
VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BITspecifies that queries managed by the pool will count the number of vertex shader invocations. This counter’s value is incremented each time a vertex shader is invoked. -
VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BITspecifies that queries managed by the pool will count the number of geometry shader invocations. This counter’s value is incremented each time a geometry shader is invoked. In the case of instanced geometry shaders, the geometry shader invocations count is incremented for each separate instanced invocation. -
VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BITspecifies that queries managed by the pool will count the number of primitives generated by geometry shader invocations. The counter’s value is incremented each time the geometry shader emits a primitive. Restarting primitive topology using the SPIR-V instructionsOpEndPrimitiveorOpEndStreamPrimitivehas no effect on the geometry shader output primitives count. -
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BITspecifies that queries managed by the pool will count the number of primitives processed by the Primitive Clipping stage of the pipeline. The counter’s value is incremented each time a primitive reaches the primitive clipping stage. -
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BITspecifies that queries managed by the pool will count the number of primitives output by the Primitive Clipping stage of the pipeline. The counter’s value is incremented each time a primitive passes the primitive clipping stage. The actual number of primitives output by the primitive clipping stage for a particular input primitive is implementation-dependent but must satisfy the following conditions:-
If at least one vertex of the input primitive lies inside the clipping volume, the counter is incremented by one or more.
-
Otherwise, the counter is incremented by zero or more.
-
-
VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BITspecifies that queries managed by the pool will count the number of fragment shader invocations. The counter’s value is incremented each time the fragment shader is invoked. -
VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BITspecifies that queries managed by the pool will count the number of patches processed by the tessellation control shader. The counter’s value is incremented once for each patch for which a tessellation control shader is invoked. -
VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BITspecifies that queries managed by the pool will count the number of invocations of the tessellation evaluation shader. The counter’s value is incremented each time the tessellation evaluation shader is invoked. -
VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BITspecifies that queries managed by the pool will count the number of compute shader invocations. The counter’s value is incremented every time the compute shader is invoked. Implementations may skip the execution of certain compute shader invocations or execute additional compute shader invocations for implementation-dependent reasons as long as the results of rendering otherwise remain unchanged.
These values are intended to measure relative statistics on one implementation. Various device architectures will count these values differently. Any or all counters may be affected by the issues described in Query Operation.
|
Note
For example, tile-based rendering devices may need to replay the scene multiple times, affecting some of the counts. |
If a pipeline has rasterizerDiscardEnable enabled, implementations
may discard primitives after the final
pre-rasterization shader
stage.
As a result, if rasterizerDiscardEnable is enabled, the clipping input
and output primitives counters may not be incremented.
When a pipeline statistics query finishes, the result for that query is
marked as available.
The application can copy the result to a buffer (via
vkCmdCopyQueryPoolResults), or request it be put into host memory (via
vkGetQueryPoolResults).
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueryPipelineStatisticFlags;
VkQueryPipelineStatisticFlags is a bitmask type for setting a mask of
zero or more VkQueryPipelineStatisticFlagBits.
18.5. Timestamp Queries
Timestamps provide applications with a mechanism for timing the execution
of commands.
A timestamp is an integer value generated by the VkPhysicalDevice.
Unlike other queries, timestamps do not operate over a range, and so do not
use vkCmdBeginQuery or vkCmdEndQuery.
The mechanism is built around a set of commands that allow the application
to tell the VkPhysicalDevice to write timestamp values to a
query pool and then either read timestamp values on the
host (using vkGetQueryPoolResults) or copy timestamp values to a
VkBuffer (using vkCmdCopyQueryPoolResults).
The application can then compute differences between timestamps to
determine execution time.
The number of valid bits in a timestamp value is determined by the
VkQueueFamilyProperties::timestampValidBits property of the
queue on which the timestamp is written.
Timestamps are supported on any queue which reports a non-zero value for
timestampValidBits via vkGetPhysicalDeviceQueueFamilyProperties.
If the timestampComputeAndGraphics limit is VK_TRUE, timestamps are
supported by every queue family that supports either graphics or compute
operations (see VkQueueFamilyProperties).
The number of nanoseconds it takes for a timestamp value to be incremented
by 1 can be obtained from
VkPhysicalDeviceLimits::timestampPeriod after a call to
vkGetPhysicalDeviceProperties.
To request a timestamp and write the value to memory, call:
// Provided by VK_VERSION_1_3
void vkCmdWriteTimestamp2(
VkCommandBuffer commandBuffer,
VkPipelineStageFlags2 stage,
VkQueryPool queryPool,
uint32_t query);
or the equivalent command
// Provided by VK_KHR_synchronization2
void vkCmdWriteTimestamp2KHR(
VkCommandBuffer commandBuffer,
VkPipelineStageFlags2 stage,
VkQueryPool queryPool,
uint32_t query);
-
commandBufferis the command buffer into which the command will be recorded. -
stagespecifies a stage of the pipeline. -
queryPoolis the query pool that will manage the timestamp. -
queryis the query within the query pool that will contain the timestamp.
When vkCmdWriteTimestamp2 is submitted to a queue, it defines an
execution dependency on commands that were submitted before it, and writes a
timestamp to a query pool.
The first synchronization scope
includes all commands that occur earlier in
submission order.
The synchronization scope is limited to operations on the pipeline stage
specified by stage.
The second synchronization scope includes only the timestamp write operation.
When the timestamp value is written, the availability status of the query is set to available.
|
Note
If an implementation is unable to detect completion and latch the timer
immediately after |
Comparisons between timestamps are not meaningful if the timestamps are written by commands submitted to different queues.
|
Note
An example of such a comparison is subtracting an older timestamp from a newer one to determine the execution time of a sequence of commands. |
If vkCmdWriteTimestamp2 is called while executing a render pass
instance that has multiview enabled, the timestamp uses N consecutive
query indices in the query pool (starting at query) where N is
the number of bits set in the view mask of the subpass the command is
executed in.
The resulting query values are determined by an implementation-dependent
choice of one of the following behaviors:
-
The first query is a timestamp value and (if more than one bit is set in the view mask) zero is written to the remaining queries. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the difference between the first query written by each command.
-
All N queries are timestamp values. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the sum of the difference between corresponding queries written by each command. The difference between corresponding queries may be the execution time of a single view.
In either case, the application can sum the differences between all N queries to determine the total execution time.
To request a timestamp and write the value to memory, call:
// Provided by VK_VERSION_1_0
void vkCmdWriteTimestamp(
VkCommandBuffer commandBuffer,
VkPipelineStageFlagBits pipelineStage,
VkQueryPool queryPool,
uint32_t query);
-
commandBufferis the command buffer into which the command will be recorded. -
pipelineStageis a VkPipelineStageFlagBits value, specifying a stage of the pipeline. -
queryPoolis the query pool that will manage the timestamp. -
queryis the query within the query pool that will contain the timestamp.
When vkCmdWriteTimestamp is submitted to a queue, it defines an
execution dependency on commands that were submitted before it, and writes a
timestamp to a query pool.
The first synchronization scope
includes all commands that occur earlier in
submission order.
The synchronization scope is limited to operations on the pipeline stage
specified by pipelineStage.
The second synchronization scope includes only the timestamp write operation.
When the timestamp value is written, the availability status of the query is set to available.
|
Note
If an implementation is unable to detect completion and latch the timer
immediately after |
Comparisons between timestamps are not meaningful if the timestamps are written by commands submitted to different queues.
|
Note
An example of such a comparison is subtracting an older timestamp from a newer one to determine the execution time of a sequence of commands. |
If vkCmdWriteTimestamp is called while executing a render pass
instance that has multiview enabled, the timestamp uses N consecutive
query indices in the query pool (starting at query) where N is
the number of bits set in the view mask of the subpass the command is
executed in.
The resulting query values are determined by an implementation-dependent
choice of one of the following behaviors:
-
The first query is a timestamp value and (if more than one bit is set in the view mask) zero is written to the remaining queries. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the difference between the first query written by each command.
-
All N queries are timestamp values. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the sum of the difference between corresponding queries written by each command. The difference between corresponding queries may be the execution time of a single view.
In either case, the application can sum the differences between all N queries to determine the total execution time.
18.6. Performance Queries
Performance queries provide applications with a mechanism for getting performance counter information about the execution of command buffers, render passes, and commands.
Each queue family advertises the performance counters that can be queried on a queue of that family via a call to vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR. Implementations may limit access to performance counters based on platform requirements or only to specialized drivers for development purposes.
|
Note
This may include no performance counters being enumerated, or a reduced set. Please refer to platform-specific documentation for guidance on any such restrictions. |
Performance queries use the existing vkCmdBeginQuery and vkCmdEndQuery to control what command buffers, render passes, or commands to get performance information for.
Implementations may require multiple passes where the command buffer, render passes, or commands being recorded are the same and are executed on the same queue to record performance counter data. This is achieved by submitting the same batch and providing a VkPerformanceQuerySubmitInfoKHR structure containing a counter pass index. The number of passes required for a given performance query pool can be queried via a call to vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR.
|
Note
Command buffers created with
|
Performance counter results from a performance query pool can be obtained with the command vkGetQueryPoolResults.
The VkPerformanceCounterResultKHR union is defined as:
-
int32is a 32-bit signed integer value. -
int64is a 64-bit signed integer value. -
uint32is a 32-bit unsigned integer value. -
uint64is a 64-bit unsigned integer value. -
float32is a 32-bit floating-point value. -
float64is a 64-bit floating-point value.
Performance query results are returned in an array of
VkPerformanceCounterResultKHR unions containing the data associated
with each counter in the query, stored in the same order as the counters
supplied in pCounterIndices when creating the performance query.
The VkPerformanceCounterKHR::unit enumeration specifies how to
parse the counter data.
// Provided by VK_KHR_performance_query
typedef union VkPerformanceCounterResultKHR {
int32_t int32;
int64_t int64;
uint32_t uint32;
uint64_t uint64;
float float32;
double float64;
} VkPerformanceCounterResultKHR;
18.6.1. Profiling Lock
To record and submit a command buffer containing a performance query pool the profiling lock must be held. The profiling lock must be acquired prior to any call to vkBeginCommandBuffer that will be using a performance query pool. The profiling lock must be held while any command buffer containing a performance query pool is in the recording, executable, or pending state. To acquire the profiling lock, call:
// Provided by VK_KHR_performance_query
VkResult vkAcquireProfilingLockKHR(
VkDevice device,
const VkAcquireProfilingLockInfoKHR* pInfo);
-
deviceis the logical device to profile. -
pInfois a pointer to aVkAcquireProfilingLockInfoKHRstructure containing information about how the profiling is to be acquired.
Implementations may allow multiple actors to hold the profiling lock concurrently.
The VkAcquireProfilingLockInfoKHR structure is defined as:
// Provided by VK_KHR_performance_query
typedef struct VkAcquireProfilingLockInfoKHR {
VkStructureType sType;
const void* pNext;
VkAcquireProfilingLockFlagsKHR flags;
uint64_t timeout;
} VkAcquireProfilingLockInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
timeoutindicates how long the function waits, in nanoseconds, if the profiling lock is not available.
If timeout is 0, vkAcquireProfilingLockKHR will not block while
attempting to acquire the profling lock.
If timeout is UINT64_MAX, the function will not return until the
profiling lock was acquired.
// Provided by VK_KHR_performance_query
typedef enum VkAcquireProfilingLockFlagBitsKHR {
} VkAcquireProfilingLockFlagBitsKHR;
// Provided by VK_KHR_performance_query
typedef VkFlags VkAcquireProfilingLockFlagsKHR;
VkAcquireProfilingLockFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.
To release the profiling lock, call:
// Provided by VK_KHR_performance_query
void vkReleaseProfilingLockKHR(
VkDevice device);
-
deviceis the logical device to cease profiling on.
18.7. Transform Feedback Queries
Transform feedback queries track the number of primitives attempted to be
written and actually written, by the vertex stream being captured, to a
transform feedback buffer.
This query is updated during drawing commands while transform feedback is
active.
The number of primitives actually written will be less than the number
attempted to be written if the bound transform feedback buffer size was too
small for the number of primitives actually drawn.
Primitives are not written beyond the bound range of the transform feedback
buffer.
A transform feedback query is begun and ended by calling
vkCmdBeginQuery and vkCmdEndQuery, respectively to query for
vertex stream zero.
vkCmdBeginQueryIndexedEXT and vkCmdEndQueryIndexedEXT can be
used to begin and end transform feedback queries for any supported vertex
stream.
When a transform feedback query begins, the count of primitives written and
primitives needed starts from zero.
For each drawing command, the count is incremented as vertex attribute
outputs are captured to the transform feedback buffers while transform
feedback is active.
When a transform feedback query finishes, the result for that query is
marked as available.
The application can then either copy the result to a buffer (via
vkCmdCopyQueryPoolResults) or request it be put into host memory (via
vkGetQueryPoolResults).
18.8. Primitives Generated Queries
When a generated primitive query for a vertex stream is active, the
primitives-generated count is incremented every time a primitive emitted to
that stream reaches the transform feedback stage, whether or not transform
feedback is active.
A primitives generated query is begun and ended by calling
vkCmdBeginQuery and vkCmdEndQuery, respectively to query for
vertex stream zero.
vkCmdBeginQueryIndexedEXT and vkCmdEndQueryIndexedEXT can be
used to begin and end primitives generated queries for any supported vertex
stream.
When a primitives generated query begins, the count of primitives generated
starts from zero.
When a primitives generated query finishes, the result for that query is
marked as available.
The application can then either copy the result to a buffer (via
vkCmdCopyQueryPoolResults) or request it be put into host memory (via
vkGetQueryPoolResults).
|
Note
The result of this query is typically identical to
|
18.9. Intel performance queries
Intel performance queries allow an application to capture performance data for a set of commands. Performance queries are used in a similar way than other types of queries. A main difference with existing queries is that the resulting data should be handed over to a library capabable to produce human readable results rather than being read directly by an application.
Prior to creating a performance query pool, initialize the device for performance queries with the call:
// Provided by VK_INTEL_performance_query
VkResult vkInitializePerformanceApiINTEL(
VkDevice device,
const VkInitializePerformanceApiInfoINTEL* pInitializeInfo);
-
deviceis the logical device used for the queries. -
pInitializeInfois a pointer to a VkInitializePerformanceApiInfoINTEL structure specifying initialization parameters.
The VkInitializePerformanceApiInfoINTEL structure is defined as :
// Provided by VK_INTEL_performance_query
typedef struct VkInitializePerformanceApiInfoINTEL {
VkStructureType sType;
const void* pNext;
void* pUserData;
} VkInitializePerformanceApiInfoINTEL;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pUserDatais a pointer for application data.
Once performance query operations have completed, uninitalize the device for performance queries with the call:
// Provided by VK_INTEL_performance_query
void vkUninitializePerformanceApiINTEL(
VkDevice device);
-
deviceis the logical device used for the queries.
Some performance query features of a device can be discovered with the call:
// Provided by VK_INTEL_performance_query
VkResult vkGetPerformanceParameterINTEL(
VkDevice device,
VkPerformanceParameterTypeINTEL parameter,
VkPerformanceValueINTEL* pValue);
-
deviceis the logical device to query. -
parameteris the parameter to query. -
pValueis a pointer to a VkPerformanceValueINTEL structure in which the type and value of the parameter are returned.
Possible values of vkGetPerformanceParameterINTEL::parameter,
specifying a performance query feature, are:
// Provided by VK_INTEL_performance_query
typedef enum VkPerformanceParameterTypeINTEL {
VK_PERFORMANCE_PARAMETER_TYPE_HW_COUNTERS_SUPPORTED_INTEL = 0,
VK_PERFORMANCE_PARAMETER_TYPE_STREAM_MARKER_VALID_BITS_INTEL = 1,
} VkPerformanceParameterTypeINTEL;
-
VK_PERFORMANCE_PARAMETER_TYPE_HW_COUNTERS_SUPPORTED_INTELhas a boolean result which tells whether hardware counters can be captured. -
VK_PERFORMANCE_PARAMETER_TYPE_STREAM_MARKER_VALID_BITS_INTELhas a 32 bits integer result which tells how many bits can be written into theVkPerformanceValueINTELvalue.
The VkPerformanceValueINTEL structure is defined as:
// Provided by VK_INTEL_performance_query
typedef struct VkPerformanceValueINTEL {
VkPerformanceValueTypeINTEL type;
VkPerformanceValueDataINTEL data;
} VkPerformanceValueINTEL;
-
typeis a VkPerformanceValueTypeINTEL value specifying the type of the returned data. -
datais a VkPerformanceValueDataINTEL union specifying the value of the returned data.
Possible values of VkPerformanceValueINTEL::type, specifying the
type of the data returned in VkPerformanceValueINTEL::data, are:
-
VK_PERFORMANCE_VALUE_TYPE_UINT32_INTELspecifies that unsigned 32-bit integer data is returned indata.value32. -
VK_PERFORMANCE_VALUE_TYPE_UINT64_INTELspecifies that unsigned 64-bit integer data is returned indata.value64. -
VK_PERFORMANCE_VALUE_TYPE_FLOAT_INTELspecifies that floating-point data is returned indata.valueFloat. -
VK_PERFORMANCE_VALUE_TYPE_BOOL_INTELspecifies thatBool32data is returned indata.valueBool. -
VK_PERFORMANCE_VALUE_TYPE_STRING_INTELspecifies that a pointer to a null-terminated UTF-8 string is returned indata.valueString. The pointer is valid for the lifetime of thedeviceparameter passed to vkGetPerformanceParameterINTEL.
// Provided by VK_INTEL_performance_query
typedef enum VkPerformanceValueTypeINTEL {
VK_PERFORMANCE_VALUE_TYPE_UINT32_INTEL = 0,
VK_PERFORMANCE_VALUE_TYPE_UINT64_INTEL = 1,
VK_PERFORMANCE_VALUE_TYPE_FLOAT_INTEL = 2,
VK_PERFORMANCE_VALUE_TYPE_BOOL_INTEL = 3,
VK_PERFORMANCE_VALUE_TYPE_STRING_INTEL = 4,
} VkPerformanceValueTypeINTEL;
The VkPerformanceValueDataINTEL union is defined as:
// Provided by VK_INTEL_performance_query
typedef union VkPerformanceValueDataINTEL {
uint32_t value32;
uint64_t value64;
float valueFloat;
VkBool32 valueBool;
const char* valueString;
} VkPerformanceValueDataINTEL;
-
data.value32represents 32-bit integer data. -
data.value64represents 64-bit integer data. -
data.valueFloatrepresents floating-point data. -
data.valueBoolrepresentsBool32data. -
data.valueStringrepresents a pointer to a null-terminated UTF-8 string.
The correct member of the union is determined by the associated VkPerformanceValueTypeINTEL value.
The VkQueryPoolPerformanceQueryCreateInfoINTEL structure is defined
as:
// Provided by VK_INTEL_performance_query
typedef struct VkQueryPoolPerformanceQueryCreateInfoINTEL {
VkStructureType sType;
const void* pNext;
VkQueryPoolSamplingModeINTEL performanceCountersSampling;
} VkQueryPoolPerformanceQueryCreateInfoINTEL;
// Provided by VK_INTEL_performance_query
typedef VkQueryPoolPerformanceQueryCreateInfoINTEL VkQueryPoolCreateInfoINTEL;
To create a pool for Intel performance queries, set
VkQueryPoolCreateInfo::queryType to
VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL and add a
VkQueryPoolPerformanceQueryCreateInfoINTEL structure to the
pNext chain of the VkQueryPoolCreateInfo structure.
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
performanceCountersSamplingdescribe how performance queries should be captured.
Possible values of
VkQueryPoolPerformanceQueryCreateInfoINTEL::performanceCountersSampling
are:
// Provided by VK_INTEL_performance_query
typedef enum VkQueryPoolSamplingModeINTEL {
VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL = 0,
} VkQueryPoolSamplingModeINTEL;
-
VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTELis the default mode in which the application calls vkCmdBeginQuery and vkCmdEndQuery to record performance data.
To help associate query results with a particular point at which an application emitted commands, markers can be set into the command buffers with the call:
// Provided by VK_INTEL_performance_query
VkResult vkCmdSetPerformanceMarkerINTEL(
VkCommandBuffer commandBuffer,
const VkPerformanceMarkerInfoINTEL* pMarkerInfo);
The last marker set onto a command buffer before the end of a query will be part of the query result.
The VkPerformanceMarkerInfoINTEL structure is defined as:
// Provided by VK_INTEL_performance_query
typedef struct VkPerformanceMarkerInfoINTEL {
VkStructureType sType;
const void* pNext;
uint64_t marker;
} VkPerformanceMarkerInfoINTEL;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
markeris the marker value that will be recorded into the opaque query results.
When monitoring the behavior of an application within the dataset generated by the entire set of applications running on the system, it is useful to identify draw calls within a potentially huge amount of performance data. To do so, application can generate stream markers that will be used to trace back a particular draw call with a particular performance data item.
// Provided by VK_INTEL_performance_query
VkResult vkCmdSetPerformanceStreamMarkerINTEL(
VkCommandBuffer commandBuffer,
const VkPerformanceStreamMarkerInfoINTEL* pMarkerInfo);
The VkPerformanceStreamMarkerInfoINTEL structure is defined as:
// Provided by VK_INTEL_performance_query
typedef struct VkPerformanceStreamMarkerInfoINTEL {
VkStructureType sType;
const void* pNext;
uint32_t marker;
} VkPerformanceStreamMarkerInfoINTEL;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
markeris the marker value that will be recorded into the reports consumed by an external application.
Some applications might want measure the effect of a set of commands with a different settings. It is possible to override a particular settings using :
// Provided by VK_INTEL_performance_query
VkResult vkCmdSetPerformanceOverrideINTEL(
VkCommandBuffer commandBuffer,
const VkPerformanceOverrideInfoINTEL* pOverrideInfo);
-
commandBufferis the command buffer where the override takes place. -
pOverrideInfois a pointer to a VkPerformanceOverrideInfoINTEL structure selecting the parameter to override.
The VkPerformanceOverrideInfoINTEL structure is defined as:
// Provided by VK_INTEL_performance_query
typedef struct VkPerformanceOverrideInfoINTEL {
VkStructureType sType;
const void* pNext;
VkPerformanceOverrideTypeINTEL type;
VkBool32 enable;
uint64_t parameter;
} VkPerformanceOverrideInfoINTEL;
-
typeis the particular VkPerformanceOverrideTypeINTEL to set. -
enabledefines whether the override is enabled. -
parameteris a potential required parameter for the override.
Possible values of VkPerformanceOverrideInfoINTEL::type,
specifying performance override types, are:
// Provided by VK_INTEL_performance_query
typedef enum VkPerformanceOverrideTypeINTEL {
VK_PERFORMANCE_OVERRIDE_TYPE_NULL_HARDWARE_INTEL = 0,
VK_PERFORMANCE_OVERRIDE_TYPE_FLUSH_GPU_CACHES_INTEL = 1,
} VkPerformanceOverrideTypeINTEL;
-
VK_PERFORMANCE_OVERRIDE_TYPE_NULL_HARDWARE_INTELturns all rendering operations into noop. -
VK_PERFORMANCE_OVERRIDE_TYPE_FLUSH_GPU_CACHES_INTELstalls the stream of commands until all previously emitted commands have completed and all caches been flushed and invalidated.
Before submitting command buffers containing performance queries commands to a device queue, the application must acquire and set a performance query configuration. The configuration can be released once all command buffers containing performance query commands are not in a pending state.
// Provided by VK_INTEL_performance_query
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPerformanceConfigurationINTEL)
To acquire a device performance configuration, call:
// Provided by VK_INTEL_performance_query
VkResult vkAcquirePerformanceConfigurationINTEL(
VkDevice device,
const VkPerformanceConfigurationAcquireInfoINTEL* pAcquireInfo,
VkPerformanceConfigurationINTEL* pConfiguration);
-
deviceis the logical device that the performance query commands will be submitted to. -
pAcquireInfois a pointer to a VkPerformanceConfigurationAcquireInfoINTEL structure, specifying the performance configuration to acquire. -
pConfigurationis a pointer to aVkPerformanceConfigurationINTELhandle in which the resulting configuration object is returned.
The VkPerformanceConfigurationAcquireInfoINTEL structure is defined
as:
// Provided by VK_INTEL_performance_query
typedef struct VkPerformanceConfigurationAcquireInfoINTEL {
VkStructureType sType;
const void* pNext;
VkPerformanceConfigurationTypeINTEL type;
} VkPerformanceConfigurationAcquireInfoINTEL;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis one of the VkPerformanceConfigurationTypeINTEL type of performance configuration that will be acquired.
Possible values of
VkPerformanceConfigurationAcquireInfoINTEL::type, specifying
performance configuration types, are:
// Provided by VK_INTEL_performance_query
typedef enum VkPerformanceConfigurationTypeINTEL {
VK_PERFORMANCE_CONFIGURATION_TYPE_COMMAND_QUEUE_METRICS_DISCOVERY_ACTIVATED_INTEL = 0,
} VkPerformanceConfigurationTypeINTEL;
To set a performance configuration, call:
// Provided by VK_INTEL_performance_query
VkResult vkQueueSetPerformanceConfigurationINTEL(
VkQueue queue,
VkPerformanceConfigurationINTEL configuration);
-
queueis the queue on which the configuration will be used. -
configurationis the configuration to use.
To release a device performance configuration, call:
// Provided by VK_INTEL_performance_query
VkResult vkReleasePerformanceConfigurationINTEL(
VkDevice device,
VkPerformanceConfigurationINTEL configuration);
-
deviceis the device associated to the configuration object to release. -
configurationis the configuration object to release.
18.10. Result Status Queries
Result status queries are used for a single purpose - to check whether a set
of operations has completed successfully or not, using the
VK_QUERY_RESULT_WITH_STATUS_BIT_KHR flag.
No other data is written to such a query.
In order to determine if a queue family supports result status queries and
use of VK_QUERY_RESULT_WITH_STATUS_BIT_KHR flag, add a
VkQueueFamilyQueryResultStatusProperties2KHR structure to the
pNext chain of VkQueueFamilyProperties2 when calling
vkGetPhysicalDeviceQueueFamilyProperties2.
The VkQueueFamilyQueryResultStatusProperties2KHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkQueueFamilyQueryResultStatusProperties2KHR {
VkStructureType sType;
void* pNext;
VkBool32 queryResultStatusSupport;
} VkQueueFamilyQueryResultStatusProperties2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queryResultStatusSupportreportsVK_TRUEif query typeVK_QUERY_TYPE_RESULT_STATUS_ONLY_KHRand use ofVK_QUERY_RESULT_WITH_STATUS_BIT_KHRare supported.
18.11. Video Encode Bitstream Buffer Range
Bitstream buffer range queries describe the range of bytes written in the bitstream buffer by video encode commands.
When an encode command is recorded within a bitstream buffer range query, two values are written to the query slot. The first value is an offset into the bitstream buffer where the encoded video data was written. This offset is an additional offset from the start of the range specified by the application. The second value is a size value describing the number of bytes written to the bitstream buffer beyond the offset.
One slot is consumed for each slice in each command recorded between a begin and end query pair.
19. Clear Commands
19.1. Clearing Images Outside A Render Pass Instance
Color and depth/stencil images can be cleared outside a render pass instance using vkCmdClearColorImage or vkCmdClearDepthStencilImage, respectively. These commands are only allowed outside of a render pass instance.
To clear one or more subranges of a color image, call:
// Provided by VK_VERSION_1_0
void vkCmdClearColorImage(
VkCommandBuffer commandBuffer,
VkImage image,
VkImageLayout imageLayout,
const VkClearColorValue* pColor,
uint32_t rangeCount,
const VkImageSubresourceRange* pRanges);
-
commandBufferis the command buffer into which the command will be recorded. -
imageis the image to be cleared. -
imageLayoutspecifies the current layout of the image subresource ranges to be cleared, and must beVK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,VK_IMAGE_LAYOUT_GENERALorVK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. -
pColoris a pointer to a VkClearColorValue structure containing the values that the image subresource ranges will be cleared to (see Clear Values below). -
rangeCountis the number of image subresource range structures inpRanges. -
pRangesis a pointer to an array of VkImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.
Each specified range in pRanges is cleared to the value specified by
pColor.
To clear one or more subranges of a depth/stencil image, call:
// Provided by VK_VERSION_1_0
void vkCmdClearDepthStencilImage(
VkCommandBuffer commandBuffer,
VkImage image,
VkImageLayout imageLayout,
const VkClearDepthStencilValue* pDepthStencil,
uint32_t rangeCount,
const VkImageSubresourceRange* pRanges);
-
commandBufferis the command buffer into which the command will be recorded. -
imageis the image to be cleared. -
imageLayoutspecifies the current layout of the image subresource ranges to be cleared, and must beVK_IMAGE_LAYOUT_GENERALorVK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. -
pDepthStencilis a pointer to a VkClearDepthStencilValue structure containing the values that the depth and stencil image subresource ranges will be cleared to (see Clear Values below). -
rangeCountis the number of image subresource range structures inpRanges. -
pRangesis a pointer to an array of VkImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.
Clears outside render pass instances are treated as transfer operations for the purposes of memory barriers.
19.2. Clearing Images Inside A Render Pass Instance
To clear one or more regions of color and depth/stencil attachments inside a render pass instance, call:
// Provided by VK_VERSION_1_0
void vkCmdClearAttachments(
VkCommandBuffer commandBuffer,
uint32_t attachmentCount,
const VkClearAttachment* pAttachments,
uint32_t rectCount,
const VkClearRect* pRects);
-
commandBufferis the command buffer into which the command will be recorded. -
attachmentCountis the number of entries in thepAttachmentsarray. -
pAttachmentsis a pointer to an array of VkClearAttachment structures defining the attachments to clear and the clear values to use. If any attachment index to be cleared is not backed by an image view, then the clear has no effect. -
rectCountis the number of entries in thepRectsarray. -
pRectsis a pointer to an array of VkClearRect structures defining regions within each selected attachment to clear.
If the render pass has a fragment density map attachment, clears follow the operations of fragment density maps as if each clear region was a primitive which generates fragments. The clear color is applied to all pixels inside each fragment’s area regardless if the pixels lie outside of the clear region. Clears may have a different set of supported fragment areas than draws.
Unlike other clear commands, vkCmdClearAttachments is not a
transfer command.
It performs its operations in rasterization order.
For color attachments, the operations are executed as color attachment
writes, by the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage.
For depth/stencil attachments, the operations are executed as
depth writes and stencil writes by
the VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and
VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages.
vkCmdClearAttachments is not affected by the bound pipeline state.
|
Note
It is generally preferable to clear attachments by using the
|
The VkClearRect structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkClearRect {
VkRect2D rect;
uint32_t baseArrayLayer;
uint32_t layerCount;
} VkClearRect;
-
rectis the two-dimensional region to be cleared. -
baseArrayLayeris the first layer to be cleared. -
layerCountis the number of layers to clear.
The layers [baseArrayLayer, baseArrayLayer +
layerCount) counting from the base layer of the attachment image view
are cleared.
The VkClearAttachment structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkClearAttachment {
VkImageAspectFlags aspectMask;
uint32_t colorAttachment;
VkClearValue clearValue;
} VkClearAttachment;
-
aspectMaskis a mask selecting the color, depth and/or stencil aspects of the attachment to be cleared. -
colorAttachmentis only meaningful ifVK_IMAGE_ASPECT_COLOR_BITis set inaspectMask, in which case it is an index into the currently bound color attachments. -
clearValueis the color or depth/stencil value to clear the attachment to, as described in Clear Values below.
19.3. Clear Values
The VkClearColorValue structure is defined as:
// Provided by VK_VERSION_1_0
typedef union VkClearColorValue {
float float32[4];
int32_t int32[4];
uint32_t uint32[4];
} VkClearColorValue;
-
float32are the color clear values when the format of the image or attachment is one of the formats in the Interpretation of Numeric Format table other than signed integer (SINT) or unsigned integer (UINT). Floating point values are automatically converted to the format of the image, with the clear value being treated as linear if the image is sRGB. -
int32are the color clear values when the format of the image or attachment is signed integer (SINT). Signed integer values are converted to the format of the image by casting to the smaller type (with negative 32-bit values mapping to negative values in the smaller type). If the integer clear value is not representable in the target type (e.g. would overflow in conversion to that type), the clear value is undefined. -
uint32are the color clear values when the format of the image or attachment is unsigned integer (UINT). Unsigned integer values are converted to the format of the image by casting to the integer type with fewer bits.
The four array elements of the clear color map to R, G, B, and A components of image formats, in order.
If the image has more than one sample, the same value is written to all samples for any pixels being cleared.
The VkClearDepthStencilValue structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkClearDepthStencilValue {
float depth;
uint32_t stencil;
} VkClearDepthStencilValue;
-
depthis the clear value for the depth aspect of the depth/stencil attachment. It is a floating-point value which is automatically converted to the attachment’s format. -
stencilis the clear value for the stencil aspect of the depth/stencil attachment. It is a 32-bit integer value which is converted to the attachment’s format by taking the appropriate number of LSBs.
The VkClearValue union is defined as:
// Provided by VK_VERSION_1_0
typedef union VkClearValue {
VkClearColorValue color;
VkClearDepthStencilValue depthStencil;
} VkClearValue;
-
colorspecifies the color image clear values to use when clearing a color image or attachment. -
depthStencilspecifies the depth and stencil clear values to use when clearing a depth/stencil image or attachment.
This union is used where part of the API requires either color or depth/stencil clear values, depending on the attachment, and defines the initial clear values in the VkRenderPassBeginInfo structure.
19.4. Filling Buffers
To clear buffer data, call:
// Provided by VK_VERSION_1_0
void vkCmdFillBuffer(
VkCommandBuffer commandBuffer,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
VkDeviceSize size,
uint32_t data);
-
commandBufferis the command buffer into which the command will be recorded. -
dstBufferis the buffer to be filled. -
dstOffsetis the byte offset into the buffer at which to start filling, and must be a multiple of 4. -
sizeis the number of bytes to fill, and must be either a multiple of 4, orVK_WHOLE_SIZEto fill the range fromoffsetto the end of the buffer. IfVK_WHOLE_SIZEis used and the remaining size of the buffer is not a multiple of 4, then the nearest smaller multiple is used. -
datais the 4-byte word written repeatedly to the buffer to fillsizebytes of data. The data word is written to memory according to the host endianness.
vkCmdFillBuffer is treated as a “transfer” operation for the
purposes of synchronization barriers.
The VK_BUFFER_USAGE_TRANSFER_DST_BIT must be specified in usage
of VkBufferCreateInfo in order for the buffer to be compatible with
vkCmdFillBuffer.
19.5. Updating Buffers
To update buffer data inline in a command buffer, call:
// Provided by VK_VERSION_1_0
void vkCmdUpdateBuffer(
VkCommandBuffer commandBuffer,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
VkDeviceSize dataSize,
const void* pData);
-
commandBufferis the command buffer into which the command will be recorded. -
dstBufferis a handle to the buffer to be updated. -
dstOffsetis the byte offset into the buffer to start updating, and must be a multiple of 4. -
dataSizeis the number of bytes to update, and must be a multiple of 4. -
pDatais a pointer to the source data for the buffer update, and must be at leastdataSizebytes in size.
dataSize must be less than or equal to 65536 bytes.
For larger updates, applications can use buffer to buffer
copies.
|
Note
Buffer updates performed with The additional cost of this functionality compared to buffer to buffer copies means it is only recommended for very small amounts of data, and is why it is limited to only 65536 bytes. Applications can work around this by issuing multiple
|
The source data is copied from the user pointer to the command buffer when the command is called.
vkCmdUpdateBuffer is only allowed outside of a render pass.
This command is treated as a “transfer” operation for the purposes of
synchronization barriers.
The VK_BUFFER_USAGE_TRANSFER_DST_BIT must be specified in usage
of VkBufferCreateInfo in order for the buffer to be compatible with
vkCmdUpdateBuffer.
|
Note
The |
20. Copy Commands
An application can copy buffer and image data using several methods
depending on the type of data transfer.
Data can be copied between buffer objects with
vkCmdCopyBuffer2 and
vkCmdCopyBuffer and a portion of an image can be copied to another
image with
vkCmdCopyImage2 and
vkCmdCopyImage.
Image data can also be copied to and from buffer memory using
vkCmdCopyImageToBuffer2, vkCmdCopyImageToBuffer,
vkCmdCopyBufferToImage2, and vkCmdCopyBufferToImage.
Image data can be blitted (with or without scaling and filtering) with
vkCmdBlitImage2 and
vkCmdBlitImage.
Multisampled images can be resolved to a non-multisampled image with
vkCmdResolveImage2 and
vkCmdResolveImage.
All copy commands are treated as “transfer” operations for the purposes of synchronization barriers.
All copy commands that have a source format with an X component in its format description read undefined values from those bits.
All copy commands that have a destination format with an X component in its format description write undefined values to those bits.
20.1. Copying Data Between Buffers
To copy data between buffer objects, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyBuffer(
VkCommandBuffer commandBuffer,
VkBuffer srcBuffer,
VkBuffer dstBuffer,
uint32_t regionCount,
const VkBufferCopy* pRegions);
-
commandBufferis the command buffer into which the command will be recorded. -
srcBufferis the source buffer. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferCopy structures specifying the regions to copy.
Each region in pRegions is copied from the source buffer to the same
region of the destination buffer.
srcBuffer and dstBuffer can be the same buffer or alias the
same memory, but the resulting values are undefined if the copy regions
overlap in memory.
The VkBufferCopy structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBufferCopy {
VkDeviceSize srcOffset;
VkDeviceSize dstOffset;
VkDeviceSize size;
} VkBufferCopy;
-
srcOffsetis the starting offset in bytes from the start ofsrcBuffer. -
dstOffsetis the starting offset in bytes from the start ofdstBuffer. -
sizeis the number of bytes to copy.
A more extensible version of the copy buffer command is defined below.
To copy data between buffer objects, call:
// Provided by VK_VERSION_1_3
void vkCmdCopyBuffer2(
VkCommandBuffer commandBuffer,
const VkCopyBufferInfo2* pCopyBufferInfo);
or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdCopyBuffer2KHR(
VkCommandBuffer commandBuffer,
const VkCopyBufferInfo2* pCopyBufferInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pCopyBufferInfois a pointer to a VkCopyBufferInfo2 structure describing the copy parameters.
This command is functionally identical to vkCmdCopyBuffer, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkCopyBufferInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCopyBufferInfo2 {
VkStructureType sType;
const void* pNext;
VkBuffer srcBuffer;
VkBuffer dstBuffer;
uint32_t regionCount;
const VkBufferCopy2* pRegions;
} VkCopyBufferInfo2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkCopyBufferInfo2 VkCopyBufferInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcBufferis the source buffer. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferCopy2 structures specifying the regions to copy.
Members defined by this structure with the same name as parameters in
vkCmdCopyBuffer have the identical effect to those parameters; the
child structure VkBufferCopy2 is a variant of VkBufferCopy which
includes sType and pNext parameters, allowing it to be extended.
The VkBufferCopy2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkBufferCopy2 {
VkStructureType sType;
const void* pNext;
VkDeviceSize srcOffset;
VkDeviceSize dstOffset;
VkDeviceSize size;
} VkBufferCopy2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkBufferCopy2 VkBufferCopy2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcOffsetis the starting offset in bytes from the start ofsrcBuffer. -
dstOffsetis the starting offset in bytes from the start ofdstBuffer. -
sizeis the number of bytes to copy.
20.2. Copying Data Between Images
vkCmdCopyImage performs image copies in a similar manner to a host
memcpy.
It does not perform general-purpose conversions such as scaling, resizing,
blending, color-space conversion, or format conversions.
Rather, it simply copies raw image data.
vkCmdCopyImage can copy between images with different formats,
provided the formats are compatible as defined below.
To copy data between image objects, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageCopy* pRegions);
-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the current layout of the source image subresource. -
dstImageis the destination image. -
dstImageLayoutis the current layout of the destination image subresource. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkImageCopy structures specifying the regions to copy.
Each region in pRegions is copied from the source image to the same
region of the destination image.
srcImage and dstImage can be the same image or alias the same
memory.
The formats of srcImage and dstImage must be compatible.
Formats are compatible if they share the same class, as shown in the
Compatible Formats table.
Depth/stencil formats must match exactly.
If either srcImage or dstImage has a
multi-planar format,
regions of each plane to be copied must be specified separately using the
srcSubresource and dstSubresource members of the
VkImageCopy structure.
In this case, the aspectMask of the srcSubresource or
dstSubresource that refers to the multi-planar image must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of vkCmdCopyImage, each plane of a multi-planar image
is treated as having the format listed in Compatible formats of planes of multi-planar formats for
the plane identified by the aspectMask of the corresponding
subresource.
This applies both to VkFormat and to coordinates used in the copy,
which correspond to texels in the plane rather than how these texels map
to coordinates in the image as a whole.
|
Note
For example, the |
vkCmdCopyImage allows copying between size-compatible compressed and
uncompressed internal formats.
Formats are size-compatible if the texel block size of the uncompressed
format is equal to the texel block size of the compressed format.
Such a copy does not perform on-the-fly compression or decompression.
When copying from an uncompressed format to a compressed format, each texel
of uncompressed data of the source image is copied as a raw value to the
corresponding compressed texel block of the destination image.
When copying from a compressed format to an uncompressed format, each
compressed texel block of the source image is copied as a raw value to the
corresponding texel of uncompressed data in the destination image.
Thus, for example, it is legal to copy between a 128-bit uncompressed format
and a compressed format which has a 128-bit sized compressed texel block
representing 4×4 texels (using 8 bits per texel), or between a 64-bit
uncompressed format and a compressed format which has a 64-bit sized
compressed texel block representing 4×4 texels (using 4 bits per
texel).
When copying between compressed and uncompressed formats the extent
members represent the texel dimensions of the source image and not the
destination.
When copying from a compressed image to an uncompressed image the image
texel dimensions written to the uncompressed image will be source extent
divided by the compressed texel block dimensions.
When copying from an uncompressed image to a compressed image the image
texel dimensions written to the compressed image will be the source extent
multiplied by the compressed texel block dimensions.
In both cases the number of bytes read and the number of bytes written will
be identical.
Copying to or from block-compressed images is typically done in multiples of
the compressed texel block size.
For this reason the extent must be a multiple of the compressed texel
block dimension.
There is one exception to this rule which is required to handle compressed
images created with dimensions that are not a multiple of the compressed
texel block dimensions: if the srcImage is compressed, then:
-
If
extent.widthis not a multiple of the compressed texel block width, then (extent.width+srcOffset.x) must equal the image subresource width. -
If
extent.heightis not a multiple of the compressed texel block height, then (extent.height+srcOffset.y) must equal the image subresource height. -
If
extent.depthis not a multiple of the compressed texel block depth, then (extent.depth+srcOffset.z) must equal the image subresource depth.
Similarly, if the dstImage is compressed, then:
-
If
extent.widthis not a multiple of the compressed texel block width, then (extent.width+dstOffset.x) must equal the image subresource width. -
If
extent.heightis not a multiple of the compressed texel block height, then (extent.height+dstOffset.y) must equal the image subresource height. -
If
extent.depthis not a multiple of the compressed texel block depth, then (extent.depth+dstOffset.z) must equal the image subresource depth.
This allows the last compressed texel block of the image in each non-multiple dimension to be included as a source or destination of the copy.
“_422” image formats that are not
multi-planar are treated as
having a 2×1 compressed texel block for the purposes of these rules.
vkCmdCopyImage can be used to copy image data between multisample
images, but both images must have the same number of samples.
The VkImageCopy structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageCopy {
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffset;
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffset;
VkExtent3D extent;
} VkImageCopy;
-
srcSubresourceanddstSubresourceare VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. -
srcOffsetanddstOffsetselect the initialx,y, andzoffsets in texels of the sub-regions of the source and destination image data. -
extentis the size in texels of the image to copy inwidth,heightanddepth.
For VK_IMAGE_TYPE_3D images, copies are performed slice by slice
starting with the z member of the srcOffset or dstOffset,
and copying depth slices.
For images with multiple layers, copies are performed layer by layer
starting with the baseArrayLayer member of the srcSubresource or
dstSubresource and copying layerCount layers.
Image data can be copied between images with different image types.
If one image is VK_IMAGE_TYPE_3D and the other image is
VK_IMAGE_TYPE_2D with multiple layers, then each slice is copied to or
from a different layer; depth slices in the 3D image correspond to
layerCount layers in the 2D image, with an effective depth of
1 used for the 2D image.
Copies involving a multi-planar image format specify the region to be copied in terms of the
plane to be copied, not the coordinates of the multi-planar image.
This means that copies accessing the R/B planes of “_422” format
images must fit the copied region within half the width of the parent
image, and that copies accessing the R/B planes of “_420” format
images must fit the copied region within half the width and
height of the parent image.
The VkImageSubresourceLayers structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageSubresourceLayers {
VkImageAspectFlags aspectMask;
uint32_t mipLevel;
uint32_t baseArrayLayer;
uint32_t layerCount;
} VkImageSubresourceLayers;
-
aspectMaskis a combination of VkImageAspectFlagBits, selecting the color, depth and/or stencil aspects to be copied. -
mipLevelis the mipmap level to copy -
baseArrayLayerandlayerCountare the starting layer and number of layers to copy.
A more extensible version of the copy image command is defined below.
To copy data between image objects, call:
// Provided by VK_VERSION_1_3
void vkCmdCopyImage2(
VkCommandBuffer commandBuffer,
const VkCopyImageInfo2* pCopyImageInfo);
or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdCopyImage2KHR(
VkCommandBuffer commandBuffer,
const VkCopyImageInfo2* pCopyImageInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pCopyImageInfois a pointer to a VkCopyImageInfo2 structure describing the copy parameters.
This command is functionally identical to vkCmdCopyImage, but includes
extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkCopyImageInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCopyImageInfo2 {
VkStructureType sType;
const void* pNext;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkImageCopy2* pRegions;
} VkCopyImageInfo2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkCopyImageInfo2 VkCopyImageInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcImageis the source image. -
srcImageLayoutis the current layout of the source image subresource. -
dstImageis the destination image. -
dstImageLayoutis the current layout of the destination image subresource. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkImageCopy2 structures specifying the regions to copy.
The VkImageCopy2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkImageCopy2 {
VkStructureType sType;
const void* pNext;
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffset;
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffset;
VkExtent3D extent;
} VkImageCopy2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkImageCopy2 VkImageCopy2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSubresourceanddstSubresourceare VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. -
srcOffsetanddstOffsetselect the initialx,y, andzoffsets in texels of the sub-regions of the source and destination image data. -
extentis the size in texels of the image to copy inwidth,heightanddepth.
20.3. Copying Data Between Buffers and Images
To copy data from a buffer object to an image object, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyBufferToImage(
VkCommandBuffer commandBuffer,
VkBuffer srcBuffer,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkBufferImageCopy* pRegions);
-
commandBufferis the command buffer into which the command will be recorded. -
srcBufferis the source buffer. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the copy. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.
Each region in pRegions is copied from the specified region of the
source buffer to the specified region of the destination image.
If dstImage has a
multi-planar format, regions
of each plane to be a target of a copy must be specified separately using
the pRegions member of the VkBufferImageCopy structure.
In this case, the aspectMask of imageSubresource must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
Compatible formats of planes of multi-planar formats for the plane identified by the
aspectMask of the corresponding subresource.
This applies both to VkFormat and to coordinates used in the copy,
which correspond to texels in the plane rather than how these texels map
to coordinates in the image as a whole.
To copy data from an image object to a buffer object, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyImageToBuffer(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkBuffer dstBuffer,
uint32_t regionCount,
const VkBufferImageCopy* pRegions);
-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the copy. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.
Each region in pRegions is copied from the specified region of the
source image to the specified region of the destination buffer.
If srcImage has a multi-planar format, regions of each plane to be a source of a copy must
be specified separately using the pRegions member of the
VkBufferImageCopy structure.
In this case, the aspectMask of imageSubresource must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
Compatible formats of planes of multi-planar formats for the plane identified by the
aspectMask of the corresponding subresource.
This applies both to VkFormat and to coordinates used in the copy,
which correspond to texels in the plane rather than how these texels map
to coordinates in the image as a whole.
For both vkCmdCopyBufferToImage and vkCmdCopyImageToBuffer, each
element of pRegions is a structure defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBufferImageCopy {
VkDeviceSize bufferOffset;
uint32_t bufferRowLength;
uint32_t bufferImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkBufferImageCopy;
-
bufferOffsetis the offset in bytes from the start of the buffer object where the image data is copied from or to. -
bufferRowLengthandbufferImageHeightspecify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to theimageExtent. -
imageSubresourceis a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. -
imageOffsetselects the initialx,y,zoffsets in texels of the sub-region of the source or destination image data. -
imageExtentis the size in texels of the image to copy inwidth,heightanddepth.
When copying to or from a depth or stencil aspect, the data in buffer memory uses a layout that is a (mostly) tightly packed representation of the depth or stencil data. Specifically:
-
data copied to or from the stencil aspect of any depth/stencil format is tightly packed with one
VK_FORMAT_S8_UINTvalue per texel. -
data copied to or from the depth aspect of a
VK_FORMAT_D16_UNORMorVK_FORMAT_D16_UNORM_S8_UINTformat is tightly packed with oneVK_FORMAT_D16_UNORMvalue per texel. -
data copied to or from the depth aspect of a
VK_FORMAT_D32_SFLOATorVK_FORMAT_D32_SFLOAT_S8_UINTformat is tightly packed with oneVK_FORMAT_D32_SFLOATvalue per texel. -
data copied to or from the depth aspect of a
VK_FORMAT_X8_D24_UNORM_PACK32orVK_FORMAT_D24_UNORM_S8_UINTformat is packed with one 32-bit word per texel with the D24 value in the LSBs of the word, and undefined values in the eight MSBs.
|
Note
To copy both the depth and stencil aspects of a depth/stencil format, two
entries in |
Because depth or stencil aspect buffer to image copies may require format conversions on some implementations, they are not supported on queues that do not support graphics.
When copying to a depth aspect,
and the VK_EXT_depth_range_unrestricted extension is not enabled,
the data in buffer memory must be in the range [0,1], or the
resulting values are undefined.
Copies are done layer by layer starting with image layer
baseArrayLayer member of imageSubresource.
layerCount layers are copied from the source image or to the
destination image.
For purpose of valid usage statements here and in related copy commands, a blocked image is defined as:
-
an image with a single-plane, “
_422” format, which is treated as a format with a 2 × 1 compressed texel block, or -
a compressed image.
More extensible versions of the commands to copy between buffers and images are defined below.
To copy data from a buffer object to an image object, call:
// Provided by VK_VERSION_1_3
void vkCmdCopyBufferToImage2(
VkCommandBuffer commandBuffer,
const VkCopyBufferToImageInfo2* pCopyBufferToImageInfo);
or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdCopyBufferToImage2KHR(
VkCommandBuffer commandBuffer,
const VkCopyBufferToImageInfo2* pCopyBufferToImageInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pCopyBufferToImageInfois a pointer to a VkCopyBufferToImageInfo2 structure describing the copy parameters.
This command is functionally identical to vkCmdCopyBufferToImage, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkCopyBufferToImageInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCopyBufferToImageInfo2 {
VkStructureType sType;
const void* pNext;
VkBuffer srcBuffer;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkBufferImageCopy2* pRegions;
} VkCopyBufferToImageInfo2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkCopyBufferToImageInfo2 VkCopyBufferToImageInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcBufferis the source buffer. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the copy. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy2 structures specifying the regions to copy.
To copy data from an image object to a buffer object, call:
// Provided by VK_VERSION_1_3
void vkCmdCopyImageToBuffer2(
VkCommandBuffer commandBuffer,
const VkCopyImageToBufferInfo2* pCopyImageToBufferInfo);
or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdCopyImageToBuffer2KHR(
VkCommandBuffer commandBuffer,
const VkCopyImageToBufferInfo2* pCopyImageToBufferInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pCopyImageToBufferInfois a pointer to a VkCopyImageToBufferInfo2 structure describing the copy parameters.
This command is functionally identical to vkCmdCopyImageToBuffer, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkCopyImageToBufferInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCopyImageToBufferInfo2 {
VkStructureType sType;
const void* pNext;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkBuffer dstBuffer;
uint32_t regionCount;
const VkBufferImageCopy2* pRegions;
} VkCopyImageToBufferInfo2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkCopyImageToBufferInfo2 VkCopyImageToBufferInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the copy. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkBufferImageCopy2 structures specifying the regions to copy.
For both vkCmdCopyBufferToImage2 and vkCmdCopyImageToBuffer2,
each element of pRegions is a structure defined as:
// Provided by VK_VERSION_1_3
typedef struct VkBufferImageCopy2 {
VkStructureType sType;
const void* pNext;
VkDeviceSize bufferOffset;
uint32_t bufferRowLength;
uint32_t bufferImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkBufferImageCopy2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkBufferImageCopy2 VkBufferImageCopy2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferOffsetis the offset in bytes from the start of the buffer object where the image data is copied from or to. -
bufferRowLengthandbufferImageHeightspecify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to theimageExtent. -
imageSubresourceis a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. -
imageOffsetselects the initialx,y,zoffsets in texels of the sub-region of the source or destination image data. -
imageExtentis the size in texels of the image to copy inwidth,heightanddepth.
This structure is functionally identical to VkBufferImageCopy, but
adds sType and pNext parameters, allowing it to be more easily
extended.
For both vkCmdCopyBufferToImage2 and vkCmdCopyImageToBuffer2,
each region copied can include a rotation.
To specify a region with rotation, add the
VkCopyCommandTransformInfoQCOM to the pNext chain of
VkBufferImageCopy2.
When a rotation is specified, Buffer and Image Addressing with Rotation specifies how coordinates of
texels in the source region are rotated by transform to produce texel
coordinates in the destination region.
When rotation is specified, the source and destination images must each be
2D images.
They must not be blocked images or have a
multi-planar format.
The VkRenderPassTransformBeginInfoQCOM structure is defined as:
// Provided by VK_QCOM_rotated_copy_commands
typedef struct VkCopyCommandTransformInfoQCOM {
VkStructureType sType;
const void* pNext;
VkSurfaceTransformFlagBitsKHR transform;
} VkCopyCommandTransformInfoQCOM;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
transformis a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied.
20.3.1. Buffer and Image Addressing
Pseudocode for image/buffer addressing of uncompressed formats is:
rowLength = region->bufferRowLength;
if (rowLength == 0)
rowLength = region->imageExtent.width;
imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
imageHeight = region->imageExtent.height;
texelBlockSize = <texel block size of the format of the src/dstImage>;
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelBlockSize;
where x,y,z range from (0,0,0) to region->imageExtent.{width,height,depth}.
Note that imageOffset does not affect addressing calculations for
buffer memory.
Instead, bufferOffset can be used to select the starting address in
buffer memory.
For block-compressed formats, all parameters are still specified in texels rather than compressed texel blocks, but the addressing math operates on whole compressed texel blocks. Pseudocode for compressed copy addressing is:
rowLength = region->bufferRowLength;
if (rowLength == 0)
rowLength = region->imageExtent.width;
imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
imageHeight = region->imageExtent.height;
compressedTexelBlockSizeInBytes = <compressed texel block size taken from the src/dstImage>;
rowLength = (rowLength + compressedTexelBlockWidth - 1) / compressedTexelBlockWidth;
imageHeight = (imageHeight + compressedTexelBlockHeight - 1) / compressedTexelBlockHeight;
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * compressedTexelBlockSizeInBytes;
where x,y,z range from (0,0,0) to region->imageExtent.{width/compressedTexelBlockWidth,height/compressedTexelBlockHeight,depth/compressedTexelBlockDepth}.
Copying to or from block-compressed images is typically done in multiples of
the compressed texel block size.
For this reason the imageExtent must be a multiple of the compressed
texel block dimension.
There is one exception to this rule which is required to handle compressed
images created with dimensions that are not a multiple of the compressed
texel block dimensions:
-
If
imageExtent.widthis not a multiple of the compressed texel block width, then (imageExtent.width+imageOffset.x) must equal the image subresource width. -
If
imageExtent.heightis not a multiple of the compressed texel block height, then (imageExtent.height+imageOffset.y) must equal the image subresource height. -
If
imageExtent.depthis not a multiple of the compressed texel block depth, then (imageExtent.depth+imageOffset.z) must equal the image subresource depth.
This allows the last compressed texel block of the image in each non-multiple dimension to be included as a source or destination of the copy.
20.3.2. Buffer and Image Addressing with Rotation
When VkCopyCommandTransformInfoQCOM is in the pNext chain of
VkBufferImageCopy2, a rotated copy is specified.
For both vkCmdCopyImageToBuffer2 and vkCmdCopyBufferToImage2, a
rotation is applied to the region used for image accesses, but a non-rotated
region is used for buffer accesses.
In the case of rotated vkCmdCopyImageToBuffer2, the source image
region is rotated.
In the case of rotated vkCmdCopyBufferToImage2, the destination image
region is rotated.
For a rotated copy, the following description of rotated addressing replaces the description in Buffer and Image Addressing.
The following code computes rotation of unnormalized coordinates.
// Forward rotation of unnormalized coordinates
VkOffset2D RotateUV(VkOffset2D in, VkSurfaceTransformFlagBitsKHR flags)
{
VkOffset2D output;
switch (flags)
{
case VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR:
out.x = in.x;
out.y = in.y;
break;
case VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR:
out.x = -in.y;
out.y = in.x;
break;
case VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR:
out.x = -in.x;
out.y = -in.y;
break;
case VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR:
out.x = in.y;
out.y = -in.x;
break;
}
return out;
}
Pseudocode for image/buffer addressing of uncompressed formats with rotation is:
rowLength = region->bufferRowLength;
if (rowLength == 0)
rowLength = region->imageExtent.width;
imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
imageHeight = region->imageExtent.height;
texelBlockSize = <texel block size of the format of the src/dstImage>;
// Buffer addressing is unaffected by rotation:
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelBlockSize;
// When copying from buffer to image, the source buffer coordinates x,y,z range from (0,0,0) to
// region->imageExtent.{width,height,depth}. The source extent is rotated by the specified
// VK_SURFACE_TRANSFORM, centered on the imageOffset, to define a rotated destination region.
// For each source buffer texel with coordinates (x,y) the rotated destination image texel has
// coordinates (x',y') defined as:
(x',y')= RotateUV(x,y) + ImageOffset.{x,y}
// When copying from image to buffer, the the destination buffer coordinates x,y,z range from (0,0,0) to
// region->imageExtent.{width,height,depth}. The destination extent is rotated by the specified
// VK_SURFACE_TRANSFORM, centered on the imageOffset, to define a rotated source region. For each destination
// buffer texel with coordinates (x,y) the rotated source image texel has coordinates (x',y') defined as:
(x',y')= RotateUV(x,y) + ImageOffset.{x,y}
Note that imageOffset does not affect addressing calculations for
buffer memory.
Instead, bufferOffset can be used to select the starting address in
buffer memory.
20.4. Image Copies with Scaling
To copy regions of a source image into a destination image, potentially performing format conversion, arbitrary scaling, and filtering, call:
// Provided by VK_VERSION_1_0
void vkCmdBlitImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageBlit* pRegions,
VkFilter filter);
-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the blit. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the blit. -
regionCountis the number of regions to blit. -
pRegionsis a pointer to an array of VkImageBlit structures specifying the regions to blit. -
filteris a VkFilter specifying the filter to apply if the blits require scaling.
vkCmdBlitImage must not be used for multisampled source or
destination images.
Use vkCmdResolveImage for this purpose.
As the sizes of the source and destination extents can differ in any dimension, texels in the source extent are scaled and filtered to the destination extent. Scaling occurs via the following operations:
-
For each destination texel, the integer coordinate of that texel is converted to an unnormalized texture coordinate, using the effective inverse of the equations described in unnormalized to integer conversion:
-
ubase = i + ½
-
vbase = j + ½
-
wbase = k + ½
-
-
These base coordinates are then offset by the first destination offset:
-
uoffset = ubase - xdst0
-
voffset = vbase - ydst0
-
woffset = wbase - zdst0
-
aoffset = a -
baseArrayCountdst
-
-
The scale is determined from the source and destination regions, and applied to the offset coordinates:
-
scaleu = (xsrc1 - xsrc0) / (xdst1 - xdst0)
-
scalev = (ysrc1 - ysrc0) / (ydst1 - ydst0)
-
scalew = (zsrc1 - zsrc0) / (zdst1 - zdst0)
-
uscaled = uoffset × scaleu
-
vscaled = voffset × scalev
-
wscaled = woffset × scalew
-
-
Finally the source offset is added to the scaled coordinates, to determine the final unnormalized coordinates used to sample from
srcImage:-
u = uscaled + xsrc0
-
v = vscaled + ysrc0
-
w = wscaled + zsrc0
-
q =
mipLevel -
a = aoffset +
baseArrayCountsrc
-
These coordinates are used to sample from the source image, as described in
Image Operations chapter, with the filter mode equal to that
of filter, a mipmap mode of VK_SAMPLER_MIPMAP_MODE_NEAREST and
an address mode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
Implementations must clamp at the edge of the source image, and may
additionally clamp to the edge of the source region.
|
Note
Due to allowable rounding errors in the generation of the source texture coordinates, it is not always possible to guarantee exactly which source texels will be sampled for a given blit. As rounding errors are implementation-dependent, the exact results of a blitting operation are also implementation-dependent. |
Blits are done layer by layer starting with the baseArrayLayer member
of srcSubresource for the source and dstSubresource for the
destination.
layerCount layers are blitted to the destination image.
When blitting 3D textures, slices in the destination region bounded by
dstOffsets[0].z and dstOffsets[1].z are sampled from slices in
the source region bounded by srcOffsets[0].z and
srcOffsets[1].z.
If the filter parameter is VK_FILTER_LINEAR then the value
sampled from the source image is taken by doing linear filtering using the
interpolated z coordinate represented by w in the previous equations.
If the filter parameter is VK_FILTER_NEAREST then the value
sampled from the source image is taken from the single nearest slice, with
an implementation-dependent arithmetic rounding mode.
The following filtering and conversion rules apply:
-
Integer formats can only be converted to other integer formats with the same signedness.
-
No format conversion is supported between depth/stencil images. The formats must match.
-
Format conversions on unorm, snorm, scaled and packed float formats of the copied aspect of the image are performed by first converting the pixels to float values.
-
For sRGB source formats, nonlinear RGB values are converted to linear representation prior to filtering.
-
After filtering, the float values are first clamped and then cast to the destination image format. In case of sRGB destination format, linear RGB values are converted to nonlinear representation before writing the pixel to the image.
Signed and unsigned integers are converted by first clamping to the representable range of the destination format, then casting the value.
The VkImageBlit structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageBlit {
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffsets[2];
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffsets[2];
} VkImageBlit;
-
srcSubresourceis the subresource to blit from. -
srcOffsetsis a pointer to an array of two VkOffset3D structures specifying the bounds of the source region withinsrcSubresource. -
dstSubresourceis the subresource to blit into. -
dstOffsetsis a pointer to an array of two VkOffset3D structures specifying the bounds of the destination region withindstSubresource.
For each element of the pRegions array, a blit operation is performed
for the specified source and destination regions.
A more extensible version of the blit image command is defined below.
To copy regions of a source image into a destination image, potentially performing format conversion, arbitrary scaling, and filtering, call:
// Provided by VK_VERSION_1_3
void vkCmdBlitImage2(
VkCommandBuffer commandBuffer,
const VkBlitImageInfo2* pBlitImageInfo);
or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdBlitImage2KHR(
VkCommandBuffer commandBuffer,
const VkBlitImageInfo2* pBlitImageInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pBlitImageInfois a pointer to a VkBlitImageInfo2 structure describing the blit parameters.
This command is functionally identical to vkCmdBlitImage, but includes
extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkBlitImageInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkBlitImageInfo2 {
VkStructureType sType;
const void* pNext;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkImageBlit2* pRegions;
VkFilter filter;
} VkBlitImageInfo2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkBlitImageInfo2 VkBlitImageInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the blit. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the blit. -
regionCountis the number of regions to blit. -
pRegionsis a pointer to an array of VkImageBlit2 structures specifying the regions to blit. -
filteris a VkFilter specifying the filter to apply if the blits require scaling.
The VkImageBlit2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkImageBlit2 {
VkStructureType sType;
const void* pNext;
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffsets[2];
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffsets[2];
} VkImageBlit2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkImageBlit2 VkImageBlit2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSubresourceis the subresource to blit from. -
srcOffsetsis a pointer to an array of two VkOffset3D structures specifying the bounds of the source region withinsrcSubresource. -
dstSubresourceis the subresource to blit into. -
dstOffsetsis a pointer to an array of two VkOffset3D structures specifying the bounds of the destination region withindstSubresource.
For each element of the pRegions array, a blit operation is performed
for the specified source and destination regions.
For vkCmdBlitImage2, each region copied can include a rotation.
To specify a rotated region, add VkCopyCommandTransformInfoQCOM to the
pNext chain of VkImageBlit2.
For each region with a rotation specified,
Image Blits with Scaling and Rotation
specifies how coordinates are rotated prior to sampling from the source
image.
When rotation is specified, the source and destination images must each be
2D images.
They must not be blocked images or have a
multi-planar format.
20.4.1. Image Blits with Scaling and Rotation
When VkCopyCommandTransformInfoQCOM is in the pNext chain of
VkImageBlit2, the specified region is rotated during the blit.
The following description of rotated addressing replaces the description in
vkCmdBlitImage.
The following code computes rotation of normalized coordinates.
// rotation of normalized coordinates
VkOffset2D RotateNormUV(VkOffset2D in, VkSurfaceTransformFlagBitsKHR flags)
{
VkOffset2D output;
switch (flags)
{
case VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR:
out.x = in.x;
out.y = in.y;
break;
case VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR:
out.x = in.y;
out.y = 1.0 - in.x;
break;
case VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR:
out.x = 1.0 - in.x;
out.y = 1.0 - in.y;
break;
case VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR:
out.x = 1.0 - in.y;
out.y = in.x;
break;
}
return out;
}
-
For each destination texel, the integer coordinate of that texel is converted to an unnormalized texture coordinate, using the effective inverse of the equations described in unnormalized to integer conversion:
-
ubase = i + ½
-
vbase = j + ½
-
wbase = k + ½
-
-
These base coordinates are then offset by the first destination offset:
-
uoffset = ubase - xdst0
-
voffset = vbase - ydst0
-
woffset = wbase - zdst0
-
aoffset = a -
baseArrayCountdst
-
-
The UV destination coordinates are scaled by the destination region, rotated, and scaled by the source region.
-
udest_scaled = uoffset / (xdst1 - xdst0)
-
vdest_scaled = voffset / (ydst1 - ydst0)
-
(usrc_scaled, vsrc_scaled) =
RotateNormUV(udest_scaled, vdest_scaled,transform) -
uscaled = usrc_scaled × (xSrc1 - xSrc0)
-
vscaled = vsrc_scaled × (ySrc1 - ySrc0)
-
-
The W coordinate is unaffected by rotation. The scale is determined from the ratio of source and destination regions, and applied to the offset coordinate:
-
scalew = (zSrc1 - zSrc0) / (zdst1 - zdst0)
-
wscaled = woffset × scalew
-
-
Finally the source offset is added to the scaled source coordinates, to determine the final unnormalized coordinates used to sample from
srcImage:-
u = uscaled + xSrc0
-
v = vscaled + ySrc0
-
w = wscaled + zSrc0
-
q =
mipLevel -
a = aoffset +
baseArrayCountsrc
-
These coordinates are used to sample from the source image as described for
Image Operations, with the filter mode equal to that of
filter; a mipmap mode of VK_SAMPLER_MIPMAP_MODE_NEAREST; and an
address mode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
Implementations must clamp at the edge of the source image, and may
additionally clamp to the edge of the source region.
20.5. Resolving Multisample Images
To resolve a multisample color image to a non-multisample color image, call:
// Provided by VK_VERSION_1_0
void vkCmdResolveImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageResolve* pRegions);
-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the resolve. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the resolve. -
regionCountis the number of regions to resolve. -
pRegionsis a pointer to an array of VkImageResolve structures specifying the regions to resolve.
During the resolve the samples corresponding to each pixel location in the source are converted to a single sample before being written to the destination. If the source formats are floating-point or normalized types, the sample values for each pixel are resolved in an implementation-dependent manner. If the source formats are integer types, a single sample’s value is selected for each pixel.
srcOffset and dstOffset select the initial x, y, and
z offsets in texels of the sub-regions of the source and destination
image data.
extent is the size in texels of the source image to resolve in
width, height and depth.
Each element of pRegions must be a region that is contained within
its corresponding image.
Resolves are done layer by layer starting with baseArrayLayer member
of srcSubresource for the source and dstSubresource for the
destination.
layerCount layers are resolved to the destination image.
The VkImageResolve structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageResolve {
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffset;
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffset;
VkExtent3D extent;
} VkImageResolve;
-
srcSubresourceanddstSubresourceare VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. Resolve of depth/stencil images is not supported. -
srcOffsetanddstOffsetselect the initialx,y, andzoffsets in texels of the sub-regions of the source and destination image data. -
extentis the size in texels of the source image to resolve inwidth,heightanddepth.
A more extensible version of the resolve image command is defined below.
To resolve a multisample image to a non-multisample image, call:
// Provided by VK_VERSION_1_3
void vkCmdResolveImage2(
VkCommandBuffer commandBuffer,
const VkResolveImageInfo2* pResolveImageInfo);
or the equivalent command
// Provided by VK_KHR_copy_commands2
void vkCmdResolveImage2KHR(
VkCommandBuffer commandBuffer,
const VkResolveImageInfo2* pResolveImageInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pResolveImageInfois a pointer to a VkResolveImageInfo2 structure describing the resolve parameters.
This command is functionally identical to vkCmdResolveImage, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
The VkResolveImageInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkResolveImageInfo2 {
VkStructureType sType;
const void* pNext;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkImageResolve2* pRegions;
} VkResolveImageInfo2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkResolveImageInfo2 VkResolveImageInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the resolve. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the resolve. -
regionCountis the number of regions to resolve. -
pRegionsis a pointer to an array of VkImageResolve2 structures specifying the regions to resolve.
The VkImageResolve2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkImageResolve2 {
VkStructureType sType;
const void* pNext;
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffset;
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffset;
VkExtent3D extent;
} VkImageResolve2;
or the equivalent
// Provided by VK_KHR_copy_commands2
typedef VkImageResolve2 VkImageResolve2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSubresourceanddstSubresourceare VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. Resolve of depth/stencil images is not supported. -
srcOffsetanddstOffsetselect the initialx,y, andzoffsets in texels of the sub-regions of the source and destination image data. -
extentis the size in texels of the source image to resolve inwidth,heightanddepth.
20.6. Buffer Markers
To write a 32-bit marker value into a buffer as a pipelined operation, call:
// Provided by VK_KHR_synchronization2 with VK_AMD_buffer_marker
void vkCmdWriteBufferMarker2AMD(
VkCommandBuffer commandBuffer,
VkPipelineStageFlags2 stage,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
uint32_t marker);
-
commandBufferis the command buffer into which the command will be recorded. -
stagespecifies the pipeline stage whose completion triggers the marker write. -
dstBufferis the buffer where the marker will be written. -
dstOffsetis the byte offset into the buffer where the marker will be written. -
markeris the 32-bit value of the marker.
The command will write the 32-bit marker value into the buffer only after
all preceding commands have finished executing up to at least the specified
pipeline stage.
This includes the completion of other preceding
vkCmdWriteBufferMarker2AMD commands so long as their specified
pipeline stages occur either at the same time or earlier than this command’s
specified stage.
While consecutive buffer marker writes with the same stage parameter
implicitly complete in submission order, memory and execution dependencies
between buffer marker writes and other operations must still be explicitly
ordered using synchronization commands.
The access scope for buffer marker writes falls under the
VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
the synchronization scope must include both stage and
VK_PIPELINE_STAGE_TRANSFER_BIT.
|
Note
Similar to |
|
Note
Implementations may only support a limited number of pipelined marker write operations in flight at a given time. Thus an excessive number of marker write operations may degrade command execution performance. |
To write a 32-bit marker value into a buffer as a pipelined operation, call:
// Provided by VK_AMD_buffer_marker
void vkCmdWriteBufferMarkerAMD(
VkCommandBuffer commandBuffer,
VkPipelineStageFlagBits pipelineStage,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
uint32_t marker);
-
commandBufferis the command buffer into which the command will be recorded. -
pipelineStageis a VkPipelineStageFlagBits value specifying the pipeline stage whose completion triggers the marker write. -
dstBufferis the buffer where the marker will be written to. -
dstOffsetis the byte offset into the buffer where the marker will be written to. -
markeris the 32-bit value of the marker.
The command will write the 32-bit marker value into the buffer only after
all preceding commands have finished executing up to at least the specified
pipeline stage.
This includes the completion of other preceding
vkCmdWriteBufferMarkerAMD commands so long as their specified pipeline
stages occur either at the same time or earlier than this command’s
specified pipelineStage.
While consecutive buffer marker writes with the same pipelineStage
parameter are implicitly complete in submission order, memory and execution
dependencies between buffer marker writes and other operations must still be
explicitly ordered using synchronization commands.
The access scope for buffer marker writes falls under the
VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
the synchronization scope must include both pipelineStage and
VK_PIPELINE_STAGE_TRANSFER_BIT.
|
Note
Similar to |
|
Note
Implementations may only support a limited number of pipelined marker write operations in flight at a given time, thus excessive number of marker write operations may degrade command execution performance. |
21. Drawing Commands
Drawing commands (commands with Draw in the name) provoke work in a
graphics pipeline.
Drawing commands are recorded into a command buffer and when executed by a
queue, will produce work which executes according to the bound graphics
pipeline.
A graphics pipeline must be bound to a command buffer before any drawing
commands are recorded in that command buffer.
Drawing can be achieved in two modes:
-
Programmable Mesh Shading, the mesh shader assembles primitives, or
-
Programmable Primitive Shading, the input primitives are assembled
as follows.
Each draw is made up of zero or more vertices and zero or more instances,
which are processed by the device and result in the assembly of primitives.
Primitives are assembled according to the pInputAssemblyState member
of the VkGraphicsPipelineCreateInfo structure, which is of type
VkPipelineInputAssemblyStateCreateInfo:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineInputAssemblyStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineInputAssemblyStateCreateFlags flags;
VkPrimitiveTopology topology;
VkBool32 primitiveRestartEnable;
} VkPipelineInputAssemblyStateCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
topologyis a VkPrimitiveTopology defining the primitive topology, as described below. -
primitiveRestartEnablecontrols whether a special vertex index value is treated as restarting the assembly of primitives. This enable only applies to indexed draws (vkCmdDrawIndexed, vkCmdDrawMultiIndexedEXT, and vkCmdDrawIndexedIndirect), and the special index value is either 0xFFFFFFFF when theindexTypeparameter ofvkCmdBindIndexBufferis equal toVK_INDEX_TYPE_UINT32, 0xFF whenindexTypeis equal toVK_INDEX_TYPE_UINT8_EXT, or 0xFFFF whenindexTypeis equal toVK_INDEX_TYPE_UINT16. Primitive restart is not allowed for “list” topologies, unless one of the featuresprimitiveTopologyPatchListRestart(forVK_PRIMITIVE_TOPOLOGY_PATCH_LIST) orprimitiveTopologyListRestart(for all other list topologies) is enabled.
Restarting the assembly of primitives discards the most recent index values
if those elements formed an incomplete primitive, and restarts the primitive
assembly using the subsequent indices, but only assembling the immediately
following element through the end of the originally specified elements.
The primitive restart index value comparison is performed before adding the
vertexOffset value to the index value.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineInputAssemblyStateCreateFlags;
VkPipelineInputAssemblyStateCreateFlags is a bitmask type for setting
a mask, but is currently reserved for future use.
To dynamically control whether a special vertex index value is treated as restarting the assembly of primitives, call:
// Provided by VK_VERSION_1_3
void vkCmdSetPrimitiveRestartEnable(
VkCommandBuffer commandBuffer,
VkBool32 primitiveRestartEnable);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state2
void vkCmdSetPrimitiveRestartEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 primitiveRestartEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
primitiveRestartEnablecontrols whether a special vertex index value is treated as restarting the assembly of primitives. It behaves in the same way asVkPipelineInputAssemblyStateCreateInfo::primitiveRestartEnable
This command sets the primitive restart enable for subsequent drawing
commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineInputAssemblyStateCreateInfo::primitiveRestartEnable
value used to create the currently active pipeline.
21.1. Primitive Topologies
Primitive topology determines how consecutive vertices are organized into primitives, and determines the type of primitive that is used at the beginning of the graphics pipeline. The effective topology for later stages of the pipeline is altered by tessellation or geometry shading (if either is in use) and depends on the execution modes of those shaders. In the case of mesh shading the only effective topology is defined by the execution mode of the mesh shader.
The primitive topologies defined by VkPrimitiveTopology are:
// Provided by VK_VERSION_1_0
typedef enum VkPrimitiveTopology {
VK_PRIMITIVE_TOPOLOGY_POINT_LIST = 0,
VK_PRIMITIVE_TOPOLOGY_LINE_LIST = 1,
VK_PRIMITIVE_TOPOLOGY_LINE_STRIP = 2,
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST = 3,
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP = 4,
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN = 5,
VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY = 6,
VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY = 7,
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY = 8,
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY = 9,
VK_PRIMITIVE_TOPOLOGY_PATCH_LIST = 10,
} VkPrimitiveTopology;
-
VK_PRIMITIVE_TOPOLOGY_POINT_LISTspecifies a series of separate point primitives. -
VK_PRIMITIVE_TOPOLOGY_LINE_LISTspecifies a series of separate line primitives. -
VK_PRIMITIVE_TOPOLOGY_LINE_STRIPspecifies a series of connected line primitives with consecutive lines sharing a vertex. -
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LISTspecifies a series of separate triangle primitives. -
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIPspecifies a series of connected triangle primitives with consecutive triangles sharing an edge. -
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FANspecifies a series of connected triangle primitives with all triangles sharing a common vertex. If theVK_KHR_portability_subsetextension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::triangleFansisVK_FALSE, then triangle fans are not supported by the implementation, andVK_PRIMITIVE_TOPOLOGY_TRIANGLE_FANmust not be used. -
VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCYspecifies a series of separate line primitives with adjacency. -
VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCYspecifies a series of connected line primitives with adjacency, with consecutive primitives sharing three vertices. -
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCYspecifies a series of separate triangle primitives with adjacency. -
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCYspecifies connected triangle primitives with adjacency, with consecutive triangles sharing an edge. -
VK_PRIMITIVE_TOPOLOGY_PATCH_LISTspecifies separate patch primitives.
Each primitive topology, and its construction from a list of vertices, is described in detail below with a supporting diagram, according to the following key:
Vertex |
A point in 3-dimensional space. Positions chosen within the diagrams are arbitrary and for illustration only. |
|
Vertex Number |
Sequence position of a vertex within the provided vertex data. |
|
Provoking Vertex |
Provoking vertex within the main primitive. The tail is angled towards the relevant primitive. Used in flat shading. |
|
Primitive Edge |
An edge connecting the points of a main primitive. |
|
Adjacency Edge |
Points connected by these lines do not contribute to a main primitive, and are only accessible in a geometry shader. |
|
Winding Order |
The relative order in which vertices are defined within a primitive, used in the facing determination. This ordering has no specific start or end point. |
The diagrams are supported with mathematical definitions where the vertices (v) and primitives (p) are numbered starting from 0; v0 is the first vertex in the provided data and p0 is the first primitive in the set of primitives defined by the vertices and topology.
To dynamically set primitive topology, call:
// Provided by VK_VERSION_1_3
void vkCmdSetPrimitiveTopology(
VkCommandBuffer commandBuffer,
VkPrimitiveTopology primitiveTopology);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetPrimitiveTopologyEXT(
VkCommandBuffer commandBuffer,
VkPrimitiveTopology primitiveTopology);
-
commandBufferis the command buffer into which the command will be recorded. -
primitiveTopologyspecifies the primitive topology to use for drawing.
This command sets the primitive topology for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineInputAssemblyStateCreateInfo::topology value used to
create the currently active pipeline.
21.1.1. Topology Class
The primitive topologies are grouped into the following topology classes:
| Topology Class | Primitive Topology |
|---|---|
Point |
|
Line |
|
Triangle |
|
Patch |
|
21.1.2. Point Lists
When the topology is VK_PRIMITIVE_TOPOLOGY_POINT_LIST, each
consecutive vertex defines a single point primitive, according to the
equation:
-
pi = {vi}
As there is only one vertex, that vertex is the provoking vertex.
The number of primitives generated is equal to vertexCount.
21.1.3. Line Lists
When the primitive topology is VK_PRIMITIVE_TOPOLOGY_LINE_LIST, each
consecutive pair of vertices defines a single line primitive, according to
the equation:
-
pi = {v2i, v2i+1}
The number of primitives generated is equal to
⌊vertexCount/2⌋.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the
provoking vertex for pi is v2i.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for
pi is v2i+1.
21.1.4. Line Strips
When the primitive topology is VK_PRIMITIVE_TOPOLOGY_LINE_STRIP, one
line primitive is defined by each vertex and the following vertex, according
to the equation:
-
pi = {vi, vi+1}
The number of primitives generated is equal to
max(0,vertexCount-1).
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the
provoking vertex for pi is vi.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for
pi is vi+1.
21.1.5. Triangle Lists
When the primitive topology is VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,
each consecutive set of three vertices defines a single triangle primitive,
according to the equation:
-
pi = {v3i, v3i+1, v3i+2}
The number of primitives generated is equal to
⌊vertexCount/3⌋.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the
provoking vertex for pi is v3i.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for
pi is v3i+2.
21.1.6. Triangle Strips
When the primitive topology is VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP,
one triangle primitive is defined by each vertex and the two vertices that
follow it, according to the equation:
-
pi = {vi, vi+(1+i%2), vi+(2-i%2)}
The number of primitives generated is equal to
max(0,vertexCount-2).
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the
provoking vertex for pi is vi.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for
pi is vi+2.
|
Note
The ordering of the vertices in each successive triangle is reversed, so that the winding order is consistent throughout the strip. |
21.1.7. Triangle Fans
When the primitive topology is VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN,
triangle primitives are defined around a shared common vertex, according to
the equation:
-
pi = {vi+1, vi+2, v0}
The number of primitives generated is equal to
max(0,vertexCount-2).
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the
provoking vertex for pi is vi+1.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for
pi is vi+2.
|
Note
If the |
21.1.8. Line Lists With Adjacency
When the primitive topology is
VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY, each consecutive set
of four vertices defines a single line primitive with adjacency, according
to the equation:
-
pi = {v4i, v4i+1, v4i+2,v4i+3}
A line primitive is described by the second and third vertices of the total primitive, with the remaining two vertices only accessible in a geometry shader.
The number of primitives generated is equal to
⌊vertexCount/4⌋.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the
provoking vertex for pi is v4i+1.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for
pi is v4i+2.
21.1.9. Line Strips With Adjacency
When the primitive topology is
VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY, one line primitive
with adjacency is defined by each vertex and the following vertex, according
to the equation:
-
pi = {vi, vi+1, vi+2, vi+3}
A line primitive is described by the second and third vertices of the total primitive, with the remaining two vertices only accessible in a geometry shader.
The number of primitives generated is equal to
max(0,vertexCount-3).
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the
provoking vertex for pi is vi+1.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for
pi is vi+2.
21.1.10. Triangle Lists With Adjacency
When the primitive topology is
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY, each consecutive
set of six vertices defines a single triangle primitive with adjacency,
according to the equations:
-
pi = {v6i, v6i+1, v6i+2, v6i+3, v6i+4, v6i+5}
A triangle primitive is described by the first, third, and fifth vertices of the total primitive, with the remaining three vertices only accessible in a geometry shader.
The number of primitives generated is equal to
⌊vertexCount/6⌋.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the
provoking vertex for pi is v6i.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for
pi is v6i+4.
21.1.11. Triangle Strips With Adjacency
When the primitive topology is
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY, one triangle
primitive with adjacency is defined by each vertex and the following 5
vertices.
The number of primitives generated, n, is equal to ⌊max(0,
vertexCount - 4)/2⌋.
If n=1, the primitive is defined as:
-
p = {v0, v1, v2, v5, v4, v3}
If n>1, the total primitive consists of different vertices according to where it is in the strip:
-
pi = {v2i, v2i+1, v2i+2, v2i+6, v2i+4, v2i+3} when i=0
-
pi = {v2i, v2i+3, v2i+4, v2i+6, v2i+2, v2i-2} when i>0, i<n-1, and i%2=1
-
pi = {v2i, v2i-2, v2i+2, v2i+6, v2i+4, v2i+3} when i>0, i<n-1, and i%2=0
-
pi = {v2i, v2i+3, v2i+4, v2i+5, v2i+2, v2i-2} when i=n-1 and i%2=1
-
pi = {v2i, v2i-2, v2i+2, v2i+5, v2i+4, v2i+3} when i=n-1 and i%2=0
A triangle primitive is described by the first, third, and fifth vertices of the total primitive in all cases, with the remaining three vertices only accessible in a geometry shader.
|
Note
The ordering of the vertices in each successive triangle is altered so that the winding order is consistent throughout the strip. |
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the
provoking vertex for pi is always v2i.
When the provokingVertexMode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the provoking vertex for
pi is always v2i+4.
21.1.12. Patch Lists
When the primitive topology is VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, each
consecutive set of m vertices defines a single patch primitive,
according to the equation:
-
pi = {vmi, vmi+1, …, vmi+(m-2), vmi+(m-1)}
where m is equal to
VkPipelineTessellationStateCreateInfo::patchControlPoints.
Patch lists are never passed to vertex post-processing,
and as such no provoking vertex is defined for patch primitives.
The number of primitives generated is equal to
⌊vertexCount/m⌋.
The vertices comprising a patch have no implied geometry, and are used as inputs to tessellation shaders and the fixed-function tessellator to generate new point, line, or triangle primitives.
21.2. Primitive Order
Primitives generated by drawing commands progress through the stages of the graphics pipeline in primitive order. Primitive order is initially determined in the following way:
-
Submission order determines the initial ordering
-
For indirect drawing commands, the order in which accessed instances of the VkDrawIndirectCommand are stored in
buffer, from lower indirect buffer addresses to higher addresses. -
If a drawing command includes multiple instances, the order in which instances are executed, from lower numbered instances to higher.
-
The order in which primitives are specified by a drawing command:
-
For non-indexed draws, from vertices with a lower numbered
vertexIndexto a higher numberedvertexIndex. -
For indexed draws, vertices sourced from a lower index buffer addresses to higher addresses.
-
For draws using mesh shaders, the order is provided by mesh shading.
-
Within this order implementations further sort primitives:
-
If tessellation shading is active, by an implementation-dependent order of new primitives generated by tessellation.
-
If geometry shading is active, by the order new primitives are generated by geometry shading.
-
If the polygon mode is not
VK_POLYGON_MODE_FILL, orVK_POLYGON_MODE_FILL_RECTANGLE_NV, by an implementation-dependent ordering of the new primitives generated within the original primitive.
Primitive order is later used to define rasterization order, which determines the order in which fragments output results to a framebuffer.
21.3. Programmable Primitive Shading
Once primitives are assembled, they proceed to the vertex shading stage of the pipeline. If the draw includes multiple instances, then the set of primitives is sent to the vertex shading stage multiple times, once for each instance.
It is implementation-dependent whether vertex shading occurs on vertices that are discarded as part of incomplete primitives, but if it does occur then it operates as if they were vertices in complete primitives and such invocations can have side effects.
Vertex shading receives two per-vertex inputs from the primitive assembly
stage - the vertexIndex and the instanceIndex.
How these values are generated is defined below, with each command.
Drawing commands fall roughly into two categories:
-
Non-indexed drawing commands present a sequential
vertexIndexto the vertex shader. The sequential index is generated automatically by the device (see Fixed-Function Vertex Processing for details on both specifying the vertex attributes indexed byvertexIndex, as well as binding vertex buffers containing those attributes to a command buffer). These commands are: -
Indexed drawing commands read index values from an index buffer and use this to compute the
vertexIndexvalue for the vertex shader. These commands are:
To bind an index buffer to a command buffer, call:
// Provided by VK_VERSION_1_0
void vkCmdBindIndexBuffer(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkIndexType indexType);
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer being bound. -
offsetis the starting offset in bytes withinbufferused in index buffer address calculations. -
indexTypeis a VkIndexType value specifying the size of the indices.
Possible values of vkCmdBindIndexBuffer::indexType, specifying
the size of indices, are:
// Provided by VK_VERSION_1_0
typedef enum VkIndexType {
VK_INDEX_TYPE_UINT16 = 0,
VK_INDEX_TYPE_UINT32 = 1,
// Provided by VK_KHR_acceleration_structure
VK_INDEX_TYPE_NONE_KHR = 1000165000,
// Provided by VK_EXT_index_type_uint8
VK_INDEX_TYPE_UINT8_EXT = 1000265000,
// Provided by VK_NV_ray_tracing
VK_INDEX_TYPE_NONE_NV = VK_INDEX_TYPE_NONE_KHR,
} VkIndexType;
-
VK_INDEX_TYPE_UINT16specifies that indices are 16-bit unsigned integer values. -
VK_INDEX_TYPE_UINT32specifies that indices are 32-bit unsigned integer values. -
VK_INDEX_TYPE_NONE_KHRspecifies that no indices are provided. -
VK_INDEX_TYPE_UINT8_EXTspecifies that indices are 8-bit unsigned integer values.
The parameters for each drawing command are specified directly in the command or read from buffer memory, depending on the command. Drawing commands that source their parameters from buffer memory are known as indirect drawing commands.
All drawing commands interact with the robustBufferAccess feature.
To record a non-indexed draw, call:
// Provided by VK_VERSION_1_0
void vkCmdDraw(
VkCommandBuffer commandBuffer,
uint32_t vertexCount,
uint32_t instanceCount,
uint32_t firstVertex,
uint32_t firstInstance);
-
commandBufferis the command buffer into which the command is recorded. -
vertexCountis the number of vertices to draw. -
instanceCountis the number of instances to draw. -
firstVertexis the index of the first vertex to draw. -
firstInstanceis the instance ID of the first instance to draw.
When the command is executed, primitives are assembled using the current
primitive topology and vertexCount consecutive vertex indices with the
first vertexIndex value equal to firstVertex.
The primitives are drawn instanceCount times with instanceIndex
starting with firstInstance and increasing sequentially for each
instance.
The assembled primitives execute the bound graphics pipeline.
To record an indexed draw, call:
// Provided by VK_VERSION_1_0
void vkCmdDrawIndexed(
VkCommandBuffer commandBuffer,
uint32_t indexCount,
uint32_t instanceCount,
uint32_t firstIndex,
int32_t vertexOffset,
uint32_t firstInstance);
-
commandBufferis the command buffer into which the command is recorded. -
indexCountis the number of vertices to draw. -
instanceCountis the number of instances to draw. -
firstIndexis the base index within the index buffer. -
vertexOffsetis the value added to the vertex index before indexing into the vertex buffer. -
firstInstanceis the instance ID of the first instance to draw.
When the command is executed, primitives are assembled using the current
primitive topology and indexCount vertices whose indices are retrieved
from the index buffer.
The index buffer is treated as an array of tightly packed unsigned integers
of size defined by the vkCmdBindIndexBuffer::indexType parameter
with which the buffer was bound.
The first vertex index is at an offset of firstIndex ×
indexSize + offset within the bound index buffer, where
offset is the offset specified by vkCmdBindIndexBuffer and
indexSize is the byte size of the type specified by indexType.
Subsequent index values are retrieved from consecutive locations in the
index buffer.
Indices are first compared to the primitive restart value, then zero
extended to 32 bits (if the indexType is
VK_INDEX_TYPE_UINT8_EXT or
VK_INDEX_TYPE_UINT16) and have vertexOffset added to them,
before being supplied as the vertexIndex value.
The primitives are drawn instanceCount times with instanceIndex
starting with firstInstance and increasing sequentially for each
instance.
The assembled primitives execute the bound graphics pipeline.
To record an ordered sequence of drawing operations which have no state changes between them, call:
// Provided by VK_EXT_multi_draw
void vkCmdDrawMultiEXT(
VkCommandBuffer commandBuffer,
uint32_t drawCount,
const VkMultiDrawInfoEXT* pVertexInfo,
uint32_t instanceCount,
uint32_t firstInstance,
uint32_t stride);
-
commandBufferis the command buffer into which the command is recorded. -
drawCountis the number of draws to execute, and can be zero. -
pVertexInfois a pointer to an array of VkMultiDrawInfoEXT with vertex information to be drawn. -
instanceCountis the number of instances to draw. -
firstInstanceis the instance ID of the first instance to draw. -
strideis the byte stride between consecutive elements ofpVertexInfo.
drawCount draws are executed with parameters taken from
pVertexInfo.
The number of draw commands recorded is drawCount, with each command
reading, sequentially, a firstVertex and a vertexCount from
pVertexInfo.
To record an ordered sequence of indexed drawing operations which have no state changes between them, call:
// Provided by VK_EXT_multi_draw
void vkCmdDrawMultiIndexedEXT(
VkCommandBuffer commandBuffer,
uint32_t drawCount,
const VkMultiDrawIndexedInfoEXT* pIndexInfo,
uint32_t instanceCount,
uint32_t firstInstance,
uint32_t stride,
const int32_t* pVertexOffset);
-
commandBufferis the command buffer into which the command is recorded. -
drawCountis the number of draws to execute, and can be zero. -
pIndexInfois a pointer to an array of VkMultiDrawIndexedInfoEXT with index information to be drawn. -
instanceCountis the number of instances to draw. -
firstInstanceis the instance ID of the first instance to draw. -
strideis the byte stride between consecutive elements ofpIndexInfo. -
pVertexOffsetisNULLor a pointer to the value added to the vertex index before indexing into the vertex buffer. When specified,VkMultiDrawIndexedInfoEXT::offsetis ignored.
drawCount indexed draws are executed with parameters taken from
pIndexInfo.
The number of draw commands recorded is drawCount, with each command
reading, sequentially, a firstIndex and an indexCount from
pIndexInfo.
If pVertexOffset is NULL, a vertexOffset is also read from
pIndexInfo, otherwise the value from dereferencing pVertexOffset
is used.
The VkMultiDrawInfoEXT structure is defined as:
// Provided by VK_EXT_multi_draw
typedef struct VkMultiDrawInfoEXT {
uint32_t firstVertex;
uint32_t vertexCount;
} VkMultiDrawInfoEXT;
-
firstVertexis the first vertex to draw. -
vertexCountis the number of vertices to draw.
The members of VkMultiDrawInfoEXT have the same meaning as the
firstVertex and vertexCount parameters in vkCmdDraw.
The VkMultiDrawIndexedInfoEXT structure is defined as:
// Provided by VK_EXT_multi_draw
typedef struct VkMultiDrawIndexedInfoEXT {
uint32_t firstIndex;
uint32_t indexCount;
int32_t vertexOffset;
} VkMultiDrawIndexedInfoEXT;
-
firstIndexis the first index to draw. -
indexCountis the number of vertices to draw. -
vertexOffsetis the value added to the vertex index before indexing into the vertex buffer for indexed multidraws.
The firstIndex, indexCount, and vertexOffset members of
VkMultiDrawIndexedInfoEXT have the same meaning as the
firstIndex, indexCount, and vertexOffset parameters,
respectively, of vkCmdDrawIndexed.
To record a non-indexed indirect drawing command, call:
// Provided by VK_VERSION_1_0
void vkCmdDrawIndirect(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
uint32_t drawCount,
uint32_t stride);
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
drawCountis the number of draws to execute, and can be zero. -
strideis the byte stride between successive sets of draw parameters.
vkCmdDrawIndirect behaves similarly to vkCmdDraw except that the
parameters are read by the device from a buffer during execution.
drawCount draws are executed by the command, with parameters taken
from buffer starting at offset and increasing by stride
bytes for each successive draw.
The parameters of each draw are encoded in an array of
VkDrawIndirectCommand structures.
If drawCount is less than or equal to one, stride is ignored.
The VkDrawIndirectCommand structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkDrawIndirectCommand {
uint32_t vertexCount;
uint32_t instanceCount;
uint32_t firstVertex;
uint32_t firstInstance;
} VkDrawIndirectCommand;
-
vertexCountis the number of vertices to draw. -
instanceCountis the number of instances to draw. -
firstVertexis the index of the first vertex to draw. -
firstInstanceis the instance ID of the first instance to draw.
The members of VkDrawIndirectCommand have the same meaning as the
similarly named parameters of vkCmdDraw.
To record a non-indexed draw call with a draw call count sourced from a buffer, call:
// Provided by VK_VERSION_1_2
void vkCmdDrawIndirectCount(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);
or the equivalent command
// Provided by VK_KHR_draw_indirect_count
void vkCmdDrawIndirectCountKHR(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);
or the equivalent command
// Provided by VK_AMD_draw_indirect_count
void vkCmdDrawIndirectCountAMD(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
countBufferis the buffer containing the draw count. -
countBufferOffsetis the byte offset intocountBufferwhere the draw count begins. -
maxDrawCountspecifies the maximum number of draws that will be executed. The actual number of executed draw calls is the minimum of the count specified incountBufferandmaxDrawCount. -
strideis the byte stride between successive sets of draw parameters.
vkCmdDrawIndirectCount behaves similarly to vkCmdDrawIndirect
except that the draw count is read by the device from a buffer during
execution.
The command will read an unsigned 32-bit integer from countBuffer
located at countBufferOffset and use this as the draw count.
To record an indexed indirect drawing command, call:
// Provided by VK_VERSION_1_0
void vkCmdDrawIndexedIndirect(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
uint32_t drawCount,
uint32_t stride);
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
drawCountis the number of draws to execute, and can be zero. -
strideis the byte stride between successive sets of draw parameters.
vkCmdDrawIndexedIndirect behaves similarly to vkCmdDrawIndexed
except that the parameters are read by the device from a buffer during
execution.
drawCount draws are executed by the command, with parameters taken
from buffer starting at offset and increasing by stride
bytes for each successive draw.
The parameters of each draw are encoded in an array of
VkDrawIndexedIndirectCommand structures.
If drawCount is less than or equal to one, stride is ignored.
The VkDrawIndexedIndirectCommand structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkDrawIndexedIndirectCommand {
uint32_t indexCount;
uint32_t instanceCount;
uint32_t firstIndex;
int32_t vertexOffset;
uint32_t firstInstance;
} VkDrawIndexedIndirectCommand;
-
indexCountis the number of vertices to draw. -
instanceCountis the number of instances to draw. -
firstIndexis the base index within the index buffer. -
vertexOffsetis the value added to the vertex index before indexing into the vertex buffer. -
firstInstanceis the instance ID of the first instance to draw.
The members of VkDrawIndexedIndirectCommand have the same meaning as
the similarly named parameters of vkCmdDrawIndexed.
To record an indexed draw call with a draw call count sourced from a buffer, call:
// Provided by VK_VERSION_1_2
void vkCmdDrawIndexedIndirectCount(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);
or the equivalent command
// Provided by VK_KHR_draw_indirect_count
void vkCmdDrawIndexedIndirectCountKHR(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);
or the equivalent command
// Provided by VK_AMD_draw_indirect_count
void vkCmdDrawIndexedIndirectCountAMD(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
countBufferis the buffer containing the draw count. -
countBufferOffsetis the byte offset intocountBufferwhere the draw count begins. -
maxDrawCountspecifies the maximum number of draws that will be executed. The actual number of executed draw calls is the minimum of the count specified incountBufferandmaxDrawCount. -
strideis the byte stride between successive sets of draw parameters.
vkCmdDrawIndexedIndirectCount behaves similarly to
vkCmdDrawIndexedIndirect except that the draw count is read by the
device from a buffer during execution.
The command will read an unsigned 32-bit integer from countBuffer
located at countBufferOffset and use this as the draw count.
21.3.1. Drawing Transform Feedback
It is possible to draw vertex data that was previously captured during
active transform feedback by binding
one or more of the transform feedback buffers as vertex buffers.
A pipeline barrier is required between using the buffers as transform
feedback buffers and vertex buffers to ensure all writes to the transform
feedback buffers are visible when the data is read as vertex attributes.
The source access is VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT and
the destination access is VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT for the
pipeline stages VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT and
VK_PIPELINE_STAGE_VERTEX_INPUT_BIT respectively.
The value written to the counter buffer by
vkCmdEndTransformFeedbackEXT can be used to determine the vertex
count for the draw.
A pipeline barrier is required between using the counter buffer for
vkCmdEndTransformFeedbackEXT and vkCmdDrawIndirectByteCountEXT
where the source access is
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT and the destination
access is VK_ACCESS_INDIRECT_COMMAND_READ_BIT for the pipeline stages
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT and
VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT respectively.
To record a non-indexed draw call, where the vertex count is based on a byte count read from a buffer and the passed in vertex stride parameter, call:
// Provided by VK_EXT_transform_feedback
void vkCmdDrawIndirectByteCountEXT(
VkCommandBuffer commandBuffer,
uint32_t instanceCount,
uint32_t firstInstance,
VkBuffer counterBuffer,
VkDeviceSize counterBufferOffset,
uint32_t counterOffset,
uint32_t vertexStride);
-
commandBufferis the command buffer into which the command is recorded. -
instanceCountis the number of instances to draw. -
firstInstanceis the instance ID of the first instance to draw. -
counterBufferis the buffer handle from where the byte count is read. -
counterBufferOffsetis the offset into the buffer used to read the byte count, which is used to calculate the vertex count for this draw call. -
counterOffsetis subtracted from the byte count read from thecounterBufferat thecounterBufferOffset -
vertexStrideis the stride in bytes between each element of the vertex data that is used to calculate the vertex count from the counter value. This value is typically the same value that was used in the graphics pipeline state when the transform feedback was captured as theXfbStride.
When the command is executed, primitives are assembled in the same way as
done with vkCmdDraw except the vertexCount is calculated based
on the byte count read from counterBuffer at offset
counterBufferOffset.
The assembled primitives execute the bound graphics pipeline.
The effective vertexCount is calculated as follows:
const uint32_t * counterBufferPtr = (const uint8_t *)counterBuffer.address + counterBufferOffset;
vertexCount = floor(max(0, (*counterBufferPtr - counterOffset)) / vertexStride);
The effective firstVertex is zero.
21.4. Conditional Rendering
Certain rendering commands can be executed conditionally based on a value in buffer memory. These rendering commands are limited to drawing commands, dispatching commands, and clearing attachments with vkCmdClearAttachments within a conditional rendering block which is defined by commands vkCmdBeginConditionalRenderingEXT and vkCmdEndConditionalRenderingEXT. Other rendering commands remain unaffected by conditional rendering.
After beginning conditional rendering, it is considered active within the command buffer it was called until it is ended with vkCmdEndConditionalRenderingEXT.
Conditional rendering must begin and end in the same command buffer.
When conditional rendering is active, a primary command buffer can execute
secondary command buffers if the inheritedConditionalRendering feature is enabled.
For a secondary command buffer to be executed while conditional rendering is
active in the primary command buffer, it must set the
conditionalRenderingEnable flag of
VkCommandBufferInheritanceConditionalRenderingInfoEXT, as described in
the Command Buffer Recording section.
Conditional rendering must also either begin and end inside the same subpass of a render pass instance, or must both begin and end outside of a render pass instance (i.e. contain entire render pass instances).
To begin conditional rendering, call:
// Provided by VK_EXT_conditional_rendering
void vkCmdBeginConditionalRenderingEXT(
VkCommandBuffer commandBuffer,
const VkConditionalRenderingBeginInfoEXT* pConditionalRenderingBegin);
-
commandBufferis the command buffer into which this command will be recorded. -
pConditionalRenderingBeginis a pointer to a VkConditionalRenderingBeginInfoEXT structure specifying parameters of conditional rendering.
The VkConditionalRenderingBeginInfoEXT structure is defined as:
// Provided by VK_EXT_conditional_rendering
typedef struct VkConditionalRenderingBeginInfoEXT {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
VkDeviceSize offset;
VkConditionalRenderingFlagsEXT flags;
} VkConditionalRenderingBeginInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferis a buffer containing the predicate for conditional rendering. -
offsetis the byte offset intobufferwhere the predicate is located. -
flagsis a bitmask of VkConditionalRenderingFlagsEXT specifying the behavior of conditional rendering.
If the 32-bit value at offset in buffer memory is zero, then the
rendering commands are discarded, otherwise they are executed as normal.
If the value of the predicate in buffer memory changes while conditional
rendering is active, the rendering commands may be discarded in an
implementation-dependent way.
Some implementations may latch the value of the predicate upon beginning
conditional rendering while others may read it before every rendering
command.
Bits which can be set in
vkCmdBeginConditionalRenderingEXT::flags, specifying the
behavior of conditional rendering, are:
// Provided by VK_EXT_conditional_rendering
typedef enum VkConditionalRenderingFlagBitsEXT {
VK_CONDITIONAL_RENDERING_INVERTED_BIT_EXT = 0x00000001,
} VkConditionalRenderingFlagBitsEXT;
-
VK_CONDITIONAL_RENDERING_INVERTED_BIT_EXTspecifies the condition used to determine whether to discard rendering commands or not. That is, if the 32-bit predicate read frombuffermemory atoffsetis zero, the rendering commands are not discarded, and if non zero, then they are discarded.
// Provided by VK_EXT_conditional_rendering
typedef VkFlags VkConditionalRenderingFlagsEXT;
VkConditionalRenderingFlagsEXT is a bitmask type for setting a mask of
zero or more VkConditionalRenderingFlagBitsEXT.
To end conditional rendering, call:
// Provided by VK_EXT_conditional_rendering
void vkCmdEndConditionalRenderingEXT(
VkCommandBuffer commandBuffer);
-
commandBufferis the command buffer into which this command will be recorded.
Once ended, conditional rendering becomes inactive.
21.5. Programmable Mesh Shading
In this drawing approach, primitives are assembled by the mesh shader stage. Mesh shading operates similarly to dispatching compute as the shaders make use of workgroups.
To record a draw that uses the mesh pipeline, call:
// Provided by VK_NV_mesh_shader
void vkCmdDrawMeshTasksNV(
VkCommandBuffer commandBuffer,
uint32_t taskCount,
uint32_t firstTask);
-
commandBufferis the command buffer into which the command will be recorded. -
taskCountis the number of local workgroups to dispatch in the X dimension. Y and Z dimension are implicitly set to one. -
firstTaskis the X component of the first workgroup ID.
When the command is executed, a global workgroup consisting of
taskCount local workgroups is assembled.
To record an indirect mesh tasks draw, call:
// Provided by VK_NV_mesh_shader
void vkCmdDrawMeshTasksIndirectNV(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
uint32_t drawCount,
uint32_t stride);
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
drawCountis the number of draws to execute, and can be zero. -
strideis the byte stride between successive sets of draw parameters.
vkCmdDrawMeshTasksIndirectNV behaves similarly to
vkCmdDrawMeshTasksNV except that the parameters are read by the device
from a buffer during execution.
drawCount draws are executed by the command, with parameters taken
from buffer starting at offset and increasing by stride
bytes for each successive draw.
The parameters of each draw are encoded in an array of
VkDrawMeshTasksIndirectCommandNV structures.
If drawCount is less than or equal to one, stride is ignored.
The VkDrawMeshTasksIndirectCommandNV structure is defined as:
// Provided by VK_NV_mesh_shader
typedef struct VkDrawMeshTasksIndirectCommandNV {
uint32_t taskCount;
uint32_t firstTask;
} VkDrawMeshTasksIndirectCommandNV;
-
taskCountis the number of local workgroups to dispatch in the X dimension. Y and Z dimension are implicitly set to one. -
firstTaskis the X component of the first workgroup ID.
The members of VkDrawMeshTasksIndirectCommandNV have the same meaning
as the similarly named parameters of vkCmdDrawMeshTasksNV.
To record an indirect mesh tasks draw with the draw count sourced from a buffer, call:
// Provided by VK_NV_mesh_shader
void vkCmdDrawMeshTasksIndirectCountNV(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkBuffer countBuffer,
VkDeviceSize countBufferOffset,
uint32_t maxDrawCount,
uint32_t stride);
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin. -
countBufferis the buffer containing the draw count. -
countBufferOffsetis the byte offset intocountBufferwhere the draw count begins. -
maxDrawCountspecifies the maximum number of draws that will be executed. The actual number of executed draw calls is the minimum of the count specified incountBufferandmaxDrawCount. -
strideis the byte stride between successive sets of draw parameters.
vkCmdDrawMeshTasksIndirectCountNV behaves similarly to
vkCmdDrawMeshTasksIndirectNV except that the draw count is read by the
device from a buffer during execution.
The command will read an unsigned 32-bit integer from countBuffer
located at countBufferOffset and use this as the draw count.
22. Fixed-Function Vertex Processing
Vertex fetching is controlled via configurable state, as a logically distinct graphics pipeline stage.
22.1. Vertex Attributes
Vertex shaders can define input variables, which receive vertex attribute
data transferred from one or more VkBuffer(s) by drawing commands.
Vertex shader input variables are bound to buffers via an indirect binding
where the vertex shader associates a vertex input attribute number with
each variable, vertex input attributes are associated to vertex input
bindings on a per-pipeline basis, and vertex input bindings are associated
with specific buffers on a per-draw basis via the
vkCmdBindVertexBuffers command.
Vertex input attribute and vertex input binding descriptions also contain
format information controlling how data is extracted from buffer memory and
converted to the format expected by the vertex shader.
There are VkPhysicalDeviceLimits::maxVertexInputAttributes
number of vertex input attributes and
VkPhysicalDeviceLimits::maxVertexInputBindings number of vertex
input bindings (each referred to by zero-based indices), where there are at
least as many vertex input attributes as there are vertex input bindings.
Applications can store multiple vertex input attributes interleaved in a
single buffer, and use a single vertex input binding to access those
attributes.
In GLSL, vertex shaders associate input variables with a vertex input
attribute number using the location layout qualifier.
The component layout qualifier associates components of a vertex shader
input variable with components of a vertex input attribute.
// Assign location M to variableName
layout (location=M, component=2) in vec2 variableName;
// Assign locations [N,N+L) to the array elements of variableNameArray
layout (location=N) in vec4 variableNameArray[L];
In SPIR-V, vertex shaders associate input variables with a vertex input
attribute number using the Location decoration.
The Component decoration associates components of a vertex shader input
variable with components of a vertex input attribute.
The Location and Component decorations are specified via the
OpDecorate instruction.
...
%1 = OpExtInstImport "GLSL.std.450"
...
OpName %9 "variableName"
OpName %15 "variableNameArray"
OpDecorate %18 BuiltIn VertexIndex
OpDecorate %19 BuiltIn InstanceIndex
OpDecorate %9 Location M
OpDecorate %9 Component 2
OpDecorate %15 Location N
...
%2 = OpTypeVoid
%3 = OpTypeFunction %2
%6 = OpTypeFloat 32
%7 = OpTypeVector %6 2
%8 = OpTypePointer Input %7
%9 = OpVariable %8 Input
%10 = OpTypeVector %6 4
%11 = OpTypeInt 32 0
%12 = OpConstant %11 L
%13 = OpTypeArray %10 %12
%14 = OpTypePointer Input %13
%15 = OpVariable %14 Input
...
22.1.1. Attribute Location and Component Assignment
Vertex shaders allow Location and Component decorations on input
variable declarations.
The Location decoration specifies which vertex input attribute is used
to read and interpret the data that a variable will consume.
The Component decoration allows the location to be more finely
specified for scalars and vectors, down to the individual components within
a location that are consumed.
The components within a location are 0, 1, 2, and 3.
A variable starting at component N will consume components N, N+1, N+2, …
up through its size.
For single precision types, it is invalid if the sequence of components gets
larger than 3.
When a vertex shader input variable declared using a 16- or 32-bit scalar or
vector data type is assigned a location, its value(s) are taken from the
components of the input attribute specified with the corresponding
VkVertexInputAttributeDescription::location.
The components used depend on the type of variable and the Component
decoration specified in the variable declaration, as identified in
Input attribute components accessed by 16-bit and 32-bit input variables.
Any 16-bit or 32-bit scalar or vector input will consume a single location.
For 16-bit and 32-bit data types, missing components are filled in with
default values as described below.
| 16-bit or 32-bit data type | Component decoration |
Components consumed |
|---|---|---|
scalar |
0 or unspecified |
(x, o, o, o) |
scalar |
1 |
(o, y, o, o) |
scalar |
2 |
(o, o, z, o) |
scalar |
3 |
(o, o, o, w) |
two-component vector |
0 or unspecified |
(x, y, o, o) |
two-component vector |
1 |
(o, y, z, o) |
two-component vector |
2 |
(o, o, z, w) |
three-component vector |
0 or unspecified |
(x, y, z, o) |
three-component vector |
1 |
(o, y, z, w) |
four-component vector |
0 or unspecified |
(x, y, z, w) |
Components indicated by “o” are available for use by other input variables which are sourced from the same attribute, and if used, are either filled with the corresponding component from the input format (if present), or the default value.
When a vertex shader input variable declared using a 32-bit floating point
matrix type is assigned a location i, its values are taken from
consecutive input attributes starting with the corresponding
VkVertexInputAttributeDescription::location.
Such matrices are treated as an array of column vectors with values taken
from the input attributes identified in Input attributes accessed by 32-bit input matrix variables.
The VkVertexInputAttributeDescription::format must be specified
with a VkFormat that corresponds to the appropriate type of column
vector.
The Component decoration must not be used with matrix types.
| Data type | Column vector type | Locations consumed | Components consumed |
|---|---|---|---|
mat2 |
two-component vector |
i, i+1 |
(x, y, o, o), (x, y, o, o) |
mat2x3 |
three-component vector |
i, i+1 |
(x, y, z, o), (x, y, z, o) |
mat2x4 |
four-component vector |
i, i+1 |
(x, y, z, w), (x, y, z, w) |
mat3x2 |
two-component vector |
i, i+1, i+2 |
(x, y, o, o), (x, y, o, o), (x, y, o, o) |
mat3 |
three-component vector |
i, i+1, i+2 |
(x, y, z, o), (x, y, z, o), (x, y, z, o) |
mat3x4 |
four-component vector |
i, i+1, i+2 |
(x, y, z, w), (x, y, z, w), (x, y, z, w) |
mat4x2 |
two-component vector |
i, i+1, i+2, i+3 |
(x, y, o, o), (x, y, o, o), (x, y, o, o), (x, y, o, o) |
mat4x3 |
three-component vector |
i, i+1, i+2, i+3 |
(x, y, z, o), (x, y, z, o), (x, y, z, o), (x, y, z, o) |
mat4 |
four-component vector |
i, i+1, i+2, i+3 |
(x, y, z, w), (x, y, z, w), (x, y, z, w), (x, y, z, w) |
Components indicated by “o” are available for use by other input variables which are sourced from the same attribute, and if used, are either filled with the corresponding component from the input (if present), or the default value.
When a vertex shader input variable declared using a scalar or vector 64-bit
data type is assigned a location i, its values are taken from consecutive
input attributes starting with the corresponding
VkVertexInputAttributeDescription::location.
The locations and components used depend on the type of variable and the
Component decoration specified in the variable declaration, as
identified in Input attribute locations and components accessed by 64-bit input variables.
For 64-bit data types, no default attribute values are provided.
Input variables must not use more components than provided by the
attribute.
Input attributes which have one- or two-component 64-bit formats will
consume a single location.
Input attributes which have three- or four-component 64-bit formats will
consume two consecutive locations.
A 64-bit scalar data type will consume two components, and a 64-bit
two-component vector data type will consume all four components available
within a location.
A three- or four-component 64-bit data type must not specify a component.
A three-component 64-bit data type will consume all four components of the
first location and components 0 and 1 of the second location.
This leaves components 2 and 3 available for other component-qualified
declarations.
A four-component 64-bit data type will consume all four components of the
first location and all four components of the second location.
It is invalid for a scalar or two-component 64-bit data type to specify a
component of 1 or 3.
| Input format | Locations consumed | 64-bit data type | Location decoration |
Component decoration |
32-bit components consumed |
|---|---|---|---|---|---|
R64 |
i |
scalar |
i |
0 or unspecified |
(x, y, -, -) |
R64G64 |
i |
scalar |
i |
0 or unspecified |
(x, y, o, o) |
scalar |
i |
2 |
(o, o, z, w) |
||
two-component vector |
i |
0 or unspecified |
(x, y, z, w) |
||
R64G64B64 |
i, i+1 |
scalar |
i |
0 or unspecified |
(x, y, o, o), (o, o, -, -) |
scalar |
i |
2 |
(o, o, z, w), (o, o, -, -) |
||
scalar |
i+1 |
0 or unspecified |
(o, o, o, o), (x, y, -, -) |
||
two-component vector |
i |
0 or unspecified |
(x, y, z, w), (o, o, -, -) |
||
three-component vector |
i |
unspecified |
(x, y, z, w), (x, y, -, -) |
||
R64G64B64A64 |
i, i+1 |
scalar |
i |
0 or unspecified |
(x, y, o, o), (o, o, o, o) |
scalar |
i |
2 |
(o, o, z, w), (o, o, o, o) |
||
scalar |
i+1 |
0 or unspecified |
(o, o, o, o), (x, y, o, o) |
||
scalar |
i+1 |
2 |
(o, o, o, o), (o, o, z, w) |
||
two-component vector |
i |
0 or unspecified |
(x, y, z, w), (o, o, o, o) |
||
two-component vector |
i+1 |
0 or unspecified |
(o, o, o, o), (x, y, z, w) |
||
three-component vector |
i |
unspecified |
(x, y, z, w), (x, y, o, o) |
||
four-component vector |
i |
unspecified |
(x, y, z, w), (x, y, z, w) |
Components indicated by “o” are available for use by other input variables which are sourced from the same attribute. Components indicated by “-” are not available for input variables as there are no default values provided for 64-bit data types, and there is no data provided by the input format.
When a vertex shader input variable declared using a 64-bit floating-point matrix type is assigned a location i, its values are taken from consecutive input attribute locations. Such matrices are treated as an array of column vectors with values taken from the input attributes as shown in Input attribute locations and components accessed by 64-bit input variables. Each column vector starts at the location immediately following the last location of the previous column vector. The number of attributes and components assigned to each matrix is determined by the matrix dimensions and ranges from two to eight locations.
When a vertex shader input variable declared using an array type is assigned
a location, its values are taken from consecutive input attributes starting
with the corresponding
VkVertexInputAttributeDescription::location.
The number of attributes and components assigned to each element are
determined according to the data type of the array elements and
Component decoration (if any) specified in the declaration of the
array, as described above.
Each element of the array, in order, is assigned to consecutive locations,
but all at the same specified component within each location.
Only input variables declared with the data types and component decorations as specified above are supported. Location aliasing is causing two variables to have the same location number. Component aliasing is assigning the same (or overlapping) component number for two location aliases. Location aliasing is allowed only if it does not cause component aliasing. Further, when location aliasing, the aliases sharing the location must all have the same SPIR-V floating-point component type or all have the same width integer-type components.
22.2. Vertex Input Description
Applications specify vertex input attribute and vertex input binding
descriptions as part of graphics pipeline creation by setting the
VkGraphicsPipelineCreateInfo::pVertexInputState pointer to a
VkPipelineVertexInputStateCreateInfo structure.
Alternatively, if the graphics pipeline is created with the
VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state enabled, then the
vertex input attribute and vertex input binding descriptions are specified
dynamically with vkCmdSetVertexInputEXT, and the
VkGraphicsPipelineCreateInfo::pVertexInputState pointer is
ignored.
The VkPipelineVertexInputStateCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineVertexInputStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineVertexInputStateCreateFlags flags;
uint32_t vertexBindingDescriptionCount;
const VkVertexInputBindingDescription* pVertexBindingDescriptions;
uint32_t vertexAttributeDescriptionCount;
const VkVertexInputAttributeDescription* pVertexAttributeDescriptions;
} VkPipelineVertexInputStateCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
vertexBindingDescriptionCountis the number of vertex binding descriptions provided inpVertexBindingDescriptions. -
pVertexBindingDescriptionsis a pointer to an array ofVkVertexInputBindingDescriptionstructures. -
vertexAttributeDescriptionCountis the number of vertex attribute descriptions provided inpVertexAttributeDescriptions. -
pVertexAttributeDescriptionsis a pointer to an array ofVkVertexInputAttributeDescriptionstructures.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineVertexInputStateCreateFlags;
VkPipelineVertexInputStateCreateFlags is a bitmask type for setting a
mask, but is currently reserved for future use.
Each vertex input binding is specified by the
VkVertexInputBindingDescription structure, defined as:
// Provided by VK_VERSION_1_0
typedef struct VkVertexInputBindingDescription {
uint32_t binding;
uint32_t stride;
VkVertexInputRate inputRate;
} VkVertexInputBindingDescription;
-
bindingis the binding number that this structure describes. -
strideis the byte stride between consecutive elements within the buffer. -
inputRateis a VkVertexInputRate value specifying whether vertex attribute addressing is a function of the vertex index or of the instance index.
Possible values of VkVertexInputBindingDescription::inputRate,
specifying the rate at which vertex attributes are pulled from buffers, are:
// Provided by VK_VERSION_1_0
typedef enum VkVertexInputRate {
VK_VERTEX_INPUT_RATE_VERTEX = 0,
VK_VERTEX_INPUT_RATE_INSTANCE = 1,
} VkVertexInputRate;
-
VK_VERTEX_INPUT_RATE_VERTEXspecifies that vertex attribute addressing is a function of the vertex index. -
VK_VERTEX_INPUT_RATE_INSTANCEspecifies that vertex attribute addressing is a function of the instance index.
Each vertex input attribute is specified by the
VkVertexInputAttributeDescription structure, defined as:
// Provided by VK_VERSION_1_0
typedef struct VkVertexInputAttributeDescription {
uint32_t location;
uint32_t binding;
VkFormat format;
uint32_t offset;
} VkVertexInputAttributeDescription;
-
locationis the shader input location number for this attribute. -
bindingis the binding number which this attribute takes its data from. -
formatis the size and type of the vertex attribute data. -
offsetis a byte offset of this attribute relative to the start of an element in the vertex input binding.
To dynamically set the vertex input attribute and vertex input binding descriptions, call:
// Provided by VK_EXT_vertex_input_dynamic_state
void vkCmdSetVertexInputEXT(
VkCommandBuffer commandBuffer,
uint32_t vertexBindingDescriptionCount,
const VkVertexInputBindingDescription2EXT* pVertexBindingDescriptions,
uint32_t vertexAttributeDescriptionCount,
const VkVertexInputAttributeDescription2EXT* pVertexAttributeDescriptions);
-
commandBufferis the command buffer into which the command will be recorded. -
vertexBindingDescriptionCountis the number of vertex binding descriptions provided inpVertexBindingDescriptions. -
pVertexBindingDescriptionsis a pointer to an array ofVkVertexInputBindingDescription2EXTstructures. -
vertexAttributeDescriptionCountis the number of vertex attribute descriptions provided inpVertexAttributeDescriptions. -
pVertexAttributeDescriptionsis a pointer to an array ofVkVertexInputAttributeDescription2EXTstructures.
This command sets the vertex input attribute and vertex input binding
descriptions state for subsequent drawing commands when the graphics
pipeline is created with VK_DYNAMIC_STATE_VERTEX_INPUT_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkGraphicsPipelineCreateInfo::pVertexInputState values used to
create the currently active pipeline.
If the bound pipeline state object was also created with the
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE dynamic state enabled,
then vkCmdBindVertexBuffers2 can be used instead of
vkCmdSetVertexInputEXT to dynamically set the stride.
The VkVertexInputBindingDescription2EXT structure is defined as:
// Provided by VK_EXT_vertex_input_dynamic_state
typedef struct VkVertexInputBindingDescription2EXT {
VkStructureType sType;
void* pNext;
uint32_t binding;
uint32_t stride;
VkVertexInputRate inputRate;
uint32_t divisor;
} VkVertexInputBindingDescription2EXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bindingis the binding number that this structure describes. -
strideis the byte stride between consecutive elements within the buffer. -
inputRateis a VkVertexInputRate value specifying whether vertex attribute addressing is a function of the vertex index or of the instance index. -
divisoris the number of successive instances that will use the same value of the vertex attribute when instanced rendering is enabled. This member can be set to a value other than1if thevertexAttributeInstanceRateDivisorfeature is enabled. For example, if the divisor is N, the same vertex attribute will be applied to N successive instances before moving on to the next vertex attribute. The maximum value ofdivisoris implementation-dependent and can be queried usingVkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::maxVertexAttribDivisor. A value of0can be used for the divisor if thevertexAttributeInstanceRateZeroDivisorfeature is enabled. In this case, the same vertex attribute will be applied to all instances.
The VkVertexInputAttributeDescription2EXT structure is defined as:
// Provided by VK_EXT_vertex_input_dynamic_state
typedef struct VkVertexInputAttributeDescription2EXT {
VkStructureType sType;
void* pNext;
uint32_t location;
uint32_t binding;
VkFormat format;
uint32_t offset;
} VkVertexInputAttributeDescription2EXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
locationis the shader input location number for this attribute. -
bindingis the binding number which this attribute takes its data from. -
formatis the size and type of the vertex attribute data. -
offsetis a byte offset of this attribute relative to the start of an element in the vertex input binding.
To bind vertex buffers to a command buffer for use in subsequent drawing commands, call:
// Provided by VK_VERSION_1_0
void vkCmdBindVertexBuffers(
VkCommandBuffer commandBuffer,
uint32_t firstBinding,
uint32_t bindingCount,
const VkBuffer* pBuffers,
const VkDeviceSize* pOffsets);
-
commandBufferis the command buffer into which the command is recorded. -
firstBindingis the index of the first vertex input binding whose state is updated by the command. -
bindingCountis the number of vertex input bindings whose state is updated by the command. -
pBuffersis a pointer to an array of buffer handles. -
pOffsetsis a pointer to an array of buffer offsets.
The values taken from elements i of pBuffers and pOffsets
replace the current state for the vertex input binding
firstBinding + i, for i in [0,
bindingCount).
The vertex input binding is updated to start at the offset indicated by
pOffsets[i] from the start of the buffer pBuffers[i].
All vertex input attributes that use each of these bindings will use these
updated addresses in their address calculations for subsequent drawing
commands.
If the nullDescriptor feature is enabled,
elements of pBuffers can be VK_NULL_HANDLE, and can be used by
the vertex shader.
If a vertex input attribute is bound to a vertex input binding that is
VK_NULL_HANDLE, the values taken from memory are considered to be
zero, and missing G, B, or A components are
filled with (0,0,1).
Alternatively, to bind vertex buffers, along with their sizes and strides, to a command buffer for use in subsequent drawing commands, call:
// Provided by VK_VERSION_1_3
void vkCmdBindVertexBuffers2(
VkCommandBuffer commandBuffer,
uint32_t firstBinding,
uint32_t bindingCount,
const VkBuffer* pBuffers,
const VkDeviceSize* pOffsets,
const VkDeviceSize* pSizes,
const VkDeviceSize* pStrides);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdBindVertexBuffers2EXT(
VkCommandBuffer commandBuffer,
uint32_t firstBinding,
uint32_t bindingCount,
const VkBuffer* pBuffers,
const VkDeviceSize* pOffsets,
const VkDeviceSize* pSizes,
const VkDeviceSize* pStrides);
-
commandBufferis the command buffer into which the command is recorded. -
firstBindingis the index of the first vertex input binding whose state is updated by the command. -
bindingCountis the number of vertex input bindings whose state is updated by the command. -
pBuffersis a pointer to an array of buffer handles. -
pOffsetsis a pointer to an array of buffer offsets. -
pSizesisNULLor a pointer to an array of the size in bytes of vertex data bound frompBuffers. -
pStridesisNULLor a pointer to an array of buffer strides.
The values taken from elements i of pBuffers and pOffsets
replace the current state for the vertex input binding
firstBinding + i, for i in [0,
bindingCount).
The vertex input binding is updated to start at the offset indicated by
pOffsets[i] from the start of the buffer pBuffers[i].
If pSizes is not NULL then pSizes[i] specifies the bound size
of the vertex buffer starting from the corresponding elements of
pBuffers[i] plus pOffsets[i].
All vertex input attributes that use each of these bindings will use these
updated addresses in their address calculations for subsequent drawing
commands.
If the nullDescriptor feature is enabled,
elements of pBuffers can be VK_NULL_HANDLE, and can be used by
the vertex shader.
If a vertex input attribute is bound to a vertex input binding that is
VK_NULL_HANDLE, the values taken from memory are considered to be
zero, and missing G, B, or A components are
filled with (0,0,1).
This command also dynamically sets the byte
strides between consecutive elements within buffer pBuffers[i] to the
corresponding pStrides[i] value when the graphics pipeline is created
with VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, strides are specified by the
VkVertexInputBindingDescription::stride values used to create
the currently active pipeline.
If the bound pipeline state object was also created with the
VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state enabled then
vkCmdSetVertexInputEXT can be used instead of
vkCmdBindVertexBuffers2 to set the stride.
22.3. Vertex Attribute Divisor in Instanced Rendering
If the vertexAttributeInstanceRateDivisor feature is enabled and the
pNext chain of VkPipelineVertexInputStateCreateInfo includes a
VkPipelineVertexInputDivisorStateCreateInfoEXT structure, then that
structure controls how vertex attributes are assigned to an instance when
instanced rendering is enabled.
The VkPipelineVertexInputDivisorStateCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_vertex_attribute_divisor
typedef struct VkPipelineVertexInputDivisorStateCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t vertexBindingDivisorCount;
const VkVertexInputBindingDivisorDescriptionEXT* pVertexBindingDivisors;
} VkPipelineVertexInputDivisorStateCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexBindingDivisorCountis the number of elements in thepVertexBindingDivisorsarray. -
pVertexBindingDivisorsis a pointer to an array ofVkVertexInputBindingDivisorDescriptionEXTstructures specifying the divisor value for each binding.
The individual divisor values per binding are specified using the
VkVertexInputBindingDivisorDescriptionEXT structure which is defined
as:
// Provided by VK_EXT_vertex_attribute_divisor
typedef struct VkVertexInputBindingDivisorDescriptionEXT {
uint32_t binding;
uint32_t divisor;
} VkVertexInputBindingDivisorDescriptionEXT;
-
bindingis the binding number for which the divisor is specified. -
divisoris the number of successive instances that will use the same value of the vertex attribute when instanced rendering is enabled. For example, if the divisor is N, the same vertex attribute will be applied to N successive instances before moving on to the next vertex attribute. The maximum value ofdivisoris implementation-dependent and can be queried usingVkPhysicalDeviceVertexAttributeDivisorPropertiesEXT::maxVertexAttribDivisor. A value of0can be used for the divisor if thevertexAttributeInstanceRateZeroDivisorfeature is enabled. In this case, the same vertex attribute will be applied to all instances.
If this structure is not used to define a divisor value for an attribute, then the divisor has a logical default value of 1.
22.4. Vertex Input Address Calculation
The address of each attribute for each vertexIndex and
instanceIndex is calculated as follows:
-
Let
attribDescbe the member of VkPipelineVertexInputStateCreateInfo::pVertexAttributeDescriptionswithVkVertexInputAttributeDescription::locationequal to the vertex input attribute number. -
Let
bindingDescbe the member of VkPipelineVertexInputStateCreateInfo::pVertexBindingDescriptionswithVkVertexInputAttributeDescription::bindingequal toattribDesc.binding. -
Let
vertexIndexbe the index of the vertex within the draw (a value betweenfirstVertexandfirstVertex+vertexCountforvkCmdDraw, or a value taken from the index buffer plusvertexOffsetforvkCmdDrawIndexed), and letinstanceIndexbe the instance number of the draw (a value betweenfirstInstanceandfirstInstance+instanceCount). -
Let
offsetbe an array of offsets into the currently bound vertex buffers specified duringvkCmdBindVertexBuffersorvkCmdBindVertexBuffers2withpOffsets. -
Let
divisorbe the member of VkPipelineVertexInputDivisorStateCreateInfoEXT::pVertexBindingDivisorswithVkVertexInputBindingDivisorDescriptionEXT::bindingequal toattribDesc.binding.
bufferBindingAddress = buffer[binding].baseAddress + offset[binding];
if (bindingDesc.inputRate == VK_VERTEX_INPUT_RATE_VERTEX)
effectiveVertexOffset = vertexIndex * bindingDesc.stride;
else
if (divisor == 0)
effectiveVertexOffset = firstInstance * bindingDesc.stride;
else
effectiveVertexOffset = (firstInstance + ((instanceIndex - firstInstance) / divisor)) * bindingDesc.stride;
attribAddress = bufferBindingAddress + effectiveVertexOffset + attribDesc.offset;
22.4.1. Vertex Input Extraction
For each attribute, raw data is extracted starting at attribAddress and is
converted from the VkVertexInputAttributeDescription’s format to
either floating-point, unsigned integer, or signed integer based on the base
type of the format; the base type of the format must match the base type of
the input variable in the shader.
The input variable in the shader must be declared as a 64-bit data type if
and only if format is a 64-bit data type.
If format is a packed format, attribAddress must be a multiple of
the size in bytes of the whole attribute data type as described in
Packed Formats.
Otherwise, attribAddress must be a multiple of the size in bytes of the
component type indicated by format (see Formats).
For attributes that are not 64-bit data types, each component is converted
to the format of the input variable based on its type and size (as defined
in the Format Definition section for each
VkFormat), using the appropriate equations in 16-Bit Floating-Point Numbers, Unsigned 11-Bit
Floating-Point Numbers, Unsigned 10-Bit Floating-Point
Numbers, Fixed-Point Data Conversion, and
Shared Exponent to RGB.
Signed integer components smaller than 32 bits are sign-extended.
Attributes that are not 64-bit data types are expanded to four components in
the same way as described in conversion to
RGBA.
The number of components in the vertex shader input variable need not
exactly match the number of components in the format.
If the vertex shader has fewer components, the extra components are
discarded.
23. Tessellation
Tessellation involves three pipeline stages. First, a tessellation control shader transforms control points of a patch and can produce per-patch data. Second, a fixed-function tessellator generates multiple primitives corresponding to a tessellation of the patch in (u,v) or (u,v,w) parameter space. Third, a tessellation evaluation shader transforms the vertices of the tessellated patch, for example to compute their positions and attributes as part of the tessellated surface. The tessellator is enabled when the pipeline contains both a tessellation control shader and a tessellation evaluation shader.
23.1. Tessellator
If a pipeline includes both tessellation shaders (control and evaluation),
the tessellator consumes each input patch (after vertex shading) and
produces a new set of independent primitives (points, lines, or triangles).
These primitives are logically produced by subdividing a geometric primitive
(rectangle or triangle) according to the per-patch outer and inner
tessellation levels written by the tessellation control shader.
These levels are specified using the built-in
variables TessLevelOuter and TessLevelInner, respectively.
This subdivision is performed in an implementation-dependent manner.
If no tessellation shaders are present in the pipeline, the tessellator is
disabled and incoming primitives are passed through without modification.
The type of subdivision performed by the tessellator is specified by an
OpExecutionMode instruction in the tessellation evaluation or
tessellation control shader using one of execution modes Triangles,
Quads, and IsoLines.
Other tessellation-related execution modes can also be specified in either
the tessellation control or tessellation evaluation shaders, and if they are
specified in both then the modes must be the same.
Tessellation execution modes include:
-
Triangles,Quads, andIsoLines. These control the type of subdivision and topology of the output primitives. One mode must be set in at least one of the tessellation shader stages. If theVK_KHR_portability_subsetextension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::tessellationIsolinesisVK_FALSE, then isoline tessellation is not supported by the implementation, andIsoLinesmust not be used in either tessellation shader stage. -
VertexOrderCwandVertexOrderCcw. These control the orientation of triangles generated by the tessellator. One mode must be set in at least one of the tessellation shader stages. -
PointMode. Controls generation of points rather than triangles or lines. This functionality defaults to disabled, and is enabled if either shader stage includes the execution mode. If theVK_KHR_portability_subsetextension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::tessellationPointModeisVK_FALSE, then point mode tessellation is not supported by the implementation, andPointModemust not be used in either tessellation shader stage. -
SpacingEqual,SpacingFractionalEven, andSpacingFractionalOdd. Controls the spacing of segments on the edges of tessellated primitives. One mode must be set in at least one of the tessellation shader stages. -
OutputVertices. Controls the size of the output patch of the tessellation control shader. One value must be set in at least one of the tessellation shader stages.
For triangles, the tessellator subdivides a triangle primitive into smaller
triangles.
For quads, the tessellator subdivides a rectangle primitive into smaller
triangles.
For isolines, the tessellator subdivides a rectangle primitive into a
collection of line segments arranged in strips stretching across the
rectangle in the u dimension (i.e. the coordinates in TessCoord
are of the form (0,x) through (1,x) for all tessellation evaluation shader
invocations that share a line).
Each vertex produced by the tessellator has an associated (u,v,w) or (u,v)
position in a normalized parameter space, with parameter values in the range
[0,1], as illustrated
in figures Domain parameterization for tessellation primitive modes (upper-left origin) and
Domain parameterization for tessellation primitive modes (lower-left origin).
The domain space can have either an upper-left or lower-left origin,
selected by the domainOrigin member of
VkPipelineTessellationDomainOriginStateCreateInfo.
For triangles, the vertex’s position is a barycentric coordinate (u,v,w), where u + v + w = 1.0, and indicates the relative influence of the three vertices of the triangle on the position of the vertex. For quads and isolines, the position is a (u,v) coordinate indicating the relative horizontal and vertical position of the vertex relative to the subdivided rectangle. The subdivision process is explained in more detail in subsequent sections.
23.2. Tessellator Patch Discard
A patch is discarded by the tessellator if any relevant outer tessellation level is less than or equal to zero.
Patches will also be discarded if any relevant outer tessellation level corresponds to a floating-point NaN (not a number) in implementations supporting NaN.
No new primitives are generated and the tessellation evaluation shader is
not executed for patches that are discarded.
For Quads, all four outer levels are relevant.
For Triangles and IsoLines, only the first three or two outer
levels, respectively, are relevant.
Negative inner levels will not cause a patch to be discarded; they will be
clamped as described below.
23.3. Tessellator Spacing
Each of the tessellation levels is used to determine the number and spacing
of segments used to subdivide a corresponding edge.
The method used to derive the number and spacing of segments is specified by
an OpExecutionMode in the tessellation control or tessellation
evaluation shader using one of the identifiers SpacingEqual,
SpacingFractionalEven, or SpacingFractionalOdd.
If SpacingEqual is used, the floating-point tessellation level is first
clamped to [1, maxLevel], where maxLevel is the
implementation-dependent maximum tessellation level
(VkPhysicalDeviceLimits::maxTessellationGenerationLevel).
The result is rounded up to the nearest integer n, and the
corresponding edge is divided into n segments of equal length in (u,v)
space.
If SpacingFractionalEven is used, the tessellation level is first
clamped to [2, maxLevel] and then rounded up to the nearest even
integer n.
If SpacingFractionalOdd is used, the tessellation level is clamped to
[1, maxLevel - 1] and then rounded up to the nearest odd integer
n.
If n is one, the edge will not be subdivided.
Otherwise, the corresponding edge will be divided into n - 2 segments
of equal length, and two additional segments of equal length that are
typically shorter than the other segments.
The length of the two additional segments relative to the others will
decrease monotonically with n - f, where f is the clamped
floating-point tessellation level.
When n - f is zero, the additional segments will have equal length to
the other segments.
As n - f approaches 2.0, the relative length of the additional
segments approaches zero.
The two additional segments must be placed symmetrically on opposite sides
of the subdivided edge.
The relative location of these two segments is implementation-dependent, but
must be identical for any pair of subdivided edges with identical values of
f.
When tessellating triangles or quads using point mode with fractional odd spacing, the tessellator may produce interior vertices that are positioned on the edge of the patch if an inner tessellation level is less than or equal to one. Such vertices are considered distinct from vertices produced by subdividing the outer edge of the patch, even if there are pairs of vertices with identical coordinates.
23.4. Tessellation Primitive Ordering
Few guarantees are provided for the relative ordering of primitives produced by tessellation, as they pertain to primitive order.
-
The output primitives generated from each input primitive are passed to subsequent pipeline stages in an implementation-dependent order.
-
All output primitives generated from a given input primitive are passed to subsequent pipeline stages before any output primitives generated from subsequent input primitives.
23.5. Tessellator Vertex Winding Order
When the tessellator produces triangles (in the Triangles or Quads
modes), the orientation of all triangles is specified with an
OpExecutionMode of VertexOrderCw or VertexOrderCcw in the
tessellation control or tessellation evaluation shaders.
If the order is VertexOrderCw, the vertices of all generated triangles
will have clockwise ordering in (u,v) or (u,v,w) space.
If the order is VertexOrderCcw, the vertices will have
counter-clockwise ordering in that space.
If the tessellation domain has an upper-left origin, the vertices of a triangle have counter-clockwise ordering if
-
a = u0 v1 - u1 v0 + u1 v2 - u2 v1 + u2 v0 - u0 v2
is negative, and clockwise ordering if a is positive. ui and vi are the u and v coordinates in normalized parameter space of the ith vertex of the triangle. If the tessellation domain has a lower-left origin, the vertices of a triangle have counter-clockwise ordering if a is positive, and clockwise ordering if a is negative.
|
Note
The value a is proportional (with a positive factor) to the signed area of the triangle. In |
23.6. Triangle Tessellation
If the tessellation primitive mode is Triangles, an equilateral
triangle is subdivided into a collection of triangles covering the area of
the original triangle.
First, the original triangle is subdivided into a collection of concentric
equilateral triangles.
The edges of each of these triangles are subdivided, and the area between
each triangle pair is filled by triangles produced by joining the vertices
on the subdivided edges.
The number of concentric triangles and the number of subdivisions along each
triangle except the outermost is derived from the first inner tessellation
level.
The edges of the outermost triangle are subdivided independently, using the
first, second, and third outer tessellation levels to control the number of
subdivisions of the u = 0 (left), v = 0 (bottom), and w =
0 (right) edges, respectively.
The second inner tessellation level and the fourth outer tessellation level
have no effect in this mode.
If the first inner tessellation level and all three outer tessellation levels are exactly one after clamping and rounding, only a single triangle with (u,v,w) coordinates of (0,0,1), (1,0,0), and (0,1,0) is generated. If the inner tessellation level is one and any of the outer tessellation levels is greater than one, the inner tessellation level is treated as though it were originally specified as 1 + ε and will result in a two- or three-segment subdivision depending on the tessellation spacing. When used with fractional odd spacing, the three-segment subdivision may produce inner vertices positioned on the edge of the triangle.
If any tessellation level is greater than one, tessellation begins by producing a set of concentric inner triangles and subdividing their edges. First, the three outer edges are temporarily subdivided using the clamped and rounded first inner tessellation level and the specified tessellation spacing, generating n segments. For the outermost inner triangle, the inner triangle is degenerate — a single point at the center of the triangle — if n is two. Otherwise, for each corner of the outer triangle, an inner triangle corner is produced at the intersection of two lines extended perpendicular to the corner’s two adjacent edges running through the vertex of the subdivided outer edge nearest that corner. If n is three, the edges of the inner triangle are not subdivided and it is the final triangle in the set of concentric triangles. Otherwise, each edge of the inner triangle is divided into n - 2 segments, with the n - 1 vertices of this subdivision produced by intersecting the inner edge with lines perpendicular to the edge running through the n - 1 innermost vertices of the subdivision of the outer edge. Once the outermost inner triangle is subdivided, the previous subdivision process repeats itself, using the generated triangle as an outer triangle. This subdivision process is illustrated in Inner Triangle Tessellation.
Once all the concentric triangles are produced and their edges are subdivided, the area between each pair of adjacent inner triangles is filled completely with a set of non-overlapping triangles. In this subdivision, two of the three vertices of each triangle are taken from adjacent vertices on a subdivided edge of one triangle; the third is one of the vertices on the corresponding edge of the other triangle. If the innermost triangle is degenerate (i.e., a point), the triangle containing it is subdivided into six triangles by connecting each of the six vertices on that triangle with the center point. If the innermost triangle is not degenerate, that triangle is added to the set of generated triangles as-is.
After the area corresponding to any inner triangles is filled, the tessellator generates triangles to cover the area between the outermost triangle and the outermost inner triangle. To do this, the temporary subdivision of the outer triangle edge above is discarded. Instead, the u = 0, v = 0, and w = 0 edges are subdivided according to the first, second, and third outer tessellation levels, respectively, and the tessellation spacing. The original subdivision of the first inner triangle is retained. The area between the outer and first inner triangles is completely filled by non-overlapping triangles as described above. If the first (and only) inner triangle is degenerate, a set of triangles is produced by connecting each vertex on the outer triangle edges with the center point.
After all triangles are generated, each vertex in the subdivided triangle is assigned a barycentric (u,v,w) coordinate based on its location relative to the three vertices of the outer triangle.
The algorithm used to subdivide the triangular domain in (u,v,w) space into individual triangles is implementation-dependent. However, the set of triangles produced will completely cover the domain, and no portion of the domain will be covered by multiple triangles.
Output triangles are generated with a topology similar to triangle lists, except that the order in which each triangle is generated, and the order in which the vertices are generated for each triangle, are implementation-dependent. However, the order of vertices in each triangle is consistent across the domain as described in Tessellator Vertex Winding Order.
23.7. Quad Tessellation
If the tessellation primitive mode is Quads, a rectangle is subdivided
into a collection of triangles covering the area of the original rectangle.
First, the original rectangle is subdivided into a regular mesh of
rectangles, where the number of rectangles along the u = 0 and u
= 1 (vertical) and v = 0 and v = 1 (horizontal) edges are
derived from the first and second inner tessellation levels, respectively.
All rectangles, except those adjacent to one of the outer rectangle edges,
are decomposed into triangle pairs.
The outermost rectangle edges are subdivided independently, using the first,
second, third, and fourth outer tessellation levels to control the number of
subdivisions of the u = 0 (left), v = 0 (bottom), u = 1
(right), and v = 1 (top) edges, respectively.
The area between the inner rectangles of the mesh and the outer rectangle
edges are filled by triangles produced by joining the vertices on the
subdivided outer edges to the vertices on the edge of the inner rectangle
mesh.
If both clamped inner tessellation levels and all four clamped outer tessellation levels are exactly one, only a single triangle pair covering the outer rectangle is generated. Otherwise, if either clamped inner tessellation level is one, that tessellation level is treated as though it was originally specified as 1 + ε and will result in a two- or three-segment subdivision depending on the tessellation spacing. When used with fractional odd spacing, the three-segment subdivision may produce inner vertices positioned on the edge of the rectangle.
If any tessellation level is greater than one, tessellation begins by subdividing the u = 0 and u = 1 edges of the outer rectangle into m segments using the clamped and rounded first inner tessellation level and the tessellation spacing. The v = 0 and v = 1 edges are subdivided into n segments using the second inner tessellation level. Each vertex on the u = 0 and v = 0 edges are joined with the corresponding vertex on the u = 1 and v = 1 edges to produce a set of vertical and horizontal lines that divide the rectangle into a grid of smaller rectangles. The primitive generator emits a pair of non-overlapping triangles covering each such rectangle not adjacent to an edge of the outer rectangle. The boundary of the region covered by these triangles forms an inner rectangle, the edges of which are subdivided by the grid vertices that lie on the edge. If either m or n is two, the inner rectangle is degenerate, and one or both of the rectangle’s edges consist of a single point. This subdivision is illustrated in Figure Inner Quad Tessellation.
After the area corresponding to the inner rectangle is filled, the tessellator must produce triangles to cover the area between the inner and outer rectangles. To do this, the subdivision of the outer rectangle edge above is discarded. Instead, the u = 0, v = 0, u = 1, and v = 1 edges are subdivided according to the first, second, third, and fourth outer tessellation levels, respectively, and the tessellation spacing. The original subdivision of the inner rectangle is retained. The area between the outer and inner rectangles is completely filled by non-overlapping triangles. Two of the three vertices of each triangle are adjacent vertices on a subdivided edge of one rectangle; the third is one of the vertices on the corresponding edge of the other rectangle. If either edge of the innermost rectangle is degenerate, the area near the corresponding outer edges is filled by connecting each vertex on the outer edge with the single vertex making up the inner edge.
The algorithm used to subdivide the rectangular domain in (u,v) space into individual triangles is implementation-dependent. However, the set of triangles produced will completely cover the domain, and no portion of the domain will be covered by multiple triangles.
Output triangles are generated with a topology similar to triangle lists, except that the order in which each triangle is generated, and the order in which the vertices are generated for each triangle, are implementation-dependent. However, the order of vertices in each triangle is consistent across the domain as described in Tessellator Vertex Winding Order.
23.8. Isoline Tessellation
If the tessellation primitive mode is IsoLines, a set of independent
horizontal line segments is drawn.
The segments are arranged into connected strips called isolines, where the
vertices of each isoline have a constant v coordinate and u coordinates
covering the full range [0,1].
The number of isolines generated is derived from the first outer
tessellation level; the number of segments in each isoline is derived from
the second outer tessellation level.
Both inner tessellation levels and the third and fourth outer tessellation
levels have no effect in this mode.
As with quad tessellation above, isoline tessellation begins with a rectangle. The u = 0 and u = 1 edges of the rectangle are subdivided according to the first outer tessellation level. For the purposes of this subdivision, the tessellation spacing mode is ignored and treated as equal_spacing. An isoline is drawn connecting each vertex on the u = 0 rectangle edge to the corresponding vertex on the u = 1 rectangle edge, except that no line is drawn between (0,1) and (1,1). If the number of isolines on the subdivided u = 0 and u = 1 edges is n, this process will result in n equally spaced lines with constant v coordinates of 0, .
Each of the n isolines is then subdivided according to the second outer tessellation level and the tessellation spacing, resulting in m line segments. Each segment of each line is emitted by the tessellator. These line segments are generated with a topology similar to line lists, except that the order in which each line is generated, and the order in which the vertices are generated for each line segment, are implementation-dependent.
|
Note
If the |
23.9. Tessellation Point Mode
For all primitive modes, the tessellator is capable of generating points
instead of lines or triangles.
If the tessellation control or tessellation evaluation shader specifies the
OpExecutionMode PointMode, the primitive generator will generate
one point for each distinct vertex produced by tessellation, rather than
emitting triangles or lines.
Otherwise, the tessellator will produce a collection of line segments or
triangles according to the primitive mode.
These points are generated with a topology similar to point lists, except the order in which the points are generated for each
input primitive is undefined.
|
Note
If the |
23.10. Tessellation Pipeline State
The pTessellationState member of VkGraphicsPipelineCreateInfo is
a pointer to a VkPipelineTessellationStateCreateInfo structure.
The VkPipelineTessellationStateCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineTessellationStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineTessellationStateCreateFlags flags;
uint32_t patchControlPoints;
} VkPipelineTessellationStateCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
patchControlPointsis the number of control points per patch.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineTessellationStateCreateFlags;
VkPipelineTessellationStateCreateFlags is a bitmask type for setting a
mask, but is currently reserved for future use.
The VkPipelineTessellationDomainOriginStateCreateInfo structure is
defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPipelineTessellationDomainOriginStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkTessellationDomainOrigin domainOrigin;
} VkPipelineTessellationDomainOriginStateCreateInfo;
or the equivalent
// Provided by VK_KHR_maintenance2
typedef VkPipelineTessellationDomainOriginStateCreateInfo VkPipelineTessellationDomainOriginStateCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
domainOriginis a VkTessellationDomainOrigin value controlling the origin of the tessellation domain space.
If the VkPipelineTessellationDomainOriginStateCreateInfo structure is
included in the pNext chain of
VkPipelineTessellationStateCreateInfo, it controls the origin of the
tessellation domain.
If this structure is not present, it is as if domainOrigin was
VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT.
The possible tessellation domain origins are specified by the VkTessellationDomainOrigin enumeration:
// Provided by VK_VERSION_1_1
typedef enum VkTessellationDomainOrigin {
VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT = 0,
VK_TESSELLATION_DOMAIN_ORIGIN_LOWER_LEFT = 1,
// Provided by VK_KHR_maintenance2
VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT_KHR = VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT,
// Provided by VK_KHR_maintenance2
VK_TESSELLATION_DOMAIN_ORIGIN_LOWER_LEFT_KHR = VK_TESSELLATION_DOMAIN_ORIGIN_LOWER_LEFT,
} VkTessellationDomainOrigin;
or the equivalent
// Provided by VK_KHR_maintenance2
typedef VkTessellationDomainOrigin VkTessellationDomainOriginKHR;
-
VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFTspecifies that the origin of the domain space is in the upper left corner, as shown in figure Domain parameterization for tessellation primitive modes (upper-left origin). -
VK_TESSELLATION_DOMAIN_ORIGIN_LOWER_LEFTspecifies that the origin of the domain space is in the lower left corner, as shown in figure Domain parameterization for tessellation primitive modes (lower-left origin).
This enum affects how the VertexOrderCw and VertexOrderCcw
tessellation execution modes are interpreted, since the winding is defined
relative to the orientation of the domain.
24. Geometry Shading
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. Geometry shading is enabled when a geometry shader is included in the pipeline.
24.1. Geometry Shader Input Primitives
Each geometry shader invocation has access to all vertices in the primitive (and their associated data), which are presented to the shader as an array of inputs.
The input primitive type expected by the geometry shader is specified with
an OpExecutionMode instruction in the geometry shader, and must match
the incoming primitive type specified by either the pipeline’s
primitive topology if tessellation is
inactive, or the tessellation mode if tessellation is
active, as follows:
-
An input primitive type of
InputPointsmust only be used with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_POINT_LIST, or with a tessellation shader specifyingPointMode. The input arrays always contain one element, as described by the point list topology or tessellation in point mode. -
An input primitive type of
InputLinesmust only be used with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_LINE_LISTorVK_PRIMITIVE_TOPOLOGY_LINE_STRIP, or with a tessellation shader specifyingIsoLinesthat does not specifyPointMode. The input arrays always contain two elements, as described by the line list topology or line strip topology, or by isoline tessellation. -
An input primitive type of
InputLinesAdjacencymust only be used when tessellation is inactive, with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCYorVK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY. The input arrays always contain four elements, as described by the line list with adjacency topology or line strip with adjacency topology. -
An input primitive type of
Trianglesmust only be used with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, orVK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN; or with a tessellation shader specifyingQuadsorTrianglesthat does not specifyPointMode. The input arrays always contain three elements, as described by the triangle list topology, triangle strip topology, or triangle fan topology, or by triangle or quad tessellation. Vertices may be in a different absolute order than specified by the topology, but must adhere to the specified winding order. -
An input primitive type of
InputTrianglesAdjacencymust only be used when tessellation is inactive, with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCYorVK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY. The input arrays always contain six elements, as described by the triangle list with adjacency topology or triangle strip with adjacency topology. Vertices may be in a different absolute order than specified by the topology, but must adhere to the specified winding order, and the vertices making up the main primitive must still occur at the first, third, and fifth index.
24.2. Geometry Shader Output Primitives
A geometry shader generates primitives in one of three output modes: points,
line strips, or triangle strips.
The primitive mode is specified in the shader using an OpExecutionMode
instruction with the OutputPoints, OutputLineStrip or
OutputTriangleStrip modes, respectively.
Each geometry shader must include exactly one output primitive mode.
The vertices output by the geometry shader are assembled into points, lines, or triangles based on the output primitive type and the resulting primitives are then further processed as described in Rasterization. If the number of vertices emitted by the geometry shader is not sufficient to produce a single primitive, vertices corresponding to incomplete primitives are not processed by subsequent pipeline stages. The number of vertices output by the geometry shader is limited to a maximum count specified in the shader.
The maximum output vertex count is specified in the shader using an
OpExecutionMode instruction with the mode set to OutputVertices
and the maximum number of vertices that will be produced by the geometry
shader specified as a literal.
Each geometry shader must specify a maximum output vertex count.
24.3. Multiple Invocations of Geometry Shaders
Geometry shaders can be invoked more than one time for each input
primitive.
This is known as geometry shader instancing and is requested by including
an OpExecutionMode instruction with mode specified as
Invocations and the number of invocations specified as an integer
literal.
In this mode, the geometry shader will execute at least n times for
each input primitive, where n is the number of invocations specified
in the OpExecutionMode instruction.
The instance number is available to each invocation as a built-in input
using InvocationId.
24.4. Geometry Shader Primitive Ordering
Limited guarantees are provided for the relative ordering of primitives produced by a geometry shader, as they pertain to primitive order.
-
For instanced geometry shaders, the output primitives generated from each input primitive are passed to subsequent pipeline stages using the invocation number to order the primitives, from least to greatest.
-
All output primitives generated from a given input primitive are passed to subsequent pipeline stages before any output primitives generated from subsequent input primitives.
24.5. Geometry Shader Passthrough
A geometry shader that uses the PassthroughNV decoration on a variable
in its input interface is considered a passthrough geometry shader.
Output primitives in a passthrough geometry shader must have the same
topology as the input primitive and are not produced by emitting vertices.
The vertices of the output primitive have two different types of attributes,
per-vertex and per-primitive.
Geometry shader input variables with PassthroughNV decoration are
considered to produce per-vertex outputs, where values for each output
vertex are copied from the corresponding input vertex.
Any built-in or user-defined geometry shader outputs are considered
per-primitive in a passthrough geometry shader, where a single output value
is copied to all output vertices.
The remainder of this section details the usage of the PassthroughNV
decoration and modifications to the interface matching rules when using
passthrough geometry shaders.
24.5.1. PassthroughNV Decoration
Decorating a geometry shader input variable with the PassthroughNV
decoration indicates that values of this input are copied through to the
corresponding vertex of the output primitive.
Input variables and block members which do not have the PassthroughNV
decoration are consumed by the geometry shader without being passed through
to subsequent stages.
The PassthroughNV decoration must only be used within a geometry
shader.
Any variable decorated with PassthroughNV must be declared using the
Input storage class.
The PassthroughNV decoration must not be used with any of:
-
an input primitive type other than
InputPoints,InputLines, orTriangles, as specified by the mode forOpExecutionMode. -
an invocation count other than one, as specified by the
Invocationsmode forOpExecutionMode. -
an
OpEntryPointwhich statically uses theOpEmitVertexorOpEndPrimitiveinstructions. -
a variable decorated with the
InvocationIdbuilt-in decoration. -
a variable decorated with the
PrimitiveIdbuilt-in decoration that is declared using theInputstorage class.
24.5.2. Passthrough Interface Matching
When a passthrough geometry shader is in use, the Interface Matching rules involving the geometry shader input and output interfaces operate as described in this section.
For the purposes of matching passthrough geometry shader inputs with outputs
of the previous pipeline stages, the PassthroughNV decoration is
ignored.
For the purposes of matching the outputs of the geometry shader with
subsequent pipeline stages, each input variable with the PassthroughNV
decoration is considered to add an equivalent output variable with the same
type, decoration (other than PassthroughNV), number, and declaration
order on the output interface.
The output variable declaration corresponding to an input variable decorated
with PassthroughNV will be identical to the input declaration, except
that the outermost array dimension of such variables is removed.
The output block declaration corresponding to an input block decorated with
PassthroughNV or having members decorated with PassthroughNV will
be identical to the input declaration, except that the outermost array
dimension of such declaration is removed.
If an input block is decorated with PassthroughNV, the equivalent
output block contains all the members of the input block.
Otherwise, the equivalent output block contains only those input block
members decorated with PassthroughNV.
All members of the corresponding output block are assigned Location and
Component decorations identical to those assigned to the corresponding
input block members.
Output variables and blocks generated from inputs decorated with
PassthroughNV will only exist for the purposes of interface matching;
these declarations are not available to geometry shader code or listed in
the module interface.
For the purposes of component counting, passthrough geometry shaders count
all statically used input variable components declared with the
PassthroughNV decoration as output components as well, since their
values will be copied to the output primitive produced by the geometry
shader.
25. Mesh Shading
Task and mesh shaders operate in workgroups to produce a collection of primitives that will be processed by subsequent stages of the graphics pipeline.
Work on the mesh pipeline is initiated by the application drawing a set of mesh tasks organized in global workgroups. If the optional task shader is active, each workgroup triggers the execution of task shader invocations that will create a new set of mesh workgroups upon completion. Each of these created workgroups, or each of the original workgroups if no task shader is present, triggers the execution of mesh shader invocations.
Each mesh shader workgroup emits zero or more output primitives along with the group of vertices and their associated data required for each output primitive.
25.1. Task Shader Input
For every workgroup issued via the drawing commands a group of task shader invocations is executed. There are no inputs other than the builtin workgroup identifiers.
25.2. Task Shader Output
The task shader can emit zero or more mesh workgroups to be generated using
the built-in variable TaskCountNV.
This value must be less than or equal to
VkPhysicalDeviceMeshShaderPropertiesNV::maxTaskOutputCount.
It can also output user-defined data that is passed as input to all mesh
shader invocations that the task creates.
These outputs are decorated as PerTaskNV.
25.3. Mesh Generation
If a task shader exists, the mesh assembler creates a variable amount of mesh workgroups depending on each task’s output. If there is no task shader, the drawing commands emit the mesh shader invocations directly.
25.4. Mesh Shader Input
The only inputs available to the mesh shader are variables identifying the
specific workgroup and invocation and, if applicable, any outputs written as
PerTaskNV by the task shader that spawned the mesh shader’s workgroup.
The mesh shader can operate without a task shader as well.
25.5. Mesh Shader Output Primitives
A mesh shader generates primitives in one of three output modes: points,
lines, or triangles.
The primitive mode is specified in the shader using an OpExecutionMode
instruction with the OutputPoints, OutputLinesNV, or
OutputTrianglesNV modes, respectively.
Each mesh shader must include exactly one output primitive mode.
The maximum output vertex count is specified as a literal in the shader
using an OpExecutionMode instruction with the mode set to
OutputVertices and must be less than or equal to
VkPhysicalDeviceMeshShaderPropertiesNV::maxMeshOutputVertices.
The maximum output primitive count is specified as a literal in the shader
using an OpExecutionMode instruction with the mode set to
OutputPrimitivesNV and must be less than or equal to
VkPhysicalDeviceMeshShaderPropertiesNV::maxMeshOutputPrimitives.
The number of primitives output by the mesh shader is provided via writing
to the built-in variable
PrimitiveCountNV and must be less than or equal to the maximum output
primitive count specified in the shader.
A variable decorated with PrimitiveIndicesNV is an output array of
local index values into the vertex output arrays from which primitives are
assembled according to the output primitive type.
These resulting primitives are then further processed as described in
Rasterization.
25.6. Mesh Shader Per-View Outputs
The mesh shader outputs decorated with the PositionPerViewNV,
ClipDistancePerViewNV, CullDistancePerViewNV, LayerPerViewNV,
and ViewportMaskPerViewNV built-in decorations are the per-view
versions of the single-view variables with equivalent names (that is
Position, ClipDistance, CullDistance, Layer, and
ViewportMaskNV, respectively).
If a shader statically assigns a value to any element of a per-view array it
must not statically assign a value to the equivalent single-view variable.
Each of these outputs is considered arrayed, with separate values for each view. The view number is used to index the first dimension of these arrays.
The second dimension of the ClipDistancePerViewNV, and
CullDistancePerViewNV arrays have the same requirements as the
ClipDistance, and CullDistance arrays.
If a mesh shader output is per-view, the corresponding fragment shader input is taken from the element of the per-view output array that corresponds to the view that is currently being processed by the fragment shader.
25.7. Mesh Shader Primitive Ordering
Following guarantees are provided for the relative ordering of primitives produced by a mesh shader, as they pertain to primitive order.
-
When a task shader is used, mesh workgroups spawned from lower tasks will be ordered prior those workgroups from subsequent tasks.
-
All output primitives generated from a given mesh workgroup are passed to subsequent pipeline stages before any output primitives generated from subsequent input workgroups.
-
All output primitives within a mesh workgroup, will be generated in the ordering provided by the builtin primitive indexbuffer (from low address to high address).
26. Fixed-Function Vertex Post-Processing
After pre-rasterization shader stages, the following fixed-function operations are applied to vertices of the resulting primitives:
-
Transform feedback (see Transform Feedback)
-
Viewport swizzle (see Viewport Swizzle)
-
Flat shading (see Flat Shading).
-
Primitive clipping, including client-defined half-spaces (see Primitive Clipping).
-
Shader output attribute clipping (see Clipping Shader Outputs).
-
Clip space W scaling (see Controlling Viewport W Scaling).
-
Perspective division on clip coordinates (see Coordinate Transformations).
-
Viewport mapping, including depth range scaling (see Controlling the Viewport).
-
Front face determination for polygon primitives (see Basic Polygon Rasterization).
|
editing-note
TODO:Odd that this one link to a different chapter is in this list. |
Next, rasterization is performed on primitives as described in chapter Rasterization.
26.1. Transform Feedback
Before any other fixed-function vertex post-processing, vertex outputs from
the last shader in the
pre-rasterization shader
stage can be written out to one or more transform feedback buffers bound
to the command buffer.
To capture vertex outputs the last
pre-rasterization shader
stage shader must be declared with the Xfb execution mode.
Outputs decorated with XfbBuffer will be written out to the
corresponding transform feedback buffers bound to the command buffer when
transform feedback is active.
Transform feedback buffers are bound to the command buffer by using
vkCmdBindTransformFeedbackBuffersEXT.
Transform feedback is made active by calling
vkCmdBeginTransformFeedbackEXT and made inactive by calling
vkCmdEndTransformFeedbackEXT.
After vertex data is written it is possible to use
vkCmdDrawIndirectByteCountEXT to start a new draw where the
vertexCount is derived from the number of bytes written by a previous
transform feedback.
When an individual point, line, or triangle primitive reaches the transform
feedback stage while transform feedback is active, the values of the
specified output variables are assembled into primitives and appended to the
bound transform feedback buffers.
After activating transform feedback, the values of the first assembled
primitive are written at the starting offsets of the bound transform
feedback buffers, and subsequent primitives are appended to the buffer.
If the optional pCounterBuffers and pCounterBufferOffsets
parameters are specified, the starting points within the transform feedback
buffers are adjusted so data is appended to the previously written values
indicated by the value stored by the implementation in the counter buffer.
For multi-vertex primitives, all values for a given vertex are written
before writing values for any other vertex.
When transformFeedbackPreservesProvokingVertex is not enabled,
implementations
may write out any vertex within the primitive first, but all subsequent
vertices for that primitive must be written out in a consistent winding
order defined as follows:
-
If neither geometry or tessellation shading is active, vertices within a primitive are appended according to the winding order described by the primitive topology defined by the VkPipelineInputAssemblyStateCreateInfo:
topologyused to execute the drawing command. -
If geometry shading is active, vertices within a primitive are appended according to the winding order described by the primitive topology defined by the
OutputPoints,OutputLineStrips, orOutputTriangleStripsexecution mode. -
If tessellation shading is active but geometry shading is not, vertices within a primitive are appended according to the winding order defined by triangle tessellation, quad tessellation, and isoline tessellation.
When transformFeedbackPreservesProvokingVertex is enabled, then in
addition to writing vertices with a consistent winding order, the vertex
order must preserve the provoking vertex of
each primitive:
-
When the pipeline’s provoking vertex mode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT, the primitive’s provoking vertex must be the first vertex written. -
When the pipeline’s provoking vertex mode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the primitive’s provoking vertex must be the last vertex written.
If transformFeedbackPreservesTriangleFanProvokingVertex is
VK_FALSE, neither geometry nor tessellation shading is active, and the primitive topology is VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN, then the
first vertex written from each primitive is implementation-defined even when
transformFeedbackPreservesProvokingVertex is enabled.
When capturing vertices, the stride associated with each transform feedback
buffer, as indicated by the XfbStride decoration, indicates the number
of bytes of storage reserved for each vertex in the transform feedback
buffer.
For every vertex captured, each output attribute with a Offset
decoration will be written to the storage reserved for the vertex at the
associated transform feedback buffer.
When writing output variables that are arrays or structures, individual
array elements or structure members are written tightly packed in order.
For vector types, individual components are written in order.
For matrix types, outputs are written as an array of column vectors.
If any component of an output with an assigned transform feedback offset was not written to by its shader, the value recorded for that component is undefined. All components of an output variable must be written at an offset aligned to the size of the component. The size of each component of an output variable must be at least 32-bits. When capturing a vertex, any portion of the reserved storage not associated with an output variable with an assigned transform feedback offset will be unmodified.
When transform feedback is inactive, no vertices are recorded.
If there is a valid counter buffer handle and counter buffer offset in the
pCounterBuffers and pCounterBufferOffsets arrays, writes to the
corresponding transform feedback buffer will start at the byte offset
represented by the value stored in the counter buffer location.
Individual lines or triangles of a strip or fan primitive will be extracted and recorded separately. Incomplete primitives are not recorded.
When using a geometry shader that emits vertices to multiple vertex streams, a primitive will be assembled and output for each stream when there are enough vertices emitted for the output primitive type. All outputs assigned to a given transform feedback buffer are required to come from a single vertex stream.
The sizes of the transform feedback buffers are defined by the
vkCmdBindTransformFeedbackBuffersEXT pSizes parameter for each
of the bound buffers, or the size of the bound buffer, whichever is the
lesser.
If there is less space remaining in any of the transform feedback buffers
than the size of all of the vertex data for that primitive based on the
XfbStride for that XfbBuffer then no vertex data of that primitive
is recorded in any transform feedback buffer, and the value for the number
of primitives written in the corresponding
VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT query for all transform
feedback buffers is no longer incremented.
Any outputs made to a XfbBuffer that is not bound to a transform
feedback buffer is ignored.
To bind transform feedback buffers to a command buffer for use in subsequent drawing commands, call:
// Provided by VK_EXT_transform_feedback
void vkCmdBindTransformFeedbackBuffersEXT(
VkCommandBuffer commandBuffer,
uint32_t firstBinding,
uint32_t bindingCount,
const VkBuffer* pBuffers,
const VkDeviceSize* pOffsets,
const VkDeviceSize* pSizes);
-
commandBufferis the command buffer into which the command is recorded. -
firstBindingis the index of the first transform feedback binding whose state is updated by the command. -
bindingCountis the number of transform feedback bindings whose state is updated by the command. -
pBuffersis a pointer to an array of buffer handles. -
pOffsetsis a pointer to an array of buffer offsets. -
pSizesisNULLor a pointer to an array ofVkDeviceSizebuffer sizes, specifying the maximum number of bytes to capture to the corresponding transform feedback buffer. IfpSizesisNULL, or the value of thepSizesarray element isVK_WHOLE_SIZE, then the maximum number of bytes captured will be the size of the corresponding buffer minus the buffer offset.
The values taken from elements i of pBuffers, pOffsets and
pSizes replace the current state for the transform feedback binding
firstBinding + i, for i in [0,
bindingCount).
The transform feedback binding is updated to start at the offset indicated
by pOffsets[i] from the start of the buffer pBuffers[i].
Transform feedback for specific transform feedback buffers is made active by calling:
// Provided by VK_EXT_transform_feedback
void vkCmdBeginTransformFeedbackEXT(
VkCommandBuffer commandBuffer,
uint32_t firstCounterBuffer,
uint32_t counterBufferCount,
const VkBuffer* pCounterBuffers,
const VkDeviceSize* pCounterBufferOffsets);
-
commandBufferis the command buffer into which the command is recorded. -
firstCounterBufferis the index of the first transform feedback buffer corresponding topCounterBuffers[0] andpCounterBufferOffsets[0]. -
counterBufferCountis the size of thepCounterBuffersandpCounterBufferOffsetsarrays. -
pCounterBuffersisNULLor a pointer to an array of VkBuffer handles to counter buffers. Each buffer contains a 4 byte integer value representing the byte offset from the start of the corresponding transform feedback buffer from where to start capturing vertex data. If the byte offset stored to the counter buffer location was done using vkCmdEndTransformFeedbackEXT it can be used to resume transform feedback from the previous location. IfpCounterBuffersisNULL, then transform feedback will start capturing vertex data to byte offset zero in all bound transform feedback buffers. For each element ofpCounterBuffersthat is VK_NULL_HANDLE, transform feedback will start capturing vertex data to byte zero in the corresponding bound transform feedback buffer. -
pCounterBufferOffsetsisNULLor a pointer to an array ofVkDeviceSizevalues specifying offsets within each of thepCounterBufferswhere the counter values were previously written. The location in each counter buffer at these offsets must be large enough to contain 4 bytes of data. This data is the number of bytes captured by the previous transform feedback to this buffer. IfpCounterBufferOffsetsisNULL, then it is assumed the offsets are zero.
The active transform feedback buffers will capture primitives emitted from
the corresponding XfbBuffer in the bound graphics pipeline.
Any XfbBuffer emitted that does not output to an active transform
feedback buffer will not be captured.
Transform feedback for specific transform feedback buffers is made inactive by calling:
// Provided by VK_EXT_transform_feedback
void vkCmdEndTransformFeedbackEXT(
VkCommandBuffer commandBuffer,
uint32_t firstCounterBuffer,
uint32_t counterBufferCount,
const VkBuffer* pCounterBuffers,
const VkDeviceSize* pCounterBufferOffsets);
-
commandBufferis the command buffer into which the command is recorded. -
firstCounterBufferis the index of the first transform feedback buffer corresponding topCounterBuffers[0] andpCounterBufferOffsets[0]. -
counterBufferCountis the size of thepCounterBuffersandpCounterBufferOffsetsarrays. -
pCounterBuffersisNULLor a pointer to an array of VkBuffer handles to counter buffers. The counter buffers are used to record the current byte positions of each transform feedback buffer where the next vertex output data would be captured. This can be used by a subsequent vkCmdBeginTransformFeedbackEXT call to resume transform feedback capture from this position. It can also be used by vkCmdDrawIndirectByteCountEXT to determine the vertex count of the draw call. -
pCounterBufferOffsetsisNULLor a pointer to an array ofVkDeviceSizevalues specifying offsets within each of thepCounterBufferswhere the counter values can be written. The location in each counter buffer at these offsets must be large enough to contain 4 bytes of data. The data stored at this location is the byte offset from the start of the transform feedback buffer binding where the next vertex data would be written. IfpCounterBufferOffsetsisNULL, then it is assumed the offsets are zero.
26.2. Viewport Swizzle
Each primitive sent to a given viewport has a swizzle and optional negation
applied to its clip coordinates.
The swizzle that is applied depends on the viewport index, and is controlled
by the VkPipelineViewportSwizzleStateCreateInfoNV pipeline state:
// Provided by VK_NV_viewport_swizzle
typedef struct VkPipelineViewportSwizzleStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkPipelineViewportSwizzleStateCreateFlagsNV flags;
uint32_t viewportCount;
const VkViewportSwizzleNV* pViewportSwizzles;
} VkPipelineViewportSwizzleStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
viewportCountis the number of viewport swizzles used by the pipeline. -
pViewportSwizzlesis a pointer to an array of VkViewportSwizzleNV structures, defining the viewport swizzles.
// Provided by VK_NV_viewport_swizzle
typedef VkFlags VkPipelineViewportSwizzleStateCreateFlagsNV;
VkPipelineViewportSwizzleStateCreateFlagsNV is a bitmask type for
setting a mask, but is currently reserved for future use.
The VkPipelineViewportSwizzleStateCreateInfoNV state is set by adding
this structure to the pNext chain of a
VkPipelineViewportStateCreateInfo structure and setting the graphics
pipeline state with vkCreateGraphicsPipelines.
Each viewport specified from 0 to viewportCount - 1 has its x,y,z,w
swizzle state set to the corresponding x, y, z and w
in the VkViewportSwizzleNV structure.
Each component is of type VkViewportCoordinateSwizzleNV, which
determines the type of swizzle for that component.
The value of x computes the new x component of the position as:
if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_X_NV) x' = x;
if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_X_NV) x' = -x;
if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Y_NV) x' = y;
if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_Y_NV) x' = -y;
if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Z_NV) x' = z;
if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_Z_NV) x' = -z;
if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_W_NV) x' = w;
if (x == VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_W_NV) x' = -w;
Similar selections are performed for the y, z, and w
coordinates.
This swizzling is applied before clipping and perspective divide.
If the swizzle for an active viewport index is not specified, the swizzle
for x is VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_X_NV, y
is VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Y_NV, z is
VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Z_NV and w is
VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_W_NV.
Viewport swizzle parameters are specified by setting the pNext pointer
of VkGraphicsPipelineCreateInfo to point to a
VkPipelineViewportSwizzleStateCreateInfoNV structure.
VkPipelineViewportSwizzleStateCreateInfoNV uses
VkViewportSwizzleNV to set the viewport swizzle parameters.
The VkViewportSwizzleNV structure is defined as:
// Provided by VK_NV_viewport_swizzle
typedef struct VkViewportSwizzleNV {
VkViewportCoordinateSwizzleNV x;
VkViewportCoordinateSwizzleNV y;
VkViewportCoordinateSwizzleNV z;
VkViewportCoordinateSwizzleNV w;
} VkViewportSwizzleNV;
-
xis a VkViewportCoordinateSwizzleNV value specifying the swizzle operation to apply to the x component of the primitive -
yis a VkViewportCoordinateSwizzleNV value specifying the swizzle operation to apply to the y component of the primitive -
zis a VkViewportCoordinateSwizzleNV value specifying the swizzle operation to apply to the z component of the primitive -
wis a VkViewportCoordinateSwizzleNV value specifying the swizzle operation to apply to the w component of the primitive
Possible values of the VkViewportSwizzleNV::x, y, z,
and w members, specifying swizzling of the corresponding components of
primitives, are:
// Provided by VK_NV_viewport_swizzle
typedef enum VkViewportCoordinateSwizzleNV {
VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_X_NV = 0,
VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_X_NV = 1,
VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Y_NV = 2,
VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_Y_NV = 3,
VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_Z_NV = 4,
VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_Z_NV = 5,
VK_VIEWPORT_COORDINATE_SWIZZLE_POSITIVE_W_NV = 6,
VK_VIEWPORT_COORDINATE_SWIZZLE_NEGATIVE_W_NV = 7,
} VkViewportCoordinateSwizzleNV;
These values are described in detail in Viewport Swizzle.
26.3. Flat Shading
Flat shading a vertex output attribute means to assign all vertices of the
primitive the same value for that output.
The output values assigned are those of the provoking vertex of the
primitive.
Flat shading is applied to those vertex attributes that
match fragment input attributes which
are decorated as Flat.
If neither geometry nor tessellation shading
is active, the provoking vertex is determined by the
primitive topology defined by
VkPipelineInputAssemblyStateCreateInfo:topology used to execute
the drawing command.
If geometry shading is active, the provoking vertex is
determined by the primitive topology
defined by the OutputPoints,
OutputLineStrips, or
OutputTriangleStrips execution mode.
If tessellation shading is active but geometry shading is not, the provoking vertex may be any of the vertices in each primitive.
For a given primitive topology, the pipeline’s provoking vertex mode
determines which vertex is the provoking vertex.
To specify the provoking vertex mode, include a
VkPipelineRasterizationProvokingVertexStateCreateInfoEXT structure in
the VkPipelineRasterizationStateCreateInfo::pNext chain when
creating the pipeline.
The VkPipelineRasterizationProvokingVertexStateCreateInfoEXT structure
is defined as:
// Provided by VK_EXT_provoking_vertex
typedef struct VkPipelineRasterizationProvokingVertexStateCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkProvokingVertexModeEXT provokingVertexMode;
} VkPipelineRasterizationProvokingVertexStateCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
provokingVertexModeis a VkProvokingVertexModeEXT value selecting the provoking vertex mode.
If this struct is not provided when creating the pipeline, the pipeline will
use the VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT mode.
If the provokingVertexModePerPipeline limit is VK_FALSE, then all
pipelines bound within a render pass instance must have the same
provokingVertexMode.
Possible values of
VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::provokingVertexMode
are:
// Provided by VK_EXT_provoking_vertex
typedef enum VkProvokingVertexModeEXT {
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT = 0,
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT = 1,
} VkProvokingVertexModeEXT;
-
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXTspecifies that the provoking vertex is the first non-adjacency vertex in the list of vertices used by a primitive. -
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXTspecifies that the provoking vertex is the last non-adjacency vertex in the list of vertices used by a primitive.
These modes are described more precisely in Primitive Topologies.
26.4. Primitive Clipping
Primitives are culled against the cull volume and then clipped to the clip volume. In clip coordinates, the view volume is defined by:
where
if
VkPipelineViewportDepthClipControlCreateInfoEXT::negativeOneToOne
is VK_TRUE zm is equal to -wc otherwise
zm is equal to zero.
This view volume can be further restricted by as many as
VkPhysicalDeviceLimits::maxClipDistances client-defined
half-spaces.
The cull volume is the intersection of up to
VkPhysicalDeviceLimits::maxCullDistances client-defined
half-spaces (if no client-defined cull half-spaces are enabled, culling
against the cull volume is skipped).
A shader must write a single cull distance for each enabled cull half-space
to elements of the CullDistance array.
If the cull distance for any enabled cull half-space is negative for all of
the vertices of the primitive under consideration, the primitive is
discarded.
Otherwise the primitive is clipped against the clip volume as defined below.
The clip volume is the intersection of up to
VkPhysicalDeviceLimits::maxClipDistances client-defined
half-spaces with the view volume (if no client-defined clip half-spaces are
enabled, the clip volume is the view volume).
A shader must write a single clip distance for each enabled clip half-space
to elements of the ClipDistance array.
Clip half-space i is then given by the set of points satisfying the
inequality
-
ci(P) ≥ 0
where ci(P) is the clip distance i at point P. For point primitives, ci(P) is simply the clip distance for the vertex in question. For line and triangle primitives, per-vertex clip distances are interpolated using a weighted mean, with weights derived according to the algorithms described in sections Basic Line Segment Rasterization and Basic Polygon Rasterization, using the perspective interpolation equations.
The number of client-defined clip and cull half-spaces that are enabled is
determined by the explicit size of the built-in arrays ClipDistance and
CullDistance, respectively, declared as an output in the interface of
the entry point of the final shader stage before clipping.
If VkPipelineRasterizationDepthClipStateCreateInfoEXT is present in
the graphics pipeline state then depth clipping is disabled if
VkPipelineRasterizationDepthClipStateCreateInfoEXT::depthClipEnable
is VK_FALSE.
Otherwise, if VkPipelineRasterizationDepthClipStateCreateInfoEXT is
not present, depth clipping is disabled when
VkPipelineRasterizationStateCreateInfo::depthClampEnable is
VK_TRUE.
When depth clipping is disabled, the plane equation
-
zm ≤ zc ≤ wc
(see the clip volume definition above) is ignored by view volume clipping (effectively, there is no near or far plane clipping).
If the primitive under consideration is a point or line segment, then clipping passes it unchanged if its vertices lie entirely within the clip volume.
Possible values of
VkPhysicalDevicePointClippingProperties::pointClippingBehavior,
specifying clipping behavior of a point primitive whose vertex lies outside
the clip volume, are:
// Provided by VK_VERSION_1_1
typedef enum VkPointClippingBehavior {
VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES = 0,
VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY = 1,
// Provided by VK_KHR_maintenance2
VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES_KHR = VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES,
// Provided by VK_KHR_maintenance2
VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY_KHR = VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY,
} VkPointClippingBehavior;
or the equivalent
// Provided by VK_KHR_maintenance2
typedef VkPointClippingBehavior VkPointClippingBehaviorKHR;
-
VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANESspecifies that the primitive is discarded if the vertex lies outside any clip plane, including the planes bounding the view volume. -
VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLYspecifies that the primitive is discarded only if the vertex lies outside any user clip plane.
If either of a line segment’s vertices lie outside of the clip volume, the line segment may be clipped, with new vertex coordinates computed for each vertex that lies outside the clip volume. A clipped line segment endpoint lies on both the original line segment and the boundary of the clip volume.
This clipping produces a value, 0 ≤ t ≤ 1, for each clipped vertex. If the coordinates of a clipped vertex are P and the unclipped line segment’s vertex coordinates are P1 and P2, then t satisfies the following equation
-
P = t P1 + (1-t) P2.
t is used to clip vertex output attributes as described in Clipping Shader Outputs.
If the primitive is a polygon, it passes unchanged if every one of its edges lies entirely inside the clip volume, and is either clipped or discarded otherwise. If the edges of the polygon intersect the boundary of the clip volume, the intersecting edges are reconnected by new edges that lie along the boundary of the clip volume - in some cases requiring the introduction of new vertices into a polygon.
If a polygon intersects an edge of the clip volume’s boundary, the clipped polygon must include a point on this boundary edge.
Primitives rendered with user-defined half-spaces must satisfy a complementarity criterion. Suppose a series of primitives is drawn where each vertex i has a single specified clip distance di (or a number of similarly specified clip distances, if multiple half-spaces are enabled). Next, suppose that the same series of primitives are drawn again with each such clip distance replaced by -di (and the graphics pipeline is otherwise the same). In this case, primitives must not be missing any pixels, and pixels must not be drawn twice in regions where those primitives are cut by the clip planes.
The VkPipelineViewportDepthClipControlCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_depth_clip_control
typedef struct VkPipelineViewportDepthClipControlCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkBool32 negativeOneToOne;
} VkPipelineViewportDepthClipControlCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
negativeOneToOnesets the zm in the view volume to -wc
26.5. Clipping Shader Outputs
Next, vertex output attributes are clipped. The output values associated with a vertex that lies within the clip volume are unaffected by clipping. If a primitive is clipped, however, the output values assigned to vertices produced by clipping are clipped.
Let the output values assigned to the two vertices P1 and P2 of an unclipped edge be c1 and c2. The value of t (see Primitive Clipping) for a clipped point P is used to obtain the output value associated with P as
-
c = t c1 + (1-t) c2.
(Multiplying an output value by a scalar means multiplying each of x, y, z, and w by the scalar.)
Since this computation is performed in clip space before division by wc, clipped output values are perspective-correct.
Polygon clipping creates a clipped vertex along an edge of the clip volume’s boundary. This situation is handled by noting that polygon clipping proceeds by clipping against one half-space at a time. Output value clipping is done in the same way, so that clipped points always occur at the intersection of polygon edges (possibly already clipped) with the clip volume’s boundary.
For vertex output attributes whose matching fragment input attributes are
decorated with NoPerspective, the value of t used to obtain the
output value associated with P will be adjusted to produce results
that vary linearly in framebuffer space.
Output attributes of integer or unsigned integer type must always be flat shaded. Flat shaded attributes are constant over the primitive being rasterized (see Basic Line Segment Rasterization and Basic Polygon Rasterization), and no interpolation is performed. The output value c is taken from either c1 or c2, since flat shading has already occurred and the two values are identical.
26.6. Controlling Viewport W Scaling
If viewport W scaling is enabled, the W component of the clip coordinate is modified by the provided coefficients from the corresponding viewport as follows.
-
wc' = xcoeff xc + ycoeff yc + wc
The VkPipelineViewportWScalingStateCreateInfoNV structure is defined
as:
// Provided by VK_NV_clip_space_w_scaling
typedef struct VkPipelineViewportWScalingStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 viewportWScalingEnable;
uint32_t viewportCount;
const VkViewportWScalingNV* pViewportWScalings;
} VkPipelineViewportWScalingStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
viewportWScalingEnablecontrols whether viewport W scaling is enabled. -
viewportCountis the number of viewports used by W scaling, and must match the number of viewports in the pipeline if viewport W scaling is enabled. -
pViewportWScalingsis a pointer to an array ofVkViewportWScalingNVstructures defining the W scaling parameters for the corresponding viewports. If the viewport W scaling state is dynamic, this member is ignored.
The VkPipelineViewportWScalingStateCreateInfoNV state is set by adding
this structure to the pNext chain of a
VkPipelineViewportStateCreateInfo structure and setting the graphics
pipeline state with vkCreateGraphicsPipelines.
To dynamically set the viewport W scaling parameters, call:
// Provided by VK_NV_clip_space_w_scaling
void vkCmdSetViewportWScalingNV(
VkCommandBuffer commandBuffer,
uint32_t firstViewport,
uint32_t viewportCount,
const VkViewportWScalingNV* pViewportWScalings);
-
commandBufferis the command buffer into which the command will be recorded. -
firstViewportis the index of the first viewport whose parameters are updated by the command. -
viewportCountis the number of viewports whose parameters are updated by the command. -
pViewportWScalingsis a pointer to an array of VkViewportWScalingNV structures specifying viewport parameters.
The viewport parameters taken from element i of
pViewportWScalings replace the current state for the viewport index
firstViewport + i, for i in [0,
viewportCount).
This command sets the viewport W scaling for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportWScalingStateCreateInfoNV::pViewportWScalings
values used to create the currently active pipeline.
Both VkPipelineViewportWScalingStateCreateInfoNV and
vkCmdSetViewportWScalingNV use VkViewportWScalingNV to set the
viewport transformation parameters.
The VkViewportWScalingNV structure is defined as:
// Provided by VK_NV_clip_space_w_scaling
typedef struct VkViewportWScalingNV {
float xcoeff;
float ycoeff;
} VkViewportWScalingNV;
-
xcoeffandycoeffare the viewport’s W scaling factor for x and y respectively.
26.7. Coordinate Transformations
Clip coordinates for a vertex result from shader execution, which yields a
vertex coordinate Position.
Perspective division on clip coordinates yields normalized device coordinates, followed by a viewport transformation (see Controlling the Viewport) to convert these coordinates into framebuffer coordinates.
If a vertex in clip coordinates has a position given by
then the vertex’s normalized device coordinates are
26.8. Render Pass Transform
A render pass transform can be enabled for render pass instances. The clip coordinates (xc, yc) that result from vertex shader execution are transformed by a rotation of 0, 90, 180, or 270 degrees in the XY plane, centered at the origin.
When Render pass transform is enabled, the transform applies to all primitives for all subpasses of the render pass. The transformed vertex in clip coordinates has a position given by
where
-
θ is 0 degrees for
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR -
θ is 90 degrees for
VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR -
θ is 180 degrees for
VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR -
θ is 270 degrees for
VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
The transformed vertex’s normalized device coordinates are
When render pass transform is enabled for a render pass instance, the following additional features are enabled:
-
Each VkViewport specified by either VkPipelineViewportStateCreateInfo::
pViewportsor vkCmdSetViewport will have its width/height (px, py) and its center (ox, oy) similarly transformed by the implementation. -
Each scissor specified by VkPipelineViewportStateCreateInfo::
pScissorsor vkCmdSetScissor will have its (offsetx, offsety) and (extentx, extenty) similarly transformed by the implementation. -
The
renderAreaspecified in VkCommandBufferInheritanceRenderPassTransformInfoQCOM and VkRenderPassBeginInfo will be similarly transformed by the implementation. -
The (x, y) components of shader variables with built-in decorations
FragCoord,SamplePosition, orPointCoordwill be similarly transformed by the implementation. -
The (x,y) components of the
offsetoperand of theInterpolateAtOffsetextended instruction will be similarly transformed by the implementation. -
The values returned by SPIR-V derivative instructions
OpDPdx,OpDPdy,OpDPdxCourse,OpDPdyCourse,OpDPdxFine,OpDPdyFinewill be similarly transformed by the implementation.
The net result of the above, is that applications can act as if rendering
to a framebuffer oriented with the
VkSurfaceCapabilitiesKHR::currentTransform.
In other words, applications can act as if the presentation engine will be
performing the transformation of the swapchain image after rendering and
prior to presentation to the user.
In fact, the transformation of the various items cited above are being
handled by the implementation as the rendering takes place.
26.9. Controlling the Viewport
The viewport transformation is determined by the selected viewport’s width and height in pixels, px and py, respectively, and its center (ox, oy) (also in pixels), as well as its depth range min and max determining a depth range scale value pz and a depth range bias value oz (defined below). The vertex’s framebuffer coordinates (xf, yf, zf) are given by
-
xf = (px / 2) xd + ox
-
yf = (py / 2) yd + oy
-
zf = pz × zd + oz
Multiple viewports are available, numbered zero up to
VkPhysicalDeviceLimits::maxViewports minus one.
The number of viewports used by a pipeline is controlled by the
viewportCount member of the VkPipelineViewportStateCreateInfo
structure used in pipeline creation.
xf and yf have limited precision, where the number of
fractional bits retained is specified by
VkPhysicalDeviceLimits::subPixelPrecisionBits.
When rasterizing line segments, the number of fractional
bits is specified by
VkPhysicalDeviceLineRasterizationPropertiesEXT::lineSubPixelPrecisionBits.
The VkPipelineViewportStateCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineViewportStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineViewportStateCreateFlags flags;
uint32_t viewportCount;
const VkViewport* pViewports;
uint32_t scissorCount;
const VkRect2D* pScissors;
} VkPipelineViewportStateCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
viewportCountis the number of viewports used by the pipeline. -
pViewportsis a pointer to an array of VkViewport structures, defining the viewport transforms. If the viewport state is dynamic, this member is ignored. -
scissorCountis the number of scissors and must match the number of viewports. -
pScissorsis a pointer to an array of VkRect2D structures defining the rectangular bounds of the scissor for the corresponding viewport. If the scissor state is dynamic, this member is ignored.
To dynamically set the viewport count and viewports, call:
// Provided by VK_VERSION_1_3
void vkCmdSetViewportWithCount(
VkCommandBuffer commandBuffer,
uint32_t viewportCount,
const VkViewport* pViewports);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetViewportWithCountEXT(
VkCommandBuffer commandBuffer,
uint32_t viewportCount,
const VkViewport* pViewports);
-
commandBufferis the command buffer into which the command will be recorded. -
viewportCountspecifies the viewport count. -
pViewportsspecifies the viewports to use for drawing.
This command sets the viewport count and viewports state for subsequent
drawing commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the corresponding
VkPipelineViewportStateCreateInfo::viewportCount and
pViewports values used to create the currently active pipeline.
To dynamically set the scissor count and scissor rectangular bounds, call:
// Provided by VK_VERSION_1_3
void vkCmdSetScissorWithCount(
VkCommandBuffer commandBuffer,
uint32_t scissorCount,
const VkRect2D* pScissors);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetScissorWithCountEXT(
VkCommandBuffer commandBuffer,
uint32_t scissorCount,
const VkRect2D* pScissors);
-
commandBufferis the command buffer into which the command will be recorded. -
scissorCountspecifies the scissor count. -
pScissorsspecifies the scissors to use for drawing.
This command sets the scissor count and scissor rectangular bounds state for
subsequence drawing commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the corresponding
VkPipelineViewportStateCreateInfo::scissorCount and
pScissors values used to create the currently active pipeline.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineViewportStateCreateFlags;
VkPipelineViewportStateCreateFlags is a bitmask type for setting a
mask, but is currently reserved for future use.
A pre-rasterization shader
stage can direct each primitive to zero or more viewports.
The destination viewports for a primitive are selected by the last active
pre-rasterization shader
stage that has an output variable decorated with ViewportIndex
(selecting a single viewport) or ViewportMaskNV (selecting multiple
viewports).
The viewport transform uses the viewport corresponding to either the value
assigned to ViewportIndex or one of the bits set in
ViewportMaskNV, and taken from an implementation-dependent vertex of
each primitive.
If ViewportIndex or any of the bits in ViewportMaskNV are outside
the range zero to viewportCount minus one for a primitive, or if the
last active pre-rasterization
shader stage did not assign a value to either ViewportIndex or
ViewportMaskNV for all vertices of a primitive due to flow control, the
values resulting from the viewport transformation of the vertices of such
primitives are undefined.
If the last pre-rasterization
shader stage does not have an output decorated with ViewportIndex or
ViewportMaskNV, the viewport numbered zero is used by the viewport
transformation.
A single vertex can be used in more than one individual primitive, in
primitives such as VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP.
In this case, the viewport transformation is applied separately for each
primitive.
To dynamically set the viewport transformation parameters, call:
// Provided by VK_VERSION_1_0
void vkCmdSetViewport(
VkCommandBuffer commandBuffer,
uint32_t firstViewport,
uint32_t viewportCount,
const VkViewport* pViewports);
-
commandBufferis the command buffer into which the command will be recorded. -
firstViewportis the index of the first viewport whose parameters are updated by the command. -
viewportCountis the number of viewports whose parameters are updated by the command. -
pViewportsis a pointer to an array of VkViewport structures specifying viewport parameters.
This command sets the viewport transformation parameters state for
subsequent drawing commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_VIEWPORT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportStateCreateInfo::pViewports values used to
create the currently active pipeline.
The viewport parameters taken from element i of pViewports
replace the current state for the viewport index firstViewport
+ i, for i in [0, viewportCount).
Both VkPipelineViewportStateCreateInfo and vkCmdSetViewport use
VkViewport to set the viewport transformation parameters.
The VkViewport structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkViewport {
float x;
float y;
float width;
float height;
float minDepth;
float maxDepth;
} VkViewport;
-
xandyare the viewport’s upper left corner (x,y). -
widthandheightare the viewport’s width and height, respectively. -
minDepthandmaxDepthare the depth range for the viewport.
|
Note
Despite their names, |
The framebuffer depth coordinate zf may be represented using
either a fixed-point or floating-point representation.
However, a floating-point representation must be used if the depth/stencil
attachment has a floating-point depth component.
If an m-bit fixed-point representation is used, we assume that it
represents each value , where k ∈ {
0, 1, …, 2m-1 }, as k (e.g. 1.0 is represented in binary as a
string of all ones).
The viewport parameters shown in the above equations are found from these values as
-
ox =
x+width/ 2 -
oy =
y+height/ 2 -
oz =
minDepth(or (maxDepth+minDepth) / 2 if VkPipelineViewportDepthClipControlCreateInfoEXT::negativeOneToOneisVK_TRUE) -
px =
width -
py =
height -
pz =
maxDepth-minDepth(or (maxDepth-minDepth) / 2 if VkPipelineViewportDepthClipControlCreateInfoEXT::negativeOneToOneisVK_TRUE)
If a render pass transform is enabled, the values (px,py) and (ox, oy) defining the viewport are transformed as described in render pass transform before participating in the viewport transform.
The application can specify a negative term for height, which has the
effect of negating the y coordinate in clip space before performing the
transform.
When using a negative height, the application should also adjust the
y value to point to the lower left corner of the viewport instead of
the upper left corner.
Using the negative height allows the application to avoid having to
negate the y component of the Position output from the last
pre-rasterization shader
stage.
The width and height of the implementation-dependent maximum viewport dimensions must be greater than or equal to the width and height of the largest image which can be created and attached to a framebuffer.
The floating-point viewport bounds are represented with an implementation-dependent precision.
27. Rasterization
Rasterization is the process by which a primitive is converted to a two-dimensional image. Each discrete location of this image contains associated data such as depth, color, or other attributes.
Rasterizing a primitive begins by determining which squares of an integer grid in framebuffer coordinates are occupied by the primitive, and assigning one or more depth values to each such square. This process is described below for points, lines, and polygons.
A grid square, including its (x,y) framebuffer coordinates, z (depth), and associated data added by fragment shaders, is called a fragment. A fragment is located by its upper left corner, which lies on integer grid coordinates.
Rasterization operations also refer to a fragment’s sample locations, which are offset by fractional values from its upper left corner. The rasterization rules for points, lines, and triangles involve testing whether each sample location is inside the primitive. Fragments need not actually be square, and rasterization rules are not affected by the aspect ratio of fragments. Display of non-square grids, however, will cause rasterized points and line segments to appear fatter in one direction than the other.
We assume that fragments are square, since it simplifies antialiasing and texturing. After rasterization, fragments are processed by fragment operations.
Several factors affect rasterization, including the members of VkPipelineRasterizationStateCreateInfo and VkPipelineMultisampleStateCreateInfo.
The VkPipelineRasterizationStateCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineRasterizationStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineRasterizationStateCreateFlags flags;
VkBool32 depthClampEnable;
VkBool32 rasterizerDiscardEnable;
VkPolygonMode polygonMode;
VkCullModeFlags cullMode;
VkFrontFace frontFace;
VkBool32 depthBiasEnable;
float depthBiasConstantFactor;
float depthBiasClamp;
float depthBiasSlopeFactor;
float lineWidth;
} VkPipelineRasterizationStateCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
depthClampEnablecontrols whether to clamp the fragment’s depth values as described in Depth Test. If the pipeline is not created with VkPipelineRasterizationDepthClipStateCreateInfoEXT present then enabling depth clamp will also disable clipping primitives to the z planes of the frustrum as described in Primitive Clipping. Otherwise depth clipping is controlled by the state set in VkPipelineRasterizationDepthClipStateCreateInfoEXT. -
rasterizerDiscardEnablecontrols whether primitives are discarded immediately before the rasterization stage. -
polygonModeis the triangle rendering mode. See VkPolygonMode. -
cullModeis the triangle facing direction used for primitive culling. See VkCullModeFlagBits. -
frontFaceis a VkFrontFace value specifying the front-facing triangle orientation to be used for culling. -
depthBiasEnablecontrols whether to bias fragment depth values. -
depthBiasConstantFactoris a scalar factor controlling the constant depth value added to each fragment. -
depthBiasClampis the maximum (or minimum) depth bias of a fragment. -
depthBiasSlopeFactoris a scalar factor applied to a fragment’s slope in depth bias calculations. -
lineWidthis the width of rasterized line segments.
The application can also add a
VkPipelineRasterizationStateRasterizationOrderAMD structure to the
pNext chain of a VkPipelineRasterizationStateCreateInfo
structure.
This structure enables selecting the rasterization order to use when
rendering with the corresponding graphics pipeline as described in
Rasterization Order.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineRasterizationStateCreateFlags;
VkPipelineRasterizationStateCreateFlags is a bitmask type for setting
a mask, but is currently reserved for future use.
If the pNext chain of VkPipelineRasterizationStateCreateInfo
includes a VkPipelineRasterizationDepthClipStateCreateInfoEXT
structure, then that structure controls whether depth clipping is enabled or
disabled.
The VkPipelineRasterizationDepthClipStateCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_depth_clip_enable
typedef struct VkPipelineRasterizationDepthClipStateCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkPipelineRasterizationDepthClipStateCreateFlagsEXT flags;
VkBool32 depthClipEnable;
} VkPipelineRasterizationDepthClipStateCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
depthClipEnablecontrols whether depth clipping is enabled as described in Primitive Clipping.
// Provided by VK_EXT_depth_clip_enable
typedef VkFlags VkPipelineRasterizationDepthClipStateCreateFlagsEXT;
VkPipelineRasterizationDepthClipStateCreateFlagsEXT is a bitmask type
for setting a mask, but is currently reserved for future use.
The VkPipelineMultisampleStateCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineMultisampleStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineMultisampleStateCreateFlags flags;
VkSampleCountFlagBits rasterizationSamples;
VkBool32 sampleShadingEnable;
float minSampleShading;
const VkSampleMask* pSampleMask;
VkBool32 alphaToCoverageEnable;
VkBool32 alphaToOneEnable;
} VkPipelineMultisampleStateCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
rasterizationSamplesis a VkSampleCountFlagBits value specifying the number of samples used in rasterization. -
sampleShadingEnablecan be used to enable Sample Shading. -
minSampleShadingspecifies a minimum fraction of sample shading ifsampleShadingEnableis set toVK_TRUE. -
pSampleMaskis a pointer to an array ofVkSampleMaskvalues used in the sample mask test. -
alphaToCoverageEnablecontrols whether a temporary coverage value is generated based on the alpha component of the fragment’s first color output as specified in the Multisample Coverage section. -
alphaToOneEnablecontrols whether the alpha component of the fragment’s first color output is replaced with one as described in Multisample Coverage.
Each bit in the sample mask is associated with a unique
sample index as defined for the
coverage mask.
Each bit b for mask word w in the sample mask corresponds to
sample index i, where i = 32 × w + b.
pSampleMask has a length equal to ⌈
rasterizationSamples / 32 ⌉ words.
If pSampleMask is NULL, it is treated as if the mask has all bits
set to 1.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineMultisampleStateCreateFlags;
VkPipelineMultisampleStateCreateFlags is a bitmask type for setting a
mask, but is currently reserved for future use.
The elements of the sample mask array are of type VkSampleMask,
each representing 32 bits of coverage information:
// Provided by VK_VERSION_1_0
typedef uint32_t VkSampleMask;
Rasterization only generates fragments which cover one or more pixels inside the framebuffer. Pixels outside the framebuffer are never considered covered in the fragment. Fragments which would be produced by application of any of the primitive rasterization rules described below but which lie outside the framebuffer are not produced, nor are they processed by any later stage of the pipeline, including any of the fragment operations.
Surviving fragments are processed by fragment shaders. Fragment shaders determine associated data for fragments, and can also modify or replace their assigned depth values.
27.1. Discarding Primitives Before Rasterization
Primitives are discarded before rasterization if the
rasterizerDiscardEnable member of
VkPipelineRasterizationStateCreateInfo is enabled.
When enabled, primitives are discarded after they are processed by the last
active shader stage in the pipeline before rasterization.
To dynamically enable whether primitives are discarded before the rasterization stage, call:
// Provided by VK_VERSION_1_3
void vkCmdSetRasterizerDiscardEnable(
VkCommandBuffer commandBuffer,
VkBool32 rasterizerDiscardEnable);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state2
void vkCmdSetRasterizerDiscardEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 rasterizerDiscardEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
rasterizerDiscardEnablecontrols whether primitives are discarded immediately before the rasterization stage.
This command sets the discard enable for subsequent drawing commands when
the graphics pipeline is created with
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationStateCreateInfo::rasterizerDiscardEnable
value used to create the currently active pipeline.
27.2. Controlling the Vertex Stream Used for Rasterization
By default vertex data output from the last
pre-rasterization shader
stage are directed to vertex stream zero.
Geometry shaders can emit primitives to multiple independent vertex
streams.
Each vertex emitted by the geometry shader is directed at one of the vertex
streams.
As vertices are received on each vertex stream, they are arranged into
primitives of the type specified by the geometry shader output primitive
type.
The shading language instructions OpEndPrimitive and
OpEndStreamPrimitive can be used to end the primitive being assembled
on a given vertex stream and start a new empty primitive of the same type.
An implementation supports up to
VkPhysicalDeviceTransformFeedbackPropertiesEXT::maxTransformFeedbackStreams
streams, which is at least 1.
The individual streams are numbered 0 through
maxTransformFeedbackStreams minus 1.
There is no requirement on the order of the streams to which vertices are
emitted, and the number of vertices emitted to each vertex stream can be
completely independent, subject only to the
VkPhysicalDeviceTransformFeedbackPropertiesEXT::maxTransformFeedbackStreamDataSize
and
VkPhysicalDeviceTransformFeedbackPropertiesEXT::maxTransformFeedbackBufferDataSize
limits.
The primitives output from all vertex streams are passed to the transform
feedback stage to be captured to transform feedback buffers in the manner
specified by the last
pre-rasterization shader
stage shader’s XfbBuffer, XfbStride, and Offsets
decorations on the output interface variables in the graphics pipeline.
To use a vertex stream other than zero, or to use multiple streams, the
GeometryStreams capability must be specified.
By default, the primitives output from vertex stream zero are rasterized.
If the implementation supports the
VkPhysicalDeviceTransformFeedbackPropertiesEXT::transformFeedbackRasterizationStreamSelect
property it is possible to rasterize a vertex stream other than zero.
By default, geometry shaders that emit vertices to multiple vertex streams
are limited to using only the OutputPoints output primitive type.
If the implementation supports the
VkPhysicalDeviceTransformFeedbackPropertiesEXT::transformFeedbackStreamsLinesTriangles
property it is possible to emit OutputLineStrip or
OutputTriangleStrip in addition to OutputPoints.
The vertex stream used for rasterization is specified by adding a
VkPipelineRasterizationStateStreamCreateInfoEXT structure to the
pNext chain of a VkPipelineRasterizationStateCreateInfo
structure.
The VkPipelineRasterizationStateStreamCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_transform_feedback
typedef struct VkPipelineRasterizationStateStreamCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkPipelineRasterizationStateStreamCreateFlagsEXT flags;
uint32_t rasterizationStream;
} VkPipelineRasterizationStateStreamCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
rasterizationStreamis the vertex stream selected for rasterization.
If this structure is not present, rasterizationStream is assumed to be
zero.
// Provided by VK_EXT_transform_feedback
typedef VkFlags VkPipelineRasterizationStateStreamCreateFlagsEXT;
VkPipelineRasterizationStateStreamCreateFlagsEXT is a bitmask type for
setting a mask, but is currently reserved for future use.
27.3. Rasterization Order
Within a subpass of a render pass instance, for a given (x,y,layer,sample) sample location, the following operations are guaranteed to execute in rasterization order, for each separate primitive that includes that sample location:
-
Fragment operations, in the order defined
-
Blending, logic operations, and color writes
Execution of these operations for each primitive in a subpass occurs in an order determined by the application.
The rasterization order to use for a graphics pipeline is specified by
adding a VkPipelineRasterizationStateRasterizationOrderAMD structure
to the pNext chain of a VkPipelineRasterizationStateCreateInfo
structure.
The VkPipelineRasterizationStateRasterizationOrderAMD structure is
defined as:
// Provided by VK_AMD_rasterization_order
typedef struct VkPipelineRasterizationStateRasterizationOrderAMD {
VkStructureType sType;
const void* pNext;
VkRasterizationOrderAMD rasterizationOrder;
} VkPipelineRasterizationStateRasterizationOrderAMD;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rasterizationOrderis a VkRasterizationOrderAMD value specifying the primitive rasterization order to use.
If the VK_AMD_rasterization_order device extension is not enabled
or the application does not request a particular rasterization order through
specifying a VkPipelineRasterizationStateRasterizationOrderAMD
structure then the rasterization order used by the graphics pipeline
defaults to VK_RASTERIZATION_ORDER_STRICT_AMD.
Possible values of
VkPipelineRasterizationStateRasterizationOrderAMD::rasterizationOrder,
specifying the primitive rasterization order, are:
// Provided by VK_AMD_rasterization_order
typedef enum VkRasterizationOrderAMD {
VK_RASTERIZATION_ORDER_STRICT_AMD = 0,
VK_RASTERIZATION_ORDER_RELAXED_AMD = 1,
} VkRasterizationOrderAMD;
-
VK_RASTERIZATION_ORDER_STRICT_AMDspecifies that operations for each primitive in a subpass must occur in primitive order. -
VK_RASTERIZATION_ORDER_RELAXED_AMDspecifies that operations for each primitive in a subpass may not occur in primitive order.
27.4. Multisampling
Multisampling is a mechanism to antialias all Vulkan primitives: points, lines, and polygons. The technique is to sample all primitives multiple times at each pixel. Each sample in each framebuffer attachment has storage for a color, depth, and/or stencil value, such that per-fragment operations apply to each sample independently. The color sample values can be later resolved to a single color (see Resolving Multisample Images and the Render Pass chapter for more details on how to resolve multisample images to non-multisample images).
Vulkan defines rasterization rules for single-sample modes in a way that is equivalent to a multisample mode with a single sample in the center of each fragment.
Each fragment includes a coverage mask with a single bit for each sample in the fragment, and a number of depth values and associated data for each sample.
It is understood that each pixel has rasterizationSamples locations
associated with it.
These locations are exact positions, rather than regions or areas, and each
is referred to as a sample point.
The sample points associated with a pixel must be located inside or on the
boundary of the unit square that is considered to bound the pixel.
Furthermore, the relative locations of sample points may be identical for
each pixel in the framebuffer, or they may differ.
If the render pass has a fragment density map attachment, each fragment only
has rasterizationSamples locations associated with it regardless of
how many pixels are covered in the fragment area.
Fragment sample locations are defined as if the fragment had an area of
(1,1) and its sample points must be located within these bounds.
Their actual location in the framebuffer is calculated by scaling the sample
location by the fragment area.
Attachments with storage for multiple samples per pixel are located at the
pixel sample locations.
Otherwise, the fragment’s sample locations are generally used for evaluation
of associated data and fragment operations.
If the current pipeline includes a fragment shader with one or more
variables in its interface decorated with Sample and Input, the
data associated with those variables will be assigned independently for each
sample.
The values for each sample must be evaluated at the location of the sample.
The data associated with any other variables not decorated with Sample
and Input need not be evaluated independently for each sample.
A coverage mask is generated for each fragment, based on which samples within that fragment are determined to be within the area of the primitive that generated the fragment.
Single pixel fragments
and multi-pixel fragments defined by a
fragment density map
have one set of samples.
Multi-pixel fragments defined by a shading
rate image have one set of samples per pixel.
Multi-pixel fragments defined by setting the
fragment shading rate have one set of
samples per pixel.
Each set of samples has a number of samples determined by
VkPipelineMultisampleStateCreateInfo::rasterizationSamples.
Each sample in a set is assigned a unique sample index i in the
range [0, rasterizationSamples).
Each sample in a fragment is also assigned a unique coverage index j
in the range [0, n × rasterizationSamples), where n
is the number of sets in the fragment.
If the fragment contains a single set of samples, the coverage index is
always equal to the sample index.
If a shading rate image is used and a
fragment covers multiple pixels, the coverage index is determined as defined
by VkPipelineViewportCoarseSampleOrderStateCreateInfoNV or
vkCmdSetCoarseSampleOrderNV.
If the fragment shading rate is set, the coverage index j is determined as a function of the pixel index p, the sample index i, and the number of rasterization samples r as:
-
j = i + r × ((fw × fh) - 1 - p)
where the pixel index p is determined as a function of the pixel’s framebuffer location (x,y) and the fragment size (fw,fh):
-
px = x % fw
-
py = y % fh
-
p = px + (py × fw)
The table below illustrates the pixel index for multi-pixel fragments:
| 1x1 | 1x2 | 1x4 |
|---|---|---|
| 2x1 | 2x2 | 2x4 |
|---|---|---|
| 4x1 | 4x2 | 4x4 |
|---|---|---|
The coverage mask includes B bits packed into W words, defined as:
-
B = n ×
rasterizationSamples -
W = ⌈B/32⌉
Bit b in coverage mask word w is 1 if the sample with coverage
index j = 32×w + b is covered, and 0 otherwise.
If the standardSampleLocations member of VkPhysicalDeviceLimits
is VK_TRUE, then the sample counts VK_SAMPLE_COUNT_1_BIT,
VK_SAMPLE_COUNT_2_BIT, VK_SAMPLE_COUNT_4_BIT,
VK_SAMPLE_COUNT_8_BIT, and VK_SAMPLE_COUNT_16_BIT have sample
locations as listed in the following table, with the ith entry in
the table corresponding to sample index i.
VK_SAMPLE_COUNT_32_BIT and VK_SAMPLE_COUNT_64_BIT do not have
standard sample locations.
Locations are defined relative to an origin in the upper left corner of the
fragment.
| Sample count | Sample Locations | |
|---|---|---|
|
(0.5,0.5) |
|
|
(0.75,0.75) |
|
|
(0.375, 0.125) |
|
|
(0.5625, 0.3125) |
|
|
(0.5625, 0.5625) |
|
Color images created with multiple samples per pixel use a compression
technique where there are two arrays of data associated with each pixel.
The first array contains one element per sample where each element stores an
index to the second array defining the fragment mask of the pixel.
The second array contains one element per color fragment and each element
stores a unique color value in the format of the image.
With this compression technique it is not always necessary to actually use
unique storage locations for each color sample: when multiple samples share
the same color value the fragment mask may have two samples referring to
the same color fragment.
The number of color fragments is determined by the samples member of
the VkImageCreateInfo structure used to create the image.
The VK_AMD_shader_fragment_mask device extension provides shader
instructions enabling the application to get direct access to the fragment
mask and the individual color fragment values.
27.5. Custom Sample Locations
Applications can also control the sample locations used for rasterization.
If the pNext chain of the VkPipelineMultisampleStateCreateInfo
structure specified at pipeline creation time includes a
VkPipelineSampleLocationsStateCreateInfoEXT structure, then that
structure controls the sample locations used when rasterizing primitives
with the pipeline.
The VkPipelineSampleLocationsStateCreateInfoEXT structure is defined
as:
// Provided by VK_EXT_sample_locations
typedef struct VkPipelineSampleLocationsStateCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkBool32 sampleLocationsEnable;
VkSampleLocationsInfoEXT sampleLocationsInfo;
} VkPipelineSampleLocationsStateCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sampleLocationsEnablecontrols whether custom sample locations are used. IfsampleLocationsEnableisVK_FALSE, the default sample locations are used and the values specified insampleLocationsInfoare ignored. -
sampleLocationsInfois the sample locations to use during rasterization ifsampleLocationsEnableisVK_TRUEand the graphics pipeline is not created withVK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT.
The VkSampleLocationsInfoEXT structure is defined as:
// Provided by VK_EXT_sample_locations
typedef struct VkSampleLocationsInfoEXT {
VkStructureType sType;
const void* pNext;
VkSampleCountFlagBits sampleLocationsPerPixel;
VkExtent2D sampleLocationGridSize;
uint32_t sampleLocationsCount;
const VkSampleLocationEXT* pSampleLocations;
} VkSampleLocationsInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sampleLocationsPerPixelis a VkSampleCountFlagBits value specifying the number of sample locations per pixel. -
sampleLocationGridSizeis the size of the sample location grid to select custom sample locations for. -
sampleLocationsCountis the number of sample locations inpSampleLocations. -
pSampleLocationsis a pointer to an array ofsampleLocationsCountVkSampleLocationEXT structures.
This structure can be used either to specify the sample locations to be
used for rendering or to specify the set of sample locations an image
subresource has been last rendered with for the purposes of layout
transitions of depth/stencil images created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT.
The sample locations in pSampleLocations specify
sampleLocationsPerPixel number of sample locations for each pixel in
the grid of the size specified in sampleLocationGridSize.
The sample location for sample i at the pixel grid location
(x,y) is taken from pSampleLocations[(x + y ×
sampleLocationGridSize.width) × sampleLocationsPerPixel
+ i].
If the render pass has a fragment density map, the implementation will
choose the sample locations for the fragment and the contents of
pSampleLocations may be ignored.
The VkSampleLocationEXT structure is defined as:
// Provided by VK_EXT_sample_locations
typedef struct VkSampleLocationEXT {
float x;
float y;
} VkSampleLocationEXT;
-
xis the horizontal coordinate of the sample’s location. -
yis the vertical coordinate of the sample’s location.
The domain space of the sample location coordinates has an upper-left origin within the pixel in framebuffer space.
The values specified in a VkSampleLocationEXT structure are always
clamped to the implementation-dependent sample location coordinate range
[sampleLocationCoordinateRange[0],sampleLocationCoordinateRange[1]]
that can be queried using
VkPhysicalDeviceSampleLocationsPropertiesEXT.
To dynamically set the sample locations used for rasterization, call:
// Provided by VK_EXT_sample_locations
void vkCmdSetSampleLocationsEXT(
VkCommandBuffer commandBuffer,
const VkSampleLocationsInfoEXT* pSampleLocationsInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pSampleLocationsInfois the sample locations state to set.
This command sets the custom sample locations for subsequent drawing
commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates, and when the
VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable
property of the bound graphics pipeline is VK_TRUE.
Otherwise, this state is specified by the
VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsInfo
values used to create the currently active pipeline.
27.6. Fragment Shading Rates
The features advertised by VkPhysicalDeviceFragmentShadingRateFeaturesKHR allow an application to control the shading rate of a given fragment shader invocation.
The fragment shading rate strongly interacts with Multisampling, and the set of available rates for an implementation may be restricted by sample rate.
To query available shading rates, call:
// Provided by VK_KHR_fragment_shading_rate
VkResult vkGetPhysicalDeviceFragmentShadingRatesKHR(
VkPhysicalDevice physicalDevice,
uint32_t* pFragmentShadingRateCount,
VkPhysicalDeviceFragmentShadingRateKHR* pFragmentShadingRates);
-
physicalDeviceis the handle to the physical device whose properties will be queried. -
pFragmentShadingRateCountis a pointer to an integer related to the number of fragment shading rates available or queried, as described below. -
pFragmentShadingRatesis eitherNULLor a pointer to an array of VkPhysicalDeviceFragmentShadingRateKHR structures.
If pFragmentShadingRates is NULL, then the number of fragment
shading rates available is returned in pFragmentShadingRateCount.
Otherwise, pFragmentShadingRateCount must point to a variable set by
the user to the number of elements in the pFragmentShadingRates array,
and on return the variable is overwritten with the number of structures
actually written to pFragmentShadingRates.
If pFragmentShadingRateCount is less than the number of fragment
shading rates available, at most pFragmentShadingRateCount structures
will be written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available fragment shading
rates were returned.
The returned array of fragment shading rates must be ordered from largest
fragmentSize.width value to smallest, and each set of fragment shading
rates with the same fragmentSize.width value must be ordered from
largest fragmentSize.height to smallest.
Any two entries in the array must not have the same fragmentSize
values.
For any entry in the array, the following rules also apply:
-
The value of
fragmentSize.widthmust be less than or equal tomaxFragmentSize.width. -
The value of
fragmentSize.widthmust be greater than or equal to1. -
The value of
fragmentSize.widthmust be a power-of-two. -
The value of
fragmentSize.heightmust be less than or equal tomaxFragmentSize.height. -
The value of
fragmentSize.heightmust be greater than or equal to1. -
The value of
fragmentSize.heightmust be a power-of-two. -
The highest sample count in
sampleCountsmust be less than or equal tomaxFragmentShadingRateRasterizationSamples. -
The product of
fragmentSize.width,fragmentSize.height, and the highest sample count insampleCountsmust be less than or equal tomaxFragmentShadingRateCoverageSamples.
Implementations must support at least the following shading rates:
sampleCounts |
fragmentSize |
|---|---|
|
{2,2} |
|
{2,1} |
~0 |
{1,1} |
If framebufferColorSampleCounts, includes VK_SAMPLE_COUNT_2_BIT,
the required rates must also include VK_SAMPLE_COUNT_2_BIT.
|
Note
Including the {1,1} fragment size is done for completeness; it has no actual effect on the support of rendering without setting the fragment size. All sample counts and render pass transforms are supported for this rate. |
The returned set of fragment shading rates must be returned in the native
(rotated) coordinate system.
For rasterization using render pass transform not equal to
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, the application must transform
the returned fragment shading rates into the current (unrotated) coordinate
system to get the supported rates for that transform.
|
Note
For example, consider an implementation returning support for 4x2, but not
2x4 in the set of supported fragment shading rates.
This means that for transforms |
The VkPhysicalDeviceFragmentShadingRateKHR structure is defined as
// Provided by VK_KHR_fragment_shading_rate
typedef struct VkPhysicalDeviceFragmentShadingRateKHR {
VkStructureType sType;
void* pNext;
VkSampleCountFlags sampleCounts;
VkExtent2D fragmentSize;
} VkPhysicalDeviceFragmentShadingRateKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sampleCountsis a bitmask of sample counts for which the shading rate described byfragmentSizeis supported. -
fragmentSizeis a VkExtent2D describing the width and height of a supported shading rate.
Fragment shading rates can be set at three points, with the three rates combined to determine the final shading rate.
27.6.1. Pipeline Fragment Shading Rate
The pipeline fragment shading rate can be set on a per-draw basis by either setting the rate in a graphics pipeline, or dynamically via vkCmdSetFragmentShadingRateKHR.
The VkPipelineFragmentShadingRateStateCreateInfoKHR structure is
defined as:
// Provided by VK_KHR_fragment_shading_rate
typedef struct VkPipelineFragmentShadingRateStateCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkExtent2D fragmentSize;
VkFragmentShadingRateCombinerOpKHR combinerOps[2];
} VkPipelineFragmentShadingRateStateCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentSizespecifies a VkExtent2D structure containing the fragment size used to define the pipeline fragment shading rate for drawing commands using this pipeline. -
combinerOpsspecifies a VkFragmentShadingRateCombinerOpKHR value determining how the pipeline, primitive, and attachment shading rates are combined for fragments generated by drawing commands using the created pipeline.
If the pNext chain of VkGraphicsPipelineCreateInfo includes a
VkPipelineFragmentShadingRateStateCreateInfoKHR structure, then that
structure includes parameters controlling the pipeline fragment shading
rate.
If this structure is not present, fragmentSize is considered to be
equal to (1,1), and both elements of combinerOps are considered
to be equal to VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR.
To dynamically set the pipeline fragment shading rate and combiner operation, call:
// Provided by VK_KHR_fragment_shading_rate
void vkCmdSetFragmentShadingRateKHR(
VkCommandBuffer commandBuffer,
const VkExtent2D* pFragmentSize,
const VkFragmentShadingRateCombinerOpKHR combinerOps[2]);
-
commandBufferis the command buffer into which the command will be recorded. -
pFragmentSizespecifies the pipeline fragment shading rate for subsequent drawing commands. -
combinerOpsspecifies a VkFragmentShadingRateCombinerOpKHR determining how the pipeline, primitive, and attachment shading rates are combined for fragments generated by subsequent drawing commands.
This command sets the pipeline fragment shading rate and combiner operation
for subsequent drawing commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineFragmentShadingRateStateCreateInfoKHR values used to create
the currently active pipeline.
27.6.2. Primitive Fragment Shading Rate
The primitive fragment shading rate can be set via the
PrimitiveShadingRateKHR built-in in the last active
pre-rasterization shader
stage.
The rate associated with a given primitive is sourced from the value written
to PrimitiveShadingRateKHR by that primitive’s
provoking vertex.
27.6.3. Attachment Fragment Shading Rate
The attachment shading rate can be set by including VkFragmentShadingRateAttachmentInfoKHR in a subpass to define a fragment shading rate attachment. Each pixel in the framebuffer is assigned an attachment fragment shading rate by the corresponding texel in the fragment shading rate attachment, according to:
-
x' = floor(x / regionx)
-
y' = floor(y / regiony)
where x' and y' are the coordinates of a texel in the fragment
shading rate attachment, x and y are the coordinates of the
pixel in the framebuffer, and regionx and regiony are the
size of the region each texel corresponds to, as defined by the
shadingRateAttachmentTexelSize member of
VkFragmentShadingRateAttachmentInfoKHR.
If multiview is enabled and the shading
rate attachment has multiple layers, the shading rate attachment texel is
selected from the layer determined by the
ViewIndex built-in.
If multiview is disabled, and both the
shading rate attachment and the framebuffer have multiple layers, the
shading rate attachment texel is selected from the layer determined by the
Layer built-in.
Otherwise, the texel is unconditionally selected from the first layer of the
attachment.
The fragment size is encoded into the first component of the identified texel as follows:
-
sizew = 2((texel/4)&3)
-
sizeh = 2(texel&3)
where texel is the value in the first component of the identified texel, and sizew and sizeh are the width and height of the fragment size, decoded from the texel.
If no fragment shading rate attachment is specified, this size is calculated as sizew = sizeh = 1. Applications must not specify a width or height greater than 4 by this method.
The Fragment Shading Rate enumeration in SPIR-V adheres to the above encoding.
27.6.4. Combining the Fragment Shading Rates
The final rate (Cxy') used for fragment shading must be one of the rates returned by vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count and render pass transform used by rasterization.
If any of the following conditions are met, Cxy' must be set to {1,1}:
-
If Sample Shading is enabled.
-
The
fragmentShadingRateWithSampleMasklimit is not supported, and VkPipelineMultisampleStateCreateInfo::pSampleMaskcontains a zero value in any bit used by fragment operations. -
The
fragmentShadingRateWithShaderSampleMaskis not supported, and the fragment shader hasSampleMaskin the input or output interface. -
The
fragmentShadingRateWithShaderDepthStencilWriteslimit is not supported, and the fragment shader declares theFragDepthorFragStencilRefEXTbuilt-in. -
The
fragmentShadingRateWithConservativeRasterizationlimit is not supported, and VkPipelineRasterizationConservativeStateCreateInfoEXT::conservativeRasterizationModeis notVK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT. -
The
fragmentShadingRateWithFragmentShaderInterlocklimit is not supported, and the fragment shader declares any of the fragment shader interlock execution modes. -
The
fragmentShadingRateWithCustomSampleLocationslimit is not supported, and VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnableisVK_TRUE.
Otherwise, each of the specified shading rates are combined and then used to derive the value of Cxy'. As there are three ways to specify shading rates, two combiner operations are specified - between the pipeline and primitive shading rates, and between the result of that and the attachment shading rate.
The equation used for each combiner operation is defined by
VkFragmentShadingRateCombinerOpKHR:
// Provided by VK_KHR_fragment_shading_rate
typedef enum VkFragmentShadingRateCombinerOpKHR {
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR = 0,
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR = 1,
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR = 2,
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR = 3,
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR = 4,
} VkFragmentShadingRateCombinerOpKHR;
-
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHRspecifies a combiner operation of combine(Axy,Bxy) = Axy. -
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHRspecifies a combiner operation of combine(Axy,Bxy) = Bxy. -
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHRspecifies a combiner operation of combine(Axy,Bxy) = min(Axy,Bxy). -
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHRspecifies a combiner operation of combine(Axy,Bxy) = max(Axy,Bxy). -
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHRspecifies a combiner operation of combine(Axy,Bxy) = Axy*Bxy.
where combine(Axy,Bxy) is the combine operation, and Axy and Bxy are the inputs to the operation.
If fragmentShadingRateStrictMultiplyCombiner is VK_FALSE, using
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR with values of 1 for both
A and B in the same dimension results in the value 2 being produced for that
dimension.
See the definition of fragmentShadingRateStrictMultiplyCombiner for more information.
These operations are performed in a component-wise fashion.
This is used to generate a combined fragment area using the equation:
-
Cxy = combine(Axy,Bxy)
where Cxy is the combined fragment area result, and Axy and Bxy are the fragment areas of the fragment shading rates being combined.
Two combine operations are performed, first with Axy equal to the
pipeline fragment shading rate
and Bxy equal to the primitive fragment shading rate, with the combine() operation
selected by combinerOps[0].
A second combination is then performed, with Axy equal to the result
of the first combination and Bxy equal to the
attachment fragment shading
rate, with the combine() operation selected by combinerOps[1].
The result of the second combination is used as the final fragment shading
rate, reported via the ShadingRateKHR built-in.
Implementations may clamp the Cxy result of each combiner operation separately, or only after the second combiner operation.
If the final combined rate is one of the rates returned by vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count and render pass transform used by rasterization, Cxy' = Cxy. Otherwise, Cxy' is selected from the rates returned by vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count and render pass transform used by rasterization. From this list of supported rates, the following steps are applied in order, to select a single value:
-
Keep only rates where Cx' ≤ Cx and Cy' ≤ Cy.
-
Implementations may also keep rates where Cx' ≤ Cy and Cy' ≤ Cx.
-
-
Keep only rates with the highest area (Cx' × Cy').
-
Keep only rates with the lowest aspect ratio (Cx' + Cy').
-
In cases where a wide (e.g. 4x1) and tall (e.g. 1x4) rate remain, the implementation may choose either rate. However, it must choose this rate consistently for the same shading rates, render pass transform, and combiner operations for the lifetime of the VkDevice.
27.6.5. Extended Fragment Shading Rates
The features advertised by VkPhysicalDeviceFragmentShadingRateEnumsFeaturesNV provide support for additional fragment shading rates beyond those specifying one fragment shader invocation covering all pixels in a fragment whose size is indicated by the fragment shading rate.
If the fragmentShadingRateEnums feature is enabled, fragment shading
rates may be specified using the VkFragmentShadingRateNV enumerated
type defined as:
// Provided by VK_NV_fragment_shading_rate_enums
typedef enum VkFragmentShadingRateNV {
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV = 0,
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_1X2_PIXELS_NV = 1,
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X1_PIXELS_NV = 4,
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X2_PIXELS_NV = 5,
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X4_PIXELS_NV = 6,
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_4X2_PIXELS_NV = 9,
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_4X4_PIXELS_NV = 10,
VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV = 11,
VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV = 12,
VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV = 13,
VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV = 14,
VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV = 15,
} VkFragmentShadingRateNV;
-
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NVspecifies a fragment size of 1x1 pixels. -
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_1X2_PIXELS_NVspecifies a fragment size of 1x2 pixels. -
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X1_PIXELS_NVspecifies a fragment size of 2x1 pixels. -
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X2_PIXELS_NVspecifies a fragment size of 2x2 pixels. -
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X4_PIXELS_NVspecifies a fragment size of 2x4 pixels. -
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_4X2_PIXELS_NVspecifies a fragment size of 4x2 pixels. -
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_4X4_PIXELS_NVspecifies a fragment size of 4x4 pixels. -
VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NVspecifies a fragment size of 1x1 pixels, with two fragment shader invocations per fragment. -
VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NVspecifies a fragment size of 1x1 pixels, with four fragment shader invocations per fragment. -
VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NVspecifies a fragment size of 1x1 pixels, with eight fragment shader invocations per fragment. -
VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NVspecifies a fragment size of 1x1 pixels, with sixteen fragment shader invocations per fragment. -
VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NVspecifies that any portions of a primitive that use that shading rate should be discarded without invoking any fragment shader.
To use the shading rates
VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV,
VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV,
VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV, and
VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV as a pipeline,
primitive, or attachment shading rate, the
supersampleFragmentShadingRates feature must be enabled.
To use the shading rate VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV as
a pipeline, primitive, or attachment shading rate, the
noInvocationFragmentShadingRates feature must be enabled.
When using fragment shading rate enums, the pipeline fragment shading rate can be set on a per-draw basis by either setting the rate in a graphics pipeline, or dynamically via vkCmdSetFragmentShadingRateEnumNV.
The VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure is
defined as:
// Provided by VK_NV_fragment_shading_rate_enums
typedef struct VkPipelineFragmentShadingRateEnumStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkFragmentShadingRateTypeNV shadingRateType;
VkFragmentShadingRateNV shadingRate;
VkFragmentShadingRateCombinerOpKHR combinerOps[2];
} VkPipelineFragmentShadingRateEnumStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shadingRateTypespecifies a VkFragmentShadingRateTypeNV value indicating whether fragment shading rates are specified using fragment sizes or VkFragmentShadingRateNV enums. -
shadingRatespecifies a VkFragmentShadingRateNV value indicating the pipeline fragment shading rate. -
combinerOpsspecifies VkFragmentShadingRateCombinerOpKHR values determining how the pipeline, primitive, and attachment shading rates are combined for fragments generated by drawing commands using the created pipeline.
If the pNext chain of VkGraphicsPipelineCreateInfo includes a
VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure, then
that structure includes parameters controlling the pipeline fragment shading
rate.
If this structure is not present, shadingRateType is considered to be
equal to VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV,
shadingRate is considered to be equal to
VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV, and both elements
of combinerOps are considered to be equal to
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR.
The VkFragmentShadingRateTypeNV enumerated type specifies whether a graphics pipeline gets its pipeline fragment shading rates and combiners from the VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure or the VkPipelineFragmentShadingRateStateCreateInfoKHR structure.
// Provided by VK_NV_fragment_shading_rate_enums
typedef enum VkFragmentShadingRateTypeNV {
VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV = 0,
VK_FRAGMENT_SHADING_RATE_TYPE_ENUMS_NV = 1,
} VkFragmentShadingRateTypeNV;
-
VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NVspecifies that a graphics pipeline should obtain its pipeline fragment shading rate and shading rate combiner state from the VkPipelineFragmentShadingRateStateCreateInfoKHR structure and that any state specified by the VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure should be ignored. -
VK_FRAGMENT_SHADING_RATE_TYPE_ENUMS_NVspecifies that a graphics pipeline should obtain its pipeline fragment shading rate and shading rate combiner state from the VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure and that any state specified by the VkPipelineFragmentShadingRateStateCreateInfoKHR structure should be ignored.
To dynamically set the pipeline fragment shading rate and combiner operation, call:
// Provided by VK_NV_fragment_shading_rate_enums
void vkCmdSetFragmentShadingRateEnumNV(
VkCommandBuffer commandBuffer,
VkFragmentShadingRateNV shadingRate,
const VkFragmentShadingRateCombinerOpKHR combinerOps[2]);
-
commandBufferis the command buffer into which the command will be recorded. -
shadingRatespecifies a VkFragmentShadingRateNV enum indicating the pipeline fragment shading rate for subsequent drawing commands. -
combinerOpsspecifies a VkFragmentShadingRateCombinerOpKHR determining how the pipeline, primitive, and attachment shading rates are combined for fragments generated by subsequent drawing commands.
This command sets the pipeline fragment shading rate and combiner operation
for subsequent drawing commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineFragmentShadingRateEnumStateCreateInfoNV values used to
create the currently active pipeline.
|
Note
This command allows specifying additional shading rates beyond those
supported by vkCmdSetFragmentShadingRateKHR.
For more information, refer to the
|
When the supersampleFragmentShadingRates or
noInvocationFragmentShadingRates features are enabled, the behavior
of the shading rate combiner
operations is extended to support the shading rates enabled by those
features.
Primitive and attachment shading rate values are interpreted as
VkFragmentShadingRateNV values and the behavior of the combiners is
modified as follows:
-
For
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR,VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR, andVK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR, if either Axy or Bxy isVK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV, combine(Axy,Bxy) produces a shading rate ofVK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV, regardless of the other input shading rate. -
For
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR, combine(Axy,Bxy) produces a shading rate whose fragment size is the smaller of the fragment sizes of Axy and Bxy and whose invocation count is the larger of the invocation counts of Axy and Bxy. -
For
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR, combine(Axy,Bxy) produces a shading rate whose fragment size is the larger of the fragment sizes of Axy and Bxy and whose invocation count is the smaller of the invocation counts of Axy and Bxy. -
For
VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR, combine(Axy,Bxy) produces a shading rate whose fragment size and invocation count is the product of the fragment sizes and invocation counts, respectively, of Axy and Bxy. If the resulting shading rate has both multiple pixels and multiple invocations per fragment, an implementation may adjust the shading rate by reducing both the pixel and invocation counts.
If the final shading rate from the combiners is
VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV, no fragments will be
generated for any portion of a primitive using that shading rate.
If the final shading rate from the combiners specifies multiple fragment
shader invocations per fragment, the fragment will be processed with
multiple unique samples as in sample shading,
where the total number the total number of invocations is taken from the
shading rate and then clamped to rasterizationSamples and
maxFragmentShadingRateInvocationCount.
27.7. Shading Rate Image
The shadingRateImage feature allows
pipelines to use a shading rate image to
control the fragment area and the minimum number
of fragment shader invocations launched for each fragment.
When the shading rate image is enabled, the rasterizer determines a base
shading rate for each region of the framebuffer
covered by a primitive by fetching a value from the shading rate image and
translating it to a shading rate using a per-viewport shading rate palette.
This base shading rate is then adjusted to derive a final shading rate.
The final shading rate specifies the fragment area and fragment shader
invocation count to use for fragments generated in the region.
If the pNext chain of VkPipelineViewportStateCreateInfo includes
a VkPipelineViewportShadingRateImageStateCreateInfoNV structure, then
that structure includes parameters controlling the shading rate.
The VkPipelineViewportShadingRateImageStateCreateInfoNV structure is
defined as:
// Provided by VK_NV_shading_rate_image
typedef struct VkPipelineViewportShadingRateImageStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 shadingRateImageEnable;
uint32_t viewportCount;
const VkShadingRatePaletteNV* pShadingRatePalettes;
} VkPipelineViewportShadingRateImageStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shadingRateImageEnablespecifies whether shading rate image and palettes are used during rasterization. -
viewportCountspecifies the number of per-viewport palettes used to translate values stored in shading rate images. -
pShadingRatePalettesis a pointer to an array of VkShadingRatePaletteNV structures defining the palette for each viewport. If the shading rate palette state is dynamic, this member is ignored.
If this structure is not present, shadingRateImageEnable is considered
to be VK_FALSE, and the shading rate image and palettes are not used.
When shading rate image usage is enabled in the bound pipeline, the pipeline uses a shading rate image specified by the command:
// Provided by VK_NV_shading_rate_image
void vkCmdBindShadingRateImageNV(
VkCommandBuffer commandBuffer,
VkImageView imageView,
VkImageLayout imageLayout);
-
commandBufferis the command buffer into which the command will be recorded. -
imageViewis an image view handle specifying the shading rate image.imageViewmay be set to VK_NULL_HANDLE, which is equivalent to specifying a view of an image filled with zero values. -
imageLayoutis the layout that the image subresources accessible fromimageViewwill be in when the shading rate image is accessed.
When the shading rate image is enabled in the current pipeline, rasterizing
a primitive covering the pixel with coordinates (x,y) will fetch a
shading rate index value from the shading rate image bound by
vkCmdBindShadingRateImageNV.
If the shading rate image view has a type of VK_IMAGE_VIEW_TYPE_2D,
the lookup will use texel coordinates (u,v) where , , and and
are the width and height of the implementation-dependent
shading rate texel size.
If the shading rate image view has a type of
VK_IMAGE_VIEW_TYPE_2D_ARRAY, the lookup will use texel coordinates
(u,v) to extract a texel from the layer l, where l is the layer of
the framebuffer being rendered to.
If l is greater than or equal to the number of layers in the image view,
layer zero will be used.
If the bound shading rate image view is not VK_NULL_HANDLE and
contains a texel with coordinates (u,v) in layer l (if applicable),
the single unsigned integer component for that texel will be used as the
shading rate index.
If the (u,v) coordinate is outside the extents of the subresource used
by the shading rate image view, or if the image view is
VK_NULL_HANDLE, the shading rate index is zero.
If the shading rate image view has multiple mipmap levels, the base level
identified by VkImageSubresourceRange::baseMipLevel will be
used.
A shading rate index is mapped to a base shading rate using a lookup table called the shading rate image palette. There is a separate palette for each viewport. The number of entries in each palette is given by the implementation-dependent shading rate image palette size.
To dynamically set the per-viewport shading rate image palettes, call:
// Provided by VK_NV_shading_rate_image
void vkCmdSetViewportShadingRatePaletteNV(
VkCommandBuffer commandBuffer,
uint32_t firstViewport,
uint32_t viewportCount,
const VkShadingRatePaletteNV* pShadingRatePalettes);
-
commandBufferis the command buffer into which the command will be recorded. -
firstViewportis the index of the first viewport whose shading rate palette is updated by the command. -
viewportCountis the number of viewports whose shading rate palettes are updated by the command. -
pShadingRatePalettesis a pointer to an array of VkShadingRatePaletteNV structures defining the palette for each viewport.
This command sets the per-viewport shading rate image palettes for
subsequent drawing commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportShadingRateImageStateCreateInfoNV::pShadingRatePalettes
values used to create the currently active pipeline.
The VkShadingRatePaletteNV structure specifies to contents of a single
shading rate image palette and is defined as:
// Provided by VK_NV_shading_rate_image
typedef struct VkShadingRatePaletteNV {
uint32_t shadingRatePaletteEntryCount;
const VkShadingRatePaletteEntryNV* pShadingRatePaletteEntries;
} VkShadingRatePaletteNV;
-
shadingRatePaletteEntryCountspecifies the number of entries in the shading rate image palette. -
pShadingRatePaletteEntriesis a pointer to an array of VkShadingRatePaletteEntryNV enums defining the shading rate for each palette entry.
To determine the base shading rate image, a shading rate index i is mapped
to array element i in the array pShadingRatePaletteEntries for the
palette corresponding to the viewport used for the fragment.
If i is greater than or equal to the palette size
shadingRatePaletteEntryCount, the base shading rate is undefined.
The supported shading rate image palette entries are defined by VkShadingRatePaletteEntryNV:
// Provided by VK_NV_shading_rate_image
typedef enum VkShadingRatePaletteEntryNV {
VK_SHADING_RATE_PALETTE_ENTRY_NO_INVOCATIONS_NV = 0,
VK_SHADING_RATE_PALETTE_ENTRY_16_INVOCATIONS_PER_PIXEL_NV = 1,
VK_SHADING_RATE_PALETTE_ENTRY_8_INVOCATIONS_PER_PIXEL_NV = 2,
VK_SHADING_RATE_PALETTE_ENTRY_4_INVOCATIONS_PER_PIXEL_NV = 3,
VK_SHADING_RATE_PALETTE_ENTRY_2_INVOCATIONS_PER_PIXEL_NV = 4,
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_PIXEL_NV = 5,
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X1_PIXELS_NV = 6,
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_1X2_PIXELS_NV = 7,
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X2_PIXELS_NV = 8,
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_4X2_PIXELS_NV = 9,
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X4_PIXELS_NV = 10,
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_4X4_PIXELS_NV = 11,
} VkShadingRatePaletteEntryNV;
The following table indicates the width and height (in pixels) of each
fragment generated using the indicated shading rate, as well as the maximum
number of fragment shader invocations launched for each fragment.
When processing regions of a primitive that have a shading rate of
VK_SHADING_RATE_PALETTE_ENTRY_NO_INVOCATIONS_NV, no fragments will be
generated in that region.
| Shading Rate | Width | Height | Invocations |
|---|---|---|---|
|
0 |
0 |
0 |
|
1 |
1 |
16 |
|
1 |
1 |
8 |
|
1 |
1 |
4 |
|
1 |
1 |
2 |
|
1 |
1 |
1 |
|
2 |
1 |
1 |
|
1 |
2 |
1 |
|
2 |
2 |
1 |
|
4 |
2 |
1 |
|
2 |
4 |
1 |
|
4 |
4 |
1 |
When the shading rate image is disabled, a shading rate of
VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_PIXEL_NV will be used
as the base shading rate.
Once a base shading rate has been established, it is adjusted to produce a final shading rate. First, if the base shading rate uses multiple pixels for each fragment, the implementation may reduce the fragment area to ensure that the total number of coverage samples for all pixels in a fragment does not exceed an implementation-dependent maximum.
If sample shading is active in the current pipeline and would result in processing n (n > 1) unique samples per fragment when the shading rate image is disabled, the shading rate is adjusted in an implementation-dependent manner to increase the number of fragment shader invocations spawned by the primitive. If the shading rate indicates fs pixels per fragment and fs is greater than n, the fragment area is adjusted so each fragment has approximately pixels. Otherwise, if the shading rate indicates ipf invocations per fragment, the fragment area will be adjusted to a single pixel with approximately invocations per fragment.
If sample shading occurs due to the use of a fragment shader input variable
decorated with SampleId or SamplePosition, the shading rate is
ignored.
Each fragment will have a single pixel and will spawn up to
rasterizationSamples fragment shader invocations, as when using
sample shading without a shading rate image.
Finally, if the shading rate specifies multiple fragment shader invocations
per fragment, the total number of invocations in the shading rate is clamped
to be no larger than rasterizationSamples.
When the final shading rate for a primitive covering pixel (x,y) has a fragment area of , the fragment for that pixel will cover all pixels with coordinates (x',y') that satisfy the equations:
This combined fragment is considered to have multiple coverage samples; the
total number of samples in this fragment is given by where rs indicates the value of
VkPipelineMultisampleStateCreateInfo::rasterizationSamples
specified at pipeline creation time.
The set of coverage samples in the fragment is the union of the per-pixel
coverage samples in each of the fragment’s pixels The location and order of
coverage samples within each pixel in the combined fragment are assigned as
described in
Multisampling and Custom Sample Locations.
Each coverage sample in the set of pixels belonging to the combined fragment
is assigned a unique coverage
index in the range [0,samples-1].
If the shadingRateCoarseSampleOrder feature is supported, the order of
coverage samples can be specified for each combination of fragment area and
coverage sample count.
If this feature is not supported, the sample order is
implementation-dependent.
If the pNext chain of VkPipelineViewportStateCreateInfo includes
a VkPipelineViewportCoarseSampleOrderStateCreateInfoNV structure, then
that structure includes parameters controlling the order of coverage samples
in fragments larger than one pixel.
The VkPipelineViewportCoarseSampleOrderStateCreateInfoNV structure is
defined as:
// Provided by VK_NV_shading_rate_image
typedef struct VkPipelineViewportCoarseSampleOrderStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkCoarseSampleOrderTypeNV sampleOrderType;
uint32_t customSampleOrderCount;
const VkCoarseSampleOrderCustomNV* pCustomSampleOrders;
} VkPipelineViewportCoarseSampleOrderStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sampleOrderTypespecifies the mechanism used to order coverage samples in fragments larger than one pixel. -
customSampleOrderCountspecifies the number of custom sample orderings to use when ordering coverage samples. -
pCustomSampleOrdersis a pointer to an array ofcustomSampleOrderCountVkCoarseSampleOrderCustomNV structures, each structure specifying the coverage sample order for a single combination of fragment area and coverage sample count.
If this structure is not present, sampleOrderType is considered to be
VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV.
If sampleOrderType is VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV, the
coverage sample order used for any combination of fragment area and coverage
sample count not enumerated in pCustomSampleOrders will be identical
to that used for VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV.
If the pipeline was created with
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV, the contents of this
structure (if present) are ignored, and the coverage sample order is instead
specified by vkCmdSetCoarseSampleOrderNV.
The type VkCoarseSampleOrderTypeNV specifies the technique used to order coverage samples in fragments larger than one pixel, and is defined as:
// Provided by VK_NV_shading_rate_image
typedef enum VkCoarseSampleOrderTypeNV {
VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV = 0,
VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV = 1,
VK_COARSE_SAMPLE_ORDER_TYPE_PIXEL_MAJOR_NV = 2,
VK_COARSE_SAMPLE_ORDER_TYPE_SAMPLE_MAJOR_NV = 3,
} VkCoarseSampleOrderTypeNV;
-
VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NVspecifies that coverage samples will be ordered in an implementation-dependent manner. -
VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NVspecifies that coverage samples will be ordered according to the array of custom orderings provided in either thepCustomSampleOrdersmember ofVkPipelineViewportCoarseSampleOrderStateCreateInfoNVor thepCustomSampleOrdersmember of vkCmdSetCoarseSampleOrderNV. -
VK_COARSE_SAMPLE_ORDER_TYPE_PIXEL_MAJOR_NVspecifies that coverage samples will be ordered sequentially, sorted first by pixel coordinate (in row-major order) and then by sample index. -
VK_COARSE_SAMPLE_ORDER_TYPE_SAMPLE_MAJOR_NVspecifies that coverage samples will be ordered sequentially, sorted first by sample index and then by pixel coordinate (in row-major order).
When using a coarse sample order of
VK_COARSE_SAMPLE_ORDER_TYPE_PIXEL_MAJOR_NV for a fragment with an
upper-left corner of with a width of and samples per pixel,
coverage index of
the fragment will be assigned to sample index of pixel as follows:
When using a coarse sample order of
VK_COARSE_SAMPLE_ORDER_TYPE_SAMPLE_MAJOR_NV,
coverage index
will be assigned as follows:
The VkCoarseSampleOrderCustomNV structure is defined as:
// Provided by VK_NV_shading_rate_image
typedef struct VkCoarseSampleOrderCustomNV {
VkShadingRatePaletteEntryNV shadingRate;
uint32_t sampleCount;
uint32_t sampleLocationCount;
const VkCoarseSampleLocationNV* pSampleLocations;
} VkCoarseSampleOrderCustomNV;
-
shadingRateis a shading rate palette entry that identifies the fragment width and height for the combination of fragment area and per-pixel coverage sample count to control. -
sampleCountidentifies the per-pixel coverage sample count for the combination of fragment area and coverage sample count to control. -
sampleLocationCountspecifies the number of sample locations in the custom ordering. -
pSampleLocationsis a pointer to an array of VkCoarseSampleLocationNV structures specifying the location of each sample in the custom ordering.
The VkCoarseSampleOrderCustomNV structure is used with a coverage
sample ordering type of VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV to
specify the order of coverage samples for one combination of fragment width,
fragment height, and coverage sample count.
When using a custom sample ordering, element j in pSampleLocations
specifies a specific pixel location and
sample index that corresponds to
coverage index j in the
multi-pixel fragment.
The VkCoarseSampleLocationNV structure identifies a specific pixel and
sample index for one of the
coverage samples in a fragment that is larger than one pixel.
This structure is defined as:
// Provided by VK_NV_shading_rate_image
typedef struct VkCoarseSampleLocationNV {
uint32_t pixelX;
uint32_t pixelY;
uint32_t sample;
} VkCoarseSampleLocationNV;
-
pixelXis added to the x coordinate of the upper-leftmost pixel of each fragment to identify the pixel containing the coverage sample. -
pixelYis added to the y coordinate of the upper-leftmost pixel of each fragment to identify the pixel containing the coverage sample. -
sampleis the number of the coverage sample in the pixel identified bypixelXandpixelY.
To dynamically set the order of coverage samples in fragments larger than one pixel, call:
// Provided by VK_NV_shading_rate_image
void vkCmdSetCoarseSampleOrderNV(
VkCommandBuffer commandBuffer,
VkCoarseSampleOrderTypeNV sampleOrderType,
uint32_t customSampleOrderCount,
const VkCoarseSampleOrderCustomNV* pCustomSampleOrders);
-
commandBufferis the command buffer into which the command will be recorded. -
sampleOrderTypespecifies the mechanism used to order coverage samples in fragments larger than one pixel. -
customSampleOrderCountspecifies the number of custom sample orderings to use when ordering coverage samples. -
pCustomSampleOrdersis a pointer to an array of VkCoarseSampleOrderCustomNV structures, each structure specifying the coverage sample order for a single combination of fragment area and coverage sample count.
If sampleOrderType is VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV, the
coverage sample order used for any combination of fragment area and coverage
sample count not enumerated in pCustomSampleOrders will be identical
to that used for VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV.
This command sets the order of coverage samples for subsequent drawing
commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportCoarseSampleOrderStateCreateInfoNV values used to
create the currently active pipeline.
If the final shading rate for a primitive covering pixel (x,y) results in n invocations per pixel (n > 1), n separate fragment shader invocations will be generated for the fragment. Each coverage sample in the fragment will be assigned to one of the n fragment shader invocations in an implementation-dependent manner. The outputs from the fragment output interface of each shader invocation will be broadcast to all of the framebuffer samples associated with the invocation. If none of the coverage samples associated with a fragment shader invocation is covered by a primitive, the implementation may discard the fragment shader invocation for those samples.
If the final shading rate for a primitive covering pixel (x,y) results in a fragment containing multiple pixels, a single set of fragment shader invocations will be generated for all pixels in the combined fragment. Outputs from the fragment output interface will be broadcast to all covered framebuffer samples belonging to the fragment. If the fragment shader executes code discarding the fragment, none of the samples of the fragment will be updated.
27.8. Sample Shading
Sample shading can be used to specify a minimum number of unique samples to
process for each fragment.
If sample shading is enabled, an implementation must invoke the fragment
shader at least max(⌈
VkPipelineMultisampleStateCreateInfo::minSampleShading ×
VkPipelineMultisampleStateCreateInfo::rasterizationSamples
⌉, 1) times per fragment.
If a fragment shader entry point’s interface includes an input variable
decorated with a BuiltIn of SampleId or SamplePosition, a
value of 1.0 is used instead of minSampleShading.
If the VK_AMD_mixed_attachment_samples extension is enabled and the
subpass uses color attachments, the samples value used to create each
color attachment is used instead of rasterizationSamples.
Sample shading is enabled if at least one of the following conditions is true:
-
VkPipelineMultisampleStateCreateInfo::
sampleShadingEnableis set toVK_TRUE, or -
the fragment shader’s entry point interface includes input variables decorated with a
BuiltInofSampleIdorSamplePositionbuilt-ins.
If there are fewer invocations than covered samples, implementations may include those samples in fragment shader invocations in any manner as long as covered samples are all shaded at least once.
27.9. Barycentric Interpolation
When the fragmentShaderBarycentric feature is enabled, the
PerVertexKHR interpolation
decoration can be used with fragment shader inputs to indicate that the
decorated inputs do not have associated data in the fragment.
Such inputs can only be accessed in a fragment shader using an array index
whose value (0, 1, or 2) identifies one of the vertices of the primitive
that produced the fragment.
Reads of per-vertex values for missing vertices, such as the third vertex of
a line primitive, will return values from the valid vertex with the highest
index.
This means that the per-vertex values of indices 1 and 2 for point
primitives will be equal to those of index 0, and the per-vertex values of
index 2 for line primitives will be equal to those of index 1.
When tessellation, geometry shading, and
mesh shading
are not active, fragment shader inputs decorated with PerVertexKHR will
take values from one of the vertices of the primitive that produced the
fragment, identified by the extra index provided in SPIR-V code accessing
the input.
If the n vertices passed to a draw call are numbered 0 through n-1, and
the point, line, and triangle primitives produced by the draw call are
numbered with consecutive integers beginning with zero, the following table
indicates the original vertex numbers used
when the provoking vertex mode is
VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT
for index values of 0, 1, and 2.
If an input decorated with PerVertexKHR is accessed with any other
vertex index value, or is accessed while rasterizing a polygon when the
VkPipelineRasterizationStateCreateInfo::polygonMode property of
the currently active pipeline is not VK_POLYGON_MODE_FILL, an
undefined value is returned.
| Primitive Topology | Vertex 0 | Vertex 1 | Vertex 2 |
|---|---|---|---|
|
i |
i |
i |
|
2i |
2i+1 |
2i+1 |
|
i |
i+1 |
i+1 |
|
3i |
3i+1 |
3i+2 |
|
i |
i+1 |
i+2 |
|
i |
i+2 |
i+1 |
|
i+1 |
i+2 |
0 |
|
4i+1 |
4i+2 |
4i+2 |
|
i+1 |
i+2 |
i+2 |
|
6i |
6i+2 |
6i+4 |
|
2i |
2i+2 |
2i+4 |
|
2i |
2i+4 |
2i+2 |
When the provoking vertex mode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the original vertex numbers
used are the same as above except as indicated in the table below.
| Primitive Topology | Vertex 0 | Vertex 1 | Vertex 2 |
|---|---|---|---|
|
i+1 |
i |
i+2 |
|
0 |
i+1 |
i+2 |
|
2i+2 |
2i |
2i+4 |
When geometry
or mesh
shading is active, primitives processed by fragment shaders are assembled
from the vertices emitted by the geometry
or mesh
shader.
In this case, the vertices used for fragment shader inputs decorated with
PerVertexKHR are derived by treating the primitives produced by the
shader as though they were specified by a draw call and consulting
the table above.
When using tessellation without geometry shading, the tessellator produces
primitives in an implementation-dependent manner.
While there is no defined vertex ordering for inputs decorated with
PerVertexKHR, the vertex ordering used in this case will be consistent
with the ordering used to derive the values of inputs decorated with
BaryCoordKHR or BaryCoordNoPerspKHR.
Fragment shader inputs decorated with BaryCoordKHR or
BaryCoordNoPerspKHR hold three-component vectors with barycentric
weights that indicate the location of the fragment relative to the
screen-space locations of vertices of its primitive.
For point primitives, such variables are always assigned the value (1,0,0).
For line primitives, the built-ins are obtained
by interpolating an attribute whose values for the vertices numbered 0 and 1
are (1,0,0) and (0,1,0), respectively.
For polygon primitives, the built-ins are
obtained by interpolating an attribute whose values for the vertices
numbered 0, 1, and 2 are (1,0,0), (0,1,0), and (0,0,1), respectively.
For BaryCoordKHR, the values are obtained using perspective
interpolation.
For BaryCoordNoPerspKHR, the values are obtained using linear
interpolation.
The values of BaryCoordKHR and BaryCoordNoPerspKHR are undefined
while rasterizing a polygon when the
VkPipelineRasterizationStateCreateInfo::polygonMode property of
the currently active pipeline is not VK_POLYGON_MODE_FILL.
27.10. Points
A point is drawn by generating a set of fragments in the shape of a square
centered around the vertex of the point.
Each vertex has an associated point size controlling the width/height of
that square.
The point size is taken from the (potentially clipped) shader built-in
PointSize written by:
-
the geometry shader, if active;
-
the tessellation evaluation shader, if active and no geometry shader is active;
-
the vertex shader, otherwise
and clamped to the implementation-dependent point size range
[pointSizeRange[0],pointSizeRange[1]].
The value written to PointSize must be greater than zero.
Not all point sizes need be supported, but the size 1.0 must be supported.
The range of supported sizes and the size of evenly-spaced gradations within
that range are implementation-dependent.
The range and gradations are obtained from the pointSizeRange and
pointSizeGranularity members of VkPhysicalDeviceLimits.
If, for instance, the size range is from 0.1 to 2.0 and the gradation size
is 0.1, then the sizes 0.1, 0.2, …, 1.9, 2.0 are supported.
Additional point sizes may also be supported.
There is no requirement that these sizes be equally spaced.
If an unsupported size is requested, the nearest supported size is used
instead.
Further, if the render pass has a fragment density map attachment, point size may be rounded by the implementation to a multiple of the fragment’s width or height.
27.10.1. Basic Point Rasterization
Point rasterization produces a fragment for each fragment area group of
framebuffer pixels with one or more sample points that intersect a region
centered at the point’s (xf,yf).
This region is a square with side equal to the current point size.
Coverage bits that correspond to sample points that intersect the region are
1, other coverage bits are 0.
All fragments produced in rasterizing a point are assigned the same
associated data, which are those of the vertex corresponding to the point.
However, the fragment shader built-in PointCoord contains point sprite
texture coordinates.
The s and t point sprite texture coordinates vary from zero to
one across the point horizontally left-to-right and vertically
top-to-bottom, respectively.
The following formulas are used to evaluate s and t:
where size is the point’s size; (xp,yp) is the location at which the point sprite coordinates are evaluated - this may be the framebuffer coordinates of the fragment center, or the location of a sample; and (xf,yf) is the exact, unrounded framebuffer coordinate of the vertex for the point.
27.11. Line Segments
Line segment rasterization options are controlled by the VkPipelineRasterizationLineStateCreateInfoEXT structure.
The VkPipelineRasterizationLineStateCreateInfoEXT structure is defined
as:
// Provided by VK_EXT_line_rasterization
typedef struct VkPipelineRasterizationLineStateCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkLineRasterizationModeEXT lineRasterizationMode;
VkBool32 stippledLineEnable;
uint32_t lineStippleFactor;
uint16_t lineStipplePattern;
} VkPipelineRasterizationLineStateCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
lineRasterizationModeis a VkLineRasterizationModeEXT value selecting the style of line rasterization. -
stippledLineEnableenables stippled line rasterization. -
lineStippleFactoris the repeat factor used in stippled line rasterization. -
lineStipplePatternis the bit pattern used in stippled line rasterization.
If stippledLineEnable is VK_FALSE, the values of
lineStippleFactor and lineStipplePattern are ignored.
Possible values of
VkPipelineRasterizationLineStateCreateInfoEXT::lineRasterizationMode
are:
// Provided by VK_EXT_line_rasterization
typedef enum VkLineRasterizationModeEXT {
VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT = 0,
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT = 1,
VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT = 2,
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT = 3,
} VkLineRasterizationModeEXT;
-
VK_LINE_RASTERIZATION_MODE_DEFAULT_EXTis equivalent toVK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXTif VkPhysicalDeviceLimits::strictLinesisVK_TRUE, otherwise lines are drawn as non-strictLinesparallelograms. Both of these modes are defined in Basic Line Segment Rasterization. -
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXTspecifies lines drawn as if they were rectangles extruded from the line -
VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXTspecifies lines drawn by determining which pixel diamonds the line intersects and exits, as defined in Bresenham Line Segment Rasterization. -
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXTspecifies lines drawn if they were rectangles extruded from the line, with alpha falloff, as defined in Smooth Lines.
To dynamically set the line width, call:
// Provided by VK_VERSION_1_0
void vkCmdSetLineWidth(
VkCommandBuffer commandBuffer,
float lineWidth);
-
commandBufferis the command buffer into which the command will be recorded. -
lineWidthis the width of rasterized line segments.
This command sets the line width for subsequent drawing commands when the
graphics pipeline is created with VK_DYNAMIC_STATE_LINE_WIDTH set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationStateCreateInfo::lineWidth value used to
create the currently active pipeline.
Not all line widths need be supported for line segment rasterization, but
width 1.0 antialiased segments must be provided.
The range and gradations are obtained from the lineWidthRange and
lineWidthGranularity members of VkPhysicalDeviceLimits.
If, for instance, the size range is from 0.1 to 2.0 and the gradation size
is 0.1, then the sizes 0.1, 0.2, …, 1.9, 2.0 are supported.
Additional line widths may also be supported.
There is no requirement that these widths be equally spaced.
If an unsupported width is requested, the nearest supported width is used
instead.
Further, if the render pass has a fragment density map attachment, line width may be rounded by the implementation to a multiple of the fragment’s width or height.
27.11.1. Basic Line Segment Rasterization
If the lineRasterizationMode member of
VkPipelineRasterizationLineStateCreateInfoEXT is
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, rasterized
line segments produce fragments which intersect a rectangle centered on the
line segment.
Two of the edges are parallel to the specified line segment; each is at a
distance of one-half the current width from that segment in directions
perpendicular to the direction of the line.
The other two edges pass through the line endpoints and are perpendicular to
the direction of the specified line segment.
Coverage bits that correspond to sample points that intersect the rectangle
are 1, other coverage bits are 0.
Next we specify how the data associated with each rasterized fragment are
obtained.
Let pr = (xd, yd) be the framebuffer coordinates at which
associated data are evaluated.
This may be the center of a fragment or the location of a sample within the
fragment.
When rasterizationSamples is VK_SAMPLE_COUNT_1_BIT, the fragment
center must be used.
Let pa = (xa, ya) and pb = (xb,yb) be
initial and final endpoints of the line segment, respectively.
Set
(Note that t = 0 at pa and t = 1 at pb. Also note that this calculation projects the vector from pa to pr onto the line, and thus computes the normalized distance of the fragment along the line.)
If strictLines is VK_TRUE, line segments
are rasterized using perspective or linear interpolation.
Perspective interpolation for a line segment interpolates two values in a manner that is correct when taking the perspective of the viewport into consideration, by way of the line segment’s clip coordinates. An interpolated value f can be determined by
where fa and fb are the data associated with the starting and ending endpoints of the segment, respectively; wa and wb are the clip w coordinates of the starting and ending endpoints of the segment, respectively.
Linear interpolation for a line segment directly interpolates two values, and an interpolated value f can be determined by
-
f = (1 - t) fa + t fb
where fa and fb are the data associated with the starting and ending endpoints of the segment, respectively.
The clip coordinate w for a sample is determined using perspective interpolation. The depth value z for a sample is determined using linear interpolation. Interpolation of fragment shader input values are determined by Interpolation decorations.
The above description documents the preferred method of line rasterization,
and must be used when
lineRasterizationMode is
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT.
When strictLines is VK_FALSE,
and when the lineRasterizationMode is
VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT,
the edges of the lines are generated as a parallelogram surrounding the
original line.
The major axis is chosen by noting the axis in which there is the greatest
distance between the line start and end points.
If the difference is equal in both directions then the X axis is chosen as
the major axis.
Edges 2 and 3 are aligned to the minor axis and are centered on the
endpoints of the line as in Non strict lines, and each is
lineWidth long.
Edges 0 and 1 are parallel to the line and connect the endpoints of edges 2
and 3.
Coverage bits that correspond to sample points that intersect the
parallelogram are 1, other coverage bits are 0.
Samples that fall exactly on the edge of the parallelogram follow the polygon rasterization rules.
Interpolation occurs as if the parallelogram was decomposed into two triangles where each pair of vertices at each end of the line has identical attributes.
Only when strictLines is VK_FALSE implementations may deviate
from the non-strict line algorithm described above in the following ways:
-
Implementations may instead interpolate each fragment according to the formula in Basic Line Segment Rasterization using the original line segment endpoints.
-
Rasterization of non-antialiased non-strict line segments may be performed using the rules defined in Bresenham Line Segment Rasterization.
27.11.2. Bresenham Line Segment Rasterization
If lineRasterizationMode is
VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT, then the following rules
replace the line rasterization rules defined in Basic Line Segment Rasterization.
Non-strict lines may also follow these rasterization rules for non-antialiased lines.
Line segment rasterization begins by characterizing the segment as either x-major or y-major. x-major line segments have slope in the closed interval [-1,1]; all other line segments are y-major (slope is determined by the segment’s endpoints). We specify rasterization only for x-major segments except in cases where the modifications for y-major segments are not self-evident.
Ideally, Vulkan uses a diamond-exit rule to determine those fragments that are produced by rasterizing a line segment. For each fragment f with center at framebuffer coordinates xf and yf, define a diamond-shaped region that is the intersection of four half planes:
Essentially, a line segment starting at pa and ending at pb produces those fragments f for which the segment intersects Rf, except if pb is contained in Rf.
To avoid difficulties when an endpoint lies on a boundary of Rf we (in principle) perturb the supplied endpoints by a tiny amount. Let pa and pb have framebuffer coordinates (xa, ya) and (xb, yb), respectively. Obtain the perturbed endpoints pa' given by (xa, ya) - (ε, ε2) and pb' given by (xb, yb) - (ε, ε2). Rasterizing the line segment starting at pa and ending at pb produces those fragments f for which the segment starting at pa' and ending on pb' intersects Rf, except if pb' is contained in Rf. ε is chosen to be so small that rasterizing the line segment produces the same fragments when δ is substituted for ε for any 0 < δ ≤ ε.
When pa and pb lie on fragment centers, this characterization of fragments reduces to Bresenham’s algorithm with one modification: lines produced in this description are “half-open”, meaning that the final fragment (corresponding to pb) is not drawn. This means that when rasterizing a series of connected line segments, shared endpoints will be produced only once rather than twice (as would occur with Bresenham’s algorithm).
Implementations may use other line segment rasterization algorithms, subject to the following rules:
-
The coordinates of a fragment produced by the algorithm must not deviate by more than one unit in either x or y framebuffer coordinates from a corresponding fragment produced by the diamond-exit rule.
-
The total number of fragments produced by the algorithm must not differ from that produced by the diamond-exit rule by no more than one.
-
For an x-major line, two fragments that lie in the same framebuffer-coordinate column must not be produced (for a y-major line, two fragments that lie in the same framebuffer-coordinate row must not be produced).
-
If two line segments share a common endpoint, and both segments are either x-major (both left-to-right or both right-to-left) or y-major (both bottom-to-top or both top-to-bottom), then rasterizing both segments must not produce duplicate fragments. Fragments also must not be omitted so as to interrupt continuity of the connected segments.
The actual width w of Bresenham lines is determined by rounding the
line width to the nearest integer, clamping it to the
implementation-dependent lineWidthRange (with both values rounded to
the nearest integer), then clamping it to be no less than 1.
Bresenham line segments of width other than one are rasterized by offsetting them in the minor direction (for an x-major line, the minor direction is y, and for a y-major line, the minor direction is x) and producing a row or column of fragments in the minor direction. If the line segment has endpoints given by (x0, y0) and (x1, y1) in framebuffer coordinates, the segment with endpoints and is rasterized, but instead of a single fragment, a column of fragments of height w (a row of fragments of length w for a y-major segment) is produced at each x (y for y-major) location. The lowest fragment of this column is the fragment that would be produced by rasterizing the segment of width 1 with the modified coordinates.
The preferred method of attribute interpolation for a wide line is to
generate the same attribute values for all fragments in the row or column
described above, as if the adjusted line was used for interpolation and
those values replicated to the other fragments, except for FragCoord
which is interpolated as usual.
Implementations may instead interpolate each fragment according to the
formula in Basic Line Segment Rasterization, using
the original line segment endpoints.
When Bresenham lines are being rasterized, sample locations may all be treated as being at the pixel center (this may affect attribute and depth interpolation).
|
Note
The sample locations described above are not used for determining coverage, they are only used for things like attribute interpolation. The rasterization rules that determine coverage are defined in terms of whether the line intersects pixels, as opposed to the point sampling rules used for other primitive types. So these rules are independent of the sample locations. One consequence of this is that Bresenham lines cover the same pixels regardless of the number of rasterization samples, and cover all samples in those pixels (unless masked out or killed). |
27.11.3. Line Stipple
If the stippledLineEnable member of
VkPipelineRasterizationLineStateCreateInfoEXT is VK_TRUE, then
lines are rasterized with a line stipple determined by
lineStippleFactor and lineStipplePattern.
lineStipplePattern is an unsigned 16-bit integer that determines which
fragments are to be drawn or discarded when the line is rasterized.
lineStippleFactor is a count that is used to modify the effective line
stipple by causing each bit in lineStipplePattern to be used
lineStippleFactor times.
Line stippling discards certain fragments that are produced by rasterization. The masking is achieved using three parameters: the 16-bit line stipple pattern p, the line stipple factor r, and an integer stipple counter s. Let
Then a fragment is produced if the b'th bit of p is 1, and discarded otherwise. The bits of p are numbered with 0 being the least significant and 15 being the most significant.
The initial value of s is zero.
For VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT lines, s is incremented
after production of each fragment of a line segment (fragments are produced
in order, beginning at the starting point and working towards the ending
point).
For VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT and
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT lines, the
rectangular region is subdivided into adjacent unit-length rectangles, and s
is incremented once for each rectangle.
Rectangles with a value of s such that the b'th bit of p is zero are
discarded.
If the last rectangle in a line segment is shorter than unit-length, then
the remainder may carry over to the next line segment in the line strip
using the same value of s (this is the preferred behavior, for the stipple
pattern to appear more consistent through the strip).
s is reset to 0 at the start of each strip (for line strips), and before every line segment in a group of independent segments.
If the line segment has been clipped, then the value of s at the beginning of the line segment is implementation-dependent.
To dynamically set the line stipple state, call:
// Provided by VK_EXT_line_rasterization
void vkCmdSetLineStippleEXT(
VkCommandBuffer commandBuffer,
uint32_t lineStippleFactor,
uint16_t lineStipplePattern);
-
commandBufferis the command buffer into which the command will be recorded. -
lineStippleFactoris the repeat factor used in stippled line rasterization. -
lineStipplePatternis the bit pattern used in stippled line rasterization.
This command sets the line stipple state for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_LINE_STIPPLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationLineStateCreateInfoEXT::lineStippleFactor
and
VkPipelineRasterizationLineStateCreateInfoEXT::lineStipplePattern
values used to create the currently active pipeline.
27.11.4. Smooth Lines
If the lineRasterizationMode member of
VkPipelineRasterizationLineStateCreateInfoEXT is
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then lines are
considered to be rectangles using the same geometry as for
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT lines.
The rules for determining which pixels are covered are
implementation-dependent, and may include nearby pixels where no sample
locations are covered or where the rectangle does not intersect the pixel at
all.
For each pixel that is considered covered, the fragment computes a coverage
value that approximates the area of the intersection of the rectangle with
the pixel square, and this coverage value is multiplied into the color
location 0’s alpha value after fragment shading, as described in
Multisample Coverage.
|
Note
The details of the rasterization rules and area calculation are left intentionally vague, to allow implementations to generate coverage and values that are aesthetically pleasing. |
27.12. Polygons
A polygon results from the decomposition of a triangle strip, triangle fan or a series of independent triangles. Like points and line segments, polygon rasterization is controlled by several variables in the VkPipelineRasterizationStateCreateInfo structure.
27.12.1. Basic Polygon Rasterization
The first step of polygon rasterization is to determine whether the triangle is back-facing or front-facing. This determination is made based on the sign of the (clipped or unclipped) polygon’s area computed in framebuffer coordinates. One way to compute this area is:
where and are the x and y framebuffer coordinates of the ith vertex of the n-vertex polygon (vertices are numbered starting at zero for the purposes of this computation) and i ⊕ 1 is (i + 1) mod n.
The interpretation of the sign of a is determined by the
VkPipelineRasterizationStateCreateInfo::frontFace property of
the currently active pipeline.
Possible values are:
// Provided by VK_VERSION_1_0
typedef enum VkFrontFace {
VK_FRONT_FACE_COUNTER_CLOCKWISE = 0,
VK_FRONT_FACE_CLOCKWISE = 1,
} VkFrontFace;
-
VK_FRONT_FACE_COUNTER_CLOCKWISEspecifies that a triangle with positive area is considered front-facing. -
VK_FRONT_FACE_CLOCKWISEspecifies that a triangle with negative area is considered front-facing.
Any triangle which is not front-facing is back-facing, including zero-area triangles.
To dynamically set the front face orientation, call:
// Provided by VK_VERSION_1_3
void vkCmdSetFrontFace(
VkCommandBuffer commandBuffer,
VkFrontFace frontFace);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetFrontFaceEXT(
VkCommandBuffer commandBuffer,
VkFrontFace frontFace);
-
commandBufferis the command buffer into which the command will be recorded. -
frontFaceis a VkFrontFace value specifying the front-facing triangle orientation to be used for culling.
This command sets the front face orientation for subsequent drawing commands
when the graphics pipeline is created with VK_DYNAMIC_STATE_FRONT_FACE
set in VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationStateCreateInfo::frontFace value used to
create the currently active pipeline.
Once the orientation of triangles is determined, they are culled according
to the VkPipelineRasterizationStateCreateInfo::cullMode property
of the currently active pipeline.
Possible values are:
// Provided by VK_VERSION_1_0
typedef enum VkCullModeFlagBits {
VK_CULL_MODE_NONE = 0,
VK_CULL_MODE_FRONT_BIT = 0x00000001,
VK_CULL_MODE_BACK_BIT = 0x00000002,
VK_CULL_MODE_FRONT_AND_BACK = 0x00000003,
} VkCullModeFlagBits;
-
VK_CULL_MODE_NONEspecifies that no triangles are discarded -
VK_CULL_MODE_FRONT_BITspecifies that front-facing triangles are discarded -
VK_CULL_MODE_BACK_BITspecifies that back-facing triangles are discarded -
VK_CULL_MODE_FRONT_AND_BACKspecifies that all triangles are discarded.
Following culling, fragments are produced for any triangles which have not been discarded.
// Provided by VK_VERSION_1_0
typedef VkFlags VkCullModeFlags;
VkCullModeFlags is a bitmask type for setting a mask of zero or more
VkCullModeFlagBits.
To dynamically set the cull mode, call:
// Provided by VK_VERSION_1_3
void vkCmdSetCullMode(
VkCommandBuffer commandBuffer,
VkCullModeFlags cullMode);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetCullModeEXT(
VkCommandBuffer commandBuffer,
VkCullModeFlags cullMode);
-
commandBufferis the command buffer into which the command will be recorded. -
cullModespecifies the cull mode property to use for drawing.
This command sets the cull mode for subsequent drawing commands when the
graphics pipeline is created with VK_DYNAMIC_STATE_CULL_MODE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationStateCreateInfo::cullMode value used to
create the currently active pipeline.
The rule for determining which fragments are produced by polygon rasterization is called point sampling. The two-dimensional projection obtained by taking the x and y framebuffer coordinates of the polygon’s vertices is formed. Fragments are produced for any fragment area groups of pixels for which any sample points lie inside of this polygon. Coverage bits that correspond to sample points that satisfy the point sampling criteria are 1, other coverage bits are 0. Special treatment is given to a sample whose sample location lies on a polygon edge. In such a case, if two polygons lie on either side of a common edge (with identical endpoints) on which a sample point lies, then exactly one of the polygons must result in a covered sample for that fragment during rasterization. As for the data associated with each fragment produced by rasterizing a polygon, we begin by specifying how these values are produced for fragments in a triangle.
Barycentric coordinates are a set of three numbers, a, b, and c, each in the range [0,1], with a + b + c = 1. These coordinates uniquely specify any point p within the triangle or on the triangle’s boundary as
-
p = a pa + b pb + c pc
where pa, pb, and pc are the vertices of the triangle. a, b, and c are determined by:
where A(lmn) denotes the area in framebuffer coordinates of the triangle with vertices l, m, and n.
Denote an associated datum at pa, pb, or pc as fa, fb, or fc, respectively.
Perspective interpolation for a triangle interpolates three values in a manner that is correct when taking the perspective of the viewport into consideration, by way of the triangle’s clip coordinates. An interpolated value f can be determined by
where wa, wb, and wc are the clip w coordinates of pa, pb, and pc, respectively. a, b, and c are the barycentric coordinates of the location at which the data are produced.
Linear interpolation for a triangle directly interpolates three values, and an interpolated value f can be determined by
-
f = a fa + b fb + c fc
where fa, fb, and fc are the data associated with pa, pb, and pc, respectively.
The clip coordinate w for a sample is determined using perspective interpolation. The depth value z for a sample is determined using linear interpolation. Interpolation of fragment shader input values are determined by Interpolation decorations.
For a polygon with more than three edges, such as are produced by clipping a triangle, a convex combination of the values of the datum at the polygon’s vertices must be used to obtain the value assigned to each fragment produced by the rasterization algorithm. That is, it must be the case that at every fragment
where n is the number of vertices in the polygon and fi is the value of f at vertex i. For each i, 0 ≤ ai ≤ 1 and . The values of ai may differ from fragment to fragment, but at vertex i, ai = 1 and aj = 0 for j ≠ i.
|
Note
One algorithm that achieves the required behavior is to triangulate a polygon (without adding any vertices) and then treat each triangle individually as already discussed. A scan-line rasterizer that linearly interpolates data along each edge and then linearly interpolates data across each horizontal span from edge to edge also satisfies the restrictions (in this case the numerator and denominator of perspective interpolation are iterated independently, and a division is performed for each fragment). |
27.12.2. Polygon Mode
Possible values of the
VkPipelineRasterizationStateCreateInfo::polygonMode property of
the currently active pipeline, specifying the method of rasterization for
polygons, are:
// Provided by VK_VERSION_1_0
typedef enum VkPolygonMode {
VK_POLYGON_MODE_FILL = 0,
VK_POLYGON_MODE_LINE = 1,
VK_POLYGON_MODE_POINT = 2,
// Provided by VK_NV_fill_rectangle
VK_POLYGON_MODE_FILL_RECTANGLE_NV = 1000153000,
} VkPolygonMode;
-
VK_POLYGON_MODE_POINTspecifies that polygon vertices are drawn as points. -
VK_POLYGON_MODE_LINEspecifies that polygon edges are drawn as line segments. -
VK_POLYGON_MODE_FILLspecifies that polygons are rendered using the polygon rasterization rules in this section. -
VK_POLYGON_MODE_FILL_RECTANGLE_NVspecifies that polygons are rendered using polygon rasterization rules, modified to consider a sample within the primitive if the sample location is inside the axis-aligned bounding box of the triangle after projection. Note that the barycentric weights used in attribute interpolation can extend outside the range [0,1] when these primitives are shaded. Special treatment is given to a sample position on the boundary edge of the bounding box. In such a case, if two rectangles lie on either side of a common edge (with identical endpoints) on which a sample position lies, then exactly one of the triangles must produce a fragment that covers that sample during rasterization.Polygons rendered in
VK_POLYGON_MODE_FILL_RECTANGLE_NVmode may be clipped by the frustum or by user clip planes. If clipping is applied, the triangle is culled rather than clipped.Area calculation and facingness are determined for
VK_POLYGON_MODE_FILL_RECTANGLE_NVmode using the triangle’s vertices.
These modes affect only the final rasterization of polygons: in particular, a polygon’s vertices are shaded and the polygon is clipped and possibly culled before these modes are applied.
27.12.3. Depth Bias
The depth values of all fragments generated by the rasterization of a polygon can be biased (offset) by a single depth bias value that is computed for that polygon.
Depth Bias Enable
The depth bias computation is enabled by the
depthBiasEnable set with vkCmdSetDepthBiasEnable
and vkCmdSetDepthBiasEnableEXT,
or the corresponding
VkPipelineRasterizationStateCreateInfo::depthBiasEnable value
used to create the currently active pipeline.
If the depth bias enable is VK_FALSE, no bias is applied and the
fragment’s depth values are unchanged.
To dynamically enable whether to bias fragment depth values, call:
// Provided by VK_VERSION_1_3
void vkCmdSetDepthBiasEnable(
VkCommandBuffer commandBuffer,
VkBool32 depthBiasEnable);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state2
void vkCmdSetDepthBiasEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 depthBiasEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
depthBiasEnablecontrols whether to bias fragment depth values.
This command sets the depth bias enable for subsequent drawing commands when
the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationStateCreateInfo::depthBiasEnable value
used to create the currently active pipeline.
Depth Bias Computation
The depth bias depends on three parameters:
-
depthBiasSlopeFactorscales the maximum depth slope m of the polygon -
depthBiasConstantFactorscales the minimum resolvable difference r of the depth attachment -
the scaled terms are summed to produce a value which is then clamped to a minimum or maximum value specified by
depthBiasClamp
depthBiasSlopeFactor, depthBiasConstantFactor, and
depthBiasClamp can each be positive, negative, or zero.
These parameters are set as described for vkCmdSetDepthBias below.
The maximum depth slope m of a triangle is
where (xf, yf, zf) is a point on the triangle. m may be approximated as
The minimum resolvable difference r is a parameter that depends on the
depth attachment representation.
It is the smallest difference in framebuffer coordinate z values that
is guaranteed to remain distinct throughout polygon rasterization and in the
depth attachment.
All pairs of fragments generated by the rasterization of two polygons with
otherwise identical vertices, but zf values that differ by
r, will have distinct depth values.
For fixed-point depth attachment representations, r is constant throughout the range of the entire depth attachment. Its value is implementation-dependent but must be at most
-
r = 2 × 2-n
for an n-bit buffer. For floating-point depth attachment, there is no single minimum resolvable difference. In this case, the minimum resolvable difference for a given polygon is dependent on the maximum exponent, e, in the range of z values spanned by the primitive. If n is the number of bits in the floating-point mantissa, the minimum resolvable difference, r, for the given primitive is defined as
-
r = 2e-n
If a triangle is rasterized using the
VK_POLYGON_MODE_FILL_RECTANGLE_NV polygon mode, then this minimum
resolvable difference may not be resolvable for samples outside of the
triangle, where the depth is extrapolated.
If no depth attachment is present, r is undefined.
The bias value o for a polygon is
m is computed as described above. If the depth attachment uses a fixed-point representation, m is a function of depth values in the range [0,1], and o is applied to depth values in the same range.
Depth bias is applied to triangle topology primitives received by the rasterizer regardless of polygon mode. Depth bias may also be applied to line and point topology primitives received by the rasterizer.
To dynamically set the depth bias parameters, call:
// Provided by VK_VERSION_1_0
void vkCmdSetDepthBias(
VkCommandBuffer commandBuffer,
float depthBiasConstantFactor,
float depthBiasClamp,
float depthBiasSlopeFactor);
-
commandBufferis the command buffer into which the command will be recorded. -
depthBiasConstantFactoris a scalar factor controlling the constant depth value added to each fragment. -
depthBiasClampis the maximum (or minimum) depth bias of a fragment. -
depthBiasSlopeFactoris a scalar factor applied to a fragment’s slope in depth bias calculations.
This command sets the depth bias parameters for subsequent drawing commands
when the graphics pipeline is created with VK_DYNAMIC_STATE_DEPTH_BIAS
set in VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the corresponding
VkPipelineRasterizationStateCreateInfo::depthBiasConstantFactor,
depthBiasClamp, and depthBiasSlopeFactor values used to create
the currently active pipeline.
27.12.4. Conservative Rasterization
If the pNext chain of VkPipelineRasterizationStateCreateInfo
includes a VkPipelineRasterizationConservativeStateCreateInfoEXT
structure, then that structure includes parameters controlling conservative
rasterization.
VkPipelineRasterizationConservativeStateCreateInfoEXT is defined as:
// Provided by VK_EXT_conservative_rasterization
typedef struct VkPipelineRasterizationConservativeStateCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkPipelineRasterizationConservativeStateCreateFlagsEXT flags;
VkConservativeRasterizationModeEXT conservativeRasterizationMode;
float extraPrimitiveOverestimationSize;
} VkPipelineRasterizationConservativeStateCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
conservativeRasterizationModeis the conservative rasterization mode to use. -
extraPrimitiveOverestimationSizeis the extra size in pixels to increase the generating primitive during conservative rasterization at each of its edges inXandYequally in screen space beyond the base overestimation specified inVkPhysicalDeviceConservativeRasterizationPropertiesEXT::primitiveOverestimationSize. IfconservativeRasterizationModeis notVK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT, this value is ignored.
If this structure is not included in the pNext chain,
conservativeRasterizationMode is considered to be
VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT, and and conservative
rasterization is disabled.
Polygon rasterization can be made conservative by setting
conservativeRasterizationMode to
VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT or
VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT in
VkPipelineRasterizationConservativeStateCreateInfoEXT.
|
Note
If |
// Provided by VK_EXT_conservative_rasterization
typedef VkFlags VkPipelineRasterizationConservativeStateCreateFlagsEXT;
VkPipelineRasterizationConservativeStateCreateFlagsEXT is a bitmask
type for setting a mask, but is currently reserved for future use.
Possible values of
VkPipelineRasterizationConservativeStateCreateInfoEXT::conservativeRasterizationMode,
specifying the conservative rasterization mode are:
// Provided by VK_EXT_conservative_rasterization
typedef enum VkConservativeRasterizationModeEXT {
VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT = 0,
VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT = 1,
VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT = 2,
} VkConservativeRasterizationModeEXT;
-
VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXTspecifies that conservative rasterization is disabled and rasterization proceeds as normal. -
VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXTspecifies that conservative rasterization is enabled in overestimation mode. -
VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXTspecifies that conservative rasterization is enabled in underestimation mode.
When overestimate conservative rasterization is enabled, rather than evaluating coverage at individual sample locations, a determination is made of whether any portion of the pixel (including its edges and corners) is covered by the primitive. If any portion of the pixel is covered, then all bits of the coverage mask for the fragment corresponding to that pixel are enabled. If the render pass has a fragment density map attachment and any bit of the coverage mask for the fragment is enabled, then all bits of the coverage mask for the fragment are enabled.
For the purposes of evaluating which pixels are covered by the primitive,
implementations can increase the size of the primitive by up to
VkPhysicalDeviceConservativeRasterizationPropertiesEXT::primitiveOverestimationSize
pixels at each of the primitive edges.
This may increase the number of fragments generated by this primitive and
represents an overestimation of the pixel coverage.
This overestimation size can be increased further by setting the
extraPrimitiveOverestimationSize value above 0.0 in steps of
VkPhysicalDeviceConservativeRasterizationPropertiesEXT::extraPrimitiveOverestimationSizeGranularity
up to and including
VkPhysicalDeviceConservativeRasterizationPropertiesEXT::extraPrimitiveOverestimationSize.
This will: further increase the number of fragments generated by this
primitive.
The actual precision of the overestimation size used for conservative
rasterization may vary between implementations and produce results that
only approximate the primitiveOverestimationSize and
extraPrimitiveOverestimationSizeGranularity properties.
Implementations may especially vary these approximations when the render
pass has a fragment density map and the fragment area covers multiple
pixels.
For triangles if VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT
is enabled, fragments will be generated if the primitive area covers any
portion of any pixel inside the fragment area, including their edges or
corners.
The tie-breaking rule described in Basic Polygon
Rasterization does not apply during conservative rasterization and
coverage is set for all fragments generated from shared edges of polygons.
Degenerate triangles that evaluate to zero area after rasterization, even
for pixels containing a vertex or edge of the zero-area polygon, will be
culled if
VkPhysicalDeviceConservativeRasterizationPropertiesEXT::degenerateTrianglesRasterized
is VK_FALSE or will generate fragments if
degenerateTrianglesRasterized is VK_TRUE.
The fragment input values for these degenerate triangles take their
attribute and depth values from the provoking vertex.
Degenerate triangles are considered backfacing and the application can
enable backface culling if desired.
Triangles that are zero area before rasterization may be culled regardless.
For lines if VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT is
enabled, and the implementation sets
VkPhysicalDeviceConservativeRasterizationPropertiesEXT::conservativePointAndLineRasterization
to VK_TRUE, fragments will be generated if the line covers any portion
of any pixel inside the fragment area, including their edges or corners.
Degenerate lines that evaluate to zero length after rasterization will be
culled if
VkPhysicalDeviceConservativeRasterizationPropertiesEXT::degenerateLinesRasterized
is VK_FALSE or will generate fragments if
degenerateLinesRasterized is VK_TRUE.
The fragments input values for these degenerate lines take their attribute
and depth values from the provoking vertex.
Lines that are zero length before rasterization may be culled regardless.
For points if VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT is
enabled, and the implementation sets
VkPhysicalDeviceConservativeRasterizationPropertiesEXT::conservativePointAndLineRasterization
to VK_TRUE, fragments will be generated if the point square covers any
portion of any pixel inside the fragment area, including their edges or
corners.
When underestimate conservative rasterization is enabled, rather than evaluating coverage at individual sample locations, a determination is made of whether all of the pixel (including its edges and corners) is covered by the primitive. If the entire pixel is covered, then a fragment is generated with all bits of its coverage mask corresponding to the pixel enabled, otherwise the pixel is not considered covered even if some portion of the pixel is covered. The fragment is discarded if no pixels inside the fragment area are considered covered. If the render pass has a fragment density map attachment and any pixel inside the fragment area is not considered covered, then the fragment is discarded even if some pixels are considered covered.
For triangles, if VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT
is enabled, fragments will only be generated if any pixel inside the
fragment area is fully covered by the generating primitive, including its
edges and corners.
For lines, if VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is
enabled, fragments will be generated if any pixel inside the fragment area,
including its edges and corners, are entirely covered by the line.
For points, if VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is
enabled, fragments will only be generated if the point square covers the
entirety of any pixel square inside the fragment area, including its edges
or corners.
If the render pass has a fragment density map and
VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is enabled,
fragments will only be generated if the entirety of all pixels inside the
fragment area are covered by the generating primitive, line, or point.
For both overestimate and underestimate conservative rasterization modes a
fragment has all of its pixel squares fully covered by the generating
primitive must set FullyCoveredEXT to VK_TRUE if the
implementation enables the
VkPhysicalDeviceConservativeRasterizationPropertiesEXT::fullyCoveredFragmentShaderInputVariable
feature.
When
the use of a shading rate image
or
setting the fragment shading rate
results in fragments covering multiple pixels, coverage for conservative
rasterization is still evaluated on a per-pixel basis and may result in
fragments with partial coverage.
For fragment shader inputs decorated with FullyCoveredEXT, a fragment
is considered fully covered if and only if all pixels in the fragment are
fully covered by the generating primitive.
28. Fragment Operations
Fragments produced by rasterization go through a number of operations to determine whether or how values produced by fragment shading are written to the framebuffer.
The following fragment operations adhere to rasterization order, and are typically performed in this order:
The coverage mask generated by
rasterization describes the initial coverage of each sample covered by the
fragment.
Fragment operations will update the coverage mask to add or subtract
coverage where appropriate.
If a fragment operation results in all bits of the coverage mask being 0,
the fragment is discarded, and no further operations are performed.
Fragments can also be programmatically discarded in a fragment shader by
executing one of
-
OpTerminateInvocation -
OpDemoteToHelperInvocationEXT -
OpKill.
When one of the fragment operations in this chapter is described as “replacing” a fragment shader output, that output is replaced unconditionally, even if no fragment shader previously wrote to that output.
If the fragment shader declares the
PostDepthCoverage execution mode, the sample mask
test is instead performed after the depth test.
If the fragment shader declares the
EarlyFragmentTests execution mode, fragment shading
and multisample coverage operations should instead be
performed after sample counting.
If the fragment shader declares the
EarlyAndLateFragmentTestsAMD execution mode, and does not declare the
StencilRefReplacingEXT or
DepthReplacing execution mode, fragment shading and
multisample coverage operations are instead be performed
after sample counting.
For a pipeline with the following properties:
-
the fragment shader either specifies
EarlyAndLateFragmentTestsAMDor does not write to storage resources; -
the fragment shader specifies the
StencilRefReplacingEXTexecution mode; -
either
-
the fragment shader specifies the
StencilRefUnchangedFrontAMDexecution mode; -
the fragment shader specifies the
StencilRefGreaterFrontAMDexecution mode and the pipeline uses a VkPipelineDepthStencilStateCreateInfo::front.compareOpofVK_COMPARE_OP_GREATERorVK_COMPARE_OP_GREATER_OR_EQUAL; or -
the fragment shader specifies the
StencilRefLessFrontAMDexecution mode and the pipeline uses a VkPipelineDepthStencilStateCreateInfo::front.compareOpofVK_COMPARE_OP_LESSorVK_COMPARE_OP_LESS_OR_EQUAL; and
-
-
either
-
the fragment shader specifies the
StencilRefUnchangedBackAMDexecution mode; -
the fragment shader specifies the
StencilRefGreaterBackAMDexecution mode and the pipeline uses a VkPipelineDepthStencilStateCreateInfo::back.compareOpofVK_COMPARE_OP_GREATERorVK_COMPARE_OP_GREATER_OR_EQUAL; or -
the fragment shader specifies the
StencilRefLessBackAMDexecution mode and the pipeline uses a VkPipelineDepthStencilStateCreateInfo::back.compareOpofVK_COMPARE_OP_LESSorVK_COMPARE_OP_LESS_OR_EQUAL
-
an additional stencil test may be performed before
fragment shading, using the stencil reference value
specified by
VkPipelineDepthStencilStateCreateInfo::front.reference or
VkPipelineDepthStencilStateCreateInfo::back.reference.
For a pipeline with the following properties:
-
the fragment shader either specifies
EarlyAndLateFragmentTestsAMDor does not write to storage resources; -
the fragment shader specifies the
DepthReplacingexecution mode; and -
either
-
the fragment shader specifies the
DepthUnchangedexecution mode; -
the fragment shader specifies the
DepthGreaterexecution mode and the pipeline uses a VkPipelineDepthStencilStateCreateInfo::depthCompareOpofVK_COMPARE_OP_GREATERorVK_COMPARE_OP_GREATER_OR_EQUAL; or -
the fragment shader specifies the
DepthLessexecution mode and the pipeline uses a VkPipelineDepthStencilStateCreateInfo::depthCompareOpofVK_COMPARE_OP_LESSorVK_COMPARE_OP_LESS_OR_EQUAL
-
the implementation may perform depth bounds test before fragment shading and perform an additional depth test immediately after that using the interpolated depth value generated by rasterization.
Once all fragment operations have completed, fragment shader outputs for covered color attachment samples pass through framebuffer operations.
28.1. Discard Rectangles Test
The discard rectangle test compares the framebuffer coordinates (xf,yf) of each sample covered by a fragment against a set of discard rectangles.
Each discard rectangle is defined by a VkRect2D. These values are either set by the VkPipelineDiscardRectangleStateCreateInfoEXT structure during pipeline creation, or dynamically by the vkCmdSetDiscardRectangleEXT command.
A given sample is considered inside a discard rectangle if the xf is
in the range [VkRect2D::offset.x, VkRect2D::offset.x +
VkRect2D::extent.x), and yf is in the range
[VkRect2D::offset.y, VkRect2D::offset.y +
VkRect2D::extent.y).
If the test is set to be inclusive, samples that are not inside any of the
discard rectangles will have their coverage set to 0.
If the test is set to be exclusive, samples that are inside any of the
discard rectangles will have their coverage set to 0.
If no discard rectangles are specified, the coverage mask is unmodified by this operation.
The VkPipelineDiscardRectangleStateCreateInfoEXT structure is defined
as:
// Provided by VK_EXT_discard_rectangles
typedef struct VkPipelineDiscardRectangleStateCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkPipelineDiscardRectangleStateCreateFlagsEXT flags;
VkDiscardRectangleModeEXT discardRectangleMode;
uint32_t discardRectangleCount;
const VkRect2D* pDiscardRectangles;
} VkPipelineDiscardRectangleStateCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
discardRectangleModeis a VkDiscardRectangleModeEXT value determining whether the discard rectangle test is inclusive or exclusive. -
discardRectangleCountis the number of discard rectangles to use. -
pDiscardRectanglesis a pointer to an array of VkRect2D structures defining discard rectangles.
If the VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is enabled
for a pipeline, the pDiscardRectangles member is ignored.
When this structure is included in the pNext chain of
VkGraphicsPipelineCreateInfo, it defines parameters of the discard
rectangle test.
If this structure is not included in the pNext chain, it is equivalent
to specifying this structure with a discardRectangleCount of 0.
// Provided by VK_EXT_discard_rectangles
typedef VkFlags VkPipelineDiscardRectangleStateCreateFlagsEXT;
VkPipelineDiscardRectangleStateCreateFlagsEXT is a bitmask type for
setting a mask, but is currently reserved for future use.
VkDiscardRectangleModeEXT values are:
// Provided by VK_EXT_discard_rectangles
typedef enum VkDiscardRectangleModeEXT {
VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT = 0,
VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT = 1,
} VkDiscardRectangleModeEXT;
-
VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXTspecifies that the discard rectangle test is inclusive. -
VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXTspecifies that the discard rectangle test is exclusive.
To dynamically set the discard rectangles, call:
// Provided by VK_EXT_discard_rectangles
void vkCmdSetDiscardRectangleEXT(
VkCommandBuffer commandBuffer,
uint32_t firstDiscardRectangle,
uint32_t discardRectangleCount,
const VkRect2D* pDiscardRectangles);
-
commandBufferis the command buffer into which the command will be recorded. -
firstDiscardRectangleis the index of the first discard rectangle whose state is updated by the command. -
discardRectangleCountis the number of discard rectangles whose state are updated by the command. -
pDiscardRectanglesis a pointer to an array of VkRect2D structures specifying discard rectangles.
The discard rectangle taken from element i of pDiscardRectangles
replace the current state for the discard rectangle at index
firstDiscardRectangle + i, for i in [0,
discardRectangleCount).
This command sets the discard rectangles for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDiscardRectangleStateCreateInfoEXT::pDiscardRectangles
values used to create the currently active pipeline.
28.2. Scissor Test
The scissor test compares the framebuffer coordinates (xf,yf) of
each sample covered by a fragment against a scissor rectangle at the index
equal to the fragment’s ViewportIndex.
Each scissor rectangle is defined by a VkRect2D. These values are either set by the VkPipelineViewportStateCreateInfo structure during pipeline creation, or dynamically by the vkCmdSetScissor command.
A given sample is considered inside a scissor rectangle if xf is in
the range [VkRect2D::offset.x, VkRect2D::offset.x +
VkRect2D::extent.x), and yf is in the range
[VkRect2D::offset.y, VkRect2D::offset.y +
VkRect2D::extent.y).
Samples with coordinates outside the scissor rectangle at the corresponding
ViewportIndex will have their coverage set to 0.
If a render pass transform is enabled, the (offset.x and
offset.y) and (extent.width and extent.height) values are
transformed as described in render
pass transform before participating in the scissor test.
To dynamically set the scissor rectangles, call:
// Provided by VK_VERSION_1_0
void vkCmdSetScissor(
VkCommandBuffer commandBuffer,
uint32_t firstScissor,
uint32_t scissorCount,
const VkRect2D* pScissors);
-
commandBufferis the command buffer into which the command will be recorded. -
firstScissoris the index of the first scissor whose state is updated by the command. -
scissorCountis the number of scissors whose rectangles are updated by the command. -
pScissorsis a pointer to an array of VkRect2D structures defining scissor rectangles.
The scissor rectangles taken from element i of pScissors replace
the current state for the scissor index firstScissor + i,
for i in [0, scissorCount).
This command sets the scissor rectangles for subsequent drawing commands
when the graphics pipeline is created with VK_DYNAMIC_STATE_SCISSOR
set in VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportStateCreateInfo::pScissors values used to
create the currently active pipeline.
28.3. Exclusive Scissor Test
The exclusive scissor test compares the framebuffer coordinates
(xf,yf) of each sample covered by a fragment against an exclusive
scissor rectangle at the index equal to the fragment’s
ViewportIndex.
Each exclusive scissor rectangle is defined by a VkRect2D. These values are either set by the VkPipelineViewportExclusiveScissorStateCreateInfoNV structure during pipeline creation, or dynamically by the vkCmdSetExclusiveScissorNV command.
A given sample is considered inside an exclusive scissor rectangle if
xf is in the range [VkRect2D::offset.x,
VkRect2D::offset.x + VkRect2D::extent.x), and yf
is in the range [VkRect2D::offset.y, VkRect2D::offset.y
+ VkRect2D::extent.y).
Samples with coordinates inside the exclusive scissor rectangle at the
corresponding ViewportIndex will have their coverage set to 0.
If no exclusive scissor rectangles are specified, the coverage mask is unmodified by this operation.
The VkPipelineViewportExclusiveScissorStateCreateInfoNV structure is
defined as:
// Provided by VK_NV_scissor_exclusive
typedef struct VkPipelineViewportExclusiveScissorStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t exclusiveScissorCount;
const VkRect2D* pExclusiveScissors;
} VkPipelineViewportExclusiveScissorStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
exclusiveScissorCountis the number of exclusive scissor rectangles. -
pExclusiveScissorsis a pointer to an array of VkRect2D structures defining exclusive scissor rectangles.
If the VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV dynamic state is enabled
for a pipeline, the pExclusiveScissors member is ignored.
When this structure is included in the pNext chain of
VkGraphicsPipelineCreateInfo, it defines parameters of the exclusive
scissor test.
If this structure is not included in the pNext chain, it is equivalent
to specifying this structure with a exclusiveScissorCount of 0.
To dynamically set the exclusive scissor rectangles, call:
// Provided by VK_NV_scissor_exclusive
void vkCmdSetExclusiveScissorNV(
VkCommandBuffer commandBuffer,
uint32_t firstExclusiveScissor,
uint32_t exclusiveScissorCount,
const VkRect2D* pExclusiveScissors);
-
commandBufferis the command buffer into which the command will be recorded. -
firstExclusiveScissoris the index of the first exclusive scissor rectangle whose state is updated by the command. -
exclusiveScissorCountis the number of exclusive scissor rectangles updated by the command. -
pExclusiveScissorsis a pointer to an array of VkRect2D structures defining exclusive scissor rectangles.
The scissor rectangles taken from element i of
pExclusiveScissors replace the current state for the scissor index
firstExclusiveScissor + i, for i in [0,
exclusiveScissorCount).
This command sets the exclusive scissor rectangles for subsequent drawing
commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportExclusiveScissorStateCreateInfoNV::pExclusiveScissors
values used to create the currently active pipeline.
28.4. Sample Mask Test
The sample mask test compares the coverage mask for a fragment with the sample mask defined by
VkPipelineMultisampleStateCreateInfo::pSampleMask.
Each bit of the coverage mask is associated with a sample index as described
in the rasterization chapter.
If the bit in VkPipelineMultisampleStateCreateInfo::pSampleMask
which is associated with that same sample index is set to 0, the coverage
mask bit is set to 0.
28.5. Fragment Shading
Fragment shaders are invoked for each fragment, or as helper invocations.
Most operations in the fragment shader are not performed in rasterization order, with exceptions called out in the following sections.
For fragment shaders invoked by fragments, the following rules apply:
-
A fragment shader must not be executed if a fragment operation that executes before fragment shading discards the fragment.
-
A fragment shader may not be executed if:
-
An implementation determines that another fragment shader, invoked by a subsequent primitive in primitive order, overwrites all results computed by the shader (including writes to storage resources).
-
Any other fragment operation discards the fragment, and the shader does not write to any storage resources.
-
-
Otherwise, at least one fragment shader must be executed.
-
If sample shading is enabled and multiple invocations per fragment are required, additional invocations must be executed as specified.
-
If a shading rate image is used and multiple invocations per fragment are required, additional invocations must be executed as specified.
-
Each covered sample must be included in at least one fragment shader invocation.
-
|
Note
Multiple fragment shader invocations may be executed for the same fragment for any number of implementation-dependent reasons. When there is more than one fragment shader invocation per fragment, the association of samples to invocations is implementation-dependent. Stores and atomics performed by these additional invocations have the normal effect. For example, if the subpass includes multiple views in its view mask, a fragment shader may be invoked separately for each view. Similarly, if the render pass has a fragment density map attachment, more
than one fragment shader invocation may be invoked for each covered sample.
Such additional invocations are only produced if
|
28.5.1. Sample Mask
Reading from the SampleMask built-in in the Input storage class will return the
coverage mask for the current fragment as calculated by fragment operations
that executed prior to fragment shading.
If sample shading is enabled, fragment shaders
will only see values of 1 for samples being shaded - other bits will be
0.
Each bit of the coverage mask is associated with a sample index as described
in the rasterization chapter.
If the bit in SampleMask which is associated with that same sample
index is set to 0, that coverage mask bit is set to 0.
Values written to the SampleMask built-in in the Output storage class will be used by
the multisample coverage operation, with the same encoding
as the input built-in.
28.5.2. Depth Replacement
Writing to the FragDepth
built-in will replace the fragment’s calculated depth values for each sample
in the input SampleMask.
Depth testing performed after the fragment shader for
this fragment will use this new value as zf.
28.5.3. Stencil Reference Replacement
Writing to the
FragStencilRefEXT built-in
will replace the fragment’s stencil reference value for each sample in the
input SampleMask.
Stencil testing performed after the fragment shader for
this fragment will use this new value as sr.
28.5.4. Interlocked Operations
OpBeginInvocationInterlockEXT and OpEndInvocationInterlockEXT
define a section of a fragment shader which imposes additional ordering
constraints on operations performed within them.
These operations are defined as interlocked operations.
How interlocked operations are ordered against other fragment shader
invocations depends on the specified execution modes.
If the ShadingRateInterlockOrderedEXT execution mode is specified, any
interlocked operations in a fragment shader must happen before interlocked
operations in fragment shader invocations that execute later in
rasterization order and cover at least one sample in
the same fragment area, and must happen after interlocked operations in a
fragment shader that executes earlier in rasterization
order and cover at least one sample in the same fragment area.
If the ShadingRateInterlockUnorderedEXT execution mode is specified,
any interlocked operations in a fragment shader must happen before or after
interlocked operations in fragment shader invocations that execute earlier
or later in rasterization order and cover at least one
sample in the same fragment area.
If the PixelInterlockOrderedEXT execution mode is specified, any
interlocked operations in a fragment shader must happen before interlocked
operations in fragment shader invocations that execute later in
rasterization order and cover at least one sample in
the same pixel, and must happen after interlocked operations in a fragment
shader that executes earlier in rasterization order and
cover at least one sample in the same pixel.
If the PixelInterlockUnorderedEXT execution mode is specified, any
interlocked operations in a fragment shader must happen before or after
interlocked operations in fragment shader invocations that execute earlier
or later in rasterization order and cover at least one
sample in the same pixel.
If the SampleInterlockOrderedEXT execution mode is specified, any
interlocked operations in a fragment shader must happen before interlocked
operations in fragment shader invocations that execute later in
rasterization order and cover at least one of the same
samples, and must happen after interlocked operations in a fragment shader
that executes earlier in rasterization order and cover
at least one of the same samples.
If the SampleInterlockUnorderedEXT execution mode is specified, any
interlocked operations in a fragment shader must happen before or after
interlocked operations in fragment shader invocations that execute earlier
or later in rasterization order and cover at least one
of the same samples.
28.6. Multisample Coverage
If a fragment shader is active and its entry point’s interface includes a
built-in output variable decorated with SampleMask,
but not OverrideCoverageNV,
the coverage mask is ANDed with the bits of the SampleMask
built-in to generate a new coverage mask.
If the SampleMask built-in is also decorated with
OverrideCoverageNV, the coverage mask is replaced with the mask bits
set in the shader.
If sample shading is enabled, bits written to
SampleMask corresponding to samples that are not being shaded by the
fragment shader invocation are ignored.
If no fragment shader is active, or if the active fragment shader does not
include SampleMask in its interface, the coverage mask is not modified.
Next, the fragment alpha value and coverage mask are modified based on the
line coverage factor if the lineRasterizationMode member of the
VkPipelineRasterizationStateCreateInfo structure is
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, and the
alphaToCoverageEnable and alphaToOneEnable members of the
VkPipelineMultisampleStateCreateInfo structure.
All alpha values in this section refer only to the alpha component of the
fragment shader output that has a Location and Index decoration of
zero (see the Fragment Output Interface
section).
If that shader output has an integer or unsigned integer type, then these
operations are skipped.
If the lineRasterizationMode member of the
VkPipelineRasterizationStateCreateInfo structure is
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT and the fragment
came from a line segment, then the alpha value is replaced by multiplying it
by the coverage factor for the fragment computed during
smooth line rasterization.
If alphaToCoverageEnable is enabled, a temporary coverage mask is
generated where each bit is determined by the fragment’s alpha value, which
is ANDed with the fragment coverage mask.
No specific algorithm is specified for converting the alpha value to a temporary coverage mask. It is intended that the number of 1’s in this value be proportional to the alpha value (clamped to [0,1]), with all 1’s corresponding to a value of 1.0 and all 0’s corresponding to 0.0. The algorithm may be different at different framebuffer coordinates.
|
Note
Using different algorithms at different framebuffer coordinates may help to avoid artifacts caused by regular coverage sample locations. |
Finally, if alphaToOneEnable is enabled, each alpha value is replaced
by the maximum representable alpha value for fixed-point color attachments,
or by 1.0 for floating-point attachments.
Otherwise, the alpha values are not changed.
28.7. Depth and Stencil Operations
Pipeline state controlling the depth bounds tests,
stencil test, and depth test is
specified through the members of the
VkPipelineDepthStencilStateCreateInfo structure.
The VkPipelineDepthStencilStateCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineDepthStencilStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineDepthStencilStateCreateFlags flags;
VkBool32 depthTestEnable;
VkBool32 depthWriteEnable;
VkCompareOp depthCompareOp;
VkBool32 depthBoundsTestEnable;
VkBool32 stencilTestEnable;
VkStencilOpState front;
VkStencilOpState back;
float minDepthBounds;
float maxDepthBounds;
} VkPipelineDepthStencilStateCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineDepthStencilStateCreateFlagBits specifying additional depth/stencil state information. -
depthTestEnablecontrols whether depth testing is enabled. -
depthWriteEnablecontrols whether depth writes are enabled whendepthTestEnableisVK_TRUE. Depth writes are always disabled whendepthTestEnableisVK_FALSE. -
depthCompareOpis a VkCompareOp value specifying the comparison operator to use in the Depth Comparison step of the depth test. -
depthBoundsTestEnablecontrols whether depth bounds testing is enabled. -
stencilTestEnablecontrols whether stencil testing is enabled. -
frontandbackcontrol the parameters of the stencil test. -
minDepthBoundsis the minimum depth bound used in the depth bounds test. -
maxDepthBoundsis the maximum depth bound used in the depth bounds test.
VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a
mask of zero or more VkPipelineDepthStencilStateCreateFlagBits.
Bits which can be set in the
VkPipelineDepthStencilStateCreateInfo::flags parameter are:
// Provided by VK_ARM_rasterization_order_attachment_access
typedef enum VkPipelineDepthStencilStateCreateFlagBits {
// Provided by VK_ARM_rasterization_order_attachment_access
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM = 0x00000001,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM = 0x00000002,
} VkPipelineDepthStencilStateCreateFlagBits;
-
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARMindicates that access to the depth aspects of depth/stencil and input attachments will have implicit framebuffer-local memory dependencies. See renderpass feedback loops for more information. -
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARMindicates that access to the stencil aspects of depth/stencil and input attachments will have implicit framebuffer-local memory dependencies. See renderpass feedback loops for more information.
28.8. Depth Bounds Test
The depth bounds test compares the depth value za in the depth/stencil attachment at each sample’s framebuffer coordinates (xf,yf) and sample index i against a set of depth bounds.
The depth bounds are determined by two floating point values defining a
minimum (minDepthBounds) and maximum (maxDepthBounds) depth
value.
These values are either set by the
VkPipelineDepthStencilStateCreateInfo structure during pipeline
creation, or dynamically by
vkCmdSetDepthBoundsTestEnable and
vkCmdSetDepthBounds.
A given sample is considered within the depth bounds if za is in the
range [minDepthBounds,maxDepthBounds].
Samples with depth attachment values outside of the depth bounds will have
their coverage set to 0.
If the depth bounds test is disabled, or if there is no depth attachment, the coverage mask is unmodified by this operation.
To dynamically enable or disable the depth bounds test, call:
// Provided by VK_VERSION_1_3
void vkCmdSetDepthBoundsTestEnable(
VkCommandBuffer commandBuffer,
VkBool32 depthBoundsTestEnable);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetDepthBoundsTestEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 depthBoundsTestEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
depthBoundsTestEnablespecifies if the depth bounds test is enabled.
This command sets the depth bounds enable for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDepthStencilStateCreateInfo::depthBoundsTestEnable
value used to create the currently active pipeline.
To dynamically set the depth bounds range, call:
// Provided by VK_VERSION_1_0
void vkCmdSetDepthBounds(
VkCommandBuffer commandBuffer,
float minDepthBounds,
float maxDepthBounds);
-
commandBufferis the command buffer into which the command will be recorded. -
minDepthBoundsis the minimum depth bound. -
maxDepthBoundsis the maximum depth bound.
This command sets the depth bounds range for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_BOUNDS set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDepthStencilStateCreateInfo::minDepthBounds and
VkPipelineDepthStencilStateCreateInfo::maxDepthBounds values
used to create the currently active pipeline.
28.9. Stencil Test
The stencil test compares the stencil attachment value sa in the depth/stencil attachment at each sample’s framebuffer coordinates (xf,yf) and sample index i against a stencil reference value.
If the render pass has a fragment density map attachment and the fragment covers multiple pixels, there is an implementation-dependent association of coverage samples to stencil attachment samples within the fragment. However, if all samples in the fragment are covered, and the stencil attachment value is updated as a result of this test, all stencil attachment samples will be updated.
If the stencil test is not enabled, as specified by
vkCmdSetStencilTestEnable or
VkPipelineDepthStencilStateCreateInfo::stencilTestEnable, or if
there is no stencil attachment, the coverage mask is unmodified by this
operation.
The stencil test is controlled by one of two sets of stencil-related state, the front stencil state and the back stencil state. Stencil tests and writes use the back stencil state when processing fragments generated by back-facing polygons, and the front stencil state when processing fragments generated by front-facing polygons or any other primitives.
The comparison operation performed is determined by the VkCompareOp
value set by
vkCmdSetStencilOp::compareOp, or by
VkStencilOpState::compareOp during pipeline creation.
The compare mask sc and stencil reference value sr of the front or the back stencil state set determine arguments of the comparison operation. sc is set by the VkPipelineDepthStencilStateCreateInfo structure during pipeline creation, or by the vkCmdSetStencilCompareMask command. sr is set by VkPipelineDepthStencilStateCreateInfo or by vkCmdSetStencilReference.
sr and sa are each independently combined with sc
using a bitwise AND operation to create masked reference and attachment
values s'r and s'a.
s'r and s'a are used as the reference and test values,
respectively, in the operation specified by the VkCompareOp.
If the comparison evaluates to false, the coverage for the sample is set to
0.
A new stencil value sg is generated according to a stencil operation
defined by VkStencilOp parameters set by
vkCmdSetStencilOp or
VkPipelineDepthStencilStateCreateInfo.
If the stencil test fails, failOp defines the stencil operation used.
If the stencil test passes however, the stencil op used is based on the
depth test - if it passes,
VkPipelineDepthStencilStateCreateInfo::passOp is used, otherwise
VkPipelineDepthStencilStateCreateInfo::depthFailOp is used.
The stencil attachment value sa is then updated with the generated
stencil value sg according to the write mask sw defined by
VkPipelineDepthStencilStateCreateInfo::writeMask as:
-
sa = (sa & ¬sw) | (sg & sw)
To dynamically enable or disable the stencil test, call:
// Provided by VK_VERSION_1_3
void vkCmdSetStencilTestEnable(
VkCommandBuffer commandBuffer,
VkBool32 stencilTestEnable);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetStencilTestEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 stencilTestEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
stencilTestEnablespecifies if the stencil test is enabled.
This command sets the stencil test enable for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDepthStencilStateCreateInfo::stencilTestEnable value
used to create the currently active pipeline.
To dynamically set the stencil operation, call:
// Provided by VK_VERSION_1_3
void vkCmdSetStencilOp(
VkCommandBuffer commandBuffer,
VkStencilFaceFlags faceMask,
VkStencilOp failOp,
VkStencilOp passOp,
VkStencilOp depthFailOp,
VkCompareOp compareOp);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetStencilOpEXT(
VkCommandBuffer commandBuffer,
VkStencilFaceFlags faceMask,
VkStencilOp failOp,
VkStencilOp passOp,
VkStencilOp depthFailOp,
VkCompareOp compareOp);
-
commandBufferis the command buffer into which the command will be recorded. -
faceMaskis a bitmask of VkStencilFaceFlagBits specifying the set of stencil state for which to update the stencil operation. -
failOpis a VkStencilOp value specifying the action performed on samples that fail the stencil test. -
passOpis a VkStencilOp value specifying the action performed on samples that pass both the depth and stencil tests. -
depthFailOpis a VkStencilOp value specifying the action performed on samples that pass the stencil test and fail the depth test. -
compareOpis a VkCompareOp value specifying the comparison operator used in the stencil test.
This command sets the stencil operation for subsequent drawing commands when
the graphics pipeline is created with VK_DYNAMIC_STATE_STENCIL_OP set
in VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the corresponding
VkPipelineDepthStencilStateCreateInfo::failOp, passOp,
depthFailOp, and compareOp values used to create the currently
active pipeline, for both front and back faces.
The VkStencilOpState structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkStencilOpState {
VkStencilOp failOp;
VkStencilOp passOp;
VkStencilOp depthFailOp;
VkCompareOp compareOp;
uint32_t compareMask;
uint32_t writeMask;
uint32_t reference;
} VkStencilOpState;
-
failOpis a VkStencilOp value specifying the action performed on samples that fail the stencil test. -
passOpis a VkStencilOp value specifying the action performed on samples that pass both the depth and stencil tests. -
depthFailOpis a VkStencilOp value specifying the action performed on samples that pass the stencil test and fail the depth test. -
compareOpis a VkCompareOp value specifying the comparison operator used in the stencil test. -
compareMaskselects the bits of the unsigned integer stencil values participating in the stencil test. -
writeMaskselects the bits of the unsigned integer stencil values updated by the stencil test in the stencil framebuffer attachment. -
referenceis an integer stencil reference value that is used in the unsigned stencil comparison.
To dynamically set the stencil compare mask, call:
// Provided by VK_VERSION_1_0
void vkCmdSetStencilCompareMask(
VkCommandBuffer commandBuffer,
VkStencilFaceFlags faceMask,
uint32_t compareMask);
-
commandBufferis the command buffer into which the command will be recorded. -
faceMaskis a bitmask of VkStencilFaceFlagBits specifying the set of stencil state for which to update the compare mask. -
compareMaskis the new value to use as the stencil compare mask.
This command sets the stencil compare mask for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkStencilOpState::compareMask value used to create the currently
active pipeline, for both front and back faces.
VkStencilFaceFlagBits values are:
// Provided by VK_VERSION_1_0
typedef enum VkStencilFaceFlagBits {
VK_STENCIL_FACE_FRONT_BIT = 0x00000001,
VK_STENCIL_FACE_BACK_BIT = 0x00000002,
VK_STENCIL_FACE_FRONT_AND_BACK = 0x00000003,
VK_STENCIL_FRONT_AND_BACK = VK_STENCIL_FACE_FRONT_AND_BACK,
} VkStencilFaceFlagBits;
-
VK_STENCIL_FACE_FRONT_BITspecifies that only the front set of stencil state is updated. -
VK_STENCIL_FACE_BACK_BITspecifies that only the back set of stencil state is updated. -
VK_STENCIL_FACE_FRONT_AND_BACKis the combination ofVK_STENCIL_FACE_FRONT_BITandVK_STENCIL_FACE_BACK_BIT, and specifies that both sets of stencil state are updated.
// Provided by VK_VERSION_1_0
typedef VkFlags VkStencilFaceFlags;
VkStencilFaceFlags is a bitmask type for setting a mask of zero or
more VkStencilFaceFlagBits.
To dynamically set the stencil write mask, call:
// Provided by VK_VERSION_1_0
void vkCmdSetStencilWriteMask(
VkCommandBuffer commandBuffer,
VkStencilFaceFlags faceMask,
uint32_t writeMask);
-
commandBufferis the command buffer into which the command will be recorded. -
faceMaskis a bitmask of VkStencilFaceFlagBits specifying the set of stencil state for which to update the write mask, as described above for vkCmdSetStencilCompareMask. -
writeMaskis the new value to use as the stencil write mask.
This command sets the stencil write mask for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_STENCIL_WRITE_MASK set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDepthStencilStateCreateInfo::writeMask value used to
create the currently active pipeline, for both front and back faces.
To dynamically set the stencil reference value, call:
// Provided by VK_VERSION_1_0
void vkCmdSetStencilReference(
VkCommandBuffer commandBuffer,
VkStencilFaceFlags faceMask,
uint32_t reference);
-
commandBufferis the command buffer into which the command will be recorded. -
faceMaskis a bitmask of VkStencilFaceFlagBits specifying the set of stencil state for which to update the reference value, as described above for vkCmdSetStencilCompareMask. -
referenceis the new value to use as the stencil reference value.
This command sets the stencil reference value for subsequent drawing
commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_STENCIL_REFERENCE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDepthStencilStateCreateInfo::reference value used to
create the currently active pipeline, for both front and back faces.
Possible values of the failOp, passOp, and depthFailOp
members of VkStencilOpState, specifying what happens to the stored
stencil value if this or certain subsequent tests fail or pass, are:
// Provided by VK_VERSION_1_0
typedef enum VkStencilOp {
VK_STENCIL_OP_KEEP = 0,
VK_STENCIL_OP_ZERO = 1,
VK_STENCIL_OP_REPLACE = 2,
VK_STENCIL_OP_INCREMENT_AND_CLAMP = 3,
VK_STENCIL_OP_DECREMENT_AND_CLAMP = 4,
VK_STENCIL_OP_INVERT = 5,
VK_STENCIL_OP_INCREMENT_AND_WRAP = 6,
VK_STENCIL_OP_DECREMENT_AND_WRAP = 7,
} VkStencilOp;
-
VK_STENCIL_OP_KEEPkeeps the current value. -
VK_STENCIL_OP_ZEROsets the value to 0. -
VK_STENCIL_OP_REPLACEsets the value toreference. -
VK_STENCIL_OP_INCREMENT_AND_CLAMPincrements the current value and clamps to the maximum representable unsigned value. -
VK_STENCIL_OP_DECREMENT_AND_CLAMPdecrements the current value and clamps to 0. -
VK_STENCIL_OP_INVERTbitwise-inverts the current value. -
VK_STENCIL_OP_INCREMENT_AND_WRAPincrements the current value and wraps to 0 when the maximum value would have been exceeded. -
VK_STENCIL_OP_DECREMENT_AND_WRAPdecrements the current value and wraps to the maximum possible value when the value would go below 0.
For purposes of increment and decrement, the stencil bits are considered as an unsigned integer.
28.10. Depth Test
The depth test compares the depth value za in the depth/stencil attachment at each sample’s framebuffer coordinates (xf,yf) and sample index i against the sample’s depth value zf. If there is no depth attachment then the depth test is skipped.
If the render pass has a fragment density map attachment and the fragment covers multiple pixels, there is an implementation-dependent association of rasterization samples to depth attachment samples within the fragment. However, if all samples in the fragment are covered, and the depth attachment value is updated as a result of this test, all depth attachment samples will be updated.
The depth test occurs in three stages, as detailed in the following sections.
28.10.1. Depth Clamping and Range Adjustment
If VkPipelineRasterizationStateCreateInfo::depthClampEnable is
enabled, before the sample’s zf is compared to za,
zf is clamped to [min(n,f),max(n,f)], where n and
f are the minDepth and maxDepth depth range values of the
viewport used by this fragment, respectively.
If depth clamping is not enabled and zf is not in the range [0, 1] and either VK_EXT_depth_range_unrestricted is not enabled, or the depth attachment has a fixed-point format, then zf is undefined following this step.
28.10.2. Depth Comparison
If the depth test is not enabled, as specified by
vkCmdSetDepthTestEnable or
VkPipelineDepthStencilStateCreateInfo::depthTestEnable, then
this step is skipped.
The comparison operation performed is determined by the VkCompareOp
value set by
vkCmdSetDepthCompareOp, or by
VkPipelineDepthStencilStateCreateInfo::depthCompareOp during
pipeline creation.
zf and za are used as the reference and test values,
respectively, in the operation specified by the VkCompareOp.
If the comparison evaluates to false, the coverage for the sample is set to
0.
28.10.3. Depth Attachment Writes
If depth writes are enabled, as specified by
vkCmdSetDepthWriteEnable or
VkPipelineDepthStencilStateCreateInfo::depthWriteEnable, and the
comparison evaluated to true, the depth attachment value za is set
to the sample’s depth value zf.
If there is no depth attachment, no value is written.
To dynamically enable or disable the depth test, call:
// Provided by VK_VERSION_1_3
void vkCmdSetDepthTestEnable(
VkCommandBuffer commandBuffer,
VkBool32 depthTestEnable);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetDepthTestEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 depthTestEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
depthTestEnablespecifies if the depth test is enabled.
This command sets the depth test enable for subsequent drawing commands when
the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDepthStencilStateCreateInfo::depthTestEnable value
used to create the currently active pipeline.
To dynamically set the depth compare operator, call:
// Provided by VK_VERSION_1_3
void vkCmdSetDepthCompareOp(
VkCommandBuffer commandBuffer,
VkCompareOp depthCompareOp);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetDepthCompareOpEXT(
VkCommandBuffer commandBuffer,
VkCompareOp depthCompareOp);
-
commandBufferis the command buffer into which the command will be recorded. -
depthCompareOpis a VkCompareOp value specifying the comparison operator used for the Depth Comparison step of the depth test.
This command sets the depth comparison operator for subsequent drawing
commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDepthStencilStateCreateInfo::depthCompareOp value used
to create the currently active pipeline.
To dynamically set the depth write enable, call:
// Provided by VK_VERSION_1_3
void vkCmdSetDepthWriteEnable(
VkCommandBuffer commandBuffer,
VkBool32 depthWriteEnable);
or the equivalent command
// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetDepthWriteEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 depthWriteEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
depthWriteEnablespecifies if depth writes are enabled.
This command sets the depth write enable for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDepthStencilStateCreateInfo::depthWriteEnable value
used to create the currently active pipeline.
28.11. Representative Fragment Test
The representative fragment test allows implementations to reduce the amount of rasterization and fragment processing work performed for each point, line, or triangle primitive. For any primitive that produces one or more fragments that pass all prior early fragment tests, the implementation may choose one or more “representative” fragments for processing and discard all other fragments. For draw calls rendering multiple points, lines, or triangles arranged in lists, strips, or fans, the representative fragment test is performed independently for each of those primitives. The set of fragments discarded by the representative fragment test is implementation-dependent. In some cases, the representative fragment test may not discard any fragments for a given primitive.
If the pNext chain of VkGraphicsPipelineCreateInfo includes a
VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure, then
that structure includes parameters controlling the representative fragment
test.
The VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure is
defined as:
// Provided by VK_NV_representative_fragment_test
typedef struct VkPipelineRepresentativeFragmentTestStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 representativeFragmentTestEnable;
} VkPipelineRepresentativeFragmentTestStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
representativeFragmentTestEnablecontrols whether the representative fragment test is enabled.
If this structure is not included in the pNext chain,
representativeFragmentTestEnable is considered to be VK_FALSE,
and the representative fragment test is disabled.
If the active fragment shader does not specify the EarlyFragmentTests
execution mode, the representative fragment shader test has no effect, even
if enabled.
28.12. Sample Counting
Occlusion queries use query pool entries to track the number of samples that pass all the per-fragment tests. The mechanism of collecting an occlusion query value is described in Occlusion Queries.
The occlusion query sample counter increments by one for each sample with a coverage value of 1 in each fragment that survives all the per-fragment tests, including scissor, exclusive scissor, sample mask, alpha to coverage, stencil, and depth tests.
28.13. Fragment Coverage To Color
The VkPipelineCoverageToColorStateCreateInfoNV structure is defined
as:
// Provided by VK_NV_fragment_coverage_to_color
typedef struct VkPipelineCoverageToColorStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkPipelineCoverageToColorStateCreateFlagsNV flags;
VkBool32 coverageToColorEnable;
uint32_t coverageToColorLocation;
} VkPipelineCoverageToColorStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
coverageToColorEnablecontrols whether the fragment coverage value replaces a fragment color output. -
coverageToColorLocationcontrols which fragment shader color output value is replaced.
If the pNext chain of VkPipelineMultisampleStateCreateInfo
includes a VkPipelineCoverageToColorStateCreateInfoNV structure, then
that structure controls whether the fragment coverage is substituted for a
fragment color output and, if so, which output is replaced.
If coverageToColorEnable is VK_TRUE, the
coverage mask replaces the first
component of the color value corresponding to the fragment shader output
location with Location equal to coverageToColorLocation and
Index equal to zero.
If the color attachment format has fewer bits than the coverage mask, the
low bits of the sample coverage mask are taken without any clamping.
If the color attachment format has more bits than the coverage mask, the
high bits of the sample coverage mask are filled with zeros.
If coverageToColorEnable is VK_FALSE, these operations are
skipped.
If this structure is not included in the pNext chain, it is as if
coverageToColorEnable is VK_FALSE.
// Provided by VK_NV_fragment_coverage_to_color
typedef VkFlags VkPipelineCoverageToColorStateCreateFlagsNV;
VkPipelineCoverageToColorStateCreateFlagsNV is a bitmask type for
setting a mask, but is currently reserved for future use.
28.14. Coverage Reduction
Coverage reduction takes the coverage information for a fragment and converts that to a boolean coverage value for each color sample in each pixel covered by the fragment.
28.14.1. Pixel Coverage
Coverage for each pixel is first extracted from the total fragment coverage
mask.
This consists of rasterizationSamples unique coverage samples for each
pixel in the fragment area, each with a unique
sample index.
If the fragment only contains a single pixel, coverage for the pixel is
equivalent to the fragment coverage.
If the render pass has a fragment density map attachment and the fragment covers multiple pixels, pixel coverage is generated in an implementation-dependent manner. If all samples in the fragment are covered, all samples will be covered in each pixel coverage.
If a shading rate image is used, and the fragment covers multiple pixels, each pixel’s coverage consists of the coverage samples corresponding to that pixel, and each sample retains its unique sample index i.
If the fragment shading rate is set, and the fragment covers multiple pixels, each pixel’s coverage consists of the coverage samples with a pixel index matching that pixel, and each sample retains its unique sample index i.
28.14.2. Color Sample Coverage
Once pixel coverage is determined, coverage for each individual color sample corresponding to that pixel is determined.
If the
number of rasterizationSamples is identical to the number of samples
in the color attachments.
A color sample is covered if the pixel coverage sample with the same
sample index i is covered.
Otherwise, the coverage for each color sample is computed from the pixel coverage as follows.
If the VK_AMD_mixed_attachment_samples extension is enabled, for
color samples present in the color attachments, a color sample is covered if
the pixel coverage sample with the same
sample index i is covered;
additional pixel coverage samples are discarded.
If the pNext chain of VkSubpassDescription2
or VkRenderingInfo
includes a VkMultisampledRenderToSingleSampledInfoEXT structure with
the multisampledRenderToSingleSampledEnable field equal to
VK_TRUE, sample coverage is calculated as if the attachment has
VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples
samples.
When the VK_NV_coverage_reduction_mode extension is enabled, the
pipeline state controlling coverage reduction is specified through the
members of the VkPipelineCoverageReductionStateCreateInfoNV structure.
The VkPipelineCoverageReductionStateCreateInfoNV structure is defined
as:
// Provided by VK_NV_coverage_reduction_mode
typedef struct VkPipelineCoverageReductionStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkPipelineCoverageReductionStateCreateFlagsNV flags;
VkCoverageReductionModeNV coverageReductionMode;
} VkPipelineCoverageReductionStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
coverageReductionModeis a VkCoverageReductionModeNV value controlling how color sample coverage is generated from pixel coverage.
If this structure is not included in the pNext chain, or if the
extension is not enabled, the default coverage reduction mode is inferred as
follows:
-
If the
VK_NV_framebuffer_mixed_samplesextension is enabled, then it is as if thecoverageReductionModeisVK_COVERAGE_REDUCTION_MODE_MERGE_NV. -
If the
VK_AMD_mixed_attachment_samplesextension is enabled, then it is as if thecoverageReductionModeisVK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV. -
If both
VK_NV_framebuffer_mixed_samplesandVK_AMD_mixed_attachment_samplesare enabled, then the default coverage reduction mode is implementation-dependent.
// Provided by VK_NV_coverage_reduction_mode
typedef VkFlags VkPipelineCoverageReductionStateCreateFlagsNV;
VkPipelineCoverageReductionStateCreateFlagsNV is a bitmask type for
setting a mask, but is currently reserved for future use.
Possible values of
VkPipelineCoverageReductionStateCreateInfoNV::coverageReductionMode,
specifying how color sample coverage is generated from pixel coverage, are:
// Provided by VK_NV_coverage_reduction_mode
typedef enum VkCoverageReductionModeNV {
VK_COVERAGE_REDUCTION_MODE_MERGE_NV = 0,
VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV = 1,
} VkCoverageReductionModeNV;
-
VK_COVERAGE_REDUCTION_MODE_MERGE_NVspecifies that each color sample will be associated with an implementation-dependent subset of samples in the pixel coverage. If any of those associated samples are covered, the color sample is covered. -
VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NVspecifies that for color samples present in the color attachments, a color sample is covered if the pixel coverage sample with the same sample index i is covered; other pixel coverage samples are discarded.
To query the set of mixed sample combinations of coverage reduction mode, rasterization samples and color, depth, stencil attachment sample counts that are supported by a physical device, call:
// Provided by VK_NV_coverage_reduction_mode
VkResult vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV(
VkPhysicalDevice physicalDevice,
uint32_t* pCombinationCount,
VkFramebufferMixedSamplesCombinationNV* pCombinations);
-
physicalDeviceis the physical device from which to query the set of combinations. -
pCombinationCountis a pointer to an integer related to the number of combinations available or queried, as described below. -
pCombinationsis eitherNULLor a pointer to an array of VkFramebufferMixedSamplesCombinationNV values, indicating the supported combinations of coverage reduction mode, rasterization samples, and color, depth, stencil attachment sample counts.
If pCombinations is NULL, then the number of supported combinations
for the given physicalDevice is returned in pCombinationCount.
Otherwise, pCombinationCount must point to a variable set by the user
to the number of elements in the pCombinations array, and on return
the variable is overwritten with the number of values actually written to
pCombinations.
If the value of pCombinationCount is less than the number of
combinations supported for the given physicalDevice, at most
pCombinationCount values will be written to pCombinations, and
VK_INCOMPLETE will be returned instead of VK_SUCCESS, to
indicate that not all the supported values were returned.
The VkFramebufferMixedSamplesCombinationNV structure is defined as:
// Provided by VK_NV_coverage_reduction_mode
typedef struct VkFramebufferMixedSamplesCombinationNV {
VkStructureType sType;
void* pNext;
VkCoverageReductionModeNV coverageReductionMode;
VkSampleCountFlagBits rasterizationSamples;
VkSampleCountFlags depthStencilSamples;
VkSampleCountFlags colorSamples;
} VkFramebufferMixedSamplesCombinationNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
coverageReductionModeis a VkCoverageReductionModeNV value specifying the coverage reduction mode. -
rasterizationSamplesis a VkSampleCountFlagBits specifying the number of rasterization samples in the supported combination. -
depthStencilSamplesspecifies the number of samples in the depth stencil attachment in the supported combination. A value of 0 indicates the combination does not have a depth stencil attachment. -
colorSamplesspecifies the number of color samples in a color attachment in the supported combination. A value of 0 indicates the combination does not have a color attachment.
28.14.3. Coverage Modulation
As part of coverage reduction, fragment color values can also be modulated (multiplied) by a value that is a function of fraction of covered rasterization samples associated with that color sample.
Pipeline state controlling coverage modulation is specified through the
members of the VkPipelineCoverageModulationStateCreateInfoNV
structure.
The VkPipelineCoverageModulationStateCreateInfoNV structure is defined
as:
// Provided by VK_NV_framebuffer_mixed_samples
typedef struct VkPipelineCoverageModulationStateCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkPipelineCoverageModulationStateCreateFlagsNV flags;
VkCoverageModulationModeNV coverageModulationMode;
VkBool32 coverageModulationTableEnable;
uint32_t coverageModulationTableCount;
const float* pCoverageModulationTable;
} VkPipelineCoverageModulationStateCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
coverageModulationModeis a VkCoverageModulationModeNV value controlling which color components are modulated. -
coverageModulationTableEnablecontrols whether the modulation factor is looked up from a table inpCoverageModulationTable. -
coverageModulationTableCountis the number of elements inpCoverageModulationTable. -
pCoverageModulationTableis a table of modulation factors containing a value for each number of covered samples.
If coverageModulationTableEnable is VK_FALSE, then for each
color sample the associated bits of the pixel coverage are counted and
divided by the number of associated bits to produce a modulation factor
R in the range (0,1] (a value of zero would have been killed due
to a color coverage of 0).
Specifically:
-
N = value of
rasterizationSamples -
M = value of VkAttachmentDescription::
samplesfor any color attachments -
R = popcount(associated coverage bits) / (N / M)
If coverageModulationTableEnable is VK_TRUE, the value R
is computed using a programmable lookup table.
The lookup table has N / M elements, and the element of the table is
selected by:
-
R =
pCoverageModulationTable[popcount(associated coverage bits)-1]
Note that the table does not have an entry for popcount(associated coverage bits) = 0, because such samples would have been killed.
The values of pCoverageModulationTable may be rounded to an
implementation-dependent precision, which is at least as fine as 1 /
N, and clamped to [0,1].
For each color attachment with a floating point or normalized color format,
each fragment output color value is replicated to M values which can
each be modulated (multiplied) by that color sample’s associated value of
R.
Which components are modulated is controlled by
coverageModulationMode.
If this structure is not included in the pNext chain, it is as if
coverageModulationMode is VK_COVERAGE_MODULATION_MODE_NONE_NV.
If the coverage reduction mode is
VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV, each color sample is
associated with only a single coverage sample.
In this case, it is as if coverageModulationMode is
VK_COVERAGE_MODULATION_MODE_NONE_NV.
// Provided by VK_NV_framebuffer_mixed_samples
typedef VkFlags VkPipelineCoverageModulationStateCreateFlagsNV;
VkPipelineCoverageModulationStateCreateFlagsNV is a bitmask type for
setting a mask, but is currently reserved for future use.
Possible values of
VkPipelineCoverageModulationStateCreateInfoNV::coverageModulationMode,
specifying which color components are modulated, are:
// Provided by VK_NV_framebuffer_mixed_samples
typedef enum VkCoverageModulationModeNV {
VK_COVERAGE_MODULATION_MODE_NONE_NV = 0,
VK_COVERAGE_MODULATION_MODE_RGB_NV = 1,
VK_COVERAGE_MODULATION_MODE_ALPHA_NV = 2,
VK_COVERAGE_MODULATION_MODE_RGBA_NV = 3,
} VkCoverageModulationModeNV;
-
VK_COVERAGE_MODULATION_MODE_NONE_NVspecifies that no components are multiplied by the modulation factor. -
VK_COVERAGE_MODULATION_MODE_RGB_NVspecifies that the red, green, and blue components are multiplied by the modulation factor. -
VK_COVERAGE_MODULATION_MODE_ALPHA_NVspecifies that the alpha component is multiplied by the modulation factor. -
VK_COVERAGE_MODULATION_MODE_RGBA_NVspecifies that all components are multiplied by the modulation factor.
29. The Framebuffer
29.1. Blending
Blending combines the incoming source fragment’s R, G, B, and A values with the destination R, G, B, and A values of each sample stored in the framebuffer at the fragment’s (xf,yf) location. Blending is performed for each color sample covered by the fragment, rather than just once for each fragment.
Source and destination values are combined according to the blend operation, quadruplets of source and destination weighting factors determined by the blend factors, and a blend constant, to obtain a new set of R, G, B, and A values, as described below.
Blending is computed and applied separately to each color attachment used by the subpass, with separate controls for each attachment.
Prior to performing the blend operation, signed and unsigned normalized fixed-point color components undergo an implied conversion to floating-point as specified by Conversion from Normalized Fixed-Point to Floating-Point. Blending computations are treated as if carried out in floating-point, and basic blend operations are performed with a precision and dynamic range no lower than that used to represent destination components. Advanced blending operations are performed with a precision and dynamic range no lower than the smaller of that used to represent destination components or that used to represent 16-bit floating-point values.
|
Note
Blending is only defined for floating-point, UNORM, SNORM, and sRGB formats.
Within those formats, the implementation may only support blending on some
subset of them.
Which formats support blending is indicated by
|
The pipeline blend state is included in the
VkPipelineColorBlendStateCreateInfo structure during graphics pipeline
creation:
The VkPipelineColorBlendStateCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineColorBlendStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineColorBlendStateCreateFlags flags;
VkBool32 logicOpEnable;
VkLogicOp logicOp;
uint32_t attachmentCount;
const VkPipelineColorBlendAttachmentState* pAttachments;
float blendConstants[4];
} VkPipelineColorBlendStateCreateInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineColorBlendStateCreateFlagBits specifying additional color blending information. -
logicOpEnablecontrols whether to apply Logical Operations. -
logicOpselects which logical operation to apply. -
attachmentCountis the number of VkPipelineColorBlendAttachmentState elements inpAttachments. -
pAttachmentsis a pointer to an array of VkPipelineColorBlendAttachmentState structures defining blend state for each color attachment. -
blendConstantsis a pointer to an array of four values used as the R, G, B, and A components of the blend constant that are used in blending, depending on the blend factor.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineColorBlendStateCreateFlags;
VkPipelineColorBlendStateCreateFlags is a bitmask type for setting a
mask of zero or more VkPipelineColorBlendStateCreateFlagBits.
Bits which can be set in the
VkPipelineColorBlendStateCreateInfo::flags parameter are:
// Provided by VK_ARM_rasterization_order_attachment_access
typedef enum VkPipelineColorBlendStateCreateFlagBits {
// Provided by VK_ARM_rasterization_order_attachment_access
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM = 0x00000001,
} VkPipelineColorBlendStateCreateFlagBits;
-
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARMindicates that access to color and input attachments will have implicit framebuffer-local memory dependencies, allowing applications to express custom blending operations in a fragment shader. See renderpass feedback loops for more information.
The VkPipelineColorBlendAttachmentState structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineColorBlendAttachmentState {
VkBool32 blendEnable;
VkBlendFactor srcColorBlendFactor;
VkBlendFactor dstColorBlendFactor;
VkBlendOp colorBlendOp;
VkBlendFactor srcAlphaBlendFactor;
VkBlendFactor dstAlphaBlendFactor;
VkBlendOp alphaBlendOp;
VkColorComponentFlags colorWriteMask;
} VkPipelineColorBlendAttachmentState;
-
blendEnablecontrols whether blending is enabled for the corresponding color attachment. If blending is not enabled, the source fragment’s color for that attachment is passed through unmodified. -
srcColorBlendFactorselects which blend factor is used to determine the source factors (Sr,Sg,Sb). -
dstColorBlendFactorselects which blend factor is used to determine the destination factors (Dr,Dg,Db). -
colorBlendOpselects which blend operation is used to calculate the RGB values to write to the color attachment. -
srcAlphaBlendFactorselects which blend factor is used to determine the source factor Sa. -
dstAlphaBlendFactorselects which blend factor is used to determine the destination factor Da. -
alphaBlendOpselects which blend operation is use to calculate the alpha values to write to the color attachment. -
colorWriteMaskis a bitmask of VkColorComponentFlagBits specifying which of the R, G, B, and/or A components are enabled for writing, as described for the Color Write Mask.
29.1.1. Blend Factors
The source and destination color and alpha blending factors are selected from the enum:
// Provided by VK_VERSION_1_0
typedef enum VkBlendFactor {
VK_BLEND_FACTOR_ZERO = 0,
VK_BLEND_FACTOR_ONE = 1,
VK_BLEND_FACTOR_SRC_COLOR = 2,
VK_BLEND_FACTOR_ONE_MINUS_SRC_COLOR = 3,
VK_BLEND_FACTOR_DST_COLOR = 4,
VK_BLEND_FACTOR_ONE_MINUS_DST_COLOR = 5,
VK_BLEND_FACTOR_SRC_ALPHA = 6,
VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA = 7,
VK_BLEND_FACTOR_DST_ALPHA = 8,
VK_BLEND_FACTOR_ONE_MINUS_DST_ALPHA = 9,
VK_BLEND_FACTOR_CONSTANT_COLOR = 10,
VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR = 11,
VK_BLEND_FACTOR_CONSTANT_ALPHA = 12,
VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA = 13,
VK_BLEND_FACTOR_SRC_ALPHA_SATURATE = 14,
VK_BLEND_FACTOR_SRC1_COLOR = 15,
VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR = 16,
VK_BLEND_FACTOR_SRC1_ALPHA = 17,
VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA = 18,
} VkBlendFactor;
The semantics of the enum values are described in the table below:
| VkBlendFactor | RGB Blend Factors (Sr,Sg,Sb) or (Dr,Dg,Db) | Alpha Blend Factor (Sa or Da) |
|---|---|---|
|
(0,0,0) |
0 |
|
(1,1,1) |
1 |
|
(Rs0,Gs0,Bs0) |
As0 |
|
(1-Rs0,1-Gs0,1-Bs0) |
1-As0 |
|
(Rd,Gd,Bd) |
Ad |
|
(1-Rd,1-Gd,1-Bd) |
1-Ad |
|
(As0,As0,As0) |
As0 |
|
(1-As0,1-As0,1-As0) |
1-As0 |
|
(Ad,Ad,Ad) |
Ad |
|
(1-Ad,1-Ad,1-Ad) |
1-Ad |
|
(Rc,Gc,Bc) |
Ac |
|
(1-Rc,1-Gc,1-Bc) |
1-Ac |
|
(Ac,Ac,Ac) |
Ac |
|
(1-Ac,1-Ac,1-Ac) |
1-Ac |
|
(f,f,f); f = min(As0,1-Ad) |
1 |
|
(Rs1,Gs1,Bs1) |
As1 |
|
(1-Rs1,1-Gs1,1-Bs1) |
1-As1 |
|
(As1,As1,As1) |
As1 |
|
(1-As1,1-As1,1-As1) |
1-As1 |
In this table, the following conventions are used:
-
Rs0,Gs0,Bs0 and As0 represent the first source color R, G, B, and A components, respectively, for the fragment output location corresponding to the color attachment being blended.
-
Rs1,Gs1,Bs1 and As1 represent the second source color R, G, B, and A components, respectively, used in dual source blending modes, for the fragment output location corresponding to the color attachment being blended.
-
Rd,Gd,Bd and Ad represent the R, G, B, and A components of the destination color. That is, the color currently in the corresponding color attachment for this fragment/sample.
-
Rc,Gc,Bc and Ac represent the blend constant R, G, B, and A components, respectively.
To dynamically set and change the blend constants, call:
// Provided by VK_VERSION_1_0
void vkCmdSetBlendConstants(
VkCommandBuffer commandBuffer,
const float blendConstants[4]);
-
commandBufferis the command buffer into which the command will be recorded. -
blendConstantsis a pointer to an array of four values specifying the Rc, Gc, Bc, and Ac components of the blend constant color used in blending, depending on the blend factor.
This command sets blend constants for subsequent drawing commands when the
graphics pipeline is created with VK_DYNAMIC_STATE_BLEND_CONSTANTS set
in VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineColorBlendStateCreateInfo::blendConstants values used
to create the currently active pipeline.
29.1.2. Dual-Source Blending
Blend factors that use the secondary color input
(Rs1,Gs1,Bs1,As1) (VK_BLEND_FACTOR_SRC1_COLOR,
VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR,
VK_BLEND_FACTOR_SRC1_ALPHA, and
VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA) may consume implementation
resources that could otherwise be used for rendering to multiple color
attachments.
Therefore, the number of color attachments that can be used in a
framebuffer may be lower when using dual-source blending.
Dual-source blending is only supported if the dualSrcBlend feature is enabled.
The maximum number of color attachments that can be used in a subpass when
using dual-source blending functions is implementation-dependent and is
reported as the maxFragmentDualSrcAttachments member of
VkPhysicalDeviceLimits.
When using a fragment shader with dual-source blending functions, the color
outputs are bound to the first and second inputs of the blender using the
Index decoration, as described in Fragment
Output Interface.
If the second color input to the blender is not written in the shader, or if
no output is bound to the second input of a blender, the result of the
blending operation is not defined.
29.1.3. Blend Operations
Once the source and destination blend factors have been selected, they along with the source and destination components are passed to the blending operations. RGB and alpha components can use different operations. Possible values of VkBlendOp, specifying the operations, are:
// Provided by VK_VERSION_1_0
typedef enum VkBlendOp {
VK_BLEND_OP_ADD = 0,
VK_BLEND_OP_SUBTRACT = 1,
VK_BLEND_OP_REVERSE_SUBTRACT = 2,
VK_BLEND_OP_MIN = 3,
VK_BLEND_OP_MAX = 4,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_ZERO_EXT = 1000148000,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_SRC_EXT = 1000148001,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_DST_EXT = 1000148002,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_SRC_OVER_EXT = 1000148003,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_DST_OVER_EXT = 1000148004,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_SRC_IN_EXT = 1000148005,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_DST_IN_EXT = 1000148006,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_SRC_OUT_EXT = 1000148007,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_DST_OUT_EXT = 1000148008,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_SRC_ATOP_EXT = 1000148009,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_DST_ATOP_EXT = 1000148010,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_XOR_EXT = 1000148011,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_MULTIPLY_EXT = 1000148012,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_SCREEN_EXT = 1000148013,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_OVERLAY_EXT = 1000148014,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_DARKEN_EXT = 1000148015,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_LIGHTEN_EXT = 1000148016,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_COLORDODGE_EXT = 1000148017,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_COLORBURN_EXT = 1000148018,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_HARDLIGHT_EXT = 1000148019,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_SOFTLIGHT_EXT = 1000148020,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_DIFFERENCE_EXT = 1000148021,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_EXCLUSION_EXT = 1000148022,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_INVERT_EXT = 1000148023,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_INVERT_RGB_EXT = 1000148024,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_LINEARDODGE_EXT = 1000148025,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_LINEARBURN_EXT = 1000148026,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_VIVIDLIGHT_EXT = 1000148027,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_LINEARLIGHT_EXT = 1000148028,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_PINLIGHT_EXT = 1000148029,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_HARDMIX_EXT = 1000148030,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_HSL_HUE_EXT = 1000148031,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_HSL_SATURATION_EXT = 1000148032,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_HSL_COLOR_EXT = 1000148033,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_HSL_LUMINOSITY_EXT = 1000148034,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_PLUS_EXT = 1000148035,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_PLUS_CLAMPED_EXT = 1000148036,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT = 1000148037,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_PLUS_DARKER_EXT = 1000148038,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_MINUS_EXT = 1000148039,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_MINUS_CLAMPED_EXT = 1000148040,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_CONTRAST_EXT = 1000148041,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_INVERT_OVG_EXT = 1000148042,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_RED_EXT = 1000148043,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_GREEN_EXT = 1000148044,
// Provided by VK_EXT_blend_operation_advanced
VK_BLEND_OP_BLUE_EXT = 1000148045,
} VkBlendOp;
The semantics of the basic blend operations are described in the table below:
| VkBlendOp | RGB Components | Alpha Component |
|---|---|---|
|
R = Rs0 × Sr + Rd × Dr |
A = As0 × Sa + Ad × Da |
|
R = Rs0 × Sr - Rd × Dr |
A = As0 × Sa - Ad × Da |
|
R = Rd × Dr - Rs0 × Sr |
A = Ad × Da - As0 × Sa |
|
R = min(Rs0,Rd) |
A = min(As0,Ad) |
|
R = max(Rs0,Rd) |
A = max(As0,Ad) |
In this table, the following conventions are used:
-
Rs0, Gs0, Bs0 and As0 represent the first source color R, G, B, and A components, respectively.
-
Rd, Gd, Bd and Ad represent the R, G, B, and A components of the destination color. That is, the color currently in the corresponding color attachment for this fragment/sample.
-
Sr, Sg, Sb and Sa represent the source blend factor R, G, B, and A components, respectively.
-
Dr, Dg, Db and Da represent the destination blend factor R, G, B, and A components, respectively.
The blending operation produces a new set of values R, G, B and A, which are written to the framebuffer attachment. If blending is not enabled for this attachment, then R, G, B and A are assigned Rs0, Gs0, Bs0 and As0, respectively.
If the color attachment is fixed-point, the components of the source and destination values and blend factors are each clamped to [0,1] or [-1,1] respectively for an unsigned normalized or signed normalized color attachment prior to evaluating the blend operations. If the color attachment is floating-point, no clamping occurs.
If the numeric format of a framebuffer attachment uses sRGB encoding, the R, G, and B destination color values (after conversion from fixed-point to floating-point) are considered to be encoded for the sRGB color space and hence are linearized prior to their use in blending. Each R, G, and B component is converted from nonlinear to linear as described in the “sRGB EOTF” section of the Khronos Data Format Specification. If the format is not sRGB, no linearization is performed.
If the numeric format of a framebuffer attachment uses sRGB encoding, then the final R, G and B values are converted into the nonlinear sRGB representation before being written to the framebuffer attachment as described in the “sRGB EOTF -1” section of the Khronos Data Format Specification.
If the numeric format of a framebuffer color attachment is not sRGB encoded then the resulting cs values for R, G and B are unmodified. The value of A is never sRGB encoded. That is, the alpha component is always stored in memory as linear.
If the framebuffer color attachment is VK_ATTACHMENT_UNUSED, no writes
are performed through that attachment.
Writes are not performed to framebuffer color attachments greater than or
equal to the VkSubpassDescription::colorAttachmentCount
or VkSubpassDescription2::colorAttachmentCount
value.
29.1.4. Advanced Blend Operations
The advanced blend operations are those listed in tables f/X/Y/Z Advanced Blend Operations, Hue-Saturation-Luminosity Advanced Blend Operations, and Additional RGB Blend Operations.
If the pNext chain of VkPipelineColorBlendStateCreateInfo
includes a VkPipelineColorBlendAdvancedStateCreateInfoEXT structure,
then that structure includes parameters that affect advanced blend
operations.
The VkPipelineColorBlendAdvancedStateCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_blend_operation_advanced
typedef struct VkPipelineColorBlendAdvancedStateCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkBool32 srcPremultiplied;
VkBool32 dstPremultiplied;
VkBlendOverlapEXT blendOverlap;
} VkPipelineColorBlendAdvancedStateCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcPremultipliedspecifies whether the source color of the blend operation is treated as premultiplied. -
dstPremultipliedspecifies whether the destination color of the blend operation is treated as premultiplied. -
blendOverlapis a VkBlendOverlapEXT value specifying how the source and destination sample’s coverage is correlated.
If this structure is not present, srcPremultiplied and
dstPremultiplied are both considered to be VK_TRUE, and
blendOverlap is considered to be
VK_BLEND_OVERLAP_UNCORRELATED_EXT.
When using one of the operations in table f/X/Y/Z Advanced Blend Operations or Hue-Saturation-Luminosity Advanced Blend Operations, blending is performed according to the following equations:
where the function f and terms X, Y, and Z are specified in the table.
The R, G, and B components of the source color used for blending are derived
according to srcPremultiplied.
If srcPremultiplied is set to VK_TRUE, the fragment color
components are considered to have been premultiplied by the A component
prior to blending.
The base source color (Rs',Gs',Bs') is obtained by dividing
through by the A component:
If srcPremultiplied is VK_FALSE, the fragment color components
are used as the base color:
The R, G, and B components of the destination color used for blending are
derived according to dstPremultiplied.
If dstPremultiplied is set to VK_TRUE, the destination
components are considered to have been premultiplied by the A component
prior to blending.
The base destination color (Rd',Gd',Bd') is obtained by dividing
through by the A component:
If dstPremultiplied is VK_FALSE, the destination color
components are used as the base color:
When blending using advanced blend operations, we expect that the R, G, and B components of premultiplied source and destination color inputs be stored as the product of non-premultiplied R, G, and B component values and the A component of the color. If any R, G, or B component of a premultiplied input color is non-zero and the A component is zero, the color is considered ill-formed, and the corresponding component of the blend result is undefined.
All of the advanced blend operation formulas in this chapter compute the
result as a premultiplied color.
If dstPremultiplied is VK_FALSE, that result color’s R, G, and B
components are divided by the A component before being written to the
framebuffer.
If any R, G, or B component of the color is non-zero and the A component is
zero, the result is considered ill-formed, and the corresponding component
of the blend result is undefined.
If all components are zero, that value is unchanged.
If the A component of any input or result color is less than zero, the color is considered ill-formed, and all components of the blend result are undefined.
The weighting functions p0, p1, and p2 are defined in table Advanced Blend Overlap Modes. In these functions, the A components of the source and destination colors are taken to indicate the portion of the pixel covered by the fragment (source) and the fragments previously accumulated in the pixel (destination). The functions p0, p1, and p2 approximate the relative portion of the pixel covered by the intersection of the source and destination, covered only by the source, and covered only by the destination, respectively.
Possible values of
VkPipelineColorBlendAdvancedStateCreateInfoEXT::blendOverlap,
specifying the blend overlap functions, are:
// Provided by VK_EXT_blend_operation_advanced
typedef enum VkBlendOverlapEXT {
VK_BLEND_OVERLAP_UNCORRELATED_EXT = 0,
VK_BLEND_OVERLAP_DISJOINT_EXT = 1,
VK_BLEND_OVERLAP_CONJOINT_EXT = 2,
} VkBlendOverlapEXT;
-
VK_BLEND_OVERLAP_UNCORRELATED_EXTspecifies that there is no correlation between the source and destination coverage. -
VK_BLEND_OVERLAP_CONJOINT_EXTspecifies that the source and destination coverage are considered to have maximal overlap. -
VK_BLEND_OVERLAP_DISJOINT_EXTspecifies that the source and destination coverage are considered to have minimal overlap.
| Overlap Mode | Weighting Equations |
|---|---|
|
|
|
|
|
| Mode | Blend Coefficients |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When using one of the HSL blend operations in table Hue-Saturation-Luminosity Advanced Blend Operations as the blend operation, the RGB color components produced by the function f are effectively obtained by converting both the non-premultiplied source and destination colors to the HSL (hue, saturation, luminosity) color space, generating a new HSL color by selecting H, S, and L components from the source or destination according to the blend operation, and then converting the result back to RGB. In the equations below, a blended RGB color is produced according to the following pseudocode:
float minv3(vec3 c) {
return min(min(c.r, c.g), c.b);
}
float maxv3(vec3 c) {
return max(max(c.r, c.g), c.b);
}
float lumv3(vec3 c) {
return dot(c, vec3(0.30, 0.59, 0.11));
}
float satv3(vec3 c) {
return maxv3(c) - minv3(c);
}
// If any color components are outside [0,1], adjust the color to
// get the components in range.
vec3 ClipColor(vec3 color) {
float lum = lumv3(color);
float mincol = minv3(color);
float maxcol = maxv3(color);
if (mincol < 0.0) {
color = lum + ((color-lum)*lum) / (lum-mincol);
}
if (maxcol > 1.0) {
color = lum + ((color-lum)*(1-lum)) / (maxcol-lum);
}
return color;
}
// Take the base RGB color <cbase> and override its luminosity
// with that of the RGB color <clum>.
vec3 SetLum(vec3 cbase, vec3 clum) {
float lbase = lumv3(cbase);
float llum = lumv3(clum);
float ldiff = llum - lbase;
vec3 color = cbase + vec3(ldiff);
return ClipColor(color);
}
// Take the base RGB color <cbase> and override its saturation with
// that of the RGB color <csat>. The override the luminosity of the
// result with that of the RGB color <clum>.
vec3 SetLumSat(vec3 cbase, vec3 csat, vec3 clum)
{
float minbase = minv3(cbase);
float sbase = satv3(cbase);
float ssat = satv3(csat);
vec3 color;
if (sbase > 0) {
// Equivalent (modulo rounding errors) to setting the
// smallest (R,G,B) component to 0, the largest to <ssat>,
// and interpolating the "middle" component based on its
// original value relative to the smallest/largest.
color = (cbase - minbase) * ssat / sbase;
} else {
color = vec3(0.0);
}
return SetLum(color, clum);
}
| Mode | Result |
|---|---|
|
|
|
|
|
|
|
When using one of the operations in table
Additional RGB Blend
Operations as the blend operation, the source and destination colors used
by these blending operations are interpreted according to
srcPremultiplied and dstPremultiplied.
The blending operations below are evaluated where the RGB source and
destination color components are both considered to have been premultiplied
by the corresponding A component.
| Mode | Result |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
29.2. Logical Operations
The application can enable a logical operation between the fragment’s color values and the existing value in the framebuffer attachment. This logical operation is applied prior to updating the framebuffer attachment. Logical operations are applied only for signed and unsigned integer and normalized integer framebuffers. Logical operations are not applied to floating-point or sRGB format color attachments.
Logical operations are controlled by the logicOpEnable and
logicOp members of VkPipelineColorBlendStateCreateInfo.
It can also be controlled by vkCmdSetLogicOpEXT if graphics pipeline
is created with VK_DYNAMIC_STATE_LOGIC_OP_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
If logicOpEnable is VK_TRUE, then a logical operation selected
by logicOp is applied between each color attachment and the fragment’s
corresponding output value, and blending of all attachments is treated as if
it were disabled.
Any attachments using color formats for which logical operations are not
supported simply pass through the color values unmodified.
The logical operation is applied independently for each of the red, green,
blue, and alpha components.
The logicOp is selected from the following operations:
// Provided by VK_VERSION_1_0
typedef enum VkLogicOp {
VK_LOGIC_OP_CLEAR = 0,
VK_LOGIC_OP_AND = 1,
VK_LOGIC_OP_AND_REVERSE = 2,
VK_LOGIC_OP_COPY = 3,
VK_LOGIC_OP_AND_INVERTED = 4,
VK_LOGIC_OP_NO_OP = 5,
VK_LOGIC_OP_XOR = 6,
VK_LOGIC_OP_OR = 7,
VK_LOGIC_OP_NOR = 8,
VK_LOGIC_OP_EQUIVALENT = 9,
VK_LOGIC_OP_INVERT = 10,
VK_LOGIC_OP_OR_REVERSE = 11,
VK_LOGIC_OP_COPY_INVERTED = 12,
VK_LOGIC_OP_OR_INVERTED = 13,
VK_LOGIC_OP_NAND = 14,
VK_LOGIC_OP_SET = 15,
} VkLogicOp;
The logical operations supported by Vulkan are summarized in the following table in which
-
¬ is bitwise invert,
-
∧ is bitwise and,
-
∨ is bitwise or,
-
⊕ is bitwise exclusive or,
-
s is the fragment’s Rs0, Gs0, Bs0 or As0 component value for the fragment output corresponding to the color attachment being updated, and
-
d is the color attachment’s R, G, B or A component value:
| Mode | Operation |
|---|---|
|
0 |
|
s ∧ d |
|
s ∧ ¬ d |
|
s |
|
¬ s ∧ d |
|
d |
|
s ⊕ d |
|
s ∨ d |
|
¬ (s ∨ d) |
|
¬ (s ⊕ d) |
|
¬ d |
|
s ∨ ¬ d |
|
¬ s |
|
¬ s ∨ d |
|
¬ (s ∧ d) |
|
all 1s |
The result of the logical operation is then written to the color attachment as controlled by the component write mask, described in Blend Operations.
To dynamically set the logical operation to apply for blend state, call:
// Provided by VK_EXT_extended_dynamic_state2
void vkCmdSetLogicOpEXT(
VkCommandBuffer commandBuffer,
VkLogicOp logicOp);
-
commandBufferis the command buffer into which the command will be recorded. -
logicOpspecifies the logical operation to apply for blend state.
This command sets the logical operation for blend state for subsequent
drawing commands when the graphics pipeline is created with
VK_DYNAMIC_STATE_LOGIC_OP_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineColorBlendStateCreateInfo::logicOp value used to
create the currently active pipeline.
29.3. Color Write Mask
Bits which can be set in
VkPipelineColorBlendAttachmentState::colorWriteMask, determining
whether the final color values R, G, B and A are written to the
framebuffer attachment, are:
// Provided by VK_VERSION_1_0
typedef enum VkColorComponentFlagBits {
VK_COLOR_COMPONENT_R_BIT = 0x00000001,
VK_COLOR_COMPONENT_G_BIT = 0x00000002,
VK_COLOR_COMPONENT_B_BIT = 0x00000004,
VK_COLOR_COMPONENT_A_BIT = 0x00000008,
} VkColorComponentFlagBits;
-
VK_COLOR_COMPONENT_R_BITspecifies that the R value is written to the color attachment for the appropriate sample. Otherwise, the value in memory is unmodified. -
VK_COLOR_COMPONENT_G_BITspecifies that the G value is written to the color attachment for the appropriate sample. Otherwise, the value in memory is unmodified. -
VK_COLOR_COMPONENT_B_BITspecifies that the B value is written to the color attachment for the appropriate sample. Otherwise, the value in memory is unmodified. -
VK_COLOR_COMPONENT_A_BITspecifies that the A value is written to the color attachment for the appropriate sample. Otherwise, the value in memory is unmodified.
The color write mask operation is applied regardless of whether blending is enabled.
The color write mask operation is applied only if Color Write Enable is enabled for the respective attachment. Otherwise the color write mask is ignored and writes to all components of the attachment are disabled.
// Provided by VK_VERSION_1_0
typedef VkFlags VkColorComponentFlags;
VkColorComponentFlags is a bitmask type for setting a mask of zero or
more VkColorComponentFlagBits.
29.4. Color Write Enable
The VkPipelineColorWriteCreateInfoEXT structure is defined as:
// Provided by VK_EXT_color_write_enable
typedef struct VkPipelineColorWriteCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t attachmentCount;
const VkBool32* pColorWriteEnables;
} VkPipelineColorWriteCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentCountis the number ofVkBool32elements inpColorWriteEnables. -
pColorWriteEnablesis a pointer to an array of per target attachment boolean values specifying whether color writes are enabled for the given attachment.
When this structure is included in the pNext chain of
VkPipelineColorBlendStateCreateInfo, it defines per-attachment color
write state.
If this structure is not included in the pNext chain, it is equivalent
to specifying this structure with attachmentCount equal to the
attachmentCount member of VkPipelineColorBlendStateCreateInfo,
and pColorWriteEnables pointing to an array of as many VK_TRUE
values.
If the colorWriteEnable feature is not
enabled on the device, all VkBool32 elements in the
pColorWriteEnables array must be VK_TRUE.
Color Write Enable interacts with the Color Write Mask as follows:
-
If
colorWriteEnableisVK_TRUE, writes to the attachment are determined by thecolorWriteMask. -
If
colorWriteEnableisVK_FALSE, thecolorWriteMaskis ignored and writes to all components of the attachment are disabled. This is equivalent to specifying acolorWriteMaskof 0.
To dynamically enable or disable writes to a color attachment, call:
// Provided by VK_EXT_color_write_enable
void vkCmdSetColorWriteEnableEXT(
VkCommandBuffer commandBuffer,
uint32_t attachmentCount,
const VkBool32* pColorWriteEnables);
-
commandBufferis the command buffer into which the command will be recorded. -
attachmentCountis the number ofVkBool32elements inpColorWriteEnables. -
pColorWriteEnablesis a pointer to an array of per target attachment boolean values specifying whether color writes are enabled for the given attachment.
This command sets the color write enables for subsequent drawing commands
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineColorWriteCreateInfoEXT::pColorWriteEnables values
used to create the currently active pipeline.
30. Dispatching Commands
Dispatching commands (commands with Dispatch in the name) provoke
work in a compute pipeline.
Dispatching commands are recorded into a command buffer and when executed by
a queue, will produce work which executes according to the bound compute
pipeline.
A compute pipeline must be bound to a command buffer before any dispatching
commands are recorded in that command buffer.
To record a dispatch, call:
// Provided by VK_VERSION_1_0
void vkCmdDispatch(
VkCommandBuffer commandBuffer,
uint32_t groupCountX,
uint32_t groupCountY,
uint32_t groupCountZ);
-
commandBufferis the command buffer into which the command will be recorded. -
groupCountXis the number of local workgroups to dispatch in the X dimension. -
groupCountYis the number of local workgroups to dispatch in the Y dimension. -
groupCountZis the number of local workgroups to dispatch in the Z dimension.
When the command is executed, a global workgroup consisting of
groupCountX × groupCountY × groupCountZ
local workgroups is assembled.
To record an indirect dispatching command, call:
// Provided by VK_VERSION_1_0
void vkCmdDispatchIndirect(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset);
-
commandBufferis the command buffer into which the command will be recorded. -
bufferis the buffer containing dispatch parameters. -
offsetis the byte offset intobufferwhere parameters begin.
vkCmdDispatchIndirect behaves similarly to vkCmdDispatch except
that the parameters are read by the device from a buffer during execution.
The parameters of the dispatch are encoded in a
VkDispatchIndirectCommand structure taken from buffer starting
at offset.
The VkDispatchIndirectCommand structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkDispatchIndirectCommand {
uint32_t x;
uint32_t y;
uint32_t z;
} VkDispatchIndirectCommand;
-
xis the number of local workgroups to dispatch in the X dimension. -
yis the number of local workgroups to dispatch in the Y dimension. -
zis the number of local workgroups to dispatch in the Z dimension.
The members of VkDispatchIndirectCommand have the same meaning as the
corresponding parameters of vkCmdDispatch.
To record a dispatch using non-zero base values for the components of
WorkgroupId, call:
// Provided by VK_VERSION_1_1
void vkCmdDispatchBase(
VkCommandBuffer commandBuffer,
uint32_t baseGroupX,
uint32_t baseGroupY,
uint32_t baseGroupZ,
uint32_t groupCountX,
uint32_t groupCountY,
uint32_t groupCountZ);
or the equivalent command
// Provided by VK_KHR_device_group
void vkCmdDispatchBaseKHR(
VkCommandBuffer commandBuffer,
uint32_t baseGroupX,
uint32_t baseGroupY,
uint32_t baseGroupZ,
uint32_t groupCountX,
uint32_t groupCountY,
uint32_t groupCountZ);
-
commandBufferis the command buffer into which the command will be recorded. -
baseGroupXis the start value for the X component ofWorkgroupId. -
baseGroupYis the start value for the Y component ofWorkgroupId. -
baseGroupZis the start value for the Z component ofWorkgroupId. -
groupCountXis the number of local workgroups to dispatch in the X dimension. -
groupCountYis the number of local workgroups to dispatch in the Y dimension. -
groupCountZis the number of local workgroups to dispatch in the Z dimension.
When the command is executed, a global workgroup consisting of
groupCountX × groupCountY × groupCountZ
local workgroups is assembled, with WorkgroupId values ranging from
[baseGroup*, baseGroup* + groupCount*) in each
component.
vkCmdDispatch is equivalent to
vkCmdDispatchBase(0,0,0,groupCountX,groupCountY,groupCountZ).
A subpass shading dispatches a compute pipeline work with the work dimension of render area of the calling subpass and work groups are partitioned by specified work group size. Subpass operations like subpassLoad and subpassLoadMS are allowed to be used.
To record a subpass shading, call:
// Provided by VK_HUAWEI_subpass_shading
void vkCmdSubpassShadingHUAWEI(
VkCommandBuffer commandBuffer);
-
commandBufferis the command buffer into which the command will be recorded.
When the command is executed, a global workgroup consisting of ceil (render area size / local workgroup size) local workgroups is assembled.
31. Device-Generated Commands
This chapter discusses the generation of command buffer content on the device, for which these principle steps are to be taken:
-
Define via
VkIndirectCommandsLayoutNVthe sequence of commands which should be generated. -
Optionally make use of device-bindable Shader Groups.
-
Retrieve device addresses by vkGetBufferDeviceAddressEXT for setting buffers on the device.
-
Fill one or more
VkBufferwith the appropriate content that gets interpreted byVkIndirectCommandsLayoutNV. -
Create a
preprocessVkBufferusing the allocation information from vkGetGeneratedCommandsMemoryRequirementsNV. -
Optionally preprocess the input data using vkCmdPreprocessGeneratedCommandsNV in a separate action.
-
Generate and execute the actual commands via vkCmdExecuteGeneratedCommandsNV passing all required data.
vkCmdPreprocessGeneratedCommandsNV executes in a separate logical pipeline from either graphics or compute. When preprocessing commands in a separate step they must be explicitly synchronized against the command execution. When not preprocessing, the preprocessing is automatically synchronized against the command execution.
31.1. Indirect Commands Layout
The device-side command generation happens through an iterative processing of an atomic sequence comprised of command tokens, which are represented by:
// Provided by VK_NV_device_generated_commands
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectCommandsLayoutNV)
31.1.1. Creation and Deletion
Indirect command layouts are created by:
// Provided by VK_NV_device_generated_commands
VkResult vkCreateIndirectCommandsLayoutNV(
VkDevice device,
const VkIndirectCommandsLayoutCreateInfoNV* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkIndirectCommandsLayoutNV* pIndirectCommandsLayout);
-
deviceis the logical device that creates the indirect command layout. -
pCreateInfois a pointer to aVkIndirectCommandsLayoutCreateInfoNVstructure containing parameters affecting creation of the indirect command layout. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pIndirectCommandsLayoutis a pointer to aVkIndirectCommandsLayoutNVhandle in which the resulting indirect command layout is returned.
The VkIndirectCommandsLayoutCreateInfoNV structure is defined as:
// Provided by VK_NV_device_generated_commands
typedef struct VkIndirectCommandsLayoutCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkIndirectCommandsLayoutUsageFlagsNV flags;
VkPipelineBindPoint pipelineBindPoint;
uint32_t tokenCount;
const VkIndirectCommandsLayoutTokenNV* pTokens;
uint32_t streamCount;
const uint32_t* pStreamStrides;
} VkIndirectCommandsLayoutCreateInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBindPointis the VkPipelineBindPoint that this layout targets. -
flagsis a bitmask of VkIndirectCommandsLayoutUsageFlagBitsNV specifying usage hints of this layout. -
tokenCountis the length of the individual command sequence. -
pTokensis an array describing each command token in detail. See VkIndirectCommandsTokenTypeNV and VkIndirectCommandsLayoutTokenNV below for details. -
streamCountis the number of streams used to provide the token inputs. -
pStreamStridesis an array defining the byte stride for each input stream.
The following code illustrates some of the flags:
void cmdProcessAllSequences(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsTokens, sequencesCount, indexbuffer, indexbufferOffset)
{
for (s = 0; s < sequencesCount; s++)
{
sUsed = s;
if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV) {
sUsed = indexbuffer.load_uint32( sUsed * sizeof(uint32_t) + indexbufferOffset);
}
if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV) {
sUsed = incoherent_implementation_dependent_permutation[ sUsed ];
}
cmdProcessSequence( cmd, pipeline, indirectCommandsLayout, pIndirectCommandsTokens, sUsed );
}
}
When tokens are consumed, an offset is computed based on token offset and
stream stride.
The resulting offset is required to be aligned.
The alignment for a specific token is equal to the scalar alignment of the
data type as defined in Alignment
Requirements, or
VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::minIndirectCommandsBufferOffsetAlignment,
whichever is lower.
|
Note
A |
Bits which can be set in
VkIndirectCommandsLayoutCreateInfoNV::flags, specifying usage
hints of an indirect command layout, are:
// Provided by VK_NV_device_generated_commands
typedef enum VkIndirectCommandsLayoutUsageFlagBitsNV {
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NV = 0x00000001,
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NV = 0x00000002,
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV = 0x00000004,
} VkIndirectCommandsLayoutUsageFlagBitsNV;
-
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_NVspecifies that the layout is always used with the manual preprocessing step through calling vkCmdPreprocessGeneratedCommandsNV and executed by vkCmdExecuteGeneratedCommandsNV withisPreprocessedset toVK_TRUE. -
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT_NVspecifies that the input data for the sequences is not implicitly indexed from 0..sequencesUsed but a user providedVkBufferencoding the index is provided. -
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NVspecifies that the processing of sequences can happen at an implementation-dependent order, which is not: guaranteed to be coherent using the same input data.
// Provided by VK_NV_device_generated_commands
typedef VkFlags VkIndirectCommandsLayoutUsageFlagsNV;
VkIndirectCommandsLayoutUsageFlagsNV is a bitmask type for setting a
mask of zero or more VkIndirectCommandsLayoutUsageFlagBitsNV.
Indirect command layouts are destroyed by:
// Provided by VK_NV_device_generated_commands
void vkDestroyIndirectCommandsLayoutNV(
VkDevice device,
VkIndirectCommandsLayoutNV indirectCommandsLayout,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the layout. -
indirectCommandsLayoutis the layout to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
31.1.2. Token Input Streams
The VkIndirectCommandsStreamNV structure specifies the input data for
one or more tokens at processing time.
// Provided by VK_NV_device_generated_commands
typedef struct VkIndirectCommandsStreamNV {
VkBuffer buffer;
VkDeviceSize offset;
} VkIndirectCommandsStreamNV;
-
bufferspecifies the VkBuffer storing the functional arguments for each sequence. These arguments can be written by the device. -
offsetspecified an offset intobufferwhere the arguments start.
The input streams can contain raw uint32_t values, existing indirect
commands such as:
or additional commands as listed below. How the data is used is described in the next section.
The VkBindShaderGroupIndirectCommandNV structure specifies the input
data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV token.
// Provided by VK_NV_device_generated_commands
typedef struct VkBindShaderGroupIndirectCommandNV {
uint32_t groupIndex;
} VkBindShaderGroupIndirectCommandNV;
-
indexspecifies which shader group of the current bound graphics pipeline is used.
The VkBindIndexBufferIndirectCommandNV structure specifies the input
data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV token.
// Provided by VK_NV_device_generated_commands
typedef struct VkBindIndexBufferIndirectCommandNV {
VkDeviceAddress bufferAddress;
uint32_t size;
VkIndexType indexType;
} VkBindIndexBufferIndirectCommandNV;
-
bufferAddressspecifies a physical address of the VkBuffer used as index buffer. -
sizeis the byte size range which is available for this operation from the provided address. -
indexTypeis a VkIndexType value specifying how indices are treated. Instead of the Vulkan enum values, a customuint32_tvalue can be mapped to an VkIndexType by specifying theVkIndirectCommandsLayoutTokenNV::pIndexTypesandVkIndirectCommandsLayoutTokenNV::pIndexTypeValuesarrays.
The VkBindVertexBufferIndirectCommandNV structure specifies the input
data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV token.
// Provided by VK_NV_device_generated_commands
typedef struct VkBindVertexBufferIndirectCommandNV {
VkDeviceAddress bufferAddress;
uint32_t size;
uint32_t stride;
} VkBindVertexBufferIndirectCommandNV;
-
bufferAddressspecifies a physical address of the VkBuffer used as vertex input binding. -
sizeis the byte size range which is available for this operation from the provided address. -
strideis the byte size stride for this vertex input binding as inVkVertexInputBindingDescription::stride. It is only used ifVkIndirectCommandsLayoutTokenNV::vertexDynamicStridewas set, otherwise the stride is inherited from the current bound graphics pipeline.
The VkSetStateFlagsIndirectCommandNV structure specifies the input
data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV token.
Which state is changed depends on the VkIndirectStateFlagBitsNV
specified at VkIndirectCommandsLayoutNV creation time.
// Provided by VK_NV_device_generated_commands
typedef struct VkSetStateFlagsIndirectCommandNV {
uint32_t data;
} VkSetStateFlagsIndirectCommandNV;
-
dataencodes packed state that this command alters.-
Bit
0: If set representsVK_FRONT_FACE_CLOCKWISE, otherwiseVK_FRONT_FACE_COUNTER_CLOCKWISE
-
A subset of the graphics pipeline state can be altered using indirect state flags:
// Provided by VK_NV_device_generated_commands
typedef enum VkIndirectStateFlagBitsNV {
VK_INDIRECT_STATE_FLAG_FRONTFACE_BIT_NV = 0x00000001,
} VkIndirectStateFlagBitsNV;
-
VK_INDIRECT_STATE_FLAG_FRONTFACE_BIT_NVallows to toggle the VkFrontFace rasterization state for subsequent draw operations.
// Provided by VK_NV_device_generated_commands
typedef VkFlags VkIndirectStateFlagsNV;
VkIndirectStateFlagsNV is a bitmask type for setting a mask of zero or
more VkIndirectStateFlagBitsNV.
31.1.3. Tokenized Command Processing
The processing is in principle illustrated below:
void cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s)
{
for (t = 0; t < indirectCommandsLayout.tokenCount; t++)
{
uint32_t stream = indirectCommandsLayout.pTokens[t].stream;
uint32_t offset = indirectCommandsLayout.pTokens[t].offset;
uint32_t stride = indirectCommandsLayout.pStreamStrides[stream];
stream = pIndirectCommandsStreams[stream];
const void* input = stream.buffer.pointer( stream.offset + stride * s + offset )
// further details later
indirectCommandsLayout.pTokens[t].command (cmd, pipeline, input, s);
}
}
void cmdProcessAllSequences(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, sequencesCount)
{
for (s = 0; s < sequencesCount; s++)
{
cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s);
}
}
The processing of each sequence is considered stateless, therefore all state changes must occur prior work provoking commands within the sequence. A single sequence is strictly targeting the VkPipelineBindPoint it was created with.
The primary input data for each token is provided through VkBuffer
content at preprocessing using vkCmdPreprocessGeneratedCommandsNV or
execution time using vkCmdExecuteGeneratedCommandsNV, however some
functional arguments, for example binding sets, are specified at layout
creation time.
The input size is different for each token.
Possible values of those elements of the
VkIndirectCommandsLayoutCreateInfoNV::pTokens array specifying
command tokens (other elements of the array specify command parameters) are:
// Provided by VK_NV_device_generated_commands
typedef enum VkIndirectCommandsTokenTypeNV {
VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV = 0,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV = 1,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV = 2,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV = 3,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV = 4,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV = 5,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV = 6,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV = 7,
} VkIndirectCommandsTokenTypeNV;
| Token type | Equivalent command |
|---|---|
|
|
|
- |
|
|
|
|
|
|
|
|
|
|
|
The VkIndirectCommandsLayoutTokenNV structure specifies details to the
function arguments that need to be known at layout creation time:
// Provided by VK_NV_device_generated_commands
typedef struct VkIndirectCommandsLayoutTokenNV {
VkStructureType sType;
const void* pNext;
VkIndirectCommandsTokenTypeNV tokenType;
uint32_t stream;
uint32_t offset;
uint32_t vertexBindingUnit;
VkBool32 vertexDynamicStride;
VkPipelineLayout pushconstantPipelineLayout;
VkShaderStageFlags pushconstantShaderStageFlags;
uint32_t pushconstantOffset;
uint32_t pushconstantSize;
VkIndirectStateFlagsNV indirectStateFlags;
uint32_t indexTypeCount;
const VkIndexType* pIndexTypes;
const uint32_t* pIndexTypeValues;
} VkIndirectCommandsLayoutTokenNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tokenTypespecifies the token command type. -
streamis the index of the input stream containing the token argument data. -
offsetis a relative starting offset within the input stream memory for the token argument data. -
vertexBindingUnitis used for the vertex buffer binding command. -
vertexDynamicStridesets if the vertex buffer stride is provided by the binding command rather than the current bound graphics pipeline state. -
pushconstantPipelineLayoutis theVkPipelineLayoutused for the push constant command. -
pushconstantShaderStageFlagsare the shader stage flags used for the push constant command. -
pushconstantOffsetis the offset used for the push constant command. -
pushconstantSizeis the size used for the push constant command. -
indirectStateFlagsare the active states for the state flag command. -
indexTypeCountis the optional size of thepIndexTypesandpIndexTypeValuesarray pairings. If not zero, it allows to register a customuint32_tvalue to be treated as specificVkIndexType. -
pIndexTypesis the usedVkIndexTypefor the correspondinguint32_tvalue entry inpIndexTypeValues.
The following code provides detailed information on how an individual sequence is processed. For valid usage, all restrictions from the regular commands apply.
void cmdProcessSequence(cmd, pipeline, indirectCommandsLayout, pIndirectCommandsStreams, s)
{
for (uint32_t t = 0; t < indirectCommandsLayout.tokenCount; t++){
token = indirectCommandsLayout.pTokens[t];
uint32_t stride = indirectCommandsLayout.pStreamStrides[token.stream];
stream = pIndirectCommandsStreams[token.stream];
uint32_t offset = stream.offset + stride * s + token.offset;
const void* input = stream.buffer.pointer( offset )
switch(input.type){
VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV:
VkBindShaderGroupIndirectCommandNV* bind = input;
vkCmdBindPipelineShaderGroupNV(cmd, indirectCommandsLayout.pipelineBindPoint,
pipeline, bind->groupIndex);
break;
VK_INDIRECT_COMMANDS_TOKEN_TYPE_STATE_FLAGS_NV:
VkSetStateFlagsIndirectCommandNV* state = input;
if (token.indirectStateFlags & VK_INDIRECT_STATE_FLAG_FRONTFACE_BIT_NV){
if (state.data & (1 << 0)){
set VK_FRONT_FACE_CLOCKWISE;
} else {
set VK_FRONT_FACE_COUNTER_CLOCKWISE;
}
}
break;
VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV:
uint32_t* data = input;
vkCmdPushConstants(cmd,
token.pushconstantPipelineLayout
token.pushconstantStageFlags,
token.pushconstantOffset,
token.pushconstantSize, data);
break;
VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_NV:
VkBindIndexBufferIndirectCommandNV* data = input;
// the indexType may optionally be remapped
// from a custom uint32_t value, via
// VkIndirectCommandsLayoutTokenNV::pIndexTypeValues
vkCmdBindIndexBuffer(cmd,
deriveBuffer(data->bufferAddress),
deriveOffset(data->bufferAddress),
data->indexType);
break;
VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_NV:
VkBindVertexBufferIndirectCommandNV* data = input;
// if token.vertexDynamicStride is VK_TRUE
// then the stride for this binding is set
// using data->stride as well
vkCmdBindVertexBuffers(cmd,
token.vertexBindingUnit, 1,
&deriveBuffer(data->bufferAddress),
&deriveOffset(data->bufferAddress));
break;
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV:
vkCmdDrawIndexedIndirect(cmd,
stream.buffer, offset, 1, 0);
break;
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV:
vkCmdDrawIndirect(cmd,
stream.buffer,
offset, 1, 0);
break;
// only available if VK_NV_mesh_shader is supported
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV:
vkCmdDrawMeshTasksIndirectNV(cmd,
stream.buffer, offset, 1, 0);
break;
}
}
}
31.2. Indirect Commands Generation And Execution
The generation of commands on the device requires a preprocess buffer.
To retrieve the memory size and alignment requirements of a particular
execution state call:
// Provided by VK_NV_device_generated_commands
void vkGetGeneratedCommandsMemoryRequirementsNV(
VkDevice device,
const VkGeneratedCommandsMemoryRequirementsInfoNV* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device that owns the buffer. -
pInfois a pointer to aVkGeneratedCommandsMemoryRequirementsInfoNVstructure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.
// Provided by VK_NV_device_generated_commands
typedef struct VkGeneratedCommandsMemoryRequirementsInfoNV {
VkStructureType sType;
const void* pNext;
VkPipelineBindPoint pipelineBindPoint;
VkPipeline pipeline;
VkIndirectCommandsLayoutNV indirectCommandsLayout;
uint32_t maxSequencesCount;
} VkGeneratedCommandsMemoryRequirementsInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBindPointis the VkPipelineBindPoint of thepipelinethat this buffer memory is intended to be used with during the execution. -
pipelineis the VkPipeline that this buffer memory is intended to be used with during the execution. -
indirectCommandsLayoutis the VkIndirectCommandsLayoutNV that this buffer memory is intended to be used with. -
maxSequencesCountis the maximum number of sequences that this buffer memory in combination with the other state provided can be used with.
The actual generation of commands as well as their execution on the device is handled as single action with:
// Provided by VK_NV_device_generated_commands
void vkCmdExecuteGeneratedCommandsNV(
VkCommandBuffer commandBuffer,
VkBool32 isPreprocessed,
const VkGeneratedCommandsInfoNV* pGeneratedCommandsInfo);
-
commandBufferis the command buffer into which the command is recorded. -
isPreprocessedrepresents whether the input data has already been preprocessed on the device. If it isVK_FALSEthis command will implicitly trigger the preprocessing step, otherwise not. -
pGeneratedCommandsInfois a pointer to a VkGeneratedCommandsInfoNV structure containing parameters affecting the generation of commands.
// Provided by VK_NV_device_generated_commands
typedef struct VkGeneratedCommandsInfoNV {
VkStructureType sType;
const void* pNext;
VkPipelineBindPoint pipelineBindPoint;
VkPipeline pipeline;
VkIndirectCommandsLayoutNV indirectCommandsLayout;
uint32_t streamCount;
const VkIndirectCommandsStreamNV* pStreams;
uint32_t sequencesCount;
VkBuffer preprocessBuffer;
VkDeviceSize preprocessOffset;
VkDeviceSize preprocessSize;
VkBuffer sequencesCountBuffer;
VkDeviceSize sequencesCountOffset;
VkBuffer sequencesIndexBuffer;
VkDeviceSize sequencesIndexOffset;
} VkGeneratedCommandsInfoNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBindPointis the VkPipelineBindPoint used for thepipeline. -
pipelineis the VkPipeline used in the generation and execution process. -
indirectCommandsLayoutis the VkIndirectCommandsLayoutNV that provides the command sequence to generate. -
streamCountdefines the number of input streams -
pStreamsis a pointer to an array ofstreamCountVkIndirectCommandsStreamNV structures providing the input data for the tokens used inindirectCommandsLayout. -
sequencesCountis the maximum number of sequences to reserve. IfsequencesCountBufferis VK_NULL_HANDLE, this is also the actual number of sequences generated. -
preprocessBufferis the VkBuffer that is used for preprocessing the input data for execution. If this structure is used with vkCmdExecuteGeneratedCommandsNV with itsisPreprocessedset toVK_TRUE, then the preprocessing step is skipped and data is only read from this buffer. -
preprocessOffsetis the byte offset intopreprocessBufferwhere the preprocessed data is stored. -
preprocessSizeis the maximum byte size within thepreprocessBufferafter thepreprocessOffsetthat is available for preprocessing. -
sequencesCountBufferis aVkBufferin which the actual number of sequences is provided as singleuint32_tvalue. -
sequencesCountOffsetis the byte offset intosequencesCountBufferwhere the count value is stored. -
sequencesIndexBufferis aVkBufferthat encodes the used sequence indices asuint32_tarray. -
sequencesIndexOffsetis the byte offset intosequencesIndexBufferwhere the index values start.
Referencing the functions defined in Indirect Commands Layout,
vkCmdExecuteGeneratedCommandsNV behaves as:
uint32_t sequencesCount = sequencesCountBuffer ?
min(maxSequencesCount, sequencesCountBuffer.load_uint32(sequencesCountOffset) :
maxSequencesCount;
cmdProcessAllSequences(commandBuffer, pipeline,
indirectCommandsLayout, pIndirectCommandsStreams,
sequencesCount,
sequencesIndexBuffer, sequencesIndexOffset);
// The stateful commands within indirectCommandsLayout will not
// affect the state of subsequent commands in the target
// command buffer (cmd)
|
Note
It is important to note that the values of all state related to the
|
Commands can be preprocessed prior execution using the following command:
// Provided by VK_NV_device_generated_commands
void vkCmdPreprocessGeneratedCommandsNV(
VkCommandBuffer commandBuffer,
const VkGeneratedCommandsInfoNV* pGeneratedCommandsInfo);
-
commandBufferis the command buffer which does the preprocessing. -
pGeneratedCommandsInfois a pointer to a VkGeneratedCommandsInfoNV structure containing parameters affecting the preprocessing step.
32. Sparse Resources
As documented in Resource Memory Association,
VkBuffer and VkImage resources in Vulkan must be bound
completely and contiguously to a single VkDeviceMemory object.
This binding must be done before the resource is used, and the binding is
immutable for the lifetime of the resource.
Sparse resources relax these restrictions and provide these additional features:
-
Sparse resources can be bound non-contiguously to one or more
VkDeviceMemoryallocations. -
Sparse resources can be re-bound to different memory allocations over the lifetime of the resource.
-
Sparse resources can have descriptors generated and used orthogonally with memory binding commands.
32.1. Sparse Resource Features
Sparse resources have several features that must be enabled explicitly at
resource creation time.
The features are enabled by including bits in the flags parameter of
VkImageCreateInfo or VkBufferCreateInfo.
Each feature also has one or more corresponding feature enables specified in
VkPhysicalDeviceFeatures.
-
The
sparseBindingfeature is the base, and provides the following capabilities:-
Resources can be bound at some defined (sparse block) granularity.
-
The entire resource must be bound to memory before use regardless of regions actually accessed.
-
No specific mapping of image region to memory offset is defined, i.e. the location that each texel corresponds to in memory is implementation-dependent.
-
Sparse buffers have a well-defined mapping of buffer range to memory range, where an offset into a range of the buffer that is bound to a single contiguous range of memory corresponds to an identical offset within that range of memory.
-
Requested via the
VK_IMAGE_CREATE_SPARSE_BINDING_BITandVK_BUFFER_CREATE_SPARSE_BINDING_BITbits. -
A sparse image created using
VK_IMAGE_CREATE_SPARSE_BINDING_BIT(but notVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT) supports all formats that non-sparse usage supports, and supports bothVK_IMAGE_TILING_OPTIMALandVK_IMAGE_TILING_LINEARtiling.
-
-
Sparse Residency builds on (and requires) the
sparseBindingfeature. It includes the following capabilities:-
Resources do not have to be completely bound to memory before use on the device.
-
Images have a prescribed sparse image block layout, allowing specific rectangular regions of the image to be bound to specific offsets in memory allocations.
-
Consistency of access to unbound regions of the resource is defined by the absence or presence of
VkPhysicalDeviceSparseProperties::residencyNonResidentStrict. If this property is present, accesses to unbound regions of the resource are well defined and behave as if the data bound is populated with all zeros; writes are discarded. When this property is absent, accesses are considered safe, but reads will return undefined values. -
Requested via the
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BITandVK_BUFFER_CREATE_SPARSE_RESIDENCY_BITbits. -
Sparse residency support is advertised on a finer grain via the following features:
-
The
sparseResidencyBufferfeature provides support for creatingVkBufferobjects with theVK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT. -
The
sparseResidencyImage2Dfeature provides support for creating 2D single-sampledVkImageobjects withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
The
sparseResidencyImage3Dfeature provides support for creating 3DVkImageobjects withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
The
sparseResidency2Samplesfeature provides support for creating 2DVkImageobjects with 2 samples andVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
The
sparseResidency4Samplesfeature provides support for creating 2DVkImageobjects with 4 samples andVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
The
sparseResidency8Samplesfeature provides support for creating 2DVkImageobjects with 8 samples andVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
The
sparseResidency16Samplesfeature provides support for creating 2DVkImageobjects with 16 samples andVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT.
Implementations supporting
sparseResidencyImage2Dare only required to support sparse 2D, single-sampled images. Support for sparse 3D and MSAA images is optional and can be enabled viasparseResidencyImage3D,sparseResidency2Samples,sparseResidency4Samples,sparseResidency8Samples, andsparseResidency16Samples. -
-
A sparse image created using
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BITsupports all non-compressed color formats with power-of-two element size that non-sparse usage supports. Additional formats may also be supported and can be queried via vkGetPhysicalDeviceSparseImageFormatProperties.VK_IMAGE_TILING_LINEARtiling is not supported.
-
-
The
sparseResidencyAliasedfeature provides the following capability that can be enabled per resource:Allows physical memory ranges to be shared between multiple locations in the same sparse resource or between multiple sparse resources, with each binding of a memory location observing a consistent interpretation of the memory contents.
See Sparse Memory Aliasing for more information.
32.2. Sparse Buffers and Fully-Resident Images
Both VkBuffer and VkImage objects created with the
VK_IMAGE_CREATE_SPARSE_BINDING_BIT or
VK_BUFFER_CREATE_SPARSE_BINDING_BIT bits can be thought of as a
linear region of address space.
In the VkImage case if VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT is
not used, this linear region is entirely opaque, meaning that there is no
application-visible mapping between texel location and memory offset.
Unless VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT are also used, the entire
resource must be bound to one or more VkDeviceMemory objects before
use.
32.2.1. Sparse Buffer and Fully-Resident Image Block Size
The sparse block size in bytes for sparse buffers and fully-resident images
is reported as VkMemoryRequirements::alignment.
alignment represents both the memory alignment requirement and the
binding granularity (in bytes) for sparse resources.
32.3. Sparse Partially-Resident Buffers
VkBuffer objects created with the
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT bit allow the buffer to be made
only partially resident.
Partially resident VkBuffer objects are allocated and bound
identically to VkBuffer objects using only the
VK_BUFFER_CREATE_SPARSE_BINDING_BIT feature.
The only difference is the ability for some regions of the buffer to be
unbound during device use.
32.4. Sparse Partially-Resident Images
VkImage objects created with the
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT bit allow specific rectangular
regions of the image called sparse image blocks to be bound to specific
ranges of memory.
This allows the application to manage residency at either image subresource
or sparse image block granularity.
Each image subresource (outside of the mip tail)
starts on a sparse block boundary and has dimensions that are integer
multiples of the corresponding dimensions of the sparse image block.
|
Note
Applications can use these types of images to control LOD based on total memory consumption. If memory pressure becomes an issue the application can unbind and disable specific mipmap levels of images without having to recreate resources or modify texel data of unaffected levels. The application can also use this functionality to access subregions of the image in a “megatexture” fashion. The application can create a large image and only populate the region of the image that is currently being used in the scene. |
32.4.1. Accessing Unbound Regions
The following member of VkPhysicalDeviceSparseProperties affects how
data in unbound regions of sparse resources are handled by the
implementation:
-
residencyNonResidentStrict
If this property is not present, reads of unbound regions of the image will return undefined values. Both reads and writes are still considered safe and will not affect other resources or populated regions of the image.
If this property is present, all reads of unbound regions of the image will behave as if the region was bound to memory populated with all zeros; writes will be discarded.
Image operations performed on unbound memory may still alter some component values in the natural way for those accesses, e.g. substituting a value of one for alpha in formats that do not have an alpha component.
Example: Reading the alpha component of an unbacked VK_FORMAT_R8_UNORM
image will return a value of 1.0f.
See Physical Device Enumeration for instructions for retrieving physical device properties.
32.4.2. Mip Tail Regions
Sparse images created using VK_IMAGE_CREATE_SPARSE_BINDING_BIT
(without also using VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT) have no
specific mapping of image region or image subresource to memory offset
defined, so the entire image can be thought of as a linear opaque address
region.
However, images created with VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT do
have a prescribed sparse image block layout, and hence each image
subresource must start on a sparse block boundary.
Within each array layer, the set of mip levels that have a smaller size than
the sparse block size in bytes are grouped together into a mip tail
region.
If the VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT flag is present in
the flags member of VkSparseImageFormatProperties, for the
image’s format, then any mip level which has dimensions that are not
integer multiples of the corresponding dimensions of the sparse image block,
and all subsequent mip levels, are also included in the mip tail region.
The following member of VkPhysicalDeviceSparseProperties may affect
how the implementation places mip levels in the mip tail region:
-
residencyAlignedMipSize
Each mip tail region is bound to memory as an opaque region (i.e. must be bound using a VkSparseImageOpaqueMemoryBindInfo structure) and may be of a size greater than or equal to the sparse block size in bytes. This size is guaranteed to be an integer multiple of the sparse block size in bytes.
An implementation may choose to allow each array-layer’s mip tail region to
be bound to memory independently or require that all array-layer’s mip tail
regions be treated as one.
This is dictated by VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT in
VkSparseImageMemoryRequirements::flags.
The following diagrams depict how
VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and
VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT alter memory usage and
requirements.
In the absence of VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and
VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT, each array layer contains a
mip tail region containing texel data for all mip levels smaller than the
sparse image block in any dimension.
Mip levels that are as large or larger than a sparse image block in all dimensions can be bound individually. Right-edges and bottom-edges of each level are allowed to have partially used sparse blocks. Any bound partially-used-sparse-blocks must still have their full sparse block size in bytes allocated in memory.
When VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT is present all array
layers will share a single mip tail region.
|
Note
The mip tail regions are presented here in 2D arrays simply for figure size reasons. Each mip tail is logically a single array of sparse blocks with an implementation-dependent mapping of texels or compressed texel blocks to sparse blocks. |
When VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT is present the first
mip level that would contain partially used sparse blocks begins the mip
tail region.
This level and all subsequent levels are placed in the mip tail.
Only the first N mip levels whose dimensions are an exact multiple of
the sparse image block dimensions can be bound and unbound on a sparse
block basis.
|
Note
The mip tail region is presented here in a 2D array simply for figure size reasons. It is logically a single array of sparse blocks with an implementation-dependent mapping of texels or compressed texel blocks to sparse blocks. |
When both VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and
VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT are present the constraints
from each of these flags are in effect.
32.4.3. Standard Sparse Image Block Shapes
Standard sparse image block shapes define a standard set of dimensions for sparse image blocks that depend on the format of the image. Layout of texels or compressed texel blocks within a sparse image block is implementation-dependent. All currently defined standard sparse image block shapes are 64 KB in size.
For block-compressed formats (e.g. VK_FORMAT_BC5_UNORM_BLOCK), the
texel size is the size of the compressed texel block (e.g. 128-bit for
BC5) thus the dimensions of the standard sparse image block shapes
apply in terms of compressed texel blocks.
|
Note
For block-compressed formats, the dimensions of a sparse image block in terms of texels can be calculated by multiplying the sparse image block dimensions by the compressed texel block dimensions. |
| TEXEL SIZE (bits) | Block Shape (2D) | Block Shape (3D) |
|---|---|---|
8-Bit |
256 × 256 × 1 |
64 × 32 × 32 |
16-Bit |
256 × 128 × 1 |
32 × 32 × 32 |
32-Bit |
128 × 128 × 1 |
32 × 32 × 16 |
64-Bit |
128 × 64 × 1 |
32 × 16 × 16 |
128-Bit |
64 × 64 × 1 |
16 × 16 × 16 |
| TEXEL SIZE (bits) | Block Shape (2X) | Block Shape (4X) | Block Shape (8X) | Block Shape (16X) |
|---|---|---|---|---|
8-Bit |
128 × 256 × 1 |
128 × 128 × 1 |
64 × 128 × 1 |
64 × 64 × 1 |
16-Bit |
128 × 128 × 1 |
128 × 64 × 1 |
64 × 64 × 1 |
64 × 32 × 1 |
32-Bit |
64 × 128 × 1 |
64 × 64 × 1 |
32 × 64 × 1 |
32 × 32 × 1 |
64-Bit |
64 × 64 × 1 |
64 × 32 × 1 |
32 × 32 × 1 |
32 × 16 × 1 |
128-Bit |
32 × 64 × 1 |
32 × 32 × 1 |
16 × 32 × 1 |
16 × 16 × 1 |
Implementations that support the standard sparse image block shape for all
formats listed in the Standard Sparse Image Block Shapes (Single Sample) and
Standard Sparse Image Block Shapes (MSAA) tables may advertise the following
VkPhysicalDeviceSparseProperties:
-
residencyStandard2DBlockShape -
residencyStandard2DMultisampleBlockShape -
residencyStandard3DBlockShape
Reporting each of these features does not imply that all possible image types are supported as sparse. Instead, this indicates that no supported sparse image of the corresponding type will use custom sparse image block dimensions for any formats that have a corresponding standard sparse image block shape.
32.4.4. Custom Sparse Image Block Shapes
An implementation that does not support a standard image block shape for a
particular sparse partially-resident image may choose to support a custom
sparse image block shape for it instead.
The dimensions of such a custom sparse image block shape are reported in
VkSparseImageFormatProperties::imageGranularity.
As with standard sparse image block shapes, the size in bytes of the custom
sparse image block shape will be reported in
VkMemoryRequirements::alignment.
Custom sparse image block dimensions are reported through
vkGetPhysicalDeviceSparseImageFormatProperties and
vkGetImageSparseMemoryRequirements.
An implementation must not support both the standard sparse image block shape and a custom sparse image block shape for the same image. The standard sparse image block shape must be used if it is supported.
32.4.5. Multiple Aspects
Partially resident images are allowed to report separate sparse properties for different aspects of the image. One example is for depth/stencil images where the implementation separates the depth and stencil data into separate planes. Another reason for multiple aspects is to allow the application to manage memory allocation for implementation-private metadata associated with the image. See the figure below:
|
Note
The mip tail regions are presented here in 2D arrays simply for figure size reasons. Each mip tail is logically a single array of sparse blocks with an implementation-dependent mapping of texels or compressed texel blocks to sparse blocks. |
In the figure above the depth, stencil, and metadata aspects all have unique
sparse properties.
The per-texel stencil data is ¼ the size of the depth data,
hence the stencil sparse blocks include 4 × the number of
texels.
The sparse block size in bytes for all of the aspects is identical and
defined by VkMemoryRequirements::alignment.
32.5. Sparse Memory Aliasing
By default sparse resources have the same aliasing rules as non-sparse resources. See Memory Aliasing for more information.
VkDevice objects that have the sparseResidencyAliased feature enabled are able to use the
VK_BUFFER_CREATE_SPARSE_ALIASED_BIT and
VK_IMAGE_CREATE_SPARSE_ALIASED_BIT flags for resource creation.
These flags allow resources to access physical memory bound into multiple
locations within one or more sparse resources in a data consistent
fashion.
This means that reading physical memory from multiple aliased locations will
return the same value.
Care must be taken when performing a write operation to aliased physical memory. Memory dependencies must be used to separate writes to one alias from reads or writes to another alias. Writes to aliased memory that are not properly guarded against accesses to different aliases will have undefined results for all accesses to the aliased memory.
Applications that wish to make use of data consistent sparse memory aliasing must abide by the following guidelines:
-
All sparse resources that are bound to aliased physical memory must be created with the
VK_BUFFER_CREATE_SPARSE_ALIASED_BIT/VK_IMAGE_CREATE_SPARSE_ALIASED_BITflag. -
All resources that access aliased physical memory must interpret the memory in the same way. This implies the following:
-
Buffers and images cannot alias the same physical memory in a data consistent fashion. The physical memory ranges must be used exclusively by buffers or used exclusively by images for data consistency to be guaranteed.
-
Memory in sparse image mip tail regions cannot access aliased memory in a data consistent fashion.
-
Sparse images that alias the same physical memory must have compatible formats and be using the same sparse image block shape in order to access aliased memory in a data consistent fashion.
-
Failure to follow any of the above guidelines will require the application to abide by the normal, non-sparse resource aliasing rules. In this case memory cannot be accessed in a data consistent fashion.
|
Note
Enabling sparse resource memory aliasing can be a way to lower physical memory use, but it may reduce performance on some implementations. An application developer can test on their target HW and balance the memory / performance trade-offs measured. |
32.7. Sparse Resource API
The APIs related to sparse resources are grouped into the following categories:
32.7.1. Physical Device Features
Some sparse-resource related features are reported and enabled in
VkPhysicalDeviceFeatures.
These features must be supported and enabled on the VkDevice object
before applications can use them.
See Physical Device Features for information on how to get and
set enabled device features, and for more detailed explanations of these
features.
Sparse Physical Device Features
-
sparseBinding: Support for creating VkBuffer andVkImageobjects with theVK_BUFFER_CREATE_SPARSE_BINDING_BITandVK_IMAGE_CREATE_SPARSE_BINDING_BITflags, respectively. -
sparseResidencyBuffer: Support for creating VkBuffer objects with theVK_BUFFER_CREATE_SPARSE_RESIDENCY_BITflag. -
sparseResidencyImage2D: Support for creating 2D single-sampledVkImageobjects withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
sparseResidencyImage3D: Support for creating 3D VkImage objects withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
sparseResidency2Samples: Support for creating 2D VkImage objects with 2 samples andVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
sparseResidency4Samples: Support for creating 2D VkImage objects with 4 samples andVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
sparseResidency8Samples: Support for creating 2D VkImage objects with 8 samples andVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
sparseResidency16Samples: Support for creating 2D VkImage objects with 16 samples andVK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. -
sparseResidencyAliased: Support for creating VkBuffer andVkImageobjects with theVK_BUFFER_CREATE_SPARSE_ALIASED_BITandVK_IMAGE_CREATE_SPARSE_ALIASED_BITflags, respectively.
32.7.2. Physical Device Sparse Properties
Some features of the implementation are not possible to disable, and are
reported to allow applications to alter their sparse resource usage
accordingly.
These read-only capabilities are reported in the
VkPhysicalDeviceProperties::sparseProperties member, which is a
VkPhysicalDeviceSparseProperties structure.
The VkPhysicalDeviceSparseProperties structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPhysicalDeviceSparseProperties {
VkBool32 residencyStandard2DBlockShape;
VkBool32 residencyStandard2DMultisampleBlockShape;
VkBool32 residencyStandard3DBlockShape;
VkBool32 residencyAlignedMipSize;
VkBool32 residencyNonResidentStrict;
} VkPhysicalDeviceSparseProperties;
-
residencyStandard2DBlockShapeisVK_TRUEif the physical device will access all single-sample 2D sparse resources using the standard sparse image block shapes (based on image format), as described in the Standard Sparse Image Block Shapes (Single Sample) table. If this property is not supported the value returned in theimageGranularitymember of theVkSparseImageFormatPropertiesstructure for single-sample 2D images is not required to match the standard sparse image block dimensions listed in the table. -
residencyStandard2DMultisampleBlockShapeisVK_TRUEif the physical device will access all multisample 2D sparse resources using the standard sparse image block shapes (based on image format), as described in the Standard Sparse Image Block Shapes (MSAA) table. If this property is not supported, the value returned in theimageGranularitymember of theVkSparseImageFormatPropertiesstructure for multisample 2D images is not required to match the standard sparse image block dimensions listed in the table. -
residencyStandard3DBlockShapeisVK_TRUEif the physical device will access all 3D sparse resources using the standard sparse image block shapes (based on image format), as described in the Standard Sparse Image Block Shapes (Single Sample) table. If this property is not supported, the value returned in theimageGranularitymember of theVkSparseImageFormatPropertiesstructure for 3D images is not required to match the standard sparse image block dimensions listed in the table. -
residencyAlignedMipSizeisVK_TRUEif images with mip level dimensions that are not integer multiples of the corresponding dimensions of the sparse image block may be placed in the mip tail. If this property is not reported, only mip levels with dimensions smaller than theimageGranularitymember of theVkSparseImageFormatPropertiesstructure will be placed in the mip tail. If this property is reported the implementation is allowed to returnVK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BITin theflagsmember ofVkSparseImageFormatProperties, indicating that mip level dimensions that are not integer multiples of the corresponding dimensions of the sparse image block will be placed in the mip tail. -
residencyNonResidentStrictspecifies whether the physical device can consistently access non-resident regions of a resource. If this property isVK_TRUE, access to non-resident regions of resources will be guaranteed to return values as if the resource was populated with 0; writes to non-resident regions will be discarded.
32.7.3. Sparse Image Format Properties
Given that certain aspects of sparse image support, including the sparse image block dimensions, may be implementation-dependent, vkGetPhysicalDeviceSparseImageFormatProperties can be used to query for sparse image format properties prior to resource creation. This command is used to check whether a given set of sparse image parameters is supported and what the sparse image block shape will be.
Sparse Image Format Properties API
The VkSparseImageFormatProperties structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSparseImageFormatProperties {
VkImageAspectFlags aspectMask;
VkExtent3D imageGranularity;
VkSparseImageFormatFlags flags;
} VkSparseImageFormatProperties;
-
aspectMaskis a bitmask VkImageAspectFlagBits specifying which aspects of the image the properties apply to. -
imageGranularityis the width, height, and depth of the sparse image block in texels or compressed texel blocks. -
flagsis a bitmask of VkSparseImageFormatFlagBits specifying additional information about the sparse resource.
Bits which may be set in VkSparseImageFormatProperties::flags,
specifying additional information about the sparse resource, are:
// Provided by VK_VERSION_1_0
typedef enum VkSparseImageFormatFlagBits {
VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT = 0x00000001,
VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT = 0x00000002,
VK_SPARSE_IMAGE_FORMAT_NONSTANDARD_BLOCK_SIZE_BIT = 0x00000004,
} VkSparseImageFormatFlagBits;
-
VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BITspecifies that the image uses a single mip tail region for all array layers. -
VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BITspecifies that the first mip level whose dimensions are not integer multiples of the corresponding dimensions of the sparse image block begins the mip tail region. -
VK_SPARSE_IMAGE_FORMAT_NONSTANDARD_BLOCK_SIZE_BITspecifies that the image uses non-standard sparse image block dimensions, and theimageGranularityvalues do not match the standard sparse image block dimensions for the given format.
// Provided by VK_VERSION_1_0
typedef VkFlags VkSparseImageFormatFlags;
VkSparseImageFormatFlags is a bitmask type for setting a mask of zero
or more VkSparseImageFormatFlagBits.
vkGetPhysicalDeviceSparseImageFormatProperties returns an array of
VkSparseImageFormatProperties.
Each element will describe properties for one set of image aspects that are
bound simultaneously in the image.
This is usually one element for each aspect in the image, but for
interleaved depth/stencil images there is only one element describing the
combined aspects.
// Provided by VK_VERSION_1_0
void vkGetPhysicalDeviceSparseImageFormatProperties(
VkPhysicalDevice physicalDevice,
VkFormat format,
VkImageType type,
VkSampleCountFlagBits samples,
VkImageUsageFlags usage,
VkImageTiling tiling,
uint32_t* pPropertyCount,
VkSparseImageFormatProperties* pProperties);
-
physicalDeviceis the physical device from which to query the sparse image format properties. -
formatis the image format. -
typeis the dimensionality of image. -
samplesis a VkSampleCountFlagBits value specifying the number of samples per texel. -
usageis a bitmask describing the intended usage of the image. -
tilingis the tiling arrangement of the texel blocks in memory. -
pPropertyCountis a pointer to an integer related to the number of sparse format properties available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array of VkSparseImageFormatProperties structures.
If pProperties is NULL, then the number of sparse format 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 sparse format properties
available, at most pPropertyCount structures will be written.
If VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT is not supported for the given
arguments, pPropertyCount will be set to zero upon return, and no data
will be written to pProperties.
Multiple aspects are returned for depth/stencil images that are implemented
as separate planes by the implementation.
The depth and stencil data planes each have unique
VkSparseImageFormatProperties data.
Depth/stencil images with depth and stencil data interleaved into a single
plane will return a single VkSparseImageFormatProperties structure
with the aspectMask set to VK_IMAGE_ASPECT_DEPTH_BIT |
VK_IMAGE_ASPECT_STENCIL_BIT.
vkGetPhysicalDeviceSparseImageFormatProperties2 returns an array of
VkSparseImageFormatProperties2.
Each element will describe properties for one set of image aspects that are
bound simultaneously in the image.
This is usually one element for each aspect in the image, but for
interleaved depth/stencil images there is only one element describing the
combined aspects.
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceSparseImageFormatProperties2(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceSparseImageFormatInfo2* pFormatInfo,
uint32_t* pPropertyCount,
VkSparseImageFormatProperties2* pProperties);
or the equivalent command
// Provided by VK_KHR_get_physical_device_properties2
void vkGetPhysicalDeviceSparseImageFormatProperties2KHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceSparseImageFormatInfo2* pFormatInfo,
uint32_t* pPropertyCount,
VkSparseImageFormatProperties2* pProperties);
-
physicalDeviceis the physical device from which to query the sparse image format properties. -
pFormatInfois a pointer to a VkPhysicalDeviceSparseImageFormatInfo2 structure containing input parameters to the command. -
pPropertyCountis a pointer to an integer related to the number of sparse format properties available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array of VkSparseImageFormatProperties2 structures.
vkGetPhysicalDeviceSparseImageFormatProperties2 behaves identically to
vkGetPhysicalDeviceSparseImageFormatProperties, with the ability to
return extended information by adding extending structures to the
pNext chain of its pProperties parameter.
The VkPhysicalDeviceSparseImageFormatInfo2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceSparseImageFormatInfo2 {
VkStructureType sType;
const void* pNext;
VkFormat format;
VkImageType type;
VkSampleCountFlagBits samples;
VkImageUsageFlags usage;
VkImageTiling tiling;
} VkPhysicalDeviceSparseImageFormatInfo2;
or the equivalent
// Provided by VK_KHR_get_physical_device_properties2
typedef VkPhysicalDeviceSparseImageFormatInfo2 VkPhysicalDeviceSparseImageFormatInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatis the image format. -
typeis the dimensionality of image. -
samplesis a VkSampleCountFlagBits value specifying the number of samples per texel. -
usageis a bitmask describing the intended usage of the image. -
tilingis the tiling arrangement of the texel blocks in memory.
The VkSparseImageFormatProperties2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkSparseImageFormatProperties2 {
VkStructureType sType;
void* pNext;
VkSparseImageFormatProperties properties;
} VkSparseImageFormatProperties2;
or the equivalent
// Provided by VK_KHR_get_physical_device_properties2
typedef VkSparseImageFormatProperties2 VkSparseImageFormatProperties2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
propertiesis a VkSparseImageFormatProperties structure which is populated with the same values as in vkGetPhysicalDeviceSparseImageFormatProperties.
32.7.4. Sparse Resource Creation
Sparse resources require that one or more sparse feature flags be specified
(as part of the VkPhysicalDeviceFeatures structure described
previously in the Physical Device Features
section) when calling vkCreateDevice.
When the appropriate device features are enabled, the
VK_BUFFER_CREATE_SPARSE_* and VK_IMAGE_CREATE_SPARSE_* flags
can be used.
See vkCreateBuffer and vkCreateImage for details of the resource
creation APIs.
|
Note
Specifying |
32.7.5. Sparse Resource Memory Requirements
Sparse resources have specific memory requirements related to binding sparse
memory.
These memory requirements are reported differently for VkBuffer
objects and VkImage objects.
Buffer and Fully-Resident Images
Buffers (both fully and partially resident) and fully-resident images can
be bound to memory using only the data from VkMemoryRequirements.
For all sparse resources the VkMemoryRequirements::alignment
member specifies both the bindable sparse block size in bytes and required
alignment of VkDeviceMemory.
Partially Resident Images
Partially resident images have a different method for binding memory.
As with buffers and fully resident images, the
VkMemoryRequirements::alignment field specifies the bindable
sparse block size in bytes for the image.
Requesting sparse memory requirements for VkImage objects using
vkGetImageSparseMemoryRequirements will return an array of one or more
VkSparseImageMemoryRequirements structures.
Each structure describes the sparse memory requirements for a group of
aspects of the image.
The sparse image must have been created using the
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag to retrieve valid sparse
image memory requirements.
Sparse Image Memory Requirements
The VkSparseImageMemoryRequirements structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSparseImageMemoryRequirements {
VkSparseImageFormatProperties formatProperties;
uint32_t imageMipTailFirstLod;
VkDeviceSize imageMipTailSize;
VkDeviceSize imageMipTailOffset;
VkDeviceSize imageMipTailStride;
} VkSparseImageMemoryRequirements;
-
formatPropertiesis a VkSparseImageFormatProperties structure specifying properties of the image format. -
imageMipTailFirstLodis the first mip level at which image subresources are included in the mip tail region. -
imageMipTailSizeis the memory size (in bytes) of the mip tail region. IfformatProperties.flagscontainsVK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT, this is the size of the whole mip tail, otherwise this is the size of the mip tail of a single array layer. This value is guaranteed to be a multiple of the sparse block size in bytes. -
imageMipTailOffsetis the opaque memory offset used with VkSparseImageOpaqueMemoryBindInfo to bind the mip tail region(s). -
imageMipTailStrideis the offset stride between each array-layer’s mip tail, ifformatProperties.flagsdoes not containVK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT(otherwise the value is undefined).
To query sparse memory requirements for an image, call:
// Provided by VK_VERSION_1_0
void vkGetImageSparseMemoryRequirements(
VkDevice device,
VkImage image,
uint32_t* pSparseMemoryRequirementCount,
VkSparseImageMemoryRequirements* pSparseMemoryRequirements);
-
deviceis the logical device that owns the image. -
imageis the VkImage object to get the memory requirements for. -
pSparseMemoryRequirementCountis a pointer to an integer related to the number of sparse memory requirements available or queried, as described below. -
pSparseMemoryRequirementsis eitherNULLor a pointer to an array ofVkSparseImageMemoryRequirementsstructures.
If pSparseMemoryRequirements is NULL, then the number of sparse
memory requirements available is returned in
pSparseMemoryRequirementCount.
Otherwise, pSparseMemoryRequirementCount must point to a variable set
by the user to the number of elements in the pSparseMemoryRequirements
array, and on return the variable is overwritten with the number of
structures actually written to pSparseMemoryRequirements.
If pSparseMemoryRequirementCount is less than the number of sparse
memory requirements available, at most pSparseMemoryRequirementCount
structures will be written.
If the image was not created with VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
then pSparseMemoryRequirementCount will be set to zero and
pSparseMemoryRequirements will not be written to.
|
Note
It is legal for an implementation to report a larger value in
|
To query sparse memory requirements for an image, call:
// Provided by VK_VERSION_1_1
void vkGetImageSparseMemoryRequirements2(
VkDevice device,
const VkImageSparseMemoryRequirementsInfo2* pInfo,
uint32_t* pSparseMemoryRequirementCount,
VkSparseImageMemoryRequirements2* pSparseMemoryRequirements);
or the equivalent command
// Provided by VK_KHR_get_memory_requirements2
void vkGetImageSparseMemoryRequirements2KHR(
VkDevice device,
const VkImageSparseMemoryRequirementsInfo2* pInfo,
uint32_t* pSparseMemoryRequirementCount,
VkSparseImageMemoryRequirements2* pSparseMemoryRequirements);
-
deviceis the logical device that owns the image. -
pInfois a pointer to aVkImageSparseMemoryRequirementsInfo2structure containing parameters required for the memory requirements query. -
pSparseMemoryRequirementCountis a pointer to an integer related to the number of sparse memory requirements available or queried, as described below. -
pSparseMemoryRequirementsis eitherNULLor a pointer to an array ofVkSparseImageMemoryRequirements2structures.
To determine the sparse memory requirements for an image resource without creating an object, call:
// Provided by VK_VERSION_1_3
void vkGetDeviceImageSparseMemoryRequirements(
VkDevice device,
const VkDeviceImageMemoryRequirements* pInfo,
uint32_t* pSparseMemoryRequirementCount,
VkSparseImageMemoryRequirements2* pSparseMemoryRequirements);
or the equivalent command
// Provided by VK_KHR_maintenance4
void vkGetDeviceImageSparseMemoryRequirementsKHR(
VkDevice device,
const VkDeviceImageMemoryRequirements* pInfo,
uint32_t* pSparseMemoryRequirementCount,
VkSparseImageMemoryRequirements2* pSparseMemoryRequirements);
-
deviceis the logical device intended to own the image. -
pInfois a pointer to a VkDeviceImageMemoryRequirements structure containing parameters required for the memory requirements query. -
pSparseMemoryRequirementCountis a pointer to an integer related to the number of sparse memory requirements available or queried, as described below. -
pSparseMemoryRequirementsis eitherNULLor a pointer to an array ofVkSparseImageMemoryRequirements2structures.
The VkImageSparseMemoryRequirementsInfo2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImageSparseMemoryRequirementsInfo2 {
VkStructureType sType;
const void* pNext;
VkImage image;
} VkImageSparseMemoryRequirementsInfo2;
or the equivalent
// Provided by VK_KHR_get_memory_requirements2
typedef VkImageSparseMemoryRequirementsInfo2 VkImageSparseMemoryRequirementsInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis the image to query.
The VkSparseImageMemoryRequirements2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkSparseImageMemoryRequirements2 {
VkStructureType sType;
void* pNext;
VkSparseImageMemoryRequirements memoryRequirements;
} VkSparseImageMemoryRequirements2;
or the equivalent
// Provided by VK_KHR_get_memory_requirements2
typedef VkSparseImageMemoryRequirements2 VkSparseImageMemoryRequirements2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryRequirementsis a VkSparseImageMemoryRequirements structure describing the memory requirements of the sparse image.
32.7.6. Binding Resource Memory
Non-sparse resources are backed by a single physical allocation prior to
device use (via vkBindImageMemory or vkBindBufferMemory), and
their backing must not be changed.
On the other hand, sparse resources can be bound to memory non-contiguously
and these bindings can be altered during the lifetime of the resource.
|
Note
It is important to note that freeing a |
Sparse memory bindings execute on a queue that includes the
VK_QUEUE_SPARSE_BINDING_BIT bit.
Applications must use synchronization primitives to
guarantee that other queues do not access ranges of memory concurrently with
a binding change.
Applications can access other ranges of the same resource while a bind
operation is executing.
|
Note
Implementations must provide a guarantee that simultaneously binding sparse blocks while another queue accesses those same sparse blocks via a sparse resource must not access memory owned by another process or otherwise corrupt the system. |
While some implementations may include VK_QUEUE_SPARSE_BINDING_BIT
support in queue families that also include graphics and compute support,
other implementations may only expose a
VK_QUEUE_SPARSE_BINDING_BIT-only queue family.
In either case, applications must use synchronization
primitives to explicitly request any ordering dependencies between sparse
memory binding operations and other graphics/compute/transfer operations, as
sparse binding operations are not automatically ordered against command
buffer execution, even within a single queue.
When binding memory explicitly for the VK_IMAGE_ASPECT_METADATA_BIT
the application must use the VK_SPARSE_MEMORY_BIND_METADATA_BIT in
the VkSparseMemoryBind::flags field when binding memory.
Binding memory for metadata is done the same way as binding memory for the
mip tail, with the addition of the VK_SPARSE_MEMORY_BIND_METADATA_BIT
flag.
Binding the mip tail for any aspect must only be performed using
VkSparseImageOpaqueMemoryBindInfo.
If formatProperties.flags contains
VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT, then it can be bound with
a single VkSparseMemoryBind structure, with resourceOffset =
imageMipTailOffset and size = imageMipTailSize.
If formatProperties.flags does not contain
VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT then the offset for the mip
tail in each array layer is given as:
arrayMipTailOffset = imageMipTailOffset + arrayLayer * imageMipTailStride;
and the mip tail can be bound with layerCount VkSparseMemoryBind
structures, each using size = imageMipTailSize and
resourceOffset = arrayMipTailOffset as defined above.
Sparse memory binding is handled by the following APIs and related data structures.
Sparse Memory Binding Functions
The VkSparseMemoryBind structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSparseMemoryBind {
VkDeviceSize resourceOffset;
VkDeviceSize size;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
VkSparseMemoryBindFlags flags;
} VkSparseMemoryBind;
-
resourceOffsetis the offset into the resource. -
sizeis the size of the memory region to be bound. -
memoryis the VkDeviceMemory object that the range of the resource is bound to. Ifmemoryis VK_NULL_HANDLE, the range is unbound. -
memoryOffsetis the offset into the VkDeviceMemory object to bind the resource range to. Ifmemoryis VK_NULL_HANDLE, this value is ignored. -
flagsis a bitmask of VkSparseMemoryBindFlagBits specifying usage of the binding operation.
The binding range [resourceOffset, resourceOffset +
size) has different constraints based on flags.
If flags contains VK_SPARSE_MEMORY_BIND_METADATA_BIT, the
binding range must be within the mip tail region of the metadata aspect.
This metadata region is defined by:
-
metadataRegion = [base, base +
imageMipTailSize) -
base =
imageMipTailOffset+imageMipTailStride× n
and imageMipTailOffset, imageMipTailSize, and
imageMipTailStride values are from the
VkSparseImageMemoryRequirements corresponding to the metadata aspect
of the image, and n is a valid array layer index for the image,
imageMipTailStride is considered to be zero for aspects where
VkSparseImageMemoryRequirements::formatProperties.flags contains
VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT.
If flags does not contain VK_SPARSE_MEMORY_BIND_METADATA_BIT,
the binding range must be within the range
[0,VkMemoryRequirements::size).
Bits which can be set in VkSparseMemoryBind::flags, specifying
usage of a sparse memory binding operation, are:
// Provided by VK_VERSION_1_0
typedef enum VkSparseMemoryBindFlagBits {
VK_SPARSE_MEMORY_BIND_METADATA_BIT = 0x00000001,
} VkSparseMemoryBindFlagBits;
-
VK_SPARSE_MEMORY_BIND_METADATA_BITspecifies that the memory being bound is only for the metadata aspect.
// Provided by VK_VERSION_1_0
typedef VkFlags VkSparseMemoryBindFlags;
VkSparseMemoryBindFlags is a bitmask type for setting a mask of zero
or more VkSparseMemoryBindFlagBits.
Memory is bound to VkBuffer objects created with the
VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag using the following
structure:
// Provided by VK_VERSION_1_0
typedef struct VkSparseBufferMemoryBindInfo {
VkBuffer buffer;
uint32_t bindCount;
const VkSparseMemoryBind* pBinds;
} VkSparseBufferMemoryBindInfo;
-
bufferis the VkBuffer object to be bound. -
bindCountis the number of VkSparseMemoryBind structures in thepBindsarray. -
pBindsis a pointer to an array of VkSparseMemoryBind structures.
Memory is bound to opaque regions of VkImage objects created with the
VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag using the following structure:
// Provided by VK_VERSION_1_0
typedef struct VkSparseImageOpaqueMemoryBindInfo {
VkImage image;
uint32_t bindCount;
const VkSparseMemoryBind* pBinds;
} VkSparseImageOpaqueMemoryBindInfo;
-
imageis the VkImage object to be bound. -
bindCountis the number of VkSparseMemoryBind structures in thepBindsarray. -
pBindsis a pointer to an array of VkSparseMemoryBind structures.
|
Note
This operation is normally used to bind memory to fully-resident sparse images or for mip tail regions of partially resident images. However, it can also be used to bind memory for the entire binding range of partially resident images. In case When |
|
editing-note
(Jon) The preceding NOTE refers to |
Memory can be bound to sparse image blocks of VkImage objects created
with the VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag using the following
structure:
// Provided by VK_VERSION_1_0
typedef struct VkSparseImageMemoryBindInfo {
VkImage image;
uint32_t bindCount;
const VkSparseImageMemoryBind* pBinds;
} VkSparseImageMemoryBindInfo;
-
imageis the VkImage object to be bound -
bindCountis the number of VkSparseImageMemoryBind structures inpBindsarray -
pBindsis a pointer to an array of VkSparseImageMemoryBind structures
The VkSparseImageMemoryBind structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSparseImageMemoryBind {
VkImageSubresource subresource;
VkOffset3D offset;
VkExtent3D extent;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
VkSparseMemoryBindFlags flags;
} VkSparseImageMemoryBind;
-
subresourceis the image aspect and region of interest in the image. -
offsetare the coordinates of the first texel within the image subresource to bind. -
extentis the size in texels of the region within the image subresource to bind. The extent must be a multiple of the sparse image block dimensions, except when binding sparse image blocks along the edge of an image subresource it can instead be such that any coordinate ofoffset+extentequals the corresponding dimensions of the image subresource. -
memoryis the VkDeviceMemory object that the sparse image blocks of the image are bound to. Ifmemoryis VK_NULL_HANDLE, the sparse image blocks are unbound. -
memoryOffsetis an offset into VkDeviceMemory object. Ifmemoryis VK_NULL_HANDLE, this value is ignored. -
flagsare sparse memory binding flags.
To submit sparse binding operations to a queue, call:
// Provided by VK_VERSION_1_0
VkResult vkQueueBindSparse(
VkQueue queue,
uint32_t bindInfoCount,
const VkBindSparseInfo* pBindInfo,
VkFence fence);
-
queueis the queue that the sparse binding operations will be submitted to. -
bindInfoCountis the number of elements in thepBindInfoarray. -
pBindInfois a pointer to an array of VkBindSparseInfo structures, each specifying a sparse binding submission batch. -
fenceis an optional handle to a fence to be signaled. Iffenceis not VK_NULL_HANDLE, it defines a fence signal operation.
vkQueueBindSparse is a queue submission
command, with each batch defined by an element of pBindInfo as a
VkBindSparseInfo structure.
Batches begin execution in the order they appear in pBindInfo, but
may complete out of order.
Within a batch, a given range of a resource must not be bound more than once. Across batches, if a range is to be bound to one allocation and offset and then to another allocation and offset, then the application must guarantee (usually using semaphores) that the binding operations are executed in the correct order, as well as to order binding operations against the execution of command buffer submissions.
As no operation to vkQueueBindSparse causes any pipeline stage to access memory, synchronization primitives used in this command effectively only define execution dependencies.
Additional information about fence and semaphore operation is described in the synchronization chapter.
The VkBindSparseInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBindSparseInfo {
VkStructureType sType;
const void* pNext;
uint32_t waitSemaphoreCount;
const VkSemaphore* pWaitSemaphores;
uint32_t bufferBindCount;
const VkSparseBufferMemoryBindInfo* pBufferBinds;
uint32_t imageOpaqueBindCount;
const VkSparseImageOpaqueMemoryBindInfo* pImageOpaqueBinds;
uint32_t imageBindCount;
const VkSparseImageMemoryBindInfo* pImageBinds;
uint32_t signalSemaphoreCount;
const VkSemaphore* pSignalSemaphores;
} VkBindSparseInfo;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
waitSemaphoreCountis the number of semaphores upon which to wait before executing the sparse binding operations for the batch. -
pWaitSemaphoresis a pointer to an array of semaphores upon which to wait on before the sparse binding operations for this batch begin execution. If semaphores to wait on are provided, they define a semaphore wait operation. -
bufferBindCountis the number of sparse buffer bindings to perform in the batch. -
pBufferBindsis a pointer to an array of VkSparseBufferMemoryBindInfo structures. -
imageOpaqueBindCountis the number of opaque sparse image bindings to perform. -
pImageOpaqueBindsis a pointer to an array of VkSparseImageOpaqueMemoryBindInfo structures, indicating opaque sparse image bindings to perform. -
imageBindCountis the number of sparse image bindings to perform. -
pImageBindsis a pointer to an array of VkSparseImageMemoryBindInfo structures, indicating sparse image bindings to perform. -
signalSemaphoreCountis the number of semaphores to be signaled once the sparse binding operations specified by the structure have completed execution. -
pSignalSemaphoresis a pointer to an array of semaphores which will be signaled when the sparse binding operations for this batch have completed execution. If semaphores to be signaled are provided, they define a semaphore signal operation.
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 VkBindSparseInfo structure.
If the pNext chain of VkBindSparseInfo includes a
VkDeviceGroupBindSparseInfo structure, then that structure includes
device indices specifying which instance of the resources and memory are
bound.
The VkDeviceGroupBindSparseInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupBindSparseInfo {
VkStructureType sType;
const void* pNext;
uint32_t resourceDeviceIndex;
uint32_t memoryDeviceIndex;
} VkDeviceGroupBindSparseInfo;
or the equivalent
// Provided by VK_KHR_device_group
typedef VkDeviceGroupBindSparseInfo VkDeviceGroupBindSparseInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
resourceDeviceIndexis a device index indicating which instance of the resource is bound. -
memoryDeviceIndexis a device index indicating which instance of the memory the resource instance is bound to.
These device indices apply to all buffer and image memory binds included in
the batch pointing to this structure.
The semaphore waits and signals for the batch are executed only by the
physical device specified by the resourceDeviceIndex.
If this structure is not present, resourceDeviceIndex and
memoryDeviceIndex are assumed to be zero.
33. Window System Integration (WSI)
This chapter discusses the window system integration (WSI) between the Vulkan API and the various forms of displaying the results of rendering to a user. Since the Vulkan API can be used without displaying results, WSI is provided through the use of optional Vulkan extensions. This chapter provides an overview of WSI. See the appendix for additional details of each WSI extension, including which extensions must be enabled in order to use each of the functions described in this chapter.
33.1. WSI Platform
A platform is an abstraction for a window system, OS, etc. Some examples include MS Windows, Android, and Wayland. The Vulkan API may be integrated in a unique manner for each platform.
The Vulkan API does not define any type of platform object. Platform-specific WSI extensions are defined, each containing platform-specific functions for using WSI. Use of these extensions is guarded by preprocessor symbols as defined in the Window System-Specific Header Control appendix.
In order for an application to be compiled to use WSI with a given platform, it must either:
-
#definethe appropriate preprocessor symbol prior to including thevulkan.hheader file, or -
include
vulkan_core.hand any native platform headers, followed by the appropriate platform-specific header.
The preprocessor symbols and platform-specific headers are defined in the Window System Extensions and Headers table.
Each platform-specific extension is an instance extension.
The application must enable instance extensions with vkCreateInstance
before using them.
33.2. WSI Surface
Native platform surface or window objects are abstracted by surface objects,
which are represented by VkSurfaceKHR handles:
// Provided by VK_KHR_surface
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR)
The VK_KHR_surface extension declares the VkSurfaceKHR object, and
provides a function for destroying VkSurfaceKHR objects.
Separate platform-specific extensions each provide a function for creating a
VkSurfaceKHR object for the respective platform.
From the application’s perspective this is an opaque handle, just like the
handles of other Vulkan objects.
|
Note
On certain platforms, the Vulkan loader and ICDs may have conventions that
treat the handle as a pointer to a structure containing the
platform-specific information about the surface.
This will be described in the documentation for the loader-ICD interface,
and in the |
|
editing-note
TODO: Consider replacing the above note editing note with a pointer to the loader specification, when it exists. However, the information is not relevant to users of the API nor does it affect conformance of a Vulkan implementation. |
33.2.1. Android Platform
To create a VkSurfaceKHR object for an Android native window, call:
// Provided by VK_KHR_android_surface
VkResult vkCreateAndroidSurfaceKHR(
VkInstance instance,
const VkAndroidSurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate the surface with. -
pCreateInfois a pointer to aVkAndroidSurfaceCreateInfoKHRstructure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
During the lifetime of a surface created using a particular
ANativeWindow handle any attempts to create another surface for the
same ANativeWindow and any attempts to connect to the same
ANativeWindow through other platform mechanisms will fail.
|
Note
In particular, only one |
If successful, vkCreateAndroidSurfaceKHR increments the
ANativeWindow’s reference count, and vkDestroySurfaceKHR will
decrement it.
On Android, when a swapchain’s imageExtent does not match the
surface’s currentExtent, the presentable images will be scaled to the
surface’s dimensions during presentation.
minImageExtent is (1,1), and maxImageExtent is the maximum
image size supported by the consumer.
For the system compositor, currentExtent is the window size (i.e. the
consumer’s preferred size).
The VkAndroidSurfaceCreateInfoKHR structure is defined as:
// Provided by VK_KHR_android_surface
typedef struct VkAndroidSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkAndroidSurfaceCreateFlagsKHR flags;
struct ANativeWindow* window;
} VkAndroidSurfaceCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
windowis a pointer to theANativeWindowto associate the surface with.
To remove an unnecessary compile-time dependency, an incomplete type
definition of ANativeWindow is provided in the Vulkan headers:
// Provided by VK_KHR_android_surface
struct ANativeWindow;
The actual ANativeWindow type is defined in Android NDK headers.
// Provided by VK_KHR_android_surface
typedef VkFlags VkAndroidSurfaceCreateFlagsKHR;
VkAndroidSurfaceCreateFlagsKHR is a bitmask type for setting a mask,
but is currently reserved for future use.
33.2.2. Wayland Platform
To create a VkSurfaceKHR object for a Wayland surface, call:
// Provided by VK_KHR_wayland_surface
VkResult vkCreateWaylandSurfaceKHR(
VkInstance instance,
const VkWaylandSurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate the surface with. -
pCreateInfois a pointer to a VkWaylandSurfaceCreateInfoKHR structure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkWaylandSurfaceCreateInfoKHR structure is defined as:
// Provided by VK_KHR_wayland_surface
typedef struct VkWaylandSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkWaylandSurfaceCreateFlagsKHR flags;
struct wl_display* display;
struct wl_surface* surface;
} VkWaylandSurfaceCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
displayandsurfaceare pointers to the Waylandwl_displayandwl_surfaceto associate the surface with.
On Wayland, currentExtent is the special value (0xFFFFFFFF,
0xFFFFFFFF), indicating that the surface size will be determined by the
extent of a swapchain targeting the surface.
Whatever the application sets a swapchain’s imageExtent to will be the
size of the window, after the first image is presented.
minImageExtent is (1,1), and maxImageExtent is the maximum
supported surface size.
Any calls to vkGetPhysicalDeviceSurfacePresentModesKHR on a surface
created with vkCreateWaylandSurfaceKHR are required to return
VK_PRESENT_MODE_MAILBOX_KHR as one of the valid present modes.
Some Vulkan functions may send protocol over the specified wl_display
connection when using a swapchain or presentable images created from a
VkSurfaceKHR referring to a wl_surface.
Applications must therefore ensure that both the wl_display and the
wl_surface remain valid for the lifetime of any VkSwapchainKHR
objects created from a particular wl_display and wl_surface.
Also, calling vkQueuePresentKHR will result in Vulkan sending
wl_surface.commit requests to the underlying wl_surface of each
VkSwapchainKHR objects referenced by pPresentInfo.
If the swapchain is created with a present mode of
VK_PRESENT_MODE_MAILBOX_KHR or VK_PRESENT_MODE_IMMEDIATE_KHR,
then the corresponding wl_surface.attach, wl_surface.damage, and
wl_surface.commit request must be issued by the implementation during
the call to vkQueuePresentKHR and must not be issued by the
implementation outside of vkQueuePresentKHR.
This ensures that any Wayland requests sent by the client after the call to
vkQueuePresentKHR returns will be received by the compositor after the
wl_surface.commit.
Regardless of the mode of swapchain creation, a new wl_event_queue
must be created for each successful vkCreateWaylandSurfaceKHR call,
and every Wayland object created by the implementation must be assigned to
this event queue.
If the platform provides Wayland 1.11 or greater, this must be implemented
by the use of Wayland proxy object wrappers, to avoid race conditions.
If the application wishes to synchronize any window changes with a
particular frame, such requests must be sent to the Wayland display server
prior to calling vkQueuePresentKHR.
For full control over interactions between Vulkan rendering and other
Wayland protocol requests and events, a present mode of
VK_PRESENT_MODE_MAILBOX_KHR should be used.
// Provided by VK_KHR_wayland_surface
typedef VkFlags VkWaylandSurfaceCreateFlagsKHR;
VkWaylandSurfaceCreateFlagsKHR is a bitmask type for setting a mask,
but is currently reserved for future use.
33.2.3. Win32 Platform
To create a VkSurfaceKHR object for a Win32 window, call:
// Provided by VK_KHR_win32_surface
VkResult vkCreateWin32SurfaceKHR(
VkInstance instance,
const VkWin32SurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate the surface with. -
pCreateInfois a pointer to aVkWin32SurfaceCreateInfoKHRstructure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkWin32SurfaceCreateInfoKHR structure is defined as:
// Provided by VK_KHR_win32_surface
typedef struct VkWin32SurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkWin32SurfaceCreateFlagsKHR flags;
HINSTANCE hinstance;
HWND hwnd;
} VkWin32SurfaceCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
hinstanceis the Win32HINSTANCEfor the window to associate the surface with. -
hwndis the Win32HWNDfor the window to associate the surface with.
With Win32, minImageExtent, maxImageExtent, and
currentExtent must always equal the window size.
The currentExtent of a Win32 surface must have both width and
height greater than 0, or both of them 0.
|
Note
Due to above restrictions, it is only possible to create a new swapchain on
this platform with The window size may become (0, 0) on this platform (e.g. when the window is minimized), and so a swapchain cannot be created until the size changes. |
// Provided by VK_KHR_win32_surface
typedef VkFlags VkWin32SurfaceCreateFlagsKHR;
VkWin32SurfaceCreateFlagsKHR is a bitmask type for setting a mask, but
is currently reserved for future use.
33.2.4. XCB Platform
To create a VkSurfaceKHR object for an X11 window, using the XCB
client-side library, call:
// Provided by VK_KHR_xcb_surface
VkResult vkCreateXcbSurfaceKHR(
VkInstance instance,
const VkXcbSurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate the surface with. -
pCreateInfois a pointer to aVkXcbSurfaceCreateInfoKHRstructure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkXcbSurfaceCreateInfoKHR structure is defined as:
// Provided by VK_KHR_xcb_surface
typedef struct VkXcbSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkXcbSurfaceCreateFlagsKHR flags;
xcb_connection_t* connection;
xcb_window_t window;
} VkXcbSurfaceCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
connectionis a pointer to anxcb_connection_tto the X server. -
windowis thexcb_window_tfor the X11 window to associate the surface with.
With Xcb, minImageExtent, maxImageExtent, and
currentExtent must always equal the window size.
The currentExtent of an Xcb surface must have both width and
height greater than 0, or both of them 0.
|
Note
Due to above restrictions, it is only possible to create a new swapchain on
this platform with The window size may become (0, 0) on this platform (e.g. when the window is minimized), and so a swapchain cannot be created until the size changes. |
Some Vulkan functions may send protocol over the specified xcb connection when using a swapchain or presentable images created from a VkSurfaceKHR referring to an xcb window. Applications must therefore ensure the xcb connection is available to Vulkan for the duration of any functions that manipulate such swapchains or their presentable images, and any functions that build or queue command buffers that operate on such presentable images. Specifically, applications using Vulkan with xcb-based swapchains must
-
Avoid holding a server grab on an xcb connection while waiting for Vulkan operations to complete using a swapchain derived from a different xcb connection referring to the same X server instance. Failing to do so may result in deadlock.
// Provided by VK_KHR_xcb_surface
typedef VkFlags VkXcbSurfaceCreateFlagsKHR;
VkXcbSurfaceCreateFlagsKHR is a bitmask type for setting a mask, but
is currently reserved for future use.
33.2.5. Xlib Platform
To create a VkSurfaceKHR object for an X11 window, using the Xlib
client-side library, call:
// Provided by VK_KHR_xlib_surface
VkResult vkCreateXlibSurfaceKHR(
VkInstance instance,
const VkXlibSurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate the surface with. -
pCreateInfois a pointer to aVkXlibSurfaceCreateInfoKHRstructure containing the parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkXlibSurfaceCreateInfoKHR structure is defined as:
// Provided by VK_KHR_xlib_surface
typedef struct VkXlibSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkXlibSurfaceCreateFlagsKHR flags;
Display* dpy;
Window window;
} VkXlibSurfaceCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
dpyis a pointer to an XlibDisplayconnection to the X server. -
windowis an XlibWindowto associate the surface with.
With Xlib, minImageExtent, maxImageExtent, and
currentExtent must always equal the window size.
The currentExtent of an Xlib surface must have both width and
height greater than 0, or both of them 0.
|
Note
Due to above restrictions, it is only possible to create a new swapchain on
this platform with The window size may become (0, 0) on this platform (e.g. when the window is minimized), and so a swapchain cannot be created until the size changes. |
Some Vulkan functions may send protocol over the specified Xlib
Display connection when using a swapchain or presentable images created
from a VkSurfaceKHR referring to an Xlib window.
Applications must therefore ensure the display connection is available to
Vulkan for the duration of any functions that manipulate such swapchains or
their presentable images, and any functions that build or queue command
buffers that operate on such presentable images.
Specifically, applications using Vulkan with Xlib-based swapchains must
-
Avoid holding a server grab on a display connection while waiting for Vulkan operations to complete using a swapchain derived from a different display connection referring to the same X server instance. Failing to do so may result in deadlock.
Some implementations may require threads to implement some presentation
modes so applications must call XInitThreads() before calling any
other Xlib functions.
// Provided by VK_KHR_xlib_surface
typedef VkFlags VkXlibSurfaceCreateFlagsKHR;
VkXlibSurfaceCreateFlagsKHR is a bitmask type for setting a mask, but
is currently reserved for future use.
33.2.6. DirectFB Platform
To create a VkSurfaceKHR object for a DirectFB surface, call:
// Provided by VK_EXT_directfb_surface
VkResult vkCreateDirectFBSurfaceEXT(
VkInstance instance,
const VkDirectFBSurfaceCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate the surface with. -
pCreateInfois a pointer to aVkDirectFBSurfaceCreateInfoEXTstructure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkDirectFBSurfaceCreateInfoEXT structure is defined as:
// Provided by VK_EXT_directfb_surface
typedef struct VkDirectFBSurfaceCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkDirectFBSurfaceCreateFlagsEXT flags;
IDirectFB* dfb;
IDirectFBSurface* surface;
} VkDirectFBSurfaceCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
dfbis a pointer to theIDirectFBmain interface of DirectFB. -
surfaceis a pointer to aIDirectFBSurfacesurface interface.
With DirectFB, minImageExtent, maxImageExtent, and
currentExtent must always equal the surface size.
// Provided by VK_EXT_directfb_surface
typedef VkFlags VkDirectFBSurfaceCreateFlagsEXT;
VkDirectFBSurfaceCreateFlagsEXT is a bitmask type for setting a mask,
but is currently reserved for future use.
33.2.7. Fuchsia Platform
To create a VkSurfaceKHR object for a Fuchsia ImagePipe, call:
// Provided by VK_FUCHSIA_imagepipe_surface
VkResult vkCreateImagePipeSurfaceFUCHSIA(
VkInstance instance,
const VkImagePipeSurfaceCreateInfoFUCHSIA* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate with the surface. -
pCreateInfois a pointer to a VkImagePipeSurfaceCreateInfoFUCHSIA structure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkImagePipeSurfaceCreateInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_imagepipe_surface
typedef struct VkImagePipeSurfaceCreateInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkImagePipeSurfaceCreateFlagsFUCHSIA flags;
zx_handle_t imagePipeHandle;
} VkImagePipeSurfaceCreateInfoFUCHSIA;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
imagePipeHandleis azx_handle_treferring to the ImagePipe to associate with the surface.
On Fuchsia, the surface currentExtent is the special value
(0xFFFFFFFF, 0xFFFFFFFF), indicating that the surface size will be
determined by the extent of a swapchain targeting the surface.
// Provided by VK_FUCHSIA_imagepipe_surface
typedef VkFlags VkImagePipeSurfaceCreateFlagsFUCHSIA;
VkImagePipeSurfaceCreateFlagsFUCHSIA is a bitmask type for setting a
mask, but is currently reserved for future use.
33.2.8. Google Games Platform
To create a VkSurfaceKHR object for a Google Games Platform stream
descriptor, call:
// Provided by VK_GGP_stream_descriptor_surface
VkResult vkCreateStreamDescriptorSurfaceGGP(
VkInstance instance,
const VkStreamDescriptorSurfaceCreateInfoGGP* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate with the surface. -
pCreateInfois a pointer to aVkStreamDescriptorSurfaceCreateInfoGGPstructure containing parameters that affect the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkStreamDescriptorSurfaceCreateInfoGGP structure is defined as:
// Provided by VK_GGP_stream_descriptor_surface
typedef struct VkStreamDescriptorSurfaceCreateInfoGGP {
VkStructureType sType;
const void* pNext;
VkStreamDescriptorSurfaceCreateFlagsGGP flags;
GgpStreamDescriptor streamDescriptor;
} VkStreamDescriptorSurfaceCreateInfoGGP;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
streamDescriptoris aGgpStreamDescriptorreferring to the GGP stream descriptor to associate with the surface.
On Google Games Platform, the surface extents are dynamic.
The minImageExtent will never be greater than 1080p and the
maxImageExtent will never be less than 1080p.
The currentExtent will reflect the current optimal resolution.
Applications are expected to choose an appropriate size for the swapchain’s
imageExtent, within the bounds of the surface.
Using the surface’s currentExtent will offer the best performance and
quality.
When a swapchain’s imageExtent does not match the surface’s
currentExtent, the presentable images are scaled to the surface’s
dimensions during presentation if possible and VK_SUBOPTIMAL_KHR is
returned, otherwise presentation fails with VK_ERROR_OUT_OF_DATE_KHR.
// Provided by VK_GGP_stream_descriptor_surface
typedef VkFlags VkStreamDescriptorSurfaceCreateFlagsGGP;
VkStreamDescriptorSurfaceCreateFlagsGGP is a bitmask type for setting
a mask, but is currently reserved for future use.
33.2.9. iOS Platform
To create a VkSurfaceKHR object for an iOS UIView or
CAMetalLayer, call:
// Provided by VK_MVK_ios_surface
VkResult vkCreateIOSSurfaceMVK(
VkInstance instance,
const VkIOSSurfaceCreateInfoMVK* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
|
Note
The |
-
instanceis the instance with which to associate the surface. -
pCreateInfois a pointer to a VkIOSSurfaceCreateInfoMVK structure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkIOSSurfaceCreateInfoMVK structure is defined as:
// Provided by VK_MVK_ios_surface
typedef struct VkIOSSurfaceCreateInfoMVK {
VkStructureType sType;
const void* pNext;
VkIOSSurfaceCreateFlagsMVK flags;
const void* pView;
} VkIOSSurfaceCreateInfoMVK;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
pViewis a reference to either aCAMetalLayerobject or aUIViewobject.
// Provided by VK_MVK_ios_surface
typedef VkFlags VkIOSSurfaceCreateFlagsMVK;
VkIOSSurfaceCreateFlagsMVK is a bitmask type for setting a mask, but
is currently reserved for future use.
33.2.10. macOS Platform
To create a VkSurfaceKHR object for a macOS NSView or
CAMetalLayer, call:
// Provided by VK_MVK_macos_surface
VkResult vkCreateMacOSSurfaceMVK(
VkInstance instance,
const VkMacOSSurfaceCreateInfoMVK* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
|
Note
The |
-
instanceis the instance with which to associate the surface. -
pCreateInfois a pointer to a VkMacOSSurfaceCreateInfoMVK structure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkMacOSSurfaceCreateInfoMVK structure is defined as:
// Provided by VK_MVK_macos_surface
typedef struct VkMacOSSurfaceCreateInfoMVK {
VkStructureType sType;
const void* pNext;
VkMacOSSurfaceCreateFlagsMVK flags;
const void* pView;
} VkMacOSSurfaceCreateInfoMVK;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
pViewis a reference to either aCAMetalLayerobject or anNSViewobject.
// Provided by VK_MVK_macos_surface
typedef VkFlags VkMacOSSurfaceCreateFlagsMVK;
VkMacOSSurfaceCreateFlagsMVK is a bitmask type for setting a mask, but
is currently reserved for future use.
33.2.11. VI Platform
To create a VkSurfaceKHR object for an nn::vi::Layer,
query the layer’s native handle using
nn::vi::GetNativeWindow, and then call:
// Provided by VK_NN_vi_surface
VkResult vkCreateViSurfaceNN(
VkInstance instance,
const VkViSurfaceCreateInfoNN* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance with which to associate the surface. -
pCreateInfois a pointer to aVkViSurfaceCreateInfoNNstructure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
During the lifetime of a surface created using a particular
nn::vi::NativeWindowHandle, applications must not attempt to
create another surface for the same nn::vi::Layer or attempt
to connect to the same nn::vi::Layer through other platform
mechanisms.
If the native window is created with a specified size, currentExtent
will reflect that size.
In this case, applications should use the same size for the swapchain’s
imageExtent.
Otherwise, the currentExtent will have the special value
(0xFFFFFFFF, 0xFFFFFFFF), indicating that applications are expected to
choose an appropriate size for the swapchain’s imageExtent (e.g., by
matching the result of a call to
nn::vi::GetDisplayResolution).
The VkViSurfaceCreateInfoNN structure is defined as:
// Provided by VK_NN_vi_surface
typedef struct VkViSurfaceCreateInfoNN {
VkStructureType sType;
const void* pNext;
VkViSurfaceCreateFlagsNN flags;
void* window;
} VkViSurfaceCreateInfoNN;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
windowis thenn::vi::NativeWindowHandlefor thenn::vi::Layerwith which to associate the surface.
// Provided by VK_NN_vi_surface
typedef VkFlags VkViSurfaceCreateFlagsNN;
VkViSurfaceCreateFlagsNN is a bitmask type for setting a mask, but is
currently reserved for future use.
33.2.12. Metal Platform
To create a VkSurfaceKHR object for a CAMetalLayer, call:
// Provided by VK_EXT_metal_surface
VkResult vkCreateMetalSurfaceEXT(
VkInstance instance,
const VkMetalSurfaceCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance with which to associate the surface. -
pCreateInfois a pointer to a VkMetalSurfaceCreateInfoEXT structure specifying parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to aVkSurfaceKHRhandle in which the created surface object is returned.
The VkMetalSurfaceCreateInfoEXT structure is defined as:
// Provided by VK_EXT_metal_surface
typedef struct VkMetalSurfaceCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkMetalSurfaceCreateFlagsEXT flags;
const CAMetalLayer* pLayer;
} VkMetalSurfaceCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
pLayeris a reference to aCAMetalLayerobject representing a renderable surface.
To remove an unnecessary compile-time dependency, an incomplete type
definition of CAMetalLayer is provided in the Vulkan headers:
// Provided by VK_EXT_metal_surface
#ifdef __OBJC__
@class CAMetalLayer;
#else
typedef void CAMetalLayer;
#endif
The actual CAMetalLayer type is defined in the QuartzCore
framework.
// Provided by VK_EXT_metal_surface
typedef VkFlags VkMetalSurfaceCreateFlagsEXT;
VkMetalSurfaceCreateFlagsEXT is a bitmask type for setting a mask, but
is currently reserved for future use.
33.2.13. QNX Screen Platform
To create a VkSurfaceKHR object for a QNX Screen surface, call:
// Provided by VK_QNX_screen_surface
VkResult vkCreateScreenSurfaceQNX(
VkInstance instance,
const VkScreenSurfaceCreateInfoQNX* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate the surface with. -
pCreateInfois a pointer to a VkScreenSurfaceCreateInfoQNX structure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkScreenSurfaceCreateInfoQNX structure is defined as:
// Provided by VK_QNX_screen_surface
typedef struct VkScreenSurfaceCreateInfoQNX {
VkStructureType sType;
const void* pNext;
VkScreenSurfaceCreateFlagsQNX flags;
struct _screen_context* context;
struct _screen_window* window;
} VkScreenSurfaceCreateInfoQNX;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
contextandwindoware QNX Screencontextandwindowto associate the surface with.
// Provided by VK_QNX_screen_surface
typedef VkFlags VkScreenSurfaceCreateFlagsQNX;
VkScreenSurfaceCreateFlagsQNX is a bitmask type for setting a mask,
but is currently reserved for future use.
33.2.14. Platform-Independent Information
Once created, VkSurfaceKHR objects can be used in this and other
extensions, in particular the VK_KHR_swapchain extension.
Several WSI functions return VK_ERROR_SURFACE_LOST_KHR if the surface
becomes no longer available.
After such an error, the surface (and any child swapchain, if one exists)
should be destroyed, as there is no way to restore them to a not-lost
state.
Applications may attempt to create a new VkSurfaceKHR using the same
native platform window object, but whether such re-creation will succeed is
platform-dependent and may depend on the reason the surface became
unavailable.
A lost surface does not otherwise cause devices to be
lost.
To destroy a VkSurfaceKHR object, call:
// Provided by VK_KHR_surface
void vkDestroySurfaceKHR(
VkInstance instance,
VkSurfaceKHR surface,
const VkAllocationCallbacks* pAllocator);
-
instanceis the instance used to create the surface. -
surfaceis the surface to destroy. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
Destroying a VkSurfaceKHR merely severs the connection between Vulkan
and the native surface, and does not imply destroying the native surface,
closing a window, or similar behavior.
33.3. Presenting Directly to Display Devices
In some environments applications can also present Vulkan rendering
directly to display devices without using an intermediate windowing system.
This can be useful for embedded applications, or implementing the
rendering/presentation backend of a windowing system using Vulkan.
The VK_KHR_display extension provides the functionality necessary to
enumerate display devices and create VkSurfaceKHR objects that target
displays.
33.3.1. Display Enumeration
Displays are represented by VkDisplayKHR handles:
// Provided by VK_KHR_display
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayKHR)
Various functions are provided for enumerating the available display devices present on a Vulkan physical device. To query information about the available displays, call:
// Provided by VK_KHR_display
VkResult vkGetPhysicalDeviceDisplayPropertiesKHR(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkDisplayPropertiesKHR* pProperties);
-
physicalDeviceis a physical device. -
pPropertyCountis a pointer to an integer related to the number of display devices available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array ofVkDisplayPropertiesKHRstructures.
If pProperties is NULL, then the number of display devices available
for physicalDevice 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 the value of pPropertyCount is less than the number of display
devices for physicalDevice, at most pPropertyCount 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 VkDisplayPropertiesKHR structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayPropertiesKHR {
VkDisplayKHR display;
const char* displayName;
VkExtent2D physicalDimensions;
VkExtent2D physicalResolution;
VkSurfaceTransformFlagsKHR supportedTransforms;
VkBool32 planeReorderPossible;
VkBool32 persistentContent;
} VkDisplayPropertiesKHR;
-
displayis a handle that is used to refer to the display described here. This handle will be valid for the lifetime of the Vulkan instance. -
displayNameisNULLor a pointer to a null-terminated UTF-8 string containing the name of the display. Generally, this will be the name provided by the display’s EDID. IfNULL, no suitable name is available. If notNULL, the string pointed to must remain accessible and unmodified as long asdisplayis valid. -
physicalDimensionsdescribes the physical width and height of the visible portion of the display, in millimeters. -
physicalResolutiondescribes the physical, native, or preferred resolution of the display.
|
Note
For devices which have no natural value to return here, implementations should return the maximum resolution supported. |
-
supportedTransformsis a bitmask of VkSurfaceTransformFlagBitsKHR describing which transforms are supported by this display. -
planeReorderPossibletells whether the planes on this display can have their z order changed. If this isVK_TRUE, the application can re-arrange the planes on this display in any order relative to each other. -
persistentContenttells whether the display supports self-refresh/internal buffering. If this is true, the application can submit persistent present operations on swapchains created against this display.
|
Note
Persistent presents may have higher latency, and may use less power when the screen content is updated infrequently, or when only a portion of the screen needs to be updated in most frames. |
To query information about the available displays, call:
// Provided by VK_KHR_get_display_properties2
VkResult vkGetPhysicalDeviceDisplayProperties2KHR(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkDisplayProperties2KHR* pProperties);
-
physicalDeviceis a physical device. -
pPropertyCountis a pointer to an integer related to the number of display devices available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array ofVkDisplayProperties2KHRstructures.
vkGetPhysicalDeviceDisplayProperties2KHR behaves similarly to
vkGetPhysicalDeviceDisplayPropertiesKHR, with the ability to return
extended information via chained output structures.
The VkDisplayProperties2KHR structure is defined as:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayProperties2KHR {
VkStructureType sType;
void* pNext;
VkDisplayPropertiesKHR displayProperties;
} VkDisplayProperties2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
displayPropertiesis a VkDisplayPropertiesKHR structure.
Acquiring and Releasing Displays
On some platforms, access to displays is limited to a single process or native driver instance. On such platforms, some or all of the displays may not be available to Vulkan if they are already in use by a native windowing system or other application.
To acquire permission to directly access a display in Vulkan from an X11 server, call:
// Provided by VK_EXT_acquire_xlib_display
VkResult vkAcquireXlibDisplayEXT(
VkPhysicalDevice physicalDevice,
Display* dpy,
VkDisplayKHR display);
-
physicalDeviceThe physical device the display is on. -
dpyA connection to the X11 server that currently ownsdisplay. -
displayThe display the caller wishes to control in Vulkan.
All permissions necessary to control the display are granted to the Vulkan
instance associated with physicalDevice until the display is released
or the X11 connection specified by dpy is terminated.
Permission to access the display may be temporarily revoked during periods
when the X11 server from which control was acquired itself loses access to
display.
During such periods, operations which require access to the display must
fail with an approriate error code.
If the X11 server associated with dpy does not own display, or
if permission to access it has already been acquired by another entity, the
call must return the error code VK_ERROR_INITIALIZATION_FAILED.
|
Note
One example of when an X11 server loses access to a display is when it loses ownership of its virtual terminal. |
When acquiring displays from an X11 server, an application may also wish to
enumerate and identify them using a native handle rather than a
VkDisplayKHR handle.
To determine the VkDisplayKHR handle corresponding to an X11 RandR
Output, call:
// Provided by VK_EXT_acquire_xlib_display
VkResult vkGetRandROutputDisplayEXT(
VkPhysicalDevice physicalDevice,
Display* dpy,
RROutput rrOutput,
VkDisplayKHR* pDisplay);
-
physicalDeviceThe physical device to query the display handle on. -
dpyA connection to the X11 server from whichrrOutputwas queried. -
rrOutputAn X11 RandR output ID. -
pDisplayThe corresponding VkDisplayKHR handle will be returned here.
If there is no VkDisplayKHR corresponding to rrOutput on
physicalDevice, VK_NULL_HANDLE must be returned in
pDisplay.
To acquire permission to directly access a display in Vulkan on Windows 10, call:
// Provided by VK_NV_acquire_winrt_display
VkResult vkAcquireWinrtDisplayNV(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display);
-
physicalDeviceThe physical device the display is on. -
displayThe display the caller wishes to control in Vulkan.
All permissions necessary to control the display are granted to the Vulkan
instance associated with physicalDevice until the display is released
or the application is terminated.
Permission to access the display may be revoked by events that cause
Windows 10 itself to lose access to display.
If this has happened, operations which require access to the display must
fail with an appropriate error code.
If permission to access display has already been acquired by another
entity, the call must return the error code
VK_ERROR_INITIALIZATION_FAILED.
|
Note
The Vulkan instance acquires control of a “winrt::Windows::Devices::Display::Core::DisplayTarget” by performing an operation equivalent to “winrt::Windows::Devices::Display::Core::DisplayManager.TryAcquireTarget()” on the “DisplayTarget”. |
|
Note
One example of when Windows 10 loses access to a display is when the display is hot-unplugged. |
|
Note
One example of when a display has already been acquired by another entity is when the Windows desktop compositor (DWM) is in control of the display. Beginning with Windows 10 version 2004 it is possible to cause DWM to release a display by using the “Advanced display settings” sub-page of the “Display settings” control panel. vkAcquireWinrtDisplayNV does not itself cause DWM to release a display; this action must be performed outside of Vulkan. |
When acquiring displays on Windows 10, an application may also wish to
enumerate and identify them using a native handle rather than a
VkDisplayKHR handle.
To determine the VkDisplayKHR handle corresponding to a
“winrt::Windows::Devices::Display::Core::DisplayTarget”,
call:
// Provided by VK_NV_acquire_winrt_display
VkResult vkGetWinrtDisplayNV(
VkPhysicalDevice physicalDevice,
uint32_t deviceRelativeId,
VkDisplayKHR* pDisplay);
-
physicalDeviceThe physical device on which to query the display handle. -
deviceRelativeIdThe value of the “AdapterRelativeId” property of a “DisplayTarget” that is enumerated by a “DisplayAdapter” with an “Id” property matching thedeviceLUIDproperty of a VkPhysicalDeviceIDProperties forphysicalDevice. -
pDisplayThe corresponding VkDisplayKHR handle will be returned here.
If there is no VkDisplayKHR corresponding to deviceRelativeId on
physicalDevice, VK_NULL_HANDLE must be returned in
pDisplay.
To acquire permission to directly a display in Vulkan from the Direct Rendering Manager (DRM) interface, call:
// Provided by VK_EXT_acquire_drm_display
VkResult vkAcquireDrmDisplayEXT(
VkPhysicalDevice physicalDevice,
int32_t drmFd,
VkDisplayKHR display);
-
physicalDeviceThe physical device the display is on. -
drmFdDRM primary file descriptor. -
displayThe display the caller wishes Vulkan to control.
All permissions necessary to control the display are granted to the Vulkan
instance associated with the provided physicalDevice until the display
is either released or the connector is unplugged.
The provided drmFd must correspond to the one owned by the
physicalDevice.
If not, the error code VK_ERROR_UNKNOWN must be returned.
The DRM FD must have DRM master permissions.
If any error is encountered during the acquisition of the display, the call
must return the error code VK_ERROR_INITIALIZATION_FAILED.
The provided DRM fd should not be closed before the display is released, attempting to do it may result in undefined behaviour.
Before acquiring a display from the DRM interface, the caller may want to
select a specific VkDisplayKHR handle by identifying it using a
connectorId.
To do so, call:
// Provided by VK_EXT_acquire_drm_display
VkResult vkGetDrmDisplayEXT(
VkPhysicalDevice physicalDevice,
int32_t drmFd,
uint32_t connectorId,
VkDisplayKHR* display);
-
physicalDeviceThe physical device to query the display from. -
drmFdDRM primary file descriptor. -
connectorIdIdentifier of the specified DRM connector. -
displayThe corresponding VkDisplayKHR handle will be returned here.
If there is no VkDisplayKHR corresponding to the connectorId on
the physicalDevice, the returning display must be set to
VK_NULL_HANDLE.
The provided drmFd must correspond to the one owned by the
physicalDevice.
If not, the error code VK_ERROR_UNKNOWN must be returned.
Master permissions are not required, because the file descriptor is just
used for information gathering purposes.
The given connectorId must be a resource owned by the provided
drmFd.
If not, the error code VK_ERROR_UNKNOWN must be returned.
If any error is encountered during the identification of the display, the
call must return the error code VK_ERROR_INITIALIZATION_FAILED.
To release a previously acquired display, call:
// Provided by VK_EXT_direct_mode_display
VkResult vkReleaseDisplayEXT(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display);
-
physicalDeviceThe physical device the display is on. -
displayThe display to release control of.
Display Planes
Images are presented to individual planes on a display. Devices must support at least one plane on each display. Planes can be stacked and blended to composite multiple images on one display. Devices may support only a fixed stacking order and fixed mapping between planes and displays, or they may allow arbitrary application specified stacking orders and mappings between planes and displays. To query the properties of device display planes, call:
// Provided by VK_KHR_display
VkResult vkGetPhysicalDeviceDisplayPlanePropertiesKHR(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkDisplayPlanePropertiesKHR* pProperties);
-
physicalDeviceis a physical device. -
pPropertyCountis a pointer to an integer related to the number of display planes available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array ofVkDisplayPlanePropertiesKHRstructures.
If pProperties is NULL, then the number of display planes available
for physicalDevice 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 the value of pPropertyCount is less than the number of display
planes for physicalDevice, at most pPropertyCount structures
will be written.
The VkDisplayPlanePropertiesKHR structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayPlanePropertiesKHR {
VkDisplayKHR currentDisplay;
uint32_t currentStackIndex;
} VkDisplayPlanePropertiesKHR;
-
currentDisplayis the handle of the display the plane is currently associated with. If the plane is not currently attached to any displays, this will be VK_NULL_HANDLE. -
currentStackIndexis the current z-order of the plane. This will be between 0 and the value returned byvkGetPhysicalDeviceDisplayPlanePropertiesKHRinpPropertyCount.
To query the properties of a device’s display planes, call:
// Provided by VK_KHR_get_display_properties2
VkResult vkGetPhysicalDeviceDisplayPlaneProperties2KHR(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkDisplayPlaneProperties2KHR* pProperties);
-
physicalDeviceis a physical device. -
pPropertyCountis a pointer to an integer related to the number of display planes available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array ofVkDisplayPlaneProperties2KHRstructures.
vkGetPhysicalDeviceDisplayPlaneProperties2KHR behaves similarly to
vkGetPhysicalDeviceDisplayPlanePropertiesKHR, with the ability to
return extended information via chained output structures.
The VkDisplayPlaneProperties2KHR structure is defined as:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayPlaneProperties2KHR {
VkStructureType sType;
void* pNext;
VkDisplayPlanePropertiesKHR displayPlaneProperties;
} VkDisplayPlaneProperties2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
displayPlanePropertiesis a VkDisplayPlanePropertiesKHR structure.
To determine which displays a plane is usable with, call
// Provided by VK_KHR_display
VkResult vkGetDisplayPlaneSupportedDisplaysKHR(
VkPhysicalDevice physicalDevice,
uint32_t planeIndex,
uint32_t* pDisplayCount,
VkDisplayKHR* pDisplays);
-
physicalDeviceis a physical device. -
planeIndexis the plane which the application wishes to use, and must be in the range [0, physical device plane count - 1]. -
pDisplayCountis a pointer to an integer related to the number of displays available or queried, as described below. -
pDisplaysis eitherNULLor a pointer to an array ofVkDisplayKHRhandles.
If pDisplays is NULL, then the number of displays usable with the
specified planeIndex for physicalDevice is returned in
pDisplayCount.
Otherwise, pDisplayCount must point to a variable set by the user to
the number of elements in the pDisplays array, and on return the
variable is overwritten with the number of handles actually written to
pDisplays.
If the value of pDisplayCount is less than the number of usable
display-plane pairs for physicalDevice, at most pDisplayCount
handles will be written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available pairs were
returned.
Additional properties of displays are queried using specialized query functions.
Display Modes
Display modes are represented by VkDisplayModeKHR handles:
// Provided by VK_KHR_display
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayModeKHR)
Each display has one or more supported modes associated with it by default. These built-in modes are queried by calling:
// Provided by VK_KHR_display
VkResult vkGetDisplayModePropertiesKHR(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display,
uint32_t* pPropertyCount,
VkDisplayModePropertiesKHR* pProperties);
-
physicalDeviceis the physical device associated withdisplay. -
displayis the display to query. -
pPropertyCountis a pointer to an integer related to the number of display modes available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array ofVkDisplayModePropertiesKHRstructures.
If pProperties is NULL, then the number of display modes available
on the specified display for physicalDevice 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 the value of pPropertyCount is less than the number of display
modes for physicalDevice, at most pPropertyCount structures will
be written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available display modes were
returned.
The VkDisplayModePropertiesKHR structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayModePropertiesKHR {
VkDisplayModeKHR displayMode;
VkDisplayModeParametersKHR parameters;
} VkDisplayModePropertiesKHR;
-
displayModeis a handle to the display mode described in this structure. This handle will be valid for the lifetime of the Vulkan instance. -
parametersis a VkDisplayModeParametersKHR structure describing the display parameters associated withdisplayMode.
// Provided by VK_KHR_display
typedef VkFlags VkDisplayModeCreateFlagsKHR;
VkDisplayModeCreateFlagsKHR is a bitmask type for setting a mask, but
is currently reserved for future use.
To query the properties of a device’s built-in display modes, call:
// Provided by VK_KHR_get_display_properties2
VkResult vkGetDisplayModeProperties2KHR(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display,
uint32_t* pPropertyCount,
VkDisplayModeProperties2KHR* pProperties);
-
physicalDeviceis the physical device associated withdisplay. -
displayis the display to query. -
pPropertyCountis a pointer to an integer related to the number of display modes available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array ofVkDisplayModeProperties2KHRstructures.
vkGetDisplayModeProperties2KHR behaves similarly to
vkGetDisplayModePropertiesKHR, with the ability to return extended
information via chained output structures.
The VkDisplayModeProperties2KHR structure is defined as:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayModeProperties2KHR {
VkStructureType sType;
void* pNext;
VkDisplayModePropertiesKHR displayModeProperties;
} VkDisplayModeProperties2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
displayModePropertiesis a VkDisplayModePropertiesKHR structure.
The VkDisplayModeParametersKHR structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayModeParametersKHR {
VkExtent2D visibleRegion;
uint32_t refreshRate;
} VkDisplayModeParametersKHR;
-
visibleRegionis the 2D extents of the visible region. -
refreshRateis auint32_tthat is the number of times the display is refreshed each second multiplied by 1000.
|
Note
For example, a 60Hz display mode would report a |
Additional modes may also be created by calling:
// Provided by VK_KHR_display
VkResult vkCreateDisplayModeKHR(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display,
const VkDisplayModeCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDisplayModeKHR* pMode);
-
physicalDeviceis the physical device associated withdisplay. -
displayis the display to create an additional mode for. -
pCreateInfois a pointer to a VkDisplayModeCreateInfoKHR structure describing the new mode to create. -
pAllocatoris the allocator used for host memory allocated for the display mode object when there is no more specific allocator available (see Memory Allocation). -
pModeis a pointer to a VkDisplayModeKHR handle in which the mode created is returned.
The VkDisplayModeCreateInfoKHR structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayModeCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkDisplayModeCreateFlagsKHR flags;
VkDisplayModeParametersKHR parameters;
} VkDisplayModeCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use, and must be zero. -
parametersis a VkDisplayModeParametersKHR structure describing the display parameters to use in creating the new mode. If the parameters are not compatible with the specified display, the implementation must returnVK_ERROR_INITIALIZATION_FAILED.
Applications that wish to present directly to a display must select which layer, or “plane” of the display they wish to target, and a mode to use with the display. Each display supports at least one plane. The capabilities of a given mode and plane combination are determined by calling:
// Provided by VK_KHR_display
VkResult vkGetDisplayPlaneCapabilitiesKHR(
VkPhysicalDevice physicalDevice,
VkDisplayModeKHR mode,
uint32_t planeIndex,
VkDisplayPlaneCapabilitiesKHR* pCapabilities);
-
physicalDeviceis the physical device associated with the display specified bymode -
modeis the display mode the application intends to program when using the specified plane. Note this parameter also implicitly specifies a display. -
planeIndexis the plane which the application intends to use with the display, and is less than the number of display planes supported by the device. -
pCapabilitiesis a pointer to a VkDisplayPlaneCapabilitiesKHR structure in which the capabilities are returned.
The VkDisplayPlaneCapabilitiesKHR structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayPlaneCapabilitiesKHR {
VkDisplayPlaneAlphaFlagsKHR supportedAlpha;
VkOffset2D minSrcPosition;
VkOffset2D maxSrcPosition;
VkExtent2D minSrcExtent;
VkExtent2D maxSrcExtent;
VkOffset2D minDstPosition;
VkOffset2D maxDstPosition;
VkExtent2D minDstExtent;
VkExtent2D maxDstExtent;
} VkDisplayPlaneCapabilitiesKHR;
-
supportedAlphais a bitmask of VkDisplayPlaneAlphaFlagBitsKHR describing the supported alpha blending modes. -
minSrcPositionis the minimum source rectangle offset supported by this plane using the specified mode. -
maxSrcPositionis the maximum source rectangle offset supported by this plane using the specified mode. Thexandycomponents ofmaxSrcPositionmust each be greater than or equal to thexandycomponents ofminSrcPosition, respectively. -
minSrcExtentis the minimum source rectangle size supported by this plane using the specified mode. -
maxSrcExtentis the maximum source rectangle size supported by this plane using the specified mode. -
minDstPosition,maxDstPosition,minDstExtent,maxDstExtentall have similar semantics to their corresponding*Src*equivalents, but apply to the output region within the mode rather than the input region within the source image. Unlike the*Src*offsets,minDstPositionandmaxDstPositionmay contain negative values.
The minimum and maximum position and extent fields describe the
implementation limits, if any, as they apply to the specified display mode
and plane.
Vendors may support displaying a subset of a swapchain’s presentable images
on the specified display plane.
This is expressed by returning minSrcPosition, maxSrcPosition,
minSrcExtent, and maxSrcExtent values that indicate a range of
possible positions and sizes which may be used to specify the region within
the presentable images that source pixels will be read from when creating a
swapchain on the specified display mode and plane.
Vendors may also support mapping the presentable images’ content to a
subset or superset of the visible region in the specified display mode.
This is expressed by returning minDstPosition, maxDstPosition,
minDstExtent and maxDstExtent values that indicate a range of
possible positions and sizes which may be used to describe the region
within the display mode that the source pixels will be mapped to.
Other vendors may support only a 1-1 mapping between pixels in the
presentable images and the display mode.
This may be indicated by returning (0,0) for minSrcPosition,
maxSrcPosition, minDstPosition, and maxDstPosition, and
(display mode width, display mode height) for minSrcExtent,
maxSrcExtent, minDstExtent, and maxDstExtent.
The value supportedAlpha must contain at least one valid
VkDisplayPlaneAlphaFlagBitsKHR bit.
These values indicate the limits of the implementation’s individual fields.
Not all combinations of values within the offset and extent ranges returned
in VkDisplayPlaneCapabilitiesKHR are guaranteed to be supported.
Presentation requests specifying unsupported combinations may fail.
To query the capabilities of a given mode and plane combination, call:
// Provided by VK_KHR_get_display_properties2
VkResult vkGetDisplayPlaneCapabilities2KHR(
VkPhysicalDevice physicalDevice,
const VkDisplayPlaneInfo2KHR* pDisplayPlaneInfo,
VkDisplayPlaneCapabilities2KHR* pCapabilities);
-
physicalDeviceis the physical device associated withpDisplayPlaneInfo. -
pDisplayPlaneInfois a pointer to a VkDisplayPlaneInfo2KHR structure describing the plane and mode. -
pCapabilitiesis a pointer to a VkDisplayPlaneCapabilities2KHR structure in which the capabilities are returned.
vkGetDisplayPlaneCapabilities2KHR behaves similarly to
vkGetDisplayPlaneCapabilitiesKHR, with the ability to specify extended
inputs via chained input structures, and to return extended information via
chained output structures.
The VkDisplayPlaneInfo2KHR structure is defined as:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayPlaneInfo2KHR {
VkStructureType sType;
const void* pNext;
VkDisplayModeKHR mode;
uint32_t planeIndex;
} VkDisplayPlaneInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
modeis the display mode the application intends to program when using the specified plane.
|
Note
This parameter also implicitly specifies a display. |
-
planeIndexis the plane which the application intends to use with the display.
The members of VkDisplayPlaneInfo2KHR correspond to the arguments to
vkGetDisplayPlaneCapabilitiesKHR, with sType and pNext
added for extensibility.
The VkDisplayPlaneCapabilities2KHR structure is defined as:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayPlaneCapabilities2KHR {
VkStructureType sType;
void* pNext;
VkDisplayPlaneCapabilitiesKHR capabilities;
} VkDisplayPlaneCapabilities2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
capabilitiesis a VkDisplayPlaneCapabilitiesKHR structure.
33.3.2. Display Control
To set the power state of a display, call:
// Provided by VK_EXT_display_control
VkResult vkDisplayPowerControlEXT(
VkDevice device,
VkDisplayKHR display,
const VkDisplayPowerInfoEXT* pDisplayPowerInfo);
-
deviceis a logical device associated withdisplay. -
displayis the display whose power state is modified. -
pDisplayPowerInfois a pointer to a VkDisplayPowerInfoEXT structure specifying the new power state ofdisplay.
The VkDisplayPowerInfoEXT structure is defined as:
// Provided by VK_EXT_display_control
typedef struct VkDisplayPowerInfoEXT {
VkStructureType sType;
const void* pNext;
VkDisplayPowerStateEXT powerState;
} VkDisplayPowerInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
powerStateis a VkDisplayPowerStateEXT value specifying the new power state of the display.
Possible values of VkDisplayPowerInfoEXT::powerState, specifying
the new power state of a display, are:
// Provided by VK_EXT_display_control
typedef enum VkDisplayPowerStateEXT {
VK_DISPLAY_POWER_STATE_OFF_EXT = 0,
VK_DISPLAY_POWER_STATE_SUSPEND_EXT = 1,
VK_DISPLAY_POWER_STATE_ON_EXT = 2,
} VkDisplayPowerStateEXT;
-
VK_DISPLAY_POWER_STATE_OFF_EXTspecifies that the display is powered down. -
VK_DISPLAY_POWER_STATE_SUSPEND_EXTspecifies that the display is put into a low power mode, from which it may be able to transition back toVK_DISPLAY_POWER_STATE_ON_EXTmore quickly than if it were inVK_DISPLAY_POWER_STATE_OFF_EXT. This state may be the same asVK_DISPLAY_POWER_STATE_OFF_EXT. -
VK_DISPLAY_POWER_STATE_ON_EXTspecifies that the display is powered on.
33.3.3. Display Surfaces
A complete display configuration includes a mode, one or more display planes
and any parameters describing their behavior, and parameters describing some
aspects of the images associated with those planes.
Display surfaces describe the configuration of a single plane within a
complete display configuration.
To create a VkSurfaceKHR object for a display plane, call:
// Provided by VK_KHR_display
VkResult vkCreateDisplayPlaneSurfaceKHR(
VkInstance instance,
const VkDisplaySurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance corresponding to the physical device the targeted display is on. -
pCreateInfois a pointer to a VkDisplaySurfaceCreateInfoKHR structure specifying which mode, plane, and other parameters to use, as described below. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to a VkSurfaceKHR handle in which the created surface is returned.
The VkDisplaySurfaceCreateInfoKHR structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplaySurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkDisplaySurfaceCreateFlagsKHR flags;
VkDisplayModeKHR displayMode;
uint32_t planeIndex;
uint32_t planeStackIndex;
VkSurfaceTransformFlagBitsKHR transform;
float globalAlpha;
VkDisplayPlaneAlphaFlagBitsKHR alphaMode;
VkExtent2D imageExtent;
} VkDisplaySurfaceCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use, and must be zero. -
displayModeis a VkDisplayModeKHR handle specifying the mode to use when displaying this surface. -
planeIndexis the plane on which this surface appears. -
planeStackIndexis the z-order of the plane. -
transformis a VkSurfaceTransformFlagBitsKHR value specifying the transformation to apply to images as part of the scanout operation. -
globalAlphais the global alpha value. This value is ignored ifalphaModeis notVK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR. -
alphaModeis a VkDisplayPlaneAlphaFlagBitsKHR value specifying the type of alpha blending to use. -
imageExtentis the size of the presentable images to use with the surface.
|
Note
Creating a display surface must not modify the state of the displays, planes, or other resources it names. For example, it must not apply the specified mode to be set on the associated display. Application of display configuration occurs as a side effect of presenting to a display surface. |
// Provided by VK_KHR_display
typedef VkFlags VkDisplaySurfaceCreateFlagsKHR;
VkDisplaySurfaceCreateFlagsKHR is a bitmask type for setting a mask,
but is currently reserved for future use.
Bits which can be set in
VkDisplaySurfaceCreateInfoKHR::alphaMode, specifying the type of
alpha blending to use on a display, are:
// Provided by VK_KHR_display
typedef enum VkDisplayPlaneAlphaFlagBitsKHR {
VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR = 0x00000002,
VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR = 0x00000004,
VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR = 0x00000008,
} VkDisplayPlaneAlphaFlagBitsKHR;
-
VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHRspecifies that the source image will be treated as opaque. -
VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHRspecifies that a global alpha value must be specified that will be applied to all pixels in the source image. -
VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHRspecifies that the alpha value will be determined by the alpha component of the source image’s pixels. If the source format contains no alpha values, no blending will be applied. The source alpha values are not premultiplied into the source image’s other color components. -
VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHRis equivalent toVK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR, except the source alpha values are assumed to be premultiplied into the source image’s other color components.
// Provided by VK_KHR_display
typedef VkFlags VkDisplayPlaneAlphaFlagsKHR;
VkDisplayPlaneAlphaFlagsKHR is a bitmask type for setting a mask of
zero or more VkDisplayPlaneAlphaFlagBitsKHR.
33.3.4. Presenting to headless surfaces
Vulkan rendering can be presented to a headless surface, where the presentation operation is a no-op producing no externally-visible result.
|
Note
Because there is no real presentation target, the headless presentation engine may be extended to impose an arbitrary or customisable set of restrictions and features. This makes it a useful portable test target for applications targeting a wide range of presentation engines where the actual target presentation engines might be scarce, unavailable or otherwise undesirable or inconvenient to use for general Vulkan application development. The usual surface query mechanisms must be used to determine the actual restrictions and features of the implementation. |
To create a headless VkSurfaceKHR object, call:
// Provided by VK_EXT_headless_surface
VkResult vkCreateHeadlessSurfaceEXT(
VkInstance instance,
const VkHeadlessSurfaceCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate the surface with. -
pCreateInfois a pointer to a VkHeadlessSurfaceCreateInfoEXT structure containing parameters affecting the creation of the surface object. -
pAllocatoris the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurfaceis a pointer to aVkSurfaceKHRhandle in which the created surface object is returned.
The VkHeadlessSurfaceCreateInfoEXT structure is defined as:
// Provided by VK_EXT_headless_surface
typedef struct VkHeadlessSurfaceCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkHeadlessSurfaceCreateFlagsEXT flags;
} VkHeadlessSurfaceCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use.
For headless surfaces, currentExtent is the reserved value
(0xFFFFFFFF, 0xFFFFFFFF).
Whatever the application sets a swapchain’s imageExtent to will be the
size of the surface, after the first image is presented.
// Provided by VK_EXT_headless_surface
typedef VkFlags VkHeadlessSurfaceCreateFlagsEXT;
VkHeadlessSurfaceCreateFlagsEXT is a bitmask type for setting a mask,
but is currently reserved for future use.
33.4. Querying for WSI Support
Not all physical devices will include WSI support. Within a physical device, not all queue families will support presentation. WSI support and compatibility can be determined in a platform-neutral manner (which determines support for presentation to a particular surface object) and additionally may be determined in platform-specific manners (which determine support for presentation on the specified physical device but do not guarantee support for presentation to a particular surface object).
To determine whether a queue family of a physical device supports presentation to a given surface, call:
// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfaceSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
VkSurfaceKHR surface,
VkBool32* pSupported);
-
physicalDeviceis the physical device. -
queueFamilyIndexis the queue family. -
surfaceis the surface. -
pSupportedis a pointer to aVkBool32, which is set toVK_TRUEto indicate support, andVK_FALSEotherwise.
33.4.1. Android Platform
On Android, all physical devices and queue families must be capable of presentation with any native window. As a result there is no Android-specific query for these capabilities.
33.4.2. Wayland Platform
To determine whether a queue family of a physical device supports presentation to a Wayland compositor, call:
// Provided by VK_KHR_wayland_surface
VkBool32 vkGetPhysicalDeviceWaylandPresentationSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
struct wl_display* display);
-
physicalDeviceis the physical device. -
queueFamilyIndexis the queue family index. -
displayis a pointer to thewl_displayassociated with a Wayland compositor.
This platform-specific function can be called prior to creating a surface.
33.4.3. Win32 Platform
To determine whether a queue family of a physical device supports presentation to the Microsoft Windows desktop, call:
// Provided by VK_KHR_win32_surface
VkBool32 vkGetPhysicalDeviceWin32PresentationSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex);
-
physicalDeviceis the physical device. -
queueFamilyIndexis the queue family index.
This platform-specific function can be called prior to creating a surface.
33.4.4. XCB Platform
To determine whether a queue family of a physical device supports presentation to an X11 server, using the XCB client-side library, call:
// Provided by VK_KHR_xcb_surface
VkBool32 vkGetPhysicalDeviceXcbPresentationSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
xcb_connection_t* connection,
xcb_visualid_t visual_id);
-
physicalDeviceis the physical device. -
queueFamilyIndexis the queue family index. -
connectionis a pointer to anxcb_connection_tto the X server. -
visual_idis an X11 visual (xcb_visualid_t).
This platform-specific function can be called prior to creating a surface.
33.4.5. Xlib Platform
To determine whether a queue family of a physical device supports presentation to an X11 server, using the Xlib client-side library, call:
// Provided by VK_KHR_xlib_surface
VkBool32 vkGetPhysicalDeviceXlibPresentationSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
Display* dpy,
VisualID visualID);
-
physicalDeviceis the physical device. -
queueFamilyIndexis the queue family index. -
dpyis a pointer to an XlibDisplayconnection to the server. -
visualIdis an X11 visual (VisualID).
This platform-specific function can be called prior to creating a surface.
33.4.6. DirectFB Platform
To determine whether a queue family of a physical device supports presentation with DirectFB library, call:
// Provided by VK_EXT_directfb_surface
VkBool32 vkGetPhysicalDeviceDirectFBPresentationSupportEXT(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
IDirectFB* dfb);
-
physicalDeviceis the physical device. -
queueFamilyIndexis the queue family index. -
dfbis a pointer to theIDirectFBmain interface of DirectFB.
This platform-specific function can be called prior to creating a surface.
33.4.7. Fuchsia Platform
On Fuchsia, all physical devices and queue families must be capable of presentation with any ImagePipe. As a result there is no Fuchsia-specific query for these capabilities.
33.4.8. Google Games Platform
On Google Games Platform, all physical devices and queue families with the
VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT capabilities must
be capable of presentation with any Google Games Platform stream descriptor.
As a result, there is no query specific to Google Games Platform for these
capabilities.
33.4.9. iOS Platform
On iOS, all physical devices and queue families must be capable of presentation with any layer. As a result there is no iOS-specific query for these capabilities.
33.4.10. macOS Platform
On macOS, all physical devices and queue families must be capable of presentation with any layer. As a result there is no macOS-specific query for these capabilities.
33.4.11. VI Platform
On VI, all physical devices and queue families must be capable of presentation with any layer. As a result there is no VI-specific query for these capabilities.
33.4.12. QNX Screen Platform
To determine whether a queue family of a physical device supports presentation to a QNX Screen compositor, call:
// Provided by VK_QNX_screen_surface
VkBool32 vkGetPhysicalDeviceScreenPresentationSupportQNX(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
struct _screen_window* window);
-
physicalDeviceis the physical device. -
queueFamilyIndexis the queue family index. -
windowis the QNX Screenwindowobject.
This platform-specific function can be called prior to creating a surface.
33.5. Surface Queries
The capabilities of a swapchain targeting a surface are the intersection of the capabilities of the WSI platform, the native window or display, and the physical device. The resulting capabilities can be obtained with the queries listed below in this section.
|
Note
In addition to the surface capabilities as obtained by surface queries below, swapchain images are also subject to ordinary image creation limits as reported by vkGetPhysicalDeviceImageFormatProperties. As an application is instructed by the appropriate Valid Usage sections, both the surface capabilities and the image creation limits have to be satisfied whenever swapchain images are created. |
33.5.1. Surface Capabilities
To query the basic capabilities of a surface, needed in order to create a swapchain, call:
// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfaceCapabilitiesKHR(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
VkSurfaceCapabilitiesKHR* pSurfaceCapabilities);
-
physicalDeviceis the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
surfaceis the surface that will be associated with the swapchain. -
pSurfaceCapabilitiesis a pointer to a VkSurfaceCapabilitiesKHR structure in which the capabilities are returned.
The VkSurfaceCapabilitiesKHR structure is defined as:
// Provided by VK_KHR_surface
typedef struct VkSurfaceCapabilitiesKHR {
uint32_t minImageCount;
uint32_t maxImageCount;
VkExtent2D currentExtent;
VkExtent2D minImageExtent;
VkExtent2D maxImageExtent;
uint32_t maxImageArrayLayers;
VkSurfaceTransformFlagsKHR supportedTransforms;
VkSurfaceTransformFlagBitsKHR currentTransform;
VkCompositeAlphaFlagsKHR supportedCompositeAlpha;
VkImageUsageFlags supportedUsageFlags;
} VkSurfaceCapabilitiesKHR;
-
minImageCountis the minimum number of images the specified device supports for a swapchain created for the surface, and will be at least one. -
maxImageCountis the maximum number of images the specified device supports for a swapchain created for the surface, and will be either 0, or greater than or equal tominImageCount. A value of 0 means that there is no limit on the number of images, though there may be limits related to the total amount of memory used by presentable images. -
currentExtentis the current width and height of the surface, or the special value (0xFFFFFFFF, 0xFFFFFFFF) indicating that the surface size will be determined by the extent of a swapchain targeting the surface. -
minImageExtentcontains the smallest valid swapchain extent for the surface on the specified device. Thewidthandheightof the extent will each be less than or equal to the correspondingwidthandheightofcurrentExtent, unlesscurrentExtenthas the special value described above. -
maxImageExtentcontains the largest valid swapchain extent for the surface on the specified device. Thewidthandheightof the extent will each be greater than or equal to the correspondingwidthandheightofminImageExtent. Thewidthandheightof the extent will each be greater than or equal to the correspondingwidthandheightofcurrentExtent, unlesscurrentExtenthas the special value described above. -
maxImageArrayLayersis the maximum number of layers presentable images can have for a swapchain created for this device and surface, and will be at least one. -
supportedTransformsis a bitmask of VkSurfaceTransformFlagBitsKHR indicating the presentation transforms supported for the surface on the specified device. At least one bit will be set. -
currentTransformis VkSurfaceTransformFlagBitsKHR value indicating the surface’s current transform relative to the presentation engine’s natural orientation. -
supportedCompositeAlphais a bitmask of VkCompositeAlphaFlagBitsKHR, representing the alpha compositing modes supported by the presentation engine for the surface on the specified device, and at least one bit will be set. Opaque composition can be achieved in any alpha compositing mode by either using an image format that has no alpha component, or by ensuring that all pixels in the presentable images have an alpha value of 1.0. -
supportedUsageFlagsis a bitmask of VkImageUsageFlagBits representing the ways the application can use the presentable images of a swapchain created with VkPresentModeKHR set toVK_PRESENT_MODE_IMMEDIATE_KHR,VK_PRESENT_MODE_MAILBOX_KHR,VK_PRESENT_MODE_FIFO_KHRorVK_PRESENT_MODE_FIFO_RELAXED_KHRfor the surface on the specified device.VK_IMAGE_USAGE_COLOR_ATTACHMENT_BITmust be included in the set. Implementations may support additional usages.
|
Note
Supported usage flags of a presentable image when using
|
|
Note
Formulas such as min(N, |
To query the basic capabilities of a surface defined by the core or extensions, call:
// Provided by VK_KHR_get_surface_capabilities2
VkResult vkGetPhysicalDeviceSurfaceCapabilities2KHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceSurfaceInfo2KHR* pSurfaceInfo,
VkSurfaceCapabilities2KHR* pSurfaceCapabilities);
-
physicalDeviceis the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
pSurfaceInfois a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR. -
pSurfaceCapabilitiesis a pointer to a VkSurfaceCapabilities2KHR structure in which the capabilities are returned.
vkGetPhysicalDeviceSurfaceCapabilities2KHR behaves similarly to
vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to specify
extended inputs via chained input structures, and to return extended
information via chained output structures.
The VkPhysicalDeviceSurfaceInfo2KHR structure is defined as:
// Provided by VK_KHR_get_surface_capabilities2
typedef struct VkPhysicalDeviceSurfaceInfo2KHR {
VkStructureType sType;
const void* pNext;
VkSurfaceKHR surface;
} VkPhysicalDeviceSurfaceInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
surfaceis the surface that will be associated with the swapchain.
The members of VkPhysicalDeviceSurfaceInfo2KHR correspond to the
arguments to vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with
sType and pNext added for extensibility.
Additional capabilities of a surface may be available to swapchains created
with different full-screen exclusive settings - particularly if exclusive
full-screen access is application controlled.
These additional capabilities can be queried by adding a
VkSurfaceFullScreenExclusiveInfoEXT structure to the pNext chain
of this structure when used to query surface properties.
Additionally, for Win32 surfaces with application controlled exclusive
full-screen access, chaining a
VkSurfaceFullScreenExclusiveWin32InfoEXT structure may also report
additional surface capabilities.
These additional capabilities only apply to swapchains created with the same
parameters included in the pNext chain of
VkSwapchainCreateInfoKHR.
If the pNext chain of VkSwapchainCreateInfoKHR includes a
VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure
specifies the application’s preferred full-screen transition behavior.
The VkSurfaceFullScreenExclusiveInfoEXT structure is defined as:
// Provided by VK_EXT_full_screen_exclusive
typedef struct VkSurfaceFullScreenExclusiveInfoEXT {
VkStructureType sType;
void* pNext;
VkFullScreenExclusiveEXT fullScreenExclusive;
} VkSurfaceFullScreenExclusiveInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fullScreenExclusiveis a VkFullScreenExclusiveEXT value specifying the preferred full-screen transition behavior.
If this structure is not present, fullScreenExclusive is considered to
be VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT.
Possible values of
VkSurfaceFullScreenExclusiveInfoEXT::fullScreenExclusive are:
// Provided by VK_EXT_full_screen_exclusive
typedef enum VkFullScreenExclusiveEXT {
VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT = 0,
VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT = 1,
VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT = 2,
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT = 3,
} VkFullScreenExclusiveEXT;
-
VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXTindicates the implementation should determine the appropriate full-screen method by whatever means it deems appropriate. -
VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXTindicates the implementation may use full-screen exclusive mechanisms when available. Such mechanisms may result in better performance and/or the availability of different presentation capabilities, but may require a more disruptive transition during swapchain initialization, first presentation and/or destruction. -
VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXTindicates the implementation should avoid using full-screen mechanisms which rely on disruptive transitions. -
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXTindicates the application will manage full-screen exclusive mode by using the vkAcquireFullScreenExclusiveModeEXT and vkReleaseFullScreenExclusiveModeEXT commands.
The VkSurfaceFullScreenExclusiveWin32InfoEXT structure is defined as:
// Provided by VK_KHR_win32_surface with VK_EXT_full_screen_exclusive
typedef struct VkSurfaceFullScreenExclusiveWin32InfoEXT {
VkStructureType sType;
const void* pNext;
HMONITOR hmonitor;
} VkSurfaceFullScreenExclusiveWin32InfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
hmonitoris the Win32HMONITORhandle identifying the display to create the surface with.
|
Note
If |
|
Note
It is the responsibility of the application to change the display settings of the targeted Win32 display using the appropriate platform APIs. Such changes may alter the surface capabilities reported for the created surface. |
The VkSurfaceCapabilities2KHR structure is defined as:
// Provided by VK_KHR_get_surface_capabilities2
typedef struct VkSurfaceCapabilities2KHR {
VkStructureType sType;
void* pNext;
VkSurfaceCapabilitiesKHR surfaceCapabilities;
} VkSurfaceCapabilities2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
surfaceCapabilitiesis a VkSurfaceCapabilitiesKHR structure describing the capabilities of the specified surface.
An application queries if a protected VkSurfaceKHR is displayable on a
specific windowing system using VkSurfaceProtectedCapabilitiesKHR,
which can be passed in pNext parameter of
VkSurfaceCapabilities2KHR.
The VkSurfaceProtectedCapabilitiesKHR structure is defined as:
// Provided by VK_KHR_surface_protected_capabilities
typedef struct VkSurfaceProtectedCapabilitiesKHR {
VkStructureType sType;
const void* pNext;
VkBool32 supportsProtected;
} VkSurfaceProtectedCapabilitiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
supportsProtectedspecifies whether a protected swapchain created from VkPhysicalDeviceSurfaceInfo2KHR::surfacefor a particular windowing system can be displayed on screen or not. IfsupportsProtectedisVK_TRUE, then creation of swapchains with theVK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHRflag set must be supported forsurface.
If the VK_GOOGLE_surfaceless_query extension is enabled, the value
returned in supportsProtected will be identical for every valid
surface created on this physical device, and so in the
vkGetPhysicalDeviceSurfaceCapabilities2KHR call,
VkPhysicalDeviceSurfaceInfo2KHR::surface can be
VK_NULL_HANDLE.
In that case, the contents of
VkSurfaceCapabilities2KHR::surfaceCapabilities as well as any
other struct chained to it will be undefined.
The VkSharedPresentSurfaceCapabilitiesKHR structure is defined as:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sharedPresentSupportedUsageFlagsis a bitmask of VkImageUsageFlagBits representing the ways the application can use the shared presentable image from a swapchain created with VkPresentModeKHR set toVK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHRorVK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHRfor the surface on the specified device.VK_IMAGE_USAGE_COLOR_ATTACHMENT_BITmust be included in the set but implementations may support additional usages.
The VkDisplayNativeHdrSurfaceCapabilitiesAMD structure is defined as:
// Provided by VK_AMD_display_native_hdr
typedef struct VkDisplayNativeHdrSurfaceCapabilitiesAMD {
VkStructureType sType;
void* pNext;
VkBool32 localDimmingSupport;
} VkDisplayNativeHdrSurfaceCapabilitiesAMD;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
localDimmingSupportspecifies whether the surface supports local dimming. If this isVK_TRUE, VkSwapchainDisplayNativeHdrCreateInfoAMD can be used to explicitly enable or disable local dimming for the surface. Local dimming may also be overriden by vkSetLocalDimmingAMD during the lifetime of the swapchain.
The VkSurfaceCapabilitiesFullScreenExclusiveEXT structure is defined
as:
// Provided by VK_EXT_full_screen_exclusive
typedef struct VkSurfaceCapabilitiesFullScreenExclusiveEXT {
VkStructureType sType;
void* pNext;
VkBool32 fullScreenExclusiveSupported;
} VkSurfaceCapabilitiesFullScreenExclusiveEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fullScreenExclusiveControlSupportedis a boolean describing whether the surface is able to make use of exclusive full-screen access.
This structure can be included in the pNext chain of
VkSurfaceCapabilities2KHR to determine support for exclusive
full-screen access.
If fullScreenExclusiveSupported is VK_FALSE, it indicates that
exclusive full-screen access is not obtainable for this surface.
Applications must not attempt to create swapchains with
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT set if
fullScreenExclusiveSupported is VK_FALSE.
To query the basic capabilities of a surface, needed in order to create a swapchain, call:
// Provided by VK_EXT_display_surface_counter
VkResult vkGetPhysicalDeviceSurfaceCapabilities2EXT(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
VkSurfaceCapabilities2EXT* pSurfaceCapabilities);
-
physicalDeviceis the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
surfaceis the surface that will be associated with the swapchain. -
pSurfaceCapabilitiesis a pointer to a VkSurfaceCapabilities2EXT structure in which the capabilities are returned.
vkGetPhysicalDeviceSurfaceCapabilities2EXT behaves similarly to
vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to return
extended information by adding extending structures to the pNext chain
of its pSurfaceCapabilities parameter.
The VkSurfaceCapabilities2EXT structure is defined as:
// Provided by VK_EXT_display_surface_counter
typedef struct VkSurfaceCapabilities2EXT {
VkStructureType sType;
void* pNext;
uint32_t minImageCount;
uint32_t maxImageCount;
VkExtent2D currentExtent;
VkExtent2D minImageExtent;
VkExtent2D maxImageExtent;
uint32_t maxImageArrayLayers;
VkSurfaceTransformFlagsKHR supportedTransforms;
VkSurfaceTransformFlagBitsKHR currentTransform;
VkCompositeAlphaFlagsKHR supportedCompositeAlpha;
VkImageUsageFlags supportedUsageFlags;
VkSurfaceCounterFlagsEXT supportedSurfaceCounters;
} VkSurfaceCapabilities2EXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minImageCountis the minimum number of images the specified device supports for a swapchain created for the surface, and will be at least one. -
maxImageCountis the maximum number of images the specified device supports for a swapchain created for the surface, and will be either 0, or greater than or equal tominImageCount. A value of 0 means that there is no limit on the number of images, though there may be limits related to the total amount of memory used by presentable images. -
currentExtentis the current width and height of the surface, or the special value (0xFFFFFFFF, 0xFFFFFFFF) indicating that the surface size will be determined by the extent of a swapchain targeting the surface. -
minImageExtentcontains the smallest valid swapchain extent for the surface on the specified device. Thewidthandheightof the extent will each be less than or equal to the correspondingwidthandheightofcurrentExtent, unlesscurrentExtenthas the special value described above. -
maxImageExtentcontains the largest valid swapchain extent for the surface on the specified device. Thewidthandheightof the extent will each be greater than or equal to the correspondingwidthandheightofminImageExtent. Thewidthandheightof the extent will each be greater than or equal to the correspondingwidthandheightofcurrentExtent, unlesscurrentExtenthas the special value described above. -
maxImageArrayLayersis the maximum number of layers presentable images can have for a swapchain created for this device and surface, and will be at least one. -
supportedTransformsis a bitmask of VkSurfaceTransformFlagBitsKHR indicating the presentation transforms supported for the surface on the specified device. At least one bit will be set. -
currentTransformis VkSurfaceTransformFlagBitsKHR value indicating the surface’s current transform relative to the presentation engine’s natural orientation. -
supportedCompositeAlphais a bitmask of VkCompositeAlphaFlagBitsKHR, representing the alpha compositing modes supported by the presentation engine for the surface on the specified device, and at least one bit will be set. Opaque composition can be achieved in any alpha compositing mode by either using an image format that has no alpha component, or by ensuring that all pixels in the presentable images have an alpha value of 1.0. -
supportedUsageFlagsis a bitmask of VkImageUsageFlagBits representing the ways the application can use the presentable images of a swapchain created with VkPresentModeKHR set toVK_PRESENT_MODE_IMMEDIATE_KHR,VK_PRESENT_MODE_MAILBOX_KHR,VK_PRESENT_MODE_FIFO_KHRorVK_PRESENT_MODE_FIFO_RELAXED_KHRfor the surface on the specified device.VK_IMAGE_USAGE_COLOR_ATTACHMENT_BITmust be included in the set. Implementations may support additional usages. -
supportedSurfaceCountersis a bitmask of VkSurfaceCounterFlagBitsEXT indicating the supported surface counter types.
Bits which can be set in
VkSurfaceCapabilities2EXT::supportedSurfaceCounters, indicating
supported surface counter types, are:
// Provided by VK_EXT_display_surface_counter
typedef enum VkSurfaceCounterFlagBitsEXT {
VK_SURFACE_COUNTER_VBLANK_BIT_EXT = 0x00000001,
VK_SURFACE_COUNTER_VBLANK_EXT = VK_SURFACE_COUNTER_VBLANK_BIT_EXT,
} VkSurfaceCounterFlagBitsEXT;
-
VK_SURFACE_COUNTER_VBLANK_BIT_EXTspecifies a counter incrementing once every time a vertical blanking period occurs on the display associated with the surface.
// Provided by VK_EXT_display_surface_counter
typedef VkFlags VkSurfaceCounterFlagsEXT;
VkSurfaceCounterFlagsEXT is a bitmask type for setting a mask of zero
or more VkSurfaceCounterFlagBitsEXT.
Bits which may be set in
VkSurfaceCapabilitiesKHR::supportedTransforms indicating the
presentation transforms supported for the surface on the specified device,
and possible values of
VkSurfaceCapabilitiesKHR::currentTransform indicating the
surface’s current transform relative to the presentation engine’s natural
orientation, are:
// Provided by VK_KHR_surface
typedef enum VkSurfaceTransformFlagBitsKHR {
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR = 0x00000001,
VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR = 0x00000002,
VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR = 0x00000004,
VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR = 0x00000008,
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR = 0x00000010,
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR = 0x00000020,
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR = 0x00000040,
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR = 0x00000080,
VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR = 0x00000100,
} VkSurfaceTransformFlagBitsKHR;
-
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHRspecifies that image content is presented without being transformed. -
VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHRspecifies that image content is rotated 90 degrees clockwise. -
VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHRspecifies that image content is rotated 180 degrees clockwise. -
VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHRspecifies that image content is rotated 270 degrees clockwise. -
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHRspecifies that image content is mirrored horizontally. -
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHRspecifies that image content is mirrored horizontally, then rotated 90 degrees clockwise. -
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHRspecifies that image content is mirrored horizontally, then rotated 180 degrees clockwise. -
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHRspecifies that image content is mirrored horizontally, then rotated 270 degrees clockwise. -
VK_SURFACE_TRANSFORM_INHERIT_BIT_KHRspecifies that the presentation transform is not specified, and is instead determined by platform-specific considerations and mechanisms outside Vulkan.
// Provided by VK_KHR_display
typedef VkFlags VkSurfaceTransformFlagsKHR;
VkSurfaceTransformFlagsKHR is a bitmask type for setting a mask of
zero or more VkSurfaceTransformFlagBitsKHR.
The supportedCompositeAlpha member is of type
VkCompositeAlphaFlagBitsKHR, containing the following values:
// Provided by VK_KHR_surface
typedef enum VkCompositeAlphaFlagBitsKHR {
VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR = 0x00000002,
VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR = 0x00000004,
VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR = 0x00000008,
} VkCompositeAlphaFlagBitsKHR;
These values are described as follows:
-
VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha component, if it exists, of the images is ignored in the compositing process. Instead, the image is treated as if it has a constant alpha of 1.0. -
VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are expected to already be multiplied by the alpha component by the application. -
VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are not expected to already be multiplied by the alpha component by the application; instead, the compositor will multiply the non-alpha components of the image by the alpha component during compositing. -
VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the presentation engine treats the alpha component in the images is unknown to the Vulkan API. Instead, the application is responsible for setting the composite alpha blending mode using native window system commands. If the application does not set the blending mode using native window system commands, then a platform-specific default will be used.
// Provided by VK_KHR_surface
typedef VkFlags VkCompositeAlphaFlagsKHR;
VkCompositeAlphaFlagsKHR is a bitmask type for setting a mask of zero
or more VkCompositeAlphaFlagBitsKHR.
33.5.2. Surface Format Support
To query the supported swapchain format-color space pairs for a surface, call:
// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfaceFormatsKHR(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
uint32_t* pSurfaceFormatCount,
VkSurfaceFormatKHR* pSurfaceFormats);
-
physicalDeviceis the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
surfaceis the surface that will be associated with the swapchain. -
pSurfaceFormatCountis a pointer to an integer related to the number of format pairs available or queried, as described below. -
pSurfaceFormatsis eitherNULLor a pointer to an array ofVkSurfaceFormatKHRstructures.
If pSurfaceFormats is NULL, then the number of format pairs
supported for the given surface is returned in
pSurfaceFormatCount.
Otherwise, pSurfaceFormatCount must point to a variable set by the
user to the number of elements in the pSurfaceFormats array, and on
return the variable is overwritten with the number of structures actually
written to pSurfaceFormats.
If the value of pSurfaceFormatCount is less than the number of format
pairs supported, at most pSurfaceFormatCount structures will be
written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available format pairs were
returned.
The number of format pairs supported must be greater than or equal to 1.
pSurfaceFormats must not contain an entry whose value for
format is VK_FORMAT_UNDEFINED.
If pSurfaceFormats includes an entry whose value for colorSpace
is VK_COLOR_SPACE_SRGB_NONLINEAR_KHR and whose value for format
is a UNORM (or SRGB) format and the corresponding SRGB (or UNORM) format is
a color renderable format for VK_IMAGE_TILING_OPTIMAL, then
pSurfaceFormats must also contain an entry with the same value for
colorSpace and format equal to the corresponding SRGB (or UNORM)
format.
If the VK_GOOGLE_surfaceless_query extension is enabled, the values
returned in pSurfaceFormats will be identical for every valid surface
created on this physical device, and so surface can be
VK_NULL_HANDLE.
The VkSurfaceFormatKHR structure is defined as:
// Provided by VK_KHR_surface
typedef struct VkSurfaceFormatKHR {
VkFormat format;
VkColorSpaceKHR colorSpace;
} VkSurfaceFormatKHR;
-
formatis a VkFormat that is compatible with the specified surface. -
colorSpaceis a presentation VkColorSpaceKHR that is compatible with the surface.
To query the supported swapchain format tuples for a surface, call:
// Provided by VK_KHR_get_surface_capabilities2
VkResult vkGetPhysicalDeviceSurfaceFormats2KHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceSurfaceInfo2KHR* pSurfaceInfo,
uint32_t* pSurfaceFormatCount,
VkSurfaceFormat2KHR* pSurfaceFormats);
-
physicalDeviceis the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
pSurfaceInfois a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR. -
pSurfaceFormatCountis a pointer to an integer related to the number of format tuples available or queried, as described below. -
pSurfaceFormatsis eitherNULLor a pointer to an array of VkSurfaceFormat2KHR structures.
vkGetPhysicalDeviceSurfaceFormats2KHR behaves similarly to
vkGetPhysicalDeviceSurfaceFormatsKHR, with the ability to be extended
via pNext chains.
If pSurfaceFormats is NULL, then the number of format tuples
supported for the given surface is returned in
pSurfaceFormatCount.
Otherwise, pSurfaceFormatCount must point to a variable set by the
user to the number of elements in the pSurfaceFormats array, and on
return the variable is overwritten with the number of structures actually
written to pSurfaceFormats.
If the value of pSurfaceFormatCount is less than the number of format
tuples supported, at most pSurfaceFormatCount structures will be
written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available values were
returned.
The VkSurfaceFormat2KHR structure is defined as:
// Provided by VK_KHR_get_surface_capabilities2
typedef struct VkSurfaceFormat2KHR {
VkStructureType sType;
void* pNext;
VkSurfaceFormatKHR surfaceFormat;
} VkSurfaceFormat2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
surfaceFormatis a VkSurfaceFormatKHR structure describing a format-color space pair that is compatible with the specified surface.
If the imageCompressionControlSwapchain feature is supported and a
VkImageCompressionPropertiesEXT structure is included in the
pNext chain of this structure, then it will be filled with the
compression properties that are supported for the surfaceFormat.
While the format of a presentable image refers to the encoding of each
pixel, the colorSpace determines how the presentation engine
interprets the pixel values.
A color space in this document refers to a specific color space (defined by
the chromaticities of its primaries and a white point in CIE Lab), and a
transfer function that is applied before storing or transmitting color data
in the given color space.
Possible values of VkSurfaceFormatKHR::colorSpace, specifying
supported color spaces of a presentation engine, are:
// Provided by VK_KHR_surface
typedef enum VkColorSpaceKHR {
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR = 0,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT = 1000104001,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT = 1000104002,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT = 1000104003,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT = 1000104004,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_BT709_LINEAR_EXT = 1000104005,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_BT709_NONLINEAR_EXT = 1000104006,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_BT2020_LINEAR_EXT = 1000104007,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_HDR10_ST2084_EXT = 1000104008,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_DOLBYVISION_EXT = 1000104009,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_HDR10_HLG_EXT = 1000104010,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT = 1000104011,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT = 1000104012,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_PASS_THROUGH_EXT = 1000104013,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT = 1000104014,
// Provided by VK_AMD_display_native_hdr
VK_COLOR_SPACE_DISPLAY_NATIVE_AMD = 1000213000,
VK_COLORSPACE_SRGB_NONLINEAR_KHR = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_DCI_P3_LINEAR_EXT = VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT,
} VkColorSpaceKHR;
-
VK_COLOR_SPACE_SRGB_NONLINEAR_KHRspecifies support for the sRGB color space. -
VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXTspecifies support for the Display-P3 color space to be displayed using an sRGB-like EOTF (defined below). -
VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXTspecifies support for the extended sRGB color space to be displayed using a linear EOTF. -
VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXTspecifies support for the extended sRGB color space to be displayed using an sRGB EOTF. -
VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXTspecifies support for the Display-P3 color space to be displayed using a linear EOTF. -
VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXTspecifies support for the DCI-P3 color space to be displayed using the DCI-P3 EOTF. Note that values in such an image are interpreted as XYZ encoded color data by the presentation engine. -
VK_COLOR_SPACE_BT709_LINEAR_EXTspecifies support for the BT709 color space to be displayed using a linear EOTF. -
VK_COLOR_SPACE_BT709_NONLINEAR_EXTspecifies support for the BT709 color space to be displayed using the SMPTE 170M EOTF. -
VK_COLOR_SPACE_BT2020_LINEAR_EXTspecifies support for the BT2020 color space to be displayed using a linear EOTF. -
VK_COLOR_SPACE_HDR10_ST2084_EXTspecifies support for the HDR10 (BT2020 color) space to be displayed using the SMPTE ST2084 Perceptual Quantizer (PQ) EOTF. -
VK_COLOR_SPACE_DOLBYVISION_EXTspecifies support for the Dolby Vision (BT2020 color space), proprietary encoding, to be displayed using the SMPTE ST2084 EOTF. -
VK_COLOR_SPACE_HDR10_HLG_EXTspecifies support for the HDR10 (BT2020 color space) to be displayed using the Hybrid Log Gamma (HLG) EOTF. -
VK_COLOR_SPACE_ADOBERGB_LINEAR_EXTspecifies support for the AdobeRGB color space to be displayed using a linear EOTF. -
VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXTspecifies support for the AdobeRGB color space to be displayed using the Gamma 2.2 EOTF. -
VK_COLOR_SPACE_PASS_THROUGH_EXTspecifies that color components are used “as is”. This is intended to allow applications to supply data for color spaces not described here. -
VK_COLOR_SPACE_DISPLAY_NATIVE_AMDspecifies support for the display’s native color space. This matches the color space expectations of AMD’s FreeSync2 standard, for displays supporting it.
|
Note
In the initial release of the |
|
Note
In older versions of this extension
|
|
Note
For a traditional "Linear" or non-gamma transfer function color space use
|
The color components of non-linear color space swap chain images must have had the appropriate transfer function applied. The color space selected for the swap chain image will not affect the processing of data written into the image by the implementation. Vulkan requires that all implementations support the sRGB transfer function by use of an SRGB pixel format. Other transfer functions, such as SMPTE 170M or SMPTE2084, can be performed by the application shader. This extension defines enums for VkColorSpaceKHR that correspond to the following color spaces:
| Name | Red Primary | Green Primary | Blue Primary | White-point | Transfer function |
|---|---|---|---|---|---|
DCI-P3 |
1.000, 0.000 |
0.000, 1.000 |
0.000, 0.000 |
0.3333, 0.3333 |
DCI P3 |
Display-P3 |
0.680, 0.320 |
0.265, 0.690 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
Display-P3 |
BT709 |
0.640, 0.330 |
0.300, 0.600 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
ITU (SMPTE 170M) |
sRGB |
0.640, 0.330 |
0.300, 0.600 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
sRGB |
extended sRGB |
0.640, 0.330 |
0.300, 0.600 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
extended sRGB |
HDR10_ST2084 |
0.708, 0.292 |
0.170, 0.797 |
0.131, 0.046 |
0.3127, 0.3290 (D65) |
ST2084 PQ |
DOLBYVISION |
0.708, 0.292 |
0.170, 0.797 |
0.131, 0.046 |
0.3127, 0.3290 (D65) |
ST2084 PQ |
HDR10_HLG |
0.708, 0.292 |
0.170, 0.797 |
0.131, 0.046 |
0.3127, 0.3290 (D65) |
HLG |
AdobeRGB |
0.640, 0.330 |
0.210, 0.710 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
AdobeRGB |
The transfer functions are described in the “Transfer Functions” chapter of the Khronos Data Format Specification.
Except Display-P3 OETF, which is:
where L is the linear value of a color component and E is the encoded value (as stored in the image in memory).
|
Note
For most uses, the sRGB OETF is equivalent. |
33.5.3. Surface Presentation Mode Support
To query the supported presentation modes for a surface, call:
// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfacePresentModesKHR(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
uint32_t* pPresentModeCount,
VkPresentModeKHR* pPresentModes);
-
physicalDeviceis the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
surfaceis the surface that will be associated with the swapchain. -
pPresentModeCountis a pointer to an integer related to the number of presentation modes available or queried, as described below. -
pPresentModesis eitherNULLor a pointer to an array of VkPresentModeKHR values, indicating the supported presentation modes.
If pPresentModes is NULL, then the number of presentation modes
supported for the given surface is returned in
pPresentModeCount.
Otherwise, pPresentModeCount must point to a variable set by the user
to the number of elements in the pPresentModes array, and on return
the variable is overwritten with the number of values actually written to
pPresentModes.
If the value of pPresentModeCount is less than the number of
presentation modes supported, at most pPresentModeCount values will be
written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available modes were
returned.
If the VK_GOOGLE_surfaceless_query extension is enabled, the values
returned in pPresentModes will be identical for every valid surface
created on this physical device, and so surface can be
VK_NULL_HANDLE.
Alternatively, to query the supported presentation modes for a surface combined with select other fixed swapchain creation parameters, call:
// Provided by VK_EXT_full_screen_exclusive
VkResult vkGetPhysicalDeviceSurfacePresentModes2EXT(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceSurfaceInfo2KHR* pSurfaceInfo,
uint32_t* pPresentModeCount,
VkPresentModeKHR* pPresentModes);
-
physicalDeviceis the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
pSurfaceInfois a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR. -
pPresentModeCountis a pointer to an integer related to the number of presentation modes available or queried, as described below. -
pPresentModesis eitherNULLor a pointer to an array of VkPresentModeKHR values, indicating the supported presentation modes.
vkGetPhysicalDeviceSurfacePresentModes2EXT behaves similarly to
vkGetPhysicalDeviceSurfacePresentModesKHR, with the ability to specify
extended inputs via chained input structures.
Possible values of elements of the
vkGetPhysicalDeviceSurfacePresentModesKHR::pPresentModes array,
indicating the supported presentation modes for a surface, are:
// Provided by VK_KHR_surface
typedef enum VkPresentModeKHR {
VK_PRESENT_MODE_IMMEDIATE_KHR = 0,
VK_PRESENT_MODE_MAILBOX_KHR = 1,
VK_PRESENT_MODE_FIFO_KHR = 2,
VK_PRESENT_MODE_FIFO_RELAXED_KHR = 3,
// Provided by VK_KHR_shared_presentable_image
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR = 1000111000,
// Provided by VK_KHR_shared_presentable_image
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR = 1000111001,
} VkPresentModeKHR;
-
VK_PRESENT_MODE_IMMEDIATE_KHRspecifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately. -
VK_PRESENT_MODE_MAILBOX_KHRspecifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for re-use by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty. -
VK_PRESENT_MODE_FIFO_KHRspecifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value ofpresentModethat is required to be supported. -
VK_PRESENT_MODE_FIFO_RELAXED_KHRspecifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty. -
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHRspecifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing. -
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHRspecifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.
The supported VkImageUsageFlagBits of the presentable images of a swapchain created for a surface may differ depending on the presentation mode, and can be determined as per the table below:
| Presentation mode | Image usage flags |
|---|---|
|
VkSurfaceCapabilitiesKHR:: |
|
VkSurfaceCapabilitiesKHR:: |
|
VkSurfaceCapabilitiesKHR:: |
|
VkSurfaceCapabilitiesKHR:: |
|
VkSharedPresentSurfaceCapabilitiesKHR:: |
|
VkSharedPresentSurfaceCapabilitiesKHR:: |
|
Note
For reference, the mode indicated by |
33.6. Full Screen Exclusive Control
Swapchains created with fullScreenExclusive set to
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT must acquire and
release exclusive full-screen access explicitly, using the following
commands.
To acquire exclusive full-screen access for a swapchain, call:
// Provided by VK_EXT_full_screen_exclusive
VkResult vkAcquireFullScreenExclusiveModeEXT(
VkDevice device,
VkSwapchainKHR swapchain);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to acquire exclusive full-screen access for.
A return value of VK_SUCCESS indicates that the swapchain
successfully acquired exclusive full-screen access.
The swapchain will retain this exclusivity until either the application
releases exclusive full-screen access with
vkReleaseFullScreenExclusiveModeEXT, destroys the swapchain, or if any
of the swapchain commands return
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT indicating that the mode
was lost because of platform-specific changes.
If the swapchain was unable to acquire exclusive full-screen access to the
display then VK_ERROR_INITIALIZATION_FAILED is returned.
An application can attempt to acquire exclusive full-screen access again
for the same swapchain even if this command fails, or if
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT has been returned by a
swapchain command.
To release exclusive full-screen access from a swapchain, call:
// Provided by VK_EXT_full_screen_exclusive
VkResult vkReleaseFullScreenExclusiveModeEXT(
VkDevice device,
VkSwapchainKHR swapchain);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to release exclusive full-screen access from.
|
Note
Applications will not be able to present to |
33.7. Device Group Queries
A logical device that represents multiple physical devices may support presenting from images on more than one physical device, or combining images from multiple physical devices.
To query these capabilities, call:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
VkResult vkGetDeviceGroupPresentCapabilitiesKHR(
VkDevice device,
VkDeviceGroupPresentCapabilitiesKHR* pDeviceGroupPresentCapabilities);
-
deviceis the logical device. -
pDeviceGroupPresentCapabilitiesis a pointer to a VkDeviceGroupPresentCapabilitiesKHR structure in which the device’s capabilities are returned.
The VkDeviceGroupPresentCapabilitiesKHR structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
typedef struct VkDeviceGroupPresentCapabilitiesKHR {
VkStructureType sType;
void* pNext;
uint32_t presentMask[VK_MAX_DEVICE_GROUP_SIZE];
VkDeviceGroupPresentModeFlagsKHR modes;
} VkDeviceGroupPresentCapabilitiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentMaskis an array ofVK_MAX_DEVICE_GROUP_SIZEuint32_tmasks, where the mask at element i is non-zero if physical device i has a presentation engine, and where bit j is set in element i if physical device i can present swapchain images from physical device j. If element i is non-zero, then bit i must be set. -
modesis a bitmask of VkDeviceGroupPresentModeFlagBitsKHR indicating which device group presentation modes are supported.
modes always has VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR set.
The present mode flags are also used when presenting an image, in
VkDeviceGroupPresentInfoKHR::mode.
If a device group only includes a single physical device, then modes
must equal VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.
Bits which may be set in
VkDeviceGroupPresentCapabilitiesKHR::modes, indicating which
device group presentation modes are supported, are:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
typedef enum VkDeviceGroupPresentModeFlagBitsKHR {
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR = 0x00000001,
VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR = 0x00000002,
VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR = 0x00000004,
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR = 0x00000008,
} VkDeviceGroupPresentModeFlagBitsKHR;
-
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHRspecifies that any physical device with a presentation engine can present its own swapchain images. -
VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHRspecifies that any physical device with a presentation engine can present swapchain images from any physical device in itspresentMask. -
VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHRspecifies that any physical device with a presentation engine can present the sum of swapchain images from any physical devices in itspresentMask. -
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHRspecifies that multiple physical devices with a presentation engine can each present their own swapchain images.
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
typedef VkFlags VkDeviceGroupPresentModeFlagsKHR;
VkDeviceGroupPresentModeFlagsKHR is a bitmask type for setting a mask
of zero or more VkDeviceGroupPresentModeFlagBitsKHR.
Some surfaces may not be capable of using all the device group present modes.
To query the supported device group present modes for a particular surface, call:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
VkResult vkGetDeviceGroupSurfacePresentModesKHR(
VkDevice device,
VkSurfaceKHR surface,
VkDeviceGroupPresentModeFlagsKHR* pModes);
-
deviceis the logical device. -
surfaceis the surface. -
pModesis a pointer to a VkDeviceGroupPresentModeFlagsKHR in which the supported device group present modes for the surface are returned.
The modes returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded. These modes must be a subset of the modes returned by vkGetDeviceGroupPresentCapabilitiesKHR.
Alternatively, to query the supported device group presentation modes for a surface combined with select other fixed swapchain creation parameters, call:
// Provided by VK_VERSION_1_1 with VK_EXT_full_screen_exclusive, VK_KHR_device_group with VK_EXT_full_screen_exclusive
VkResult vkGetDeviceGroupSurfacePresentModes2EXT(
VkDevice device,
const VkPhysicalDeviceSurfaceInfo2KHR* pSurfaceInfo,
VkDeviceGroupPresentModeFlagsKHR* pModes);
-
deviceis the logical device. -
pSurfaceInfois a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR. -
pModesis a pointer to a VkDeviceGroupPresentModeFlagsKHR in which the supported device group present modes for the surface are returned.
vkGetDeviceGroupSurfacePresentModes2EXT behaves similarly to
vkGetDeviceGroupSurfacePresentModesKHR, with the ability to specify
extended inputs via chained input structures.
When using VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR,
the application may need to know which regions of the surface are used when
presenting locally on each physical device.
Presentation of swapchain images to this surface need only have valid
contents in the regions returned by this command.
To query a set of rectangles used in presentation on the physical device, call:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
VkResult vkGetPhysicalDevicePresentRectanglesKHR(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
uint32_t* pRectCount,
VkRect2D* pRects);
-
physicalDeviceis the physical device. -
surfaceis the surface. -
pRectCountis a pointer to an integer related to the number of rectangles available or queried, as described below. -
pRectsis eitherNULLor a pointer to an array of VkRect2D structures.
If pRects is NULL, then the number of rectangles used when
presenting the given surface is returned in pRectCount.
Otherwise, pRectCount must point to a variable set by the user to the
number of elements in the pRects array, and on return the variable is
overwritten with the number of structures actually written to pRects.
If the value of pRectCount is less than the number of rectangles, at
most pRectCount structures will be written, and VK_INCOMPLETE
will be returned instead of VK_SUCCESS, to indicate that not all the
available rectangles were returned.
The values returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded.
The rectangles returned by this command must not overlap.
33.8. Display Timing Queries
Traditional game and real-time-animation applications frequently use
VK_PRESENT_MODE_FIFO_KHR so that presentable images are updated during
the vertical blanking period of a given refresh cycle (RC) of the
presentation engine’s display.
This avoids the visual anomaly known as tearing.
However, synchronizing the presentation of images with the RC does not prevent all forms of visual anomalies. Stuttering occurs when the geometry for each presentable image is not accurately positioned for when that image will be displayed. The geometry may appear to move too little some RCs, and too much for others. Sometimes the animation appears to freeze, when the same image is used for more than one RC.
In order to minimize stuttering, an application needs to correctly position
their geometry for when the presentable image will be displayed to the user.
To accomplish this, applications need various timing information about the
presentation engine’s display.
They need to know when presentable images were actually presented, and when
they could have been presented.
Applications also need to tell the presentation engine to display an image
no sooner than a given time.
This can allow the application’s animation to look smooth to the user, with
no stuttering.
The VK_GOOGLE_display_timing extension allows an application to satisfy
these needs.
The presentation engine’s display typically refreshes the pixels that are displayed to the user on a periodic basis. The period may be fixed or variable. In many cases, the presentation engine is associated with fixed refresh rate (FRR) display technology, with a fixed refresh rate (RR, e.g. 60Hz). In some cases, the presentation engine is associated with variable refresh rate (VRR) display technology, where each refresh cycle (RC) can vary in length. This extension treats VRR displays as if they are FRR.
To query the duration of a refresh cycle (RC) for the presentation engine’s display, call:
// Provided by VK_GOOGLE_display_timing
VkResult vkGetRefreshCycleDurationGOOGLE(
VkDevice device,
VkSwapchainKHR swapchain,
VkRefreshCycleDurationGOOGLE* pDisplayTimingProperties);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to obtain the refresh duration for. -
pDisplayTimingPropertiesis a pointer to aVkRefreshCycleDurationGOOGLEstructure.
The VkRefreshCycleDurationGOOGLE structure is defined as:
// Provided by VK_GOOGLE_display_timing
typedef struct VkRefreshCycleDurationGOOGLE {
uint64_t refreshDuration;
} VkRefreshCycleDurationGOOGLE;
-
refreshDurationis the number of nanoseconds from the start of one refresh cycle to the next.
|
Note
The rate at which an application renders and presents new images is known as
the image present rate (IPR, aka frame rate).
The inverse of IPR, or the duration between each image present, is the image
present duration (IPD).
In order to provide a smooth, stutter-free animation, an application will
want its IPD to be a multiple of In order to determine a target IPD for a display (i.e. a multiple of
Adjustments to an application’s IPD may be needed because different views of
an application’s geometry can take different amounts of time to render.
For example, looking at the sky may take less time to render than looking at
multiple, complex items in a room.
In general, it is good to not frequently change IPD, as that can cause
visual anomalies.
Adjustments to a larger IPD because of late images should happen quickly,
but adjustments to a smaller IPD should only happen if the
|
The implementation will maintain a limited amount of history of timing
information about previous presents.
Because of the asynchronous nature of the presentation engine, the timing
information for a given vkQueuePresentKHR command will become
available some time later.
These time values can be asynchronously queried, and will be returned if
available.
All time values are in nanoseconds, relative to a monotonically-increasing
clock (e.g. CLOCK_MONOTONIC (see clock_gettime(2)) on Android and Linux).
To asynchronously query the presentation engine, for newly-available timing information about one or more previous presents to a given swapchain, call:
// Provided by VK_GOOGLE_display_timing
VkResult vkGetPastPresentationTimingGOOGLE(
VkDevice device,
VkSwapchainKHR swapchain,
uint32_t* pPresentationTimingCount,
VkPastPresentationTimingGOOGLE* pPresentationTimings);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to obtain presentation timing information duration for. -
pPresentationTimingCountis a pointer to an integer related to the number ofVkPastPresentationTimingGOOGLEstructures to query, as described below. -
pPresentationTimingsis eitherNULLor a pointer to an array ofVkPastPresentationTimingGOOGLEstructures.
If pPresentationTimings is NULL, then the number of newly-available
timing records for the given swapchain is returned in
pPresentationTimingCount.
Otherwise, pPresentationTimingCount must point to a variable set by
the user to the number of elements in the pPresentationTimings array,
and on return the variable is overwritten with the number of structures
actually written to pPresentationTimings.
If the value of pPresentationTimingCount is less than the number of
newly-available timing records, at most pPresentationTimingCount
structures will be written, and VK_INCOMPLETE will be returned instead
of VK_SUCCESS, to indicate that not all the available timing records
were returned.
The VkPastPresentationTimingGOOGLE structure is defined as:
// Provided by VK_GOOGLE_display_timing
typedef struct VkPastPresentationTimingGOOGLE {
uint32_t presentID;
uint64_t desiredPresentTime;
uint64_t actualPresentTime;
uint64_t earliestPresentTime;
uint64_t presentMargin;
} VkPastPresentationTimingGOOGLE;
-
presentIDis an application-provided value that was given to a previousvkQueuePresentKHRcommand via VkPresentTimeGOOGLE::presentID(see below). It can be used to uniquely identify a previous present with the vkQueuePresentKHR command. -
desiredPresentTimeis an application-provided value that was given to a previous vkQueuePresentKHR command via VkPresentTimeGOOGLE::desiredPresentTime. If non-zero, it was used by the application to indicate that an image not be presented any sooner thandesiredPresentTime. -
actualPresentTimeis the time when the image of theswapchainwas actually displayed. -
earliestPresentTimeis the time when the image of theswapchaincould have been displayed. This may differ fromactualPresentTimeif the application requested that the image be presented no sooner than VkPresentTimeGOOGLE::desiredPresentTime. -
presentMarginis an indication of how early thevkQueuePresentKHRcommand was processed compared to how soon it needed to be processed, and still be presented atearliestPresentTime.
The results for a given swapchain and presentID are only
returned once from vkGetPastPresentationTimingGOOGLE.
The application can use the VkPastPresentationTimingGOOGLE values to
occasionally adjust its timing.
For example, if actualPresentTime is later than expected (e.g. one
refreshDuration late), the application may increase its target IPD to
a higher multiple of refreshDuration (e.g. decrease its frame rate
from 60Hz to 30Hz).
If actualPresentTime and earliestPresentTime are consistently
different, and if presentMargin is consistently large enough, the
application may decrease its target IPD to a smaller multiple of
refreshDuration (e.g. increase its frame rate from 30Hz to 60Hz).
If actualPresentTime and earliestPresentTime are same, and if
presentMargin is consistently high, the application may delay the
start of its input-render-present loop in order to decrease the latency
between user input and the corresponding present (always leaving some margin
in case a new image takes longer to render than the previous image).
An application that desires its target IPD to always be the same as
refreshDuration, can also adjust features until
actualPresentTime is never late and presentMargin is
satisfactory.
The full VK_GOOGLE_display_timing extension semantics are described
for swapchains created with VK_PRESENT_MODE_FIFO_KHR.
For example, non-zero values of
VkPresentTimeGOOGLE::desiredPresentTime must be honored, and
vkGetPastPresentationTimingGOOGLE should return a
VkPastPresentationTimingGOOGLE structure with valid values for all
images presented with vkQueuePresentKHR.
The semantics for other present modes are as follows:
-
VK_PRESENT_MODE_IMMEDIATE_KHR. The presentation engine may ignore non-zero values ofVkPresentTimeGOOGLE::desiredPresentTimein favor of presenting immediately. The value ofVkPastPresentationTimingGOOGLE::earliestPresentTimemust be the same asVkPastPresentationTimingGOOGLE::actualPresentTime, which should be when the presentation engine displayed the image. -
VK_PRESENT_MODE_MAILBOX_KHR. The intention of using this present mode with this extension is to handle cases where an image is presented late, and the next image is presented soon enough to replace it at the next vertical blanking period. For images that are displayed to the user, the value ofVkPastPresentationTimingGOOGLE::actualPresentTimemust be when the image was displayed. For images that are not displayed to the user,vkGetPastPresentationTimingGOOGLEmay not return aVkPastPresentationTimingGOOGLEstructure, or it may return aVkPastPresentationTimingGOOGLEstructure with the value of zero for bothVkPastPresentationTimingGOOGLE::actualPresentTimeandVkPastPresentationTimingGOOGLE::earliestPresentTime. It is possible that an application can submit images withVkPresentTimeGOOGLE::desiredPresentTimevalues such that new images may not be displayed. For example, ifVkPresentTimeGOOGLE::desiredPresentTimeis far enough in the future that an image is not presented beforevkQueuePresentKHRis called to present another image, the first image will not be displayed to the user. If the application continues to do that, the presentation may not display new images. -
VK_PRESENT_MODE_FIFO_RELAXED_KHR. For images that are presented in time to be displayed at the next vertical blanking period, the semantics are identical as forVK_PRESENT_MODE_FIFO_RELAXED_KHR. For images that are presented late, and are displayed after the start of the vertical blanking period (i.e. with tearing), the values ofVkPastPresentationTimingGOOGLEmay be treated as if the image was displayed at the start of the vertical blanking period, or may be treated the same as forVK_PRESENT_MODE_IMMEDIATE_KHR.
33.9. Present Wait
Applications wanting to control the pacing of the application by monitoring when presentation processes have completed to limit the number of outstanding images queued for presentation, need to have a method of being signaled during the presentation process.
Using
the VK_GOOGLE_display_timing extension
applications can discover when images were presented, but only
asynchronously.
Providing a mechanism which allows applications to block, waiting for a specific step of the presentation process to complete allows them to control the amount of outstanding work (and hence the potential lag in responding to user input or changes in the rendering environment).
The VK_KHR_present_wait extension allows applications to tell the
presentation engine at the vkQueuePresentKHR call that it plans on
waiting for presentation by passing a VkPresentIdKHR structure.
The presentId passed in that structure may then be passed to a future
vkWaitForPresentKHR call to cause the application to block until that
presentation is finished.
33.10. WSI Swapchain
A swapchain object (a.k.a.
swapchain) provides the ability to present rendering results to a surface.
Swapchain objects are represented by VkSwapchainKHR handles:
// Provided by VK_KHR_swapchain
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSwapchainKHR)
A swapchain is an abstraction for an array of presentable images that are
associated with a surface.
The presentable images are represented by VkImage objects created by
the platform.
One image (which can be an array image for multiview/stereoscopic-3D
surfaces) is displayed at a time, but multiple images can be queued for
presentation.
An application renders to the image, and then queues the image for
presentation to the surface.
A native window cannot be associated with more than one non-retired swapchain at a time. Further, swapchains cannot be created for native windows that have a non-Vulkan graphics API surface associated with them.
|
Note
The presentation engine is an abstraction for the platform’s compositor or display engine. The presentation engine may be synchronous or asynchronous with respect to the application and/or logical device. Some implementations may use the device’s graphics queue or dedicated presentation hardware to perform presentation. |
The presentable images of a swapchain are owned by the presentation engine.
An application can acquire use of a presentable image from the presentation
engine.
Use of a presentable image must occur only after the image is returned by
vkAcquireNextImageKHR, and before it is released by
vkQueuePresentKHR.
This includes transitioning the image layout and rendering commands.
An application can acquire use of a presentable image with
vkAcquireNextImageKHR.
After acquiring a presentable image and before modifying it, the application
must use a synchronization primitive to ensure that the presentation engine
has finished reading from the image.
The application can then transition the image’s layout, queue rendering
commands to it, etc.
Finally, the application presents the image with vkQueuePresentKHR,
which releases the acquisition of the image.
The presentation engine controls the order in which presentable images are acquired for use by the application.
|
Note
This allows the platform to handle situations which require out-of-order return of images after presentation. At the same time, it allows the application to generate command buffers referencing all of the images in the swapchain at initialization time, rather than in its main loop. |
How this all works is described below.
If a swapchain is created with presentMode set to either
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, a single presentable
image can be acquired, referred to as a shared presentable image.
A shared presentable image may be concurrently accessed by the application
and the presentation engine, without transitioning the image’s layout after
it is initially presented.
-
With
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR, the presentation engine is only required to update to the latest contents of a shared presentable image after a present. The application must callvkQueuePresentKHRto guarantee an update. However, the presentation engine may update from it at any time. -
With
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, the presentation engine will automatically present the latest contents of a shared presentable image during every refresh cycle. The application is only required to make one initial call tovkQueuePresentKHR, after which the presentation engine will update from it without any need for further present calls. The application can indicate the image contents have been updated by callingvkQueuePresentKHR, but this does not guarantee the timing of when updates will occur.
The presentation engine may access a shared presentable image at any time after it is first presented. To avoid tearing, an application should coordinate access with the presentation engine. This requires presentation engine timing information through platform-specific mechanisms and ensuring that color attachment writes are made available during the portion of the presentation engine’s refresh cycle they are intended for.
|
Note
The |
In order to query a swapchain’s status when rendering to a shared presentable image, call:
// Provided by VK_KHR_shared_presentable_image
VkResult vkGetSwapchainStatusKHR(
VkDevice device,
VkSwapchainKHR swapchain);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to query.
The possible return values for vkGetSwapchainStatusKHR should be
interpreted as follows:
-
VK_SUCCESSspecifies the presentation engine is presenting the contents of the shared presentable image, as per the swapchain’s VkPresentModeKHR. -
VK_SUBOPTIMAL_KHRthe swapchain no longer matches the surface properties exactly, but the presentation engine is presenting the contents of the shared presentable image, as per the swapchain’s VkPresentModeKHR. -
VK_ERROR_OUT_OF_DATE_KHRthe surface has changed in such a way that it is no longer compatible with the swapchain. -
VK_ERROR_SURFACE_LOST_KHRthe surface is no longer available.
|
Note
The swapchain state may be cached by implementations, so applications
should regularly call |
To create a swapchain, call:
// Provided by VK_KHR_swapchain
VkResult vkCreateSwapchainKHR(
VkDevice device,
const VkSwapchainCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSwapchainKHR* pSwapchain);
-
deviceis the device to create the swapchain for. -
pCreateInfois a pointer to a VkSwapchainCreateInfoKHR structure specifying the parameters of the created swapchain. -
pAllocatoris the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation). -
pSwapchainis a pointer to a VkSwapchainKHR handle in which the created swapchain object will be returned.
As mentioned above, if vkCreateSwapchainKHR succeeds, it will return a
handle to a swapchain containing an array of at least
pCreateInfo->minImageCount presentable images.
While acquired by the application, presentable images can be used in any way that equivalent non-presentable images can be used. A presentable image is equivalent to a non-presentable image created with the following VkImageCreateInfo parameters:
VkImageCreateInfo Field |
Value |
|---|---|
|
all other bits are unset |
|
|
|
|
|
{ |
|
1 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The pCreateInfo->surface must not be destroyed until after the
swapchain is destroyed.
If pCreateInfo->oldSwapchain is VK_NULL_HANDLE, and the native
window referred to by pCreateInfo->surface is already associated with
a Vulkan swapchain, VK_ERROR_NATIVE_WINDOW_IN_USE_KHR must be
returned.
If the native window referred to by pCreateInfo->surface is already
associated with a non-Vulkan graphics API surface,
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR must be returned.
The native window referred to by pCreateInfo->surface must not become
associated with a non-Vulkan graphics API surface before all associated
Vulkan swapchains have been destroyed.
vkCreateSwapchainKHR will return VK_ERROR_DEVICE_LOST if the
logical device was lost.
The VkSwapchainKHR is a child of the device, and must be
destroyed before the device.
However, VkSurfaceKHR is not a child of any VkDevice and is not
affected by the lost device.
After successfully recreating a VkDevice, the same VkSurfaceKHR
can be used to create a new VkSwapchainKHR, provided the previous one
was destroyed.
If the oldSwapchain parameter of pCreateInfo is a valid
swapchain, which has exclusive full-screen access, that access is released
from pCreateInfo->oldSwapchain.
If the command succeeds in this case, the newly created swapchain will
automatically acquire exclusive full-screen access from
pCreateInfo->oldSwapchain.
|
Note
This implicit transfer is intended to avoid exiting and entering full-screen exclusive mode, which may otherwise cause unwanted visual updates to the display. |
In some cases, swapchain creation may fail if exclusive full-screen mode is
requested for application control, but for some implementation-specific
reason exclusive full-screen access is unavailable for the particular
combination of parameters provided.
If this occurs, VK_ERROR_INITIALIZATION_FAILED will be returned.
|
Note
In particular, it will fail if the |
When the VkSurfaceKHR in VkSwapchainCreateInfoKHR is a display
surface, then the VkDisplayModeKHR in display surface’s
VkDisplaySurfaceCreateInfoKHR is associated with a particular
VkDisplayKHR.
Swapchain creation may fail if that VkDisplayKHR is not acquired by
the application.
In this scenario VK_ERROR_INITIALIZATION_FAILED is returned.
The VkSwapchainCreateInfoKHR structure is defined as:
// Provided by VK_KHR_swapchain
typedef struct VkSwapchainCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkSwapchainCreateFlagsKHR flags;
VkSurfaceKHR surface;
uint32_t minImageCount;
VkFormat imageFormat;
VkColorSpaceKHR imageColorSpace;
VkExtent2D imageExtent;
uint32_t imageArrayLayers;
VkImageUsageFlags imageUsage;
VkSharingMode imageSharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
VkSurfaceTransformFlagBitsKHR preTransform;
VkCompositeAlphaFlagBitsKHR compositeAlpha;
VkPresentModeKHR presentMode;
VkBool32 clipped;
VkSwapchainKHR oldSwapchain;
} VkSwapchainCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkSwapchainCreateFlagBitsKHR indicating parameters of the swapchain creation. -
surfaceis the surface onto which the swapchain will present images. If the creation succeeds, the swapchain becomes associated withsurface. -
minImageCountis the minimum number of presentable images that the application needs. The implementation will either create the swapchain with at least that many images, or it will fail to create the swapchain. -
imageFormatis a VkFormat value specifying the format the swapchain image(s) will be created with. -
imageColorSpaceis a VkColorSpaceKHR value specifying the way the swapchain interprets image data. -
imageExtentis the size (in pixels) of the swapchain image(s). The behavior is platform-dependent if the image extent does not match the surface’scurrentExtentas returned byvkGetPhysicalDeviceSurfaceCapabilitiesKHR.NoteOn some platforms, it is normal that
maxImageExtentmay become(0, 0), for example when the window is minimized. In such a case, it is not possible to create a swapchain due to the Valid Usage requirements. -
imageArrayLayersis the number of views in a multiview/stereo surface. For non-stereoscopic-3D applications, this value is 1. -
imageUsageis a bitmask of VkImageUsageFlagBits describing the intended usage of the (acquired) swapchain images. -
imageSharingModeis the sharing mode used for the image(s) of the swapchain. -
queueFamilyIndexCountis the number of queue families having access to the image(s) of the swapchain whenimageSharingModeisVK_SHARING_MODE_CONCURRENT. -
pQueueFamilyIndicesis a pointer to an array of queue family indices having access to the images(s) of the swapchain whenimageSharingModeisVK_SHARING_MODE_CONCURRENT. -
preTransformis a VkSurfaceTransformFlagBitsKHR value describing the transform, relative to the presentation engine’s natural orientation, applied to the image content prior to presentation. If it does not match thecurrentTransformvalue returned byvkGetPhysicalDeviceSurfaceCapabilitiesKHR, the presentation engine will transform the image content as part of the presentation operation. -
compositeAlphais a VkCompositeAlphaFlagBitsKHR value indicating the alpha compositing mode to use when this surface is composited together with other surfaces on certain window systems. -
presentModeis the presentation mode the swapchain will use. A swapchain’s present mode determines how incoming present requests will be processed and queued internally. -
clippedspecifies whether the Vulkan implementation is allowed to discard rendering operations that affect regions of the surface that are not visible.-
If set to
VK_TRUE, the presentable images associated with the swapchain may not own all of their pixels. Pixels in the presentable images that correspond to regions of the target surface obscured by another window on the desktop, or subject to some other clipping mechanism will have undefined content when read back. Fragment shaders may not execute for these pixels, and thus any side effects they would have had will not occur. SettingVK_TRUEdoes not guarantee any clipping will occur, but allows more efficient presentation methods to be used on some platforms. -
If set to
VK_FALSE, presentable images associated with the swapchain will own all of the pixels they contain.NoteApplications should set this value to
VK_TRUEif they do not expect to read back the content of presentable images before presenting them or after reacquiring them, and if their fragment shaders do not have any side effects that require them to run for all pixels in the presentable image.
-
-
oldSwapchainis VK_NULL_HANDLE, or the existing non-retired swapchain currently associated withsurface. Providing a validoldSwapchainmay aid in the resource reuse, and also allows the application to still present any images that are already acquired from it.
Upon calling vkCreateSwapchainKHR with an oldSwapchain that is
not VK_NULL_HANDLE, oldSwapchain is retired — even if creation
of the new swapchain fails.
The new swapchain is created in the non-retired state whether or not
oldSwapchain is VK_NULL_HANDLE.
Upon calling vkCreateSwapchainKHR with an oldSwapchain that is
not VK_NULL_HANDLE, any images from oldSwapchain that are not
acquired by the application may be freed by the implementation, which may
occur even if creation of the new swapchain fails.
The application can destroy oldSwapchain to free all memory
associated with oldSwapchain.
|
Note
Multiple retired swapchains can be associated with the same
After The application can continue to use a shared presentable image obtained
from |
Bits which can be set in VkSwapchainCreateInfoKHR::flags,
specifying parameters of swapchain creation, are:
// Provided by VK_KHR_swapchain
typedef enum VkSwapchainCreateFlagBitsKHR {
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR = 0x00000001,
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR = 0x00000002,
// Provided by VK_KHR_swapchain_mutable_format
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR = 0x00000004,
} VkSwapchainCreateFlagBitsKHR;
-
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHRspecifies that images created from the swapchain (i.e. with theswapchainmember of VkImageSwapchainCreateInfoKHR set to this swapchain’s handle) must useVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT. -
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHRspecifies that images created from the swapchain are protected images. -
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHRspecifies that the images of the swapchain can be used to create aVkImageViewwith a different format than what the swapchain was created with. The list of allowed image view formats is specified by adding a VkImageFormatListCreateInfo structure to thepNextchain of VkSwapchainCreateInfoKHR. In addition, this flag also specifies that the swapchain can be created with usage flags that are not supported for the format the swapchain is created with but are supported for at least one of the allowed image view formats.
// Provided by VK_KHR_swapchain
typedef VkFlags VkSwapchainCreateFlagsKHR;
VkSwapchainCreateFlagsKHR is a bitmask type for setting a mask of zero
or more VkSwapchainCreateFlagBitsKHR.
If the pNext chain of VkSwapchainCreateInfoKHR includes a
VkDeviceGroupSwapchainCreateInfoKHR structure, then that structure
includes a set of device group present modes that the swapchain can be used
with.
The VkDeviceGroupSwapchainCreateInfoKHR structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkDeviceGroupSwapchainCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkDeviceGroupPresentModeFlagsKHR modes;
} VkDeviceGroupSwapchainCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
modesis a bitfield of modes that the swapchain can be used with.
If this structure is not present, modes is considered to be
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.
If the pNext chain of VkSwapchainCreateInfoKHR includes a
VkSwapchainDisplayNativeHdrCreateInfoAMD structure, then that
structure includes additional swapchain creation parameters specific to
display native HDR support.
The VkSwapchainDisplayNativeHdrCreateInfoAMD structure is defined as:
// Provided by VK_AMD_display_native_hdr
typedef struct VkSwapchainDisplayNativeHdrCreateInfoAMD {
VkStructureType sType;
const void* pNext;
VkBool32 localDimmingEnable;
} VkSwapchainDisplayNativeHdrCreateInfoAMD;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
localDimmingEnablespecifies whether local dimming is enabled for the swapchain.
If the pNext chain of VkSwapchainCreateInfoKHR does not include
this structure, the default value for localDimmingEnable is
VK_TRUE, meaning local dimming is initially enabled for the swapchain.
The local dimming HDR setting may also be changed over the life of a swapchain by calling:
// Provided by VK_AMD_display_native_hdr
void vkSetLocalDimmingAMD(
VkDevice device,
VkSwapchainKHR swapChain,
VkBool32 localDimmingEnable);
-
deviceis the device associated withswapChain. -
swapChainhandle to enable local dimming. -
localDimmingEnablespecifies whether local dimming is enabled for the swapchain.
If the pNext chain of VkSwapchainCreateInfoKHR includes a
VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure
specifies the application’s preferred full-screen presentation behavior.
If this structure is not present, fullScreenExclusive is considered to
be VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT.
To enable surface counters when creating a swapchain, add a
VkSwapchainCounterCreateInfoEXT structure to the pNext chain of
VkSwapchainCreateInfoKHR.
VkSwapchainCounterCreateInfoEXT is defined as:
// Provided by VK_EXT_display_control
typedef struct VkSwapchainCounterCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkSurfaceCounterFlagsEXT surfaceCounters;
} VkSwapchainCounterCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
surfaceCountersis a bitmask of VkSurfaceCounterFlagBitsEXT specifying surface counters to enable for the swapchain.
The requested counters become active when the first presentation command for the associated swapchain is processed by the presentation engine. To query the value of an active counter, use:
// Provided by VK_EXT_display_control
VkResult vkGetSwapchainCounterEXT(
VkDevice device,
VkSwapchainKHR swapchain,
VkSurfaceCounterFlagBitsEXT counter,
uint64_t* pCounterValue);
-
deviceis the VkDevice associated withswapchain. -
swapchainis the swapchain from which to query the counter value. -
counteris a VkSurfaceCounterFlagBitsEXT value specifying the counter to query. -
pCounterValuewill return the current value of the counter.
If a counter is not available because the swapchain is out of date, the
implementation may return VK_ERROR_OUT_OF_DATE_KHR.
To specify compression properties for the swapchain images in this
swapchain, add a VkImageCompressionControlEXT structure to the
pNext chain of the VkSwapchainCreateInfoKHR structure.
To destroy a swapchain object call:
// Provided by VK_KHR_swapchain
void vkDestroySwapchainKHR(
VkDevice device,
VkSwapchainKHR swapchain,
const VkAllocationCallbacks* pAllocator);
-
deviceis the VkDevice associated withswapchain. -
swapchainis the swapchain to destroy. -
pAllocatoris the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation).
The application must not destroy a swapchain until after completion of all
outstanding operations on images that were acquired from the swapchain.
swapchain and all associated VkImage handles are destroyed, and
must not be acquired or used any more by the application.
The memory of each VkImage will only be freed after that image is no
longer used by the presentation engine.
For example, if one image of the swapchain is being displayed in a window,
the memory for that image may not be freed until the window is destroyed,
or another swapchain is created for the window.
Destroying the swapchain does not invalidate the parent VkSurfaceKHR,
and a new swapchain can be created with it.
When a swapchain associated with a display surface is destroyed, if the image most recently presented to the display surface is from the swapchain being destroyed, then either any display resources modified by presenting images from any swapchain associated with the display surface must be reverted by the implementation to their state prior to the first present performed on one of these swapchains, or such resources must be left in their current state.
If swapchain has exclusive full-screen access, it is released before
the swapchain is destroyed.
To obtain the array of presentable images associated with a swapchain, call:
// Provided by VK_KHR_swapchain
VkResult vkGetSwapchainImagesKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint32_t* pSwapchainImageCount,
VkImage* pSwapchainImages);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to query. -
pSwapchainImageCountis a pointer to an integer related to the number of presentable images available or queried, as described below. -
pSwapchainImagesis eitherNULLor a pointer to an array ofVkImagehandles.
If pSwapchainImages is NULL, then the number of presentable images
for swapchain is returned in pSwapchainImageCount.
Otherwise, pSwapchainImageCount must point to a variable set by the
user to the number of elements in the pSwapchainImages array, and on
return the variable is overwritten with the number of structures actually
written to pSwapchainImages.
If the value of pSwapchainImageCount is less than the number of
presentable images for swapchain, at most pSwapchainImageCount
structures will be written, and VK_INCOMPLETE will be returned instead
of VK_SUCCESS, to indicate that not all the available presentable
images were returned.
|
Note
By knowing all presentable images used in the swapchain, the application can create command buffers that reference these images prior to entering its main rendering loop. |
Images returned by vkGetSwapchainImagesKHR are fully backed by memory
before they are passed to the application.
All presentable images are initially in the VK_IMAGE_LAYOUT_UNDEFINED
layout, thus before using presentable images, the application must
transition them to a valid layout for the intended use.
Further, the lifetime of presentable images is controlled by the implementation, so applications must not destroy a presentable image. See vkDestroySwapchainKHR for further details on the lifetime of presentable images.
Images can also be created by using vkCreateImage with
VkImageSwapchainCreateInfoKHR and bound to swapchain memory using
vkBindImageMemory2 with VkBindImageMemorySwapchainInfoKHR.
These images can be used anywhere swapchain images are used, and are useful
in logical devices with multiple physical devices to create peer memory
bindings of swapchain memory.
These images and bindings have no effect on what memory is presented.
Unlike images retrieved from vkGetSwapchainImagesKHR, these images
must be destroyed with vkDestroyImage.
To acquire an available presentable image to use, and retrieve the index of that image, call:
// Provided by VK_KHR_swapchain
VkResult vkAcquireNextImageKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint64_t timeout,
VkSemaphore semaphore,
VkFence fence,
uint32_t* pImageIndex);
-
deviceis the device associated withswapchain. -
swapchainis the non-retired swapchain from which an image is being acquired. -
timeoutspecifies how long the function waits, in nanoseconds, if no image is available. -
semaphoreis VK_NULL_HANDLE or a semaphore to signal. -
fenceis VK_NULL_HANDLE or a fence to signal. -
pImageIndexis a pointer to auint32_tin which the index of the next image to use (i.e. an index into the array of images returned byvkGetSwapchainImagesKHR) is returned.
When successful, vkAcquireNextImageKHR acquires a presentable image
from swapchain that an application can use, and sets
pImageIndex to the index of that image within the swapchain.
The presentation engine may not have finished reading from the image at the
time it is acquired, so the application must use semaphore and/or
fence to ensure that the image layout and contents are not modified
until the presentation engine reads have completed.
If semaphore is not VK_NULL_HANDLE, the application may assume
that, once vkAcquireNextImageKHR returns, the semaphore signal
operation referenced by semaphore has been submitted for execution.
The order in which images are acquired is implementation-dependent, and may
be different than the order the images were presented.
If timeout is zero, then vkAcquireNextImageKHR does not wait,
and will either successfully acquire an image, or fail and return
VK_NOT_READY if no image is available.
If the specified timeout period expires before an image is acquired,
vkAcquireNextImageKHR returns VK_TIMEOUT.
If timeout is UINT64_MAX, the timeout period is treated as
infinite, and vkAcquireNextImageKHR will block until an image is
acquired or an error occurs.
vkAcquireNextImageKHR should not be called if the number of images
that the application has currently acquired is greater than the difference
between the number of images in swapchain and the value of
VkSurfaceCapabilitiesKHR::minImageCount.
If vkAcquireNextImageKHR is called when the number of images that the
application has currently acquired is less or equal than the difference
between the number of images in swapchain and the value of
VkSurfaceCapabilitiesKHR::minImageCount,
vkAcquireNextImageKHR must return in finite time with an allowed
VkResult code.
|
Note
Returning a result in finite time guarantees that the implementation cannot
deadlock an application, or suspend its execution indefinitely with correct
API usage.
Acquiring too many images at once may block indefinitely, which is covered
by valid usage when attempting to use |
If an image is acquired successfully, vkAcquireNextImageKHR must
either return VK_SUCCESS or VK_SUBOPTIMAL_KHR.
The implementation may return VK_SUBOPTIMAL_KHR if the swapchain no
longer matches the surface properties exactly, but can still be used for
presentation.
|
Note
|
If the swapchain images no longer match native surface properties, either
VK_SUBOPTIMAL_KHR or VK_ERROR_OUT_OF_DATE_KHR must be returned.
If VK_ERROR_OUT_OF_DATE_KHR is returned, no image is acquired and
attempts to present previously acquired images to the swapchain will also
fail with VK_ERROR_OUT_OF_DATE_KHR.
Applications need to create a new swapchain for the surface to continue
presenting if VK_ERROR_OUT_OF_DATE_KHR is returned.
If device loss occurs (see Lost Device) before
the timeout has expired, vkAcquireNextImageKHR must return in finite
time with either one of the allowed success codes, or
VK_ERROR_DEVICE_LOST.
If semaphore is not VK_NULL_HANDLE, the semaphore must be
unsignaled, with no signal or wait operations pending.
It will become signaled when the application can use the image.
|
Note
Use of |
If fence is not equal to VK_NULL_HANDLE, the fence must be
unsignaled, with no signal operations pending.
It will become signaled when the application can use the image.
|
Note
Applications should not rely on |
An application must wait until either the semaphore or fence is
signaled before accessing the image’s data.
|
Note
When the presentable image will be accessed by some stage S, the recommended idiom for ensuring correct synchronization is:
|
After a successful return, the image indicated by pImageIndex and its
data will be unmodified compared to when it was presented.
|
Note
Exclusive ownership of presentable images corresponding to a swapchain
created with |
The possible return values for vkAcquireNextImageKHR depend on the
timeout provided:
-
VK_SUCCESSis returned if an image became available. -
VK_ERROR_SURFACE_LOST_KHRis returned if the surface becomes no longer available. -
VK_NOT_READYis returned iftimeoutis zero and no image was available. -
VK_TIMEOUTis returned iftimeoutis greater than zero and less thanUINT64_MAX, and no image became available within the time allowed. -
VK_SUBOPTIMAL_KHRis returned if an image became available, and the swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.
|
Note
This may happen, for example, if the platform surface has been resized but the platform is able to scale the presented images to the new size to produce valid surface updates. It is up to the application to decide whether it prefers to continue using the current swapchain indefinitely or temporarily in this state, or to re-create the swapchain to better match the platform surface properties. |
-
VK_ERROR_OUT_OF_DATE_KHRis returned if the 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.
If the native surface and presented image sizes no longer match,
presentation may fail.
If presentation does succeed, the mapping from the presented image to the
native surface is implementation-defined.
It is the application’s responsibility to detect surface size changes and
react appropriately.
If presentation fails because of a mismatch in the surface and presented
image sizes, a VK_ERROR_OUT_OF_DATE_KHR error will be returned.
|
Note
For example, consider a 4x3 window/surface that gets resized to be 3x4 (taller than wider). On some window systems, the portion of the window/surface that was previously and still is visible (the 3x3 part) will contain the same contents as before, while the remaining parts of the window will have undefined contents. Other window systems may squash/stretch the image to fill the new window size without any undefined contents, or apply some other mapping. |
To acquire an available presentable image to use, and retrieve the index of that image, call:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VkResult vkAcquireNextImage2KHR(
VkDevice device,
const VkAcquireNextImageInfoKHR* pAcquireInfo,
uint32_t* pImageIndex);
-
deviceis the device associated withswapchain. -
pAcquireInfois a pointer to a VkAcquireNextImageInfoKHR structure containing parameters of the acquire. -
pImageIndexis a pointer to auint32_tthat is set to the index of the next image to use.
The VkAcquireNextImageInfoKHR structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkAcquireNextImageInfoKHR {
VkStructureType sType;
const void* pNext;
VkSwapchainKHR swapchain;
uint64_t timeout;
VkSemaphore semaphore;
VkFence fence;
uint32_t deviceMask;
} VkAcquireNextImageInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainis a non-retired swapchain from which an image is acquired. -
timeoutspecifies how long the function waits, in nanoseconds, if no image is available. -
semaphoreis VK_NULL_HANDLE or a semaphore to signal. -
fenceis VK_NULL_HANDLE or a fence to signal. -
deviceMaskis a mask of physical devices for which the swapchain image will be ready to use when the semaphore or fence is signaled.
If vkAcquireNextImageKHR is used, the device mask is considered to include all physical devices in the logical device.
|
Note
vkAcquireNextImage2KHR signals at most one semaphore, even if the
application requests waiting for multiple physical devices to be ready via
the |
After queueing all rendering commands and transitioning the image to the correct layout, to queue an image for presentation, call:
// Provided by VK_KHR_swapchain
VkResult vkQueuePresentKHR(
VkQueue queue,
const VkPresentInfoKHR* pPresentInfo);
-
queueis a queue that is capable of presentation to the target surface’s platform on the same device as the image’s swapchain. -
pPresentInfois a pointer to a VkPresentInfoKHR structure specifying parameters of the presentation.
|
Note
There is no requirement for an application to present images in the same order that they were acquired - applications can arbitrarily present any image that is currently acquired. |
Any writes to memory backing the images referenced by the
pImageIndices and pSwapchains members of pPresentInfo,
that are available before vkQueuePresentKHR is executed, are
automatically made visible to the read access performed by the presentation
engine.
This automatic visibility operation for an image happens-after the semaphore
signal operation, and happens-before the presentation engine accesses the
image.
Queueing an image for presentation defines a set of queue operations, including waiting on the semaphores and submitting a presentation request to the presentation engine. However, the scope of this set of queue operations does not include the actual processing of the image by the presentation engine.
|
Note
The origin of the native orientation of the surface coordinate system is not
specified in the Vulkan specification; it depends on the platform.
For most platforms the origin is by default upper-left, meaning the pixel of
the presented VkImage at coordinates (0,0) would appear at the
upper left pixel of the platform surface (assuming
|
If vkQueuePresentKHR fails to enqueue the corresponding set of queue
operations, 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 is unaffected by the
call or its failure.
If vkQueuePresentKHR fails in such a way that the implementation is
unable to make that guarantee, the implementation must return
VK_ERROR_DEVICE_LOST.
However, if the presentation request is rejected by the presentation engine
with an error VK_ERROR_OUT_OF_DATE_KHR,
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT,
or VK_ERROR_SURFACE_LOST_KHR, the set of queue operations are still
considered to be enqueued and thus any semaphore wait operation specified in
VkPresentInfoKHR will execute when the corresponding queue operation
is complete.
Calls to vkQueuePresentKHR may block, but must return in finite
time.
If any swapchain member of pPresentInfo was created with
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT,
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT will be returned if that
swapchain does not have exclusive full-screen access, possibly for
implementation-specific reasons outside of the application’s control.
The VkPresentInfoKHR structure is defined as:
// Provided by VK_KHR_swapchain
typedef struct VkPresentInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t waitSemaphoreCount;
const VkSemaphore* pWaitSemaphores;
uint32_t swapchainCount;
const VkSwapchainKHR* pSwapchains;
const uint32_t* pImageIndices;
VkResult* pResults;
} VkPresentInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
waitSemaphoreCountis the number of semaphores to wait for before issuing the present request. The number may be zero. -
pWaitSemaphoresisNULLor a pointer to an array of VkSemaphore objects withwaitSemaphoreCountentries, and specifies the semaphores to wait for before issuing the present request. -
swapchainCountis the number of swapchains being presented to by this command. -
pSwapchainsis a pointer to an array of VkSwapchainKHR objects withswapchainCountentries. A given swapchain must not appear in this list more than once. -
pImageIndicesis a pointer to an array of indices into the array of each swapchain’s presentable images, withswapchainCountentries. Each entry in this array identifies the image to present on the corresponding entry in thepSwapchainsarray. -
pResultsis a pointer to an array of VkResult typed elements withswapchainCountentries. Applications that do not need per-swapchain results can useNULLforpResults. If non-NULL, each entry inpResultswill be set to the VkResult for presenting the swapchain corresponding to the same index inpSwapchains.
Before an application can present an image, the image’s layout must be
transitioned to the VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
layout, or for a shared presentable image the
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
layout.
|
Note
When transitioning the image to
|
When the VK_KHR_incremental_present extension is enabled, additional
fields can be specified that allow an application to specify that only
certain rectangular regions of the presentable images of a swapchain are
changed.
This is an optimization hint that a presentation engine may use to only
update the region of a surface that is actually changing.
The application still must ensure that all pixels of a presented image
contain the desired values, in case the presentation engine ignores this
hint.
An application can provide this hint by adding a VkPresentRegionsKHR
structure to the pNext chain of the VkPresentInfoKHR structure.
The VkPresentRegionsKHR structure is defined as:
// Provided by VK_KHR_incremental_present
typedef struct VkPresentRegionsKHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const VkPresentRegionKHR* pRegions;
} VkPresentRegionsKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainCountis the number of swapchains being presented to by this command. -
pRegionsisNULLor a pointer to an array ofVkPresentRegionKHRelements withswapchainCountentries. If notNULL, each element ofpRegionscontains the region that has changed since the last present to the swapchain in the corresponding entry in theVkPresentInfoKHR::pSwapchainsarray.
For a given image and swapchain, the region to present is specified by the
VkPresentRegionKHR structure, which is defined as:
// Provided by VK_KHR_incremental_present
typedef struct VkPresentRegionKHR {
uint32_t rectangleCount;
const VkRectLayerKHR* pRectangles;
} VkPresentRegionKHR;
-
rectangleCountis the number of rectangles inpRectangles, or zero if the entire image has changed and should be presented. -
pRectanglesis eitherNULLor a pointer to an array ofVkRectLayerKHRstructures. TheVkRectLayerKHRstructure is the framebuffer coordinates, plus layer, of a portion of a presentable image that has changed and must be presented. If non-NULL, each entry inpRectanglesis a rectangle of the given image that has changed since the last image was presented to the given swapchain. The rectangles must be specified relative to VkSurfaceCapabilitiesKHR::currentTransform, regardless of the swapchain’spreTransform. The presentation engine will apply thepreTransformtransformation to the rectangles, along with any further transformation it applies to the image content.
The VkRectLayerKHR structure is defined as:
// Provided by VK_KHR_incremental_present
typedef struct VkRectLayerKHR {
VkOffset2D offset;
VkExtent2D extent;
uint32_t layer;
} VkRectLayerKHR;
-
offsetis the origin of the rectangle, in pixels. -
extentis the size of the rectangle, in pixels. -
layeris the layer of the image. For images with only one layer, the value oflayermust be 0.
Some platforms allow the size of a surface to change, and then scale the
pixels of the image to fit the surface.
VkRectLayerKHR specifies pixels of the swapchain’s image(s), which
will be constant for the life of the swapchain.
When the VK_KHR_display_swapchain extension is enabled additional fields
can be specified when presenting an image to a swapchain by setting
VkPresentInfoKHR::pNext to point to a
VkDisplayPresentInfoKHR structure.
The VkDisplayPresentInfoKHR structure is defined as:
// Provided by VK_KHR_display_swapchain
typedef struct VkDisplayPresentInfoKHR {
VkStructureType sType;
const void* pNext;
VkRect2D srcRect;
VkRect2D dstRect;
VkBool32 persistent;
} VkDisplayPresentInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcRectis a rectangular region of pixels to present. It must be a subset of the image being presented. IfVkDisplayPresentInfoKHRis not specified, this region will be assumed to be the entire presentable image. -
dstRectis a rectangular region within the visible region of the swapchain’s display mode. IfVkDisplayPresentInfoKHRis not specified, this region will be assumed to be the entire visible region of the swapchain’s mode. If the specified rectangle is a subset of the display mode’s visible region, content from display planes below the swapchain’s plane will be visible outside the rectangle. If there are no planes below the swapchain’s, the area outside the specified rectangle will be black. If portions of the specified rectangle are outside of the display’s visible region, pixels mapping only to those portions of the rectangle will be discarded. -
persistent: If this isVK_TRUE, the display engine will enable buffered mode on displays that support it. This allows the display engine to stop sending content to the display until a new image is presented. The display will instead maintain a copy of the last presented image. This allows less power to be used, but may increase presentation latency. IfVkDisplayPresentInfoKHRis not specified, persistent mode will not be used.
If the extent of the srcRect and dstRect are not equal, the
presented pixels will be scaled accordingly.
If the pNext chain of VkPresentInfoKHR includes a
VkDeviceGroupPresentInfoKHR structure, then that structure includes an
array of device masks and a device group present mode.
The VkDeviceGroupPresentInfoKHR structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkDeviceGroupPresentInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const uint32_t* pDeviceMasks;
VkDeviceGroupPresentModeFlagBitsKHR mode;
} VkDeviceGroupPresentInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainCountis zero or the number of elements inpDeviceMasks. -
pDeviceMasksis a pointer to an array of device masks, one for each element of VkPresentInfoKHR::pSwapchains. -
modeis a VkDeviceGroupPresentModeFlagBitsKHR value specifying the device group present mode that will be used for this present.
If mode is VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then each
element of pDeviceMasks selects which instance of the swapchain image
is presented.
Each element of pDeviceMasks must have exactly one bit set, and the
corresponding physical device must have a presentation engine as reported
by VkDeviceGroupPresentCapabilitiesKHR.
If mode is VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then
each element of pDeviceMasks selects which instance of the swapchain
image is presented.
Each element of pDeviceMasks must have exactly one bit set, and some
physical device in the logical device must include that bit in its
VkDeviceGroupPresentCapabilitiesKHR::presentMask.
If mode is VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each
element of pDeviceMasks selects which instances of the swapchain image
are component-wise summed and the sum of those images is presented.
If the sum in any component is outside the representable range, the value of
that component is undefined.
Each element of pDeviceMasks must have a value for which all set bits
are set in one of the elements of
VkDeviceGroupPresentCapabilitiesKHR::presentMask.
If mode is
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then each
element of pDeviceMasks selects which instance(s) of the swapchain
images are presented.
For each bit set in each element of pDeviceMasks, the corresponding
physical device must have a presentation engine as reported by
VkDeviceGroupPresentCapabilitiesKHR.
If VkDeviceGroupPresentInfoKHR is not provided or swapchainCount
is zero then the masks are considered to be 1.
If VkDeviceGroupPresentInfoKHR is not provided, mode is
considered to be VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.
When the VK_GOOGLE_display_timing extension is enabled, additional
fields can be specified that allow an application to specify the earliest
time that an image should be displayed.
This allows an application to avoid stutter that is caused by an image being
displayed earlier than planned.
Such stuttering can occur with both fixed and variable-refresh-rate
displays, because stuttering occurs when the geometry is not correctly
positioned for when the image is displayed.
An application can instruct the presentation engine that an image should
not be displayed earlier than a specified time by adding a
VkPresentTimesInfoGOOGLE structure to the pNext chain of the
VkPresentInfoKHR structure.
The VkPresentTimesInfoGOOGLE structure is defined as:
// Provided by VK_GOOGLE_display_timing
typedef struct VkPresentTimesInfoGOOGLE {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const VkPresentTimeGOOGLE* pTimes;
} VkPresentTimesInfoGOOGLE;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainCountis the number of swapchains being presented to by this command. -
pTimesisNULLor a pointer to an array ofVkPresentTimeGOOGLEelements withswapchainCountentries. If notNULL, each element ofpTimescontains the earliest time to present the image corresponding to the entry in theVkPresentInfoKHR::pImageIndicesarray.
The VkPresentTimeGOOGLE structure is defined as:
// Provided by VK_GOOGLE_display_timing
typedef struct VkPresentTimeGOOGLE {
uint32_t presentID;
uint64_t desiredPresentTime;
} VkPresentTimeGOOGLE;
-
presentIDis an application-provided identification value, that can be used with the results of vkGetPastPresentationTimingGOOGLE, in order to uniquely identify this present. In order to be useful to the application, it should be unique within some period of time that is meaningful to the application. -
desiredPresentTimespecifies that the image given should not be displayed to the user any earlier than this time.desiredPresentTimeis a time in nanoseconds, relative to a monotonically-increasing clock (e.g.CLOCK_MONOTONIC(see clock_gettime(2)) on Android and Linux). A value of zero specifies that the presentation engine may display the image at any time. This is useful when the application desires to providepresentID, but does not need a specificdesiredPresentTime.
The VkPresentIdKHR structure is defined as:
// Provided by VK_KHR_present_id
typedef struct VkPresentIdKHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const uint64_t* pPresentIds;
} VkPresentIdKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainCountis the number of swapchains being presented to thevkQueuePresentKHRcommand. -
pPresentIdsisNULLor a pointer to an array of uint64_t withswapchainCountentries. If notNULL, each non-zero value inpPresentIdsspecifies the present id to be associated with the presentation of the swapchain with the same index in the vkQueuePresentKHR call.
For applications to be able to reference specific presentation events queued
by a call to vkQueuePresentKHR, an identifier needs to be associated
with them.
When the presentId feature is enabled,
applications can include the VkPresentIdKHR structure in the
pNext chain of the VkPresentInfoKHR structure to supply
identifiers.
Each VkSwapchainKHR has a presentId associated with it.
This value is initially set to zero when the VkSwapchainKHR is
created.
When a VkPresentIdKHR structure with a non-NULL pPresentIds is
included in the pNext chain of a VkPresentInfoKHR structure,
each pSwapchains entry has a presentId associated in the
pPresentIds array at the same index as the swapchain in the
pSwapchains array.
If this presentId is non-zero, then the application can later use this
value to refer to that image presentation.
A value of zero indicates that this presentation has no associated
presentId.
A non-zero presentId must be greater than any non-zero presentId passed
previously by the application for the same swapchain.
There is no requirement for any precise timing relationship between the presentation of the image to the user and the update of the presentId value, but implementations should make this as close as possible to the presentation of the first pixel in the new image to the user.
When the presentWait feature is enabled, an
application can wait for an image to be presented to the user by first
specifying a presentId for the target presentation by adding a
VkPresentIdKHR structure to the pNext chain of the
VkPresentInfoKHR structure and then waiting for that presentation to
complete by calling:
// Provided by VK_KHR_present_wait
VkResult vkWaitForPresentKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint64_t presentId,
uint64_t timeout);
-
deviceis the device associated withswapchain. -
swapchainis the non-retired swapchain on which an image was queued for presentation. -
presentIdis the presentation presentId to wait for. -
timeoutis the timeout period in units of nanoseconds.timeoutis 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.
vkWaitForPresentKHR waits for the presentId associated with
swapchain to be increased in value so that it is at least equal to
presentId.
For VK_PRESENT_MODE_MAILBOX_KHR (or other present mode where images
may be replaced in the presentation queue) any wait of this type associated
with such an image must be signaled no later than a wait associated with
the replacing image would be signaled.
When the presentation has completed, the presentId associated with the
related pSwapchains entry will be increased in value so that it is at
least equal to the value provided in the VkPresentIdKHR structure.
There is no requirement for any precise timing relationship between the presentation of the image to the user and the update of the presentId value, but implementations should make this as close as possible to the presentation of the first pixel in the new image to the user.
The call to vkWaitForPresentKHR will block until either the presentId
associated with swapchain is greater than or equal to presentId,
or timeout nanoseconds passes.
When the swapchain becomes OUT_OF_DATE, the call will either return
VK_SUCCESS (if the image was delivered to the presentation engine and
may have been presented to the user) or will return early with status
VK_ERROR_OUT_OF_DATE_KHR (if the image was not presented to the user).
As an exception to the normal rules for objects which are externally
synchronized, the swapchain passed to vkWaitForPresentKHR may
be simultaneously used by other threads in calls to functions other than
vkDestroySwapchainKHR.
Access to the swapchain data associated with this extension must be atomic
within the implementation.
When the VK_GGP_frame_token extension is enabled, a Google Games
Platform frame token can be specified when presenting an image to a
swapchain by adding a VkPresentFrameTokenGGP structure to the
pNext chain of the VkPresentInfoKHR structure.
The VkPresentFrameTokenGGP structure is defined as:
// Provided by VK_GGP_frame_token
typedef struct VkPresentFrameTokenGGP {
VkStructureType sType;
const void* pNext;
GgpFrameToken frameToken;
} VkPresentFrameTokenGGP;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
frameTokenis the Google Games Platform frame token.
vkQueuePresentKHR, releases the acquisition of the images referenced
by imageIndices.
The queue family corresponding to the queue vkQueuePresentKHR is
executed on must have ownership of the presented images as defined in
Resource Sharing.
vkQueuePresentKHR does not alter the queue family ownership, but the
presented images must not be used again before they have been reacquired
using vkAcquireNextImageKHR.
The processing of the presentation happens in issue order with other queue operations, but semaphores have to be used to ensure that prior rendering and other commands in the specified queue complete before the presentation begins. The presentation command itself does not delay processing of subsequent commands on the queue, however, presentation requests sent to a particular queue are always performed in order. Exact presentation timing is controlled by the semantics of the presentation engine and native platform in use.
If an image is presented to a swapchain created from a display surface, the mode of the associated display will be updated, if necessary, to match the mode specified when creating the display surface. The mode switch and presentation of the specified image will be performed as one atomic operation.
The result codes VK_ERROR_OUT_OF_DATE_KHR and VK_SUBOPTIMAL_KHR
have the same meaning when returned by vkQueuePresentKHR as they do
when returned by vkAcquireNextImageKHR.
If multiple swapchains are presented, the result code is determined applying
the following rules in order:
-
If the device is lost,
VK_ERROR_DEVICE_LOSTis returned. -
If any of the target surfaces are no longer available the error
VK_ERROR_SURFACE_LOST_KHRis returned. -
If any of the presents would have a result of
VK_ERROR_OUT_OF_DATE_KHRif issued separately thenVK_ERROR_OUT_OF_DATE_KHRis returned. -
If any of the presents would have a result of
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXTif issued separately thenVK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXTis returned. -
If any of the presents would have a result of
VK_SUBOPTIMAL_KHRif issued separately thenVK_SUBOPTIMAL_KHRis returned. -
Otherwise
VK_SUCCESSis returned.
Presentation is a read-only operation that will not affect the content of
the presentable images.
Upon reacquiring the image and transitioning it away from the
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout, the contents will be the same
as they were prior to transitioning the image to the present source layout
and presenting it.
However, if a mechanism other than Vulkan is used to modify the platform
window associated with the swapchain, the content of all presentable images
in the swapchain becomes undefined.
|
Note
The application can continue to present any acquired images from a retired
swapchain as long as the swapchain has not entered a state that causes
vkQueuePresentKHR to return |
33.11. Hdr Metadata
This section describes how to improve color reproduction of content to better reproduce colors as seen on the reference monitor. Definitions below are from the associated SMPTE 2086, CTA 861.3 and CIE 15:2004 specifications.
To provide Hdr metadata to an implementation, call:
// Provided by VK_EXT_hdr_metadata
void vkSetHdrMetadataEXT(
VkDevice device,
uint32_t swapchainCount,
const VkSwapchainKHR* pSwapchains,
const VkHdrMetadataEXT* pMetadata);
-
deviceis the logical device where the swapchain(s) were created. -
swapchainCountis the number of swapchains included inpSwapchains. -
pSwapchainsis a pointer to an array ofswapchainCountVkSwapchainKHR handles. -
pMetadatais a pointer to an array ofswapchainCountVkHdrMetadataEXT structures.
The metadata will be applied to the specified VkSwapchainKHR objects
at the next vkQueuePresentKHR call using that VkSwapchainKHR
object.
The metadata will persist until a subsequent vkSetHdrMetadataEXT
changes it.
The VkHdrMetadataEXT structure is defined as:
// Provided by VK_EXT_hdr_metadata
typedef struct VkHdrMetadataEXT {
VkStructureType sType;
const void* pNext;
VkXYColorEXT displayPrimaryRed;
VkXYColorEXT displayPrimaryGreen;
VkXYColorEXT displayPrimaryBlue;
VkXYColorEXT whitePoint;
float maxLuminance;
float minLuminance;
float maxContentLightLevel;
float maxFrameAverageLightLevel;
} VkHdrMetadataEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
displayPrimaryRedis a VkXYColorEXT structure specifying the reference monitor’s red primary in chromaticity coordinates -
displayPrimaryGreenis a VkXYColorEXT structure specifying the reference monitor’s green primary in chromaticity coordinates -
displayPrimaryBlueis a VkXYColorEXT structure specifying the reference monitor’s blue primary in chromaticity coordinates -
whitePointis a VkXYColorEXT structure specifying the reference monitor’s white-point in chromaticity coordinates -
maxLuminanceis the maximum luminance of the reference monitor in nits -
minLuminanceis the minimum luminance of the reference monitor in nits -
maxContentLightLevelis content’s maximum luminance in nits -
maxFrameAverageLightLevelis the maximum frame average light level in nits
|
Note
The validity and use of this data is outside the scope of Vulkan. |
The VkXYColorEXT structure is defined as:
// Provided by VK_EXT_hdr_metadata
typedef struct VkXYColorEXT {
float x;
float y;
} VkXYColorEXT;
-
xis the x chromaticity coordinate. -
yis the y chromaticity coordinate.
Chromaticity coordinates are as specified in CIE 15:2004 “Calculation of chromaticity coordinates” (Section 7.3) and are limited to between 0 and 1 for real colors for the reference monitor.
34. Deferred Host Operations
Certain Vulkan commands are inherently expensive for the host CPU to execute. It is often desirable to offload such work onto background threads, and to parallelize the work across multiple CPUs. The concept of deferred operations allows applications and drivers to coordinate the execution of expensive host commands using an application-managed thread pool.
The VK_KHR_deferred_host_operations extension defines the
infrastructure and usage patterns for deferrable commands, but does not
specify any commands as deferrable.
This is left to additional dependant extensions.
Commands must not be deferred unless the deferral is specifically allowed
by another extension which depends on
VK_KHR_deferred_host_operations.
This specification will refer to such extensions as deferral extensions.
34.1. Requesting Deferral
When an application requests an operation deferral, the implementation may
defer the operation.
When deferral is requested and the implementation defers any operation, the
implementation must return VK_OPERATION_DEFERRED_KHR as the success
code if no errors occurred.
When deferral is requested, the implementation should defer the operation
when the workload is significant, however if the implementation chooses not
to defer any of the requested operations and instead executes all of them
immediately, the implementation must return
VK_OPERATION_NOT_DEFERRED_KHR as the success code if no errors
occurred.
A deferred operation is created complete with an initial result value of
VK_SUCCESS.
The deferred operation becomes pending when an operation has been
successfully deferred with that deferred operation object.
A deferred operation is considered pending until the deferred operation completes. A pending deferred operation becomes complete when it has been fully executed by one or more threads. Pending deferred operations will never complete until they are joined by an application thread, using vkDeferredOperationJoinKHR. Applications can join multiple threads to the same deferred operation, enabling concurrent execution of subtasks within that operation.
The application can query the status of a VkDeferredOperationKHR using the vkGetDeferredOperationMaxConcurrencyKHR or vkGetDeferredOperationResultKHR commands.
Parameters to the command requesting a deferred operation may be accessed at any time until the deferred operation enters the pending state. While a deferred operation is pending:
-
Externally synchronized parameters must not be accessed.
-
Pointer parameters must not be modified (e.g. reallocated/freed).
-
The contents of pointer parameters which may be read by the command must not be modified.
-
The contents of pointer parameters which may be written by the command must not be read.
-
Vulkan object parameters must not be passed as externally synchronized parameters to any other command.
When the deferred operation is complete, the application should call vkGetDeferredOperationResultKHR to obtain the VkResult indicating success or failure of the operation. The VkResult value returned will be one of the values that the command requesting the deferred operation is able to return. Writes to output parameters of the requesting command will happen-before the deferred operation is complete.
34.2. Deferred Host Operations API
The VkDeferredOperationKHR handle is defined as:
// Provided by VK_KHR_deferred_host_operations
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDeferredOperationKHR)
This handle refers to a tracking structure which manages the execution state for a deferred command.
To construct the tracking object for a deferred command, call:
// Provided by VK_KHR_deferred_host_operations
VkResult vkCreateDeferredOperationKHR(
VkDevice device,
const VkAllocationCallbacks* pAllocator,
VkDeferredOperationKHR* pDeferredOperation);
-
deviceis the device which ownsoperation. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pDeferredOperationis a pointer to a handle in which the created VkDeferredOperationKHR is returned.
To assign a thread to a deferred operation, call:
// Provided by VK_KHR_deferred_host_operations
VkResult vkDeferredOperationJoinKHR(
VkDevice device,
VkDeferredOperationKHR operation);
-
deviceis the device which ownsoperation. -
operationis the deferred operation that the calling thread should work on.
The vkDeferredOperationJoinKHR command will execute a portion of the
deferred operation on the calling thread.
The return value will be one of the following:
-
A return value of
VK_SUCCESSindicates thatoperationis complete. The application should use vkGetDeferredOperationResultKHR to retrieve the result ofoperation. -
A return value of
VK_THREAD_DONE_KHRindicates that the deferred operation is not complete, but there is no work remaining to assign to threads. Future calls to vkDeferredOperationJoinKHR are not necessary and will simply harm performance. This situation may occur when other threads executing vkDeferredOperationJoinKHR are about to completeoperation, and the implementation is unable to partition the workload any further. -
A return value of
VK_THREAD_IDLE_KHRindicates that the deferred operation is not complete, and there is no work for the thread to do at the time of the call. This situation may occur if the operation encounters a temporary reduction in parallelism. By returningVK_THREAD_IDLE_KHR, the implementation is signaling that it expects that more opportunities for parallelism will emerge as execution progresses, and that future calls to vkDeferredOperationJoinKHR can be beneficial. In the meantime, the application can perform other work on the calling thread.
Implementations must guarantee forward progress by enforcing the following invariants:
-
If only one thread has invoked vkDeferredOperationJoinKHR on a given operation, that thread must execute the operation to completion and return
VK_SUCCESS. -
If multiple threads have concurrently invoked vkDeferredOperationJoinKHR on the same operation, then at least one of them must complete the operation and return
VK_SUCCESS.
When a deferred operation is completed, the application can destroy the tracking object by calling:
// Provided by VK_KHR_deferred_host_operations
void vkDestroyDeferredOperationKHR(
VkDevice device,
VkDeferredOperationKHR operation,
const VkAllocationCallbacks* pAllocator);
-
deviceis the device which ownsoperation. -
operationis the completed operation to be destroyed. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
To query the number of additional threads that can usefully be joined to a deferred operation, call:
// Provided by VK_KHR_deferred_host_operations
uint32_t vkGetDeferredOperationMaxConcurrencyKHR(
VkDevice device,
VkDeferredOperationKHR operation);
-
deviceis the device which ownsoperation. -
operationis the deferred operation to be queried.
The returned value is the maximum number of threads that can usefully
execute a deferred operation concurrently, reported for the state of the
deferred operation at the point this command is called.
This value is intended to be used to better schedule work onto available
threads.
Applications can join any number of threads to the deferred operation and
expect it to eventually complete, though excessive joins may return
VK_THREAD_DONE_KHR immediately, performing no useful work.
If operation is complete,
vkGetDeferredOperationMaxConcurrencyKHR returns zero.
If operation is currently joined to any threads, the value returned by
this command may immediately be out of date.
If operation is pending, implementations must not return zero unless
at least one thread is currently executing vkDeferredOperationJoinKHR
on operation.
If there are such threads, the implementation should return an estimate of
the number of additional threads which it could profitably use.
Implementations may return 232-1 to indicate that the maximum concurrency is unknown and cannot be easily derived. Implementations may return values larger than the maximum concurrency available on the host CPU. In these situations, an application should clamp the return value rather than oversubscribing the machine.
|
Note
The recommended usage pattern for applications is to query this value once,
after deferral, and schedule no more than the specified number of threads to
join the operation.
Each time a joined thread receives |
The vkGetDeferredOperationResultKHR function is defined as:
// Provided by VK_KHR_deferred_host_operations
VkResult vkGetDeferredOperationResultKHR(
VkDevice device,
VkDeferredOperationKHR operation);
-
deviceis the device which ownsoperation. -
operationis the operation whose deferred result is being queried.
If no command has been deferred on operation,
vkGetDeferredOperationResultKHR returns VK_SUCCESS.
If the deferred operation is pending, vkGetDeferredOperationResultKHR
returns VK_NOT_READY.
If the deferred operation is complete, it returns the appropriate return value from the original command. This value must be one of the VkResult values which could have been returned by the original command if the operation had not been deferred.
35. Private Data
The private data extension provides a way for users to associate arbitrary user defined data with Vulkan objects. This association is accomplished by storing 64-bit unsigned integers of user defined data in private data slots. A private data slot represents a storage allocation for one data item for each child object of the device.
An application can reserve private data slots at device creation.
To reserve private data slots, insert a VkDevicePrivateDataCreateInfo
in the pNext chain in VkDeviceCreateInfo before device creation.
Multiple VkDevicePrivateDataCreateInfo structures can be chained
together, and the sum of the requested slots will be reserved.
This is an exception to the specified valid usage for
structure pointer chains.
Reserving slots in this manner is not strictly necessary but it may improve
performance.
Private data slots are represented by VkPrivateDataSlot handles:
// Provided by VK_VERSION_1_3
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPrivateDataSlot)
or the equivalent
// Provided by VK_EXT_private_data
typedef VkPrivateDataSlot VkPrivateDataSlotEXT;
To create a private data slot, call:
// Provided by VK_VERSION_1_3
VkResult vkCreatePrivateDataSlot(
VkDevice device,
const VkPrivateDataSlotCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkPrivateDataSlot* pPrivateDataSlot);
or the equivalent command
// Provided by VK_EXT_private_data
VkResult vkCreatePrivateDataSlotEXT(
VkDevice device,
const VkPrivateDataSlotCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkPrivateDataSlot* pPrivateDataSlot);
-
deviceis the logical device associated with the creation of the object(s) holding the private data slot. -
pCreateInfois a pointer to aVkPrivateDataSlotCreateInfo -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pPrivateDataSlotis a pointer to a VkPrivateDataSlot handle in which the resulting private data slot is returned
The VkPrivateDataSlotCreateInfo structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPrivateDataSlotCreateInfo {
VkStructureType sType;
const void* pNext;
VkPrivateDataSlotCreateFlags flags;
} VkPrivateDataSlotCreateInfo;
or the equivalent
// Provided by VK_EXT_private_data
typedef VkPrivateDataSlotCreateInfo VkPrivateDataSlotCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use.
// Provided by VK_VERSION_1_3
typedef VkFlags VkPrivateDataSlotCreateFlags;
or the equivalent
// Provided by VK_EXT_private_data
typedef VkPrivateDataSlotCreateFlags VkPrivateDataSlotCreateFlagsEXT;
VkPrivateDataSlotCreateFlags is a bitmask type for setting a mask, but
is currently reserved for future use.
To destroy a private data slot, call:
// Provided by VK_VERSION_1_3
void vkDestroyPrivateDataSlot(
VkDevice device,
VkPrivateDataSlot privateDataSlot,
const VkAllocationCallbacks* pAllocator);
or the equivalent command
// Provided by VK_EXT_private_data
void vkDestroyPrivateDataSlotEXT(
VkDevice device,
VkPrivateDataSlot privateDataSlot,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device associated with the creation of the object(s) holding the private data slot. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
privateDataSlotis the private data slot to destroy.
To store user defined data in a slot associated with a Vulkan object, call:
// Provided by VK_VERSION_1_3
VkResult vkSetPrivateData(
VkDevice device,
VkObjectType objectType,
uint64_t objectHandle,
VkPrivateDataSlot privateDataSlot,
uint64_t data);
or the equivalent command
// Provided by VK_EXT_private_data
VkResult vkSetPrivateDataEXT(
VkDevice device,
VkObjectType objectType,
uint64_t objectHandle,
VkPrivateDataSlot privateDataSlot,
uint64_t data);
-
deviceis the device that created the object. -
objectTypeis a VkObjectType specifying the type of object to associate data with. -
objectHandleis a handle to the object to associate data with. -
privateDataSlotis a handle to a VkPrivateDataSlot specifying location of private data storage. -
datais user defined data to associate the object with. This data will be stored atprivateDataSlot.
To retrieve user defined data from a slot associated with a Vulkan object, call:
// Provided by VK_VERSION_1_3
void vkGetPrivateData(
VkDevice device,
VkObjectType objectType,
uint64_t objectHandle,
VkPrivateDataSlot privateDataSlot,
uint64_t* pData);
or the equivalent command
// Provided by VK_EXT_private_data
void vkGetPrivateDataEXT(
VkDevice device,
VkObjectType objectType,
uint64_t objectHandle,
VkPrivateDataSlot privateDataSlot,
uint64_t* pData);
-
deviceis the device that created the object -
objectTypeis a VkObjectType specifying the type of object data is associated with. -
objectHandleis a handle to the object data is associated with. -
privateDataSlotis a handle to a VkPrivateDataSlot specifying location of private data pointer storage. -
pDatais a pointer to specify where user data is returned.0will be written in the absence of a previous call tovkSetPrivateDatausing the object specified byobjectHandle.
|
Note
Due to platform details on Android, implementations might not be able to
reliably return |
36. Acceleration Structures
36.1. Acceleration Structures
Acceleration structures are data structures used by the implementation to efficiently manage scene geometry as it is traversed during a ray tracing query. The application is responsible for managing acceleration structure objects (see Acceleration Structures), including allocation, destruction, executing builds or updates, and synchronizing resources used during ray tracing queries.
There are two types of acceleration structures, top level acceleration structures and bottom level acceleration structures.
An acceleration structure is considered to be constructed if an acceleration structure build command or copy command has been executed with the given acceleration structure as the destination.
36.1.2. Top Level Acceleration Structures
Opaque acceleration structure for an array of instances. The descriptor or device address referencing this is the starting point for traversal.
The top level acceleration structure takes a reference to any bottom level acceleration structure referenced by its instances. Those bottom level acceleration structure objects must be valid when the top level acceleration structure is accessed.
36.1.3. Bottom Level Acceleration Structures
Opaque acceleration structure for an array of geometries.
36.1.4. Acceleration Structure Update Rules
The API defines two types of operations to produce acceleration structures from geometry:
-
A build operation is used to construct an acceleration structure.
-
An update operation is used to modify an existing acceleration structure.
An update operation imposes certain constraints on the input, in exchange for considerably faster execution. When performing an update, the application is required to provide a full description of the acceleration structure, but is prohibited from changing anything other than instance definitions, transform matrices, and vertex or AABB positions. All other aspects of the description must exactly match the one from the original build.
More precisely, the application must not use an update operation to do any of the following:
-
Change primitives or instances from active to inactive, or vice versa (as defined in Inactive Primitives and Instances).
-
Change the index or vertex formats of triangle geometry.
-
Change triangle geometry transform pointers from null to non-null or vice versa.
-
Change the number of geometries or instances in the structure.
-
Change the geometry flags for any geometry in the structure.
-
Change the number of vertices or primitives for any geometry in the structure.
36.1.5. Inactive Primitives and Instances
Acceleration structures allow the use of particular input values to signal inactive primitives or instances.
An inactive triangle is one for which the first (X) component of any vertex is NaN. If any other vertex component is NaN, and the first is not, the behavior is undefined. If the vertex format does not have a NaN representation, then all triangles are considered active.
An inactive instance is one whose acceleration structure handle is VK_NULL_HANDLE.
An inactive AABB is one for which the minimum X coordinate is NaN. If any other component is NaN, and the first is not, the behavior is undefined.
In the above definitions, “NaN” refers to any type of NaN. Signaling, non-signaling, quiet, loud, or otherwise.
An inactive object is considered invisible to all rays, and should not be represented in the acceleration structure. Implementations should ensure that the presence of inactive objects does not seriously degrade traversal performance.
Inactive objects are counted in the auto-generated index sequences which are
provided to shaders via InstanceId and PrimitiveId SPIR-V
decorations.
This allows objects in the scene to change freely between the active and
inactive states, without affecting the layout of any arrays which are being
indexed using the ID values.
Any transition between the active and inactive states requires a full acceleration structure rebuild. Applications must not perform an acceleration structure update where an object is active in the source acceleration structure but would be inactive in the destination, or vice versa.
36.1.6. Building Acceleration Structures
To build an acceleration structure call:
// Provided by VK_NV_ray_tracing
void vkCmdBuildAccelerationStructureNV(
VkCommandBuffer commandBuffer,
const VkAccelerationStructureInfoNV* pInfo,
VkBuffer instanceData,
VkDeviceSize instanceOffset,
VkBool32 update,
VkAccelerationStructureNV dst,
VkAccelerationStructureNV src,
VkBuffer scratch,
VkDeviceSize scratchOffset);
-
commandBufferis the command buffer into which the command will be recorded. -
pInfocontains the shared information for the acceleration structure’s structure. -
instanceDatais the buffer containing an array of VkAccelerationStructureInstanceKHR structures defining acceleration structures. This parameter must beNULLfor bottom level acceleration structures. -
instanceOffsetis the offset in bytes (relative to the start ofinstanceData) at which the instance data is located. -
updatespecifies whether to update thedstacceleration structure with the data insrc. -
dstis a pointer to the target acceleration structure for the build. -
srcis a pointer to an existing acceleration structure that is to be used to update thedstacceleration structure. -
scratchis the VkBuffer that will be used as scratch memory for the build. -
scratchOffsetis the offset in bytes relative to the start ofscratchthat will be used as a scratch memory.
Accesses to dst, src, and scratch must be
synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.
To build acceleration structures call:
// Provided by VK_KHR_acceleration_structure
void vkCmdBuildAccelerationStructuresKHR(
VkCommandBuffer commandBuffer,
uint32_t infoCount,
const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
const VkAccelerationStructureBuildRangeInfoKHR* const* ppBuildRangeInfos);
-
commandBufferis the command buffer into which the command will be recorded. -
infoCountis the number of acceleration structures to build. It specifies the number of thepInfosstructures andppBuildRangeInfospointers that must be provided. -
pInfosis a pointer to an array ofinfoCountVkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. -
ppBuildRangeInfosis a pointer to an array ofinfoCountpointers to arrays of VkAccelerationStructureBuildRangeInfoKHR structures. EachppBuildRangeInfos[i] is a pointer to an array ofpInfos[i].geometryCountVkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfos[i].
The vkCmdBuildAccelerationStructuresKHR command provides the ability
to initiate multiple acceleration structures builds, however there is no
ordering or synchronization implied between any of the individual
acceleration structure builds.
|
Note
This means that an application cannot build a top-level acceleration structure in the same vkCmdBuildAccelerationStructuresKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds. |
Accesses to the acceleration structure scratch buffers as identified by the
VkAccelerationStructureBuildGeometryInfoKHR::scratchData buffer
device addresses must be synchronized with
the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.
Similarly for accesses to each
VkAccelerationStructureBuildGeometryInfoKHR::srcAccelerationStructure
and
VkAccelerationStructureBuildGeometryInfoKHR::dstAccelerationStructure.
Accesses to other input buffers as identified by any used values of
VkAccelerationStructureGeometryMotionTrianglesDataNV::vertexData,
VkAccelerationStructureGeometryTrianglesDataKHR::vertexData,
VkAccelerationStructureGeometryTrianglesDataKHR::indexData,
VkAccelerationStructureGeometryTrianglesDataKHR::transformData,
VkAccelerationStructureGeometryAabbsDataKHR::data, and
VkAccelerationStructureGeometryInstancesDataKHR::data must be
synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_SHADER_READ_BIT.
To build acceleration structures with some parameters sourced on the device call:
// Provided by VK_KHR_acceleration_structure
void vkCmdBuildAccelerationStructuresIndirectKHR(
VkCommandBuffer commandBuffer,
uint32_t infoCount,
const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
const VkDeviceAddress* pIndirectDeviceAddresses,
const uint32_t* pIndirectStrides,
const uint32_t* const* ppMaxPrimitiveCounts);
-
commandBufferis the command buffer into which the command will be recorded. -
infoCountis the number of acceleration structures to build. -
pInfosis a pointer to an array ofinfoCountVkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. -
pIndirectDeviceAddressesis a pointer to an array ofinfoCountbuffer device addresses which point topInfos[i].geometryCountVkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfos[i]. -
pIndirectStridesis a pointer to an array ofinfoCountbyte strides between elements ofpIndirectDeviceAddresses. -
ppMaxPrimitiveCountsis a pointer to an array ofinfoCountpointers to arrays ofpInfos[i].geometryCountvalues indicating the maximum number of primitives that will be built by this command for each geometry.
Accesses to acceleration structures, scratch buffers, vertex buffers, index buffers, and instance buffers must be synchronized as with vkCmdBuildAccelerationStructuresKHR.
Accesses to any element of pIndirectDeviceAddresses must be
synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_INDIRECT_COMMAND_READ_BIT.
The VkAccelerationStructureBuildGeometryInfoKHR structure is defined
as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureBuildGeometryInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureTypeKHR type;
VkBuildAccelerationStructureFlagsKHR flags;
VkBuildAccelerationStructureModeKHR mode;
VkAccelerationStructureKHR srcAccelerationStructure;
VkAccelerationStructureKHR dstAccelerationStructure;
uint32_t geometryCount;
const VkAccelerationStructureGeometryKHR* pGeometries;
const VkAccelerationStructureGeometryKHR* const* ppGeometries;
VkDeviceOrHostAddressKHR scratchData;
} VkAccelerationStructureBuildGeometryInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure being built. -
flagsis a bitmask of VkBuildAccelerationStructureFlagBitsKHR specifying additional parameters of the acceleration structure. -
modeis a VkBuildAccelerationStructureModeKHR value specifying the type of operation to perform. -
srcAccelerationStructureis a pointer to an existing acceleration structure that is to be used to update thedstacceleration structure whenmodeisVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR. -
dstAccelerationStructureis a pointer to the target acceleration structure for the build. -
geometryCountspecifies the number of geometries that will be built intodstAccelerationStructure. -
pGeometriesis a pointer to an array of VkAccelerationStructureGeometryKHR structures. -
ppGeometriesis a pointer to an array of pointers to VkAccelerationStructureGeometryKHR structures. -
scratchDatais the device or host address to memory that will be used as scratch memory for the build.
Only one of pGeometries or ppGeometries can be a valid pointer,
the other must be NULL.
Each element of the non-NULL array describes the data used to build each
acceleration structure geometry.
The index of each element of the pGeometries or ppGeometries
members of VkAccelerationStructureBuildGeometryInfoKHR is used as the
geometry index during ray traversal.
The geometry index is available in ray shaders via the
RayGeometryIndexKHR
built-in, and is used to
determine hit and intersection shaders executed during traversal.
The geometry index is available to ray queries via the
OpRayQueryGetIntersectionGeometryIndexKHR instruction.
Setting VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in flags
indicates that this build is a motion top level acceleration structure.
A motion top level uses instances of format
VkAccelerationStructureMotionInstanceNV if
VkAccelerationStructureGeometryInstancesDataKHR::arrayOfPointers
is VK_FALSE.
If
VkAccelerationStructureGeometryInstancesDataKHR::arrayOfPointers
is VK_TRUE, the pointer for any given element of the array of instance
pointers consists of 4 bits of
VkAccelerationStructureMotionInstanceTypeNV in the low 4 bits of the
pointer identifying the type of structure at the pointer.
The device address accessed is the value in the array with the low 4 bits
set to zero.
The structure at the pointer is one of
VkAccelerationStructureInstanceKHR,
VkAccelerationStructureMatrixMotionInstanceNV or
VkAccelerationStructureSRTMotionInstanceNV, depending on the type
value encoded in the low 4 bits.
A top level acceleration structure with either motion instances or vertex
motion in its instances must set
VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in flags.
Members srcAccelerationStructure and dstAccelerationStructure
may be the same or different for an update operation (when mode is
VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR).
If they are the same, the update happens in-place.
Otherwise, the target acceleration structure is updated and the source is
not modified.
The VkBuildAccelerationStructureModeKHR enumeration is defined as:
// Provided by VK_KHR_acceleration_structure
typedef enum VkBuildAccelerationStructureModeKHR {
VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR = 0,
VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR = 1,
} VkBuildAccelerationStructureModeKHR;
-
VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHRspecifies that the destination acceleration structure will be built using the specified geometries. -
VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHRspecifies that the destination acceleration structure will be built using data in a source acceleration structure, updated by the specified geometries.
The VkDeviceOrHostAddressKHR union is defined as:
// Provided by VK_KHR_acceleration_structure
typedef union VkDeviceOrHostAddressKHR {
VkDeviceAddress deviceAddress;
void* hostAddress;
} VkDeviceOrHostAddressKHR;
-
deviceAddressis a buffer device address as returned by the vkGetBufferDeviceAddressKHR command. -
hostAddressis a host memory address.
The VkDeviceOrHostAddressConstKHR union is defined as:
// Provided by VK_KHR_acceleration_structure
typedef union VkDeviceOrHostAddressConstKHR {
VkDeviceAddress deviceAddress;
const void* hostAddress;
} VkDeviceOrHostAddressConstKHR;
-
deviceAddressis a buffer device address as returned by the vkGetBufferDeviceAddressKHR command. -
hostAddressis a const host memory address.
The VkAccelerationStructureGeometryKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryKHR {
VkStructureType sType;
const void* pNext;
VkGeometryTypeKHR geometryType;
VkAccelerationStructureGeometryDataKHR geometry;
VkGeometryFlagsKHR flags;
} VkAccelerationStructureGeometryKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
geometryTypedescribes which type of geometry thisVkAccelerationStructureGeometryKHRrefers to. -
geometryis a VkAccelerationStructureGeometryDataKHR union describing the geometry data for the relevant geometry type. -
flagsis a bitmask of VkGeometryFlagBitsKHR values describing additional properties of how the geometry should be built.
The VkAccelerationStructureGeometryDataKHR union is defined as:
// Provided by VK_KHR_acceleration_structure
typedef union VkAccelerationStructureGeometryDataKHR {
VkAccelerationStructureGeometryTrianglesDataKHR triangles;
VkAccelerationStructureGeometryAabbsDataKHR aabbs;
VkAccelerationStructureGeometryInstancesDataKHR instances;
} VkAccelerationStructureGeometryDataKHR;
-
trianglesis a VkAccelerationStructureGeometryTrianglesDataKHR structure. -
aabbsis a VkAccelerationStructureGeometryAabbsDataKHR struture. -
instancesis a VkAccelerationStructureGeometryInstancesDataKHR structure.
The VkAccelerationStructureGeometryTrianglesDataKHR structure is
defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryTrianglesDataKHR {
VkStructureType sType;
const void* pNext;
VkFormat vertexFormat;
VkDeviceOrHostAddressConstKHR vertexData;
VkDeviceSize vertexStride;
uint32_t maxVertex;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexData;
VkDeviceOrHostAddressConstKHR transformData;
} VkAccelerationStructureGeometryTrianglesDataKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexFormatis the VkFormat of each vertex element. -
vertexDatais a device or host address to memory containing vertex data for this geometry. -
maxVertexis the highest index of a vertex that will be addressed by a build command using this structure. -
vertexStrideis the stride in bytes between each vertex. -
indexTypeis the VkIndexType of each index element. -
indexDatais a device or host address to memory containing index data for this geometry. -
transformDatais a device or host address to memory containing an optional reference to a VkTransformMatrixKHR structure describing a transformation from the space in which the vertices in this geometry are described to the space in which the acceleration structure is defined.
|
Note
Unlike the stride for vertex buffers in
VkVertexInputBindingDescription for graphics pipelines which must not
exceed |
The VkAccelerationStructureGeometryMotionTrianglesDataNV structure is
defined as:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureGeometryMotionTrianglesDataNV {
VkStructureType sType;
const void* pNext;
VkDeviceOrHostAddressConstKHR vertexData;
} VkAccelerationStructureGeometryMotionTrianglesDataNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexDatais a pointer to vertex data for this geometry at time 1.0
If VkAccelerationStructureGeometryMotionTrianglesDataNV is included in
the pNext chain of a
VkAccelerationStructureGeometryTrianglesDataKHR structure, the basic
vertex positions are used for the position of the triangles in the geometry
at time 0.0 and the vertexData in
VkAccelerationStructureGeometryMotionTrianglesDataNV is used for the
vertex positions at time 1.0, with positions linearly interpolated at
intermediate times.
Indexing for VkAccelerationStructureGeometryMotionTrianglesDataNV
vertexData is equivalent to the basic vertex position data.
The VkTransformMatrixKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkTransformMatrixKHR {
float matrix[3][4];
} VkTransformMatrixKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkTransformMatrixKHR VkTransformMatrixNV;
-
matrixis a 3x4 row-major affine transformation matrix.
The VkAccelerationStructureGeometryAabbsDataKHR structure is defined
as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryAabbsDataKHR {
VkStructureType sType;
const void* pNext;
VkDeviceOrHostAddressConstKHR data;
VkDeviceSize stride;
} VkAccelerationStructureGeometryAabbsDataKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
datais a device or host address to memory containing VkAabbPositionsKHR structures containing position data for each axis-aligned bounding box in the geometry. -
strideis the stride in bytes between each entry indata. The stride must be a multiple of8.
The VkAabbPositionsKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAabbPositionsKHR {
float minX;
float minY;
float minZ;
float maxX;
float maxY;
float maxZ;
} VkAabbPositionsKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkAabbPositionsKHR VkAabbPositionsNV;
-
minXis the x position of one opposing corner of a bounding box. -
minYis the y position of one opposing corner of a bounding box. -
minZis the z position of one opposing corner of a bounding box. -
maxXis the x position of the other opposing corner of a bounding box. -
maxYis the y position of the other opposing corner of a bounding box. -
maxZis the z position of the other opposing corner of a bounding box.
The VkAccelerationStructureGeometryInstancesDataKHR structure is
defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryInstancesDataKHR {
VkStructureType sType;
const void* pNext;
VkBool32 arrayOfPointers;
VkDeviceOrHostAddressConstKHR data;
} VkAccelerationStructureGeometryInstancesDataKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
arrayOfPointersspecifies whetherdatais used as an array of addresses or just an array. -
datais either the address of an array of device or host addresses referencing individual VkAccelerationStructureInstanceKHR structures or packed motion instance information as described in motion instances ifarrayOfPointersisVK_TRUE, or the address of an array of VkAccelerationStructureInstanceKHR or VkAccelerationStructureMotionInstanceNV structures. Addresses and VkAccelerationStructureInstanceKHR structures are tightly packed. VkAccelerationStructureMotionInstanceNV structures have a stride of 160 bytes.
Acceleration structure instances can be built into top-level acceleration structures. Each acceleration structure instance is a separate entry in the top-level acceleration structure which includes all the geometry of a bottom-level acceleration structure at a transformed location. Multiple instances can point to the same bottom level acceleration structure.
An acceleration structure instance is defined by the structure:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureInstanceKHR {
VkTransformMatrixKHR transform;
uint32_t instanceCustomIndex:24;
uint32_t mask:8;
uint32_t instanceShaderBindingTableRecordOffset:24;
VkGeometryInstanceFlagsKHR flags:8;
uint64_t accelerationStructureReference;
} VkAccelerationStructureInstanceKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkAccelerationStructureInstanceKHR VkAccelerationStructureInstanceNV;
-
transformis a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure. -
instanceCustomIndexis a 24-bit user-specified index value accessible to ray shaders in theInstanceCustomIndexKHRbuilt-in. -
maskis an 8-bit visibility mask for the geometry. The instance may only be hit ifCull Mask & instance.mask != 0 -
instanceShaderBindingTableRecordOffsetis a 24-bit offset used in calculating the hit shader binding table index. -
flagsis an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance. -
accelerationStructureReferenceis either:-
a device address containing the value obtained from vkGetAccelerationStructureDeviceAddressKHR or vkGetAccelerationStructureHandleNV (used by device operations which reference acceleration structures) or,
-
a VkAccelerationStructureKHR object (used by host operations which reference acceleration structures).
-
The C language specification does not define the ordering of bit-fields, but in practice, this struct produces the correct layout with existing compilers. The intended bit pattern is for the following:
-
instanceCustomIndexandmaskoccupy the same memory as if a singleuint32_twas specified in their place-
instanceCustomIndexoccupies the 24 least significant bits of that memory -
maskoccupies the 8 most significant bits of that memory
-
-
instanceShaderBindingTableRecordOffsetandflagsoccupy the same memory as if a singleuint32_twas specified in their place-
instanceShaderBindingTableRecordOffsetoccupies the 24 least significant bits of that memory -
flagsoccupies the 8 most significant bits of that memory
-
If a compiler produces code that diverges from that pattern, applications must employ another method to set values according to the correct bit pattern.
Possible values of flags in the instance modifying the behavior of
that instance are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkGeometryInstanceFlagBitsKHR {
VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR = 0x00000001,
VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHR = 0x00000002,
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR = 0x00000004,
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR = 0x00000008,
VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR = VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV = VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_NV = VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV = VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV = VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR,
} VkGeometryInstanceFlagBitsKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryInstanceFlagBitsKHR VkGeometryInstanceFlagBitsNV;
-
VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHRdisables face culling for this instance. -
VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHRindicates that the facing determination for geometry in this instance is inverted. Because the facing is determined in object space, an instance transform does not change the winding, but a geometry transform does. -
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHRcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-VNoOpaqueKHRray flag. -
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHRcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere not specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-VOpaqueKHRray flag.
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR and
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR must not be used in the
same flag.
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkGeometryInstanceFlagsKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryInstanceFlagsKHR VkGeometryInstanceFlagsNV;
VkGeometryInstanceFlagsKHR is a bitmask type for setting a mask of
zero or more VkGeometryInstanceFlagBitsKHR.
Acceleration structure motion instances can be built into top-level acceleration structures. Each acceleration structure instance is a separate entry in the top-level acceleration structure which includes all the geometry of a bottom-level acceleration structure at a transformed location including a type of motion and parameters to determine the motion of the instance over time.
An acceleration structure motion instance is defined by the structure:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureMotionInstanceNV {
VkAccelerationStructureMotionInstanceTypeNV type;
VkAccelerationStructureMotionInstanceFlagsNV flags;
VkAccelerationStructureMotionInstanceDataNV data;
} VkAccelerationStructureMotionInstanceNV;
-
typeis a VkAccelerationStructureMotionInstanceTypeNV enumerant identifying which type of motion instance this is and which type of the union is valid. -
flagsis currently unused, but is required to keep natural alignment ofdata. -
datais a VkAccelerationStructureMotionInstanceDataNV containing motion instance data for this instance.
|
Note
If writing this other than with a standard C compiler, note that the final structure should be 152 bytes in size. |
Acceleration structure motion instance is defined by the union:
// Provided by VK_NV_ray_tracing_motion_blur
typedef union VkAccelerationStructureMotionInstanceDataNV {
VkAccelerationStructureInstanceKHR staticInstance;
VkAccelerationStructureMatrixMotionInstanceNV matrixMotionInstance;
VkAccelerationStructureSRTMotionInstanceNV srtMotionInstance;
} VkAccelerationStructureMotionInstanceDataNV;
-
staticInstanceis a VkAccelerationStructureInstanceKHR structure containing data for a static instance. -
matrixMotionInstanceis a VkAccelerationStructureMatrixMotionInstanceNV structure containing data for a matrix motion instance. -
srtMotionInstanceis a VkAccelerationStructureSRTMotionInstanceNV structure containing data for an SRT motion instance.
// Provided by VK_NV_ray_tracing_motion_blur
typedef VkFlags VkAccelerationStructureMotionInstanceFlagsNV;
VkAccelerationStructureMotionInstanceFlagsNV is a bitmask type for
setting a mask, but is currently reserved for future use.
The VkAccelerationStructureMotionInstanceTypeNV enumeration is defined
as:
// Provided by VK_NV_ray_tracing_motion_blur
typedef enum VkAccelerationStructureMotionInstanceTypeNV {
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_STATIC_NV = 0,
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_MATRIX_MOTION_NV = 1,
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_SRT_MOTION_NV = 2,
} VkAccelerationStructureMotionInstanceTypeNV;
-
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_STATIC_NVspecifies that the instance is a static instance with no instance motion. -
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_MATRIX_MOTION_NVspecifies that the instance is a motion instance with motion specified by interpolation between two matrices. -
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_SRT_MOTION_NVspecifies that the instance is a motion instance with motion specified by interpolation in the SRT decomposition.
An acceleration structure matrix motion instance is defined by the structure:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureMatrixMotionInstanceNV {
VkTransformMatrixKHR transformT0;
VkTransformMatrixKHR transformT1;
uint32_t instanceCustomIndex:24;
uint32_t mask:8;
uint32_t instanceShaderBindingTableRecordOffset:24;
VkGeometryInstanceFlagsKHR flags:8;
uint64_t accelerationStructureReference;
} VkAccelerationStructureMatrixMotionInstanceNV;
-
transformT0is a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure at time 0. -
transformT1is a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure at time 1. -
instanceCustomIndexis a 24-bit user-specified index value accessible to ray shaders in theInstanceCustomIndexKHRbuilt-in. -
maskis an 8-bit visibility mask for the geometry. The instance may only be hit ifCull Mask & instance.mask != 0 -
instanceShaderBindingTableRecordOffsetis a 24-bit offset used in calculating the hit shader binding table index. -
flagsis an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance. -
accelerationStructureReferenceis either:-
a device address containing the value obtained from vkGetAccelerationStructureDeviceAddressKHR or vkGetAccelerationStructureHandleNV (used by device operations which reference acceleration structures) or,
-
a VkAccelerationStructureKHR object (used by host operations which reference acceleration structures).
-
The C language specification does not define the ordering of bit-fields, but in practice, this struct produces the correct layout with existing compilers. The intended bit pattern is for the following:
-
instanceCustomIndexandmaskoccupy the same memory as if a singleuint32_twas specified in their place-
instanceCustomIndexoccupies the 24 least significant bits of that memory -
maskoccupies the 8 most significant bits of that memory
-
-
instanceShaderBindingTableRecordOffsetandflagsoccupy the same memory as if a singleuint32_twas specified in their place-
instanceShaderBindingTableRecordOffsetoccupies the 24 least significant bits of that memory -
flagsoccupies the 8 most significant bits of that memory
-
If a compiler produces code that diverges from that pattern, applications must employ another method to set values according to the correct bit pattern.
The transform for a matrix motion instance at a point in time is derived by
component-wise linear interpolation of the two transforms.
That is, for a time in [0,1] the resulting transform is
-
transformT0× (1 -time) +transformT1×time
An acceleration structure SRT motion instance is defined by the structure:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureSRTMotionInstanceNV {
VkSRTDataNV transformT0;
VkSRTDataNV transformT1;
uint32_t instanceCustomIndex:24;
uint32_t mask:8;
uint32_t instanceShaderBindingTableRecordOffset:24;
VkGeometryInstanceFlagsKHR flags:8;
uint64_t accelerationStructureReference;
} VkAccelerationStructureSRTMotionInstanceNV;
-
transformT0is a VkSRTDataNV structure describing a transformation to be applied to the acceleration structure at time 0. -
transformT1is a VkSRTDataNV structure describing a transformation to be applied to the acceleration structure at time 1. -
instanceCustomIndexis a 24-bit user-specified index value accessible to ray shaders in theInstanceCustomIndexKHRbuilt-in. -
maskis an 8-bit visibility mask for the geometry. The instance may only be hit ifCull Mask & instance.mask != 0 -
instanceShaderBindingTableRecordOffsetis a 24-bit offset used in calculating the hit shader binding table index. -
flagsis an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance. -
accelerationStructureReferenceis either:-
a device address containing the value obtained from vkGetAccelerationStructureDeviceAddressKHR or vkGetAccelerationStructureHandleNV (used by device operations which reference acceleration structures) or,
-
a VkAccelerationStructureKHR object (used by host operations which reference acceleration structures).
-
The C language specification does not define the ordering of bit-fields, but in practice, this struct produces the correct layout with existing compilers. The intended bit pattern is for the following:
-
instanceCustomIndexandmaskoccupy the same memory as if a singleuint32_twas specified in their place-
instanceCustomIndexoccupies the 24 least significant bits of that memory -
maskoccupies the 8 most significant bits of that memory
-
-
instanceShaderBindingTableRecordOffsetandflagsoccupy the same memory as if a singleuint32_twas specified in their place-
instanceShaderBindingTableRecordOffsetoccupies the 24 least significant bits of that memory -
flagsoccupies the 8 most significant bits of that memory
-
If a compiler produces code that diverges from that pattern, applications must employ another method to set values according to the correct bit pattern.
The transform for a SRT motion instance at a point in time is derived from
component-wise linear interpolation of the two SRT transforms.
That is, for a time in [0,1] the resulting transform is
-
transformT0× (1 -time) +transformT1×time
An acceleration structure SRT transform is defined by the structure:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkSRTDataNV {
float sx;
float a;
float b;
float pvx;
float sy;
float c;
float pvy;
float sz;
float pvz;
float qx;
float qy;
float qz;
float qw;
float tx;
float ty;
float tz;
} VkSRTDataNV;
-
sxis the x component of the scale of the transform -
ais one component of the shear for the transform -
bis one component of the shear for the transform -
pvxis the x component of the pivot point of the transform -
syis the y component of the scale of the transform -
cis one component of the shear for the transform -
pvyis the y component of the pivot point of the transform -
szis the z component of the scale of the transform -
pvzis the z component of the pivot point of the transform -
qxis the x component of the rotation quaternion -
qyis the y component of the rotation quaternion -
qzis the z component of the rotation quaternion -
qwis the w component of the rotation quaternion -
txis the x component of the post-rotation translation -
tyis the y component of the post-rotation translation -
tzis the z component of the post-rotation translation
This transform decomposition consists of three elements. The first is a matrix S, consisting of a scale, shear, and translation, usually used to define the pivot point of the following rotation. This matrix is constructed from the parameters above by:
The rotation quaternion is defined as:
-
R= [qx,qy,qz,qw]
This is a rotation around a conceptual normalized axis [ ax, ay, az ]
of amount theta such that:
-
[
qx,qy,qz] = sin(theta/2) × [ax,ay,az]
and
-
qw= cos(theta/2)
Finally, the transform has a translation T constructed from the parameters above by:
The effective derived transform is then given by
-
T×R×S
VkAccelerationStructureBuildRangeInfoKHR is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureBuildRangeInfoKHR {
uint32_t primitiveCount;
uint32_t primitiveOffset;
uint32_t firstVertex;
uint32_t transformOffset;
} VkAccelerationStructureBuildRangeInfoKHR;
-
primitiveCountdefines the number of primitives for a corresponding acceleration structure geometry. -
primitiveOffsetdefines an offset in bytes into the memory where primitive data is defined. -
firstVertexis the index of the first vertex to build from for triangle geometry. -
transformOffsetdefines an offset in bytes into the memory where a transform matrix is defined.
The primitive count and primitive offset are interpreted differently depending on the VkGeometryTypeKHR used:
-
For geometries of type
VK_GEOMETRY_TYPE_TRIANGLES_KHR,primitiveCountis the number of triangles to be built, where each triangle is treated as 3 vertices.-
If the geometry uses indices,
primitiveCount× 3 indices are consumed from VkAccelerationStructureGeometryTrianglesDataKHR::indexData, starting at an offset ofprimitiveOffset. The value offirstVertexis added to the index values before fetching vertices. -
If the geometry does not use indices,
primitiveCount× 3 vertices are consumed from VkAccelerationStructureGeometryTrianglesDataKHR::vertexData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometryTrianglesDataKHR::vertexStride×firstVertex. -
If VkAccelerationStructureGeometryTrianglesDataKHR::
transformDatais notNULL, a single VkTransformMatrixKHR structure is consumed from VkAccelerationStructureGeometryTrianglesDataKHR::transformData, at an offset oftransformOffset. This matrix describes a transformation from the space in which the vertices for all triangles in this geometry are described to the space in which the acceleration structure is defined.
-
-
For geometries of type
VK_GEOMETRY_TYPE_AABBS_KHR,primitiveCountis the number of axis-aligned bounding boxes.primitiveCountVkAabbPositionsKHR structures are consumed from VkAccelerationStructureGeometryAabbsDataKHR::data, starting at an offset ofprimitiveOffset. -
For geometries of type
VK_GEOMETRY_TYPE_INSTANCES_KHR,primitiveCountis the number of acceleration structures.primitiveCountVkAccelerationStructureInstanceKHR or VkAccelerationStructureMotionInstanceNV structures are consumed from VkAccelerationStructureGeometryInstancesDataKHR::data, starting at an offset ofprimitiveOffset.
36.1.7. Copying Acceleration Structures
An additional command exists for copying acceleration structures without updating their contents. The acceleration structure object can be compacted in order to improve performance. Before copying, an application must query the size of the resulting acceleration structure.
To query acceleration structure size parameters call:
// Provided by VK_KHR_acceleration_structure
void vkCmdWriteAccelerationStructuresPropertiesKHR(
VkCommandBuffer commandBuffer,
uint32_t accelerationStructureCount,
const VkAccelerationStructureKHR* pAccelerationStructures,
VkQueryType queryType,
VkQueryPool queryPool,
uint32_t firstQuery);
-
commandBufferis the command buffer into which the command will be recorded. -
accelerationStructureCountis the count of acceleration structures for which to query the property. -
pAccelerationStructuresis a pointer to an array of existing previously built acceleration structures. -
queryTypeis a VkQueryType value specifying the type of queries managed by the pool. -
queryPoolis the query pool that will manage the results of the query. -
firstQueryis the first query index within the query pool that will contain theaccelerationStructureCountnumber of results.
Accesses to any of the acceleration structures listed in
pAccelerationStructures must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR.
-
If
queryTypeisVK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then the value written out is the number of bytes required by a compacted acceleration structure. -
If
queryTypeisVK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then the value written out is the number of bytes required by a serialized acceleration structure.
To query acceleration structure size parameters call:
// Provided by VK_NV_ray_tracing
void vkCmdWriteAccelerationStructuresPropertiesNV(
VkCommandBuffer commandBuffer,
uint32_t accelerationStructureCount,
const VkAccelerationStructureNV* pAccelerationStructures,
VkQueryType queryType,
VkQueryPool queryPool,
uint32_t firstQuery);
-
commandBufferis the command buffer into which the command will be recorded. -
accelerationStructureCountis the count of acceleration structures for which to query the property. -
pAccelerationStructuresis a pointer to an array of existing previously built acceleration structures. -
queryTypeis a VkQueryType value specifying the type of queries managed by the pool. -
queryPoolis the query pool that will manage the results of the query. -
firstQueryis the first query index within the query pool that will contain theaccelerationStructureCountnumber of results.
Accesses to any of the acceleration structures listed in
pAccelerationStructures must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR.
To copy an acceleration structure call:
// Provided by VK_NV_ray_tracing
void vkCmdCopyAccelerationStructureNV(
VkCommandBuffer commandBuffer,
VkAccelerationStructureNV dst,
VkAccelerationStructureNV src,
VkCopyAccelerationStructureModeKHR mode);
-
commandBufferis the command buffer into which the command will be recorded. -
dstis the target acceleration structure for the copy. -
srcis the source acceleration structure for the copy. -
modeis a VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy.
Accesses to src and dst must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate.
To copy an acceleration structure call:
// Provided by VK_KHR_acceleration_structure
void vkCmdCopyAccelerationStructureKHR(
VkCommandBuffer commandBuffer,
const VkCopyAccelerationStructureInfoKHR* pInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pInfois a pointer to a VkCopyAccelerationStructureInfoKHR structure defining the copy operation.
This command copies the pInfo->src acceleration structure to the
pInfo->dst acceleration structure in the manner specified by
pInfo->mode.
Accesses to pInfo->src and pInfo->dst must be
synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate.
The VkCopyAccelerationStructureInfoKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkCopyAccelerationStructureInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureKHR src;
VkAccelerationStructureKHR dst;
VkCopyAccelerationStructureModeKHR mode;
} VkCopyAccelerationStructureInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcis the source acceleration structure for the copy. -
dstis the target acceleration structure for the copy. -
modeis a VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy.
Possible values of mode specifying additional operations to perform
during the copy, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkCopyAccelerationStructureModeKHR {
VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR = 0,
VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR = 1,
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR = 2,
VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR = 3,
// Provided by VK_NV_ray_tracing
VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NV = VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR,
// Provided by VK_NV_ray_tracing
VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV = VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR,
} VkCopyAccelerationStructureModeKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkCopyAccelerationStructureModeKHR VkCopyAccelerationStructureModeNV;
-
VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHRcreates a direct copy of the acceleration structure specified insrcinto the one specified bydst. Thedstacceleration structure must have been created with the same parameters assrc. Ifsrccontains references to other acceleration structures,dstwill reference the same acceleration structures. -
VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHRcreates a more compact version of an acceleration structuresrcintodst. The acceleration structuredstmust have been created with a size at least as large as that returned by vkCmdWriteAccelerationStructuresPropertiesKHR or vkWriteAccelerationStructuresPropertiesKHR after the build of the acceleration structure specified bysrc. Ifsrccontains references to other acceleration structures,dstwill reference the same acceleration structures. -
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHRserializes the acceleration structure to a semi-opaque format which can be reloaded on a compatible implementation. -
VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHRdeserializes the semi-opaque serialization format in the buffer to the acceleration structure.
To copy an acceleration structure to device memory call:
// Provided by VK_KHR_acceleration_structure
void vkCmdCopyAccelerationStructureToMemoryKHR(
VkCommandBuffer commandBuffer,
const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pInfois an a pointer to a VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.
Accesses to pInfo->src must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR.
Accesses to the buffer indicated by pInfo->dst.deviceAddress must be
synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage
and an access type of VK_ACCESS_TRANSFER_WRITE_BIT.
This command produces the same results as vkCopyAccelerationStructureToMemoryKHR, but writes its result to a device address, and is executed on the device rather than the host. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToAccelerationStructureKHR or vkCopyMemoryToAccelerationStructureKHR.
The defined header structure for the serialized data consists of:
-
VK_UUID_SIZEbytes of data matchingVkPhysicalDeviceIDProperties::driverUUID -
VK_UUID_SIZEbytes of data identifying the compatibility for comparison using vkGetDeviceAccelerationStructureCompatibilityKHR -
A 64-bit integer of the total size matching the value queried using
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR -
A 64-bit integer of the deserialized size to be passed in to
VkAccelerationStructureCreateInfoKHR::size -
A 64-bit integer of the count of the number of acceleration structure handles following. This value matches the value queried using
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR. This will be zero for a bottom-level acceleration structure. For top-level acceleration structures this number is implementation-dependent; the number of and ordering of the handles may not match the instance descriptions which were used to build the acceleration structure.
The corresponding handles matching the values returned by vkGetAccelerationStructureDeviceAddressKHR or vkGetAccelerationStructureHandleNV are tightly packed in the buffer following the count. The application is expected to store a mapping between those handles and the original application-generated bottom-level acceleration structures to provide when deserializing. The serialized data is written to the buffer (or read from the buffer) according to the host endianness.
// Provided by VK_KHR_acceleration_structure
typedef struct VkCopyAccelerationStructureToMemoryInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureKHR src;
VkDeviceOrHostAddressKHR dst;
VkCopyAccelerationStructureModeKHR mode;
} VkCopyAccelerationStructureToMemoryInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcis the source acceleration structure for the copy -
dstis the device or host address to memory which is the target for the copy -
modeis a VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy.
To copy device memory to an acceleration structure call:
// Provided by VK_KHR_acceleration_structure
void vkCmdCopyMemoryToAccelerationStructureKHR(
VkCommandBuffer commandBuffer,
const VkCopyMemoryToAccelerationStructureInfoKHR* pInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pInfois a pointer to a VkCopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation.
Accesses to pInfo->dst must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.
Accesses to the buffer indicated by pInfo->src.deviceAddress must be
synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage
and an access type of VK_ACCESS_TRANSFER_READ_BIT.
This command can accept acceleration structures produced by either vkCmdCopyAccelerationStructureToMemoryKHR or vkCopyAccelerationStructureToMemoryKHR.
The structure provided as input to deserialize is as described in vkCmdCopyAccelerationStructureToMemoryKHR, with any acceleration structure handles filled in with the newly-queried handles to bottom level acceleration structures created before deserialization. These do not need to be built at deserialize time, but must be created.
The VkCopyMemoryToAccelerationStructureInfoKHR structure is defined
as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkCopyMemoryToAccelerationStructureInfoKHR {
VkStructureType sType;
const void* pNext;
VkDeviceOrHostAddressConstKHR src;
VkAccelerationStructureKHR dst;
VkCopyAccelerationStructureModeKHR mode;
} VkCopyMemoryToAccelerationStructureInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcis the device or host address to memory containing the source data for the copy. -
dstis the target acceleration structure for the copy. -
modeis a VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy.
To check if a serialized acceleration structure is compatible with the current device call:
// Provided by VK_KHR_acceleration_structure
void vkGetDeviceAccelerationStructureCompatibilityKHR(
VkDevice device,
const VkAccelerationStructureVersionInfoKHR* pVersionInfo,
VkAccelerationStructureCompatibilityKHR* pCompatibility);
-
deviceis the device to check the version against. -
pVersionInfois a pointer to a VkAccelerationStructureVersionInfoKHR structure specifying version information to check against the device. -
pCompatibilityis a pointer to a VkAccelerationStructureCompatibilityKHR value in which compatibility information is returned.
The VkAccelerationStructureVersionInfoKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureVersionInfoKHR {
VkStructureType sType;
const void* pNext;
const uint8_t* pVersionData;
} VkAccelerationStructureVersionInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pVersionDatais a pointer to the version header of an acceleration structure as defined in vkCmdCopyAccelerationStructureToMemoryKHR
|
Note
|
Possible values of pCompatibility returned by
vkGetDeviceAccelerationStructureCompatibilityKHR are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureCompatibilityKHR {
VK_ACCELERATION_STRUCTURE_COMPATIBILITY_COMPATIBLE_KHR = 0,
VK_ACCELERATION_STRUCTURE_COMPATIBILITY_INCOMPATIBLE_KHR = 1,
} VkAccelerationStructureCompatibilityKHR;
-
VK_ACCELERATION_STRUCTURE_COMPATIBILITY_COMPATIBLE_KHRif thepVersionDataversion acceleration structure is compatible withdevice. -
VK_ACCELERATION_STRUCTURE_COMPATIBILITY_INCOMPATIBLE_KHRif thepVersionDataversion acceleration structure is not compatible withdevice.
36.2. Host Acceleration Structure Operations
Implementations are also required to provide host implementations of the
acceleration structure operations if the
accelerationStructureHostCommands feature is enabled:
-
vkBuildAccelerationStructuresKHR corresponding to vkCmdBuildAccelerationStructuresKHR
-
vkCopyAccelerationStructureKHR corresponding to vkCmdCopyAccelerationStructureKHR
-
vkCopyAccelerationStructureToMemoryKHR corresponding to vkCmdCopyAccelerationStructureToMemoryKHR
-
vkCopyMemoryToAccelerationStructureKHR corresponding to vkCmdCopyMemoryToAccelerationStructureKHR
-
vkWriteAccelerationStructuresPropertiesKHR corresponding to vkCmdWriteAccelerationStructuresPropertiesKHR
These commands are functionally equivalent to their device counterparts, except that they are executed on the host timeline, rather than being enqueued into command buffers.
All acceleration structures used by the host commands must be bound to host-visible memory, and all input data for acceleration structure builds must be referenced using host addresses instead of device addresses. Applications are not required to map acceleration structure memory when using the host commands.
|
Note
The vkBuildAccelerationStructuresKHR and vkCmdBuildAccelerationStructuresKHR may use different algorithms, and thus are not required to produce identical structures. The structures produced by these two commands may exhibit different memory footprints or traversal performance, but should strive to be similar where possible. Apart from these details, the host and device operations are interchangable. For example, an application can use vkBuildAccelerationStructuresKHR to build a structure, compact it on the device using vkCmdCopyAccelerationStructureKHR, and serialize the result using vkCopyAccelerationStructureToMemoryKHR. |
|
Note
For efficient execution, acceleration structures manipulated using these commands should always be bound to host cached memory, as the implementation may need to repeatedly read and write this memory during the execution of the command. |
To build acceleration structures on the host, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkBuildAccelerationStructuresKHR(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
uint32_t infoCount,
const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
const VkAccelerationStructureBuildRangeInfoKHR* const* ppBuildRangeInfos);
-
deviceis theVkDevicefor which the acceleration structures are being built. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
infoCountis the number of acceleration structures to build. It specifies the number of thepInfosstructures andppBuildRangeInfospointers that must be provided. -
pInfosis a pointer to an array ofinfoCountVkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. -
ppBuildRangeInfosis a pointer to an array ofinfoCountpointers to arrays of VkAccelerationStructureBuildRangeInfoKHR structures. EachppBuildRangeInfos[i] is a pointer to an array ofpInfos[i].geometryCountVkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfos[i].
This command fulfills the same task as vkCmdBuildAccelerationStructuresKHR but is executed by the host.
The vkBuildAccelerationStructuresKHR command provides the ability to
initiate multiple acceleration structures builds, however there is no
ordering or synchronization implied between any of the individual
acceleration structure builds.
|
Note
This means that an application cannot build a top-level acceleration structure in the same vkBuildAccelerationStructuresKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds. |
To copy or compact an acceleration structure on the host, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkCopyAccelerationStructureKHR(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
const VkCopyAccelerationStructureInfoKHR* pInfo);
-
deviceis the device which owns the acceleration structures. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
pInfois a pointer to a VkCopyAccelerationStructureInfoKHR structure defining the copy operation.
This command fulfills the same task as vkCmdCopyAccelerationStructureKHR but is executed by the host.
To copy host accessible memory to an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkCopyMemoryToAccelerationStructureKHR(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
const VkCopyMemoryToAccelerationStructureInfoKHR* pInfo);
-
deviceis the device which ownspInfo->dst. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
pInfois a pointer to a VkCopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation.
This command fulfills the same task as vkCmdCopyMemoryToAccelerationStructureKHR but is executed by the host.
This command can accept acceleration structures produced by either vkCmdCopyAccelerationStructureToMemoryKHR or vkCopyAccelerationStructureToMemoryKHR.
To copy an acceleration structure to host accessible memory, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkCopyAccelerationStructureToMemoryKHR(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);
-
deviceis the device which ownspInfo->src. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
pInfois a pointer to a VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.
This command fulfills the same task as vkCmdCopyAccelerationStructureToMemoryKHR but is executed by the host.
This command produces the same results as vkCmdCopyAccelerationStructureToMemoryKHR, but writes its result directly to a host pointer, and is executed on the host rather than the device. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToAccelerationStructureKHR or vkCopyMemoryToAccelerationStructureKHR.
To query acceleration structure size parameters on the host, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkWriteAccelerationStructuresPropertiesKHR(
VkDevice device,
uint32_t accelerationStructureCount,
const VkAccelerationStructureKHR* pAccelerationStructures,
VkQueryType queryType,
size_t dataSize,
void* pData,
size_t stride);
-
deviceis the device which owns the acceleration structures inpAccelerationStructures. -
accelerationStructureCountis the count of acceleration structures for which to query the property. -
pAccelerationStructuresis a pointer to an array of existing previously built acceleration structures. -
queryTypeis a VkQueryType value specifying the property to be queried. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to a user-allocated buffer where the results will be written. -
strideis the stride in bytes between results for individual queries withinpData.
This command fulfills the same task as vkCmdWriteAccelerationStructuresPropertiesKHR but is executed by the host.
37. Ray Traversal
The ray traversal process identifies and handles intersections between a ray and geometries in an acceleration structure.
Ray traversal cannot be started by a Vulkan API command directly - a shader
must execute
OpRayQueryProceedKHR
or
OpTraceRayKHR
.
When the rayTracingPipeline feature
is enabled, OpTraceRayKHR can be used for ray tracing
in a ray tracing pipeline.
When the rayQuery feature is enabled,
OpRayQueryProceedKHR can be used in any shader stage.
37.1. Ray Intersection Candidate Determination
Once tracing begins, rays are first tested against instances in a top-level acceleration structure. A ray that intersects an instance will be transformed into the space of the instance to continue traversal within that instance; therefore the transform matrix stored in the instance must be invertible.
Next, rays are tested against geometries in an bottom-level acceleration structure to determine if a hit occurred between them, initially based only on their geometric properties (i.e. their vertices). The implementation performs similar operations to that of rasterization, but with the effective viewport determined by the parameters of the ray, and the geometry transformed into a space determined by that viewport.
The vertices of each primitive are transformed from acceleration structure space as to ray space r according to the ray origin and direction as follows:
is the axis of rotation from the unnormalized ray direction vector to the axis vector :
and are the sine and cosine of the angle of rotation about from to :
is the unit vector:
and are the ray origin and unnormalized direction, respectively; the vector described by xas, yas, and zas is any position in acceleration structure space; and the vector described by xr, yr, and zr is the same position in ray space.
An intersection candidate is a unique point of intersection between a ray and a geometric primitive. For any primitive that has within its bounds a position such that
(where ), an intersection candidate exists.
Triangle primitive bounds consist of all points on the plane formed by the three vertices and within the bounds of the edges between the vertices, subject to the watertightness constraints below. AABB primitive bounds consist of all points within an implementation-defined bound which includes the specified box.
|
Note
The bounds of the AABB including all points internal to the bound implies that a ray started within the AABB will hit that AABB. |
The determination of this condition is performed in an implementation specific manner, and may be performed with floating point operations. Due to the complexity and number of operations involved, inaccuracies are expected, particularly as the scale of values involved begins to diverge. Implementations should take efforts to maintain as much precision as possible.
|
Note
One very common case is when geometries are close to each other at some distance from the origin in acceleration structure space, where an effect similar to “z-fighting” is likely to be observed. Applications can mitigate this by ensuring their detailed geometries remain close to the origin. Another likely case is when the origin of a ray is set to a position on a previously intersected surface, and its tmin is zero or near zero; an intersection may be detected on the emitting surface. This case can usually be mitigated by offsetting tmin slightly. |
For a motion primitive or a motion instance, the positions for intersection
are evaluated at the time specified in the time parameter to
OpTraceRayMotionNV by interpolating between the two endpoints as
specified for the given motion type.
If a motion acceleration structure is traced with OpTraceRayKHR, it
behaves as a OpTraceRayMotionNV with time of 0.0.
In the case of AABB geometries, implementations may increase their size in an acceleration structure in order to mitigate precision issues. This may result in false positive intersections being reported to the application.
For triangle intersection candidates, the b and c
barycentric coordinates on the triangle
where the above condition is met are made available to future shading.
If the ray was traced with OpTraceRayKHR, these values are available as
a vector of 2 32-bit floating point values in the HitAttributeKHR
storage class.
Once an intersection candidate is determined, it proceeds through the following operations, in order:
The sections below describe the exact details of these tests. There is no ordering guarantee between operations performed on different intersection candidates.
37.1.1. Watertightness
For a set of triangles with identical transforms, within a single instance:
-
Any set of two or more triangles where all triangles have one vertex with an identical position value, that vertex is a shared vertex.
-
Any set of two triangles with two shared vertices that were specified in the same winding order in each triangle have a shared edge defined by those vertices.
A closed fan is a set of three or more triangles where:
-
All triangles in the set have the same shared vertex as one of their vertices.
-
All edges that include the above vertex are shared edges.
-
All above shared edges are shared by exactly two triangles from the set.
-
No two triangles in the set intersect, except at shared edges.
-
Every triangle in the set is joined to every other triangle in the set by a series of the above shared edges.
Implementations should not double-hit or miss when a ray intersects a shared edge, or a shared vertex of a closed fan.
37.2. Ray Intersection Culling
Candidate intersections go through several phases of culling before confirmation as an actual hit. There is no particular ordering dependency between the different culling operations.
37.2.1. Ray Primitive Culling
If the rayTraversalPrimitiveCulling or rayQuery features are enabled, the SkipTrianglesKHR and
SkipAABBsKHR ray flags can be specified when tracing a ray.
SkipTrianglesKHR and SkipAABBsKHR are mutually exclusive.
SkipTrianglesKHR is also mutually exclusive with
CullBackFacingTrianglesKHR and CullFrontFacingTrianglesKHR.
If SkipTrianglesKHR was included in the Ray Flags operand of the ray
trace instruction, and the intersection is with a triangle primitive, the
intersection is dropped, and no further processing of this intersection
occurs.
If VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR was included
in the pipeline, traversal with OpTraceRayKHR calls will all behave as
if SkipTrianglesKHR was included in its Ray Flags operand.
If SkipAABBsKHR was included in the Ray Flags operand of the ray
trace instruction, and the intersection is with an AABB primitive, the
intersection is dropped, and no further processing of this intersection
occurs.
If VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR was included in
the pipeline, traversal with OpTraceRayKHR calls will all behave as if
SkipAABBsKHR was included in its Ray Flags operand.
37.2.2. Ray Mask Culling
Instances can be made invisible to particular rays based on the value of
VkAccelerationStructureInstanceKHR::mask used to add that
instance to a top-level acceleration structure, and the Cull Mask
parameter used to trace the ray.
For the instance which is intersected, if mask & Cull Mask ==
0, the intersection is dropped, and no further processing occurs.
37.2.3. Ray Face Culling
As in polygon rasterization, one of the stages of ray traversal is to determine if a triangle primitive is back- or front-facing, and primitives can be culled based on that facing.
If the intersection candidate is with an AABB primitive, this operation is skipped.
When a ray intersects a triangle primitive, the order that vertices are specified for the polygon affects whether the ray intersects the front or back face. Front or back facing is determined in the same way as they are for rasterization, based on the sign of the polygon’s area but using the ray space coordinates instead of framebuffer coordinates. One way to compute this area is:
where and are the x and y ray space coordinates of the ith vertex of the n-vertex polygon (vertices are numbered starting at zero for the purposes of this computation) and i ⊕ 1 is (i + 1) mod n.
By default, if a is negative then the intersection is with the front
face of the triangle, otherwise it is with the back face.
If VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHR is included in
VkAccelerationStructureInstanceKHR::flags for the instance
containing the intersected triangle, this determination is reversed.
Additionally, if a is 0, the intersection candidate is treated as not
intersecting with any face, irrespective of the sign.
|
Note
In a left-handed coordinate system, an intersection will be with the front
face of a triangle if the vertices of the triangle, as defined in index
order, appear from the ray’s perspective in a clockwise rotation order.
|
If the ray was traced with OpTraceRayKHR, the HitKindKHR built-in
is set to HitKindFrontFacingTriangleKHR if the intersection is with
front-facing geometry, and HitKindBackFacingTriangleKHR if the
intersection is with back-facing geometry, for shader stages considering
this intersection.
If the ray was traced with OpRayQueryProceedKHR,
OpRayQueryGetIntersectionFrontFaceKHR will return true for intersection
candidates with front faces, or false for back faces.
If CullBackFacingTrianglesKHR was included in the Ray Flags parameter
of the ray trace instruction, and the intersection is determined as with the
back face of a triangle primitive, the intersection is dropped, and no
further processing of this intersection occurs.
If CullFrontFacingTrianglesKHR was included in the Ray Flags
parameter of the ray trace instruction, and the intersection is determined
as with the front face of a triangle primitive, the intersection is dropped,
and no further processing of this intersection occurs.
This culling is disabled if
VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR was included
in VkAccelerationStructureInstanceKHR::flags for the instance
which the intersected geometry belongs to.
Intersection candidates that have not intersected with any face (a == 0) are unconditionally culled, irrespective of ray flags and geometry instance flags.
The CullBackFacingTrianglesKHR and CullFrontFacingTrianglesKHR
Ray Flags are mutually exclusive.
37.2.4. Ray Opacity Culling
Each geometry in the acceleration structure may be considered either opaque or not. Opaque geometries continue through traversal as normal, whereas non-opaque geometries need to be either confirmed or discarded by shader code. Intersection candidates can also be culled based on their opacity.
Each individual intersection candidate is initally determined as opaque if
VK_GEOMETRY_OPAQUE_BIT_KHR was included in the
VkAccelerationStructureGeometryKHR::flags when the geometry it
intersected with was built, otherwise it is considered non-opaque.
If the intersection candidate was generated by an intersection shader, the intersection is initially considered to have opacity matching the AABB candidate that it was generated from.
However, this opacity can be overridden when it is built into an instance.
Setting VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR in
VkAccelerationStructureInstanceKHR::flags will force all
geometries in the instance to be considered opaque.
Similarly, setting VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR will
force all geometries in the instance to be considered non-opaque.
This can again be overridden by including OpaqueKHR or NoOpaqueKHR
in the Ray Flags parameter when tracing a ray.
OpaqueKHR forces all geometries to behave as if they are opaque,
regardless of their build parameters.
Similarly, NoOpaqueKHR forces all geometries to behave as if they are
non-opaque.
If the ray was traced with OpRayQueryProceedKHR, to determine the
opacity of AABB intersection candidates,
OpRayQueryGetIntersectionCandidateAABBOpaqueKHR can be used.
This instruction will return true for opaque intersection candidates,
and false for non-opaque intersection candidates.
If CullOpaqueKHR is included in the Ray Flags parameter when tracing
a ray, an intersection with a geometry that is considered opaque is dropped,
and no further processing occurs.
If CullNoOpaqueKHR is included in the Ray Flags parameter when
tracing a ray, an intersection with a geometry that is considered non-opaque
is dropped, and no further processing occurs.
The OpaqueKHR, NoOpaqueKHR, CullOpaqueKHR, and
CullNoOpaqueKHR Ray Flags are mutually exclusive.
37.3. Ray Intersection Confirmation
Depending on the opacity of intersected geometry and whether it is a triangle or an AABB, candidate intersections are further processed to determine the eventual hit result. Candidates generated from AABB intersections run through the same confirmation process as triangle hits.
37.3.1. AABB Intersection Candidates
For an intersection candidate with an AABB geometry generated by Ray Intersection Candidate Determination, shader code is executed to determine whether any hits should be reported to the traversal infrastructure; no further processing of this intersection candidate occurs. The occurrence of an AABB intersection candidate does not guarantee the ray intersects the primitive bounds. To avoid propagating false intersections the application should verify the intersection candidate before reporting any hits.
If the ray was traced with OpTraceRayKHR, an intersection shader is invoked from the Shader Binding Table according
to the specified indexing for the
intersected geometry.
If this shader calls OpReportIntersectionKHR, a new intersection
candidate is generated as described
below.
If the intersection shader is VK_SHADER_UNUSED_KHR (which is only
allowed for a zero shader group) then no further processing of the
intersection candidate occurs.
Each new candidate generated as a result of this processing is a generated
intersection candidate that intersects the AABB geometry, with a t
value equal to the Hit parameter of the OpReportIntersectionKHR
instruction.
The new generated candidate is then independently run through
Ray Intersection Confirmation as a
generated
intersection.
If the ray was traced with OpRayQueryProceedKHR, control is returned to
the shader which executed OpRayQueryProceedKHR, returning true.
The resulting ray query has a candidate intersection type of
RayQueryCandidateIntersectionAABBKHR.
OpRayQueryGenerateIntersectionKHR can be called to commit a new
intersection candidate with committed intersection type of
RayQueryCommittedIntersectionGeneratedKHR.
Further ray query processing can be continued by executing
OpRayQueryProceedKHR with the same ray query, or intersection can be
terminated with OpRayQueryTerminateKHR.
Unlike rays traced with OpTraceRayKHR, candidates generated in this way
skip generated intersection candidate confirmation; applications should
make this determination before generating the intersection.
This operation may be executed multiple times for the same intersection candidate.
37.3.2. Triangle and Generated Intersection Candidates
For triangle and generated intersection candidates, additional shader code may be executed based on the intersection’s opacity.
If the intersection is opaque, the candidate is immediately confirmed as a valid hit and passes to the next stage of processing.
For non-opaque intersection candidates, shader code is executed to determine whether a hit occurred or not.
If the ray was traced with OpTraceRayKHR, an any-hit
shader is invoked from the Shader Binding Table according to the
specified indexing.
If this shader calls OpIgnoreIntersectionKHR, the candidate is dropped
and no further processing of the candidate occurs.
If the any-hit shader identified is
VK_SHADER_UNUSED_KHR, the candidate is immediately confirmed as a
valid hit and passes to the next stage of processing.
If the ray was traced with OpRayQueryProceedKHR, control is returned to
the shader which executed OpRayQueryProceedKHR, returning true.
As only triangle candidates participate in this operation with ray queries,
the resulting candidate intersection type is always
RayQueryCandidateIntersectionTriangleKHR.
OpRayQueryConfirmIntersectionKHR can be called on the ray query to
confirm the candidate as a hit with committed intersection type of
RayQueryCommittedIntersectionTriangleKHR.
Further ray query processing can be continued by executing
OpRayQueryProceedKHR with the same ray query, or intersection can be
terminated with OpRayQueryTerminateKHR.
If OpRayQueryConfirmIntersectionKHR has not been executed, the
candidate is dropped and no further processing of the candidate occurs.
This operation may be executed multiple times for the same intersection
candidate unless VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR
was specified for the intersected geometry.
37.4. Ray Closest Hit Determination
Unless the ray was traced with the TerminateOnFirstHitKHR ray flag, the
implementation must track the closest confirmed hit until all geometries
have been tested and either confirmed or dropped.
After an intersection candidate is confirmed, its t value is compared to tmax to determine which intersection is closer, where t is the parametric distance along the ray at which the intersection occurred.
-
If t < tmax, tmax is set to t and the candidate is set as the current closest hit.
-
If t > tmax, the candidate is dropped and no further processing of that candidate occurs.
-
If t = tmax, the candidate may be set as the current closest hit or dropped.
If TerminateOnFirstHitKHR was included in the Ray Flags used to trace
the ray, once the first hit is confirmed, the ray trace is terminated.
37.5. Ray Result Determination
Once all candidates have finished processing the prior stages, or if the ray is forcibly terminated, the final result of the ray trace is determined.
If a closest hit result was identified by Ray Closest Hit Determination, a closest hit has occurred, otherwise the final result is a miss.
For rays traced with OpTraceRayKHR, if a closest hit result was
identified, a closest hit shader is invoked from
the Shader Binding Table according to the
specified indexing for the
intersected geometry.
Control returns to the shader that executed OpTraceRayKHR once this
shader returns.
This shader is skipped if either the ray flags included
SkipClosestHitShaderKHR, or if the closest hit
shader identified is VK_SHADER_UNUSED_KHR.
For rays traced with OpTraceRayKHR where no hit result was identified,
the miss shader identified by the Miss Index parameter
of OpTraceRayKHR is invoked.
Control returns to the shader that executed OpTraceRayKHR once this
shader returns.
This shader is skipped if the miss shader identified is
VK_SHADER_UNUSED_KHR.
If the ray was traced with OpRayQueryProceedKHR, control is returned to
the shader which executed OpRayQueryProceedKHR, returning false.
If a closest hit was identified by Ray Closest Hit Determination, the
ray query will now have a committed intersection type of
RayQueryCommittedIntersectionGeneratedKHR or
RayQueryCommittedIntersectionTriangleKHR.
If no closest hit was identified, the committed intersection type will be
RayQueryCommittedIntersectionNoneKHR.
No further processing of a ray query occurs after this result is determined.
38. Ray Tracing
Ray tracing uses a separate rendering pipeline from both the graphics and compute pipelines (see Ray Tracing Pipeline).
Within the ray tracing pipeline, OpTraceRayKHR
or OpTraceRayMotionNV
can be called to perform a ray traversal that invokes the
various ray tracing shader stages during its execution.
The relationship between the ray tracing pipeline object and the geometries
present in the acceleration structure traversed is passed into the ray
tracing command in a VkBuffer object known as a shader binding
table.
OpExecuteCallableKHR can also be used in ray tracing pipelines to
invoke a callable shader.
During execution, control alternates between scheduling and other operations. The scheduling functionality is implementation-specific and is responsible for workload execution. The shader stages are programmable. Traversal, which refers to the process of traversing acceleration structures to find potential intersections of rays with geometry, is fixed function.
The programmable portions of the pipeline are exposed in a single-ray
programming model, with each invocation handling one ray at a time.
Memory operations can be synchronized using standard memory barriers.
The Workgroup scope and variables with a storage class of
Workgroup must not be used in the ray tracing pipeline.
38.1. Shader Call Instructions
A shader call is an instruction which may cause execution to continue elsewhere by creating one or more invocations that execute a different shader stage.
The shader call instructions are:
-
OpTraceRayKHRwhich may invoke intersection, any-hit, closest hit, or miss shaders, -
OpTraceRayMotionNVwhich may invoke intersection, any-hit, closest hit, or miss shaders, -
OpReportIntersectionKHRwhich may invoke any-hit shaders, and -
OpExecuteCallableKHRwhich will invoke a callable shader.
The invocations created by shader call instructions are grouped into subgroups by the implementation. Those subgroups may be unrelated to the subgroup of the parent invocation.
Pipeline trace ray instructions can be used recursively; invoked shaders
can themselves execute pipeline trace ray instructions, to a maximum depth
defined by the
maxRecursionDepth or
maxRayRecursionDepth limit.
Shaders directly invoked from the API always have a recursion depth of 0;
each shader executed by a pipeline trace ray instruction has a recursion
depth one higher than the recursion depth of the shader which invoked it.
Applications must not invoke a shader with a recursion depth greater than
the value of
maxRecursionDepth or
maxPipelineRayRecursionDepth specified in the pipeline.
There is no explicit recursion limit for other shader call instructions
which may recurse (e.g. OpExecuteCallableKHR) but there is an upper
bound determined by the stack size.
An invocation repack instruction is a ray tracing shader call instruction
where the implementation may change the set of invocations that are
executing.
When a repack instruction is encountered, the invocation is suspended and a
new invocation begins and executes the instruction.
After executing the repack instruction (which may result in other ray
tracing shader stages executing) the new invocation ends and the original
invocation is resumed, but it may be resumed in a different subgroup or at
a different SubgroupLocalInvocationId within the same subgroup.
When a subset of invocations in a subgroup execute the invocation repack
instruction, those that do not execute it remain in the same subgroup at the
same SubgroupLocalInvocationId.
The OpTraceRayKHR,
OpTraceRayMotionNV,
OpReportIntersectionKHR, and OpExecuteCallableKHR instructions are
invocation repack instructions.
The invocations that are executing before an invocation repack instruction, after the instruction, or are created by the instruction, are shader-call-related.
If the implementation changes the composition of subgroups, the values of
SubgroupSize, SubgroupLocalInvocationId,
SMIDNV, WarpIDNV,
and builtin variables that are derived from them (SubgroupEqMask,
SubgroupGeMask, SubgroupGtMask, SubgroupLeMask,
SubgroupLtMask) must be changed accordingly by the invocation repack
instruction.
The application must use Volatile
semantics on these BuiltIn variables when used in the ray generation,
closest hit, miss, intersection, and callable shaders.
Similarly, the application must use Volatile semantics on any
RayTmaxKHR decorated Builtin used in an intersection shader.
|
Note
Subgroup operations are permitted in the programmable ray tracing shader stages. However, shader call instructions place a bound on where results of subgroup instructions or subgroup-scoped instructions that execute the dynamic instance of that instruction are potentially valid. For example, care must be taken when using the result of a ballot operation that was computed before an invocation repack instruction, after that repack instruction. The ballot may be incorrect as the set of invocations could have changed. While the For clock operations, the value of a |
When a ray tracing shader executes a dynamic instance of an invocation repack instruction which results in another ray tracing shader being invoked, their instructions are related by shader-call-order.
For ray tracing invocations that are shader-call-related:
-
memory operations on
StorageBuffer,Image, andShaderRecordBufferKHRstorage classes can be synchronized using theShaderCallKHRscope. -
the
CallableDataKHR,IncomingCallableDataKHR,RayPayloadKHR,HitAttributeKHR, andIncomingRayPayloadKHRstorage classes are system-synchronized and no application availability and visibility operations are required. -
memory operations within a single invocation before and after the invocation repack instruction are ordered by program-order and do not require explicit synchronzation.
38.2. Ray Tracing Commands
Ray tracing commands provoke work in the ray tracing pipeline. Ray tracing commands are recorded into a command buffer and when executed by a queue will produce work that executes according to the currently bound ray tracing pipeline. A ray tracing pipeline must be bound to a command buffer before any ray tracing commands are recorded in that command buffer.
To dispatch ray tracing use:
// Provided by VK_NV_ray_tracing
void vkCmdTraceRaysNV(
VkCommandBuffer commandBuffer,
VkBuffer raygenShaderBindingTableBuffer,
VkDeviceSize raygenShaderBindingOffset,
VkBuffer missShaderBindingTableBuffer,
VkDeviceSize missShaderBindingOffset,
VkDeviceSize missShaderBindingStride,
VkBuffer hitShaderBindingTableBuffer,
VkDeviceSize hitShaderBindingOffset,
VkDeviceSize hitShaderBindingStride,
VkBuffer callableShaderBindingTableBuffer,
VkDeviceSize callableShaderBindingOffset,
VkDeviceSize callableShaderBindingStride,
uint32_t width,
uint32_t height,
uint32_t depth);
-
commandBufferis the command buffer into which the command will be recorded. -
raygenShaderBindingTableBufferis the buffer object that holds the shader binding table data for the ray generation shader stage. -
raygenShaderBindingOffsetis the offset in bytes (relative toraygenShaderBindingTableBuffer) of the ray generation shader being used for the trace. -
missShaderBindingTableBufferis the buffer object that holds the shader binding table data for the miss shader stage. -
missShaderBindingOffsetis the offset in bytes (relative tomissShaderBindingTableBuffer) of the miss shader being used for the trace. -
missShaderBindingStrideis the size in bytes of each shader binding table record inmissShaderBindingTableBuffer. -
hitShaderBindingTableBufferis the buffer object that holds the shader binding table data for the hit shader stages. -
hitShaderBindingOffsetis the offset in bytes (relative tohitShaderBindingTableBuffer) of the hit shader group being used for the trace. -
hitShaderBindingStrideis the size in bytes of each shader binding table record inhitShaderBindingTableBuffer. -
callableShaderBindingTableBufferis the buffer object that holds the shader binding table data for the callable shader stage. -
callableShaderBindingOffsetis the offset in bytes (relative tocallableShaderBindingTableBuffer) of the callable shader being used for the trace. -
callableShaderBindingStrideis the size in bytes of each shader binding table record incallableShaderBindingTableBuffer. -
widthis the width of the ray trace query dimensions. -
heightis height of the ray trace query dimensions. -
depthis depth of the ray trace query dimensions.
When the command is executed, a ray generation group of width
× height × depth rays is assembled.
To dispatch ray tracing use:
// Provided by VK_KHR_ray_tracing_pipeline
void vkCmdTraceRaysKHR(
VkCommandBuffer commandBuffer,
const VkStridedDeviceAddressRegionKHR* pRaygenShaderBindingTable,
const VkStridedDeviceAddressRegionKHR* pMissShaderBindingTable,
const VkStridedDeviceAddressRegionKHR* pHitShaderBindingTable,
const VkStridedDeviceAddressRegionKHR* pCallableShaderBindingTable,
uint32_t width,
uint32_t height,
uint32_t depth);
-
commandBufferis the command buffer into which the command will be recorded. -
pRaygenShaderBindingTableis a VkStridedDeviceAddressRegionKHR that holds the shader binding table data for the ray generation shader stage. -
pMissShaderBindingTableis a VkStridedDeviceAddressRegionKHR that holds the shader binding table data for the miss shader stage. -
pHitShaderBindingTableis a VkStridedDeviceAddressRegionKHR that holds the shader binding table data for the hit shader stage. -
pCallableShaderBindingTableis a VkStridedDeviceAddressRegionKHR that holds the shader binding table data for the callable shader stage. -
widthis the width of the ray trace query dimensions. -
heightis height of the ray trace query dimensions. -
depthis depth of the ray trace query dimensions.
When the command is executed, a ray generation group of width
× height × depth rays is assembled.
The VkStridedDeviceAddressRegionKHR structure is defined as:
// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkStridedDeviceAddressRegionKHR {
VkDeviceAddress deviceAddress;
VkDeviceSize stride;
VkDeviceSize size;
} VkStridedDeviceAddressRegionKHR;
-
deviceAddressis the device address (as returned by the vkGetBufferDeviceAddress command) at which the region starts, or zero if the region is unused. -
strideis the byte stride between consecutive elements. -
sizeis the size in bytes of the region starting atdeviceAddress.
When invocation mask image usage is enabled in the bound ray tracing pipeline, the pipeline uses an invocation mask image specified by the command:
// Provided by VK_HUAWEI_invocation_mask
void vkCmdBindInvocationMaskHUAWEI(
VkCommandBuffer commandBuffer,
VkImageView imageView,
VkImageLayout imageLayout);
-
commandBufferis the command buffer into which the command will be recorded -
imageViewis an image view handle specifying the invocation mask imageimageViewmay be set to VK_NULL_HANDLE, which is equivalent to specifying a view of an image filled with ones value. -
imageLayoutis the layout that the image subresources accessible fromimageViewwill be in when the invocation mask image is accessed
To dispatch ray tracing, with some parameters sourced on the device, use:
// Provided by VK_KHR_ray_tracing_pipeline
void vkCmdTraceRaysIndirectKHR(
VkCommandBuffer commandBuffer,
const VkStridedDeviceAddressRegionKHR* pRaygenShaderBindingTable,
const VkStridedDeviceAddressRegionKHR* pMissShaderBindingTable,
const VkStridedDeviceAddressRegionKHR* pHitShaderBindingTable,
const VkStridedDeviceAddressRegionKHR* pCallableShaderBindingTable,
VkDeviceAddress indirectDeviceAddress);
-
commandBufferis the command buffer into which the command will be recorded. -
pRaygenShaderBindingTableis a VkStridedDeviceAddressRegionKHR that holds the shader binding table data for the ray generation shader stage. -
pMissShaderBindingTableis a VkStridedDeviceAddressRegionKHR that holds the shader binding table data for the miss shader stage. -
pHitShaderBindingTableis a VkStridedDeviceAddressRegionKHR that holds the shader binding table data for the hit shader stage. -
pCallableShaderBindingTableis a VkStridedDeviceAddressRegionKHR that holds the shader binding table data for the callable shader stage. -
indirectDeviceAddressis a buffer device address which is a pointer to a VkTraceRaysIndirectCommandKHR structure containing the trace ray parameters.
vkCmdTraceRaysIndirectKHR behaves similarly to vkCmdTraceRaysKHR
except that the ray trace query dimensions are read by the device from
indirectDeviceAddress during execution.
The VkTraceRaysIndirectCommandKHR structure is defined as:
// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkTraceRaysIndirectCommandKHR {
uint32_t width;
uint32_t height;
uint32_t depth;
} VkTraceRaysIndirectCommandKHR;
-
widthis the width of the ray trace query dimensions. -
heightis height of the ray trace query dimensions. -
depthis depth of the ray trace query dimensions.
The members of VkTraceRaysIndirectCommandKHR have the same meaning as
the similarly named parameters of vkCmdTraceRaysKHR.
To dispatch ray tracing, with some parameters sourced on the device, use:
// Provided by VK_KHR_ray_tracing_maintenance1 with VK_KHR_ray_tracing_pipeline
void vkCmdTraceRaysIndirect2KHR(
VkCommandBuffer commandBuffer,
VkDeviceAddress indirectDeviceAddress);
-
commandBufferis the command buffer into which the command will be recorded. -
indirectDeviceAddressis a buffer device address which is a pointer to a VkTraceRaysIndirectCommand2KHR structure containing the trace ray parameters.
vkCmdTraceRaysIndirect2KHR behaves similarly to
vkCmdTraceRaysIndirectKHR except that shader binding table parameters
as well as dispatch dimensions are read by the device from
indirectDeviceAddress during execution.
The VkTraceRaysIndirectCommand2KHR structure is defined as:
// Provided by VK_KHR_ray_tracing_maintenance1 with VK_KHR_ray_tracing_pipeline
typedef struct VkTraceRaysIndirectCommand2KHR {
VkDeviceAddress raygenShaderRecordAddress;
VkDeviceSize raygenShaderRecordSize;
VkDeviceAddress missShaderBindingTableAddress;
VkDeviceSize missShaderBindingTableSize;
VkDeviceSize missShaderBindingTableStride;
VkDeviceAddress hitShaderBindingTableAddress;
VkDeviceSize hitShaderBindingTableSize;
VkDeviceSize hitShaderBindingTableStride;
VkDeviceAddress callableShaderBindingTableAddress;
VkDeviceSize callableShaderBindingTableSize;
VkDeviceSize callableShaderBindingTableStride;
uint32_t width;
uint32_t height;
uint32_t depth;
} VkTraceRaysIndirectCommand2KHR;
-
raygenShaderRecordAddressis aVkDeviceAddressof the ray generation shader binding table record used by this command. -
raygenShaderRecordSizeis aVkDeviceSizenumber of bytes corresponding to the ray generation shader binding table record at base addressraygenShaderRecordAddress. -
missShaderBindingTableAddressis aVkDeviceAddressof the first record in the miss shader binding table used by this command. -
missShaderBindingTableSizeis aVkDeviceSizenumber of bytes corresponding to the total size of the miss shader binding table atmissShaderBindingTableAddressthat may be accessed by this command. -
missShaderBindingTableStrideis aVkDeviceSizenumber of bytes between records of the miss shader binding table. -
hitShaderBindingTableAddressis aVkDeviceAddressof the first record in the hit shader binding table used by this command. -
hitShaderBindingTableSizeis aVkDeviceSizenumber of bytes corresponding to the total size of the hit shader binding table athitShaderBindingTableAddressthat may be accessed by this command. -
hitShaderBindingTableStrideis aVkDeviceSizenumber of bytes between records of the hit shader binding table. -
callableShaderBindingTableAddressis aVkDeviceAddressof the first record in the callable shader binding table used by this command. -
callableShaderBindingTableSizeis aVkDeviceSizenumber of bytes corresponding to the total size of the callable shader binding table atcallableShaderBindingTableAddressthat may be accessed by this command. -
callableShaderBindingTableStrideis aVkDeviceSizenumber of bytes between records of the callable shader binding table. -
widthis the width of the ray trace query dimensions. -
heightis height of the ray trace query dimensions. -
depthis depth of the ray trace query dimensions.
The members of VkTraceRaysIndirectCommand2KHR have the same meaning as
the similarly named parameters of vkCmdTraceRaysKHR.
Indirect shader binding table buffer parameters must satisfy the same memory alignment and binding requirements as their counterparts in vkCmdTraceRaysIndirectKHR and vkCmdTraceRaysKHR.
38.3. Shader Binding Table
A shader binding table is a resource which establishes the relationship between the ray tracing pipeline and the acceleration structures that were built for the ray tracing pipeline. It indicates the shaders that operate on each geometry in an acceleration structure. In addition, it contains the resources accessed by each shader, including indices of textures, buffer device addresses, and constants. The application allocates and manages shader binding tables as VkBuffer objects.
Each entry in the shader binding table consists of
shaderGroupHandleSize bytes of data, either as queried by
vkGetRayTracingShaderGroupHandlesKHR to refer to those specified
shaders, or all zeros to refer to a zero shader group.
A zero shader group behaves as though it is a shader group consisting
entirely of VK_SHADER_UNUSED_KHR.
The remainder of the data specified by the stride is application-visible
data that can be referenced by a ShaderRecordBufferKHR block in the
shader.
The shader binding tables to use in a ray tracing pipeline are passed to the vkCmdTraceRaysNV, vkCmdTraceRaysKHR, or vkCmdTraceRaysIndirectKHR commands. Shader binding tables are read-only in shaders that are executing on the ray tracing pipeline.
Shader variables identified with the ShaderRecordBufferKHR storage
class are used to access the provided shader binding table.
Such variables must be:
-
typed as
OpTypeStruct, or an array of this type, -
identified with a
Blockdecoration, and -
laid out explicitly using the
Offset,ArrayStride, andMatrixStridedecorations as specified in Offset and Stride Assignment.
The Offset decoration for any member of a Block-decorated variable
in the ShaderRecordBufferKHR storage class must not cause the space
required for that variable to extend outside the range [0,
maxStorageBufferRange).
Accesses to the shader binding table from ray tracing pipelines must be
synchronized with the
VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_SHADER_READ_BIT.
|
Note
Because different shader record buffers can be associated with the same
shader, a shader variable with |
38.3.1. Indexing Rules
In order to execute the correct shaders and access the correct resources during a ray tracing dispatch, the implementation must be able to locate shader binding table entries at various stages of execution. This is accomplished by defining a set of indexing rules that compute shader binding table record positions relative to the buffer’s base address in memory. The application must organize the contents of the shader binding table’s memory in a way that application of the indexing rules will lead to correct records.
Ray Generation Shaders
Only one ray generation shader is executed per ray tracing dispatch.
For vkCmdTraceRaysKHR, the location of the ray generation shader is
specified by the pRaygenShaderBindingTable->deviceAddress parameter — there is no indexing.
All data accessed must be less than pRaygenShaderBindingTable->size
bytes from deviceAddress.
pRaygenShaderBindingTable->stride is unused, and must be equal to
pRaygenShaderBindingTable->size.
For vkCmdTraceRaysNV, the location of the ray generation shader is
specified by the raygenShaderBindingTableBuffer and
raygenShaderBindingOffset parameters — there is no indexing.
Hit Shaders
The base for the computation of intersection, any-hit, and closest hit
shader locations is the instanceShaderBindingTableRecordOffset value
stored with each instance of a top-level acceleration structure
(VkAccelerationStructureInstanceKHR).
This value determines the beginning of the shader binding table records for
a given instance.
In the following rule, geometryIndex refers to the
geometry index of the intersected
geometry within the instance.
The sbtRecordOffset and sbtRecordStride values are passed in as
parameters to
traceNV()
or
traceRayEXT()
calls made in the shaders.
See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language
Specification for more details.
In SPIR-V, these correspond to the SBTOffset and SBTStride
parameters to the
OpTraceRayNV
or
OpTraceRayKHR
or OpTraceRayMotionNV
instruction.
The result of this computation is then added to
pHitShaderBindingTable->deviceAddress, a device address passed to
vkCmdTraceRaysKHR
, or
hitShaderBindingOffset, a base offset passed to vkCmdTraceRaysNV
.
For vkCmdTraceRaysKHR, the complete rule to compute a hit shader
binding table record address in the pHitShaderBindingTable is:
-
pHitShaderBindingTable->deviceAddress+pHitShaderBindingTable->stride× (instanceShaderBindingTableRecordOffset+geometryIndex×sbtRecordStride+sbtRecordOffset)
All data accessed must be less than pHitShaderBindingTable->size
bytes from the base address.
For vkCmdTraceRaysNV, the offset and stride come from direct
parameters, so the full rule to compute a hit shader binding table record
address in the hitShaderBindingTableBuffer is:
-
hitShaderBindingOffset+hitShaderBindingStride× (instanceShaderBindingTableRecordOffset+geometryIndex×sbtRecordStride+sbtRecordOffset)
Miss Shaders
A miss shader is executed whenever a ray query fails to find an intersection for the given scene geometry. Multiple miss shaders may be executed throughout a ray tracing dispatch.
The base for the computation of miss shader locations is
pMissShaderBindingTable->deviceAddress, a device address passed into
vkCmdTraceRaysKHR
, or
missShaderBindingOffset, a base offset passed into
vkCmdTraceRaysNV
.
The missIndex value is passed in as a parameter to
traceNV()
or
traceRayEXT()
calls made in the shaders.
See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language
Specification for more details.
In SPIR-V, this corresponds to the MissIndex parameter to the
OpTraceRayNV
or
OpTraceRayKHR
or OpTraceRayMotionNV
instruction.
For vkCmdTraceRaysKHR, the complete rule to compute a miss shader
binding table record address in the pMissShaderBindingTable is:
-
pMissShaderBindingTable->deviceAddress+pMissShaderBindingTable->stride×missIndex
All data accessed must be less than pMissShaderBindingTable->size
bytes from the base address.
For vkCmdTraceRaysNV, the offset and stride come from direct
parameters, so the full rule to compute a miss shader binding table record
address in the missShaderBindingTableBuffer is:
-
missShaderBindingOffset+missShaderBindingStride×missIndex
Callable Shaders
A callable shader is executed when requested by a ray tracing shader. Multiple callable shaders may be executed throughout a ray tracing dispatch.
The base for the computation of callable shader locations is
pCallableShaderBindingTable->deviceAddress, a device address passed
into vkCmdTraceRaysKHR
, or
callableShaderBindingOffset, a base offset passed into
vkCmdTraceRaysNV
.
The sbtRecordIndex value is passed in as a parameter to
executeCallableNV()
or
executeCallableEXT()
calls made in the shaders.
See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language
Specification for more details.
In SPIR-V, this corresponds to the SBTIndex parameter to the
OpExecuteCallableNV
or
OpExecuteCallableKHR
instruction.
For vkCmdTraceRaysKHR, the complete rule to compute a callable shader
binding table record address in the pCallableShaderBindingTable is:
-
pCallableShaderBindingTable->deviceAddress+pCallableShaderBindingTable->stride×sbtRecordIndex
All data accessed must be less than pCallableShaderBindingTable->size
bytes from the base address.
For vkCmdTraceRaysNV, the offset and stride come from direct
parameters, so the full rule to compute a callable shader binding table
record address in the callableShaderBindingTableBuffer is:
-
callableShaderBindingOffset+callableShaderBindingStride×sbtRecordIndex
38.4. Ray Tracing Pipeline Stack
Ray tracing pipelines have a potentially large set of shaders which may be invoked in various call chain combinations to perform ray tracing. To store parameters for a given shader execution, an implementation may use a stack of data in memory. This stack must be sized to the sum of the stack sizes of all shaders in any call chain executed by the application.
If the stack size is not set explicitly, the stack size for a pipeline is:
-
rayGenStackMax + min(1,
maxPipelineRayRecursionDepth) × max(closestHitStackMax, missStackMax, intersectionStackMax + anyHitStackMax) + max(0,maxPipelineRayRecursionDepth-1) × max(closestHitStackMax, missStackMax) + 2 × callableStackMax
where rayGenStackMax, closestHitStackMax, missStackMax, anyHitStackMax, intersectionStackMax, and callableStackMax are the maximum stack values queried by the respective shader stages for any shaders in any shader groups defined by the pipeline.
This stack size is potentially significant, so an application may want to provide a more accurate stack size after pipeline compilation. The value that the application provides is the maximum value of the sum of all shaders in a call chain across all possible call chains, taking into account any application specific knowledge about the properties of the call chains.
|
Note
For example, if an application has two types of closest hit and miss shaders that it can use but the first level of rays will only use the first kind (possibly reflection) and the second level will only use the second kind (occlusion or shadow ray, for example) then the application can compute the stack size by something similar to:
This is guaranteed to be no larger than the default stack size computation which assumes that both call levels may be the larger of the two. |
39. Video Decode and Encode Operations
Vulkan implementations can expose video decode and encode engines, which are independent from the graphics and compute engines. Video decode and encode is performed by recording video operations and submitting them to video decode and encode queues. Vulkan provides core support for video decode and encode and can support a variety of video codecs through individual extensions built on the core video support.
The subsections below detail the fundamental components and operation of Vulkan video.
39.1. Technical Terminology and Semantics
39.1.1. Video Picture Resources
Video Picture Resources contain format information, can be multidimensional and may have associated metadata. The metadata can include implementation-private details required for the decode or encode operations and application managed color-space related information.
In Vulkan, a Video Picture Resource is represented by a VkImage. The VkImageView, representing the VkImage, is used with the decode operations as Output and Decoded Picture Buffer (DPB), and with the encode operation as Input and Reconstructed Video Picture Resource.
39.1.2. Reference Picture
Video Reference Picture is a Video Picture Resource that can be used in the video decode or encode process to provide predictions of the values of samples in the subsequently decoded or encoded pictures.
39.1.3. Decoded Output Picture
The pixels resulting from the video decoding process are stored in a Decoded Output Picture, represented by a VkImageView. This can be shared with the Encoder Reconstructed or Decoder DPB Video Picture Resources. It can also be used as an input for Video Encode, Graphics, Compute processing, or WSI presentation.
39.1.4. Input Picture to Encode
The primary source of input pixels for the video encoding process is the Input Picture to Encode, represented by a VkImageView. This can be shared with the Encoder Reconstructed or Decoder DPB Video Picture Resources. It can be a direct target of Video Decode, Graphics, Compute processing, or WSI presentation.
39.1.5. Decoded Picture Buffer (DPB)
Previously decoded pictures are used by video codecs to provide predictions of the values of samples in the subsequently decoded pictures. At the decoder, such Video Picture Resources are stored in a Decoded Picture Buffer (DPB) as an indexed set of Reference Pictures.
39.1.6. Reconstructed Pictures
An integral part of the video decoding pipeline is the reconstruction of pictures from the compressed stream. A similar stage exists in the video encoding pipeline as well. Such reconstructed pictures may be used as Reference Pictures for subsequently decoded or encoded pictures. The correct use of such Reference Pictures is driven by the video compression standard, the implementation, and the application-specific use cases.
This specification refers to the collection of the Decoded Picture Buffer and Reconstructed Pictures as Decoded Picture Buffer (DPB) Set, or only, DPB.
39.1.7. Decoded Picture Buffer (DPB) Slot
Decoded Picture Buffer (DPB) Slot represents a single or multi-layer indexed Reference Picture’s entry within the Video Session’s DPB Set. A valid DPB Slot index starts from zero and goes up to the maximum of N - 1, where N is the number of Reference Picture entries requested for a Video Session.
39.1.8. Reference Picture Metadata
The opaque DPB Slot state managed by the implementation may contain Reference Picture Metadata, present when the picture resource associated with the DPB Slot is used as a reference picture in one or more video decode or encode operations.
An implementation or application may have other Picture Metadata related to the Video Picture Resource or the DPB Slot, but such data is outside the scope of this specification.
|
Note:
The video decode or encode implementation does not maintain internal references to the Reference Pictures, beyond the Reference Picture Metadata. It is the responsibility of the Vulkan Application to create, manage, and destroy, as well as to provide those Video Picture Resources, when required, during the decoding or encoding process. |
39.1.9. Color Space Metadata
Color Space Metadata is the additional static or dynamic state associated with a Video Picture Resource specifying the color volume (the color primaries, white point, and luminance range) of the display that was used in mastering the video content. The use of Color Space Metadata is outside the scope of the current version of the video core specification.
39.2. Introduction
This chapter discusses extensions supporting Video Decode or Encode
operations.
Video Decode and Encode operations are supported by queues with an
advertised queue capability of VK_QUEUE_VIDEO_DECODE_BIT_KHR and
VK_QUEUE_VIDEO_ENCODE_BIT_KHR, respectively.
Video Decode or Encode queue operation support allows for Vulkan
applications to cooperate closely with other graphics or compute operations
seamlessly and efficiently, therefore improving the overall application
performance.
39.2.1. Video Decode Queue
VK_KHR_video_decode_queue adds a video decode queue type bit
VK_QUEUE_VIDEO_DECODE_BIT_KHR to VkQueueFlagBits.
As in the case of other queue types, an application must use
vkGetPhysicalDeviceQueueFamilyProperties to query whether the physical
device has support for the Video Decode Queue.
When the implementation reports the VK_QUEUE_VIDEO_DECODE_BIT_KHR bit
for a queue family, it advertises general support for Vulkan queue
operations described in Devices and Queues.
39.2.2. Video Encode Queue
VK_KHR_video_encode_queue adds a video encode queue type bit
VK_QUEUE_VIDEO_ENCODE_BIT_KHR to VkQueueFlagBits.
As in the case of other queue types, an application must use
vkGetPhysicalDeviceQueueFamilyProperties to query whether the physical
device has support for the Video Encode Queue.
When the implementation reports the VK_QUEUE_VIDEO_ENCODE_BIT_KHR bit
for a queue family, it advertises general support for Vulkan queue
operations described in Devices and Queues.
The rest of the chapter focuses, specifically, on Video Decode and Encode queue operations.
39.2.3. Video Session
Before performing any video decoding or encoding operations, the application must create a Video Session instance, of type VkVideoSessionKHR. A Video Session instance is an immutable object and supports a single compression standard (for example, H.264, H.265, VP9, AV1, etc.). The implementation uses the VkVideoSessionKHR object to maintain the video state for the video decode or video encode operation. A Video Session instance is created specifically:
-
For a particular video compression standard;
-
For video decoding or video encoding;
-
With maximum supported decoded or encoded picture width/height;
-
With the maximum number of supported DPB or Reconstructed Pictures slots that can be allocated;
-
With the maximum number of Reference Pictures that can be used simultaneously for video decode or encode operations;
-
Codec color and features profile;
-
Color Space format description (not supported with this version of the specification);
VkVideoSessionKHR represents a single video decode or encode stream. For each concurrently used stream, a separate instance of VkVideoSessionKHR is required. After the application has finished with the processing of a stream, it can reuse the Video Session instance for another, provided that the configuration parameters between the two usages are compatible (as determined by the video compression standard in use). Once the VkVideoSessionKHR instance has been created, the video compression standard and profiles, Input / Output / DPB formats, and the settings like the maximum extent cannot be changed.
The values of the following VkVideoSessionKHR parameters can be updated each frame, subject to the restrictions imposed on parameter updates by the video compression standard in use:
-
decoded or encoded picture size
-
number of active DPB or Reconstructed Picture slots
-
number of Reference Pictures in use,
-
color space and color space metadata
-
color space metadata.
The updated parameters must not exceed the maximum limits specified when creating the VkVideoSessionKHR instance.
39.2.4. Video Session Device Memory Heaps
After creating a Video Session instance, and before the object can be used for any of the decode or encode operations, the application must allocate and bind device memory resources to the Video Session object. An implementation may require one or more device memory heaps of different memory types, as reported by the vkGetVideoSessionMemoryRequirementsKHR function, to be bound with the vkBindVideoSessionMemoryKHR function to the Video Session, For more information about the Video Session Device Memory, please refer to the Binding the Session Object Device Memory section, below.
39.2.5. Video Session Parameters
A lot of codec standards require parameters that are in use for the entire video stream. For example, H.264/AVC and HEVC standards require sequence and picture parameter sets (SPS and PPS) that apply to multiple Video Decode and Encode frames, layers, and sub-layers. Vulkan Video uses Video Session Parameters objects to store such standard parameters. The application creates one or more Video Session Parameters Objects against a Video Session, with a set of common Video Parameters that are required for the processing of the video content. During the object creation, the implementation stores the parameters to the created instance. During command buffer recording, it is the responsibility of the application to provide the Video Session Parameters object containing the parameters that are necessary for the processing the portion of the stream under consideration.
39.2.6. Video Picture Subresources
For Video Picture Resources, an application has
the option to use single or multi-layer images for
image views.
The layer to be used during decode or encode operations can be specified
when the image view is being created with the
VkImageSubresourceRange::baseArrayLayer parameter, and/or within
the resource binding operations in command buffer by using the
VkVideoPictureResourceKHR::baseArrayLayer parameter.
|
Note:
Both Video Decode and Encode operations only work with a single layer at the time. |
The Image views representing the
Input / Output /
DPB Video Picture Resources could have
been created with sizes bigger than the coded size that is used with Video
Decode and Encode operations.
This allows for the same Video Picture Resources to be reused when there is
a change in the input video content resolution.
The effective coded size of the Video Picture
Resources used for Video Decode and Encode operations is provided with
VkVideoPictureResourceKHR::extent parameter of each resource in
use.
|
Note:
Many codec standards require the coded and Video Picture Resources' sizes to match. |
Video Session DPB and Reconstructed Video Picture Resources
The video compression standard chosen may require the use of Reference Pictures. In Vulkan Video, like any other Video Picture Resources, the Reference Pictures are represented with Image Views.
When an application requires Reference Picture Resources, it creates and then associates image views, representing these resources, with Video Session DPB or Reconstructed slots while recording the command buffer.
Decoded output pictures may be used as reference pictures in future video decode operations. The same pictures may be used in texture sampling operations or in the (WSI) presentation pipeline. Representing the DPB’s Video Picture Resources by image views makes it possible to accommodate all these use cases in a “zero-copy” fashion. Also, it provides more fine-grained control of the application over the efficient usage of the DPB and Reconstructed Device Memory Resources.
Video Session DPB and Reconstructed Slot Resource Management
Before Video Picture Resources can be used as Reference Picture Resources, Video Session DPB or Reconstructed Slots must be associated with those resources.
The application allocates a DPB or Reconstructed Slot and associates it with a Video Picture Resource and then sets up the resource as a target of decode or encode operation. After successfully decoding or encoding a picture with the targeted DPB or Reconstructed Slot , in addition to the Reference Picture pixel data, the implementation may generate an opaque Reference Picture Metadata for that video session Slot and its associated Video Picture Resource.
Subsequently, one or more DPB or Reconstructed video session Slots, along with their associated Video Picture Resources, can be used as Reference Picture’s source for the video decode or encode operations.
If Reference Pictures were to be required for decoding
or encoding of the video bitstream, the
VkVideoSessionCreateInfoKHR::maxReferencePicturesSlotsCount
must be set to a value bigger than 0 when the instance of the
Video Session object is created.
Up to
VkVideoSessionCreateInfoKHR::maxReferencePicturesSlotsCount
slots can be activated with Video Picture
Resources for a video session and up to
VkVideoSessionCreateInfoKHR::maxReferencePicturesActiveCount
active slots can be used as DPB or Reconstructed
Reference Pictures within a single decode or encode
operation.
When the implementation is associating Reference Picture Metadata with the Video Picture Resources themselves, such data must be independent of the Video Session to allow for those Video Picture Resources to be shared with other Video Session instances. All of the Video Session-dependent Reference Picture Metadata must only be associated with the Video Session DPB or Reconstructed Slots.
The application with the help of the implementation is responsible for managing the individual DPB, or Reconstructed Slots that belong to a single Video Session DPB set:
-
The application maintains the Slot allocation and per-slot Reference Picture Resources;
-
Implementation maintains global and per-slot opaque Reference Picture Metadata;
The application also manages the mapping between the codec-specific picture IDs and DPB Slots.
When a Video Picture is decoded and is set as a Reference Picture against a Video Session DPB Slot, or is encoded and a Reconstructed Video Picture Resource is associated with a Video Session DPB Slot then:
-
The Video Picture Resource associated with the Slot is filled with the decoded or reconstructed pixel data;
-
The implementation generates the DPB Slot’s Reference Picture Metadata;
When a DPB’s Slot is deactivated, or a different Video Picture Resource is used with the Slot, or the content of the Video Picture Resource is modified, the Reference Picture Metadata associated with the DPB Slot gets invalidated by the implementation. Subsequent attempts to use such, invalidated, DPB Slot as a Reference source would produce undefined results.
Video Session DPB Slot subresources
DPB Reference Picture’s coded width and height can
change, dynamically, via VkVideoPictureResourceKHR::extent, and
the picture parameters from the codec-specific extensions.
When a DPB Slot is activated as a Reference
Picture and a decode or encode operation is performed against that slot,
the coded extent can be recorded by the implementation to the corresponding
DPB Slot’s metadata state.
Subsequently, when the Reference Pictures are used
with the decoded Output or encoded
Input Picture, their coded extent can differ.
Decoding or encoding pictures, using picture sizes, different from the
previously produced Reference Pictures should be used
with care, not to conflict with the codec standard and the implementation’s
support for that.
It is the responsibility of the application to ensure that valid DPB
Set of Reference Pictures are in use, according to
the codec standard.
In addition, the Video Picture Resources extent
cannot exceed the VkVideoSessionCreateInfoKHR::maxCodedExtent.
|
Note:
Coding Standards such as VP9 and AV1 allow for images with different sizes to be used as Reference Pictures. Others, like H.264 and H.265, do not support Reference Pictures with different sizes. Using Reference Pictures with incompatible sizes with such standards would render undefined results. |
The application is in control of the allocation and use of the system resource
In Vulkan Video, the application has complete control over how and when system resources are used. The Vulkan Video framework provides the following tools to ensure that device and host memory resources are used in an optimal way:
-
The video application can allocate or destroy the number of allocated Output or Input Pictures, and can grow, or shrink the DPB set of Reference Pictures, dynamically, based on the changing video content requirement.
-
Reference Pictures can be shared with the decoded Output or encoded Input pictures.
-
The application can use sparse memory for the images, representing Video Picture Resources. The use of sparse memory would allow the application to remove the Device Memory backing of the image resources when the DPB Slot is not in active use. Furthermore, if the
sparseResidencyfeature is supported by the implementation (see Sparse Resources), then images can be, partially, bound with the resource memory. This feature is particularly important when using video content with a significant change of decoded or encoded resolution. -
If the implementation supports image arrays, and sparse memory resources, then the application can remove the Device Memory backing of image array layers that are not used by any DPB Slots.
Using DPB and Reconstructed Slot’s Associated Resources
Before a DPB Slot is to become Valid for use with a Reference Picture, it requires memory resources to be bound to it.
Some of the memory resources required for the DPB Slot, are
opaquely managed by the implementation and, internally, allocated from the
Session’s Device Memory Heaps.
The application provides the image resources of one or
more Reference Pictures, in the
VkVideoBeginCodingInfoKHR::pReferenceSlots as part of the
vkCmdBeginVideoCodingKHR command.
If a DPB Slot was already used with an image view, and a new image view or a VK_NULL_HANDLE handle is used with that Slot, then the DPB Slot’s state will be invalidated by the implementation. If a DPB Slot were to be reused with the same image view, the state of the Slot would not change.
Video Session Activating DPB Slot as a Reference
Before a DPB Slot is to be used for a
Reference Pictures index, it must be activated.
The activation of a DPB Slot is done within the
vkCmdDecodeVideoKHR command’s
VkVideoDecodeInfoKHR::slotIndex field for the decode operations,
and within the vkCmdEncodeVideoKHR command’s
VkVideoEncodeInfoKHR::slotIndex field for the encode operations.
While activating a Slot for DPB, it must already have an associated
image view, within the
VkVideoBeginCodingInfoKHR::pReferenceSlots in the
vkCmdBeginVideoCodingKHR command and Device Memory
backing of the image resources must be resident.
When a DPB Slot were to be activated, the
VkVideoDecodeInfoKHR::slotIndex for decode, or
VkVideoEncodeInfoKHR::slotIndex for encode, must be set to the
application’s allocated DPB Slot’s index.
When activating a DPB Slot, the application will perform a
decode or encode operation against its Slot’s index in order to enable its
state as a Valid Picture Reference.
If a DPB Slot is activated, but a decode or encode operation is
not performed against that Slot’s index, or the decode or encode operation
was unsuccessful, then the DPB Slot would remain in the
Invalid Picture Reference state (see below the
DPB Slot States).
By just providing a Video Picture Resources for
a DPB Slot within the
VkVideoBeginCodingInfoKHR::pReferenceSlots, and without
successfully performing a decode or encode operation against that Slot, the
DPB Slot’s state cannot be changed to Valid Picture
Reference.
If the DPB Slots were already in Valid Picture Reference, and
there is no Video Picture Resources associated
with the DPB Slot for a decode or encode operation, the state
DPB Slot would not change.
However, if an application is referring to a valid DPB Slot in
its current decode or encode operations, then a valid
image view must be provided for that Slot within
VkVideoPictureResourceKHR::imageViewBinding for that decode or
encode operation.
Video Session Invalidating DPB Slot’s Reference State
When a DPB Slot is invalidated, its state is set to Invalid Picture Reference. Using a DPB Slot as a Reference Picture index for video decode or encode operations while the Slot is in Invalid Picture Reference state would render undefined results.
Video Session DPB Slot States
To help understand the valid use of the Video Session DPB and its resource management, this section aims to explain the different states and correct usage of DPB Slots.
There are four (4) states that a DPB Slot could be in:
-
Picture Reference Unused;
-
Invalid Picture Reference;
-
Updating Picture Reference;
-
Valid Picture Reference;
The different states are outlined within the DPB Slot States and DPB Slot States Flow Diagram below.
All DPB Slot management operations are performed via the
VkVideoDecodeInfoKHR::slotIndex or
VkVideoEncodeInfoKHR::slotIndex field.
All DPB resource binding, invalidating, and activating Slot management
operations are performed, by the implementation, before the decoding or
encoding commands, based on the VkVideoDecodeInfoKHR::slotIndex
or VkVideoEncodeInfoKHR::slotIndex field and the entries from
the VkVideoBeginCodingInfoKHR::pReferenceSlots.
The application cannot move a DPB Slot from a Picture Reference Unused to
Updating Picture Reference state, implicitly, within a decode or encode
command operation.
Such a DPB Slot must first be transitioned to an Invalid Picture
Reference state using VkVideoDecodeInfoKHR::slotIndex or
VkVideoEncodeInfoKHR::slotIndex, as part of a decode command.
For more details, see Video Picture Decode
Modes.
When using sparse memory resources, it would be acceptable and valid behavior for the application to unbind the memory while the DPB Slot is any of the DPB Slot states, provided the command buffers, in a pending state, do not reference any such Video Picture Resources.
Accessing unbound regions of the
sparse memory resources by the decoder or encoder,
regardless if those are used as Output,
Input, DPB or
Reconstructed Video
Picture Resources, would render undefined results.
The VkPhysicalDeviceSparseProperties::residencyNonResidentStrict
property reported by the implementation does not offer guarantees on the
behavior of decode or encode operations when it comes to accessing
unbound regions.
However, both reads and writes are still considered safe and will not affect
other resources or populated regions of the image.
| DPB Slot State | Moving to DPB Slot State | Exiting DPB Slot State | Retain Video Picture Resource Memory |
|---|---|---|---|
Picture Reference Unused |
|
|
Application Controlled |
Invalid Picture Reference |
|
|
Application Controlled |
Updating Picture Reference |
Start decode or encode operation with an active Reference DPB Slot target; |
Decode or encode operation with an active Reference DPB Slot target Completed Successfully → Valid Picture Reference; |
Yes |
Valid Picture Reference |
Video decode or encode operation with an active Reference DPB Slot target Completed Successfully; |
|
Yes |
39.3. Video Physical Device Capabilities
39.3.1. Supported Video Codec Operations Enumeration
The structure VkVideoQueueFamilyProperties2KHR may be chained to VkQueueFamilyProperties2 when calling vkGetPhysicalDeviceQueueFamilyProperties2 to retrieve the video codec operations supported for the physical device queue family index.
The VkVideoQueueFamilyProperties2KHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoQueueFamilyProperties2KHR {
VkStructureType sType;
void* pNext;
VkVideoCodecOperationFlagsKHR videoCodecOperations;
} VkVideoQueueFamilyProperties2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoCodecOperationsis a bitmask of VkVideoCodecOperationFlagBitsKHR specifying supported video codec operation(s).
The codec operations are defined with the VkVideoCodecOperationFlagBitsKHR enum:
// Provided by VK_KHR_video_queue
typedef enum VkVideoCodecOperationFlagBitsKHR {
VK_VIDEO_CODEC_OPERATION_INVALID_BIT_KHR = 0,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_encode_h264
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT = 0x00010000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_encode_h265
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT = 0x00020000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h264
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_EXT = 0x00000001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_EXT_video_decode_h265
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_EXT = 0x00000002,
#endif
} VkVideoCodecOperationFlagBitsKHR;
Each decode or encode codec-specific extension extends this enumeration with the appropriate bit corresponding to the extension’s codec operation:
-
VK_VIDEO_CODEC_OPERATION_INVALID_BIT_KHR- No video operations are supported for this queue family. -
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT- H.264 video encode operations are supported by this queue family. -
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_EXT- H.264 video decode operations are supported by this queue family. -
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_EXT- H.265 video decode operations are supported by this queue family.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoCodecOperationFlagsKHR;
VkVideoCodecOperationFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoCodecOperationFlagBitsKHR.
39.3.2. Video Profiles
A video profile is defined by VkVideoProfileKHR structure as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoProfileKHR {
VkStructureType sType;
const void* pNext;
VkVideoCodecOperationFlagBitsKHR videoCodecOperation;
VkVideoChromaSubsamplingFlagsKHR chromaSubsampling;
VkVideoComponentBitDepthFlagsKHR lumaBitDepth;
VkVideoComponentBitDepthFlagsKHR chromaBitDepth;
} VkVideoProfileKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoCodecOperationis a VkVideoCodecOperationFlagBitsKHR value specifying a video codec operation. -
chromaSubsamplingis a bitmask of VkVideoChromaSubsamplingFlagBitsKHR specifying video chroma subsampling information. -
lumaBitDepthis a bitmask of VkVideoComponentBitDepthFlagBitsKHR specifying video luma bit depth information. -
chromaBitDepthis a bitmask of VkVideoComponentBitDepthFlagBitsKHR specifying video chroma bit depth information.
When a VkVideoProfileKHR structure is specified through the
pProfiles member of an VkVideoProfilesKHR structure in the
pNext chain of the input parameter of a query command such as
vkGetPhysicalDeviceVideoCapabilitiesKHR,
vkGetPhysicalDeviceVideoFormatPropertiesKHR, or
vkGetPhysicalDeviceImageFormatProperties2, the following error codes
indicate specific causes of the failure of the query operation:
-
VK_ERROR_VIDEO_PICTURE_LAYOUT_NOT_SUPPORTED_KHRThe requested video picture layout (e.g. through thepictureLayoutmember of a VkVideoDecodeH264ProfileEXT structure included in thepNextchain ofVkVideoProfileKHR) is not supported. -
VK_ERROR_VIDEO_PROFILE_OPERATION_NOT_SUPPORTED_KHRA video profile operation specified byvideoCodecOperationis not supported. -
VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHRFormat parameters specified bychromaSubsampling,lumaBitDepth, orchromaBitDepthare not supported. -
VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHRCodec-specific parameters corresponding to thevideoCodecOperationare not provided through thepNextchain ofVkVideoProfileKHR, or the specified parameters are not supported.
The video format chroma subsampling is defined with the following enums:
// Provided by VK_KHR_video_queue
typedef enum VkVideoChromaSubsamplingFlagBitsKHR {
VK_VIDEO_CHROMA_SUBSAMPLING_INVALID_BIT_KHR = 0,
VK_VIDEO_CHROMA_SUBSAMPLING_MONOCHROME_BIT_KHR = 0x00000001,
VK_VIDEO_CHROMA_SUBSAMPLING_420_BIT_KHR = 0x00000002,
VK_VIDEO_CHROMA_SUBSAMPLING_422_BIT_KHR = 0x00000004,
VK_VIDEO_CHROMA_SUBSAMPLING_444_BIT_KHR = 0x00000008,
} VkVideoChromaSubsamplingFlagBitsKHR;
-
VK_VIDEO_CHROMA_SUBSAMPLING_MONOCHROME_BIT_KHR- the format is monochrome. -
VK_VIDEO_CHROMA_SUBSAMPLING_420_BIT_KHR- the format is 4:2:0 chroma subsampled. The two chroma components are each subsampled at a factor of 2 both horizontally and vertically. -
VK_VIDEO_CHROMA_SUBSAMPLING_422_BIT_KHR- the format is 4:2:2 chroma subsampled. The two chroma components are sampled at half the sample rate of luma. The horizontal chroma resolution is halved. -
VK_VIDEO_CHROMA_SUBSAMPLING_444_BIT_KHR- the format is 4:4:4 chroma sampled. Each of the three YCbCr components have the same sample rate, thus there is no chroma subsampling.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoChromaSubsamplingFlagsKHR;
VkVideoChromaSubsamplingFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoChromaSubsamplingFlagBitsKHR.
The video format component bit depth is defined with the following enums:
// Provided by VK_KHR_video_queue
typedef enum VkVideoComponentBitDepthFlagBitsKHR {
VK_VIDEO_COMPONENT_BIT_DEPTH_INVALID_KHR = 0,
VK_VIDEO_COMPONENT_BIT_DEPTH_8_BIT_KHR = 0x00000001,
VK_VIDEO_COMPONENT_BIT_DEPTH_10_BIT_KHR = 0x00000004,
VK_VIDEO_COMPONENT_BIT_DEPTH_12_BIT_KHR = 0x00000010,
} VkVideoComponentBitDepthFlagBitsKHR;
-
VK_VIDEO_COMPONENT_BIT_DEPTH_8_BIT_KHR- the format component bit depth is 8 bits. -
VK_VIDEO_COMPONENT_BIT_DEPTH_10_BIT_KHR- the format component bit depth is 10 bits. -
VK_VIDEO_COMPONENT_BIT_DEPTH_12_BIT_KHR- the format component bit depth is 12 bits.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoComponentBitDepthFlagsKHR;
VkVideoComponentBitDepthFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoComponentBitDepthFlagBitsKHR.
A video profile is provided when querying capabilities or image formats for
video using vkGetPhysicalDeviceVideoCapabilitiesKHR or
vkGetPhysicalDeviceVideoFormatPropertiesKHR, respectively.
A video profile is also provided when creating resources (images, video
sessions, etc.) used by video queues.
Each instance of VkVideoProfileKHR must chain a codec-operation
specific video profile extension structure, corresponding to the
codec-operation specified in
VkVideoProfileKHR::videoCodecOperation.
Additional information is provided in each codec-operation-specific video
extension.
39.3.3. Supported Video Decode or Encode Capabilities
To query video decode or encode capabilities for a specific codec, call:
// Provided by VK_KHR_video_queue
VkResult vkGetPhysicalDeviceVideoCapabilitiesKHR(
VkPhysicalDevice physicalDevice,
const VkVideoProfileKHR* pVideoProfile,
VkVideoCapabilitiesKHR* pCapabilities);
-
physicalDeviceis the physical device whose video decode or encode capabilities will be queried. -
pVideoProfileis a pointer to a VkVideoProfileKHR structure with a chained codec-operation specific video profile structure. -
pCapabilitiesis a pointer to a VkVideoCapabilitiesKHR structure in which the capabilities are returned.
If pVideoProfile and the chained codec-specific parameters are not
supported, then one of the video-profile-specific error codes are returned.
Otherwise, the implementation will fill pCapabilities with
capabilities associated with this video profile.
The VkVideoCapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoCapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkVideoCapabilityFlagsKHR capabilityFlags;
VkDeviceSize minBitstreamBufferOffsetAlignment;
VkDeviceSize minBitstreamBufferSizeAlignment;
VkExtent2D videoPictureExtentGranularity;
VkExtent2D minExtent;
VkExtent2D maxExtent;
uint32_t maxReferencePicturesSlotsCount;
uint32_t maxReferencePicturesActiveCount;
VkExtensionProperties stdHeaderVersion;
} VkVideoCapabilitiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
capabilityFlagsis a bitmask of VkVideoCapabilityFlagBitsKHR specifying capability flags. -
minBitstreamBufferOffsetAlignmentis the minimum alignment for the input or output bitstream buffer offset. -
minBitstreamBufferSizeAlignmentis the minimum alignment for the input or output bitstream buffer size -
videoPictureExtentGranularityis the minimum size alignment of the extent with the required padding for the decoded or encoded video images. -
minExtentis the minimum width and height of the decoded or encoded video. -
maxExtentis the maximum width and height of the decoded or encoded video. -
maxReferencePicturesSlotsCountis the maximum number of DPB Slots supported by the implementation for a single video session instance. -
maxReferencePicturesActiveCountis the maximum slots that can be used as Reference Pictures with a single decode or encode operation. -
stdHeaderVersionis a VkExtensionProperties structure reporting the Video Std header version supported for thecodecOperationrequested invkGetPhysicalDeviceVideoCapabilitiesKHR::pVideoProfile.
The VkVideoCapabilitiesKHR flags are defined with the following enumeration:
// Provided by VK_KHR_video_queue
typedef enum VkVideoCapabilityFlagBitsKHR {
VK_VIDEO_CAPABILITY_PROTECTED_CONTENT_BIT_KHR = 0x00000001,
VK_VIDEO_CAPABILITY_SEPARATE_REFERENCE_IMAGES_BIT_KHR = 0x00000002,
} VkVideoCapabilityFlagBitsKHR;
-
VK_VIDEO_CAPABILITY_PROTECTED_CONTENT_BIT_KHR- the decode or encode session supports protected content. -
VK_VIDEO_CAPABILITY_SEPARATE_REFERENCE_IMAGES_BIT_KHR- the DPB or Reconstructed Video Picture Resources for the video session may be created as a separate VkImage for each DPB picture. If not supported, the DPB must be created as single multi-layered image where each layer represents one of the DPB Video Picture Resources.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoCapabilityFlagsKHR;
VkVideoCapabilityFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoCapabilityFlagBitsKHR.
39.3.4. Enumeration of Supported Video Output, Input and DPB Formats
To enumerate the supported output, input and DPB image formats for a specific codec operation and video profile, call:
// Provided by VK_KHR_video_queue
VkResult vkGetPhysicalDeviceVideoFormatPropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceVideoFormatInfoKHR* pVideoFormatInfo,
uint32_t* pVideoFormatPropertyCount,
VkVideoFormatPropertiesKHR* pVideoFormatProperties);
-
physicalDeviceis the physical device being queried. -
pVideoFormatInfois a pointer to a VkPhysicalDeviceVideoFormatInfoKHR structure specifying the codec and video profile for which information is returned. -
pVideoFormatPropertyCountis a pointer to an integer related to the number of video format properties available or queried, as described below. -
pVideoFormatPropertiesis a pointer to an array of VkVideoFormatPropertiesKHR structures in which supported formats and image parameters are returned.
If pVideoFormatProperties is NULL, then the number of video format
properties supported for the given physicalDevice is returned in
pVideoFormatPropertyCount.
Otherwise, pVideoFormatPropertyCount must point to a variable set by
the user to the number of elements in the pVideoFormatProperties
array, and on return the variable is overwritten with the number of values
actually written to pVideoFormatProperties.
If the value of pVideoFormatPropertyCount is less than the number of
video format properties supported, at most pVideoFormatPropertyCount
values will be written to pVideoFormatProperties, and
VK_INCOMPLETE will be returned instead of VK_SUCCESS, to
indicate that not all the available values were returned.
If an implementation reports
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR is
supported but
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR is not
supported in VkVideoDecodeCapabilitiesKHR::flags, then to query
for video format properties for decode DPB or output,
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage must have both
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR and
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR set.
Otherwise, the call will fail with
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
If an implementation reports
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR is
supported but
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR is not
supported in VkVideoDecodeCapabilitiesKHR::flags, then to query
for video format properties for decode DPB,
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage must have
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR set and
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR not set.
Otherwise, the call will fail with
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
Similarly, to query for video format properties for decode output,
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage must have
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR set and
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR not set.
Otherwise, the call will fail with
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
The imageUsage member of the VkPhysicalDeviceVideoFormatInfoKHR
structure specifies the expected video usage flags that the returned video
formats must support.
Correspondingly, the imageUsageFlags member of each
VkVideoFormatPropertiesKHR structure returned will contain at least
the same set of image usage flags.
If the implementation supports using video input, output, or DPB images of a
particular format in operations other than video decode/encode then the
imageUsageFlags member of the corresponding
VkVideoFormatPropertiesKHR structure returned will include additional
image usage flags indicating that.
|
Note:
For most use cases, only decode or encode related usage flags are going to be specified. For a use case such as transcode, if the image were to be shared between decode and encode session(s), then both decode and encode related usage flags can be set. |
Video format properties are always queried with respect to a specific set of
video profiles, as defined by the VkVideoProfileKHR structure.
These are specified by chaining the VkVideoProfilesKHR structure to
pVideoFormatInfo.
For most use cases, the images are used by a single video session and a single video profile is provided. For a use case such as transcode, where a decode session output image can be used as encode input in one or more encode sessions, multiple video profiles corresponding to the video sessions that will share the image must be provided.
If any of the profiles specified via
VkVideoProfilesKHR::pProfiles are not supported, then
vkGetPhysicalDeviceVideoFormatPropertiesKHR returns one of the
video-profile-specific error codes.
Furthermore, if VkPhysicalDeviceVideoFormatInfoKHR::imageUsage
includes any image usage flags not supported by the specified video profiles
then vkGetPhysicalDeviceVideoFormatPropertiesKHR returns
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
Multiple VkVideoFormatPropertiesKHR entries may be returned with the
same format member with different componentMapping,
imageType, or imageTiling values, as described later.
In addition, a different set of VkVideoFormatPropertiesKHR entries
may be returned depending on the imageUsage member of the
VkPhysicalDeviceVideoFormatInfoKHR structure, even for the same set of
video profiles, for example, based on whether encode input, encode DPB,
decode output, and/or decode DPB usage is requested.
The application can select the parameters returned in the
VkVideoFormatPropertiesKHR entries and use compatible parameters when
creating the input, output, and DPB images.
The implementation will report all image creation and usage flags that are
valid for images used with the requested video profiles but applications
should create images only with those that are necessary for the particular
use case.
Before creating an image, the application can obtain the complete set of
supported image format features by calling
vkGetPhysicalDeviceImageFormatProperties2 using parameters derived
from the members of one of the reported VkVideoFormatPropertiesKHR
entries and adding the same VkVideoProfilesKHR structure to the
pNext chain of VkPhysicalDeviceImageFormatInfo2.
The componentMapping member of VkVideoFormatPropertiesKHR
defines the ordering of the Y′CBCR color channels from the perspective of
the video codec operations specified in VkVideoProfilesKHR.
For example, if the implementation produces video decode output with the
format VK_FORMAT_G8_B8R8_2PLANE_420_UNORM where the blue and red
chrominance channels are swapped then the componentMapping member of
the corresponding VkVideoFormatPropertiesKHR structure will have the
following member values:
components.r = VK_COMPONENT_SWIZZLE_B; // Cb component
components.g = VK_COMPONENT_SWIZZLE_IDENTITY; // Y component
components.b = VK_COMPONENT_SWIZZLE_R; // Cr component
components.a = VK_COMPONENT_SWIZZLE_IDENTITY; // unused, defaults to 1.0
The VkPhysicalDeviceVideoFormatInfoKHR input structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkPhysicalDeviceVideoFormatInfoKHR {
VkStructureType sType;
void* pNext;
VkImageUsageFlags imageUsage;
} VkPhysicalDeviceVideoFormatInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageUsageis a bitmask of VkImageUsageFlagBits specifying the intended usage of the video images.
The VkVideoProfilesKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoProfilesKHR {
VkStructureType sType;
const void* pNext;
uint32_t profileCount;
const VkVideoProfileKHR* pProfiles;
} VkVideoProfilesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
profileCountis an integer which holds the number of video profiles included inpProfiles. -
pProfilesis a pointer to an array of VkVideoProfileKHR structures. Each VkVideoProfileKHR structure must chain the corresponding codec-operation specific extension video profile structure.
Video transcoding is an example of a use case that necessitates numerous profiles. When the application provides one or more video decode and encode profiles in the list of profiles, the implementation ensures that the video formats and parameters reported produce video resources suitable for the transcoding use cases without the need for manual transformation.
The VkVideoFormatPropertiesKHR output structure for vkGetPhysicalDeviceVideoFormatPropertiesKHR is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoFormatPropertiesKHR {
VkStructureType sType;
void* pNext;
VkFormat format;
VkComponentMapping componentMapping;
VkImageCreateFlags imageCreateFlags;
VkImageType imageType;
VkImageTiling imageTiling;
VkImageUsageFlags imageUsageFlags;
} VkVideoFormatPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatis a VkFormat that specifies the format that can be used with the specified video profiles and image usages. -
componentMappingdefines the color channel order used for the format.formatalong withcomponentMappingdescribe how the color channels are ordered when producing video decoder output or are expected to be ordered in video encoder input, when applicable. If theformatreported does not require component swizzling then all members ofcomponentMappingwill be set toVK_COMPONENT_SWIZZLE_IDENTITY. -
imageCreateFlagsis a bitmask of VkImageCreateFlagBits specifying the supported image creation flags for the format. -
imageTypeis a VkImageType that specifies the image type the format can be used with. -
imageTilingis a VkImageTiling that specifies the image tiling the format can be used with. -
imageUsageFlagsis a bitmask of VkImageUsageFlagBits specifying the supported image usage flags for the format.
39.4. Video Session Objects
39.4.1. Video Session
Video session objects are abstracted and represented by VkVideoSessionKHR handles:
// Provided by VK_KHR_video_queue
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkVideoSessionKHR)
Creating a Video Session
To create a video session object, call:
// Provided by VK_KHR_video_queue
VkResult vkCreateVideoSessionKHR(
VkDevice device,
const VkVideoSessionCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkVideoSessionKHR* pVideoSession);
-
deviceis the logical device that creates the decode or encode session object. -
pCreateInfois a pointer to a VkVideoSessionCreateInfoKHR structure containing parameters specifying the creation of the decode or encode session. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pVideoSessionis a pointer to a VkVideoSessionKHR structure specifying the decode or encode video session object which will be created by this function when it returnsVK_SUCCESS
The VkVideoSessionCreateInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoSessionCreateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t queueFamilyIndex;
VkVideoSessionCreateFlagsKHR flags;
const VkVideoProfileKHR* pVideoProfile;
VkFormat pictureFormat;
VkExtent2D maxCodedExtent;
VkFormat referencePicturesFormat;
uint32_t maxReferencePicturesSlotsCount;
uint32_t maxReferencePicturesActiveCount;
const VkExtensionProperties* pStdHeaderVersion;
} VkVideoSessionCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queueFamilyIndexis the queue family of the created video session. -
flagsis a bitmask of VkVideoSessionCreateFlagBitsKHR specifying creation flags. -
pVideoProfileis a pointer to a VkVideoProfileKHR structure. -
pictureFormatis the format of the image views representing decoded Output or encoded Input pictures. -
maxCodedExtentis the maximum width and height of the coded pictures that this instance will be able to support. -
referencePicturesFormatis the format of the DPB image views representing the Reference Pictures. -
maxReferencePicturesSlotsCountis the maximum number of DPB Slots that can be activated with associated Video Picture Resources for the created video session. -
maxReferencePicturesActiveCountis the maximum number of active DPB Slots that can be used as Dpb or Reconstructed Reference Pictures within a single decode or encode operation for the created video session. -
pStdHeaderVersionis a pointer to a VkExtensionProperties structure requesting the Video Std header version to use forcodecOperationinpVideoProfile.
The decode or encode session creation flags defined with the following enums:
// Provided by VK_KHR_video_queue
typedef enum VkVideoSessionCreateFlagBitsKHR {
VK_VIDEO_SESSION_CREATE_DEFAULT_KHR = 0,
VK_VIDEO_SESSION_CREATE_PROTECTED_CONTENT_BIT_KHR = 0x00000001,
} VkVideoSessionCreateFlagBitsKHR;
-
VK_VIDEO_SESSION_CREATE_PROTECTED_CONTENT_BIT_KHR- create the video session for use with protected video content
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoSessionCreateFlagsKHR;
VkVideoSessionCreateFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoSessionCreateFlagBitsKHR.
39.4.2. Destroying a Video Session
To destroy a decode session object, call:
// Provided by VK_KHR_video_queue
void vkDestroyVideoSessionKHR(
VkDevice device,
VkVideoSessionKHR videoSession,
const VkAllocationCallbacks* pAllocator);
-
deviceis the device that was used for the creation of the video session. -
videoSessionis the decode or encode video session to be destroyed. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
39.4.3. Video Session Memory Resource Management
Obtaining the Video Session Object Device Memory Requirements
To get memory requirements for a video session, call:
// Provided by VK_KHR_video_queue
VkResult vkGetVideoSessionMemoryRequirementsKHR(
VkDevice device,
VkVideoSessionKHR videoSession,
uint32_t* pVideoSessionMemoryRequirementsCount,
VkVideoGetMemoryPropertiesKHR* pVideoSessionMemoryRequirements);
-
deviceis the logical device that owns the video session. -
videoSessionis the video session to query. -
pVideoSessionMemoryRequirementsCountis a pointer to an integer related to the number of memory heap requirements available or queried, as described below. -
pVideoSessionMemoryRequirementsisNULLor a pointer to an array of VkVideoGetMemoryPropertiesKHR structures in which the memory heap requirements of the video session are returned.
If pVideoSessionMemoryRequirements is NULL, then the number of
memory heap types required for the video session is returned in
pVideoSessionMemoryRequirementsCount.
Otherwise, pVideoSessionMemoryRequirementsCount must point to a
variable set by the user with the number of elements in the
pVideoSessionMemoryRequirements array, and on return the variable is
overwritten with the number of formats actually written to
pVideoSessionMemoryRequirements.
If pVideoSessionMemoryRequirementsCount is less than the number of
memory heap types required for the video session, then at most
pVideoSessionMemoryRequirementsCount elements will be written to
pVideoSessionMemoryRequirements, and VK_INCOMPLETE will be
returned, instead of VK_SUCCESS, to indicate that not all required
memory heap types were returned.
The VkVideoGetMemoryPropertiesKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoGetMemoryPropertiesKHR {
VkStructureType sType;
const void* pNext;
uint32_t memoryBindIndex;
VkMemoryRequirements2* pMemoryRequirements;
} VkVideoGetMemoryPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryBindIndexis the memory bind index of the memory heap type described by the information returned inpMemoryRequirements. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the requested memory heap requirements for the heap with indexmemoryBindIndexare returned.
Binding the Session Object Device Memory
To attach memory to a video session object, call:
// Provided by VK_KHR_video_queue
VkResult vkBindVideoSessionMemoryKHR(
VkDevice device,
VkVideoSessionKHR videoSession,
uint32_t videoSessionBindMemoryCount,
const VkVideoBindMemoryKHR* pVideoSessionBindMemories);
-
deviceis the logical device that owns the video session’s memory. -
videoSessionis the video session to be bound with device memory. -
videoSessionBindMemoryCountis the number ofpVideoSessionBindMemoriesto be bound. -
pVideoSessionBindMemoriesis a pointer to an array of VkVideoBindMemoryKHR structures specifying memory regions to be bound to a device memory heap.
The VkVideoBindMemoryKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoBindMemoryKHR {
VkStructureType sType;
const void* pNext;
uint32_t memoryBindIndex;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
VkDeviceSize memorySize;
} VkVideoBindMemoryKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryBindIndexis the index of the device memory heap returned in VkVideoGetMemoryPropertiesKHR::memoryBindIndexfrom vkGetVideoSessionMemoryRequirementsKHR. -
memoryis the allocated device memory to be bound to the video session’s heap with indexmemoryBindIndex. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound. -
memorySizeis the size in bytes of the region ofmemory, starting frommemoryOffsetbytes, to be bound.
39.4.4. Video Session Parameters
This specification supports several classes of preprocessed parameters stored in Video Session Parameters objects. The Video Session Parameters objects reduces the number of parameters being dispatched and then processed by the implementation while recording video command buffers.
39.4.5. Creating Video Session Parameters
Video session parameter objects are represented by VkVideoSessionParametersKHR handles:
// Provided by VK_KHR_video_queue
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkVideoSessionParametersKHR)
To create a video session parameters object, call:
// Provided by VK_KHR_video_queue
VkResult vkCreateVideoSessionParametersKHR(
VkDevice device,
const VkVideoSessionParametersCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkVideoSessionParametersKHR* pVideoSessionParameters);
-
deviceis the logical device that was used for the creation of the video session object. -
pCreateInfois a pointer to VkVideoSessionParametersCreateInfoKHR structure specifying the video session parameters. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pVideoSessionParametersis a pointer to a VkVideoSessionParametersKHR handle in which the video session parameters object is returned.
The VkVideoSessionParametersCreateInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoSessionParametersCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoSessionParametersKHR videoSessionParametersTemplate;
VkVideoSessionKHR videoSession;
} VkVideoSessionParametersCreateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoSessionParametersTemplateis VK_NULL_HANDLE or a valid handle to a VkVideoSessionParametersKHR object. If this parameter represents a valid handle, then the underlying Video Session Parameters object will be used as a template for constructing the new video session parameters object. All of the template object’s current parameters will be inherited by the new object in such a case. Optionally, some of the template’s parameters can be updated or new parameters added to the newly constructed object via the extension-specific parameters. -
videoSessionis the video session object against which the video session parameters object is going to be created.
39.4.6. Updating the parameters of the Video Session Parameters object
To update, add, or remove video session parameters state, call:
// Provided by VK_KHR_video_queue
VkResult vkUpdateVideoSessionParametersKHR(
VkDevice device,
VkVideoSessionParametersKHR videoSessionParameters,
const VkVideoSessionParametersUpdateInfoKHR* pUpdateInfo);
-
deviceis the logical device that was used for the creation of the video session object. -
videoSessionParametersis the video session parameters object that is going to be updated. -
pUpdateInfois a pointer to aVkVideoSessionParametersUpdateInfoKHRstructure containing the session parameters update information.
The VkVideoSessionParametersUpdateInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoSessionParametersUpdateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t updateSequenceCount;
} VkVideoSessionParametersUpdateInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
updateSequenceCountis the sequence number of the object update with parameters, starting from1and incrementing the value by one with each subsequent update.
39.4.7. Destroying Video Session Parameters
To destroy a video session parameters object, call:
// Provided by VK_KHR_video_queue
void vkDestroyVideoSessionParametersKHR(
VkDevice device,
VkVideoSessionParametersKHR videoSessionParameters,
const VkAllocationCallbacks* pAllocator);
-
deviceis the device the video session parameters object was created with. -
videoSessionParametersis the video session parameters object to be destroyed. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
39.4.8. Video Encode and Decode commands
To start video decode or encode operations, call:
// Provided by VK_KHR_video_queue
void vkCmdBeginVideoCodingKHR(
VkCommandBuffer commandBuffer,
const VkVideoBeginCodingInfoKHR* pBeginInfo);
-
commandBufferis the command buffer to be used when recording commands for the video decode or encode operations. -
pBeginInfois a pointer to a VkVideoBeginCodingInfoKHR structure.
The VkVideoBeginCodingInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoBeginCodingInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoBeginCodingFlagsKHR flags;
VkVideoCodingQualityPresetFlagsKHR codecQualityPreset;
VkVideoSessionKHR videoSession;
VkVideoSessionParametersKHR videoSessionParameters;
uint32_t referenceSlotCount;
const VkVideoReferenceSlotKHR* pReferenceSlots;
} VkVideoBeginCodingInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
codecQualityPresetis a bitmask of VkVideoCodingQualityPresetFlagBitsKHR specifying the Video Decode or Encode quality preset. -
videoSessionis the video session object to be bound for the processing of the video commands. -
videoSessionParametersis VK_NULL_HANDLE or a handle of a VkVideoSessionParametersKHR object to be used for the processing of the video commands. If VK_NULL_HANDLE, then no video session parameters apply to this command buffer context. -
referenceSlotCountis the number of reference slot entries provided inpReferenceSlots. -
pReferenceSlotsis a pointer to an array of VkVideoReferenceSlotKHR structures specifying reference slots, used within the video command context between this vkCmdBeginVideoCodingKHR command and the vkCmdEndVideoCodingKHR commmand that follows. Each reference slot provides a slot index and the VkVideoPictureResourceKHR specifying the reference picture resource bound to this slot index. A slot index must not appear more than once inpReferenceSlotsin a given command.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoBeginCodingFlagsKHR;
VkVideoBeginCodingFlagsKHR is a bitmask type for setting a mask, but
is currently reserved for future use.
The decode preset types are defined with the following:
// Provided by VK_KHR_video_queue
typedef enum VkVideoCodingQualityPresetFlagBitsKHR {
VK_VIDEO_CODING_QUALITY_PRESET_NORMAL_BIT_KHR = 0x00000001,
VK_VIDEO_CODING_QUALITY_PRESET_POWER_BIT_KHR = 0x00000002,
VK_VIDEO_CODING_QUALITY_PRESET_QUALITY_BIT_KHR = 0x00000004,
} VkVideoCodingQualityPresetFlagBitsKHR;
-
VK_VIDEO_CODING_QUALITY_PRESET_NORMAL_BIT_KHRdefines normal decode case. -
VK_VIDEO_CODING_QUALITY_PRESET_POWER_BIT_KHRdefines power efficient case. -
VK_VIDEO_CODING_QUALITY_PRESET_QUALITY_BIT_KHRdefines quality focus case.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoCodingQualityPresetFlagsKHR;
VkVideoCodingQualityPresetFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoCodingQualityPresetFlagBitsKHR.
The VkVideoReferenceSlotKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoReferenceSlotKHR {
VkStructureType sType;
const void* pNext;
int8_t slotIndex;
const VkVideoPictureResourceKHR* pPictureResource;
} VkVideoReferenceSlotKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
slotIndexis the unique reference slot index used for the encode or decode operation. -
pPictureResourceis a pointer to a VkVideoPictureResourceKHR structure describing the picture resource bound to this slot index.
The VkVideoPictureResourceKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoPictureResourceKHR {
VkStructureType sType;
const void* pNext;
VkOffset2D codedOffset;
VkExtent2D codedExtent;
uint32_t baseArrayLayer;
VkImageView imageViewBinding;
} VkVideoPictureResourceKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
codedOffsetis the offset to be used for the picture resource. -
codedExtentis the extent to be used for the picture resource. -
baseArrayLayeris the first array layer to be accessed for the Decode or Encode Operations. -
imageViewBindingis a VkImageView image view representing this picture resource.
39.4.9. End of the Video Session
To end video decode or encode operations, call:
// Provided by VK_KHR_video_queue
void vkCmdEndVideoCodingKHR(
VkCommandBuffer commandBuffer,
const VkVideoEndCodingInfoKHR* pEndCodingInfo);
-
commandBufferis the command buffer to be filled by this function. -
pEndCodingInfois a pointer to a VkVideoEndCodingInfoKHR structure.
The VkVideoEndCodingInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoEndCodingInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEndCodingFlagsKHR flags;
} VkVideoEndCodingInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoEndCodingFlagsKHR;
VkVideoEndCodingFlagsKHR is a bitmask type for setting a mask, but is
currently reserved for future use.
39.4.10. Video Session Control Command
To apply dynamic controls to video decode or video encode operations, call:
// Provided by VK_KHR_video_queue
void vkCmdControlVideoCodingKHR(
VkCommandBuffer commandBuffer,
const VkVideoCodingControlInfoKHR* pCodingControlInfo);
-
commandBufferis the command buffer to be filled by this function. -
pCodingControlInfois a pointer to a VkVideoCodingControlInfoKHR structure.
The settings provided in this call are applied to the video stream at the
time of queue submission and are in effect until the submission of a
subsequent vkCmdControlVideoCodingKHR.
The VkVideoCodingControlInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoCodingControlInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoCodingControlFlagsKHR flags;
} VkVideoCodingControlInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoCodingControlFlagsKHR specifying control flags.
The vkCmdControlVideoCodingKHR flags are defined with the following enumeration:
// Provided by VK_KHR_video_queue
typedef enum VkVideoCodingControlFlagBitsKHR {
VK_VIDEO_CODING_CONTROL_DEFAULT_KHR = 0,
VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR = 0x00000001,
} VkVideoCodingControlFlagBitsKHR;
-
VK_VIDEO_CODING_CONTROL_DEFAULT_KHRindicates a request for the coding control paramaters to be applied to the current state of the bound video session. -
VK_VIDEO_CODING_CONTROL_RESET_BIT_KHRindicates a request for the bound video session device context to be reset before the coding control parameters are applied.
A newly created video session must be reset before use for video decode or encode operations. The reset operation returns all session DPB slots to the unused state (see DPB Slot States). For encode sessions, the reset operation returns rate control configuration to implementation default settings. After decode or encode operations are performed on a session, the reset operation may be used to return the video session device context to the same initial state as after the reset of a newly created video session. This may be used when different video sequences are processed with the same session.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoCodingControlFlagsKHR;
VkVideoCodingControlFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoCodingControlFlagBitsKHR.
39.5. Video Decode Operations
Before the application can start recording Vulkan command buffers for the Video Decode Operations, it must do the following, beforehand:
-
Ensure that the implementation can decode the Video Content by querying the supported codec operations and profiles using vkGetPhysicalDeviceQueueFamilyProperties2.
-
By using vkGetPhysicalDeviceVideoFormatPropertiesKHR and providing one or more video profiles, choose the Vulkan formats supported by the implementation. The formats for output and reference pictures must be queried and chosen separately. Refer to the section on enumeration of supported video formats.
-
Before creating an image to be used as a video picture resource, obtain the supported image creation parameters by querying with vkGetPhysicalDeviceFormatProperties2 and vkGetPhysicalDeviceImageFormatProperties2 using one of the reported formats and adding VkVideoProfilesKHR to the
pNextchain of VkFormatProperties2. When querying the parameters with vkGetPhysicalDeviceImageFormatProperties2 for images targeting decoded output and reference (DPB) pictures, the VkPhysicalDeviceImageFormatInfo2::usagefield should containVK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHRandVK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, respectively. -
Create none, some, or all of the required images for the decoded output and reference pictures. More Video Picture Resources can be created at some later point if needed while processing the decoded content. Also, if the decoded picture size is expected to change, the images can be created based on the maximum decoded content size required.
-
Create the video session to be used for video decode operations. Before creating the Decode Video Session, the decode capabilities should be queried with vkGetPhysicalDeviceVideoCapabilitiesKHR to obtain the limits of the parameters allowed by the implementation for a particular codec profile.
-
Bind memory resources with the decode video session by calling vkBindVideoSessionMemoryKHR. The video session cannot be used until memory resources are allocated and bound to it. In order to determine the required memory sizes and heap types of the device memory allocations, vkGetVideoSessionMemoryRequirementsKHR should be called.
-
Create one or more Session Parameter objects for use across command buffer recording operations, if required by the codec extension in use. These objects must be created against a video session with the parameters required by the codec. Each Session Parameter object created is a child object of the associated Session object and cannot be bound in the command buffer with any other Session Object.
The recording of Video Decode Commands against a Vulkan command buffer consists of the following sequence:
-
vkCmdBeginVideoCodingKHR starts the recording of one or more Video Decode operations in the command buffer. For each Video Decode Command operation, a Video Session must be bound to the command buffer within this command. This command establishes a Vulkan Video Decode Context that consists of the bound Video Session Object, Session Parameters Object, and the required Video Picture Resources. The established Video Decode Context is in effect until the vkCmdEndVideoCodingKHR command is recorded. If more Video Decode operations are to be required after the vkCmdEndVideoCodingKHR command, another Video Decode Context can be started with the vkCmdBeginVideoCodingKHR command.
-
vkCmdDecodeVideoKHR specifies one or more compressed data buffers to be decoded. The VkVideoDecodeInfoKHR parameters, and the codec extension structures chained to this, specify the details of the decode operation.
-
vkCmdControlVideoCodingKHR records operations against the decoded data, decoding device, or the Video Session state.
-
vkCmdEndVideoCodingKHR signals the end of the recording of the Vulkan Video Decode Context, as established by vkCmdBeginVideoCodingKHR.
In addition to the above, the following commands can be recorded between vkCmdBeginVideoCodingKHR and vkCmdEndVideoCodingKHR:
-
Query operations
-
Global Memory Barriers
-
Buffer Memory Barriers
-
Image Memory Barriers (these must be used to transition the Video Picture Resources to the proper
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHRandVK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHRlayouts). -
Pipeline Barriers
-
Events
-
Timestamps
-
Device Groups (device mask)
The following Video Decode related commands must be recorded outside the Vulkan Video Decode Context established with the vkCmdBeginVideoCodingKHR and vkCmdEndVideoCodingKHR commands:
-
Sparse Memory Binding
-
Copy Commands
-
Clear Commands
39.5.1. Video Picture Decode Modes
There are a few ways that the vkCmdDecodeVideoKHR can be configured for the Video Picture Decode Operations, based on:
-
if the output resource would need to be used as Reference Picture for subsequent decode operations and;
-
if DPB Slots are required for use as Reference Pictures indexes.
The most basic Video Picture Decode operation with the vkCmdDecodeVideoKHR command is to output the decoded pixel data without using any DPB Reference Pictures and without updating any DPB Slot’s indexes.
In this case, the following VkVideoDecodeInfoKHR parameters must be set:
-
VkVideoDecodeInfoKHR::
pSetupReferenceSlot->pPictureResource->imageViewBindingmust be a valid VkImageView. This VkImageView represents the output resource where the decoded pixels will be populated after a successful decode operation. -
VkVideoDecodeInfoKHR::
pSetupReferenceSlot->slotIndexmust be an invalid DPB Slot index (-1) since the decoded picture is not intended to be used as a reference picture with subsequent video decode operations. -
The value of the VkVideoDecodeInfoKHR::
referenceSlotCountcan be0and VkVideoDecodeInfoKHR::pReferenceSlotscan beNULL. -
If VkVideoDecodeInfoKHR::
pReferenceSlotsis notNULL, it can still have entries representing DPB Slot indexes with a Valid Picture Reference. The codec extension selects the actual use of the Reference Pictures by referring to a DPB Slot index with a Valid Picture Reference.
Video Picture Decode operations with the vkCmdDecodeVideoKHR command, requiring one or more Reference Pictures for the predictions of the values of samples for the decoded output picture would require DPB Slots with Valid Picture Reference.
In this case, the following VkVideoDecodeInfoKHR parameters must be set:
-
VkVideoDecodeInfoKHR::
pSetupReferenceSlot->pPictureResource->imageViewBindingmust be a valid VkImageView. This VkImageView represents the output resource where the decoded pixels will be populated after a successful decode operation. -
VkVideoDecodeInfoKHR::
pSetupReferenceSlot->slotIndexmust be an invalid DPB Slot index (-1) since the decoded picture is not intended to be used as a reference picture with subsequent video decode operations. -
The value of the VkVideoDecodeInfoKHR::
referenceSlotCountmust not be0and VkVideoDecodeInfoKHR::pReferenceSlotsshould represent at least the number of the reference slots required for the decode operation. The codec extension selects the actual use of the Reference Pictures by referring to a DPB Slot index with a Valid Picture Reference. If the implementation does not use an opaque DPB, each DPB slot representing a reference picture must refer to a valid image view. The image views must represent the same image resources that were used to create the reference picture for the corresponding DPB Slot index. -
VkVideoDecodeInfoKHR::
pReferenceSlotscan still have entries representing DPB Slot indexes with a Valid Picture Reference.
After the vkCmdDecodeVideoKHR operation is completed successfully, the
VkVideoDecodeInfoKHR::pSetupReferenceSlot->pPictureResource->imageViewBinding
pixel data will be updated with the decoded content.
The operation will not update any DPB Slot with
Reference Pictures data.
However, any DPB Slot activation, invalidation, or deactivation
operations requested via VkVideoDecodeInfoKHR::pReferenceSlots
are still going to be performed.
Video Picture Decode with a Reference Picture slot update and using optional Reference Pictures
When it is known that the picture to be decoded will be used as a reference picture for subsequent decode operations, one of the available DPB Slots needs to be selected for activation and update operations as part of the vkCmdDecodeVideoKHR command.
Based on whether a decode operation with reference pictures or without reference pictures is required, the vkCmdDecodeVideoKHR should be configured with parameters as described in the previous sections. In addition, one of the available DPB Slots must be selected by the application, activated with resources and then set-up for an update with the decode operation.
In this case, the following VkVideoDecodeInfoKHR parameters must be set:
-
VkVideoDecodeInfoKHR::
pSetupReferenceSlot->pPictureResource->imageViewBindingmust be a valid VkImageView. This VkImageView represents the output resource where the decoded pixels will be populated after a successful decode operation. If the implementation does not use an opaque DPB, both the output and reference picture resource coincide. -
VkVideoDecodeInfoKHR::
pSetupReferenceSlot->slotIndexmust be a valid DPB Slot index selected by the application, based on the currently available slots. -
VkVideoDecodeInfoKHR::
pReferenceSlotscan still have entries representing DPB Slot indexes with a Valid Picture Reference.
After the vkCmdDecodeVideoKHR operation has completed successfully,
the decoded content will be available in the resource provided for
VkVideoDecodeInfoKHR::pSetupReferenceSlot->pPictureResource->imageViewBinding.
In addition, this operation will update the selected DPB Slot
with Reference Pictures data.
Any other DPB Slot activation,invalidation, or deactivation
operation requested via the
VkVideoDecodeInfoKHR::pReferenceSlots are going to be performed
as well.
39.5.2. Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR with
pVideoProfile->videoCodecOperation specified as one of the decode
operation bits, the VkVideoDecodeCapabilitiesKHR structure must be
included in the pNext chain of the VkVideoCapabilitiesKHR
structure to retrieve capabilities specific to video decoding.
The VkVideoDecodeCapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_decode_queue
typedef struct VkVideoDecodeCapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkVideoDecodeCapabilityFlagsKHR flags;
} VkVideoDecodeCapabilitiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoDecodeCapabilityFlagBitsKHR describing supported decoding features.
// Provided by VK_KHR_video_decode_queue
typedef VkFlags VkVideoDecodeCapabilityFlagsKHR;
VkVideoDecodeCapabilityFlagsKHR is a bitmask type for setting a mask
of zero or more VkVideoDecodeCapabilityFlagBitsKHR.
Bits which may be set in VkVideoDecodeCapabilitiesKHR::flags,
indicating the decoding features supported, are:
// Provided by VK_KHR_video_decode_queue
typedef enum VkVideoDecodeCapabilityFlagBitsKHR {
VK_VIDEO_DECODE_CAPABILITY_DEFAULT_KHR = 0,
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR = 0x00000001,
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR = 0x00000002,
} VkVideoDecodeCapabilityFlagBitsKHR;
-
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR- reports the implementation supports using the same Video Picture Resource for decode DPB and decode output. -
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR- reports the implementation supports using distinct Video Picture Resources for decode DPB and decode output.
An implementation must report at least one of
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR or
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR as
supported.
|
Note:
If both |
39.5.3. Video Decode Command Buffer Commands
To decode a frame, call:
// Provided by VK_KHR_video_decode_queue
void vkCmdDecodeVideoKHR(
VkCommandBuffer commandBuffer,
const VkVideoDecodeInfoKHR* pFrameInfo);
-
commandBufferis the command buffer to be filled with this function for decode frame command. -
pFrameInfois a pointer to a VkVideoDecodeInfoKHR structure.
The VkVideoDecodeInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_queue
typedef struct VkVideoDecodeInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoDecodeFlagsKHR flags;
VkBuffer srcBuffer;
VkDeviceSize srcBufferOffset;
VkDeviceSize srcBufferRange;
VkVideoPictureResourceKHR dstPictureResource;
const VkVideoReferenceSlotKHR* pSetupReferenceSlot;
uint32_t referenceSlotCount;
const VkVideoReferenceSlotKHR* pReferenceSlots;
} VkVideoDecodeInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. All the codec specific structures related to each frame(picture parameters, quantization matrix, etc.) must be chained here and pass to decode session with the function call vkCmdDecodeVideoKHR. -
flagsis a bitmask of VkVideoDecodeFlagBitsKHR specifying decode flags, reserved for future versions of this specification. -
srcBufferis the source buffer that holds the encoded bitstream. -
srcBufferOffsetis the buffer offset where the valid encoded bitstream starts in srcBuffer. It must meet the alignment requirementminBitstreamBufferOffsetAlignmentwithin VkVideoCapabilitiesKHR queried with the vkGetPhysicalDeviceVideoCapabilitiesKHR function. -
srcBufferRangeis the size of the srcBuffer with valid encoded bitstream, starting fromsrcBufferOffset. It must meet the alignment requirementminBitstreamBufferSizeAlignmentwithin VkVideoCapabilitiesKHR queried with the vkGetPhysicalDeviceVideoCapabilitiesKHR function. -
dstPictureResourceis the destination Decoded Output Picture Resource. -
pSetupReferenceSlotisNULLor a pointer to a VkVideoReferenceSlotKHR structure used for generating a DPB reference slot and Picture Resource.pSetupReferenceSlot->slotIndexspecifies the slot index number to use as a target for producing the DPB data.slotIndexmust reference a valid entry as specified in VkVideoBeginCodingInfoKHR via thepReferenceSlotswithin the vkCmdBeginVideoCodingKHR command that established the Vulkan Video Decode Context for this command. -
referenceSlotCountis the number of the DPB Reference Pictures that will be used when this decoding operation is executing. -
pReferenceSlotsis a pointer to an array of VkVideoReferenceSlotKHR structures specifying the DPB Reference pictures that will be used when this decoding operation is executing.
The coded size of the decode operation is specified in codedExtent of
dstPictureResource.
The coded offset of the decode operation is specified in codedOffset
of dstPictureResource.
The purpose of this field is interpreted based on the codec extension.
When decoding content in H.264 field mode, codedOffset specifies the
line or picture field’s offset within the image.
The vkCmdDecodeVideoKHR flags are defined with the following enumeration:
// Provided by VK_KHR_video_decode_queue
typedef enum VkVideoDecodeFlagBitsKHR {
VK_VIDEO_DECODE_DEFAULT_KHR = 0,
VK_VIDEO_DECODE_RESERVED_0_BIT_KHR = 0x00000001,
} VkVideoDecodeFlagBitsKHR;
-
VK_VIDEO_DECODE_RESERVED_0_BIT_KHRThe current version of the specification has reserved this value for future use.
// Provided by VK_KHR_video_decode_queue
typedef VkFlags VkVideoDecodeFlagsKHR;
VkVideoDecodeFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoDecodeFlagBitsKHR.
39.6. Video Decode of AVC (ITU-T H.264)
This extension adds H.264 codec specific structures needed for decode session to execute decode jobs which include H.264 sequence header, picture parameter header and quantization matrix etc. Unless otherwise noted, all references to the H.264 specification are to the 2010 edition published by the ITU-T, dated March 2010. This specification is available at https://www.itu.int/rec/T-REC-H.264.
39.6.1. H.264 decode profile
A H.264 decode profile is specified using VkVideoDecodeH264ProfileEXT
chained to VkVideoProfileKHR when the codec-operation in
VkVideoProfileKHR is
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_EXT.
The VkVideoDecodeH264ProfileEXT structure is defined as:
// Provided by VK_EXT_video_decode_h264
typedef struct VkVideoDecodeH264ProfileEXT {
VkStructureType sType;
const void* pNext;
StdVideoH264ProfileIdc stdProfileIdc;
VkVideoDecodeH264PictureLayoutFlagsEXT pictureLayout;
} VkVideoDecodeH264ProfileEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileIdcis aStdVideoH264ProfileIdcvalue specifying the H.264 codec profile IDC -
pictureLayoutis a bitmask of VkVideoDecodeH264PictureLayoutFlagBitsEXT specifying the layout of the decoded picture’s contents depending on the nature (progressive vs. interlaced) of the input content.
|
Note
When passing |
// Provided by VK_EXT_video_decode_h264
typedef VkFlags VkVideoDecodeH264PictureLayoutFlagsEXT;
VkVideoDecodeH264PictureLayoutFlagsEXT is a bitmask type for setting a
mask of zero or more VkVideoDecodeH264PictureLayoutFlagBitsEXT.
The H.264 video decode picture layout flags are defined with the following enum:
// Provided by VK_EXT_video_decode_h264
typedef enum VkVideoDecodeH264PictureLayoutFlagBitsEXT {
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_PROGRESSIVE_EXT = 0,
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_EXT = 0x00000001,
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_EXT = 0x00000002,
} VkVideoDecodeH264PictureLayoutFlagBitsEXT;
-
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_PROGRESSIVE_EXTspecifies support for progressive content. This flag has the value0. -
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_EXTspecifies support for or use of a picture layout for interlaced content where all lines belonging to the first field are decoded to the even-numbered lines within the picture resource, and all lines belonging to the second field are decoded to the odd-numbered lines within the picture resource. -
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_EXTspecifies support for or use of a picture layout for interlaced content where all lines belonging to the first field are grouped together in a single plane, followed by another plane containing all lines belonging to the second field.
39.6.2. Selecting a H.264 decode profile
When using vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for the input pVideoProfile with
videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_EXT, a
VkVideoDecodeH264ProfileEXT structure must be chained to
VkVideoProfileKHR to select a H.264 decode profile.
If supported, the implementation returns the capabilities associated with
the specified H.264 decode profile.
The requirement is similar when querying supported image formats using
vkGetPhysicalDeviceVideoFormatPropertiesKHR.
A supported H.264 decode profile must be selected when creating a video session by chaining VkVideoDecodeH264ProfileEXT to the VkVideoProfileKHR field of VkVideoSessionCreateInfoKHR.
39.6.3. Capabilities
The VkVideoDecodeH264CapabilitiesEXT structure is defined as:
// Provided by VK_EXT_video_decode_h264
typedef struct VkVideoDecodeH264CapabilitiesEXT {
VkStructureType sType;
void* pNext;
StdVideoH264Level maxLevel;
VkOffset2D fieldOffsetGranularity;
} VkVideoDecodeH264CapabilitiesEXT;
When using vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for the input pVideoProfile with
videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_EXT, a
VkVideoDecodeH264CapabilitiesEXT structure must be chained to
VkVideoCapabilitiesKHR to get this H.264 decode profile specific
capabilities.
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxLevelis the maximum H.264 level supported by the device. -
fieldOffsetGranularity- if Interlaced Video Content is suported, the maximum field offset granularity supported for the picture resource.
39.6.4. Decoder Parameter Sets
To reduce parameter traffic during decoding, the decoder parameter set object supports storing H.264 SPS/PPS parameter sets that may be later referenced during decoding.
The VkVideoDecodeH264SessionParametersCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_video_decode_h264
typedef struct VkVideoDecodeH264SessionParametersCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t maxSpsStdCount;
uint32_t maxPpsStdCount;
const VkVideoDecodeH264SessionParametersAddInfoEXT* pParametersAddInfo;
} VkVideoDecodeH264SessionParametersCreateInfoEXT;
A VkVideoDecodeH264SessionParametersCreateInfoEXT structure holding one H.264 SPS and at least one H.264 PPS paramater set must be chained to VkVideoSessionParametersCreateInfoKHR when calling vkCreateVideoSessionParametersKHR to store these parameter set(s) with the decoder parameter set object for later reference. The provided H.264 SPS/PPS parameters must be within the limits specified during decoder creation for the decoder specified in VkVideoSessionParametersCreateInfoKHR.
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxSpsStdCountis the maximum number of SPS parameters that theVkVideoSessionParametersKHRcan contain. -
maxPpsStdCountis the maximum number of PPS parameters that theVkVideoSessionParametersKHRcan contain. -
pParametersAddInfoisNULLor a pointer to a VkVideoDecodeH264SessionParametersAddInfoEXT structure specifying H.264 parameters to add upon object creation.
The VkVideoDecodeH264SessionParametersAddInfoEXT structure is defined
as:
// Provided by VK_EXT_video_decode_h264
typedef struct VkVideoDecodeH264SessionParametersAddInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t spsStdCount;
const StdVideoH264SequenceParameterSet* pSpsStd;
uint32_t ppsStdCount;
const StdVideoH264PictureParameterSet* pPpsStd;
} VkVideoDecodeH264SessionParametersAddInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
spsStdCountis the number of SPS elements inpSpsStd. Its value must be less than or equal to the value ofmaxSpsStdCount. -
pSpsStdis a pointer to an array ofStdVideoH264SequenceParameterSetstructures representing H.264 sequence parameter sets. Each element of the array must have a unique H.264 SPS ID. -
ppsStdCountis the number of PPS provided inpPpsStd. Its value must be less than or equal to the value ofmaxPpsStdCount. -
pPpsStdis a pointer to an array ofStdVideoH264PictureParameterSetstructures representing H.264 picture parameter sets. Each element of the array must have a unique H.264 SPS-PPS ID pair.
39.6.5. Picture Decoding
To decode a picture, the structure VkVideoDecodeH264PictureInfoEXT may be chained to VkVideoDecodeInfoKHR when calling vkCmdDecodeVideoKHR.
The VkVideoDecodeH264PictureInfoEXT structure represents a picture decode operation and is defined as:
// Provided by VK_EXT_video_decode_h264
typedef struct VkVideoDecodeH264PictureInfoEXT {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeH264PictureInfo* pStdPictureInfo;
uint32_t slicesCount;
const uint32_t* pSlicesDataOffsets;
} VkVideoDecodeH264PictureInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdPictureInfois a pointer to aStdVideoDecodeH264PictureInfostructure specifying the codec standard specific picture information from the H.264 specification. -
slicesCountis the number of slices in this picture. -
pSlicesDataOffsetsis a pointer to an array ofslicesCountoffsets indicating the start offset of each slice within the bitstream buffer.
The VkVideoDecodeH264DpbSlotInfoEXT structure correlates a DPB Slot index with codec-specific information and is defined as:
// Provided by VK_EXT_video_decode_h264
typedef struct VkVideoDecodeH264DpbSlotInfoEXT {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeH264ReferenceInfo* pStdReferenceInfo;
} VkVideoDecodeH264DpbSlotInfoEXT;
-
sTypeis the type of this structure. -
pStdReferenceInfois a pointer to aStdVideoDecodeH264ReferenceInfostructure specifying the codec standard specific picture reference information from the H.264 specification.
The VkVideoDecodeH264MvcEXT structure is defined as:
// Provided by VK_EXT_video_decode_h264
typedef struct VkVideoDecodeH264MvcEXT {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeH264Mvc* pStdMvc;
} VkVideoDecodeH264MvcEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdMvcis a pointer to aStdVideoDecodeH264Mvcstructure specifying H.264 codec specification information for MVC.
When the content type is H.264 MVC, a VkVideoDecodeH264MvcEXT structure must be chained to VkVideoDecodeH264PictureInfoEXT.
39.7. Video Decode of HEVC (ITU-T H.265)
This extension adds H.265 codec specific structures needed for decode session to execute decode jobs which include H.265 sequence header, picture parameter header and quantization matrix etc. Unless otherwise noted, all references to the H.265 specification are to the 2013 edition published by the ITU-T, dated April 2013. This specification is available at https://www.itu.int/rec/T-REC-H.265.
39.7.1. H.265 decode profile
A H.265 decode profile is specified using VkVideoDecodeH265ProfileEXT
chained to VkVideoProfileKHR when the codec-operation in
VkVideoProfileKHR is
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_EXT.
The VkVideoDecodeH265ProfileEXT structure is defined as:
// Provided by VK_EXT_video_decode_h265
typedef struct VkVideoDecodeH265ProfileEXT {
VkStructureType sType;
const void* pNext;
StdVideoH265ProfileIdc stdProfileIdc;
} VkVideoDecodeH265ProfileEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileIdcis aStdVideoH265ProfileIdcvalue specifying the H.265 codec profile IDC.
39.7.2. Selecting an H.265 Profile
When using vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for the input pVideoProfile with
videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_EXT, a
VkVideoDecodeH265ProfileEXT structure must be chained to
VkVideoProfileKHR to select a H.265 decode profile.
If supported, the implementation returns the capabilities associated with
the specified H.265 decode profile.
The requirement is similar when querying supported image formats using
vkGetPhysicalDeviceVideoFormatPropertiesKHR.
A supported H.265 decode profile must be selected when creating a video session by chaining VkVideoDecodeH265ProfileEXT to the VkVideoProfileKHR field of VkVideoSessionCreateInfoKHR.
39.7.3. Capabilities
The VkVideoDecodeH265CapabilitiesEXT structure is defined as:
// Provided by VK_EXT_video_decode_h265
typedef struct VkVideoDecodeH265CapabilitiesEXT {
VkStructureType sType;
void* pNext;
StdVideoH265Level maxLevel;
} VkVideoDecodeH265CapabilitiesEXT;
When using vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for the parameter videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_EXT, a
VkVideoDecodeH265CapabilitiesEXT structure can be chained to
VkVideoCapabilitiesKHR to return this H.265 extension specific
capabilities.
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxLevelis the maximum H.265 level supported by the device.
39.7.4. Decoder Parameter Sets
To reduce parameter traffic during decoding, the decoder parameter set object supports storing H.265 VPS/SPS/PPS parameter sets that may be later referenced during decoding.
The VkVideoDecodeH265SessionParametersCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_video_decode_h265
typedef struct VkVideoDecodeH265SessionParametersCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t maxVpsStdCount;
uint32_t maxSpsStdCount;
uint32_t maxPpsStdCount;
const VkVideoDecodeH265SessionParametersAddInfoEXT* pParametersAddInfo;
} VkVideoDecodeH265SessionParametersCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxVpsStdCountis the maximum number of entries of typeStdVideoH265VideoParameterSetwithinVkVideoSessionParametersKHR. -
maxSpsStdCountis the maximum number of SPS parameters that theVkVideoSessionParametersKHRcan contain. -
maxPpsStdCountis the maximum number of PPS parameters that theVkVideoSessionParametersKHRcan contain. -
pParametersAddInfoisNULLor a pointer to a VkVideoDecodeH265SessionParametersAddInfoEXT structure specifying H.265 parameters to add upon object creation.
When a VkVideoSessionParametersKHR object contains
maxVpsStdCount StdVideoH265VideoParameterSet entries, no
additional StdVideoH265VideoParameterSet entries can be added to it,
and VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made
to add these entries.
When a VkVideoSessionParametersKHR object contains
maxSpsStdCount StdVideoH265SequenceParameterSet entries, no
additional StdVideoH265SequenceParameterSet entries can be added to it,
and VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made
to add these entries.
When a VkVideoSessionParametersKHR object contains
maxPpsStdCount StdVideoH265PictureParameterSet entries, no
additional StdVideoH265PictureParameterSet entries can be added to it,
and VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made
to add these entries.
The provided H.265 VPS/SPS/PPS parameters must be within the limits
specified during decoder creation for the decoder specified in
VkVideoSessionParametersCreateInfoKHR.
The VkVideoDecodeH265SessionParametersAddInfoEXT structure is defined
as:
// Provided by VK_EXT_video_decode_h265
typedef struct VkVideoDecodeH265SessionParametersAddInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t vpsStdCount;
const StdVideoH265VideoParameterSet* pVpsStd;
uint32_t spsStdCount;
const StdVideoH265SequenceParameterSet* pSpsStd;
uint32_t ppsStdCount;
const StdVideoH265PictureParameterSet* pPpsStd;
} VkVideoDecodeH265SessionParametersAddInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vpsStdCountis the number of VPS elements inpVpsStd. -
pVpsStdis a pointer to an array ofvpsStdCountStdVideoH265VideoParameterSetstructures representing H.265 video parameter sets. -
spsStdCountis the number of SPS elements in thepSpsStd. Its value must be less than or equal to the value ofmaxSpsStdCount. -
pSpsStdis a pointer to an array ofStdVideoH265SequenceParameterSetstructures representing H.265 sequence parameter sets. Each element of the array must have a unique H.265 VPS-SPS ID pair. -
ppsStdCountis the number of PPS provided inpPpsStd. Its value must be less than or equal to the value ofmaxPpsStdCount. -
pPpsStdis a pointer to an array ofStdVideoH265PictureParameterSetstructures representing H.265 picture parameter sets. Each element of the array entry must have a unique H.265 VPS-SPS-PPS ID tuple.
39.7.5. Picture Parameters
The VkVideoDecodeH265PictureInfoEXT structure is defined as:
// Provided by VK_EXT_video_decode_h265
typedef struct VkVideoDecodeH265PictureInfoEXT {
VkStructureType sType;
const void* pNext;
StdVideoDecodeH265PictureInfo* pStdPictureInfo;
uint32_t slicesCount;
const uint32_t* pSlicesDataOffsets;
} VkVideoDecodeH265PictureInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdPictureInfois a pointer to aStdVideoDecodeH265PictureInfostructure specifying codec standard specific picture information from the H.265 specification. -
slicesCountis the number of slices in this picture. -
pSlicesDataOffsetsis a pointer to an array ofslicesCountoffsets indicating the start offset of each slice within the bitstream buffer.
The VkVideoDecodeH265DpbSlotInfoEXT structure is defined as:
// Provided by VK_EXT_video_decode_h265
typedef struct VkVideoDecodeH265DpbSlotInfoEXT {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeH265ReferenceInfo* pStdReferenceInfo;
} VkVideoDecodeH265DpbSlotInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdReferenceInfois a pointer to aStdVideoDecodeH265ReferenceInfostructure specifying the codec standard specific picture reference information from the H.264 specification.
39.8. Video Encode Operations
Before the application can start recording Vulkan command buffers for the Video Encode Operations, it must do the following, beforehand:
-
Ensure that the implementation can encode the Video Content by querying the supported codec operations and profiles using vkGetPhysicalDeviceQueueFamilyProperties2.
-
By using vkGetPhysicalDeviceVideoFormatPropertiesKHR and providing one or more video profiles, choose the Vulkan formats supported by the implementation. The formats for input and reference pictures must be queried and chosen separately. Refer to the section on enumeration of supported video formats.
-
Before creating an image to be used as a video picture resource, obtain the supported image creation parameters by querying with vkGetPhysicalDeviceFormatProperties2 and vkGetPhysicalDeviceImageFormatProperties2 using one of the reported formats and adding VkVideoProfilesKHR to the
pNextchain of VkFormatProperties2. When querying the parameters with vkGetPhysicalDeviceImageFormatProperties2 for images targeting input and reference (DPB) pictures, the VkPhysicalDeviceImageFormatInfo2::usagefield should containVK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHRandVK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, respectively. -
Create none, some, or all of the required images for the input and reference pictures. More Video Picture Resources can be created at some later point if needed while processing the content to be encoded. Also, if the size of the picture to be encoded is expected to change, the images can be created based on the maximum expected content size.
-
Create the video session to be used for video encode operations. Before creating the Encode Video Session, the encode capabilities should be queried with vkGetPhysicalDeviceVideoCapabilitiesKHR to obtain the limits of the parameters allowed by the implementation for a particular codec profile.
-
Bind memory resources with the encode video session by calling vkBindVideoSessionMemoryKHR. The video session cannot be used until memory resources are allocated and bound to it. In order to determine the required memory sizes and heap types of the device memory allocations, vkGetVideoSessionMemoryRequirementsKHR should be called.
-
Create one or more Session Parameter objects for use across command buffer recording operations, if required by the codec extension in use. These objects must be created against a video session with the parameters required by the codec. Each Session Parameter object created is a child object of the associated Session object and cannot be bound in the command buffer with any other Session Object.
The recording of Video Encode Commands against a Vulkan Command Buffer consists of the following sequence:
-
vkCmdBeginVideoCodingKHR starts the recording of one or more Video Encode operations in the command buffer. For each Video Encode Command operation, a Video Session must be bound to the command buffer within this command. This command establishes a Vulkan Video Encode Context that consists of the bound Video Session Object, Session Parameters Object, and the required Video Picture Resources. The established Video Encode Context is in effect until the vkCmdEndVideoCodingKHR command is recorded. If more Video Encode operations are to be required after the vkCmdEndVideoCodingKHR command, another Video Encode Context can be started with the vkCmdBeginVideoCodingKHR command.
-
vkCmdEncodeVideoKHR specifies one or more frames to be encoded. The VkVideoEncodeInfoKHR parameters, and the codec extension structures chained to this, specify the details of the encode operation.
-
vkCmdControlVideoCodingKHR records operations against the encoded data, encoding device, or the Video Session state.
-
vkCmdEndVideoCodingKHR signals the end of the recording of the Vulkan Video Encode Context, as established by vkCmdBeginVideoCodingKHR.
In addition to the above, the following commands can be recorded between vkCmdBeginVideoCodingKHR and vkCmdEndVideoCodingKHR:
-
Query operations
-
Global Memory Barriers
-
Buffer Memory Barriers
-
Image Memory Barriers (these must be used to transition the Video Picture Resources to the proper
VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHRandVK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHRlayouts). -
Pipeline Barriers
-
Events
-
Timestamps
-
Device Groups (device mask)
The following Video Encode related commands must be recorded outside the Vulkan Video Encode Context established with the vkCmdBeginVideoCodingKHR and vkCmdEndVideoCodingKHR commands:
-
Sparse Memory Binding
-
Copy Commands
-
Clear Commands
39.8.1. Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR with
pVideoProfile->videoCodecOperation specified as one of the encode
operation bits, the VkVideoEncodeCapabilitiesKHR structure must be
included in the pNext chain of the VkVideoCapabilitiesKHR
structure to retrieve capabilities specific to video encoding.
The VkVideoEncodeCapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeCapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeCapabilityFlagsKHR flags;
VkVideoEncodeRateControlModeFlagsKHR rateControlModes;
uint8_t rateControlLayerCount;
uint8_t qualityLevelCount;
VkExtent2D inputImageDataFillAlignment;
} VkVideoEncodeCapabilitiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeCapabilityFlagBitsKHR describing supported encoding features. -
rateControlModesis a bitmask of VkVideoEncodeRateControlModeFlagBitsKHR describing supported rate control modes. All implementations must supportVK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR. -
rateControlLayerCountreports the maximum number of rate control layers supported. Implementations must report at least 1. -
qualityLevelCountis the number of discrete quality levels supported. Implementations must report at least 1. -
inputImageDataFillAlignmentreports alignment of data that should be filled in the input image horizontally and vertically in pixels before encode operations are performed on the input image.
The input content and encode resolution (specified in
VkVideoEncodeInfoKHR::codedExtent) may not be aligned with the
codec-specific coding block size.
For example, the input content may be 1920x1080 and the coding block size
may be 16x16 pixel blocks.
In this example, the content is horizontally aligned with the coding block
size, but not vertically aligned with the coding block size.
Encoding of the last row of blocks may be impacted by contents of the input
image in pixel rows 1081 to 1088 (the next vertical alignment with the
coding block size).
In general, to ensure efficient encoding for the last row/column of blocks,
and/or to ensure consistent encoding results between repeated encoding of
the same input content, these extra pixel rows/columns should be filled to
known values up to the coding block size alignment before encoding
operations are performed.
Some implementations support performing auto-fill of unaligned pixels beyond
a specific alignment, which is reported in
inputImageDataFillAlignment.
For example, if an implementation reports 1x1 in
inputImageDataFillAlignment, then the implementation will perform
auto-fill for any unaligned pixels beyond the encode resolution up to the
next coding block size.
For a coding block size of 16x16, if the implementation reports 16x16 in
inputImageDataFillAlignment, then it is the application’s
responsibility to fill any unaligned pixels, if desired.
If not, it may impact the encoding efficiency, but it will not affect the
validity of the generated bitstream.
If the implementation reports 8x8 in inputImageDataFillAlignment, then
for the 1920x1080 example, since the content is aligned to 8 pixels
vertically, the implementation will auto-fill pixel rows 1081 to 1088 (up to
the 16x16 coding block size in the example).
The auto-fill value(s) are implementation-specific.
The auto-fill value(s) are not written to the input image memory, but are
used as part of the encoding operation on the input image.
// Provided by VK_KHR_video_encode_queue
typedef VkFlags VkVideoEncodeCapabilityFlagsKHR;
VkVideoEncodeCapabilityFlagsKHR is a bitmask type for setting a mask
of zero or more VkVideoEncodeCapabilityFlagBitsKHR.
Bits which may be set in VkVideoEncodeCapabilitiesKHR::flags,
indicating the encoding tools supported, are:
// Provided by VK_KHR_video_encode_queue
typedef enum VkVideoEncodeCapabilityFlagBitsKHR {
VK_VIDEO_ENCODE_CAPABILITY_DEFAULT_KHR = 0,
VK_VIDEO_ENCODE_CAPABILITY_PRECEDING_EXTERNALLY_ENCODED_BYTES_BIT_KHR = 0x00000001,
} VkVideoEncodeCapabilityFlagBitsKHR;
-
VK_VIDEO_ENCODE_CAPABILITY_PRECEDING_EXTERNALLY_ENCODED_BYTES_BIT_KHRreports that the implementation supports use of VkVideoEncodeInfoKHR::precedingExternallyEncodedBytes.
39.8.2. Video Encode Vulkan Command Buffer Commands
To launch an encode operation that results in bitstream generation, call:
// Provided by VK_KHR_video_encode_queue
void vkCmdEncodeVideoKHR(
VkCommandBuffer commandBuffer,
const VkVideoEncodeInfoKHR* pEncodeInfo);
-
commandBufferis the command buffer to be filled with this function for encoding to generate a bitstream. -
pEncodeInfois a pointer to a VkVideoEncodeInfoKHR structure.
The VkVideoEncodeInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeFlagsKHR flags;
uint32_t qualityLevel;
VkBuffer dstBitstreamBuffer;
VkDeviceSize dstBitstreamBufferOffset;
VkDeviceSize dstBitstreamBufferMaxRange;
VkVideoPictureResourceKHR srcPictureResource;
const VkVideoReferenceSlotKHR* pSetupReferenceSlot;
uint32_t referenceSlotCount;
const VkVideoReferenceSlotKHR* pReferenceSlots;
uint32_t precedingExternallyEncodedBytes;
} VkVideoEncodeInfoKHR;
-
sTypeis the type of this structure. -
pNextis a pointer to a structure extending this structure. A codec-specific extension structure must be chained to specify what bitstream unit to generate with this encode operation. -
flagsis a bitmask of VkVideoEncodeFlagBitsKHR specifying encode flags, and is reserved for future versions of this specification. -
qualityLevelis the coding quality level of the encoding. It is defined by the codec-specific extensions. -
dstBitstreamBufferis the buffer where the encoded bitstream output will be produced. -
dstBitstreamBufferOffsetis the offset in thedstBitstreamBufferwhere the encoded bitstream output will start.dstBitstreamBufferOffset’s value must be aligned to VkVideoCapabilitiesKHR::minBitstreamBufferOffsetAlignment, as reported by the implementation. -
dstBitstreamBufferMaxRangeis the maximum size of thedstBitstreamBufferthat can be used while the encoded bitstream output is produced.dstBitstreamBufferMaxRange’s value must be aligned to VkVideoCapabilitiesKHR::minBitstreamBufferSizeAlignment, as reported by the implementation. -
srcPictureResourceis the Picture Resource of the Input Picture to be encoded by the operation. -
pSetupReferenceSlotis a pointer to a VkVideoReferenceSlotKHR structure used for generating a reconstructed reference slot and Picture Resource.pSetupReferenceSlot->slotIndexspecifies the slot index number to use as a target for producing the Reconstructed (DPB) data.pSetupReferenceSlotmust be one of the entries provided in VkVideoBeginCodingInfoKHR via thepReferenceSlotswithin the vkCmdBeginVideoCodingKHR command that established the Vulkan Video Encode Context for this command. -
referenceSlotCountis the number of Reconstructed Reference Pictures that will be used when this encoding operation is executing. -
pReferenceSlotsisNULLor a pointer to an array of VkVideoReferenceSlotKHR structures that will be used when this encoding operation is executing. Each entry inpReferenceSlotsmust be one of the entries provided in VkVideoBeginCodingInfoKHR via thepReferenceSlotswithin the vkCmdBeginVideoCodingKHR command that established the Vulkan Video Encode Context for this command. -
precedingExternallyEncodedBytesis the number of bytes externally encoded for insertion in the active video encode session overall bitstream prior to the bitstream that will be generated by the implementation for this instance ofVkVideoEncodeInfoKHR. Valid when VkVideoEncodeRateControlInfoKHR::rateControlModeis notVK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR. The value provided is used to update the implementation’s rate control algorithm for the rate control layer this instance ofVkVideoEncodeInfoKHRbelongs to, by accounting for the bitrate budget consumed by these externally encoded bytes. See VkVideoEncodeRateControlInfoKHR for additional information about encode rate control.
The coded size of the encode operation is specified in codedExtent of
srcPictureResource.
Multiple vkCmdEncodeVideoKHR commands may be recorded within a Vulkan
Video Encode Context.
The execution of each vkCmdEncodeVideoKHR command will result in
generating codec-specific bitstream units.
These bitstream units are generated consecutively into the bitstream buffer
specified in dstBitstreamBuffer of a VkVideoEncodeInfoKHR
structure within the vkCmdBeginVideoCodingKHR command.
The produced bitstream is the sum of all these bitstream units, including
any padding between the bitstream units.
Any bitstream padding must be filled with data compliant to the codec
standard so as not to cause any syntax errors during decoding of the
bitstream units with the padding included.
The range of the bitstream buffer written can be queried via
video encode bitstream buffer
range queries.
The vkCmdEncodeVideoKHR flags are defined with the following enumeration:
// Provided by VK_KHR_video_encode_queue
typedef enum VkVideoEncodeFlagBitsKHR {
VK_VIDEO_ENCODE_DEFAULT_KHR = 0,
VK_VIDEO_ENCODE_RESERVED_0_BIT_KHR = 0x00000001,
} VkVideoEncodeFlagBitsKHR;
-
VK_VIDEO_ENCODE_RESERVED_0_BIT_KHRThe current version of the specification has reserved this value for future use.
// Provided by VK_KHR_video_encode_queue
typedef VkFlags VkVideoEncodeFlagsKHR;
VkVideoEncodeFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoEncodeFlagBitsKHR.
The VkVideoEncodeRateControlInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeRateControlInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeRateControlFlagsKHR flags;
VkVideoEncodeRateControlModeFlagBitsKHR rateControlMode;
uint8_t layerCount;
const VkVideoEncodeRateControlLayerInfoKHR* pLayerConfigs;
} VkVideoEncodeRateControlInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeRateControlFlagBitsKHR specifying encode rate control flags. -
rateControlModeis a VkVideoEncodeRateControlModeFlagBitsKHR value specifying the encode stream rate control mode. -
layerCountspecifies the number of rate control layers in the video encode stream. -
pLayerConfigsis a pointer to an array of VkVideoEncodeRateControlLayerInfoKHR structures specifying the rate control configurations oflayerCountrate control layers.
In order to provide video encode stream rate control settings, add a
VkVideoEncodeRateControlInfoKHR structure to the pNext chain of
the VkVideoCodingControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command.
A codec-specific extension structure for further encode stream rate control parameter settings may be chained to VkVideoEncodeRateControlInfoKHR.
To ensure that the video session is properly initalized with stream-level rate control settings, the application must call vkCmdControlVideoCodingKHR with stream-level rate control settings at least once in execution order before the first vkCmdEncodeVideoKHR command that is executed after video session reset. If not provided, default implementation-specific stream rate control settings will be used.
Stream rate control settings can also be re-initialized during an active
video encoding session.
The re-initialization takes effect whenever the
VkVideoEncodeRateControlInfoKHR structure is included in the
pNext chain of the VkVideoCodingControlInfoKHR structure in the
call to vkCmdControlVideoCodingKHR, and only impacts
vkCmdEncodeVideoKHR operations that follow in execution order.
// Provided by VK_KHR_video_encode_queue
typedef VkFlags VkVideoEncodeRateControlFlagsKHR;
VkVideoEncodeRateControlFlagsKHR is a bitmask type for setting a mask,
but currently reserved for future use.
// Provided by VK_KHR_video_encode_queue
typedef enum VkVideoEncodeRateControlFlagBitsKHR {
VK_VIDEO_ENCODE_RATE_CONTROL_DEFAULT_KHR = 0,
VK_VIDEO_ENCODE_RATE_CONTROL_RESERVED_0_BIT_KHR = 0x00000001,
} VkVideoEncodeRateControlFlagBitsKHR;
VkVideoEncodeRateControlFlagBitsKHR defines bits which may be set in a VkVideoEncodeRateControlFlagsKHR value, but is currently unused.
The rate control modes are defined with the following enums:
// Provided by VK_KHR_video_encode_queue
typedef enum VkVideoEncodeRateControlModeFlagBitsKHR {
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR = 0,
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR = 1,
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR = 2,
} VkVideoEncodeRateControlModeFlagBitsKHR;
-
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHRfor disabling rate control. -
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHRfor constant bitrate rate control mode. -
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHRfor variable bitrate rate control mode.
The VkVideoEncodeRateControlLayerInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeRateControlLayerInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t averageBitrate;
uint32_t maxBitrate;
uint32_t frameRateNumerator;
uint32_t frameRateDenominator;
uint32_t virtualBufferSizeInMs;
uint32_t initialVirtualBufferSizeInMs;
} VkVideoEncodeRateControlLayerInfoKHR;
-
sTypeis the type of this structure. -
pNextis a pointer to a structure extending this structure. -
averageBitrateis the average bitrate in bits/second. Valid when rate control mode is notVK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR. -
maxBitrateis the peak bitrate in bits/second. Valid when rate control mode isVK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR. -
frameRateNumeratoris the numerator of the frame rate. Valid when rate control mode is notVK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR. -
frameRateDenominatoris the denominator of the frame rate. Valid when rate control mode is notVK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR. -
virtualBufferSizeInMsis the leaky bucket model virtual buffer size in milliseconds, with respect to peak bitrate. Valid when rate control mode is notVK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR. For example, virtual buffer size is (virtualBufferSizeInMs×maxBitrate/ 1000). -
initialVirtualBufferSizeInMsis the initial occupancy in milliseconds of the virtual buffer in the leaky bucket model. Valid when the rate control mode is notVK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR.
A codec-specific structure specifying additional per-layer rate control
settings must be chained to VkVideoEncodeRateControlLayerInfoKHR.
If multiple rate control layers are enabled
(VkVideoEncodeRateControlInfoKHR::layerCount is greater than 1),
then the chained codec-specific extension structure also identifies the
specific video coding layer its parent
VkVideoEncodeRateControlLayerInfoKHR applies to.
If multiple rate control layers are enabled, the number of rate control
layers must match the number of video coding layers.
The specification for an encode codec-specific extension would describe how
multiple video coding layers are enabled for the corresponding codec.
Per-layer rate control settings for all enabled rate control layers must be
initialized or re-initialized whenever stream rate control settings are
provided via VkVideoEncodeRateControlInfoKHR.
This is done by specifying settings for all enabled rate control layers in
VkVideoEncodeRateControlInfoKHR::pLayerConfigs.
To adjust rate control settings for an individual layer at runtime, add a
VkVideoEncodeRateControlLayerInfoKHR structure to the pNext
chain of the VkVideoCodingControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command.
This adjustment only impacts the specified layer without impacting the rate
control settings or implementation rate control algorithm behavior for any
other enabled rate control layers.
The adjustment takes effect whenever the corresponding
vkCmdControlVideoCodingKHR is executed, and only impacts
vkCmdEncodeVideoKHR operations pertaining to the corresponding video
coding layer that follow in execution order.
It is possible for an application to enable multiple video coding layers
(via codec-specific extensions to encoding operations) while only enabling a
single layer of rate control for the entire video stream.
To achieve this, layerCount in VkVideoEncodeRateControlInfoKHR
must be set to 1, and the single VkVideoEncodeRateControlLayerInfoKHR
provided in pLayerConfigs would apply to all encoded segments of the
video stream, regardless of which codec-defined video coding layer they
belong to.
In this case, the implementation decides bitrate distribution across video
coding layers (if applicable to the specified stream rate control mode).
39.9. Encode H.264
This extension adds H.264 codec specific structures/types needed to support H.264 encoding. Unless otherwise noted, all references to the H.264 specification are to the 2010 edition published by the ITU-T, dated March 2010. This specification is available at https://www.itu.int/rec/T-REC-H.264.
39.9.1. H.264 encode profile
The VkVideoEncodeH264ProfileEXT structure is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264ProfileEXT {
VkStructureType sType;
const void* pNext;
StdVideoH264ProfileIdc stdProfileIdc;
} VkVideoEncodeH264ProfileEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileIdcis aStdVideoH264ProfileIdcvalue specifying the H.264 codec profile IDC.
An H.264 encode profile is specified by including a
VkVideoEncodeH264ProfileEXT structure in the pNext chain of the
VkVideoProfileKHR structure when
VkVideoProfileKHR::videoCodecOperation is
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT.
39.9.2. Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR with
pVideoProfile->videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, the
VkVideoEncodeH264CapabilitiesEXT structure must be included in the
pNext chain of the VkVideoCapabilitiesKHR structure to retrieve
more capabilities specific to H.264 video encoding.
The VkVideoEncodeH264CapabilitiesEXT structure is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264CapabilitiesEXT {
VkStructureType sType;
void* pNext;
VkVideoEncodeH264CapabilityFlagsEXT flags;
VkVideoEncodeH264InputModeFlagsEXT inputModeFlags;
VkVideoEncodeH264OutputModeFlagsEXT outputModeFlags;
uint8_t maxPPictureL0ReferenceCount;
uint8_t maxBPictureL0ReferenceCount;
uint8_t maxL1ReferenceCount;
VkBool32 motionVectorsOverPicBoundariesFlag;
uint32_t maxBytesPerPicDenom;
uint32_t maxBitsPerMbDenom;
uint32_t log2MaxMvLengthHorizontal;
uint32_t log2MaxMvLengthVertical;
} VkVideoEncodeH264CapabilitiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeH264CapabilityFlagBitsEXT describing supported encoding tools. -
inputModeFlagsis a bitmask of VkVideoEncodeH264InputModeFlagBitsEXT describing supported command buffer input granularities/modes. -
outputModeFlagsis a bitmask of VkVideoEncodeH264OutputModeFlagBitsEXT describing supported output (bitstream size reporting) granularities/modes. -
maxPPictureL0ReferenceCountreports the maximum number of reference pictures the implementation supports in the reference list L0 for P pictures. -
maxBPictureL0ReferenceCountreports the maximum number of reference pictures the implementation supports in the reference list L0 for B pictures. The reported value is0if encoding of B pictures is not supported. -
maxL1ReferenceCountreports the maximum number of reference pictures the implementation supports in the reference list L1 if encoding of B pictures is supported. The reported value is0if encoding of B pictures is not supported. -
motionVectorsOverPicBoundariesFlagifVK_TRUE, indicates motion_vectors_over_pic_boundaries_flag will be enabled if bitstream_restriction_flag is enabled in StdVideoH264SpsVuiFlags. -
maxBytesPerPicDenomreports the value that will be used for max_bytes_per_pic_denom if bitstream_restriction_flag is enabled in StdVideoH264SpsVuiFlags. -
maxBitsPerMbDenomreports the value that will be used for max_bits_per_mb_denom if bitstream_restriction_flag is enabled in StdVideoH264SpsVuiFlags. -
log2MaxMvLengthHorizontalreports the value that will be used for log2_max_mv_length_horizontal if bitstream_restriction_flag is enabled in StdVideoH264SpsVuiFlags. -
log2MaxMvLengthVerticalreports the value that will be used for log2_max_mv_length_vertical if bitstream_restriction_flag is enabled in StdVideoH264SpsVuiFlags.
When vkGetPhysicalDeviceVideoCapabilitiesKHR is called to query the
capabilities with parameter videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, a
VkVideoEncodeH264CapabilitiesEXT structure can be chained to
VkVideoCapabilitiesKHR to retrieve H.264 extension specific
capabilities.
// Provided by VK_EXT_video_encode_h264
typedef VkFlags VkVideoEncodeH264CapabilityFlagsEXT;
VkVideoEncodeH264CapabilityFlagsEXT is a bitmask type for setting a
mask of zero or more VkVideoEncodeH264CapabilityFlagBitsEXT.
Bits which may be set in
VkVideoEncodeH264CapabilitiesEXT::flags, indicating the encoding
tools supported, are:
// Provided by VK_EXT_video_encode_h264
typedef enum VkVideoEncodeH264CapabilityFlagBitsEXT {
VK_VIDEO_ENCODE_H264_CAPABILITY_DIRECT_8X8_INFERENCE_ENABLED_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H264_CAPABILITY_DIRECT_8X8_INFERENCE_DISABLED_BIT_EXT = 0x00000002,
VK_VIDEO_ENCODE_H264_CAPABILITY_SEPARATE_COLOUR_PLANE_BIT_EXT = 0x00000004,
VK_VIDEO_ENCODE_H264_CAPABILITY_QPPRIME_Y_ZERO_TRANSFORM_BYPASS_BIT_EXT = 0x00000008,
VK_VIDEO_ENCODE_H264_CAPABILITY_SCALING_LISTS_BIT_EXT = 0x00000010,
VK_VIDEO_ENCODE_H264_CAPABILITY_HRD_COMPLIANCE_BIT_EXT = 0x00000020,
VK_VIDEO_ENCODE_H264_CAPABILITY_CHROMA_QP_OFFSET_BIT_EXT = 0x00000040,
VK_VIDEO_ENCODE_H264_CAPABILITY_SECOND_CHROMA_QP_OFFSET_BIT_EXT = 0x00000080,
VK_VIDEO_ENCODE_H264_CAPABILITY_PIC_INIT_QP_MINUS26_BIT_EXT = 0x00000100,
VK_VIDEO_ENCODE_H264_CAPABILITY_WEIGHTED_PRED_BIT_EXT = 0x00000200,
VK_VIDEO_ENCODE_H264_CAPABILITY_WEIGHTED_BIPRED_EXPLICIT_BIT_EXT = 0x00000400,
VK_VIDEO_ENCODE_H264_CAPABILITY_WEIGHTED_BIPRED_IMPLICIT_BIT_EXT = 0x00000800,
VK_VIDEO_ENCODE_H264_CAPABILITY_WEIGHTED_PRED_NO_TABLE_BIT_EXT = 0x00001000,
VK_VIDEO_ENCODE_H264_CAPABILITY_TRANSFORM_8X8_BIT_EXT = 0x00002000,
VK_VIDEO_ENCODE_H264_CAPABILITY_CABAC_BIT_EXT = 0x00004000,
VK_VIDEO_ENCODE_H264_CAPABILITY_CAVLC_BIT_EXT = 0x00008000,
VK_VIDEO_ENCODE_H264_CAPABILITY_DEBLOCKING_FILTER_DISABLED_BIT_EXT = 0x00010000,
VK_VIDEO_ENCODE_H264_CAPABILITY_DEBLOCKING_FILTER_ENABLED_BIT_EXT = 0x00020000,
VK_VIDEO_ENCODE_H264_CAPABILITY_DEBLOCKING_FILTER_PARTIAL_BIT_EXT = 0x00040000,
VK_VIDEO_ENCODE_H264_CAPABILITY_DISABLE_DIRECT_SPATIAL_MV_PRED_BIT_EXT = 0x00080000,
VK_VIDEO_ENCODE_H264_CAPABILITY_MULTIPLE_SLICE_PER_FRAME_BIT_EXT = 0x00100000,
VK_VIDEO_ENCODE_H264_CAPABILITY_SLICE_MB_COUNT_BIT_EXT = 0x00200000,
VK_VIDEO_ENCODE_H264_CAPABILITY_ROW_UNALIGNED_SLICE_BIT_EXT = 0x00400000,
VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_EXT = 0x00800000,
VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_EXT = 0x01000000,
} VkVideoEncodeH264CapabilityFlagBitsEXT;
-
VK_VIDEO_ENCODE_H264_CAPABILITY_DIRECT_8X8_INFERENCE_ENABLED_BIT_EXTreports if enabling direct_8x8_inference_flag in StdVideoH264SpsFlags is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_DIRECT_8X8_INFERENCE_DISABLED_BIT_EXTreports if disabling direct_8x8_inference_flag in StdVideoH264SpsFlags is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_SEPARATE_COLOUR_PLANE_BIT_EXTreports if enabling separate_colour_plane_flag in StdVideoH264SpsFlags is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_QPPRIME_Y_ZERO_TRANSFORM_BYPASS_BIT_EXTreports if enabling qpprime_y_zero_transform_bypass_flag in StdVideoH264SpsFlags is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_SCALING_LISTS_BIT_EXTreports if enabling seq_scaling_matrix_present_flag in StdVideoH264SpsFlags or pic_scaling_matrix_present_flag in StdVideoH264PpsFlags are supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_HRD_COMPLIANCE_BIT_EXTreports if the implementation guarantees generating a HRD compliant bitstream if nal_hrd_parameters_present_flag or vcl_hrd_parameters_present_flag are enabled in StdVideoH264SpsVuiFlags. -
VK_VIDEO_ENCODE_H264_CAPABILITY_CHROMA_QP_OFFSET_BIT_EXTreports if setting non-zero chroma_qp_index_offset in StdVideoH264PictureParameterSet is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_SECOND_CHROMA_QP_OFFSET_BIT_EXTreports if setting non-zero second_chroma_qp_index_offset in StdVideoH264PictureParameterSet is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_PIC_INIT_QP_MINUS26_BIT_EXTreports if setting non-zero pic_init_qp_minus26 in StdVideoH264PictureParameterSet is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_WEIGHTED_PRED_BIT_EXTreports if enabling weighted_pred_flag in StdVideoH264PpsFlags is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_WEIGHTED_BIPRED_EXPLICIT_BIT_EXTreports if using STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT from StdVideoH264WeightedBipredIdc is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_WEIGHTED_BIPRED_IMPLICIT_BIT_EXTreports if using STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_IMPLICIT from StdVideoH264WeightedBipredIdc is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_WEIGHTED_PRED_NO_TABLE_BIT_EXTreports that when weighted_pred_flag is enabled or STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT from StdVideoH264WeightedBipredIdc is used, the implementation is able to internally decide syntax for pred_weight_table. -
VK_VIDEO_ENCODE_H264_CAPABILITY_TRANSFORM_8X8_BIT_EXTreports if enabling transform_8x8_mode_flag in StdVideoH264PpsFlags is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_CABAC_BIT_EXTreports if CABAC entropy coding is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_CAVLC_BIT_EXTreports if CAVLC entropy coding is supported. An implementation must support at least one entropy coding mode. -
VK_VIDEO_ENCODE_H264_CAPABILITY_DEBLOCKING_FILTER_DISABLED_BIT_EXTreports if using STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_DISABLED from StdVideoH264DisableDeblockingFilterIdc is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_DEBLOCKING_FILTER_ENABLED_BIT_EXTreports if using STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_ENABLED from StdVideoH264DisableDeblockingFilterIdc is supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_DEBLOCKING_FILTER_PARTIAL_BIT_EXTreports if using STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_PARTIAL from StdVideoH264DisableDeblockingFilterIdc is supported. An implementation must support at least one deblocking filter mode. -
VK_VIDEO_ENCODE_H264_CAPABILITY_DISABLE_DIRECT_SPATIAL_MV_PRED_BIT_EXTreports if disablingStdVideoEncodeH264SliceHeaderFlags::direct_spatial_mv_pred_flag is supported when it is present in the slice header. -
VK_VIDEO_ENCODE_H264_CAPABILITY_MULTIPLE_SLICE_PER_FRAME_BIT_EXTreports if encoding multiple slices per frame is supported. If not set, the implementation is only able to encode a single slice for the entire frame. -
VK_VIDEO_ENCODE_H264_CAPABILITY_SLICE_MB_COUNT_BIT_EXTreports support for configuring VkVideoEncodeH264NaluSliceEXT::mbCountand first_mb_in_slice in StdVideoEncodeH264SliceHeader for each slice in a frame with multiple slices. If not supported, the implementation decides the number of macroblocks in each slice based on VkVideoEncodeH264VclFrameInfoEXT::naluSliceEntryCount. -
VK_VIDEO_ENCODE_H264_CAPABILITY_ROW_UNALIGNED_SLICE_BIT_EXTreports that each slice in a frame with multiple slices may begin or finish at any offset in a macroblock row. If not supported, all slices in the frame must begin at the start of a macroblock row (and hence each slice must finish at the end of a macroblock row). -
VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_EXTreports that whenVK_VIDEO_ENCODE_H264_CAPABILITY_MULTIPLE_SLICE_PER_FRAME_BIT_EXTis supported and a frame is encoded with multiple slices, the implementation allows encoding each slice with a differentStdVideoEncodeH264SliceHeader::slice_type. If not supported, all slices of the frame must be encoded with the sameslice_typewhich corresponds to the picture type of the frame. For example, all slices of a P-frame would be encoded as P-slices. -
VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_EXTreports support for using a B frame as L1 reference.
// Provided by VK_EXT_video_encode_h264
typedef VkFlags VkVideoEncodeH264InputModeFlagsEXT;
VkVideoEncodeH264InputModeFlagsEXT is a bitmask type for setting a
mask of zero or more VkVideoEncodeH264InputModeFlagBitsEXT.
The inputModeFlags field reports the various commmand buffer input
granularities supported by the implementation as follows:
// Provided by VK_EXT_video_encode_h264
typedef enum VkVideoEncodeH264InputModeFlagBitsEXT {
VK_VIDEO_ENCODE_H264_INPUT_MODE_FRAME_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H264_INPUT_MODE_SLICE_BIT_EXT = 0x00000002,
VK_VIDEO_ENCODE_H264_INPUT_MODE_NON_VCL_BIT_EXT = 0x00000004,
} VkVideoEncodeH264InputModeFlagBitsEXT;
-
VK_VIDEO_ENCODE_H264_INPUT_MODE_FRAME_BIT_EXTindicates that a single command buffer must at least encode an entire frame. Any non-VCL NALUs must be encoded using the same command buffer as the frame ifVK_VIDEO_ENCODE_H264_INPUT_MODE_NON_VCL_BIT_EXTis not supported. -
VK_VIDEO_ENCODE_H264_INPUT_MODE_SLICE_BIT_EXTindicates that a single command buffer must at least encode a single slice. Any non-VCL NALUs must be encoded using the same command buffer as the first slice of the frame ifVK_VIDEO_ENCODE_H264_INPUT_MODE_NON_VCL_BIT_EXTis not supported. -
VK_VIDEO_ENCODE_H264_INPUT_MODE_NON_VCL_BIT_EXTindicates that a single command buffer may encode a non-VCL NALU by itself.
An implementation must support at least one of
VK_VIDEO_ENCODE_H264_INPUT_MODE_FRAME_BIT_EXT or
VK_VIDEO_ENCODE_H264_INPUT_MODE_SLICE_BIT_EXT.
If VK_VIDEO_ENCODE_H264_INPUT_MODE_SLICE_BIT_EXT is not supported, the
following two additional restrictions apply for frames encoded with multiple
slices.
First, all frame slices must have the same pRefList0ModOperations and the
same pRefList1ModOperations.
Second, the order in which slices appear in
VkVideoEncodeH264VclFrameInfoEXT::pNaluSliceEntries or in the
command buffer must match the placement order of the slices in the frame.
// Provided by VK_EXT_video_encode_h264
typedef VkFlags VkVideoEncodeH264OutputModeFlagsEXT;
VkVideoEncodeH264OutputModeFlagsEXT is a bitmask type for setting a
mask of zero or more VkVideoEncodeH264InputModeFlagBitsEXT.
Bits which may be set in
VkVideoEncodeH264CapabilitiesEXT::outputModeFlags, indicating
the minimum bitstream generation commands that must be included between
each vkCmdBeginVideoCodingKHR and vkCmdEndVideoCodingKHR pair
(henceforth simply begin/end pair), are:
// Provided by VK_EXT_video_encode_h264
typedef enum VkVideoEncodeH264OutputModeFlagBitsEXT {
VK_VIDEO_ENCODE_H264_OUTPUT_MODE_FRAME_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H264_OUTPUT_MODE_SLICE_BIT_EXT = 0x00000002,
VK_VIDEO_ENCODE_H264_OUTPUT_MODE_NON_VCL_BIT_EXT = 0x00000004,
} VkVideoEncodeH264OutputModeFlagBitsEXT;
-
VK_VIDEO_ENCODE_H264_OUTPUT_MODE_FRAME_BIT_EXTindicates that calls to generate all NALUs of a frame must be included within a single begin/end pair. Any non-VCL NALUs must be encoded within the same begin/end pair ifVK_VIDEO_ENCODE_H264_OUTPUT_MODE_NON_VCL_BIT_EXTis not supported. -
VK_VIDEO_ENCODE_H264_OUTPUT_MODE_SLICE_BIT_EXTindicates that each begin/end pair must encode at least one slice. Any non-VCL NALUs must be encoded within the same begin/end pair as the first slice of the frame ifVK_VIDEO_ENCODE_H264_OUTPUT_MODE_NON_VCL_BIT_EXTis not supported. -
VK_VIDEO_ENCODE_H264_OUTPUT_MODE_NON_VCL_BIT_EXTindicates that each begin/end pair may encode only a non-VCL NALU by itself. An implementation must support at least one ofVK_VIDEO_ENCODE_H264_OUTPUT_MODE_FRAME_BIT_EXTorVK_VIDEO_ENCODE_H264_OUTPUT_MODE_SLICE_BIT_EXT.
A single begin/end pair must not encode more than a single frame.
The bitstreams of NALUs generated within a single begin/end pair are written continuously into the same bitstream buffer (any padding between the NALUs must be compliant to the H.264 standard).
The supported input modes must be coarser or equal to the supported output modes. For example, it is illegal to report slice input is supported but only frame output is supported.
An implementation must report one of the following combinations of input/output modes:
-
Input: Frame, Output: Frame
-
Input: Frame, Output: Frame and Non-VCL
-
Input: Frame, Output: Slice
-
Input: Frame, Output: Slice and Non-VCL
-
Input: Slice, Output: Slice
-
Input: Slice, Output: Slice and Non-VCL
-
Input: Frame and Non-VCL, Output: Frame and Non-VCL
-
Input: Frame and Non-VCL, Output: Slice and Non-VCL
-
Input: Slice and Non-VCL, Output: Slice and Non-VCL
39.9.3. Encoder Parameter Sets
To reduce parameter traffic during encoding, the encoder parameter set object supports storing H.264 SPS/PPS parameter sets that may be later referenced during encoding.
The VkVideoEncodeH264SessionParametersCreateInfoEXT structure is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264SessionParametersCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t maxSpsStdCount;
uint32_t maxPpsStdCount;
const VkVideoEncodeH264SessionParametersAddInfoEXT* pParametersAddInfo;
} VkVideoEncodeH264SessionParametersCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxSpsStdCountis the maximum number of SPS parameters that theVkVideoSessionParametersKHRcan contain. -
maxPpsStdCountis the maximum number of PPS parameters that theVkVideoSessionParametersKHRcan contain. -
pParametersAddInfoisNULLor a pointer to aVkVideoEncodeH264SessionParametersAddInfoEXTstructure specifying H.264 parameters to add upon object creation.
A VkVideoEncodeH264SessionParametersCreateInfoEXT structure holding
one H.264 SPS and at least one H.264 PPS paramater set must be chained to
VkVideoSessionParametersCreateInfoKHR when calling
vkCreateVideoSessionParametersKHR to store these parameter set(s) with
the encoder parameter set object for later reference.
The provided H.264 SPS/PPS parameters must be within the limits specified
during encoder creation for the encoder specified in
VkVideoSessionParametersCreateInfoKHR.
The VkVideoEncodeH264SessionParametersAddInfoEXT structure is defined
as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264SessionParametersAddInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t spsStdCount;
const StdVideoH264SequenceParameterSet* pSpsStd;
uint32_t ppsStdCount;
const StdVideoH264PictureParameterSet* pPpsStd;
} VkVideoEncodeH264SessionParametersAddInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
spsStdCountis the number of SPS elements in thepSpsStd. Its value must be less than or equal to the value ofmaxSpsStdCount. -
pSpsStdis a pointer to an array ofStdVideoH264SequenceParameterSetstructures representing H.264 sequence parameter sets. Each element of the array must have a unique H.264 SPS ID. -
ppsStdCountis the number of PPS provided inpPpsStd. Its value must be less than or equal to the value ofmaxPpsStdCount. -
pPpsStdis a pointer to an array ofStdVideoH264PictureParameterSetstructures representing H.264 picture parameter sets. Each element of the array must have a unique H.264 SPS-PPS ID pair.
39.9.4. Frame Encoding
In order to encode a frame, add a VkVideoEncodeH264VclFrameInfoEXT
structure to the pNext chain of the VkVideoEncodeInfoKHR
structure passed to the vkCmdEncodeVideoKHR command.
The VkVideoEncodeH264VclFrameInfoEXT structure representing a frame encode operation is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264VclFrameInfoEXT {
VkStructureType sType;
const void* pNext;
const VkVideoEncodeH264ReferenceListsEXT* pReferenceFinalLists;
uint32_t naluSliceEntryCount;
const VkVideoEncodeH264NaluSliceEXT* pNaluSliceEntries;
const StdVideoEncodeH264PictureInfo* pCurrentPictureInfo;
} VkVideoEncodeH264VclFrameInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pReferenceFinalListsisNULLor a pointer to a VkVideoEncodeH264ReferenceListsEXT structure specifying the reference lists to be used for the current picture. -
naluSliceEntryCountis the number of slice NALUs in the frame. -
pNaluSliceEntriesis a pointer to an array ofnaluSliceEntryCountVkVideoEncodeH264NaluSliceEXT structures specifying the division of the current picture into slices and the properties of these slices. This is an ordered sequence; the NALUs are generated consecutively in VkVideoEncodeInfoKHR::dstBitstreamBufferin the same order as in this array. -
pCurrentPictureInfois a pointer to aStdVideoEncodeH264PictureInfostructure specifying the syntax and other codec-specific information from the H.264 specification associated with this picture. The information provided must reflect the decoded picture marking operations that are applicable to this frame.
The VkVideoEncodeH264NaluSliceEXT structure representing a slice is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264NaluSliceEXT {
VkStructureType sType;
const void* pNext;
uint32_t mbCount;
const VkVideoEncodeH264ReferenceListsEXT* pReferenceFinalLists;
const StdVideoEncodeH264SliceHeader* pSliceHeaderStd;
} VkVideoEncodeH264NaluSliceEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
mbCountis the number of macroblocks in this slice. -
pReferenceFinalListsisNULLor a pointer to a VkVideoEncodeH264ReferenceListsEXT structure specifying the reference lists to be used for the current slice. IfpReferenceFinalListsis notNULL, these reference lists override the reference lists provided in VkVideoEncodeH264VclFrameInfoEXT::pReferenceFinalLists. -
pSliceHeaderStdis a pointer to aStdVideoEncodeH264SliceHeaderstructure specifying the slice header for the current slice.
The VkVideoEncodeH264DpbSlotInfoEXT structure, representing a reconstructed picture that is being used as a reference picture, is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264DpbSlotInfoEXT {
VkStructureType sType;
const void* pNext;
int8_t slotIndex;
const StdVideoEncodeH264ReferenceInfo* pStdReferenceInfo;
} VkVideoEncodeH264DpbSlotInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
slotIndexis the DPB Slot index for this picture.slotIndexmust match theslotIndexinpSetupReferenceSlotof VkVideoEncodeInfoKHR in the command used to encode the corresponding picture. -
pStdReferenceInfois a pointer to aStdVideoEncodeH264ReferenceInfostructure specifying the syntax and other codec-specific information from the H.264 specification associated with this reference picture.
The VkVideoEncodeH264ReferenceListsEXT structure representing reference lists is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264ReferenceListsEXT {
VkStructureType sType;
const void* pNext;
uint8_t referenceList0EntryCount;
const VkVideoEncodeH264DpbSlotInfoEXT* pReferenceList0Entries;
uint8_t referenceList1EntryCount;
const VkVideoEncodeH264DpbSlotInfoEXT* pReferenceList1Entries;
const StdVideoEncodeH264RefMemMgmtCtrlOperations* pMemMgmtCtrlOperations;
} VkVideoEncodeH264ReferenceListsEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
referenceList0EntryCountis the number of reference pictures in reference list L0 and is identical toStdVideoEncodeH264SliceHeader::num_ref_idx_l0_active_minus1+ 1. -
pReferenceList0Entriesis a pointer to an array ofreferenceList0EntryCountVkVideoEncodeH264DpbSlotInfoEXT structures specifying the reference list L0 entries for the current picture. The entries provided must be ordered after all reference list L0 modification operations are applied (i.e. final list order). The entries provided must not reflect decoded picture marking operations in this frame that are applicable to references; the impact of such operations must be reflected in future frame encode commands. The slot index in each entry must match one of the slot indexes provided in thepReferenceSlotsof the parent VkVideoEncodeInfoKHR structure. -
referenceList1EntryCountis the number of reference pictures in reference list L1 and is identical toStdVideoEncodeH264SliceHeader::num_ref_idx_l1_active_minus1+ 1. -
pReferenceList1Entriesis a pointer to an array ofreferenceList1EntryCountVkVideoEncodeH264DpbSlotInfoEXT structures specifying the reference list L1 entries for the current picture. The entries provided must be ordered after all reference list L1 modification operations are applied (i.e. final list order). The entries provided must not reflect decoded picture marking operations in this frame that are applicable to references; the impact of such operations must be reflected in future frame encode commands. The slot index in each entry must match one of the slot indexes provided in thepReferenceSlotsof the parent VkVideoEncodeInfoKHR structure. -
pMemMgmtCtrlOperationsis a pointer to aStdVideoEncodeH264RefMemMgmtCtrlOperationsstructure specifying reference lists modifications and decoded picture marking operations.
The VkVideoEncodeH264EmitPictureParametersEXT structure is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264EmitPictureParametersEXT {
VkStructureType sType;
const void* pNext;
uint8_t spsId;
VkBool32 emitSpsEnable;
uint32_t ppsIdEntryCount;
const uint8_t* ppsIdEntries;
} VkVideoEncodeH264EmitPictureParametersEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
spsIdis the H.264 SPS ID for the H.264 SPS to insert in the bitstream. The SPS ID must match the SPS provided inspsStdof VkVideoEncodeH264SessionParametersCreateInfoEXT. This is retrieved from the VkVideoSessionParametersKHR object provided in VkVideoBeginCodingInfoKHR. -
emitSpsEnableenables the emitting of the SPS structure with id ofspsId. -
ppsIdEntryCountis the number of entries in theppsIdEntries. If this parameter is0then no pps entries are going to be emitted in the bitstream. -
ppsIdEntriesis a pointer to an array of H.264 PPS IDs for the H.264 PPS to insert in the bitstream. The PPS IDs must match one of the IDs of the PPS(s) provided inpPpsStdof VkVideoEncodeH264SessionParametersCreateInfoEXT to identify the PPS parameter set to insert in the bitstream. This is retrieved from the VkVideoSessionParametersKHR object provided in VkVideoBeginCodingInfoKHR.
39.9.5. Rate control
The VkVideoEncodeH264RateControlInfoEXT structure is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264RateControlInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t gopFrameCount;
uint32_t idrPeriod;
uint32_t consecutiveBFrameCount;
VkVideoEncodeH264RateControlStructureFlagBitsEXT rateControlStructure;
uint8_t temporalLayerCount;
} VkVideoEncodeH264RateControlInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
gopFrameCountis the number of frames contained within the group of pictures (GOP), starting from an intra frame and until the next intra frame. If it is set to 0, the implementation chooses a suitable value. If it is set toUINT32_MAX, the GOP length is treated as infinite. -
idrPeriodis the interval, in terms of number of frames, between two IDR frames. If it is set to 0, the implementation chooses a suitable value. If it is set toUINT32_MAX, the IDR period is treated as infinite. -
consecutiveBFrameCountis the number of consecutive B-frames between I- and/or P-frames within the GOP. -
rateControlStructureis a VkVideoEncodeH264RateControlStructureFlagBitsEXT value specifying the expected encode stream reference structure, to aid in rate control calculations. -
temporalLayerCountspecifies the number of temporal layers enabled in the stream.
In order to provide H.264-specific stream rate control parameters, add a
VkVideoEncodeH264RateControlInfoEXT structure to the pNext chain
of the VkVideoEncodeRateControlInfoKHR structure in the pNext
chain of the VkVideoCodingControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command.
The parameters from this structure act as a guidance for implementations to apply various rate control heuristics.
It is possible to infer the picture type to be used when encoding a frame,
on the basis of the values provided for consecutiveBFrameCount,
idrPeriod, and gopFrameCount, but this inferred picture type
will not be used by implementations to override the picture type provided in
vkCmdEncodeVideoKHR.
Additionally, it is not required for the video session to be reset if the
inferred picture type does not match the actual picture type.
The rateControlStructure in VkVideoEncodeH264RateControlInfoEXT
specifies one of the following video stream reference structures as a hint
for the rate control implementation:
// Provided by VK_EXT_video_encode_h264
typedef enum VkVideoEncodeH264RateControlStructureFlagBitsEXT {
VK_VIDEO_ENCODE_H264_RATE_CONTROL_STRUCTURE_UNKNOWN_EXT = 0,
VK_VIDEO_ENCODE_H264_RATE_CONTROL_STRUCTURE_FLAT_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H264_RATE_CONTROL_STRUCTURE_DYADIC_BIT_EXT = 0x00000002,
} VkVideoEncodeH264RateControlStructureFlagBitsEXT;
-
VK_VIDEO_ENCODE_H264_RATE_CONTROL_STRUCTURE_UNKNOWN_EXTis0, and specifies a reference structure unknown at the time of stream rate control configuration. -
VK_VIDEO_ENCODE_H264_RATE_CONTROL_STRUCTURE_FLAT_BIT_EXTspecifies a flat reference structure. -
VK_VIDEO_ENCODE_H264_RATE_CONTROL_STRUCTURE_DYADIC_BIT_EXTspecifies a dyadic reference structure.
The VkVideoEncodeH264RateControlLayerInfoEXT structure is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264RateControlLayerInfoEXT {
VkStructureType sType;
const void* pNext;
uint8_t temporalLayerId;
VkBool32 useInitialRcQp;
VkVideoEncodeH264QpEXT initialRcQp;
VkBool32 useMinQp;
VkVideoEncodeH264QpEXT minQp;
VkBool32 useMaxQp;
VkVideoEncodeH264QpEXT maxQp;
VkBool32 useMaxFrameSize;
VkVideoEncodeH264FrameSizeEXT maxFrameSize;
} VkVideoEncodeH264RateControlLayerInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
temporalLayerIdspecifies the H.264 temporal layer ID of the video coding layer that settings provided in this structure and its parent VkVideoEncodeRateControlLayerInfoKHR structure apply to. -
useInitialRcQpindicates whether the values withininitialRcQpshould be used by the implementation. -
initialRcQpprovides the QP values for each picture type, to be used in rate control calculations at the start of video encode operations on a newly-created video session, or immediately after a session reset. These values are ignored when VkVideoEncodeRateControlInfoKHR::rateControlModeisVK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR. -
useMinQpindicates whether the values withinminQpshould be used by the implementation. When it is set toVK_FALSE, the implementation ignores the values inminQpand chooses suitable values. -
minQpprovides the lower bound on the QP values for each picture type, to be used in rate control calculations. -
useMaxQpindicates whether the values withinmaxQpshould be used by the implementation. When it is set toVK_FALSE, the implementation ignores the values inmaxQpand chooses suitable values. -
maxQpprovides the upper bound on the QP values for each picture type, to be used in rate control calculations. -
useMaxFrameSizeindicates whether the values withinmaxFrameSizeshould be used by the implementation. -
maxFrameSizeprovides the upper bound on the encoded frame size for each picture type. The implementation does not guarantee the encoded frame sizes will be within the specified limits, however these limits may be used as a guide in rate control calculations. If enabled and not set properly, themaxQplimit may prevent the implementation from respecting themaxFrameSizelimit.
H.264-specific per-layer rate control parameters must be specified by
adding a VkVideoEncodeH264RateControlLayerInfoEXT structure to the
pNext chain of each VkVideoEncodeRateControlLayerInfoKHR
structure in a call to vkCmdControlVideoCodingKHR command, when the
command buffer context has an active video encode H.264 session.
The VkVideoEncodeH264QpEXT structure is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264QpEXT {
int32_t qpI;
int32_t qpP;
int32_t qpB;
} VkVideoEncodeH264QpEXT;
-
qpIis the QP to be used for I-frames. -
qpPis the QP to be used for P-frames. -
qpBis the QP to be used for B-frames.
The VkVideoEncodeH264FrameSizeEXT structure is defined as:
// Provided by VK_EXT_video_encode_h264
typedef struct VkVideoEncodeH264FrameSizeEXT {
uint32_t frameISize;
uint32_t framePSize;
uint32_t frameBSize;
} VkVideoEncodeH264FrameSizeEXT;
-
frameISizeis the size in bytes to be used for I-frames. -
framePSizeis the size in bytes to be used for P-frames. -
frameBSizeis the size in bytes to be used for B-frames.
39.10. Encode H.265
This extension adds H.265 codec-specific structures/types needed to support H.265 video encoding. Unless otherwise noted, all references to the H.265 specification are to the 2013 edition published by the ITU-T, dated April 2013. This specification is available at https://www.itu.int/rec/T-REC-H.265.
39.10.1. H.265 encode profile
An H.265 encode profile is specified by including the
VkVideoEncodeH265ProfileEXT structure in the pNext chain of the
VkVideoProfileKHR structure when
VkVideoProfileKHR::videoCodecOperation is
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT.
The VkVideoEncodeH265ProfileEXT structure is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265ProfileEXT {
VkStructureType sType;
const void* pNext;
StdVideoH265ProfileIdc stdProfileIdc;
} VkVideoEncodeH265ProfileEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileIdcis aStdVideoH265ProfileIdcvalue specifying the H.265 codec profile IDC.
39.10.2. Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR with
pVideoProfile->videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT, the
VkVideoEncodeH265CapabilitiesEXT structure must be included in the
pNext chain of the VkVideoCapabilitiesKHR structure to retrieve
more capabilities specific to H.265 video encoding.
The VkVideoEncodeH265CapabilitiesEXT structure is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265CapabilitiesEXT {
VkStructureType sType;
void* pNext;
VkVideoEncodeH265CapabilityFlagsEXT flags;
VkVideoEncodeH265InputModeFlagsEXT inputModeFlags;
VkVideoEncodeH265OutputModeFlagsEXT outputModeFlags;
VkVideoEncodeH265CtbSizeFlagsEXT ctbSizes;
VkVideoEncodeH265TransformBlockSizeFlagsEXT transformBlockSizes;
uint8_t maxPPictureL0ReferenceCount;
uint8_t maxBPictureL0ReferenceCount;
uint8_t maxL1ReferenceCount;
uint8_t maxSubLayersCount;
uint8_t minLog2MinLumaCodingBlockSizeMinus3;
uint8_t maxLog2MinLumaCodingBlockSizeMinus3;
uint8_t minLog2MinLumaTransformBlockSizeMinus2;
uint8_t maxLog2MinLumaTransformBlockSizeMinus2;
uint8_t minMaxTransformHierarchyDepthInter;
uint8_t maxMaxTransformHierarchyDepthInter;
uint8_t minMaxTransformHierarchyDepthIntra;
uint8_t maxMaxTransformHierarchyDepthIntra;
uint8_t maxDiffCuQpDeltaDepth;
uint8_t minMaxNumMergeCand;
uint8_t maxMaxNumMergeCand;
} VkVideoEncodeH265CapabilitiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeH265CapabilityFlagBitsEXT describing supported encoding tools. -
inputModeFlagsis a bitmask of VkVideoEncodeH265InputModeFlagBitsEXT describing the command buffer input granularities/modes supported by the implementation. -
outputModeFlagsis a bitmask of VkVideoEncodeH265OutputModeFlagBitsEXT describing the output (bitstream size reporting) granularities/modes supported by the implementation. -
ctbSizesis a bitmask of VkVideoEncodeH265CtbSizeFlagBitsEXT describing the supported CTB sizes. -
transformBlockSizesis a bitmask of VkVideoEncodeH265TransformBlockSizeFlagBitsEXT describing the supported transform block sizes. -
maxPPictureL0ReferenceCountreports the maximum number of reference pictures the implementation supports in the reference list L0 for P pictures. -
maxBPictureL0ReferenceCountreports the maximum number of reference pictures the implementation supports in the reference list L0 for B pictures. The reported value is0if encoding of B pictures is not supported. -
maxL1ReferenceCountreports the maximum number of reference pictures the implementation supports in the reference list L1 if encoding of B pictures is supported. The reported value is0if encoding of B pictures is not supported. -
maxSubLayersCountreports the maximum number of sublayers. -
minLog2MinLumaCodingBlockSizeMinus3reports the minimum value that may be set for log2_min_luma_coding_block_size_minus3 in StdVideoH265SequenceParameterSet. -
maxLog2MinLumaCodingBlockSizeMinus3reports the maximum value that may be set for log2_min_luma_coding_block_size_minus3 in StdVideoH265SequenceParameterSet. -
minLog2MinLumaTransformBlockSizeMinus2reports the minimum value that may be set for log2_min_luma_transform_block_size_minus2 in StdVideoH265SequenceParameterSet. -
maxLog2MinLumaTransformBlockSizeMinus2reports the maximum value that may be set for log2_min_luma_transform_block_size_minus2 in StdVideoH265SequenceParameterSet. -
minMaxTransformHierarchyDepthInterreports the minimum value that may be set for max_transform_hierarchy_depth_inter in StdVideoH265SequenceParameterSet. -
maxMaxTransformHierarchyDepthInterreports the maximum value that may be set for max_transform_hierarchy_depth_inter in StdVideoH265SequenceParameterSet. -
minMaxTransformHierarchyDepthIntrareports the minimum value that may be set for max_transform_hierarchy_depth_intra in StdVideoH265SequenceParameterSet. -
maxMaxTransformHierarchyDepthIntrareports the maximum value that may be set for max_transform_hierarchy_depth_intra in StdVideoH265SequenceParameterSet. -
maxDiffCuQpDeltaDepthreports the maximum value that may be set for diff_cu_qp_delta_depth in StdVideoH265PictureParameterSet. -
minMaxNumMergeCandreports the minimum value that may be set for MaxNumMergeCand in StdVideoEncodeH265SliceHeader. -
maxMaxNumMergeCandreports the maximum value that may be set for MaxNumMergeCand in StdVideoEncodeH265SliceHeader.
// Provided by VK_EXT_video_encode_h265
typedef VkFlags VkVideoEncodeH265CapabilityFlagsEXT;
VkVideoEncodeH265CapabilityFlagsEXT is a bitmask type for setting a
mask of zero or more VkVideoEncodeH265CapabilityFlagBitsEXT.
Bits which may be set in
VkVideoEncodeH265CapabilitiesEXT::flags, indicating the encoding
tools supported, are:
// Provided by VK_EXT_video_encode_h265
typedef enum VkVideoEncodeH265CapabilityFlagBitsEXT {
VK_VIDEO_ENCODE_H265_CAPABILITY_SEPARATE_COLOUR_PLANE_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H265_CAPABILITY_SCALING_LISTS_BIT_EXT = 0x00000002,
VK_VIDEO_ENCODE_H265_CAPABILITY_SAMPLE_ADAPTIVE_OFFSET_ENABLED_BIT_EXT = 0x00000004,
VK_VIDEO_ENCODE_H265_CAPABILITY_PCM_ENABLE_BIT_EXT = 0x00000008,
VK_VIDEO_ENCODE_H265_CAPABILITY_SPS_TEMPORAL_MVP_ENABLED_BIT_EXT = 0x00000010,
VK_VIDEO_ENCODE_H265_CAPABILITY_HRD_COMPLIANCE_BIT_EXT = 0x00000020,
VK_VIDEO_ENCODE_H265_CAPABILITY_INIT_QP_MINUS26_BIT_EXT = 0x00000040,
VK_VIDEO_ENCODE_H265_CAPABILITY_LOG2_PARALLEL_MERGE_LEVEL_MINUS2_BIT_EXT = 0x00000080,
VK_VIDEO_ENCODE_H265_CAPABILITY_SIGN_DATA_HIDING_ENABLED_BIT_EXT = 0x00000100,
VK_VIDEO_ENCODE_H265_CAPABILITY_TRANSFORM_SKIP_ENABLED_BIT_EXT = 0x00000200,
VK_VIDEO_ENCODE_H265_CAPABILITY_TRANSFORM_SKIP_DISABLED_BIT_EXT = 0x00000400,
VK_VIDEO_ENCODE_H265_CAPABILITY_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT_BIT_EXT = 0x00000800,
VK_VIDEO_ENCODE_H265_CAPABILITY_WEIGHTED_PRED_BIT_EXT = 0x00001000,
VK_VIDEO_ENCODE_H265_CAPABILITY_WEIGHTED_BIPRED_BIT_EXT = 0x00002000,
VK_VIDEO_ENCODE_H265_CAPABILITY_WEIGHTED_PRED_NO_TABLE_BIT_EXT = 0x00004000,
VK_VIDEO_ENCODE_H265_CAPABILITY_TRANSQUANT_BYPASS_ENABLED_BIT_EXT = 0x00008000,
VK_VIDEO_ENCODE_H265_CAPABILITY_ENTROPY_CODING_SYNC_ENABLED_BIT_EXT = 0x00010000,
VK_VIDEO_ENCODE_H265_CAPABILITY_DEBLOCKING_FILTER_OVERRIDE_ENABLED_BIT_EXT = 0x00020000,
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILE_PER_FRAME_BIT_EXT = 0x00040000,
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_PER_TILE_BIT_EXT = 0x00080000,
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILE_PER_SLICE_BIT_EXT = 0x00100000,
VK_VIDEO_ENCODE_H265_CAPABILITY_SLICE_SEGMENT_CTB_COUNT_BIT_EXT = 0x00200000,
VK_VIDEO_ENCODE_H265_CAPABILITY_ROW_UNALIGNED_SLICE_SEGMENT_BIT_EXT = 0x00400000,
VK_VIDEO_ENCODE_H265_CAPABILITY_DEPENDENT_SLICE_SEGMENT_BIT_EXT = 0x00800000,
VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_EXT = 0x01000000,
VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_EXT = 0x02000000,
} VkVideoEncodeH265CapabilityFlagBitsEXT;
-
VK_VIDEO_ENCODE_H265_CAPABILITY_SEPARATE_COLOUR_PLANE_BIT_EXTreports if enabling separate_colour_plane_flag in StdVideoH265SpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_SCALING_LISTS_BIT_EXTreports if enabling scaling_list_enabled_flag and sps_scaling_list_data_present_flag in StdVideoH265SpsFlags, or enabling pps_scaling_list_data_present_flag in StdVideoH265PpsFlags are supproted. -
VK_VIDEO_ENCODE_H265_CAPABILITY_SAMPLE_ADAPTIVE_OFFSET_ENABLED_BIT_EXTreports if enabling sample_adaptive_offset_enabled_flag in StdVideoH265SpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_PCM_ENABLE_BIT_EXTreports if enabling pcm_enable_flag in StdVideoH265SpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_SPS_TEMPORAL_MVP_ENABLED_BIT_EXTreports if enabling sps_temporal_mvp_enabled_flag in StdVideoH265SpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_HRD_COMPLIANCE_BIT_EXTreports if the implementation guarantees generating a HRD compliant bitstream if nal_hrd_parameters_present_flag, vcl_hrd_parameters_present_flag, or sub_pic_hrd_params_present_flag are enabled in StdVideoH265HrdFlags, or vui_hrd_parameters_present_flag is enabled in StdVideoH265SpsVuiFlags. -
VK_VIDEO_ENCODE_H265_CAPABILITY_INIT_QP_MINUS26_BIT_EXTreports if setting non-zero init_qp_minus26 in StdVideoH265PictureParameterSet is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_LOG2_PARALLEL_MERGE_LEVEL_MINUS2_BIT_EXTreports if setting non-zero value for log2_parallel_merge_level_minus2 in StdVideoH265PictureParameterSet is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_SIGN_DATA_HIDING_ENABLED_BIT_EXTreports if enabling sign_data_hiding_enabled_flag in StdVideoH265PpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_TRANSFORM_SKIP_ENABLED_BIT_EXTreports if enabling transform_skip_enabled_flag in StdVideoH265PpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_TRANSFORM_SKIP_DISABLED_BIT_EXTreports if disabling transform_skip_enabled_flag in StdVideoH265PpsFlags is supported. Implementations must report at least one ofVK_VIDEO_ENCODE_H265_CAPABILITY_TRANSFORM_SKIP_ENABLED_BIT_EXTandVK_VIDEO_ENCODE_H265_CAPABILITY_TRANSFORM_SKIP_DISABLED_BIT_EXTas supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT_BIT_EXTreports if enabling pps_slice_chroma_qp_offsets_present_flag in StdVideoH265PpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_WEIGHTED_PRED_BIT_EXTreports if enabling weighted_pred_flag in StdVideoH265PpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_WEIGHTED_BIPRED_BIT_EXTreports if enabling weighted_bipred_flag in StdVideoH265PpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_WEIGHTED_PRED_NO_TABLE_BIT_EXTreports that when weighted_pred_flag or weighted_bipred_flag in StdVideoH265PpsFlags are enabled, the implementation is able to internally decide syntax for pred_weight_table. -
VK_VIDEO_ENCODE_H265_CAPABILITY_TRANSQUANT_BYPASS_ENABLED_BIT_EXTreports if enabling transquant_bypass_enabled_flag in StdVideoH265PpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_ENTROPY_CODING_SYNC_ENABLED_BIT_EXTreports if enabling entropy_coding_sync_enabled_flag in StdVideoH265PpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_DEBLOCKING_FILTER_OVERRIDE_ENABLED_BIT_EXTreports if enabling deblocking_filter_override_enabled_flag in StdVideoH265PpsFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILE_PER_FRAME_BIT_EXTreports if encoding multiple tiles per frame is supported. If not set, the implementation is only able to encode a single tile for each frame. -
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_PER_TILE_BIT_EXTreports if encoding multiple slices per tile is supported. If not set, the implementation is only able to encode a single slice for each tile. -
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILE_PER_SLICE_BIT_EXTreports if encoding multiple tiles per slice is supported. If not set, the implementation is only able to encode a single tile for each slice. -
VK_VIDEO_ENCODE_H265_CAPABILITY_SLICE_SEGMENT_CTB_COUNT_BIT_EXTreports support for configuring VkVideoEncodeH265NaluSliceSegmentEXT::ctbCountand slice_segment_address in StdVideoEncodeH265SliceSegmentHeader for each slice segment in a frame with multiple slice segments. If not supported, the implementation decides the number of CTBs in each slice segment based on VkVideoEncodeH265VclFrameInfoEXT::naluSliceSegmentEntryCount. -
VK_VIDEO_ENCODE_H265_CAPABILITY_ROW_UNALIGNED_SLICE_SEGMENT_BIT_EXTreports that each slice segment in a frame with a single or multiple tiles per slice may begin or finish at any offset in a CTB row. If not supported, all slice segments in such a frame must begin at the start of a CTB row (and hence each slice segment must finish at the end of a CTB row). Also reports that each slice segment in a frame with multiple slices per tile may begin or finish at any offset within the enclosing tile’s CTB row. If not supported, slice segments in such a frame must begin at the start of the enclosing tile’s CTB row (and hence each slice segment must finish at the end of the enclosing tile’s CTB row). -
VK_VIDEO_ENCODE_H265_CAPABILITY_DEPENDENT_SLICE_SEGMENT_BIT_EXTreports if enabling dependent_slice_segment_flag in StdVideoEncodeH265SliceHeaderFlags is supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_EXTreports that whenVK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_PER_TILE_BIT_EXTis supported and a frame is encoded with multiple slices, the implementation allows encoding each slice segment with a differentStdVideoEncodeH265SliceSegmentHeader::slice_type. If not supported, all slice segments of the frame must be encoded with the sameslice_typewhich corresponds to the picture type of the frame. For example, all slice segments of a P-frame would be encoded as P-slices. -
VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_EXTreports support for using a B frame as L1 reference.
// Provided by VK_EXT_video_encode_h265
typedef VkFlags VkVideoEncodeH265InputModeFlagsEXT;
VkVideoEncodeH265InputModeFlagsEXT is a bitmask type for setting a
mask of zero or more VkVideoEncodeH265InputModeFlagBitsEXT.
Bits which may be set in
VkVideoEncodeH265CapabilitiesEXT::inputModeFlags, indicating the
commmand buffer input granularities supported by the implementation, are:
// Provided by VK_EXT_video_encode_h265
typedef enum VkVideoEncodeH265InputModeFlagBitsEXT {
VK_VIDEO_ENCODE_H265_INPUT_MODE_FRAME_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H265_INPUT_MODE_SLICE_SEGMENT_BIT_EXT = 0x00000002,
VK_VIDEO_ENCODE_H265_INPUT_MODE_NON_VCL_BIT_EXT = 0x00000004,
} VkVideoEncodeH265InputModeFlagBitsEXT;
-
VK_VIDEO_ENCODE_H265_INPUT_MODE_FRAME_BIT_EXTindicates that a single command buffer must at least encode an entire frame. Any non-VCL NALUs must be encoded using the same command buffer as the frame ifVK_VIDEO_ENCODE_H265_INPUT_MODE_NON_VCL_BIT_EXTis not supported. -
VK_VIDEO_ENCODE_H265_INPUT_MODE_SLICE_SEGMENT_BIT_EXTindicates that a single command buffer must at least encode a single slice segment. Any non-VCL NALUs must be encoded using the same command buffer as the first slice segment of the frame ifVK_VIDEO_ENCODE_H265_INPUT_MODE_NON_VCL_BIT_EXTis not supported. -
VK_VIDEO_ENCODE_H265_INPUT_MODE_NON_VCL_BIT_EXTindicates that a single command buffer may encode a non-VCL NALU by itself.
An implementation must support at least one of
VK_VIDEO_ENCODE_H265_INPUT_MODE_FRAME_BIT_EXT or
VK_VIDEO_ENCODE_H265_INPUT_MODE_SLICE_SEGMENT_BIT_EXT.
If VK_VIDEO_ENCODE_H265_INPUT_MODE_SLICE_SEGMENT_BIT_EXT is not
supported, the following two additional restrictions apply for frames
encoded with multiple slice segments.
First, all frame slice segments must have the same pReferenceFinalLists.
Second, the order in which slice segments appear in
VkVideoEncodeH265VclFrameInfoEXT::pNaluSliceSegmentEntries or in
the command buffer must match the placement order of the slice segments in
the frame.
// Provided by VK_EXT_video_encode_h265
typedef VkFlags VkVideoEncodeH265OutputModeFlagsEXT;
VkVideoEncodeH265OutputModeFlagsEXT is a bitmask type for setting a
mask of zero or more VkVideoEncodeH265OutputModeFlagBitsEXT.
Bits which may be set in
VkVideoEncodeH265CapabilitiesEXT::outputModeFlags, indicating
the minimum bitstream generation commands that must be included between
each vkCmdBeginVideoCodingKHR and vkCmdEndVideoCodingKHR pair
(henceforth simply begin/end pair), are:
// Provided by VK_EXT_video_encode_h265
typedef enum VkVideoEncodeH265OutputModeFlagBitsEXT {
VK_VIDEO_ENCODE_H265_OUTPUT_MODE_FRAME_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H265_OUTPUT_MODE_SLICE_SEGMENT_BIT_EXT = 0x00000002,
VK_VIDEO_ENCODE_H265_OUTPUT_MODE_NON_VCL_BIT_EXT = 0x00000004,
} VkVideoEncodeH265OutputModeFlagBitsEXT;
-
VK_VIDEO_ENCODE_H265_OUTPUT_MODE_FRAME_BIT_EXTindicates that calls to generate all NALUs of a frame must be included within a single begin/end pair. Any non-VCL NALUs must be encoded within the same begin/end pair ifVK_VIDEO_ENCODE_H265_OUTPUT_MODE_NON_VCL_BIT_EXTis not supported. -
VK_VIDEO_ENCODE_H265_OUTPUT_MODE_SLICE_SEGMENT_BIT_EXTindicates that each begin/end pair must encode at least one slice segment. Any non-VCL NALUs must be encoded within the same begin/end pair as the first slice segment of the frame ifVK_VIDEO_ENCODE_H265_OUTPUT_MODE_NON_VCL_BIT_EXTis not supported. -
VK_VIDEO_ENCODE_H265_OUTPUT_MODE_NON_VCL_BIT_EXTindicates that each begin/end pair may encode only a non-VCL NALU by itself. An implementation must support at least one ofVK_VIDEO_ENCODE_H265_OUTPUT_MODE_FRAME_BIT_EXTorVK_VIDEO_ENCODE_H265_OUTPUT_MODE_SLICE_SEGMENT_BIT_EXT.
A single begin/end pair must not encode more than a single frame.
The bitstreams of NALUs generated within a single begin/end pair are written continuously into the same bitstream buffer (any padding between the NALUs must be compliant to the H.265 standard).
The supported input modes must be coarser or equal to the supported output modes. For example, it is illegal to report slice segment input is supported but only frame output is supported.
An implementation must report one of the following combinations of input/output modes:
-
Input: Frame, Output: Frame
-
Input: Frame, Output: Frame and Non-VCL
-
Input: Frame, Output: Slice Segment
-
Input: Frame, Output: Slice Segment and Non-VCL
-
Input: Slice Segment, Output: Slice Segment
-
Input: Slice Segment, Output: Slice Segment and Non-VCL
-
Input: Frame and Non-VCL, Output: Frame and Non-VCL
-
Input: Frame and Non-VCL, Output: Slice Segment and Non-VCL
-
Input: Slice Segment and Non-VCL, Output: Slice Segment and Non-VCL
// Provided by VK_EXT_video_encode_h265
typedef VkFlags VkVideoEncodeH265CtbSizeFlagsEXT;
VkVideoEncodeH265CtbSizeFlagsEXT is a bitmask type for setting a mask
of zero or more VkVideoEncodeH265CtbSizeFlagBitsEXT.
Bits which may be set in
VkVideoEncodeH265CapabilitiesEXT::ctbSizes, indicating the CTB
sizes supported by the implementation, are:
// Provided by VK_EXT_video_encode_h265
typedef enum VkVideoEncodeH265CtbSizeFlagBitsEXT {
VK_VIDEO_ENCODE_H265_CTB_SIZE_16_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H265_CTB_SIZE_32_BIT_EXT = 0x00000002,
VK_VIDEO_ENCODE_H265_CTB_SIZE_64_BIT_EXT = 0x00000004,
} VkVideoEncodeH265CtbSizeFlagBitsEXT;
-
VK_VIDEO_ENCODE_H265_CTB_SIZE_16_BIT_EXTspecifies that a CTB size of 16x16 is supported. -
VK_VIDEO_ENCODE_H265_CTB_SIZE_32_BIT_EXTspecifies that a CTB size of 32x32 is supported. -
VK_VIDEO_ENCODE_H265_CTB_SIZE_64_BIT_EXTspecifies that a CTB size of 64x64 is supported.
// Provided by VK_EXT_video_encode_h265
typedef VkFlags VkVideoEncodeH265TransformBlockSizeFlagsEXT;
VkVideoEncodeH265TransformBlockSizeFlagsEXT is a bitmask type for
setting a mask of zero or more
VkVideoEncodeH265TransformBlockSizeFlagBitsEXT.
Bits which may be set in
VkVideoEncodeH265CapabilitiesEXT::transformBlockSizes,
indicating the transform block sizes supported by the implementation, are:
// Provided by VK_EXT_video_encode_h265
typedef enum VkVideoEncodeH265TransformBlockSizeFlagBitsEXT {
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_4_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_8_BIT_EXT = 0x00000002,
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_16_BIT_EXT = 0x00000004,
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_32_BIT_EXT = 0x00000008,
} VkVideoEncodeH265TransformBlockSizeFlagBitsEXT;
-
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_4_BIT_EXTspecifies that a transform block size of 4x4 is supported. -
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_8_BIT_EXTspecifies that a transform block size of 8x8 is supported. -
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_16_BIT_EXTspecifies that a transform block size of 16x16 is supported. -
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_32_BIT_EXTspecifies that a transform block size of 32x32 is supported.
39.10.3. Encoder H.265 Video Session Parameters Object
When creating a Video Session Parameters object, add a
VkVideoEncodeH265SessionParametersCreateInfoEXT structure to the
pNext chain of the VkVideoSessionParametersCreateInfoKHR
structure passed to vkCreateVideoSessionParametersKHR in order to
specify the H.265-specific video encoder session parameters.
The VkVideoEncodeH265SessionParametersCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265SessionParametersCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t maxVpsStdCount;
uint32_t maxSpsStdCount;
uint32_t maxPpsStdCount;
const VkVideoEncodeH265SessionParametersAddInfoEXT* pParametersAddInfo;
} VkVideoEncodeH265SessionParametersCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxVpsStdCountis the maximum number of entries of typeStdVideoH265VideoParameterSetwithinVkVideoSessionParametersKHR. -
maxSpsStdCountis the maximum number of entries of typeStdVideoH265SequenceParameterSetwithinVkVideoSessionParametersKHR. -
maxPpsStdCountis the maximum number of entries of typeStdVideoH265PictureParameterSetwithinVkVideoSessionParametersKHR. -
pParametersAddInfoisNULLor a pointer to a VkVideoEncodeH265SessionParametersAddInfoEXT structure specifying the video session parameters to add upon creation of this object.
When a VkVideoSessionParametersKHR object contains
maxVpsStdCount StdVideoH265VideoParameterSet entries, no
additional StdVideoH265VideoParameterSet entries can be added to it,
and VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made
to add these entries.
When a VkVideoSessionParametersKHR object contains
maxSpsStdCount StdVideoH265SequenceParameterSet entries, no
additional StdVideoH265SequenceParameterSet entries can be added to it,
and VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made
to add these entries.
When a VkVideoSessionParametersKHR object contains
maxPpsStdCount StdVideoH265PictureParameterSet entries, no
additional StdVideoH265PictureParameterSet entries can be added to it,
and VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made
to add these entries.
The VkVideoEncodeH265SessionParametersAddInfoEXT structure is defined
as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265SessionParametersAddInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t vpsStdCount;
const StdVideoH265VideoParameterSet* pVpsStd;
uint32_t spsStdCount;
const StdVideoH265SequenceParameterSet* pSpsStd;
uint32_t ppsStdCount;
const StdVideoH265PictureParameterSet* pPpsStd;
} VkVideoEncodeH265SessionParametersAddInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vpsStdCountis the number of VPS elements inpVpsStd. -
pVpsStdis a pointer to an array ofvpsStdCountStdVideoH265VideoParameterSetstructures representing H.265 video parameter sets. -
spsStdCountis the number of SPS elements inpSpsStd. -
pSpsStdis a pointer to an array ofspsStdCountStdVideoH265SequenceParameterSetstructures representing H.265 sequence parameter sets. -
ppsStdCountis the number of PPS elements inpPpsStd. -
pPpsStdis a pointer to an array ofppsStdCountStdVideoH265PictureParameterSetstructures representing H.265 picture parameter sets.
39.10.4. Frame Encoding
In order to encode a frame, add a VkVideoEncodeH265VclFrameInfoEXT
structure to the pNext chain of the VkVideoEncodeInfoKHR
structure passed to the vkCmdEncodeVideoKHR command.
The VkVideoEncodeH265VclFrameInfoEXT structure representing a frame encode operation is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265VclFrameInfoEXT {
VkStructureType sType;
const void* pNext;
const VkVideoEncodeH265ReferenceListsEXT* pReferenceFinalLists;
uint32_t naluSliceSegmentEntryCount;
const VkVideoEncodeH265NaluSliceSegmentEXT* pNaluSliceSegmentEntries;
const StdVideoEncodeH265PictureInfo* pCurrentPictureInfo;
} VkVideoEncodeH265VclFrameInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pReferenceFinalListsisNULLor a pointer to a VkVideoEncodeH265ReferenceListsEXT structure specifying the reference lists to be used for the current picture. -
naluSliceSegmentEntryCountis the number of slice segment NALUs in the frame. -
pNaluSliceSegmentEntriesis a pointer to an array of VkVideoEncodeH265NaluSliceSegmentEXT structures specifying the division of the current picture into slice segments and the properties of these slice segments. -
pCurrentPictureInfois a pointer to aStdVideoEncodeH265PictureInfostructure specifying the syntax and other codec-specific information from the H.265 specification, associated with this picture.
The VkVideoEncodeH265NaluSliceSegmentEXT structure representing a slice segment is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265NaluSliceSegmentEXT {
VkStructureType sType;
const void* pNext;
uint32_t ctbCount;
const VkVideoEncodeH265ReferenceListsEXT* pReferenceFinalLists;
const StdVideoEncodeH265SliceSegmentHeader* pSliceSegmentHeaderStd;
} VkVideoEncodeH265NaluSliceSegmentEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
ctbCountis the number of CTBs in this slice segment. -
pReferenceFinalListsisNULLor a pointer to a VkVideoEncodeH265ReferenceListsEXT structure specifying the reference lists to be used for the current slice segment. IfpReferenceFinalListsis notNULL, these reference lists override the reference lists provided in VkVideoEncodeH265VclFrameInfoEXT::pReferenceFinalLists. -
pSliceSegmentHeaderStdis a pointer to aStdVideoEncodeH265SliceSegmentHeaderstructure specifying the slice segment header for the current slice segment.
The VkVideoEncodeH265DpbSlotInfoEXT structure, representing a reconstructed picture that is being used as a reference picture, is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265DpbSlotInfoEXT {
VkStructureType sType;
const void* pNext;
int8_t slotIndex;
const StdVideoEncodeH265ReferenceInfo* pStdReferenceInfo;
} VkVideoEncodeH265DpbSlotInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
slotIndexis the DPB Slot index for this picture. -
pStdReferenceInfois a pointer to aStdVideoEncodeH265ReferenceInfostructure specifying the syntax and other codec-specific information from the H.265 specification, associated with this reference picture.
The VkVideoEncodeH265ReferenceListsEXT structure representing reference lists is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265ReferenceListsEXT {
VkStructureType sType;
const void* pNext;
uint8_t referenceList0EntryCount;
const VkVideoEncodeH265DpbSlotInfoEXT* pReferenceList0Entries;
uint8_t referenceList1EntryCount;
const VkVideoEncodeH265DpbSlotInfoEXT* pReferenceList1Entries;
const StdVideoEncodeH265ReferenceModifications* pReferenceModifications;
} VkVideoEncodeH265ReferenceListsEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
referenceList0EntryCountis the number of reference pictures in reference list L0 and is identical toStdVideoEncodeH265SliceSegmentHeader::num_ref_idx_l0_active_minus1+ 1. -
pReferenceList0Entriesis a pointer to an array ofreferenceList0EntryCountVkVideoEncodeH265DpbSlotInfoEXT structures specifying the reference list L0 entries for the current picture. -
referenceList1EntryCountis the number of reference pictures in reference list L1 and is identical toStdVideoEncodeH265SliceSegmentHeader::num_ref_idx_l1_active_minus1+ 1. -
pReferenceList1Entriesis a pointer to an array ofreferenceList1EntryCountVkVideoEncodeH265DpbSlotInfoEXT structures specifying the reference list L1 entries for the current picture. -
pReferenceModificationsis a pointer to aStdVideoEncodeH265ReferenceModificationsstructure specifying reference list modifications.
The VkVideoEncodeH265EmitPictureParametersEXT structure is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265EmitPictureParametersEXT {
VkStructureType sType;
const void* pNext;
uint8_t vpsId;
uint8_t spsId;
VkBool32 emitVpsEnable;
VkBool32 emitSpsEnable;
uint32_t ppsIdEntryCount;
const uint8_t* ppsIdEntries;
} VkVideoEncodeH265EmitPictureParametersEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vpsIdis the H.265 VPS ID for the H.265 VPS to insert in the bitstream. The VPS ID must match the VPS provided invpsStdof VkVideoEncodeH265SessionParametersCreateInfoEXT. This is retrieved from the VkVideoSessionParametersKHR object provided in VkVideoBeginCodingInfoKHR. -
spsIdis the H.265 SPS ID for the H.265 SPS to insert in the bitstream. The SPS ID must match one of the IDs of the SPS(s) provided inpSpsStdof VkVideoEncodeH265SessionParametersCreateInfoEXT to identify the SPS parameter set to insert in the bitstream. This is retrieved from the VkVideoSessionParametersKHR object provided in VkVideoBeginCodingInfoKHR. -
emitVpsEnableenables the emitting of the VPS structure with id ofvpsId. -
emitSpsEnableenables the emitting of the SPS structure with id ofspsId. -
ppsIdEntryCountis the number of entries in theppsIdEntries. If this parameter is0then no pps entries are going to be emitted in the bitstream. -
ppsIdEntriesis the H.265 PPS IDs for the H.265 PPS to insert in the bitstream. The PPS IDs must match one of the IDs of the PPS(s) provided inpPpsStdof VkVideoEncodeH265SessionParametersCreateInfoEXT to identify the PPS parameter set to insert in the bitstream. This is retrieved from the VkVideoSessionParametersKHR object provided in VkVideoBeginCodingInfoKHR.
39.10.5. Rate control
The VkVideoEncodeH265RateControlInfoEXT structure is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265RateControlInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t gopFrameCount;
uint32_t idrPeriod;
uint32_t consecutiveBFrameCount;
VkVideoEncodeH265RateControlStructureFlagBitsEXT rateControlStructure;
uint8_t subLayerCount;
} VkVideoEncodeH265RateControlInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
gopFrameCountis the number of frames contained within the group of pictures (GOP), starting from an intra frame and until the next intra frame. If it is set to 0, the implementation chooses a suitable value. If it is set toUINT32_MAX, the GOP length is treated as infinite. -
idrPeriodis the interval, in terms of number of frames, between two IDR frames. If it is set to 0, the implementation chooses a suitable value. If it is set toUINT32_MAX, the IDR period is treated as infinite. -
consecutiveBFrameCountis the number of consecutive B-frames between I- and/or P-frames within the GOP. -
rateControlStructureis a VkVideoEncodeH265RateControlStructureFlagBitsEXT value specifying the expected encode stream reference structure, to aid in rate control calculations. -
subLayerCountspecifies the number of sub layers enabled in the stream.
In order to provide H.265-specific stream rate control parameters, add a
VkVideoEncodeH265RateControlInfoEXT structure to the pNext chain
of the VkVideoEncodeRateControlInfoKHR structure in the pNext
chain of the VkVideoCodingControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command.
The parameters from this structure act as a guidance for implementations to apply various rate control heuristics.
It is possible to infer the picture type to be used when encoding a frame,
on the basis of the values provided for consecutiveBFrameCount,
idrPeriod, and gopFrameCount, but this inferred picture type
will not be used by implementations to override the picture type provided in
vkCmdEncodeVideoKHR.
Additionally, it is not required for the video session to be reset if the
inferred picture type does not match the actual picture type.
Possible values of
VkVideoEncodeH265RateControlInfoEXT::rateControlStructure,
specifying a video stream reference structure as a hint for the rate control
implementation, are:
// Provided by VK_EXT_video_encode_h265
typedef enum VkVideoEncodeH265RateControlStructureFlagBitsEXT {
VK_VIDEO_ENCODE_H265_RATE_CONTROL_STRUCTURE_UNKNOWN_EXT = 0,
VK_VIDEO_ENCODE_H265_RATE_CONTROL_STRUCTURE_FLAT_BIT_EXT = 0x00000001,
VK_VIDEO_ENCODE_H265_RATE_CONTROL_STRUCTURE_DYADIC_BIT_EXT = 0x00000002,
} VkVideoEncodeH265RateControlStructureFlagBitsEXT;
-
VK_VIDEO_ENCODE_H265_RATE_CONTROL_STRUCTURE_UNKNOWN_EXTis0, and specifies a reference structure unknown at the time of stream rate control configuration. -
VK_VIDEO_ENCODE_H265_RATE_CONTROL_STRUCTURE_FLAT_BIT_EXTspecifies a flat reference structure. -
VK_VIDEO_ENCODE_H265_RATE_CONTROL_STRUCTURE_DYADIC_BIT_EXTspecifies a dyadic reference structure.
The VkVideoEncodeH265RateControlLayerInfoEXT structure is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265RateControlLayerInfoEXT {
VkStructureType sType;
const void* pNext;
uint8_t temporalId;
VkBool32 useInitialRcQp;
VkVideoEncodeH265QpEXT initialRcQp;
VkBool32 useMinQp;
VkVideoEncodeH265QpEXT minQp;
VkBool32 useMaxQp;
VkVideoEncodeH265QpEXT maxQp;
VkBool32 useMaxFrameSize;
VkVideoEncodeH265FrameSizeEXT maxFrameSize;
} VkVideoEncodeH265RateControlLayerInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
temporalIdspecifies the H.265 temporal ID of the video coding layer that settings provided in this structure and its parent VkVideoEncodeRateControlLayerInfoKHR structure apply to. -
useInitialRcQpindicates whether the values withininitialRcQpshould be used by the implementation. -
initialRcQpprovides the QP values for each picture type, to be used in rate control calculations at the start of video encode operations on a newly-created video session, or immediately after a session reset. These values are ignored when VkVideoEncodeRateControlInfoKHR::rateControlModeisVK_VIDEO_ENCODE_RATE_CONTROL_MODE_NONE_BIT_KHR. -
useMinQpindicates whether the values withinminQpshould be used by the implementation. When it is set toVK_FALSE, the implementation ignores the values inminQpand chooses suitable values. -
minQpprovides the lower bound on the QP values for each picture type, to be used in rate control calculations. -
useMaxQpindicates whether the values withinmaxQpshould be used by the implementation. When it is set toVK_FALSE, the implementation ignores the values inmaxQpand chooses suitable values. -
maxQpprovides the upper bound on the QP values for each picture type, to be used in rate control calculations. -
useMaxFrameSizeindicates whether the values withinmaxFrameSizeshould be used by the implementation. -
maxFrameSizeprovides the upper bound on the encoded frame size for each picture type. The implementation does not guarantee the encoded frame sizes will be within the specified limits, however these limits may be used as a guide in rate control calculations. If enabled and not set properly, themaxQplimit may prevent the implementation from respecting themaxFrameSizelimit.
H.265-specific per-layer rate control parameters must be specified by
adding a VkVideoEncodeH265RateControlLayerInfoEXT structure to the
pNext chain of each VkVideoEncodeRateControlLayerInfoKHR
structure in a call to vkCmdControlVideoCodingKHR command, when the
command buffer context has an active video encode H.265 session.
The VkVideoEncodeH265QpEXT structure is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265QpEXT {
int32_t qpI;
int32_t qpP;
int32_t qpB;
} VkVideoEncodeH265QpEXT;
-
qpIis the QP to be used for I-frames. -
qpPis the QP to be used for P-frames. -
qpBis the QP to be used for B-frames.
The VkVideoEncodeH265FrameSizeEXT structure is defined as:
// Provided by VK_EXT_video_encode_h265
typedef struct VkVideoEncodeH265FrameSizeEXT {
uint32_t frameISize;
uint32_t framePSize;
uint32_t frameBSize;
} VkVideoEncodeH265FrameSizeEXT;
-
frameISizeis the size in bytes to be used for I-frames. -
framePSizeis the size in bytes to be used for P-frames. -
frameBSizeis the size in bytes to be used for B-frames.
40. Extending Vulkan
New functionality may be added to Vulkan via either new extensions or new versions of the core, or new versions of an extension in some cases.
This chapter describes how Vulkan is versioned, how compatibility is affected between different versions, and compatibility rules that are followed by the Vulkan Working Group.
40.1. Instance and Device Functionality
Commands that enumerate instance properties, or that accept a VkInstance object as a parameter, are considered instance-level functionality. Commands that enumerate physical device properties, or that accept a VkDevice object or any of a device’s child objects as a parameter, are considered device-level functionality.
|
Note
Applications usually interface to Vulkan using a loader that implements only instance-level functionality, passing device-level functionality to implementations of the full Vulkan API on the system. In some circumstances, as these may be implemented independently, it is possible that the loader and device implementations on a given installation will support different versions. To allow for this and call out when it happens, the Vulkan specification enumerates device and instance level functionality separately - they have independent version queries. |
|
Note
Vulkan 1.0 initially specified new physical device enumeration functionality
as instance-level, requiring it to be included in an instance extension.
As the capabilities of device-level functionality require discovery via
physical device enumeration, this led to the situation where many device
extensions required an instance extension as well.
To alleviate this extra work,
|
40.2. Core Versions
The Vulkan Specification is regularly updated with bug fixes and clarifications. Occasionally new functionality is added to the core and at some point it is expected that there will be a desire to perform a large, breaking change to the API. In order to indicate to developers how and when these changes are made to the specification, and to provide a way to identify each set of changes, the Vulkan API maintains a version number.
40.2.1. Version Numbers
The Vulkan version number comprises four parts indicating the variant, major, minor and patch version of the Vulkan API Specification.
The variant indicates the variant of the Vulkan API supported by the implementation. This is always 0 for the Vulkan API.
|
Note
A non-zero variant indicates the API is a variant of the Vulkan API and applications will typically need to be modified to run against it. The variant field was a later addition to the version number, added in version 1.2.175 of the Specification. As Vulkan uses variant 0, this change is fully backwards compatible with the previous version number format for Vulkan implementations. New version number macros have been added for this change and the old macros deprecated. For existing applications using the older format and macros, an implementation with non-zero variant will decode as a very high Vulkan version. The high version number should be detectable by applications performing suitable version checking. |
The major version indicates a significant change in the API, which will encompass a wholly new version of the specification.
The minor version indicates the incorporation of new functionality into the core specification.
The patch version indicates bug fixes, clarifications, and language improvements have been incorporated into the specification.
Compatibility guarantees made about versions of the API sharing any of the same version numbers are documented in Core Versions
The version number is used in several places in the API. In each such use, the version numbers are packed into a 32-bit integer as follows:
-
The variant is a 3-bit integer packed into bits 31-29.
-
The major version is a 7-bit integer packed into bits 28-22.
-
The minor version number is a 10-bit integer packed into bits 21-12.
-
The patch version number is a 12-bit integer packed into bits 11-0.
VK_API_VERSION_VARIANT extracts the API variant number from a packed
version number:
// Provided by VK_VERSION_1_0
#define VK_API_VERSION_VARIANT(version) ((uint32_t)(version) >> 29)
VK_API_VERSION_MAJOR extracts the API major version number from a
packed version number:
// Provided by VK_VERSION_1_0
#define VK_API_VERSION_MAJOR(version) (((uint32_t)(version) >> 22) & 0x7FU)
VK_VERSION_MAJOR extracts the API major version number from a packed
version number:
// Provided by VK_VERSION_1_0
// DEPRECATED: This define is deprecated. VK_API_VERSION_MAJOR should be used instead.
#define VK_VERSION_MAJOR(version) ((uint32_t)(version) >> 22)
VK_API_VERSION_MINOR extracts the API minor version number from a
packed version number:
// Provided by VK_VERSION_1_0
#define VK_API_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3FFU)
VK_VERSION_MINOR extracts the API minor version number from a packed
version number:
// Provided by VK_VERSION_1_0
// DEPRECATED: This define is deprecated. VK_API_VERSION_MINOR should be used instead.
#define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3FFU)
VK_API_VERSION_PATCH extracts the API patch version number from a
packed version number:
// Provided by VK_VERSION_1_0
#define VK_API_VERSION_PATCH(version) ((uint32_t)(version) & 0xFFFU)
VK_VERSION_PATCH extracts the API patch version number from a packed
version number:
// Provided by VK_VERSION_1_0
// DEPRECATED: This define is deprecated. VK_API_VERSION_PATCH should be used instead.
#define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xFFFU)
VK_MAKE_API_VERSION constructs an API version number.
// Provided by VK_VERSION_1_0
#define VK_MAKE_API_VERSION(variant, major, minor, patch) \
((((uint32_t)(variant)) << 29) | (((uint32_t)(major)) << 22) | (((uint32_t)(minor)) << 12) | ((uint32_t)(patch)))
-
variantis the variant number. -
majoris the major version number. -
minoris the minor version number. -
patchis the patch version number.
VK_MAKE_VERSION constructs an API version number.
// Provided by VK_VERSION_1_0
// DEPRECATED: This define is deprecated. VK_MAKE_API_VERSION should be used instead.
#define VK_MAKE_VERSION(major, minor, patch) \
((((uint32_t)(major)) << 22) | (((uint32_t)(minor)) << 12) | ((uint32_t)(patch)))
-
majoris the major version number. -
minoris the minor version number. -
patchis the patch version number.
VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0.0.
// Provided by VK_VERSION_1_0
// Vulkan 1.0 version number
#define VK_API_VERSION_1_0 VK_MAKE_API_VERSION(0, 1, 0, 0)// Patch version should always be set to 0
VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1.0.
// Provided by VK_VERSION_1_1
// Vulkan 1.1 version number
#define VK_API_VERSION_1_1 VK_MAKE_API_VERSION(0, 1, 1, 0)// Patch version should always be set to 0
VK_API_VERSION_1_2 returns the API version number for Vulkan 1.2.0.
// Provided by VK_VERSION_1_2
// Vulkan 1.2 version number
#define VK_API_VERSION_1_2 VK_MAKE_API_VERSION(0, 1, 2, 0)// Patch version should always be set to 0
VK_API_VERSION_1_3 returns the API version number for Vulkan 1.3.0.
// Provided by VK_VERSION_1_3
// Vulkan 1.3 version number
#define VK_API_VERSION_1_3 VK_MAKE_API_VERSION(0, 1, 3, 0)// Patch version should always be set to 0
40.2.2. Querying Version Support
The version of instance-level functionality can be queried by calling vkEnumerateInstanceVersion.
The version of device-level functionality can be queried by calling
vkGetPhysicalDeviceProperties
or vkGetPhysicalDeviceProperties2,
and is returned in VkPhysicalDeviceProperties::apiVersion,
encoded as described in Version Numbers.
40.3. Layers
When a layer is enabled, it inserts itself into the call chain for Vulkan commands the layer is interested in. Layers can be used for a variety of tasks that extend the base behavior of Vulkan beyond what is required by the specification - such as call logging, tracing, validation, or providing additional extensions.
|
Note
For example, an implementation is not expected to check that the value of enums used by the application fall within allowed ranges. Instead, a validation layer would do those checks and flag issues. This avoids a performance penalty during production use of the application because those layers would not be enabled in production. |
|
Note
Vulkan layers may wrap object handles (i.e. return a different handle value to the application than that generated by the implementation). This is generally discouraged, as it increases the probability of incompatibilities with new extensions. The validation layers wrap handles in order to track the proper use and destruction of each object. See the “Architecture of the Vulkan Loader Interfaces” document for additional information. |
To query the available layers, call:
// Provided by VK_VERSION_1_0
VkResult vkEnumerateInstanceLayerProperties(
uint32_t* pPropertyCount,
VkLayerProperties* pProperties);
-
pPropertyCountis a pointer to an integer related to the number of layer properties available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array of VkLayerProperties structures.
If pProperties is NULL, then the number of layer 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 layer 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 properties were returned.
The list of available layers may change at any time due to actions outside
of the Vulkan implementation, so two calls to
vkEnumerateInstanceLayerProperties with the same parameters may
return different results, or retrieve different pPropertyCount values
or pProperties contents.
Once an instance has been created, the layers enabled for that instance will
continue to be enabled and valid for the lifetime of that instance, even if
some of them become unavailable for future instances.
The VkLayerProperties structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkLayerProperties {
char layerName[VK_MAX_EXTENSION_NAME_SIZE];
uint32_t specVersion;
uint32_t implementationVersion;
char description[VK_MAX_DESCRIPTION_SIZE];
} VkLayerProperties;
-
layerNameis an array ofVK_MAX_EXTENSION_NAME_SIZEcharcontaining a null-terminated UTF-8 string which is the name of the layer. Use this name in theppEnabledLayerNamesarray passed in the VkInstanceCreateInfo structure to enable this layer for an instance. -
specVersionis the Vulkan version the layer was written to, encoded as described in Version Numbers. -
implementationVersionis the version of this layer. It is an integer, increasing with backward compatible changes. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which provides additional details that can be used by the application to identify the layer.
VK_MAX_EXTENSION_NAME_SIZE is the length in char values of an
array containing a layer or extension name string, as returned in
VkLayerProperties::layerName,
VkExtensionProperties::extensionName, and other queries.
#define VK_MAX_EXTENSION_NAME_SIZE 256U
VK_MAX_DESCRIPTION_SIZE is the length in char values of an array
containing a string with additional descriptive information about a query,
as returned in VkLayerProperties::description and other queries.
#define VK_MAX_DESCRIPTION_SIZE 256U
To enable a layer, the name of the layer should be added to the
ppEnabledLayerNames member of VkInstanceCreateInfo when creating
a VkInstance.
Loader implementations may provide mechanisms outside the Vulkan API for
enabling specific layers.
Layers enabled through such a mechanism are implicitly enabled, while
layers enabled by including the layer name in the ppEnabledLayerNames
member of VkInstanceCreateInfo are explicitly enabled.
Implicitly enabled layers are loaded before explicitly enabled layers, such
that implicitly enabled layers are closer to the application, and explicitly
enabled layers are closer to the driver.
Except where otherwise specified, implicitly enabled and explicitly enabled
layers differ only in the way they are enabled, and the order in which they
are loaded.
Explicitly enabling a layer that is implicitly enabled results in this layer
being loaded as an implicitly enabled layer; it has no additional effect.
40.3.1. Device Layer Deprecation
Previous versions of this specification distinguished between instance and
device layers.
Instance layers were only able to intercept commands that operate on
VkInstance and VkPhysicalDevice, except they were not able to
intercept vkCreateDevice.
Device layers were enabled for individual devices when they were created,
and could only intercept commands operating on that device or its child
objects.
Device-only layers are now deprecated, and this specification no longer distinguishes between instance and device layers. Layers are enabled during instance creation, and are able to intercept all commands operating on that instance or any of its child objects. At the time of deprecation there were no known device-only layers and no compelling reason to create one.
In order to maintain compatibility with implementations released prior to
device-layer deprecation, applications should still enumerate and enable
device layers.
The behavior of vkEnumerateDeviceLayerProperties and valid usage of
the ppEnabledLayerNames member of VkDeviceCreateInfo maximizes
compatibility with applications written to work with the previous
requirements.
To enumerate device layers, call:
// Provided by VK_VERSION_1_0
VkResult vkEnumerateDeviceLayerProperties(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkLayerProperties* pProperties);
-
physicalDeviceis the physical device that will be queried. -
pPropertyCountis a pointer to an integer related to the number of layer properties available or queried. -
pPropertiesis eitherNULLor a pointer to an array of VkLayerProperties structures.
If pProperties is NULL, then the number of layer 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 layer 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 properties were returned.
The list of layers enumerated by vkEnumerateDeviceLayerProperties
must be exactly the sequence of layers enabled for the instance.
The members of VkLayerProperties for each enumerated layer must be
the same as the properties when the layer was enumerated by
vkEnumerateInstanceLayerProperties.
|
Note
Due to platform details on Android, |
The ppEnabledLayerNames and enabledLayerCount members of
VkDeviceCreateInfo are deprecated and their values must be ignored by
implementations.
However, for compatibility, only an empty list of layers or a list that
exactly matches the sequence enabled at instance creation time are valid,
and validation layers should issue diagnostics for other cases.
Regardless of the enabled layer list provided in VkDeviceCreateInfo, the sequence of layers active for a device will be exactly the sequence of layers enabled when the parent instance was created.
40.4. Extensions
Extensions may define new Vulkan commands, structures, and enumerants.
For compilation purposes, the interfaces defined by registered extensions,
including new structures and enumerants as well as function pointer types
for new commands, are defined in the Khronos-supplied vulkan_core.h
together with the core API.
However, commands defined by extensions may not be available for static
linking - in which case function pointers to these commands should be
queried at runtime as described in Command Function Pointers.
Extensions may be provided by layers as well as by a Vulkan implementation.
Because extensions may extend or change the behavior of the Vulkan API, extension authors should add support for their extensions to the Khronos validation layers. This is especially important for new commands whose parameters have been wrapped by the validation layers. See the “Architecture of the Vulkan Loader Interfaces” document for additional information.
|
Note
To enable an instance extension, the name of the extension can be added to
the To enable a device extension, the name of the extension can be added to the
Physical-Device-Level functionality does not have any enabling mechanism and can be used as long as the VkPhysicalDevice supports the device extension as determined by vkEnumerateDeviceExtensionProperties. Enabling an extension (with no further use of that extension) does not change the behavior of functionality exposed by the core Vulkan API or any other extension, other than making valid the use of the commands, enums and structures defined by that extension. Valid Usage sections for individual commands and structures do not currently contain which extensions have to be enabled in order to make their use valid, although they might do so in the future. It is defined only in the Valid Usage for Extensions section. |
40.4.1. Instance Extensions
Instance extensions add new instance-level functionality to the API, outside of the core specification.
To query the available instance extensions, call:
// Provided by VK_VERSION_1_0
VkResult vkEnumerateInstanceExtensionProperties(
const char* pLayerName,
uint32_t* pPropertyCount,
VkExtensionProperties* pProperties);
-
pLayerNameis eitherNULLor a pointer to a null-terminated UTF-8 string naming the layer to retrieve extensions from. -
pPropertyCountis a pointer to an integer related to the number of extension properties available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array of VkExtensionProperties structures.
When pLayerName parameter is NULL, only extensions provided by the
Vulkan implementation or by implicitly enabled layers are returned.
When pLayerName is the name of a layer, the instance extensions
provided by that layer are returned.
If pProperties is NULL, then the number of extensions 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 extension 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 properties were returned.
Because the list of available layers may change externally between calls to
vkEnumerateInstanceExtensionProperties, two calls may retrieve
different results if a pLayerName is available in one call but not in
another.
The extensions supported by a layer may also change between two calls, e.g.
if the layer implementation is replaced by a different version between those
calls.
Implementations must not advertise any pair of extensions that cannot be enabled together due to behavioral differences, or any extension that cannot be enabled against the advertised version.
40.4.2. Device Extensions
Device extensions add new device-level functionality to the API, outside of the core specification.
To query the extensions available to a given physical device, call:
// Provided by VK_VERSION_1_0
VkResult vkEnumerateDeviceExtensionProperties(
VkPhysicalDevice physicalDevice,
const char* pLayerName,
uint32_t* pPropertyCount,
VkExtensionProperties* pProperties);
-
physicalDeviceis the physical device that will be queried. -
pLayerNameis eitherNULLor a pointer to a null-terminated UTF-8 string naming the layer to retrieve extensions from. -
pPropertyCountis a pointer to an integer related to the number of extension properties available or queried, and is treated in the same fashion as the vkEnumerateInstanceExtensionProperties::pPropertyCountparameter. -
pPropertiesis eitherNULLor a pointer to an array of VkExtensionProperties structures.
When pLayerName parameter is NULL, only extensions provided by the
Vulkan implementation or by implicitly enabled layers are returned.
When pLayerName is the name of a layer, the device extensions provided
by that layer are returned.
Implementations must not advertise any pair of extensions that cannot be enabled together due to behavioral differences, or any extension that cannot be enabled against the advertised version.
Implementations claiming support for the Roadmap 2022
profile must advertise the VK_KHR_global_priority extension in
pProperties.
|
Note
Due to platform details on Android,
|
The VkExtensionProperties structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkExtensionProperties {
char extensionName[VK_MAX_EXTENSION_NAME_SIZE];
uint32_t specVersion;
} VkExtensionProperties;
-
extensionNameis an array ofVK_MAX_EXTENSION_NAME_SIZEcharcontaining a null-terminated UTF-8 string which is the name of the extension. -
specVersionis the version of this extension. It is an integer, incremented with backward compatible changes.
40.5. Extension Dependencies
Some extensions are dependent on other extensions, or on specific core API versions, to function. To enable extensions with dependencies, any required extensions must also be enabled through the same API mechanisms when creating an instance with vkCreateInstance or a device with vkCreateDevice. Each extension which has such dependencies documents them in the appendix summarizing that extension.
If an extension is supported (as queried by vkEnumerateInstanceExtensionProperties or vkEnumerateDeviceExtensionProperties), then required extensions of that extension must also be supported for the same instance or physical device.
Any device extension that has an instance extension dependency that is not enabled by vkCreateInstance is considered to be unsupported, hence it must not be returned by vkEnumerateDeviceExtensionProperties for any VkPhysicalDevice child of the instance. Instance extensions do not have dependencies on device extensions.
If a required extension has been promoted to another extension or to a core API version, then as a general rule, the dependency is also satisfied by the promoted extension or core version. This will be true so long as any features required by the original extension are also required or enabled by the promoted extension or core version. However, in some cases an extension is promoted while making some of its features optional in the promoted extension or core version. In this case, the dependency may not be satisfied. The only way to be certain is to look at the descriptions of the original dependency and the promoted version in the Layers & Extensions and Core Revisions appendices.
|
Note
There is metadata in |
40.6. Compatibility Guarantees (Informative)
This section is marked as informal as there is no binding responsibility on implementations of the Vulkan API - these guarantees are however a contract between the Vulkan Working Group and developers using this Specification.
40.6.1. Core Versions
Each of the major, minor, and patch versions of the Vulkan specification provide different compatibility guarantees.
Patch Versions
A difference in the patch version indicates that a set of bug fixes or clarifications have been made to the Specification. Informative enums returned by Vulkan commands that will not affect the runtime behavior of a valid application may be added in a patch version (e.g. VkVendorId).
The specification’s patch version is strictly increasing for a given major version of the specification; any change to a specification as described above will result in the patch version being increased by 1. Patch versions are applied to all minor versions, even if a given minor version is not affected by the provoking change.
Specifications with different patch versions but the same major and minor version are fully compatible with each other - such that a valid application written against one will work with an implementation of another.
|
Note
If a patch version includes a bug fix or clarification that could have a significant impact on developer expectations, these will be highlighted in the change log. Generally the Vulkan Working Group tries to avoid these kinds of changes, instead fixing them in either an extension or core version. |
Minor Versions
Changes in the minor version of the specification indicate that new functionality has been added to the core specification. This will usually include new interfaces in the header, and may also include behavior changes and bug fixes. Core functionality may be deprecated in a minor version, but will not be obsoleted or removed.
The specification’s minor version is strictly increasing for a given major version of the specification; any change to a specification as described above will result in the minor version being increased by 1. Changes that can be accommodated in a patch version will not increase the minor version.
Specifications with a lower minor version are backwards compatible with an implementation of a specification with a higher minor version for core functionality and extensions issued with the KHR vendor tag. Vendor and multi-vendor extensions are not guaranteed to remain functional across minor versions, though in general they are with few exceptions - see Obsoletion for more information.
Major Versions
A difference in the major version of specifications indicates a large set of changes which will likely include interface changes, behavioral changes, removal of deprecated functionality, and the modification, addition, or replacement of other functionality.
The specification’s major version is monotonically increasing; any change to the specification as described above will result in the major version being increased. Changes that can be accommodated in a patch or minor version will not increase the major version.
The Vulkan Working Group intends to only issue a new major version of the Specification in order to realise significant improvements to the Vulkan API that will necessarily require breaking compatibility.
A new major version will likely include a wholly new version of the specification to be issued - which could include an overhaul of the versioning semantics for the minor and patch versions. The patch and minor versions of a specification are therefore not meaningful across major versions. If a major version of the specification includes similar versioning semantics, it is expected that the patch and the minor version will be reset to 0 for that major version.
40.6.2. Extensions
A KHR extension must be able to be enabled alongside any other KHR extension, and for any minor or patch version of the core Specification beyond the minimum version it requires. A multi-vendor extension should be able to be enabled alongside any KHR extension or other multi-vendor extension, and for any minor or patch version of the core Specification beyond the minimum version it requires. A vendor extension should be able to be enabled alongside any KHR extension, multi-vendor extension, or other vendor extension from the same vendor, and for any minor or patch version of the core Specification beyond the minimum version it requires. A vendor extension may be able to be enabled alongside vendor extensions from another vendor.
The one other exception to this is if a vendor or multi-vendor extension is made obsolete by either a core version or another extension, which will be highlighted in the extension appendix.
Promotion
Extensions, or features of an extension, may be promoted to a new core version of the API, or a newer extension which an equal or greater number of implementors are in favour of.
When extension functionality is promoted, minor changes may be introduced, limited to the following:
-
Naming
-
Non-intrusive parameters changes
-
Combining structure parameters into larger structures
-
Author ID suffixes changed or removed
|
Note
If extension functionality is promoted, there is no guarantee of direct compatibility, however it should require little effort to port code from the original feature to the promoted one. The Vulkan Working Group endeavours to ensure that larger changes are marked as either deprecated or obsoleted as appropriate, and can do so retroactively if necessary. |
Extensions that are promoted are listed as being promoted in their extension appendices, with reference to where they were promoted to.
When an extension is promoted, any backwards compatibility aliases which exist in the extension will not be promoted.
|
Note
As a hypothetical example, if the |
Deprecation
Extensions may be marked as deprecated when the intended use cases either become irrelevant or can be solved in other ways. Generally, a new feature will become available to solve the use case in another extension or core version of the API, but it is not guaranteed.
|
Note
Features that are intended to replace deprecated functionality have no guarantees of compatibility, and applications may require drastic modification in order to make use of the new features. |
Extensions that are deprecated are listed as being deprecated in their extension appendices, with an explanation of the deprecation and any features that are relevant.
Obsoletion
Occasionally, an extension will be marked as obsolete if a new version of the core API or a new extension is fundamentally incompatible with it. An obsoleted extension must not be used with the extension or core version that obsoleted it.
Extensions that are obsoleted are listed as being obsoleted in their extension appendices, with reference to what they were obsoleted by.
Aliases
When an extension is promoted or deprecated by a newer feature, some or all of its functionality may be replicated into the newer feature. Rather than duplication of all the documentation and definitions, the specification instead identifies the identical commands and types as aliases of one another. Each alias is mentioned together with the definition it aliases, with the older aliases marked as “equivalents”. Each alias of the same command has identical behavior, and each alias of the same type has identical meaning - they can be used interchangeably in an application with no compatibility issues.
|
Note
For promoted types, the aliased extension type is semantically identical to
the new core type.
The C99 headers simply For promoted command aliases, however, there are two separate entry point definitions, due to the fact that the C99 ABI has no way to alias command definitions without resorting to macros. Calling via either entry point definition will produce identical behavior within the bounds of the specification, and should still invoke the same entry point in the implementation. Debug tools may use separate entry points with different debug behavior; to write the appropriate command name to an output log, for instance. |
Special Use Extensions
Some extensions exist only to support a specific purpose or specific class of application. These are referred to as “special use extensions”. Use of these extensions in applications not meeting the special use criteria is not recommended.
Special use cases are restricted, and only those defined below are used to describe extensions:
| Special Use | XML Tag | Full Description |
|---|---|---|
CAD support |
cadsupport |
Extension is intended to support specialized functionality used by CAD/CAM applications. |
D3D support |
d3demulation |
Extension is intended to support D3D emulation layers, and applications ported from D3D, by adding functionality specific to D3D. |
Developer tools |
devtools |
Extension is intended to support developer tools such as capture-replay libraries. |
Debugging tools |
debugging |
Extension is intended for use by applications when debugging. |
OpenGL / ES support |
glemulation |
Extension is intended to support OpenGL and/or OpenGL ES emulation layers, and applications ported from those APIs, by adding functionality specific to those APIs. |
Special use extensions are identified in the metadata for each such extension in the Layers & Extensions appendix, using the name in the “Special Use” column above.
Special use extensions are also identified in vk.xml with the short name
in “XML Tag” column above, as described in the “API Extensions
(extension tag)” section of the registry schema
documentation.
41. Features
Features describe functionality which is not supported on all implementations. Features are properties of the physical device. Features are optional, and must be explicitly enabled before use. Support for features is reported and enabled on a per-feature basis.
|
Note
Features are reported via the basic VkPhysicalDeviceFeatures
structure, as well as the extensible structure
|
For convenience, new core versions of Vulkan may introduce new unified feature structures for features promoted from extensions. At the same time, the extension’s original feature structure (if any) is also promoted to the core API, and is an alias of the extension’s structure. This results in multiple names for the same feature: in the original extension’s feature structure and the promoted structure alias, in the unified feature structure. When a feature was implicitly supported and enabled in the extension, but an explicit name was added during promotion, then the extension itself acts as an alias for the feature as listed in the table below.
All aliases of the same feature in the core API must be reported consistently: either all must be reported as supported, or none of them. When a promoted extension is available, any corresponding feature aliases must be supported.
| Extension | Feature(s) |
|---|---|
To query supported features, call:
// Provided by VK_VERSION_1_0
void vkGetPhysicalDeviceFeatures(
VkPhysicalDevice physicalDevice,
VkPhysicalDeviceFeatures* pFeatures);
-
physicalDeviceis the physical device from which to query the supported features. -
pFeaturesis a pointer to a VkPhysicalDeviceFeatures structure in which the physical device features are returned. For each feature, a value ofVK_TRUEspecifies that the feature is supported on this physical device, andVK_FALSEspecifies that the feature is not supported.
Fine-grained features used by a logical device must be enabled at
VkDevice creation time.
If a feature is enabled that the physical device does not support,
VkDevice creation will fail and return
VK_ERROR_FEATURE_NOT_PRESENT.
The fine-grained features are enabled by passing a pointer to the
VkPhysicalDeviceFeatures structure via the pEnabledFeatures
member of the VkDeviceCreateInfo structure that is passed into the
vkCreateDevice call.
If a member of pEnabledFeatures is set to VK_TRUE or
VK_FALSE, then the device will be created with the indicated feature
enabled or disabled, respectively.
Features can also be enabled by using the VkPhysicalDeviceFeatures2
structure.
If an application wishes to enable all features supported by a device, it
can simply pass in the VkPhysicalDeviceFeatures structure that was
previously returned by vkGetPhysicalDeviceFeatures.
To disable an individual feature, the application can set the desired
member to VK_FALSE in the same structure.
Setting pEnabledFeatures to NULL
and not including a VkPhysicalDeviceFeatures2 in the pNext chain
of VkDeviceCreateInfo
is equivalent to setting all members of the structure to VK_FALSE.
|
Note
Some features, such as |
To query supported features defined by the core or extensions, call:
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceFeatures2(
VkPhysicalDevice physicalDevice,
VkPhysicalDeviceFeatures2* pFeatures);
or the equivalent command
// Provided by VK_KHR_get_physical_device_properties2
void vkGetPhysicalDeviceFeatures2KHR(
VkPhysicalDevice physicalDevice,
VkPhysicalDeviceFeatures2* pFeatures);
-
physicalDeviceis the physical device from which to query the supported features. -
pFeaturesis a pointer to a VkPhysicalDeviceFeatures2 structure in which the physical device features are returned.
Each structure in pFeatures and its pNext chain contains members
corresponding to fine-grained features.
vkGetPhysicalDeviceFeatures2 writes each member to a boolean value
indicating whether that feature is supported.
The VkPhysicalDeviceFeatures2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceFeatures2 {
VkStructureType sType;
void* pNext;
VkPhysicalDeviceFeatures features;
} VkPhysicalDeviceFeatures2;
or the equivalent
// Provided by VK_KHR_get_physical_device_properties2
typedef VkPhysicalDeviceFeatures2 VkPhysicalDeviceFeatures2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
featuresis a VkPhysicalDeviceFeatures structure describing the fine-grained features of the Vulkan 1.0 API.
The pNext chain of this structure is used to extend the structure with
features defined by extensions.
This structure can be used in vkGetPhysicalDeviceFeatures2 or can be
included in the pNext chain of a VkDeviceCreateInfo structure,
in which case it controls which features are enabled in the device in lieu
of pEnabledFeatures.
The VkPhysicalDeviceFeatures structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPhysicalDeviceFeatures {
VkBool32 robustBufferAccess;
VkBool32 fullDrawIndexUint32;
VkBool32 imageCubeArray;
VkBool32 independentBlend;
VkBool32 geometryShader;
VkBool32 tessellationShader;
VkBool32 sampleRateShading;
VkBool32 dualSrcBlend;
VkBool32 logicOp;
VkBool32 multiDrawIndirect;
VkBool32 drawIndirectFirstInstance;
VkBool32 depthClamp;
VkBool32 depthBiasClamp;
VkBool32 fillModeNonSolid;
VkBool32 depthBounds;
VkBool32 wideLines;
VkBool32 largePoints;
VkBool32 alphaToOne;
VkBool32 multiViewport;
VkBool32 samplerAnisotropy;
VkBool32 textureCompressionETC2;
VkBool32 textureCompressionASTC_LDR;
VkBool32 textureCompressionBC;
VkBool32 occlusionQueryPrecise;
VkBool32 pipelineStatisticsQuery;
VkBool32 vertexPipelineStoresAndAtomics;
VkBool32 fragmentStoresAndAtomics;
VkBool32 shaderTessellationAndGeometryPointSize;
VkBool32 shaderImageGatherExtended;
VkBool32 shaderStorageImageExtendedFormats;
VkBool32 shaderStorageImageMultisample;
VkBool32 shaderStorageImageReadWithoutFormat;
VkBool32 shaderStorageImageWriteWithoutFormat;
VkBool32 shaderUniformBufferArrayDynamicIndexing;
VkBool32 shaderSampledImageArrayDynamicIndexing;
VkBool32 shaderStorageBufferArrayDynamicIndexing;
VkBool32 shaderStorageImageArrayDynamicIndexing;
VkBool32 shaderClipDistance;
VkBool32 shaderCullDistance;
VkBool32 shaderFloat64;
VkBool32 shaderInt64;
VkBool32 shaderInt16;
VkBool32 shaderResourceResidency;
VkBool32 shaderResourceMinLod;
VkBool32 sparseBinding;
VkBool32 sparseResidencyBuffer;
VkBool32 sparseResidencyImage2D;
VkBool32 sparseResidencyImage3D;
VkBool32 sparseResidency2Samples;
VkBool32 sparseResidency4Samples;
VkBool32 sparseResidency8Samples;
VkBool32 sparseResidency16Samples;
VkBool32 sparseResidencyAliased;
VkBool32 variableMultisampleRate;
VkBool32 inheritedQueries;
} VkPhysicalDeviceFeatures;
This structure describes the following features:
-
robustBufferAccessspecifies that accesses to buffers are bounds-checked against the range of the buffer descriptor (as determined byVkDescriptorBufferInfo::range, VkBufferViewCreateInfo::range, or the size of the buffer). Out of bounds accesses must not cause application termination, and the effects of shader loads, stores, and atomics must conform to an implementation-dependent behavior as described below.-
A buffer access is considered to be out of bounds if any of the following are true:
-
The pointer was formed by
OpImageTexelPointerand the coordinate is less than zero or greater than or equal to the number of whole elements in the bound range. -
The pointer was not formed by
OpImageTexelPointerand the object pointed to is not wholly contained within the bound range. This includes accesses performed via variable pointers where the buffer descriptor being accessed cannot be statically determined. Uninitialized pointers and pointers equal toOpConstantNullare treated as pointing to a zero-sized object, so all accesses through such pointers are considered to be out of bounds. Buffer accesses through buffer device addresses are not bounds-checked. If thecooperativeMatrixRobustBufferAccessfeature is not enabled, then accesses usingOpCooperativeMatrixLoadNVandOpCooperativeMatrixStoreNVmay not be bounds-checked.NoteIf a SPIR-V
OpLoadinstruction loads a structure and the tail end of the structure is out of bounds, then all members of the structure are considered out of bounds even if the members at the end are not statically used. -
If
robustBufferAccess2is not enabled and any buffer access is determined to be out of bounds, then any other access of the same type (load, store, or atomic) to the same buffer that accesses an address less than 16 bytes away from the out of bounds address may also be considered out of bounds. -
If the access is a load that reads from the same memory locations as a prior store in the same shader invocation, with no other intervening accesses to the same memory locations in that shader invocation, then the result of the load may be the value stored by the store instruction, even if the access is out of bounds. If the load is
Volatile, then an out of bounds load must return the appropriate out of bounds value.
-
-
Accesses to descriptors written with a VK_NULL_HANDLE resource or view are not considered to be out of bounds. Instead, each type of descriptor access defines a specific behavior for accesses to a null descriptor.
-
Out-of-bounds buffer loads will return any of the following values:
-
If the access is to a uniform buffer and
robustBufferAccess2is enabled, loads of offsets between the end of the descriptor range and the end of the descriptor range rounded up to a multiple of robustUniformBufferAccessSizeAlignment bytes must return either zero values or the contents of the memory at the offset being loaded. Loads of offsets past the descriptor range rounded up to a multiple of robustUniformBufferAccessSizeAlignment bytes must return zero values. -
If the access is to a storage buffer and
robustBufferAccess2is enabled, loads of offsets between the end of the descriptor range and the end of the descriptor range rounded up to a multiple of robustStorageBufferAccessSizeAlignment bytes must return either zero values or the contents of the memory at the offset being loaded. Loads of offsets past the descriptor range rounded up to a multiple of robustStorageBufferAccessSizeAlignment bytes must return zero values. Similarly, stores to addresses between the end of the descriptor range and the end of the descriptor range rounded up to a multiple of robustStorageBufferAccessSizeAlignment bytes may be discarded. -
Non-atomic accesses to storage buffers that are a multiple of 32 bits may be decomposed into 32-bit accesses that are individually bounds-checked.
-
If the access is to an index buffer and
robustBufferAccess2is enabled, zero values must be returned. -
If the access is to a uniform texel buffer or storage texel buffer and
robustBufferAccess2is enabled, zero values must be returned, and then Conversion to RGBA is applied based on the buffer view’s format. -
Values from anywhere within the memory range(s) bound to the buffer (possibly including bytes of memory past the end of the buffer, up to the end of the bound range).
-
Zero values, or (0,0,0,x) vectors for vector reads where x is a valid value represented in the type of the vector components and may be any of:
-
0, 1, or the maximum representable positive integer value, for signed or unsigned integer components
-
0.0 or 1.0, for floating-point components
-
-
-
Out-of-bounds writes may modify values within the memory range(s) bound to the buffer, but must not modify any other memory.
-
If
robustBufferAccess2is enabled, out of bounds writes must not modify any memory.
-
-
Out-of-bounds atomics may modify values within the memory range(s) bound to the buffer, but must not modify any other memory, and return an undefined value.
-
If
robustBufferAccess2is enabled, out of bounds atomics must not modify any memory, and return an undefined value.
-
-
If
robustBufferAccess2is disabled, vertex input attributes are considered out of bounds if the offset of the attribute in the bound vertex buffer range plus the size of the attribute is greater than either:-
vertexBufferRangeSize, ifbindingStride== 0; or -
(
vertexBufferRangeSize- (vertexBufferRangeSize%bindingStride))
where
vertexBufferRangeSizeis the byte size of the memory range bound to the vertex buffer binding andbindingStrideis the byte stride of the corresponding vertex input binding. Further, if any vertex input attribute using a specific vertex input binding is out of bounds, then all vertex input attributes using that vertex input binding for that vertex shader invocation are considered out of bounds.-
If a vertex input attribute is out of bounds, it will be assigned one of the following values:
-
Values from anywhere within the memory range(s) bound to the buffer, converted according to the format of the attribute.
-
Zero values, format converted according to the format of the attribute.
-
Zero values, or (0,0,0,x) vectors, as described above.
-
-
-
If
robustBufferAccess2is enabled, vertex input attributes are considered out of bounds if the offset of the attribute in the bound vertex buffer range plus the size of the attribute is greater than the byte size of the memory range bound to the vertex buffer binding.-
If a vertex input attribute is out of bounds, the raw data extracted are zero values, and missing G, B, or A components are filled with (0,0,1).
-
-
If
robustBufferAccessis not enabled, applications must not perform out of bounds accesses except under the conditions enabled by thepipelineRobustnessfeature. .
-
-
fullDrawIndexUint32specifies the full 32-bit range of indices is supported for indexed draw calls when using a VkIndexType ofVK_INDEX_TYPE_UINT32.maxDrawIndexedIndexValueis the maximum index value that may be used (aside from the primitive restart index, which is always 232-1 when the VkIndexType isVK_INDEX_TYPE_UINT32). If this feature is supported,maxDrawIndexedIndexValuemust be 232-1; otherwise it must be no smaller than 224-1. See maxDrawIndexedIndexValue. -
imageCubeArrayspecifies whether image views with a VkImageViewType ofVK_IMAGE_VIEW_TYPE_CUBE_ARRAYcan be created, and that the correspondingSampledCubeArrayandImageCubeArraySPIR-V capabilities can be used in shader code. -
independentBlendspecifies whether theVkPipelineColorBlendAttachmentStatesettings are controlled independently per-attachment. If this feature is not enabled, theVkPipelineColorBlendAttachmentStatesettings for all color attachments must be identical. Otherwise, a differentVkPipelineColorBlendAttachmentStatecan be provided for each bound color attachment. -
geometryShaderspecifies whether geometry shaders are supported. If this feature is not enabled, theVK_SHADER_STAGE_GEOMETRY_BITandVK_PIPELINE_STAGE_GEOMETRY_SHADER_BITenum values must not be used. This also specifies whether shader modules can declare theGeometrycapability. -
tessellationShaderspecifies whether tessellation control and evaluation shaders are supported. If this feature is not enabled, theVK_SHADER_STAGE_TESSELLATION_CONTROL_BIT,VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT,VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT,VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, andVK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_STATE_CREATE_INFOenum values must not be used. This also specifies whether shader modules can declare theTessellationcapability. -
sampleRateShadingspecifies whether Sample Shading and multisample interpolation are supported. If this feature is not enabled, thesampleShadingEnablemember of the VkPipelineMultisampleStateCreateInfo structure must be set toVK_FALSEand theminSampleShadingmember is ignored. This also specifies whether shader modules can declare theSampleRateShadingcapability. -
dualSrcBlendspecifies whether blend operations which take two sources are supported. If this feature is not enabled, theVK_BLEND_FACTOR_SRC1_COLOR,VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR,VK_BLEND_FACTOR_SRC1_ALPHA, andVK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHAenum values must not be used as source or destination blending factors. See Dual-Source Blending. -
logicOpspecifies whether logic operations are supported. If this feature is not enabled, thelogicOpEnablemember of the VkPipelineColorBlendStateCreateInfo structure must be set toVK_FALSE, and thelogicOpmember is ignored. -
multiDrawIndirectspecifies whether multiple draw indirect is supported. If this feature is not enabled, thedrawCountparameter to thevkCmdDrawIndirectandvkCmdDrawIndexedIndirectcommands must be 0 or 1. ThemaxDrawIndirectCountmember of theVkPhysicalDeviceLimitsstructure must also be 1 if this feature is not supported. See maxDrawIndirectCount. -
drawIndirectFirstInstancespecifies whether indirect drawing calls support thefirstInstanceparameter. If this feature is not enabled, thefirstInstancemember of allVkDrawIndirectCommandandVkDrawIndexedIndirectCommandstructures that are provided to thevkCmdDrawIndirectandvkCmdDrawIndexedIndirectcommands must be 0. -
depthClampspecifies whether depth clamping is supported. If this feature is not enabled, thedepthClampEnablemember of the VkPipelineRasterizationStateCreateInfo structure must be set toVK_FALSE. Otherwise, settingdepthClampEnabletoVK_TRUEwill enable depth clamping. -
depthBiasClampspecifies whether depth bias clamping is supported. If this feature is not enabled, thedepthBiasClampmember of the VkPipelineRasterizationStateCreateInfo structure must be set to 0.0 unless theVK_DYNAMIC_STATE_DEPTH_BIASdynamic state is enabled, and thedepthBiasClampparameter tovkCmdSetDepthBiasmust be set to 0.0. -
fillModeNonSolidspecifies whether point and wireframe fill modes are supported. If this feature is not enabled, theVK_POLYGON_MODE_POINTandVK_POLYGON_MODE_LINEenum values must not be used. -
depthBoundsspecifies whether depth bounds tests are supported. If this feature is not enabled, thedepthBoundsTestEnablemember of the VkPipelineDepthStencilStateCreateInfo structure must be set toVK_FALSE. WhendepthBoundsTestEnableis set toVK_FALSE, theminDepthBoundsandmaxDepthBoundsmembers of the VkPipelineDepthStencilStateCreateInfo structure are ignored. -
wideLinesspecifies whether lines with width other than 1.0 are supported. If this feature is not enabled, thelineWidthmember of the VkPipelineRasterizationStateCreateInfo structure must be set to 1.0 unless theVK_DYNAMIC_STATE_LINE_WIDTHdynamic state is enabled, and thelineWidthparameter tovkCmdSetLineWidthmust be set to 1.0. When this feature is supported, the range and granularity of supported line widths are indicated by thelineWidthRangeandlineWidthGranularitymembers of theVkPhysicalDeviceLimitsstructure, respectively. -
largePointsspecifies whether points with size greater than 1.0 are supported. If this feature is not enabled, only a point size of 1.0 written by a shader is supported. The range and granularity of supported point sizes are indicated by thepointSizeRangeandpointSizeGranularitymembers of theVkPhysicalDeviceLimitsstructure, respectively. -
alphaToOnespecifies whether the implementation is able to replace the alpha value of the fragment shader color output in the Multisample Coverage fragment operation. If this feature is not enabled, then thealphaToOneEnablemember of the VkPipelineMultisampleStateCreateInfo structure must be set toVK_FALSE. Otherwise settingalphaToOneEnabletoVK_TRUEwill enable alpha-to-one behavior. -
multiViewportspecifies whether more than one viewport is supported. If this feature is not enabled:-
The
viewportCountandscissorCountmembers of the VkPipelineViewportStateCreateInfo structure must be set to 1. -
The
firstViewportandviewportCountparameters to thevkCmdSetViewportcommand must be set to 0 and 1, respectively. -
The
firstScissorandscissorCountparameters to thevkCmdSetScissorcommand must be set to 0 and 1, respectively. -
The
exclusiveScissorCountmember of the VkPipelineViewportExclusiveScissorStateCreateInfoNV structure must be set to 0 or 1. -
The
firstExclusiveScissorandexclusiveScissorCountparameters to thevkCmdSetExclusiveScissorNVcommand must be set to 0 and 1, respectively.
-
-
samplerAnisotropyspecifies whether anisotropic filtering is supported. If this feature is not enabled, theanisotropyEnablemember of the VkSamplerCreateInfo structure must beVK_FALSE. -
textureCompressionETC2specifies whether all of the ETC2 and EAC compressed texture formats are supported. If this feature is enabled, then theVK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT,VK_FORMAT_FEATURE_BLIT_SRC_BITandVK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BITfeatures must be supported inoptimalTilingFeaturesfor the following formats:-
VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK -
VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK -
VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK -
VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK -
VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK -
VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK -
VK_FORMAT_EAC_R11_UNORM_BLOCK -
VK_FORMAT_EAC_R11_SNORM_BLOCK -
VK_FORMAT_EAC_R11G11_UNORM_BLOCK -
VK_FORMAT_EAC_R11G11_SNORM_BLOCK
To query for additional properties, or if the feature is not enabled, vkGetPhysicalDeviceFormatProperties and vkGetPhysicalDeviceImageFormatProperties can be used to check for supported properties of individual formats as normal.
-
-
textureCompressionASTC_LDRspecifies whether all of the ASTC LDR compressed texture formats are supported. If this feature is enabled, then theVK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT,VK_FORMAT_FEATURE_BLIT_SRC_BITandVK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BITfeatures must be supported inoptimalTilingFeaturesfor the following formats:-
VK_FORMAT_ASTC_4x4_UNORM_BLOCK -
VK_FORMAT_ASTC_4x4_SRGB_BLOCK -
VK_FORMAT_ASTC_5x4_UNORM_BLOCK -
VK_FORMAT_ASTC_5x4_SRGB_BLOCK -
VK_FORMAT_ASTC_5x5_UNORM_BLOCK -
VK_FORMAT_ASTC_5x5_SRGB_BLOCK -
VK_FORMAT_ASTC_6x5_UNORM_BLOCK -
VK_FORMAT_ASTC_6x5_SRGB_BLOCK -
VK_FORMAT_ASTC_6x6_UNORM_BLOCK -
VK_FORMAT_ASTC_6x6_SRGB_BLOCK -
VK_FORMAT_ASTC_8x5_UNORM_BLOCK -
VK_FORMAT_ASTC_8x5_SRGB_BLOCK -
VK_FORMAT_ASTC_8x6_UNORM_BLOCK -
VK_FORMAT_ASTC_8x6_SRGB_BLOCK -
VK_FORMAT_ASTC_8x8_UNORM_BLOCK -
VK_FORMAT_ASTC_8x8_SRGB_BLOCK -
VK_FORMAT_ASTC_10x5_UNORM_BLOCK -
VK_FORMAT_ASTC_10x5_SRGB_BLOCK -
VK_FORMAT_ASTC_10x6_UNORM_BLOCK -
VK_FORMAT_ASTC_10x6_SRGB_BLOCK -
VK_FORMAT_ASTC_10x8_UNORM_BLOCK -
VK_FORMAT_ASTC_10x8_SRGB_BLOCK -
VK_FORMAT_ASTC_10x10_UNORM_BLOCK -
VK_FORMAT_ASTC_10x10_SRGB_BLOCK -
VK_FORMAT_ASTC_12x10_UNORM_BLOCK -
VK_FORMAT_ASTC_12x10_SRGB_BLOCK -
VK_FORMAT_ASTC_12x12_UNORM_BLOCK -
VK_FORMAT_ASTC_12x12_SRGB_BLOCK
To query for additional properties, or if the feature is not enabled, vkGetPhysicalDeviceFormatProperties and vkGetPhysicalDeviceImageFormatProperties can be used to check for supported properties of individual formats as normal.
-
-
textureCompressionBCspecifies whether all of the BC compressed texture formats are supported. If this feature is enabled, then theVK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT,VK_FORMAT_FEATURE_BLIT_SRC_BITandVK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BITfeatures must be supported inoptimalTilingFeaturesfor the following formats:-
VK_FORMAT_BC1_RGB_UNORM_BLOCK -
VK_FORMAT_BC1_RGB_SRGB_BLOCK -
VK_FORMAT_BC1_RGBA_UNORM_BLOCK -
VK_FORMAT_BC1_RGBA_SRGB_BLOCK -
VK_FORMAT_BC2_UNORM_BLOCK -
VK_FORMAT_BC2_SRGB_BLOCK -
VK_FORMAT_BC3_UNORM_BLOCK -
VK_FORMAT_BC3_SRGB_BLOCK -
VK_FORMAT_BC4_UNORM_BLOCK -
VK_FORMAT_BC4_SNORM_BLOCK -
VK_FORMAT_BC5_UNORM_BLOCK -
VK_FORMAT_BC5_SNORM_BLOCK -
VK_FORMAT_BC6H_UFLOAT_BLOCK -
VK_FORMAT_BC6H_SFLOAT_BLOCK -
VK_FORMAT_BC7_UNORM_BLOCK -
VK_FORMAT_BC7_SRGB_BLOCK
To query for additional properties, or if the feature is not enabled, vkGetPhysicalDeviceFormatProperties and vkGetPhysicalDeviceImageFormatProperties can be used to check for supported properties of individual formats as normal.
-
-
occlusionQueryPrecisespecifies whether occlusion queries returning actual sample counts are supported. Occlusion queries are created in aVkQueryPoolby specifying thequeryTypeofVK_QUERY_TYPE_OCCLUSIONin the VkQueryPoolCreateInfo structure which is passed tovkCreateQueryPool. If this feature is enabled, queries of this type can enableVK_QUERY_CONTROL_PRECISE_BITin theflagsparameter tovkCmdBeginQuery. If this feature is not supported, the implementation supports only boolean occlusion queries. When any samples are passed, boolean queries will return a non-zero result value, otherwise a result value of zero is returned. When this feature is enabled andVK_QUERY_CONTROL_PRECISE_BITis set, occlusion queries will report the actual number of samples passed. -
pipelineStatisticsQueryspecifies whether the pipeline statistics queries are supported. If this feature is not enabled, queries of typeVK_QUERY_TYPE_PIPELINE_STATISTICScannot be created, and none of the VkQueryPipelineStatisticFlagBits bits can be set in thepipelineStatisticsmember of the VkQueryPoolCreateInfo structure. -
vertexPipelineStoresAndAtomicsspecifies whether storage buffers and images support stores and atomic operations in the vertex, tessellation, and geometry shader stages. If this feature is not enabled, all storage image, storage texel buffer, and storage buffer variables used by these stages in shader modules must be decorated with theNonWritabledecoration (or thereadonlymemory qualifier in GLSL). -
fragmentStoresAndAtomicsspecifies whether storage buffers and images support stores and atomic operations in the fragment shader stage. If this feature is not enabled, all storage image, storage texel buffer, and storage buffer variables used by the fragment stage in shader modules must be decorated with theNonWritabledecoration (or thereadonlymemory qualifier in GLSL). -
shaderTessellationAndGeometryPointSizespecifies whether thePointSizebuilt-in decoration is available in the tessellation control, tessellation evaluation, and geometry shader stages. If this feature is not enabled, members decorated with thePointSizebuilt-in decoration must not be read from or written to and all points written from a tessellation or geometry shader will have a size of 1.0. This also specifies whether shader modules can declare theTessellationPointSizecapability for tessellation control and evaluation shaders, or if the shader modules can declare theGeometryPointSizecapability for geometry shaders. An implementation supporting this feature must also support one or both of thetessellationShaderorgeometryShaderfeatures. -
shaderImageGatherExtendedspecifies whether the extended set of image gather instructions are available in shader code. If this feature is not enabled, theOpImage*Gatherinstructions do not support theOffsetandConstOffsetsoperands. This also specifies whether shader modules can declare theImageGatherExtendedcapability. -
shaderStorageImageExtendedFormatsspecifies whether all the “storage image extended formats” below are supported; if this feature is supported, then theVK_FORMAT_FEATURE_STORAGE_IMAGE_BITmust be supported inoptimalTilingFeaturesfor the following formats:-
VK_FORMAT_R16G16_SFLOAT -
VK_FORMAT_B10G11R11_UFLOAT_PACK32 -
VK_FORMAT_R16_SFLOAT -
VK_FORMAT_R16G16B16A16_UNORM -
VK_FORMAT_A2B10G10R10_UNORM_PACK32 -
VK_FORMAT_R16G16_UNORM -
VK_FORMAT_R8G8_UNORM -
VK_FORMAT_R16_UNORM -
VK_FORMAT_R8_UNORM -
VK_FORMAT_R16G16B16A16_SNORM -
VK_FORMAT_R16G16_SNORM -
VK_FORMAT_R8G8_SNORM -
VK_FORMAT_R16_SNORM -
VK_FORMAT_R8_SNORM -
VK_FORMAT_R16G16_SINT -
VK_FORMAT_R8G8_SINT -
VK_FORMAT_R16_SINT -
VK_FORMAT_R8_SINT -
VK_FORMAT_A2B10G10R10_UINT_PACK32 -
VK_FORMAT_R16G16_UINT -
VK_FORMAT_R8G8_UINT -
VK_FORMAT_R16_UINT -
VK_FORMAT_R8_UINT
NoteshaderStorageImageExtendedFormatsfeature only adds a guarantee of format support, which is specified for the whole physical device. Therefore enabling or disabling the feature via vkCreateDevice has no practical effect.To query for additional properties, or if the feature is not supported, vkGetPhysicalDeviceFormatProperties and vkGetPhysicalDeviceImageFormatProperties can be used to check for supported properties of individual formats, as usual rules allow.
VK_FORMAT_R32G32_UINT,VK_FORMAT_R32G32_SINT, andVK_FORMAT_R32G32_SFLOATfromStorageImageExtendedFormatsSPIR-V capability, are already covered by core Vulkan mandatory format support. -
-
shaderStorageImageMultisamplespecifies whether multisampled storage images are supported. If this feature is not enabled, images that are created with ausagethat includesVK_IMAGE_USAGE_STORAGE_BITmust be created withsamplesequal toVK_SAMPLE_COUNT_1_BIT. This also specifies whether shader modules can declare theStorageImageMultisampleandImageMSArraycapabilities. -
shaderStorageImageReadWithoutFormatspecifies whether storage images require a format qualifier to be specified when reading.shaderStorageImageReadWithoutFormatapplies only to formats listed in the storage without format list. -
shaderStorageImageWriteWithoutFormatspecifies whether storage images require a format qualifier to be specified when writing.shaderStorageImageWriteWithoutFormatapplies only to formats listed in the storage without format list. -
shaderUniformBufferArrayDynamicIndexingspecifies whether arrays of uniform buffers can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMICmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also specifies whether shader modules can declare theUniformBufferArrayDynamicIndexingcapability. -
shaderSampledImageArrayDynamicIndexingspecifies whether arrays of samplers or sampled images can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_SAMPLER,VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, orVK_DESCRIPTOR_TYPE_SAMPLED_IMAGEmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also specifies whether shader modules can declare theSampledImageArrayDynamicIndexingcapability. -
shaderStorageBufferArrayDynamicIndexingspecifies whether arrays of storage buffers can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMICmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also specifies whether shader modules can declare theStorageBufferArrayDynamicIndexingcapability. -
shaderStorageImageArrayDynamicIndexingspecifies whether arrays of storage images can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_IMAGEmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also specifies whether shader modules can declare theStorageImageArrayDynamicIndexingcapability. -
shaderClipDistancespecifies whether clip distances are supported in shader code. If this feature is not enabled, any members decorated with theClipDistancebuilt-in decoration must not be read from or written to in shader modules. This also specifies whether shader modules can declare theClipDistancecapability. -
shaderCullDistancespecifies whether cull distances are supported in shader code. If this feature is not enabled, any members decorated with theCullDistancebuilt-in decoration must not be read from or written to in shader modules. This also specifies whether shader modules can declare theCullDistancecapability. -
shaderFloat64specifies whether 64-bit floats (doubles) are supported in shader code. If this feature is not enabled, 64-bit floating-point types must not be used in shader code. This also specifies whether shader modules can declare theFloat64capability. Declaring and using 64-bit floats is enabled for all storage classes that SPIR-V allows with theFloat64capability. -
shaderInt64specifies whether 64-bit integers (signed and unsigned) are supported in shader code. If this feature is not enabled, 64-bit integer types must not be used in shader code. This also specifies whether shader modules can declare theInt64capability. Declaring and using 64-bit integers is enabled for all storage classes that SPIR-V allows with theInt64capability. -
shaderInt16specifies whether 16-bit integers (signed and unsigned) are supported in shader code. If this feature is not enabled, 16-bit integer types must not be used in shader code. This also specifies whether shader modules can declare theInt16capability. However, this only enables a subset of the storage classes that SPIR-V allows for theInt16SPIR-V capability: Declaring and using 16-bit integers in thePrivate,Workgroup(for non-Block variables), andFunctionstorage classes is enabled, while declaring them in the interface storage classes (e.g.,UniformConstant,Uniform,StorageBuffer,Input,Output, andPushConstant) is not enabled. -
shaderResourceResidencyspecifies whether image operations that return resource residency information are supported in shader code. If this feature is not enabled, theOpImageSparse*instructions must not be used in shader code. This also specifies whether shader modules can declare theSparseResidencycapability. The feature requires at least one of thesparseResidency*features to be supported. -
shaderResourceMinLodspecifies whether image operations specifying the minimum resource LOD are supported in shader code. If this feature is not enabled, theMinLodimage operand must not be used in shader code. This also specifies whether shader modules can declare theMinLodcapability. -
sparseBindingspecifies whether resource memory can be managed at opaque sparse block level instead of at the object level. If this feature is not enabled, resource memory must be bound only on a per-object basis using thevkBindBufferMemoryandvkBindImageMemorycommands. In this case, buffers and images must not be created withVK_BUFFER_CREATE_SPARSE_BINDING_BITandVK_IMAGE_CREATE_SPARSE_BINDING_BITset in theflagsmember of the VkBufferCreateInfo and VkImageCreateInfo structures, respectively. Otherwise resource memory can be managed as described in Sparse Resource Features. -
sparseResidencyBufferspecifies whether the device can access partially resident buffers. If this feature is not enabled, buffers must not be created withVK_BUFFER_CREATE_SPARSE_RESIDENCY_BITset in theflagsmember of the VkBufferCreateInfo structure. -
sparseResidencyImage2Dspecifies whether the device can access partially resident 2D images with 1 sample per pixel. If this feature is not enabled, images with animageTypeofVK_IMAGE_TYPE_2Dandsamplesset toVK_SAMPLE_COUNT_1_BITmust not be created withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BITset in theflagsmember of the VkImageCreateInfo structure. -
sparseResidencyImage3Dspecifies whether the device can access partially resident 3D images. If this feature is not enabled, images with animageTypeofVK_IMAGE_TYPE_3Dmust not be created withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BITset in theflagsmember of the VkImageCreateInfo structure. -
sparseResidency2Samplesspecifies whether the physical device can access partially resident 2D images with 2 samples per pixel. If this feature is not enabled, images with animageTypeofVK_IMAGE_TYPE_2Dandsamplesset toVK_SAMPLE_COUNT_2_BITmust not be created withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BITset in theflagsmember of the VkImageCreateInfo structure. -
sparseResidency4Samplesspecifies whether the physical device can access partially resident 2D images with 4 samples per pixel. If this feature is not enabled, images with animageTypeofVK_IMAGE_TYPE_2Dandsamplesset toVK_SAMPLE_COUNT_4_BITmust not be created withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BITset in theflagsmember of the VkImageCreateInfo structure. -
sparseResidency8Samplesspecifies whether the physical device can access partially resident 2D images with 8 samples per pixel. If this feature is not enabled, images with animageTypeofVK_IMAGE_TYPE_2Dandsamplesset toVK_SAMPLE_COUNT_8_BITmust not be created withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BITset in theflagsmember of the VkImageCreateInfo structure. -
sparseResidency16Samplesspecifies whether the physical device can access partially resident 2D images with 16 samples per pixel. If this feature is not enabled, images with animageTypeofVK_IMAGE_TYPE_2Dandsamplesset toVK_SAMPLE_COUNT_16_BITmust not be created withVK_IMAGE_CREATE_SPARSE_RESIDENCY_BITset in theflagsmember of the VkImageCreateInfo structure. -
sparseResidencyAliasedspecifies whether the physical device can correctly access data aliased into multiple locations. If this feature is not enabled, theVK_BUFFER_CREATE_SPARSE_ALIASED_BITandVK_IMAGE_CREATE_SPARSE_ALIASED_BITenum values must not be used inflagsmembers of the VkBufferCreateInfo and VkImageCreateInfo structures, respectively. -
variableMultisampleRatespecifies whether all pipelines that will be bound to a command buffer during a subpass which uses no attachments must have the same value for VkPipelineMultisampleStateCreateInfo::rasterizationSamples. If set toVK_TRUE, the implementation supports variable multisample rates in a subpass which uses no attachments. If set toVK_FALSE, then all pipelines bound in such a subpass must have the same multisample rate. This has no effect in situations where a subpass uses any attachments. -
inheritedQueriesspecifies whether a secondary command buffer may be executed while a query is active.
The VkPhysicalDeviceVulkan11Features structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceVulkan11Features {
VkStructureType sType;
void* pNext;
VkBool32 storageBuffer16BitAccess;
VkBool32 uniformAndStorageBuffer16BitAccess;
VkBool32 storagePushConstant16;
VkBool32 storageInputOutput16;
VkBool32 multiview;
VkBool32 multiviewGeometryShader;
VkBool32 multiviewTessellationShader;
VkBool32 variablePointersStorageBuffer;
VkBool32 variablePointers;
VkBool32 protectedMemory;
VkBool32 samplerYcbcrConversion;
VkBool32 shaderDrawParameters;
} VkPhysicalDeviceVulkan11Features;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
storageBuffer16BitAccessspecifies whether objects in theStorageBuffer,ShaderRecordBufferKHR, orPhysicalStorageBufferstorage class with theBlockdecoration can have 16-bit integer and 16-bit floating-point members. If this feature is not enabled, 16-bit integer or 16-bit floating-point members must not be used in such objects. This also specifies whether shader modules can declare theStorageBuffer16BitAccesscapability. -
uniformAndStorageBuffer16BitAccessspecifies whether objects in theUniformstorage class with theBlockdecoration can have 16-bit integer and 16-bit floating-point members. If this feature is not enabled, 16-bit integer or 16-bit floating-point members must not be used in such objects. This also specifies whether shader modules can declare theUniformAndStorageBuffer16BitAccesscapability. -
storagePushConstant16specifies whether objects in thePushConstantstorage class can have 16-bit integer and 16-bit floating-point members. If this feature is not enabled, 16-bit integer or floating-point members must not be used in such objects. This also specifies whether shader modules can declare theStoragePushConstant16capability. -
storageInputOutput16specifies whether objects in theInputandOutputstorage classes can have 16-bit integer and 16-bit floating-point members. If this feature is not enabled, 16-bit integer or 16-bit floating-point members must not be used in such objects. This also specifies whether shader modules can declare theStorageInputOutput16capability. -
multiviewspecifies whether the implementation supports multiview rendering within a render pass. If this feature is not enabled, the view mask of each subpass must always be zero. -
multiviewGeometryShaderspecifies whether the implementation supports multiview rendering within a render pass, with geometry shaders. If this feature is not enabled, then a pipeline compiled against a subpass with a non-zero view mask must not include a geometry shader. -
multiviewTessellationShaderspecifies whether the implementation supports multiview rendering within a render pass, with tessellation shaders. If this feature is not enabled, then a pipeline compiled against a subpass with a non-zero view mask must not include any tessellation shaders. -
variablePointersStorageBufferspecifies whether the implementation supports the SPIR-VVariablePointersStorageBuffercapability. When this feature is not enabled, shader modules must not declare theSPV_KHR_variable_pointersextension or theVariablePointersStorageBuffercapability. -
variablePointersspecifies whether the implementation supports the SPIR-VVariablePointerscapability. When this feature is not enabled, shader modules must not declare theVariablePointerscapability. -
protectedMemoryspecifies whether protected memory is supported. -
samplerYcbcrConversionspecifies whether the implementation supports sampler Y′CBCR conversion. IfsamplerYcbcrConversionisVK_FALSE, sampler Y′CBCR conversion is not supported, and samplers using sampler Y′CBCR conversion must not be used. -
shaderDrawParametersspecifies whether the implementation supports the SPIR-VDrawParameterscapability. When this feature is not enabled, shader modules must not declare theSPV_KHR_shader_draw_parametersextension or theDrawParameterscapability.
If the VkPhysicalDeviceVulkan11Features structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceVulkan11Features can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceVulkan12Features structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceVulkan12Features {
VkStructureType sType;
void* pNext;
VkBool32 samplerMirrorClampToEdge;
VkBool32 drawIndirectCount;
VkBool32 storageBuffer8BitAccess;
VkBool32 uniformAndStorageBuffer8BitAccess;
VkBool32 storagePushConstant8;
VkBool32 shaderBufferInt64Atomics;
VkBool32 shaderSharedInt64Atomics;
VkBool32 shaderFloat16;
VkBool32 shaderInt8;
VkBool32 descriptorIndexing;
VkBool32 shaderInputAttachmentArrayDynamicIndexing;
VkBool32 shaderUniformTexelBufferArrayDynamicIndexing;
VkBool32 shaderStorageTexelBufferArrayDynamicIndexing;
VkBool32 shaderUniformBufferArrayNonUniformIndexing;
VkBool32 shaderSampledImageArrayNonUniformIndexing;
VkBool32 shaderStorageBufferArrayNonUniformIndexing;
VkBool32 shaderStorageImageArrayNonUniformIndexing;
VkBool32 shaderInputAttachmentArrayNonUniformIndexing;
VkBool32 shaderUniformTexelBufferArrayNonUniformIndexing;
VkBool32 shaderStorageTexelBufferArrayNonUniformIndexing;
VkBool32 descriptorBindingUniformBufferUpdateAfterBind;
VkBool32 descriptorBindingSampledImageUpdateAfterBind;
VkBool32 descriptorBindingStorageImageUpdateAfterBind;
VkBool32 descriptorBindingStorageBufferUpdateAfterBind;
VkBool32 descriptorBindingUniformTexelBufferUpdateAfterBind;
VkBool32 descriptorBindingStorageTexelBufferUpdateAfterBind;
VkBool32 descriptorBindingUpdateUnusedWhilePending;
VkBool32 descriptorBindingPartiallyBound;
VkBool32 descriptorBindingVariableDescriptorCount;
VkBool32 runtimeDescriptorArray;
VkBool32 samplerFilterMinmax;
VkBool32 scalarBlockLayout;
VkBool32 imagelessFramebuffer;
VkBool32 uniformBufferStandardLayout;
VkBool32 shaderSubgroupExtendedTypes;
VkBool32 separateDepthStencilLayouts;
VkBool32 hostQueryReset;
VkBool32 timelineSemaphore;
VkBool32 bufferDeviceAddress;
VkBool32 bufferDeviceAddressCaptureReplay;
VkBool32 bufferDeviceAddressMultiDevice;
VkBool32 vulkanMemoryModel;
VkBool32 vulkanMemoryModelDeviceScope;
VkBool32 vulkanMemoryModelAvailabilityVisibilityChains;
VkBool32 shaderOutputViewportIndex;
VkBool32 shaderOutputLayer;
VkBool32 subgroupBroadcastDynamicId;
} VkPhysicalDeviceVulkan12Features;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
samplerMirrorClampToEdgeindicates whether the implementation supports theVK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGEsampler address mode. If this feature is not enabled, theVK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGEsampler address mode must not be used. -
drawIndirectCountindicates whether the implementation supports the vkCmdDrawIndirectCount and vkCmdDrawIndexedIndirectCount functions. If this feature is not enabled, these functions must not be used. -
storageBuffer8BitAccessindicates whether objects in theStorageBuffer,ShaderRecordBufferKHR, orPhysicalStorageBufferstorage class with theBlockdecoration can have 8-bit integer members. If this feature is not enabled, 8-bit integer members must not be used in such objects. This also indicates whether shader modules can declare theStorageBuffer8BitAccesscapability. -
uniformAndStorageBuffer8BitAccessindicates whether objects in theUniformstorage class with theBlockdecoration can have 8-bit integer members. If this feature is not enabled, 8-bit integer members must not be used in such objects. This also indicates whether shader modules can declare theUniformAndStorageBuffer8BitAccesscapability. -
storagePushConstant8indicates whether objects in thePushConstantstorage class can have 8-bit integer members. If this feature is not enabled, 8-bit integer members must not be used in such objects. This also indicates whether shader modules can declare theStoragePushConstant8capability. -
shaderBufferInt64Atomicsindicates whether shaders can perform 64-bit unsigned and signed integer atomic operations on buffers. -
shaderSharedInt64Atomicsindicates whether shaders can perform 64-bit unsigned and signed integer atomic operations on shared memory. -
shaderFloat16indicates whether 16-bit floats (halfs) are supported in shader code. This also indicates whether shader modules can declare theFloat16capability. However, this only enables a subset of the storage classes that SPIR-V allows for theFloat16SPIR-V capability: Declaring and using 16-bit floats in thePrivate,Workgroup(for non-Block variables), andFunctionstorage classes is enabled, while declaring them in the interface storage classes (e.g.,UniformConstant,Uniform,StorageBuffer,Input,Output, andPushConstant) is not enabled. -
shaderInt8indicates whether 8-bit integers (signed and unsigned) are supported in shader code. This also indicates whether shader modules can declare theInt8capability. However, this only enables a subset of the storage classes that SPIR-V allows for theInt8SPIR-V capability: Declaring and using 8-bit integers in thePrivate,Workgroup(for non-Block variables), andFunctionstorage classes is enabled, while declaring them in the interface storage classes (e.g.,UniformConstant,Uniform,StorageBuffer,Input,Output, andPushConstant) is not enabled. -
descriptorIndexingindicates whether the implementation supports the minimum set of descriptor indexing features as described in the Feature Requirements section. Enabling thedescriptorIndexingmember when vkCreateDevice is called does not imply the other minimum descriptor indexing features are also enabled. Those other descriptor indexing features must be enabled individually as needed by the application. -
shaderInputAttachmentArrayDynamicIndexingindicates whether arrays of input attachments can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theInputAttachmentArrayDynamicIndexingcapability. -
shaderUniformTexelBufferArrayDynamicIndexingindicates whether arrays of uniform texel buffers can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theUniformTexelBufferArrayDynamicIndexingcapability. -
shaderStorageTexelBufferArrayDynamicIndexingindicates whether arrays of storage texel buffers can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageTexelBufferArrayDynamicIndexingcapability. -
shaderUniformBufferArrayNonUniformIndexingindicates whether arrays of uniform buffers can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMICmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theUniformBufferArrayNonUniformIndexingcapability. -
shaderSampledImageArrayNonUniformIndexingindicates whether arrays of samplers or sampled images can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_SAMPLER,VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, orVK_DESCRIPTOR_TYPE_SAMPLED_IMAGEmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theSampledImageArrayNonUniformIndexingcapability. -
shaderStorageBufferArrayNonUniformIndexingindicates whether arrays of storage buffers can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMICmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageBufferArrayNonUniformIndexingcapability. -
shaderStorageImageArrayNonUniformIndexingindicates whether arrays of storage images can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_IMAGEmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageImageArrayNonUniformIndexingcapability. -
shaderInputAttachmentArrayNonUniformIndexingindicates whether arrays of input attachments can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theInputAttachmentArrayNonUniformIndexingcapability. -
shaderUniformTexelBufferArrayNonUniformIndexingindicates whether arrays of uniform texel buffers can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theUniformTexelBufferArrayNonUniformIndexingcapability. -
shaderStorageTexelBufferArrayNonUniformIndexingindicates whether arrays of storage texel buffers can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageTexelBufferArrayNonUniformIndexingcapability. -
descriptorBindingUniformBufferUpdateAfterBindindicates whether the implementation supports updating uniform buffer descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER. -
descriptorBindingSampledImageUpdateAfterBindindicates whether the implementation supports updating sampled image descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_SAMPLER,VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, orVK_DESCRIPTOR_TYPE_SAMPLED_IMAGE. -
descriptorBindingStorageImageUpdateAfterBindindicates whether the implementation supports updating storage image descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_STORAGE_IMAGE. -
descriptorBindingStorageBufferUpdateAfterBindindicates whether the implementation supports updating storage buffer descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_STORAGE_BUFFER. -
descriptorBindingUniformTexelBufferUpdateAfterBindindicates whether the implementation supports updating uniform texel buffer descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER. -
descriptorBindingStorageTexelBufferUpdateAfterBindindicates whether the implementation supports updating storage texel buffer descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER. -
descriptorBindingUpdateUnusedWhilePendingindicates whether the implementation supports updating descriptors while the set is in use. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BITmust not be used. -
descriptorBindingPartiallyBoundindicates whether the implementation supports statically using a descriptor set binding in which some descriptors are not valid. If this feature is not enabled,VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BITmust not be used. -
descriptorBindingVariableDescriptorCountindicates whether the implementation supports descriptor sets with a variable-sized last binding. If this feature is not enabled,VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BITmust not be used. -
runtimeDescriptorArrayindicates whether the implementation supports the SPIR-VRuntimeDescriptorArraycapability. If this feature is not enabled, descriptors must not be declared in runtime arrays. -
samplerFilterMinmaxindicates whether the implementation supports a minimum set of required formats supporting min/max filtering as defined by thefilterMinmaxSingleComponentFormatsproperty minimum requirements. If this feature is not enabled, then VkSamplerReductionModeCreateInfo must only useVK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE. -
scalarBlockLayoutindicates that the implementation supports the layout of resource blocks in shaders using scalar alignment. -
imagelessFramebufferindicates that the implementation supports specifying the image view for attachments at render pass begin time via VkRenderPassAttachmentBeginInfo. -
uniformBufferStandardLayoutindicates that the implementation supports the same layouts for uniform buffers as for storage and other kinds of buffers. See Standard Buffer Layout. -
shaderSubgroupExtendedTypesis a boolean specifying whether subgroup operations can use 8-bit integer, 16-bit integer, 64-bit integer, 16-bit floating-point, and vectors of these types in group operations with subgroup scope, if the implementation supports the types. -
separateDepthStencilLayoutsindicates whether the implementation supports aVkImageMemoryBarrierfor a depth/stencil image with only one ofVK_IMAGE_ASPECT_DEPTH_BITorVK_IMAGE_ASPECT_STENCIL_BITset, and whetherVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL,VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL,VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, orVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMALcan be used. -
hostQueryResetindicates that the implementation supports resetting queries from the host with vkResetQueryPool. -
timelineSemaphoreindicates whether semaphores created with a VkSemaphoreType ofVK_SEMAPHORE_TYPE_TIMELINEare supported. -
bufferDeviceAddressindicates that the implementation supports accessing buffer memory in shaders as storage buffers via an address queried from vkGetBufferDeviceAddress. -
bufferDeviceAddressCaptureReplayindicates that the implementation supports saving and reusing buffer and device addresses, e.g. for trace capture and replay. -
bufferDeviceAddressMultiDeviceindicates that the implementation supports thebufferDeviceAddress,rayTracingPipelineandrayQueryfeatures for logical devices created with multiple physical devices. If this feature is not supported, buffer and acceleration structure addresses must not be queried on a logical device created with more than one physical device. -
vulkanMemoryModelindicates whether the Vulkan Memory Model is supported, as defined in Vulkan Memory Model. This also indicates whether shader modules can declare theVulkanMemoryModelcapability. -
vulkanMemoryModelDeviceScopeindicates whether the Vulkan Memory Model can useDevicescope synchronization. This also indicates whether shader modules can declare theVulkanMemoryModelDeviceScopecapability. -
vulkanMemoryModelAvailabilityVisibilityChainsindicates whether the Vulkan Memory Model can use availability and visibility chains with more than one element. -
shaderOutputViewportIndexindicates whether the implementation supports theShaderViewportIndexSPIR-V capability enabling variables decorated with theViewportIndexbuilt-in to be exported from vertex or tessellation evaluation shaders. If this feature is not enabled, theViewportIndexbuilt-in decoration must not be used on outputs in vertex or tessellation evaluation shaders. -
shaderOutputLayerindicates whether the implementation supports theShaderLayerSPIR-V capability enabling variables decorated with theLayerbuilt-in to be exported from vertex or tessellation evaluation shaders. If this feature is not enabled, theLayerbuilt-in decoration must not be used on outputs in vertex or tessellation evaluation shaders. -
If
subgroupBroadcastDynamicIdisVK_TRUE, the “Id” operand ofOpGroupNonUniformBroadcastcan be dynamically uniform within a subgroup, and the “Index” operand ofOpGroupNonUniformQuadBroadcastcan be dynamically uniform within the derivative group. If it isVK_FALSE, these operands must be constants.
If the VkPhysicalDeviceVulkan12Features structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceVulkan12Features can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceVulkan13Features structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceVulkan13Features {
VkStructureType sType;
void* pNext;
VkBool32 robustImageAccess;
VkBool32 inlineUniformBlock;
VkBool32 descriptorBindingInlineUniformBlockUpdateAfterBind;
VkBool32 pipelineCreationCacheControl;
VkBool32 privateData;
VkBool32 shaderDemoteToHelperInvocation;
VkBool32 shaderTerminateInvocation;
VkBool32 subgroupSizeControl;
VkBool32 computeFullSubgroups;
VkBool32 synchronization2;
VkBool32 textureCompressionASTC_HDR;
VkBool32 shaderZeroInitializeWorkgroupMemory;
VkBool32 dynamicRendering;
VkBool32 shaderIntegerDotProduct;
VkBool32 maintenance4;
} VkPhysicalDeviceVulkan13Features;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
robustImageAccessindicates whether image accesses are tightly bounds-checked against the dimensions of the image view. Invalid texels resulting from out of bounds image loads will be replaced as described in Texel Replacement, with either (0,0,1) or (0,0,0) values inserted for missing G, B, or A components based on the format. -
inlineUniformBlockindicates whether the implementation supports inline uniform block descriptors. If this feature is not enabled,VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKmust not be used. -
descriptorBindingInlineUniformBlockUpdateAfterBindindicates whether the implementation supports updating inline uniform block descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK. -
pipelineCreationCacheControlindicates that the implementation supports:-
The following can be used in
Vk*PipelineCreateInfo::flags:-
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT -
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT
-
-
The following can be used in VkPipelineCacheCreateInfo::
flags:-
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT
-
-
-
privateDataindicates whether the implementation supports private data. See Private Data. -
shaderDemoteToHelperInvocationindicates whether the implementation supports the SPIR-VDemoteToHelperInvocationEXTcapability. -
shaderTerminateInvocationspecifies whether the implementation supports SPIR-V modules that use theSPV_KHR_terminate_invocationextension. -
subgroupSizeControlindicates whether the implementation supports controlling shader subgroup sizes via theVK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BITflag and the VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure. -
computeFullSubgroupsindicates whether the implementation supports requiring full subgroups in compute shaders via theVK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BITflag. -
synchronization2indicates whether the implementation supports the new set of synchronization commands introduced inVK_KHR_synchronization2. -
textureCompressionASTC_HDRindicates whether all of the ASTC HDR compressed texture formats are supported. If this feature is enabled, then theVK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT,VK_FORMAT_FEATURE_BLIT_SRC_BITandVK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BITfeatures must be supported inoptimalTilingFeaturesfor the following formats:-
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK -
VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK -
VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK -
VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK -
VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK -
VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK -
VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK
To query for additional properties, or if the feature is not enabled, vkGetPhysicalDeviceFormatProperties and vkGetPhysicalDeviceImageFormatProperties can be used to check for supported properties of individual formats as normal.
-
-
shaderZeroInitializeWorkgroupMemoryspecifies whether the implementation supports initializing a variable in Workgroup storage class. -
dynamicRenderingspecifies that the implementation supports dynamic render pass instances using the vkCmdBeginRendering command. -
shaderIntegerDotProductspecifies whether shader modules can declare theDotProductInputAllKHR,DotProductInput4x8BitKHR,DotProductInput4x8BitPackedKHRandDotProductKHRcapabilities. -
maintenance4indicates that the implementation supports the following:-
The application may destroy a VkPipelineLayout object immediately after using it to create another object.
-
LocalSizeIdcan be used as an alternative toLocalSizeto specify the local workgroup size with specialization constants. -
Images created with identical creation parameters will always have the same alignment requirements.
-
The size memory requirement of a buffer or image is never greater than that of another buffer or image created with a greater or equal size.
-
Push constants do not have to be initialized before they are dynamically accessed.
-
The interface matching rules allow a larger output vector to match with a smaller input vector, with additional values being discarded.
-
If the VkPhysicalDeviceVulkan13Features structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceVulkan13Features can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceVariablePointersFeatures structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceVariablePointersFeatures {
VkStructureType sType;
void* pNext;
VkBool32 variablePointersStorageBuffer;
VkBool32 variablePointers;
} VkPhysicalDeviceVariablePointersFeatures;
// Provided by VK_VERSION_1_1
typedef VkPhysicalDeviceVariablePointersFeatures VkPhysicalDeviceVariablePointerFeatures;
or the equivalent
// Provided by VK_KHR_variable_pointers
typedef VkPhysicalDeviceVariablePointersFeatures VkPhysicalDeviceVariablePointersFeaturesKHR;
// Provided by VK_KHR_variable_pointers
typedef VkPhysicalDeviceVariablePointersFeatures VkPhysicalDeviceVariablePointerFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
variablePointersStorageBufferspecifies whether the implementation supports the SPIR-VVariablePointersStorageBuffercapability. When this feature is not enabled, shader modules must not declare theSPV_KHR_variable_pointersextension or theVariablePointersStorageBuffercapability. -
variablePointersspecifies whether the implementation supports the SPIR-VVariablePointerscapability. When this feature is not enabled, shader modules must not declare theVariablePointerscapability.
If the VkPhysicalDeviceVariablePointersFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceVariablePointersFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceMultiviewFeatures structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceMultiviewFeatures {
VkStructureType sType;
void* pNext;
VkBool32 multiview;
VkBool32 multiviewGeometryShader;
VkBool32 multiviewTessellationShader;
} VkPhysicalDeviceMultiviewFeatures;
or the equivalent
// Provided by VK_KHR_multiview
typedef VkPhysicalDeviceMultiviewFeatures VkPhysicalDeviceMultiviewFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
multiviewspecifies whether the implementation supports multiview rendering within a render pass. If this feature is not enabled, the view mask of each subpass must always be zero. -
multiviewGeometryShaderspecifies whether the implementation supports multiview rendering within a render pass, with geometry shaders. If this feature is not enabled, then a pipeline compiled against a subpass with a non-zero view mask must not include a geometry shader. -
multiviewTessellationShaderspecifies whether the implementation supports multiview rendering within a render pass, with tessellation shaders. If this feature is not enabled, then a pipeline compiled against a subpass with a non-zero view mask must not include any tessellation shaders.
If the VkPhysicalDeviceMultiviewFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceMultiviewFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderAtomicFloatFeaturesEXT structure is defined as:
// Provided by VK_EXT_shader_atomic_float
typedef struct VkPhysicalDeviceShaderAtomicFloatFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 shaderBufferFloat32Atomics;
VkBool32 shaderBufferFloat32AtomicAdd;
VkBool32 shaderBufferFloat64Atomics;
VkBool32 shaderBufferFloat64AtomicAdd;
VkBool32 shaderSharedFloat32Atomics;
VkBool32 shaderSharedFloat32AtomicAdd;
VkBool32 shaderSharedFloat64Atomics;
VkBool32 shaderSharedFloat64AtomicAdd;
VkBool32 shaderImageFloat32Atomics;
VkBool32 shaderImageFloat32AtomicAdd;
VkBool32 sparseImageFloat32Atomics;
VkBool32 sparseImageFloat32AtomicAdd;
} VkPhysicalDeviceShaderAtomicFloatFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
shaderBufferFloat32Atomicsindicates whether shaders can perform 32-bit floating-point load, store and exchange atomic operations on storage buffers. -
shaderBufferFloat32AtomicAddindicates whether shaders can perform 32-bit floating-point add atomic operations on storage buffers. -
shaderBufferFloat64Atomicsindicates whether shaders can perform 64-bit floating-point load, store and exchange atomic operations on storage buffers. -
shaderBufferFloat64AtomicAddindicates whether shaders can perform 64-bit floating-point add atomic operations on storage buffers. -
shaderSharedFloat32Atomicsindicates whether shaders can perform 32-bit floating-point load, store and exchange atomic operations on shared memory. -
shaderSharedFloat32AtomicAddindicates whether shaders can perform 32-bit floating-point add atomic operations on shared memory. -
shaderSharedFloat64Atomicsindicates whether shaders can perform 64-bit floating-point load, store and exchange atomic operations on shared memory. -
shaderSharedFloat64AtomicAddindicates whether shaders can perform 64-bit floating-point add atomic operations on shared memory. -
shaderImageFloat32Atomicsindicates whether shaders can perform 32-bit floating-point load, store and exchange atomic image operations. -
shaderImageFloat32AtomicAddindicates whether shaders can perform 32-bit floating-point add atomic image operations. -
sparseImageFloat32Atomicsindicates whether 32-bit floating-point load, store and exchange atomic operations can be used on sparse images. -
sparseImageFloat32AtomicAddindicates whether 32-bit floating-point add atomic operations can be used on sparse images.
If the VkPhysicalDeviceShaderAtomicFloatFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderAtomicFloatFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderAtomicFloat2FeaturesEXT structure is defined as:
// Provided by VK_EXT_shader_atomic_float2
typedef struct VkPhysicalDeviceShaderAtomicFloat2FeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 shaderBufferFloat16Atomics;
VkBool32 shaderBufferFloat16AtomicAdd;
VkBool32 shaderBufferFloat16AtomicMinMax;
VkBool32 shaderBufferFloat32AtomicMinMax;
VkBool32 shaderBufferFloat64AtomicMinMax;
VkBool32 shaderSharedFloat16Atomics;
VkBool32 shaderSharedFloat16AtomicAdd;
VkBool32 shaderSharedFloat16AtomicMinMax;
VkBool32 shaderSharedFloat32AtomicMinMax;
VkBool32 shaderSharedFloat64AtomicMinMax;
VkBool32 shaderImageFloat32AtomicMinMax;
VkBool32 sparseImageFloat32AtomicMinMax;
} VkPhysicalDeviceShaderAtomicFloat2FeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
shaderBufferFloat16Atomicsindicates whether shaders can perform 16-bit floating-point load, store, and exchange atomic operations on storage buffers. -
shaderBufferFloat16AtomicAddindicates whether shaders can perform 16-bit floating-point add atomic operations on storage buffers. -
shaderBufferFloat16AtomicMinMaxindicates whether shaders can perform 16-bit floating-point min and max atomic operations on storage buffers. -
shaderBufferFloat32AtomicMinMaxindicates whether shaders can perform 32-bit floating-point min and max atomic operations on storage buffers. -
shaderBufferFloat64AtomicMinMaxindicates whether shaders can perform 64-bit floating-point min and max atomic operations on storage buffers. -
shaderSharedFloat16Atomicsindicates whether shaders can perform 16-bit floating-point load, store and exchange atomic operations on shared memory. -
shaderSharedFloat16AtomicAddindicates whether shaders can perform 16-bit floating-point add atomic operations on shared memory. -
shaderSharedFloat16AtomicMinMaxindicates whether shaders can perform 16-bit floating-point min and max atomic operations on shared memory. -
shaderSharedFloat32AtomicMinMaxindicates whether shaders can perform 32-bit floating-point min and max atomic operations on shared memory. -
shaderSharedFloat64AtomicMinMaxindicates whether shaders can perform 64-bit floating-point min and max atomic operations on shared memory. -
shaderImageFloat32AtomicMinMaxindicates whether shaders can perform 32-bit floating-point min and max atomic image operations. -
sparseImageFloat32AtomicMinMaxindicates whether 32-bit floating-point min and max atomic operations can be used on sparse images.
If the VkPhysicalDeviceShaderAtomicFloat2FeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderAtomicFloat2FeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderAtomicInt64Features structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceShaderAtomicInt64Features {
VkStructureType sType;
void* pNext;
VkBool32 shaderBufferInt64Atomics;
VkBool32 shaderSharedInt64Atomics;
} VkPhysicalDeviceShaderAtomicInt64Features;
or the equivalent
// Provided by VK_KHR_shader_atomic_int64
typedef VkPhysicalDeviceShaderAtomicInt64Features VkPhysicalDeviceShaderAtomicInt64FeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceShaderAtomicInt64Features structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderAtomicInt64Features can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderImageAtomicInt64FeaturesEXT structure is defined as:
// Provided by VK_EXT_shader_image_atomic_int64
typedef struct VkPhysicalDeviceShaderImageAtomicInt64FeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 shaderImageInt64Atomics;
VkBool32 sparseImageInt64Atomics;
} VkPhysicalDeviceShaderImageAtomicInt64FeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderImageInt64Atomicsindicates whether shaders can support 64-bit unsigned and signed integer atomic operations on images. -
sparseImageInt64Atomicsindicates whether 64-bit integer atomics can be used on sparse images.
If the VkPhysicalDeviceShaderAtomicInt64FeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderAtomicInt64FeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevice8BitStorageFeatures structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDevice8BitStorageFeatures {
VkStructureType sType;
void* pNext;
VkBool32 storageBuffer8BitAccess;
VkBool32 uniformAndStorageBuffer8BitAccess;
VkBool32 storagePushConstant8;
} VkPhysicalDevice8BitStorageFeatures;
or the equivalent
// Provided by VK_KHR_8bit_storage
typedef VkPhysicalDevice8BitStorageFeatures VkPhysicalDevice8BitStorageFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
storageBuffer8BitAccessindicates whether objects in theStorageBuffer,ShaderRecordBufferKHR, orPhysicalStorageBufferstorage class with theBlockdecoration can have 8-bit integer members. If this feature is not enabled, 8-bit integer members must not be used in such objects. This also indicates whether shader modules can declare theStorageBuffer8BitAccesscapability. -
uniformAndStorageBuffer8BitAccessindicates whether objects in theUniformstorage class with theBlockdecoration can have 8-bit integer members. If this feature is not enabled, 8-bit integer members must not be used in such objects. This also indicates whether shader modules can declare theUniformAndStorageBuffer8BitAccesscapability. -
storagePushConstant8indicates whether objects in thePushConstantstorage class can have 8-bit integer members. If this feature is not enabled, 8-bit integer members must not be used in such objects. This also indicates whether shader modules can declare theStoragePushConstant8capability.
If the VkPhysicalDevice8BitStorageFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevice8BitStorageFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevice16BitStorageFeatures structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDevice16BitStorageFeatures {
VkStructureType sType;
void* pNext;
VkBool32 storageBuffer16BitAccess;
VkBool32 uniformAndStorageBuffer16BitAccess;
VkBool32 storagePushConstant16;
VkBool32 storageInputOutput16;
} VkPhysicalDevice16BitStorageFeatures;
or the equivalent
// Provided by VK_KHR_16bit_storage
typedef VkPhysicalDevice16BitStorageFeatures VkPhysicalDevice16BitStorageFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
storageBuffer16BitAccessspecifies whether objects in theStorageBuffer,ShaderRecordBufferKHR, orPhysicalStorageBufferstorage class with theBlockdecoration can have 16-bit integer and 16-bit floating-point members. If this feature is not enabled, 16-bit integer or 16-bit floating-point members must not be used in such objects. This also specifies whether shader modules can declare theStorageBuffer16BitAccesscapability. -
uniformAndStorageBuffer16BitAccessspecifies whether objects in theUniformstorage class with theBlockdecoration can have 16-bit integer and 16-bit floating-point members. If this feature is not enabled, 16-bit integer or 16-bit floating-point members must not be used in such objects. This also specifies whether shader modules can declare theUniformAndStorageBuffer16BitAccesscapability. -
storagePushConstant16specifies whether objects in thePushConstantstorage class can have 16-bit integer and 16-bit floating-point members. If this feature is not enabled, 16-bit integer or floating-point members must not be used in such objects. This also specifies whether shader modules can declare theStoragePushConstant16capability. -
storageInputOutput16specifies whether objects in theInputandOutputstorage classes can have 16-bit integer and 16-bit floating-point members. If this feature is not enabled, 16-bit integer or 16-bit floating-point members must not be used in such objects. This also specifies whether shader modules can declare theStorageInputOutput16capability.
If the VkPhysicalDevice16BitStorageFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevice16BitStorageFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderFloat16Int8Features structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceShaderFloat16Int8Features {
VkStructureType sType;
void* pNext;
VkBool32 shaderFloat16;
VkBool32 shaderInt8;
} VkPhysicalDeviceShaderFloat16Int8Features;
or the equivalent
// Provided by VK_KHR_shader_float16_int8
typedef VkPhysicalDeviceShaderFloat16Int8Features VkPhysicalDeviceShaderFloat16Int8FeaturesKHR;
// Provided by VK_KHR_shader_float16_int8
typedef VkPhysicalDeviceShaderFloat16Int8Features VkPhysicalDeviceFloat16Int8FeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
shaderFloat16indicates whether 16-bit floats (halfs) are supported in shader code. This also indicates whether shader modules can declare theFloat16capability. However, this only enables a subset of the storage classes that SPIR-V allows for theFloat16SPIR-V capability: Declaring and using 16-bit floats in thePrivate,Workgroup(for non-Block variables), andFunctionstorage classes is enabled, while declaring them in the interface storage classes (e.g.,UniformConstant,Uniform,StorageBuffer,Input,Output, andPushConstant) is not enabled. -
shaderInt8indicates whether 8-bit integers (signed and unsigned) are supported in shader code. This also indicates whether shader modules can declare theInt8capability. However, this only enables a subset of the storage classes that SPIR-V allows for theInt8SPIR-V capability: Declaring and using 8-bit integers in thePrivate,Workgroup(for non-Block variables), andFunctionstorage classes is enabled, while declaring them in the interface storage classes (e.g.,UniformConstant,Uniform,StorageBuffer,Input,Output, andPushConstant) is not enabled.
If the VkPhysicalDeviceShaderFloat16Int8Features structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderFloat16Int8Features can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderClockFeaturesKHR structure is defined as:
// Provided by VK_KHR_shader_clock
typedef struct VkPhysicalDeviceShaderClockFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 shaderSubgroupClock;
VkBool32 shaderDeviceClock;
} VkPhysicalDeviceShaderClockFeaturesKHR;
This structure describes the following features:
If the VkPhysicalDeviceShaderClockFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderClockFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceSamplerYcbcrConversionFeatures structure is
defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceSamplerYcbcrConversionFeatures {
VkStructureType sType;
void* pNext;
VkBool32 samplerYcbcrConversion;
} VkPhysicalDeviceSamplerYcbcrConversionFeatures;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkPhysicalDeviceSamplerYcbcrConversionFeatures VkPhysicalDeviceSamplerYcbcrConversionFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
samplerYcbcrConversionspecifies whether the implementation supports sampler Y′CBCR conversion. IfsamplerYcbcrConversionisVK_FALSE, sampler Y′CBCR conversion is not supported, and samplers using sampler Y′CBCR conversion must not be used.
If the VkPhysicalDeviceSamplerYcbcrConversionFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceSamplerYcbcrConversionFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceProtectedMemoryFeatures structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceProtectedMemoryFeatures {
VkStructureType sType;
void* pNext;
VkBool32 protectedMemory;
} VkPhysicalDeviceProtectedMemoryFeatures;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
protectedMemoryspecifies whether protected memory is supported.
If the VkPhysicalDeviceProtectedMemoryFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceProtectedMemoryFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT structure is
defined as:
// Provided by VK_EXT_blend_operation_advanced
typedef struct VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 advancedBlendCoherentOperations;
} VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
advancedBlendCoherentOperationsspecifies whether blending using advanced blend operations is guaranteed to execute atomically and in primitive order. If this isVK_TRUE,VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXTis treated the same asVK_ACCESS_COLOR_ATTACHMENT_READ_BIT, and advanced blending needs no additional synchronization over basic blending. If this isVK_FALSE, then memory dependencies are required to guarantee order between two advanced blending operations that occur on the same sample.
If the VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceConditionalRenderingFeaturesEXT structure is
defined as:
// Provided by VK_EXT_conditional_rendering
typedef struct VkPhysicalDeviceConditionalRenderingFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 conditionalRendering;
VkBool32 inheritedConditionalRendering;
} VkPhysicalDeviceConditionalRenderingFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
conditionalRenderingspecifies whether conditional rendering is supported. -
inheritedConditionalRenderingspecifies whether a secondary command buffer can be executed while conditional rendering is active in the primary command buffer.
If the VkPhysicalDeviceConditionalRenderingFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceConditionalRenderingFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderDrawParametersFeatures structure is defined
as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceShaderDrawParametersFeatures {
VkStructureType sType;
void* pNext;
VkBool32 shaderDrawParameters;
} VkPhysicalDeviceShaderDrawParametersFeatures;
// Provided by VK_VERSION_1_1
typedef VkPhysicalDeviceShaderDrawParametersFeatures VkPhysicalDeviceShaderDrawParameterFeatures;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceShaderDrawParametersFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderDrawParametersFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceMeshShaderFeaturesNV structure is defined as:
// Provided by VK_NV_mesh_shader
typedef struct VkPhysicalDeviceMeshShaderFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 taskShader;
VkBool32 meshShader;
} VkPhysicalDeviceMeshShaderFeaturesNV;
This structure describes the following features:
If the VkPhysicalDeviceMeshShaderFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceMeshShaderFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceDescriptorIndexingFeatures structure is defined
as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceDescriptorIndexingFeatures {
VkStructureType sType;
void* pNext;
VkBool32 shaderInputAttachmentArrayDynamicIndexing;
VkBool32 shaderUniformTexelBufferArrayDynamicIndexing;
VkBool32 shaderStorageTexelBufferArrayDynamicIndexing;
VkBool32 shaderUniformBufferArrayNonUniformIndexing;
VkBool32 shaderSampledImageArrayNonUniformIndexing;
VkBool32 shaderStorageBufferArrayNonUniformIndexing;
VkBool32 shaderStorageImageArrayNonUniformIndexing;
VkBool32 shaderInputAttachmentArrayNonUniformIndexing;
VkBool32 shaderUniformTexelBufferArrayNonUniformIndexing;
VkBool32 shaderStorageTexelBufferArrayNonUniformIndexing;
VkBool32 descriptorBindingUniformBufferUpdateAfterBind;
VkBool32 descriptorBindingSampledImageUpdateAfterBind;
VkBool32 descriptorBindingStorageImageUpdateAfterBind;
VkBool32 descriptorBindingStorageBufferUpdateAfterBind;
VkBool32 descriptorBindingUniformTexelBufferUpdateAfterBind;
VkBool32 descriptorBindingStorageTexelBufferUpdateAfterBind;
VkBool32 descriptorBindingUpdateUnusedWhilePending;
VkBool32 descriptorBindingPartiallyBound;
VkBool32 descriptorBindingVariableDescriptorCount;
VkBool32 runtimeDescriptorArray;
} VkPhysicalDeviceDescriptorIndexingFeatures;
or the equivalent
// Provided by VK_EXT_descriptor_indexing
typedef VkPhysicalDeviceDescriptorIndexingFeatures VkPhysicalDeviceDescriptorIndexingFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
shaderInputAttachmentArrayDynamicIndexingindicates whether arrays of input attachments can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theInputAttachmentArrayDynamicIndexingcapability. -
shaderUniformTexelBufferArrayDynamicIndexingindicates whether arrays of uniform texel buffers can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theUniformTexelBufferArrayDynamicIndexingcapability. -
shaderStorageTexelBufferArrayDynamicIndexingindicates whether arrays of storage texel buffers can be indexed by dynamically uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageTexelBufferArrayDynamicIndexingcapability. -
shaderUniformBufferArrayNonUniformIndexingindicates whether arrays of uniform buffers can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMICmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theUniformBufferArrayNonUniformIndexingcapability. -
shaderSampledImageArrayNonUniformIndexingindicates whether arrays of samplers or sampled images can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_SAMPLER,VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, orVK_DESCRIPTOR_TYPE_SAMPLED_IMAGEmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theSampledImageArrayNonUniformIndexingcapability. -
shaderStorageBufferArrayNonUniformIndexingindicates whether arrays of storage buffers can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMICmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageBufferArrayNonUniformIndexingcapability. -
shaderStorageImageArrayNonUniformIndexingindicates whether arrays of storage images can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_IMAGEmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageImageArrayNonUniformIndexingcapability. -
shaderInputAttachmentArrayNonUniformIndexingindicates whether arrays of input attachments can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theInputAttachmentArrayNonUniformIndexingcapability. -
shaderUniformTexelBufferArrayNonUniformIndexingindicates whether arrays of uniform texel buffers can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theUniformTexelBufferArrayNonUniformIndexingcapability. -
shaderStorageTexelBufferArrayNonUniformIndexingindicates whether arrays of storage texel buffers can be indexed by non-uniform integer expressions in shader code. If this feature is not enabled, resources with a descriptor type ofVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageTexelBufferArrayNonUniformIndexingcapability. -
descriptorBindingUniformBufferUpdateAfterBindindicates whether the implementation supports updating uniform buffer descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER. -
descriptorBindingSampledImageUpdateAfterBindindicates whether the implementation supports updating sampled image descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_SAMPLER,VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, orVK_DESCRIPTOR_TYPE_SAMPLED_IMAGE. -
descriptorBindingStorageImageUpdateAfterBindindicates whether the implementation supports updating storage image descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_STORAGE_IMAGE. -
descriptorBindingStorageBufferUpdateAfterBindindicates whether the implementation supports updating storage buffer descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_STORAGE_BUFFER. -
descriptorBindingUniformTexelBufferUpdateAfterBindindicates whether the implementation supports updating uniform texel buffer descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER. -
descriptorBindingStorageTexelBufferUpdateAfterBindindicates whether the implementation supports updating storage texel buffer descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER. -
descriptorBindingUpdateUnusedWhilePendingindicates whether the implementation supports updating descriptors while the set is in use. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BITmust not be used. -
descriptorBindingPartiallyBoundindicates whether the implementation supports statically using a descriptor set binding in which some descriptors are not valid. If this feature is not enabled,VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BITmust not be used. -
descriptorBindingVariableDescriptorCountindicates whether the implementation supports descriptor sets with a variable-sized last binding. If this feature is not enabled,VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BITmust not be used. -
runtimeDescriptorArrayindicates whether the implementation supports the SPIR-VRuntimeDescriptorArraycapability. If this feature is not enabled, descriptors must not be declared in runtime arrays.
If the VkPhysicalDeviceDescriptorIndexingFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceDescriptorIndexingFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT structure is
defined as:
// Provided by VK_EXT_vertex_attribute_divisor
typedef struct VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 vertexAttributeInstanceRateDivisor;
VkBool32 vertexAttributeInstanceRateZeroDivisor;
} VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexAttributeInstanceRateDivisorspecifies whether vertex attribute fetching may be repeated in case of instanced rendering. -
vertexAttributeInstanceRateZeroDivisorspecifies whether a zero value forVkVertexInputBindingDivisorDescriptionEXT::divisoris supported.
If the VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceASTCDecodeFeaturesEXT structure is defined as:
// Provided by VK_EXT_astc_decode_mode
typedef struct VkPhysicalDeviceASTCDecodeFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 decodeModeSharedExponent;
} VkPhysicalDeviceASTCDecodeFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDeviceASTCDecodeFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceASTCDecodeFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceTransformFeedbackFeaturesEXT structure is defined
as:
// Provided by VK_EXT_transform_feedback
typedef struct VkPhysicalDeviceTransformFeedbackFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 transformFeedback;
VkBool32 geometryStreams;
} VkPhysicalDeviceTransformFeedbackFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
transformFeedbackindicates whether the implementation supports transform feedback and shader modules can declare theTransformFeedbackcapability. -
geometryStreamsindicates whether the implementation supports theGeometryStreamsSPIR-V capability.
If the VkPhysicalDeviceTransformFeedbackFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceTransformFeedbackFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceVulkanMemoryModelFeatures structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceVulkanMemoryModelFeatures {
VkStructureType sType;
void* pNext;
VkBool32 vulkanMemoryModel;
VkBool32 vulkanMemoryModelDeviceScope;
VkBool32 vulkanMemoryModelAvailabilityVisibilityChains;
} VkPhysicalDeviceVulkanMemoryModelFeatures;
or the equivalent
// Provided by VK_KHR_vulkan_memory_model
typedef VkPhysicalDeviceVulkanMemoryModelFeatures VkPhysicalDeviceVulkanMemoryModelFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
vulkanMemoryModelindicates whether the Vulkan Memory Model is supported, as defined in Vulkan Memory Model. This also indicates whether shader modules can declare theVulkanMemoryModelcapability. -
vulkanMemoryModelDeviceScopeindicates whether the Vulkan Memory Model can useDevicescope synchronization. This also indicates whether shader modules can declare theVulkanMemoryModelDeviceScopecapability. -
vulkanMemoryModelAvailabilityVisibilityChainsindicates whether the Vulkan Memory Model can use availability and visibility chains with more than one element.
If the VkPhysicalDeviceVulkanMemoryModelFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceVulkanMemoryModelFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceInlineUniformBlockFeatures structure is defined
as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceInlineUniformBlockFeatures {
VkStructureType sType;
void* pNext;
VkBool32 inlineUniformBlock;
VkBool32 descriptorBindingInlineUniformBlockUpdateAfterBind;
} VkPhysicalDeviceInlineUniformBlockFeatures;
or the equivalent
// Provided by VK_EXT_inline_uniform_block
typedef VkPhysicalDeviceInlineUniformBlockFeatures VkPhysicalDeviceInlineUniformBlockFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
inlineUniformBlockindicates whether the implementation supports inline uniform block descriptors. If this feature is not enabled,VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCKmust not be used. -
descriptorBindingInlineUniformBlockUpdateAfterBindindicates whether the implementation supports updating inline uniform block descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK.
If the VkPhysicalDeviceInlineUniformBlockFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceInlineUniformBlockFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceRepresentativeFragmentTestFeaturesNV structure is
defined as:
// Provided by VK_NV_representative_fragment_test
typedef struct VkPhysicalDeviceRepresentativeFragmentTestFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 representativeFragmentTest;
} VkPhysicalDeviceRepresentativeFragmentTestFeaturesNV;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
representativeFragmentTestindicates whether the implementation supports the representative fragment test. See Representative Fragment Test.
If the VkPhysicalDeviceRepresentativeFragmentTestFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceRepresentativeFragmentTestFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceExclusiveScissorFeaturesNV structure is defined
as:
// Provided by VK_NV_scissor_exclusive
typedef struct VkPhysicalDeviceExclusiveScissorFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 exclusiveScissor;
} VkPhysicalDeviceExclusiveScissorFeaturesNV;
This structure describes the following feature:
See Exclusive Scissor Test for more information.
If the VkPhysicalDeviceExclusiveScissorFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceExclusiveScissorFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceCornerSampledImageFeaturesNV structure is defined
as:
// Provided by VK_NV_corner_sampled_image
typedef struct VkPhysicalDeviceCornerSampledImageFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 cornerSampledImage;
} VkPhysicalDeviceCornerSampledImageFeaturesNV;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cornerSampledImagespecifies whether images can be created with a VkImageCreateInfo::flagscontainingVK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV. See Corner-Sampled Images.
If the VkPhysicalDeviceCornerSampledImageFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceCornerSampledImageFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceComputeShaderDerivativesFeaturesNV structure is
defined as:
// Provided by VK_NV_compute_shader_derivatives
typedef struct VkPhysicalDeviceComputeShaderDerivativesFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 computeDerivativeGroupQuads;
VkBool32 computeDerivativeGroupLinear;
} VkPhysicalDeviceComputeShaderDerivativesFeaturesNV;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
computeDerivativeGroupQuadsindicates that the implementation supports theComputeDerivativeGroupQuadsNVSPIR-V capability. -
computeDerivativeGroupLinearindicates that the implementation supports theComputeDerivativeGroupLinearNVSPIR-V capability.
See Quad shader scope for more information.
If the VkPhysicalDeviceComputeShaderDerivativesFeaturesNVfeatures. structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceComputeShaderDerivativesFeaturesNVfeatures. can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR structure is
defined as:
// Provided by VK_KHR_fragment_shader_barycentric
typedef struct VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 fragmentShaderBarycentric;
} VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR;
or the equivalent
// Provided by VK_NV_fragment_shader_barycentric
typedef VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR VkPhysicalDeviceFragmentShaderBarycentricFeaturesNV;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentShaderBarycentricindicates that the implementation supports theBaryCoordKHRandBaryCoordNoPerspKHRSPIR-V fragment shader built-ins and supports thePerVertexKHRSPIR-V decoration on fragment shader input variables.
See Barycentric Interpolation for more information.
If the VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderImageFootprintFeaturesNV structure is
defined as:
// Provided by VK_NV_shader_image_footprint
typedef struct VkPhysicalDeviceShaderImageFootprintFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 imageFootprint;
} VkPhysicalDeviceShaderImageFootprintFeaturesNV;
This structure describes the following feature:
See Texel Footprint Evaluation for more information.
If the VkPhysicalDeviceShaderImageFootprintFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderImageFootprintFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShadingRateImageFeaturesNV structure is defined
as:
// Provided by VK_NV_shading_rate_image
typedef struct VkPhysicalDeviceShadingRateImageFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 shadingRateImage;
VkBool32 shadingRateCoarseSampleOrder;
} VkPhysicalDeviceShadingRateImageFeaturesNV;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shadingRateImageindicates that the implementation supports the use of a shading rate image to derive an effective shading rate for fragment processing. It also indicates that the implementation supports theShadingRateNVSPIR-V execution mode. -
shadingRateCoarseSampleOrderindicates that the implementation supports a user-configurable ordering of coverage samples in fragments larger than one pixel.
See Shading Rate Image for more information.
If the VkPhysicalDeviceShadingRateImageFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShadingRateImageFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceFragmentDensityMapFeaturesEXT structure is defined
as:
// Provided by VK_EXT_fragment_density_map
typedef struct VkPhysicalDeviceFragmentDensityMapFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 fragmentDensityMap;
VkBool32 fragmentDensityMapDynamic;
VkBool32 fragmentDensityMapNonSubsampledImages;
} VkPhysicalDeviceFragmentDensityMapFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityMapspecifies whether the implementation supports render passes with a fragment density map attachment. If this feature is not enabled and thepNextchain of VkRenderPassCreateInfo includes a VkRenderPassFragmentDensityMapCreateInfoEXT structure,fragmentDensityMapAttachmentmust beVK_ATTACHMENT_UNUSED. -
fragmentDensityMapDynamicspecifies whether the implementation supports dynamic fragment density map image views. If this feature is not enabled,VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXTmust not be included in VkImageViewCreateInfo::flags. -
fragmentDensityMapNonSubsampledImagesspecifies whether the implementation supports regular non-subsampled image attachments with fragment density map render passes. If this feature is not enabled, render passes with a fragment density map attachment must only have subsampled attachments bound.
If the VkPhysicalDeviceFragmentDensityMapFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceFragmentDensityMapFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceFragmentDensityMap2FeaturesEXT structure is
defined as:
// Provided by VK_EXT_fragment_density_map2
typedef struct VkPhysicalDeviceFragmentDensityMap2FeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 fragmentDensityMapDeferred;
} VkPhysicalDeviceFragmentDensityMap2FeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityMapDeferredspecifies whether the implementation supports deferred reads of fragment density map image views. If this feature is not enabled,VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXTmust not be included inVkImageViewCreateInfo::flags.
If the VkPhysicalDeviceFragmentDensityMap2FeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceFragmentDensityMap2FeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceFragmentDensityMapOffsetFeaturesQCOM structure is
defined as:
// Provided by VK_QCOM_fragment_density_map_offset
typedef struct VkPhysicalDeviceFragmentDensityMapOffsetFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 fragmentDensityMapOffset;
} VkPhysicalDeviceFragmentDensityMapOffsetFeaturesQCOM;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityMapOffsetsspecifies whether the implementation supports fragment density map offsets
If the VkPhysicalDeviceFragmentDensityMapOffsetFeaturesQCOM structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceFragmentDensityMapOffsetFeaturesQCOM can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceInvocationMaskFeaturesHUAWEI structure is defined
as:
// Provided by VK_HUAWEI_invocation_mask
typedef struct VkPhysicalDeviceInvocationMaskFeaturesHUAWEI {
VkStructureType sType;
void* pNext;
VkBool32 invocationMask;
} VkPhysicalDeviceInvocationMaskFeaturesHUAWEI;
This structure describes the following feature:
If the VkPhysicalDeviceInvocationMaskFeaturesHUAWEI structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceInvocationMaskFeaturesHUAWEI can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceScalarBlockLayoutFeatures structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceScalarBlockLayoutFeatures {
VkStructureType sType;
void* pNext;
VkBool32 scalarBlockLayout;
} VkPhysicalDeviceScalarBlockLayoutFeatures;
or the equivalent
// Provided by VK_EXT_scalar_block_layout
typedef VkPhysicalDeviceScalarBlockLayoutFeatures VkPhysicalDeviceScalarBlockLayoutFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
scalarBlockLayoutindicates that the implementation supports the layout of resource blocks in shaders using scalar alignment.
If the VkPhysicalDeviceScalarBlockLayoutFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceScalarBlockLayoutFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceUniformBufferStandardLayoutFeatures structure is
defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceUniformBufferStandardLayoutFeatures {
VkStructureType sType;
void* pNext;
VkBool32 uniformBufferStandardLayout;
} VkPhysicalDeviceUniformBufferStandardLayoutFeatures;
or the equivalent
// Provided by VK_KHR_uniform_buffer_standard_layout
typedef VkPhysicalDeviceUniformBufferStandardLayoutFeatures VkPhysicalDeviceUniformBufferStandardLayoutFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
uniformBufferStandardLayoutindicates that the implementation supports the same layouts for uniform buffers as for storage and other kinds of buffers. See Standard Buffer Layout.
If the VkPhysicalDeviceUniformBufferStandardLayoutFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceUniformBufferStandardLayoutFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceDepthClipEnableFeaturesEXT structure is defined
as:
// Provided by VK_EXT_depth_clip_enable
typedef struct VkPhysicalDeviceDepthClipEnableFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 depthClipEnable;
} VkPhysicalDeviceDepthClipEnableFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
depthClipEnableindicates that the implementation supports setting the depth clipping operation explicitly via the VkPipelineRasterizationDepthClipStateCreateInfoEXT pipeline state. Otherwise depth clipping is only enabled when VkPipelineRasterizationStateCreateInfo::depthClampEnableis set toVK_FALSE.
If the VkPhysicalDeviceDepthClipEnableFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceDepthClipEnableFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceMemoryPriorityFeaturesEXT structure is defined as:
// Provided by VK_EXT_memory_priority
typedef struct VkPhysicalDeviceMemoryPriorityFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 memoryPriority;
} VkPhysicalDeviceMemoryPriorityFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryPriorityindicates that the implementation supports memory priorities specified at memory allocation time via VkMemoryPriorityAllocateInfoEXT.
If the VkPhysicalDeviceMemoryPriorityFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceMemoryPriorityFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceBufferDeviceAddressFeatures structure is defined
as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceBufferDeviceAddressFeatures {
VkStructureType sType;
void* pNext;
VkBool32 bufferDeviceAddress;
VkBool32 bufferDeviceAddressCaptureReplay;
VkBool32 bufferDeviceAddressMultiDevice;
} VkPhysicalDeviceBufferDeviceAddressFeatures;
or the equivalent
// Provided by VK_KHR_buffer_device_address
typedef VkPhysicalDeviceBufferDeviceAddressFeatures VkPhysicalDeviceBufferDeviceAddressFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
bufferDeviceAddressindicates that the implementation supports accessing buffer memory in shaders as storage buffers via an address queried from vkGetBufferDeviceAddress. -
bufferDeviceAddressCaptureReplayindicates that the implementation supports saving and reusing buffer and device addresses, e.g. for trace capture and replay. -
bufferDeviceAddressMultiDeviceindicates that the implementation supports thebufferDeviceAddress,rayTracingPipelineandrayQueryfeatures for logical devices created with multiple physical devices. If this feature is not supported, buffer and acceleration structure addresses must not be queried on a logical device created with more than one physical device.
|
Note
|
See vkGetBufferDeviceAddress for more information.
If the VkPhysicalDeviceBufferDeviceAddressFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceBufferDeviceAddressFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceBufferDeviceAddressFeaturesEXT structure is
defined as:
// Provided by VK_EXT_buffer_device_address
typedef struct VkPhysicalDeviceBufferDeviceAddressFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 bufferDeviceAddress;
VkBool32 bufferDeviceAddressCaptureReplay;
VkBool32 bufferDeviceAddressMultiDevice;
} VkPhysicalDeviceBufferDeviceAddressFeaturesEXT;
// Provided by VK_EXT_buffer_device_address
typedef VkPhysicalDeviceBufferDeviceAddressFeaturesEXT VkPhysicalDeviceBufferAddressFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferDeviceAddressindicates that the implementation supports accessing buffer memory in shaders as storage buffers via an address queried from vkGetBufferDeviceAddressEXT. -
bufferDeviceAddressCaptureReplayindicates that the implementation supports saving and reusing buffer addresses, e.g. for trace capture and replay. -
bufferDeviceAddressMultiDeviceindicates that the implementation supports thebufferDeviceAddressfeature for logical devices created with multiple physical devices. If this feature is not supported, buffer addresses must not be queried on a logical device created with more than one physical device.
If the VkPhysicalDeviceBufferDeviceAddressFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceBufferDeviceAddressFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
|
Note
The |
The VkPhysicalDeviceDedicatedAllocationImageAliasingFeaturesNV
structure is defined as:
// Provided by VK_NV_dedicated_allocation_image_aliasing
typedef struct VkPhysicalDeviceDedicatedAllocationImageAliasingFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 dedicatedAllocationImageAliasing;
} VkPhysicalDeviceDedicatedAllocationImageAliasingFeaturesNV;
This structure describes the following feature:
If the VkPhysicalDeviceDedicatedAllocationImageAliasingFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceDedicatedAllocationImageAliasingFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceImagelessFramebufferFeatures structure is defined
as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceImagelessFramebufferFeatures {
VkStructureType sType;
void* pNext;
VkBool32 imagelessFramebuffer;
} VkPhysicalDeviceImagelessFramebufferFeatures;
or the equivalent
// Provided by VK_KHR_imageless_framebuffer
typedef VkPhysicalDeviceImagelessFramebufferFeatures VkPhysicalDeviceImagelessFramebufferFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
imagelessFramebufferindicates that the implementation supports specifying the image view for attachments at render pass begin time via VkRenderPassAttachmentBeginInfo.
If the VkPhysicalDeviceImagelessFramebufferFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceImagelessFramebufferFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceFragmentShaderInterlockFeaturesEXT structure is
defined as:
// Provided by VK_EXT_fragment_shader_interlock
typedef struct VkPhysicalDeviceFragmentShaderInterlockFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 fragmentShaderSampleInterlock;
VkBool32 fragmentShaderPixelInterlock;
VkBool32 fragmentShaderShadingRateInterlock;
} VkPhysicalDeviceFragmentShaderInterlockFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentShaderSampleInterlockindicates that the implementation supports theFragmentShaderSampleInterlockEXTSPIR-V capability. -
fragmentShaderPixelInterlockindicates that the implementation supports theFragmentShaderPixelInterlockEXTSPIR-V capability. -
fragmentShaderShadingRateInterlockindicates that the implementation supports theFragmentShaderShadingRateInterlockEXTSPIR-V capability.
If the VkPhysicalDeviceFragmentShaderInterlockFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceFragmentShaderInterlockFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceCooperativeMatrixFeaturesNV structure is defined
as:
// Provided by VK_NV_cooperative_matrix
typedef struct VkPhysicalDeviceCooperativeMatrixFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 cooperativeMatrix;
VkBool32 cooperativeMatrixRobustBufferAccess;
} VkPhysicalDeviceCooperativeMatrixFeaturesNV;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cooperativeMatrixindicates that the implementation supports theCooperativeMatrixNVSPIR-V capability. -
cooperativeMatrixRobustBufferAccessindicates that the implementation supports robust buffer access for SPIR-VOpCooperativeMatrixLoadNVandOpCooperativeMatrixStoreNVinstructions.
If the VkPhysicalDeviceCooperativeMatrixFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceCooperativeMatrixFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceYcbcrImageArraysFeaturesEXT structure is defined
as:
// Provided by VK_EXT_ycbcr_image_arrays
typedef struct VkPhysicalDeviceYcbcrImageArraysFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 ycbcrImageArrays;
} VkPhysicalDeviceYcbcrImageArraysFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
ycbcrImageArraysindicates that the implementation supports creating images with a format that requires Y′CBCR conversion and has multiple array layers.
If the VkPhysicalDeviceYcbcrImageArraysFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceYcbcrImageArraysFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures structure is
defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures {
VkStructureType sType;
void* pNext;
VkBool32 shaderSubgroupExtendedTypes;
} VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures;
or the equivalent
// Provided by VK_KHR_shader_subgroup_extended_types
typedef VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures VkPhysicalDeviceShaderSubgroupExtendedTypesFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
shaderSubgroupExtendedTypesis a boolean specifying whether subgroup operations can use 8-bit integer, 16-bit integer, 64-bit integer, 16-bit floating-point, and vectors of these types in group operations with subgroup scope, if the implementation supports the types.
If the VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceHostQueryResetFeatures structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceHostQueryResetFeatures {
VkStructureType sType;
void* pNext;
VkBool32 hostQueryReset;
} VkPhysicalDeviceHostQueryResetFeatures;
or the equivalent
// Provided by VK_EXT_host_query_reset
typedef VkPhysicalDeviceHostQueryResetFeatures VkPhysicalDeviceHostQueryResetFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
hostQueryResetindicates that the implementation supports resetting queries from the host with vkResetQueryPool.
If the VkPhysicalDeviceHostQueryResetFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceHostQueryResetFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderIntegerFunctions2FeaturesINTEL structure is
defined as:
// Provided by VK_INTEL_shader_integer_functions2
typedef struct VkPhysicalDeviceShaderIntegerFunctions2FeaturesINTEL {
VkStructureType sType;
void* pNext;
VkBool32 shaderIntegerFunctions2;
} VkPhysicalDeviceShaderIntegerFunctions2FeaturesINTEL;
This structure describes the following feature:
If the VkPhysicalDeviceShaderIntegerFunctions2FeaturesINTELfeatures. structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderIntegerFunctions2FeaturesINTELfeatures. can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceCoverageReductionModeFeaturesNV structure is
defined as:
// Provided by VK_NV_coverage_reduction_mode
typedef struct VkPhysicalDeviceCoverageReductionModeFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 coverageReductionMode;
} VkPhysicalDeviceCoverageReductionModeFeaturesNV;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
coverageReductionModeindicates whether the implementation supports coverage reduction modes. See Coverage Reduction.
If the VkPhysicalDeviceCoverageReductionModeFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceCoverageReductionModeFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceTimelineSemaphoreFeatures structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceTimelineSemaphoreFeatures {
VkStructureType sType;
void* pNext;
VkBool32 timelineSemaphore;
} VkPhysicalDeviceTimelineSemaphoreFeatures;
or the equivalent
// Provided by VK_KHR_timeline_semaphore
typedef VkPhysicalDeviceTimelineSemaphoreFeatures VkPhysicalDeviceTimelineSemaphoreFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
timelineSemaphoreindicates whether semaphores created with a VkSemaphoreType ofVK_SEMAPHORE_TYPE_TIMELINEare supported.
If the VkPhysicalDeviceTimelineSemaphoreFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceTimelineSemaphoreFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceIndexTypeUint8FeaturesEXT structure is defined as:
// Provided by VK_EXT_index_type_uint8
typedef struct VkPhysicalDeviceIndexTypeUint8FeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 indexTypeUint8;
} VkPhysicalDeviceIndexTypeUint8FeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
indexTypeUint8indicates thatVK_INDEX_TYPE_UINT8_EXTcan be used with vkCmdBindIndexBuffer.
If the VkPhysicalDeviceIndexTypeUint8FeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceIndexTypeUint8FeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePrimitiveTopologyListRestartFeaturesEXT structure
is defined as:
// Provided by VK_EXT_primitive_topology_list_restart
typedef struct VkPhysicalDevicePrimitiveTopologyListRestartFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 primitiveTopologyListRestart;
VkBool32 primitiveTopologyPatchListRestart;
} VkPhysicalDevicePrimitiveTopologyListRestartFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
primitiveTopologyListRestartindicates that list type primitives,VK_PRIMITIVE_TOPOLOGY_POINT_LIST,VK_PRIMITIVE_TOPOLOGY_LINE_LIST,VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCYandVK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY, can use the primitive restart index value in index buffers. -
primitiveTopologyPatchListRestartindicates that theVK_PRIMITIVE_TOPOLOGY_PATCH_LISTtopology can use the primitive restart index value in index buffers.
If the VkPhysicalDevicePrimitiveTopologyListRestartFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePrimitiveTopologyListRestartFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderSMBuiltinsFeaturesNV structure is defined
as:
// Provided by VK_NV_shader_sm_builtins
typedef struct VkPhysicalDeviceShaderSMBuiltinsFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 shaderSMBuiltins;
} VkPhysicalDeviceShaderSMBuiltinsFeaturesNV;
This structure describes the following feature:
If the VkPhysicalDeviceShaderSMBuiltinsFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderSMBuiltinsFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures structure is
defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures {
VkStructureType sType;
void* pNext;
VkBool32 separateDepthStencilLayouts;
} VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures;
or the equivalent
// Provided by VK_KHR_separate_depth_stencil_layouts
typedef VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures VkPhysicalDeviceSeparateDepthStencilLayoutsFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
separateDepthStencilLayoutsindicates whether the implementation supports aVkImageMemoryBarrierfor a depth/stencil image with only one ofVK_IMAGE_ASPECT_DEPTH_BITorVK_IMAGE_ASPECT_STENCIL_BITset, and whetherVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL,VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL,VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, orVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMALcan be used.
If the VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePipelineExecutablePropertiesFeaturesKHR structure
is defined as:
// Provided by VK_KHR_pipeline_executable_properties
typedef struct VkPhysicalDevicePipelineExecutablePropertiesFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 pipelineExecutableInfo;
} VkPhysicalDevicePipelineExecutablePropertiesFeaturesKHR;
This structure describes the following feature:
If the VkPhysicalDevicePipelineExecutablePropertiesFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePipelineExecutablePropertiesFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures structure
is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures {
VkStructureType sType;
void* pNext;
VkBool32 shaderDemoteToHelperInvocation;
} VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures;
or the equivalent
// Provided by VK_EXT_shader_demote_to_helper_invocation
typedef VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures VkPhysicalDeviceShaderDemoteToHelperInvocationFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceTexelBufferAlignmentFeaturesEXT structure is
defined as:
// Provided by VK_EXT_texel_buffer_alignment
typedef struct VkPhysicalDeviceTexelBufferAlignmentFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 texelBufferAlignment;
} VkPhysicalDeviceTexelBufferAlignmentFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
texelBufferAlignmentindicates whether the implementation uses more specific alignment requirements advertised in VkPhysicalDeviceTexelBufferAlignmentProperties rather than VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment.
If the VkPhysicalDeviceTexelBufferAlignmentFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceTexelBufferAlignmentFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceTextureCompressionASTCHDRFeatures structure is
defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceTextureCompressionASTCHDRFeatures {
VkStructureType sType;
void* pNext;
VkBool32 textureCompressionASTC_HDR;
} VkPhysicalDeviceTextureCompressionASTCHDRFeatures;
or the equivalent
// Provided by VK_EXT_texture_compression_astc_hdr
typedef VkPhysicalDeviceTextureCompressionASTCHDRFeatures VkPhysicalDeviceTextureCompressionASTCHDRFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
textureCompressionASTC_HDRindicates whether all of the ASTC HDR compressed texture formats are supported. If this feature is enabled, then theVK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT,VK_FORMAT_FEATURE_BLIT_SRC_BITandVK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BITfeatures must be supported inoptimalTilingFeaturesfor the following formats:-
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK -
VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK -
VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK -
VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK -
VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK -
VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK -
VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK
To query for additional properties, or if the feature is not enabled, vkGetPhysicalDeviceFormatProperties and vkGetPhysicalDeviceImageFormatProperties can be used to check for supported properties of individual formats as normal.
-
If the VkPhysicalDeviceTextureCompressionASTCHDRFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceTextureCompressionASTCHDRFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceLineRasterizationFeaturesEXT structure is defined
as:
// Provided by VK_EXT_line_rasterization
typedef struct VkPhysicalDeviceLineRasterizationFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 rectangularLines;
VkBool32 bresenhamLines;
VkBool32 smoothLines;
VkBool32 stippledRectangularLines;
VkBool32 stippledBresenhamLines;
VkBool32 stippledSmoothLines;
} VkPhysicalDeviceLineRasterizationFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rectangularLinesindicates whether the implementation supports rectangular line rasterization. -
bresenhamLinesindicates whether the implementation supports Bresenham-style line rasterization. -
smoothLinesindicates whether the implementation supports smooth line rasterization. -
stippledRectangularLinesindicates whether the implementation supports stippled line rasterization withVK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXTlines. -
stippledBresenhamLinesindicates whether the implementation supports stippled line rasterization withVK_LINE_RASTERIZATION_MODE_BRESENHAM_EXTlines. -
stippledSmoothLinesindicates whether the implementation supports stippled line rasterization withVK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXTlines.
If the VkPhysicalDeviceLineRasterizationFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceLineRasterizationFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceSubgroupSizeControlFeatures structure is defined
as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceSubgroupSizeControlFeatures {
VkStructureType sType;
void* pNext;
VkBool32 subgroupSizeControl;
VkBool32 computeFullSubgroups;
} VkPhysicalDeviceSubgroupSizeControlFeatures;
or the equivalent
// Provided by VK_EXT_subgroup_size_control
typedef VkPhysicalDeviceSubgroupSizeControlFeatures VkPhysicalDeviceSubgroupSizeControlFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
subgroupSizeControlindicates whether the implementation supports controlling shader subgroup sizes via theVK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BITflag and the VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure. -
computeFullSubgroupsindicates whether the implementation supports requiring full subgroups in compute shaders via theVK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BITflag.
If the VkPhysicalDeviceSubgroupSizeControlFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceSubgroupSizeControlFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
|
Note
The Vulkan 1.3 implementations always support the features structure. |
The VkPhysicalDeviceCoherentMemoryFeaturesAMD structure is defined as:
// Provided by VK_AMD_device_coherent_memory
typedef struct VkPhysicalDeviceCoherentMemoryFeaturesAMD {
VkStructureType sType;
void* pNext;
VkBool32 deviceCoherentMemory;
} VkPhysicalDeviceCoherentMemoryFeaturesAMD;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceCoherentMemoryindicates that the implementation supports device coherent memory.
If the VkPhysicalDeviceCoherentMemoryFeaturesAMD structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceCoherentMemoryFeaturesAMD can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceAccelerationStructureFeaturesKHR structure is
defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkPhysicalDeviceAccelerationStructureFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 accelerationStructure;
VkBool32 accelerationStructureCaptureReplay;
VkBool32 accelerationStructureIndirectBuild;
VkBool32 accelerationStructureHostCommands;
VkBool32 descriptorBindingAccelerationStructureUpdateAfterBind;
} VkPhysicalDeviceAccelerationStructureFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructureindicates whether the implementation supports the acceleration structure functionality. See Acceleration Structures. -
accelerationStructureCaptureReplayindicates whether the implementation supports saving and reusing acceleration structure device addresses, e.g. for trace capture and replay. -
accelerationStructureIndirectBuildindicates whether the implementation supports indirect acceleration structure build commands, e.g. vkCmdBuildAccelerationStructuresIndirectKHR. -
accelerationStructureHostCommandsindicates whether the implementation supports host side acceleration structure commands, e.g. vkBuildAccelerationStructuresKHR, vkCopyAccelerationStructureKHR, vkCopyAccelerationStructureToMemoryKHR, vkCopyMemoryToAccelerationStructureKHR, vkWriteAccelerationStructuresPropertiesKHR. -
descriptorBindingAccelerationStructureUpdateAfterBindindicates whether the implementation supports updating acceleration structure descriptors after a set is bound. If this feature is not enabled,VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITmust not be used withVK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR.
If the VkPhysicalDeviceAccelerationStructureFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceAccelerationStructureFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure is defined
as:
// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkPhysicalDeviceRayTracingPipelineFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 rayTracingPipeline;
VkBool32 rayTracingPipelineShaderGroupHandleCaptureReplay;
VkBool32 rayTracingPipelineShaderGroupHandleCaptureReplayMixed;
VkBool32 rayTracingPipelineTraceRaysIndirect;
VkBool32 rayTraversalPrimitiveCulling;
} VkPhysicalDeviceRayTracingPipelineFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rayTracingPipelineindicates whether the implementation supports the ray tracing pipeline functionality. See Ray Tracing. -
rayTracingPipelineShaderGroupHandleCaptureReplayindicates whether the implementation supports saving and reusing shader group handles, e.g. for trace capture and replay. -
rayTracingPipelineShaderGroupHandleCaptureReplayMixedindicates whether the implementation supports reuse of shader group handles being arbitrarily mixed with creation of non-reused shader group handles. If this isVK_FALSE, all reused shader group handles must be specified before any non-reused handles may be created. -
rayTracingPipelineTraceRaysIndirectindicates whether the implementation supports indirect ray tracing commands, e.g. vkCmdTraceRaysIndirectKHR. -
rayTraversalPrimitiveCullingindicates whether the implementation supports primitive culling during ray traversal.
If the VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceRayTracingPipelineFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceRayQueryFeaturesKHR structure is defined as:
// Provided by VK_KHR_ray_query
typedef struct VkPhysicalDeviceRayQueryFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 rayQuery;
} VkPhysicalDeviceRayQueryFeaturesKHR;
This structure describes the following feature:
If the VkPhysicalDeviceRayQueryFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceRayQueryFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceRayTracingMaintenance1FeaturesKHR structure is
defined as:
// Provided by VK_KHR_ray_tracing_maintenance1
typedef struct VkPhysicalDeviceRayTracingMaintenance1FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 rayTracingMaintenance1;
VkBool32 rayTracingPipelineTraceRaysIndirect2;
} VkPhysicalDeviceRayTracingMaintenance1FeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rayTracingMaintenance1indicates that the implementation supports the following:-
The
CullMaskKHRSPIR-V builtin using theSPV_KHR_ray_cull_maskSPIR-V extension. -
Additional acceleration structure property queries:
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHRandVK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR. -
A new access flag
VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR. -
A new pipeline stage flag bit
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
-
-
rayTracingPipelineTraceRaysIndirect2indicates whether the implementation supports the extended indirect ray tracing command vkCmdTraceRaysIndirect2KHR.
If the VkPhysicalDeviceRayTracingMaintenance1FeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceRayTracingMaintenance1FeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceExtendedDynamicStateFeaturesEXT structure is
defined as:
// Provided by VK_EXT_extended_dynamic_state
typedef struct VkPhysicalDeviceExtendedDynamicStateFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 extendedDynamicState;
} VkPhysicalDeviceExtendedDynamicStateFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
extendedDynamicStateindicates that the implementation supports the following dynamic states:-
VK_DYNAMIC_STATE_CULL_MODE -
VK_DYNAMIC_STATE_FRONT_FACE -
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY -
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT -
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT -
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE -
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE -
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE -
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP -
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE -
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE -
VK_DYNAMIC_STATE_STENCIL_OP
-
If the VkPhysicalDeviceExtendedDynamicStateFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceExtendedDynamicStateFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceExtendedDynamicState2FeaturesEXT structure is
defined as:
// Provided by VK_EXT_extended_dynamic_state2
typedef struct VkPhysicalDeviceExtendedDynamicState2FeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 extendedDynamicState2;
VkBool32 extendedDynamicState2LogicOp;
VkBool32 extendedDynamicState2PatchControlPoints;
} VkPhysicalDeviceExtendedDynamicState2FeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
extendedDynamicState2indicates that the implementation supports the following dynamic states:-
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE -
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE -
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE
-
-
extendedDynamicState2LogicOpindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_LOGIC_OP_EXT
-
-
extendedDynamicState2PatchControlPointsindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT
-
If the VkPhysicalDeviceExtendedDynamicState2FeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceExtendedDynamicState2FeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV structure is
defined as:
// Provided by VK_NV_device_generated_commands
typedef struct VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 deviceGeneratedCommands;
} VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceGeneratedCommandsindicates whether the implementation supports functionality to generate commands on the device. See Device-Generated Commands.
If the VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceDiagnosticsConfigFeaturesNV structure is defined
as:
// Provided by VK_NV_device_diagnostics_config
typedef struct VkPhysicalDeviceDiagnosticsConfigFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 diagnosticsConfig;
} VkPhysicalDeviceDiagnosticsConfigFeaturesNV;
This structure describes the following feature:
If the VkPhysicalDeviceDiagnosticsConfigFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceDiagnosticsConfigFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceDeviceMemoryReportFeaturesEXT structure is defined
as:
// Provided by VK_EXT_device_memory_report
typedef struct VkPhysicalDeviceDeviceMemoryReportFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 deviceMemoryReport;
} VkPhysicalDeviceDeviceMemoryReportFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDeviceDeviceMemoryReportFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceDeviceMemoryReportFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceGlobalPriorityQueryFeaturesKHR structure is
defined as:
// Provided by VK_KHR_global_priority
typedef struct VkPhysicalDeviceGlobalPriorityQueryFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 globalPriorityQuery;
} VkPhysicalDeviceGlobalPriorityQueryFeaturesKHR;
or the equivalent
// Provided by VK_EXT_global_priority_query
typedef VkPhysicalDeviceGlobalPriorityQueryFeaturesKHR VkPhysicalDeviceGlobalPriorityQueryFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDeviceGlobalPriorityQueryFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceGlobalPriorityQueryFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePipelineCreationCacheControlFeatures structure is
defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDevicePipelineCreationCacheControlFeatures {
VkStructureType sType;
void* pNext;
VkBool32 pipelineCreationCacheControl;
} VkPhysicalDevicePipelineCreationCacheControlFeatures;
or the equivalent
// Provided by VK_EXT_pipeline_creation_cache_control
typedef VkPhysicalDevicePipelineCreationCacheControlFeatures VkPhysicalDevicePipelineCreationCacheControlFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
pipelineCreationCacheControlindicates that the implementation supports:-
The following can be used in
Vk*PipelineCreateInfo::flags:-
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT -
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT
-
-
The following can be used in VkPipelineCacheCreateInfo::
flags:-
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT
-
-
If the VkPhysicalDevicePipelineCreationCacheControlFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePipelineCreationCacheControlFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures structure is
defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures {
VkStructureType sType;
void* pNext;
VkBool32 shaderZeroInitializeWorkgroupMemory;
} VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures;
or the equivalent
// Provided by VK_KHR_zero_initialize_workgroup_memory
typedef VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePrivateDataFeatures structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDevicePrivateDataFeatures {
VkStructureType sType;
void* pNext;
VkBool32 privateData;
} VkPhysicalDevicePrivateDataFeatures;
or the equivalent
// Provided by VK_EXT_private_data
typedef VkPhysicalDevicePrivateDataFeatures VkPhysicalDevicePrivateDataFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
privateDataindicates whether the implementation supports private data. See Private Data.
If the VkPhysicalDevicePrivateDataFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePrivateDataFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderSubgroupUniformControlFlowFeaturesKHR
structure is defined as:
// Provided by VK_KHR_shader_subgroup_uniform_control_flow
typedef struct VkPhysicalDeviceShaderSubgroupUniformControlFlowFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 shaderSubgroupUniformControlFlow;
} VkPhysicalDeviceShaderSubgroupUniformControlFlowFeaturesKHR;
This structure describes the following feature:
If the VkPhysicalDeviceShaderSubgroupUniformControlFlowFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderSubgroupUniformControlFlowFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceRobustness2FeaturesEXT structure is defined as:
// Provided by VK_EXT_robustness2
typedef struct VkPhysicalDeviceRobustness2FeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 robustBufferAccess2;
VkBool32 robustImageAccess2;
VkBool32 nullDescriptor;
} VkPhysicalDeviceRobustness2FeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
robustBufferAccess2indicates whether buffer accesses are tightly bounds-checked against the range of the descriptor. Uniform buffers must be bounds-checked to the range of the descriptor, where the range is rounded up to a multiple of robustUniformBufferAccessSizeAlignment. Storage buffers must be bounds-checked to the range of the descriptor, where the range is rounded up to a multiple of robustStorageBufferAccessSizeAlignment. Out of bounds buffer loads will return zero values, and image load, sample, and atomic operations from texel buffers will have (0,0,1) values inserted for missing G, B, or A components based on the format. -
robustImageAccess2indicates whether image accesses are tightly bounds-checked against the dimensions of the image view. Out of bounds image load, sample, and atomic operations from images will return zero values, with (0,0,1) values inserted for missing G, B, or A components based on the format. -
nullDescriptorindicates whether descriptors can be written with a VK_NULL_HANDLE resource or view, which are considered valid to access and act as if the descriptor were bound to nothing.
If the VkPhysicalDeviceRobustness2FeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceRobustness2FeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceImageRobustnessFeatures structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceImageRobustnessFeatures {
VkStructureType sType;
void* pNext;
VkBool32 robustImageAccess;
} VkPhysicalDeviceImageRobustnessFeatures;
or the equivalent
// Provided by VK_EXT_image_robustness
typedef VkPhysicalDeviceImageRobustnessFeatures VkPhysicalDeviceImageRobustnessFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
robustImageAccessindicates whether image accesses are tightly bounds-checked against the dimensions of the image view. Invalid texels resulting from out of bounds image loads will be replaced as described in Texel Replacement, with either (0,0,1) or (0,0,0) values inserted for missing G, B, or A components based on the format.
If the VkPhysicalDeviceImageRobustnessFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceImageRobustnessFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderTerminateInvocationFeatures structure is
defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceShaderTerminateInvocationFeatures {
VkStructureType sType;
void* pNext;
VkBool32 shaderTerminateInvocation;
} VkPhysicalDeviceShaderTerminateInvocationFeatures;
or the equivalent
// Provided by VK_KHR_shader_terminate_invocation
typedef VkPhysicalDeviceShaderTerminateInvocationFeatures VkPhysicalDeviceShaderTerminateInvocationFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceShaderTerminateInvocationFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderTerminateInvocationFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceCustomBorderColorFeaturesEXT structure is defined
as:
// Provided by VK_EXT_custom_border_color
typedef struct VkPhysicalDeviceCustomBorderColorFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 customBorderColors;
VkBool32 customBorderColorWithoutFormat;
} VkPhysicalDeviceCustomBorderColorFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
customBorderColorsindicates that the implementation supports providing aborderColorvalue with one of the following values at sampler creation time:-
VK_BORDER_COLOR_FLOAT_CUSTOM_EXT -
VK_BORDER_COLOR_INT_CUSTOM_EXT
-
-
customBorderColorWithoutFormatindicates that explicit formats are not required for custom border colors and the value of theformatmember of the VkSamplerCustomBorderColorCreateInfoEXT structure may beVK_FORMAT_UNDEFINED. If this feature bit is not set, applications must provide the VkFormat of the image view(s) being sampled by this sampler in theformatmember of the VkSamplerCustomBorderColorCreateInfoEXT structure.
If the VkPhysicalDeviceCustomBorderColorFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceCustomBorderColorFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceBorderColorSwizzleFeaturesEXT structure is defined
as:
// Provided by VK_EXT_border_color_swizzle
typedef struct VkPhysicalDeviceBorderColorSwizzleFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 borderColorSwizzle;
VkBool32 borderColorSwizzleFromImage;
} VkPhysicalDeviceBorderColorSwizzleFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
borderColorSwizzleindicates that defined values are returned by sampled image operations when used with a sampler that uses aVK_BORDER_COLOR_FLOAT_OPAQUE_BLACK,VK_BORDER_COLOR_INT_OPAQUE_BLACK,VK_BORDER_COLOR_FLOAT_CUSTOM_EXT, orVK_BORDER_COLOR_INT_CUSTOM_EXTborderColorand an image view that uses a non-identity component mapping, when eitherborderColorSwizzleFromImageis enabled or the VkSamplerBorderColorComponentMappingCreateInfoEXT is specified. -
borderColorSwizzleFromImageindicates that the implementation will return the correct border color values from sampled image operations under the conditions expressed above, without the application having to specify the border color component mapping when creating the sampler object. If this feature bit is not set, applications can chain a VkSamplerBorderColorComponentMappingCreateInfoEXT structure when creating samplers for use with image views that do not have an identity swizzle and, when those samplers are combined with image views using the same component mapping, sampled image operations that use opaque black or custom border colors will return the correct border color values.
If the VkPhysicalDeviceBorderColorSwizzleFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceBorderColorSwizzleFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePortabilitySubsetFeaturesKHR structure is defined
as:
// Provided by VK_KHR_portability_subset
typedef struct VkPhysicalDevicePortabilitySubsetFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 constantAlphaColorBlendFactors;
VkBool32 events;
VkBool32 imageViewFormatReinterpretation;
VkBool32 imageViewFormatSwizzle;
VkBool32 imageView2DOn3DImage;
VkBool32 multisampleArrayImage;
VkBool32 mutableComparisonSamplers;
VkBool32 pointPolygons;
VkBool32 samplerMipLodBias;
VkBool32 separateStencilMaskRef;
VkBool32 shaderSampleRateInterpolationFunctions;
VkBool32 tessellationIsolines;
VkBool32 tessellationPointMode;
VkBool32 triangleFans;
VkBool32 vertexAttributeAccessBeyondStride;
} VkPhysicalDevicePortabilitySubsetFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
constantAlphaColorBlendFactorsindicates whether this implementation supports constant alpha Blend Factors used as source or destination color Blending. -
eventsindicates whether this implementation supports synchronization using Events. -
imageViewFormatReinterpretationindicates whether this implementation supports aVkImageViewbeing created with a texel format containing a different number of components, or a different number of bits in each component, than the texel format of the underlyingVkImage. -
imageViewFormatSwizzleindicates whether this implementation supports remapping format components using VkImageViewCreateInfo::components. -
imageView2DOn3DImageindicates whether this implementation supports aVkImagebeing created with theVK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BITflag set, permitting a 2D or 2D array image view to be created on a 3DVkImage. -
multisampleArrayImageindicates whether this implementation supports aVkImagebeing created as a 2D array with multiple samples per texel. -
mutableComparisonSamplersindicates whether this implementation allows descriptors with comparison samplers to be updated. -
pointPolygonsindicates whether this implementation supports Rasterization using a point Polygon Mode. -
samplerMipLodBiasindicates whether this implementation supports setting a mipmap LOD bias value when creating a sampler. -
separateStencilMaskRefindicates whether this implementation supports separate front and back Stencil Test reference values. -
shaderSampleRateInterpolationFunctionsindicates whether this implementation supports fragment shaders which use theInterpolationFunctioncapability and the extended instructionsInterpolateAtCentroid,InterpolateAtOffset, andInterpolateAtSamplefrom theGLSL.std.450extended instruction set. This member is only meaningful if thesampleRateShadingfeature is supported. -
tessellationIsolinesindicates whether this implementation supports isoline output from the Tessellation stage of a graphics pipeline. This member is only meaningful iftessellationShaderare supported. -
tessellationPointModeindicates whether this implementation supports point output from the Tessellation stage of a graphics pipeline. This member is only meaningful iftessellationShaderare supported. -
triangleFansindicates whether this implementation supports Triangle Fans primitive topology. -
vertexAttributeAccessBeyondStrideindicates whether this implementation supports accessing a vertex input attribute beyond the stride of the corresponding vertex input binding.
If the VkPhysicalDevicePortabilitySubsetFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePortabilitySubsetFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePerformanceQueryFeaturesKHR structure is defined
as:
// Provided by VK_KHR_performance_query
typedef struct VkPhysicalDevicePerformanceQueryFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 performanceCounterQueryPools;
VkBool32 performanceCounterMultipleQueryPools;
} VkPhysicalDevicePerformanceQueryFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
performanceCounterQueryPoolsindicates whether the implementation supports performance counter query pools. -
performanceCounterMultipleQueryPoolsindicates whether the implementation supports using multiple performance query pools in a primary command buffer and secondary command buffers executed within it.
If the VkPhysicalDevicePerformanceQueryFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePerformanceQueryFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevice4444FormatsFeaturesEXT structure is defined as:
// Provided by VK_EXT_4444_formats
typedef struct VkPhysicalDevice4444FormatsFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 formatA4R4G4B4;
VkBool32 formatA4B4G4R4;
} VkPhysicalDevice4444FormatsFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatA4R4G4B4indicates that the implementation must support using a VkFormat ofVK_FORMAT_A4R4G4B4_UNORM_PACK16_EXTwith at least the following VkFormatFeatureFlagBits:-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT -
VK_FORMAT_FEATURE_BLIT_SRC_BIT -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
-
-
formatA4B4G4R4indicates that the implementation must support using a VkFormat ofVK_FORMAT_A4B4G4R4_UNORM_PACK16_EXTwith at least the following VkFormatFeatureFlagBits:-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT -
VK_FORMAT_FEATURE_BLIT_SRC_BIT -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
-
If the VkPhysicalDevice4444FormatsFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevice4444FormatsFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
|
Note
Although the formats defined by the |
The VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE structure is
defined as:
// Provided by VK_VALVE_mutable_descriptor_type
typedef struct VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE {
VkStructureType sType;
void* pNext;
VkBool32 mutableDescriptorType;
} VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
mutableDescriptorTypeindicates that the implementation must support using the VkDescriptorType ofVK_DESCRIPTOR_TYPE_MUTABLE_VALVEwith at least the following descriptor types, where any combination of the types must be supported:-
VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE -
VK_DESCRIPTOR_TYPE_STORAGE_IMAGE -
VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER -
VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER -
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER -
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER
-
-
Additionally,
mutableDescriptorTypeindicates that:-
Non-uniform descriptor indexing must be supported if all descriptor types in a VkMutableDescriptorTypeListVALVE for
VK_DESCRIPTOR_TYPE_MUTABLE_VALVEhave the corresponding non-uniform indexing features enabled in VkPhysicalDeviceDescriptorIndexingFeatures. -
VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITwithdescriptorTypeofVK_DESCRIPTOR_TYPE_MUTABLE_VALVErelaxes the list of required descriptor types to the descriptor types which have the corresponding update-after-bind feature enabled in VkPhysicalDeviceDescriptorIndexingFeatures. -
Dynamically uniform descriptor indexing must be supported if all descriptor types in a VkMutableDescriptorTypeListVALVE for
VK_DESCRIPTOR_TYPE_MUTABLE_VALVEhave the corresponding dynamic indexing features enabled. -
VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVEmust be supported. -
VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVEmust be supported.
-
If the VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceDepthClipControlFeaturesEXT structure is defined
as:
// Provided by VK_EXT_depth_clip_control
typedef struct VkPhysicalDeviceDepthClipControlFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 depthClipControl;
} VkPhysicalDeviceDepthClipControlFeaturesEXT;
This structure describe the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
depthClipControlindicates that the implementation supports setting VkPipelineViewportDepthClipControlCreateInfoEXT::negativeOneToOnetoVK_TRUE.
If the VkPhysicalDeviceDepthClipControlFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceDepthClipControlFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceWorkgroupMemoryExplicitLayoutFeaturesKHR structure
is defined as:
// Provided by VK_KHR_workgroup_memory_explicit_layout
typedef struct VkPhysicalDeviceWorkgroupMemoryExplicitLayoutFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 workgroupMemoryExplicitLayout;
VkBool32 workgroupMemoryExplicitLayoutScalarBlockLayout;
VkBool32 workgroupMemoryExplicitLayout8BitAccess;
VkBool32 workgroupMemoryExplicitLayout16BitAccess;
} VkPhysicalDeviceWorkgroupMemoryExplicitLayoutFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
workgroupMemoryExplicitLayoutindicates whether the implementation supports the SPIR-VWorkgroupMemoryExplicitLayoutKHRcapability. -
workgroupMemoryExplicitLayoutScalarBlockLayoutindicates whether the implementation supports scalar alignment for laying out Workgroup Blocks. -
workgroupMemoryExplicitLayout8BitAccessindicates whether objects in theWorkgroupstorage class with theBlockdecoration can have 8-bit integer members. If this feature is not enabled, 8-bit integer members must not be used in such objects. This also indicates whether shader modules can declare theWorkgroupMemoryExplicitLayout8BitAccessKHRcapability. -
workgroupMemoryExplicitLayout16BitAccessindicates whether objects in theWorkgroupstorage class with theBlockdecoration can have 16-bit integer and 16-bit floating-point members. If this feature is not enabled, 16-bit integer or 16-bit floating-point members must not be used in such objects. This also indicates whether shader modules can declare theWorkgroupMemoryExplicitLayout16BitAccessKHRcapability.
If the VkPhysicalDeviceWorkgroupMemoryExplicitLayoutFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceWorkgroupMemoryExplicitLayoutFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceSynchronization2Features structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceSynchronization2Features {
VkStructureType sType;
void* pNext;
VkBool32 synchronization2;
} VkPhysicalDeviceSynchronization2Features;
or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkPhysicalDeviceSynchronization2Features VkPhysicalDeviceSynchronization2FeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
synchronization2indicates whether the implementation supports the new set of synchronization commands introduced inVK_KHR_synchronization2.
If the VkPhysicalDeviceSynchronization2Features structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceSynchronization2Features can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceVertexInputDynamicStateFeaturesEXT structure is
defined as:
// Provided by VK_EXT_vertex_input_dynamic_state
typedef struct VkPhysicalDeviceVertexInputDynamicStateFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 vertexInputDynamicState;
} VkPhysicalDeviceVertexInputDynamicStateFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDeviceVertexInputDynamicStateFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceVertexInputDynamicStateFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePrimitivesGeneratedQueryFeaturesEXT structure is
defined as:
// Provided by VK_EXT_primitives_generated_query
typedef struct VkPhysicalDevicePrimitivesGeneratedQueryFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 primitivesGeneratedQuery;
VkBool32 primitivesGeneratedQueryWithRasterizerDiscard;
VkBool32 primitivesGeneratedQueryWithNonZeroStreams;
} VkPhysicalDevicePrimitivesGeneratedQueryFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
primitivesGeneratedQueryindicates whether the implementation supports theVK_QUERY_TYPE_PRIMITIVES_GENERATED_EXTquery type. -
primitivesGeneratedQueryWithRasterizerDiscardindicates whether the implementation supports this query when rasterization discard is enabled. -
primitivesGeneratedQueryWithNonZeroStreamsindicates whether the implementation supports this query with a non-zero index in vkCmdBeginQueryIndexedEXT.
If the VkPhysicalDevicePrimitivesGeneratedQueryFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePrimitivesGeneratedQueryFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceFragmentShadingRateFeaturesKHR structure is
defined as:
// Provided by VK_KHR_fragment_shading_rate
typedef struct VkPhysicalDeviceFragmentShadingRateFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 pipelineFragmentShadingRate;
VkBool32 primitiveFragmentShadingRate;
VkBool32 attachmentFragmentShadingRate;
} VkPhysicalDeviceFragmentShadingRateFeaturesKHR;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineFragmentShadingRateindicates that the implementation supports the pipeline fragment shading rate. -
primitiveFragmentShadingRateindicates that the implementation supports the primitive fragment shading rate. -
attachmentFragmentShadingRateindicates that the implementation supports the attachment fragment shading rate.
If the VkPhysicalDeviceFragmentShadingRateFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceFragmentShadingRateFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceFragmentShadingRateEnumsFeaturesNV structure is
defined as:
// Provided by VK_NV_fragment_shading_rate_enums
typedef struct VkPhysicalDeviceFragmentShadingRateEnumsFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 fragmentShadingRateEnums;
VkBool32 supersampleFragmentShadingRates;
VkBool32 noInvocationFragmentShadingRates;
} VkPhysicalDeviceFragmentShadingRateEnumsFeaturesNV;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentShadingRateEnumsindicates that the implementation supports specifying fragment shading rates using theVkFragmentShadingRateNVenumerated type. -
supersampleFragmentShadingRatesindicates that the implementation supports fragment shading rate enum values indicating more than one invocation per fragment. -
noInvocationFragmentShadingRatesindicates that the implementation supports a fragment shading rate enum value indicating that no fragment shaders should be invoked when that shading rate is used.
If the VkPhysicalDeviceFragmentShadingRateEnumsFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceFragmentShadingRateEnumsFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceInheritedViewportScissorFeaturesNV structure is
defined as:
// Provided by VK_NV_inherited_viewport_scissor
typedef struct VkPhysicalDeviceInheritedViewportScissorFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 inheritedViewportScissor2D;
} VkPhysicalDeviceInheritedViewportScissorFeaturesNV;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
inheritedViewportScissor2Dindicates whether secondary command buffers can inherit most of the dynamic state affected byVK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT,VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT,VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT,VK_DYNAMIC_STATE_VIEWPORTorVK_DYNAMIC_STATE_SCISSOR, from a primary command buffer.
If the VkPhysicalDeviceInheritedViewportScissorFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceInheritedViewportScissorFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceYcbcr2Plane444FormatsFeaturesEXT structure is
defined as:
// Provided by VK_EXT_ycbcr_2plane_444_formats
typedef struct VkPhysicalDeviceYcbcr2Plane444FormatsFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 ycbcr2plane444Formats;
} VkPhysicalDeviceYcbcr2Plane444FormatsFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
ycbcr2plane444Formatsindicates that the implementation supports the following 2-plane 444 Y′CBCR formats:-
VK_FORMAT_G8_B8R8_2PLANE_444_UNORM -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_444_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_444_UNORM_3PACK16 -
VK_FORMAT_G16_B16R16_2PLANE_444_UNORM
-
If the VkPhysicalDeviceYcbcr2Plane444FormatsFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceYcbcr2Plane444FormatsFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
|
Note
Although the formats defined by the |
The VkPhysicalDeviceColorWriteEnableFeaturesEXT structure is defined
as:
// Provided by VK_EXT_color_write_enable
typedef struct VkPhysicalDeviceColorWriteEnableFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 colorWriteEnable;
} VkPhysicalDeviceColorWriteEnableFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDeviceColorWriteEnableFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceColorWriteEnableFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePipelinePropertiesFeaturesEXT structure is defined
as:
// Provided by VK_EXT_pipeline_properties
typedef struct VkPhysicalDevicePipelinePropertiesFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 pipelinePropertiesIdentifier;
} VkPhysicalDevicePipelinePropertiesFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDevicePipelinePropertiesFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePipelinePropertiesFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceProvokingVertexFeaturesEXT structure is defined
as:
// Provided by VK_EXT_provoking_vertex
typedef struct VkPhysicalDeviceProvokingVertexFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 provokingVertexLast;
VkBool32 transformFeedbackPreservesProvokingVertex;
} VkPhysicalDeviceProvokingVertexFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
provokingVertexLastindicates whether the implementation supports theVK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXTprovoking vertex mode for flat shading. -
transformFeedbackPreservesProvokingVertexindicates that the order of vertices within each primitive written by transform feedback will preserve the provoking vertex. This does not apply to triangle fan primitives whentransformFeedbackPreservesTriangleFanProvokingVertexisVK_FALSE.transformFeedbackPreservesProvokingVertexmust beVK_FALSEwhen the VK_EXT_transform_feedback extension is not supported.
If the VkPhysicalDeviceProvokingVertexFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceProvokingVertexFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
When VkPhysicalDeviceProvokingVertexFeaturesEXT is in the pNext
chain of VkDeviceCreateInfo but the transformFeedback feature is not enabled, the value of
transformFeedbackPreservesProvokingVertex is ignored.
The VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT structure is
defined as:
// Provided by VK_EXT_pageable_device_local_memory
typedef struct VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 pageableDeviceLocalMemory;
} VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pageableDeviceLocalMemoryindicates that the implementation supports pageable device-local memory and may transparently move device-local memory allocations to host-local memory to better share device-local memory with other applications.
If the VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceMultiDrawFeaturesEXT structure is defined as:
// Provided by VK_EXT_multi_draw
typedef struct VkPhysicalDeviceMultiDrawFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 multiDraw;
} VkPhysicalDeviceMultiDrawFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
multiDrawindicates that the implementation supports vkCmdDrawMultiEXT and vkCmdDrawMultiIndexedEXT.
If the VkPhysicalDeviceMultiDrawFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceMultiDrawFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceRayTracingMotionBlurFeaturesNV structure is
defined as:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkPhysicalDeviceRayTracingMotionBlurFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 rayTracingMotionBlur;
VkBool32 rayTracingMotionBlurPipelineTraceRaysIndirect;
} VkPhysicalDeviceRayTracingMotionBlurFeaturesNV;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rayTracingMotionBlurindicates whether the implementation supports the motion blur feature. -
rayTracingMotionBlurPipelineTraceRaysIndirectindicates whether the implementation supports indirect ray tracing commands with the motion blur feature enabled.
If the VkPhysicalDeviceRayTracingMotionBlurFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceRayTracingMotionBlurFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceSubpassShadingFeaturesHUAWEI structure is defined
as:
// Provided by VK_HUAWEI_subpass_shading
typedef struct VkPhysicalDeviceSubpassShadingFeaturesHUAWEI {
VkStructureType sType;
void* pNext;
VkBool32 subpassShading;
} VkPhysicalDeviceSubpassShadingFeaturesHUAWEI;
This structure describes the following feature:
If the VkPhysicalDeviceSubpassShadingFeaturesHUAWEI structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceSubpassShadingFeaturesHUAWEI can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceExternalMemoryRDMAFeaturesNV structure is defined
as:
// Provided by VK_NV_external_memory_rdma
typedef struct VkPhysicalDeviceExternalMemoryRDMAFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 externalMemoryRDMA;
} VkPhysicalDeviceExternalMemoryRDMAFeaturesNV;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalMemoryRDMAindicates whether the implementation has support for theVK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NVmemory property and theVK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NVexternal memory handle type.
If the VkPhysicalDeviceExternalMemoryRDMAFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceExternalMemoryRDMAFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePresentIdFeaturesKHR structure is defined as:
// Provided by VK_KHR_present_id
typedef struct VkPhysicalDevicePresentIdFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 presentId;
} VkPhysicalDevicePresentIdFeaturesKHR;
This structure describes the following feature:
If the VkPhysicalDevicePresentIdFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePresentIdFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePresentWaitFeaturesKHR structure is defined as:
// Provided by VK_KHR_present_wait
typedef struct VkPhysicalDevicePresentWaitFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 presentWait;
} VkPhysicalDevicePresentWaitFeaturesKHR;
This structure describes the following feature:
If the VkPhysicalDevicePresentWaitFeaturesKHR structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePresentWaitFeaturesKHR can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderIntegerDotProductFeatures structure is
defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceShaderIntegerDotProductFeatures {
VkStructureType sType;
void* pNext;
VkBool32 shaderIntegerDotProduct;
} VkPhysicalDeviceShaderIntegerDotProductFeatures;
or the equivalent
// Provided by VK_KHR_shader_integer_dot_product
typedef VkPhysicalDeviceShaderIntegerDotProductFeatures VkPhysicalDeviceShaderIntegerDotProductFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceShaderIntegerDotProductFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderIntegerDotProductFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceMaintenance4Features structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceMaintenance4Features {
VkStructureType sType;
void* pNext;
VkBool32 maintenance4;
} VkPhysicalDeviceMaintenance4Features;
or the equivalent
// Provided by VK_KHR_maintenance4
typedef VkPhysicalDeviceMaintenance4Features VkPhysicalDeviceMaintenance4FeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
maintenance4indicates that the implementation supports the following:-
The application may destroy a VkPipelineLayout object immediately after using it to create another object.
-
LocalSizeIdcan be used as an alternative toLocalSizeto specify the local workgroup size with specialization constants. -
Images created with identical creation parameters will always have the same alignment requirements.
-
The size memory requirement of a buffer or image is never greater than that of another buffer or image created with a greater or equal size.
-
Push constants do not have to be initialized before they are dynamically accessed.
-
The interface matching rules allow a larger output vector to match with a smaller input vector, with additional values being discarded.
-
If the VkPhysicalDeviceMaintenance4Features structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceMaintenance4Features can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceDynamicRenderingFeatures structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceDynamicRenderingFeatures {
VkStructureType sType;
void* pNext;
VkBool32 dynamicRendering;
} VkPhysicalDeviceDynamicRenderingFeatures;
or the equivalent
// Provided by VK_KHR_dynamic_rendering
typedef VkPhysicalDeviceDynamicRenderingFeatures VkPhysicalDeviceDynamicRenderingFeaturesKHR;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
dynamicRenderingspecifies that the implementation supports dynamic render pass instances using the vkCmdBeginRendering command.
If the VkPhysicalDeviceDynamicRenderingFeatures structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceDynamicRenderingFeatures can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT structure is defined
as:
// Provided by VK_EXT_rgba10x6_formats
typedef struct VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 formatRgba10x6WithoutYCbCrSampler;
} VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT;
This structure describe the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatRgba10x6WithoutYCbCrSamplerindicates thatVK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16can be used with aVkImageViewwithsubresourceRange.aspectMaskequal toVK_IMAGE_ASPECT_COLOR_BITwithout a sampler Y′CBCR conversion enabled.
If the VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDevicePipelineRobustnessFeaturesEXT structure is defined
as:
// Provided by VK_EXT_pipeline_robustness
typedef struct VkPhysicalDevicePipelineRobustnessFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 pipelineRobustness;
} VkPhysicalDevicePipelineRobustnessFeaturesEXT;
The members of the VkPhysicalDevicePipelineRobustnessFeaturesEXT
structure describe the following features:
|
Note
Enabling |
If the VkPhysicalDevicePipelineRobustnessFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDevicePipelineRobustnessFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceImageViewMinLodFeaturesEXT structure is defined
as:
// Provided by VK_EXT_image_view_min_lod
typedef struct VkPhysicalDeviceImageViewMinLodFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 minLod;
} VkPhysicalDeviceImageViewMinLodFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minLodindicates whether the implementation supports clamping the minimum LOD value during Image Level(s) Selection and Integer Texel Coordinate Operations with a given VkImageView by VkImageViewMinLodCreateInfoEXT::minLod.
If the VkPhysicalDeviceImageViewMinLodFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceImageViewMinLodFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesARM
structure is defined as:
// Provided by VK_ARM_rasterization_order_attachment_access
typedef struct VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesARM {
VkStructureType sType;
void* pNext;
VkBool32 rasterizationOrderColorAttachmentAccess;
VkBool32 rasterizationOrderDepthAttachmentAccess;
VkBool32 rasterizationOrderStencilAttachmentAccess;
} VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesARM;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rasterizationOrderColorAttachmentAccessindicates that rasterization order access to color and input attachments is supported by the implementation. -
rasterizationOrderDepthAttachmentAccessindicates that rasterization order access to the depth aspect of depth/stencil and input attachments is supported by the implementation. -
rasterizationOrderStencilAttachmentAccessindicates that rasterization order access to the stencil aspect of depth/stencil and input attachments is supported by the implementation.
If the VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesARM structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesARM can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceSubpassMergeFeedbackFeaturesEXT structure is
defined as:
// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkPhysicalDeviceSubpassMergeFeedbackFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 subpassMergeFeedback;
} VkPhysicalDeviceSubpassMergeFeedbackFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDeviceSubpassMergeFeedbackFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceSubpassMergeFeedbackFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceLinearColorAttachmentFeaturesNV structure is
defined as:
// Provided by VK_NV_linear_color_attachment
typedef struct VkPhysicalDeviceLinearColorAttachmentFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 linearColorAttachment;
} VkPhysicalDeviceLinearColorAttachmentFeaturesNV;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
linearColorAttachmentindicates whether the implementation supports renderable Linear Color Attachment
If the VkPhysicalDeviceLinearColorAttachmentFeaturesNV structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceLinearColorAttachmentFeaturesNV can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceGraphicsPipelineLibraryFeaturesEXT structure is
defined as:
// Provided by VK_EXT_graphics_pipeline_library
typedef struct VkPhysicalDeviceGraphicsPipelineLibraryFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 graphicsPipelineLibrary;
} VkPhysicalDeviceGraphicsPipelineLibraryFeaturesEXT;
This structure describes the following feature:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
graphicsPipelineLibraryindicates that the implementation supports graphics pipeline libraries.
If the VkPhysicalDeviceGraphicsPipelineLibraryFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceGraphicsPipelineLibraryFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceMultisampledRenderToSingleSampledFeaturesEXT
structure is defined as:
// Provided by VK_EXT_multisampled_render_to_single_sampled
typedef struct VkPhysicalDeviceMultisampledRenderToSingleSampledFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 multisampledRenderToSingleSampled;
} VkPhysicalDeviceMultisampledRenderToSingleSampledFeaturesEXT;
This structure describes the following features:
If the VkPhysicalDeviceMultisampledRenderToSingleSampledFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceMultisampledRenderToSingleSampledFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceImage2DViewOf3DFeaturesEXT structure is defined
as:
// Provided by VK_EXT_image_2d_view_of_3d
typedef struct VkPhysicalDeviceImage2DViewOf3DFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 image2DViewOf3D;
VkBool32 sampler2DViewOf3D;
} VkPhysicalDeviceImage2DViewOf3DFeaturesEXT;
This structure describes the following features:
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
image2DViewOf3Dindicates that the implementation supports using a 2D view of a 3D image in a descriptor of typeVK_DESCRIPTOR_TYPE_STORAGE_IMAGEif the image is created usingVK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT. -
sampler2DViewOf3Dindicates that the implementation supports using a 2D view of a 3D image in a descriptor of typeVK_DESCRIPTOR_TYPE_SAMPLED_IMAGEorVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERif the image is created usingVK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT.
If the VkPhysicalDeviceImage2DViewOf3DFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceImage2DViewOf3DFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceImageCompressionControlFeaturesEXT structure is
defined as:
// Provided by VK_EXT_image_compression_control
typedef struct VkPhysicalDeviceImageCompressionControlFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 imageCompressionControl;
} VkPhysicalDeviceImageCompressionControlFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDeviceImageCompressionControlFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceImageCompressionControlFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceImageCompressionControlSwapchainFeaturesEXT
structure is defined as:
// Provided by VK_EXT_image_compression_control_swapchain
typedef struct VkPhysicalDeviceImageCompressionControlSwapchainFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 imageCompressionControlSwapchain;
} VkPhysicalDeviceImageCompressionControlSwapchainFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDeviceImageCompressionControlSwapchainFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceImageCompressionControlSwapchainFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderEarlyAndLateFragmentTestsFeaturesAMD
structure is defined as:
// Provided by VK_AMD_shader_early_and_late_fragment_tests
typedef struct VkPhysicalDeviceShaderEarlyAndLateFragmentTestsFeaturesAMD {
VkStructureType sType;
void* pNext;
VkBool32 shaderEarlyAndLateFragmentTests;
} VkPhysicalDeviceShaderEarlyAndLateFragmentTestsFeaturesAMD;
This structure describes the following feature:
If the VkPhysicalDeviceShaderEarlyAndLateFragmentTestsFeaturesAMD structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderEarlyAndLateFragmentTestsFeaturesAMD can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceNonSeamlessCubeMapFeaturesEXT structure is defined
as:
// Provided by VK_EXT_non_seamless_cube_map
typedef struct VkPhysicalDeviceNonSeamlessCubeMapFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 nonSeamlessCubeMap;
} VkPhysicalDeviceNonSeamlessCubeMapFeaturesEXT;
This structure describes the following feature:
If the VkPhysicalDeviceNonSeamlessCubeMapFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceNonSeamlessCubeMapFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
The VkPhysicalDeviceShaderModuleIdentifierFeaturesEXT structure is
defined as:
// Provided by VK_EXT_shader_module_identifier
typedef struct VkPhysicalDeviceShaderModuleIdentifierFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 shaderModuleIdentifier;
} VkPhysicalDeviceShaderModuleIdentifierFeaturesEXT;
This structure describes the following features:
-
shaderModuleIdentifierindicates whether the implementation supports querying an identifier of a VkShaderModule or VkShaderModuleCreateInfo structure, and creating pipelines from identifiers only.
If the VkPhysicalDeviceShaderModuleIdentifierFeaturesEXT structure is included in the pNext chain of the
VkPhysicalDeviceFeatures2 structure passed to
vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each
corresponding feature is supported.
VkPhysicalDeviceShaderModuleIdentifierFeaturesEXT can also be used in the pNext chain of
VkDeviceCreateInfo to selectively enable these features.
41.1. Feature Requirements
All Vulkan graphics implementations must support the following features:
-
robustBufferAccess, unless theVK_KHR_portability_subsetextension is enabled. -
multiview, if Vulkan 1.1 is supported. -
shaderDrawParameters, if theVK_KHR_shader_draw_parametersextension is supported. -
uniformBufferStandardLayout, if Vulkan 1.2 or theVK_KHR_uniform_buffer_standard_layoutextension is supported. -
variablePointersStorageBuffer, if theVK_KHR_variable_pointersextension is supported. -
storageBuffer8BitAccess, if theVK_KHR_8bit_storageextension is supported. -
storageBuffer8BitAccess, ifuniformAndStorageBuffer8BitAccessis enabled. -
If the
descriptorIndexingfeature is supported, or if theVK_EXT_descriptor_indexingextension is supported: -
If Vulkan 1.3 is supported:
-
inlineUniformBlock, if Vulkan 1.3 or theVK_EXT_inline_uniform_blockextension is supported. -
descriptorBindingInlineUniformBlockUpdateAfterBind, if Vulkan 1.3 or theVK_EXT_inline_uniform_blockextension is supported; and if thedescriptorIndexingfeature is supported, or theVK_EXT_descriptor_indexingextension is supported. -
scalarBlockLayout, if theVK_EXT_scalar_block_layoutextension is supported. -
subgroupBroadcastDynamicId, if Vulkan 1.2 is supported. -
samplerMirrorClampToEdge, if theVK_KHR_sampler_mirror_clamp_to_edgeextension is supported. -
drawIndirectCount, if theVK_KHR_draw_indirect_countextension is supported. -
samplerFilterMinmax, if theVK_EXT_sampler_filter_minmaxextension is supported. -
shaderOutputViewportIndex, if theVK_EXT_shader_viewport_index_layerextension is supported. -
shaderOutputLayer, if theVK_EXT_shader_viewport_index_layerextension is supported. -
subgroupSizeControl, if Vulkan 1.3 or theVK_EXT_subgroup_size_controlextension is supported. -
computeFullSubgroups, if Vulkan 1.3 or theVK_EXT_subgroup_size_controlextension is supported. -
deviceMemoryReport, if theVK_EXT_device_memory_reportextension is supported. -
globalPriorityQuery, if theVK_EXT_global_priority_queryextension is supported. -
globalPriorityQuery, if theVK_KHR_global_priorityextension is supported. -
imagelessFramebuffer, if Vulkan 1.2 or theVK_KHR_imageless_framebufferextension is supported. -
separateDepthStencilLayouts, if Vulkan 1.2 or theVK_KHR_separate_depth_stencil_layoutsextension is supported. -
hostQueryReset, if Vulkan 1.2 or theVK_EXT_host_query_resetextension is supported. -
timelineSemaphore, if Vulkan 1.2 or theVK_KHR_timeline_semaphoreextension is supported. -
If the
VK_KHR_acceleration_structureextension is supported:-
All the features required by the
descriptorIndexingfeature if Vulkan 1.2 is supported, or theVK_EXT_descriptor_indexingextension. -
bufferDeviceAddressfrom Vulkan 1.2 or theVK_KHR_buffer_device_addressextension.
-
If the
VK_KHR_ray_tracing_pipelineextension is supported:-
rayTraversalPrimitiveCulling, ifrayQueryis supported -
the
VK_KHR_pipeline_libraryextension must be supported.
-
rayQuery, if theVK_KHR_ray_queryextension is supported. -
pipelineCreationCacheControl, if Vulkan 1.3 or theVK_EXT_pipeline_creation_cache_controlextension is supported. -
shaderSubgroupExtendedTypes, if Vulkan 1.2 or theVK_KHR_shader_subgroup_extended_typesextension is supported. -
samplerYcbcrConversion, if theVK_KHR_sampler_ycbcr_conversionextension is supported. -
pipelineExecutableInfo, if theVK_KHR_pipeline_executable_propertiesextension is supported. -
textureCompressionASTC_HDR, if theVK_EXT_texture_compression_astc_hdrextension is supported. -
depthClipEnable, if theVK_EXT_depth_clip_enableextension is supported. -
memoryPriority, if theVK_EXT_memory_priorityextension is supported. -
ycbcrImageArrays, if theVK_EXT_ycbcr_image_arraysextension is supported. -
indexTypeUint8, if theVK_EXT_index_type_uint8extension is supported. -
primitiveTopologyListRestart, if theVK_EXT_primitive_topology_list_restartextension is supported. -
shaderDemoteToHelperInvocation, if Vulkan 1.3 or theVK_EXT_shader_demote_to_helper_invocationextension is supported. -
texelBufferAlignment, if Vulkan 1.3 or theVK_EXT_texel_buffer_alignmentextension is supported. -
vulkanMemoryModel, if theVK_KHR_vulkan_memory_modelextension is supported. -
bufferDeviceAddress, if Vulkan 1.3 or theVK_KHR_buffer_device_addressextension is supported. -
performanceCounterQueryPools, if theVK_KHR_performance_queryextension is supported. -
transformFeedback, if theVK_EXT_transform_feedbackextension is supported. -
conditionalRendering, if theVK_EXT_conditional_renderingextension is supported. -
vertexAttributeInstanceRateDivisor, if theVK_EXT_vertex_attribute_divisorextension is supported. -
fragmentDensityMap, if theVK_EXT_fragment_density_mapextension is supported. -
shaderSubgroupClock, if theVK_KHR_shader_clockextension is supported. -
shaderBufferInt64Atomics, if theVK_KHR_shader_atomic_int64extension is supported. -
shaderInt64, if theshaderSharedInt64AtomicsorshaderBufferInt64Atomicsfeatures are supported. -
shaderFloat16orshaderInt8, if theVK_KHR_shader_float16_int8extension is supported. -
fragmentShaderSampleInterlockorfragmentShaderPixelInterlockorfragmentShaderShadingRateInterlock, if theVK_EXT_fragment_shader_interlockextension is supported. -
rectangularLinesorbresenhamLinesorsmoothLinesorstippledRectangularLinesorstippledBresenhamLinesorstippledSmoothLines, if theVK_EXT_line_rasterizationextension is supported. -
storageBuffer16BitAccess, if theVK_KHR_16bit_storageextension is supported. -
storageBuffer16BitAccess, ifuniformAndStorageBuffer16BitAccessis enabled. -
robustImageAccess, if Vulkan 1.3 or theVK_EXT_image_robustnessextension is supported. -
formatA4R4G4B4, if theVK_EXT_4444_formatsextension is supported. -
mutableDescriptorType, if theVK_VALVE_mutable_descriptor_typeextension is supported. -
shaderInt64andshaderImageInt64Atomics, if theVK_EXT_shader_image_atomic_int64extension is supported. -
shaderImageInt64Atomics, if thesparseImageInt64Atomicsfeature is supported. -
shaderImageFloat32Atomics, if thesparseImageFloat32Atomicsfeature is supported. -
shaderImageFloat32AtomicAdd, if thesparseImageFloat32AtomicAddfeature is supported. -
primitivesGeneratedQuery, if theVK_EXT_primitives_generated_queryextension is supported. -
pipelineFragmentShadingRate, if theVK_KHR_fragment_shading_rateextension is supported. -
shaderTerminateInvocationif Vulkan 1.3 or theVK_KHR_shader_terminate_invocationextension is supported. -
shaderZeroInitializeWorkgroupMemory, if Vulkan 1.3 or theVK_KHR_zero_initialize_workgroup_memoryextension is supported. -
workgroupMemoryExplicitLayout, if theVK_KHR_workgroup_memory_explicit_layoutextension is supported. -
vertexInputDynamicState, if theVK_EXT_vertex_input_dynamic_stateextension is supported. -
synchronization2if Vulkan 1.3 or theVK_KHR_synchronization2extension is supported. -
provokingVertexLast, if theVK_EXT_provoking_vertexextension is supported. -
shaderSubgroupUniformControlFlow, if theVK_KHR_shader_subgroup_uniform_control_flowextension is supported. -
borderColorSwizzleif the VK_EXT_border_color_swizzle extension is supported. -
multiDraw, if theVK_EXT_multi_drawextension is supported. -
shaderImageFloat32AtomicMinMax, if thesparseImageFloat32AtomicMinMaxfeature is supported. -
presentId, if theVK_KHR_present_idextension is supported. -
presentWait, if theVK_KHR_present_waitextension is supported. -
shaderIntegerDotProductif Vulkan 1.3 or theVK_KHR_shader_integer_dot_productextension is supported. -
maintenance4, if Vulkan 1.3 or theVK_KHR_maintenance4extension is supported. -
image2DViewOf3D, if theVK_EXT_image_2d_view_of_3dextension is supported. -
privateData, if Vulkan 1.3 or theVK_EXT_private_dataextension is supported. -
extendedDynamicState, if theVK_EXT_extended_dynamic_stateextension is supported. -
extendedDynamicState2, if theVK_EXT_extended_dynamic_state2extension is supported. -
depthClipControl, if theVK_EXT_depth_clip_controlextension is supported. -
minLod, if theVK_EXT_image_view_min_lodextension is supported. -
linearColorAttachment, if theVK_NV_linear_color_attachmentextension is supported. -
graphicsPipelineLibrary, if theVK_EXT_graphics_pipeline_libraryextension is supported. -
dynamicRendering, if Vulkan 1.3 or theVK_KHR_dynamic_renderingextension is supported. -
subpassMergeFeedback, if theVK_EXT_subpass_merge_feedbackextension is supported. -
rayTracingMaintenance1, if theVK_KHR_ray_tracing_maintenance1extension is supported. -
colorWriteEnable, if theVK_EXT_color_write_enableextension is supported. -
multisampledRenderToSingleSampled, if theVK_EXT_multisampled_render_to_single_sampledextension is supported. -
imageCompressionControl, if theVK_EXT_image_compression_controlextension is supported. -
imageCompressionControlSwapchain, if theVK_EXT_image_compression_control_swapchainextension is supported. -
shaderEarlyAndLateFragmentTests, if theVK_AMD_shader_early_and_late_fragment_testsextension is supported. -
nonSeamlessCubeMap, if theVK_EXT_non_seamless_cube_mapextension is supported. -
shaderModuleIdentifier, ifVK_EXT_shader_module_identifierextension is supported. -
pipelineRobustness, if theVK_EXT_pipeline_robustnessextension is supported.
All other features defined in the Specification are optional.
41.2. Profile Features
41.2.1. Roadmap 2022
Implementations that claim support for the Roadmap 2022 profile must support the following features:
42. Limits
Limits are implementation-dependent minimums, maximums, and other device characteristics that an application may need to be aware of.
|
Note
Limits are reported via the basic VkPhysicalDeviceLimits structure as
well as the extensible structure |
The VkPhysicalDeviceLimits structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPhysicalDeviceLimits {
uint32_t maxImageDimension1D;
uint32_t maxImageDimension2D;
uint32_t maxImageDimension3D;
uint32_t maxImageDimensionCube;
uint32_t maxImageArrayLayers;
uint32_t maxTexelBufferElements;
uint32_t maxUniformBufferRange;
uint32_t maxStorageBufferRange;
uint32_t maxPushConstantsSize;
uint32_t maxMemoryAllocationCount;
uint32_t maxSamplerAllocationCount;
VkDeviceSize bufferImageGranularity;
VkDeviceSize sparseAddressSpaceSize;
uint32_t maxBoundDescriptorSets;
uint32_t maxPerStageDescriptorSamplers;
uint32_t maxPerStageDescriptorUniformBuffers;
uint32_t maxPerStageDescriptorStorageBuffers;
uint32_t maxPerStageDescriptorSampledImages;
uint32_t maxPerStageDescriptorStorageImages;
uint32_t maxPerStageDescriptorInputAttachments;
uint32_t maxPerStageResources;
uint32_t maxDescriptorSetSamplers;
uint32_t maxDescriptorSetUniformBuffers;
uint32_t maxDescriptorSetUniformBuffersDynamic;
uint32_t maxDescriptorSetStorageBuffers;
uint32_t maxDescriptorSetStorageBuffersDynamic;
uint32_t maxDescriptorSetSampledImages;
uint32_t maxDescriptorSetStorageImages;
uint32_t maxDescriptorSetInputAttachments;
uint32_t maxVertexInputAttributes;
uint32_t maxVertexInputBindings;
uint32_t maxVertexInputAttributeOffset;
uint32_t maxVertexInputBindingStride;
uint32_t maxVertexOutputComponents;
uint32_t maxTessellationGenerationLevel;
uint32_t maxTessellationPatchSize;
uint32_t maxTessellationControlPerVertexInputComponents;
uint32_t maxTessellationControlPerVertexOutputComponents;
uint32_t maxTessellationControlPerPatchOutputComponents;
uint32_t maxTessellationControlTotalOutputComponents;
uint32_t maxTessellationEvaluationInputComponents;
uint32_t maxTessellationEvaluationOutputComponents;
uint32_t maxGeometryShaderInvocations;
uint32_t maxGeometryInputComponents;
uint32_t maxGeometryOutputComponents;
uint32_t maxGeometryOutputVertices;
uint32_t maxGeometryTotalOutputComponents;
uint32_t maxFragmentInputComponents;
uint32_t maxFragmentOutputAttachments;
uint32_t maxFragmentDualSrcAttachments;
uint32_t maxFragmentCombinedOutputResources;
uint32_t maxComputeSharedMemorySize;
uint32_t maxComputeWorkGroupCount[3];
uint32_t maxComputeWorkGroupInvocations;
uint32_t maxComputeWorkGroupSize[3];
uint32_t subPixelPrecisionBits;
uint32_t subTexelPrecisionBits;
uint32_t mipmapPrecisionBits;
uint32_t maxDrawIndexedIndexValue;
uint32_t maxDrawIndirectCount;
float maxSamplerLodBias;
float maxSamplerAnisotropy;
uint32_t maxViewports;
uint32_t maxViewportDimensions[2];
float viewportBoundsRange[2];
uint32_t viewportSubPixelBits;
size_t minMemoryMapAlignment;
VkDeviceSize minTexelBufferOffsetAlignment;
VkDeviceSize minUniformBufferOffsetAlignment;
VkDeviceSize minStorageBufferOffsetAlignment;
int32_t minTexelOffset;
uint32_t maxTexelOffset;
int32_t minTexelGatherOffset;
uint32_t maxTexelGatherOffset;
float minInterpolationOffset;
float maxInterpolationOffset;
uint32_t subPixelInterpolationOffsetBits;
uint32_t maxFramebufferWidth;
uint32_t maxFramebufferHeight;
uint32_t maxFramebufferLayers;
VkSampleCountFlags framebufferColorSampleCounts;
VkSampleCountFlags framebufferDepthSampleCounts;
VkSampleCountFlags framebufferStencilSampleCounts;
VkSampleCountFlags framebufferNoAttachmentsSampleCounts;
uint32_t maxColorAttachments;
VkSampleCountFlags sampledImageColorSampleCounts;
VkSampleCountFlags sampledImageIntegerSampleCounts;
VkSampleCountFlags sampledImageDepthSampleCounts;
VkSampleCountFlags sampledImageStencilSampleCounts;
VkSampleCountFlags storageImageSampleCounts;
uint32_t maxSampleMaskWords;
VkBool32 timestampComputeAndGraphics;
float timestampPeriod;
uint32_t maxClipDistances;
uint32_t maxCullDistances;
uint32_t maxCombinedClipAndCullDistances;
uint32_t discreteQueuePriorities;
float pointSizeRange[2];
float lineWidthRange[2];
float pointSizeGranularity;
float lineWidthGranularity;
VkBool32 strictLines;
VkBool32 standardSampleLocations;
VkDeviceSize optimalBufferCopyOffsetAlignment;
VkDeviceSize optimalBufferCopyRowPitchAlignment;
VkDeviceSize nonCoherentAtomSize;
} VkPhysicalDeviceLimits;
The VkPhysicalDeviceLimits are properties of the physical device.
These are available in the limits member of the
VkPhysicalDeviceProperties structure which is returned from
vkGetPhysicalDeviceProperties.
-
maxImageDimension1Dis the largest dimension (width) that is guaranteed to be supported for all images created with animageTypeofVK_IMAGE_TYPE_1D. Some combinations of image parameters (format, usage, etc.) may allow support for larger dimensions, which can be queried using vkGetPhysicalDeviceImageFormatProperties. -
maxImageDimension2Dis the largest dimension (widthorheight) that is guaranteed to be supported for all images created with animageTypeofVK_IMAGE_TYPE_2Dand withoutVK_IMAGE_CREATE_CUBE_COMPATIBLE_BITset inflags. Some combinations of image parameters (format, usage, etc.) may allow support for larger dimensions, which can be queried using vkGetPhysicalDeviceImageFormatProperties. -
maxImageDimension3Dis the largest dimension (width,height, ordepth) that is guaranteed to be supported for all images created with animageTypeofVK_IMAGE_TYPE_3D. Some combinations of image parameters (format, usage, etc.) may allow support for larger dimensions, which can be queried using vkGetPhysicalDeviceImageFormatProperties. -
maxImageDimensionCubeis the largest dimension (widthorheight) that is guaranteed to be supported for all images created with animageTypeofVK_IMAGE_TYPE_2Dand withVK_IMAGE_CREATE_CUBE_COMPATIBLE_BITset inflags. Some combinations of image parameters (format, usage, etc.) may allow support for larger dimensions, which can be queried using vkGetPhysicalDeviceImageFormatProperties. -
maxImageArrayLayersis the maximum number of layers (arrayLayers) for an image. -
maxTexelBufferElementsis the maximum number of addressable texels for a buffer view created on a buffer which was created with theVK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BITorVK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BITset in theusagemember of the VkBufferCreateInfo structure. -
maxUniformBufferRangeis the maximum value that can be specified in therangemember of a VkDescriptorBufferInfo structure passed to vkUpdateDescriptorSets for descriptors of typeVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC. -
maxStorageBufferRangeis the maximum value that can be specified in therangemember of a VkDescriptorBufferInfo structure passed to vkUpdateDescriptorSets for descriptors of typeVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC. -
maxPushConstantsSizeis the maximum size, in bytes, of the pool of push constant memory. For each of the push constant ranges indicated by thepPushConstantRangesmember of the VkPipelineLayoutCreateInfo structure, (offset+size) must be less than or equal to this limit. -
maxMemoryAllocationCountis the maximum number of device memory allocations, as created by vkAllocateMemory, which can simultaneously exist. -
maxSamplerAllocationCountis the maximum number of sampler objects, as created by vkCreateSampler, which can simultaneously exist on a device. -
bufferImageGranularityis the granularity, in bytes, at which buffer or linear image resources, and optimal image resources can be bound to adjacent offsets in the sameVkDeviceMemoryobject without aliasing. See Buffer-Image Granularity for more details. -
sparseAddressSpaceSizeis the total amount of address space available, in bytes, for sparse memory resources. This is an upper bound on the sum of the sizes of all sparse resources, regardless of whether any memory is bound to them. -
maxBoundDescriptorSetsis the maximum number of descriptor sets that can be simultaneously used by a pipeline. AllDescriptorSetdecorations in shader modules must have a value less thanmaxBoundDescriptorSets. See Descriptor Sets. -
maxPerStageDescriptorSamplersis the maximum number of samplers that can be accessible to a single shader stage in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_SAMPLERorVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. A descriptor is accessible to a shader stage when thestageFlagsmember of theVkDescriptorSetLayoutBindingstructure has the bit for that shader stage set. See Sampler and Combined Image Sampler. -
maxPerStageDescriptorUniformBuffersis the maximum number of uniform buffers that can be accessible to a single shader stage in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMICcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. A descriptor is accessible to a shader stage when thestageFlagsmember of theVkDescriptorSetLayoutBindingstructure has the bit for that shader stage set. See Uniform Buffer and Dynamic Uniform Buffer. -
maxPerStageDescriptorStorageBuffersis the maximum number of storage buffers that can be accessible to a single shader stage in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMICcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. A descriptor is accessible to a pipeline shader stage when thestageFlagsmember of theVkDescriptorSetLayoutBindingstructure has the bit for that shader stage set. See Storage Buffer and Dynamic Storage Buffer. -
maxPerStageDescriptorSampledImagesis the maximum number of sampled images that can be accessible to a single shader stage in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, orVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. A descriptor is accessible to a pipeline shader stage when thestageFlagsmember of theVkDescriptorSetLayoutBindingstructure has the bit for that shader stage set. See Combined Image Sampler, Sampled Image, and Uniform Texel Buffer. -
maxPerStageDescriptorStorageImagesis the maximum number of storage images that can be accessible to a single shader stage in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_STORAGE_IMAGE, orVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. A descriptor is accessible to a pipeline shader stage when thestageFlagsmember of theVkDescriptorSetLayoutBindingstructure has the bit for that shader stage set. See Storage Image, and Storage Texel Buffer. -
maxPerStageDescriptorInputAttachmentsis the maximum number of input attachments that can be accessible to a single shader stage in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. A descriptor is accessible to a pipeline shader stage when thestageFlagsmember of theVkDescriptorSetLayoutBindingstructure has the bit for that shader stage set. These are only supported for the fragment stage. See Input Attachment. -
maxPerStageResourcesis the maximum number of resources that can be accessible to a single shader stage in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,VK_DESCRIPTOR_TYPE_STORAGE_IMAGE,VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER,VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER,VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER,VK_DESCRIPTOR_TYPE_STORAGE_BUFFER,VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC,VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, orVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. For the fragment shader stage the framebuffer color attachments also count against this limit. -
maxDescriptorSetSamplersis the maximum number of samplers that can be included in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_SAMPLERorVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. See Sampler and Combined Image Sampler. -
maxDescriptorSetUniformBuffersis the maximum number of uniform buffers that can be included in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMICcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. See Uniform Buffer and Dynamic Uniform Buffer. -
maxDescriptorSetUniformBuffersDynamicis the maximum number of dynamic uniform buffers that can be included in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMICcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. See Dynamic Uniform Buffer. -
maxDescriptorSetStorageBuffersis the maximum number of storage buffers that can be included in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMICcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. See Storage Buffer and Dynamic Storage Buffer. -
maxDescriptorSetStorageBuffersDynamicis the maximum number of dynamic storage buffers that can be included in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMICcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. See Dynamic Storage Buffer. -
maxDescriptorSetSampledImagesis the maximum number of sampled images that can be included in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, orVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. See Combined Image Sampler, Sampled Image, and Uniform Texel Buffer. -
maxDescriptorSetStorageImagesis the maximum number of storage images that can be included in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_STORAGE_IMAGE, orVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. See Storage Image, and Storage Texel Buffer. -
maxDescriptorSetInputAttachmentsis the maximum number of input attachments that can be included in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTcount against this limit. Only descriptors in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. See Input Attachment. -
maxVertexInputAttributesis the maximum number of vertex input attributes that can be specified for a graphics pipeline. These are described in the array ofVkVertexInputAttributeDescriptionstructures that are provided at graphics pipeline creation time via thepVertexAttributeDescriptionsmember of the VkPipelineVertexInputStateCreateInfo structure. See Vertex Attributes and Vertex Input Description. -
maxVertexInputBindingsis the maximum number of vertex buffers that can be specified for providing vertex attributes to a graphics pipeline. These are described in the array ofVkVertexInputBindingDescriptionstructures that are provided at graphics pipeline creation time via thepVertexBindingDescriptionsmember of the VkPipelineVertexInputStateCreateInfo structure. Thebindingmember ofVkVertexInputBindingDescriptionmust be less than this limit. See Vertex Input Description. -
maxVertexInputAttributeOffsetis the maximum vertex input attribute offset that can be added to the vertex input binding stride. Theoffsetmember of theVkVertexInputAttributeDescriptionstructure must be less than or equal to this limit. See Vertex Input Description. -
maxVertexInputBindingStrideis the maximum vertex input binding stride that can be specified in a vertex input binding. Thestridemember of theVkVertexInputBindingDescriptionstructure must be less than or equal to this limit. See Vertex Input Description. -
maxVertexOutputComponentsis the maximum number of components of output variables which can be output by a vertex shader. See Vertex Shaders. -
maxTessellationGenerationLevelis the maximum tessellation generation level supported by the fixed-function tessellation primitive generator. See Tessellation. -
maxTessellationPatchSizeis the maximum patch size, in vertices, of patches that can be processed by the tessellation control shader and tessellation primitive generator. ThepatchControlPointsmember of the VkPipelineTessellationStateCreateInfo structure specified at pipeline creation time and the value provided in theOutputVerticesexecution mode of shader modules must be less than or equal to this limit. See Tessellation. -
maxTessellationControlPerVertexInputComponentsis the maximum number of components of input variables which can be provided as per-vertex inputs to the tessellation control shader stage. -
maxTessellationControlPerVertexOutputComponentsis the maximum number of components of per-vertex output variables which can be output from the tessellation control shader stage. -
maxTessellationControlPerPatchOutputComponentsis the maximum number of components of per-patch output variables which can be output from the tessellation control shader stage. -
maxTessellationControlTotalOutputComponentsis the maximum total number of components of per-vertex and per-patch output variables which can be output from the tessellation control shader stage. -
maxTessellationEvaluationInputComponentsis the maximum number of components of input variables which can be provided as per-vertex inputs to the tessellation evaluation shader stage. -
maxTessellationEvaluationOutputComponentsis the maximum number of components of per-vertex output variables which can be output from the tessellation evaluation shader stage. -
maxGeometryShaderInvocationsis the maximum invocation count supported for instanced geometry shaders. The value provided in theInvocationsexecution mode of shader modules must be less than or equal to this limit. See Geometry Shading. -
maxGeometryInputComponentsis the maximum number of components of input variables which can be provided as inputs to the geometry shader stage. -
maxGeometryOutputComponentsis the maximum number of components of output variables which can be output from the geometry shader stage. -
maxGeometryOutputVerticesis the maximum number of vertices which can be emitted by any geometry shader. -
maxGeometryTotalOutputComponentsis the maximum total number of components of output variables, across all emitted vertices, which can be output from the geometry shader stage. -
maxFragmentInputComponentsis the maximum number of components of input variables which can be provided as inputs to the fragment shader stage. -
maxFragmentOutputAttachmentsis the maximum number of output attachments which can be written to by the fragment shader stage. -
maxFragmentDualSrcAttachmentsis the maximum number of output attachments which can be written to by the fragment shader stage when blending is enabled and one of the dual source blend modes is in use. See Dual-Source Blending anddualSrcBlend. -
maxFragmentCombinedOutputResourcesis the total number of storage buffers, storage images, and outputLocationdecorated color attachments (described in Fragment Output Interface) which can be used in the fragment shader stage. -
maxComputeSharedMemorySizeis the maximum total storage size, in bytes, available for variables declared with theWorkgroupstorage class in shader modules (or with thesharedstorage qualifier in GLSL) in the compute shader stage. When variables declared with theWorkgroupstorage class are explicitly laid out (hence they are also decorated withBlock), 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 theWorkgroupstorage 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 withWorkgroupstorage class were assigned offsets in an arbitrary order by successively taking the smallest valid offset according to the Standard Storage Buffer Layout rules. (This is equivalent to using the GLSL std430 layout rules.) -
maxComputeWorkGroupCount[3] is the maximum number of local workgroups that can be dispatched by a single dispatching command. These three values represent the maximum number of local workgroups for the X, Y, and Z dimensions, respectively. The workgroup count parameters to the dispatching commands must be less than or equal to the corresponding limit. See Dispatching Commands. -
maxComputeWorkGroupInvocationsis the maximum total number of compute shader invocations in a single local workgroup. The product of the X, Y, and Z sizes, as specified by theLocalSizeorLocalSizeIdexecution mode in shader modules or by the object decorated by theWorkgroupSizedecoration, must be less than or equal to this limit. -
maxComputeWorkGroupSize[3] is the maximum size of a local compute workgroup, per dimension. These three values represent the maximum local workgroup size in the X, Y, and Z dimensions, respectively. Thex,y, andzsizes, as specified by theLocalSizeorLocalSizeIdexecution mode or by the object decorated by theWorkgroupSizedecoration in shader modules, must be less than or equal to the corresponding limit. -
subPixelPrecisionBitsis the number of bits of subpixel precision in framebuffer coordinates xf and yf. See Rasterization. -
subTexelPrecisionBitsis the number of bits of precision in the division along an axis of an image used for minification and magnification filters. 2subTexelPrecisionBitsis the actual number of divisions along each axis of the image represented. Sub-texel values calculated during image sampling will snap to these locations when generating the filtered results. -
mipmapPrecisionBitsis the number of bits of division that the LOD calculation for mipmap fetching get snapped to when determining the contribution from each mip level to the mip filtered results. 2mipmapPrecisionBitsis the actual number of divisions. -
maxDrawIndexedIndexValueis the maximum index value that can be used for indexed draw calls when using 32-bit indices. This excludes the primitive restart index value of 0xFFFFFFFF. SeefullDrawIndexUint32. -
maxDrawIndirectCountis the maximum draw count that is supported for indirect drawing calls. SeemultiDrawIndirect. -
maxSamplerLodBiasis the maximum absolute sampler LOD bias. The sum of themipLodBiasmember of the VkSamplerCreateInfo structure and theBiasoperand of image sampling operations in shader modules (or 0 if noBiasoperand is provided to an image sampling operation) are clamped to the range [-maxSamplerLodBias,+maxSamplerLodBias]. See [samplers-mipLodBias]. -
maxSamplerAnisotropyis the maximum degree of sampler anisotropy. The maximum degree of anisotropic filtering used for an image sampling operation is the minimum of themaxAnisotropymember of the VkSamplerCreateInfo structure and this limit. See [samplers-maxAnisotropy]. -
maxViewportsis the maximum number of active viewports. TheviewportCountmember of the VkPipelineViewportStateCreateInfo structure that is provided at pipeline creation must be less than or equal to this limit. -
maxViewportDimensions[2] are the maximum viewport dimensions in the X (width) and Y (height) dimensions, respectively. The maximum viewport dimensions must be greater than or equal to the largest image which can be created and used as a framebuffer attachment. See Controlling the Viewport. -
viewportBoundsRange[2] is the [minimum, maximum] range that the corners of a viewport must be contained in. This range must be at least [-2 ×size, 2 ×size- 1], wheresize= max(maxViewportDimensions[0],maxViewportDimensions[1]). See Controlling the Viewport.NoteThe intent of the
viewportBoundsRangelimit is to allow a maximum sized viewport to be arbitrarily shifted relative to the output target as long as at least some portion intersects. This would give a bounds limit of [-size+ 1, 2 ×size- 1] which would allow all possible non-empty-set intersections of the output target and the viewport. Since these numbers are typically powers of two, picking the signed number range using the smallest possible number of bits ends up with the specified range. -
viewportSubPixelBitsis the number of bits of subpixel precision for viewport bounds. The subpixel precision that floating-point viewport bounds are interpreted at is given by this limit. -
minMemoryMapAlignmentis the minimum required alignment, in bytes, of host visible memory allocations within the host address space. When mapping a memory allocation with vkMapMemory, subtractingoffsetbytes from the returned pointer will always produce an integer multiple of this limit. See Host Access to Device Memory Objects. The value must be a power of two. -
minTexelBufferOffsetAlignmentis the minimum required alignment, in bytes, for theoffsetmember of the VkBufferViewCreateInfo structure for texel buffers. The value must be a power of two. IftexelBufferAlignmentis enabled, this limit is equivalent to the maximum of theuniformTexelBufferOffsetAlignmentBytesandstorageTexelBufferOffsetAlignmentBytesmembers of VkPhysicalDeviceTexelBufferAlignmentProperties, but smaller alignment is optionally allowed bystorageTexelBufferOffsetSingleTexelAlignmentanduniformTexelBufferOffsetSingleTexelAlignment. IftexelBufferAlignmentis not enabled, VkBufferViewCreateInfo::offsetmust be a multiple of this value. -
minUniformBufferOffsetAlignmentis the minimum required alignment, in bytes, for theoffsetmember of theVkDescriptorBufferInfostructure for uniform buffers. When a descriptor of typeVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMICis updated, theoffsetmust be an integer multiple of this limit. Similarly, dynamic offsets for uniform buffers must be multiples of this limit. The value must be a power of two. -
minStorageBufferOffsetAlignmentis the minimum required alignment, in bytes, for theoffsetmember of theVkDescriptorBufferInfostructure for storage buffers. When a descriptor of typeVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMICis updated, theoffsetmust be an integer multiple of this limit. Similarly, dynamic offsets for storage buffers must be multiples of this limit. The value must be a power of two. -
minTexelOffsetis the minimum offset value for theConstOffsetimage operand of any of theOpImageSample*orOpImageFetch*image instructions. -
maxTexelOffsetis the maximum offset value for theConstOffsetimage operand of any of theOpImageSample*orOpImageFetch*image instructions. -
minTexelGatherOffsetis the minimum offset value for theOffset,ConstOffset, orConstOffsetsimage operands of any of theOpImage*Gatherimage instructions. -
maxTexelGatherOffsetis the maximum offset value for theOffset,ConstOffset, orConstOffsetsimage operands of any of theOpImage*Gatherimage instructions. -
minInterpolationOffsetis the base minimum (inclusive) negative offset value for theOffsetoperand of theInterpolateAtOffsetextended instruction. -
maxInterpolationOffsetis the base maximum (inclusive) positive offset value for theOffsetoperand of theInterpolateAtOffsetextended instruction. -
subPixelInterpolationOffsetBitsis the number of fractional bits that thexandyoffsets to theInterpolateAtOffsetextended instruction may be rounded to as fixed-point values. -
maxFramebufferWidthis the maximum width for a framebuffer. Thewidthmember of the VkFramebufferCreateInfo structure must be less than or equal to this limit. -
maxFramebufferHeightis the maximum height for a framebuffer. Theheightmember of the VkFramebufferCreateInfo structure must be less than or equal to this limit. -
maxFramebufferLayersis the maximum layer count for a layered framebuffer. Thelayersmember of the VkFramebufferCreateInfo structure must be less than or equal to this limit. -
framebufferColorSampleCountsis a bitmask1 of VkSampleCountFlagBits indicating the color sample counts that are supported for all framebuffer color attachments with floating- or fixed-point formats. For color attachments with integer formats, seeframebufferIntegerColorSampleCounts. -
framebufferDepthSampleCountsis a bitmask1 of VkSampleCountFlagBits indicating the supported depth sample counts for all framebuffer depth/stencil attachments, when the format includes a depth component. -
framebufferStencilSampleCountsis a bitmask1 of VkSampleCountFlagBits indicating the supported stencil sample counts for all framebuffer depth/stencil attachments, when the format includes a stencil component. -
framebufferNoAttachmentsSampleCountsis a bitmask1 of VkSampleCountFlagBits indicating the supported sample counts for a subpass which uses no attachments. -
maxColorAttachmentsis the maximum number of color attachments that can be used by a subpass in a render pass. ThecolorAttachmentCountmember of theVkSubpassDescriptionorVkSubpassDescription2structure must be less than or equal to this limit. -
sampledImageColorSampleCountsis a bitmask1 of VkSampleCountFlagBits indicating the sample counts supported for all 2D images created withVK_IMAGE_TILING_OPTIMAL,usagecontainingVK_IMAGE_USAGE_SAMPLED_BIT, and a non-integer color format. -
sampledImageIntegerSampleCountsis a bitmask1 of VkSampleCountFlagBits indicating the sample counts supported for all 2D images created withVK_IMAGE_TILING_OPTIMAL,usagecontainingVK_IMAGE_USAGE_SAMPLED_BIT, and an integer color format. -
sampledImageDepthSampleCountsis a bitmask1 of VkSampleCountFlagBits indicating the sample counts supported for all 2D images created withVK_IMAGE_TILING_OPTIMAL,usagecontainingVK_IMAGE_USAGE_SAMPLED_BIT, and a depth format. -
sampledImageStencilSampleCountsis a bitmask1 of VkSampleCountFlagBits indicating the sample counts supported for all 2D images created withVK_IMAGE_TILING_OPTIMAL,usagecontainingVK_IMAGE_USAGE_SAMPLED_BIT, and a stencil format. -
storageImageSampleCountsis a bitmask1 of VkSampleCountFlagBits indicating the sample counts supported for all 2D images created withVK_IMAGE_TILING_OPTIMAL, andusagecontainingVK_IMAGE_USAGE_STORAGE_BIT. -
maxSampleMaskWordsis the maximum number of array elements of a variable decorated with theSampleMaskbuilt-in decoration. -
timestampComputeAndGraphicsspecifies support for timestamps on all graphics and compute queues. If this limit is set toVK_TRUE, all queues that advertise theVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BITin theVkQueueFamilyProperties::queueFlagssupportVkQueueFamilyProperties::timestampValidBitsof at least 36. See Timestamp Queries. -
timestampPeriodis the number of nanoseconds required for a timestamp query to be incremented by 1. See Timestamp Queries. -
maxClipDistancesis the maximum number of clip distances that can be used in a single shader stage. The size of any array declared with theClipDistancebuilt-in decoration in a shader module must be less than or equal to this limit. -
maxCullDistancesis the maximum number of cull distances that can be used in a single shader stage. The size of any array declared with theCullDistancebuilt-in decoration in a shader module must be less than or equal to this limit. -
maxCombinedClipAndCullDistancesis the maximum combined number of clip and cull distances that can be used in a single shader stage. The sum of the sizes of any pair of arrays declared with theClipDistanceandCullDistancebuilt-in decoration used by a single shader stage in a shader module must be less than or equal to this limit. -
discreteQueuePrioritiesis the number of discrete priorities that can be assigned to a queue based on the value of each member of VkDeviceQueueCreateInfo::pQueuePriorities. This must be at least 2, and levels must be spread evenly over the range, with at least one level at 1.0, and another at 0.0. See Queue Priority. -
pointSizeRange[2] is the range [minimum,maximum] of supported sizes for points. Values written to variables decorated with thePointSizebuilt-in decoration are clamped to this range. -
lineWidthRange[2] is the range [minimum,maximum] of supported widths for lines. Values specified by thelineWidthmember of the VkPipelineRasterizationStateCreateInfo or thelineWidthparameter tovkCmdSetLineWidthare clamped to this range. -
pointSizeGranularityis the granularity of supported point sizes. Not all point sizes in the range defined bypointSizeRangeare supported. This limit specifies the granularity (or increment) between successive supported point sizes. -
lineWidthGranularityis the granularity of supported line widths. Not all line widths in the range defined bylineWidthRangeare supported. This limit specifies the granularity (or increment) between successive supported line widths. -
strictLinesspecifies whether lines are rasterized according to the preferred method of rasterization. If set toVK_FALSE, lines may be rasterized under a relaxed set of rules. If set toVK_TRUE, lines are rasterized as per the strict definition. See Basic Line Segment Rasterization. -
standardSampleLocationsspecifies whether rasterization uses the standard sample locations as documented in Multisampling. If set toVK_TRUE, the implementation uses the documented sample locations. If set toVK_FALSE, the implementation may use different sample locations. -
optimalBufferCopyOffsetAlignmentis the optimal buffer offset alignment in bytes for vkCmdCopyBufferToImage2, vkCmdCopyBufferToImage, vkCmdCopyImageToBuffer2, and vkCmdCopyImageToBuffer. The per texel alignment requirements are enforced, but applications should use the optimal alignment for optimal performance and power use. The value must be a power of two. -
optimalBufferCopyRowPitchAlignmentis the optimal buffer row pitch alignment in bytes for vkCmdCopyBufferToImage2, vkCmdCopyBufferToImage, vkCmdCopyImageToBuffer2, and vkCmdCopyImageToBuffer. Row pitch is the number of bytes between texels with the same X coordinate in adjacent rows (Y coordinates differ by one). The per texel alignment requirements are enforced, but applications should use the optimal alignment for optimal performance and power use. The value must be a power of two. -
nonCoherentAtomSizeis the size and alignment in bytes that bounds concurrent access to host-mapped device memory. The value must be a power of two.- 1
-
For all bitmasks of VkSampleCountFlagBits, the sample count limits defined above represent the minimum supported sample counts for each image type. Individual images may support additional sample counts, which are queried using vkGetPhysicalDeviceImageFormatProperties as described in Supported Sample Counts.
Bits which may be set in the sample count limits returned by VkPhysicalDeviceLimits, as well as in other queries and structures representing image sample counts, are:
// Provided by VK_VERSION_1_0
typedef enum VkSampleCountFlagBits {
VK_SAMPLE_COUNT_1_BIT = 0x00000001,
VK_SAMPLE_COUNT_2_BIT = 0x00000002,
VK_SAMPLE_COUNT_4_BIT = 0x00000004,
VK_SAMPLE_COUNT_8_BIT = 0x00000008,
VK_SAMPLE_COUNT_16_BIT = 0x00000010,
VK_SAMPLE_COUNT_32_BIT = 0x00000020,
VK_SAMPLE_COUNT_64_BIT = 0x00000040,
} VkSampleCountFlagBits;
-
VK_SAMPLE_COUNT_1_BITspecifies an image with one sample per pixel. -
VK_SAMPLE_COUNT_2_BITspecifies an image with 2 samples per pixel. -
VK_SAMPLE_COUNT_4_BITspecifies an image with 4 samples per pixel. -
VK_SAMPLE_COUNT_8_BITspecifies an image with 8 samples per pixel. -
VK_SAMPLE_COUNT_16_BITspecifies an image with 16 samples per pixel. -
VK_SAMPLE_COUNT_32_BITspecifies an image with 32 samples per pixel. -
VK_SAMPLE_COUNT_64_BITspecifies an image with 64 samples per pixel.
// Provided by VK_VERSION_1_0
typedef VkFlags VkSampleCountFlags;
VkSampleCountFlags is a bitmask type for setting a mask of zero or
more VkSampleCountFlagBits.
The VkPhysicalDevicePushDescriptorPropertiesKHR structure is defined
as:
// Provided by VK_KHR_push_descriptor
typedef struct VkPhysicalDevicePushDescriptorPropertiesKHR {
VkStructureType sType;
void* pNext;
uint32_t maxPushDescriptors;
} VkPhysicalDevicePushDescriptorPropertiesKHR;
If the VkPhysicalDevicePushDescriptorPropertiesKHR structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceMultiviewProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceMultiviewProperties {
VkStructureType sType;
void* pNext;
uint32_t maxMultiviewViewCount;
uint32_t maxMultiviewInstanceIndex;
} VkPhysicalDeviceMultiviewProperties;
or the equivalent
// Provided by VK_KHR_multiview
typedef VkPhysicalDeviceMultiviewProperties VkPhysicalDeviceMultiviewPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceMultiviewProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceFloatControlsProperties structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceFloatControlsProperties {
VkStructureType sType;
void* pNext;
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;
} VkPhysicalDeviceFloatControlsProperties;
or the equivalent
// Provided by VK_KHR_shader_float_controls
typedef VkPhysicalDeviceFloatControlsProperties VkPhysicalDeviceFloatControlsPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
denormBehaviorIndependenceis a VkShaderFloatControlsIndependence value indicating whether, and how, denorm behavior can be set independently for different bit widths. -
roundingModeIndependenceis a VkShaderFloatControlsIndependence value indicating whether, and how, rounding modes can be set independently for different bit widths. -
shaderSignedZeroInfNanPreserveFloat16is a boolean value indicating whether sign of a zero, Nans and can be preserved in 16-bit floating-point computations. It also indicates whether theSignedZeroInfNanPreserveexecution mode can be used for 16-bit floating-point types. -
shaderSignedZeroInfNanPreserveFloat32is a boolean value indicating whether sign of a zero, Nans and can be preserved in 32-bit floating-point computations. It also indicates whether theSignedZeroInfNanPreserveexecution mode can be used for 32-bit floating-point types. -
shaderSignedZeroInfNanPreserveFloat64is a boolean value indicating whether sign of a zero, Nans and can be preserved in 64-bit floating-point computations. It also indicates whether theSignedZeroInfNanPreserveexecution mode can be used for 64-bit floating-point types. -
shaderDenormPreserveFloat16is a boolean value indicating whether denormals can be preserved in 16-bit floating-point computations. It also indicates whether theDenormPreserveexecution mode can be used for 16-bit floating-point types. -
shaderDenormPreserveFloat32is a boolean value indicating whether denormals can be preserved in 32-bit floating-point computations. It also indicates whether theDenormPreserveexecution mode can be used for 32-bit floating-point types. -
shaderDenormPreserveFloat64is a boolean value indicating whether denormals can be preserved in 64-bit floating-point computations. It also indicates whether theDenormPreserveexecution mode can be used for 64-bit floating-point types. -
shaderDenormFlushToZeroFloat16is a boolean value indicating whether denormals can be flushed to zero in 16-bit floating-point computations. It also indicates whether theDenormFlushToZeroexecution mode can be used for 16-bit floating-point types. -
shaderDenormFlushToZeroFloat32is a boolean value indicating whether denormals can be flushed to zero in 32-bit floating-point computations. It also indicates whether theDenormFlushToZeroexecution mode can be used for 32-bit floating-point types. -
shaderDenormFlushToZeroFloat64is a boolean value indicating whether denormals can be flushed to zero in 64-bit floating-point computations. It also indicates whether theDenormFlushToZeroexecution mode can be used for 64-bit floating-point types. -
shaderRoundingModeRTEFloat16is 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 theRoundingModeRTEexecution mode can be used for 16-bit floating-point types. -
shaderRoundingModeRTEFloat32is 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 theRoundingModeRTEexecution mode can be used for 32-bit floating-point types. -
shaderRoundingModeRTEFloat64is 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 theRoundingModeRTEexecution mode can be used for 64-bit floating-point types. -
shaderRoundingModeRTZFloat16is 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 theRoundingModeRTZexecution mode can be used for 16-bit floating-point types. -
shaderRoundingModeRTZFloat32is 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 theRoundingModeRTZexecution mode can be used for 32-bit floating-point types. -
shaderRoundingModeRTZFloat64is 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 theRoundingModeRTZexecution mode can be used for 64-bit floating-point types.
|
editing-note
Implementations may not be able to control behavior of denorms for floating-point atomics. This needs to be taken into account when such atomics will be added to Vulkan. |
If the VkPhysicalDeviceFloatControlsProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
Values which may be returned in the denormBehaviorIndependence and
roundingModeIndependence fields of
VkPhysicalDeviceFloatControlsProperties are:
// Provided by VK_VERSION_1_2
typedef enum VkShaderFloatControlsIndependence {
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_32_BIT_ONLY = 0,
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_ALL = 1,
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_NONE = 2,
// Provided by VK_KHR_shader_float_controls
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_32_BIT_ONLY_KHR = VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_32_BIT_ONLY,
// Provided by VK_KHR_shader_float_controls
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_ALL_KHR = VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_ALL,
// Provided by VK_KHR_shader_float_controls
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_NONE_KHR = VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_NONE,
} VkShaderFloatControlsIndependence;
or the equivalent
// Provided by VK_KHR_shader_float_controls
typedef VkShaderFloatControlsIndependence VkShaderFloatControlsIndependenceKHR;
-
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_32_BIT_ONLYspecifies that shader float controls for 32-bit floating point can be set independently; other bit widths must be set identically to each other. -
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_ALLspecifies that shader float controls for all bit widths can be set independently. -
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_NONEspecifies that shader float controls for all bit widths must be set identically.
The VkPhysicalDeviceDiscardRectanglePropertiesEXT structure is defined
as:
// Provided by VK_EXT_discard_rectangles
typedef struct VkPhysicalDeviceDiscardRectanglePropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t maxDiscardRectangles;
} VkPhysicalDeviceDiscardRectanglePropertiesEXT;
If the VkPhysicalDeviceDiscardRectanglePropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceSampleLocationsPropertiesEXT structure is defined
as:
// Provided by VK_EXT_sample_locations
typedef struct VkPhysicalDeviceSampleLocationsPropertiesEXT {
VkStructureType sType;
void* pNext;
VkSampleCountFlags sampleLocationSampleCounts;
VkExtent2D maxSampleLocationGridSize;
float sampleLocationCoordinateRange[2];
uint32_t sampleLocationSubPixelBits;
VkBool32 variableSampleLocations;
} VkPhysicalDeviceSampleLocationsPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sampleLocationSampleCountsis a bitmask of VkSampleCountFlagBits indicating the sample counts supporting custom sample locations. -
maxSampleLocationGridSizeis the maximum size of the pixel grid in which sample locations can vary that is supported for all sample counts insampleLocationSampleCounts. -
sampleLocationCoordinateRange[2] is the range of supported sample location coordinates. -
sampleLocationSubPixelBitsis the number of bits of subpixel precision for sample locations. -
variableSampleLocationsspecifies whether the sample locations used by all pipelines that will be bound to a command buffer during a subpass must match. If set toVK_TRUE, the implementation supports variable sample locations in a subpass. If set toVK_FALSE, then the sample locations must stay constant in each subpass.
If the VkPhysicalDeviceSampleLocationsPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceExternalMemoryHostPropertiesEXT structure is
defined as:
// Provided by VK_EXT_external_memory_host
typedef struct VkPhysicalDeviceExternalMemoryHostPropertiesEXT {
VkStructureType sType;
void* pNext;
VkDeviceSize minImportedHostPointerAlignment;
} VkPhysicalDeviceExternalMemoryHostPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minImportedHostPointerAlignmentis the minimum required alignment, in bytes, for the base address and size of host pointers that can be imported to a Vulkan memory object. The value must be a power of two.
If the VkPhysicalDeviceExternalMemoryHostPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceMultiviewPerViewAttributesPropertiesNVX structure
is defined as:
// Provided by VK_NVX_multiview_per_view_attributes
typedef struct VkPhysicalDeviceMultiviewPerViewAttributesPropertiesNVX {
VkStructureType sType;
void* pNext;
VkBool32 perViewPositionAllComponents;
} VkPhysicalDeviceMultiviewPerViewAttributesPropertiesNVX;
If the VkPhysicalDeviceMultiviewPerViewAttributesPropertiesNVX structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDevicePointClippingProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDevicePointClippingProperties {
VkStructureType sType;
void* pNext;
VkPointClippingBehavior pointClippingBehavior;
} VkPhysicalDevicePointClippingProperties;
or the equivalent
// Provided by VK_KHR_maintenance2
typedef VkPhysicalDevicePointClippingProperties VkPhysicalDevicePointClippingPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
pointClippingBehavioris a VkPointClippingBehavior value specifying the point clipping behavior supported by the implementation.
If the VkPhysicalDevicePointClippingProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceSubgroupProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceSubgroupProperties {
VkStructureType sType;
void* pNext;
uint32_t subgroupSize;
VkShaderStageFlags supportedStages;
VkSubgroupFeatureFlags supportedOperations;
VkBool32 quadOperationsInAllStages;
} VkPhysicalDeviceSubgroupProperties;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
subgroupSizeis the default number of invocations in each subgroup.subgroupSizeis at least 1 if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BIT.subgroupSizeis a power-of-two. -
supportedStagesis a bitfield of VkShaderStageFlagBits describing the shader stages that group operations with subgroup scope are supported in.supportedStageswill have theVK_SHADER_STAGE_COMPUTE_BITbit set if any of the physical device’s queues supportVK_QUEUE_COMPUTE_BIT. -
supportedOperationsis a bitmask of VkSubgroupFeatureFlagBits specifying the sets of group operations with subgroup scope supported on this device.supportedOperationswill have theVK_SUBGROUP_FEATURE_BASIC_BITbit set if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BIT. -
quadOperationsInAllStagesis a boolean specifying whether quad group operations are available in all stages, or are restricted to fragment and compute stages.
If the VkPhysicalDeviceSubgroupProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
If supportedOperations includes VK_SUBGROUP_FEATURE_QUAD_BIT,
or shaderSubgroupUniformControlFlow is enabled,
subgroupSize must be greater than or equal to 4.
Bits which can be set in
VkPhysicalDeviceSubgroupProperties::supportedOperations
and
VkPhysicalDeviceVulkan11Properties::subgroupSupportedOperations
to specify supported group operations with
subgroup scope are:
// Provided by VK_VERSION_1_1
typedef enum VkSubgroupFeatureFlagBits {
VK_SUBGROUP_FEATURE_BASIC_BIT = 0x00000001,
VK_SUBGROUP_FEATURE_VOTE_BIT = 0x00000002,
VK_SUBGROUP_FEATURE_ARITHMETIC_BIT = 0x00000004,
VK_SUBGROUP_FEATURE_BALLOT_BIT = 0x00000008,
VK_SUBGROUP_FEATURE_SHUFFLE_BIT = 0x00000010,
VK_SUBGROUP_FEATURE_SHUFFLE_RELATIVE_BIT = 0x00000020,
VK_SUBGROUP_FEATURE_CLUSTERED_BIT = 0x00000040,
VK_SUBGROUP_FEATURE_QUAD_BIT = 0x00000080,
// Provided by VK_NV_shader_subgroup_partitioned
VK_SUBGROUP_FEATURE_PARTITIONED_BIT_NV = 0x00000100,
} VkSubgroupFeatureFlagBits;
-
VK_SUBGROUP_FEATURE_BASIC_BITspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformcapability. -
VK_SUBGROUP_FEATURE_VOTE_BITspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformVotecapability. -
VK_SUBGROUP_FEATURE_ARITHMETIC_BITspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformArithmeticcapability. -
VK_SUBGROUP_FEATURE_BALLOT_BITspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformBallotcapability. -
VK_SUBGROUP_FEATURE_SHUFFLE_BITspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformShufflecapability. -
VK_SUBGROUP_FEATURE_SHUFFLE_RELATIVE_BITspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformShuffleRelativecapability. -
VK_SUBGROUP_FEATURE_CLUSTERED_BITspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformClusteredcapability. -
VK_SUBGROUP_FEATURE_QUAD_BITspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformQuadcapability. -
VK_SUBGROUP_FEATURE_PARTITIONED_BIT_NVspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformPartitionedNVcapability.
// Provided by VK_VERSION_1_1
typedef VkFlags VkSubgroupFeatureFlags;
VkSubgroupFeatureFlags is a bitmask type for setting a mask of zero or
more VkSubgroupFeatureFlagBits.
The VkPhysicalDeviceSubgroupSizeControlProperties structure is defined
as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceSubgroupSizeControlProperties {
VkStructureType sType;
void* pNext;
uint32_t minSubgroupSize;
uint32_t maxSubgroupSize;
uint32_t maxComputeWorkgroupSubgroups;
VkShaderStageFlags requiredSubgroupSizeStages;
} VkPhysicalDeviceSubgroupSizeControlProperties;
or the equivalent
// Provided by VK_EXT_subgroup_size_control
typedef VkPhysicalDeviceSubgroupSizeControlProperties VkPhysicalDeviceSubgroupSizeControlPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
minSubgroupSizeis the minimum subgroup size supported by this device.minSubgroupSizeis at least one if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BIT.minSubgroupSizeis a power-of-two.minSubgroupSizeis less than or equal tomaxSubgroupSize.minSubgroupSizeis less than or equal tosubgroupSize. -
maxSubgroupSizeis the maximum subgroup size supported by this device.maxSubgroupSizeis at least one if any of the physical device’s queues supportVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BIT.maxSubgroupSizeis a power-of-two.maxSubgroupSizeis greater than or equal tominSubgroupSize.maxSubgroupSizeis greater than or equal tosubgroupSize. -
maxComputeWorkgroupSubgroupsis the maximum number of subgroups supported by the implementation within a workgroup. -
requiredSubgroupSizeStagesis a bitfield of what shader stages support having a required subgroup size specified.
If the VkPhysicalDeviceSubgroupSizeControlProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
If VkPhysicalDeviceSubgroupProperties::supportedOperations
includes VK_SUBGROUP_FEATURE_QUAD_BIT,
minSubgroupSize must be greater than or equal to 4.
The VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT structure is
defined as:
// Provided by VK_EXT_blend_operation_advanced
typedef struct VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t advancedBlendMaxColorAttachments;
VkBool32 advancedBlendIndependentBlend;
VkBool32 advancedBlendNonPremultipliedSrcColor;
VkBool32 advancedBlendNonPremultipliedDstColor;
VkBool32 advancedBlendCorrelatedOverlap;
VkBool32 advancedBlendAllOperations;
} VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
advancedBlendMaxColorAttachmentsis one greater than the highest color attachment index that can be used in a subpass, for a pipeline that uses an advanced blend operation. -
advancedBlendIndependentBlendspecifies whether advanced blend operations can vary per-attachment. -
advancedBlendNonPremultipliedSrcColorspecifies whether the source color can be treated as non-premultiplied. If this isVK_FALSE, then VkPipelineColorBlendAdvancedStateCreateInfoEXT::srcPremultipliedmust beVK_TRUE. -
advancedBlendNonPremultipliedDstColorspecifies whether the destination color can be treated as non-premultiplied. If this isVK_FALSE, then VkPipelineColorBlendAdvancedStateCreateInfoEXT::dstPremultipliedmust beVK_TRUE. -
advancedBlendCorrelatedOverlapspecifies whether the overlap mode can be treated as correlated. If this isVK_FALSE, then VkPipelineColorBlendAdvancedStateCreateInfoEXT::blendOverlapmust beVK_BLEND_OVERLAP_UNCORRELATED_EXT. -
advancedBlendAllOperationsspecifies whether all advanced blend operation enums are supported. See the valid usage of VkPipelineColorBlendAttachmentState.
If the VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT structure is
defined as:
// Provided by VK_EXT_vertex_attribute_divisor
typedef struct VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t maxVertexAttribDivisor;
} VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT;
If the VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceSamplerFilterMinmaxProperties structure is defined
as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceSamplerFilterMinmaxProperties {
VkStructureType sType;
void* pNext;
VkBool32 filterMinmaxSingleComponentFormats;
VkBool32 filterMinmaxImageComponentMapping;
} VkPhysicalDeviceSamplerFilterMinmaxProperties;
or the equivalent
// Provided by VK_EXT_sampler_filter_minmax
typedef VkPhysicalDeviceSamplerFilterMinmaxProperties VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
filterMinmaxSingleComponentFormatsis a boolean value indicating whether a minimum set of required formats support min/max filtering. -
filterMinmaxImageComponentMappingis a boolean value indicating whether the implementation supports non-identity component mapping of the image when doing min/max filtering.
If the VkPhysicalDeviceSamplerFilterMinmaxProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
If filterMinmaxSingleComponentFormats is VK_TRUE, the following
formats must support the
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT feature with
VK_IMAGE_TILING_OPTIMAL, if they support
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT:
-
VK_FORMAT_R8_UNORM -
VK_FORMAT_R8_SNORM -
VK_FORMAT_R16_UNORM -
VK_FORMAT_R16_SNORM -
VK_FORMAT_R16_SFLOAT -
VK_FORMAT_R32_SFLOAT -
VK_FORMAT_D16_UNORM -
VK_FORMAT_X8_D24_UNORM_PACK32 -
VK_FORMAT_D32_SFLOAT -
VK_FORMAT_D16_UNORM_S8_UINT -
VK_FORMAT_D24_UNORM_S8_UINT -
VK_FORMAT_D32_SFLOAT_S8_UINT
If the format is a depth/stencil format, this bit only specifies that the depth aspect (not the stencil aspect) of an image of this format supports min/max filtering, and that min/max filtering of the depth aspect is supported when depth compare is disabled in the sampler.
If filterMinmaxImageComponentMapping is VK_FALSE the component
mapping of the image view used with min/max filtering must have been
created with the r component set to the
identity swizzle.
Only the r component of the sampled image value is defined and the
other component values are undefined.
If filterMinmaxImageComponentMapping is VK_TRUE this restriction
does not apply and image component mapping works as normal.
The VkPhysicalDeviceProtectedMemoryProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceProtectedMemoryProperties {
VkStructureType sType;
void* pNext;
VkBool32 protectedNoFault;
} VkPhysicalDeviceProtectedMemoryProperties;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
protectedNoFaultspecifies 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.
If the VkPhysicalDeviceProtectedMemoryProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceMaintenance3Properties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceMaintenance3Properties {
VkStructureType sType;
void* pNext;
uint32_t maxPerSetDescriptors;
VkDeviceSize maxMemoryAllocationSize;
} VkPhysicalDeviceMaintenance3Properties;
or the equivalent
// Provided by VK_KHR_maintenance3
typedef VkPhysicalDeviceMaintenance3Properties VkPhysicalDeviceMaintenance3PropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
maxPerSetDescriptorsis 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. -
maxMemoryAllocationSizeis the maximum size of a memory allocation that can be created, even if there is more space available in the heap.
If the VkPhysicalDeviceMaintenance3Properties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceMaintenance4Properties structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceMaintenance4Properties {
VkStructureType sType;
void* pNext;
VkDeviceSize maxBufferSize;
} VkPhysicalDeviceMaintenance4Properties;
or the equivalent
// Provided by VK_KHR_maintenance4
typedef VkPhysicalDeviceMaintenance4Properties VkPhysicalDeviceMaintenance4PropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceMaintenance4Properties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceMeshShaderPropertiesNV structure is defined as:
// Provided by VK_NV_mesh_shader
typedef struct VkPhysicalDeviceMeshShaderPropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t maxDrawMeshTasksCount;
uint32_t maxTaskWorkGroupInvocations;
uint32_t maxTaskWorkGroupSize[3];
uint32_t maxTaskTotalMemorySize;
uint32_t maxTaskOutputCount;
uint32_t maxMeshWorkGroupInvocations;
uint32_t maxMeshWorkGroupSize[3];
uint32_t maxMeshTotalMemorySize;
uint32_t maxMeshOutputVertices;
uint32_t maxMeshOutputPrimitives;
uint32_t maxMeshMultiviewViewCount;
uint32_t meshOutputPerVertexGranularity;
uint32_t meshOutputPerPrimitiveGranularity;
} VkPhysicalDeviceMeshShaderPropertiesNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxDrawMeshTasksCountis the maximum number of local workgroups that can be launched by a single draw mesh tasks command. See Programmable Mesh Shading. -
maxTaskWorkGroupInvocationsis the maximum total number of task shader invocations in a single local workgroup. The product of the X, Y, and Z sizes, as specified by theLocalSizeorLocalSizeIdexecution mode in shader modules or by the object decorated by theWorkgroupSizedecoration, must be less than or equal to this limit. -
maxTaskWorkGroupSize[3] is the maximum size of a local task workgroup. These three values represent the maximum local workgroup size in the X, Y, and Z dimensions, respectively. Thex,y, andzsizes, as specified by theLocalSizeorLocalSizeIdexecution mode or by the object decorated by theWorkgroupSizedecoration in shader modules, must be less than or equal to the corresponding limit. -
maxTaskTotalMemorySizeis the maximum number of bytes that the task shader can use in total for shared and output memory combined. -
maxTaskOutputCountis the maximum number of output tasks a single task shader workgroup can emit. -
maxMeshWorkGroupInvocationsis the maximum total number of mesh shader invocations in a single local workgroup. The product of the X, Y, and Z sizes, as specified by theLocalSizeorLocalSizeIdexecution mode in shader modules or by the object decorated by theWorkgroupSizedecoration, must be less than or equal to this limit. -
maxMeshWorkGroupSize[3] is the maximum size of a local mesh workgroup. These three values represent the maximum local workgroup size in the X, Y, and Z dimensions, respectively. Thex,y, andzsizes, as specified by theLocalSizeorLocalSizeIdexecution mode or by the object decorated by theWorkgroupSizedecoration in shader modules, must be less than or equal to the corresponding limit. -
maxMeshTotalMemorySizeis the maximum number of bytes that the mesh shader can use in total for shared and output memory combined. -
maxMeshOutputVerticesis the maximum number of vertices a mesh shader output can store. -
maxMeshOutputPrimitivesis the maximum number of primitives a mesh shader output can store. -
maxMeshMultiviewViewCountis the maximum number of multi-view views a mesh shader can use. -
meshOutputPerVertexGranularityis the granularity with which mesh vertex outputs are allocated. The value can be used to compute the memory size used by the mesh shader, which must be less than or equal tomaxMeshTotalMemorySize. -
meshOutputPerPrimitiveGranularityis the granularity with which mesh outputs qualified as per-primitive are allocated. The value can be used to compute the memory size used by the mesh shader, which must be less than or equal tomaxMeshTotalMemorySize.
If the VkPhysicalDeviceMeshShaderPropertiesNV structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceDescriptorIndexingProperties structure is defined
as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceDescriptorIndexingProperties {
VkStructureType sType;
void* pNext;
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;
} VkPhysicalDeviceDescriptorIndexingProperties;
or the equivalent
// Provided by VK_EXT_descriptor_indexing
typedef VkPhysicalDeviceDescriptorIndexingProperties VkPhysicalDeviceDescriptorIndexingPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
maxUpdateAfterBindDescriptorsInAllPoolsis 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_BITbit 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. -
shaderUniformBufferArrayNonUniformIndexingNativeis 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. -
shaderSampledImageArrayNonUniformIndexingNativeis 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. -
shaderStorageBufferArrayNonUniformIndexingNativeis 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. -
shaderStorageImageArrayNonUniformIndexingNativeis 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. -
shaderInputAttachmentArrayNonUniformIndexingNativeis 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. -
robustBufferAccessUpdateAfterBindis a boolean value indicating whetherrobustBufferAccesscan be enabled in a device simultaneously withdescriptorBindingUniformBufferUpdateAfterBind,descriptorBindingStorageBufferUpdateAfterBind,descriptorBindingUniformTexelBufferUpdateAfterBind, and/ordescriptorBindingStorageTexelBufferUpdateAfterBind. If this isVK_FALSE, then eitherrobustBufferAccessmust be disabled or all of these update-after-bind features must be disabled. -
quadDivergentImplicitLodis a boolean value indicating whether implicit level of detail 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. -
maxPerStageDescriptorUpdateAfterBindSamplersis similar tomaxPerStageDescriptorSamplersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindUniformBuffersis similar tomaxPerStageDescriptorUniformBuffersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindStorageBuffersis similar tomaxPerStageDescriptorStorageBuffersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindSampledImagesis similar tomaxPerStageDescriptorSampledImagesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindStorageImagesis similar tomaxPerStageDescriptorStorageImagesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindInputAttachmentsis similar tomaxPerStageDescriptorInputAttachmentsbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageUpdateAfterBindResourcesis similar tomaxPerStageResourcesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindSamplersis similar tomaxDescriptorSetSamplersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindUniformBuffersis similar tomaxDescriptorSetUniformBuffersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindUniformBuffersDynamicis similar tomaxDescriptorSetUniformBuffersDynamicbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit 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. -
maxDescriptorSetUpdateAfterBindStorageBuffersis similar tomaxDescriptorSetStorageBuffersbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindStorageBuffersDynamicis similar tomaxDescriptorSetStorageBuffersDynamicbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit 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. -
maxDescriptorSetUpdateAfterBindSampledImagesis similar tomaxDescriptorSetSampledImagesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindStorageImagesis similar tomaxDescriptorSetStorageImagesbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindInputAttachmentsis similar tomaxDescriptorSetInputAttachmentsbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set.
If the VkPhysicalDeviceDescriptorIndexingProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceInlineUniformBlockProperties structure is defined
as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceInlineUniformBlockProperties {
VkStructureType sType;
void* pNext;
uint32_t maxInlineUniformBlockSize;
uint32_t maxPerStageDescriptorInlineUniformBlocks;
uint32_t maxPerStageDescriptorUpdateAfterBindInlineUniformBlocks;
uint32_t maxDescriptorSetInlineUniformBlocks;
uint32_t maxDescriptorSetUpdateAfterBindInlineUniformBlocks;
} VkPhysicalDeviceInlineUniformBlockProperties;
or the equivalent
// Provided by VK_EXT_inline_uniform_block
typedef VkPhysicalDeviceInlineUniformBlockProperties VkPhysicalDeviceInlineUniformBlockPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
maxInlineUniformBlockSizeis the maximum size in bytes of an inline uniform block binding. -
maxPerStageDescriptorInlineUniformBlockis 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_BLOCKcount against this limit. Only descriptor bindings in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. -
maxPerStageDescriptorUpdateAfterBindInlineUniformBlocksis similar tomaxPerStageDescriptorInlineUniformBlocksbut counts descriptor bindings from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetInlineUniformBlocksis 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_BLOCKcount against this limit. Only descriptor bindings in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. -
maxDescriptorSetUpdateAfterBindInlineUniformBlocksis similar tomaxDescriptorSetInlineUniformBlocksbut counts descriptor bindings from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set.
If the VkPhysicalDeviceInlineUniformBlockProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceConservativeRasterizationPropertiesEXT structure
is defined as:
// Provided by VK_EXT_conservative_rasterization
typedef struct VkPhysicalDeviceConservativeRasterizationPropertiesEXT {
VkStructureType sType;
void* pNext;
float primitiveOverestimationSize;
float maxExtraPrimitiveOverestimationSize;
float extraPrimitiveOverestimationSizeGranularity;
VkBool32 primitiveUnderestimation;
VkBool32 conservativePointAndLineRasterization;
VkBool32 degenerateTrianglesRasterized;
VkBool32 degenerateLinesRasterized;
VkBool32 fullyCoveredFragmentShaderInputVariable;
VkBool32 conservativeRasterizationPostDepthCoverage;
} VkPhysicalDeviceConservativeRasterizationPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
primitiveOverestimationSizeis the size in pixels the generating primitive is increased at each of its edges during conservative rasterization overestimation mode. Even with a size of 0.0, conservative rasterization overestimation rules still apply and if any part of the pixel rectangle is covered by the generating primitive, fragments are generated for the entire pixel. However implementations may make the pixel coverage area even more conservative by increasing the size of the generating primitive. -
maxExtraPrimitiveOverestimationSizeis the maximum size in pixels of extra overestimation the implementation supports in the pipeline state. A value of 0.0 means the implementation does not support any additional overestimation of the generating primitive during conservative rasterization. A value above 0.0 allows the application to further increase the size of the generating primitive during conservative rasterization overestimation. -
extraPrimitiveOverestimationSizeGranularityis the granularity of extra overestimation that can be specified in the pipeline state between 0.0 andmaxExtraPrimitiveOverestimationSizeinclusive. A value of 0.0 means the implementation can use the smallest representable non-zero value in the screen space pixel fixed-point grid. -
primitiveUnderestimationisVK_TRUEif the implementation supports theVK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXTconservative rasterization mode in addition toVK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT. Otherwise the implementation only supportsVK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT. -
conservativePointAndLineRasterizationisVK_TRUEif the implementation supports conservative rasterization of point and line primitives as well as triangle primitives. Otherwise the implementation only supports triangle primitives. -
degenerateTrianglesRasterizedisVK_FALSEif the implementation culls primitives generated from triangles that become zero area after they are quantized to the fixed-point rasterization pixel grid.degenerateTrianglesRasterizedisVK_TRUEif these primitives are not culled and the provoking vertex attributes and depth value are used for the fragments. The primitive area calculation is done on the primitive generated from the clipped triangle if applicable. Zero area primitives are backfacing and the application can enable backface culling if desired. -
degenerateLinesRasterizedisVK_FALSEif the implementation culls lines that become zero length after they are quantized to the fixed-point rasterization pixel grid.degenerateLinesRasterizedisVK_TRUEif zero length lines are not culled and the provoking vertex attributes and depth value are used for the fragments. -
fullyCoveredFragmentShaderInputVariableisVK_TRUEif the implementation supports the SPIR-V builtin fragment shader input variableFullyCoveredEXTspecifying that conservative rasterization is enabled and the fragment area is fully covered by the generating primitive. -
conservativeRasterizationPostDepthCoverageisVK_TRUEif the implementation supports conservative rasterization with thePostDepthCoverageexecution mode enabled. Otherwise thePostDepthCoverageexecution mode must not be used when conservative rasterization is enabled.
If the VkPhysicalDeviceConservativeRasterizationPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceFragmentDensityMapPropertiesEXT structure is
defined as:
// Provided by VK_EXT_fragment_density_map
typedef struct VkPhysicalDeviceFragmentDensityMapPropertiesEXT {
VkStructureType sType;
void* pNext;
VkExtent2D minFragmentDensityTexelSize;
VkExtent2D maxFragmentDensityTexelSize;
VkBool32 fragmentDensityInvocations;
} VkPhysicalDeviceFragmentDensityMapPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minFragmentDensityTexelSizeis the minimum fragment density texel size. -
maxFragmentDensityTexelSizeis the maximum fragment density texel size. -
fragmentDensityInvocationsspecifies whether the implementation may invoke additional fragment shader invocations for each covered sample.
If the VkPhysicalDeviceFragmentDensityMapPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceFragmentDensityMap2PropertiesEXT structure is
defined as:
// Provided by VK_EXT_fragment_density_map2
typedef struct VkPhysicalDeviceFragmentDensityMap2PropertiesEXT {
VkStructureType sType;
void* pNext;
VkBool32 subsampledLoads;
VkBool32 subsampledCoarseReconstructionEarlyAccess;
uint32_t maxSubsampledArrayLayers;
uint32_t maxDescriptorSetSubsampledSamplers;
} VkPhysicalDeviceFragmentDensityMap2PropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
subsampledLoadsspecifies if performing image data read with load operations on subsampled attachments will be resampled to the fragment density of the render pass -
subsampledCoarseReconstructionEarlyAccessspecifies if performing image data read with samplers created withflagscontainingVK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXTin fragment shader will trigger additional reads duringVK_PIPELINE_STAGE_VERTEX_SHADER_BIT -
maxSubsampledArrayLayersis the maximum number of VkImageView array layers for usages supporting subsampled samplers -
maxDescriptorSetSubsampledSamplersis the maximum number of subsampled samplers that can be included in a VkPipelineLayout
If the VkPhysicalDeviceFragmentDensityMap2PropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceFragmentDensityMapOffsetPropertiesQCOM structure
is defined as:
// Provided by VK_QCOM_fragment_density_map_offset
typedef struct VkPhysicalDeviceFragmentDensityMapOffsetPropertiesQCOM {
VkStructureType sType;
void* pNext;
VkExtent2D fragmentDensityOffsetGranularity;
} VkPhysicalDeviceFragmentDensityMapOffsetPropertiesQCOM;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityOffsetGranularityis the granularity for fragment density offsets.
If the VkPhysicalDeviceFragmentDensityMapOffsetPropertiesQCOM structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceShaderCorePropertiesAMD structure is defined as:
// Provided by VK_AMD_shader_core_properties
typedef struct VkPhysicalDeviceShaderCorePropertiesAMD {
VkStructureType sType;
void* pNext;
uint32_t shaderEngineCount;
uint32_t shaderArraysPerEngineCount;
uint32_t computeUnitsPerShaderArray;
uint32_t simdPerComputeUnit;
uint32_t wavefrontsPerSimd;
uint32_t wavefrontSize;
uint32_t sgprsPerSimd;
uint32_t minSgprAllocation;
uint32_t maxSgprAllocation;
uint32_t sgprAllocationGranularity;
uint32_t vgprsPerSimd;
uint32_t minVgprAllocation;
uint32_t maxVgprAllocation;
uint32_t vgprAllocationGranularity;
} VkPhysicalDeviceShaderCorePropertiesAMD;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderEngineCountis an unsigned integer value indicating the number of shader engines found inside the shader core of the physical device. -
shaderArraysPerEngineCountis an unsigned integer value indicating the number of shader arrays inside a shader engine. Each shader array has its own scan converter, set of compute units, and a render back end (color and depth attachments). Shader arrays within a shader engine share shader processor input (wave launcher) and shader export (export buffer) units. Currently, a shader engine can have one or two shader arrays. -
computeUnitsPerShaderArrayis an unsigned integer value indicating the physical number of compute units within a shader array. The active number of compute units in a shader array may be lower. A compute unit houses a set of SIMDs along with a sequencer module and a local data store. -
simdPerComputeUnitis an unsigned integer value indicating the number of SIMDs inside a compute unit. Each SIMD processes a single instruction at a time. -
wavefrontSizeis an unsigned integer value indicating the maximum size of a subgroup. -
sgprsPerSimdis an unsigned integer value indicating the number of physical Scalar General Purpose Registers (SGPRs) per SIMD. -
minSgprAllocationis an unsigned integer value indicating the minimum number of SGPRs allocated for a wave. -
maxSgprAllocationis an unsigned integer value indicating the maximum number of SGPRs allocated for a wave. -
sgprAllocationGranularityis an unsigned integer value indicating the granularity of SGPR allocation for a wave. -
vgprsPerSimdis an unsigned integer value indicating the number of physical Vector General Purpose Registers (VGPRs) per SIMD. -
minVgprAllocationis an unsigned integer value indicating the minimum number of VGPRs allocated for a wave. -
maxVgprAllocationis an unsigned integer value indicating the maximum number of VGPRs allocated for a wave. -
vgprAllocationGranularityis an unsigned integer value indicating the granularity of VGPR allocation for a wave.
If the VkPhysicalDeviceShaderCorePropertiesAMD structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceShaderCoreProperties2AMD structure is defined as:
// Provided by VK_AMD_shader_core_properties2
typedef struct VkPhysicalDeviceShaderCoreProperties2AMD {
VkStructureType sType;
void* pNext;
VkShaderCorePropertiesFlagsAMD shaderCoreFeatures;
uint32_t activeComputeUnitCount;
} VkPhysicalDeviceShaderCoreProperties2AMD;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderCoreFeaturesis a bitmask of VkShaderCorePropertiesFlagBitsAMD indicating the set of features supported by the shader core. -
activeComputeUnitCountis an unsigned integer value indicating the number of compute units that have been enabled.
If the VkPhysicalDeviceShaderCoreProperties2AMD structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
Bits for this type may be defined by future extensions, or new versions of
the VK_AMD_shader_core_properties2 extension.
Possible values of the flags member of
VkShaderCorePropertiesFlagsAMD are:
// Provided by VK_AMD_shader_core_properties2
typedef enum VkShaderCorePropertiesFlagBitsAMD {
} VkShaderCorePropertiesFlagBitsAMD;
// Provided by VK_AMD_shader_core_properties2
typedef VkFlags VkShaderCorePropertiesFlagsAMD;
VkShaderCorePropertiesFlagsAMD is a bitmask type for providing zero or
more VkShaderCorePropertiesFlagBitsAMD.
The VkPhysicalDeviceDepthStencilResolveProperties structure is defined
as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceDepthStencilResolveProperties {
VkStructureType sType;
void* pNext;
VkResolveModeFlags supportedDepthResolveModes;
VkResolveModeFlags supportedStencilResolveModes;
VkBool32 independentResolveNone;
VkBool32 independentResolve;
} VkPhysicalDeviceDepthStencilResolveProperties;
or the equivalent
// Provided by VK_KHR_depth_stencil_resolve
typedef VkPhysicalDeviceDepthStencilResolveProperties VkPhysicalDeviceDepthStencilResolvePropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
supportedDepthResolveModesis a bitmask of VkResolveModeFlagBits indicating the set of supported depth resolve modes.VK_RESOLVE_MODE_SAMPLE_ZERO_BITmust be included in the set but implementations may support additional modes. -
supportedStencilResolveModesis a bitmask of VkResolveModeFlagBits indicating the set of supported stencil resolve modes.VK_RESOLVE_MODE_SAMPLE_ZERO_BITmust be included in the set but implementations may support additional modes.VK_RESOLVE_MODE_AVERAGE_BITmust not be included in the set. -
independentResolveNoneisVK_TRUEif 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. -
independentResolveisVK_TRUEif 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 supportsindependentResolvemust also supportindependentResolveNone.
If the VkPhysicalDeviceDepthStencilResolveProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDevicePerformanceQueryPropertiesKHR structure is defined
as:
// Provided by VK_KHR_performance_query
typedef struct VkPhysicalDevicePerformanceQueryPropertiesKHR {
VkStructureType sType;
void* pNext;
VkBool32 allowCommandBufferQueryCopies;
} VkPhysicalDevicePerformanceQueryPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
allowCommandBufferQueryCopiesisVK_TRUEif the performance query pools are allowed to be used with vkCmdCopyQueryPoolResults.
If the VkPhysicalDevicePerformanceQueryPropertiesKHR structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceShadingRateImagePropertiesNV structure is defined
as:
// Provided by VK_NV_shading_rate_image
typedef struct VkPhysicalDeviceShadingRateImagePropertiesNV {
VkStructureType sType;
void* pNext;
VkExtent2D shadingRateTexelSize;
uint32_t shadingRatePaletteSize;
uint32_t shadingRateMaxCoarseSamples;
} VkPhysicalDeviceShadingRateImagePropertiesNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shadingRateTexelSizeindicates the width and height of the portion of the framebuffer corresponding to each texel in the shading rate image. -
shadingRatePaletteSizeindicates the maximum number of palette entries supported for the shading rate image. -
shadingRateMaxCoarseSamplesspecifies the maximum number of coverage samples supported in a single fragment. If the product of the fragment size derived from the base shading rate and the number of coverage samples per pixel exceeds this limit, the final shading rate will be adjusted so that its product does not exceed the limit.
If the VkPhysicalDeviceShadingRateImagePropertiesNV 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 are related to the shading rate image feature.
The VkPhysicalDeviceTransformFeedbackPropertiesEXT structure is
defined as:
// Provided by VK_EXT_transform_feedback
typedef struct VkPhysicalDeviceTransformFeedbackPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t maxTransformFeedbackStreams;
uint32_t maxTransformFeedbackBuffers;
VkDeviceSize maxTransformFeedbackBufferSize;
uint32_t maxTransformFeedbackStreamDataSize;
uint32_t maxTransformFeedbackBufferDataSize;
uint32_t maxTransformFeedbackBufferDataStride;
VkBool32 transformFeedbackQueries;
VkBool32 transformFeedbackStreamsLinesTriangles;
VkBool32 transformFeedbackRasterizationStreamSelect;
VkBool32 transformFeedbackDraw;
} VkPhysicalDeviceTransformFeedbackPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxTransformFeedbackStreamsis the maximum number of vertex streams that can be output from geometry shaders declared with theGeometryStreamscapability. If the implementation does not supportVkPhysicalDeviceTransformFeedbackFeaturesEXT::geometryStreamsthenmaxTransformFeedbackStreamsmust be set to1. -
maxTransformFeedbackBuffersis the maximum number of transform feedback buffers that can be bound for capturing shader outputs from the last pre-rasterization shader stage. -
maxTransformFeedbackBufferSizeis the maximum size that can be specified when binding a buffer for transform feedback in vkCmdBindTransformFeedbackBuffersEXT. -
maxTransformFeedbackStreamDataSizeis the maximum amount of data in bytes for each vertex that captured to one or more transform feedback buffers associated with a specific vertex stream. -
maxTransformFeedbackBufferDataSizeis the maximum amount of data in bytes for each vertex that can be captured to a specific transform feedback buffer. -
maxTransformFeedbackBufferDataStrideis the maximum stride between each capture of vertex data to the buffer. -
transformFeedbackQueriesisVK_TRUEif the implementation supports theVK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXTquery type.transformFeedbackQueriesisVK_FALSEif queries of this type cannot be created. -
transformFeedbackStreamsLinesTrianglesisVK_TRUEif the implementation supports the geometry shaderOpExecutionModeofOutputLineStripandOutputTriangleStripin addition toOutputPointswhen more than one vertex stream is output. IftransformFeedbackStreamsLinesTrianglesisVK_FALSEthe implementation only supports anOpExecutionModeofOutputPointswhen more than one vertex stream is output from the geometry shader. -
transformFeedbackRasterizationStreamSelectisVK_TRUEif the implementation supports theGeometryStreamsSPIR-V capability and the application can use VkPipelineRasterizationStateStreamCreateInfoEXT to modify which vertex stream output is used for rasterization. Otherwise vertex stream0must always be used for rasterization. -
transformFeedbackDrawisVK_TRUEif the implementation supports the vkCmdDrawIndirectByteCountEXT function otherwise the function must not be called.
If the VkPhysicalDeviceTransformFeedbackPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceRayTracingPropertiesNV structure is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkPhysicalDeviceRayTracingPropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t shaderGroupHandleSize;
uint32_t maxRecursionDepth;
uint32_t maxShaderGroupStride;
uint32_t shaderGroupBaseAlignment;
uint64_t maxGeometryCount;
uint64_t maxInstanceCount;
uint64_t maxTriangleCount;
uint32_t maxDescriptorSetAccelerationStructures;
} VkPhysicalDeviceRayTracingPropertiesNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderGroupHandleSizeis the size in bytes of the shader header. -
maxRecursionDepthis the maximum number of levels of recursion allowed in a trace command. -
maxShaderGroupStrideis the maximum stride in bytes allowed between shader groups in the shader binding table. -
shaderGroupBaseAlignmentis the required alignment in bytes for the base of the shader binding table. -
maxGeometryCountis the maximum number of geometries in the bottom level acceleration structure. -
maxInstanceCountis the maximum number of instances in the top level acceleration structure. -
maxTriangleCountis the maximum number of triangles in all geometries in the bottom level acceleration structure. -
maxDescriptorSetAccelerationStructuresis the maximum number of acceleration structure descriptors that are allowed in a descriptor set.
Due to the fact that the geometry, instance, and triangle counts are
specified at acceleration structure creation as 32-bit values,
maxGeometryCount, maxInstanceCount, and maxTriangleCount
must not exceed 232-1.
If the VkPhysicalDeviceRayTracingPropertiesNV structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
Limits specified by this structure must match those specified with the same name in VkPhysicalDeviceAccelerationStructurePropertiesKHR and VkPhysicalDeviceRayTracingPipelinePropertiesKHR.
The VkPhysicalDeviceAccelerationStructurePropertiesKHR structure is
defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkPhysicalDeviceAccelerationStructurePropertiesKHR {
VkStructureType sType;
void* pNext;
uint64_t maxGeometryCount;
uint64_t maxInstanceCount;
uint64_t maxPrimitiveCount;
uint32_t maxPerStageDescriptorAccelerationStructures;
uint32_t maxPerStageDescriptorUpdateAfterBindAccelerationStructures;
uint32_t maxDescriptorSetAccelerationStructures;
uint32_t maxDescriptorSetUpdateAfterBindAccelerationStructures;
uint32_t minAccelerationStructureScratchOffsetAlignment;
} VkPhysicalDeviceAccelerationStructurePropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxGeometryCountis the maximum number of geometries in the bottom level acceleration structure. -
maxInstanceCountis the maximum number of instances in the top level acceleration structure. -
maxPrimitiveCountis the maximum number of triangles or AABBs in all geometries in the bottom level acceleration structure. -
maxPerStageDescriptorAccelerationStructuresis the maximum number of acceleration structure bindings that can be accessible to a single shader stage in a pipeline layout. Descriptor bindings with a descriptor type ofVK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHRcount against this limit. Only descriptor bindings in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. -
maxPerStageDescriptorUpdateAfterBindAccelerationStructuresis similar tomaxPerStageDescriptorAccelerationStructuresbut counts descriptor bindings from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetAccelerationStructuresis the maximum number of acceleration structure descriptors 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_ACCELERATION_STRUCTURE_KHRcount against this limit. Only descriptor bindings in descriptor set layouts created without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set count against this limit. -
maxDescriptorSetUpdateAfterBindAccelerationStructuresis similar tomaxDescriptorSetAccelerationStructuresbut counts descriptor bindings from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
minAccelerationStructureScratchOffsetAlignmentis the minimum required alignment, in bytes, for scratch data passed in to an acceleration structure build command. The value must be a power of two.
Due to the fact that the geometry, instance, and primitive counts are
specified at acceleration structure creation as 32-bit values,
maxGeometryCount,
maxInstanceCount, and
maxPrimitiveCount must not exceed
232-1.
If the VkPhysicalDeviceAccelerationStructurePropertiesKHR structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
Limits specified by this structure must match those specified with the same name in VkPhysicalDeviceRayTracingPropertiesNV.
The VkPhysicalDeviceRayTracingPipelinePropertiesKHR structure is
defined as:
// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkPhysicalDeviceRayTracingPipelinePropertiesKHR {
VkStructureType sType;
void* pNext;
uint32_t shaderGroupHandleSize;
uint32_t maxRayRecursionDepth;
uint32_t maxShaderGroupStride;
uint32_t shaderGroupBaseAlignment;
uint32_t shaderGroupHandleCaptureReplaySize;
uint32_t maxRayDispatchInvocationCount;
uint32_t shaderGroupHandleAlignment;
uint32_t maxRayHitAttributeSize;
} VkPhysicalDeviceRayTracingPipelinePropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderGroupHandleSizeis the size in bytes of the shader header. -
maxRayRecursionDepthis the maximum number of levels of ray recursion allowed in a trace command. -
maxShaderGroupStrideis the maximum stride in bytes allowed between shader groups in the shader binding table. -
shaderGroupBaseAlignmentis the required alignment in bytes for the base of the shader binding table. -
shaderGroupHandleCaptureReplaySizeis the number of bytes for the information required to do capture and replay for shader group handles. -
maxRayDispatchInvocationCountis the maximum number of ray generation shader invocations which may be produced by a single vkCmdTraceRaysIndirectKHR or vkCmdTraceRaysKHR command. -
shaderGroupHandleAlignmentis the required alignment in bytes for each shader binding table entry. The value must be a power of two. -
maxRayHitAttributeSizeis the maximum size in bytes for a ray attribute structure
If the VkPhysicalDeviceRayTracingPipelinePropertiesKHR structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
Limits specified by this structure must match those specified with the same name in VkPhysicalDeviceRayTracingPropertiesNV.
The VkPhysicalDeviceCooperativeMatrixPropertiesNV structure is defined
as:
// Provided by VK_NV_cooperative_matrix
typedef struct VkPhysicalDeviceCooperativeMatrixPropertiesNV {
VkStructureType sType;
void* pNext;
VkShaderStageFlags cooperativeMatrixSupportedStages;
} VkPhysicalDeviceCooperativeMatrixPropertiesNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cooperativeMatrixSupportedStagesis a bitfield of VkShaderStageFlagBits describing the shader stages that cooperative matrix instructions are supported in.cooperativeMatrixSupportedStageswill have theVK_SHADER_STAGE_COMPUTE_BITbit set if any of the physical device’s queues supportVK_QUEUE_COMPUTE_BIT.
If the VkPhysicalDeviceCooperativeMatrixPropertiesNV structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceShaderSMBuiltinsPropertiesNV structure is defined
as:
// Provided by VK_NV_shader_sm_builtins
typedef struct VkPhysicalDeviceShaderSMBuiltinsPropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t shaderSMCount;
uint32_t shaderWarpsPerSM;
} VkPhysicalDeviceShaderSMBuiltinsPropertiesNV;
If the VkPhysicalDeviceShaderSMBuiltinsPropertiesNV structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceTexelBufferAlignmentProperties structure is
defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceTexelBufferAlignmentProperties {
VkStructureType sType;
void* pNext;
VkDeviceSize storageTexelBufferOffsetAlignmentBytes;
VkBool32 storageTexelBufferOffsetSingleTexelAlignment;
VkDeviceSize uniformTexelBufferOffsetAlignmentBytes;
VkBool32 uniformTexelBufferOffsetSingleTexelAlignment;
} VkPhysicalDeviceTexelBufferAlignmentProperties;
or the equivalent
// Provided by VK_EXT_texel_buffer_alignment
typedef VkPhysicalDeviceTexelBufferAlignmentProperties VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
storageTexelBufferOffsetAlignmentBytesis a byte alignment that is sufficient for a storage texel buffer of any format. The value must be a power of two. -
storageTexelBufferOffsetSingleTexelAlignmentindicates whether single texel alignment is sufficient for a storage texel buffer of any format. -
uniformTexelBufferOffsetAlignmentBytesis a byte alignment that is sufficient for a uniform texel buffer of any format. The value must be a power of two. -
uniformTexelBufferOffsetSingleTexelAlignmentindicates whether single texel alignment is sufficient for a uniform texel buffer of any format.
If the VkPhysicalDeviceTexelBufferAlignmentProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
If the single texel alignment property is VK_FALSE, then the buffer
view’s offset must be aligned to the corresponding byte alignment value.
If the single texel alignment property is VK_TRUE, then the buffer
view’s offset must be aligned to the lesser of the corresponding byte
alignment value or the size of a single texel, based on
VkBufferViewCreateInfo::format.
If the size of a single texel is a multiple of three bytes, then the size of
a single component of the format is used instead.
These limits must not advertise a larger alignment than the
required maximum minimum value of
VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment, for any
format that supports use as a texel buffer.
The VkPhysicalDeviceTimelineSemaphoreProperties structure is defined
as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceTimelineSemaphoreProperties {
VkStructureType sType;
void* pNext;
uint64_t maxTimelineSemaphoreValueDifference;
} VkPhysicalDeviceTimelineSemaphoreProperties;
or the equivalent
// Provided by VK_KHR_timeline_semaphore
typedef VkPhysicalDeviceTimelineSemaphoreProperties VkPhysicalDeviceTimelineSemaphorePropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceTimelineSemaphoreProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceLineRasterizationPropertiesEXT structure is
defined as:
// Provided by VK_EXT_line_rasterization
typedef struct VkPhysicalDeviceLineRasterizationPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t lineSubPixelPrecisionBits;
} VkPhysicalDeviceLineRasterizationPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
lineSubPixelPrecisionBitsis the number of bits of subpixel precision in framebuffer coordinates xf and yf when rasterizing line segments.
If the VkPhysicalDeviceLineRasterizationPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceRobustness2PropertiesEXT structure is defined as:
// Provided by VK_EXT_robustness2
typedef struct VkPhysicalDeviceRobustness2PropertiesEXT {
VkStructureType sType;
void* pNext;
VkDeviceSize robustStorageBufferAccessSizeAlignment;
VkDeviceSize robustUniformBufferAccessSizeAlignment;
} VkPhysicalDeviceRobustness2PropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
robustStorageBufferAccessSizeAlignmentis the number of bytes that the range of a storage buffer descriptor is rounded up to when used for bounds-checking when therobustBufferAccess2feature is enabled. This value must be either 1 or 4. -
robustUniformBufferAccessSizeAlignmentis the number of bytes that the range of a uniform buffer descriptor is rounded up to when used for bounds-checking when therobustBufferAccess2feature is enabled. This value must be a power of two in the range [1, 256].
If the VkPhysicalDeviceRobustness2PropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV structure is
defined as:
// Provided by VK_NV_device_generated_commands
typedef struct VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t maxGraphicsShaderGroupCount;
uint32_t maxIndirectSequenceCount;
uint32_t maxIndirectCommandsTokenCount;
uint32_t maxIndirectCommandsStreamCount;
uint32_t maxIndirectCommandsTokenOffset;
uint32_t maxIndirectCommandsStreamStride;
uint32_t minSequencesCountBufferOffsetAlignment;
uint32_t minSequencesIndexBufferOffsetAlignment;
uint32_t minIndirectCommandsBufferOffsetAlignment;
} VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxGraphicsShaderGroupCountis the maximum number of shader groups in VkGraphicsPipelineShaderGroupsCreateInfoNV. -
maxIndirectSequenceCountis the maximum number of sequences in VkGeneratedCommandsInfoNV and in VkGeneratedCommandsMemoryRequirementsInfoNV. -
maxIndirectCommandsTokenCountis the maximum number of tokens in VkIndirectCommandsLayoutCreateInfoNV. -
maxIndirectCommandsStreamCountis the maximum number of streams in VkIndirectCommandsLayoutCreateInfoNV. -
maxIndirectCommandsTokenOffsetis the maximum offset inVkIndirectCommandsLayoutTokenNV. -
maxIndirectCommandsStreamStrideis the maximum stream stride in VkIndirectCommandsLayoutCreateInfoNV. -
minSequencesCountBufferOffsetAlignmentis the minimum alignment for memory addresses which can be used inVkGeneratedCommandsInfoNV. -
minSequencesIndexBufferOffsetAlignmentis the minimum alignment for memory addresses which can be used inVkGeneratedCommandsInfoNV. -
minIndirectCommandsBufferOffsetAlignmentis the minimum alignment for memory addresses used inVkIndirectCommandsStreamNV, and as preprocess buffer inVkGeneratedCommandsInfoNV.
If the VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDevicePortabilitySubsetPropertiesKHR structure is
defined as:
// Provided by VK_KHR_portability_subset
typedef struct VkPhysicalDevicePortabilitySubsetPropertiesKHR {
VkStructureType sType;
void* pNext;
uint32_t minVertexInputBindingStrideAlignment;
} VkPhysicalDevicePortabilitySubsetPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minVertexInputBindingStrideAlignmentindicates the minimum alignment for vertex input strides. VkVertexInputBindingDescription::stridemust be a multiple of, and at least as large as, this value. The value must be a power of two.
If the VkPhysicalDevicePortabilitySubsetPropertiesKHR structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceFragmentShadingRatePropertiesKHR structure is
defined as:
// Provided by VK_KHR_fragment_shading_rate
typedef struct VkPhysicalDeviceFragmentShadingRatePropertiesKHR {
VkStructureType sType;
void* pNext;
VkExtent2D minFragmentShadingRateAttachmentTexelSize;
VkExtent2D maxFragmentShadingRateAttachmentTexelSize;
uint32_t maxFragmentShadingRateAttachmentTexelSizeAspectRatio;
VkBool32 primitiveFragmentShadingRateWithMultipleViewports;
VkBool32 layeredShadingRateAttachments;
VkBool32 fragmentShadingRateNonTrivialCombinerOps;
VkExtent2D maxFragmentSize;
uint32_t maxFragmentSizeAspectRatio;
uint32_t maxFragmentShadingRateCoverageSamples;
VkSampleCountFlagBits maxFragmentShadingRateRasterizationSamples;
VkBool32 fragmentShadingRateWithShaderDepthStencilWrites;
VkBool32 fragmentShadingRateWithSampleMask;
VkBool32 fragmentShadingRateWithShaderSampleMask;
VkBool32 fragmentShadingRateWithConservativeRasterization;
VkBool32 fragmentShadingRateWithFragmentShaderInterlock;
VkBool32 fragmentShadingRateWithCustomSampleLocations;
VkBool32 fragmentShadingRateStrictMultiplyCombiner;
} VkPhysicalDeviceFragmentShadingRatePropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minFragmentShadingRateAttachmentTexelSizeindicates minimum supported width and height of the portion of the framebuffer corresponding to each texel in a fragment shading rate attachment. Each value must be less than or equal to the values inmaxFragmentShadingRateAttachmentTexelSize. Each value must be a power-of-two. It must be (0,0) if theattachmentFragmentShadingRatefeature is not supported. -
maxFragmentShadingRateAttachmentTexelSizeindicates maximum supported width and height of the portion of the framebuffer corresponding to each texel in a fragment shading rate attachment. Each value must be greater than or equal to the values inminFragmentShadingRateAttachmentTexelSize. Each value must be a power-of-two. It must be (0,0) if theattachmentFragmentShadingRatefeature is not supported. -
maxFragmentShadingRateAttachmentTexelSizeAspectRatioindicates the maximum ratio between the width and height of the portion of the framebuffer corresponding to each texel in a fragment shading rate attachment.maxFragmentShadingRateAttachmentTexelSizeAspectRatiomust be a power-of-two value, and must be less than or equal to max(maxFragmentShadingRateAttachmentTexelSize.width/minFragmentShadingRateAttachmentTexelSize.height,maxFragmentShadingRateAttachmentTexelSize.height/minFragmentShadingRateAttachmentTexelSize.width). It must be 0 if theattachmentFragmentShadingRatefeature is not supported. -
primitiveFragmentShadingRateWithMultipleViewportsspecifies whether the primitive fragment shading rate can be used when multiple viewports are used. If this value isVK_FALSE, only a single viewport must be used, and applications must not write to theViewportMaskNVorViewportIndexbuilt-in when settingPrimitiveShadingRateKHR. It must beVK_FALSEif theshaderOutputViewportIndexfeature, theVK_EXT_shader_viewport_index_layerextension, or thegeometryShaderfeature is not supported, or if theprimitiveFragmentShadingRatefeature is not supported. -
layeredShadingRateAttachmentsspecifies whether a shading rate attachment image view can be created with multiple layers. If this value isVK_FALSE, when creating an image view with ausagethat includesVK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,layerCountmust be1. It must beVK_FALSEif themultiviewfeature, theshaderOutputViewportIndexfeature, theVK_EXT_shader_viewport_index_layerextension, or thegeometryShaderfeature is not supported, or if theattachmentFragmentShadingRatefeature is not supported. -
fragmentShadingRateNonTrivialCombinerOpsspecifies whether VkFragmentShadingRateCombinerOpKHR enums other thanVK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHRorVK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHRcan be used. It must beVK_FALSEunless either theprimitiveFragmentShadingRateorattachmentFragmentShadingRatefeature is supported. -
maxFragmentSizeindicates the maximum supported width and height of a fragment. Itswidthandheightmembers must both be power-of-two values. This limit is purely informational, and is not validated. -
maxFragmentSizeAspectRatioindicates the maximum ratio between the width and height of a fragment.maxFragmentSizeAspectRatiomust be a power-of-two value, and must be less than or equal to the maximum of thewidthandheightmembers ofmaxFragmentSize. This limit is purely informational, and is not validated. -
maxFragmentShadingRateCoverageSamplesspecifies the maximum number of coverage samples supported in a single fragment.maxFragmentShadingRateCoverageSamplesmust be less than or equal to the product of thewidthandheightmembers ofmaxFragmentSize, and the sample count reported bymaxFragmentShadingRateRasterizationSamples.maxFragmentShadingRateCoverageSamplesmust be less than or equal tomaxSampleMaskWords× 32 iffragmentShadingRateWithShaderSampleMaskis supported. This limit is purely informational, and is not validated. -
maxFragmentShadingRateRasterizationSamplesis a VkSampleCountFlagBits value specifying the maximum sample rate supported when a fragment covers multiple pixels. This limit is purely informational, and is not validated. -
fragmentShadingRateWithShaderDepthStencilWritesspecifies whether the implementation supports writingFragDepthorFragStencilRefEXTfrom a fragment shader for multi-pixel fragments. If this value isVK_FALSE, writing to those built-ins will clamp the fragment shading rate to (1,1). -
fragmentShadingRateWithSampleMaskspecifies whether the the implementation supports setting valid bits of VkPipelineMultisampleStateCreateInfo::pSampleMaskto0for multi-pixel fragments. If this value isVK_FALSE, zeroing valid bits in the sample mask will clamp the fragment shading rate to (1,1). -
fragmentShadingRateWithShaderSampleMaskspecifies whether the implementation supports reading or writingSampleMaskfor multi-pixel fragments. If this value isVK_FALSE, using that built-in will clamp the fragment shading rate to (1,1). -
fragmentShadingRateWithConservativeRasterizationspecifies whether conservative rasterization is supported for multi-pixel fragments. It must beVK_FALSEifVK_EXT_conservative_rasterizationis not supported. If this value isVK_FALSE, using conservative rasterization will clamp the fragment shading rate to (1,1). -
fragmentShadingRateWithFragmentShaderInterlockspecifies whether fragment shader interlock is supported for multi-pixel fragments. It must beVK_FALSEifVK_EXT_fragment_shader_interlockis not supported. If this value isVK_FALSE, using fragment shader interlock will clamp the fragment shading rate to (1,1). -
fragmentShadingRateWithCustomSampleLocationsspecifies whether custom sample locations are supported for multi-pixel fragments. It must beVK_FALSEifVK_EXT_sample_locationsis not supported. If this value isVK_FALSE, using custom sample locations will clamp the fragment shading rate to (1,1). -
fragmentShadingRateStrictMultiplyCombinerspecifies whetherVK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHRaccurately performs a multiplication or not. Implementations where this value isVK_FALSEwill instead combine rates with an addition. IffragmentShadingRateNonTrivialCombinerOpsisVK_FALSE, implementations must report this asVK_FALSE. IffragmentShadingRateNonTrivialCombinerOpsisVK_TRUE, implementations should report this asVK_TRUE.
|
Note
Multiplication of the combiner rates using the fragment width/height in
linear space is equivalent to an addition of those values in log2 space.
Some implementations inadvertently implemented an addition in linear space
due to unclear requirements originating outside of this specification.
This resulted in |
If the VkPhysicalDeviceFragmentShadingRatePropertiesKHR 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 are related to fragment shading rates.
The VkPhysicalDeviceFragmentShadingRateEnumsPropertiesNV structure is
defined as:
// Provided by VK_NV_fragment_shading_rate_enums
typedef struct VkPhysicalDeviceFragmentShadingRateEnumsPropertiesNV {
VkStructureType sType;
void* pNext;
VkSampleCountFlagBits maxFragmentShadingRateInvocationCount;
} VkPhysicalDeviceFragmentShadingRateEnumsPropertiesNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxFragmentShadingRateInvocationCountis a VkSampleCountFlagBits value indicating the maximum number of fragment shader invocations per fragment supported in pipeline, primitive, and attachment fragment shading rates.
If the VkPhysicalDeviceFragmentShadingRateEnumsPropertiesNV 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 are related to fragment shading rates.
The VkPhysicalDeviceCustomBorderColorPropertiesEXT structure is
defined as:
// Provided by VK_EXT_custom_border_color
typedef struct VkPhysicalDeviceCustomBorderColorPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t maxCustomBorderColorSamplers;
} VkPhysicalDeviceCustomBorderColorPropertiesEXT;
If the VkPhysicalDeviceCustomBorderColorPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceProvokingVertexPropertiesEXT structure is defined
as:
// Provided by VK_EXT_provoking_vertex
typedef struct VkPhysicalDeviceProvokingVertexPropertiesEXT {
VkStructureType sType;
void* pNext;
VkBool32 provokingVertexModePerPipeline;
VkBool32 transformFeedbackPreservesTriangleFanProvokingVertex;
} VkPhysicalDeviceProvokingVertexPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
provokingVertexModePerPipelineindicates whether the implementation supports graphics pipelines with different provoking vertex modes within the same render pass instance. -
transformFeedbackPreservesTriangleFanProvokingVertexindicates whether the implementation can preserve the provoking vertex order when writing triangle fan vertices to transform feedback.
If the VkPhysicalDeviceProvokingVertexPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceSubpassShadingPropertiesHUAWEI structure is
defined as:
// Provided by VK_HUAWEI_subpass_shading
typedef struct VkPhysicalDeviceSubpassShadingPropertiesHUAWEI {
VkStructureType sType;
void* pNext;
uint32_t maxSubpassShadingWorkgroupSizeAspectRatio;
} VkPhysicalDeviceSubpassShadingPropertiesHUAWEI;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxSubpassShadingWorkgroupSizeAspectRatioindicates the maximum ratio between the width and height of the portion of the subpass shading shader workgroup size.maxSubpassShadingWorkgroupSizeAspectRatiomust be a power-of-two value, and must be less than or equal to max(WorkgroupSize.x/WorkgroupSize.y,WorkgroupSize.y/WorkgroupSize.x).
If the VkPhysicalDeviceSubpassShadingPropertiesHUAWEI structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceMultiDrawPropertiesEXT structure is defined as:
// Provided by VK_EXT_multi_draw
typedef struct VkPhysicalDeviceMultiDrawPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t maxMultiDrawCount;
} VkPhysicalDeviceMultiDrawPropertiesEXT;
The members of the VkPhysicalDeviceMultiDrawPropertiesEXT structure
describe the following features:
If the VkPhysicalDeviceMultiDrawPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceGraphicsPipelineLibraryPropertiesEXT structure is
defined as:
// Provided by VK_EXT_graphics_pipeline_library
typedef struct VkPhysicalDeviceGraphicsPipelineLibraryPropertiesEXT {
VkStructureType sType;
void* pNext;
VkBool32 graphicsPipelineLibraryFastLinking;
VkBool32 graphicsPipelineLibraryIndependentInterpolationDecoration;
} VkPhysicalDeviceGraphicsPipelineLibraryPropertiesEXT;
-
graphicsPipelineLibraryFastLinkingindicates whether fast linking of graphics pipelines is supported. If it isVK_TRUE, creating a graphics pipeline entirely from pipeline libraries withoutVK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXTis comparable in cost to recording a command in a command buffer. -
graphicsPipelineLibraryIndependentInterpolationDecorationindicates whetherNoPerspectiveandFlatinterpolation decorations in the last vertex processing stage and the fragment shader are required to match when using graphics pipeline libraries. If it isVK_TRUE, the interpolation decorations do not need to match. If it isVK_FALSE, these decorations must either be present in both stages or neither stage in order for a given interface variable to match.
If the VkPhysicalDeviceGraphicsPipelineLibraryPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceFragmentShaderBarycentricPropertiesKHR structure
is defined as:
// Provided by VK_KHR_fragment_shader_barycentric
typedef struct VkPhysicalDeviceFragmentShaderBarycentricPropertiesKHR {
VkStructureType sType;
void* pNext;
VkBool32 triStripVertexOrderIndependentOfProvokingVertex;
} VkPhysicalDeviceFragmentShaderBarycentricPropertiesKHR;
-
triStripVertexOrderIndependentOfProvokingVertexindicates that the implementation does not change its vertex numbering for triangle strip primitives when the provoking vertex mode isVK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, as shown in the last vertex table.
If the VkPhysicalDeviceFragmentShaderBarycentricPropertiesKHR structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDeviceShaderModuleIdentifierPropertiesEXT structure is
defined as:
// Provided by VK_EXT_shader_module_identifier
typedef struct VkPhysicalDeviceShaderModuleIdentifierPropertiesEXT {
VkStructureType sType;
void* pNext;
uint8_t shaderModuleIdentifierAlgorithmUUID[VK_UUID_SIZE];
} VkPhysicalDeviceShaderModuleIdentifierPropertiesEXT;
The members of the VkPhysicalDeviceShaderModuleIdentifierPropertiesEXT
structure describe the following:
-
shaderModuleIdentifierAlgorithmUUIDis an array ofVK_UUID_SIZEuint8_tvalues which uniquely represents the algorithm used to compute an identifier in vkGetShaderModuleIdentifierEXT and vkGetShaderModuleCreateInfoIdentifierEXT. Implementations should not change this value in different driver versions if the algorithm used to compute an identifier is the same.
|
Note
The algorithm UUID may be the same in different ICDs if the algorithms are guaranteed to produce the same results. This may happen in driver stacks which support different kinds of hardware with shared code. Khronos' conformance testing can not guarantee that
|
If the VkPhysicalDeviceShaderModuleIdentifierPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
The VkPhysicalDevicePipelineRobustnessPropertiesEXT structure is
defined as:
// Provided by VK_EXT_pipeline_robustness
typedef struct VkPhysicalDevicePipelineRobustnessPropertiesEXT {
VkStructureType sType;
void* pNext;
VkPipelineRobustnessBufferBehaviorEXT defaultRobustnessStorageBuffers;
VkPipelineRobustnessBufferBehaviorEXT defaultRobustnessUniformBuffers;
VkPipelineRobustnessBufferBehaviorEXT defaultRobustnessVertexInputs;
VkPipelineRobustnessImageBehaviorEXT defaultRobustnessImages;
} VkPhysicalDevicePipelineRobustnessPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
defaultRobustnessStorageBuffersdescribes the behaviour of out of bounds accesses made to storage buffers when no robustness features are enabled -
defaultRobustnessUniformBuffersdescribes the behaviour of out of bounds accesses made to uniform buffers when no robustness features are enabled -
defaultRobustnessVertexInputsdescribes the behaviour of out of bounds accesses made to vertex input attributes when no robustness features are enabled -
defaultRobustnessImagesdescribes the behaviour of out of bounds accesses made to images when no robustness features are enabled
Some implementations of Vulkan may be able to guarantee that certain types of accesses are always performed with robustness even when the Vulkan API’s robustness features are not explicitly enabled.
Even when an implementation reports that accesses to a given resource type are robust by default, it remains invalid to make an out of bounds access without requesting the appropriate robustness feature.
If the VkPhysicalDevicePipelineRobustnessPropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
42.1. Limit Requirements
The following table specifies the required minimum/maximum for all Vulkan graphics implementations. Where a limit corresponds to a fine-grained device feature which is optional, the feature name is listed with two required limits, one when the feature is supported and one when it is not supported. If an implementation supports a feature, the limits reported are the same whether or not the feature is enabled.
| Type | Limit | Feature |
|---|---|---|
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- |
|
|
- |
|
|
|
|
|
- |
|
|
- |
3 × |
|
- |
|
|
- |
3 × |
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
|
|
|
- |
|
|
|
|
|
|
2 × |
|
- |
2 × |
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- |
|
|
- |
|
|
- |
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
- |
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
|
|
|
|
|
|
- |
2 × |
|
|
2 × |
|
|
|
|
|
|
|
|
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2 × |
|
|
2 × |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2 × |
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
- |
| Limit | Unsupported Limit | Supported Limit | Limit Type1 |
|---|---|---|---|
|
- |
4096 |
min |
|
- |
4096 |
min |
|
- |
256 |
min |
|
- |
4096 |
min |
|
- |
256 |
min |
|
- |
65536 |
min |
|
- |
16384 |
min |
|
- |
227 |
min |
|
- |
128 |
min |
|
- |
4096 |
min |
|
- |
4000 |
min |
|
- |
131072 |
max |
|
0 |
231 |
min |
|
- |
4 |
min |
|
- |
16 |
min |
|
- |
12 |
min |
|
- |
4 |
min |
|
- |
16 |
min |
|
- |
4 |
min |
|
- |
4 |
min |
|
- |
128 2 |
min |
|
- |
96 8 |
min, n × PerStage |
|
- |
72 8 |
min, n × PerStage |
|
- |
8 |
min |
|
- |
24 8 |
min, n × PerStage |
|
- |
4 |
min |
|
- |
96 8 |
min, n × PerStage |
|
- |
24 8 |
min, n × PerStage |
|
- |
4 |
min |
|
- |
16 |
min |
|
- |
16 10 |
min |
|
- |
2047 |
min |
|
- |
2048 |
min |
|
- |
64 |
min |
|
0 |
64 |
min |
|
0 |
32 |
min |
|
0 |
64 |
min |
|
0 |
64 |
min |
|
0 |
120 |
min |
|
0 |
2048 |
min |
|
0 |
64 |
min |
|
0 |
64 |
min |
|
0 |
32 |
min |
|
0 |
64 |
min |
|
0 |
64 |
min |
|
0 |
256 |
min |
|
0 |
1024 |
min |
|
- |
64 |
min |
|
- |
4 |
min |
|
0 |
1 |
min |
|
- |
4 |
min |
|
- |
16384 |
min |
|
- |
(65535,65535,65535) |
min |
|
- |
128 |
min |
|
- |
(128,128,64) |
min |
|
- |
4 |
min |
|
- |
4 |
min |
|
- |
4 |
min |
|
224-1 |
232-1 |
min |
|
1 |
216-1 |
min |
|
- |
2 |
min |
|
1 |
16 |
min |
|
1 |
16 |
min |
|
- |
(4096,4096) 3 |
min |
|
- |
(-8192,8191) 4 |
(max,min) |
|
- |
0 |
min |
|
- |
64 |
min |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
-8 |
max |
|
- |
7 |
min |
|
0 |
-8 |
max |
|
0 |
7 |
min |
|
0.0 |
-0.5 5 |
max |
|
0.0 |
0.5 - (1 ULP) 5 |
min |
|
0 |
4 5 |
min |
|
- |
4096 |
min |
|
- |
4096 |
min |
|
- |
256 |
min |
|
- |
( |
min |
|
- |
( |
min |
|
- |
( |
min |
|
- |
( |
min |
|
- |
( |
min |
|
- |
4 |
min |
|
- |
( |
min |
|
- |
|
min |
|
- |
( |
min |
|
- |
( |
min |
|
|
( |
min |
|
- |
1 |
min |
|
- |
- |
implementation-dependent |
|
- |
- |
duration |
|
0 |
8 |
min |
|
0 |
8 |
min |
|
0 |
8 |
min |
|
- |
2 |
min |
|
(1.0,1.0) |
(1.0,64.0 - ULP)6 |
(max,min) |
|
(1.0,1.0) |
(1.0,8.0 - ULP)7 |
(max,min) |
|
0.0 |
1.0 6 |
max, fixed point increment |
|
0.0 |
1.0 7 |
max, fixed point increment |
|
- |
- |
implementation-dependent |
|
- |
- |
implementation-dependent |
|
- |
- |
recommendation |
|
- |
- |
recommendation |
|
- |
256 |
max |
|
- |
32 |
min |
|
- |
6 |
min |
|
- |
227-1 |
min |
|
0 |
4 |
min |
|
- |
|
min |
|
- |
(1,1) |
min |
|
- |
(0.0, 0.9375) |
(max,min) |
|
- |
4 |
min |
|
- |
false |
implementation-dependent |
|
- |
65536 |
max |
|
- |
- |
implementation-dependent |
|
- |
- |
implementation-dependent |
|
- |
- |
implementation-dependent |
|
- |
1 |
min |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
1024 |
min |
|
- |
230 |
min |
|
- |
230 |
min |
|
- |
0.0 |
min |
|
- |
0.0 |
min |
|
- |
0.0 |
min |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
0 |
500000 |
min |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
09 |
500000 9 |
min |
|
09 |
12 9 |
min |
|
09 |
500000 9 |
min |
|
09 |
500000 9 |
min |
|
09 |
500000 9 |
min |
|
09 |
4 9 |
min |
|
09 |
500000 9 |
min |
|
09 |
500000 9 |
min |
|
09 |
72 8 9 |
min, n × PerStage |
|
09 |
8 9 |
min |
|
09 |
500000 9 |
min |
|
09 |
4 9 |
min |
|
09 |
500000 9 |
min |
|
09 |
500000 9 |
min |
|
09 |
4 9 |
min |
|
- |
256 |
min |
|
- |
4 |
min |
|
- |
4 |
min |
|
- |
4 |
min |
|
- |
4 |
min |
|
- |
256 |
min |
|
- |
216-1 |
min |
|
- |
216-1 |
min |
|
- |
32 |
min |
|
- |
(32,1,1) |
min |
|
- |
16384 |
min |
|
- |
216-1 |
min |
|
- |
32 |
min |
|
- |
(32,1,1) |
min |
|
- |
16384 |
min |
|
- |
256 |
min |
|
- |
256 |
min |
|
- |
1 |
min |
|
- |
- |
implementation-dependent |
|
- |
- |
implementation-dependent |
|
- |
1 |
min |
|
- |
1 |
min |
|
- |
227 |
min |
|
- |
512 |
min |
|
- |
512 |
min |
|
- |
512 |
min |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
(1,1) |
min |
|
- |
(1,1) |
min |
|
- |
- |
implementation-dependent |
|
true |
false |
implementation-dependent |
|
false |
false |
implementation-dependent |
|
2 |
2 |
min |
|
1 |
1 |
min |
|
- |
(1024,1024) |
max |
VkPhysicalDeviceRayTracingPropertiesNV:: |
- |
16 |
min |
VkPhysicalDeviceRayTracingPropertiesNV:: |
- |
31 |
min |
VkPhysicalDeviceRayTracingPipelinePropertiesKHR:: |
- |
32 |
exact |
VkPhysicalDeviceRayTracingPipelinePropertiesKHR:: |
- |
1 |
min |
|
- |
4096 |
min |
|
- |
64 |
max |
|
- |
224-1 |
min |
|
- |
224-1 |
min |
|
- |
229-1 |
min |
|
- |
229-1 |
min |
|
- |
16 |
min |
|
- |
500000 9 |
min |
|
- |
16 |
min |
|
- |
500000 9 |
min |
|
- |
256 |
max |
|
- |
64 |
max |
|
- |
230 |
min |
|
- |
32 |
max |
|
- |
32 |
min |
|
- |
231-1 |
min |
|
- |
4 |
min |
|
- |
212 |
min |
|
- |
220 |
min |
|
- |
16 |
min |
|
- |
16 |
min |
|
- |
2047 |
min |
|
- |
2048 |
min |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
32 |
min |
|
- |
4 |
max |
|
- |
256 |
max |
|
(0,0) |
(32,32) |
max |
|
(0,0) |
(8,8) |
min |
|
0 |
1 |
min |
|
false |
false |
implementation-dependent |
|
false |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
(2,2) |
min |
|
- |
2 |
min |
|
- |
16 |
min |
|
- |
|
min |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
|
min |
|
0 |
1 |
min |
|
- |
1024 |
min |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
- 1
-
The Limit Type column specifies the limit is either the minimum limit all implementations must support, the maximum limit all implementations must support, or the exact value all implementations must support. For bitmasks a minimum limit is the least bits all implementations must set, but they may have additional bits set beyond this minimum.
- 2
-
The
maxPerStageResourcesmust be at least the smallest of the following:-
the sum of the
maxPerStageDescriptorUniformBuffers,maxPerStageDescriptorStorageBuffers,maxPerStageDescriptorSampledImages,maxPerStageDescriptorStorageImages,maxPerStageDescriptorInputAttachments,maxColorAttachmentslimits, or -
128.
It may not be possible to reach this limit in every stage.
-
- 3
-
See
maxViewportDimensionsfor the required relationship to other limits. - 4
-
See
viewportBoundsRangefor the required relationship to other limits. - 5
-
The values
minInterpolationOffsetandmaxInterpolationOffsetdescribe the closed interval of supported interpolation offsets: [minInterpolationOffset,maxInterpolationOffset]. The ULP is determined bysubPixelInterpolationOffsetBits. IfsubPixelInterpolationOffsetBitsis 4, this provides increments of (1/24) = 0.0625, and thus the range of supported interpolation offsets would be [-0.5, 0.4375]. - 6
-
The point size ULP is determined by
pointSizeGranularity. If thepointSizeGranularityis 0.125, the range of supported point sizes must be at least [1.0, 63.875]. - 7
-
The line width ULP is determined by
lineWidthGranularity. If thelineWidthGranularityis 0.0625, the range of supported line widths must be at least [1.0, 7.9375]. - 8
-
The minimum
maxDescriptorSet*limit is n times the corresponding specification minimummaxPerStageDescriptor*limit, where n is the number of shader stages supported by the VkPhysicalDevice. If all shader stages are supported, n = 6 (vertex, tessellation control, tessellation evaluation, geometry, fragment, compute). - 9
-
The
UpdateAfterBinddescriptor limits must each be greater than or equal to the correspondingnon-UpdateAfterBind limit. - 10
-
If the
VK_KHR_portability_subsetextension is enabled, the required minimum value ofmaxVertexInputBindingsis8.
42.2. Additional Multisampling Capabilities
To query additional multisampling capabilities which may be supported for a specific sample count, beyond the minimum capabilities described for Limits above, call:
// Provided by VK_EXT_sample_locations
void vkGetPhysicalDeviceMultisamplePropertiesEXT(
VkPhysicalDevice physicalDevice,
VkSampleCountFlagBits samples,
VkMultisamplePropertiesEXT* pMultisampleProperties);
-
physicalDeviceis the physical device from which to query the additional multisampling capabilities. -
samplesis a VkSampleCountFlagBits value specifying the sample count to query capabilities for. -
pMultisamplePropertiesis a pointer to a VkMultisamplePropertiesEXT structure in which information about additional multisampling capabilities specific to the sample count is returned.
The VkMultisamplePropertiesEXT structure is defined as
// Provided by VK_EXT_sample_locations
typedef struct VkMultisamplePropertiesEXT {
VkStructureType sType;
void* pNext;
VkExtent2D maxSampleLocationGridSize;
} VkMultisamplePropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxSampleLocationGridSizeis the maximum size of the pixel grid in which sample locations can vary.
If the sample count for which additional multisampling capabilities are
requested using vkGetPhysicalDeviceMultisamplePropertiesEXT is set
in VkPhysicalDeviceSampleLocationsPropertiesEXT::
sampleLocationSampleCounts the
width and height members of
VkMultisamplePropertiesEXT::maxSampleLocationGridSize must be
greater than or equal to the corresponding members of
VkPhysicalDeviceSampleLocationsPropertiesEXT::
maxSampleLocationGridSize,
respectively, otherwise both members must be 0.
42.3. Profile Limits
42.3.1. Roadmap 2022
Implementations that claim support for the Roadmap 2022 profile must satisfy the following additional limit requirements:
| Limit | Supported Limit | Limit Type1 |
|---|---|---|
|
8192 |
min |
|
8192 |
min |
|
8192 |
min |
|
2048 |
min |
|
65536 |
min |
|
4096 |
max |
|
64 |
min |
|
15 |
min |
|
30 |
min |
|
200 |
min |
|
16 |
min |
|
200 |
min |
|
576 |
min |
|
90 |
min |
|
96 |
min |
|
1800 |
min |
|
144 |
min |
|
16 |
min |
|
256 |
min |
|
(256,256,64) |
min |
|
8 |
min |
|
6 |
min |
|
14 |
min |
|
0.125 |
max |
|
0.5 |
max |
|
|
Boolean |
|
7 |
min |
|
4 |
min |
|
|
bitfield |
|
|
bitfield |
|
|
Boolean |
|
|
Boolean |
|
4 |
min |
|
7 |
min |
43. Formats
Supported buffer and image formats may vary across implementations. A minimum set of format features are guaranteed, but others must be explicitly queried before use to ensure they are supported by the implementation.
The features for the set of formats (VkFormat) supported by the implementation are queried individually using the vkGetPhysicalDeviceFormatProperties command.
43.1. Format Definition
The following image formats can be passed to, and may be returned from Vulkan commands. The memory required to store each format is discussed with that format, and also summarized in the Representation and Texel Block Size section and the Compatible formats table.
// Provided by VK_VERSION_1_0
typedef enum VkFormat {
VK_FORMAT_UNDEFINED = 0,
VK_FORMAT_R4G4_UNORM_PACK8 = 1,
VK_FORMAT_R4G4B4A4_UNORM_PACK16 = 2,
VK_FORMAT_B4G4R4A4_UNORM_PACK16 = 3,
VK_FORMAT_R5G6B5_UNORM_PACK16 = 4,
VK_FORMAT_B5G6R5_UNORM_PACK16 = 5,
VK_FORMAT_R5G5B5A1_UNORM_PACK16 = 6,
VK_FORMAT_B5G5R5A1_UNORM_PACK16 = 7,
VK_FORMAT_A1R5G5B5_UNORM_PACK16 = 8,
VK_FORMAT_R8_UNORM = 9,
VK_FORMAT_R8_SNORM = 10,
VK_FORMAT_R8_USCALED = 11,
VK_FORMAT_R8_SSCALED = 12,
VK_FORMAT_R8_UINT = 13,
VK_FORMAT_R8_SINT = 14,
VK_FORMAT_R8_SRGB = 15,
VK_FORMAT_R8G8_UNORM = 16,
VK_FORMAT_R8G8_SNORM = 17,
VK_FORMAT_R8G8_USCALED = 18,
VK_FORMAT_R8G8_SSCALED = 19,
VK_FORMAT_R8G8_UINT = 20,
VK_FORMAT_R8G8_SINT = 21,
VK_FORMAT_R8G8_SRGB = 22,
VK_FORMAT_R8G8B8_UNORM = 23,
VK_FORMAT_R8G8B8_SNORM = 24,
VK_FORMAT_R8G8B8_USCALED = 25,
VK_FORMAT_R8G8B8_SSCALED = 26,
VK_FORMAT_R8G8B8_UINT = 27,
VK_FORMAT_R8G8B8_SINT = 28,
VK_FORMAT_R8G8B8_SRGB = 29,
VK_FORMAT_B8G8R8_UNORM = 30,
VK_FORMAT_B8G8R8_SNORM = 31,
VK_FORMAT_B8G8R8_USCALED = 32,
VK_FORMAT_B8G8R8_SSCALED = 33,
VK_FORMAT_B8G8R8_UINT = 34,
VK_FORMAT_B8G8R8_SINT = 35,
VK_FORMAT_B8G8R8_SRGB = 36,
VK_FORMAT_R8G8B8A8_UNORM = 37,
VK_FORMAT_R8G8B8A8_SNORM = 38,
VK_FORMAT_R8G8B8A8_USCALED = 39,
VK_FORMAT_R8G8B8A8_SSCALED = 40,
VK_FORMAT_R8G8B8A8_UINT = 41,
VK_FORMAT_R8G8B8A8_SINT = 42,
VK_FORMAT_R8G8B8A8_SRGB = 43,
VK_FORMAT_B8G8R8A8_UNORM = 44,
VK_FORMAT_B8G8R8A8_SNORM = 45,
VK_FORMAT_B8G8R8A8_USCALED = 46,
VK_FORMAT_B8G8R8A8_SSCALED = 47,
VK_FORMAT_B8G8R8A8_UINT = 48,
VK_FORMAT_B8G8R8A8_SINT = 49,
VK_FORMAT_B8G8R8A8_SRGB = 50,
VK_FORMAT_A8B8G8R8_UNORM_PACK32 = 51,
VK_FORMAT_A8B8G8R8_SNORM_PACK32 = 52,
VK_FORMAT_A8B8G8R8_USCALED_PACK32 = 53,
VK_FORMAT_A8B8G8R8_SSCALED_PACK32 = 54,
VK_FORMAT_A8B8G8R8_UINT_PACK32 = 55,
VK_FORMAT_A8B8G8R8_SINT_PACK32 = 56,
VK_FORMAT_A8B8G8R8_SRGB_PACK32 = 57,
VK_FORMAT_A2R10G10B10_UNORM_PACK32 = 58,
VK_FORMAT_A2R10G10B10_SNORM_PACK32 = 59,
VK_FORMAT_A2R10G10B10_USCALED_PACK32 = 60,
VK_FORMAT_A2R10G10B10_SSCALED_PACK32 = 61,
VK_FORMAT_A2R10G10B10_UINT_PACK32 = 62,
VK_FORMAT_A2R10G10B10_SINT_PACK32 = 63,
VK_FORMAT_A2B10G10R10_UNORM_PACK32 = 64,
VK_FORMAT_A2B10G10R10_SNORM_PACK32 = 65,
VK_FORMAT_A2B10G10R10_USCALED_PACK32 = 66,
VK_FORMAT_A2B10G10R10_SSCALED_PACK32 = 67,
VK_FORMAT_A2B10G10R10_UINT_PACK32 = 68,
VK_FORMAT_A2B10G10R10_SINT_PACK32 = 69,
VK_FORMAT_R16_UNORM = 70,
VK_FORMAT_R16_SNORM = 71,
VK_FORMAT_R16_USCALED = 72,
VK_FORMAT_R16_SSCALED = 73,
VK_FORMAT_R16_UINT = 74,
VK_FORMAT_R16_SINT = 75,
VK_FORMAT_R16_SFLOAT = 76,
VK_FORMAT_R16G16_UNORM = 77,
VK_FORMAT_R16G16_SNORM = 78,
VK_FORMAT_R16G16_USCALED = 79,
VK_FORMAT_R16G16_SSCALED = 80,
VK_FORMAT_R16G16_UINT = 81,
VK_FORMAT_R16G16_SINT = 82,
VK_FORMAT_R16G16_SFLOAT = 83,
VK_FORMAT_R16G16B16_UNORM = 84,
VK_FORMAT_R16G16B16_SNORM = 85,
VK_FORMAT_R16G16B16_USCALED = 86,
VK_FORMAT_R16G16B16_SSCALED = 87,
VK_FORMAT_R16G16B16_UINT = 88,
VK_FORMAT_R16G16B16_SINT = 89,
VK_FORMAT_R16G16B16_SFLOAT = 90,
VK_FORMAT_R16G16B16A16_UNORM = 91,
VK_FORMAT_R16G16B16A16_SNORM = 92,
VK_FORMAT_R16G16B16A16_USCALED = 93,
VK_FORMAT_R16G16B16A16_SSCALED = 94,
VK_FORMAT_R16G16B16A16_UINT = 95,
VK_FORMAT_R16G16B16A16_SINT = 96,
VK_FORMAT_R16G16B16A16_SFLOAT = 97,
VK_FORMAT_R32_UINT = 98,
VK_FORMAT_R32_SINT = 99,
VK_FORMAT_R32_SFLOAT = 100,
VK_FORMAT_R32G32_UINT = 101,
VK_FORMAT_R32G32_SINT = 102,
VK_FORMAT_R32G32_SFLOAT = 103,
VK_FORMAT_R32G32B32_UINT = 104,
VK_FORMAT_R32G32B32_SINT = 105,
VK_FORMAT_R32G32B32_SFLOAT = 106,
VK_FORMAT_R32G32B32A32_UINT = 107,
VK_FORMAT_R32G32B32A32_SINT = 108,
VK_FORMAT_R32G32B32A32_SFLOAT = 109,
VK_FORMAT_R64_UINT = 110,
VK_FORMAT_R64_SINT = 111,
VK_FORMAT_R64_SFLOAT = 112,
VK_FORMAT_R64G64_UINT = 113,
VK_FORMAT_R64G64_SINT = 114,
VK_FORMAT_R64G64_SFLOAT = 115,
VK_FORMAT_R64G64B64_UINT = 116,
VK_FORMAT_R64G64B64_SINT = 117,
VK_FORMAT_R64G64B64_SFLOAT = 118,
VK_FORMAT_R64G64B64A64_UINT = 119,
VK_FORMAT_R64G64B64A64_SINT = 120,
VK_FORMAT_R64G64B64A64_SFLOAT = 121,
VK_FORMAT_B10G11R11_UFLOAT_PACK32 = 122,
VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 = 123,
VK_FORMAT_D16_UNORM = 124,
VK_FORMAT_X8_D24_UNORM_PACK32 = 125,
VK_FORMAT_D32_SFLOAT = 126,
VK_FORMAT_S8_UINT = 127,
VK_FORMAT_D16_UNORM_S8_UINT = 128,
VK_FORMAT_D24_UNORM_S8_UINT = 129,
VK_FORMAT_D32_SFLOAT_S8_UINT = 130,
VK_FORMAT_BC1_RGB_UNORM_BLOCK = 131,
VK_FORMAT_BC1_RGB_SRGB_BLOCK = 132,
VK_FORMAT_BC1_RGBA_UNORM_BLOCK = 133,
VK_FORMAT_BC1_RGBA_SRGB_BLOCK = 134,
VK_FORMAT_BC2_UNORM_BLOCK = 135,
VK_FORMAT_BC2_SRGB_BLOCK = 136,
VK_FORMAT_BC3_UNORM_BLOCK = 137,
VK_FORMAT_BC3_SRGB_BLOCK = 138,
VK_FORMAT_BC4_UNORM_BLOCK = 139,
VK_FORMAT_BC4_SNORM_BLOCK = 140,
VK_FORMAT_BC5_UNORM_BLOCK = 141,
VK_FORMAT_BC5_SNORM_BLOCK = 142,
VK_FORMAT_BC6H_UFLOAT_BLOCK = 143,
VK_FORMAT_BC6H_SFLOAT_BLOCK = 144,
VK_FORMAT_BC7_UNORM_BLOCK = 145,
VK_FORMAT_BC7_SRGB_BLOCK = 146,
VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK = 147,
VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK = 148,
VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK = 149,
VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK = 150,
VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK = 151,
VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK = 152,
VK_FORMAT_EAC_R11_UNORM_BLOCK = 153,
VK_FORMAT_EAC_R11_SNORM_BLOCK = 154,
VK_FORMAT_EAC_R11G11_UNORM_BLOCK = 155,
VK_FORMAT_EAC_R11G11_SNORM_BLOCK = 156,
VK_FORMAT_ASTC_4x4_UNORM_BLOCK = 157,
VK_FORMAT_ASTC_4x4_SRGB_BLOCK = 158,
VK_FORMAT_ASTC_5x4_UNORM_BLOCK = 159,
VK_FORMAT_ASTC_5x4_SRGB_BLOCK = 160,
VK_FORMAT_ASTC_5x5_UNORM_BLOCK = 161,
VK_FORMAT_ASTC_5x5_SRGB_BLOCK = 162,
VK_FORMAT_ASTC_6x5_UNORM_BLOCK = 163,
VK_FORMAT_ASTC_6x5_SRGB_BLOCK = 164,
VK_FORMAT_ASTC_6x6_UNORM_BLOCK = 165,
VK_FORMAT_ASTC_6x6_SRGB_BLOCK = 166,
VK_FORMAT_ASTC_8x5_UNORM_BLOCK = 167,
VK_FORMAT_ASTC_8x5_SRGB_BLOCK = 168,
VK_FORMAT_ASTC_8x6_UNORM_BLOCK = 169,
VK_FORMAT_ASTC_8x6_SRGB_BLOCK = 170,
VK_FORMAT_ASTC_8x8_UNORM_BLOCK = 171,
VK_FORMAT_ASTC_8x8_SRGB_BLOCK = 172,
VK_FORMAT_ASTC_10x5_UNORM_BLOCK = 173,
VK_FORMAT_ASTC_10x5_SRGB_BLOCK = 174,
VK_FORMAT_ASTC_10x6_UNORM_BLOCK = 175,
VK_FORMAT_ASTC_10x6_SRGB_BLOCK = 176,
VK_FORMAT_ASTC_10x8_UNORM_BLOCK = 177,
VK_FORMAT_ASTC_10x8_SRGB_BLOCK = 178,
VK_FORMAT_ASTC_10x10_UNORM_BLOCK = 179,
VK_FORMAT_ASTC_10x10_SRGB_BLOCK = 180,
VK_FORMAT_ASTC_12x10_UNORM_BLOCK = 181,
VK_FORMAT_ASTC_12x10_SRGB_BLOCK = 182,
VK_FORMAT_ASTC_12x12_UNORM_BLOCK = 183,
VK_FORMAT_ASTC_12x12_SRGB_BLOCK = 184,
// Provided by VK_VERSION_1_1
VK_FORMAT_G8B8G8R8_422_UNORM = 1000156000,
// Provided by VK_VERSION_1_1
VK_FORMAT_B8G8R8G8_422_UNORM = 1000156001,
// Provided by VK_VERSION_1_1
VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM = 1000156002,
// Provided by VK_VERSION_1_1
VK_FORMAT_G8_B8R8_2PLANE_420_UNORM = 1000156003,
// Provided by VK_VERSION_1_1
VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM = 1000156004,
// Provided by VK_VERSION_1_1
VK_FORMAT_G8_B8R8_2PLANE_422_UNORM = 1000156005,
// Provided by VK_VERSION_1_1
VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM = 1000156006,
// Provided by VK_VERSION_1_1
VK_FORMAT_R10X6_UNORM_PACK16 = 1000156007,
// Provided by VK_VERSION_1_1
VK_FORMAT_R10X6G10X6_UNORM_2PACK16 = 1000156008,
// Provided by VK_VERSION_1_1
VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 = 1000156009,
// Provided by VK_VERSION_1_1
VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16 = 1000156010,
// Provided by VK_VERSION_1_1
VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16 = 1000156011,
// Provided by VK_VERSION_1_1
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16 = 1000156012,
// Provided by VK_VERSION_1_1
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16 = 1000156013,
// Provided by VK_VERSION_1_1
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16 = 1000156014,
// Provided by VK_VERSION_1_1
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16 = 1000156015,
// Provided by VK_VERSION_1_1
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16 = 1000156016,
// Provided by VK_VERSION_1_1
VK_FORMAT_R12X4_UNORM_PACK16 = 1000156017,
// Provided by VK_VERSION_1_1
VK_FORMAT_R12X4G12X4_UNORM_2PACK16 = 1000156018,
// Provided by VK_VERSION_1_1
VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16 = 1000156019,
// Provided by VK_VERSION_1_1
VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16 = 1000156020,
// Provided by VK_VERSION_1_1
VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16 = 1000156021,
// Provided by VK_VERSION_1_1
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16 = 1000156022,
// Provided by VK_VERSION_1_1
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16 = 1000156023,
// Provided by VK_VERSION_1_1
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16 = 1000156024,
// Provided by VK_VERSION_1_1
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16 = 1000156025,
// Provided by VK_VERSION_1_1
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16 = 1000156026,
// Provided by VK_VERSION_1_1
VK_FORMAT_G16B16G16R16_422_UNORM = 1000156027,
// Provided by VK_VERSION_1_1
VK_FORMAT_B16G16R16G16_422_UNORM = 1000156028,
// Provided by VK_VERSION_1_1
VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM = 1000156029,
// Provided by VK_VERSION_1_1
VK_FORMAT_G16_B16R16_2PLANE_420_UNORM = 1000156030,
// Provided by VK_VERSION_1_1
VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM = 1000156031,
// Provided by VK_VERSION_1_1
VK_FORMAT_G16_B16R16_2PLANE_422_UNORM = 1000156032,
// Provided by VK_VERSION_1_1
VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM = 1000156033,
// Provided by VK_VERSION_1_3
VK_FORMAT_G8_B8R8_2PLANE_444_UNORM = 1000330000,
// Provided by VK_VERSION_1_3
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_444_UNORM_3PACK16 = 1000330001,
// Provided by VK_VERSION_1_3
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_444_UNORM_3PACK16 = 1000330002,
// Provided by VK_VERSION_1_3
VK_FORMAT_G16_B16R16_2PLANE_444_UNORM = 1000330003,
// Provided by VK_VERSION_1_3
VK_FORMAT_A4R4G4B4_UNORM_PACK16 = 1000340000,
// Provided by VK_VERSION_1_3
VK_FORMAT_A4B4G4R4_UNORM_PACK16 = 1000340001,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK = 1000066000,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK = 1000066001,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK = 1000066002,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK = 1000066003,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK = 1000066004,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK = 1000066005,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK = 1000066006,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK = 1000066007,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK = 1000066008,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK = 1000066009,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK = 1000066010,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK = 1000066011,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK = 1000066012,
// Provided by VK_VERSION_1_3
VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK = 1000066013,
// Provided by VK_IMG_format_pvrtc
VK_FORMAT_PVRTC1_2BPP_UNORM_BLOCK_IMG = 1000054000,
// Provided by VK_IMG_format_pvrtc
VK_FORMAT_PVRTC1_4BPP_UNORM_BLOCK_IMG = 1000054001,
// Provided by VK_IMG_format_pvrtc
VK_FORMAT_PVRTC2_2BPP_UNORM_BLOCK_IMG = 1000054002,
// Provided by VK_IMG_format_pvrtc
VK_FORMAT_PVRTC2_4BPP_UNORM_BLOCK_IMG = 1000054003,
// Provided by VK_IMG_format_pvrtc
VK_FORMAT_PVRTC1_2BPP_SRGB_BLOCK_IMG = 1000054004,
// Provided by VK_IMG_format_pvrtc
VK_FORMAT_PVRTC1_4BPP_SRGB_BLOCK_IMG = 1000054005,
// Provided by VK_IMG_format_pvrtc
VK_FORMAT_PVRTC2_2BPP_SRGB_BLOCK_IMG = 1000054006,
// Provided by VK_IMG_format_pvrtc
VK_FORMAT_PVRTC2_4BPP_SRGB_BLOCK_IMG = 1000054007,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK,
// Provided by VK_EXT_texture_compression_astc_hdr
VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK_EXT = VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G8B8G8R8_422_UNORM_KHR = VK_FORMAT_G8B8G8R8_422_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_B8G8R8G8_422_UNORM_KHR = VK_FORMAT_B8G8R8G8_422_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM_KHR = VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G8_B8R8_2PLANE_420_UNORM_KHR = VK_FORMAT_G8_B8R8_2PLANE_420_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM_KHR = VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G8_B8R8_2PLANE_422_UNORM_KHR = VK_FORMAT_G8_B8R8_2PLANE_422_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM_KHR = VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_R10X6_UNORM_PACK16_KHR = VK_FORMAT_R10X6_UNORM_PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_R10X6G10X6_UNORM_2PACK16_KHR = VK_FORMAT_R10X6G10X6_UNORM_2PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16_KHR = VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16_KHR = VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16_KHR = VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16_KHR = VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16_KHR = VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16_KHR = VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16_KHR = VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16_KHR = VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_R12X4_UNORM_PACK16_KHR = VK_FORMAT_R12X4_UNORM_PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_R12X4G12X4_UNORM_2PACK16_KHR = VK_FORMAT_R12X4G12X4_UNORM_2PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16_KHR = VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16_KHR = VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16_KHR = VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16_KHR = VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16_KHR = VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16_KHR = VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16_KHR = VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16_KHR = VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G16B16G16R16_422_UNORM_KHR = VK_FORMAT_G16B16G16R16_422_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_B16G16R16G16_422_UNORM_KHR = VK_FORMAT_B16G16R16G16_422_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM_KHR = VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G16_B16R16_2PLANE_420_UNORM_KHR = VK_FORMAT_G16_B16R16_2PLANE_420_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM_KHR = VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G16_B16R16_2PLANE_422_UNORM_KHR = VK_FORMAT_G16_B16R16_2PLANE_422_UNORM,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM_KHR = VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM,
// Provided by VK_EXT_ycbcr_2plane_444_formats
VK_FORMAT_G8_B8R8_2PLANE_444_UNORM_EXT = VK_FORMAT_G8_B8R8_2PLANE_444_UNORM,
// Provided by VK_EXT_ycbcr_2plane_444_formats
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_444_UNORM_3PACK16_EXT = VK_FORMAT_G10X6_B10X6R10X6_2PLANE_444_UNORM_3PACK16,
// Provided by VK_EXT_ycbcr_2plane_444_formats
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_444_UNORM_3PACK16_EXT = VK_FORMAT_G12X4_B12X4R12X4_2PLANE_444_UNORM_3PACK16,
// Provided by VK_EXT_ycbcr_2plane_444_formats
VK_FORMAT_G16_B16R16_2PLANE_444_UNORM_EXT = VK_FORMAT_G16_B16R16_2PLANE_444_UNORM,
// Provided by VK_EXT_4444_formats
VK_FORMAT_A4R4G4B4_UNORM_PACK16_EXT = VK_FORMAT_A4R4G4B4_UNORM_PACK16,
// Provided by VK_EXT_4444_formats
VK_FORMAT_A4B4G4R4_UNORM_PACK16_EXT = VK_FORMAT_A4B4G4R4_UNORM_PACK16,
} VkFormat;
-
VK_FORMAT_UNDEFINEDspecifies that the format is not specified. -
VK_FORMAT_R4G4_UNORM_PACK8specifies a two-component, 8-bit packed unsigned normalized format that has a 4-bit R component in bits 4..7, and a 4-bit G component in bits 0..3. -
VK_FORMAT_R4G4B4A4_UNORM_PACK16specifies a four-component, 16-bit packed unsigned normalized format that has a 4-bit R component in bits 12..15, a 4-bit G component in bits 8..11, a 4-bit B component in bits 4..7, and a 4-bit A component in bits 0..3. -
VK_FORMAT_B4G4R4A4_UNORM_PACK16specifies a four-component, 16-bit packed unsigned normalized format that has a 4-bit B component in bits 12..15, a 4-bit G component in bits 8..11, a 4-bit R component in bits 4..7, and a 4-bit A component in bits 0..3. -
VK_FORMAT_A4R4G4B4_UNORM_PACK16specifies a four-component, 16-bit packed unsigned normalized format that has a 4-bit A component in bits 12..15, a 4-bit R component in bits 8..11, a 4-bit G component in bits 4..7, and a 4-bit B component in bits 0..3. -
VK_FORMAT_A4B4G4R4_UNORM_PACK16specifies a four-component, 16-bit packed unsigned normalized format that has a 4-bit A component in bits 12..15, a 4-bit B component in bits 8..11, a 4-bit G component in bits 4..7, and a 4-bit R component in bits 0..3. -
VK_FORMAT_R5G6B5_UNORM_PACK16specifies a three-component, 16-bit packed unsigned normalized format that has a 5-bit R component in bits 11..15, a 6-bit G component in bits 5..10, and a 5-bit B component in bits 0..4. -
VK_FORMAT_B5G6R5_UNORM_PACK16specifies a three-component, 16-bit packed unsigned normalized format that has a 5-bit B component in bits 11..15, a 6-bit G component in bits 5..10, and a 5-bit R component in bits 0..4. -
VK_FORMAT_R5G5B5A1_UNORM_PACK16specifies a four-component, 16-bit packed unsigned normalized format that has a 5-bit R component in bits 11..15, a 5-bit G component in bits 6..10, a 5-bit B component in bits 1..5, and a 1-bit A component in bit 0. -
VK_FORMAT_B5G5R5A1_UNORM_PACK16specifies a four-component, 16-bit packed unsigned normalized format that has a 5-bit B component in bits 11..15, a 5-bit G component in bits 6..10, a 5-bit R component in bits 1..5, and a 1-bit A component in bit 0. -
VK_FORMAT_A1R5G5B5_UNORM_PACK16specifies a four-component, 16-bit packed unsigned normalized format that has a 1-bit A component in bit 15, a 5-bit R component in bits 10..14, a 5-bit G component in bits 5..9, and a 5-bit B component in bits 0..4. -
VK_FORMAT_R8_UNORMspecifies a one-component, 8-bit unsigned normalized format that has a single 8-bit R component. -
VK_FORMAT_R8_SNORMspecifies a one-component, 8-bit signed normalized format that has a single 8-bit R component. -
VK_FORMAT_R8_USCALEDspecifies a one-component, 8-bit unsigned scaled integer format that has a single 8-bit R component. -
VK_FORMAT_R8_SSCALEDspecifies a one-component, 8-bit signed scaled integer format that has a single 8-bit R component. -
VK_FORMAT_R8_UINTspecifies a one-component, 8-bit unsigned integer format that has a single 8-bit R component. -
VK_FORMAT_R8_SINTspecifies a one-component, 8-bit signed integer format that has a single 8-bit R component. -
VK_FORMAT_R8_SRGBspecifies a one-component, 8-bit unsigned normalized format that has a single 8-bit R component stored with sRGB nonlinear encoding. -
VK_FORMAT_R8G8_UNORMspecifies a two-component, 16-bit unsigned normalized format that has an 8-bit R component in byte 0, and an 8-bit G component in byte 1. -
VK_FORMAT_R8G8_SNORMspecifies a two-component, 16-bit signed normalized format that has an 8-bit R component in byte 0, and an 8-bit G component in byte 1. -
VK_FORMAT_R8G8_USCALEDspecifies a two-component, 16-bit unsigned scaled integer format that has an 8-bit R component in byte 0, and an 8-bit G component in byte 1. -
VK_FORMAT_R8G8_SSCALEDspecifies a two-component, 16-bit signed scaled integer format that has an 8-bit R component in byte 0, and an 8-bit G component in byte 1. -
VK_FORMAT_R8G8_UINTspecifies a two-component, 16-bit unsigned integer format that has an 8-bit R component in byte 0, and an 8-bit G component in byte 1. -
VK_FORMAT_R8G8_SINTspecifies a two-component, 16-bit signed integer format that has an 8-bit R component in byte 0, and an 8-bit G component in byte 1. -
VK_FORMAT_R8G8_SRGBspecifies a two-component, 16-bit unsigned normalized format that has an 8-bit R component stored with sRGB nonlinear encoding in byte 0, and an 8-bit G component stored with sRGB nonlinear encoding in byte 1. -
VK_FORMAT_R8G8B8_UNORMspecifies a three-component, 24-bit unsigned normalized format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, and an 8-bit B component in byte 2. -
VK_FORMAT_R8G8B8_SNORMspecifies a three-component, 24-bit signed normalized format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, and an 8-bit B component in byte 2. -
VK_FORMAT_R8G8B8_USCALEDspecifies a three-component, 24-bit unsigned scaled format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, and an 8-bit B component in byte 2. -
VK_FORMAT_R8G8B8_SSCALEDspecifies a three-component, 24-bit signed scaled format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, and an 8-bit B component in byte 2. -
VK_FORMAT_R8G8B8_UINTspecifies a three-component, 24-bit unsigned integer format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, and an 8-bit B component in byte 2. -
VK_FORMAT_R8G8B8_SINTspecifies a three-component, 24-bit signed integer format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, and an 8-bit B component in byte 2. -
VK_FORMAT_R8G8B8_SRGBspecifies a three-component, 24-bit unsigned normalized format that has an 8-bit R component stored with sRGB nonlinear encoding in byte 0, an 8-bit G component stored with sRGB nonlinear encoding in byte 1, and an 8-bit B component stored with sRGB nonlinear encoding in byte 2. -
VK_FORMAT_B8G8R8_UNORMspecifies a three-component, 24-bit unsigned normalized format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, and an 8-bit R component in byte 2. -
VK_FORMAT_B8G8R8_SNORMspecifies a three-component, 24-bit signed normalized format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, and an 8-bit R component in byte 2. -
VK_FORMAT_B8G8R8_USCALEDspecifies a three-component, 24-bit unsigned scaled format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, and an 8-bit R component in byte 2. -
VK_FORMAT_B8G8R8_SSCALEDspecifies a three-component, 24-bit signed scaled format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, and an 8-bit R component in byte 2. -
VK_FORMAT_B8G8R8_UINTspecifies a three-component, 24-bit unsigned integer format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, and an 8-bit R component in byte 2. -
VK_FORMAT_B8G8R8_SINTspecifies a three-component, 24-bit signed integer format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, and an 8-bit R component in byte 2. -
VK_FORMAT_B8G8R8_SRGBspecifies a three-component, 24-bit unsigned normalized format that has an 8-bit B component stored with sRGB nonlinear encoding in byte 0, an 8-bit G component stored with sRGB nonlinear encoding in byte 1, and an 8-bit R component stored with sRGB nonlinear encoding in byte 2. -
VK_FORMAT_R8G8B8A8_UNORMspecifies a four-component, 32-bit unsigned normalized format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, an 8-bit B component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_R8G8B8A8_SNORMspecifies a four-component, 32-bit signed normalized format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, an 8-bit B component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_R8G8B8A8_USCALEDspecifies a four-component, 32-bit unsigned scaled format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, an 8-bit B component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_R8G8B8A8_SSCALEDspecifies a four-component, 32-bit signed scaled format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, an 8-bit B component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_R8G8B8A8_UINTspecifies a four-component, 32-bit unsigned integer format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, an 8-bit B component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_R8G8B8A8_SINTspecifies a four-component, 32-bit signed integer format that has an 8-bit R component in byte 0, an 8-bit G component in byte 1, an 8-bit B component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_R8G8B8A8_SRGBspecifies a four-component, 32-bit unsigned normalized format that has an 8-bit R component stored with sRGB nonlinear encoding in byte 0, an 8-bit G component stored with sRGB nonlinear encoding in byte 1, an 8-bit B component stored with sRGB nonlinear encoding in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_B8G8R8A8_UNORMspecifies a four-component, 32-bit unsigned normalized format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, an 8-bit R component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_B8G8R8A8_SNORMspecifies a four-component, 32-bit signed normalized format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, an 8-bit R component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_B8G8R8A8_USCALEDspecifies a four-component, 32-bit unsigned scaled format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, an 8-bit R component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_B8G8R8A8_SSCALEDspecifies a four-component, 32-bit signed scaled format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, an 8-bit R component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_B8G8R8A8_UINTspecifies a four-component, 32-bit unsigned integer format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, an 8-bit R component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_B8G8R8A8_SINTspecifies a four-component, 32-bit signed integer format that has an 8-bit B component in byte 0, an 8-bit G component in byte 1, an 8-bit R component in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_B8G8R8A8_SRGBspecifies a four-component, 32-bit unsigned normalized format that has an 8-bit B component stored with sRGB nonlinear encoding in byte 0, an 8-bit G component stored with sRGB nonlinear encoding in byte 1, an 8-bit R component stored with sRGB nonlinear encoding in byte 2, and an 8-bit A component in byte 3. -
VK_FORMAT_A8B8G8R8_UNORM_PACK32specifies a four-component, 32-bit packed unsigned normalized format that has an 8-bit A component in bits 24..31, an 8-bit B component in bits 16..23, an 8-bit G component in bits 8..15, and an 8-bit R component in bits 0..7. -
VK_FORMAT_A8B8G8R8_SNORM_PACK32specifies a four-component, 32-bit packed signed normalized format that has an 8-bit A component in bits 24..31, an 8-bit B component in bits 16..23, an 8-bit G component in bits 8..15, and an 8-bit R component in bits 0..7. -
VK_FORMAT_A8B8G8R8_USCALED_PACK32specifies a four-component, 32-bit packed unsigned scaled integer format that has an 8-bit A component in bits 24..31, an 8-bit B component in bits 16..23, an 8-bit G component in bits 8..15, and an 8-bit R component in bits 0..7. -
VK_FORMAT_A8B8G8R8_SSCALED_PACK32specifies a four-component, 32-bit packed signed scaled integer format that has an 8-bit A component in bits 24..31, an 8-bit B component in bits 16..23, an 8-bit G component in bits 8..15, and an 8-bit R component in bits 0..7. -
VK_FORMAT_A8B8G8R8_UINT_PACK32specifies a four-component, 32-bit packed unsigned integer format that has an 8-bit A component in bits 24..31, an 8-bit B component in bits 16..23, an 8-bit G component in bits 8..15, and an 8-bit R component in bits 0..7. -
VK_FORMAT_A8B8G8R8_SINT_PACK32specifies a four-component, 32-bit packed signed integer format that has an 8-bit A component in bits 24..31, an 8-bit B component in bits 16..23, an 8-bit G component in bits 8..15, and an 8-bit R component in bits 0..7. -
VK_FORMAT_A8B8G8R8_SRGB_PACK32specifies a four-component, 32-bit packed unsigned normalized format that has an 8-bit A component in bits 24..31, an 8-bit B component stored with sRGB nonlinear encoding in bits 16..23, an 8-bit G component stored with sRGB nonlinear encoding in bits 8..15, and an 8-bit R component stored with sRGB nonlinear encoding in bits 0..7. -
VK_FORMAT_A2R10G10B10_UNORM_PACK32specifies a four-component, 32-bit packed unsigned normalized format that has a 2-bit A component in bits 30..31, a 10-bit R component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit B component in bits 0..9. -
VK_FORMAT_A2R10G10B10_SNORM_PACK32specifies a four-component, 32-bit packed signed normalized format that has a 2-bit A component in bits 30..31, a 10-bit R component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit B component in bits 0..9. -
VK_FORMAT_A2R10G10B10_USCALED_PACK32specifies a four-component, 32-bit packed unsigned scaled integer format that has a 2-bit A component in bits 30..31, a 10-bit R component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit B component in bits 0..9. -
VK_FORMAT_A2R10G10B10_SSCALED_PACK32specifies a four-component, 32-bit packed signed scaled integer format that has a 2-bit A component in bits 30..31, a 10-bit R component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit B component in bits 0..9. -
VK_FORMAT_A2R10G10B10_UINT_PACK32specifies a four-component, 32-bit packed unsigned integer format that has a 2-bit A component in bits 30..31, a 10-bit R component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit B component in bits 0..9. -
VK_FORMAT_A2R10G10B10_SINT_PACK32specifies a four-component, 32-bit packed signed integer format that has a 2-bit A component in bits 30..31, a 10-bit R component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit B component in bits 0..9. -
VK_FORMAT_A2B10G10R10_UNORM_PACK32specifies a four-component, 32-bit packed unsigned normalized format that has a 2-bit A component in bits 30..31, a 10-bit B component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit R component in bits 0..9. -
VK_FORMAT_A2B10G10R10_SNORM_PACK32specifies a four-component, 32-bit packed signed normalized format that has a 2-bit A component in bits 30..31, a 10-bit B component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit R component in bits 0..9. -
VK_FORMAT_A2B10G10R10_USCALED_PACK32specifies a four-component, 32-bit packed unsigned scaled integer format that has a 2-bit A component in bits 30..31, a 10-bit B component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit R component in bits 0..9. -
VK_FORMAT_A2B10G10R10_SSCALED_PACK32specifies a four-component, 32-bit packed signed scaled integer format that has a 2-bit A component in bits 30..31, a 10-bit B component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit R component in bits 0..9. -
VK_FORMAT_A2B10G10R10_UINT_PACK32specifies a four-component, 32-bit packed unsigned integer format that has a 2-bit A component in bits 30..31, a 10-bit B component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit R component in bits 0..9. -
VK_FORMAT_A2B10G10R10_SINT_PACK32specifies a four-component, 32-bit packed signed integer format that has a 2-bit A component in bits 30..31, a 10-bit B component in bits 20..29, a 10-bit G component in bits 10..19, and a 10-bit R component in bits 0..9. -
VK_FORMAT_R16_UNORMspecifies a one-component, 16-bit unsigned normalized format that has a single 16-bit R component. -
VK_FORMAT_R16_SNORMspecifies a one-component, 16-bit signed normalized format that has a single 16-bit R component. -
VK_FORMAT_R16_USCALEDspecifies a one-component, 16-bit unsigned scaled integer format that has a single 16-bit R component. -
VK_FORMAT_R16_SSCALEDspecifies a one-component, 16-bit signed scaled integer format that has a single 16-bit R component. -
VK_FORMAT_R16_UINTspecifies a one-component, 16-bit unsigned integer format that has a single 16-bit R component. -
VK_FORMAT_R16_SINTspecifies a one-component, 16-bit signed integer format that has a single 16-bit R component. -
VK_FORMAT_R16_SFLOATspecifies a one-component, 16-bit signed floating-point format that has a single 16-bit R component. -
VK_FORMAT_R16G16_UNORMspecifies a two-component, 32-bit unsigned normalized format that has a 16-bit R component in bytes 0..1, and a 16-bit G component in bytes 2..3. -
VK_FORMAT_R16G16_SNORMspecifies a two-component, 32-bit signed normalized format that has a 16-bit R component in bytes 0..1, and a 16-bit G component in bytes 2..3. -
VK_FORMAT_R16G16_USCALEDspecifies a two-component, 32-bit unsigned scaled integer format that has a 16-bit R component in bytes 0..1, and a 16-bit G component in bytes 2..3. -
VK_FORMAT_R16G16_SSCALEDspecifies a two-component, 32-bit signed scaled integer format that has a 16-bit R component in bytes 0..1, and a 16-bit G component in bytes 2..3. -
VK_FORMAT_R16G16_UINTspecifies a two-component, 32-bit unsigned integer format that has a 16-bit R component in bytes 0..1, and a 16-bit G component in bytes 2..3. -
VK_FORMAT_R16G16_SINTspecifies a two-component, 32-bit signed integer format that has a 16-bit R component in bytes 0..1, and a 16-bit G component in bytes 2..3. -
VK_FORMAT_R16G16_SFLOATspecifies a two-component, 32-bit signed floating-point format that has a 16-bit R component in bytes 0..1, and a 16-bit G component in bytes 2..3. -
VK_FORMAT_R16G16B16_UNORMspecifies a three-component, 48-bit unsigned normalized format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, and a 16-bit B component in bytes 4..5. -
VK_FORMAT_R16G16B16_SNORMspecifies a three-component, 48-bit signed normalized format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, and a 16-bit B component in bytes 4..5. -
VK_FORMAT_R16G16B16_USCALEDspecifies a three-component, 48-bit unsigned scaled integer format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, and a 16-bit B component in bytes 4..5. -
VK_FORMAT_R16G16B16_SSCALEDspecifies a three-component, 48-bit signed scaled integer format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, and a 16-bit B component in bytes 4..5. -
VK_FORMAT_R16G16B16_UINTspecifies a three-component, 48-bit unsigned integer format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, and a 16-bit B component in bytes 4..5. -
VK_FORMAT_R16G16B16_SINTspecifies a three-component, 48-bit signed integer format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, and a 16-bit B component in bytes 4..5. -
VK_FORMAT_R16G16B16_SFLOATspecifies a three-component, 48-bit signed floating-point format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, and a 16-bit B component in bytes 4..5. -
VK_FORMAT_R16G16B16A16_UNORMspecifies a four-component, 64-bit unsigned normalized format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, a 16-bit B component in bytes 4..5, and a 16-bit A component in bytes 6..7. -
VK_FORMAT_R16G16B16A16_SNORMspecifies a four-component, 64-bit signed normalized format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, a 16-bit B component in bytes 4..5, and a 16-bit A component in bytes 6..7. -
VK_FORMAT_R16G16B16A16_USCALEDspecifies a four-component, 64-bit unsigned scaled integer format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, a 16-bit B component in bytes 4..5, and a 16-bit A component in bytes 6..7. -
VK_FORMAT_R16G16B16A16_SSCALEDspecifies a four-component, 64-bit signed scaled integer format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, a 16-bit B component in bytes 4..5, and a 16-bit A component in bytes 6..7. -
VK_FORMAT_R16G16B16A16_UINTspecifies a four-component, 64-bit unsigned integer format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, a 16-bit B component in bytes 4..5, and a 16-bit A component in bytes 6..7. -
VK_FORMAT_R16G16B16A16_SINTspecifies a four-component, 64-bit signed integer format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, a 16-bit B component in bytes 4..5, and a 16-bit A component in bytes 6..7. -
VK_FORMAT_R16G16B16A16_SFLOATspecifies a four-component, 64-bit signed floating-point format that has a 16-bit R component in bytes 0..1, a 16-bit G component in bytes 2..3, a 16-bit B component in bytes 4..5, and a 16-bit A component in bytes 6..7. -
VK_FORMAT_R32_UINTspecifies a one-component, 32-bit unsigned integer format that has a single 32-bit R component. -
VK_FORMAT_R32_SINTspecifies a one-component, 32-bit signed integer format that has a single 32-bit R component. -
VK_FORMAT_R32_SFLOATspecifies a one-component, 32-bit signed floating-point format that has a single 32-bit R component. -
VK_FORMAT_R32G32_UINTspecifies a two-component, 64-bit unsigned integer format that has a 32-bit R component in bytes 0..3, and a 32-bit G component in bytes 4..7. -
VK_FORMAT_R32G32_SINTspecifies a two-component, 64-bit signed integer format that has a 32-bit R component in bytes 0..3, and a 32-bit G component in bytes 4..7. -
VK_FORMAT_R32G32_SFLOATspecifies a two-component, 64-bit signed floating-point format that has a 32-bit R component in bytes 0..3, and a 32-bit G component in bytes 4..7. -
VK_FORMAT_R32G32B32_UINTspecifies a three-component, 96-bit unsigned integer format that has a 32-bit R component in bytes 0..3, a 32-bit G component in bytes 4..7, and a 32-bit B component in bytes 8..11. -
VK_FORMAT_R32G32B32_SINTspecifies a three-component, 96-bit signed integer format that has a 32-bit R component in bytes 0..3, a 32-bit G component in bytes 4..7, and a 32-bit B component in bytes 8..11. -
VK_FORMAT_R32G32B32_SFLOATspecifies a three-component, 96-bit signed floating-point format that has a 32-bit R component in bytes 0..3, a 32-bit G component in bytes 4..7, and a 32-bit B component in bytes 8..11. -
VK_FORMAT_R32G32B32A32_UINTspecifies a four-component, 128-bit unsigned integer format that has a 32-bit R component in bytes 0..3, a 32-bit G component in bytes 4..7, a 32-bit B component in bytes 8..11, and a 32-bit A component in bytes 12..15. -
VK_FORMAT_R32G32B32A32_SINTspecifies a four-component, 128-bit signed integer format that has a 32-bit R component in bytes 0..3, a 32-bit G component in bytes 4..7, a 32-bit B component in bytes 8..11, and a 32-bit A component in bytes 12..15. -
VK_FORMAT_R32G32B32A32_SFLOATspecifies a four-component, 128-bit signed floating-point format that has a 32-bit R component in bytes 0..3, a 32-bit G component in bytes 4..7, a 32-bit B component in bytes 8..11, and a 32-bit A component in bytes 12..15. -
VK_FORMAT_R64_UINTspecifies a one-component, 64-bit unsigned integer format that has a single 64-bit R component. -
VK_FORMAT_R64_SINTspecifies a one-component, 64-bit signed integer format that has a single 64-bit R component. -
VK_FORMAT_R64_SFLOATspecifies a one-component, 64-bit signed floating-point format that has a single 64-bit R component. -
VK_FORMAT_R64G64_UINTspecifies a two-component, 128-bit unsigned integer format that has a 64-bit R component in bytes 0..7, and a 64-bit G component in bytes 8..15. -
VK_FORMAT_R64G64_SINTspecifies a two-component, 128-bit signed integer format that has a 64-bit R component in bytes 0..7, and a 64-bit G component in bytes 8..15. -
VK_FORMAT_R64G64_SFLOATspecifies a two-component, 128-bit signed floating-point format that has a 64-bit R component in bytes 0..7, and a 64-bit G component in bytes 8..15. -
VK_FORMAT_R64G64B64_UINTspecifies a three-component, 192-bit unsigned integer format that has a 64-bit R component in bytes 0..7, a 64-bit G component in bytes 8..15, and a 64-bit B component in bytes 16..23. -
VK_FORMAT_R64G64B64_SINTspecifies a three-component, 192-bit signed integer format that has a 64-bit R component in bytes 0..7, a 64-bit G component in bytes 8..15, and a 64-bit B component in bytes 16..23. -
VK_FORMAT_R64G64B64_SFLOATspecifies a three-component, 192-bit signed floating-point format that has a 64-bit R component in bytes 0..7, a 64-bit G component in bytes 8..15, and a 64-bit B component in bytes 16..23. -
VK_FORMAT_R64G64B64A64_UINTspecifies a four-component, 256-bit unsigned integer format that has a 64-bit R component in bytes 0..7, a 64-bit G component in bytes 8..15, a 64-bit B component in bytes 16..23, and a 64-bit A component in bytes 24..31. -
VK_FORMAT_R64G64B64A64_SINTspecifies a four-component, 256-bit signed integer format that has a 64-bit R component in bytes 0..7, a 64-bit G component in bytes 8..15, a 64-bit B component in bytes 16..23, and a 64-bit A component in bytes 24..31. -
VK_FORMAT_R64G64B64A64_SFLOATspecifies a four-component, 256-bit signed floating-point format that has a 64-bit R component in bytes 0..7, a 64-bit G component in bytes 8..15, a 64-bit B component in bytes 16..23, and a 64-bit A component in bytes 24..31. -
VK_FORMAT_B10G11R11_UFLOAT_PACK32specifies a three-component, 32-bit packed unsigned floating-point format that has a 10-bit B component in bits 22..31, an 11-bit G component in bits 11..21, an 11-bit R component in bits 0..10. See Unsigned 10-Bit Floating-Point Numbers and Unsigned 11-Bit Floating-Point Numbers. -
VK_FORMAT_E5B9G9R9_UFLOAT_PACK32specifies a three-component, 32-bit packed unsigned floating-point format that has a 5-bit shared exponent in bits 27..31, a 9-bit B component mantissa in bits 18..26, a 9-bit G component mantissa in bits 9..17, and a 9-bit R component mantissa in bits 0..8. -
VK_FORMAT_D16_UNORMspecifies a one-component, 16-bit unsigned normalized format that has a single 16-bit depth component. -
VK_FORMAT_X8_D24_UNORM_PACK32specifies a two-component, 32-bit format that has 24 unsigned normalized bits in the depth component and, optionally, 8 bits that are unused. -
VK_FORMAT_D32_SFLOATspecifies a one-component, 32-bit signed floating-point format that has 32 bits in the depth component. -
VK_FORMAT_S8_UINTspecifies a one-component, 8-bit unsigned integer format that has 8 bits in the stencil component. -
VK_FORMAT_D16_UNORM_S8_UINTspecifies a two-component, 24-bit format that has 16 unsigned normalized bits in the depth component and 8 unsigned integer bits in the stencil component. -
VK_FORMAT_D24_UNORM_S8_UINTspecifies a two-component, 32-bit packed format that has 8 unsigned integer bits in the stencil component, and 24 unsigned normalized bits in the depth component. -
VK_FORMAT_D32_SFLOAT_S8_UINTspecifies a two-component format that has 32 signed float bits in the depth component and 8 unsigned integer bits in the stencil component. There are optionally 24 bits that are unused. -
VK_FORMAT_BC1_RGB_UNORM_BLOCKspecifies a three-component, block-compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGB texel data. This format has no alpha and is considered opaque. -
VK_FORMAT_BC1_RGB_SRGB_BLOCKspecifies a three-component, block-compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGB texel data with sRGB nonlinear encoding. This format has no alpha and is considered opaque. -
VK_FORMAT_BC1_RGBA_UNORM_BLOCKspecifies a four-component, block-compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGB texel data, and provides 1 bit of alpha. -
VK_FORMAT_BC1_RGBA_SRGB_BLOCKspecifies a four-component, block-compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGB texel data with sRGB nonlinear encoding, and provides 1 bit of alpha. -
VK_FORMAT_BC2_UNORM_BLOCKspecifies a four-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with the first 64 bits encoding alpha values followed by 64 bits encoding RGB values. -
VK_FORMAT_BC2_SRGB_BLOCKspecifies a four-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with the first 64 bits encoding alpha values followed by 64 bits encoding RGB values with sRGB nonlinear encoding. -
VK_FORMAT_BC3_UNORM_BLOCKspecifies a four-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with the first 64 bits encoding alpha values followed by 64 bits encoding RGB values. -
VK_FORMAT_BC3_SRGB_BLOCKspecifies a four-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with the first 64 bits encoding alpha values followed by 64 bits encoding RGB values with sRGB nonlinear encoding. -
VK_FORMAT_BC4_UNORM_BLOCKspecifies a one-component, block-compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized red texel data. -
VK_FORMAT_BC4_SNORM_BLOCKspecifies a one-component, block-compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of signed normalized red texel data. -
VK_FORMAT_BC5_UNORM_BLOCKspecifies a two-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RG texel data with the first 64 bits encoding red values followed by 64 bits encoding green values. -
VK_FORMAT_BC5_SNORM_BLOCKspecifies a two-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of signed normalized RG texel data with the first 64 bits encoding red values followed by 64 bits encoding green values. -
VK_FORMAT_BC6H_UFLOAT_BLOCKspecifies a three-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned floating-point RGB texel data. -
VK_FORMAT_BC6H_SFLOAT_BLOCKspecifies a three-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of signed floating-point RGB texel data. -
VK_FORMAT_BC7_UNORM_BLOCKspecifies a four-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_BC7_SRGB_BLOCKspecifies a four-component, block-compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCKspecifies a three-component, ETC2 compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGB texel data. This format has no alpha and is considered opaque. -
VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCKspecifies a three-component, ETC2 compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGB texel data with sRGB nonlinear encoding. This format has no alpha and is considered opaque. -
VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCKspecifies a four-component, ETC2 compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGB texel data, and provides 1 bit of alpha. -
VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCKspecifies a four-component, ETC2 compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGB texel data with sRGB nonlinear encoding, and provides 1 bit of alpha. -
VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCKspecifies a four-component, ETC2 compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with the first 64 bits encoding alpha values followed by 64 bits encoding RGB values. -
VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCKspecifies a four-component, ETC2 compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with the first 64 bits encoding alpha values followed by 64 bits encoding RGB values with sRGB nonlinear encoding applied. -
VK_FORMAT_EAC_R11_UNORM_BLOCKspecifies a one-component, ETC2 compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized red texel data. -
VK_FORMAT_EAC_R11_SNORM_BLOCKspecifies a one-component, ETC2 compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of signed normalized red texel data. -
VK_FORMAT_EAC_R11G11_UNORM_BLOCKspecifies a two-component, ETC2 compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RG texel data with the first 64 bits encoding red values followed by 64 bits encoding green values. -
VK_FORMAT_EAC_R11G11_SNORM_BLOCKspecifies a two-component, ETC2 compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of signed normalized RG texel data with the first 64 bits encoding red values followed by 64 bits encoding green values. -
VK_FORMAT_ASTC_4x4_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_4x4_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 4×4 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_5x4_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 5×4 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_5x4_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 5×4 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_5x4_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 5×4 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_5x5_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 5×5 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_5x5_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 5×5 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_5x5_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 5×5 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_6x5_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 6×5 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_6x5_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 6×5 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_6x5_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 6×5 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_6x6_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 6×6 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_6x6_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 6×6 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_6x6_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 6×6 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_8x5_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an 8×5 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_8x5_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an 8×5 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_8x5_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 8×5 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_8x6_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an 8×6 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_8x6_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an 8×6 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_8x6_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 8×6 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_8x8_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an 8×8 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_8x8_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an 8×8 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_8x8_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 8×8 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_10x5_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×5 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_10x5_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×5 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_10x5_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×5 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_10x6_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×6 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_10x6_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×6 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_10x6_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×6 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_10x8_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×8 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_10x8_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×8 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_10x8_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×8 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_10x10_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×10 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_10x10_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×10 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_10x10_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 10×10 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_12x10_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 12×10 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_12x10_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 12×10 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_12x10_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 12×10 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_ASTC_12x12_UNORM_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 12×12 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_ASTC_12x12_SRGB_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 12×12 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_ASTC_12x12_SFLOAT_BLOCKspecifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a 12×12 rectangle of signed floating-point RGBA texel data. -
VK_FORMAT_G8B8G8R8_422_UNORMspecifies a four-component, 32-bit format containing a pair of G components, an R component, and a B component, collectively encoding a 2×1 rectangle of unsigned normalized RGB texel data. One G value is present at each i coordinate, with the B and R values shared across both G values and thus recorded at half the horizontal resolution of the image. This format has an 8-bit G component for the even i coordinate in byte 0, an 8-bit B component in byte 1, an 8-bit G component for the odd i coordinate in byte 2, and an 8-bit R component in byte 3. This format only supports images with a width that is a multiple of two. For the purposes of the constraints on copy extents, this format is treated as a compressed format with a 2×1 compressed texel block. -
VK_FORMAT_B8G8R8G8_422_UNORMspecifies a four-component, 32-bit format containing a pair of G components, an R component, and a B component, collectively encoding a 2×1 rectangle of unsigned normalized RGB texel data. One G value is present at each i coordinate, with the B and R values shared across both G values and thus recorded at half the horizontal resolution of the image. This format has an 8-bit B component in byte 0, an 8-bit G component for the even i coordinate in byte 1, an 8-bit R component in byte 2, and an 8-bit G component for the odd i coordinate in byte 3. This format only supports images with a width that is a multiple of two. For the purposes of the constraints on copy extents, this format is treated as a compressed format with a 2×1 compressed texel block. -
VK_FORMAT_G8_B8_R8_3PLANE_420_UNORMspecifies an unsigned normalized multi-planar format that has an 8-bit G component in plane 0, an 8-bit B component in plane 1, and an 8-bit R component in plane 2. The horizontal and vertical dimensions of the R and B planes are halved relative to the image dimensions, and each R and B component is shared with the G components for which and . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. This format only supports images with a width and height that is a multiple of two. -
VK_FORMAT_G8_B8R8_2PLANE_420_UNORMspecifies an unsigned normalized multi-planar format that has an 8-bit G component in plane 0, and a two-component, 16-bit BR plane 1 consisting of an 8-bit B component in byte 0 and an 8-bit R component in byte 1. The horizontal and vertical dimensions of the BR plane are halved relative to the image dimensions, and each R and B value is shared with the G components for which and . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. This format only supports images with a width and height that is a multiple of two. -
VK_FORMAT_G8_B8_R8_3PLANE_422_UNORMspecifies an unsigned normalized multi-planar format that has an 8-bit G component in plane 0, an 8-bit B component in plane 1, and an 8-bit R component in plane 2. The horizontal dimension of the R and B plane is halved relative to the image dimensions, and each R and B value is shared with the G components for which . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. This format only supports images with a width that is a multiple of two. -
VK_FORMAT_G8_B8R8_2PLANE_422_UNORMspecifies an unsigned normalized multi-planar format that has an 8-bit G component in plane 0, and a two-component, 16-bit BR plane 1 consisting of an 8-bit B component in byte 0 and an 8-bit R component in byte 1. The horizontal dimension of the BR plane is halved relative to the image dimensions, and each R and B value is shared with the G components for which . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. This format only supports images with a width that is a multiple of two. -
VK_FORMAT_G8_B8_R8_3PLANE_444_UNORMspecifies an unsigned normalized multi-planar format that has an 8-bit G component in plane 0, an 8-bit B component in plane 1, and an 8-bit R component in plane 2. Each plane has the same dimensions and each R, G and B component contributes to a single texel. The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. -
VK_FORMAT_R10X6_UNORM_PACK16specifies a one-component, 16-bit unsigned normalized format that has a single 10-bit R component in the top 10 bits of a 16-bit word, with the bottom 6 bits unused. -
VK_FORMAT_R10X6G10X6_UNORM_2PACK16specifies a two-component, 32-bit unsigned normalized format that has a 10-bit R component in the top 10 bits of the word in bytes 0..1, and a 10-bit G component in the top 10 bits of the word in bytes 2..3, with the bottom 6 bits of each word unused. -
VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16specifies a four-component, 64-bit unsigned normalized format that has a 10-bit R component in the top 10 bits of the word in bytes 0..1, a 10-bit G component in the top 10 bits of the word in bytes 2..3, a 10-bit B component in the top 10 bits of the word in bytes 4..5, and a 10-bit A component in the top 10 bits of the word in bytes 6..7, with the bottom 6 bits of each word unused. -
VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16specifies a four-component, 64-bit format containing a pair of G components, an R component, and a B component, collectively encoding a 2×1 rectangle of unsigned normalized RGB texel data. One G value is present at each i coordinate, with the B and R values shared across both G values and thus recorded at half the horizontal resolution of the image. This format has a 10-bit G component for the even i coordinate in the top 10 bits of the word in bytes 0..1, a 10-bit B component in the top 10 bits of the word in bytes 2..3, a 10-bit G component for the odd i coordinate in the top 10 bits of the word in bytes 4..5, and a 10-bit R component in the top 10 bits of the word in bytes 6..7, with the bottom 6 bits of each word unused. This format only supports images with a width that is a multiple of two. For the purposes of the constraints on copy extents, this format is treated as a compressed format with a 2×1 compressed texel block. -
VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16specifies a four-component, 64-bit format containing a pair of G components, an R component, and a B component, collectively encoding a 2×1 rectangle of unsigned normalized RGB texel data. One G value is present at each i coordinate, with the B and R values shared across both G values and thus recorded at half the horizontal resolution of the image. This format has a 10-bit B component in the top 10 bits of the word in bytes 0..1, a 10-bit G component for the even i coordinate in the top 10 bits of the word in bytes 2..3, a 10-bit R component in the top 10 bits of the word in bytes 4..5, and a 10-bit G component for the odd i coordinate in the top 10 bits of the word in bytes 6..7, with the bottom 6 bits of each word unused. This format only supports images with a width that is a multiple of two. For the purposes of the constraints on copy extents, this format is treated as a compressed format with a 2×1 compressed texel block. -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 10-bit G component in the top 10 bits of each 16-bit word of plane 0, a 10-bit B component in the top 10 bits of each 16-bit word of plane 1, and a 10-bit R component in the top 10 bits of each 16-bit word of plane 2, with the bottom 6 bits of each word unused. The horizontal and vertical dimensions of the R and B planes are halved relative to the image dimensions, and each R and B component is shared with the G components for which and . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. This format only supports images with a width and height that is a multiple of two. -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 10-bit G component in the top 10 bits of each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 10-bit B component in the top 10 bits of the word in bytes 0..1, and a 10-bit R component in the top 10 bits of the word in bytes 2..3, with the bottom 6 bits of each word unused. The horizontal and vertical dimensions of the BR plane are halved relative to the image dimensions, and each R and B value is shared with the G components for which and . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. This format only supports images with a width and height that is a multiple of two. -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 10-bit G component in the top 10 bits of each 16-bit word of plane 0, a 10-bit B component in the top 10 bits of each 16-bit word of plane 1, and a 10-bit R component in the top 10 bits of each 16-bit word of plane 2, with the bottom 6 bits of each word unused. The horizontal dimension of the R and B plane is halved relative to the image dimensions, and each R and B value is shared with the G components for which . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. This format only supports images with a width that is a multiple of two. -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 10-bit G component in the top 10 bits of each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 10-bit B component in the top 10 bits of the word in bytes 0..1, and a 10-bit R component in the top 10 bits of the word in bytes 2..3, with the bottom 6 bits of each word unused. The horizontal dimension of the BR plane is halved relative to the image dimensions, and each R and B value is shared with the G components for which . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. This format only supports images with a width that is a multiple of two. -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 10-bit G component in the top 10 bits of each 16-bit word of plane 0, a 10-bit B component in the top 10 bits of each 16-bit word of plane 1, and a 10-bit R component in the top 10 bits of each 16-bit word of plane 2, with the bottom 6 bits of each word unused. Each plane has the same dimensions and each R, G and B component contributes to a single texel. The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. -
VK_FORMAT_R12X4_UNORM_PACK16specifies a one-component, 16-bit unsigned normalized format that has a single 12-bit R component in the top 12 bits of a 16-bit word, with the bottom 4 bits unused. -
VK_FORMAT_R12X4G12X4_UNORM_2PACK16specifies a two-component, 32-bit unsigned normalized format that has a 12-bit R component in the top 12 bits of the word in bytes 0..1, and a 12-bit G component in the top 12 bits of the word in bytes 2..3, with the bottom 4 bits of each word unused. -
VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16specifies a four-component, 64-bit unsigned normalized format that has a 12-bit R component in the top 12 bits of the word in bytes 0..1, a 12-bit G component in the top 12 bits of the word in bytes 2..3, a 12-bit B component in the top 12 bits of the word in bytes 4..5, and a 12-bit A component in the top 12 bits of the word in bytes 6..7, with the bottom 4 bits of each word unused. -
VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16specifies a four-component, 64-bit format containing a pair of G components, an R component, and a B component, collectively encoding a 2×1 rectangle of unsigned normalized RGB texel data. One G value is present at each i coordinate, with the B and R values shared across both G values and thus recorded at half the horizontal resolution of the image. This format has a 12-bit G component for the even i coordinate in the top 12 bits of the word in bytes 0..1, a 12-bit B component in the top 12 bits of the word in bytes 2..3, a 12-bit G component for the odd i coordinate in the top 12 bits of the word in bytes 4..5, and a 12-bit R component in the top 12 bits of the word in bytes 6..7, with the bottom 4 bits of each word unused. This format only supports images with a width that is a multiple of two. For the purposes of the constraints on copy extents, this format is treated as a compressed format with a 2×1 compressed texel block. -
VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16specifies a four-component, 64-bit format containing a pair of G components, an R component, and a B component, collectively encoding a 2×1 rectangle of unsigned normalized RGB texel data. One G value is present at each i coordinate, with the B and R values shared across both G values and thus recorded at half the horizontal resolution of the image. This format has a 12-bit B component in the top 12 bits of the word in bytes 0..1, a 12-bit G component for the even i coordinate in the top 12 bits of the word in bytes 2..3, a 12-bit R component in the top 12 bits of the word in bytes 4..5, and a 12-bit G component for the odd i coordinate in the top 12 bits of the word in bytes 6..7, with the bottom 4 bits of each word unused. This format only supports images with a width that is a multiple of two. For the purposes of the constraints on copy extents, this format is treated as a compressed format with a 2×1 compressed texel block. -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 12-bit G component in the top 12 bits of each 16-bit word of plane 0, a 12-bit B component in the top 12 bits of each 16-bit word of plane 1, and a 12-bit R component in the top 12 bits of each 16-bit word of plane 2, with the bottom 4 bits of each word unused. The horizontal and vertical dimensions of the R and B planes are halved relative to the image dimensions, and each R and B component is shared with the G components for which and . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. This format only supports images with a width and height that is a multiple of two. -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 12-bit G component in the top 12 bits of each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 12-bit B component in the top 12 bits of the word in bytes 0..1, and a 12-bit R component in the top 12 bits of the word in bytes 2..3, with the bottom 4 bits of each word unused. The horizontal and vertical dimensions of the BR plane are halved relative to the image dimensions, and each R and B value is shared with the G components for which and . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. This format only supports images with a width and height that is a multiple of two. -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 12-bit G component in the top 12 bits of each 16-bit word of plane 0, a 12-bit B component in the top 12 bits of each 16-bit word of plane 1, and a 12-bit R component in the top 12 bits of each 16-bit word of plane 2, with the bottom 4 bits of each word unused. The horizontal dimension of the R and B plane is halved relative to the image dimensions, and each R and B value is shared with the G components for which . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. This format only supports images with a width that is a multiple of two. -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 12-bit G component in the top 12 bits of each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 12-bit B component in the top 12 bits of the word in bytes 0..1, and a 12-bit R component in the top 12 bits of the word in bytes 2..3, with the bottom 4 bits of each word unused. The horizontal dimension of the BR plane is halved relative to the image dimensions, and each R and B value is shared with the G components for which . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. This format only supports images with a width that is a multiple of two. -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 12-bit G component in the top 12 bits of each 16-bit word of plane 0, a 12-bit B component in the top 12 bits of each 16-bit word of plane 1, and a 12-bit R component in the top 12 bits of each 16-bit word of plane 2, with the bottom 4 bits of each word unused. Each plane has the same dimensions and each R, G and B component contributes to a single texel. The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. -
VK_FORMAT_G16B16G16R16_422_UNORMspecifies a four-component, 64-bit format containing a pair of G components, an R component, and a B component, collectively encoding a 2×1 rectangle of unsigned normalized RGB texel data. One G value is present at each i coordinate, with the B and R values shared across both G values and thus recorded at half the horizontal resolution of the image. This format has a 16-bit G component for the even i coordinate in the word in bytes 0..1, a 16-bit B component in the word in bytes 2..3, a 16-bit G component for the odd i coordinate in the word in bytes 4..5, and a 16-bit R component in the word in bytes 6..7. This format only supports images with a width that is a multiple of two. For the purposes of the constraints on copy extents, this format is treated as a compressed format with a 2×1 compressed texel block. -
VK_FORMAT_B16G16R16G16_422_UNORMspecifies a four-component, 64-bit format containing a pair of G components, an R component, and a B component, collectively encoding a 2×1 rectangle of unsigned normalized RGB texel data. One G value is present at each i coordinate, with the B and R values shared across both G values and thus recorded at half the horizontal resolution of the image. This format has a 16-bit B component in the word in bytes 0..1, a 16-bit G component for the even i coordinate in the word in bytes 2..3, a 16-bit R component in the word in bytes 4..5, and a 16-bit G component for the odd i coordinate in the word in bytes 6..7. This format only supports images with a width that is a multiple of two. For the purposes of the constraints on copy extents, this format is treated as a compressed format with a 2×1 compressed texel block. -
VK_FORMAT_G16_B16_R16_3PLANE_420_UNORMspecifies an unsigned normalized multi-planar format that has a 16-bit G component in each 16-bit word of plane 0, a 16-bit B component in each 16-bit word of plane 1, and a 16-bit R component in each 16-bit word of plane 2. The horizontal and vertical dimensions of the R and B planes are halved relative to the image dimensions, and each R and B component is shared with the G components for which and . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. This format only supports images with a width and height that is a multiple of two. -
VK_FORMAT_G16_B16R16_2PLANE_420_UNORMspecifies an unsigned normalized multi-planar format that has a 16-bit G component in each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 16-bit B component in the word in bytes 0..1, and a 16-bit R component in the word in bytes 2..3. The horizontal and vertical dimensions of the BR plane are halved relative to the image dimensions, and each R and B value is shared with the G components for which and . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. This format only supports images with a width and height that is a multiple of two. -
VK_FORMAT_G16_B16_R16_3PLANE_422_UNORMspecifies an unsigned normalized multi-planar format that has a 16-bit G component in each 16-bit word of plane 0, a 16-bit B component in each 16-bit word of plane 1, and a 16-bit R component in each 16-bit word of plane 2. The horizontal dimension of the R and B plane is halved relative to the image dimensions, and each R and B value is shared with the G components for which . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. This format only supports images with a width that is a multiple of two. -
VK_FORMAT_G16_B16R16_2PLANE_422_UNORMspecifies an unsigned normalized multi-planar format that has a 16-bit G component in each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 16-bit B component in the word in bytes 0..1, and a 16-bit R component in the word in bytes 2..3. The horizontal dimension of the BR plane is halved relative to the image dimensions, and each R and B value is shared with the G components for which . The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. This format only supports images with a width that is a multiple of two. -
VK_FORMAT_G16_B16_R16_3PLANE_444_UNORMspecifies an unsigned normalized multi-planar format that has a 16-bit G component in each 16-bit word of plane 0, a 16-bit B component in each 16-bit word of plane 1, and a 16-bit R component in each 16-bit word of plane 2. Each plane has the same dimensions and each R, G and B component contributes to a single texel. The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane,VK_IMAGE_ASPECT_PLANE_1_BITfor the B plane, andVK_IMAGE_ASPECT_PLANE_2_BITfor the R plane. -
VK_FORMAT_G8_B8R8_2PLANE_444_UNORMspecifies an unsigned normalized multi-planar format that has an 8-bit G component in plane 0, and a two-component, 16-bit BR plane 1 consisting of an 8-bit B component in byte 0 and an 8-bit R component in byte 1. Both planes have the same dimensions and each R, G and B component contributes to a single texel. The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_444_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 10-bit G component in the top 10 bits of each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 10-bit B component in the top 10 bits of the word in bytes 0..1, and a 10-bit R component in the top 10 bits of the word in bytes 2..3, the bottom 6 bits of each word unused. Both planes have the same dimensions and each R, G and B component contributes to a single texel. The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_444_UNORM_3PACK16specifies an unsigned normalized multi-planar format that has a 12-bit G component in the top 12 bits of each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 12-bit B component in the top 12 bits of the word in bytes 0..1, and a 12-bit R component in the top 12 bits of the word in bytes 2..3, the bottom 4 bits of each word unused. Both planes have the same dimensions and each R, G and B component contributes to a single texel. The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. -
VK_FORMAT_G16_B16R16_2PLANE_444_UNORMspecifies an unsigned normalized multi-planar format that has a 16-bit G component in each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 16-bit B component in the word in bytes 0..1, and a 16-bit R component in the word in bytes 2..3. Both planes have the same dimensions and each R, G and B component contributes to a single texel. The location of each plane when this image is in linear layout can be determined via vkGetImageSubresourceLayout, usingVK_IMAGE_ASPECT_PLANE_0_BITfor the G plane, andVK_IMAGE_ASPECT_PLANE_1_BITfor the BR plane. -
VK_FORMAT_PVRTC1_2BPP_UNORM_BLOCK_IMGspecifies a four-component, PVRTC compressed format where each 64-bit compressed texel block encodes an 8×4 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_PVRTC1_4BPP_UNORM_BLOCK_IMGspecifies a four-component, PVRTC compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_PVRTC2_2BPP_UNORM_BLOCK_IMGspecifies a four-component, PVRTC compressed format where each 64-bit compressed texel block encodes an 8×4 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_PVRTC2_4BPP_UNORM_BLOCK_IMGspecifies a four-component, PVRTC compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data. -
VK_FORMAT_PVRTC1_2BPP_SRGB_BLOCK_IMGspecifies a four-component, PVRTC compressed format where each 64-bit compressed texel block encodes an 8×4 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_PVRTC1_4BPP_SRGB_BLOCK_IMGspecifies a four-component, PVRTC compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_PVRTC2_2BPP_SRGB_BLOCK_IMGspecifies a four-component, PVRTC compressed format where each 64-bit compressed texel block encodes an 8×4 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -
VK_FORMAT_PVRTC2_4BPP_SRGB_BLOCK_IMGspecifies a four-component, PVRTC compressed format where each 64-bit compressed texel block encodes a 4×4 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components.
43.1.1. Compatible formats of planes of multi-planar formats
Individual planes of multi-planar formats are compatible with single-plane formats if they occupy the same number of bits per texel block. In the following table, individual planes of a multi-planar format are compatible with the format listed against the relevant plane index for that multi-planar format, and any format compatible with the listed single-plane format according to Format Compatibility Classes.
| Plane | Compatible format for plane | Width relative to the width w of the plane with the largest dimensions | Height relative to the height h of the plane with the largest dimensions |
|---|---|---|---|
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h/2 |
2 |
|
w/2 |
h/2 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h/2 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h |
2 |
|
w/2 |
h |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h |
|
|||
0 |
|
w |
h |
1 |
|
w |
h |
2 |
|
w |
h |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h/2 |
2 |
|
w/2 |
h/2 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h/2 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h |
2 |
|
w/2 |
h |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h |
|
|||
0 |
|
w |
h |
1 |
|
w |
h |
2 |
|
w |
h |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h/2 |
2 |
|
w/2 |
h/2 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h/2 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h |
2 |
|
w/2 |
h |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h |
|
|||
0 |
|
w |
h |
1 |
|
w |
h |
2 |
|
w |
h |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h/2 |
2 |
|
w/2 |
h/2 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h/2 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h |
2 |
|
w/2 |
h |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h |
|
|||
0 |
|
w |
h |
1 |
|
w |
h |
2 |
|
w |
h |
|
|||
0 |
|
w |
h |
1 |
|
w |
h |
|
|||
0 |
|
w |
h |
1 |
|
w |
h |
|
|||
0 |
|
w |
h |
1 |
|
w |
h |
|
|||
0 |
|
w |
h |
1 |
|
w |
h |
43.1.2. Packed Formats
For the purposes of address alignment when accessing buffer memory containing vertex attribute or texel data, the following formats are considered packed - components of the texels or attributes are stored in bitfields packed into one or more 8-, 16-, or 32-bit fundamental data type.
-
-
VK_FORMAT_R4G4_UNORM_PACK8
-
-
Packed into 16-bit data types:
-
VK_FORMAT_R4G4B4A4_UNORM_PACK16 -
VK_FORMAT_B4G4R4A4_UNORM_PACK16 -
VK_FORMAT_R5G6B5_UNORM_PACK16 -
VK_FORMAT_B5G6R5_UNORM_PACK16 -
VK_FORMAT_R5G5B5A1_UNORM_PACK16 -
VK_FORMAT_B5G5R5A1_UNORM_PACK16 -
VK_FORMAT_A1R5G5B5_UNORM_PACK16 -
VK_FORMAT_R10X6_UNORM_PACK16 -
VK_FORMAT_R10X6G10X6_UNORM_2PACK16 -
VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 -
VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16 -
VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16 -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16 -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16 -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16 -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16 -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16 -
VK_FORMAT_R12X4_UNORM_PACK16 -
VK_FORMAT_R12X4G12X4_UNORM_2PACK16 -
VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16 -
VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16 -
VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16 -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16 -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_444_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_444_UNORM_3PACK16 -
VK_FORMAT_A4R4G4B4_UNORM_PACK16 -
VK_FORMAT_A4B4G4R4_UNORM_PACK16
-
-
Packed into 32-bit data types:
-
VK_FORMAT_A8B8G8R8_UNORM_PACK32 -
VK_FORMAT_A8B8G8R8_SNORM_PACK32 -
VK_FORMAT_A8B8G8R8_USCALED_PACK32 -
VK_FORMAT_A8B8G8R8_SSCALED_PACK32 -
VK_FORMAT_A8B8G8R8_UINT_PACK32 -
VK_FORMAT_A8B8G8R8_SINT_PACK32 -
VK_FORMAT_A8B8G8R8_SRGB_PACK32 -
VK_FORMAT_A2R10G10B10_UNORM_PACK32 -
VK_FORMAT_A2R10G10B10_SNORM_PACK32 -
VK_FORMAT_A2R10G10B10_USCALED_PACK32 -
VK_FORMAT_A2R10G10B10_SSCALED_PACK32 -
VK_FORMAT_A2R10G10B10_UINT_PACK32 -
VK_FORMAT_A2R10G10B10_SINT_PACK32 -
VK_FORMAT_A2B10G10R10_UNORM_PACK32 -
VK_FORMAT_A2B10G10R10_SNORM_PACK32 -
VK_FORMAT_A2B10G10R10_USCALED_PACK32 -
VK_FORMAT_A2B10G10R10_SSCALED_PACK32 -
VK_FORMAT_A2B10G10R10_UINT_PACK32 -
VK_FORMAT_A2B10G10R10_SINT_PACK32 -
VK_FORMAT_B10G11R11_UFLOAT_PACK32 -
VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 -
VK_FORMAT_X8_D24_UNORM_PACK32
-
43.1.3. Identification of Formats
A “format” is represented by a single enum value. The name of a format is usually built up by using the following pattern:
VK_FORMAT_{component-format|compression-scheme}_{numeric-format}
The component-format indicates either the size of the R, G, B, and A components (if they are present) in the case of a color format, or the size of the depth (D) and stencil (S) components (if they are present) in the case of a depth/stencil format (see below). An X indicates a component that is unused, but may be present for padding.
| Numeric format | SPIR-V Sampled Type | Description |
|---|---|---|
|
OpTypeFloat |
The components are unsigned normalized values in the range [0,1] |
|
OpTypeFloat |
The components are signed normalized values in the range [-1,1] |
|
OpTypeFloat |
The components are unsigned integer values that get converted to floating-point in the range [0,2n-1] |
|
OpTypeFloat |
The components are signed integer values that get converted to floating-point in the range [-2n-1,2n-1-1] |
|
OpTypeInt |
The components are unsigned integer values in the range [0,2n-1] |
|
OpTypeInt |
The components are signed integer values in the range [-2n-1,2n-1-1] |
|
OpTypeFloat |
The components are unsigned floating-point numbers (used by packed, shared exponent, and some compressed formats) |
|
OpTypeFloat |
The components are signed floating-point numbers |
|
OpTypeFloat |
The R, G, and B components are unsigned normalized values that represent values using sRGB nonlinear encoding, while the A component (if one exists) is a regular unsigned normalized value |
n is the number of bits in the component. |
||
The suffix _PACKnn indicates that the format is packed into an
underlying type with nn bits.
The suffix _mPACKnn is a short-hand that indicates that the format has
m groups of components (which may or may not be stored in separate
planes) that are each packed into an underlying type with nn bits.
The suffix _BLOCK indicates that the format is a block-compressed
format, with the representation of multiple pixels encoded interdependently
within a region.
| Compression scheme | Description |
|---|---|
|
Block Compression. See Block-Compressed Image Formats. |
|
Ericsson Texture Compression. See ETC Compressed Image Formats. |
|
ETC2 Alpha Compression. See ETC Compressed Image Formats. |
|
Adaptive Scalable Texture Compression (LDR Profile). See ASTC Compressed Image Formats. |
For multi-planar images, the components in separate planes are separated
by underscores, and the number of planes is indicated by the addition of a
_2PLANE or _3PLANE suffix.
Similarly, the separate aspects of depth-stencil formats are separated by
underscores, although these are not considered separate planes.
Formats are suffixed by _422 to indicate that planes other than the
first are reduced in size by a factor of two horizontally or that the R and
B values appear at half the horizontal frequency of the G values, _420
to indicate that planes other than the first are reduced in size by a factor
of two both horizontally and vertically, and _444 for consistency to
indicate that all three planes of a three-planar image are the same size.
|
Note
No common format has a single plane containing both R and B components but does not store these components at reduced horizontal resolution. |
43.1.4. Representation and Texel Block Size
Color formats must be represented in memory in exactly the form indicated by the format’s name. This means that promoting one format to another with more bits per component and/or additional components must not occur for color formats. Depth/stencil formats have more relaxed requirements as discussed below.
Each format has a texel block size, the number of bytes used to store one texel block (a single addressable element of an uncompressed image, or a single compressed block of a compressed image). The texel block size for each format is shown in the Compatible formats table.
The representation of non-packed formats is that the first component specified in the name of the format is in the lowest memory addresses and the last component specified is in the highest memory addresses. See Byte mappings for non-packed/compressed color formats. The in-memory ordering of bytes within a component is determined by the host endianness.
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | ← Byte |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
R |
|
|||||||||||||||
R |
G |
|
||||||||||||||
R |
G |
B |
|
|||||||||||||
B |
G |
R |
|
|||||||||||||
R |
G |
B |
A |
|
||||||||||||
B |
G |
R |
A |
|
||||||||||||
G0 |
B |
G1 |
R |
|
||||||||||||
B |
G0 |
R |
G1 |
|
||||||||||||
R |
|
|||||||||||||||
R |
G |
|
||||||||||||||
R |
G |
B |
|
|||||||||||||
R |
G |
B |
A |
|
||||||||||||
G0 |
B |
G1 |
R |
|
||||||||||||
B |
G0 |
R |
G1 |
|
||||||||||||
R |
|
|||||||||||||||
R |
G |
|
||||||||||||||
R |
G |
B |
|
|||||||||||||
R |
G |
B |
A |
|
||||||||||||
R |
|
|||||||||||||||
R |
G |
|
||||||||||||||
|
||||||||||||||||
|
||||||||||||||||
Packed formats store multiple components within one underlying type. The bit representation is that the first component specified in the name of the format is in the most-significant bits and the last component specified is in the least-significant bits of the underlying type. The in-memory ordering of bytes comprising the underlying type is determined by the host endianness.
| Bit | |||||||
|---|---|---|---|---|---|---|---|
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
|
|||||||
R |
G |
||||||
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
| Bit | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
15 |
14 |
13 |
12 |
11 |
10 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||
R |
G |
B |
A |
||||||||||||
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
|
|||||||||||||||
B |
G |
R |
A |
||||||||||||
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
|
|||||||||||||||
A |
R |
G |
B |
||||||||||||
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
|
|||||||||||||||
A |
B |
G |
R |
||||||||||||
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
|
|||||||||||||||
R |
G |
B |
|||||||||||||
4 |
3 |
2 |
1 |
0 |
5 |
4 |
3 |
2 |
1 |
0 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||
B |
G |
R |
|||||||||||||
4 |
3 |
2 |
1 |
0 |
5 |
4 |
3 |
2 |
1 |
0 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||
R |
G |
B |
A |
||||||||||||
4 |
3 |
2 |
1 |
0 |
4 |
3 |
2 |
1 |
0 |
4 |
3 |
2 |
1 |
0 |
0 |
|
|||||||||||||||
B |
G |
R |
A |
||||||||||||
4 |
3 |
2 |
1 |
0 |
4 |
3 |
2 |
1 |
0 |
4 |
3 |
2 |
1 |
0 |
0 |
|
|||||||||||||||
A |
R |
G |
B |
||||||||||||
0 |
4 |
3 |
2 |
1 |
0 |
4 |
3 |
2 |
1 |
0 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||
R |
X |
||||||||||||||
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
5 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||
R |
X |
||||||||||||||
11 |
10 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
3 |
2 |
1 |
0 |
| Bit | |||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
31 |
30 |
29 |
28 |
27 |
26 |
25 |
24 |
23 |
22 |
21 |
20 |
19 |
18 |
17 |
16 |
15 |
14 |
13 |
12 |
11 |
10 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||||||||||||||||||
A |
B |
G |
R |
||||||||||||||||||||||||||||
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||||||||||||||||||
A |
R |
G |
B |
||||||||||||||||||||||||||||
1 |
0 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||||||||||||||||||
A |
B |
G |
R |
||||||||||||||||||||||||||||
1 |
0 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||||||||||||||||||
B |
G |
R |
|||||||||||||||||||||||||||||
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
10 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
10 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||||||||||||||||||
E |
B |
G |
R |
||||||||||||||||||||||||||||
4 |
3 |
2 |
1 |
0 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
|
|||||||||||||||||||||||||||||||
X |
D |
||||||||||||||||||||||||||||||
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
23 |
22 |
21 |
20 |
19 |
18 |
17 |
16 |
15 |
14 |
13 |
12 |
11 |
10 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
43.1.5. Depth/Stencil Formats
Depth/stencil formats are considered opaque and need not be stored in the exact number of bits per texel or component ordering indicated by the format enum. However, implementations must not substitute a different depth or stencil precision than is described in the format (e.g. D16 must not be implemented as D24 or D32).
43.1.6. Format Compatibility Classes
Uncompressed color formats are compatible with each other if they occupy the same number of bits per texel block. Compressed color formats are compatible with each other if the only difference between them is the numerical type of the uncompressed pixels (e.g. signed vs. unsigned, or SRGB vs. UNORM encoding). Each depth/stencil format is only compatible with itself. In the following table, all the formats in the same row are compatible.
| Class, Texel Block Size, # Texels/Block | Formats |
|---|---|
8-bit |
|
16-bit |
|
24-bit |
|
32-bit |
|
48-bit |
|
64-bit |
|
96-bit |
|
128-bit |
|
192-bit |
|
256-bit |
|
D16 |
|
D24 |
|
D32 |
|
S8 |
|
D16S8 |
|
D24S8 |
|
D32S8 |
|
BC1_RGB |
|
BC1_RGBA |
|
BC2 |
|
BC3 |
|
BC4 |
|
BC5 |
|
BC6H |
|
BC7 |
|
ETC2_RGB |
|
ETC2_RGBA |
|
ETC2_EAC_RGBA |
|
EAC_R |
|
EAC_RG |
|
ASTC_4x4 |
|
ASTC_5x4 |
|
ASTC_5x5 |
|
ASTC_6x5 |
|
ASTC_6x6 |
|
ASTC_8x5 |
|
ASTC_8x6 |
|
ASTC_8x8 |
|
ASTC_10x5 |
|
ASTC_10x6 |
|
ASTC_10x8 |
|
ASTC_10x10 |
|
ASTC_12x10 |
|
ASTC_12x12 |
|
32-bit G8B8G8R8 |
|
32-bit B8G8R8G8 |
|
8-bit 3-plane 420 |
|
8-bit 2-plane 420 |
|
8-bit 3-plane 422 |
|
8-bit 2-plane 422 |
|
8-bit 3-plane 444 |
|
64-bit R10G10B10A10 |
|
64-bit G10B10G10R10 |
|
64-bit B10G10R10G10 |
|
10-bit 3-plane 420 |
|
10-bit 2-plane 420 |
|
10-bit 3-plane 422 |
|
10-bit 2-plane 422 |
|
10-bit 3-plane 444 |
|
64-bit R12G12B12A12 |
|
64-bit G12B12G12R12 |
|
64-bit B12G12R12G12 |
|
12-bit 3-plane 420 |
|
12-bit 2-plane 420 |
|
12-bit 3-plane 422 |
|
12-bit 2-plane 422 |
|
12-bit 3-plane 444 |
|
64-bit G16B16G16R16 |
|
64-bit B16G16R16G16 |
|
16-bit 3-plane 420 |
|
16-bit 2-plane 420 |
|
16-bit 3-plane 422 |
|
16-bit 2-plane 422 |
|
16-bit 3-plane 444 |
|
PVRTC1_2BPP |
|
PVRTC1_4BPP |
|
PVRTC2_2BPP |
|
PVRTC2_4BPP |
|
8-bit 2-plane 444 |
|
10-bit 2-plane 444 |
|
12-bit 2-plane 444 |
|
16-bit 2-plane 444 |
|
43.2. Format Properties
To query supported format features which are properties of the physical device, call:
// Provided by VK_VERSION_1_0
void vkGetPhysicalDeviceFormatProperties(
VkPhysicalDevice physicalDevice,
VkFormat format,
VkFormatProperties* pFormatProperties);
-
physicalDeviceis the physical device from which to query the format properties. -
formatis the format whose properties are queried. -
pFormatPropertiesis a pointer to a VkFormatProperties structure in which physical device properties forformatare returned.
The VkFormatProperties structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkFormatProperties {
VkFormatFeatureFlags linearTilingFeatures;
VkFormatFeatureFlags optimalTilingFeatures;
VkFormatFeatureFlags bufferFeatures;
} VkFormatProperties;
-
linearTilingFeaturesis a bitmask of VkFormatFeatureFlagBits specifying features supported by images created with atilingparameter ofVK_IMAGE_TILING_LINEAR. -
optimalTilingFeaturesis a bitmask of VkFormatFeatureFlagBits specifying features supported by images created with atilingparameter ofVK_IMAGE_TILING_OPTIMAL. -
bufferFeaturesis a bitmask of VkFormatFeatureFlagBits specifying features supported by buffers.
|
Note
If no format feature flags are supported, the format itself is not supported, and images of that format cannot be created. |
If format is a block-compressed format, then bufferFeatures
must not support any features for the format.
If format is not a multi-plane format then linearTilingFeatures
and optimalTilingFeatures must not contain
VK_FORMAT_FEATURE_DISJOINT_BIT.
Bits which can be set in the VkFormatProperties features
linearTilingFeatures, optimalTilingFeatures,
VkDrmFormatModifierPropertiesEXT::drmFormatModifierTilingFeatures,
and bufferFeatures are:
// Provided by VK_VERSION_1_0
typedef enum VkFormatFeatureFlagBits {
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT = 0x00000001,
VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT = 0x00000002,
VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT = 0x00000004,
VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT = 0x00000008,
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT = 0x00000010,
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT = 0x00000020,
VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT = 0x00000040,
VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT = 0x00000080,
VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT = 0x00000100,
VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000200,
VK_FORMAT_FEATURE_BLIT_SRC_BIT = 0x00000400,
VK_FORMAT_FEATURE_BLIT_DST_BIT = 0x00000800,
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT = 0x00001000,
// Provided by VK_VERSION_1_1
VK_FORMAT_FEATURE_TRANSFER_SRC_BIT = 0x00004000,
// Provided by VK_VERSION_1_1
VK_FORMAT_FEATURE_TRANSFER_DST_BIT = 0x00008000,
// Provided by VK_VERSION_1_1
VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT = 0x00020000,
// Provided by VK_VERSION_1_1
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT = 0x00040000,
// Provided by VK_VERSION_1_1
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT = 0x00080000,
// Provided by VK_VERSION_1_1
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT = 0x00100000,
// Provided by VK_VERSION_1_1
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT = 0x00200000,
// Provided by VK_VERSION_1_1
VK_FORMAT_FEATURE_DISJOINT_BIT = 0x00400000,
// Provided by VK_VERSION_1_1
VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT = 0x00800000,
// Provided by VK_VERSION_1_2
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT = 0x00010000,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_FORMAT_FEATURE_VIDEO_DECODE_OUTPUT_BIT_KHR = 0x02000000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_decode_queue
VK_FORMAT_FEATURE_VIDEO_DECODE_DPB_BIT_KHR = 0x04000000,
#endif
// Provided by VK_KHR_acceleration_structure
VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR = 0x20000000,
// Provided by VK_EXT_filter_cubic
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT = 0x00002000,
// Provided by VK_EXT_fragment_density_map
VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x01000000,
// Provided by VK_KHR_fragment_shading_rate
VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x40000000,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_encode_queue
VK_FORMAT_FEATURE_VIDEO_ENCODE_INPUT_BIT_KHR = 0x08000000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_encode_queue
VK_FORMAT_FEATURE_VIDEO_ENCODE_DPB_BIT_KHR = 0x10000000,
#endif
// Provided by VK_IMG_filter_cubic
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG = VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT,
// Provided by VK_KHR_maintenance1
VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR = VK_FORMAT_FEATURE_TRANSFER_SRC_BIT,
// Provided by VK_KHR_maintenance1
VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR = VK_FORMAT_FEATURE_TRANSFER_DST_BIT,
// Provided by VK_EXT_sampler_filter_minmax
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT = VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT_KHR = VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR = VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR = VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR = VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR = VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_FEATURE_DISJOINT_BIT_KHR = VK_FORMAT_FEATURE_DISJOINT_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR = VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT,
} VkFormatFeatureFlagBits;
These values
all have the same meaning as the equivalently named values for
VkFormatFeatureFlags2 and
may be set in
linearTilingFeatures, optimalTilingFeatures, and
VkDrmFormatModifierPropertiesEXT::drmFormatModifierTilingFeatures,
specifying that the features are supported by images or
image views
or sampler Y′CBCR conversion objects
created with the queried
vkGetPhysicalDeviceFormatProperties::format:
-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BITspecifies that an image view can be sampled from. -
VK_FORMAT_FEATURE_STORAGE_IMAGE_BITspecifies that an image view can be used as a storage image. -
VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BITspecifies that an image view can be used as storage image that supports atomic operations. -
VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BITspecifies that an image view can be used as a framebuffer color attachment and as an input attachment. -
VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BITspecifies that an image view can be used as a framebuffer color attachment that supports blending and as an input attachment. -
VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BITspecifies that an image view can be used as a framebuffer depth/stencil attachment and as an input attachment. -
VK_FORMAT_FEATURE_BLIT_SRC_BITspecifies that an image can be used assrcImagefor thevkCmdBlitImage2andvkCmdBlitImagecommands. -
VK_FORMAT_FEATURE_BLIT_DST_BITspecifies that an image can be used asdstImagefor thevkCmdBlitImage2andvkCmdBlitImagecommands. -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BITspecifies that ifVK_FORMAT_FEATURE_SAMPLED_IMAGE_BITis also set, an image view can be used with a sampler that has either ofmagFilterorminFilterset toVK_FILTER_LINEAR, ormipmapModeset toVK_SAMPLER_MIPMAP_MODE_LINEAR. IfVK_FORMAT_FEATURE_BLIT_SRC_BITis also set, an image can be used as thesrcImagetovkCmdBlitImage2andvkCmdBlitImagewith afilterofVK_FILTER_LINEAR. This bit must only be exposed for formats that also support theVK_FORMAT_FEATURE_SAMPLED_IMAGE_BITorVK_FORMAT_FEATURE_BLIT_SRC_BIT.If the format being queried is a depth/stencil format, this bit only specifies that the depth aspect (not the stencil aspect) of an image of this format supports linear filtering, and that linear filtering of the depth aspect is supported whether depth compare is enabled in the sampler or not. Where depth comparison is supported it may be linear filtered whether this bit is present or not, but where this bit is not present the filtered value may be computed in an implementation-dependent manner which differs from the normal rules of linear filtering. The resulting value must be in the range [0,1] and should be proportional to, or a weighted average of, the number of comparison passes or failures.
-
VK_FORMAT_FEATURE_TRANSFER_SRC_BITspecifies that an image can be used as a source image for copy commands. -
VK_FORMAT_FEATURE_TRANSFER_DST_BITspecifies that an image can be used as a destination image for copy commands and clear commands. -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BITspecifiesVkImagecan be used as a sampled image with a min or max VkSamplerReductionMode. This bit must only be exposed for formats that also support theVK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT. -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXTspecifies thatVkImagecan be used with a sampler that has either ofmagFilterorminFilterset toVK_FILTER_CUBIC_EXT, or be the source image for a blit withfilterset toVK_FILTER_CUBIC_EXT. This bit must only be exposed for formats that also support theVK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT. If the format being queried is a depth/stencil format, this only specifies that the depth aspect is cubic filterable. -
VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BITspecifies that an application can define a sampler Y′CBCR conversion using this format as a source, and that an image of this format can be used with a VkSamplerYcbcrConversionCreateInfoxChromaOffsetand/oryChromaOffsetofVK_CHROMA_LOCATION_MIDPOINT. Otherwise bothxChromaOffsetandyChromaOffsetmust beVK_CHROMA_LOCATION_COSITED_EVEN. If a format does not incorporate chroma downsampling (it is not a “422” or “420” format) but the implementation supports sampler Y′CBCR conversion for this format, the implementation must setVK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT. -
VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BITspecifies that an application can define a sampler Y′CBCR conversion using this format as a source, and that an image of this format can be used with a VkSamplerYcbcrConversionCreateInfoxChromaOffsetand/oryChromaOffsetofVK_CHROMA_LOCATION_COSITED_EVEN. Otherwise bothxChromaOffsetandyChromaOffsetmust beVK_CHROMA_LOCATION_MIDPOINT. If neitherVK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BITnorVK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BITis set, the application must not define a sampler Y′CBCR conversion using this format as a source. -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BITspecifies that an application can define a sampler Y′CBCR conversion using this format as a source withchromaFilterset toVK_FILTER_LINEAR. -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BITspecifies that the format can have different chroma, min, and mag filters. -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BITspecifies that reconstruction is explicit, as described in Chroma Reconstruction. If this bit is not present, reconstruction is implicit by default. -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BITspecifies that reconstruction can be forcibly made explicit by setting VkSamplerYcbcrConversionCreateInfo::forceExplicitReconstructiontoVK_TRUE. If the format being queried supportsVK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BITit must also supportVK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT. -
VK_FORMAT_FEATURE_DISJOINT_BITspecifies that a multi-planar image can have theVK_IMAGE_CREATE_DISJOINT_BITset during image creation. An implementation must not setVK_FORMAT_FEATURE_DISJOINT_BITfor single-plane formats. -
VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXTspecifies that an image view can be used as a fragment density map attachment. -
VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies that an image view can be used as a fragment shading rate attachment. An implementation must not set this feature for formats with numeric type other than*UINT, or set it as a buffer feature. -
VK_FORMAT_FEATURE_VIDEO_DECODE_OUTPUT_BIT_KHRspecifies that an image view with this format can be used as an output for video decode operations -
VK_FORMAT_FEATURE_VIDEO_DECODE_DPB_BIT_KHRspecifies that an image view with this format can be used as a DPB for video decode operations -
VK_FORMAT_FEATURE_VIDEO_ENCODE_INPUT_BIT_KHRspecifies that an image view with this format can be used as an input to video encode operations -
VK_FORMAT_FEATURE_VIDEO_ENCODE_DPB_BIT_KHRspecifies that an image view with this format can be used as a DPB for video encode operationsNoteSpecific video profiles may have additional restrictions on the format and other image creation parameters corresponding to image views used by video coding operations that can be enumerated using the vkGetPhysicalDeviceVideoFormatPropertiesKHR command, as described in Enumeration of Supported Video Output, Input and DPB Formats.
The following bits may be set in bufferFeatures, specifying that the
features are supported by buffers or buffer
views created with the queried
vkGetPhysicalDeviceFormatProperties::format:
-
VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BITspecifies that the format can be used to create a buffer view that can be bound to aVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERdescriptor. -
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BITspecifies that the format can be used to create a buffer view that can be bound to aVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERdescriptor. -
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BITspecifies that atomic operations are supported onVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERwith this format. -
VK_FORMAT_FEATURE_VERTEX_BUFFER_BITspecifies that the format can be used as a vertex attribute format (VkVertexInputAttributeDescription::format). -
VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHRspecifies that the format can be used as the vertex format when creating an acceleration structure (VkAccelerationStructureGeometryTrianglesDataKHR::vertexFormat). This format can also be used as the vertex format in host memory when doing host acceleration structure builds.
// Provided by VK_VERSION_1_0
typedef VkFlags VkFormatFeatureFlags;
VkFormatFeatureFlags is a bitmask type for setting a mask of zero or
more VkFormatFeatureFlagBits.
To query supported format features which are properties of the physical device, call:
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceFormatProperties2(
VkPhysicalDevice physicalDevice,
VkFormat format,
VkFormatProperties2* pFormatProperties);
or the equivalent command
// Provided by VK_KHR_get_physical_device_properties2
void vkGetPhysicalDeviceFormatProperties2KHR(
VkPhysicalDevice physicalDevice,
VkFormat format,
VkFormatProperties2* pFormatProperties);
-
physicalDeviceis the physical device from which to query the format properties. -
formatis the format whose properties are queried. -
pFormatPropertiesis a pointer to a VkFormatProperties2 structure in which physical device properties forformatare returned.
vkGetPhysicalDeviceFormatProperties2 behaves similarly to
vkGetPhysicalDeviceFormatProperties, with the ability to return
extended information in a pNext chain of output structures.
The VkFormatProperties2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkFormatProperties2 {
VkStructureType sType;
void* pNext;
VkFormatProperties formatProperties;
} VkFormatProperties2;
or the equivalent
// Provided by VK_KHR_get_physical_device_properties2
typedef VkFormatProperties2 VkFormatProperties2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatPropertiesis a VkFormatProperties structure describing features supported by the requested format.
To obtain the list of Linux DRM format
modifiers compatible with a VkFormat, add a
VkDrmFormatModifierPropertiesListEXT structure to the pNext
chain of VkFormatProperties2.
The VkDrmFormatModifierPropertiesListEXT structure is defined as:
// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkDrmFormatModifierPropertiesListEXT {
VkStructureType sType;
void* pNext;
uint32_t drmFormatModifierCount;
VkDrmFormatModifierPropertiesEXT* pDrmFormatModifierProperties;
} VkDrmFormatModifierPropertiesListEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifierCountis an inout parameter related to the number of modifiers compatible with theformat, as described below. -
pDrmFormatModifierPropertiesis eitherNULLor a pointer to an array of VkDrmFormatModifierPropertiesEXT structures.
If pDrmFormatModifierProperties is NULL, then the function returns
in drmFormatModifierCount the number of modifiers compatible with the
queried format.
Otherwise, the application must set drmFormatModifierCount to the
length of the array pDrmFormatModifierProperties; the function will
write at most drmFormatModifierCount elements to the array, and will
return in drmFormatModifierCount the number of elements written.
Among the elements in array pDrmFormatModifierProperties, each
returned drmFormatModifier must be unique.
The VkDrmFormatModifierPropertiesEXT structure describes properties of a VkFormat when that format is combined with a Linux DRM format modifier. These properties, like those of VkFormatProperties2, are independent of any particular image.
The VkDrmFormatModifierPropertiesEXT structure is defined as:
// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkDrmFormatModifierPropertiesEXT {
uint64_t drmFormatModifier;
uint32_t drmFormatModifierPlaneCount;
VkFormatFeatureFlags drmFormatModifierTilingFeatures;
} VkDrmFormatModifierPropertiesEXT;
-
drmFormatModifieris a Linux DRM format modifier. -
drmFormatModifierPlaneCountis the number of memory planes in any image created withformatanddrmFormatModifier. An image’s memory planecount is distinct from its format planecount, as explained below. -
drmFormatModifierTilingFeaturesis a bitmask of VkFormatFeatureFlagBits that are supported by any image created withformatanddrmFormatModifier.
The returned drmFormatModifierTilingFeatures must contain at least
one bit.
The implementation must not return DRM_FORMAT_MOD_INVALID in
drmFormatModifier.
An image’s memory planecount (as returned by
drmFormatModifierPlaneCount) is distinct from its format planecount
(in the sense of multi-planar
Y′CBCR formats).
In VkImageAspectFlags, each
VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT represents a memory plane
and each VK_IMAGE_ASPECT_PLANE_i_BIT a format plane.
An image’s set of format planes is an ordered partition of the image’s
content into separable groups of format components.
The ordered partition is encoded in the name of each VkFormat.
For example, VK_FORMAT_G8_B8R8_2PLANE_420_UNORM contains two format
planes; the first plane contains the green component and the second plane
contains the blue component and red component.
If the format name does not contain PLANE, then the format contains a
single plane; for example, VK_FORMAT_R8G8B8A8_UNORM.
Some commands, such as vkCmdCopyBufferToImage, do not operate on all
format components in the image, but instead operate only on the format
planes explicitly chosen by the application and operate on each format
plane independently.
An image’s set of memory planes is an ordered partition of the image’s memory rather than the image’s content. Each memory plane is a contiguous range of memory. The union of an image’s memory planes is not necessarily contiguous.
If an image is linear, then the partition is
the same for memory planes and for format planes.
Therefore, if the returned drmFormatModifier is
DRM_FORMAT_MOD_LINEAR, then drmFormatModifierPlaneCount must
equal the format planecount, and drmFormatModifierTilingFeatures
must be identical to the
VkFormatProperties2::linearTilingFeatures returned in the same
pNext chain.
If an image is non-linear, then the partition
of the image’s memory into memory planes is implementation-specific and
may be unrelated to the partition of the image’s content into format
planes.
For example, consider an image whose format is
VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM, tiling is
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, whose drmFormatModifier
is not DRM_FORMAT_MOD_LINEAR, and flags lacks
VK_IMAGE_CREATE_DISJOINT_BIT.
The image has 3 format planes, and commands such
vkCmdCopyBufferToImage act on each format plane independently as if
the data of each format plane were separable from the data of the other
planes.
In a straightforward implementation, the implementation may store the
image’s content in 3 adjacent memory planes where each memory plane
corresponds exactly to a format plane.
However, the implementation may also store the image’s content in a single
memory plane where all format components are combined using an
implementation-private block-compressed format; or the implementation may
store the image’s content in a collection of 7 adjacent memory planes
using an implementation-private sharding technique.
Because the image is non-linear and non-disjoint, the implementation has
much freedom when choosing the image’s placement in memory.
The memory planecount applies to function parameters and structures only
when the API specifies an explicit requirement on
drmFormatModifierPlaneCount.
In all other cases, the memory planecount is ignored.
The list of Linux DRM format modifiers
compatible with a VkFormat can be obtained by adding a
VkDrmFormatModifierPropertiesList2EXT structure to the pNext
chain of VkFormatProperties2.
The VkDrmFormatModifierPropertiesList2EXT structure is defined as:
// Provided by VK_KHR_format_feature_flags2 with VK_EXT_image_drm_format_modifier
typedef struct VkDrmFormatModifierPropertiesList2EXT {
VkStructureType sType;
void* pNext;
uint32_t drmFormatModifierCount;
VkDrmFormatModifierProperties2EXT* pDrmFormatModifierProperties;
} VkDrmFormatModifierPropertiesList2EXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifierCountis an inout parameter related to the number of modifiers compatible with theformat, as described below. -
pDrmFormatModifierPropertiesis eitherNULLor a pointer to an array of VkDrmFormatModifierProperties2EXT structures.
If pDrmFormatModifierProperties is NULL, the number of modifiers
compatible with the queried format is returned in
drmFormatModifierCount.
Otherwise, the application must set drmFormatModifierCount to the
length of the array pDrmFormatModifierProperties; the function will
write at most drmFormatModifierCount elements to the array, and will
return in drmFormatModifierCount the number of elements written.
Among the elements in array pDrmFormatModifierProperties, each
returned drmFormatModifier must be unique.
Among the elements in array pDrmFormatModifierProperties, the bits
reported in drmFormatModifierTilingFeatures must include the bits
reported in the corresponding element of
VkDrmFormatModifierPropertiesListEXT::pDrmFormatModifierProperties.
The VkDrmFormatModifierProperties2EXT structure describes properties of a VkFormat when that format is combined with a Linux DRM format modifier. These properties, like those of VkFormatProperties2, are independent of any particular image.
The VkDrmFormatModifierPropertiesEXT structure is defined as:
// Provided by VK_KHR_format_feature_flags2 with VK_EXT_image_drm_format_modifier
typedef struct VkDrmFormatModifierProperties2EXT {
uint64_t drmFormatModifier;
uint32_t drmFormatModifierPlaneCount;
VkFormatFeatureFlags2 drmFormatModifierTilingFeatures;
} VkDrmFormatModifierProperties2EXT;
-
drmFormatModifieris a Linux DRM format modifier. -
drmFormatModifierPlaneCountis the number of memory planes in any image created withformatanddrmFormatModifier. An image’s memory planecount is distinct from its format planecount, as explained below. -
drmFormatModifierTilingFeaturesis a bitmask of VkFormatFeatureFlagBits2 that are supported by any image created withformatanddrmFormatModifier.
To query supported format extended features which are properties of the
physical device, add VkFormatProperties3 structure to the pNext
chain of VkFormatProperties2.
The VkFormatProperties3 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkFormatProperties3 {
VkStructureType sType;
void* pNext;
VkFormatFeatureFlags2 linearTilingFeatures;
VkFormatFeatureFlags2 optimalTilingFeatures;
VkFormatFeatureFlags2 bufferFeatures;
} VkFormatProperties3;
or the equivalent
// Provided by VK_KHR_format_feature_flags2
typedef VkFormatProperties3 VkFormatProperties3KHR;
-
linearTilingFeaturesis a bitmask of VkFormatFeatureFlagBits2 specifying features supported by images created with atilingparameter ofVK_IMAGE_TILING_LINEAR. -
optimalTilingFeaturesis a bitmask of VkFormatFeatureFlagBits2 specifying features supported by images created with atilingparameter ofVK_IMAGE_TILING_OPTIMAL. -
bufferFeaturesis a bitmask of VkFormatFeatureFlagBits2 specifying features supported by buffers.
The bits reported in linearTilingFeatures, optimalTilingFeatures
and bufferFeatures must include the bits reported in the
corresponding fields of VkFormatProperties2::formatProperties.
Bits which can be set in the VkFormatProperties3 features
linearTilingFeatures, optimalTilingFeatures, and
bufferFeatures are:
// Provided by VK_VERSION_1_3
// Flag bits for VkFormatFeatureFlagBits2
typedef VkFlags64 VkFormatFeatureFlagBits2;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT = 0x00000001ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT_KHR = 0x00000001ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_IMAGE_BIT = 0x00000002ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_IMAGE_BIT_KHR = 0x00000002ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_IMAGE_ATOMIC_BIT = 0x00000004ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_IMAGE_ATOMIC_BIT_KHR = 0x00000004ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_UNIFORM_TEXEL_BUFFER_BIT = 0x00000008ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR = 0x00000008ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_BIT = 0x00000010ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_BIT_KHR = 0x00000010ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_ATOMIC_BIT = 0x00000020ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_ATOMIC_BIT_KHR = 0x00000020ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VERTEX_BUFFER_BIT = 0x00000040ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VERTEX_BUFFER_BIT_KHR = 0x00000040ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BIT = 0x00000080ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BIT_KHR = 0x00000080ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BLEND_BIT = 0x00000100ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BLEND_BIT_KHR = 0x00000100ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000200ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_DEPTH_STENCIL_ATTACHMENT_BIT_KHR = 0x00000200ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BLIT_SRC_BIT = 0x00000400ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BLIT_SRC_BIT_KHR = 0x00000400ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BLIT_DST_BIT = 0x00000800ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BLIT_DST_BIT_KHR = 0x00000800ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_LINEAR_BIT = 0x00001000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_LINEAR_BIT_KHR = 0x00001000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_CUBIC_BIT = 0x00002000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT = 0x00002000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TRANSFER_SRC_BIT = 0x00004000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TRANSFER_SRC_BIT_KHR = 0x00004000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TRANSFER_DST_BIT = 0x00008000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TRANSFER_DST_BIT_KHR = 0x00008000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_MINMAX_BIT = 0x00010000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_MINMAX_BIT_KHR = 0x00010000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_MIDPOINT_CHROMA_SAMPLES_BIT = 0x00020000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_MIDPOINT_CHROMA_SAMPLES_BIT_KHR = 0x00020000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT = 0x00040000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR = 0x00040000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT = 0x00080000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR = 0x00080000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT = 0x00100000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR = 0x00100000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT = 0x00200000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR = 0x00200000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_DISJOINT_BIT = 0x00400000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_DISJOINT_BIT_KHR = 0x00400000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COSITED_CHROMA_SAMPLES_BIT = 0x00800000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COSITED_CHROMA_SAMPLES_BIT_KHR = 0x00800000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT = 0x80000000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHR = 0x80000000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT = 0x100000000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHR = 0x100000000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT = 0x200000000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT_KHR = 0x200000000ULL;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_format_feature_flags2 with VK_KHR_video_decode_queue
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_DECODE_OUTPUT_BIT_KHR = 0x02000000ULL;
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_format_feature_flags2 with VK_KHR_video_decode_queue
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_DECODE_DPB_BIT_KHR = 0x04000000ULL;
#endif
// Provided by VK_KHR_acceleration_structure with VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR = 0x20000000ULL;
// Provided by VK_KHR_format_feature_flags2 with VK_EXT_fragment_density_map
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x01000000ULL;
// Provided by VK_KHR_format_feature_flags2 with VK_KHR_fragment_shading_rate
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x40000000ULL;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_format_feature_flags2 with VK_KHR_video_encode_queue
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_ENCODE_INPUT_BIT_KHR = 0x08000000ULL;
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_format_feature_flags2 with VK_KHR_video_encode_queue
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_ENCODE_DPB_BIT_KHR = 0x10000000ULL;
#endif
// Provided by VK_KHR_format_feature_flags2 with VK_NV_linear_color_attachment
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV = 0x4000000000ULL;
or the equivalent
// Provided by VK_KHR_format_feature_flags2
typedef VkFormatFeatureFlagBits2 VkFormatFeatureFlagBits2KHR;
The following bits may be set in linearTilingFeatures and
optimalTilingFeatures, specifying that the features are supported by
images or image views
or sampler Y′CBCR conversion objects
created with the queried
vkGetPhysicalDeviceFormatProperties2::format:
-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BITspecifies that an image view can be sampled from. -
VK_FORMAT_FEATURE_2_STORAGE_IMAGE_BITspecifies that an image view can be used as a storage image. -
VK_FORMAT_FEATURE_2_STORAGE_IMAGE_ATOMIC_BITspecifies that an image view can be used as storage image that supports atomic operations. -
VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BITspecifies that an image view can be used as a framebuffer color attachment and as an input attachment. -
VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BLEND_BITspecifies that an image view can be used as a framebuffer color attachment that supports blending and as an input attachment. -
VK_FORMAT_FEATURE_2_DEPTH_STENCIL_ATTACHMENT_BITspecifies that an image view can be used as a framebuffer depth/stencil attachment and as an input attachment. -
VK_FORMAT_FEATURE_2_BLIT_SRC_BITspecifies that an image can be used as thesrcImagefor vkCmdBlitImage2 and vkCmdBlitImage. -
VK_FORMAT_FEATURE_2_BLIT_DST_BITspecifies that an image can be used as thedstImagefor vkCmdBlitImage2 and vkCmdBlitImage. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_LINEAR_BITspecifies that ifVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BITis also set, an image view can be used with a sampler that has either ofmagFilterorminFilterset toVK_FILTER_LINEAR, ormipmapModeset toVK_SAMPLER_MIPMAP_MODE_LINEAR. IfVK_FORMAT_FEATURE_2_BLIT_SRC_BITis also set, an image can be used as thesrcImagefor vkCmdBlitImage2 andvkCmdBlitImagewith afilterofVK_FILTER_LINEAR. This bit must only be exposed for formats that also support theVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BITorVK_FORMAT_FEATURE_2_BLIT_SRC_BIT.If the format being queried is a depth/stencil format, this bit only specifies that the depth aspect (not the stencil aspect) of an image of this format supports linear filtering. Where depth comparison is supported it may be linear filtered whether this bit is present or not, but where this bit is not present the filtered value may be computed in an implementation-dependent manner which differs from the normal rules of linear filtering. The resulting value must be in the range [0,1] and should be proportional to, or a weighted average of, the number of comparison passes or failures.
-
VK_FORMAT_FEATURE_2_TRANSFER_SRC_BITspecifies that an image can be used as a source image for copy commands. -
VK_FORMAT_FEATURE_2_TRANSFER_DST_BITspecifies that an image can be used as a destination image for copy commands and clear commands. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_MINMAX_BITspecifiesVkImagecan be used as a sampled image with a min or max VkSamplerReductionMode. This bit must only be exposed for formats that also support theVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_CUBIC_BITspecifies thatVkImagecan be used with a sampler that has either ofmagFilterorminFilterset toVK_FILTER_CUBIC_EXT, or be the source image for a blit withfilterset toVK_FILTER_CUBIC_EXT. This bit must only be exposed for formats that also support theVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT. If the format being queried is a depth/stencil format, this only specifies that the depth aspect is cubic filterable. -
VK_FORMAT_FEATURE_2_MIDPOINT_CHROMA_SAMPLES_BITspecifies that an application can define a sampler Y′CBCR conversion using this format as a source, and that an image of this format can be used with a VkSamplerYcbcrConversionCreateInfoxChromaOffsetand/oryChromaOffsetofVK_CHROMA_LOCATION_MIDPOINT. Otherwise bothxChromaOffsetandyChromaOffsetmust beVK_CHROMA_LOCATION_COSITED_EVEN. If a format does not incorporate chroma downsampling (it is not a “422” or “420” format) but the implementation supports sampler Y′CBCR conversion for this format, the implementation must setVK_FORMAT_FEATURE_2_MIDPOINT_CHROMA_SAMPLES_BIT. -
VK_FORMAT_FEATURE_2_COSITED_CHROMA_SAMPLES_BITspecifies that an application can define a sampler Y′CBCR conversion using this format as a source, and that an image of this format can be used with a VkSamplerYcbcrConversionCreateInfoxChromaOffsetand/oryChromaOffsetofVK_CHROMA_LOCATION_COSITED_EVEN. Otherwise bothxChromaOffsetandyChromaOffsetmust beVK_CHROMA_LOCATION_MIDPOINT. If neitherVK_FORMAT_FEATURE_2_COSITED_CHROMA_SAMPLES_BITnorVK_FORMAT_FEATURE_2_MIDPOINT_CHROMA_SAMPLES_BITis set, the application must not define a sampler Y′CBCR conversion using this format as a source. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BITspecifies that an application can define a sampler Y′CBCR conversion using this format as a source withchromaFilterset toVK_FILTER_LINEAR. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BITspecifies that the format can have different chroma, min, and mag filters. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BITspecifies that reconstruction is explicit, as described in Chroma Reconstruction. If this bit is not present, reconstruction is implicit by default. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BITspecifies that reconstruction can be forcibly made explicit by setting VkSamplerYcbcrConversionCreateInfo::forceExplicitReconstructiontoVK_TRUE. If the format being queried supportsVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BITit must also supportVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT. -
VK_FORMAT_FEATURE_2_DISJOINT_BITspecifies that a multi-planar image can have theVK_IMAGE_CREATE_DISJOINT_BITset during image creation. An implementation must not setVK_FORMAT_FEATURE_2_DISJOINT_BITfor single-plane formats. -
VK_FORMAT_FEATURE_2_FRAGMENT_DENSITY_MAP_BIT_EXTspecifies that an image view can be used as a fragment density map attachment. -
VK_FORMAT_FEATURE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies that an image view can be used as a fragment shading rate attachment. An implementation must not set this feature for formats with numeric type other than*UINT, or set it as a buffer feature. -
VK_FORMAT_FEATURE_2_VIDEO_DECODE_OUTPUT_BIT_KHRspecifies that an image view with this format can be used as an output for video decode operations -
VK_FORMAT_FEATURE_2_VIDEO_DECODE_DPB_BIT_KHRspecifies that an image view with this format can be used as a DPB for video decode operations -
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_INPUT_BIT_KHRspecifies that an image view with this format can be used as an input to video encode operations -
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_DPB_BIT_KHRspecifies that an image view with this format can be used as a DPB for video encode operationsNoteSpecific video profiles may have additional restrictions on the format and other image creation parameters corresponding to image views used by video coding operations that can be enumerated using the vkGetPhysicalDeviceVideoFormatPropertiesKHR command, as described in Enumeration of Supported Video Output, Input and DPB Formats.
-
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BITspecifies that image views created with this format can be used as storage images for read operations without specifying a format. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITspecifies that image views created with this format can be used as storage images for write operations without specifying a format. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BITspecifies that image views created with this format can be used for depth comparison performed byOpImage*Dref*instructions. -
VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NVspecifies that the format is supported as a renderable Linear Color Attachment. This bit will be set for renderable color formats in thelinearTilingFeatures. This must not be set in theoptimalTilingFeaturesorbufferFeaturesmembers.
The following bits may be set in bufferFeatures, specifying that the
features are supported by buffers or buffer
views created with the queried
vkGetPhysicalDeviceFormatProperties2::format:
-
VK_FORMAT_FEATURE_2_UNIFORM_TEXEL_BUFFER_BITspecifies that the format can be used to create a buffer view that can be bound to aVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERdescriptor. -
VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_BITspecifies that the format can be used to create a buffer view that can be bound to aVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERdescriptor. -
VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_ATOMIC_BITspecifies that atomic operations are supported onVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERwith this format. -
VK_FORMAT_FEATURE_2_VERTEX_BUFFER_BITspecifies that the format can be used as a vertex attribute format (VkVertexInputAttributeDescription::format). -
VK_FORMAT_FEATURE_2_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHRspecifies that the format can be used as the vertex format when creating an acceleration structure (VkAccelerationStructureGeometryTrianglesDataKHR::vertexFormat). This format can also be used as the vertex format in host memory when doing host acceleration structure builds.
// Provided by VK_VERSION_1_3
typedef VkFlags64 VkFormatFeatureFlags2;
or the equivalent
// Provided by VK_KHR_format_feature_flags2
typedef VkFormatFeatureFlags2 VkFormatFeatureFlags2KHR;
VkFormatFeatureFlags2 is a bitmask type for setting a mask of zero or
more VkFormatFeatureFlagBits2.
To query the performance characteristics of a subpass
resolve operation for an attachment with a VkFormat, add a
VkSubpassResolvePerformanceQueryEXT structure to the pNext chain
of VkFormatProperties2.
The VkSubpassResolvePerformanceQueryEXT structure is defined as:
// Provided by VK_EXT_multisampled_render_to_single_sampled
typedef struct VkSubpassResolvePerformanceQueryEXT {
VkStructureType sType;
void* pNext;
VkBool32 optimal;
} VkSubpassResolvePerformanceQueryEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
optimalspecifies that a subpass resolve operation is optimally performed.
If optimal is VK_FALSE for a VkFormat, using a subpass
resolve operation on a multisampled attachment with this format can incur
additional costs, including additional memory bandwidth usage and a higher
memory footprint.
If an attachment with such a format is used in a
multisampled-render-to-single-sampled
subpass, the additional memory and memory bandwidth usage can nullify the
benefits of using the VK_EXT_multisampled_render_to_single_sampled
extension.
43.2.1. Potential Format Features
Some valid usage conditions depend on the format features supported by an VkImage whose VkImageTiling is unknown. In such cases the exact VkFormatFeatureFlagBits supported by the VkImage cannot be determined, so the valid usage conditions are expressed in terms of the potential format features of the VkImage format.
The potential format features of a VkFormat are defined as follows:
-
The union of VkFormatFeatureFlagBits and VkFormatFeatureFlagBits2, supported when the VkImageTiling is
VK_IMAGE_TILING_OPTIMAL,VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, orVK_IMAGE_TILING_LINEARif VkFormat is notVK_FORMAT_UNDEFINED -
VkAndroidHardwareBufferFormatPropertiesANDROID::
formatFeaturesand VkAndroidHardwareBufferFormatProperties2ANDROID::formatFeaturesof a valid external format if VkFormat isVK_FORMAT_UNDEFINED
43.3. Required Format Support
Implementations must support at least the following set of features on the listed formats. For images, these features must be supported for every VkImageType (including arrayed and cube variants) unless otherwise noted. These features are supported on existing formats without needing to advertise an extension or needing to explicitly enable them. Support for additional functionality beyond the requirements listed here is queried using the vkGetPhysicalDeviceFormatProperties command.
|
Note
Unless otherwise excluded below, the required formats are supported for all VkImageCreateFlags values as long as those flag values are otherwise allowed. |
The following tables show which feature bits must be supported for each
format.
Formats that are required to support
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT must also support
VK_FORMAT_FEATURE_TRANSFER_SRC_BIT and
VK_FORMAT_FEATURE_TRANSFER_DST_BIT.
✓ |
This feature must be supported on the named format |
† |
This feature must be supported on at least some of the named formats, with more information in the table where the symbol appears |
‡ |
This feature must be supported with some caveats or preconditions, with more information in the table where the symbol appears |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
✓ |
||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||||
|
† |
† |
† |
||||||||||
|
‡ |
‡ |
‡ |
||||||||||
Format features marked † must be supported for
|
|||||||||||||
Format features marked ‡ must be supported for
|
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
✓ |
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
✓ |
||||
|
✓ |
✓ |
✓ |
‡ |
✓ |
✓ |
|||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
||||||
|
|||||||||||||
|
✓ |
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
✓ |
||||
|
✓ |
✓ |
✓ |
‡ |
✓ |
✓ |
|||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
Format features marked with ‡ must be supported for
|
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
✓ |
||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
|||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
Format features marked with ‡ must be supported for
|
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
‡ |
✓ |
|||||||||||
|
‡ |
✓ |
|||||||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
✓ |
||||
|
‡ |
✓ |
|||||||||||
|
‡ |
✓ |
|||||||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
||||||
|
✓ |
✓ |
✓ |
‡ |
✓ |
✓ |
✓ |
✓ |
✓ |
||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
‡ |
✓ |
|||||||||||
|
‡ |
✓ |
|||||||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||
Format features marked with ‡ must be supported for
|
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
||||||||||||
|
✓ |
||||||||||||
|
✓ |
||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
If the |
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
† |
† |
|||||||||||
|
† |
† |
|||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
|||||||||||||
|
✓ |
✓ |
✓ |
‡ |
✓ |
||||||||
|
✓ |
✓ |
✓ |
||||||||||
Format features marked with ‡ must be supported for
|
|||||||||||||
If the |
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
✓ |
✓ |
✓ |
||||||||||
|
† |
||||||||||||
|
✓ |
✓ |
† |
||||||||||
|
|||||||||||||
|
|||||||||||||
|
† |
||||||||||||
|
† |
||||||||||||
|
|||||||||||||
|
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
The |
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
The |
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
|
† |
† |
† |
||||||||||
The |
|||||||||||||
If cubic filtering is supported,
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT must be
supported for the following image view types:
-
VK_IMAGE_VIEW_TYPE_2D -
VK_IMAGE_VIEW_TYPE_2D_ARRAY
for the following formats:
-
VK_FORMAT_R4G4_UNORM_PACK8 -
VK_FORMAT_R4G4B4A4_UNORM_PACK16 -
VK_FORMAT_B4G4R4A4_UNORM_PACK16 -
VK_FORMAT_R5G6B5_UNORM_PACK16 -
VK_FORMAT_B5G6R5_UNORM_PACK16 -
VK_FORMAT_R5G5B5A1_UNORM_PACK16 -
VK_FORMAT_B5G5R5A1_UNORM_PACK16 -
VK_FORMAT_A1R5G5B5_UNORM_PACK16 -
VK_FORMAT_R8_UNORM -
VK_FORMAT_R8_SNORM -
VK_FORMAT_R8_SRGB -
VK_FORMAT_R8G8_UNORM -
VK_FORMAT_R8G8_SNORM -
VK_FORMAT_R8G8_SRGB -
VK_FORMAT_R8G8B8_UNORM -
VK_FORMAT_R8G8B8_SNORM -
VK_FORMAT_R8G8B8_SRGB -
VK_FORMAT_B8G8R8_UNORM -
VK_FORMAT_B8G8R8_SNORM -
VK_FORMAT_B8G8R8_SRGB -
VK_FORMAT_R8G8B8A8_UNORM -
VK_FORMAT_R8G8B8A8_SNORM -
VK_FORMAT_R8G8B8A8_SRGB -
VK_FORMAT_B8G8R8A8_UNORM -
VK_FORMAT_B8G8R8A8_SNORM -
VK_FORMAT_B8G8R8A8_SRGB -
VK_FORMAT_A8B8G8R8_UNORM_PACK32 -
VK_FORMAT_A8B8G8R8_SNORM_PACK32 -
VK_FORMAT_A8B8G8R8_SRGB_PACK32
If ETC compressed formats are supported,
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT must be
supported for the following image view types:
-
VK_IMAGE_VIEW_TYPE_2D -
VK_IMAGE_VIEW_TYPE_2D_ARRAY
for the following additional formats:
-
VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK -
VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK -
VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK -
VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK -
VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK -
VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK
If cubic filtering is supported for any other formats, the following image view types must be supported for those formats:
-
VK_IMAGE_VIEW_TYPE_2D -
VK_IMAGE_VIEW_TYPE_2D_ARRAY
To be used with VkImageView with subresourceRange.aspectMask
equal to VK_IMAGE_ASPECT_COLOR_BIT, sampler Y′CBCR conversion must be enabled for the following formats:
|
↓ |
||||||||||
|
↓ |
||||||||||
|
↓ |
||||||||||
|
↓ |
||||||||||
|
↓ |
||||||||||
|
↓ |
||||||||||
|
↓ |
||||||||||
|
↓ |
||||||||||
|
↓ |
||||||||||
|
↓ |
||||||||||
Format |
Planes |
||||||||||
|
1 |
||||||||||
|
1 |
||||||||||
|
3 |
† |
† |
† |
† |
||||||
|
2 |
† |
† |
† |
† |
||||||
|
3 |
||||||||||
|
2 |
||||||||||
|
3 |
||||||||||
|
1 |
||||||||||
|
1 |
||||||||||
|
1 |
||||||||||
|
3 |
||||||||||
|
2 |
||||||||||
|
3 |
||||||||||
|
2 |
||||||||||
|
3 |
||||||||||
|
1 |
||||||||||
|
1 |
||||||||||
|
1 |
||||||||||
|
3 |
||||||||||
|
2 |
||||||||||
|
3 |
||||||||||
|
2 |
||||||||||
|
3 |
||||||||||
|
1 |
||||||||||
|
1 |
||||||||||
|
3 |
||||||||||
|
2 |
||||||||||
|
3 |
||||||||||
|
2 |
||||||||||
|
3 |
||||||||||
|
2 |
||||||||||
|
2 |
||||||||||
|
2 |
||||||||||
|
2 |
||||||||||
Format features marked † must be supported for
|
|||||||||||
Formats marked ‡ do not require a sampler Y′CBCR conversion for
|
|||||||||||
Implementations are not required to support the
VK_IMAGE_CREATE_SPARSE_BINDING_BIT,
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or
VK_IMAGE_CREATE_SPARSE_ALIASED_BIT VkImageCreateFlags for the
above formats that require sampler Y′CBCR
conversion.
To determine whether the implementation supports sparse image creation flags
with these formats use vkGetPhysicalDeviceImageFormatProperties or
vkGetPhysicalDeviceImageFormatProperties2.
VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXT must be supported for
the following formats if the fragmentDensityMap feature is enabled:
-
VK_FORMAT_R8G8_UNORM
VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR must
be supported in bufferFeatures for the following formats if the
accelerationStructure feature is
supported:
-
VK_FORMAT_R32G32_SFLOAT -
VK_FORMAT_R32G32B32_SFLOAT -
VK_FORMAT_R16G16_SFLOAT -
VK_FORMAT_R16G16B16A16_SFLOAT -
VK_FORMAT_R16G16_SNORM -
VK_FORMAT_R16G16B16A16_SNORM
VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR must be
supported for the following formats if the
attachmentFragmentShadingRate feature is supported:
-
VK_FORMAT_R8_UINT
43.3.1. Formats without shader storage format
The device-level features for using a storage image with an image format of
Unknown, shaderStorageImageReadWithoutFormat and
shaderStorageImageWriteWithoutFormat, only apply to the following
formats:
-
VK_FORMAT_R8G8B8A8_UNORM -
VK_FORMAT_R8G8B8A8_SNORM -
VK_FORMAT_R8G8B8A8_UINT -
VK_FORMAT_R8G8B8A8_SINT -
VK_FORMAT_R32_UINT -
VK_FORMAT_R32_SINT -
VK_FORMAT_R32_SFLOAT -
VK_FORMAT_R32G32_UINT -
VK_FORMAT_R32G32_SINT -
VK_FORMAT_R32G32_SFLOAT -
VK_FORMAT_R32G32B32A32_UINT -
VK_FORMAT_R32G32B32A32_SINT -
VK_FORMAT_R32G32B32A32_SFLOAT -
VK_FORMAT_R16G16B16A16_UINT -
VK_FORMAT_R16G16B16A16_SINT -
VK_FORMAT_R16G16B16A16_SFLOAT -
VK_FORMAT_R16G16_SFLOAT -
VK_FORMAT_B10G11R11_UFLOAT_PACK32 -
VK_FORMAT_R16_SFLOAT -
VK_FORMAT_R16G16B16A16_UNORM -
VK_FORMAT_A2B10G10R10_UNORM_PACK32 -
VK_FORMAT_R16G16_UNORM -
VK_FORMAT_R8G8_UNORM -
VK_FORMAT_R16_UNORM -
VK_FORMAT_R8_UNORM -
VK_FORMAT_R16G16B16A16_SNORM -
VK_FORMAT_R16G16_SNORM -
VK_FORMAT_R8G8_SNORM -
VK_FORMAT_R16_SNORM -
VK_FORMAT_R8_SNORM -
VK_FORMAT_R16G16_SINT -
VK_FORMAT_R8G8_SINT -
VK_FORMAT_R16_SINT -
VK_FORMAT_R8_SINT -
VK_FORMAT_A2B10G10R10_UINT_PACK32 -
VK_FORMAT_R16G16_UINT -
VK_FORMAT_R8G8_UINT -
VK_FORMAT_R16_UINT -
VK_FORMAT_R8_UINT
|
Note
This list of formats is the union of required storage formats from
Required Format Support section and
formats listed in |
An implementation that supports VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT
for any format from the given list of formats and supports
shaderStorageImageReadWithoutFormat must support
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT for that same
format if Vulkan 1.3 or the VK_KHR_format_feature_flags2 extension
is supported.
An implementation that supports VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT
for any format from the given list of formats and supports
shaderStorageImageWriteWithoutFormat must support
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT for that same
format if Vulkan 1.3 or the VK_KHR_format_feature_flags2 extension
is supported.
43.3.2. Depth comparison format support
If Vulkan 1.3 or the VK_KHR_format_feature_flags2 extension is
supported, a depth/stencil format with a depth component supporting
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT must support
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT.
44. Additional Capabilities
This chapter describes additional capabilities beyond the minimum capabilities described in the Limits and Formats chapters, including:
44.1. Additional Image Capabilities
Additional image capabilities, such as larger dimensions or additional sample counts for certain image types, or additional capabilities for linear tiling format images, are described in this section.
To query additional capabilities specific to image types, call:
// Provided by VK_VERSION_1_0
VkResult vkGetPhysicalDeviceImageFormatProperties(
VkPhysicalDevice physicalDevice,
VkFormat format,
VkImageType type,
VkImageTiling tiling,
VkImageUsageFlags usage,
VkImageCreateFlags flags,
VkImageFormatProperties* pImageFormatProperties);
-
physicalDeviceis the physical device from which to query the image capabilities. -
formatis a VkFormat value specifying the image format, corresponding to VkImageCreateInfo::format. -
typeis a VkImageType value specifying the image type, corresponding to VkImageCreateInfo::imageType. -
tilingis a VkImageTiling value specifying the image tiling, corresponding to VkImageCreateInfo::tiling. -
usageis a bitmask of VkImageUsageFlagBits specifying the intended usage of the image, corresponding to VkImageCreateInfo::usage. -
flagsis a bitmask of VkImageCreateFlagBits specifying additional parameters of the image, corresponding to VkImageCreateInfo::flags. -
pImageFormatPropertiesis a pointer to a VkImageFormatProperties structure in which capabilities are returned.
The format, type, tiling, usage, and flags
parameters correspond to parameters that would be consumed by
vkCreateImage (as members of VkImageCreateInfo).
If format is not a supported image format, or if the combination of
format, type, tiling, usage, and flags is not
supported for images, then vkGetPhysicalDeviceImageFormatProperties
returns VK_ERROR_FORMAT_NOT_SUPPORTED.
The limitations on an image format that are reported by
vkGetPhysicalDeviceImageFormatProperties have the following property:
if usage1 and usage2 of type VkImageUsageFlags are such that
the bits set in usage1 are a subset of the bits set in usage2, and
flags1 and flags2 of type VkImageCreateFlags are such that
the bits set in flags1 are a subset of the bits set in flags2,
then the limitations for usage1 and flags1 must be no more strict
than the limitations for usage2 and flags2, for all values of
format, type, and tiling.
The VkImageFormatProperties structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageFormatProperties {
VkExtent3D maxExtent;
uint32_t maxMipLevels;
uint32_t maxArrayLayers;
VkSampleCountFlags sampleCounts;
VkDeviceSize maxResourceSize;
} VkImageFormatProperties;
-
maxExtentare the maximum image dimensions. See the Allowed Extent Values section below for how these values are constrained bytype. -
maxMipLevelsis the maximum number of mipmap levels.maxMipLevelsmust be equal to the number of levels in the complete mipmap chain based on themaxExtent.width,maxExtent.height, andmaxExtent.depth, except when one of the following conditions is true, in which case it may instead be1:-
vkGetPhysicalDeviceImageFormatProperties::tilingwasVK_IMAGE_TILING_LINEAR -
VkPhysicalDeviceImageFormatInfo2::
tilingwasVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT -
the VkPhysicalDeviceImageFormatInfo2::
pNextchain included a VkPhysicalDeviceExternalImageFormatInfo structure with a handle type included in thehandleTypesmember for which mipmap image support is not required -
image
formatis one of the formats that require a sampler Y′CBCR conversion -
flagscontainsVK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
-
maxArrayLayersis the maximum number of array layers.maxArrayLayersmust be no less than VkPhysicalDeviceLimits::maxImageArrayLayers, except when one of the following conditions is true, in which case it may instead be1:-
tilingisVK_IMAGE_TILING_LINEAR -
tilingisVK_IMAGE_TILING_OPTIMALandtypeisVK_IMAGE_TYPE_3D -
formatis one of the formats that require a sampler Y′CBCR conversion
-
-
If
tilingisVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, thenmaxArrayLayersmust not be 0. -
sampleCountsis a bitmask of VkSampleCountFlagBits specifying all the supported sample counts for this image as described below. -
maxResourceSizeis an upper bound on the total image size in bytes, inclusive of all image subresources. Implementations may have an address space limit on total size of a resource, which is advertised by this property.maxResourceSizemust be at least 231.
|
Note
There is no mechanism to query the size of an image before creating it, to
compare that size against |
If the combination of parameters to
vkGetPhysicalDeviceImageFormatProperties is not supported by the
implementation for use in vkCreateImage, then all members of
VkImageFormatProperties will be filled with zero.
|
Note
Filling |
To determine the image capabilities compatible with an external memory handle type, call:
// Provided by VK_NV_external_memory_capabilities
VkResult vkGetPhysicalDeviceExternalImageFormatPropertiesNV(
VkPhysicalDevice physicalDevice,
VkFormat format,
VkImageType type,
VkImageTiling tiling,
VkImageUsageFlags usage,
VkImageCreateFlags flags,
VkExternalMemoryHandleTypeFlagsNV externalHandleType,
VkExternalImageFormatPropertiesNV* pExternalImageFormatProperties);
-
physicalDeviceis the physical device from which to query the image capabilities -
formatis the image format, corresponding to VkImageCreateInfo::format. -
typeis the image type, corresponding to VkImageCreateInfo::imageType. -
tilingis the image tiling, corresponding to VkImageCreateInfo::tiling. -
usageis the intended usage of the image, corresponding to VkImageCreateInfo::usage. -
flagsis a bitmask describing additional parameters of the image, corresponding to VkImageCreateInfo::flags. -
externalHandleTypeis either one of the bits from VkExternalMemoryHandleTypeFlagBitsNV, or 0. -
pExternalImageFormatPropertiesis a pointer to a VkExternalImageFormatPropertiesNV structure in which capabilities are returned.
If externalHandleType is 0,
pExternalImageFormatProperties->imageFormatProperties will return the
same values as a call to vkGetPhysicalDeviceImageFormatProperties, and
the other members of pExternalImageFormatProperties will all be 0.
Otherwise, they are filled in as described for
VkExternalImageFormatPropertiesNV.
The VkExternalImageFormatPropertiesNV structure is defined as:
// Provided by VK_NV_external_memory_capabilities
typedef struct VkExternalImageFormatPropertiesNV {
VkImageFormatProperties imageFormatProperties;
VkExternalMemoryFeatureFlagsNV externalMemoryFeatures;
VkExternalMemoryHandleTypeFlagsNV exportFromImportedHandleTypes;
VkExternalMemoryHandleTypeFlagsNV compatibleHandleTypes;
} VkExternalImageFormatPropertiesNV;
-
imageFormatPropertieswill be filled in as when calling vkGetPhysicalDeviceImageFormatProperties, but the values returned may vary depending on the external handle type requested. -
externalMemoryFeaturesis a bitmask of VkExternalMemoryFeatureFlagBitsNV, indicating properties of the external memory handle type (vkGetPhysicalDeviceExternalImageFormatPropertiesNV::externalHandleType) being queried, or 0 if the external memory handle type is 0. -
exportFromImportedHandleTypesis a bitmask of VkExternalMemoryHandleTypeFlagBitsNV containing a bit set for every external handle type that may be used to create memory from which the handles of the type specified in vkGetPhysicalDeviceExternalImageFormatPropertiesNV::externalHandleTypecan be exported, or 0 if the external memory handle type is 0. -
compatibleHandleTypesis a bitmask of VkExternalMemoryHandleTypeFlagBitsNV containing a bit set for every external handle type that may be specified simultaneously with the handle type specified by vkGetPhysicalDeviceExternalImageFormatPropertiesNV::externalHandleTypewhen calling vkAllocateMemory, or 0 if the external memory handle type is 0.compatibleHandleTypeswill always contain vkGetPhysicalDeviceExternalImageFormatPropertiesNV::externalHandleType
Bits which can be set in
VkExternalImageFormatPropertiesNV::externalMemoryFeatures,
indicating properties of the external memory handle type, are:
// Provided by VK_NV_external_memory_capabilities
typedef enum VkExternalMemoryFeatureFlagBitsNV {
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV = 0x00000001,
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_NV = 0x00000002,
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_NV = 0x00000004,
} VkExternalMemoryFeatureFlagBitsNV;
-
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NVspecifies that external memory of the specified type must be created as a dedicated allocation when used in the manner specified. -
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_NVspecifies that the implementation supports exporting handles of the specified type. -
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_NVspecifies that the implementation supports importing handles of the specified type.
// Provided by VK_NV_external_memory_capabilities
typedef VkFlags VkExternalMemoryFeatureFlagsNV;
VkExternalMemoryFeatureFlagsNV is a bitmask type for setting a mask of
zero or more VkExternalMemoryFeatureFlagBitsNV.
To query additional capabilities specific to image types, call:
// Provided by VK_VERSION_1_1
VkResult vkGetPhysicalDeviceImageFormatProperties2(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceImageFormatInfo2* pImageFormatInfo,
VkImageFormatProperties2* pImageFormatProperties);
or the equivalent command
// Provided by VK_KHR_get_physical_device_properties2
VkResult vkGetPhysicalDeviceImageFormatProperties2KHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceImageFormatInfo2* pImageFormatInfo,
VkImageFormatProperties2* pImageFormatProperties);
-
physicalDeviceis the physical device from which to query the image capabilities. -
pImageFormatInfois a pointer to a VkPhysicalDeviceImageFormatInfo2 structure describing the parameters that would be consumed by vkCreateImage. -
pImageFormatPropertiesis a pointer to a VkImageFormatProperties2 structure in which capabilities are returned.
vkGetPhysicalDeviceImageFormatProperties2 behaves similarly to
vkGetPhysicalDeviceImageFormatProperties, with the ability to return
extended information in a pNext chain of output structures.
If the pNext chain of pImageFormatInfo includes a
VkVideoProfilesKHR structure with a profileCount member greater
than 0, then vkGetPhysicalDeviceImageFormatProperties2 returns
format capabilities specific to image types used in conjunction with the
specified video codec operations and corresponding video profiles.
In this case vkGetPhysicalDeviceImageFormatProperties2 returns one of
the video-profile-specific error codes if any
of the profiles specified via VkVideoProfilesKHR::pProfiles are
not supported.
Furthermore, if VkPhysicalDeviceImageFormatInfo2::usage includes
any image usage flags not supported by the specified video profiles then
vkGetPhysicalDeviceImageFormatProperties2 returns
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
The VkPhysicalDeviceImageFormatInfo2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceImageFormatInfo2 {
VkStructureType sType;
const void* pNext;
VkFormat format;
VkImageType type;
VkImageTiling tiling;
VkImageUsageFlags usage;
VkImageCreateFlags flags;
} VkPhysicalDeviceImageFormatInfo2;
or the equivalent
// Provided by VK_KHR_get_physical_device_properties2
typedef VkPhysicalDeviceImageFormatInfo2 VkPhysicalDeviceImageFormatInfo2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. ThepNextchain ofVkPhysicalDeviceImageFormatInfo2is used to provide additional image parameters tovkGetPhysicalDeviceImageFormatProperties2. -
formatis a VkFormat value indicating the image format, corresponding to VkImageCreateInfo::format. -
typeis a VkImageType value indicating the image type, corresponding to VkImageCreateInfo::imageType. -
tilingis a VkImageTiling value indicating the image tiling, corresponding to VkImageCreateInfo::tiling. -
usageis a bitmask of VkImageUsageFlagBits indicating the intended usage of the image, corresponding to VkImageCreateInfo::usage. -
flagsis a bitmask of VkImageCreateFlagBits indicating additional parameters of the image, corresponding to VkImageCreateInfo::flags.
The members of VkPhysicalDeviceImageFormatInfo2 correspond to the
arguments to vkGetPhysicalDeviceImageFormatProperties, with
sType and pNext added for extensibility.
The VkImageFormatProperties2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImageFormatProperties2 {
VkStructureType sType;
void* pNext;
VkImageFormatProperties imageFormatProperties;
} VkImageFormatProperties2;
or the equivalent
// Provided by VK_KHR_get_physical_device_properties2
typedef VkImageFormatProperties2 VkImageFormatProperties2KHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. ThepNextchain ofVkImageFormatProperties2is used to allow the specification of additional capabilities to be returned fromvkGetPhysicalDeviceImageFormatProperties2. -
imageFormatPropertiesis a VkImageFormatProperties structure in which capabilities are returned.
If the combination of parameters to
vkGetPhysicalDeviceImageFormatProperties2 is not supported by the
implementation for use in vkCreateImage, then all members of
imageFormatProperties will be filled with zero.
|
Note
Filling |
To determine if texture gather functions that take explicit LOD and/or bias
argument values can be used with a given image format, add a
VkTextureLODGatherFormatPropertiesAMD structure to the pNext
chain of the VkImageFormatProperties2 structure in a call to
vkGetPhysicalDeviceImageFormatProperties2.
The VkTextureLODGatherFormatPropertiesAMD structure is defined as:
// Provided by VK_AMD_texture_gather_bias_lod
typedef struct VkTextureLODGatherFormatPropertiesAMD {
VkStructureType sType;
void* pNext;
VkBool32 supportsTextureGatherLODBiasAMD;
} VkTextureLODGatherFormatPropertiesAMD;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
supportsTextureGatherLODBiasAMDtells if the image format can be used with texture gather bias/LOD functions, as introduced by theVK_AMD_texture_gather_bias_lodextension. This field is set by the implementation. User-specified value is ignored.
To determine the image capabilities compatible with an external memory
handle type, add a VkPhysicalDeviceExternalImageFormatInfo structure
to the pNext chain of the VkPhysicalDeviceImageFormatInfo2
structure and a VkExternalImageFormatProperties structure to the
pNext chain of the VkImageFormatProperties2 structure.
The VkPhysicalDeviceExternalImageFormatInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalImageFormatInfo {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlagBits handleType;
} VkPhysicalDeviceExternalImageFormatInfo;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkPhysicalDeviceExternalImageFormatInfo VkPhysicalDeviceExternalImageFormatInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the memory handle type that will be used with the memory associated with the image.
If handleType is 0, vkGetPhysicalDeviceImageFormatProperties2
will behave as if VkPhysicalDeviceExternalImageFormatInfo was not
present, and VkExternalImageFormatProperties will be ignored.
If handleType is not compatible with the format, type,
tiling, usage, and flags specified in
VkPhysicalDeviceImageFormatInfo2, then
vkGetPhysicalDeviceImageFormatProperties2 returns
VK_ERROR_FORMAT_NOT_SUPPORTED.
Possible values of
VkPhysicalDeviceExternalImageFormatInfo::handleType, specifying
an external memory handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalMemoryHandleTypeFlagBits {
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT = 0x00000001,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT = 0x00000002,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT = 0x00000004,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT = 0x00000008,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT = 0x00000010,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT = 0x00000020,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT = 0x00000040,
// Provided by VK_EXT_external_memory_dma_buf
VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT = 0x00000200,
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID = 0x00000400,
// Provided by VK_EXT_external_memory_host
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT = 0x00000080,
// Provided by VK_EXT_external_memory_host
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT = 0x00000100,
// Provided by VK_FUCHSIA_external_memory
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA = 0x00000800,
// Provided by VK_NV_external_memory_rdma
VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV = 0x00001000,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT,
} VkExternalMemoryHandleTypeFlagBits;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryHandleTypeFlagBits VkExternalMemoryHandleTypeFlagBitsKHR;
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BITspecifies a POSIX file descriptor handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must be compatible with the POSIX system callsdup,dup2,close, and the non-standard system calldup3. Additionally, it must be transportable over a socket using anSCM_RIGHTScontrol message. It owns a reference to the underlying memory resource represented by its Vulkan memory object. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BITspecifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must be compatible with the functionsDuplicateHandle,CloseHandle,CompareObjectHandles,GetHandleInformation, andSetHandleInformation. It owns a reference to the underlying memory resource represented by its Vulkan memory object. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BITspecifies a global share handle that has only limited valid usage outside of Vulkan and other compatible APIs. It is not compatible with any native APIs. It does not own a reference to the underlying memory resource represented by its Vulkan memory object, and will therefore become invalid when all Vulkan memory objects associated with it are destroyed. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BITspecifies an NT handle returned byIDXGIResource1::CreateSharedHandlereferring to a Direct3D 10 or 11 texture resource. It owns a reference to the memory used by the Direct3D resource. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BITspecifies a global share handle returned byIDXGIResource::GetSharedHandlereferring to a Direct3D 10 or 11 texture resource. It does not own a reference to the underlying Direct3D resource, and will therefore become invalid when all Vulkan memory objects and Direct3D resources associated with it are destroyed. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BITspecifies an NT handle returned byID3D12Device::CreateSharedHandlereferring to a Direct3D 12 heap resource. It owns a reference to the resources used by the Direct3D heap. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BITspecifies an NT handle returned byID3D12Device::CreateSharedHandlereferring to a Direct3D 12 committed resource. It owns a reference to the memory used by the Direct3D resource. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXTspecifies a host pointer returned by a host memory allocation command. It does not own a reference to the underlying memory resource, and will therefore become invalid if the host memory is freed. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXTspecifies a host pointer to host mapped foreign memory. It does not own a reference to the underlying memory resource, and will therefore become invalid if the foreign memory is unmapped or otherwise becomes no longer available. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXTis a file descriptor for a Linux dma_buf. It owns a reference to the underlying memory resource represented by its Vulkan memory object. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROIDspecifies anAHardwareBufferobject defined by the Android NDK. See Android Hardware Buffers for more details of this handle type. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIAis a Zircon handle to a virtual memory object. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NVis a handle to an allocation accessible by remote devices. It owns a reference to the underlying memory resource represented by its Vulkan memory object.
Some external memory handle types can only be shared within the same underlying physical device and/or the same driver version, as defined in the following table:
Handle type |
|
|
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
Note
The above table does not restrict the drivers and devices with which
|
|
Note
Even though the above table does not restrict the drivers and devices with
which |
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalMemoryHandleTypeFlags;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryHandleTypeFlags VkExternalMemoryHandleTypeFlagsKHR;
VkExternalMemoryHandleTypeFlags is a bitmask type for setting a mask
of zero or more VkExternalMemoryHandleTypeFlagBits.
The VkExternalImageFormatProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalImageFormatProperties {
VkStructureType sType;
void* pNext;
VkExternalMemoryProperties externalMemoryProperties;
} VkExternalImageFormatProperties;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalImageFormatProperties VkExternalImageFormatPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalMemoryPropertiesis a VkExternalMemoryProperties structure specifying various capabilities of the external handle type when used with the specified image creation parameters.
The VkExternalMemoryProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryProperties {
VkExternalMemoryFeatureFlags externalMemoryFeatures;
VkExternalMemoryHandleTypeFlags exportFromImportedHandleTypes;
VkExternalMemoryHandleTypeFlags compatibleHandleTypes;
} VkExternalMemoryProperties;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryProperties VkExternalMemoryPropertiesKHR;
-
externalMemoryFeaturesis a bitmask of VkExternalMemoryFeatureFlagBits specifying the features ofhandleType. -
exportFromImportedHandleTypesis a bitmask of VkExternalMemoryHandleTypeFlagBits specifying which types of imported handlehandleTypecan be exported from. -
compatibleHandleTypesis a bitmask of VkExternalMemoryHandleTypeFlagBits specifying handle types which can be specified at the same time ashandleTypewhen creating an image compatible with external memory.
compatibleHandleTypes must include at least handleType.
Inclusion of a handle type in compatibleHandleTypes does not imply the
values returned in VkImageFormatProperties2 will be the same when
VkPhysicalDeviceExternalImageFormatInfo::handleType is set to
that type.
The application is responsible for querying the capabilities of all handle
types intended for concurrent use in a single image and intersecting them to
obtain the compatible set of capabilities.
Bits which may be set in
VkExternalMemoryProperties::externalMemoryFeatures, specifying
features of an external memory handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalMemoryFeatureFlagBits {
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT = 0x00000001,
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT = 0x00000002,
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT = 0x00000004,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_KHR = VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_KHR = VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_KHR = VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT,
} VkExternalMemoryFeatureFlagBits;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryFeatureFlagBits VkExternalMemoryFeatureFlagBitsKHR;
-
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BITspecifies that images or buffers created with the specified parameters and handle type must use the mechanisms defined by VkMemoryDedicatedRequirements and VkMemoryDedicatedAllocateInfo to create (or import) a dedicated allocation for the image or buffer. -
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BITspecifies that handles of this type can be exported from Vulkan memory objects. -
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BITspecifies that handles of this type can be imported as Vulkan memory objects.
Because their semantics in external APIs roughly align with that of an image
or buffer with a dedicated allocation in Vulkan, implementations are
required to report VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for
the following external handle types:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROIDfor images only
Implementations must not report
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for buffers with
external handle type
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.
Implementations must not report
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for images or buffers
with external handle type
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, or
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT.
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalMemoryFeatureFlags;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryFeatureFlags VkExternalMemoryFeatureFlagsKHR;
VkExternalMemoryFeatureFlags is a bitmask type for setting a mask of
zero or more VkExternalMemoryFeatureFlagBits.
To query the image capabilities that are compatible with a
Linux DRM format modifier, set
VkPhysicalDeviceImageFormatInfo2::tiling to
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and add a
VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure to the
pNext chain of VkPhysicalDeviceImageFormatInfo2.
The VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure is defined as:
// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkPhysicalDeviceImageDrmFormatModifierInfoEXT {
VkStructureType sType;
const void* pNext;
uint64_t drmFormatModifier;
VkSharingMode sharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
} VkPhysicalDeviceImageDrmFormatModifierInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifieris the image’s Linux DRM format modifier, corresponding to VkImageDrmFormatModifierExplicitCreateInfoEXT::modifieror to VkImageDrmFormatModifierListCreateInfoEXT::pModifiers. -
sharingModespecifies how the image will be accessed by multiple queue families. -
queueFamilyIndexCountis the number of entries in thepQueueFamilyIndicesarray. -
pQueueFamilyIndicesis a pointer to an array of queue families that will access the image. It is ignored ifsharingModeis notVK_SHARING_MODE_CONCURRENT.
If the drmFormatModifier is incompatible with the parameters specified
in VkPhysicalDeviceImageFormatInfo2 and its pNext chain, then
vkGetPhysicalDeviceImageFormatProperties2 returns
VK_ERROR_FORMAT_NOT_SUPPORTED.
The implementation must support the query of any drmFormatModifier,
including unknown and invalid modifier values.
To determine the number of combined image samplers required to support a
multi-planar format, add VkSamplerYcbcrConversionImageFormatProperties
to the pNext chain of the VkImageFormatProperties2 structure in
a call to vkGetPhysicalDeviceImageFormatProperties2.
The VkSamplerYcbcrConversionImageFormatProperties structure is defined
as:
// Provided by VK_VERSION_1_1
typedef struct VkSamplerYcbcrConversionImageFormatProperties {
VkStructureType sType;
void* pNext;
uint32_t combinedImageSamplerDescriptorCount;
} VkSamplerYcbcrConversionImageFormatProperties;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkSamplerYcbcrConversionImageFormatProperties VkSamplerYcbcrConversionImageFormatPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
combinedImageSamplerDescriptorCountis the number of combined image sampler descriptors that the implementation uses to access the format.
combinedImageSamplerDescriptorCount is a number between 1 and the
number of planes in the format.
A descriptor set layout binding with immutable Y′CBCR conversion samplers
will have a maximum combinedImageSamplerDescriptorCount which is the
maximum across all formats supported by its samplers of the
combinedImageSamplerDescriptorCount for each format.
Descriptor sets with that layout will internally use that maximum
combinedImageSamplerDescriptorCount descriptors for each descriptor in
the binding.
This expanded number of descriptors will be consumed from the descriptor
pool when a descriptor set is allocated, and counts towards the
maxDescriptorSetSamplers, maxDescriptorSetSampledImages,
maxPerStageDescriptorSamplers, and
maxPerStageDescriptorSampledImages limits.
|
Note
All descriptors in a binding use the same maximum
For example, consider a descriptor set layout binding with two descriptors
and immutable samplers for multi-planar formats that have
|
To obtain optimal Android hardware buffer usage flags for specific image
creation parameters, add a VkAndroidHardwareBufferUsageANDROID
structure to the pNext chain of a VkImageFormatProperties2
structure passed to vkGetPhysicalDeviceImageFormatProperties2.
This structure is defined as:
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
typedef struct VkAndroidHardwareBufferUsageANDROID {
VkStructureType sType;
void* pNext;
uint64_t androidHardwareBufferUsage;
} VkAndroidHardwareBufferUsageANDROID;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
androidHardwareBufferUsagereturns the Android hardware buffer usage flags.
The androidHardwareBufferUsage field must include Android hardware
buffer usage flags listed in the
AHardwareBuffer Usage
Equivalence table when the corresponding Vulkan image usage or image
creation flags are included in the usage or flags fields of
VkPhysicalDeviceImageFormatInfo2.
It must include at least one GPU usage flag
(AHARDWAREBUFFER_USAGE_GPU_*), even if none of the corresponding Vulkan
usages or flags are requested.
|
Note
Requiring at least one GPU usage flag ensures that Android hardware buffer memory will be allocated in a memory pool accessible to the Vulkan implementation, and that specializing the memory layout based on usage flags does not prevent it from being compatible with Vulkan. Implementations may avoid unnecessary restrictions caused by this requirement by using vendor usage flags to indicate that only the Vulkan uses indicated in VkImageFormatProperties2 are required. |
To determine if cubic filtering can be used with a given image format and a
given image view type add a
VkPhysicalDeviceImageViewImageFormatInfoEXT structure to the
pNext chain of the VkPhysicalDeviceImageFormatInfo2 structure,
and a VkFilterCubicImageViewImageFormatPropertiesEXT structure to the
pNext chain of the VkImageFormatProperties2 structure.
The VkPhysicalDeviceImageViewImageFormatInfoEXT structure is defined
as:
// Provided by VK_EXT_filter_cubic
typedef struct VkPhysicalDeviceImageViewImageFormatInfoEXT {
VkStructureType sType;
void* pNext;
VkImageViewType imageViewType;
} VkPhysicalDeviceImageViewImageFormatInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewTypeis a VkImageViewType value specifying the type of the image view.
The VkFilterCubicImageViewImageFormatPropertiesEXT structure is
defined as:
// Provided by VK_EXT_filter_cubic
typedef struct VkFilterCubicImageViewImageFormatPropertiesEXT {
VkStructureType sType;
void* pNext;
VkBool32 filterCubic;
VkBool32 filterCubicMinmax;
} VkFilterCubicImageViewImageFormatPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
filterCubictells if image format, image type and image view type can be used with cubic filtering. This field is set by the implementation. User-specified value is ignored. -
filterCubicMinmaxtells if image format, image type and image view type can be used with cubic filtering and minmax filtering. This field is set by the implementation. User-specified value is ignored.
44.1.1. Supported Sample Counts
vkGetPhysicalDeviceImageFormatProperties returns a bitmask of
VkSampleCountFlagBits in sampleCounts specifying the supported
sample counts for the image parameters.
sampleCounts will be set to VK_SAMPLE_COUNT_1_BIT if at least
one of the following conditions is true:
-
tilingisVK_IMAGE_TILING_LINEAR -
typeis notVK_IMAGE_TYPE_2D -
flagscontainsVK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT -
Neither the
VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BITflag nor theVK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BITflag inVkFormatProperties::optimalTilingFeaturesreturned by vkGetPhysicalDeviceFormatProperties is set -
VkPhysicalDeviceExternalImageFormatInfo::
handleTypeis an external handle type for which multisampled image support is not required. -
formatis one of the formats that require a sampler Y′CBCR conversion -
usagecontainsVK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
usagecontainsVK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
Otherwise, the bits set in sampleCounts will be the sample counts
supported for the specified values of usage and format.
For each bit set in usage, the supported sample counts relate to the
limits in VkPhysicalDeviceLimits as follows:
-
If
usageincludesVK_IMAGE_USAGE_COLOR_ATTACHMENT_BITandformatis a floating- or fixed-point color format, a superset ofVkPhysicalDeviceLimits::framebufferColorSampleCounts -
If
usageincludesVK_IMAGE_USAGE_COLOR_ATTACHMENT_BITandformatis an integer format, a superset ofVkPhysicalDeviceVulkan12Properties::framebufferIntegerColorSampleCounts -
If
usageincludesVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, andformatincludes a depth aspect, a superset ofVkPhysicalDeviceLimits::framebufferDepthSampleCounts -
If
usageincludesVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, andformatincludes a stencil aspect, a superset ofVkPhysicalDeviceLimits::framebufferStencilSampleCounts -
If
usageincludesVK_IMAGE_USAGE_SAMPLED_BIT, andformatincludes a color aspect, a superset ofVkPhysicalDeviceLimits::sampledImageColorSampleCounts -
If
usageincludesVK_IMAGE_USAGE_SAMPLED_BIT, andformatincludes a depth aspect, a superset ofVkPhysicalDeviceLimits::sampledImageDepthSampleCounts -
If
usageincludesVK_IMAGE_USAGE_SAMPLED_BIT, andformatis an integer format, a superset ofVkPhysicalDeviceLimits::sampledImageIntegerSampleCounts -
If
usageincludesVK_IMAGE_USAGE_STORAGE_BIT, a superset ofVkPhysicalDeviceLimits::storageImageSampleCounts
If multiple bits are set in usage, sampleCounts will be the
intersection of the per-usage values described above.
If none of the bits described above are set in usage, then there is no
corresponding limit in VkPhysicalDeviceLimits.
In this case, sampleCounts must include at least
VK_SAMPLE_COUNT_1_BIT.
44.1.2. Allowed Extent Values Based On Image Type
Implementations may support extent values larger than the required minimum/maximum values for certain types of images.
VkImageFormatProperties::maxExtent for each type is subject to
the constraints below.
|
Note
Implementations must support images with dimensions up to the required minimum/maximum values for all types of images. It follows that the query for additional capabilities must return extent values that are at least as large as the required values. |
For VK_IMAGE_TYPE_1D:
-
maxExtent.width≥ VkPhysicalDeviceLimits::maxImageDimension1D -
maxExtent.height= 1 -
maxExtent.depth= 1
For VK_IMAGE_TYPE_2D when flags does not contain
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT:
-
maxExtent.width≥ VkPhysicalDeviceLimits::maxImageDimension2D -
maxExtent.height≥ VkPhysicalDeviceLimits::maxImageDimension2D -
maxExtent.depth= 1
For VK_IMAGE_TYPE_2D when flags contains
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT:
-
maxExtent.width≥ VkPhysicalDeviceLimits::maxImageDimensionCube -
maxExtent.height≥ VkPhysicalDeviceLimits::maxImageDimensionCube -
maxExtent.depth= 1
For VK_IMAGE_TYPE_3D:
-
maxExtent.width≥ VkPhysicalDeviceLimits::maxImageDimension3D -
maxExtent.height≥ VkPhysicalDeviceLimits::maxImageDimension3D -
maxExtent.depth≥ VkPhysicalDeviceLimits::maxImageDimension3D
44.2. Additional Buffer Capabilities
To query the external handle types supported by buffers, call:
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceExternalBufferProperties(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalBufferInfo* pExternalBufferInfo,
VkExternalBufferProperties* pExternalBufferProperties);
or the equivalent command
// Provided by VK_KHR_external_memory_capabilities
void vkGetPhysicalDeviceExternalBufferPropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalBufferInfo* pExternalBufferInfo,
VkExternalBufferProperties* pExternalBufferProperties);
-
physicalDeviceis the physical device from which to query the buffer capabilities. -
pExternalBufferInfois a pointer to a VkPhysicalDeviceExternalBufferInfo structure describing the parameters that would be consumed by vkCreateBuffer. -
pExternalBufferPropertiesis a pointer to a VkExternalBufferProperties structure in which capabilities are returned.
The VkPhysicalDeviceExternalBufferInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalBufferInfo {
VkStructureType sType;
const void* pNext;
VkBufferCreateFlags flags;
VkBufferUsageFlags usage;
VkExternalMemoryHandleTypeFlagBits handleType;
} VkPhysicalDeviceExternalBufferInfo;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkPhysicalDeviceExternalBufferInfo VkPhysicalDeviceExternalBufferInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkBufferCreateFlagBits describing additional parameters of the buffer, corresponding to VkBufferCreateInfo::flags. -
usageis a bitmask of VkBufferUsageFlagBits describing the intended usage of the buffer, corresponding to VkBufferCreateInfo::usage. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the memory handle type that will be used with the memory associated with the buffer.
The VkExternalBufferProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalBufferProperties {
VkStructureType sType;
void* pNext;
VkExternalMemoryProperties externalMemoryProperties;
} VkExternalBufferProperties;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalBufferProperties VkExternalBufferPropertiesKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalMemoryPropertiesis a VkExternalMemoryProperties structure specifying various capabilities of the external handle type when used with the specified buffer creation parameters.
44.3. Optional Semaphore Capabilities
Semaphores may support import and export of their payload to external handles. To query the external handle types supported by semaphores, call:
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceExternalSemaphoreProperties(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalSemaphoreInfo* pExternalSemaphoreInfo,
VkExternalSemaphoreProperties* pExternalSemaphoreProperties);
or the equivalent command
// Provided by VK_KHR_external_semaphore_capabilities
void vkGetPhysicalDeviceExternalSemaphorePropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalSemaphoreInfo* pExternalSemaphoreInfo,
VkExternalSemaphoreProperties* pExternalSemaphoreProperties);
-
physicalDeviceis the physical device from which to query the semaphore capabilities. -
pExternalSemaphoreInfois a pointer to a VkPhysicalDeviceExternalSemaphoreInfo structure describing the parameters that would be consumed by vkCreateSemaphore. -
pExternalSemaphorePropertiesis a pointer to a VkExternalSemaphoreProperties structure in which capabilities are returned.
The VkPhysicalDeviceExternalSemaphoreInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalSemaphoreInfo {
VkStructureType sType;
const void* pNext;
VkExternalSemaphoreHandleTypeFlagBits handleType;
} VkPhysicalDeviceExternalSemaphoreInfo;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkPhysicalDeviceExternalSemaphoreInfo VkPhysicalDeviceExternalSemaphoreInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalSemaphoreHandleTypeFlagBits value specifying the external semaphore handle type for which capabilities will be returned.
Bits which may be set in
VkPhysicalDeviceExternalSemaphoreInfo::handleType, specifying an
external semaphore handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalSemaphoreHandleTypeFlagBits {
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT = 0x00000001,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT = 0x00000002,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT = 0x00000004,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT = 0x00000008,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT = 0x00000010,
// Provided by VK_FUCHSIA_external_semaphore
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA = 0x00000080,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE_BIT = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT,
} VkExternalSemaphoreHandleTypeFlagBits;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreHandleTypeFlagBits VkExternalSemaphoreHandleTypeFlagBitsKHR;
-
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BITspecifies a POSIX file descriptor handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must be compatible with the POSIX system callsdup,dup2,close, and the non-standard system calldup3. Additionally, it must be transportable over a socket using anSCM_RIGHTScontrol message. It owns a reference to the underlying synchronization primitive represented by its Vulkan semaphore object. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BITspecifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must be compatible with the functionsDuplicateHandle,CloseHandle,CompareObjectHandles,GetHandleInformation, andSetHandleInformation. It owns a reference to the underlying synchronization primitive represented by its Vulkan semaphore object. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BITspecifies a global share handle that has only limited valid usage outside of Vulkan and other compatible APIs. It is not compatible with any native APIs. It does not own a reference to the underlying synchronization primitive represented by its Vulkan semaphore object, and will therefore become invalid when all Vulkan semaphore objects associated with it are destroyed. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BITspecifies an NT handle returned byID3D12Device::CreateSharedHandlereferring to a Direct3D 12 fence, orID3D11Device5::CreateFencereferring to a Direct3D 11 fence. It owns a reference to the underlying synchronization primitive associated with the Direct3D fence. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE_BITis an alias ofVK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BITwith the same meaning. It is provided for convenience and code clarity when interacting with D3D11 fences. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BITspecifies a POSIX file descriptor handle to a Linux Sync File or Android Fence object. It can be used with any native API accepting a valid sync file or fence as input. It owns a reference to the underlying synchronization primitive associated with the file descriptor. Implementations which support importing this handle type must accept any type of sync or fence FD supported by the native system they are running on. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIAspecifies a handle to a Zircon event object. It can be used with any native API that accepts a Zircon event handle. Zircon event handles are created withZX_RIGHTS_BASICandZX_RIGHTS_SIGNALrights. Vulkan on Fuchsia uses only the ZX_EVENT_SIGNALED bit when signaling or waiting.
|
Note
Handles of type |
Some external semaphore handle types can only be shared within the same underlying physical device and/or the same driver version, as defined in the following table:
Handle type |
|
|
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalSemaphoreHandleTypeFlags;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreHandleTypeFlags VkExternalSemaphoreHandleTypeFlagsKHR;
VkExternalSemaphoreHandleTypeFlags is a bitmask type for setting a
mask of zero or more VkExternalSemaphoreHandleTypeFlagBits.
The VkExternalSemaphoreProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalSemaphoreProperties {
VkStructureType sType;
void* pNext;
VkExternalSemaphoreHandleTypeFlags exportFromImportedHandleTypes;
VkExternalSemaphoreHandleTypeFlags compatibleHandleTypes;
VkExternalSemaphoreFeatureFlags externalSemaphoreFeatures;
} VkExternalSemaphoreProperties;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreProperties VkExternalSemaphorePropertiesKHR;
-
sTypeis the type of this structure -
pNextisNULLor a pointer to a structure extending this structure. -
exportFromImportedHandleTypesis a bitmask of VkExternalSemaphoreHandleTypeFlagBits specifying which types of imported handlehandleTypecan be exported from. -
compatibleHandleTypesis a bitmask of VkExternalSemaphoreHandleTypeFlagBits specifying handle types which can be specified at the same time ashandleTypewhen creating a semaphore. -
externalSemaphoreFeaturesis a bitmask of VkExternalSemaphoreFeatureFlagBits describing the features ofhandleType.
If handleType is not supported by the implementation, then
VkExternalSemaphoreProperties::externalSemaphoreFeatures will be
set to zero.
Bits which may be set in
VkExternalSemaphoreProperties::externalSemaphoreFeatures,
specifying the features of an external semaphore handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalSemaphoreFeatureFlagBits {
VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT = 0x00000001,
VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT = 0x00000002,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT_KHR = VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT_KHR = VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT,
} VkExternalSemaphoreFeatureFlagBits;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreFeatureFlagBits VkExternalSemaphoreFeatureFlagBitsKHR;
-
VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BITspecifies that handles of this type can be exported from Vulkan semaphore objects. -
VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BITspecifies that handles of this type can be imported as Vulkan semaphore objects.
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalSemaphoreFeatureFlags;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreFeatureFlags VkExternalSemaphoreFeatureFlagsKHR;
VkExternalSemaphoreFeatureFlags is a bitmask type for setting a mask
of zero or more VkExternalSemaphoreFeatureFlagBits.
44.4. Optional Fence Capabilities
Fences may support import and export of their payload to external handles. To query the external handle types supported by fences, call:
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceExternalFenceProperties(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalFenceInfo* pExternalFenceInfo,
VkExternalFenceProperties* pExternalFenceProperties);
or the equivalent command
// Provided by VK_KHR_external_fence_capabilities
void vkGetPhysicalDeviceExternalFencePropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalFenceInfo* pExternalFenceInfo,
VkExternalFenceProperties* pExternalFenceProperties);
-
physicalDeviceis the physical device from which to query the fence capabilities. -
pExternalFenceInfois a pointer to a VkPhysicalDeviceExternalFenceInfo structure describing the parameters that would be consumed by vkCreateFence. -
pExternalFencePropertiesis a pointer to a VkExternalFenceProperties structure in which capabilities are returned.
The VkPhysicalDeviceExternalFenceInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalFenceInfo {
VkStructureType sType;
const void* pNext;
VkExternalFenceHandleTypeFlagBits handleType;
} VkPhysicalDeviceExternalFenceInfo;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkPhysicalDeviceExternalFenceInfo VkPhysicalDeviceExternalFenceInfoKHR;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalFenceHandleTypeFlagBits value specifying an external fence handle type for which capabilities will be returned.
|
Note
Handles of type |
Bits which may be set in
-
VkPhysicalDeviceExternalFenceInfo::
handleType -
VkExternalFenceProperties::
exportFromImportedHandleTypes -
VkExternalFenceProperties::
compatibleHandleTypes
indicate external fence handle types, and are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalFenceHandleTypeFlagBits {
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT = 0x00000001,
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT = 0x00000002,
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT = 0x00000004,
VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT = 0x00000008,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT_KHR = VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR = VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR = VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT_KHR = VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT,
} VkExternalFenceHandleTypeFlagBits;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceHandleTypeFlagBits VkExternalFenceHandleTypeFlagBitsKHR;
-
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BITspecifies a POSIX file descriptor handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must be compatible with the POSIX system callsdup,dup2,close, and the non-standard system calldup3. Additionally, it must be transportable over a socket using anSCM_RIGHTScontrol message. It owns a reference to the underlying synchronization primitive represented by its Vulkan fence object. -
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BITspecifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must be compatible with the functionsDuplicateHandle,CloseHandle,CompareObjectHandles,GetHandleInformation, andSetHandleInformation. It owns a reference to the underlying synchronization primitive represented by its Vulkan fence object. -
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BITspecifies a global share handle that has only limited valid usage outside of Vulkan and other compatible APIs. It is not compatible with any native APIs. It does not own a reference to the underlying synchronization primitive represented by its Vulkan fence object, and will therefore become invalid when all Vulkan fence objects associated with it are destroyed. -
VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BITspecifies a POSIX file descriptor handle to a Linux Sync File or Android Fence. It can be used with any native API accepting a valid sync file or fence as input. It owns a reference to the underlying synchronization primitive associated with the file descriptor. Implementations which support importing this handle type must accept any type of sync or fence FD supported by the native system they are running on.
Some external fence handle types can only be shared within the same underlying physical device and/or the same driver version, as defined in the following table:
Handle type |
|
|
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
No restriction |
No restriction |
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalFenceHandleTypeFlags;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceHandleTypeFlags VkExternalFenceHandleTypeFlagsKHR;
VkExternalFenceHandleTypeFlags is a bitmask type for setting a mask of
zero or more VkExternalFenceHandleTypeFlagBits.
The VkExternalFenceProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalFenceProperties {
VkStructureType sType;
void* pNext;
VkExternalFenceHandleTypeFlags exportFromImportedHandleTypes;
VkExternalFenceHandleTypeFlags compatibleHandleTypes;
VkExternalFenceFeatureFlags externalFenceFeatures;
} VkExternalFenceProperties;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceProperties VkExternalFencePropertiesKHR;
-
exportFromImportedHandleTypesis a bitmask of VkExternalFenceHandleTypeFlagBits indicating which types of imported handlehandleTypecan be exported from. -
compatibleHandleTypesis a bitmask of VkExternalFenceHandleTypeFlagBits specifying handle types which can be specified at the same time ashandleTypewhen creating a fence. -
externalFenceFeaturesis a bitmask of VkExternalFenceFeatureFlagBits indicating the features ofhandleType.
If handleType is not supported by the implementation, then
VkExternalFenceProperties::externalFenceFeatures will be set to
zero.
Bits which may be set in
VkExternalFenceProperties::externalFenceFeatures, indicating
features of a fence external handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalFenceFeatureFlagBits {
VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT = 0x00000001,
VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT = 0x00000002,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT_KHR = VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT_KHR = VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT,
} VkExternalFenceFeatureFlagBits;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceFeatureFlagBits VkExternalFenceFeatureFlagBitsKHR;
-
VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BITspecifies handles of this type can be exported from Vulkan fence objects. -
VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BITspecifies handles of this type can be imported to Vulkan fence objects.
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalFenceFeatureFlags;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceFeatureFlags VkExternalFenceFeatureFlagsKHR;
VkExternalFenceFeatureFlags is a bitmask type for setting a mask of
zero or more VkExternalFenceFeatureFlagBits.
44.5. Timestamp Calibration Capabilities
To query the set of time domains for which a physical device supports timestamp calibration, call:
// Provided by VK_EXT_calibrated_timestamps
VkResult vkGetPhysicalDeviceCalibrateableTimeDomainsEXT(
VkPhysicalDevice physicalDevice,
uint32_t* pTimeDomainCount,
VkTimeDomainEXT* pTimeDomains);
-
physicalDeviceis the physical device from which to query the set of calibrateable time domains. -
pTimeDomainCountis a pointer to an integer related to the number of calibrateable time domains available or queried, as described below. -
pTimeDomainsis eitherNULLor a pointer to an array of VkTimeDomainEXT values, indicating the supported calibrateable time domains.
If pTimeDomains is NULL, then the number of calibrateable time
domains supported for the given physicalDevice is returned in
pTimeDomainCount.
Otherwise, pTimeDomainCount must point to a variable set by the user
to the number of elements in the pTimeDomains array, and on return the
variable is overwritten with the number of values actually written to
pTimeDomains.
If the value of pTimeDomainCount is less than the number of
calibrateable time domains supported, at most pTimeDomainCount values
will be written to pTimeDomains, and VK_INCOMPLETE will be
returned instead of VK_SUCCESS, to indicate that not all the available
time domains were returned.
45. Debugging
To aid developers in tracking down errors in the application’s use of Vulkan, particularly in combination with an external debugger or profiler, debugging extensions may be available.
The VkObjectType enumeration defines values, each of which corresponds to a specific Vulkan handle type. These values can be used to associate debug information with a particular type of object through one or more extensions.
// Provided by VK_VERSION_1_0
typedef enum VkObjectType {
VK_OBJECT_TYPE_UNKNOWN = 0,
VK_OBJECT_TYPE_INSTANCE = 1,
VK_OBJECT_TYPE_PHYSICAL_DEVICE = 2,
VK_OBJECT_TYPE_DEVICE = 3,
VK_OBJECT_TYPE_QUEUE = 4,
VK_OBJECT_TYPE_SEMAPHORE = 5,
VK_OBJECT_TYPE_COMMAND_BUFFER = 6,
VK_OBJECT_TYPE_FENCE = 7,
VK_OBJECT_TYPE_DEVICE_MEMORY = 8,
VK_OBJECT_TYPE_BUFFER = 9,
VK_OBJECT_TYPE_IMAGE = 10,
VK_OBJECT_TYPE_EVENT = 11,
VK_OBJECT_TYPE_QUERY_POOL = 12,
VK_OBJECT_TYPE_BUFFER_VIEW = 13,
VK_OBJECT_TYPE_IMAGE_VIEW = 14,
VK_OBJECT_TYPE_SHADER_MODULE = 15,
VK_OBJECT_TYPE_PIPELINE_CACHE = 16,
VK_OBJECT_TYPE_PIPELINE_LAYOUT = 17,
VK_OBJECT_TYPE_RENDER_PASS = 18,
VK_OBJECT_TYPE_PIPELINE = 19,
VK_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT = 20,
VK_OBJECT_TYPE_SAMPLER = 21,
VK_OBJECT_TYPE_DESCRIPTOR_POOL = 22,
VK_OBJECT_TYPE_DESCRIPTOR_SET = 23,
VK_OBJECT_TYPE_FRAMEBUFFER = 24,
VK_OBJECT_TYPE_COMMAND_POOL = 25,
// Provided by VK_VERSION_1_1
VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION = 1000156000,
// Provided by VK_VERSION_1_1
VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE = 1000085000,
// Provided by VK_VERSION_1_3
VK_OBJECT_TYPE_PRIVATE_DATA_SLOT = 1000295000,
// Provided by VK_KHR_surface
VK_OBJECT_TYPE_SURFACE_KHR = 1000000000,
// Provided by VK_KHR_swapchain
VK_OBJECT_TYPE_SWAPCHAIN_KHR = 1000001000,
// Provided by VK_KHR_display
VK_OBJECT_TYPE_DISPLAY_KHR = 1000002000,
// Provided by VK_KHR_display
VK_OBJECT_TYPE_DISPLAY_MODE_KHR = 1000002001,
// Provided by VK_EXT_debug_report
VK_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT = 1000011000,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_OBJECT_TYPE_VIDEO_SESSION_KHR = 1000023000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_video_queue
VK_OBJECT_TYPE_VIDEO_SESSION_PARAMETERS_KHR = 1000023001,
#endif
// Provided by VK_NVX_binary_import
VK_OBJECT_TYPE_CU_MODULE_NVX = 1000029000,
// Provided by VK_NVX_binary_import
VK_OBJECT_TYPE_CU_FUNCTION_NVX = 1000029001,
// Provided by VK_EXT_debug_utils
VK_OBJECT_TYPE_DEBUG_UTILS_MESSENGER_EXT = 1000128000,
// Provided by VK_KHR_acceleration_structure
VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR = 1000150000,
// Provided by VK_EXT_validation_cache
VK_OBJECT_TYPE_VALIDATION_CACHE_EXT = 1000160000,
// Provided by VK_NV_ray_tracing
VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV = 1000165000,
// Provided by VK_INTEL_performance_query
VK_OBJECT_TYPE_PERFORMANCE_CONFIGURATION_INTEL = 1000210000,
// Provided by VK_KHR_deferred_host_operations
VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR = 1000268000,
// Provided by VK_NV_device_generated_commands
VK_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NV = 1000277000,
// Provided by VK_FUCHSIA_buffer_collection
VK_OBJECT_TYPE_BUFFER_COLLECTION_FUCHSIA = 1000366000,
// Provided by VK_KHR_descriptor_update_template
VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR = VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_KHR = VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION,
// Provided by VK_EXT_private_data
VK_OBJECT_TYPE_PRIVATE_DATA_SLOT_EXT = VK_OBJECT_TYPE_PRIVATE_DATA_SLOT,
} VkObjectType;
| VkObjectType | Vulkan Handle Type |
|---|---|
|
Unknown/Undefined Handle |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If this Specification was generated with any such extensions included, they will be described in the remainder of this chapter.
45.1. Debug Utilities
Vulkan provides flexible debugging utilities for debugging an application.
The Object Debug Annotation section describes how to associate either a name or binary data with a specific Vulkan object.
The Queue Labels section describes how to annotate and group the work submitted to a queue.
The Command Buffer Labels section describes how to associate logical elements of the scene with commands in a VkCommandBuffer.
The Debug Messengers section describes how to create debug messenger objects associated with an application supplied callback to capture debug messages from a variety of Vulkan components.
45.1.1. Object Debug Annotation
It can be useful for an application to provide its own content relative to a specific Vulkan object. The following commands allow application developers to associate user-defined information with Vulkan objects.
Object Naming
An object can be provided a user-defined name by calling
vkSetDebugUtilsObjectNameEXT as defined below.
// Provided by VK_EXT_debug_utils
VkResult vkSetDebugUtilsObjectNameEXT(
VkDevice device,
const VkDebugUtilsObjectNameInfoEXT* pNameInfo);
-
deviceis the device that created the object. -
pNameInfois a pointer to a VkDebugUtilsObjectNameInfoEXT structure specifying parameters of the name to set on the object.
The VkDebugUtilsObjectNameInfoEXT structure is defined as:
// Provided by VK_EXT_debug_utils
typedef struct VkDebugUtilsObjectNameInfoEXT {
VkStructureType sType;
const void* pNext;
VkObjectType objectType;
uint64_t objectHandle;
const char* pObjectName;
} VkDebugUtilsObjectNameInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
objectTypeis a VkObjectType specifying the type of the object to be named. -
objectHandleis the object to be named. -
pObjectNameis eitherNULLor a null-terminated UTF-8 string specifying the name to apply toobjectHandle.
Applications may change the name associated with an object simply by
calling vkSetDebugUtilsObjectNameEXT again with a new string.
If pObjectName is either NULL or an empty string, then any
previously set name is removed.
The graphicsPipelineLibrary
feature allows the specification of pipelines without the creation of
VkShaderModule objects beforehand.
In order to continue to allow naming these shaders independently,
VkDebugUtilsObjectNameInfoEXT can be included in the pNext
chain of VkPipelineShaderStageCreateInfo, which associates a static
name with that particular shader.
Object Data Association
In addition to setting a name for an object, debugging and validation layers may have uses for additional binary data on a per-object basis that have no other place in the Vulkan API.
For example, a VkShaderModule could have additional debugging data
attached to it to aid in offline shader tracing.
Additional data can be attached to an object by calling
vkSetDebugUtilsObjectTagEXT as defined below.
// Provided by VK_EXT_debug_utils
VkResult vkSetDebugUtilsObjectTagEXT(
VkDevice device,
const VkDebugUtilsObjectTagInfoEXT* pTagInfo);
-
deviceis the device that created the object. -
pTagInfois a pointer to a VkDebugUtilsObjectTagInfoEXT structure specifying parameters of the tag to attach to the object.
The VkDebugUtilsObjectTagInfoEXT structure is defined as:
// Provided by VK_EXT_debug_utils
typedef struct VkDebugUtilsObjectTagInfoEXT {
VkStructureType sType;
const void* pNext;
VkObjectType objectType;
uint64_t objectHandle;
uint64_t tagName;
size_t tagSize;
const void* pTag;
} VkDebugUtilsObjectTagInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
objectTypeis a VkObjectType specifying the type of the object to be named. -
objectHandleis the object to be tagged. -
tagNameis a numerical identifier of the tag. -
tagSizeis the number of bytes of data to attach to the object. -
pTagis a pointer to an array oftagSizebytes containing the data to be associated with the object.
The tagName parameter gives a name or identifier to the type of data
being tagged.
This can be used by debugging layers to easily filter for only data that can
be used by that implementation.
45.1.2. Queue Labels
All Vulkan work must be submitted using queues. It is possible for an application to use multiple queues, each containing multiple command buffers, when performing work. It can be useful to identify which queue, or even where in a queue, something has occurred.
To begin identifying a region using a debug label inside a queue, you may use the vkQueueBeginDebugUtilsLabelEXT command.
Then, when the region of interest has passed, you may end the label region using vkQueueEndDebugUtilsLabelEXT.
Additionally, a single debug label may be inserted at any time using vkQueueInsertDebugUtilsLabelEXT.
A queue debug label region is opened by calling:
// Provided by VK_EXT_debug_utils
void vkQueueBeginDebugUtilsLabelEXT(
VkQueue queue,
const VkDebugUtilsLabelEXT* pLabelInfo);
-
queueis the queue in which to start a debug label region. -
pLabelInfois a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label region to open.
The VkDebugUtilsLabelEXT structure is defined as:
// Provided by VK_EXT_debug_utils
typedef struct VkDebugUtilsLabelEXT {
VkStructureType sType;
const void* pNext;
const char* pLabelName;
float color[4];
} VkDebugUtilsLabelEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pLabelNameis a pointer to a null-terminated UTF-8 string containing the name of the label. -
coloris an optional RGBA color value that can be associated with the label. A particular implementation may choose to ignore this color value. The values contain RGBA values in order, in the range 0.0 to 1.0. If all elements incolorare set to 0.0 then it is ignored.
A queue debug label region is closed by calling:
// Provided by VK_EXT_debug_utils
void vkQueueEndDebugUtilsLabelEXT(
VkQueue queue);
-
queueis the queue in which a debug label region should be closed.
The calls to vkQueueBeginDebugUtilsLabelEXT and vkQueueEndDebugUtilsLabelEXT must be matched and balanced.
A single label can be inserted into a queue by calling:
// Provided by VK_EXT_debug_utils
void vkQueueInsertDebugUtilsLabelEXT(
VkQueue queue,
const VkDebugUtilsLabelEXT* pLabelInfo);
-
queueis the queue into which a debug label will be inserted. -
pLabelInfois a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label to insert.
45.1.3. Command Buffer Labels
Typical Vulkan applications will submit many command buffers in each frame, with each command buffer containing a large number of individual commands. Being able to logically annotate regions of command buffers that belong together as well as hierarchically subdivide the frame is important to a developer’s ability to navigate the commands viewed holistically.
To identify the beginning of a debug label region in a command buffer, vkCmdBeginDebugUtilsLabelEXT can be used as defined below.
To indicate the end of a debug label region in a command buffer, vkCmdEndDebugUtilsLabelEXT can be used.
To insert a single command buffer debug label inside of a command buffer, vkCmdInsertDebugUtilsLabelEXT can be used as defined below.
A command buffer debug label region can be opened by calling:
// Provided by VK_EXT_debug_utils
void vkCmdBeginDebugUtilsLabelEXT(
VkCommandBuffer commandBuffer,
const VkDebugUtilsLabelEXT* pLabelInfo);
-
commandBufferis the command buffer into which the command is recorded. -
pLabelInfois a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label region to open.
A command buffer label region can be closed by calling:
// Provided by VK_EXT_debug_utils
void vkCmdEndDebugUtilsLabelEXT(
VkCommandBuffer commandBuffer);
-
commandBufferis the command buffer into which the command is recorded.
An application may open a debug label region in one command buffer and close it in another, or otherwise split debug label regions across multiple command buffers or multiple queue submissions. When viewed from the linear series of submissions to a single queue, the calls to vkCmdBeginDebugUtilsLabelEXT and vkCmdEndDebugUtilsLabelEXT must be matched and balanced.
There can be problems reporting command buffer debug labels during the recording process because command buffers may be recorded out of sequence with the resulting execution order. Since the recording order may be different, a solitary command buffer may have an inconsistent view of the debug label regions by itself. Therefore, if an issue occurs during the recording of a command buffer, and the environment requires returning debug labels, the implementation may return only those labels it is aware of. This is true even if the implementation is aware of only the debug labels within the command buffer being actively recorded.
A single debug label can be inserted into a command buffer by calling:
// Provided by VK_EXT_debug_utils
void vkCmdInsertDebugUtilsLabelEXT(
VkCommandBuffer commandBuffer,
const VkDebugUtilsLabelEXT* pLabelInfo);
-
commandBufferis the command buffer into which the command is recorded. -
pInfois a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label to insert.
45.1.4. Debug Messengers
Vulkan allows an application to register multiple callbacks with any Vulkan component wishing to report debug information. Some callbacks may log the information to a file, others may cause a debug break point or other application defined behavior. A primary producer of callback messages are the validation layers. An application can register callbacks even when no validation layers are enabled, but they will only be called for the Vulkan loader and, if implemented, other layer and driver events.
A VkDebugUtilsMessengerEXT is a messenger object which handles passing
along debug messages to a provided debug callback.
// Provided by VK_EXT_debug_utils
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDebugUtilsMessengerEXT)
The debug messenger will provide detailed feedback on the application’s use of Vulkan when events of interest occur. When an event of interest does occur, the debug messenger will submit a debug message to the debug callback that was provided during its creation. Additionally, the debug messenger is responsible with filtering out debug messages that the callback is not interested in and will only provide desired debug messages.
A debug messenger triggers a debug callback with a debug message when an event of interest occurs. To create a debug messenger which will trigger a debug callback, call:
// Provided by VK_EXT_debug_utils
VkResult vkCreateDebugUtilsMessengerEXT(
VkInstance instance,
const VkDebugUtilsMessengerCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDebugUtilsMessengerEXT* pMessenger);
-
instanceis the instance the messenger will be used with. -
pCreateInfois a pointer to a VkDebugUtilsMessengerCreateInfoEXT structure containing the callback pointer, as well as defining conditions under which this messenger will trigger the callback. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pMessengeris a pointer to a VkDebugUtilsMessengerEXT handle in which the created object is returned.
The application must ensure that vkCreateDebugUtilsMessengerEXT is
not executed in parallel with any Vulkan command that is also called with
instance or child of instance as the dispatchable argument.
The definition of VkDebugUtilsMessengerCreateInfoEXT is:
// Provided by VK_EXT_debug_utils
typedef struct VkDebugUtilsMessengerCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkDebugUtilsMessengerCreateFlagsEXT flags;
VkDebugUtilsMessageSeverityFlagsEXT messageSeverity;
VkDebugUtilsMessageTypeFlagsEXT messageType;
PFN_vkDebugUtilsMessengerCallbackEXT pfnUserCallback;
void* pUserData;
} VkDebugUtilsMessengerCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis0and is reserved for future use. -
messageSeverityis a bitmask of VkDebugUtilsMessageSeverityFlagBitsEXT specifying which severity of event(s) will cause this callback to be called. -
messageTypeis a bitmask of VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of event(s) will cause this callback to be called. -
pfnUserCallbackis the application callback function to call. -
pUserDatais user data to be passed to the callback.
For each VkDebugUtilsMessengerEXT that is created the
VkDebugUtilsMessengerCreateInfoEXT::messageSeverity and
VkDebugUtilsMessengerCreateInfoEXT::messageType determine when
that VkDebugUtilsMessengerCreateInfoEXT::pfnUserCallback is
called.
The process to determine if the user’s pfnUserCallback is triggered
when an event occurs is as follows:
-
The implementation will perform a bitwise AND of the event’s VkDebugUtilsMessageSeverityFlagBitsEXT with the
messageSeverityprovided during creation of the VkDebugUtilsMessengerEXT object.-
If the value is 0, the message is skipped.
-
-
The implementation will perform bitwise AND of the event’s VkDebugUtilsMessageTypeFlagBitsEXT with the
messageTypeprovided during the creation of the VkDebugUtilsMessengerEXT object.-
If the value is 0, the message is skipped.
-
-
The callback will trigger a debug message for the current event
The callback will come directly from the component that detected the event, unless some other layer intercepts the calls for its own purposes (filter them in a different way, log to a system error log, etc.).
An application can receive multiple callbacks if multiple
VkDebugUtilsMessengerEXT objects are created.
A callback will always be executed in the same thread as the originating
Vulkan call.
A callback can be called from multiple threads simultaneously (if the application is making Vulkan calls from multiple threads).
// Provided by VK_EXT_debug_utils
typedef VkFlags VkDebugUtilsMessengerCreateFlagsEXT;
VkDebugUtilsMessengerCreateFlagsEXT is a bitmask type for setting a
mask, but is currently reserved for future use.
Bits which can be set in
VkDebugUtilsMessengerCreateInfoEXT::messageSeverity, specifying
event severities which cause a debug messenger to call the callback, are:
// Provided by VK_EXT_debug_utils
typedef enum VkDebugUtilsMessageSeverityFlagBitsEXT {
VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT = 0x00000001,
VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT = 0x00000010,
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT = 0x00000100,
VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT = 0x00001000,
} VkDebugUtilsMessageSeverityFlagBitsEXT;
-
VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXTspecifies the most verbose output indicating all diagnostic messages from the Vulkan loader, layers, and drivers should be captured. -
VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXTspecifies an informational message such as resource details that may be handy when debugging an application. -
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXTspecifies use of Vulkan that may expose an app bug. Such cases may not be immediately harmful, such as a fragment shader outputting to a location with no attachment. Other cases may point to behavior that is almost certainly bad when unintended such as using an image whose memory has not been filled. In general if you see a warning but you know that the behavior is intended/desired, then simply ignore the warning. -
VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXTspecifies that the application has violated a valid usage condition of the specification.
|
Note
The values of VkDebugUtilsMessageSeverityFlagBitsEXT are sorted based on severity. The higher the flag value, the more severe the message. This allows for simple boolean operation comparisons when looking at VkDebugUtilsMessageSeverityFlagBitsEXT values. For example:
In addition, space has been left between the enums to allow for later addition of new severities in between the existing values. |
// Provided by VK_EXT_debug_utils
typedef VkFlags VkDebugUtilsMessageSeverityFlagsEXT;
VkDebugUtilsMessageSeverityFlagsEXT is a bitmask type for setting a
mask of zero or more VkDebugUtilsMessageSeverityFlagBitsEXT.
Bits which can be set in
VkDebugUtilsMessengerCreateInfoEXT::messageType, specifying
event types which cause a debug messenger to call the callback, are:
// Provided by VK_EXT_debug_utils
typedef enum VkDebugUtilsMessageTypeFlagBitsEXT {
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT = 0x00000001,
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT = 0x00000002,
VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT = 0x00000004,
} VkDebugUtilsMessageTypeFlagBitsEXT;
-
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXTspecifies that some general event has occurred. This is typically a non-specification, non-performance event. -
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXTspecifies that something has occurred during validation against the Vulkan specification that may indicate invalid behavior. -
VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXTspecifies a potentially non-optimal use of Vulkan, e.g. using vkCmdClearColorImage when setting VkAttachmentDescription::loadOptoVK_ATTACHMENT_LOAD_OP_CLEARwould have worked.
// Provided by VK_EXT_debug_utils
typedef VkFlags VkDebugUtilsMessageTypeFlagsEXT;
VkDebugUtilsMessageTypeFlagsEXT is a bitmask type for setting a mask
of zero or more VkDebugUtilsMessageTypeFlagBitsEXT.
The prototype for the
VkDebugUtilsMessengerCreateInfoEXT::pfnUserCallback function
implemented by the application is:
// Provided by VK_EXT_debug_utils
typedef VkBool32 (VKAPI_PTR *PFN_vkDebugUtilsMessengerCallbackEXT)(
VkDebugUtilsMessageSeverityFlagBitsEXT messageSeverity,
VkDebugUtilsMessageTypeFlagsEXT messageTypes,
const VkDebugUtilsMessengerCallbackDataEXT* pCallbackData,
void* pUserData);
-
messageSeverityspecifies the VkDebugUtilsMessageSeverityFlagBitsEXT that triggered this callback. -
messageTypesis a bitmask of VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of event(s) triggered this callback. -
pCallbackDatacontains all the callback related data in the VkDebugUtilsMessengerCallbackDataEXT structure. -
pUserDatais the user data provided when the VkDebugUtilsMessengerEXT was created.
The callback returns a VkBool32, which is interpreted in a
layer-specified manner.
The application should always return VK_FALSE.
The VK_TRUE value is reserved for use in layer development.
The definition of VkDebugUtilsMessengerCallbackDataEXT is:
// Provided by VK_EXT_debug_utils
typedef struct VkDebugUtilsMessengerCallbackDataEXT {
VkStructureType sType;
const void* pNext;
VkDebugUtilsMessengerCallbackDataFlagsEXT flags;
const char* pMessageIdName;
int32_t messageIdNumber;
const char* pMessage;
uint32_t queueLabelCount;
const VkDebugUtilsLabelEXT* pQueueLabels;
uint32_t cmdBufLabelCount;
const VkDebugUtilsLabelEXT* pCmdBufLabels;
uint32_t objectCount;
const VkDebugUtilsObjectNameInfoEXT* pObjects;
} VkDebugUtilsMessengerCallbackDataEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis0and is reserved for future use. -
pMessageIdNameis a null-terminated string that identifies the particular message ID that is associated with the provided message. If the message corresponds to a validation layer message, then this string may contain the portion of the Vulkan specification that is believed to have been violated. -
messageIdNumberis the ID number of the triggering message. If the message corresponds to a validation layer message, then this number is related to the internal number associated with the message being triggered. -
pMessageis a null-terminated string detailing the trigger conditions. -
queueLabelCountis a count of items contained in thepQueueLabelsarray. -
pQueueLabelsisNULLor a pointer to an array of VkDebugUtilsLabelEXT active in the currentVkQueueat the time the callback was triggered. Refer to Queue Labels for more information. -
cmdBufLabelCountis a count of items contained in thepCmdBufLabelsarray. -
pCmdBufLabelsisNULLor a pointer to an array of VkDebugUtilsLabelEXT active in the currentVkCommandBufferat the time the callback was triggered. Refer to Command Buffer Labels for more information. -
objectCountis a count of items contained in thepObjectsarray. -
pObjectsis a pointer to an array of VkDebugUtilsObjectNameInfoEXT objects related to the detected issue. The array is roughly in order or importance, but the 0th element is always guaranteed to be the most important object for this message.
|
Note
This structure should only be considered valid during the lifetime of the triggered callback. |
Since adding queue and command buffer labels behaves like pushing and
popping onto a stack, the order of both pQueueLabels and
pCmdBufLabels is based on the order the labels were defined.
The result is that the first label in either pQueueLabels or
pCmdBufLabels will be the first defined (and therefore the oldest)
while the last label in each list will be the most recent.
|
Note
Likewise, |
// Provided by VK_EXT_debug_utils
typedef VkFlags VkDebugUtilsMessengerCallbackDataFlagsEXT;
VkDebugUtilsMessengerCallbackDataFlagsEXT is a bitmask type for
setting a mask, but is currently reserved for future use.
There may be times that a user wishes to intentionally submit a debug message. To do this, call:
// Provided by VK_EXT_debug_utils
void vkSubmitDebugUtilsMessageEXT(
VkInstance instance,
VkDebugUtilsMessageSeverityFlagBitsEXT messageSeverity,
VkDebugUtilsMessageTypeFlagsEXT messageTypes,
const VkDebugUtilsMessengerCallbackDataEXT* pCallbackData);
-
instanceis the debug stream’s VkInstance. -
messageSeverityis a VkDebugUtilsMessageSeverityFlagBitsEXT value specifying the severity of this event/message. -
messageTypesis a bitmask of VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of event(s) to identify with this message. -
pCallbackDatacontains all the callback related data in the VkDebugUtilsMessengerCallbackDataEXT structure.
The call will propagate through the layers and generate callback(s) as
indicated by the message’s flags.
The parameters are passed on to the callback in addition to the
pUserData value that was defined at the time the messenger was
registered.
To destroy a VkDebugUtilsMessengerEXT object, call:
// Provided by VK_EXT_debug_utils
void vkDestroyDebugUtilsMessengerEXT(
VkInstance instance,
VkDebugUtilsMessengerEXT messenger,
const VkAllocationCallbacks* pAllocator);
-
instanceis the instance where the callback was created. -
messengeris the VkDebugUtilsMessengerEXT object to destroy.messengeris an externally synchronized object and must not be used on more than one thread at a time. This means thatvkDestroyDebugUtilsMessengerEXTmust not be called when a callback is active. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
The application must ensure that vkDestroyDebugUtilsMessengerEXT is
not executed in parallel with any Vulkan command that is also called with
instance or child of instance as the dispatchable argument.
45.2. Debug Markers
Debug markers provide a flexible way for debugging and validation layers to receive annotation and debug information.
The Object Annotation section describes how to associate a name or binary data with a Vulkan object.
The Command Buffer Markers section describes how to associate logical elements of the scene with commands in the command buffer.
45.2.1. Object Annotation
The commands in this section allow application developers to associate user-defined information with Vulkan objects at will.
An object can be given a user-friendly name by calling:
// Provided by VK_EXT_debug_marker
VkResult vkDebugMarkerSetObjectNameEXT(
VkDevice device,
const VkDebugMarkerObjectNameInfoEXT* pNameInfo);
-
deviceis the device that created the object. -
pNameInfois a pointer to a VkDebugMarkerObjectNameInfoEXT structure specifying the parameters of the name to set on the object.
The VkDebugMarkerObjectNameInfoEXT structure is defined as:
// Provided by VK_EXT_debug_marker
typedef struct VkDebugMarkerObjectNameInfoEXT {
VkStructureType sType;
const void* pNext;
VkDebugReportObjectTypeEXT objectType;
uint64_t object;
const char* pObjectName;
} VkDebugMarkerObjectNameInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
objectTypeis a VkDebugReportObjectTypeEXT specifying the type of the object to be named. -
objectis the object to be named. -
pObjectNameis a null-terminated UTF-8 string specifying the name to apply toobject.
Applications may change the name associated with an object simply by
calling vkDebugMarkerSetObjectNameEXT again with a new string.
To remove a previously set name, pObjectName should be set to an
empty string.
In addition to setting a name for an object, debugging and validation layers
may have uses for additional binary data on a per-object basis that has no
other place in the Vulkan API.
For example, a VkShaderModule could have additional debugging data
attached to it to aid in offline shader tracing.
To attach data to an object, call:
// Provided by VK_EXT_debug_marker
VkResult vkDebugMarkerSetObjectTagEXT(
VkDevice device,
const VkDebugMarkerObjectTagInfoEXT* pTagInfo);
-
deviceis the device that created the object. -
pTagInfois a pointer to a VkDebugMarkerObjectTagInfoEXT structure specifying the parameters of the tag to attach to the object.
The VkDebugMarkerObjectTagInfoEXT structure is defined as:
// Provided by VK_EXT_debug_marker
typedef struct VkDebugMarkerObjectTagInfoEXT {
VkStructureType sType;
const void* pNext;
VkDebugReportObjectTypeEXT objectType;
uint64_t object;
uint64_t tagName;
size_t tagSize;
const void* pTag;
} VkDebugMarkerObjectTagInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
objectTypeis a VkDebugReportObjectTypeEXT specifying the type of the object to be named. -
objectis the object to be tagged. -
tagNameis a numerical identifier of the tag. -
tagSizeis the number of bytes of data to attach to the object. -
pTagis a pointer to an array oftagSizebytes containing the data to be associated with the object.
The tagName parameter gives a name or identifier to the type of data
being tagged.
This can be used by debugging layers to easily filter for only data that can
be used by that implementation.
45.2.2. Command Buffer Markers
Typical Vulkan applications will submit many command buffers in each frame, with each command buffer containing a large number of individual commands. Being able to logically annotate regions of command buffers that belong together as well as hierarchically subdivide the frame is important to a developer’s ability to navigate the commands viewed holistically.
The marker commands vkCmdDebugMarkerBeginEXT and
vkCmdDebugMarkerEndEXT define regions of a series of commands that are
grouped together, and they can be nested to create a hierarchy.
The vkCmdDebugMarkerInsertEXT command allows insertion of a single
label within a command buffer.
A marker region can be opened by calling:
// Provided by VK_EXT_debug_marker
void vkCmdDebugMarkerBeginEXT(
VkCommandBuffer commandBuffer,
const VkDebugMarkerMarkerInfoEXT* pMarkerInfo);
-
commandBufferis the command buffer into which the command is recorded. -
pMarkerInfois a pointer to a VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker region to open.
The VkDebugMarkerMarkerInfoEXT structure is defined as:
// Provided by VK_EXT_debug_marker
typedef struct VkDebugMarkerMarkerInfoEXT {
VkStructureType sType;
const void* pNext;
const char* pMarkerName;
float color[4];
} VkDebugMarkerMarkerInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pMarkerNameis a pointer to a null-terminated UTF-8 string containing the name of the marker. -
coloris an optional RGBA color value that can be associated with the marker. A particular implementation may choose to ignore this color value. The values contain RGBA values in order, in the range 0.0 to 1.0. If all elements incolorare set to 0.0 then it is ignored.
A marker region can be closed by calling:
// Provided by VK_EXT_debug_marker
void vkCmdDebugMarkerEndEXT(
VkCommandBuffer commandBuffer);
-
commandBufferis the command buffer into which the command is recorded.
An application may open a marker region in one command buffer and close it
in another, or otherwise split marker regions across multiple command
buffers or multiple queue submissions.
When viewed from the linear series of submissions to a single queue, the
calls to vkCmdDebugMarkerBeginEXT and vkCmdDebugMarkerEndEXT
must be matched and balanced.
A single marker label can be inserted into a command buffer by calling:
// Provided by VK_EXT_debug_marker
void vkCmdDebugMarkerInsertEXT(
VkCommandBuffer commandBuffer,
const VkDebugMarkerMarkerInfoEXT* pMarkerInfo);
-
commandBufferis the command buffer into which the command is recorded. -
pMarkerInfois a pointer to a VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker to insert.
45.3. Debug Report Callbacks
Debug report callbacks are represented by VkDebugReportCallbackEXT
handles:
// Provided by VK_EXT_debug_report
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDebugReportCallbackEXT)
Debug report callbacks give more detailed feedback on the application’s use of Vulkan when events of interest occur.
To register a debug report callback, an application uses vkCreateDebugReportCallbackEXT.
// Provided by VK_EXT_debug_report
VkResult vkCreateDebugReportCallbackEXT(
VkInstance instance,
const VkDebugReportCallbackCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDebugReportCallbackEXT* pCallback);
-
instanceis the instance the callback will be logged on. -
pCreateInfois a pointer to a VkDebugReportCallbackCreateInfoEXT structure defining the conditions under which this callback will be called. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pCallbackis a pointer to a VkDebugReportCallbackEXT handle in which the created object is returned.
The definition of VkDebugReportCallbackCreateInfoEXT is:
// Provided by VK_EXT_debug_report
typedef struct VkDebugReportCallbackCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkDebugReportFlagsEXT flags;
PFN_vkDebugReportCallbackEXT pfnCallback;
void* pUserData;
} VkDebugReportCallbackCreateInfoEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkDebugReportFlagBitsEXT specifying which event(s) will cause this callback to be called. -
pfnCallbackis the application callback function to call. -
pUserDatais user data to be passed to the callback.
For each VkDebugReportCallbackEXT that is created the
VkDebugReportCallbackCreateInfoEXT::flags determine when that
VkDebugReportCallbackCreateInfoEXT::pfnCallback is called.
When an event happens, the implementation will do a bitwise AND of the
event’s VkDebugReportFlagBitsEXT flags to each
VkDebugReportCallbackEXT object’s flags.
For each non-zero result the corresponding callback will be called.
The callback will come directly from the component that detected the event,
unless some other layer intercepts the calls for its own purposes (filter
them in a different way, log to a system error log, etc.).
An application may receive multiple callbacks if multiple
VkDebugReportCallbackEXT objects were created.
A callback will always be executed in the same thread as the originating
Vulkan call.
A callback may be called from multiple threads simultaneously (if the application is making Vulkan calls from multiple threads).
Bits which can be set in
VkDebugReportCallbackCreateInfoEXT::flags, specifying events
which cause a debug report, are:
// Provided by VK_EXT_debug_report
typedef enum VkDebugReportFlagBitsEXT {
VK_DEBUG_REPORT_INFORMATION_BIT_EXT = 0x00000001,
VK_DEBUG_REPORT_WARNING_BIT_EXT = 0x00000002,
VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT = 0x00000004,
VK_DEBUG_REPORT_ERROR_BIT_EXT = 0x00000008,
VK_DEBUG_REPORT_DEBUG_BIT_EXT = 0x00000010,
} VkDebugReportFlagBitsEXT;
-
VK_DEBUG_REPORT_ERROR_BIT_EXTspecifies that the application has violated a valid usage condition of the specification. -
VK_DEBUG_REPORT_WARNING_BIT_EXTspecifies use of Vulkan that may expose an app bug. Such cases may not be immediately harmful, such as a fragment shader outputting to a location with no attachment. Other cases may point to behavior that is almost certainly bad when unintended such as using an image whose memory has not been filled. In general if you see a warning but you know that the behavior is intended/desired, then simply ignore the warning. -
VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXTspecifies a potentially non-optimal use of Vulkan, e.g. using vkCmdClearColorImage when setting VkAttachmentDescription::loadOptoVK_ATTACHMENT_LOAD_OP_CLEARwould have worked. -
VK_DEBUG_REPORT_INFORMATION_BIT_EXTspecifies an informational message such as resource details that may be handy when debugging an application. -
VK_DEBUG_REPORT_DEBUG_BIT_EXTspecifies diagnostic information from the implementation and layers.
// Provided by VK_EXT_debug_report
typedef VkFlags VkDebugReportFlagsEXT;
VkDebugReportFlagsEXT is a bitmask type for setting a mask of zero or
more VkDebugReportFlagBitsEXT.
The prototype for the
VkDebugReportCallbackCreateInfoEXT::pfnCallback function
implemented by the application is:
// Provided by VK_EXT_debug_report
typedef VkBool32 (VKAPI_PTR *PFN_vkDebugReportCallbackEXT)(
VkDebugReportFlagsEXT flags,
VkDebugReportObjectTypeEXT objectType,
uint64_t object,
size_t location,
int32_t messageCode,
const char* pLayerPrefix,
const char* pMessage,
void* pUserData);
-
flagsspecifies the VkDebugReportFlagBitsEXT that triggered this callback. -
objectTypeis a VkDebugReportObjectTypeEXT value specifying the type of object being used or created at the time the event was triggered. -
objectis the object where the issue was detected. IfobjectTypeisVK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT,objectis undefined. -
locationis a component (layer, driver, loader) defined value specifying the location of the trigger. This is an optional value. -
messageCodeis a layer-defined value indicating what test triggered this callback. -
pLayerPrefixis a null-terminated string that is an abbreviation of the name of the component making the callback.pLayerPrefixis only valid for the duration of the callback. -
pMessageis a null-terminated string detailing the trigger conditions.pMessageis only valid for the duration of the callback. -
pUserDatais the user data given when the VkDebugReportCallbackEXT was created.
The callback must not call vkDestroyDebugReportCallbackEXT.
The callback returns a VkBool32, which is interpreted in a
layer-specified manner.
The application should always return VK_FALSE.
The VK_TRUE value is reserved for use in layer development.
object must be a Vulkan object or VK_NULL_HANDLE.
If objectType is not VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT and
object is not VK_NULL_HANDLE, object must be a Vulkan
object of the corresponding type associated with objectType as defined
in VkDebugReportObjectTypeEXT and Vulkan Handle Relationship.
Possible values passed to the objectType parameter of the callback
function specified by
VkDebugReportCallbackCreateInfoEXT::pfnCallback, specifying the
type of object handle being reported, are:
// Provided by VK_EXT_debug_marker, VK_EXT_debug_report
typedef enum VkDebugReportObjectTypeEXT {
VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT = 0,
VK_DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT = 1,
VK_DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT = 2,
VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT = 3,
VK_DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT = 4,
VK_DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT = 5,
VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT = 6,
VK_DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT = 7,
VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT = 8,
VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT = 9,
VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT = 10,
VK_DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT = 11,
VK_DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT = 12,
VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT = 13,
VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT = 14,
VK_DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT = 15,
VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT = 16,
VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT = 17,
VK_DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT = 18,
VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT = 19,
VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT = 20,
VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT = 21,
VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT = 22,
VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT = 23,
VK_DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT = 24,
VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT = 25,
VK_DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT = 26,
VK_DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT = 27,
VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT = 28,
VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT = 29,
VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT = 30,
VK_DEBUG_REPORT_OBJECT_TYPE_VALIDATION_CACHE_EXT_EXT = 33,
// Provided by VK_VERSION_1_1 with VK_EXT_debug_report, VK_KHR_sampler_ycbcr_conversion with VK_EXT_debug_report
VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_EXT = 1000156000,
// Provided by VK_VERSION_1_1 with VK_EXT_debug_report
VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT = 1000085000,
// Provided by VK_NVX_binary_import
VK_DEBUG_REPORT_OBJECT_TYPE_CU_MODULE_NVX_EXT = 1000029000,
// Provided by VK_NVX_binary_import
VK_DEBUG_REPORT_OBJECT_TYPE_CU_FUNCTION_NVX_EXT = 1000029001,
// Provided by VK_KHR_acceleration_structure
VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR_EXT = 1000150000,
// Provided by VK_NV_ray_tracing
VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV_EXT = 1000165000,
// Provided by VK_FUCHSIA_buffer_collection
VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_COLLECTION_FUCHSIA_EXT = 1000366000,
VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT = VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT,
VK_DEBUG_REPORT_OBJECT_TYPE_VALIDATION_CACHE_EXT = VK_DEBUG_REPORT_OBJECT_TYPE_VALIDATION_CACHE_EXT_EXT,
// Provided by VK_KHR_descriptor_update_template with VK_EXT_debug_report
VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT = VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_KHR_EXT = VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_EXT,
} VkDebugReportObjectTypeEXT;
| VkDebugReportObjectTypeEXT | Vulkan Handle Type |
|---|---|
|
Unknown/Undefined Handle |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note
The primary expected use of |
To inject its own messages into the debug stream, call:
// Provided by VK_EXT_debug_report
void vkDebugReportMessageEXT(
VkInstance instance,
VkDebugReportFlagsEXT flags,
VkDebugReportObjectTypeEXT objectType,
uint64_t object,
size_t location,
int32_t messageCode,
const char* pLayerPrefix,
const char* pMessage);
-
instanceis the debug stream’s VkInstance. -
flagsspecifies the VkDebugReportFlagBitsEXT classification of this event/message. -
objectTypeis a VkDebugReportObjectTypeEXT specifying the type of object being used or created at the time the event was triggered. -
objectis the object where the issue was detected.objectcan be VK_NULL_HANDLE if there is no object associated with the event. -
locationis an application defined value. -
messageCodeis an application defined value. -
pLayerPrefixis the abbreviation of the component making this event/message. -
pMessageis a null-terminated string detailing the trigger conditions.
The call will propagate through the layers and generate callback(s) as
indicated by the message’s flags.
The parameters are passed on to the callback in addition to the
pUserData value that was defined at the time the callback was
registered.
To destroy a VkDebugReportCallbackEXT object, call:
// Provided by VK_EXT_debug_report
void vkDestroyDebugReportCallbackEXT(
VkInstance instance,
VkDebugReportCallbackEXT callback,
const VkAllocationCallbacks* pAllocator);
-
instanceis the instance where the callback was created. -
callbackis the VkDebugReportCallbackEXT object to destroy.callbackis an externally synchronized object and must not be used on more than one thread at a time. This means thatvkDestroyDebugReportCallbackEXTmust not be called when a callback is active. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
45.4. Device Loss Debugging
45.4.1. Device Diagnostic Checkpoints
Device execution progress can be tracked for the purposes of debugging a device loss by annotating the command stream with application-defined diagnostic checkpoints.
Device diagnostic checkpoints are inserted into the command stream by calling vkCmdSetCheckpointNV.
// Provided by VK_NV_device_diagnostic_checkpoints
void vkCmdSetCheckpointNV(
VkCommandBuffer commandBuffer,
const void* pCheckpointMarker);
-
commandBufferis the command buffer that will receive the marker -
pCheckpointMarkeris an opaque application-provided value that will be associated with the checkpoint.
Note that pCheckpointMarker is treated as an opaque value.
It does not need to be a valid pointer and will not be dereferenced by the
implementation.
If the device encounters an error during execution, the implementation will
return a VK_ERROR_DEVICE_LOST error to the application at some point
during host execution.
When this happens, the application can call
vkGetQueueCheckpointData2NV to retrieve information on the most recent
diagnostic checkpoints that were executed by the device.
// Provided by VK_KHR_synchronization2 with VK_NV_device_diagnostic_checkpoints
void vkGetQueueCheckpointData2NV(
VkQueue queue,
uint32_t* pCheckpointDataCount,
VkCheckpointData2NV* pCheckpointData);
-
queueis the VkQueue object the caller would like to retrieve checkpoint data for -
pCheckpointDataCountis a pointer to an integer related to the number of checkpoint markers available or queried, as described below. -
pCheckpointDatais eitherNULLor a pointer to an array ofVkCheckpointData2NVstructures.
If pCheckpointData is NULL, then the number of checkpoint markers
available is returned in pCheckpointDataCount.
Otherwise, pCheckpointDataCount must point to a variable set by the
user to the number of elements in the pCheckpointData array, and on
return the variable is overwritten with the number of structures actually
written to pCheckpointData.
If pCheckpointDataCount is less than the number of checkpoint markers
available, at most pCheckpointDataCount structures will be written.
The VkCheckpointData2NV structure is defined as:
// Provided by VK_KHR_synchronization2 with VK_NV_device_diagnostic_checkpoints
typedef struct VkCheckpointData2NV {
VkStructureType sType;
void* pNext;
VkPipelineStageFlags2 stage;
void* pCheckpointMarker;
} VkCheckpointData2NV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stageindicates a single pipeline stage which the checkpoint marker data refers to. -
pCheckpointMarkercontains the value of the last checkpoint marker executed in the stage thatstagerefers to.
The stages at which a checkpoint marker can be executed are implementation-defined and can be queried by calling vkGetPhysicalDeviceQueueFamilyProperties2.
If the device encounters an error during execution, the implementation will
return a VK_ERROR_DEVICE_LOST error to the application at a certain
point during host execution.
When this happens, the application can call
vkGetQueueCheckpointDataNV to retrieve information on the most recent
diagnostic checkpoints that were executed by the device.
// Provided by VK_NV_device_diagnostic_checkpoints
void vkGetQueueCheckpointDataNV(
VkQueue queue,
uint32_t* pCheckpointDataCount,
VkCheckpointDataNV* pCheckpointData);
-
queueis the VkQueue object the caller would like to retrieve checkpoint data for -
pCheckpointDataCountis a pointer to an integer related to the number of checkpoint markers available or queried, as described below. -
pCheckpointDatais eitherNULLor a pointer to an array ofVkCheckpointDataNVstructures.
If pCheckpointData is NULL, then the number of checkpoint markers
available is returned in pCheckpointDataCount.
Otherwise, pCheckpointDataCount must point to a variable set by the
user to the number of elements in the pCheckpointData array, and on
return the variable is overwritten with the number of structures actually
written to pCheckpointData.
If pCheckpointDataCount is less than the number of checkpoint markers
available, at most pCheckpointDataCount structures will be written.
The VkCheckpointDataNV structure is defined as:
// Provided by VK_NV_device_diagnostic_checkpoints
typedef struct VkCheckpointDataNV {
VkStructureType sType;
void* pNext;
VkPipelineStageFlagBits stage;
void* pCheckpointMarker;
} VkCheckpointDataNV;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stageis aVkPipelineStageFlagBitsvalue specifying which pipeline stage the checkpoint marker data refers to. -
pCheckpointMarkercontains the value of the last checkpoint marker executed in the stage thatstagerefers to.
The stages at which a checkpoint marker can be executed are implementation-defined and can be queried by calling vkGetPhysicalDeviceQueueFamilyProperties2.
45.5. Active Tooling Information
Information about tools providing debugging, profiling, or similar services, active for a given physical device, can be obtained by calling:
// Provided by VK_VERSION_1_3
VkResult vkGetPhysicalDeviceToolProperties(
VkPhysicalDevice physicalDevice,
uint32_t* pToolCount,
VkPhysicalDeviceToolProperties* pToolProperties);
or the equivalent command
// Provided by VK_EXT_tooling_info
VkResult vkGetPhysicalDeviceToolPropertiesEXT(
VkPhysicalDevice physicalDevice,
uint32_t* pToolCount,
VkPhysicalDeviceToolProperties* pToolProperties);
-
physicalDeviceis the handle to the physical device to query for active tools. -
pToolCountis a pointer to an integer describing the number of tools active onphysicalDevice. -
pToolPropertiesis eitherNULLor a pointer to an array of VkPhysicalDeviceToolProperties structures.
If pToolProperties is NULL, then the number of tools currently
active on physicalDevice is returned in pToolCount.
Otherwise, pToolCount must point to a variable set by the user to the
number of elements in the pToolProperties array, and on return the
variable is overwritten with the number of structures actually written to
pToolProperties.
If pToolCount is less than the number of currently active tools, at
most pToolCount structures will be written.
The count and properties of active tools may change in response to events outside the scope of the specification. An application should assume these properties might change at any given time.
The VkPhysicalDeviceToolProperties structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceToolProperties {
VkStructureType sType;
void* pNext;
char name[VK_MAX_EXTENSION_NAME_SIZE];
char version[VK_MAX_EXTENSION_NAME_SIZE];
VkToolPurposeFlags purposes;
char description[VK_MAX_DESCRIPTION_SIZE];
char layer[VK_MAX_EXTENSION_NAME_SIZE];
} VkPhysicalDeviceToolProperties;
or the equivalent
// Provided by VK_EXT_tooling_info
typedef VkPhysicalDeviceToolProperties VkPhysicalDeviceToolPropertiesEXT;
-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nameis a null-terminated UTF-8 string containing the name of the tool. -
versionis a null-terminated UTF-8 string containing the version of the tool. -
purposesis a bitmask of VkToolPurposeFlagBits which is populated with purposes supported by the tool. -
descriptionis a null-terminated UTF-8 string containing a description of the tool. -
layeris a null-terminated UTF-8 string containing the name of the layer implementing the tool, if the tool is implemented in a layer - otherwise it may be an empty string.
Bits which can be set in
VkPhysicalDeviceToolProperties::purposes, specifying the
purposes of an active tool, are:
// Provided by VK_VERSION_1_3
typedef enum VkToolPurposeFlagBits {
VK_TOOL_PURPOSE_VALIDATION_BIT = 0x00000001,
VK_TOOL_PURPOSE_PROFILING_BIT = 0x00000002,
VK_TOOL_PURPOSE_TRACING_BIT = 0x00000004,
VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT = 0x00000008,
VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT = 0x00000010,
// Provided by VK_EXT_debug_report with VK_EXT_tooling_info, VK_EXT_debug_utils with VK_EXT_tooling_info
VK_TOOL_PURPOSE_DEBUG_REPORTING_BIT_EXT = 0x00000020,
// Provided by VK_EXT_debug_marker with VK_EXT_tooling_info, VK_EXT_debug_utils with VK_EXT_tooling_info
VK_TOOL_PURPOSE_DEBUG_MARKERS_BIT_EXT = 0x00000040,
VK_TOOL_PURPOSE_VALIDATION_BIT_EXT = VK_TOOL_PURPOSE_VALIDATION_BIT,
VK_TOOL_PURPOSE_PROFILING_BIT_EXT = VK_TOOL_PURPOSE_PROFILING_BIT,
VK_TOOL_PURPOSE_TRACING_BIT_EXT = VK_TOOL_PURPOSE_TRACING_BIT,
VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT_EXT = VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT,
VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT_EXT = VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT,
} VkToolPurposeFlagBits;
or the equivalent
// Provided by VK_EXT_tooling_info
typedef VkToolPurposeFlagBits VkToolPurposeFlagBitsEXT;
-
VK_TOOL_PURPOSE_VALIDATION_BITspecifies that the tool provides validation of API usage. -
VK_TOOL_PURPOSE_PROFILING_BITspecifies that the tool provides profiling of API usage. -
VK_TOOL_PURPOSE_TRACING_BITspecifies that the tool is capturing data about the application’s API usage, including anything from simple logging to capturing data for later replay. -
VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BITspecifies that the tool provides additional API features/extensions on top of the underlying implementation. -
VK_TOOL_PURPOSE_MODIFYING_FEATURES_BITspecifies that the tool modifies the API features/limits/extensions presented to the application. -
VK_TOOL_PURPOSE_DEBUG_REPORTING_BIT_EXTspecifies that the tool reports additional information to the application via callbacks specified by vkCreateDebugReportCallbackEXT or vkCreateDebugUtilsMessengerEXT -
VK_TOOL_PURPOSE_DEBUG_MARKERS_BIT_EXTspecifies that the tool consumes debug markers or object debug annotation, queue labels, or command buffer labels
// Provided by VK_VERSION_1_3
typedef VkFlags VkToolPurposeFlags;
or the equivalent
// Provided by VK_EXT_tooling_info
typedef VkToolPurposeFlags VkToolPurposeFlagsEXT;
VkToolPurposeFlags is a bitmask type for setting a mask of zero or more VkToolPurposeFlagBits.
Appendix A: Vulkan Environment for SPIR-V
Shaders for Vulkan are defined by the Khronos SPIR-V Specification as well as the Khronos SPIR-V Extended Instructions for GLSL Specification. This appendix defines additional SPIR-V requirements applying to Vulkan shaders.
Versions and Formats
A Vulkan 1.3 implementation must support the 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, and 1.6 versions of SPIR-V and the 1.0 version of the SPIR-V Extended Instructions for GLSL.
A SPIR-V module passed into vkCreateShaderModule is interpreted as a series of 32-bit words in host endianness, with literal strings packed as described in section 2.2 of the SPIR-V Specification. The first few words of the SPIR-V module must be a magic number and a SPIR-V version number, as described in section 2.3 of the SPIR-V Specification.
Capabilities
The table below lists the set of SPIR-V
capabilities that may be supported in Vulkan implementations.
The application must not use any of these capabilities in SPIR-V passed to
vkCreateShaderModule unless one of the following conditions is met for
the VkDevice specified in the device parameter of
vkCreateShaderModule:
-
The corresponding field in the table is blank.
-
Any corresponding Vulkan feature is enabled.
-
Any corresponding Vulkan extension is enabled.
-
Any corresponding Vulkan property is supported.
-
The corresponding core version is supported (as returned by VkPhysicalDeviceProperties::
apiVersion).
The application must not pass a SPIR-V module containing any of the following to vkCreateShaderModule:
-
any
OpCapabilitynot listed above, -
an unsupported capability, or
-
a capability which corresponds to a Vulkan feature or extension which has not been enabled.
SPIR-V Extensions
The following table lists SPIR-V extensions
that implementations may support.
The application must not pass a SPIR-V module to vkCreateShaderModule
that uses the following SPIR-V extensions unless one of the following
conditions is met for the VkDevice specified in the device
parameter of vkCreateShaderModule:
-
Any corresponding Vulkan extension is enabled.
-
The corresponding core version is supported (as returned by VkPhysicalDeviceProperties::
apiVersion).
SPIR-V OpExtensionVulkan extension or core version |
|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Validation Rules within a Module
A SPIR-V module passed to vkCreateShaderModule must conform to the following rules:
Precision and Operation of SPIR-V Instructions
The following rules apply to half, single, and double-precision floating point instructions:
-
Positive and negative infinities and positive and negative zeros are generated as dictated by IEEE 754, but subject to the precisions allowed in the following table.
-
Dividing a non-zero by a zero results in the appropriately signed IEEE 754 infinity.
-
Signaling NaNs are not required to be generated and exceptions are never raised. Signaling NaN may be converted to quiet NaNs values by any floating point instruction.
-
By default, the implementation may perform optimizations on half, single, or double-precision floating-point instructions that ignore sign of a zero, or assume that arguments and results are not NaNs or infinities. If the entry point is declared with the
SignedZeroInfNanPreserveexecution mode, then NaNs, infinities, and the sign of zero must not be ignored.-
The following core SPIR-V instructions must respect the
SignedZeroInfNanPreserveexecution mode:OpPhi,OpSelect,OpReturnValue,OpVectorExtractDynamic,OpVectorInsertDynamic,OpVectorShuffle,OpCompositeConstruct,OpCompositeExtract,OpCompositeInsert,OpCopyObject,OpTranspose,OpFConvert,OpFNegate,OpFAdd,OpFSub,OpFMul,OpStore. This execution mode must also be respected byOpLoadexcept for loads from theInputstorage class in the fragment shader stage with the floating-point result type. Other SPIR-V instructions may also respect theSignedZeroInfNanPreserveexecution mode.
-
-
The following instructions must not flush denormalized values:
OpConstant,OpConstantComposite,OpSpecConstant,OpSpecConstantComposite,OpLoad,OpStore,OpBitcast,OpPhi,OpSelect,OpFunctionCall,OpReturnValue,OpVectorExtractDynamic,OpVectorInsertDynamic,OpVectorShuffle,OpCompositeConstruct,OpCompositeExtract,OpCompositeInsert,OpCopyMemory,OpCopyObject. -
Denormalized values are supported.
-
By default, any half, single, or double-precision denormalized value input into a shader or potentially generated by any instruction (except those listed above) or any extended instructions for GLSL in a shader may be flushed to zero.
-
If the entry point is declared with the
DenormFlushToZeroexecution mode then for the affected instuctions the denormalized result must be flushed to zero and the denormalized operands may be flushed to zero. Denormalized values obtained via unpacking an integer into a vector of values with smaller bit width and interpreting those values as floating-point numbers must be flushed to zero. -
The following core SPIR-V instructions must respect the
DenormFlushToZeroexecution mode:OpSpecConstantOp(with opcodeOpFConvert),OpFConvert,OpFNegate,OpFAdd,OpFSub,OpFMul,OpFDiv,OpFRem,OpFMod,OpVectorTimesScalar,OpMatrixTimesScalar,OpVectorTimesMatrix,OpMatrixTimesVector,OpMatrixTimesMatrix,OpOuterProduct,OpDot; and the following extended instructions for GLSL:Round,RoundEven,Trunc,FAbs,Floor,Ceil,Fract,Radians,Degrees,Sin,Cos,Tan,Asin,Acos,Atan,Sinh,Cosh,Tanh,Asinh,Acosh,Atanh,Atan2,Pow,Exp,Log,Exp2,Log2,Sqrt,InverseSqrt,Determinant,MatrixInverse,Modf,ModfStruct,FMin,FMax,FClamp,FMix,Step,SmoothStep,Fma,UnpackHalf2x16,UnpackDouble2x32,Length,Distance,Cross,Normalize,FaceForward,Reflect,Refract,NMin,NMax,NClamp. Other SPIR-V instructions (except those excluded above) may also flush denormalized values. -
The following core SPIR-V instructions must respect the
DenormPreserveexecution mode:OpTranspose,OpSpecConstantOp,OpFConvert,OpFNegate,OpFAdd,OpFSub,OpFMul,OpVectorTimesScalar,OpMatrixTimesScalar,OpVectorTimesMatrix,OpMatrixTimesVector,OpMatrixTimesMatrix,OpOuterProduct,OpDot,OpFOrdEqual,OpFUnordEqual,OpFOrdNotEqual,OpFUnordNotEqual,OpFOrdLessThan,OpFUnordLessThan,OpFOrdGreaterThan,OpFUnordGreaterThan,OpFOrdLessThanEqual,OpFUnordLessThanEqual,OpFOrdGreaterThanEqual,OpFUnordGreaterThanEqual; and the following extended instructions for GLSL:FAbs,FSign,Radians,Degrees,FMin,FMax,FClamp,FMix,Fma,PackHalf2x16,PackDouble2x32,UnpackHalf2x16,UnpackDouble2x32,NMin,NMax,NClamp. Other SPIR-V instructions may also preserve denorm values.
-
The precision of double-precision instructions is at least that of single precision.
The precision of operations is defined either in terms of rounding, as an error bound in ULP, or as inherited from a formula as follows.
Operations described as “correctly rounded” will return the infinitely
precise result, x, rounded so as to be representable in
floating-point.
The rounding mode is not specified, unless the entry point is declared with
the RoundingModeRTE or the RoundingModeRTZ execution mode.
These execution modes affect only correctly rounded SPIR-V instructions.
These execution modes do not affect OpQuantizeToF16.
If the rounding mode is not specified then this rounding is implementation
specific, subject to the following rules.
If x is exactly representable then x will be returned.
Otherwise, either the floating-point value closest to and no less than
x or the value closest to and no greater than x will be
returned.
Where an error bound of n ULP (units in the last place) is given, for an operation with infinitely precise result x the value returned must be in the range [x - n × ulp(x), x + n × ulp(x)]. The function ulp(x) is defined as follows:
-
If there exist non-equal floating-point numbers a and b such that a ≤ x ≤ b then ulp(x) is the minimum possible distance between such numbers, . If such numbers do not exist then ulp(x) is defined to be the difference between the two finite floating-point numbers nearest to x.
Where the range of allowed return values includes any value of magnitude larger than that of the largest representable finite floating-point number, operations may, additionally, return either an infinity of the appropriate sign or the finite number with the largest magnitude of the appropriate sign. If the infinitely precise result of the operation is not mathematically defined then the value returned is undefined.
Where an operation’s precision is described as being inherited from a
formula, the result returned must be at least as accurate as the result of
computing an approximation to x using a formula equivalent to the
given formula applied to the supplied inputs.
Specifically, the formula given may be transformed using the mathematical
associativity, commutativity and distributivity of the operators involved to
yield an equivalent formula.
The SPIR-V precision rules, when applied to each such formula and the given
input values, define a range of permitted values.
If NaN is one of the permitted values then the operation may return
any result, otherwise let the largest permitted value in any of the ranges
be Fmax and the smallest be Fmin.
The operation must return a value in the range [x - E, x + E]
where .
If the entry point is declared with the DenormFlushToZero execution
mode, then any intermediate denormal value(s) while evaluating the formula
may be flushed to zero.
Denormal final results must be flushed to zero.
If the entry point is declared with the DenormPreserve execution mode,
then denormals must be preserved throughout the formula.
For half- (16 bit) and single- (32 bit) precision instructions, precisions are required to be at least as follows:
| Instruction | Single precision, unless decorated with RelaxedPrecision | Half precision |
|---|---|---|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Inherited from . |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
2.5 ULP for |y| in the range [2-126, 2126]. |
2.5 ULP for |y| in the range [2-14, 214]. |
|
Inherited from x - y × trunc(x/y). |
|
|
Inherited from x - y × floor(x/y). |
|
conversions between types |
Correctly rounded. |
|
|
Note
The |
| Instruction | Single precision, unless decorated with RelaxedPrecision | Half precision |
|---|---|---|
|
Inherited from |
|
|
ULP. |
ULP. |
|
3 ULP outside the range . Absolute error < inside the range . |
3 ULP outside the range . Absolute error < inside the range . |
|
Inherited from |
|
|
Inherited from 1.0 / |
|
|
2 ULP. |
|
|
Inherited from . |
|
|
Inherited from . |
|
|
Absolute error inside the range . |
Absolute error inside the range . |
|
Absolute error inside the range . |
Absolute error inside the range . |
|
Inherited from . |
|
|
Inherited from . |
|
|
Inherited from . |
|
|
4096 ULP |
5 ULP. |
|
Inherited from . |
|
|
Inherited from . |
|
|
Inherited from . |
|
|
Inherited from . |
|
|
Inherited from . |
|
|
Inherited from . |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Inherited from . |
|
|
Inherited from . |
|
|
Inherited from |
|
|
Inherited from . |
|
|
Inherited from |
|
|
Inherited from x - 2.0 × |
|
|
Inherited from k < 0.0 ? 0.0 : eta × I - (eta × |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Inherited from . |
|
|
Correctly rounded. |
|
|
Inherited from , where . |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
GLSL.std.450 extended instructions specifically defined in terms of the above instructions inherit the above errors. GLSL.std.450 extended instructions not listed above and not defined in terms of the above have undefined precision.
For the OpSRem and OpSMod instructions, if either operand is
negative the result is undefined.
|
Note
While the |
OpCooperativeMatrixMulAddNV performs its operations in an
implementation-dependent order and internal precision.
Signedness of SPIR-V Image Accesses
SPIR-V associates a signedness with all integer image accesses.
This is required in certain parts of the SPIR-V and the Vulkan image access
pipeline to ensure defined results.
The signedness is determined from a combination of the access instruction’s
Image Operands and the underlying image’s Sampled Type
as follows:
-
If the instruction’s
ImageOperandscontains theSignExtendoperand then the access is signed. -
If the instruction’s
ImageOperandscontains theZeroExtendoperand then the access is unsigned. -
Otherwise, the image accesses signedness matches that of the
SampledTypeof theOpTypeImagebeing accessed.
Image Format and Type Matching
When specifying the Image Format of an OpTypeImage, the
converted bit width and type, as shown in the table below, must match the
Sampled Type.
The signedness must match the signedness of any
access to the image.
|
Note
Formatted accesses are always converted from a shader readable type to the resource’s format or vice versa via Format Conversion for reads and Texel Output Format Conversion for writes. As such, the bit width and format below do not necessarily match 1:1 with what might be expected for some formats. |
For a given Image Format, the Sampled Type must be the
type described in the Type column of the below table, with its
Literal Width set to that in the Bit Width column.
Every access that is made to the image must have a signedness equal to that
in the Signedness column (where applicable).
| Image Format | Type | Bit Width | Signedness |
|---|---|---|---|
|
Any |
Any |
Any |
|
|
32 |
N/A |
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|
32 |
1 |
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
0 |
||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|
64 |
1 |
|
0 |
Compatibility Between SPIR-V Image Formats And Vulkan Formats
SPIR-V Image Format values are compatible with VkFormat
values as defined below:
| SPIR-V Image Format | Compatible Vulkan Format |
|---|---|
|
Any |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Appendix B: Memory Model
Agent
Operation is a general term for any task that is executed on the system.
|
Note
An operation is by definition something that is executed. Thus if an instruction is skipped due to control flow, it does not constitute an operation. |
Each operation is executed by a particular agent. Possible agents include each shader invocation, each host thread, and each fixed-function stage of the pipeline.
Memory Location
A memory location identifies unique storage for 8 bits of data. Memory operations access a set of memory locations consisting of one or more memory locations at a time, e.g. an operation accessing a 32-bit integer in memory would read/write a set of four memory locations. Memory operations that access whole aggregates may access any padding bytes between elements or members, but no padding bytes at the end of the aggregate. Two sets of memory locations overlap if the intersection of their sets of memory locations is non-empty. A memory operation must not affect memory at a memory location not within its set of memory locations.
Memory locations for buffers and images are explicitly allocated in VkDeviceMemory objects, and are implicitly allocated for SPIR-V variables in each shader invocation.
Variables with Workgroup storage class that point to a block-decorated
type share a set of memory locations.
Allocation
The values stored in newly allocated memory locations are determined by a SPIR-V variable’s initializer, if present, or else are undefined. At the time an allocation is created there have been no memory operations to any of its memory locations. The initialization is not considered to be a memory operation.
|
Note
For tessellation control shader output variables, a consequence of initialization not being considered a memory operation is that some implementations may need to insert a barrier between the initialization of the output variables and any reads of those variables. |
Memory Operation
For an operation A and memory location M:
|
Note
A write whose value is the same as what was already in those memory locations is still considered to be a write and has all the same effects. |
Reference
A reference is an object that a particular agent can use to access a set of memory locations. On the host, a reference is a host virtual address. On the device, a reference is:
-
The descriptor that a variable is bound to, for variables in Image, Uniform, or StorageBuffer storage classes. If the variable is an array (or array of arrays, etc.) then each element of the array may be a unique reference.
-
The address range for a buffer in
PhysicalStorageBufferstorage class, where the base of the address range is queried with vkGetBufferDeviceAddress and the length of the range is the size of the buffer. -
A single common reference for all variables with
Workgroupstorage class that point to a block-decorated type. -
The variable itself for non-block-decorated type variables in
Workgroupstorage class. -
The variable itself for variables in other storage classes.
Two memory accesses through distinct references may require availability and visibility operations as defined below.
Program-Order
A dynamic instance of an instruction is defined in SPIR-V (https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#DynamicInstance) as a way of referring to a particular execution of a static instruction. Program-order is an ordering on dynamic instances of instructions executed by a single shader invocation:
-
(Basic block): If instructions A and B are in the same basic block, and A is listed in the module before B, then the n’th dynamic instance of A is program-ordered before the n’th dynamic instance of B.
-
(Branch): The dynamic instance of a branch or switch instruction is program-ordered before the dynamic instance of the OpLabel instruction to which it transfers control.
-
(Call entry): The dynamic instance of an
OpFunctionCallinstruction is program-ordered before the dynamic instances of theOpFunctionParameterinstructions and the body of the called function. -
(Call exit): The dynamic instance of the instruction following an
OpFunctionCallinstruction is program-ordered after the dynamic instance of the return instruction executed by the called function. -
(Transitive Closure): If dynamic instance A of any instruction is program-ordered before dynamic instance B of any instruction and B is program-ordered before dynamic instance C of any instruction then A is program-ordered before C.
-
(Complete definition): No other dynamic instances are program-ordered.
For instructions executed on the host, the source language defines the program-order relation (e.g. as “sequenced-before”).
Shader Call Related
Shader-call-related is an equivalence relation on invocations defined as the symmetric and transitive closure of:
-
A is shader-call-related to B if A is created by an invocation repack instruction executed by B.
Shader Call Order
Shader-call-order is a partial order on dynamic instances of instructions executed by invocations that are shader-call-related:
-
(Program order): If dynamic instance A is program-ordered before B, then A is shader-call-ordered before B.
-
(Shader call entry): If A is a dynamic instance of an invocation repack instruction and B is a dynamic instance executed by an invocation that is created by A, then A is shader-call-ordered before B.
-
(Shader call exit): If A is a dynamic instance of an invocation repack instruction, B is the next dynamic instance executed by the same invocation, and C is a dynamic instance executed by an invocation that is created by A, then C is shader-call-ordered before B.
-
(Transitive closure): If A is shader-call-ordered-before B and B is shader-call-ordered-before C, then A is shader-call-ordered-before C.
-
(Complete definition): No other dynamic instances are shader-call-ordered.
Scope
Atomic and barrier instructions include scopes which identify sets of shader invocations that must obey the requested ordering and atomicity rules of the operation, as defined below.
The various scopes are described in detail in the Shaders chapter.
Atomic Operation
An atomic operation on the device is any SPIR-V operation whose name
begins with OpAtomic.
An atomic operation on the host is any operation performed with an
std::atomic typed object.
Each atomic operation has a memory scope and a
semantics.
Informally, the scope determines which other agents it is atomic with
respect to, and the semantics constrains
its ordering against other memory accesses.
Device atomic operations have explicit scopes and semantics.
Each host atomic operation implicitly uses the CrossDevice scope, and
uses a memory semantics equivalent to a C++ std::memory_order value of
relaxed, acquire, release, acq_rel, or seq_cst.
Two atomic operations A and B are potentially-mutually-ordered if and only if all of the following are true:
-
They access the same set of memory locations.
-
They use the same reference.
-
A is in the instance of B’s memory scope.
-
B is in the instance of A’s memory scope.
-
A and B are not the same operation (irreflexive).
Two atomic operations A and B are mutually-ordered if and only if they are potentially-mutually-ordered and any of the following are true:
-
A and B are both device operations.
-
A and B are both host operations.
-
A is a device operation, B is a host operation, and the implementation supports concurrent host- and device-atomics.
|
Note
If two atomic operations are not mutually-ordered, and if their sets of memory locations overlap, then each must be synchronized against the other as if they were non-atomic operations. |
Scoped Modification Order
For a given atomic write A, all atomic writes that are mutually-ordered with A occur in an order known as A’s scoped modification order. A’s scoped modification order relates no other operations.
|
Note
Invocations outside the instance of A’s memory scope may observe the values at A’s set of memory locations becoming visible to it in an order that disagrees with the scoped modification order. |
|
Note
It is valid to have non-atomic operations or atomics in a different scope instance to the same set of memory locations, as long as they are synchronized against each other as if they were non-atomic (if they are not, it is treated as a data race). That means this definition of A’s scoped modification order could include atomic operations that occur much later, after intervening non-atomics. That is a bit non-intuitive, but it helps to keep this definition simple and non-circular. |
Memory Semantics
Non-atomic memory operations, by default, may be observed by one agent in a different order than they were written by another agent.
Atomics and some synchronization operations include memory semantics, which are flags that constrain the order in which other memory accesses (including non-atomic memory accesses and availability and visibility operations) performed by the same agent can be observed by other agents, or can observe accesses by other agents.
Device instructions that include semantics are OpAtomic*,
OpControlBarrier, OpMemoryBarrier, and OpMemoryNamedBarrier.
Host instructions that include semantics are some std::atomic methods and
memory fences.
SPIR-V supports the following memory semantics:
-
Relaxed: No constraints on order of other memory accesses.
-
Acquire: A memory read with this semantic performs an acquire operation. A memory barrier with this semantic is an acquire barrier.
-
Release: A memory write with this semantic performs a release operation. A memory barrier with this semantic is a release barrier.
-
AcquireRelease: A memory read-modify-write operation with this semantic performs both an acquire operation and a release operation, and inherits the limitations on ordering from both of those operations. A memory barrier with this semantic is both a release and acquire barrier.
|
Note
SPIR-V does not support “consume” semantics on the device. |
The memory semantics operand also includes storage class semantics which indicate which storage classes are constrained by the synchronization. SPIR-V storage class semantics include:
-
UniformMemory
-
WorkgroupMemory
-
ImageMemory
-
OutputMemory
Each SPIR-V memory operation accesses a single storage class. Semantics in synchronization operations can include a combination of storage classes.
The UniformMemory storage class semantic applies to accesses to memory in
the
PhysicalStorageBuffer,
ShaderRecordBufferKHR,
Uniform and StorageBuffer storage classes.
The WorkgroupMemory storage class semantic applies to accesses to memory in
the Workgroup storage class.
The ImageMemory storage class semantic applies to accesses to memory in the
Image storage class.
The OutputMemory storage class semantic applies to accesses to memory in the
Output storage class.
|
Note
Informally, these constraints limit how memory operations can be reordered, and these limits apply not only to the order of accesses as performed in the agent that executes the instruction, but also to the order the effects of writes become visible to all other agents within the same instance of the instruction’s memory scope. |
|
Note
Release and acquire operations in different threads can act as synchronization operations, to guarantee that writes that happened before the release are visible after the acquire. (This is not a formal definition, just an Informative forward reference.) |
|
Note
The OutputMemory storage class semantic is only useful in tessellation control shaders, which is the only execution model where output variables are shared between invocations. |
The memory semantics operand can also include availability and visibility flags, which apply availability and visibility operations as described in availability and visibility. The availability/visibility flags are:
-
MakeAvailable: Semantics must be Release or AcquireRelease. Performs an availability operation before the release operation or barrier.
-
MakeVisible: Semantics must be Acquire or AcquireRelease. Performs a visibility operation after the acquire operation or barrier.
The specifics of these operations are defined in Availability and Visibility Semantics.
Host atomic operations may support a different list of memory semantics and synchronization operations, depending on the host architecture and source language.
Release Sequence
After an atomic operation A performs a release operation on a set of memory locations M, the release sequence headed by A is the longest continuous subsequence of A’s scoped modification order that consists of:
-
the atomic operation A as its first element
-
atomic read-modify-write operations on M by any agent
|
Note
The atomics in the last bullet must be mutually-ordered with A by virtue of being in A’s scoped modification order. |
|
Note
This intentionally omits “atomic writes to M performed by the same agent that performed A”, which is present in the corresponding C++ definition. |
Synchronizes-With
Synchronizes-with is a relation between operations, where each operation is either an atomic operation or a memory barrier (aka fence on the host).
If A and B are atomic operations, then A synchronizes-with B if and only if all of the following are true:
-
A performs a release operation
-
B performs an acquire operation
-
A and B are mutually-ordered
-
B reads a value written by A or by an operation in the release sequence headed by A
OpControlBarrier, OpMemoryBarrier, and OpMemoryNamedBarrier
are memory barrier instructions in SPIR-V.
If A is a release barrier and B is an atomic operation that performs an acquire operation, then A synchronizes-with B if and only if all of the following are true:
-
there exists an atomic write X (with any memory semantics)
-
A is program-ordered before X
-
X and B are mutually-ordered
-
B reads a value written by X or by an operation in the release sequence headed by X
-
If X is relaxed, it is still considered to head a hypothetical release sequence for this rule
-
-
A and B are in the instance of each other’s memory scopes
-
X’s storage class is in A’s semantics.
If A is an atomic operation that performs a release operation and B is an acquire barrier, then A synchronizes-with B if and only if all of the following are true:
-
there exists an atomic read X (with any memory semantics)
-
X is program-ordered before B
-
X and A are mutually-ordered
-
X reads a value written by A or by an operation in the release sequence headed by A
-
A and B are in the instance of each other’s memory scopes
-
X’s storage class is in B’s semantics.
If A is a release barrier and B is an acquire barrier, then A synchronizes-with B if all of the following are true:
-
there exists an atomic write X (with any memory semantics)
-
A is program-ordered before X
-
there exists an atomic read Y (with any memory semantics)
-
Y is program-ordered before B
-
X and Y are mutually-ordered
-
Y reads the value written by X or by an operation in the release sequence headed by X
-
If X is relaxed, it is still considered to head a hypothetical release sequence for this rule
-
-
A and B are in the instance of each other’s memory scopes
-
X’s and Y’s storage class is in A’s and B’s semantics.
-
NOTE: X and Y must have the same storage class, because they are mutually ordered.
-
If A is a release barrier, B is an acquire barrier, and C is a control barrier (where A can equal C, and B can equal C), then A synchronizes-with B if all of the following are true:
-
A is program-ordered before (or equals) C
-
C is program-ordered before (or equals) B
-
A and B are in the instance of each other’s memory scopes
-
A and B are in the instance of C’s execution scope
|
Note
This is similar to the barrier-barrier synchronization above, but with a control barrier filling the role of the relaxed atomics. |
Let F be an ordering of fragment shader invocations, such that invocation F1 is ordered before invocation F2 if and only if F1 and F2 overlap as described in Fragment Shader Interlock and F1 executes the interlocked code before F2.
If A is an OpEndInvocationInterlockEXT instruction and B is an
OpBeginInvocationInterlockEXT instruction, then A synchronizes-with B
if the agent that executes A is ordered before the agent that executes B in
F. A and B are both considered to have FragmentInterlock memory scope
and semantics of UniformMemory and ImageMemory, and A is considered to have
Release semantics and B is considered to have Acquire semantics.
|
Note
|
If A is a release barrier and B is an acquire barrier, then A synchronizes-with B if all of the following are true:
-
A is shader-call-ordered-before B
-
A and B are in the instance of each other’s memory scopes
No other release and acquire barriers synchronize-with each other.
System-Synchronizes-With
System-synchronizes-with is a relation between arbitrary operations on the device or host. Certain operations system-synchronize-with each other, which informally means the first operation occurs before the second and that the synchronization is performed without using application-visible memory accesses.
If there is an execution dependency between two operations A and B, then the operation in the first synchronization scope system-synchronizes-with the operation in the second synchronization scope.
|
Note
This covers all Vulkan synchronization primitives, including device operations executing before a synchronization primitive is signaled, wait operations happening before subsequent device operations, signal operations happening before host operations that wait on them, and host operations happening before vkQueueSubmit. The list is spread throughout the synchronization chapter, and is not repeated here. |
System-synchronizes-with implicitly includes all storage class semantics and
has CrossDevice scope.
If A system-synchronizes-with B, we also say A is system-synchronized-before B and B is system-synchronized-after A.
Private vs. Non-Private
By default, non-atomic memory operations are treated as private, meaning such a memory operation is not intended to be used for communication with other agents. Memory operations with the NonPrivatePointer/NonPrivateTexel bit set are treated as non-private, and are intended to be used for communication with other agents.
More precisely, for private memory operations to be Location-Ordered between distinct agents requires using system-synchronizes-with rather than shader-based synchronization. Non-private memory operations still obey program-order.
Atomic operations are always considered non-private.
Inter-Thread-Happens-Before
Let SC be a non-empty set of storage class semantics. Then (using template syntax) operation A inter-thread-happens-before<SC> operation B if and only if any of the following is true:
-
A system-synchronizes-with B
-
A synchronizes-with B, and both A and B have all of SC in their semantics
-
A is an operation on memory in a storage class in SC or that has all of SC in its semantics, B is a release barrier or release atomic with all of SC in its semantics, and A is program-ordered before B
-
A is an acquire barrier or acquire atomic with all of SC in its semantics, B is an operation on memory in a storage class in SC or that has all of SC in its semantics, and A is program-ordered before B
-
A and B are both host operations and A inter-thread-happens-before B as defined in the host language specification
-
A inter-thread-happens-before<SC> some X and X inter-thread-happens-before<SC> B
Happens-Before
Operation A happens-before operation B if and only if any of the following is true:
-
A is program-ordered before B
-
A inter-thread-happens-before<SC> B for some set of storage classes SC
Happens-after is defined similarly.
|
Note
Unlike C++, happens-before is not always sufficient for a write to be visible to a read. Additional availability and visibility operations may be required for writes to be visible-to other memory accesses. |
|
Note
Happens-before is not transitive, but each of program-order and inter-thread-happens-before<SC> are transitive. These can be thought of as covering the “single-threaded” case and the “multi-threaded” case, and it is not necessary (and not valid) to form chains between the two. |
Availability and Visibility
Availability and visibility are states of a write operation, which (informally) track how far the write has permeated the system, i.e. which agents and references are able to observe the write. Availability state is per memory domain. Visibility state is per (agent,reference) pair. Availability and visibility states are per-memory location for each write.
Memory domains are named according to the agents whose memory accesses use the domain. Domains used by shader invocations are organized hierarchically into multiple smaller memory domains which correspond to the different scopes. Each memory domain is considered the dual of a scope, and vice versa. The memory domains defined in Vulkan include:
-
host - accessible by host agents
-
device - accessible by all device agents for a particular device
-
shader - accessible by shader agents for a particular device, corresponding to the
Devicescope -
queue family instance - accessible by shader agents in a single queue family, corresponding to the
QueueFamilyscope. -
fragment interlock instance - accessible by fragment shader agents that overlap, corresponding to the
FragmentInterlockscope. -
shader call instance - accessible by shader agents that are shader-call-related, corresponding to the
ShaderCallKHRscope. -
workgroup instance - accessible by shader agents in the same workgroup, corresponding to the
Workgroupscope. -
subgroup instance - accessible by shader agents in the same subgroup, corresponding to the
Subgroupscope.
The memory domains are nested in the order listed above, except for shader call instance domain, with memory domains later in the list nested in the domains earlier in the list. The shader call instance domain is at an implementation-dependent location in the list, and is nested according to that location. The shader call instance domain is not broader than the queue family instance domain.
|
Note
Memory domains do not correspond to storage classes or device-local and host-local VkDeviceMemory allocations, rather they indicate whether a write can be made visible only to agents in the same subgroup, same workgroup, overlapping fragment shader invocation, shader-call-related ray tracing invocation, in any shader invocation, or anywhere on the device, or host. The shader, queue family instance, fragment interlock instance, shader call instance, workgroup instance, and subgroup instance domains are only used for shader-based availability/visibility operatons, in other cases writes can be made available from/visible to the shader via the device domain. |
Availability operations, visibility operations, and memory domain operations alter the state of the write operations that happen-before them, and which are included in their source scope to be available or visible to their destination scope.
-
For an availability operation, the source scope is a set of (agent,reference,memory location) tuples, and the destination scope is a set of memory domains.
-
For a memory domain operation, the source scope is a memory domain and the destination scope is a memory domain.
-
For a visibility operation, the source scope is a set of memory domains and the destination scope is a set of (agent,reference,memory location) tuples.
How the scopes are determined depends on the specific operation. Availability and memory domain operations expand the set of memory domains to which the write is available. Visibility operations expand the set of (agent,reference,memory location) tuples to which the write is visible.
Recall that availability and visibility states are per-memory location, and let W be a write operation to one or more locations performed by agent A via reference R. Let L be one of the locations written. (W,L) (the write W to L), is initially not available to any memory domain and only visible to (A,R,L). An availability operation AV that happens-after W and that includes (A,R,L) in its source scope makes (W,L) available to the memory domains in its destination scope.
A memory domain operation DOM that happens-after AV and for which (W,L) is available in the source scope makes (W,L) available in the destination memory domain.
A visibility operation VIS that happens-after AV (or DOM) and for which (W,L) is available in any domain in the source scope makes (W,L) visible to all (agent,reference,L) tuples included in its destination scope.
If write W2 happens-after W, and their sets of memory locations overlap, then W will not be available/visible to all agents/references for those memory locations that overlap (and future AV/DOM/VIS ops cannot revive W’s write to those locations).
Availability, memory domain, and visibility operations are treated like other non-atomic memory accesses for the purpose of memory semantics, meaning they can be ordered by release-acquire sequences or memory barriers.
An availability chain is a sequence of availability operations to increasingly broad memory domains, where element N+1 of the chain is performed in the dual scope instance of the destination memory domain of element N and element N happens-before element N+1. An example is an availability operation with destination scope of the workgroup instance domain that happens-before an availability operation to the shader domain performed by an invocation in the same workgroup. An availability chain AVC that happens-after W and that includes (A,R,L) in the source scope makes (W,L) available to the memory domains in its final destination scope. An availability chain with a single element is just the availability operation.
Similarly, a visibility chain is a sequence of visibility operations from increasingly narrow memory domains, where element N of the chain is performed in the dual scope instance of the source memory domain of element N+1 and element N happens-before element N+1. An example is a visibility operation with source scope of the shader domain that happens-before a visibility operation with source scope of the workgroup instance domain performed by an invocation in the same workgroup. A visibility chain VISC that happens-after AVC (or DOM) and for which (W,L) is available in any domain in the source scope makes (W,L) visible to all (agent,reference,L) tuples included in its final destination scope. A visibility chain with a single element is just the visibility operation.
Availability, Visibility, and Domain Operations
The following operations generate availability, visibility, and domain operations. When multiple availability/visibility/domain operations are described, they are system-synchronized-with each other in the order listed.
An operation that performs a memory dependency generates:
-
If the source access mask includes
VK_ACCESS_HOST_WRITE_BIT, then the dependency includes a memory domain operation from host domain to device domain. -
An availability operation with source scope of all writes in the first access scope of the dependency and a destination scope of the device domain.
-
A visibility operation with source scope of the device domain and destination scope of the second access scope of the dependency.
-
If the destination access mask includes
VK_ACCESS_HOST_READ_BITorVK_ACCESS_HOST_WRITE_BIT, then the dependency includes a memory domain operation from device domain to host domain.
vkFlushMappedMemoryRanges performs an availability operation, with a source scope of (agents,references) = (all host threads, all mapped memory ranges passed to the command), and destination scope of the host domain.
vkInvalidateMappedMemoryRanges performs a visibility operation, with a source scope of the host domain and a destination scope of (agents,references) = (all host threads, all mapped memory ranges passed to the command).
vkQueueSubmit performs a memory domain operation from host to device, and a visibility operation with source scope of the device domain and destination scope of all agents and references on the device.
Availability and Visibility Semantics
A memory barrier or atomic operation via agent A that includes MakeAvailable in its semantics performs an availability operation whose source scope includes agent A and all references in the storage classes in that instruction’s storage class semantics, and all memory locations, and whose destination scope is a set of memory domains selected as specified below. The implicit availability operation is program-ordered between the barrier or atomic and all other operations program-ordered before the barrier or atomic.
A memory barrier or atomic operation via agent A that includes MakeVisible in its semantics performs a visibility operation whose source scope is a set of memory domains selected as specified below, and whose destination scope includes agent A and all references in the storage classes in that instruction’s storage class semantics, and all memory locations. The implicit visibility operation is program-ordered between the barrier or atomic and all other operations program-ordered after the barrier or atomic.
The memory domains are selected based on the memory scope of the instruction as follows:
-
Devicescope uses the shader domain -
QueueFamilyscope uses the queue family instance domain -
FragmentInterlockscope uses the fragment interlock instance domain -
ShaderCallKHRscope uses the shader call instance domain -
Workgroupscope uses the workgroup instance domain -
Subgroupuses the subgroup instance domain -
Invocationperform no availability/visibility operations.
When an availability operation performed by an agent A includes a memory domain D in its destination scope, where D corresponds to scope instance S, it also includes the memory domains that correspond to each smaller scope instance S' that is a subset of S and that includes A. Similarly for visibility operations.
Per-Instruction Availability and Visibility Semantics
A memory write instruction that includes MakePointerAvailable, or an image write instruction that includes MakeTexelAvailable, performs an availability operation whose source scope includes the agent and reference used to perform the write and the memory locations written by the instruction, and whose destination scope is a set of memory domains selected by the Scope operand specified in Availability and Visibility Semantics. The implicit availability operation is program-ordered between the write and all other operations program-ordered after the write.
A memory read instruction that includes MakePointerVisible, or an image read instruction that includes MakeTexelVisible, performs a visibility operation whose source scope is a set of memory domains selected by the Scope operand as specified in Availability and Visibility Semantics, and whose destination scope includes the agent and reference used to perform the read and the memory locations read by the instruction. The implicit visibility operation is program-ordered between read and all other operations program-ordered before the read.
|
Note
Although reads with per-instruction visibility only perform visibility ops from the shader or fragment interlock instance or shader call instance or workgroup instance or subgroup instance domain, they will also see writes that were made visible via the device domain, i.e. those writes previously performed by non-shader agents and made visible via API commands. |
|
Note
It is expected that all invocations in a subgroup execute on the same processor with the same path to memory, and thus availability and visibility operations with subgroup scope can be expected to be “free”. |
Location-Ordered
Let X and Y be memory accesses to overlapping sets of memory locations M, where X != Y. Let (AX,RX) be the agent and reference used for X, and (AY,RY) be the agent and reference used for Y. For now, let “→” denote happens-before and “→rcpo” denote the reflexive closure of program-ordered before.
If D1 and D2 are different memory domains, then let DOM(D1,D2) be a memory domain operation from D1 to D2. Otherwise, let DOM(D,D) be a placeholder such that X→DOM(D,D)→Y if and only if X→Y.
X is location-ordered before Y for a location L in M if and only if any of the following is true:
-
AX == AY and RX == RY and X→Y
-
NOTE: this case means no availability/visibility ops are required when it is the same (agent,reference).
-
-
X is a read, both X and Y are non-private, and X→Y
-
X is a read, and X (transitively) system-synchronizes with Y
-
If RX == RY and AX and AY access a common memory domain D (e.g. are in the same workgroup instance if D is the workgroup instance domain), and both X and Y are non-private:
-
X is a write, Y is a write, AVC(AX,RX,D,L) is an availability chain making (X,L) available to domain D, and X→rcpoAVC(AX,RX,D,L)→Y
-
X is a write, Y is a read, AVC(AX,RX,D,L) is an availability chain making (X,L) available to domain D, VISC(AY,RY,D,L) is a visibility chain making writes to L available in domain D visible to Y, and X→rcpoAVC(AX,RX,D,L)→VISC(AY,RY,D,L)→rcpoY
-
If VkPhysicalDeviceVulkanMemoryModelFeatures::
vulkanMemoryModelAvailabilityVisibilityChainsisVK_FALSE, then AVC and VISC must each only have a single element in the chain, in each sub-bullet above.
-
-
Let DX and DY each be either the device domain or the host domain, depending on whether AX and AY execute on the device or host:
-
X is a write and Y is a write, and X→AV(AX,RX,DX,L)→DOM(DX,DY)→Y
-
X is a write and Y is a read, and X→AV(AX,RX,DX,L)→DOM(DX,DY)→VIS(AY,RY,DY,L)→Y
-
|
Note
The final bullet (synchronization through device/host domain) requires API-level synchronization operations, since the device/host domains are not accessible via shader instructions. And “device domain” is not to be confused with “device scope”, which synchronizes through the “shader domain”. |
Data Race
Let X and Y be operations that access overlapping sets of memory locations M, where X != Y, and at least one of X and Y is a write, and X and Y are not mutually-ordered atomic operations. If there does not exist a location-ordered relation between X and Y for each location in M, then there is a data race.
Applications must ensure that no data races occur during the execution of their application.
|
Note
Data races can only occur due to instructions that are actually executed. For example, an instruction skipped due to control flow must not contribute to a data race. |
Visible-To
Let X be a write and Y be a read whose sets of memory locations overlap, and let M be the set of memory locations that overlap. Let M2 be a non-empty subset of M. Then X is visible-to Y for memory locations M2 if and only if all of the following are true:
-
X is location-ordered before Y for each location L in M2.
-
There does not exist another write Z to any location L in M2 such that X is location-ordered before Z for location L and Z is location-ordered before Y for location L.
If X is visible-to Y, then Y reads the value written by X for locations M2.
|
Note
It is possible for there to be a write between X and Y that overwrites a subset of the memory locations, but the remaining memory locations (M2) will still be visible-to Y. |
Acyclicity
Reads-from is a relation between operations, where the first operation is a write, the second operation is a read, and the second operation reads the value written by the first operation. From-reads is a relation between operations, where the first operation is a read, the second operation is a write, and the first operation reads a value written earlier than the second operation in the second operation’s scoped modification order (or the first operation reads from the initial value, and the second operation is any write to the same locations).
Then the implementation must guarantee that no cycles exist in the union of the following relations:
-
location-ordered
-
scoped modification order (over all atomic writes)
-
reads-from
-
from-reads
|
Note
This is a “consistency” axiom, which informally guarantees that sequences of operations cannot violate causality. |
Scoped Modification Order Coherence
Let A and B be mutually-ordered atomic operations, where A is location-ordered before B. Then the following rules are a consequence of acyclicity:
-
If A and B are both reads and A does not read the initial value, then the write that A takes its value from must be earlier in its own scoped modification order than (or the same as) the write that B takes its value from (no cycles between location-order, reads-from, and from-reads).
-
If A is a read and B is a write and A does not read the initial value, then A must take its value from a write earlier than B in B’s scoped modification order (no cycles between location-order, scope modification order, and reads-from).
-
If A is a write and B is a read, then B must take its value from A or a write later than A in A’s scoped modification order (no cycles between location-order, scoped modification order, and from-reads).
-
If A and B are both writes, then A must be earlier than B in A’s scoped modification order (no cycles between location-order and scoped modification order).
-
If A is a write and B is a read-modify-write and B reads the value written by A, then B comes immediately after A in A’s scoped modification order (no cycles between scoped modification order and from-reads).
Shader I/O
If a shader invocation A in a shader stage other than Vertex performs a
memory read operation X from an object in storage class
CallableDataKHR, IncomingCallableDataKHR, RayPayloadKHR,
HitAttributeKHR, IncomingRayPayloadKHR, or
Input, then X is system-synchronized-after all writes to the
corresponding
CallableDataKHR, IncomingCallableDataKHR, RayPayloadKHR,
HitAttributeKHR, IncomingRayPayloadKHR, or
Output storage variable(s) in the shader invocation(s) that contribute
to generating invocation A, and those writes are all visible-to X.
|
Note
It is not necessary for the upstream shader invocations to have completed execution, they only need to have generated the output that is being read. |
Deallocation
A call to vkFreeMemory must happen-after all memory operations on all memory locations in that VkDeviceMemory object.
|
Note
Normally, device memory operations in a given queue are synchronized with vkFreeMemory by having a host thread wait on a fence signalled by that queue, and the wait happens-before the call to vkFreeMemory on the host. |
The deallocation of SPIR-V variables is managed by the system and happens-after all operations on those variables.
Descriptions (Informative)
This subsection offers more easily understandable consequences of the memory model for app/compiler developers.
Let SC be the storage class(es) specified by a release or acquire operation or barrier.
-
An atomic write with release semantics must not be reordered against any read or write to SC that is program-ordered before it (regardless of the storage class the atomic is in).
-
An atomic read with acquire semantics must not be reordered against any read or write to SC that is program-ordered after it (regardless of the storage class the atomic is in).
-
Any write to SC program-ordered after a release barrier must not be reordered against any read or write to SC program-ordered before that barrier.
-
Any read from SC program-ordered before an acquire barrier must not be reordered against any read or write to SC program-ordered after the barrier.
A control barrier (even if it has no memory semantics) must not be reordered against any memory barriers.
This memory model allows memory accesses with and without availability and visibility operations, as well as atomic operations, all to be performed on the same memory location. This is critical to allow it to reason about memory that is reused in multiple ways, e.g. across the lifetime of different shader invocations or draw calls. While GLSL (and legacy SPIR-V) applies the “coherent” decoration to variables (for historical reasons), this model treats each memory access instruction as having optional implicit availability/visibility operations. GLSL to SPIR-V compilers should map all (non-atomic) operations on a coherent variable to Make{Pointer,Texel}{Available}{Visible} flags in this model.
Atomic operations implicitly have availability/visibility operations, and the scope of those operations is taken from the atomic operation’s scope.
Tessellation Output Ordering
For SPIR-V that uses the Vulkan Memory Model, the OutputMemory storage
class is used to synchronize accesses to tessellation control output
variables.
For legacy SPIR-V that does not enable the Vulkan Memory Model via
OpMemoryModel, tessellation outputs can be ordered using a control
barrier with no particular memory scope or semantics, as defined below.
Let X and Y be memory operations performed by shader invocations AX and AY. Operation X is tessellation-output-ordered before operation Y if and only if all of the following are true:
-
There is a dynamic instance of an
OpControlBarrierinstruction C such that X is program-ordered before C in AX and C is program-ordered before Y in AY. -
AX and AY are in the same instance of C’s execution scope.
If shader invocations AX and AY in the TessellationControl
execution model execute memory operations X and Y, respectively, on the
Output storage class, and X is tessellation-output-ordered before Y
with a scope of Workgroup, then X is location-ordered before Y, and if
X is a write and Y is a read then X is visible-to Y.
Cooperative Matrix Memory Access
For each dynamic instance of a cooperative matrix load or store instruction
(OpCooperativeMatrixLoadNV or OpCooperativeMatrixStoreNV), a
single implementation-dependent invocation within the instance of the
matrix’s scope performs a non-atomic load or store (respectively) to each
memory location that is defined to be accessed by the instruction.
Appendix C: Compressed Image Formats
The compressed texture formats used by Vulkan are described in the specifically identified sections of the Khronos Data Format Specification, version 1.3.
Unless otherwise described, the quantities encoded in these compressed formats are treated as normalized, unsigned values.
Those formats listed as sRGB-encoded have in-memory representations of R, G and B components which are nonlinearly-encoded as R', G', and B'; any alpha component is unchanged. As part of filtering, the nonlinear R', G', and B' values are converted to linear R, G, and B components; any alpha component is unchanged. The conversion between linear and nonlinear encoding is performed as described in the “KHR_DF_TRANSFER_SRGB” section of the Khronos Data Format Specification.
Block-Compressed Image Formats
BC1, BC2 and BC3 formats are described in “S3TC Compressed Texture Image Formats” chapter of the Khronos Data Format Specification. BC4 and BC5 are described in the “RGTC Compressed Texture Image Formats” chapter. BC6H and BC7 are described in the “BPTC Compressed Texture Image Formats” chapter.
| VkFormat | Khronos Data Format Specification description |
|---|---|
Formats described in the “S3TC Compressed Texture Image Formats” chapter |
|
|
BC1 with no alpha |
|
BC1 with no alpha, sRGB-encoded |
|
BC1 with alpha |
|
BC1 with alpha, sRGB-encoded |
|
BC2 |
|
BC2, sRGB-encoded |
|
BC3 |
|
BC3, sRGB-encoded |
Formats described in the “RGTC Compressed Texture Image Formats” chapter |
|
|
BC4 unsigned |
|
BC4 signed |
|
BC5 unsigned |
|
BC5 signed |
Formats described in the “BPTC Compressed Texture Image Formats” chapter |
|
|
BC6H (unsigned version) |
|
BC6H (signed version) |
|
BC7 |
|
BC7, sRGB-encoded |
ETC Compressed Image Formats
The following formats are described in the “ETC2 Compressed Texture Image Formats” chapter of the Khronos Data Format Specification.
| VkFormat | Khronos Data Format Specification description |
|---|---|
|
RGB ETC2 |
|
RGB ETC2 with sRGB encoding |
|
RGB ETC2 with punch-through alpha |
|
RGB ETC2 with punch-through alpha and sRGB |
|
RGBA ETC2 |
|
RGBA ETC2 with sRGB encoding |
|
Unsigned R11 EAC |
|
Signed R11 EAC |
|
Unsigned RG11 EAC |
|
Signed RG11 EAC |
ASTC Compressed Image Formats
ASTC formats are described in the “ASTC Compressed Texture Image Formats” chapter of the Khronos Data Format Specification.
| VkFormat | Compressed texel block dimensions | Requested mode |
|---|---|---|
|
4 × 4 |
Linear LDR |
|
4 × 4 |
sRGB |
|
5 × 4 |
Linear LDR |
|
5 × 4 |
sRGB |
|
5 × 5 |
Linear LDR |
|
5 × 5 |
sRGB |
|
6 × 5 |
Linear LDR |
|
6 × 5 |
sRGB |
|
6 × 6 |
Linear LDR |
|
6 × 6 |
sRGB |
|
8 × 5 |
Linear LDR |
|
8 × 5 |
sRGB |
|
8 × 6 |
Linear LDR |
|
8 × 6 |
sRGB |
|
8 × 8 |
Linear LDR |
|
8 × 8 |
sRGB |
|
10 × 5 |
Linear LDR |
|
10 × 5 |
sRGB |
|
10 × 6 |
Linear LDR |
|
10 × 6 |
sRGB |
|
10 × 8 |
Linear LDR |
|
10 × 8 |
sRGB |
|
10 × 10 |
Linear LDR |
|
10 × 10 |
sRGB |
|
12 × 10 |
Linear LDR |
|
12 × 10 |
sRGB |
|
12 × 12 |
Linear LDR |
|
12 × 12 |
sRGB |
|
4 × 4 |
HDR |
|
5 × 4 |
HDR |
|
5 × 5 |
HDR |
|
6 × 5 |
HDR |
|
6 × 6 |
HDR |
|
8 × 5 |
HDR |
|
8 × 6 |
HDR |
|
8 × 8 |
HDR |
|
10 × 5 |
HDR |
|
10 × 6 |
HDR |
|
10 × 8 |
HDR |
|
10 × 10 |
HDR |
|
12 × 10 |
HDR |
|
12 × 12 |
HDR |
ASTC textures containing HDR block encodings should be passed to the API using an ASTC SFLOAT texture format.
|
Note
An HDR block in a texture passed using a LDR UNORM format will return the appropriate ASTC error color if the implementation supports only the ASTC LDR profile, but may result in either the error color or a decompressed HDR color if the implementation supports HDR decoding. |
ASTC decode mode
If the VK_EXT_astc_decode_mode extension is enabled, the decode mode is
determined as follows:
| VkFormat | Decoding mode |
|---|---|
|
decode_float16 |
|
decode_unorm8 |
|
decode_rgb9e5 |
Otherwise, the ASTC decode mode is decode_float16.
Note that an implementation may use HDR mode when linear LDR mode is requested unless the decode mode is decode_unorm8.
PVRTC Compressed Image Formats
PVRTC formats are described in the “PVRTC Compressed Texture Image Formats” chapter of the Khronos Data Format Specification.
| VkFormat | Compressed texel block dimensions | sRGB-encoded |
|---|---|---|
|
8 × 4 |
No |
|
4 × 4 |
No |
|
8 × 4 |
No |
|
4 × 4 |
No |
|
8 × 4 |
Yes |
|
4 × 4 |
Yes |
|
8 × 4 |
Yes |
|
4 × 4 |
Yes |
Appendix D: Core Revisions (Informative)
New minor versions of the Vulkan API are defined periodically by the Khronos Vulkan Working Group. These consist of some amount of additional functionality added to the core API, potentially including both new functionality and functionality promoted from extensions.
It is possible to build the specification for earlier versions, but to aid readability of the latest versions, this appendix gives an overview of the changes as compared to earlier versions.
Version 1.3
Vulkan Version 1.3 promoted a number of key extensions into the core API:
All differences in behavior between these extensions and the corresponding Vulkan 1.3 functionality are summarized below.
Differences relative to VK_EXT_4444_formats
If the VK_EXT_4444_formats extension is not supported, support for all
formats defined by it are optional in Vulkan 1.3.
There are no members in the VkPhysicalDeviceVulkan13Features structure
corresponding to the VkPhysicalDevice4444FormatsFeaturesEXT structure.
Differences relative to VK_EXT_extended_dynamic_state
All dynamic state enumerants and entry points defined by
VK_EXT_extended_dynamic_state are required in Vulkan 1.3.
There are no members in the VkPhysicalDeviceVulkan13Features structure
corresponding to the VkPhysicalDeviceExtendedDynamicStateFeaturesEXT
structure.
Differences relative to VK_EXT_extended_dynamic_state2
The optional dynamic state enumerants and entry points defined by
VK_EXT_extended_dynamic_state2 for patch control points and logic op
are not promoted in Vulkan 1.3.
There are no members in the VkPhysicalDeviceVulkan13Features structure
corresponding to the VkPhysicalDeviceExtendedDynamicState2FeaturesEXT
structure.
Differences relative to VK_EXT_texel_buffer_alignment
The more specific alignment requirements defined by VkPhysicalDeviceTexelBufferAlignmentProperties are required in Vulkan 1.3. There are no members in the VkPhysicalDeviceVulkan13Features structure corresponding to the VkPhysicalDeviceTexelBufferAlignmentFeaturesEXT structure.
Differences relative to VK_EXT_texture_compression_astc_hdr
If the VK_EXT_texture_compression_astc_hdr extension is not supported,
support for all formats defined by it are optional in Vulkan 1.3.
The textureCompressionASTC_HDR member of
VkPhysicalDeviceVulkan13Features indicates whether a Vulkan 1.3
implementation supports these formats.
Differences relative to VK_EXT_ycbcr_2plane_444_formats
If the VK_EXT_ycbcr_2plane_444_formats extension is not supported,
support for all formats defined by it are optional in Vulkan 1.3.
There are no members in the VkPhysicalDeviceVulkan13Features structure
corresponding to the VkPhysicalDeviceYcbcr2Plane444FormatsFeaturesEXT
structure.
Additional Vulkan 1.3 Feature Support
In addition to the promoted extensions described above, Vulkan 1.3 added required support for:
-
SPIR-V version 1.6
-
SPIR-V 1.6 deprecates (but does not remove) the
WorkgroupSizedecoration.
-
-
The
bufferDeviceAddressfeature which indicates support for accessing memory in shaders as storage buffers via vkGetBufferDeviceAddress. -
The
vulkanMemoryModelandvulkanMemoryModelDeviceScopefeatures, which indicate support for the corresponding Vulkan Memory Model capabilities. -
The
maxInlineUniformTotalSizelimit is added to provide the total size of all inline uniform block bindings in a pipeline layout.
New Structures
-
Extending VkCommandBufferInheritanceInfo:
-
Extending VkDescriptorPoolCreateInfo:
-
Extending VkDeviceCreateInfo:
-
Extending VkFormatProperties2:
-
Extending VkGraphicsPipelineCreateInfo:
-
Extending VkGraphicsPipelineCreateInfo, VkComputePipelineCreateInfo, VkRayTracingPipelineCreateInfoNV, VkRayTracingPipelineCreateInfoKHR:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineShaderStageCreateInfo:
-
Extending VkSubpassDependency2:
-
Extending VkWriteDescriptorSet:
New Enum Constants
-
Extending VkAccessFlagBits:
-
VK_ACCESS_NONE
-
-
Extending VkAttachmentStoreOp:
-
VK_ATTACHMENT_STORE_OP_NONE
-
-
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_CULL_MODE -
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE -
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE -
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP -
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE -
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE -
VK_DYNAMIC_STATE_FRONT_FACE -
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE -
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY -
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE -
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT -
VK_DYNAMIC_STATE_STENCIL_OP -
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE -
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE -
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT
-
-
Extending VkEventCreateFlagBits:
-
VK_EVENT_CREATE_DEVICE_ONLY_BIT
-
-
Extending VkFormat:
-
VK_FORMAT_A4B4G4R4_UNORM_PACK16 -
VK_FORMAT_A4R4G4B4_UNORM_PACK16 -
VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK -
VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK -
VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK -
VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK -
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK -
VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK -
VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK -
VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK -
VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK -
VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_444_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_444_UNORM_3PACK16 -
VK_FORMAT_G16_B16R16_2PLANE_444_UNORM -
VK_FORMAT_G8_B8R8_2PLANE_444_UNORM
-
-
Extending VkImageAspectFlagBits:
-
VK_IMAGE_ASPECT_NONE
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL -
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_PRIVATE_DATA_SLOT
-
-
Extending VkPipelineCacheCreateFlagBits:
-
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT -
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT
-
-
Extending VkPipelineShaderStageCreateFlagBits:
-
VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT -
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_NONE
-
-
Extending VkResult:
-
VK_PIPELINE_COMPILE_REQUIRED
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2 -
VK_STRUCTURE_TYPE_BUFFER_COPY_2 -
VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2 -
VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2 -
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO -
VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO -
VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2 -
VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2 -
VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2 -
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2 -
VK_STRUCTURE_TYPE_DEPENDENCY_INFO -
VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO -
VK_STRUCTURE_TYPE_DEVICE_BUFFER_MEMORY_REQUIREMENTS -
VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS -
VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO -
VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3 -
VK_STRUCTURE_TYPE_IMAGE_BLIT_2 -
VK_STRUCTURE_TYPE_IMAGE_COPY_2 -
VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2 -
VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2 -
VK_STRUCTURE_TYPE_MEMORY_BARRIER_2 -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES -
VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO -
VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO -
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO -
VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO -
VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO -
VK_STRUCTURE_TYPE_RENDERING_INFO -
VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2 -
VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO -
VK_STRUCTURE_TYPE_SUBMIT_INFO_2 -
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK
-
Version 1.2
Vulkan Version 1.2 promoted a number of key extensions into the core API:
All differences in behavior between these extensions and the corresponding Vulkan 1.2 functionality are summarized below.
Differences relative to VK_KHR_8bit_storage
If the VK_KHR_8bit_storage extension is not supported, support for
the SPIR-V storageBuffer8BitAccess capability in shader modules is optional.
Support for this feature is defined by
VkPhysicalDeviceVulkan12Features::storageBuffer8BitAccess when
queried via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_KHR_draw_indirect_count
If the VK_KHR_draw_indirect_count extension is not supported,
support for the entry points vkCmdDrawIndirectCount and
vkCmdDrawIndexedIndirectCount is optional.
Support for this feature is defined by
VkPhysicalDeviceVulkan12Features::drawIndirectCount when queried
via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_KHR_sampler_mirror_clamp_to_edge
If the VK_KHR_sampler_mirror_clamp_to_edge extension is not
supported, support for the VkSamplerAddressMode
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE is optional.
Support for this feature is defined by
VkPhysicalDeviceVulkan12Features::samplerMirrorClampToEdge when
queried via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_EXT_descriptor_indexing
If the VK_EXT_descriptor_indexing extension is not supported,
support for the descriptorIndexing
feature is optional.
Support for this feature is defined by
VkPhysicalDeviceVulkan12Features::descriptorIndexing when
queried via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_EXT_scalar_block_layout
If the VK_EXT_scalar_block_layout extension is not supported,
support for the scalarBlockLayout
feature is optional.
Support for this feature is defined by
VkPhysicalDeviceVulkan12Features::scalarBlockLayout when queried
via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_EXT_shader_viewport_index_layer
If the VK_EXT_shader_viewport_index_layer extension is not
supported, support for the ShaderViewportIndexLayerEXT SPIR-V
capability is optional.
Support for this feature is defined by
VkPhysicalDeviceVulkan12Features::shaderOutputViewportIndex and
VkPhysicalDeviceVulkan12Features::shaderOutputLayer when queried
via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_KHR_buffer_device_address
If the VK_KHR_buffer_device_address extension is not supported,
support for the bufferDeviceAddress
feature is optional.
Support for this feature is defined by
VkPhysicalDeviceVulkan12Features::bufferDeviceAddress when
queried via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_KHR_shader_atomic_int64
If the VK_KHR_shader_atomic_int64 extension is not supported,
support for the shaderBufferInt64Atomics feature is optional.
Support for this feature is defined by
VkPhysicalDeviceVulkan12Features::shaderBufferInt64Atomics when
queried via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_KHR_shader_float16_int8
If the VK_KHR_shader_float16_int8 extension is not supported,
support for the shaderFloat16 and
shaderInt8 features is optional.
Support for these features are defined by
VkPhysicalDeviceVulkan12Features::shaderFloat16 and
VkPhysicalDeviceVulkan12Features::shaderInt8 when queried via
vkGetPhysicalDeviceFeatures2.
Differences relative to VK_KHR_vulkan_memory_model
If the VK_KHR_vulkan_memory_model extension is not supported,
support for the vulkanMemoryModel
feature is optional.
Support for this feature is defined by
VkPhysicalDeviceVulkan12Features::vulkanMemoryModel when queried
via vkGetPhysicalDeviceFeatures2.
Additional Vulkan 1.2 Feature Support
In addition to the promoted extensions described above, Vulkan 1.2 added support for:
-
SPIR-V version 1.4.
-
SPIR-V version 1.5.
-
The
samplerMirrorClampToEdgefeature which indicates whether the implementation supports theVK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGEsampler address mode. -
The
ShaderNonUniformcapability in SPIR-V version 1.5. -
The
shaderOutputViewportIndexfeature which indicates that theShaderViewportIndexcapability can be used. -
The
shaderOutputLayerfeature which indicates that theShaderLayercapability can be used. -
The
subgroupBroadcastDynamicIdfeature which allows the “Id” operand ofOpGroupNonUniformBroadcastto be dynamically uniform within a subgroup, and the “Index” operand ofOpGroupNonUniformQuadBroadcastto be dynamically uniform within a derivative group, in shader modules of version 1.5 or higher. -
The
drawIndirectCountfeature which indicates whether the vkCmdDrawIndirectCount and vkCmdDrawIndexedIndirectCount functions can be used. -
The
descriptorIndexingfeature which indicates the implementation supports the minimum number of descriptor indexing features as defined in the Feature Requirements section. -
The
samplerFilterMinmaxfeature which indicates whether the implementation supports the minimum number of image formats that support theVK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BITfeature bit as defined by thefilterMinmaxSingleComponentFormatsproperty minimum requirements. -
The
framebufferIntegerColorSampleCountslimit which indicates the color sample counts that are supported for all framebuffer color attachments with integer formats.
New Structures
-
Extending VkAttachmentDescription2:
-
Extending VkAttachmentReference2:
-
Extending VkBufferCreateInfo:
-
Extending VkDescriptorSetAllocateInfo:
-
Extending VkDescriptorSetLayoutCreateInfo:
-
Extending VkDescriptorSetLayoutSupport:
-
Extending VkFramebufferCreateInfo:
-
Extending VkImageCreateInfo, VkPhysicalDeviceImageFormatInfo2:
-
Extending VkImageCreateInfo, VkSwapchainCreateInfoKHR, VkPhysicalDeviceImageFormatInfo2:
-
Extending VkMemoryAllocateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkRenderPassBeginInfo:
-
Extending VkSamplerCreateInfo:
-
Extending VkSemaphoreCreateInfo, VkPhysicalDeviceExternalSemaphoreInfo:
-
Extending VkSubmitInfo, VkBindSparseInfo:
-
Extending VkSubpassDescription2:
New Enum Constants
-
VK_MAX_DRIVER_INFO_SIZE -
VK_MAX_DRIVER_NAME_SIZE -
Extending VkBufferCreateFlagBits:
-
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT
-
-
Extending VkDescriptorPoolCreateFlagBits:
-
VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT
-
-
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT
-
-
Extending VkFramebufferCreateFlagBits:
-
VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL -
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
-
-
Extending VkMemoryAllocateFlagBits:
-
VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT -
VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT
-
-
Extending VkResult:
-
VK_ERROR_FRAGMENTATION -
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS
-
-
Extending VkSamplerAddressMode:
-
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2 -
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT -
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2 -
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT -
VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO -
VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO -
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO -
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_ALLOCATE_INFO -
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_LAYOUT_SUPPORT -
VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO -
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO -
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO -
VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO -
VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO -
VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES -
VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO -
VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2 -
VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO -
VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO -
VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO -
VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO -
VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO -
VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2 -
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2 -
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE -
VK_STRUCTURE_TYPE_SUBPASS_END_INFO -
VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO
-
Version 1.1
Vulkan Version 1.1 promoted a number of key extensions into the core API:
All differences in behavior between these extensions and the corresponding Vulkan 1.1 functionality are summarized below.
Differences relative to VK_KHR_16bit_storage
If the VK_KHR_16bit_storage extension is not supported, support for
the storageBuffer16BitAccess
feature is optional.
Support for this feature is defined by
VkPhysicalDevice16BitStorageFeatures::storageBuffer16BitAccess
or VkPhysicalDeviceVulkan11Features::storageBuffer16BitAccess
when queried via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_KHR_sampler_ycbcr_conversion
If the VK_KHR_sampler_ycbcr_conversion extension is not supported,
support for the samplerYcbcrConversion feature is optional.
Support for this feature is defined by
VkPhysicalDeviceSamplerYcbcrConversionFeatures::samplerYcbcrConversion
or VkPhysicalDeviceVulkan11Features::samplerYcbcrConversion
when queried via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_KHR_shader_draw_parameters
If the VK_KHR_shader_draw_parameters extension is not supported,
support for the
SPV_KHR_shader_draw_parameters
SPIR-V extension is optional.
Support for this feature is defined by
VkPhysicalDeviceShaderDrawParametersFeatures::shaderDrawParameters
or VkPhysicalDeviceVulkan11Features::shaderDrawParameters
when queried via vkGetPhysicalDeviceFeatures2.
Differences relative to VK_KHR_variable_pointers
If the VK_KHR_variable_pointers extension is not supported, support
for the variablePointersStorageBuffer feature is optional.
Support for this feature is defined by
VkPhysicalDeviceVariablePointersFeatures::variablePointersStorageBuffer
or
VkPhysicalDeviceVulkan11Features::variablePointersStorageBuffer
when queried via vkGetPhysicalDeviceFeatures2.
Additional Vulkan 1.1 Feature Support
In addition to the promoted extensions described above, Vulkan 1.1 added support for:
-
The group operations and subgroup scope.
-
The protected memory feature.
-
A new command to enumerate the instance version: vkEnumerateInstanceVersion.
-
The VkPhysicalDeviceShaderDrawParametersFeatures feature query struct (where the
VK_KHR_shader_draw_parametersextension did not have one).
New Structures
-
Extending VkBindBufferMemoryInfo:
-
Extending VkBindImageMemoryInfo:
-
Extending VkBindSparseInfo:
-
Extending VkBufferCreateInfo:
-
Extending VkCommandBufferBeginInfo:
-
Extending VkDeviceCreateInfo:
-
Extending VkFenceCreateInfo:
-
Extending VkImageCreateInfo:
-
Extending VkImageFormatProperties2:
-
Extending VkImageMemoryRequirementsInfo2:
-
Extending VkImageViewCreateInfo:
-
Extending VkMemoryAllocateInfo:
-
Extending VkMemoryRequirements2:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceImageFormatInfo2:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineTessellationStateCreateInfo:
-
Extending VkRenderPassBeginInfo, VkRenderingInfo:
-
Extending VkRenderPassCreateInfo:
-
Extending VkSamplerCreateInfo, VkImageViewCreateInfo:
-
Extending VkSemaphoreCreateInfo:
-
Extending VkSubmitInfo:
New Enum Constants
-
VK_LUID_SIZE -
VK_MAX_DEVICE_GROUP_SIZE -
VK_QUEUE_FAMILY_EXTERNAL -
Extending VkBufferCreateFlagBits:
-
VK_BUFFER_CREATE_PROTECTED_BIT
-
-
Extending VkCommandPoolCreateFlagBits:
-
VK_COMMAND_POOL_CREATE_PROTECTED_BIT
-
-
Extending VkDependencyFlagBits:
-
VK_DEPENDENCY_DEVICE_GROUP_BIT -
VK_DEPENDENCY_VIEW_LOCAL_BIT
-
-
Extending VkDeviceQueueCreateFlagBits:
-
VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT
-
-
Extending VkFormat:
-
VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16 -
VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16 -
VK_FORMAT_B16G16R16G16_422_UNORM -
VK_FORMAT_B8G8R8G8_422_UNORM -
VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16 -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16 -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16 -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16 -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16 -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16 -
VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16 -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16 -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16 -
VK_FORMAT_G16B16G16R16_422_UNORM -
VK_FORMAT_G16_B16R16_2PLANE_420_UNORM -
VK_FORMAT_G16_B16R16_2PLANE_422_UNORM -
VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM -
VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM -
VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM -
VK_FORMAT_G8B8G8R8_422_UNORM -
VK_FORMAT_G8_B8R8_2PLANE_420_UNORM -
VK_FORMAT_G8_B8R8_2PLANE_422_UNORM -
VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM -
VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM -
VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM -
VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 -
VK_FORMAT_R10X6G10X6_UNORM_2PACK16 -
VK_FORMAT_R10X6_UNORM_PACK16 -
VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16 -
VK_FORMAT_R12X4G12X4_UNORM_2PACK16 -
VK_FORMAT_R12X4_UNORM_PACK16
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT -
VK_FORMAT_FEATURE_DISJOINT_BIT -
VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT -
VK_FORMAT_FEATURE_TRANSFER_DST_BIT -
VK_FORMAT_FEATURE_TRANSFER_SRC_BIT
-
-
Extending VkImageAspectFlagBits:
-
VK_IMAGE_ASPECT_PLANE_0_BIT -
VK_IMAGE_ASPECT_PLANE_1_BIT -
VK_IMAGE_ASPECT_PLANE_2_BIT
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT -
VK_IMAGE_CREATE_ALIAS_BIT -
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT -
VK_IMAGE_CREATE_DISJOINT_BIT -
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT -
VK_IMAGE_CREATE_PROTECTED_BIT -
VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL
-
-
Extending VkMemoryHeapFlagBits:
-
VK_MEMORY_HEAP_MULTI_INSTANCE_BIT
-
-
Extending VkMemoryPropertyFlagBits:
-
VK_MEMORY_PROPERTY_PROTECTED_BIT
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE -
VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_DISPATCH_BASE -
VK_PIPELINE_CREATE_DISPATCH_BASE_BIT -
VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT
-
-
Extending VkQueueFlagBits:
-
VK_QUEUE_PROTECTED_BIT
-
-
Extending VkResult:
-
VK_ERROR_INVALID_EXTERNAL_HANDLE -
VK_ERROR_OUT_OF_POOL_MEMORY
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO -
VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO -
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO -
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO -
VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO -
VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2 -
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT -
VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO -
VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO -
VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO -
VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO -
VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO -
VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO -
VK_STRUCTURE_TYPE_DEVICE_QUEUE_INFO_2 -
VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO -
VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO -
VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO -
VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES -
VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES -
VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES -
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO -
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO -
VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES -
VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2 -
VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2 -
VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2 -
VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO -
VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2 -
VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO -
VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO -
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO -
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS -
VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2 -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2 -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2 -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2 -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2 -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROTECTED_MEMORY_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROTECTED_MEMORY_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETERS_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETER_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2 -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES -
VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO -
VK_STRUCTURE_TYPE_PROTECTED_SUBMIT_INFO -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2 -
VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO -
VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO -
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO -
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_IMAGE_FORMAT_PROPERTIES -
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO -
VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2 -
VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2
-
Version 1.0
Vulkan Version 1.0 was the initial release of the Vulkan API.
New Structures
-
Extending VkPipelineShaderStageCreateInfo:
New Enum Constants
-
VK_ATTACHMENT_UNUSED -
VK_FALSE -
VK_LOD_CLAMP_NONE -
VK_MAX_DESCRIPTION_SIZE -
VK_MAX_EXTENSION_NAME_SIZE -
VK_MAX_MEMORY_HEAPS -
VK_MAX_MEMORY_TYPES -
VK_MAX_PHYSICAL_DEVICE_NAME_SIZE -
VK_QUEUE_FAMILY_IGNORED -
VK_REMAINING_ARRAY_LAYERS -
VK_REMAINING_MIP_LEVELS -
VK_SUBPASS_EXTERNAL -
VK_TRUE -
VK_UUID_SIZE -
VK_WHOLE_SIZE
Appendix E: Layers & Extensions (Informative)
Extensions to the Vulkan API can be defined by authors, groups of authors, and the Khronos Vulkan Working Group. In order not to compromise the readability of the Vulkan Specification, the core Specification does not incorporate most extensions. The online Registry of extensions is available at URL
and allows generating versions of the Specification incorporating different extensions.
Most of the content previously in this appendix does not specify use of specific Vulkan extensions and layers, but rather specifies the processes by which extensions and layers are created. As of version 1.0.21 of the Vulkan Specification, this content has been migrated to the Vulkan Documentation and Extensions document. Authors creating extensions and layers must follow the mandatory procedures in that document.
The remainder of this appendix documents a set of extensions chosen when this document was built. Versions of the Specification published in the Registry include:
-
Core API + mandatory extensions required of all Vulkan implementations.
-
Core API + all registered and published Khronos (
KHR) extensions. -
Core API + all registered and published extensions.
Extensions are grouped as Khronos KHR, multivendor EXT, and then
alphabetically by author ID.
Within each group, extensions are listed in alphabetical order by their
name.
|
Note
As of the initial Vulkan 1.1 public release, the Some vendors may use an alternate author ID ending in |
List of Current Extensions
VK_KHR_acceleration_structure
- Name String
-
VK_KHR_acceleration_structure - Extension Type
-
Device extension
- Registered Extension Number
-
151
- Revision
-
13
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
Requires
VK_EXT_descriptor_indexingto be enabled for any device-level functionality -
Requires
VK_KHR_buffer_device_addressto be enabled for any device-level functionality -
Requires
VK_KHR_deferred_host_operationsto be enabled for any device-level functionality
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2021-09-30
- Contributors
-
-
Samuel Bourasseau, Adobe
-
Matthäus Chajdas, AMD
-
Greg Grebe, AMD
-
Nicolai Hähnle, AMD
-
Tobias Hector, AMD
-
Dave Oldcorn, AMD
-
Skyler Saleh, AMD
-
Mathieu Robart, Arm
-
Marius Bjorge, Arm
-
Tom Olson, Arm
-
Sebastian Tafuri, EA
-
Henrik Rydgard, Embark
-
Juan Cañada, Epic Games
-
Patrick Kelly, Epic Games
-
Yuriy O’Donnell, Epic Games
-
Michael Doggett, Facebook/Oculus
-
Ricardo Garcia, Igalia
-
Andrew Garrard, Imagination
-
Don Scorgie, Imagination
-
Dae Kim, Imagination
-
Joshua Barczak, Intel
-
Slawek Grajewski, Intel
-
Jeff Bolz, NVIDIA
-
Pascal Gautron, NVIDIA
-
Daniel Koch, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Ashwin Lele, NVIDIA
-
Robert Stepinski, NVIDIA
-
Martin Stich, NVIDIA
-
Nuno Subtil, NVIDIA
-
Eric Werness, NVIDIA
-
Jon Leech, Khronos
-
Jeroen van Schijndel, OTOY
-
Juul Joosten, OTOY
-
Alex Bourd, Qualcomm
-
Roman Larionov, Qualcomm
-
David McAllister, Qualcomm
-
Lewis Gordon, Samsung
-
Ralph Potter, Samsung
-
Jasper Bekkers, Traverse Research
-
Jesse Barker, Unity
-
Baldur Karlsson, Valve
-
Description
In order to be efficient, rendering techniques such as ray tracing need a quick way to identify which primitives may be intersected by a ray traversing the geometries. Acceleration structures are the most common way to represent the geometry spatially sorted, in order to quickly identify such potential intersections.
This extension adds new functionalities:
-
Acceleration structure objects and build commands
-
Structures to describe geometry inputs to acceleration structure builds
-
Acceleration structure copy commands
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkWriteDescriptorSet:
New Enum Constants
-
VK_KHR_ACCELERATION_STRUCTURE_EXTENSION_NAME -
VK_KHR_ACCELERATION_STRUCTURE_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR -
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR -
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR
-
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR_EXT
-
-
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR
-
-
Extending VkIndexType:
-
VK_INDEX_TYPE_NONE_KHR
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR -
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_GEOMETRY_INFO_KHR -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_SIZES_INFO_KHR -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_DEVICE_ADDRESS_INFO_KHR -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_AABBS_DATA_KHR -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_INSTANCES_DATA_KHR -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_KHR -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_TRIANGLES_DATA_KHR -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_INFO_KHR -
VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_INFO_KHR -
VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_TO_MEMORY_INFO_KHR -
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_ACCELERATION_STRUCTURE_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ACCELERATION_STRUCTURE_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ACCELERATION_STRUCTURE_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_KHR
-
If VK_KHR_format_feature_flags2 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR
-
Issues
(1) How does this extension differ from VK_NV_ray_tracing?
DISCUSSION:
The following is a summary of the main functional differences between VK_KHR_acceleration_structure and VK_NV_ray_tracing:
-
added acceleration structure serialization / deserialization (
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR,VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR, vkCmdCopyAccelerationStructureToMemoryKHR, vkCmdCopyMemoryToAccelerationStructureKHR) -
document inactive primitives and instances
-
added VkPhysicalDeviceAccelerationStructureFeaturesKHR structure
-
added indirect and batched acceleration structure builds (vkCmdBuildAccelerationStructuresIndirectKHR)
-
added host acceleration structure commands
-
reworked geometry structures so they could be better shared between device, host, and indirect builds
-
explicitly made VkAccelerationStructureKHR use device addresses
-
added acceleration structure compatibility check function (vkGetDeviceAccelerationStructureCompatibilityKHR)
-
add parameter for requesting memory requirements for host and/or device build
-
added format feature for acceleration structure build vertex formats (
VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR)
(2) Can you give a more detailed comparison of differences and similarities between VK_NV_ray_tracing and VK_KHR_acceleration_structure?
DISCUSSION:
The following is a more detailed comparison of which commands, structures, and enums are aliased, changed, or removed.
-
Aliased functionality — enums, structures, and commands that are considered equivalent:
-
VkAccelerationStructureTypeNV ↔ VkAccelerationStructureTypeKHR
-
VkCopyAccelerationStructureModeNV ↔ VkCopyAccelerationStructureModeKHR
-
VkGeometryInstanceFlagBitsNV ↔ VkGeometryInstanceFlagBitsKHR
-
VkBuildAccelerationStructureFlagsNV ↔ VkBuildAccelerationStructureFlagsKHR
-
VkBuildAccelerationStructureFlagBitsNV ↔ VkBuildAccelerationStructureFlagBitsKHR
-
VkTransformMatrixNV ↔ VkTransformMatrixKHR (added to VK_NV_ray_tracing for descriptive purposes)
-
VkAabbPositionsNV ↔ VkAabbPositionsKHR (added to VK_NV_ray_tracing for descriptive purposes)
-
VkAccelerationStructureInstanceNV ↔ VkAccelerationStructureInstanceKHR (added to VK_NV_ray_tracing for descriptive purposes)
-
Changed enums, structures, and commands:
-
renamed
VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV→VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHRin VkGeometryInstanceFlagBitsKHR -
VkGeometryTrianglesNV → VkAccelerationStructureGeometryTrianglesDataKHR (device or host address instead of buffer+offset)
-
VkGeometryAABBNV → VkAccelerationStructureGeometryAabbsDataKHR (device or host address instead of buffer+offset)
-
VkGeometryDataNV → VkAccelerationStructureGeometryDataKHR (union of triangle/aabbs/instances)
-
VkGeometryNV → VkAccelerationStructureGeometryKHR (changed type of geometry)
-
VkAccelerationStructureCreateInfoNV → VkAccelerationStructureCreateInfoKHR (reshuffle geometry layout/information)
-
VkPhysicalDeviceRayTracingPropertiesNV → VkPhysicalDeviceAccelerationStructurePropertiesKHR (for acceleration structure properties, renamed
maxTriangleCounttomaxPrimitiveCount, added per stage and update after bind limits) and VkPhysicalDeviceRayTracingPipelinePropertiesKHR (for ray tracing pipeline properties) -
VkAccelerationStructureMemoryRequirementsInfoNV (deleted - replaced by allocating on top of VkBuffer)
-
VkWriteDescriptorSetAccelerationStructureNV → VkWriteDescriptorSetAccelerationStructureKHR (different acceleration structure type)
-
vkCreateAccelerationStructureNV → vkCreateAccelerationStructureKHR (device address, different geometry layout/information)
-
vkGetAccelerationStructureMemoryRequirementsNV (deleted - replaced by allocating on top of VkBuffer)
-
vkCmdBuildAccelerationStructureNV → vkCmdBuildAccelerationStructuresKHR (params moved to structs, layout differences)
-
vkCmdCopyAccelerationStructureNV → vkCmdCopyAccelerationStructureKHR (params to struct, extendable)
-
vkGetAccelerationStructureHandleNV → vkGetAccelerationStructureDeviceAddressKHR (device address instead of handle)
-
VkAccelerationStructureMemoryRequirementsTypeNV → size queries for scratch space moved to vkGetAccelerationStructureBuildSizesKHR
-
vkDestroyAccelerationStructureNV → vkDestroyAccelerationStructureKHR (different acceleration structure types)
-
vkCmdWriteAccelerationStructuresPropertiesNV → vkCmdWriteAccelerationStructuresPropertiesKHR (different acceleration structure types)
-
-
Added enums, structures and commands:
-
VK_GEOMETRY_TYPE_INSTANCES_KHRto VkGeometryTypeKHR enum -
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR,VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHRto VkCopyAccelerationStructureModeKHR enum -
VkDeviceOrHostAddressKHR and VkDeviceOrHostAddressConstKHR unions
-
vkBuildAccelerationStructuresKHR command (host build)
-
vkCopyAccelerationStructureKHR command (host copy)
-
vkCopyAccelerationStructureToMemoryKHR (host serialize)
-
vkCopyMemoryToAccelerationStructureKHR (host deserialize)
-
vkWriteAccelerationStructuresPropertiesKHR (host properties)
-
vkCmdCopyAccelerationStructureToMemoryKHR (device serialize)
-
vkCmdCopyMemoryToAccelerationStructureKHR (device deserialize)
-
vkGetDeviceAccelerationStructureCompatibilityKHR (serialization)
-
(3) What are the changes between the public provisional (VK_KHR_ray_tracing v8) release and the internal provisional (VK_KHR_ray_tracing v9) release?
-
added
geometryFlagstoVkAccelerationStructureCreateGeometryTypeInfoKHR(later reworked to obsolete this) -
added
minAccelerationStructureScratchOffsetAlignmentproperty to VkPhysicalDeviceRayTracingPropertiesKHR -
fix naming and return enum from vkGetDeviceAccelerationStructureCompatibilityKHR
-
renamed
VkAccelerationStructureVersionKHRto VkAccelerationStructureVersionInfoKHR -
renamed
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_KHRtoVK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_INFO_KHR -
removed
VK_ERROR_INCOMPATIBLE_VERSION_KHR -
added VkAccelerationStructureCompatibilityKHR enum
-
remove return value from vkGetDeviceAccelerationStructureCompatibilityKHR and added return enum parameter
-
-
Require Vulkan 1.1
-
added creation time capture and replay flags
-
added VkAccelerationStructureCreateFlagBitsKHR and VkAccelerationStructureCreateFlagsKHR
-
renamed the
flagsmember of VkAccelerationStructureCreateInfoKHR tobuildFlags(later removed) and added thecreateFlagsmember
-
-
change vkCmdBuildAccelerationStructuresIndirectKHR to use buffer device address for indirect parameter
-
make
VK_KHR_deferred_host_operationsan interaction instead of a required extension (later went back on this) -
renamed
VkAccelerationStructureBuildOffsetInfoKHRto VkAccelerationStructureBuildRangeInfoKHR-
renamed the
ppOffsetInfosparameter of vkCmdBuildAccelerationStructuresKHR toppBuildRangeInfos
-
-
Re-unify geometry description between build and create
-
remove
VkAccelerationStructureCreateGeometryTypeInfoKHRandVK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_GEOMETRY_TYPE_INFO_KHR -
added
VkAccelerationStructureCreateSizeInfoKHRstructure (later removed) -
change type of the
pGeometryInfosmember of VkAccelerationStructureCreateInfoKHR fromVkAccelerationStructureCreateGeometryTypeInfoKHRto VkAccelerationStructureGeometryKHR (later removed) -
added
pCreateSizeInfosmember to VkAccelerationStructureCreateInfoKHR (later removed)
-
-
Fix ppGeometries ambiguity, add pGeometries
-
remove
geometryArrayOfPointersmember of VkAccelerationStructureBuildGeometryInfoKHR -
disambiguate two meanings of
ppGeometriesby explicitly addingpGeometriesto the VkAccelerationStructureBuildGeometryInfoKHR structure and require one of them beNULL
-
-
added
nullDescriptorsupport for acceleration structures -
changed the
updatemember of VkAccelerationStructureBuildGeometryInfoKHR from a bool to themodeVkBuildAccelerationStructureModeKHR enum which allows future extensibility in update types -
Clarify deferred host ops for pipeline creation
-
VkDeferredOperationKHR is now a top-level parameter for vkBuildAccelerationStructuresKHR, vkCreateRayTracingPipelinesKHR, vkCopyAccelerationStructureToMemoryKHR, vkCopyAccelerationStructureKHR, and vkCopyMemoryToAccelerationStructureKHR
-
removed
VkDeferredOperationInfoKHRstructure -
change deferred host creation/return parameter behavior such that the implementation can modify such parameters until the deferred host operation completes
-
VK_KHR_deferred_host_operationsis required again
-
-
Change acceleration structure build to always be sized
-
de-alias
VkAccelerationStructureMemoryRequirementsTypeNVandVkAccelerationStructureMemoryRequirementsTypeKHR, and removeVkAccelerationStructureMemoryRequirementsTypeKHR -
add vkGetAccelerationStructureBuildSizesKHR command and VkAccelerationStructureBuildSizesInfoKHR structure and
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_SIZES_INFO_KHRenum to query sizes for acceleration structures and scratch storage -
move size queries for scratch space to vkGetAccelerationStructureBuildSizesKHR
-
remove
compactedSize,buildFlags,maxGeometryCount,pGeometryInfos,pCreateSizeInfosmembers of VkAccelerationStructureCreateInfoKHR and add thesizemember -
add
maxVertexmember to VkAccelerationStructureGeometryTrianglesDataKHR structure -
remove
VkAccelerationStructureCreateSizeInfoKHRstructure
-
(4) What are the changes between the internal provisional (VK_KHR_ray_tracing v9) release and the final (VK_KHR_acceleration_structure v11) release?
-
refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation flexibility and decoupling ray query support from ray pipelines:
-
VK_KHR_acceleration_structure(for acceleration structure operations) -
VK_KHR_ray_tracing_pipeline(for ray tracing pipeline and shader stages) -
VK_KHR_ray_query(for ray queries in existing shader stages)
-
-
clarify buffer usage flags for ray tracing
-
VK_BUFFER_USAGE_RAY_TRACING_BIT_NVis left alone inVK_NV_ray_tracing(required onscratchandinstanceData) -
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHRis added as an alias ofVK_BUFFER_USAGE_RAY_TRACING_BIT_NVinVK_KHR_ray_tracing_pipelineand is required on shader binding table buffers -
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHRis added inVK_KHR_acceleration_structurefor all vertex, index, transform, aabb, and instance buffer data referenced by device build commands -
VK_BUFFER_USAGE_STORAGE_BUFFER_BITis used forscratchData
-
-
add max primitive counts (
ppMaxPrimitiveCounts) to vkCmdBuildAccelerationStructuresIndirectKHR -
Allocate acceleration structures from
VkBuffersand add a mode to constrain the device address-
de-alias
VkBindAccelerationStructureMemoryInfoNVandvkBindAccelerationStructureMemoryNV, and removeVkBindAccelerationStructureMemoryInfoKHR,VkAccelerationStructureMemoryRequirementsInfoKHR, andvkGetAccelerationStructureMemoryRequirementsKHR -
acceleration structures now take a VkBuffer and offset at creation time for memory placement
-
add a new
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHRbuffer usage for such buffers -
add a new
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHRacceleration structure type for layering
-
-
move
VK_GEOMETRY_TYPE_INSTANCES_KHRto main enum instead of being added via extension -
make build commands more consistent - all now build multiple acceleration structures and are named plurally (vkCmdBuildAccelerationStructuresIndirectKHR, vkCmdBuildAccelerationStructuresKHR, vkBuildAccelerationStructuresKHR)
-
add interactions with
VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITfor acceleration structures, including a new feature (descriptorBindingAccelerationStructureUpdateAfterBind) and 3 new properties (maxPerStageDescriptorAccelerationStructures,maxPerStageDescriptorUpdateAfterBindAccelerationStructures,maxDescriptorSetUpdateAfterBindAccelerationStructures) -
extension is no longer provisional
-
define synchronization requirements for builds, traces, and copies
-
define synchronization requirements for AS build inputs and indirect build buffer
(5) What is VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR for?
RESOLVED: It is primarily intended for API layering. In DXR, the acceleration structure is basically just a buffer in a special layout, and you do not know at creation time whether it will be used as a top or bottom level acceleration structure. We thus added a generic acceleration structure type whose type is unknown at creation time, but is specified at build time instead. Applications which are written directly for Vulkan should not use it.
Version History
-
Revision 1, 2019-12-05 (Members of the Vulkan Ray Tracing TSG)
-
Internal revisions (forked from VK_NV_ray_tracing)
-
-
Revision 2, 2019-12-20 (Daniel Koch, Eric Werness)
-
Add const version of DeviceOrHostAddress (!3515)
-
Add VU to clarify that only handles in the current pipeline are valid (!3518)
-
Restore some missing VUs and add in-place update language (#1902, !3522)
-
rename VkAccelerationStructureInstanceKHR member from accelerationStructure to accelerationStructureReference to better match its type (!3523)
-
Allow VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS for pipeline creation if shader group handles cannot be reused (!3523)
-
update documentation for the VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error code and add missing documentation for new return codes from VK_KHR_deferred_host_operations (!3523)
-
list new query types for VK_KHR_ray_tracing (!3523)
-
Fix VU statements for VkAccelerationStructureGeometryKHR referring to correct union members and update to use more current wording (!3523)
-
-
Revision 3, 2020-01-10 (Daniel Koch, Jon Leech, Christoph Kubisch)
-
Fix 'instance of' and 'that/which contains/defines' markup issues (!3528)
-
factor out VK_KHR_pipeline_library as stand-alone extension (!3540)
-
Resolve Vulkan-hpp issues (!3543)
-
add missing require for VkGeometryInstanceFlagsKHR
-
de-alias VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV since the KHR structure is no longer equivalent
-
add len to pDataSize attribute for vkWriteAccelerationStructuresPropertiesKHR
-
-
-
Revision 4, 2020-01-23 (Daniel Koch, Eric Werness)
-
Improve vkWriteAccelerationStructuresPropertiesKHR, add return value and VUs (#1947)
-
Clarify language to allow multiple raygen shaders (#1959)
-
Various editorial feedback (!3556)
-
Add language to help deal with looped self-intersecting fans (#1901)
-
Change vkCmdTraceRays{Indirect}KHR args to pointers (!3559)
-
Add scratch address validation language (#1941, !3551)
-
Fix definition and add hierarchy information for shader call scope (#1977, !3571)
-
-
Revision 5, 2020-02-04 (Eric Werness, Jeff Bolz, Daniel Koch)
-
remove vestigial accelerationStructureUUID (!3582)
-
update definition of repack instructions and improve memory model interactions (#1910, #1913, !3584)
-
Fix wrong sType for VkPhysicalDeviceRayTracingFeaturesKHR (#1988)
-
Use provisional SPIR-V capabilities (#1987)
-
require rayTraversalPrimitiveCulling if rayQuery is supported (#1927)
-
Miss shaders do not have object parameters (!3592)
-
Fix missing required types in XML (!3592)
-
clarify matching conditions for update (!3592)
-
add goal that host and device builds be similar (!3592)
-
clarify that
maxPrimitiveCountlimit should apply to triangles and AABBs (!3592) -
Require alignment for instance arrayOfPointers (!3592)
-
Zero is a valid value for instance flags (!3592)
-
Add some alignment VUs that got lost in refactoring (!3592)
-
Recommend TMin epsilon rather than culling (!3592)
-
Get angle from dot product not cross product (!3592)
-
Clarify that AH can access the payload and attributes (!3592)
-
Match DXR behavior for inactive primitive definition (!3592)
-
Use a more generic term than degenerate for inactive to avoid confusion (!3592)
-
-
Revision 6, 2020-02-20 (Daniel Koch)
-
fix some dangling NV references (#1996)
-
rename VkCmdTraceRaysIndirectCommandKHR to VkTraceRaysIndirectCommandKHR (!3607)
-
update contributor list (!3611)
-
use uint64_t instead of VkAccelerationStructureReferenceKHR in VkAccelerationStructureInstanceKHR (#2004)
-
-
Revision 7, 2020-02-28 (Tobias Hector)
-
remove HitTKHR SPIR-V builtin (spirv/spirv-extensions#7)
-
-
Revision 8, 2020-03-06 (Tobias Hector, Dae Kim, Daniel Koch, Jeff Bolz, Eric Werness)
-
explicitly state that Tmax is updated when new closest intersection is accepted (#2020,!3536)
-
Made references to min and max t values consistent (!3644)
-
finish enumerating differences relative to VK_NV_ray_tracing in issues (1) and (2) (#1974,!3642)
-
fix formatting in some math equations (!3642)
-
Restrict the Hit Kind operand of
OpReportIntersectionKHRto 7-bits (spirv/spirv-extensions#8,!3646) -
Say ray tracing 'should' be watertight (#2008,!3631)
-
Clarify memory requirements for ray tracing buffers (#2005,!3649)
-
Add callable size limits (#1997,!3652)
-
-
Revision 9, 2020-04-15 (Eric Werness, Daniel Koch, Tobias Hector, Joshua Barczak)
-
Add geometry flags to acceleration structure creation (!3672)
-
add build scratch memory alignment (minAccelerationStructureScratchOffsetAlignment) (#2065,!3725)
-
fix naming and return enum from vkGetDeviceAccelerationStructureCompatibilityKHR (#2051,!3726)
-
require SPIR-V 1.4 (#2096,!3777)
-
added creation time capture/replay flags (#2104,!3774)
-
require Vulkan 1.1 (#2133,!3806)
-
use device addresses instead of VkBuffers for ray tracing commands (#2074,!3815)
-
add interactions with Vulkan 1.2 and VK_KHR_vulkan_memory_model (#2133,!3830)
-
make VK_KHR_pipeline_library an interaction instead of required (#2045,#2108,!3830)
-
make VK_KHR_deferred_host_operations an interaction instead of required (#2045,!3830)
-
removed maxCallableSize and added explicit stack size management for ray pipelines (#1997,!3817,!3772,!3844)
-
improved documentation for VkAccelerationStructureVersionInfoKHR (#2135,3835)
-
rename VkAccelerationStructureBuildOffsetInfoKHR to VkAccelerationStructureBuildRangeInfoKHR (#2058,!3754)
-
Re-unify geometry description between build and create (!3754)
-
Fix ppGeometries ambiguity, add pGeometries (#2032,!3811)
-
add interactions with VK_EXT_robustness2 and allow nullDescriptor support for acceleration structures (#1920,!3848)
-
added future extensibility for AS updates (#2114,!3849)
-
Fix VU for dispatchrays and add a limit on the size of the full grid (#2160,!3851)
-
Add shaderGroupHandleAlignment property (#2180,!3875)
-
Clarify deferred host ops for pipeline creation (#2067,!3813)
-
Change acceleration structure build to always be sized (#2131,#2197,#2198,!3854,!3883,!3880)
-
-
Revision 10, 2020-07-03 (Mathieu Robart, Daniel Koch, Eric Werness, Tobias Hector)
-
Decomposition of the specification, from VK_KHR_ray_tracing to VK_KHR_acceleration_structure (#1918,!3912)
-
clarify buffer usage flags for ray tracing (#2181,!3939)
-
add max primitive counts to build indirect command (#2233,!3944)
-
Allocate acceleration structures from VkBuffers and add a mode to constrain the device address (#2131,!3936)
-
Move VK_GEOMETRY_TYPE_INSTANCES_KHR to main enum (#2243,!3952)
-
make build commands more consistent (#2247,!3958)
-
add interactions with UPDATE_AFTER_BIND (#2128,!3986)
-
correct and expand build command VUs (!4020)
-
fix copy command VUs (!4018)
-
added various alignment requirements (#2229,!3943)
-
fix valid usage for arrays of geometryCount items (#2198,!4010)
-
define what is allowed to change on RTAS updates and relevant VUs (#2177,!3961)
-
-
Revision 11, 2020-11-12 (Eric Werness, Josh Barczak, Daniel Koch, Tobias Hector)
-
de-alias NV and KHR acceleration structure types and associated commands (#2271,!4035)
-
specify alignment for host copy commands (#2273,!4037)
-
document
VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR -
specify that acceleration structures are non-linear (#2289,!4068)
-
add several missing VUs for strides, vertexFormat, and indexType (#2315,!4069)
-
restore VUs for VkAccelerationStructureBuildGeometryInfoKHR (#2337,!4098)
-
ban multi-instance memory for host operations (#2324,!4102)
-
allow dstAccelerationStructure to be null for vkGetAccelerationStructureBuildSizesKHR (#2330,!4111)
-
more build VU cleanup (#2138,#4130)
-
specify host endianness for AS serialization (#2261,!4136)
-
add invertible transform matrix VU (#1710,!4140)
-
require geometryCount to be 1 for TLAS builds (!4145)
-
improved validity conditions for build addresses (#4142)
-
add single statement SPIR-V VUs, build limit VUs (!4158)
-
document limits for vertex and aabb strides (#2390,!4184)
-
specify that
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHRapplies to AS copies (#2382,#4173) -
define sync for AS build inputs and indirect buffer (#2407,!4208)
-
-
Revision 12, 2021-08-06 (Samuel Bourasseau)
-
rename VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR to VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHR (keep previous as alias).
-
Clarify description and add note.
-
-
Revision 13, 2021-09-30 (Jon Leech)
-
Add interaction with
VK_KHR_format_feature_flags2tovk.xml
-
VK_KHR_android_surface
- Name String
-
VK_KHR_android_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
9
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2016-01-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_android_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) that refers to an
ANativeWindow, Android’s native surface type.
The ANativeWindow represents the producer endpoint of any buffer
queue, regardless of consumer endpoint.
Common consumer endpoints for ANativeWindows are the system window
compositor, video encoders, and application-specific compositors importing
the images through a SurfaceTexture.
New Enum Constants
-
VK_KHR_ANDROID_SURFACE_EXTENSION_NAME -
VK_KHR_ANDROID_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does Android need a way to query for compatibility between a particular physical device (and queue family?) and a specific Android display?
RESOLVED: No. Currently on Android, any physical device is expected to be able to present to the system compositor, and all queue families must support the necessary image layout transitions and synchronization operations.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft.
-
-
Revision 2, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_android_surface to VK_KHR_android_surface.
-
-
Revision 3, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to surface creation function.
-
-
Revision 4, 2015-11-10 (Jesse Hall)
-
Removed VK_ERROR_INVALID_ANDROID_WINDOW_KHR.
-
-
Revision 5, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
-
Revision 6, 2016-01-14 (James Jones)
-
Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface to the VK_KHR_surface extension.
-
VK_KHR_deferred_host_operations
- Name String
-
VK_KHR_deferred_host_operations - Extension Type
-
Device extension
- Registered Extension Number
-
269
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Josh Barczak jbarczak
-
Other Extension Metadata
- Last Modified Date
-
2020-11-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Barczak, Intel
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Slawek Grajewski, Intel
-
Tobias Hector, AMD
-
Yuriy O’Donnell, Epic
-
Eric Werness, NVIDIA
-
Baldur Karlsson, Valve
-
Jesse Barker, Unity
-
Contributors to VK_KHR_acceleration_structure, VK_KHR_ray_tracing_pipeline
-
Description
The VK_KHR_deferred_host_operations extension defines the
infrastructure and usage patterns for deferrable commands, but does not
specify any commands as deferrable.
This is left to additional dependent extensions.
Commands must not be deferred unless the deferral is specifically allowed
by another extension which depends on
VK_KHR_deferred_host_operations.
New Enum Constants
-
VK_KHR_DEFERRED_HOST_OPERATIONS_EXTENSION_NAME -
VK_KHR_DEFERRED_HOST_OPERATIONS_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR
-
-
Extending VkResult:
-
VK_OPERATION_DEFERRED_KHR -
VK_OPERATION_NOT_DEFERRED_KHR -
VK_THREAD_DONE_KHR -
VK_THREAD_IDLE_KHR
-
Code Examples
The following examples will illustrate the concept of deferrable operations
using a hypothetical example.
The command vkDoSomethingExpensive denotes a deferrable command.
The following example illustrates how a vulkan application might request deferral of an expensive operation:
// create a deferred operation
VkDeferredOperationKHR hOp;
VkResult result = vkCreateDeferredOperationKHR(device, pCallbacks, &hOp);
assert(result == VK_SUCCESS);
result = vkDoSomethingExpensive(device, hOp, ...);
assert( result == VK_OPERATION_DEFERRED_KHR );
// operation was deferred. Execute it asynchronously
std::async::launch(
[ hOp ] ( )
{
vkDeferredOperationJoinKHR(device, hOp);
result = vkGetDeferredOperationResultKHR(device, hOp);
// deferred operation is now complete. 'result' indicates success or failure
vkDestroyDeferredOperationKHR(device, hOp, pCallbacks);
}
);
The following example illustrates extracting concurrency from a single deferred operation:
// create a deferred operation
VkDeferredOperationKHR hOp;
VkResult result = vkCreateDeferredOperationKHR(device, pCallbacks, &hOp);
assert(result == VK_SUCCESS);
result = vkDoSomethingExpensive(device, hOp, ...);
assert( result == VK_OPERATION_DEFERRED_KHR );
// Query the maximum amount of concurrency and clamp to the desired maximum
uint32_t numLaunches = std::min(vkGetDeferredOperationMaxConcurrencyKHR(device, hOp), maxThreads);
std::vector<std::future<void> > joins;
for (uint32_t i = 0; i < numLaunches; i++) {
joins.emplace_back(std::async::launch(
[ hOp ] ( )
{
vkDeferredOperationJoinKHR(device, hOp);
// in a job system, a return of VK_THREAD_IDLE_KHR should queue another
// job, but it is not functionally required
}
));
}
for (auto &f : joins) {
f.get();
}
result = vkGetDeferredOperationResultKHR(device, hOp);
// deferred operation is now complete. 'result' indicates success or failure
vkDestroyDeferredOperationKHR(device, hOp, pCallbacks);
The following example shows a subroutine which guarantees completion of a deferred operation, in the presence of multiple worker threads, and returns the result of the operation.
VkResult FinishDeferredOperation(VkDeferredOperationKHR hOp)
{
// Attempt to join the operation until the implementation indicates that we should stop
VkResult result = vkDeferredOperationJoinKHR(device, hOp);
while( result == VK_THREAD_IDLE_KHR )
{
std::this_thread::yield();
result = vkDeferredOperationJoinKHR(device, hOp);
}
switch( result )
{
case VK_SUCCESS:
{
// deferred operation has finished. Query its result
result = vkGetDeferredOperationResultKHR(device, hOp);
}
break;
case VK_THREAD_DONE_KHR:
{
// deferred operation is being wrapped up by another thread
// wait for that thread to finish
do
{
std::this_thread::yield();
result = vkGetDeferredOperationResultKHR(device, hOp);
} while( result == VK_NOT_READY );
}
break;
default:
assert(false); // other conditions are illegal.
break;
}
return result;
}
Issues
-
Should this extension have a VkPhysicalDevice*FeaturesKHR structure?
RESOLVED: No. This extension does not add any functionality on its own and requires a dependent extension to actually enable functionality and thus there is no value in adding a feature structure. If necessary, any dependent extension could add a feature boolean if it wanted to indicate that it is adding optional deferral support.
Version History
-
Revision 1, 2019-12-05 (Josh Barczak, Daniel Koch)
-
Initial draft.
-
-
Revision 2, 2020-03-06 (Daniel Koch, Tobias Hector)
-
Add missing VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR enum
-
fix sample code
-
Clarified deferred operation parameter lifetimes (#2018,!3647)
-
-
Revision 3, 2020-05-15 (Josh Barczak)
-
Clarify behavior of vkGetDeferredOperationMaxConcurrencyKHR, allowing it to return 0 if the operation is complete (#2036,!3850)
-
-
Revision 4, 2020-11-12 (Tobias Hector, Daniel Koch)
-
Remove VkDeferredOperationInfoKHR and change return value semantics when deferred host operations are in use (#2067,3813)
-
clarify return value of vkGetDeferredOperationResultKHR (#2339,!4110)
-
VK_KHR_display
- Name String
-
VK_KHR_display - Extension Type
-
Instance extension
- Registered Extension Number
-
3
- Revision
-
23
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
Other Extension Metadata
- Last Modified Date
-
2017-03-13
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Norbert Nopper, Freescale
-
Jeff Vigil, Qualcomm
-
Daniel Rakos, AMD
-
Description
This extension provides the API to enumerate displays and available modes on a given device.
New Enum Constants
-
VK_KHR_DISPLAY_EXTENSION_NAME -
VK_KHR_DISPLAY_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_DISPLAY_KHR -
VK_OBJECT_TYPE_DISPLAY_MODE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR
-
Issues
1) Which properties of a mode should be fixed in the mode information vs. settable in some other function when setting the mode? E.g., do we need to double the size of the mode pool to include both stereo and non-stereo modes? YUV and RGB scanout even if they both take RGB input images? BGR vs. RGB input? etc.
PROPOSED RESOLUTION: Many modern displays support at most a handful of resolutions and timings natively. Other “modes” are expected to be supported using scaling hardware on the display engine or GPU. Other properties, such as rotation and mirroring should not require duplicating hardware modes just to express all combinations. Further, these properties may be implemented on a per-display or per-overlay granularity.
To avoid the exponential growth of modes as mutable properties are added, as
was the case with EGLConfig/WGL pixel formats/GLXFBConfig, this
specification should separate out hardware properties and configurable state
into separate objects.
Modes and overlay planes will express capabilities of the hardware, while a
separate structure will allow applications to configure scaling, rotation,
mirroring, color keys, LUT values, alpha masks, etc.
for a given swapchain independent of the mode in use.
Constraints on these settings will be established by properties of the
immutable objects.
Note the resolution of this issue may affect issue 5 as well.
2) What properties of a display itself are useful?
PROPOSED RESOLUTION: This issue is too broad. It was meant to prompt general discussion, but resolving this issue amounts to completing this specification. All interesting properties should be included. The issue will remain as a placeholder since removing it would make it hard to parse existing discussion notes that refer to issues by number.
3) How are multiple overlay planes within a display or mode enumerated?
PROPOSED RESOLUTION: They are referred to by an index. Each display will report the number of overlay planes it contains.
4) Should swapchains be created relative to a mode or a display?
PROPOSED RESOLUTION: When using this extension, swapchains are created relative to a mode and a plane. The mode implies the display object the swapchain will present to. If the specified mode is not the display’s current mode, the new mode will be applied when the first image is presented to the swapchain, and the default operating system mode, if any, will be restored when the swapchain is destroyed.
5) Should users query generic ranges from displays and construct their own modes explicitly using those constraints rather than querying a fixed set of modes (Most monitors only have one real “mode” these days, even though many support relatively arbitrary scaling, either on the monitor side or in the GPU display engine, making “modes” something of a relic/compatibility construct).
PROPOSED RESOLUTION: Expose both. Display information structures will expose a set of predefined modes, as well as any attributes necessary to construct a customized mode.
6) Is it fine if we return the display and display mode handles in the structure used to query their properties?
PROPOSED RESOLUTION: Yes.
7) Is there a possibility that not all displays of a device work with all of the present queues of a device? If yes, how do we determine which displays work with which present queues?
PROPOSED RESOLUTION: No known hardware has such limitations, but
determining such limitations is supported automatically using the existing
VK_KHR_surface and VK_KHR_swapchain query mechanisms.
8) Should all presentation need to be done relative to an overlay plane, or can a display mode + display be used alone to target an output?
PROPOSED RESOLUTION: Require specifying a plane explicitly.
9) Should displays have an associated window system display, such as an
HDC or Display*?
PROPOSED RESOLUTION: No.
Displays are independent of any windowing system in use on the system.
Further, neither HDC nor Display* refer to a physical display
object.
10) Are displays queried from a physical GPU or from a device instance?
PROPOSED RESOLUTION: Developers prefer to query modes directly from the physical GPU so they can use display information as an input to their device selection algorithms prior to device creation. This avoids the need to create placeholder device instances to enumerate displays.
This preference must be weighed against the extra initialization that must be done by driver vendors prior to device instance creation to support this usage.
11) Should displays and/or modes be dispatchable objects? If functions are to take displays, overlays, or modes as their first parameter, they must be dispatchable objects as defined in Khronos bug 13529. If they are not added to the list of dispatchable objects, functions operating on them must take some higher-level object as their first parameter. There is no performance case against making them dispatchable objects, but they would be the first extension objects to be dispatchable.
PROPOSED RESOLUTION: Do not make displays or modes dispatchable. They will dispatch based on their associated physical device.
12) Should hardware cursor capabilities be exposed?
PROPOSED RESOLUTION: Defer. This could be a separate extension on top of the base WSI specs.
|
editing-note
There appears to be a missing sentence for the first part of issue 13 here. |
if they are one physical display device to an end user, but may internally be implemented as two side-by-side displays using the same display engine (and sometimes cabling) resources as two physically separate display devices.
RESOLVED: Tiled displays will appear as a single display object in this API.
14) Should the raw EDID data be included in the display information?
RESOLVED: No. A future extension could be added which reports the EDID if necessary. This may be complicated by the outcome of issue 13.
15) Should min and max scaling factor capabilities of overlays be exposed?
RESOLVED: Yes. This is exposed indirectly by allowing applications to query the min/max position and extent of the source and destination regions from which image contents are fetched by the display engine when using a particular mode and overlay pair.
16) Should devices be able to expose planes that can be moved between displays? If so, how?
RESOLVED: Yes. Applications can determine which displays a given plane supports using vkGetDisplayPlaneSupportedDisplaysKHR.
17) Should there be a way to destroy display modes? If so, does it support destroying “built in” modes?
RESOLVED: Not in this extension. A future extension could add this functionality.
18) What should the lifetime of display and built-in display mode objects be?
RESOLVED: The lifetime of the instance. These objects cannot be destroyed. A future extension may be added to expose a way to destroy these objects and/or support display hotplug.
19) Should persistent mode for smart panels be enabled/disabled at swapchain creation time, or on a per-present basis.
RESOLVED: On a per-present basis.
Examples
|
Note
The example code for the |
Version History
-
Revision 1, 2015-02-24 (James Jones)
-
Initial draft
-
-
Revision 2, 2015-03-12 (Norbert Nopper)
-
Added overlay enumeration for a display.
-
-
Revision 3, 2015-03-17 (Norbert Nopper)
-
Fixed typos and namings as discussed in Bugzilla.
-
Reordered and grouped functions.
-
Added functions to query count of display, mode and overlay.
-
Added native display handle, which may be needed on some platforms to create a native Window.
-
-
Revision 4, 2015-03-18 (Norbert Nopper)
-
Removed primary and virtualPostion members (see comment of James Jones in Bugzilla).
-
Added native overlay handle to information structure.
-
Replaced , with ; in struct.
-
-
Revision 6, 2015-03-18 (Daniel Rakos)
-
Added WSI extension suffix to all items.
-
Made the whole API more “Vulkanish”.
-
Replaced all functions with a single vkGetDisplayInfoKHR function to better match the rest of the API.
-
Made the display, display mode, and overlay objects be first class objects, not subclasses of VkBaseObject as they do not support the common functions anyways.
-
Renamed *Info structures to *Properties.
-
Removed overlayIndex field from VkOverlayProperties as there is an implicit index already as a result of moving to a “Vulkanish” API.
-
Displays are not get through device, but through physical GPU to match the rest of the Vulkan API. Also this is something ISVs explicitly requested.
-
Added issue (6) and (7).
-
-
Revision 7, 2015-03-25 (James Jones)
-
Added an issues section
-
Added rotation and mirroring flags
-
-
Revision 8, 2015-03-25 (James Jones)
-
Combined the duplicate issues sections introduced in last change.
-
Added proposed resolutions to several issues.
-
-
Revision 9, 2015-04-01 (Daniel Rakos)
-
Rebased extension against Vulkan 0.82.0
-
-
Revision 10, 2015-04-01 (James Jones)
-
Added issues (10) and (11).
-
Added more straw-man issue resolutions, and cleaned up the proposed resolution for issue (4).
-
Updated the rotation and mirroring enums to have proper bitmask semantics.
-
-
Revision 11, 2015-04-15 (James Jones)
-
Added proposed resolution for issues (1) and (2).
-
Added issues (12), (13), (14), and (15)
-
Removed pNativeHandle field from overlay structure.
-
Fixed small compilation errors in example code.
-
-
Revision 12, 2015-07-29 (James Jones)
-
Rewrote the guts of the extension against the latest WSI swapchain specifications and the latest Vulkan API.
-
Address overlay planes by their index rather than an object handle and refer to them as “planes” rather than “overlays” to make it slightly clearer that even a display with no “overlays” still has at least one base “plane” that images can be displayed on.
-
Updated most of the issues.
-
Added an “extension type” section to the specification header.
-
Re-used the VK_EXT_KHR_surface surface transform enumerations rather than redefining them here.
-
Updated the example code to use the new semantics.
-
-
Revision 13, 2015-08-21 (Ian Elliott)
-
Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.
-
Switched from “revision” to “version”, including use of the VK_MAKE_VERSION macro in the header file.
-
-
Revision 14, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 15, 2015-09-08 (James Jones)
-
Added alpha flags enum.
-
Added premultiplied alpha support.
-
-
Revision 16, 2015-09-08 (James Jones)
-
Added description section to the spec.
-
Added issues 16 - 18.
-
-
Revision 17, 2015-10-02 (James Jones)
-
Planes are now a property of the entire device rather than individual displays. This allows planes to be moved between multiple displays on devices that support it.
-
Added a function to create a VkSurfaceKHR object describing a display plane and mode to align with the new per-platform surface creation conventions.
-
Removed detailed mode timing data. It was agreed that the mode extents and refresh rate are sufficient for current use cases. Other information could be added back in as an extension if it is needed in the future.
-
Added support for smart/persistent/buffered display devices.
-
-
Revision 18, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_display to VK_KHR_display.
-
-
Revision 19, 2015-11-02 (James Jones)
-
Updated example code to match revision 17 changes.
-
-
Revision 20, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to creation functions.
-
-
Revision 21, 2015-11-10 (Jesse Hall)
-
Added VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR, and use VkDisplayPlaneAlphaFlagBitsKHR for VkDisplayPlanePropertiesKHR::alphaMode instead of VkDisplayPlaneAlphaFlagsKHR, since it only represents one mode.
-
Added reserved flags bitmask to VkDisplayPlanePropertiesKHR.
-
Use VkSurfaceTransformFlagBitsKHR instead of obsolete VkSurfaceTransformKHR.
-
Renamed vkGetDisplayPlaneSupportedDisplaysKHR parameters for clarity.
-
-
Revision 22, 2015-12-18 (James Jones)
-
Added missing “planeIndex” parameter to vkGetDisplayPlaneSupportedDisplaysKHR()
-
-
Revision 23, 2017-03-13 (James Jones)
-
Closed all remaining issues. The specification and implementations have been shipping with the proposed resolutions for some time now.
-
Removed the sample code and noted it has been integrated into the official Vulkan SDK cube demo.
-
VK_KHR_display_swapchain
- Name String
-
VK_KHR_display_swapchain - Extension Type
-
Device extension
- Registered Extension Number
-
4
- Revision
-
10
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality -
Requires
VK_KHR_displayto be enabled for any device-level functionality
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2017-03-13
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Vigil, Qualcomm
-
Jesse Hall, Google
-
Description
This extension provides an API to create a swapchain directly on a device’s display without any underlying window system.
New Structures
-
Extending VkPresentInfoKHR:
New Enum Constants
-
VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME -
VK_KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION -
Extending VkResult:
-
VK_ERROR_INCOMPATIBLE_DISPLAY_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR
-
Issues
1) Should swapchains sharing images each hold a reference to the images, or should it be up to the application to destroy the swapchains and images in an order that avoids the need for reference counting?
RESOLVED: Take a reference. The lifetime of presentable images is already complex enough.
2) Should the srcRect and dstRect parameters be specified as
part of the presentation command, or at swapchain creation time?
RESOLVED: As part of the presentation command. This allows moving and scaling the image on the screen without the need to respecify the mode or create a new swapchain and presentable images.
3) Should srcRect and dstRect be specified as rects, or separate
offset/extent values?
RESOLVED: As rects. Specifying them separately might make it easier for hardware to expose support for one but not the other, but in such cases applications must just take care to obey the reported capabilities and not use non-zero offsets or extents that require scaling, as appropriate.
4) How can applications create multiple swapchains that use the same images?
RESOLVED: By calling vkCreateSharedSwapchainsKHR.
An earlier resolution used vkCreateSwapchainKHR, chaining multiple
VkSwapchainCreateInfoKHR structures through pNext.
In order to allow each swapchain to also allow other extension structs, a
level of indirection was used: VkSwapchainCreateInfoKHR::pNext
pointed to a different structure, which had both sType and pNext
members for additional extensions, and also had a pointer to the next
VkSwapchainCreateInfoKHR structure.
The number of swapchains to be created could only be found by walking this
linked list of alternating structures, and the pSwapchains out
parameter was reinterpreted to be an array of VkSwapchainKHR handles.
Another option considered was a method to specify a “shared” swapchain when creating a new swapchain, such that groups of swapchains using the same images could be built up one at a time. This was deemed unusable because drivers need to know all of the displays an image will be used on when determining which internal formats and layouts to use for that image.
Examples
|
Note
The example code for the |
Version History
-
Revision 1, 2015-07-29 (James Jones)
-
Initial draft
-
-
Revision 2, 2015-08-21 (Ian Elliott)
-
Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.
-
Switched from “revision” to “version”, including use of the VK_MAKE_VERSION macro in the header file.
-
-
Revision 3, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 4, 2015-09-08 (James Jones)
-
Allow creating multiple swap chains that share the same images using a single call to vkCreateSwapchainKHR().
-
-
Revision 5, 2015-09-10 (Alon Or-bach)
-
Removed underscores from SWAP_CHAIN in two enums.
-
-
Revision 6, 2015-10-02 (James Jones)
-
Added support for smart panels/buffered displays.
-
-
Revision 7, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_display_swapchain to VK_KHR_display_swapchain.
-
-
Revision 8, 2015-11-03 (Daniel Rakos)
-
Updated sample code based on the changes to VK_KHR_swapchain.
-
-
Revision 9, 2015-11-10 (Jesse Hall)
-
Replaced VkDisplaySwapchainCreateInfoKHR with vkCreateSharedSwapchainsKHR, changing resolution of issue #4.
-
-
Revision 10, 2017-03-13 (James Jones)
-
Closed all remaining issues. The specification and implementations have been shipping with the proposed resolutions for some time now.
-
Removed the sample code and noted it has been integrated into the official Vulkan SDK cube demo.
-
VK_KHR_external_fence_fd
- Name String
-
VK_KHR_external_fence_fd - Extension Type
-
Device extension
- Registered Extension Number
-
116
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_fenceto be enabled for any device-level functionality
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2017-05-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Cass Everitt, Oculus
-
Contributors to
VK_KHR_external_semaphore_fd
-
Description
An application using external memory may wish to synchronize access to that memory using fences. This extension enables an application to export fence payload to and import fence payload from POSIX file descriptors.
New Enum Constants
-
VK_KHR_EXTERNAL_FENCE_FD_EXTENSION_NAME -
VK_KHR_EXTERNAL_FENCE_FD_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FENCE_GET_FD_INFO_KHR -
VK_STRUCTURE_TYPE_IMPORT_FENCE_FD_INFO_KHR
-
Issues
This extension borrows concepts, semantics, and language from
VK_KHR_external_semaphore_fd.
That extension’s issues apply equally to this extension.
VK_KHR_external_fence_win32
- Name String
-
VK_KHR_external_fence_win32 - Extension Type
-
Device extension
- Registered Extension Number
-
115
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_fenceto be enabled for any device-level functionality
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2017-05-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Cass Everitt, Oculus
-
Contributors to
VK_KHR_external_semaphore_win32
-
Description
An application using external memory may wish to synchronize access to that memory using fences. This extension enables an application to export fence payload to and import fence payload from Windows handles.
New Enum Constants
-
VK_KHR_EXTERNAL_FENCE_WIN32_EXTENSION_NAME -
VK_KHR_EXTERNAL_FENCE_WIN32_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_FENCE_WIN32_HANDLE_INFO_KHR -
VK_STRUCTURE_TYPE_FENCE_GET_WIN32_HANDLE_INFO_KHR -
VK_STRUCTURE_TYPE_IMPORT_FENCE_WIN32_HANDLE_INFO_KHR
-
Issues
This extension borrows concepts, semantics, and language from
VK_KHR_external_semaphore_win32.
That extension’s issues apply equally to this extension.
1) Should D3D12 fence handle types be supported, like they are for semaphores?
RESOLVED: No.
Doing so would require extending the fence signal and wait operations to
provide values to signal / wait for, like VkD3D12FenceSubmitInfoKHR
does.
A D3D12 fence can be signaled by importing it into a VkSemaphore
instead of a VkFence, and applications can check status or wait on the
D3D12 fence using non-Vulkan APIs.
The convenience of being able to do these operations on VkFence
objects does not justify the extra API complexity.
VK_KHR_external_memory_fd
- Name String
-
VK_KHR_external_memory_fd - Extension Type
-
Device extension
- Registered Extension Number
-
75
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_memoryto be enabled for any device-level functionality
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Description
An application may wish to reference device memory in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension enables an application to export POSIX file descriptor handles from Vulkan memory objects and to import Vulkan memory objects from POSIX file descriptor handles exported from other Vulkan memory objects or from similar resources in other APIs.
New Enum Constants
-
VK_KHR_EXTERNAL_MEMORY_FD_EXTENSION_NAME -
VK_KHR_EXTERNAL_MEMORY_FD_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_FD_INFO_KHR -
VK_STRUCTURE_TYPE_MEMORY_FD_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_MEMORY_GET_FD_INFO_KHR
-
Issues
1) Does the application need to close the file descriptor returned by vkGetMemoryFdKHR?
RESOLVED: Yes, unless it is passed back in to a driver instance to import the memory. A successful get call transfers ownership of the file descriptor to the application, and a successful import transfers it back to the driver. Destroying the original memory object will not close the file descriptor or remove its reference to the underlying memory resource associated with it.
2) Do drivers ever need to expose multiple file descriptors per memory object?
RESOLVED: No. This would indicate there are actually multiple memory objects, rather than a single memory object.
3) How should the valid size and memory type for POSIX file descriptor memory handles created outside of Vulkan be specified?
RESOLVED: The valid memory types are queried directly from the external handle. The size will be specified by future extensions that introduce such external memory handle types.
VK_KHR_external_memory_win32
- Name String
-
VK_KHR_external_memory_win32 - Extension Type
-
Device extension
- Registered Extension Number
-
74
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_memoryto be enabled for any device-level functionality
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
An application may wish to reference device memory in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension enables an application to export Windows handles from Vulkan memory objects and to import Vulkan memory objects from Windows handles exported from other Vulkan memory objects or from similar resources in other APIs.
New Enum Constants
-
VK_KHR_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME -
VK_KHR_EXTERNAL_MEMORY_WIN32_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_KHR -
VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_KHR -
VK_STRUCTURE_TYPE_MEMORY_GET_WIN32_HANDLE_INFO_KHR -
VK_STRUCTURE_TYPE_MEMORY_WIN32_HANDLE_PROPERTIES_KHR
-
Issues
1) Do applications need to call CloseHandle() on the values returned
from vkGetMemoryWin32HandleKHR when handleType is
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR?
|
editing-note
(Jon) This issue refers to a token from
|
RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application. Destroying the memory object will not destroy the handle or the handle’s reference to the underlying memory resource.
2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time?
RESOLVED: No. Support for them can be deprecated by drivers if they choose, by no longer returning them in the supported handle types of the instance level queries.
3) How should the valid size and memory type for windows memory handles created outside of Vulkan be specified?
RESOLVED: The valid memory types are queried directly from the external handle. The size is determined by the associated image or buffer memory requirements for external handle types that require dedicated allocations, and by the size specified when creating the object from which the handle was exported for other external handle types.
VK_KHR_external_semaphore_fd
- Name String
-
VK_KHR_external_semaphore_fd - Extension Type
-
Device extension
- Registered Extension Number
-
80
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_semaphoreto be enabled for any device-level functionality
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to export semaphore payload to and import semaphore payload from POSIX file descriptors.
New Enum Constants
-
VK_KHR_EXTERNAL_SEMAPHORE_FD_EXTENSION_NAME -
VK_KHR_EXTERNAL_SEMAPHORE_FD_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_FD_INFO_KHR -
VK_STRUCTURE_TYPE_SEMAPHORE_GET_FD_INFO_KHR
-
Issues
1) Does the application need to close the file descriptor returned by vkGetSemaphoreFdKHR?
RESOLVED: Yes, unless it is passed back in to a driver instance to import the semaphore. A successful get call transfers ownership of the file descriptor to the application, and a successful import transfers it back to the driver. Destroying the original semaphore object will not close the file descriptor or remove its reference to the underlying semaphore resource associated with it.
VK_KHR_external_semaphore_win32
- Name String
-
VK_KHR_external_semaphore_win32 - Extension Type
-
Device extension
- Registered Extension Number
-
79
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_semaphoreto be enabled for any device-level functionality
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to export semaphore payload to and import semaphore payload from Windows handles.
New Enum Constants
-
VK_KHR_EXTERNAL_SEMAPHORE_WIN32_EXTENSION_NAME -
VK_KHR_EXTERNAL_SEMAPHORE_WIN32_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR -
VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR -
VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR -
VK_STRUCTURE_TYPE_SEMAPHORE_GET_WIN32_HANDLE_INFO_KHR
-
Issues
1) Do applications need to call CloseHandle() on the values returned
from vkGetSemaphoreWin32HandleKHR when handleType is
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR?
RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application. Destroying the semaphore object will not destroy the handle or the handle’s reference to the underlying semaphore resource.
2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time?
RESOLVED: No. Support for them can be deprecated by drivers if they choose, by no longer returning them in the supported handle types of the instance level queries.
3) Should applications be allowed to specify additional object attributes for shared handles?
RESOLVED: Yes. Applications will be allowed to provide similar attributes to those they would to any other handle creation API.
4) How do applications communicate the desired fence values to use with
D3D12_FENCE-based Vulkan semaphores?
RESOLVED: There are a couple of options. The values for the signaled and reset states could be communicated up front when creating the object and remain static for the life of the Vulkan semaphore, or they could be specified using auxiliary structures when submitting semaphore signal and wait operations, similar to what is done with the keyed mutex extensions. The latter is more flexible and consistent with the keyed mutex usage, but the former is a much simpler API.
Since Vulkan tends to favor flexibility and consistency over simplicity, a new structure specifying D3D12 fence acquire and release values is added to the vkQueueSubmit function.
VK_KHR_fragment_shader_barycentric
- Name String
-
VK_KHR_fragment_shader_barycentric - Extension Type
-
Device extension
- Registered Extension Number
-
323
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Stu Smith
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-03-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_fragment_shader_barycentric -
This extension provides API support for
GL_EXT_fragment_shader_barycentric
-
- Contributors
-
-
Stu Smith, AMD
-
Tobias Hector, AMD
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, Arm
-
Slawek Grajewski, Intel
-
Pat Brown, NVIDIA
-
Hans-Kristian Arntzen, Valve
-
Contributors to the VK_NV_fragment_shader_barycentric specification
-
Description
This extension is based on the VK_NV_fragment_shader_barycentric
extension, and adds support for the following SPIR-V extension in Vulkan:
The extension provides access to three additional fragment shader variable decorations in SPIR-V:
-
PerVertexKHR, which indicates that a fragment shader input will not have interpolated values, but instead must be accessed with an extra array index that identifies one of the vertices of the primitive producing the fragment -
BaryCoordKHR, which indicates that the variable is a three-component floating-point vector holding barycentric weights for the fragment produced using perspective interpolation -
BaryCoordNoPerspKHR, which indicates that the variable is a three-component floating-point vector holding barycentric weights for the fragment produced using linear interpolation
When using GLSL source-based shader languages, the following variables from
GL_EXT_fragment_shader_barycentric map to these SPIR-V built-in
decorations:
-
in vec3 gl_BaryCoordEXT;→BaryCoordKHR -
in vec3 gl_BaryCoordNoPerspEXT;→BaryCoordNoPerspKHR
GLSL variables declared using the pervertexEXT GLSL qualifier are
expected to be decorated with PerVertexKHR in SPIR-V.
New Enum Constants
-
VK_KHR_FRAGMENT_SHADER_BARYCENTRIC_EXTENSION_NAME -
VK_KHR_FRAGMENT_SHADER_BARYCENTRIC_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_PROPERTIES_KHR
-
Issues
1) What are the interactions with MSAA and how are BaryCoordKHR and
BaryCoordNoPerspKHR interpolated?
RESOLVED: The inputs decorated with BaryCoordKHR or
BaryCoordNoPerspKHR may also be decorated with the Centroid or
Sample qualifiers to specify interpolation, like any other fragment
shader input.
If shaderSampleRateInterpolationFunctions is enabled, the extended
instructions InterpolateAtCentroid, InterpolateAtOffset, and
InterpolateAtSample from the GLSL.std.450 may also be used with inputs
decorated with BaryCoordKHR or BaryCoordNoPerspKHR.
VK_KHR_fragment_shading_rate
- Name String
-
VK_KHR_fragment_shading_rate - Extension Type
-
Device extension
- Registered Extension Number
-
227
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_create_renderpass2to be enabled for any device-level functionality -
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Tobias Hector tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-09-30
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_fragment_shading_rate. -
This extension provides API support for
GL_EXT_fragment_shading_rate
-
- Contributors
-
-
Tobias Hector, AMD
-
Guennadi Riguer, AMD
-
Matthaeus Chajdas, AMD
-
Pat Brown, Nvidia
-
Matthew Netsch, Qualcomm
-
Slawomir Grajewski, Intel
-
Jan-Harald Fredriksen, Arm
-
Jeff Bolz, Nvidia
-
Arseny Kapoulkine, Roblox
-
Contributors to the VK_NV_shading_rate_image specification
-
Contributors to the VK_EXT_fragment_density_map specification
-
Description
This extension adds the ability to change the rate at which fragments are shaded. Rather than the usual single fragment invocation for each pixel covered by a primitive, multiple pixels can be shaded by a single fragment shader invocation.
Up to three methods are available to the application to change the fragment shading rate:
-
Pipeline Fragment Shading Rate, which allows the specification of a rate per-draw.
-
Primitive Fragment Shading Rate, which allows the specification of a rate per primitive, specified during shading.
-
Attachment Fragment Shading Rate, which allows the specification of a rate per-region of the framebuffer, specified in a specialized image attachment.
Additionally, these rates can all be specified and combined in order to adjust the overall detail in the image at each point.
This functionality can be used to focus shading efforts where higher levels of detail are needed in some parts of a scene compared to others. This can be particularly useful in high resolution rendering, or for XR contexts.
This extension also adds support for the SPV_KHR_fragment_shading_rate
extension which enables setting the
primitive fragment shading
rate, and allows querying the final shading rate from a fragment shader.
New Structures
-
Extending VkGraphicsPipelineCreateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkSubpassDescription2:
New Enum Constants
-
VK_KHR_FRAGMENT_SHADING_RATE_EXTENSION_NAME -
VK_KHR_FRAGMENT_SHADING_RATE_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PIPELINE_FRAGMENT_SHADING_RATE_STATE_CREATE_INFO_KHR
-
If VK_KHR_format_feature_flags2 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
Version History
-
Revision 1, 2020-05-06 (Tobias Hector)
-
Initial revision
-
-
Revision 2, 2021-09-30 (Jon Leech)
-
Add interaction with
VK_KHR_format_feature_flags2tovk.xml
-
VK_KHR_get_display_properties2
- Name String
-
VK_KHR_get_display_properties2 - Extension Type
-
Instance extension
- Registered Extension Number
-
122
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_displayto be enabled
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2017-02-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
James Jones, NVIDIA
-
Description
This extension provides new entry points to query device display properties
and capabilities in a way that can be easily extended by other extensions,
without introducing any further entry points.
This extension can be considered the VK_KHR_display equivalent of
the VK_KHR_get_physical_device_properties2 extension.
New Enum Constants
-
VK_KHR_GET_DISPLAY_PROPERTIES_2_EXTENSION_NAME -
VK_KHR_GET_DISPLAY_PROPERTIES_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_MODE_PROPERTIES_2_KHR -
VK_STRUCTURE_TYPE_DISPLAY_PLANE_CAPABILITIES_2_KHR -
VK_STRUCTURE_TYPE_DISPLAY_PLANE_INFO_2_KHR -
VK_STRUCTURE_TYPE_DISPLAY_PLANE_PROPERTIES_2_KHR -
VK_STRUCTURE_TYPE_DISPLAY_PROPERTIES_2_KHR
-
Issues
1) What should this extension be named?
RESOLVED: VK_KHR_get_display_properties2.
Other alternatives:
-
VK_KHR_display2 -
One extension, combined with
VK_KHR_surface_capabilites2.
2) Should extensible input structs be added for these new functions:
RESOLVED:
-
vkGetPhysicalDeviceDisplayProperties2KHR: No. The only current input is a VkPhysicalDevice. Other inputs would not make sense.
-
vkGetPhysicalDeviceDisplayPlaneProperties2KHR: No. The only current input is a VkPhysicalDevice. Other inputs would not make sense.
-
vkGetDisplayModeProperties2KHR: No. The only current inputs are a VkPhysicalDevice and a VkDisplayModeKHR. Other inputs would not make sense.
3) Should additional display query functions be extended?
RESOLVED:
-
vkGetDisplayPlaneSupportedDisplaysKHR: No. Extensions should instead extend vkGetDisplayPlaneCapabilitiesKHR().
VK_KHR_get_surface_capabilities2
- Name String
-
VK_KHR_get_surface_capabilities2 - Extension Type
-
Instance extension
- Registered Extension Number
-
120
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2017-02-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
James Jones, NVIDIA
-
Alon Or-bach, Samsung
-
Description
This extension provides new entry points to query device surface
capabilities in a way that can be easily extended by other extensions,
without introducing any further entry points.
This extension can be considered the VK_KHR_surface equivalent of
the VK_KHR_get_physical_device_properties2 extension.
New Enum Constants
-
VK_KHR_GET_SURFACE_CAPABILITIES_2_EXTENSION_NAME -
VK_KHR_GET_SURFACE_CAPABILITIES_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SURFACE_INFO_2_KHR -
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_KHR -
VK_STRUCTURE_TYPE_SURFACE_FORMAT_2_KHR
-
Issues
1) What should this extension be named?
RESOLVED: VK_KHR_get_surface_capabilities2.
Other alternatives:
-
VK_KHR_surface2 -
One extension, combining a separate display-specific query extension.
2) Should additional WSI query functions be extended?
RESOLVED:
-
vkGetPhysicalDeviceSurfaceCapabilitiesKHR: Yes. The need for this motivated the extension.
-
vkGetPhysicalDeviceSurfaceSupportKHR: No. Currently only has boolean output. Extensions should instead extend vkGetPhysicalDeviceSurfaceCapabilities2KHR.
-
vkGetPhysicalDeviceSurfacePresentModesKHR: No. Recent discussion concluded this introduced too much variability for applications to deal with. Extensions should instead extend vkGetPhysicalDeviceSurfaceCapabilities2KHR.
-
vkGetPhysicalDeviceXlibPresentationSupportKHR: Not in this extension.
-
vkGetPhysicalDeviceXcbPresentationSupportKHR: Not in this extension.
-
vkGetPhysicalDeviceWaylandPresentationSupportKHR: Not in this extension.
-
vkGetPhysicalDeviceWin32PresentationSupportKHR: Not in this extension.
VK_KHR_global_priority
- Name String
-
VK_KHR_global_priority - Extension Type
-
Device extension
- Registered Extension Number
-
189
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2021-10-22
- Contributors
-
-
Tobias Hector, AMD
-
Contributors to VK_EXT_global_priority
-
Contributors to VK_EXT_global_priority_query
-
Description
In Vulkan, users can specify device-scope queue priorities.
In some cases it may be useful to extend this concept to a system-wide
scope.
This device extension allows applications to query the global queue
priorities supported by a queue family, and then set a priority when
creating queues.
The default queue priority is VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT.
Implementations can report which global priority levels are treated differently by the implementation. It is intended primarily for use in system integration along with certain platform-specific priority enforcement rules.
The driver implementation will attempt to skew hardware resource allocation in favour of the higher-priority task. Therefore, higher-priority work may retain similar latency and throughput characteristics even if the system is congested with lower priority work.
The global priority level of a queue shall take precedence over the
per-process queue priority
(VkDeviceQueueCreateInfo::pQueuePriorities).
Abuse of this feature may result in starving the rest of the system from
hardware resources.
Therefore, the driver implementation may deny requests to acquire a priority
above the default priority (VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) if
the caller does not have sufficient privileges.
In this scenario VK_ERROR_NOT_PERMITTED_EXT is returned.
The driver implementation may fail the queue allocation request if resources
required to complete the operation have been exhausted (either by the same
process or a different process).
In this scenario VK_ERROR_INITIALIZATION_FAILED is returned.
New Enum Constants
-
VK_KHR_GLOBAL_PRIORITY_EXTENSION_NAME -
VK_KHR_GLOBAL_PRIORITY_SPEC_VERSION -
VK_MAX_GLOBAL_PRIORITY_SIZE_KHR -
Extending VkResult:
-
VK_ERROR_NOT_PERMITTED_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GLOBAL_PRIORITY_QUERY_FEATURES_KHR -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES_KHR
-
Issues
1) Can we additionally query whether a caller is permitted to acquire a specific global queue priority in this extension?
RESOLVED: No. Whether a caller has enough privilege goes with the OS, and the Vulkan driver cannot really guarantee that the privilege will not change in between this query and the actual queue creation call.
2) If more than 1 queue using global priority is requested, is there a good way to know which queue is failing the device creation?
RESOLVED: No. There is not a good way at this moment, and it is also not quite actionable for the applications to know that because the information may not be accurate. Queue creation can fail because of runtime constraints like insufficient privilege or lack of resource, and the failure is not necessarily tied to that particular queue configuration requested.
VK_KHR_incremental_present
- Name String
-
VK_KHR_incremental_present - Extension Type
-
Device extension
- Registered Extension Number
-
85
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality
-
- Contact
-
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2016-11-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Alon Or-bach, Samsung
-
James Jones, NVIDIA
-
Daniel Rakos, AMD
-
Ray Smith, ARM
-
Mika Isojarvi, Google
-
Jeff Juliano, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This device extension extends vkQueuePresentKHR, from the
VK_KHR_swapchain extension, allowing an application to specify a
list of rectangular, modified regions of each image to present.
This should be used in situations where an application is only changing a
small portion of the presentable images within a swapchain, since it enables
the presentation engine to avoid wasting time presenting parts of the
surface that have not changed.
This extension is leveraged from the EGL_KHR_swap_buffers_with_damage
extension.
New Enum Constants
-
VK_KHR_INCREMENTAL_PRESENT_EXTENSION_NAME -
VK_KHR_INCREMENTAL_PRESENT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_REGIONS_KHR
-
Issues
1) How should we handle steroescopic-3D swapchains? We need to add a layer
for each rectangle.
One approach is to create another struct containing the VkRect2D plus
layer, and have VkPresentRegionsKHR point to an array of that struct.
Another approach is to have two parallel arrays, pRectangles and
pLayers, where pRectangles[i] and pLayers[i] must be used
together.
Which approach should we use, and if the array of a new structure, what
should that be called?
RESOLVED: Create a new structure, which is a VkRect2D plus a layer, and will be called VkRectLayerKHR.
2) Where is the origin of the VkRectLayerKHR?
RESOLVED: The upper left corner of the presentable image(s) of the swapchain, per the definition of framebuffer coordinates.
3) Does the rectangular region, VkRectLayerKHR, specify pixels of the swapchain’s image(s), or of the surface?
RESOLVED: Of the image(s). Some presentation engines may scale the pixels of a swapchain’s image(s) to the size of the surface. The size of the swapchain’s image(s) will be consistent, where the size of the surface may vary over time.
4) What if all of the rectangles for a given swapchain contain a width and/or height of zero?
RESOLVED: The application is indicating that no pixels changed since the last present. The presentation engine may use such a hint and not update any pixels for the swapchain. However, all other semantics of vkQueuePresentKHR must still be honored, including waiting for semaphores to signal.
5) When the swapchain is created with
VkSwapchainCreateInfoKHR::preTransform set to a value other than
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, should the rectangular region,
VkRectLayerKHR, be transformed to align with the preTransform?
RESOLVED: No. The rectangular region in VkRectLayerKHR should not be tranformed. As such, it may not align with the extents of the swapchain’s image(s). It is the responsibility of the presentation engine to transform the rectangular region. This matches the behavior of the Android presentation engine, which set the precedent.
Version History
-
Revision 1, 2016-11-02 (Ian Elliott)
-
Internal revisions
-
-
Revision 2, 2021-03-18 (Ian Elliott)
-
Clarified alignment of rectangles for presentation engines that support transformed swapchains.
-
VK_KHR_performance_query
- Name String
-
VK_KHR_performance_query - Extension Type
-
Device extension
- Registered Extension Number
-
117
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Special Use
- Contact
-
-
Alon Or-bach alonorbach
-
Other Extension Metadata
- Last Modified Date
-
2019-10-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Barker, Unity Technologies
-
Kenneth Benzie, Codeplay
-
Jan-Harald Fredriksen, ARM
-
Jeff Leger, Qualcomm
-
Jesse Hall, Google
-
Tobias Hector, AMD
-
Neil Henning, Codeplay
-
Baldur Karlsson
-
Lionel Landwerlin, Intel
-
Peter Lohrmann, AMD
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Niklas Smedberg, Unity Technologies
-
Igor Ostrowski, Intel
-
Description
The VK_KHR_performance_query extension adds a mechanism to allow querying
of performance counters for use in applications and by profiling tools.
Each queue family may expose counters that can be enabled on a queue of that family. We extend VkQueryType to add a new query type for performance queries, and chain a structure on VkQueryPoolCreateInfo to specify the performance queries to enable.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkQueryPoolCreateInfo:
-
Extending VkSubmitInfo, VkSubmitInfo2:
New Enum Constants
-
VK_KHR_PERFORMANCE_QUERY_EXTENSION_NAME -
VK_KHR_PERFORMANCE_QUERY_SPEC_VERSION -
Extending VkQueryType:
-
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR -
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_DESCRIPTION_KHR -
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_KHR -
VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR
-
Issues
1) Should this extension include a mechanism to begin a query in command buffer A and end the query in command buffer B?
RESOLVED No - queries are tied to command buffer creation and thus have to be encapsulated within a single command buffer.
2) Should this extension include a mechanism to begin and end queries globally on the queue, not using the existing command buffer commands?
RESOLVED No - for the same reasoning as the resolution of 1).
3) Should this extension expose counters that require multiple passes?
RESOLVED Yes - users should re-submit a command buffer with the same commands in it multiple times, specifying the pass to count as the query parameter in VkPerformanceQuerySubmitInfoKHR.
4) How to handle counters across parallel workloads?
RESOLVED In the spirit of Vulkan, a counter description flag
VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHR
denotes that the accuracy of a counter result is affected by parallel
workloads.
5) How to handle secondary command buffers?
RESOLVED Secondary command buffers inherit any counter pass index specified in the parent primary command buffer. Note: this is no longer an issue after change from issue 10 resolution
6) What commands does the profiling lock have to be held for?
RESOLVED For any command buffer that is being queried with a performance query pool, the profiling lock must be held while that command buffer is in the recording, executable, or pending state.
7) Should we support vkCmdCopyQueryPoolResults?
RESOLVED Yes.
8) Should we allow performance queries to interact with multiview?
RESOLVED Yes, but the performance queries must be performed once for each pass per view.
9) Should a queryCount > 1 be usable for performance queries?
RESOLVED Yes.
Some vendors will have costly performance counter query pool creation, and
would rather if a certain set of counters were to be used multiple times
that a queryCount > 1 can be used to amortize the instantiation cost.
10) Should we introduce an indirect mechanism to set the counter pass index?
RESOLVED Specify the counter pass index at submit time instead, to avoid requiring re-recording of command buffers when multiple counter passes are needed.
Examples
The following example shows how to find what performance counters a queue family supports, setup a query pool to record these performance counters, how to add the query pool to the command buffer to record information, and how to get the results from the query pool.
// A previously created physical device
VkPhysicalDevice physicalDevice;
// One of the queue families our device supports
uint32_t queueFamilyIndex;
uint32_t counterCount;
// Get the count of counters supported
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
physicalDevice,
queueFamilyIndex,
&counterCount,
NULL,
NULL);
VkPerformanceCounterKHR* counters =
malloc(sizeof(VkPerformanceCounterKHR) * counterCount);
VkPerformanceCounterDescriptionKHR* counterDescriptions =
malloc(sizeof(VkPerformanceCounterDescriptionKHR) * counterCount);
// Get the counters supported
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
physicalDevice,
queueFamilyIndex,
&counterCount,
counters,
counterDescriptions);
// Try to enable the first 8 counters
uint32_t enabledCounters[8];
const uint32_t enabledCounterCount = min(counterCount, 8));
for (uint32_t i = 0; i < enabledCounterCount; i++) {
enabledCounters[i] = i;
}
// A previously created device that had the performanceCounterQueryPools feature
// set to VK_TRUE
VkDevice device;
VkQueryPoolPerformanceCreateInfoKHR performanceQueryCreateInfo = {
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR,
NULL,
// Specify the queue family that this performance query is performed on
queueFamilyIndex,
// The number of counters to enable
enabledCounterCount,
// The array of indices of counters to enable
enabledCounters
};
// Get the number of passes our counters will require.
uint32_t numPasses;
vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(
physicalDevice,
&performanceQueryCreateInfo,
&numPasses);
VkQueryPoolCreateInfo queryPoolCreateInfo = {
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
&performanceQueryCreateInfo,
0,
// Using our new query type here
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR,
1,
0
};
VkQueryPool queryPool;
VkResult result = vkCreateQueryPool(
device,
&queryPoolCreateInfo,
NULL,
&queryPool);
assert(VK_SUCCESS == result);
// A queue from queueFamilyIndex
VkQueue queue;
// A command buffer we want to record counters on
VkCommandBuffer commandBuffer;
VkCommandBufferBeginInfo commandBufferBeginInfo = {
VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
NULL,
0,
NULL
};
VkAcquireProfilingLockInfoKHR lockInfo = {
VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR,
NULL,
0,
UINT64_MAX // Wait forever for the lock
};
// Acquire the profiling lock before we record command buffers
// that will use performance queries
result = vkAcquireProfilingLockKHR(device, &lockInfo);
assert(VK_SUCCESS == result);
result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo);
assert(VK_SUCCESS == result);
vkCmdResetQueryPool(
commandBuffer,
queryPool,
0,
1);
vkCmdBeginQuery(
commandBuffer,
queryPool,
0,
0);
// Perform the commands you want to get performance information on
// ...
// Perform a barrier to ensure all previous commands were complete before
// ending the query
vkCmdPipelineBarrier(commandBuffer,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
0,
0,
NULL,
0,
NULL,
0,
NULL);
vkCmdEndQuery(
commandBuffer,
queryPool,
0);
result = vkEndCommandBuffer(commandBuffer);
assert(VK_SUCCESS == result);
for (uint32_t counterPass = 0; counterPass < numPasses; counterPass++) {
VkPerformanceQuerySubmitInfoKHR performanceQuerySubmitInfo = {
VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR,
NULL,
counterPass
};
// Submit the command buffer and wait for its completion
// ...
}
// Release the profiling lock after the command buffer is no longer in the
// pending state.
vkReleaseProfilingLockKHR(device);
result = vkResetCommandBuffer(commandBuffer, 0);
assert(VK_SUCCESS == result);
// Create an array to hold the results of all counters
VkPerformanceCounterResultKHR* recordedCounters = malloc(
sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount);
result = vkGetQueryPoolResults(
device,
queryPool,
0,
1,
sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount,
recordedCounters,
sizeof(VkPerformanceCounterResultKHR),
NULL);
// recordedCounters is filled with our counters, we will look at one for posterity
switch (counters[0].storage) {
case VK_PERFORMANCE_COUNTER_STORAGE_INT32:
// use recordCounters[0].int32 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_INT64:
// use recordCounters[0].int64 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_UINT32:
// use recordCounters[0].uint32 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_UINT64:
// use recordCounters[0].uint64 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32:
// use recordCounters[0].float32 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64:
// use recordCounters[0].float64 to get at the counter result!
break;
}
VK_KHR_pipeline_executable_properties
- Name String
-
VK_KHR_pipeline_executable_properties - Extension Type
-
Device extension
- Registered Extension Number
-
270
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Special Use
- Contact
-
-
Jason Ekstrand jekstrand
-
Other Extension Metadata
- Last Modified Date
-
2019-05-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
- Contributors
-
-
Jason Ekstrand, Intel
-
Ian Romanick, Intel
-
Kenneth Graunke, Intel
-
Baldur Karlsson, Valve
-
Jesse Hall, Google
-
Jeff Bolz, Nvidia
-
Piers Daniel, Nvidia
-
Tobias Hector, AMD
-
Jan-Harald Fredriksen, ARM
-
Tom Olson, ARM
-
Daniel Koch, Nvidia
-
Spencer Fricke, Samsung
-
Description
When a pipeline is created, its state and shaders are compiled into zero or more device-specific executables, which are used when executing commands against that pipeline. This extension adds a mechanism to query properties and statistics about the different executables produced by the pipeline compilation process. This is intended to be used by debugging and performance tools to allow them to provide more detailed information to the user. Certain compile-time shader statistics provided through this extension may be useful to developers for debugging or performance analysis.
New Enum Constants
-
VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_EXTENSION_NAME -
VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_SPEC_VERSION -
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR -
VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_EXECUTABLE_PROPERTIES_FEATURES_KHR -
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR -
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR -
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR -
VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR
-
Issues
1) What should we call the pieces of the pipeline which are produced by the compilation process and about which you can query properties and statistics?
RESOLVED: Call them “executables”. The name “binary” was used in early drafts of the extension but it was determined that “pipeline binary” could have a fairly broad meaning (such as a binary serialized form of an entire pipeline) and was too big of a namespace for the very specific needs of this extension.
VK_KHR_pipeline_library
- Name String
-
VK_KHR_pipeline_library - Extension Type
-
Device extension
- Registered Extension Number
-
291
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Christoph Kubisch pixeljetstream
-
Other Extension Metadata
- Last Modified Date
-
2020-01-08
- IP Status
-
No known IP claims.
- Contributors
-
-
See contributors to
VK_KHR_ray_tracing_pipeline
-
Description
A pipeline library is a special pipeline that cannot be bound, instead it defines a set of shaders and shader groups which can be linked into other pipelines. This extension defines the infrastructure for pipeline libraries, but does not specify the creation or usage of pipeline libraries. This is left to additional dependent extensions.
New Enum Constants
-
VK_KHR_PIPELINE_LIBRARY_EXTENSION_NAME -
VK_KHR_PIPELINE_LIBRARY_SPEC_VERSION -
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_LIBRARY_CREATE_INFO_KHR
-
VK_KHR_portability_enumeration
- Name String
-
VK_KHR_portability_enumeration - Extension Type
-
Instance extension
- Registered Extension Number
-
395
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Charles Giessen charles-lunarg
-
Other Extension Metadata
- Last Modified Date
-
2021-06-02
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with
VK_KHR_portability_subset
-
- Contributors
-
-
Lenny Komow, LunarG
-
Charles Giessen, LunarG
-
Description
This extension allows applications to control whether devices that expose
the VK_KHR_portability_subset extension are included in the results
of physical device enumeration.
Since devices which support the VK_KHR_portability_subset extension
are not fully conformant Vulkan implementations, the Vulkan loader does not
report those devices unless the application explicitly asks for them.
This prevents applications which may not be aware of non-conformant devices
from accidentally using them, as any device which supports the
VK_KHR_portability_subset extension mandates that the extension
must be enabled if that device is used.
This extension is implemented in the loader.
New Enum Constants
-
VK_KHR_PORTABILITY_ENUMERATION_EXTENSION_NAME -
VK_KHR_PORTABILITY_ENUMERATION_SPEC_VERSION -
Extending VkInstanceCreateFlagBits:
-
VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR
-
VK_KHR_present_id
- Name String
-
VK_KHR_present_id - Extension Type
-
Device extension
- Registered Extension Number
-
295
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality
-
- Contact
-
-
Keith Packard keithp
-
Other Extension Metadata
- Last Modified Date
-
2019-05-15
- IP Status
-
No known IP claims.
- Contributors
-
-
Keith Packard, Valve
-
Ian Elliott, Google
-
Alon Or-bach, Samsung
-
Description
This device extension allows an application that uses the
VK_KHR_swapchain extension to provide an identifier for present
operations on a swapchain.
An application can use this to reference specific present operations in
other extensions.
New Enum Constants
-
VK_KHR_PRESENT_ID_EXTENSION_NAME -
VK_KHR_PRESENT_ID_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_ID_FEATURES_KHR -
VK_STRUCTURE_TYPE_PRESENT_ID_KHR
-
VK_KHR_present_wait
- Name String
-
VK_KHR_present_wait - Extension Type
-
Device extension
- Registered Extension Number
-
249
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality -
Requires
VK_KHR_present_idto be enabled for any device-level functionality
-
- Contact
-
-
Keith Packard keithp
-
Other Extension Metadata
- Last Modified Date
-
2019-05-15
- IP Status
-
No known IP claims.
- Contributors
-
-
Keith Packard, Valve
-
Ian Elliott, Google
-
Tobias Hector, AMD
-
Daniel Stone, Collabora
-
Description
This device extension allows an application that uses the
VK_KHR_swapchain extension to wait for present operations to
complete.
An application can use this to monitor and control the pacing of the
application by managing the number of outstanding images yet to be
presented.
New Enum Constants
-
VK_KHR_PRESENT_WAIT_EXTENSION_NAME -
VK_KHR_PRESENT_WAIT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_WAIT_FEATURES_KHR
-
Issues
1) When does the wait finish?
RESOLVED. The wait will finish when the present is visible to the user. There is no requirement for any precise timing relationship between the presentation of the image to the user, but implementations should signal the wait as close as possible to the presentation of the first pixel in the new image to the user.
2) Should this use fences or other existing synchronization mechanism.
RESOLVED. Because display and rendering are often implemented in separate drivers, this extension will provide a separate synchronization API.
3) Should this extension share present identification with other extensions?
RESOLVED. Yes. A new extension, VK_KHR_present_id, should be created to provide a shared structure for presentation identifiers.
4) What happens when presentations complete out of order wrt calls to vkQueuePresent? This could happen if the semaphores for the presentations were ready out of order.
OPTION A: Require that when a PresentId is set that the driver ensure that images are always presented in the order of calls to vkQueuePresent.
OPTION B: Finish both waits when the earliest present completes. This will complete the later present wait earlier than the actual presentation. This should be the easiest to implement as the driver need only track the largest present ID completed. This is also the 'natural' consequence of interpreting the existing vkWaitForPresentKHR specificationn.
OPTION C: Finish both waits when both have completed. This will complete the earlier presentation later than the actual presentation time. This is allowed by the current specification as there is no precise timing requirement for when the presentId value is updated. This requires slightly more complexity in the driver as it will need to track all outstanding presentId values.
VK_KHR_push_descriptor
- Name String
-
VK_KHR_push_descriptor - Extension Type
-
Device extension
- Registered Extension Number
-
81
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-09-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Michael Worcester, Imagination Technologies
-
Description
This extension allows descriptors to be written into the command buffer, while the implementation is responsible for managing their memory. Push descriptors may enable easier porting from older APIs and in some cases can be more efficient than writing descriptors into descriptor sets.
New Enum Constants
-
VK_KHR_PUSH_DESCRIPTOR_EXTENSION_NAME -
VK_KHR_PUSH_DESCRIPTOR_SPEC_VERSION -
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR
-
If VK_KHR_descriptor_update_template is supported:
-
Extending VkDescriptorUpdateTemplateType:
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
-
If Version 1.1 is supported:
-
Extending VkDescriptorUpdateTemplateType:
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
-
Version History
-
Revision 1, 2016-10-15 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2017-09-12 (Tobias Hector)
-
Added interactions with Vulkan 1.1
-
VK_KHR_ray_query
- Name String
-
VK_KHR_ray_query - Extension Type
-
Device extension
- Registered Extension Number
-
349
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
Requires
VK_KHR_spirv_1_4to be enabled for any device-level functionality -
Requires
VK_KHR_acceleration_structureto be enabled for any device-level functionality
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2020-11-12
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_ray_query -
This extension provides API support for
GLSL_EXT_ray_query
-
- Contributors
-
-
Matthäus Chajdas, AMD
-
Greg Grebe, AMD
-
Nicolai Hähnle, AMD
-
Tobias Hector, AMD
-
Dave Oldcorn, AMD
-
Skyler Saleh, AMD
-
Mathieu Robart, Arm
-
Marius Bjorge, Arm
-
Tom Olson, Arm
-
Sebastian Tafuri, EA
-
Henrik Rydgard, Embark
-
Juan Cañada, Epic Games
-
Patrick Kelly, Epic Games
-
Yuriy O’Donnell, Epic Games
-
Michael Doggett, Facebook/Oculus
-
Andrew Garrard, Imagination
-
Don Scorgie, Imagination
-
Dae Kim, Imagination
-
Joshua Barczak, Intel
-
Slawek Grajewski, Intel
-
Jeff Bolz, NVIDIA
-
Pascal Gautron, NVIDIA
-
Daniel Koch, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Ashwin Lele, NVIDIA
-
Robert Stepinski, NVIDIA
-
Martin Stich, NVIDIA
-
Nuno Subtil, NVIDIA
-
Eric Werness, NVIDIA
-
Jon Leech, Khronos
-
Jeroen van Schijndel, OTOY
-
Juul Joosten, OTOY
-
Alex Bourd, Qualcomm
-
Roman Larionov, Qualcomm
-
David McAllister, Qualcomm
-
Spencer Fricke, Samsung
-
Lewis Gordon, Samsung
-
Ralph Potter, Samsung
-
Jasper Bekkers, Traverse Research
-
Jesse Barker, Unity
-
Baldur Karlsson, Valve
-
Description
Rasterization has been the dominant method to produce interactive graphics, but increasing performance of graphics hardware has made ray tracing a viable option for interactive rendering. Being able to integrate ray tracing with traditional rasterization makes it easier for applications to incrementally add ray traced effects to existing applications or to do hybrid approaches with rasterization for primary visibility and ray tracing for secondary queries.
Ray queries are available to all shader types, including graphics, compute and ray tracing pipelines. Ray queries are not able to launch additional shaders, instead returning traversal results to the calling shader.
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_ray_query
New Enum Constants
-
VK_KHR_RAY_QUERY_EXTENSION_NAME -
VK_KHR_RAY_QUERY_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_QUERY_FEATURES_KHR
-
Sample Code
Example of ray query in a GLSL shader, illustrating how to use ray queries to determine whether a given position (at ray origin) is in shadow or not, by tracing a ray towards the light, and checking for any intersections with geometry occluding the light.
rayQueryEXT rq;
rayQueryInitializeEXT(rq, accStruct, gl_RayFlagsTerminateOnFirstHitEXT, cullMask, origin, tMin, direction, tMax);
// Traverse the acceleration structure and store information about the first intersection (if any)
rayQueryProceedEXT(rq);
if (rayQueryGetIntersectionTypeEXT(rq, true) == gl_RayQueryCommittedIntersectionNoneEXT) {
// Not in shadow
}
Issues
(1) What are the changes between the public provisional (VK_KHR_ray_tracing v8) release and the final (VK_KHR_acceleration_structure v11 / VK_KHR_ray_query v1) release?
-
refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation flexibility and decoupling ray query support from ray pipelines:
-
VK_KHR_acceleration_structure(for acceleration structure operations) -
VK_KHR_ray_tracing_pipeline(for ray tracing pipeline and shader stages) -
VK_KHR_ray_query(for ray queries in existing shader stages)
-
-
Update SPIRV capabilities to use
RayQueryKHR -
extension is no longer provisional
Version History
-
Revision 1, 2020-11-12 (Mathieu Robart, Daniel Koch, Andrew Garrard)
-
Decomposition of the specification, from VK_KHR_ray_tracing to VK_KHR_ray_query (#1918,!3912)
-
update to use
RayQueryKHRSPIR-V capability -
add numerical limits for ray parameters (#2235,!3960)
-
relax formula for ray intersection candidate determination (#2322,!4080)
-
restrict traces to TLAS (#2239,!4141)
-
require
HitTto be in ray interval forOpRayQueryGenerateIntersectionKHR(#2359,!4146) -
add ray query shader stages for AS read bit (#2407,!4203)
-
VK_KHR_ray_tracing_maintenance1
- Name String
-
VK_KHR_ray_tracing_maintenance1 - Extension Type
-
Device extension
- Registered Extension Number
-
387
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
Requires
VK_KHR_acceleration_structureto be enabled for any device-level functionality
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2022-02-21
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_ray_cull_mask -
This extension provides API support for
GLSL_EXT_ray_cull_mask -
Interacts with
VK_KHR_ray_tracing_pipeline -
Interacts with
VK_KHR_synchronization2
-
- Contributors
-
-
Stu Smith, AMD
-
Tobias Hector, AMD
-
Marius Bjorge, Arm
-
Tom Olson, Arm
-
Yuriy O’Donnell, Epic Games
-
Yunpeng Zhu, Huawei
-
Andrew Garrard, Imagination
-
Dae Kim, Imagination
-
Joshua Barczak, Intel
-
Lionel Landwerlin, Intel
-
Daniel Koch, NVIDIA
-
Eric Werness, NVIDIA
-
Spencer Fricke, Samsung
-
Description
VK_KHR_ray_tracing_maintenance1 adds a collection of minor ray tracing
features, none of which would warrant an entire extension of their own.
The new features are as follows:
-
Adds support for the
SPV_KHR_ray_cull_maskSPIR-V extension in Vulkan. This extension provides access to built-inCullMaskKHRshader variable which contains the value of theOpTrace*Cull Maskparameter. This new shader variable is accessible in the intersection, any-hit, closest-hit and miss shader stages. -
Adds support for a new pipeline stage and access mask built on top of
VK_KHR_synchronization2:-
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHRto specify execution of acceleration structure copy commands -
VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHRto specify read access to a shader binding table in any shader pipeline stage
-
-
Adds two new acceleration structure query parameters:
-
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHRto query the acceleration structure size on the device timeline -
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHRto query the number of bottom level acceleration structure pointers for serialization
-
-
Adds an optional new indirect ray tracing dispatch command, vkCmdTraceRaysIndirect2KHR, which sources the shader binding table parameters as well as the dispatch dimensions from the device. The
rayTracingPipelineTraceRaysIndirect2feature indicates whether this functionality is supported.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
If VK_KHR_ray_tracing_pipeline is supported:
New Enum Constants
-
VK_KHR_RAY_TRACING_MAINTENANCE_1_EXTENSION_NAME -
VK_KHR_RAY_TRACING_MAINTENANCE_1_SPEC_VERSION -
Extending VkQueryType:
-
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR -
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_MAINTENANCE_1_FEATURES_KHR
-
If VK_KHR_synchronization2 is supported:
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
-
If VK_KHR_synchronization2,VK_KHR_ray_tracing_pipeline is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR
-
VK_KHR_ray_tracing_pipeline
- Name String
-
VK_KHR_ray_tracing_pipeline - Extension Type
-
Device extension
- Registered Extension Number
-
348
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
Requires
VK_KHR_spirv_1_4to be enabled for any device-level functionality -
Requires
VK_KHR_acceleration_structureto be enabled for any device-level functionality
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2020-11-12
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_ray_tracing -
This extension provides API support for
GLSL_EXT_ray_tracing -
This extension interacts with Vulkan 1.2 and
VK_KHR_vulkan_memory_model, adding the shader-call-related relation of invocations, shader-call-order partial order of dynamic instances of instructions, and theShaderCallKHRscope. -
This extension interacts with
VK_KHR_pipeline_library, enabling pipeline libraries to be used with ray tracing pipelines and enabling usage of VkRayTracingPipelineInterfaceCreateInfoKHR.
-
- Contributors
-
-
Matthäus Chajdas, AMD
-
Greg Grebe, AMD
-
Nicolai Hähnle, AMD
-
Tobias Hector, AMD
-
Dave Oldcorn, AMD
-
Skyler Saleh, AMD
-
Mathieu Robart, Arm
-
Marius Bjorge, Arm
-
Tom Olson, Arm
-
Sebastian Tafuri, EA
-
Henrik Rydgard, Embark
-
Juan Cañada, Epic Games
-
Patrick Kelly, Epic Games
-
Yuriy O’Donnell, Epic Games
-
Michael Doggett, Facebook/Oculus
-
Andrew Garrard, Imagination
-
Don Scorgie, Imagination
-
Dae Kim, Imagination
-
Joshua Barczak, Intel
-
Slawek Grajewski, Intel
-
Jeff Bolz, NVIDIA
-
Pascal Gautron, NVIDIA
-
Daniel Koch, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Ashwin Lele, NVIDIA
-
Robert Stepinski, NVIDIA
-
Martin Stich, NVIDIA
-
Nuno Subtil, NVIDIA
-
Eric Werness, NVIDIA
-
Jon Leech, Khronos
-
Jeroen van Schijndel, OTOY
-
Juul Joosten, OTOY
-
Alex Bourd, Qualcomm
-
Roman Larionov, Qualcomm
-
David McAllister, Qualcomm
-
Spencer Fricke, Samsung
-
Lewis Gordon, Samsung
-
Ralph Potter, Samsung
-
Jasper Bekkers, Traverse Research
-
Jesse Barker, Unity
-
Baldur Karlsson, Valve
-
Description
Rasterization has been the dominant method to produce interactive graphics, but increasing performance of graphics hardware has made ray tracing a viable option for interactive rendering. Being able to integrate ray tracing with traditional rasterization makes it easier for applications to incrementally add ray traced effects to existing applications or to do hybrid approaches with rasterization for primary visibility and ray tracing for secondary queries.
To enable ray tracing, this extension adds a few different categories of new functionality:
-
A new ray tracing pipeline type with new shader domains: ray generation, intersection, any-hit, closest hit, miss, and callable
-
A shader binding indirection table to link shader groups with acceleration structure items
-
Ray tracing commands which initiate the ray pipeline traversal and invocation of the various new shader domains depending on which traversal conditions are met
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_ray_tracing
New Enum Constants
-
VK_KHR_RAY_TRACING_PIPELINE_EXTENSION_NAME -
VK_KHR_RAY_TRACING_PIPELINE_SPEC_VERSION -
VK_SHADER_UNUSED_KHR -
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
-
-
Extending VkPipelineBindPoint:
-
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR -
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR -
VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR
-
-
Extending VkShaderStageFlagBits:
-
VK_SHADER_STAGE_ANY_HIT_BIT_KHR -
VK_SHADER_STAGE_CALLABLE_BIT_KHR -
VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR -
VK_SHADER_STAGE_INTERSECTION_BIT_KHR -
VK_SHADER_STAGE_MISS_BIT_KHR -
VK_SHADER_STAGE_RAYGEN_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_INTERFACE_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_KHR
-
Issues
(1) How does this extension differ from VK_NV_ray_tracing?
DISCUSSION:
The following is a summary of the main functional differences between VK_KHR_ray_tracing_pipeline and VK_NV_ray_tracing:
-
added support for indirect ray tracing (vkCmdTraceRaysIndirectKHR)
-
uses SPV_KHR_ray_tracing instead of SPV_NV_ray_tracing
-
refer to KHR SPIR-V enums instead of NV SPIR-V enums (which are functionally equivalent and aliased to the same values).
-
added
RayGeometryIndexKHRbuilt-in
-
-
removed vkCompileDeferredNV compilation functionality and replaced with deferred host operations interactions for ray tracing
-
added VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure
-
extended VkPhysicalDeviceRayTracingPipelinePropertiesKHR structure
-
renamed
maxRecursionDepthtomaxRayRecursionDepthand it has a minimum of 1 instead of 31 -
require
shaderGroupHandleSizeto be 32 bytes -
added
maxRayDispatchInvocationCount,shaderGroupHandleAlignmentandmaxRayHitAttributeSize
-
-
reworked geometry structures so they could be better shared between device, host, and indirect builds
-
changed SBT parameters to a structure and added size (VkStridedDeviceAddressRegionKHR)
-
add parameter for requesting memory requirements for host and/or device build
-
added pipeline library support for ray tracing
-
added no-null-shader pipeline flags (
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_*_SHADERS_BIT_KHR) -
added memory model interactions with ray tracing and define how subgroups work and can be repacked
(2) Can you give a more detailed comparison of differences and similarities between VK_NV_ray_tracing and VK_KHR_ray_tracing_pipeline?
DISCUSSION:
The following is a more detailed comparison of which commands, structures, and enums are aliased, changed, or removed.
-
Aliased functionality — enums, structures, and commands that are considered equivalent:
-
Changed enums, structures, and commands:
-
VkRayTracingShaderGroupCreateInfoNV → VkRayTracingShaderGroupCreateInfoKHR (added
pShaderGroupCaptureReplayHandle) -
VkRayTracingPipelineCreateInfoNV → VkRayTracingPipelineCreateInfoKHR (changed type of
pGroups, addedlibraries,pLibraryInterface, andpDynamicState) -
VkPhysicalDeviceRayTracingPropertiesNV → VkPhysicalDeviceRayTracingPropertiesKHR (renamed
maxTriangleCounttomaxPrimitiveCount, addedshaderGroupHandleCaptureReplaySize) -
vkCmdTraceRaysNV → vkCmdTraceRaysKHR (params to struct)
-
vkCreateRayTracingPipelinesNV → vkCreateRayTracingPipelinesKHR (different struct, changed functionality)
-
-
Added enums, structures and commands:
-
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHRVK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR,VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR,VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR,VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR,VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHRto VkPipelineCreateFlagBits -
VkDeviceOrHostAddressKHR and VkDeviceOrHostAddressConstKHR unions
-
vkCmdTraceRaysIndirectKHR command and VkTraceRaysIndirectCommandKHR struct
-
vkGetRayTracingCaptureReplayShaderGroupHandlesKHR (shader group capture/replay)
-
vkCmdSetRayTracingPipelineStackSizeKHR and vkGetRayTracingShaderGroupStackSizeKHR commands for stack size control
-
-
Functionality removed:
-
VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV -
vkCompileDeferredNV command (replaced with
VK_KHR_deferred_host_operations)
-
(3) What are the changes between the public provisional (VK_KHR_ray_tracing v8) release and the internal provisional (VK_KHR_ray_tracing v9) release?
-
Require Vulkan 1.1 and SPIR-V 1.4
-
Added interactions with Vulkan 1.2 and
VK_KHR_vulkan_memory_model -
added creation time capture and replay flags
-
added
VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHRto VkPipelineCreateFlagBits
-
-
replace
VkStridedBufferRegionKHRwith VkStridedDeviceAddressRegionKHR and change vkCmdTraceRaysKHR, vkCmdTraceRaysIndirectKHR, to take these for the shader binding table and use device addresses instead of buffers. -
require the shader binding table buffers to have the
VK_BUFFER_USAGE_RAY_TRACING_BIT_KHRset -
make
VK_KHR_pipeline_libraryan interaction instead of required extension -
rename the
librariesmember of VkRayTracingPipelineCreateInfoKHR topLibraryInfoand make it a pointer -
make
VK_KHR_deferred_host_operationsan interaction instead of a required extension (later went back on this) -
added explicit stack size management for ray tracing pipelines
-
removed the
maxCallableSizemember of VkRayTracingPipelineInterfaceCreateInfoKHR -
added the
pDynamicStatemember to VkRayTracingPipelineCreateInfoKHR -
added
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHRdynamic state for ray tracing pipelines -
added vkGetRayTracingShaderGroupStackSizeKHR and vkCmdSetRayTracingPipelineStackSizeKHR commands
-
added VkShaderGroupShaderKHR enum
-
-
Added
maxRayDispatchInvocationCountlimit to VkPhysicalDeviceRayTracingPipelinePropertiesKHR -
Added
shaderGroupHandleAlignmentproperty to VkPhysicalDeviceRayTracingPipelinePropertiesKHR -
Added
maxRayHitAttributeSizeproperty to VkPhysicalDeviceRayTracingPipelinePropertiesKHR -
Clarify deferred host ops for pipeline creation
-
VkDeferredOperationKHR is now a top-level parameter for vkCreateRayTracingPipelinesKHR
-
removed
VkDeferredOperationInfoKHRstructure -
change deferred host creation/return parameter behavior such that the implementation can modify such parameters until the deferred host operation completes
-
VK_KHR_deferred_host_operationsis required again
-
(4) What are the changes between the internal provisional (VK_KHR_ray_tracing v9) release and the final (VK_KHR_acceleration_structure v11 / VK_KHR_ray_tracing_pipeline v1) release?
-
refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation flexibility and decoupling ray query support from ray pipelines:
-
VK_KHR_acceleration_structure(for acceleration structure operations) -
VK_KHR_ray_tracing_pipeline(for ray tracing pipeline and shader stages) -
VK_KHR_ray_query(for ray queries in existing shader stages)
-
-
Require
Volatilefor the following builtins in the ray generation, closest hit, miss, intersection, and callable shader stages:-
SubgroupSize,SubgroupLocalInvocationId,SubgroupEqMask,SubgroupGeMask,SubgroupGtMask,SubgroupLeMask,SubgroupLtMask -
SMIDNV,WarpIDNV
-
-
clarify buffer usage flags for ray tracing
-
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHRis added as an alias ofVK_BUFFER_USAGE_RAY_TRACING_BIT_NVand is required on shader binding table buffers -
VK_BUFFER_USAGE_STORAGE_BUFFER_BITis used inVK_KHR_acceleration_structureforscratchData
-
-
rename
maxRecursionDepthtomaxRayPipelineRecursionDepth(pipeline creation) andmaxRayRecursionDepth(limit) to reduce confusion -
Add queryable
maxRayHitAttributeSizelimit and rename members of VkRayTracingPipelineInterfaceCreateInfoKHR tomaxPipelineRayPayloadSizeandmaxPipelineRayHitAttributeSizefor clarity -
Update SPIRV capabilities to use
RayTracingKHR -
extension is no longer provisional
-
define synchronization requirements for indirect trace rays and indirect buffer
(5) This extension adds gl_InstanceID for the intersection, any-hit, and closest hit shaders, but in KHR_vulkan_glsl, gl_InstanceID is replaced with gl_InstanceIndex. Which should be used for Vulkan in this extension?
RESOLVED: This extension uses gl_InstanceID and maps it to InstanceId
in SPIR-V.
It is acknowledged that this is different than other shader stages in
Vulkan.
There are two main reasons for the difference here:
-
symmetry with gl_PrimitiveID which is also available in these shaders
-
there is no “baseInstance” relevant for these shaders, and so ID makes it more obvious that this is zero-based.
(6) Why is VK_KHR_pipeline_library an interaction instead of a
required dependency, particularly when the “Feature Requirements” section
says it is required to be supported anyhow?
RESOLVED: If VK_KHR_pipeline_library were a required extension
dependency, then every application would need to enable the extension
whether or not they actually want to use the pipeline library functionality.
Developers found this to be annoying and unfriendly behavior.
We do wish to require all implementations to support it though, and thus
it is listed in the feature requirements section.
Sample Code
Example ray generation GLSL shader
#version 450 core
#extension GL_EXT_ray_tracing : require
layout(set = 0, binding = 0, rgba8) uniform image2D image;
layout(set = 0, binding = 1) uniform accelerationStructureEXT as;
layout(location = 0) rayPayloadEXT float payload;
void main()
{
vec4 col = vec4(0, 0, 0, 1);
vec3 origin = vec3(float(gl_LaunchIDEXT.x)/float(gl_LaunchSizeEXT.x), float(gl_LaunchIDEXT.y)/float(gl_LaunchSizeEXT.y), 1.0);
vec3 dir = vec3(0.0, 0.0, -1.0);
traceRayEXT(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0);
col.y = payload;
imageStore(image, ivec2(gl_LaunchIDEXT.xy), col);
}
Version History
-
Revision 1, 2020-11-12 (Mathieu Robart, Daniel Koch, Eric Werness, Tobias Hector)
-
Decomposition of the specification, from VK_KHR_ray_tracing to VK_KHR_ray_tracing_pipeline (#1918,!3912)
-
require certain subgroup and sm_shader_builtin shader builtins to be decorated as volatile in the ray generation, closest hit, miss, intersection, and callable stages (#1924,!3903,!3954)
-
clarify buffer usage flags for ray tracing (#2181,!3939)
-
rename maxRecursionDepth to maxRayPipelineRecursionDepth and maxRayRecursionDepth (#2203,!3937)
-
add queriable maxRayHitAttributeSize and rename members of VkRayTracingPipelineInterfaceCreateInfoKHR (#2102,!3966)
-
update to use
RayTracingKHRSPIR-V capability -
add VUs for matching hit group type against geometry type (#2245,!3994)
-
require
RayTMaxKHRbe volatile in intersection shaders (#2268,!4030) -
add numerical limits for ray parameters (#2235,!3960)
-
fix SBT indexing rules for device addresses (#2308,!4079)
-
relax formula for ray intersection candidate determination (#2322,!4080)
-
add more details on
ShaderRecordBufferKHRvariables (#2230,!4083) -
clarify valid bits for
InstanceCustomIndexKHR(GLSL/GLSL#19,!4128) -
allow at most one
IncomingRayPayloadKHR,IncomingCallableDataKHR, andHitAttributeKHR(!4129) -
add minimum for maxShaderGroupStride (#2353,!4131)
-
require VK_KHR_pipeline_library extension to be supported (#2348,!4135)
-
clarify meaning of 'geometry index' (#2272,!4137)
-
restrict traces to TLAS (#2239,!4141)
-
add note about maxPipelineRayPayloadSize (#2383,!4172)
-
do not require raygen shader in pipeline libraries (!4185)
-
define sync for indirect trace rays and indirect buffer (#2407,!4208)
-
VK_KHR_shader_clock
- Name String
-
VK_KHR_shader_clock - Extension Type
-
Device extension
- Registered Extension Number
-
182
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Aaron Hagan ahagan
-
Other Extension Metadata
- Last Modified Date
-
2019-4-25
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_shader_clock. -
This extension provides API support for
ARB_shader_clockandEXT_shader_realtime_clock
-
- Contributors
-
-
Aaron Hagan, AMD
-
Daniel Koch, NVIDIA
-
Description
This extension advertises the SPIR-V ShaderClockKHR capability for
Vulkan, which allows a shader to query a real-time or monotonically
incrementing counter at the subgroup level or across the device level.
The two valid SPIR-V scopes for OpReadClockKHR are Subgroup and
Device.
When using GLSL source-based shading languages, the clockRealtime*EXT()
timing functions map to the OpReadClockKHR instruction with a scope of
Device, and the clock*ARB() timing functions map to the
OpReadClockKHR instruction with a scope of Subgroup.
New Enum Constants
-
VK_KHR_SHADER_CLOCK_EXTENSION_NAME -
VK_KHR_SHADER_CLOCK_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CLOCK_FEATURES_KHR
-
VK_KHR_shader_subgroup_uniform_control_flow
- Name String
-
VK_KHR_shader_subgroup_uniform_control_flow - Extension Type
-
Device extension
- Registered Extension Number
-
324
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
- Contact
-
-
Alan Baker alan-baker
-
Other Extension Metadata
- Last Modified Date
-
2020-08-27
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires SPIR-V 1.3.
-
This extension requires
SPV_KHR_subgroup_uniform_control_flow -
This extension provides API support for
GL_EXT_subgroupuniform_qualifier
-
- Contributors
-
-
Alan Baker, Google
-
Jeff Bolz, NVIDIA
-
Description
This extension allows the use of the SPV_KHR_subgroup_uniform_control_flow
SPIR-V extension in shader modules.
SPV_KHR_subgroup_uniform_control_flow provides stronger guarantees that
diverged subgroups will reconverge.
Developers should utilize this extension if they use subgroup operations to reduce the work performed by a uniform subgroup. This extension will guarantee that uniform subgroup will reconverge in the same manner as invocation groups (see “Uniform Control Flow” in the Khronos SPIR-V Specification).
New Enum Constants
-
VK_KHR_SHADER_SUBGROUP_UNIFORM_CONTROL_FLOW_EXTENSION_NAME -
VK_KHR_SHADER_SUBGROUP_UNIFORM_CONTROL_FLOW_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_UNIFORM_CONTROL_FLOW_FEATURES_KHR
-
VK_KHR_shared_presentable_image
- Name String
-
VK_KHR_shared_presentable_image - Extension Type
-
Device extension
- Registered Extension Number
-
112
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality -
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_get_surface_capabilities2to be enabled for any device-level functionality
-
- Contact
-
-
Alon Or-bach alonorbach
-
Other Extension Metadata
- Last Modified Date
-
2017-03-20
- IP Status
-
No known IP claims.
- Contributors
-
-
Alon Or-bach, Samsung Electronics
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Pablo Ceballos, Google
-
Chris Forbes, Google
-
Jeff Juliano, NVIDIA
-
James Jones, NVIDIA
-
Daniel Rakos, AMD
-
Tobias Hector, Imagination Technologies
-
Graham Connor, Imagination Technologies
-
Michael Worcester, Imagination Technologies
-
Cass Everitt, Oculus
-
Johannes Van Waveren, Oculus
-
Description
This extension extends VK_KHR_swapchain to enable creation of a
shared presentable image.
This allows the application to use the image while the presention engine is
accessing it, in order to reduce the latency between rendering and
presentation.
New Enum Constants
-
VK_KHR_SHARED_PRESENTABLE_IMAGE_EXTENSION_NAME -
VK_KHR_SHARED_PRESENTABLE_IMAGE_SPEC_VERSION -
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
-
-
Extending VkPresentModeKHR:
-
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR -
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SHARED_PRESENT_SURFACE_CAPABILITIES_KHR
-
Issues
1) Should we allow a Vulkan WSI swapchain to toggle between normal usage and shared presentation usage?
RESOLVED: No. WSI swapchains are typically recreated with new properties instead of having their properties changed. This can also save resources, assuming that fewer images are needed for shared presentation, and assuming that most VR applications do not need to switch between normal and shared usage.
2) Should we have a query for determining how the presentation engine refresh is triggered?
RESOLVED: Yes. This is done via which presentation modes a surface supports.
3) Should the object representing a shared presentable image be an extension of a VkSwapchainKHR or a separate object?
RESOLVED: Extension of a swapchain due to overlap in creation properties and to allow common functionality between shared and normal presentable images and swapchains.
4) What should we call the extension and the new structures it creates?
RESOLVED: Shared presentable image / shared present.
5) Should the minImageCount and presentMode values of the
VkSwapchainCreateInfoKHR be ignored, or required to be compatible
values?
RESOLVED: minImageCount must be set to 1, and presentMode
should be set to either VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR.
6) What should the layout of the shared presentable image be?
RESOLVED: After acquiring the shared presentable image, the application
must transition it to the VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR layout
prior to it being used.
After this initial transition, any image usage that was requested during
swapchain creation can be performed on the image without layout transitions
being performed.
7) Do we need a new API for the trigger to refresh new content?
RESOLVED: vkQueuePresentKHR to act as API to trigger a refresh, as will allow combination with other compatible extensions to vkQueuePresentKHR.
8) How should an application detect a VK_ERROR_OUT_OF_DATE_KHR error
on a swapchain using the VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
present mode?
RESOLVED: Introduce vkGetSwapchainStatusKHR to allow applications to query the status of a swapchain using a shared presentation mode.
9) What should subsequent calls to vkQueuePresentKHR for
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR swapchains be defined to
do?
RESOLVED: State that implementations may use it as a hint for updated content.
10) Can the ownership of a shared presentable image be transferred to a different queue?
RESOLVED: No.
It is not possible to transfer ownership of a shared presentable image
obtained from a swapchain created using VK_SHARING_MODE_EXCLUSIVE
after it has been presented.
11) How should vkQueueSubmit behave if a command buffer uses an image
from a VK_ERROR_OUT_OF_DATE_KHR swapchain?
RESOLVED: vkQueueSubmit is expected to return the
VK_ERROR_DEVICE_LOST error.
12) Can Vulkan provide any guarantee on the order of rendering, to enable beam chasing?
RESOLVED: This could be achieved via use of render passes to ensure strip rendering.
VK_KHR_surface
- Name String
-
VK_KHR_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
1
- Revision
-
25
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
James Jones cubanismo
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2016-08-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Ian Elliott, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Jason Ekstrand, Intel
-
Description
The VK_KHR_surface extension is an instance extension.
It introduces VkSurfaceKHR objects, which abstract native platform
surface or window objects for use with Vulkan.
It also provides a way to determine whether a queue family in a physical
device supports presenting to particular surface.
Separate extensions for each platform provide the mechanisms for creating
VkSurfaceKHR objects, but once created they may be used in this and
other platform-independent extensions, in particular the
VK_KHR_swapchain extension.
New Enum Constants
-
VK_KHR_SURFACE_EXTENSION_NAME -
VK_KHR_SURFACE_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_SURFACE_KHR
-
-
Extending VkResult:
-
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR -
VK_ERROR_SURFACE_LOST_KHR
-
Examples
|
Note
The example code for the |
Issues
1) Should this extension include a method to query whether a physical device supports presenting to a specific window or native surface on a given platform?
RESOLVED: Yes. Without this, applications would need to create a device instance to determine whether a particular window can be presented to. Knowing that a device supports presentation to a platform in general is not sufficient, as a single machine might support multiple seats, or instances of the platform that each use different underlying physical devices. Additionally, on some platforms, such as the X Window System, different drivers and devices might be used for different windows depending on which section of the desktop they exist on.
2) Should the vkGetPhysicalDeviceSurfaceCapabilitiesKHR,
vkGetPhysicalDeviceSurfaceFormatsKHR, and
vkGetPhysicalDeviceSurfacePresentModesKHR functions be in this
extension and operate on physical devices, rather than being in
VK_KHR_swapchain (i.e. device extension) and being dependent on
VkDevice?
RESOLVED: Yes.
While it might be useful to depend on VkDevice (and therefore on
enabled extensions and features) for the queries, Vulkan was released only
with the VkPhysicalDevice versions.
Many cases can be resolved by a Valid Usage statement, and/or by a separate
pNext chain version of the query struct specific to a given extension
or parameters, via extensible versions of the queries:
vkGetPhysicalDeviceSurfacePresentModes2EXT,
vkGetPhysicalDeviceSurfaceCapabilities2KHR, and
vkGetPhysicalDeviceSurfaceFormats2KHR.
3) Should Vulkan support Xlib or XCB as the API for accessing the X Window System platform?
RESOLVED: Both. XCB is a more modern and efficient API, but Xlib usage is deeply ingrained in many applications and likely will remain in use for the foreseeable future. Not all drivers necessarily need to support both, but including both as options in the core specification will probably encourage support, which should in turn ease adoption of the Vulkan API in older codebases. Additionally, the performance improvements possible with XCB likely will not have a measurable impact on the performance of Vulkan presentation and other minimal window system interactions defined here.
4) Should the GBM platform be included in the list of platform enums?
RESOLVED: Deferred, and will be addressed with a platform-specific extension to be written in the future.
Version History
-
Revision 1, 2015-05-20 (James Jones)
-
Initial draft, based on LunarG KHR spec, other KHR specs, patches attached to bugs.
-
-
Revision 2, 2015-05-22 (Ian Elliott)
-
Created initial Description section.
-
Removed query for whether a platform requires the use of a queue for presentation, since it was decided that presentation will always be modeled as being part of the queue.
-
Fixed typos and other minor mistakes.
-
-
Revision 3, 2015-05-26 (Ian Elliott)
-
Improved the Description section.
-
-
Revision 4, 2015-05-27 (James Jones)
-
Fixed compilation errors in example code.
-
-
Revision 5, 2015-06-01 (James Jones)
-
Added issues 1 and 2 and made related spec updates.
-
-
Revision 6, 2015-06-01 (James Jones)
-
Merged the platform type mappings table previously removed from VK_KHR_swapchain with the platform description table in this spec.
-
Added issues 3 and 4 documenting choices made when building the initial list of native platforms supported.
-
-
Revision 7, 2015-06-11 (Ian Elliott)
-
Updated table 1 per input from the KHR TSG.
-
Updated issue 4 (GBM) per discussion with Daniel Stone. He will create a platform-specific extension sometime in the future.
-
-
Revision 8, 2015-06-17 (James Jones)
-
Updated enum-extending values using new convention.
-
Fixed the value of VK_SURFACE_PLATFORM_INFO_TYPE_SUPPORTED_KHR.
-
-
Revision 9, 2015-06-17 (James Jones)
-
Rebased on Vulkan API version 126.
-
-
Revision 10, 2015-06-18 (James Jones)
-
Marked issues 2 and 3 resolved.
-
-
Revision 11, 2015-06-23 (Ian Elliott)
-
Examples now show use of function pointers for extension functions.
-
Eliminated extraneous whitespace.
-
-
Revision 12, 2015-07-07 (Daniel Rakos)
-
Added error section describing when each error is expected to be reported.
-
Replaced the term “queue node index” with “queue family index” in the spec as that is the agreed term to be used in the latest version of the core header and spec.
-
Replaced bool32_t with VkBool32.
-
-
Revision 13, 2015-08-06 (Daniel Rakos)
-
Updated spec against latest core API header version.
-
-
Revision 14, 2015-08-20 (Ian Elliott)
-
Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.
-
Switched from “revision” to “version”, including use of the VK_MAKE_VERSION macro in the header file.
-
Did miscellaneous cleanup, etc.
-
-
Revision 15, 2015-08-20 (Ian Elliott—porting a 2015-07-29 change from James Jones)
-
Moved the surface transform enums here from VK_WSI_swapchain so they could be reused by VK_WSI_display.
-
-
Revision 16, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 17, 2015-09-01 (James Jones)
-
Fix example code compilation errors.
-
-
Revision 18, 2015-09-26 (Jesse Hall)
-
Replaced VkSurfaceDescriptionKHR with the VkSurfaceKHR object, which is created via layered extensions. Added VkDestroySurfaceKHR.
-
-
Revision 19, 2015-09-28 (Jesse Hall)
-
Renamed from VK_EXT_KHR_swapchain to VK_EXT_KHR_surface.
-
-
Revision 20, 2015-09-30 (Jeff Vigil)
-
Add error result VK_ERROR_SURFACE_LOST_KHR.
-
-
Revision 21, 2015-10-15 (Daniel Rakos)
-
Updated the resolution of issue #2 and include the surface capability queries in this extension.
-
Renamed SurfaceProperties to SurfaceCapabilities as it better reflects that the values returned are the capabilities of the surface on a particular device.
-
Other minor cleanup and consistency changes.
-
-
Revision 22, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_surface to VK_KHR_surface.
-
-
Revision 23, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkDestroySurfaceKHR.
-
-
Revision 24, 2015-11-10 (Jesse Hall)
-
Removed VkSurfaceTransformKHR. Use VkSurfaceTransformFlagBitsKHR instead.
-
Rename VkSurfaceCapabilitiesKHR member maxImageArraySize to maxImageArrayLayers.
-
-
Revision 25, 2016-01-14 (James Jones)
-
Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface to the VK_KHR_surface extension.
-
-
2016-08-23 (Ian Elliott)
-
Update the example code, to not have so many characters per line, and to split out a new example to show how to obtain function pointers.
-
-
2016-08-25 (Ian Elliott)
-
A note was added at the beginning of the example code, stating that it will be removed from future versions of the appendix.
-
VK_KHR_surface_protected_capabilities
- Name String
-
VK_KHR_surface_protected_capabilities - Extension Type
-
Instance extension
- Registered Extension Number
-
240
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
Requires
VK_KHR_get_surface_capabilities2to be enabled
-
- Contact
-
-
Sandeep Shinde sashinde
-
Other Extension Metadata
- Last Modified Date
-
2018-12-18
- IP Status
-
No known IP claims.
- Contributors
-
-
Sandeep Shinde, NVIDIA
-
James Jones, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
This extension extends VkSurfaceCapabilities2KHR, providing
applications a way to query whether swapchains can be created with the
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR flag set.
Vulkan 1.1 added (optional) support for protect memory and protected
resources including buffers (VK_BUFFER_CREATE_PROTECTED_BIT), images
(VK_IMAGE_CREATE_PROTECTED_BIT), and swapchains
(VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR).
However, on implementations which support multiple windowing systems, not
all window systems may be able to provide a protected display path.
This extension provides a way to query if a protected swapchain created for a surface (and thus a specific windowing system) can be displayed on screen. It extends the existing VkSurfaceCapabilities2KHR structure with a new VkSurfaceProtectedCapabilitiesKHR structure from which the application can obtain information about support for protected swapchain creation through vkGetPhysicalDeviceSurfaceCapabilities2KHR.
New Enum Constants
-
VK_KHR_SURFACE_PROTECTED_CAPABILITIES_EXTENSION_NAME -
VK_KHR_SURFACE_PROTECTED_CAPABILITIES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_PROTECTED_CAPABILITIES_KHR
-
VK_KHR_swapchain
- Name String
-
VK_KHR_swapchain - Extension Type
-
Device extension
- Registered Extension Number
-
2
- Revision
-
70
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled for any device-level functionality
-
- Contact
-
-
James Jones cubanismo
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2017-10-06
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1
-
- Contributors
-
-
Patrick Doane, Blizzard
-
Ian Elliott, LunarG
-
Jesse Hall, Google
-
Mathias Heyer, NVIDIA
-
James Jones, NVIDIA
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Jason Ekstrand, Intel
-
Matthaeus G. Chajdas, AMD
-
Ray Smith, ARM
-
Description
The VK_KHR_swapchain extension is the device-level companion to the
VK_KHR_surface extension.
It introduces VkSwapchainKHR objects, which provide the ability to
present rendering results to a surface.
New Structures
If Version 1.1 is supported:
-
Extending VkBindImageMemoryInfo:
-
Extending VkImageCreateInfo:
-
Extending VkPresentInfoKHR:
-
Extending VkSwapchainCreateInfoKHR:
New Enums
If Version 1.1 is supported:
New Bitmasks
If Version 1.1 is supported:
New Enum Constants
-
VK_KHR_SWAPCHAIN_EXTENSION_NAME -
VK_KHR_SWAPCHAIN_SPEC_VERSION -
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_SWAPCHAIN_KHR
-
-
Extending VkResult:
-
VK_ERROR_OUT_OF_DATE_KHR -
VK_SUBOPTIMAL_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_INFO_KHR -
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR
-
If Version 1.1 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR -
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
-
-
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR -
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
-
Issues
1) Does this extension allow the application to specify the memory backing of the presentable images?
RESOLVED: No. Unlike standard images, the implementation will allocate the memory backing of the presentable image.
2) What operations are allowed on presentable images?
RESOLVED: This is determined by the image usage flags specified when creating the presentable image’s swapchain.
3) Does this extension support MSAA presentable images?
RESOLVED: No. Presentable images are always single-sampled. Multi-sampled rendering must use regular images. To present the rendering results the application must manually resolve the multi- sampled image to a single-sampled presentable image prior to presentation.
4) Does this extension support stereo/multi-view presentable images?
RESOLVED: Yes.
The number of views associated with a presentable image is determined by the
imageArrayLayers specified when creating a swapchain.
All presentable images in a given swapchain use the same array size.
5) Are the layers of stereo presentable images half-sized?
RESOLVED: No. The image extents always match those requested by the application.
6) Do the “present” and “acquire next image” commands operate on a queue? If not, do they need to include explicit semaphore objects to interlock them with queue operations?
RESOLVED: The present command operates on a queue. The image ownership operation it represents happens in order with other operations on the queue, so no explicit semaphore object is required to synchronize its actions.
Applications may want to acquire the next image in separate threads from those in which they manage their queue, or in multiple threads. To make such usage easier, the acquire next image command takes a semaphore to signal as a method of explicit synchronization. The application must later queue a wait for this semaphore before queuing execution of any commands using the image.
7) Does vkAcquireNextImageKHR block if no images are available?
RESOLVED: The command takes a timeout parameter.
Special values for the timeout are 0, which makes the call a non-blocking
operation, and UINT64_MAX, which blocks indefinitely.
Values in between will block for up to the specified time.
The call will return when an image becomes available or an error occurs.
It may, but is not required to, return before the specified timeout expires
if the swapchain becomes out of date.
8) Can multiple presents be queued using one vkQueuePresentKHR call?
RESOLVED: Yes. VkPresentInfoKHR contains a list of swapchains and corresponding image indices that will be presented. When supported, all presentations queued with a single vkQueuePresentKHR call will be applied atomically as one operation. The same swapchain must not appear in the list more than once. Later extensions may provide applications stronger guarantees of atomicity for such present operations, and/or allow them to query whether atomic presentation of a particular group of swapchains is possible.
9) How do the presentation and acquire next image functions notify the application the targeted surface has changed?
RESOLVED: Two new result codes are introduced for this purpose:
-
VK_SUBOPTIMAL_KHR- Presentation will still succeed, subject to the window resize behavior, but the swapchain is no longer configured optimally for the surface it targets. Applications should query updated surface information and recreate their swapchain at the next convenient opportunity. -
VK_ERROR_OUT_OF_DATE_KHR- Failure. The swapchain is no longer compatible with the surface it targets. The application must query updated surface information and recreate the swapchain before presentation will succeed.
These can be returned by both vkAcquireNextImageKHR and vkQueuePresentKHR.
10) Does the vkAcquireNextImageKHR command return a semaphore to the application via an output parameter, or accept a semaphore to signal from the application as an object handle parameter?
RESOLVED: Accept a semaphore to signal as an object handle. This avoids the need to specify whether the application must destroy the semaphore or whether it is owned by the swapchain, and if the latter, what its lifetime is and whether it can be reused for other operations once it is received from vkAcquireNextImageKHR.
11) What types of swapchain queuing behavior should be exposed? Options include swap interval specification, mailbox/most recent vs. FIFO queue management, targeting specific vertical blank intervals or absolute times for a given present operation, and probably others. For some of these, whether they are specified at swapchain creation time or as per-present parameters needs to be decided as well.
RESOLVED: The base swapchain extension will expose 3 possible behaviors (of which, FIFO will always be supported):
-
Immediate present: Does not wait for vertical blanking period to update the current image, likely resulting in visible tearing. No internal queue is used. Present requests are applied immediately.
-
Mailbox queue: Waits for the next vertical blanking period to update the current image. No tearing should be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for reuse by the application.
-
FIFO queue: Waits for the next vertical blanking period to update the current image. No tearing should be observed. An internal queue containing
numSwapchainImages- 1 entries is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty
Not all surfaces will support all of these modes, so the modes supported will be returned using a surface information query. All surfaces must support the FIFO queue mode. Applications must choose one of these modes up front when creating a swapchain. Switching modes can be accomplished by recreating the swapchain.
12) Can VK_PRESENT_MODE_MAILBOX_KHR provide non-blocking guarantees
for vkAcquireNextImageKHR? If so, what is the proper criteria?
RESOLVED: Yes. The difficulty is not immediately obvious here. Naively, if at least 3 images are requested, mailbox mode should always have an image available for the application if the application does not own any images when the call to vkAcquireNextImageKHR was made. However, some presentation engines may have more than one “current” image, and would still need to block in some cases. The right requirement appears to be that if the application allocates the surface’s minimum number of images + 1 then it is guaranteed non-blocking behavior when it does not currently own any images.
13) Is there a way to create and initialize a new swapchain for a surface
that has generated a VK_SUBOPTIMAL_KHR return code while still using
the old swapchain?
RESOLVED: Not as part of this specification. This could be useful to allow the application to create an “optimal” replacement swapchain and rebuild all its command buffers using it in a background thread at a low priority while continuing to use the “suboptimal” swapchain in the main thread. It could probably use the same “atomic replace” semantics proposed for recreating direct-to-device swapchains without incurring a mode switch. However, after discussion, it was determined some platforms probably could not support concurrent swapchains for the same surface though, so this will be left out of the base KHR extensions. A future extension could add this for platforms where it is supported.
14) Should there be a special value for
VkSurfaceCapabilitiesKHR::maxImageCount to indicate there are no
practical limits on the number of images in a swapchain?
RESOLVED: Yes. There will often be cases where there is no practical limit to the number of images in a swapchain other than the amount of available resources (i.e., memory) in the system. Trying to derive a hard limit from things like memory size is prone to failure. It is better in such cases to leave it to applications to figure such soft limits out via trial/failure iterations.
15) Should there be a special value for
VkSurfaceCapabilitiesKHR::currentExtent to indicate the size of
the platform surface is undefined?
RESOLVED: Yes. On some platforms (Wayland, for example), the surface size is defined by the images presented to it rather than the other way around.
16) Should there be a special value for
VkSurfaceCapabilitiesKHR::maxImageExtent to indicate there is no
practical limit on the surface size?
RESOLVED: No. It seems unlikely such a system would exist. 0 could be used to indicate the platform places no limits on the extents beyond those imposed by Vulkan for normal images, but this query could just as easily return those same limits, so a special “unlimited” value does not seem useful for this field.
17) How should surface rotation and mirroring be exposed to applications? How do they specify rotation and mirroring transforms applied prior to presentation?
RESOLVED: Applications can query both the supported and current transforms
of a surface.
Both are specified relative to the device’s “natural” display rotation and
direction.
The supported transforms indicate which orientations the presentation engine
accepts images in.
For example, a presentation engine that does not support transforming
surfaces as part of presentation, and which is presenting to a surface that
is displayed with a 90-degree rotation, would return only one supported
transform bit: VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR.
Applications must transform their rendering by the transform they specify
when creating the swapchain in preTransform field.
18) Can surfaces ever not support VK_MIRROR_NONE? Can they support
vertical and horizontal mirroring simultaneously? Relatedly, should
VK_MIRROR_NONE[_BIT] be zero, or bit one, and should applications be
allowed to specify multiple pre and current mirror transform bits, or
exactly one?
RESOLVED: Since some platforms may not support presenting with a transform
other than the native window’s current transform, and prerotation/mirroring
are specified relative to the device’s natural rotation and direction,
rather than relative to the surface’s current rotation and direction, it is
necessary to express lack of support for no mirroring.
To allow this, the MIRROR_NONE enum must occupy a bit in the flags.
Since MIRROR_NONE must be a bit in the bitmask rather than a bitmask
with no values set, allowing more than one bit to be set in the bitmask
would make it possible to describe undefined transforms such as
VK_MIRROR_NONE_BIT | VK_MIRROR_HORIZONTAL_BIT, or a transform
that includes both “no mirroring” and “horizontal mirroring”
simultaneously.
Therefore, it is desirable to allow specifying all supported mirroring
transforms using only one bit.
The question then becomes, should there be a
VK_MIRROR_HORIZONTAL_AND_VERTICAL_BIT to represent a simultaneous
horizontal and vertical mirror transform? However, such a transform is
equivalent to a 180 degree rotation, so presentation engines and
applications that wish to support or use such a transform can express it
through rotation instead.
Therefore, 3 exclusive bits are sufficient to express all needed mirroring
transforms.
19) Should support for sRGB be required?
RESOLVED: In the advent of UHD and HDR display devices, proper color space information is vital to the display pipeline represented by the swapchain. The app can discover the supported format/color-space pairs and select a pair most suited to its rendering needs. Currently only the sRGB color space is supported, future extensions may provide support for more color spaces. See issues 23 and 24.
20) Is there a mechanism to modify or replace an existing swapchain with one targeting the same surface?
RESOLVED: Yes. This is described above in the text.
21) Should there be a way to set prerotation and mirroring using native APIs when presenting using a Vulkan swapchain?
RESOLVED: Yes.
The transforms that can be expressed in this extension are a subset of those
possible on native platforms.
If a platform exposes a method to specify the transform of presented images
for a given surface using native methods and exposes more transforms or
other properties for surfaces than Vulkan supports, it might be impossible,
difficult, or inconvenient to set some of those properties using Vulkan KHR
extensions and some using the native interfaces.
To avoid overwriting properties set using native commands when presenting
using a Vulkan swapchain, the application can set the pretransform to
“inherit”, in which case the current native properties will be used, or if
none are available, a platform-specific default will be used.
Platforms that do not specify a reasonable default or do not provide native
mechanisms to specify such transforms should not include the inherit bits in
the supportedTransforms bitmask they return in
VkSurfaceCapabilitiesKHR.
22) Should the content of presentable images be clipped by objects obscuring their target surface?
RESOLVED: Applications can choose which behavior they prefer. Allowing the content to be clipped could enable more efficient presentation methods on some platforms, but some applications might rely on the content of presentable images to perform techniques such as partial updates or motion blurs.
23) What is the purpose of specifying a VkColorSpaceKHR along with VkFormat when creating a swapchain?
RESOLVED: While Vulkan itself is color space agnostic (e.g. even the
meaning of R, G, B and A can be freely defined by the rendering
application), the swapchain eventually will have to present the images on a
display device with specific color reproduction characteristics.
If any color space transformations are necessary before an image can be
displayed, the color space of the presented image must be known to the
swapchain.
A swapchain will only support a restricted set of color format and -space
pairs.
This set can be discovered via vkGetPhysicalDeviceSurfaceFormatsKHR.
As it can be expected that most display devices support the sRGB color
space, at least one format/color-space pair has to be exposed, where the
color space is VK_COLOR_SPACE_SRGB_NONLINEAR_KHR.
24) How are sRGB formats and the sRGB color space related?
RESOLVED: While Vulkan exposes a number of SRGB texture formats, using
such formats does not guarantee working in a specific color space.
It merely means that the hardware can directly support applying the
non-linear transfer functions defined by the sRGB standard color space when
reading from or writing to images of those formats.
Still, it is unlikely that a swapchain will expose a *_SRGB format
along with any color space other than
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR.
On the other hand, non-*_SRGB formats will be very likely exposed in
pair with a SRGB color space.
This means, the hardware will not apply any transfer function when reading
from or writing to such images, yet they will still be presented on a device
with sRGB display characteristics.
In this case the application is responsible for applying the transfer
function, for instance by using shader math.
25) How are the lifetimes of surfaces and swapchains targeting them related?
RESOLVED: A surface must outlive any swapchains targeting it. A VkSurfaceKHR owns the binding of the native window to the Vulkan driver.
26) How can the client control the way the alpha component of swapchain images is treated by the presentation engine during compositing?
RESOLVED: We should add new enum values to allow the client to negotiate
with the presentation engine on how to treat image alpha values during the
compositing process.
Since not all platforms can practically control this through the Vulkan
driver, a value of VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR is provided like
for surface transforms.
27) Is vkCreateSwapchainKHR the right function to return
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR, or should the various
platform-specific VkSurfaceKHR factory functions catch this error
earlier?
RESOLVED: For most platforms, the VkSurfaceKHR structure is a simple container holding the data that identifies a native window or other object representing a surface on a particular platform. For the surface factory functions to return this error, they would likely need to register a reference on the native objects with the native display server somehow, and ensure no other such references exist. Surfaces were not intended to be that heavyweight.
Swapchains are intended to be the objects that directly manipulate native windows and communicate with the native presentation mechanisms. Swapchains will already need to communicate with the native display server to negotiate allocation and/or presentation of presentable images for a native surface. Therefore, it makes more sense for swapchain creation to be the point at which native object exclusivity is enforced. Platforms may choose to enforce further restrictions on the number of VkSurfaceKHR objects that may be created for the same native window if such a requirement makes sense on a particular platform, but a global requirement is only sensible at the swapchain level.
Examples
|
Note
The example code for the |
Version History
-
Revision 1, 2015-05-20 (James Jones)
-
Initial draft, based on LunarG KHR spec, other KHR specs, patches attached to bugs.
-
-
Revision 2, 2015-05-22 (Ian Elliott)
-
Made many agreed-upon changes from 2015-05-21 KHR TSG meeting. This includes using only a queue for presentation, and having an explicit function to acquire the next image.
-
Fixed typos and other minor mistakes.
-
-
Revision 3, 2015-05-26 (Ian Elliott)
-
Improved the Description section.
-
Added or resolved issues that were found in improving the Description. For example, pSurfaceDescription is used consistently, instead of sometimes using pSurface.
-
-
Revision 4, 2015-05-27 (James Jones)
-
Fixed some grammatical errors and typos
-
Filled in the description of imageUseFlags when creating a swapchain.
-
Added a description of swapInterval.
-
Replaced the paragraph describing the order of operations on a queue for image ownership and presentation.
-
-
Revision 5, 2015-05-27 (James Jones)
-
Imported relevant issues from the (abandoned) vk_wsi_persistent_swapchain_images extension.
-
Added issues 6 and 7, regarding behavior of the acquire next image and present commands with respect to queues.
-
Updated spec language and examples to align with proposed resolutions to issues 6 and 7.
-
-
Revision 6, 2015-05-27 (James Jones)
-
Added issue 8, regarding atomic presentation of multiple swapchains
-
Updated spec language and examples to align with proposed resolution to issue 8.
-
-
Revision 7, 2015-05-27 (James Jones)
-
Fixed compilation errors in example code, and made related spec fixes.
-
-
Revision 8, 2015-05-27 (James Jones)
-
Added issue 9, and the related VK_SUBOPTIMAL_KHR result code.
-
Renamed VK_OUT_OF_DATE_KHR to VK_ERROR_OUT_OF_DATE_KHR.
-
-
Revision 9, 2015-05-27 (James Jones)
-
Added inline proposed resolutions (marked with [JRJ]) to some XXX questions/issues. These should be moved to the issues section in a subsequent update if the proposals are adopted.
-
-
Revision 10, 2015-05-28 (James Jones)
-
Converted vkAcquireNextImageKHR back to a non-queue operation that uses a VkSemaphore object for explicit synchronization.
-
Added issue 10 to determine whether vkAcquireNextImageKHR generates or returns semaphores, or whether it operates on a semaphore provided by the application.
-
-
Revision 11, 2015-05-28 (James Jones)
-
Marked issues 6, 7, and 8 resolved.
-
Renamed VkSurfaceCapabilityPropertiesKHR to VkSurfacePropertiesKHR to better convey the mutable nature of the information it contains.
-
-
Revision 12, 2015-05-28 (James Jones)
-
Added issue 11 with a proposed resolution, and the related issue 12.
-
Updated various sections of the spec to match the proposed resolution to issue 11.
-
-
Revision 13, 2015-06-01 (James Jones)
-
Moved some structures to VK_EXT_KHR_swap_chain to resolve the specification’s issues 1 and 2.
-
-
Revision 14, 2015-06-01 (James Jones)
-
Added code for example 4 demonstrating how an application might make use of the two different present and acquire next image KHR result codes.
-
Added issue 13.
-
-
Revision 15, 2015-06-01 (James Jones)
-
Added issues 14 - 16 and related spec language.
-
Fixed some spelling errors.
-
Added language describing the meaningful return values for vkAcquireNextImageKHR and vkQueuePresentKHR.
-
-
Revision 16, 2015-06-02 (James Jones)
-
Added issues 17 and 18, as well as related spec language.
-
Removed some erroneous text added by mistake in the last update.
-
-
Revision 17, 2015-06-15 (Ian Elliott)
-
Changed special value from “-1” to “0” so that the data types can be unsigned.
-
-
Revision 18, 2015-06-15 (Ian Elliott)
-
Clarified the values of VkSurfacePropertiesKHR::minImageCount and the timeout parameter of the vkAcquireNextImageKHR function.
-
-
Revision 19, 2015-06-17 (James Jones)
-
Misc. cleanup. Removed resolved inline issues and fixed typos.
-
Fixed clarification of VkSurfacePropertiesKHR::minImageCount made in version 18.
-
Added a brief “Image Ownership” definition to the list of terms used in the spec.
-
-
Revision 20, 2015-06-17 (James Jones)
-
Updated enum-extending values using new convention.
-
-
Revision 21, 2015-06-17 (James Jones)
-
Added language describing how to use VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR.
-
Cleaned up an XXX comment regarding the description of which queues vkQueuePresentKHR can be used on.
-
-
Revision 22, 2015-06-17 (James Jones)
-
Rebased on Vulkan API version 126.
-
-
Revision 23, 2015-06-18 (James Jones)
-
Updated language for issue 12 to read as a proposed resolution.
-
Marked issues 11, 12, 13, 16, and 17 resolved.
-
Temporarily added links to the relevant bugs under the remaining unresolved issues.
-
Added issues 19 and 20 as well as proposed resolutions.
-
-
Revision 24, 2015-06-19 (Ian Elliott)
-
Changed special value for VkSurfacePropertiesKHR::currentExtent back to “-1” from “0”. This value will never need to be unsigned, and “0” is actually a legal value.
-
-
Revision 25, 2015-06-23 (Ian Elliott)
-
Examples now show use of function pointers for extension functions.
-
Eliminated extraneous whitespace.
-
-
Revision 26, 2015-06-25 (Ian Elliott)
-
Resolved Issues 9 & 10 per KHR TSG meeting.
-
-
Revision 27, 2015-06-25 (James Jones)
-
Added oldSwapchain member to VkSwapchainCreateInfoKHR.
-
-
Revision 28, 2015-06-25 (James Jones)
-
Added the “inherit” bits to the rotation and mirroring flags and the associated issue 21.
-
-
Revision 29, 2015-06-25 (James Jones)
-
Added the “clipped” flag to VkSwapchainCreateInfoKHR, and the associated issue 22.
-
Specified that presenting an image does not modify it.
-
-
Revision 30, 2015-06-25 (James Jones)
-
Added language to the spec that clarifies the behavior of vkCreateSwapchainKHR() when the oldSwapchain field of VkSwapchainCreateInfoKHR is not NULL.
-
-
Revision 31, 2015-06-26 (Ian Elliott)
-
Example of new VkSwapchainCreateInfoKHR members, “oldSwapchain” and “clipped”.
-
Example of using VkSurfacePropertiesKHR::{min|max}ImageCount to set VkSwapchainCreateInfoKHR::minImageCount.
-
Rename vkGetSurfaceInfoKHR()'s 4th parameter to “pDataSize”, for consistency with other functions.
-
Add macro with C-string name of extension (just to header file).
-
-
Revision 32, 2015-06-26 (James Jones)
-
Minor adjustments to the language describing the behavior of “oldSwapchain”
-
Fixed the version date on my previous two updates.
-
-
Revision 33, 2015-06-26 (Jesse Hall)
-
Add usage flags to VkSwapchainCreateInfoKHR
-
-
Revision 34, 2015-06-26 (Ian Elliott)
-
Rename vkQueuePresentKHR()'s 2nd parameter to “pPresentInfo”, for consistency with other functions.
-
-
Revision 35, 2015-06-26 (Jason Ekstrand)
-
Merged the VkRotationFlagBitsKHR and VkMirrorFlagBitsKHR enums into a single VkSurfaceTransformFlagBitsKHR enum.
-
-
Revision 36, 2015-06-26 (Jason Ekstrand)
-
Added a VkSurfaceTransformKHR enum that is not a bitmask. Each value in VkSurfaceTransformKHR corresponds directly to one of the bits in VkSurfaceTransformFlagBitsKHR so transforming from one to the other is easy. Having a separate enum means that currentTransform and preTransform are now unambiguous by definition.
-
-
Revision 37, 2015-06-29 (Ian Elliott)
-
Corrected one of the signatures of vkAcquireNextImageKHR, which had the last two parameters switched from what it is elsewhere in the specification and header files.
-
-
Revision 38, 2015-06-30 (Ian Elliott)
-
Corrected a typo in description of the vkGetSwapchainInfoKHR() function.
-
Corrected a typo in header file comment for VkPresentInfoKHR::sType.
-
-
Revision 39, 2015-07-07 (Daniel Rakos)
-
Added error section describing when each error is expected to be reported.
-
Replaced bool32_t with VkBool32.
-
-
Revision 40, 2015-07-10 (Ian Elliott)
-
Updated to work with version 138 of the
vulkan.hheader. This includes declaring the VkSwapchainKHR type using the new VK_DEFINE_NONDISP_HANDLE macro, and no longer extending VkObjectType (which was eliminated).
-
-
Revision 41 2015-07-09 (Mathias Heyer)
-
Added color space language.
-
-
Revision 42, 2015-07-10 (Daniel Rakos)
-
Updated query mechanism to reflect the convention changes done in the core spec.
-
Removed “queue” from the name of VK_STRUCTURE_TYPE_QUEUE_PRESENT_INFO_KHR to be consistent with the established naming convention.
-
Removed reference to the no longer existing VkObjectType enum.
-
-
Revision 43, 2015-07-17 (Daniel Rakos)
-
Added support for concurrent sharing of swapchain images across queue families.
-
Updated sample code based on recent changes
-
-
Revision 44, 2015-07-27 (Ian Elliott)
-
Noted that support for VK_PRESENT_MODE_FIFO_KHR is required. That is ICDs may optionally support IMMEDIATE and MAILBOX, but must support FIFO.
-
-
Revision 45, 2015-08-07 (Ian Elliott)
-
Corrected a typo in spec file (type and variable name had wrong case for the imageColorSpace member of the VkSwapchainCreateInfoKHR struct).
-
Corrected a typo in header file (last parameter in PFN_vkGetSurfacePropertiesKHR was missing “KHR” at the end of type: VkSurfacePropertiesKHR).
-
-
Revision 46, 2015-08-20 (Ian Elliott)
-
Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.
-
Switched from “revision” to “version”, including use of the VK_MAKE_VERSION macro in the header file.
-
Made improvements to several descriptions.
-
Changed the status of several issues from PROPOSED to RESOLVED, leaving no unresolved issues.
-
Resolved several TODOs, did miscellaneous cleanup, etc.
-
-
Revision 47, 2015-08-20 (Ian Elliott—porting a 2015-07-29 change from James Jones)
-
Moved the surface transform enums to VK_WSI_swapchain so they could be reused by VK_WSI_display.
-
-
Revision 48, 2015-09-01 (James Jones)
-
Various minor cleanups.
-
-
Revision 49, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 50, 2015-09-01 (James Jones)
-
Update Example #4 to include code that illustrates how to use the oldSwapchain field.
-
-
Revision 51, 2015-09-01 (James Jones)
-
Fix example code compilation errors.
-
-
Revision 52, 2015-09-08 (Matthaeus G. Chajdas)
-
Corrected a typo.
-
-
Revision 53, 2015-09-10 (Alon Or-bach)
-
Removed underscore from SWAP_CHAIN left in VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR.
-
-
Revision 54, 2015-09-11 (Jesse Hall)
-
Described the execution and memory coherence requirements for image transitions to and from VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR.
-
-
Revision 55, 2015-09-11 (Ray Smith)
-
Added errors for destroying and binding memory to presentable images
-
-
Revision 56, 2015-09-18 (James Jones)
-
Added fence argument to vkAcquireNextImageKHR
-
Added example of how to meter a host thread based on presentation rate.
-
-
Revision 57, 2015-09-26 (Jesse Hall)
-
Replace VkSurfaceDescriptionKHR with VkSurfaceKHR.
-
Added issue 25 with agreed resolution.
-
-
Revision 58, 2015-09-28 (Jesse Hall)
-
Renamed from VK_EXT_KHR_device_swapchain to VK_EXT_KHR_swapchain.
-
-
Revision 59, 2015-09-29 (Ian Elliott)
-
Changed vkDestroySwapchainKHR() to return void.
-
-
Revision 60, 2015-10-01 (Jeff Vigil)
-
Added error result VK_ERROR_SURFACE_LOST_KHR.
-
-
Revision 61, 2015-10-05 (Jason Ekstrand)
-
Added the VkCompositeAlpha enum and corresponding structure fields.
-
-
Revision 62, 2015-10-12 (Daniel Rakos)
-
Added VK_PRESENT_MODE_FIFO_RELAXED_KHR.
-
-
Revision 63, 2015-10-15 (Daniel Rakos)
-
Moved surface capability queries to VK_EXT_KHR_surface.
-
-
Revision 64, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_swapchain to VK_KHR_swapchain.
-
-
Revision 65, 2015-10-28 (Ian Elliott)
-
Added optional pResult member to VkPresentInfoKHR, so that per-swapchain results can be obtained from vkQueuePresentKHR().
-
-
Revision 66, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to create and destroy functions.
-
Updated resource transition language.
-
Updated sample code.
-
-
Revision 67, 2015-11-10 (Jesse Hall)
-
Add reserved flags bitmask to VkSwapchainCreateInfoKHR.
-
Modify naming and member ordering to match API style conventions, and so the VkSwapchainCreateInfoKHR image property members mirror corresponding VkImageCreateInfo members but with an 'image' prefix.
-
Make VkPresentInfoKHR::pResults non-const; it is an output array parameter.
-
Make pPresentInfo parameter to vkQueuePresentKHR const.
-
-
Revision 68, 2016-04-05 (Ian Elliott)
-
Moved the “validity” include for vkAcquireNextImage to be in its proper place, after the prototype and list of parameters.
-
Clarified language about presentable images, including how they are acquired, when applications can and cannot use them, etc. As part of this, removed language about “ownership” of presentable images, and replaced it with more-consistent language about presentable images being “acquired” by the application.
-
-
2016-08-23 (Ian Elliott)
-
Update the example code, to use the final API command names, to not have so many characters per line, and to split out a new example to show how to obtain function pointers. This code is more similar to the LunarG “cube” demo program.
-
-
2016-08-25 (Ian Elliott)
-
A note was added at the beginning of the example code, stating that it will be removed from future versions of the appendix.
-
-
Revision 69, 2017-09-07 (Tobias Hector)
-
Added interactions with Vulkan 1.1
-
-
Revision 70, 2017-10-06 (Ian Elliott)
-
Corrected interactions with Vulkan 1.1
-
VK_KHR_swapchain_mutable_format
- Name String
-
VK_KHR_swapchain_mutable_format - Extension Type
-
Device extension
- Registered Extension Number
-
201
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality -
Requires
VK_KHR_maintenance2to be enabled for any device-level functionality -
Requires
VK_KHR_image_format_listto be enabled for any device-level functionality
-
- Contact
-
-
Daniel Rakos drakos-arm
-
Other Extension Metadata
- Last Modified Date
-
2018-03-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Jason Ekstrand, Intel
-
Jan-Harald Fredriksen, ARM
-
Jesse Hall, Google
-
Daniel Rakos, AMD
-
Ray Smith, ARM
-
Description
This extension allows processing of swapchain images as different formats to that used by the window system, which is particularly useful for switching between sRGB and linear RGB formats.
It adds a new swapchain creation flag that enables creating image views from presentable images with a different format than the one used to create the swapchain.
New Enum Constants
-
VK_KHR_SWAPCHAIN_MUTABLE_FORMAT_EXTENSION_NAME -
VK_KHR_SWAPCHAIN_MUTABLE_FORMAT_SPEC_VERSION -
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
-
Issues
1) Are there any new capabilities needed?
RESOLVED: No. It is expected that all implementations exposing this extension support swapchain image format mutability.
2) Do we need a separate VK_SWAPCHAIN_CREATE_EXTENDED_USAGE_BIT_KHR?
RESOLVED: No.
This extension requires VK_KHR_maintenance2 and presentable images of
swapchains created with VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR are
created internally in a way equivalent to specifying both
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT and
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR.
3) Do we need a separate structure to allow specifying an image format list for swapchains?
RESOLVED: No.
We simply use the same VkImageFormatListCreateInfoKHR structure
introduced by VK_KHR_image_format_list.
The structure is required to be included in the pNext chain of
VkSwapchainCreateInfoKHR for swapchains created with
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR.
VK_KHR_wayland_surface
- Name String
-
VK_KHR_wayland_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
7
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_wayland_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) that refers to a Wayland
wl_surface, as well as a query to determine support for rendering to a
Wayland compositor.
New Enum Constants
-
VK_KHR_WAYLAND_SURFACE_EXTENSION_NAME -
VK_KHR_WAYLAND_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does Wayland need a way to query for compatibility between a particular
physical device and a specific Wayland display? This would be a more general
query than vkGetPhysicalDeviceSurfaceSupportKHR: if the
Wayland-specific query returned VK_TRUE for a (VkPhysicalDevice,
struct wl_display*) pair, then the physical device could be assumed to
support presentation to any VkSurfaceKHR for surfaces on the display.
RESOLVED: Yes. vkGetPhysicalDeviceWaylandPresentationSupportKHR was added to address this issue.
2) Should we require surfaces created with vkCreateWaylandSurfaceKHR
to support the VK_PRESENT_MODE_MAILBOX_KHR present mode?
RESOLVED: Yes.
Wayland is an inherently mailbox window system and mailbox support is
required for some Wayland compositor interactions to work as expected.
While handling these interactions may be possible with
VK_PRESENT_MODE_FIFO_KHR, it is much more difficult to do without
deadlock and requiring all Wayland applications to be able to support
implementations which only support VK_PRESENT_MODE_FIFO_KHR would be
an onerous restriction on application developers.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added vkGetPhysicalDeviceWaylandPresentationSupportKHR() to resolve issue #1.
-
Adjusted wording of issue #1 to match the agreed-upon solution.
-
Renamed “window” parameters to “surface” to match Wayland conventions.
-
-
Revision 3, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_wayland_surface to VK_KHR_wayland_surface.
-
-
Revision 4, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkCreateWaylandSurfaceKHR.
-
-
Revision 5, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
-
Revision 6, 2017-02-08 (Jason Ekstrand)
-
Added the requirement that implementations support
VK_PRESENT_MODE_MAILBOX_KHR. -
Added wording about interactions between vkQueuePresentKHR and the Wayland requests sent to the compositor.
-
VK_KHR_win32_keyed_mutex
- Name String
-
VK_KHR_win32_keyed_mutex - Extension Type
-
Device extension
- Registered Extension Number
-
76
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_memory_win32to be enabled for any device-level functionality
-
- Contact
-
-
Carsten Rohde crohde
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
Applications that wish to import Direct3D 11 memory objects into the Vulkan API may wish to use the native keyed mutex mechanism to synchronize access to the memory between Vulkan and Direct3D. This extension provides a way for an application to access the keyed mutex associated with an imported Vulkan memory object when submitting command buffers to a queue.
New Enum Constants
-
VK_KHR_WIN32_KEYED_MUTEX_EXTENSION_NAME -
VK_KHR_WIN32_KEYED_MUTEX_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_KHR
-
VK_KHR_win32_surface
- Name String
-
VK_KHR_win32_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
10
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2017-04-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_win32_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) that refers to a Win32 HWND, as
well as a query to determine support for rendering to the windows desktop.
New Enum Constants
-
VK_KHR_WIN32_SURFACE_EXTENSION_NAME -
VK_KHR_WIN32_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does Win32 need a way to query for compatibility between a particular physical device and a specific screen? Compatibility between a physical device and a window generally only depends on what screen the window is on. However, there is not an obvious way to identify a screen without already having a window on the screen.
RESOLVED: No. While it may be useful, there is not a clear way to do this on Win32. However, a method was added to query support for presenting to the windows desktop as a whole.
2) If a native window object (HWND) is used by one graphics API, and
then is later used by a different graphics API (one of which is Vulkan), can
these uses interfere with each other?
RESOLVED: Yes.
Uses of a window object by multiple graphics APIs results in undefined behavior. Such behavior may succeed when using one Vulkan implementation but fail when using a different Vulkan implementation. Potential failures include:
-
Creating then destroying a flip presentation model DXGI swapchain on a window object can prevent vkCreateSwapchainKHR from succeeding on the same window object.
-
Creating then destroying a VkSwapchainKHR on a window object can prevent creation of a bitblt model DXGI swapchain on the same window object.
-
Creating then destroying a VkSwapchainKHR on a window object can effectively
SetPixelFormatto a different format than the format chosen by an OpenGL application. -
Creating then destroying a VkSwapchainKHR on a window object on one VkPhysicalDevice can prevent vkCreateSwapchainKHR from succeeding on the same window object, but on a different VkPhysicalDevice that is associated with a different Vulkan ICD.
In all cases the problem can be worked around by creating a new window object.
Technical details include:
-
Creating a DXGI swapchain over a window object can alter the object for the remainder of its lifetime. The alteration persists even after the DXGI swapchain has been destroyed. This alteration can make it impossible for a conformant Vulkan implementation to create a VkSwapchainKHR over the same window object. Mention of this alteration can be found in the remarks section of the MSDN documentation for
DXGI_SWAP_EFFECT. -
Calling GDI’s
SetPixelFormat(needed by OpenGL’s WGL layer) on a window object alters the object for the remainder of its lifetime. The MSDN documentation forSetPixelFormatexplains that a window object’s pixel format can be set only one time. -
Creating a VkSwapchainKHR over a window object can alter the object for its remaining lifetime. Either of the above alterations may occur as a side effect of vkCreateSwapchainKHR.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added presentation support query for win32 desktops.
-
-
Revision 3, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_win32_surface to VK_KHR_win32_surface.
-
-
Revision 4, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkCreateWin32SurfaceKHR.
-
-
Revision 5, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
-
Revision 6, 2017-04-24 (Jeff Juliano)
-
Add issue 2 addressing reuse of a native window object in a different Graphics API, or by a different Vulkan ICD.
-
VK_KHR_workgroup_memory_explicit_layout
- Name String
-
VK_KHR_workgroup_memory_explicit_layout - Extension Type
-
Device extension
- Registered Extension Number
-
337
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Caio Marcelo de Oliveira Filho cmarcelo
-
Other Extension Metadata
- Last Modified Date
-
2020-06-01
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_workgroup_memory_explicit_layout -
This extension provides API support for
GL_EXT_shared_memory_block
-
- Contributors
-
-
Caio Marcelo de Oliveira Filho, Intel
-
Jeff Bolz, NVIDIA
-
Graeme Leese, Broadcom
-
Jason Ekstrand, Intel
-
Daniel Koch, NVIDIA
-
Description
This extension adds Vulkan support for the
SPV_KHR_workgroup_memory_explicit_layout
SPIR-V extension, which allows shaders to explicitly define the layout of
Workgroup storage class memory and create aliases between variables
from that storage class in a compute shader.
The aliasing feature allows different “views” on the same data, so the shader can bulk copy data from another storage class using one type (e.g. an array of large vectors), and then use the data with a more specific type. It also enables reducing the amount of workgroup memory consumed by allowing the shader to alias data whose lifetimes do not overlap.
The explicit layout support and some form of aliasing is also required for layering OpenCL on top of Vulkan.
New Enum Constants
-
VK_KHR_WORKGROUP_MEMORY_EXPLICIT_LAYOUT_EXTENSION_NAME -
VK_KHR_WORKGROUP_MEMORY_EXPLICIT_LAYOUT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_WORKGROUP_MEMORY_EXPLICIT_LAYOUT_FEATURES_KHR
-
VK_KHR_xcb_surface
- Name String
-
VK_KHR_xcb_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
6
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_xcb_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) that refers to an X11 Window,
using the XCB client-side library, as well as a query to determine support
for rendering via XCB.
New Enum Constants
-
VK_KHR_XCB_SURFACE_EXTENSION_NAME -
VK_KHR_XCB_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does XCB need a way to query for compatibility between a particular
physical device and a specific screen? This would be a more general query
than vkGetPhysicalDeviceSurfaceSupportKHR: If it returned
VK_TRUE, then the physical device could be assumed to support
presentation to any window on that screen.
RESOLVED: Yes, this is needed for toolkits that want to create a VkDevice before creating a window. To ensure the query is reliable, it must be made against a particular X visual rather than the screen in general.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added presentation support query for an (xcb_connection_t*, xcb_visualid_t) pair.
-
Removed “root” parameter from CreateXcbSurfaceKHR(), as it is redundant when a window on the same screen is specified as well.
-
Adjusted wording of issue #1 and added agreed upon resolution.
-
-
Revision 3, 2015-10-14 (Ian Elliott)
-
Removed “root” parameter from CreateXcbSurfaceKHR() in one more place.
-
-
Revision 4, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_xcb_surface to VK_KHR_xcb_surface.
-
-
Revision 5, 2015-10-23 (Daniel Rakos)
-
Added allocation callbacks to vkCreateXcbSurfaceKHR.
-
-
Revision 6, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
VK_KHR_xlib_surface
- Name String
-
VK_KHR_xlib_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
5
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_xlib_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) that refers to an X11 Window,
using the Xlib client-side library, as well as a query to determine support
for rendering via Xlib.
New Enum Constants
-
VK_KHR_XLIB_SURFACE_EXTENSION_NAME -
VK_KHR_XLIB_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does X11 need a way to query for compatibility between a particular
physical device and a specific screen? This would be a more general query
than vkGetPhysicalDeviceSurfaceSupportKHR; if it returned
VK_TRUE, then the physical device could be assumed to support
presentation to any window on that screen.
RESOLVED: Yes, this is needed for toolkits that want to create a VkDevice before creating a window. To ensure the query is reliable, it must be made against a particular X visual rather than the screen in general.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added presentation support query for (Display*, VisualID) pair.
-
Removed “root” parameter from CreateXlibSurfaceKHR(), as it is redundant when a window on the same screen is specified as well.
-
Added appropriate X errors.
-
Adjusted wording of issue #1 and added agreed upon resolution.
-
-
Revision 3, 2015-10-14 (Ian Elliott)
-
Renamed this extension from VK_EXT_KHR_x11_surface to VK_EXT_KHR_xlib_surface.
-
-
Revision 4, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_xlib_surface to VK_KHR_xlib_surface.
-
-
Revision 5, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkCreateXlibSurfaceKHR.
-
-
Revision 6, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
VK_EXT_acquire_drm_display
- Name String
-
VK_EXT_acquire_drm_display - Extension Type
-
Instance extension
- Registered Extension Number
-
286
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_direct_mode_displayto be enabled
-
- Contact
-
-
Drew DeVault sir@cmpwn.com
-
Other Extension Metadata
- Last Modified Date
-
2021-06-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Simon Zeni, Status Holdings, Ltd.
-
Description
This extension allows an application to take exclusive control of a display using the Direct Rendering Manager (DRM) interface. When acquired, the display will be under full control of the application until the display is either released or the connector is unplugged.
New Enum Constants
-
VK_EXT_ACQUIRE_DRM_DISPLAY_EXTENSION_NAME -
VK_EXT_ACQUIRE_DRM_DISPLAY_SPEC_VERSION
VK_EXT_acquire_xlib_display
- Name String
-
VK_EXT_acquire_xlib_display - Extension Type
-
Instance extension
- Registered Extension Number
-
90
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_direct_mode_displayto be enabled
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Dave Airlie, Red Hat
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Liam Middlebrook, NVIDIA
-
Daniel Vetter, Intel
-
Description
This extension allows an application to take exclusive control on a display currently associated with an X11 screen. When control is acquired, the display will be deassociated from the X11 screen until control is released or the specified display connection is closed. Essentially, the X11 screen will behave as if the monitor has been unplugged until control is released.
New Enum Constants
-
VK_EXT_ACQUIRE_XLIB_DISPLAY_EXTENSION_NAME -
VK_EXT_ACQUIRE_XLIB_DISPLAY_SPEC_VERSION
Issues
1) Should vkAcquireXlibDisplayEXT take an RandR display ID, or a Vulkan display handle as input?
RESOLVED: A Vulkan display handle. Otherwise there would be no way to specify handles to displays that had been prevented from being included in the X11 display list by some native platform or vendor-specific mechanism.
2) How does an application figure out which RandR display corresponds to a Vulkan display?
RESOLVED: A new function, vkGetRandROutputDisplayEXT, is introduced for this purpose.
3) Should vkGetRandROutputDisplayEXT be part of this extension, or a general Vulkan / RandR or Vulkan / Xlib extension?
RESOLVED: To avoid yet another extension, include it in this extension.
VK_EXT_astc_decode_mode
- Name String
-
VK_EXT_astc_decode_mode - Extension Type
-
Device extension
- Registered Extension Number
-
68
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
Description
The existing specification requires that low dynamic range (LDR) ASTC textures are decompressed to FP16 values per component. In many cases, decompressing LDR textures to a lower precision intermediate result gives acceptable image quality. Source material for LDR textures is typically authored as 8-bit UNORM values, so decoding to FP16 values adds little value. On the other hand, reducing precision of the decoded result reduces the size of the decompressed data, potentially improving texture cache performance and saving power.
The goal of this extension is to enable this efficiency gain on existing ASTC texture data. This is achieved by giving the application the ability to select the intermediate decoding precision.
Three decoding options are provided:
-
Decode to
VK_FORMAT_R16G16B16A16_SFLOATprecision: This is the default, and matches the required behavior in the core API. -
Decode to
VK_FORMAT_R8G8B8A8_UNORMprecision: This is provided as an option in LDR mode. -
Decode to
VK_FORMAT_E5B9G9R9_UFLOAT_PACK32precision: This is provided as an option in both LDR and HDR mode. In this mode, negative values cannot be represented and are clamped to zero. The alpha component is ignored, and the results are as if alpha was 1.0. This decode mode is optional and support can be queried via the physical device properties.
New Enum Constants
-
VK_EXT_ASTC_DECODE_MODE_EXTENSION_NAME -
VK_EXT_ASTC_DECODE_MODE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ASTC_DECODE_FEATURES_EXT
-
Issues
1) Are implementations allowed to decode at a higher precision than what is requested?
RESOLUTION: No. If we allow this, then this extension could be exposed on all implementations that support ASTC. But developers would have no way of knowing what precision was actually used, and thus whether the image quality is sufficient at reduced precision.
2) Should the decode mode be image view state and/or sampler state?
RESOLUTION: Image view state only. Some implementations treat the different decode modes as different texture formats.
Example
Create an image view that decodes to VK_FORMAT_R8G8B8A8_UNORM
precision:
VkImageViewASTCDecodeModeEXT decodeMode =
{
VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT, // sType
NULL, // pNext
VK_FORMAT_R8G8B8A8_UNORM // decode mode
};
VkImageViewCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO, // sType
&decodeMode, // pNext
// flags, image, viewType set to application-desired values
VK_FORMAT_ASTC_8x8_UNORM_BLOCK, // format
// components, subresourceRange set to application-desired values
};
VkImageView imageView;
VkResult result = vkCreateImageView(
device,
&createInfo,
NULL,
&imageView);
VK_EXT_blend_operation_advanced
- Name String
-
VK_EXT_blend_operation_advanced - Extension Type
-
Device extension
- Registered Extension Number
-
149
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Description
This extension adds a number of “advanced” blending operations that can be used to perform new color blending operations, many of which are more complex than the standard blend modes provided by unextended Vulkan. This extension requires different styles of usage, depending on the level of hardware support and the enabled features:
-
If VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT::
advancedBlendCoherentOperationsisVK_FALSE, the new blending operations are supported, but a memory dependency must separate each advanced blend operation on a given sample.VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXTis used to synchronize reads using advanced blend operations. -
If VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT::
advancedBlendCoherentOperationsisVK_TRUE, advanced blend operations obey primitive order just like basic blend operations.
In unextended Vulkan, the set of blending operations is limited, and can be
expressed very simply.
The VK_BLEND_OP_MIN and VK_BLEND_OP_MAX blend operations simply
compute component-wise minimums or maximums of source and destination color
components.
The VK_BLEND_OP_ADD, VK_BLEND_OP_SUBTRACT, and
VK_BLEND_OP_REVERSE_SUBTRACT modes multiply the source and destination
colors by source and destination factors and either add the two products
together or subtract one from the other.
This limited set of operations supports many common blending operations but
precludes the use of more sophisticated transparency and blending operations
commonly available in many dedicated imaging APIs.
This extension provides a number of new “advanced” blending operations.
Unlike traditional blending operations using VK_BLEND_OP_ADD, these
blending equations do not use source and destination factors specified by
VkBlendFactor.
Instead, each blend operation specifies a complete equation based on the
source and destination colors.
These new blend operations are used for both RGB and alpha components; they
must not be used to perform separate RGB and alpha blending (via different
values of color and alpha VkBlendOp).
These blending operations are performed using premultiplied colors, where
RGB colors can be considered premultiplied or non-premultiplied by alpha,
according to the srcPremultiplied and dstPremultiplied members
of VkPipelineColorBlendAdvancedStateCreateInfoEXT.
If a color is considered non-premultiplied, the (R,G,B) color components are
multiplied by the alpha component prior to blending.
For non-premultiplied color components in the range [0,1], the
corresponding premultiplied color component would have values in the range
[0 × A, 1 × A].
Many of these advanced blending equations are formulated where the result of
blending source and destination colors with partial coverage have three
separate contributions: from the portions covered by both the source and the
destination, from the portion covered only by the source, and from the
portion covered only by the destination.
The blend parameter
VkPipelineColorBlendAdvancedStateCreateInfoEXT::blendOverlap
can be used to specify a correlation between source and destination pixel
coverage.
If set to VK_BLEND_OVERLAP_CONJOINT_EXT, the source and destination
are considered to have maximal overlap, as would be the case if drawing two
objects on top of each other.
If set to VK_BLEND_OVERLAP_DISJOINT_EXT, the source and destination
are considered to have minimal overlap, as would be the case when rendering
a complex polygon tessellated into individual non-intersecting triangles.
If set to VK_BLEND_OVERLAP_UNCORRELATED_EXT, the source and
destination coverage are assumed to have no spatial correlation within the
pixel.
In addition to the coherency issues on implementations not supporting
advancedBlendCoherentOperations, this extension has several
limitations worth noting.
First, the new blend operations have a limit on the number of color
attachments they can be used with, as indicated by
VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::advancedBlendMaxColorAttachments.
Additionally, blending precision may be limited to 16-bit floating-point,
which may result in a loss of precision and dynamic range for framebuffer
formats with 32-bit floating-point components, and in a loss of precision
for formats with 12- and 16-bit signed or unsigned normalized integer
components.
New Enum Constants
-
VK_EXT_BLEND_OPERATION_ADVANCED_EXTENSION_NAME -
VK_EXT_BLEND_OPERATION_ADVANCED_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT
-
-
Extending VkBlendOp:
-
VK_BLEND_OP_BLUE_EXT -
VK_BLEND_OP_COLORBURN_EXT -
VK_BLEND_OP_COLORDODGE_EXT -
VK_BLEND_OP_CONTRAST_EXT -
VK_BLEND_OP_DARKEN_EXT -
VK_BLEND_OP_DIFFERENCE_EXT -
VK_BLEND_OP_DST_ATOP_EXT -
VK_BLEND_OP_DST_EXT -
VK_BLEND_OP_DST_IN_EXT -
VK_BLEND_OP_DST_OUT_EXT -
VK_BLEND_OP_DST_OVER_EXT -
VK_BLEND_OP_EXCLUSION_EXT -
VK_BLEND_OP_GREEN_EXT -
VK_BLEND_OP_HARDLIGHT_EXT -
VK_BLEND_OP_HARDMIX_EXT -
VK_BLEND_OP_HSL_COLOR_EXT -
VK_BLEND_OP_HSL_HUE_EXT -
VK_BLEND_OP_HSL_LUMINOSITY_EXT -
VK_BLEND_OP_HSL_SATURATION_EXT -
VK_BLEND_OP_INVERT_EXT -
VK_BLEND_OP_INVERT_OVG_EXT -
VK_BLEND_OP_INVERT_RGB_EXT -
VK_BLEND_OP_LIGHTEN_EXT -
VK_BLEND_OP_LINEARBURN_EXT -
VK_BLEND_OP_LINEARDODGE_EXT -
VK_BLEND_OP_LINEARLIGHT_EXT -
VK_BLEND_OP_MINUS_CLAMPED_EXT -
VK_BLEND_OP_MINUS_EXT -
VK_BLEND_OP_MULTIPLY_EXT -
VK_BLEND_OP_OVERLAY_EXT -
VK_BLEND_OP_PINLIGHT_EXT -
VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT -
VK_BLEND_OP_PLUS_CLAMPED_EXT -
VK_BLEND_OP_PLUS_DARKER_EXT -
VK_BLEND_OP_PLUS_EXT -
VK_BLEND_OP_RED_EXT -
VK_BLEND_OP_SCREEN_EXT -
VK_BLEND_OP_SOFTLIGHT_EXT -
VK_BLEND_OP_SRC_ATOP_EXT -
VK_BLEND_OP_SRC_EXT -
VK_BLEND_OP_SRC_IN_EXT -
VK_BLEND_OP_SRC_OUT_EXT -
VK_BLEND_OP_SRC_OVER_EXT -
VK_BLEND_OP_VIVIDLIGHT_EXT -
VK_BLEND_OP_XOR_EXT -
VK_BLEND_OP_ZERO_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_ADVANCED_STATE_CREATE_INFO_EXT
-
Version History
-
Revision 1, 2017-06-12 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2017-06-12 (Jeff Bolz)
-
Internal revisions
-
VK_EXT_border_color_swizzle
- Name String
-
VK_EXT_border_color_swizzle - Extension Type
-
Device extension
- Registered Extension Number
-
412
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_custom_border_colorto be enabled for any device-level functionality
-
- Special Uses
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2021-10-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, Arm
-
Ricardo Garcia, Igalia
-
Shahbaz Youssefi, Google
-
Stu Smith, AMD
-
Description
After the publication of VK_EXT_custom_border_color, it was discovered that some implementations had undefined behavior when combining a sampler that uses a custom border color with image views whose component mapping is not the identity mapping.
Since VK_EXT_custom_border_color has already shipped, this new extension VK_EXT_border_color_swizzle was created to define the interaction between custom border colors and non-identity image view swizzles, and provide a work-around for implementations that must pre-swizzle the sampler border color to match the image view component mapping it is combined with.
This extension also defines the behavior between samplers with an opaque black border color and image views with a non-identity component swizzle, which was previously left undefined.
New Enum Constants
-
VK_EXT_BORDER_COLOR_SWIZZLE_EXTENSION_NAME -
VK_EXT_BORDER_COLOR_SWIZZLE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BORDER_COLOR_SWIZZLE_FEATURES_EXT -
VK_STRUCTURE_TYPE_SAMPLER_BORDER_COLOR_COMPONENT_MAPPING_CREATE_INFO_EXT
-
VK_EXT_calibrated_timestamps
- Name String
-
VK_EXT_calibrated_timestamps - Extension Type
-
Device extension
- Registered Extension Number
-
185
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2018-10-04
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Alan Harrison, AMD
-
Derrick Owens, AMD
-
Daniel Rakos, AMD
-
Jason Ekstrand, Intel
-
Keith Packard, Valve
-
Description
This extension provides an interface to query calibrated timestamps obtained quasi simultaneously from two time domains.
New Enum Constants
-
VK_EXT_CALIBRATED_TIMESTAMPS_EXTENSION_NAME -
VK_EXT_CALIBRATED_TIMESTAMPS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT
-
Issues
1) Is the device timestamp value returned in the same time domain as the timestamp values written by vkCmdWriteTimestamp?
RESOLVED: Yes.
2) What time domain is the host timestamp returned in?
RESOLVED: A query is provided to determine the calibrateable time domains. The expected host time domain used on Windows is that of QueryPerformanceCounter, and on Linux that of CLOCK_MONOTONIC.
3) Should we support other time domain combinations than just one host and the device time domain?
RESOLVED: Supporting that would need the application to query the set of supported time domains, while supporting only one host and the device time domain would only need a query for the host time domain type. The proposed API chooses the general approach for the sake of extensibility.
4) Should we use CLOCK_MONOTONIC_RAW instead of CLOCK_MONOTONIC?
RESOLVED: CLOCK_MONOTONIC is usable in a wider set of situations, however, it is subject to NTP adjustments so some use cases may prefer CLOCK_MONOTONIC_RAW. Thus this extension allows both to be exposed.
5) How can the application extrapolate future device timestamp values from the calibrated timestamp value?
RESOLVED: VkPhysicalDeviceLimits::timestampPeriod makes it
possible to calculate future device timestamps as follows:
6) In what queue are timestamp values in time domain
VK_TIME_DOMAIN_DEVICE_EXT captured by
vkGetCalibratedTimestampsEXT?
RESOLVED: An implementation supporting this extension will have all its VkQueue share the same time domain.
futureTimestamp = calibratedTimestamp + deltaNanoseconds / timestampPeriod
6) Can the host and device timestamp values drift apart over longer periods of time?
RESOLVED: Yes, especially as some time domains by definition allow for that to happen (e.g. CLOCK_MONOTONIC is subject to NTP adjustments). Thus it is recommended that applications re-calibrate from time to time.
7) Should we add a query for reporting the maximum deviation of the timestamp values returned by calibrated timestamp queries?
RESOLVED: A global query seems inappropriate and difficult to enforce. However, it is possible to return the maximum deviation any single calibrated timestamp query can have by sampling one of the time domains twice as follows:
timestampX = timestampX_before = SampleTimeDomain(X)
for each time domain Y != X
timestampY = SampleTimeDomain(Y)
timestampX_after = SampleTimeDomain(X)
maxDeviation = timestampX_after - timestampX_before
8) Can the maximum deviation reported ever be zero?
RESOLVED: Unless the tick of each clock corresponding to the set of time domains coincides and all clocks can literally be sampled simutaneously, there is not really a possibility for the maximum deviation to be zero, so by convention the maximum deviation is always at least the maximum of the length of the ticks of the set of time domains calibrated and thus can never be zero.
Version History
-
Revision 2, 2021-03-16 (Lionel Landwerlin)
-
Specify requirement on device timestamps
-
-
Revision 1, 2018-10-04 (Daniel Rakos)
-
Internal revisions.
-
VK_EXT_color_write_enable
- Name String
-
VK_EXT_color_write_enable - Extension Type
-
Device extension
- Registered Extension Number
-
382
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Sharif Elcott selcott
-
Other Extension Metadata
- Last Modified Date
-
2020-02-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Sharif Elcott, Google
-
Tobias Hector, AMD
-
Piers Daniell, NVIDIA
-
Description
This extension allows for selectively enabling and disabling writes to output color attachments via a pipeline dynamic state.
The intended use cases for this new state are mostly identical to those of colorWriteMask, such as selectively disabling writes to avoid feedback loops between subpasses or bandwidth savings for unused outputs. By making the state dynamic, one additional benefit is the ability to reduce pipeline counts and pipeline switching via shaders that write a superset of the desired data of which subsets are selected dynamically. The reason for a new state, colorWriteEnable, rather than making colorWriteMask dynamic is that, on many implementations, the more flexible per-component semantics of the colorWriteMask state cannot be made dynamic in a performant manner.
New Enum Constants
-
VK_EXT_COLOR_WRITE_ENABLE_EXTENSION_NAME -
VK_EXT_COLOR_WRITE_ENABLE_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COLOR_WRITE_ENABLE_FEATURES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_COLOR_WRITE_CREATE_INFO_EXT
-
VK_EXT_conditional_rendering
- Name String
-
VK_EXT_conditional_rendering - Extension Type
-
Device extension
- Registered Extension Number
-
82
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Vikram Kushwaha vkushwaha
-
Other Extension Metadata
- Last Modified Date
-
2018-05-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Daniel Rakos, AMD
-
Jesse Hall, Google
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
Stuart Smith, Imagination Technologies
-
Description
This extension allows the execution of one or more rendering commands to be conditional on a value in buffer memory. This may help an application reduce the latency by conditionally discarding rendering commands without application intervention. The conditional rendering commands are limited to draws, compute dispatches and clearing attachments within a conditional rendering block.
New Enum Constants
-
VK_EXT_CONDITIONAL_RENDERING_EXTENSION_NAME -
VK_EXT_CONDITIONAL_RENDERING_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_CONDITIONAL_RENDERING_INFO_EXT -
VK_STRUCTURE_TYPE_CONDITIONAL_RENDERING_BEGIN_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONDITIONAL_RENDERING_FEATURES_EXT
-
Issues
1) Should conditional rendering affect copy and blit commands?
RESOLVED: Conditional rendering should not affect copies and blits.
2) Should secondary command buffers be allowed to execute while conditional rendering is active in the primary command buffer?
RESOLVED: The rendering commands in secondary command buffer will be
affected by an active conditional rendering in primary command buffer if the
conditionalRenderingEnable is set to VK_TRUE.
Conditional rendering must not be active in the primary command buffer if
conditionalRenderingEnable is VK_FALSE.
Version History
-
Revision 1, 2018-04-19 (Vikram Kushwaha)
-
First Version
-
-
Revision 2, 2018-05-21 (Vikram Kushwaha)
-
Add new pipeline stage, access flags and limit conditional rendering to a subpass or entire render pass.
-
VK_EXT_conservative_rasterization
- Name String
-
VK_EXT_conservative_rasterization - Extension Type
-
Device extension
- Registered Extension Number
-
102
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2020-06-09
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_fragment_fully_coveredif theVkPhysicalDeviceConservativeRasterizationPropertiesEXT::fullyCoveredFragmentShaderInputVariablefeature is used. -
This extension requires
SPV_KHR_post_depth_coverageif theVkPhysicalDeviceConservativeRasterizationPropertiesEXT::conservativeRasterizationPostDepthCoveragefeature is used. -
This extension provides API support for
GL_NV_conservative_raster_underestimationif theVkPhysicalDeviceConservativeRasterizationPropertiesEXT::fullyCoveredFragmentShaderInputVariablefeature is used.
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Daniel Rakos, AMD
-
Jeff Bolz, NVIDIA
-
Slawomir Grajewski, Intel
-
Stu Smith, Imagination Technologies
-
Description
This extension adds a new rasterization mode called conservative rasterization. There are two modes of conservative rasterization; overestimation and underestimation.
When overestimation is enabled, if any part of the primitive, including its edges, covers any part of the rectangular pixel area, including its sides, then a fragment is generated with all coverage samples turned on. This extension allows for some variation in implementations by accounting for differences in overestimation, where the generating primitive size is increased at each of its edges by some sub-pixel amount to further increase conservative pixel coverage. Implementations can allow the application to specify an extra overestimation beyond the base overestimation the implementation already does. It also allows implementations to either cull degenerate primitives or rasterize them.
When underestimation is enabled, fragments are only generated if the rectangular pixel area is fully covered by the generating primitive. If supported by the implementation, when a pixel rectangle is fully covered the fragment shader input variable builtin called FullyCoveredEXT is set to true. The shader variable works in either overestimation or underestimation mode.
Implementations can process degenerate triangles and lines by either discarding them or generating conservative fragments for them. Degenerate triangles are those that end up with zero area after the rasterizer quantizes them to the fixed-point pixel grid. Degenerate lines are those with zero length after quantization.
New Enum Constants
-
VK_EXT_CONSERVATIVE_RASTERIZATION_EXTENSION_NAME -
VK_EXT_CONSERVATIVE_RASTERIZATION_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONSERVATIVE_RASTERIZATION_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_CONSERVATIVE_STATE_CREATE_INFO_EXT
-
Version History
-
Revision 1.1, 2020-09-06 (Piers Daniell)
-
Add missing SPIR-V and GLSL dependencies.
-
-
Revision 1, 2017-08-28 (Piers Daniell)
-
Internal revisions
-
VK_EXT_custom_border_color
- Name String
-
VK_EXT_custom_border_color - Extension Type
-
Device extension
- Registered Extension Number
-
288
- Revision
-
12
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Uses
- Contact
-
-
Liam Middlebrook liam-middlebrook
-
Other Extension Metadata
- Last Modified Date
-
2020-04-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Ashton, Valve
-
Hans-Kristian Arntzen, Valve
-
Philip Rebohle, Valve
-
Liam Middlebrook, NVIDIA
-
Jeff Bolz, NVIDIA
-
Tobias Hector, AMD
-
Jason Ekstrand, Intel
-
Spencer Fricke, Samsung Electronics
-
Graeme Leese, Broadcom
-
Jesse Hall, Google
-
Jan-Harald Fredriksen, ARM
-
Tom Olson, ARM
-
Stuart Smith, Imagination Technologies
-
Donald Scorgie, Imagination Technologies
-
Alex Walters, Imagination Technologies
-
Peter Quayle, Imagination Technologies
-
Description
This extension provides cross-vendor functionality to specify a custom
border color for use when the sampler address mode
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER is used.
To create a sampler which uses a custom border color set
VkSamplerCreateInfo::borderColor to one of:
-
VK_BORDER_COLOR_FLOAT_CUSTOM_EXT -
VK_BORDER_COLOR_INT_CUSTOM_EXT
When VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or
VK_BORDER_COLOR_INT_CUSTOM_EXT is used, applications must provide a
VkSamplerCustomBorderColorCreateInfoEXT in the pNext chain for
VkSamplerCreateInfo.
New Enum Constants
-
VK_EXT_CUSTOM_BORDER_COLOR_EXTENSION_NAME -
VK_EXT_CUSTOM_BORDER_COLOR_SPEC_VERSION -
Extending VkBorderColor:
-
VK_BORDER_COLOR_FLOAT_CUSTOM_EXT -
VK_BORDER_COLOR_INT_CUSTOM_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_SAMPLER_CUSTOM_BORDER_COLOR_CREATE_INFO_EXT
-
Issues
1) Should VkClearColorValue be used for the border color value, or should we have our own struct/union? Do we need to specify the type of the input values for the components? This is more of a concern if VkClearColorValue is used here because it provides a union of float,int,uint types.
RESOLVED: Will reuse existing VkClearColorValue structure in order to easily take advantage of float,int,uint borderColor types.
2) For hardware which supports a limited number of border colors what happens if that number is exceeded? Should this be handled by the driver unbeknownst to the application? In Revision 1 we had solved this issue using a new Object type, however that may have lead to additional system resource consumption which would otherwise not be required.
RESOLVED: Added
VkPhysicalDeviceCustomBorderColorPropertiesEXT::maxCustomBorderColorSamplers
for tracking implementation-specific limit, and Valid Usage statement
handling overflow.
3) Should this be supported for immutable samplers at all, or by a feature bit? Some implementations may not be able to support custom border colors on immutable samplers — is it worthwhile enabling this to work on them for implementations that can support it, or forbidding it entirely.
RESOLVED: Samplers created with a custom border color are forbidden from being immutable. This resolves concerns for implementations where the custom border color is an index to a LUT instead of being directly embedded into sampler state.
4) Should UINT and SINT (unsigned integer and signed integer) border color types be separated or should they be combined into one generic INT (integer) type?
RESOLVED: Separating these does not make much sense as the existing fixed border color types do not have this distinction, and there is no reason in hardware to do so. This separation would also create unnecessary work and considerations for the application.
Version History
-
Revision 1, 2019-10-10 (Joshua Ashton)
-
Internal revisions.
-
-
Revision 2, 2019-10-11 (Liam Middlebrook)
-
Remove VkCustomBorderColor object and associated functions
-
Add issues concerning HW limitations for custom border color count
-
-
Revision 3, 2019-10-12 (Joshua Ashton)
-
Re-expose the limits for the maximum number of unique border colors
-
Add extra details about border color tracking
-
Fix typos
-
-
Revision 4, 2019-10-12 (Joshua Ashton)
-
Changed maxUniqueCustomBorderColors to a uint32_t from a VkDeviceSize
-
-
Revision 5, 2019-10-14 (Liam Middlebrook)
-
Added features bit
-
-
Revision 6, 2019-10-15 (Joshua Ashton)
-
Type-ize VK_BORDER_COLOR_CUSTOM
-
Fix const-ness on
pNextof VkSamplerCustomBorderColorCreateInfoEXT
-
-
Revision 7, 2019-11-26 (Liam Middlebrook)
-
Renamed maxUniqueCustomBorderColors to maxCustomBorderColors
-
-
Revision 8, 2019-11-29 (Joshua Ashton)
-
Renamed borderColor member of VkSamplerCustomBorderColorCreateInfoEXT to customBorderColor
-
-
Revision 9, 2020-02-19 (Joshua Ashton)
-
Renamed maxCustomBorderColors to maxCustomBorderColorSamplers
-
-
Revision 10, 2020-02-21 (Joshua Ashton)
-
Added format to VkSamplerCustomBorderColorCreateInfoEXT and feature bit
-
-
Revision 11, 2020-04-07 (Joshua Ashton)
-
Dropped UINT/SINT border color differences, consolidated types
-
-
Revision 12, 2020-04-16 (Joshua Ashton)
-
Renamed VK_BORDER_COLOR_CUSTOM_FLOAT_EXT to VK_BORDER_COLOR_FLOAT_CUSTOM_EXT for consistency
-
VK_EXT_debug_utils
- Name String
-
VK_EXT_debug_utils - Extension Type
-
Instance extension
- Registered Extension Number
-
129
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Use
- Contact
-
-
Mark Young marky-lunarg
-
Other Extension Metadata
- Last Modified Date
-
2020-04-03
- Revision
-
2
- IP Status
-
No known IP claims.
- Dependencies
-
-
This extension is written against version 1.0 of the Vulkan API.
-
Requires VkObjectType
-
- Contributors
-
-
Mark Young, LunarG
-
Baldur Karlsson
-
Ian Elliott, Google
-
Courtney Goeltzenleuchter, Google
-
Karl Schultz, LunarG
-
Mark Lobodzinski, LunarG
-
Mike Schuchardt, LunarG
-
Jaakko Konttinen, AMD
-
Dan Ginsburg, Valve Software
-
Rolando Olivares, Epic Games
-
Dan Baker, Oxide Games
-
Kyle Spagnoli, NVIDIA
-
Jon Ashburn, LunarG
-
Piers Daniell, NVIDIA
-
Description
Due to the nature of the Vulkan interface, there is very little error
information available to the developer and application.
By using the VK_EXT_debug_utils extension, developers can obtain more
information.
When combined with validation layers, even more detailed feedback on the
application’s use of Vulkan will be provided.
This extension provides the following capabilities:
-
The ability to create a debug messenger which will pass along debug messages to an application supplied callback.
-
The ability to identify specific Vulkan objects using a name or tag to improve tracking.
-
The ability to identify specific sections within a
VkQueueorVkCommandBufferusing labels to aid organization and offline analysis in external tools.
The main difference between this extension and VK_EXT_debug_report
and VK_EXT_debug_marker is that those extensions use
VkDebugReportObjectTypeEXT to identify objects.
This extension uses the core VkObjectType in place of
VkDebugReportObjectTypeEXT.
The primary reason for this move is that no future object type handle
enumeration values will be added to VkDebugReportObjectTypeEXT since
the creation of VkObjectType.
In addition, this extension combines the functionality of both
VK_EXT_debug_report and VK_EXT_debug_marker by allowing
object name and debug markers (now called labels) to be returned to the
application’s callback function.
This should assist in clarifying the details of a debug message including:
what objects are involved and potentially which location within a
VkQueue or VkCommandBuffer the message occurred.
New Enum Constants
-
VK_EXT_DEBUG_UTILS_EXTENSION_NAME -
VK_EXT_DEBUG_UTILS_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_DEBUG_UTILS_MESSENGER_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT -
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT -
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT -
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_TAG_INFO_EXT
-
Examples
Example 1
VK_EXT_debug_utils allows an application to register multiple callbacks
with any Vulkan component wishing to report debug information.
Some callbacks may log the information to a file, others may cause a debug
break point or other application defined behavior.
An application can register callbacks even when no validation layers are
enabled, but they will only be called for loader and, if implemented, driver
events.
To capture events that occur while creating or destroying an instance an
application can link a VkDebugUtilsMessengerCreateInfoEXT structure
to the pNext element of the VkInstanceCreateInfo structure given
to vkCreateInstance.
Example uses: Create three callback objects.
One will log errors and warnings to the debug console using Windows
OutputDebugString.
The second will cause the debugger to break at that callback when an error
happens and the third will log warnings to stdout.
extern VkInstance instance;
VkResult res;
VkDebugUtilsMessengerEXT cb1, cb2, cb3;
// Must call extension functions through a function pointer:
PFN_vkCreateDebugUtilsMessengerEXT pfnCreateDebugUtilsMessengerEXT = (PFN_vkCreateDebugUtilsMessengerEXT)vkGetInstanceProcAddr(instance, "vkCreateDebugUtilsMessengerEXT");
PFN_vkDestroyDebugUtilsMessengerEXT pfnDestroyDebugUtilsMessengerEXT = (PFN_vkDestroyDebugUtilsMessengerEXT)vkGetInstanceProcAddr(instance, "vkDestroyDebugUtilsMessengerEXT");
VkDebugUtilsMessengerCreateInfoEXT callback1 = {
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT, // sType
NULL, // pNext
0, // flags
VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT | // messageSeverity
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT | // messageType
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
myOutputDebugString, // pfnUserCallback
NULL // pUserData
};
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, NULL, &cb1);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
callback1.messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT;
callback1.pfnUserCallback = myDebugBreak;
callback1.pUserData = NULL;
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, NULL, &cb2);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
VkDebugUtilsMessengerCreateInfoEXT callback3 = {
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT, // sType
NULL, // pNext
0, // flags
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT, // messageSeverity
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT | // messageType
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
mystdOutLogger, // pfnUserCallback
NULL // pUserData
};
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback3, NULL, &cb3);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
...
// Remove callbacks when cleaning up
pfnDestroyDebugUtilsMessengerEXT(instance, cb1, NULL);
pfnDestroyDebugUtilsMessengerEXT(instance, cb2, NULL);
pfnDestroyDebugUtilsMessengerEXT(instance, cb3, NULL);
Example 2
Associate a name with an image, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages.
extern VkInstance instance;
extern VkDevice device;
extern VkImage image;
// Must call extension functions through a function pointer:
PFN_vkSetDebugUtilsObjectNameEXT pfnSetDebugUtilsObjectNameEXT = (PFN_vkSetDebugUtilsObjectNameEXT)vkGetInstanceProcAddr(instance, "vkSetDebugUtilsObjectNameEXT");
// Set a name on the image
const VkDebugUtilsObjectNameInfoEXT imageNameInfo =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT, // sType
NULL, // pNext
VK_OBJECT_TYPE_IMAGE, // objectType
(uint64_t)image, // objectHandle
"Brick Diffuse Texture", // pObjectName
};
pfnSetDebugUtilsObjectNameEXT(device, &imageNameInfo);
// A subsequent error might print:
// Image 'Brick Diffuse Texture' (0xc0dec0dedeadbeef) is used in a
// command buffer with no memory bound to it.
Example 3
Annotating regions of a workload with naming information so that offline analysis tools can display a more usable visualization of the commands submitted.
extern VkInstance instance;
extern VkCommandBuffer commandBuffer;
// Must call extension functions through a function pointer:
PFN_vkQueueBeginDebugUtilsLabelEXT pfnQueueBeginDebugUtilsLabelEXT = (PFN_vkQueueBeginDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkQueueBeginDebugUtilsLabelEXT");
PFN_vkQueueEndDebugUtilsLabelEXT pfnQueueEndDebugUtilsLabelEXT = (PFN_vkQueueEndDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkQueueEndDebugUtilsLabelEXT");
PFN_vkCmdBeginDebugUtilsLabelEXT pfnCmdBeginDebugUtilsLabelEXT = (PFN_vkCmdBeginDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkCmdBeginDebugUtilsLabelEXT");
PFN_vkCmdEndDebugUtilsLabelEXT pfnCmdEndDebugUtilsLabelEXT = (PFN_vkCmdEndDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkCmdEndDebugUtilsLabelEXT");
PFN_vkCmdInsertDebugUtilsLabelEXT pfnCmdInsertDebugUtilsLabelEXT = (PFN_vkCmdInsertDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkCmdInsertDebugUtilsLabelEXT");
// Describe the area being rendered
const VkDebugUtilsLabelEXT houseLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
"Brick House", // pLabelName
{ 1.0f, 0.0f, 0.0f, 1.0f }, // color
};
// Start an annotated group of calls under the 'Brick House' name
pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &houseLabel);
{
// A mutable structure for each part being rendered
VkDebugUtilsLabelEXT housePartLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
NULL, // pLabelName
{ 0.0f, 0.0f, 0.0f, 0.0f }, // color
};
// Set the name and insert the marker
housePartLabel.pLabelName = "Walls";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
// Insert the drawcall for the walls
vkCmdDrawIndexed(commandBuffer, 1000, 1, 0, 0, 0);
// Insert a recursive region for two sets of windows
housePartLabel.pLabelName = "Windows";
pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
{
vkCmdDrawIndexed(commandBuffer, 75, 6, 1000, 0, 0);
vkCmdDrawIndexed(commandBuffer, 100, 2, 1450, 0, 0);
}
pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
housePartLabel.pLabelName = "Front Door";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
vkCmdDrawIndexed(commandBuffer, 350, 1, 1650, 0, 0);
housePartLabel.pLabelName = "Roof";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
vkCmdDrawIndexed(commandBuffer, 500, 1, 2000, 0, 0);
}
// End the house annotation started above
pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
// Do other work
vkEndCommandBuffer(commandBuffer);
// Describe the queue being used
const VkDebugUtilsLabelEXT queueLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
"Main Render Work", // pLabelName
{ 0.0f, 1.0f, 0.0f, 1.0f }, // color
};
// Identify the queue label region
pfnQueueBeginDebugUtilsLabelEXT(queue, &queueLabel);
// Submit the work for the main render thread
const VkCommandBuffer cmd_bufs[] = {commandBuffer};
VkSubmitInfo submit_info = {.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO,
.pNext = NULL,
.waitSemaphoreCount = 0,
.pWaitSemaphores = NULL,
.pWaitDstStageMask = NULL,
.commandBufferCount = 1,
.pCommandBuffers = cmd_bufs,
.signalSemaphoreCount = 0,
.pSignalSemaphores = NULL};
vkQueueSubmit(queue, 1, &submit_info, fence);
// End the queue label region
pfnQueueEndDebugUtilsLabelEXT(queue);
Issues
1) Should we just name this extension VK_EXT_debug_report2
RESOLVED: No. There is enough additional changes to the structures to break backwards compatibility. So, a new name was decided that would not indicate any interaction with the previous extension.
2) Will validation layers immediately support all the new features.
RESOLVED: Not immediately.
As one can imagine, there is a lot of work involved with converting the
validation layer logging over to the new functionality.
Basic logging, as seen in the origin VK_EXT_debug_report extension
will be made available immediately.
However, adding the labels and object names will take time.
Since the priority for Khronos at this time is to continue focusing on Valid
Usage statements, it may take a while before the new functionality is fully
exposed.
3) If the validation layers will not expose the new functionality immediately, then what is the point of this extension?
RESOLVED: We needed a replacement for VK_EXT_debug_report because
the VkDebugReportObjectTypeEXT enumeration will no longer be updated
and any new objects will need to be debugged using the new functionality
provided by this extension.
4) Should this extension be split into two separate parts (1 extension that is an instance extension providing the callback functionality, and another device extension providing the general debug marker and annotation functionality)?
RESOLVED: No, the functionality for this extension is too closely related. If we did split up the extension, where would the structures and enums live, and how would you define that the device behavior in the instance extension is really only valid if the device extension is enabled, and the functionality is passed in. It is cleaner to just define this all as an instance extension, plus it allows the application to enable all debug functionality provided with one enable string during vkCreateInstance.
Version History
-
Revision 1, 2017-09-14 (Mark Young and all listed Contributors)
-
Initial draft, based on
VK_EXT_debug_reportandVK_EXT_debug_markerin addition to previous feedback supplied from various companies including Valve, Epic, and Oxide games.
-
-
Revision 2, 2020-04-03 (Mark Young and Piers Daniell)
-
Updated to allow either
NULLor an empty string to be passed in forpObjectNameinVkDebugUtilsObjectNameInfoEXT, because the loader and various drivers supportNULLalready.
-
VK_EXT_depth_clip_control
- Name String
-
VK_EXT_depth_clip_control - Extension Type
-
Device extension
- Registered Extension Number
-
356
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Special Use
- Contact
-
-
Shahbaz Youssefi syoussefi
-
Other Extension Metadata
- Last Modified Date
-
2021-11-09
- Contributors
-
-
Spencer Fricke, Samsung Electronics
-
Shahbaz Youssefi, Google
-
Ralph Potter, Samsung Electronics
-
Description
This extension allows the application to use the OpenGL depth range in NDC, i.e. with depth in range [-1, 1], as opposed to Vulkan’s default of [0, 1]. The purpose of this extension is to allow efficient layering of OpenGL over Vulkan, by avoiding emulation in the pre-rasterization shader stages. This emulation, which effectively duplicates gl_Position but with a different depth value, costs ALU and consumes shader output components that the implementation may not have to spare to meet OpenGL minimum requirements.
New Enum Constants
-
VK_EXT_DEPTH_CLIP_CONTROL_EXTENSION_NAME -
VK_EXT_DEPTH_CLIP_CONTROL_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLIP_CONTROL_FEATURES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_DEPTH_CLIP_CONTROL_CREATE_INFO_EXT
-
Issues
1) Should this extension include an origin control option to match GL_LOWER_LEFT found in ARB_clip_control?
RESOLVED: No. The fix for porting over the origin is a simple y-axis flip. The depth clip control is a much harder problem to solve than what this extension is aimed to solve. Adding an equivalent to GL_LOWER_LEFT would require more testing.
2) Should this pipeline state be dynamic?
RESOLVED: Yes.
The purpose of this extension is to emulate the OpenGL depth range, which is
expected to be globally fixed (in case of OpenGL ES) or very infrequently
changed (with glClipControl in OpenGL).
3) Should the control provided in this extension be an enum that could be extended in the future?
RESOLVED: No.
It is highly unlikely that the depth range is changed to anything other than
[0, 1] in the future.
Should that happen a new extension will be required to extend such an enum,
and that extension might as well add a new struct to chain to
VkPipelineViewportStateCreateInfo::pNext instead.
Version History
-
Revision 0, 2020-10-01 (Spencer Fricke)
-
Internal revisions
-
-
Revision 1, 2020-11-26 (Shahbaz Youssefi)
-
Language fixes
-
VK_EXT_depth_clip_enable
- Name String
-
VK_EXT_depth_clip_enable - Extension Type
-
Device extension
- Registered Extension Number
-
103
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Use
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2018-12-20
- Contributors
-
-
Daniel Rakos, AMD
-
Henri Verbeet, CodeWeavers
-
Jeff Bolz, NVIDIA
-
Philip Rebohle, DXVK
-
Tobias Hector, AMD
-
Description
This extension allows the depth clipping operation, that is normally
implicitly controlled by
VkPipelineRasterizationStateCreateInfo::depthClampEnable, to
instead be controlled explicitly by
VkPipelineRasterizationDepthClipStateCreateInfoEXT::depthClipEnable.
This is useful for translating DX content which assumes depth clamping is always enabled, but depth clip can be controlled by the DepthClipEnable rasterization state (D3D12_RASTERIZER_DESC).
New Enum Constants
-
VK_EXT_DEPTH_CLIP_ENABLE_EXTENSION_NAME -
VK_EXT_DEPTH_CLIP_ENABLE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLIP_ENABLE_FEATURES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_DEPTH_CLIP_STATE_CREATE_INFO_EXT
-
VK_EXT_depth_range_unrestricted
- Name String
-
VK_EXT_depth_range_unrestricted - Extension Type
-
Device extension
- Registered Extension Number
-
14
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2017-06-22
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension removes the VkViewport minDepth and
maxDepth restrictions that the values must be between 0.0 and 1.0,
inclusive.
It also removes the same restriction on
VkPipelineDepthStencilStateCreateInfo minDepthBounds and
maxDepthBounds.
Finally it removes the restriction on the depth value in
VkClearDepthStencilValue.
New Enum Constants
-
VK_EXT_DEPTH_RANGE_UNRESTRICTED_EXTENSION_NAME -
VK_EXT_DEPTH_RANGE_UNRESTRICTED_SPEC_VERSION
Issues
1) How do VkViewport minDepth and maxDepth values outside
of the 0.0 to 1.0 range interact with
Primitive Clipping?
RESOLVED: The behavior described in Primitive
Clipping still applies.
If depth clamping is disabled the depth values are still clipped to 0
≤ zc ≤ wc before the viewport transform.
If depth clamping is enabled the above equation is ignored and the depth
values are instead clamped to the VkViewport minDepth and
maxDepth values, which in the case of this extension can be outside of
the 0.0 to 1.0 range.
2) What happens if a resulting depth fragment is outside of the 0.0 to
1.0 range and the depth buffer is fixed-point rather than floating-point?
RESOLVED: The supported range of a fixed-point depth buffer is 0.0 to
1.0 and depth fragments are clamped to this range.
VK_EXT_device_memory_report
- Name String
-
VK_EXT_device_memory_report - Extension Type
-
Device extension
- Registered Extension Number
-
285
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Special Use
- Contact
-
-
Yiwei Zhang zhangyiwei
-
Other Extension Metadata
- Last Modified Date
-
2021-01-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Yiwei Zhang, Google
-
Jesse Hall, Google
-
Description
This device extension allows registration of device memory event callbacks upon device creation, so that applications or middleware can obtain detailed information about memory usage and how memory is associated with Vulkan objects. This extension exposes the actual underlying device memory usage, including allocations that are not normally visible to the application, such as memory consumed by vkCreateGraphicsPipelines. It is intended primarily for use by debug tooling rather than for production applications.
New Enum Constants
-
VK_EXT_DEVICE_MEMORY_REPORT_EXTENSION_NAME -
VK_EXT_DEVICE_MEMORY_REPORT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_DEVICE_MEMORY_REPORT_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_DEVICE_MEMORY_REPORT_CALLBACK_DATA_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_MEMORY_REPORT_FEATURES_EXT
-
Issues
1) Should this be better expressed as an extension to VK_EXT_debug_utils and its general-purpose messenger construct?
RESOLVED: No.
The intended lifecycle is quite different.
We want to make this extension tied to the device’s lifecycle.
Each ICD just handles its own implementation of this extension, and this
extension will only be directly exposed from the ICD.
So we can avoid the extra implementation complexity used to accommodate the
flexibility of VK_EXT_debug_utils extension.
2) Can we extend and use the existing internal allocation callbacks instead of adding the new callback structure in this extension?
RESOLVED: No.
Our memory reporting layer that combines this information with other memory
information it collects directly (e.g. bindings of resources to
VkDeviceMemory) would have to intercept all entry points that take a
VkAllocationCallbacks parameter and inject its own
pfnInternalAllocation and pfnInternalFree.
That may be doable for the extensions we know about, but not for ones we do
not.
The proposal would work fine in the face of most unknown extensions.
But even for ones we know about, since apps can provide a different set of
callbacks and userdata and those can be retained by the driver and used
later (esp.
for pool object, but not just those), we would have to dynamically allocate
the interception trampoline every time.
That is getting to be an unreasonably large amount of complexity and
(possibly) overhead.
We are interested in both alloc/free and import/unimport.
The latter is fairly important for tracking (and avoiding double-counting)
of swapchain images (still true with “native swapchains” based on external
memory) and media/camera interop.
Though we might be able to handle this with additional
VkInternalAllocationType values, for import/export we do want to be
able to tie this to the external resource, which is one thing that the
memoryObjectId is for.
The internal alloc/free callbacks are not extensible except via new VkInternalAllocationType values. The VkDeviceMemoryReportCallbackDataEXT in this extension is extensible. That was deliberate: there is a real possibility we will want to get extra information in the future. As one example, currently this reports only physical allocations, but we believe there are interesting cases for tracking how populated that VA region is.
The callbacks are clearly specified as only callable within the context of a call from the app into Vulkan. We believe there are some cases where drivers can allocate device memory asynchronously. This was one of the sticky issues that derailed the internal device memory allocation reporting design (which is essentially what this extension is trying to do) leading up to 1.0.
VkAllocationCallbacks is described in a section called “Host memory” and the intro to it is very explicitly about host memory. The other callbacks are all inherently about host memory. But this extension is very focused on device memory.
3) Should the callback be reporting which heap is used?
RESOLVED: Yes.
It is important for non-UMA systems to have all the device memory
allocations attributed to the corresponding device memory heaps.
For internally-allocated device memory, heapIndex will always
correspond to an advertised heap, rather than having a magic value
indicating a non-advertised heap.
Drivers can advertise heaps that do not have any corresponding memory types
if they need to.
4) Should we use an array of callback for the layers to intercept instead of
chaining multiple of the VkDeviceDeviceMemoryReportCreateInfoEXT
structures in the pNext of VkDeviceCreateInfo?
RESOLVED No.
The pointer to the VkDeviceDeviceMemoryReportCreateInfoEXT structure
itself is const and you cannot just cast it away.
Thus we cannot update the callback array inside the structure.
In addition, we cannot drop this pNext chain either, so making a copy
of this whole structure does not work either.
5) Should we track bulk allocations shared among multiple objects?
RESOLVED No.
Take the shader heap as an example.
Some implementations will let multiple VkPipeline objects share the
same shader heap.
We are not asking the implementation to report VK_OBJECT_TYPE_PIPELINE
along with a VK_NULL_HANDLE for this bulk allocation.
Instead, this bulk allocation is considered as a layer below what this
extension is interested in.
Later, when the actual VkPipeline objects are created by suballocating
from the bulk allocation, we ask the implementation to report the valid
handles of the VkPipeline objects along with the actual suballocated
sizes and different memoryObjectId.
6) Can we require the callbacks to be always called in the same thread with the Vulkan commands?
RESOLVED No. Some implementations might choose to multiplex work from multiple application threads into a single backend thread and perform JIT allocations as a part of that flow. Since this behavior is theoretically legit, we cannot require the callbacks to be always called in the same thread with the Vulkan commands, and the note is to remind the applications to handle this case properly.
7) Should we add an additional “allocation failed” event type with things like size and heap index reported?
RESOLVED Yes.
This fits in well with the callback infrastructure added in this extension,
and implementation touches the same code and has the same overheads as the
rest of the extension.
It could help debugging things like getting an
VK_ERROR_OUT_OF_HOST_MEMORY error when ending a command buffer.
Right now the allocation failure could have happened anywhere during
recording, and a callback would be really useful to understand where and
why.
Version History
-
Revision 1, 2020-08-26 (Yiwei Zhang)
-
Initial version
-
-
Revision 2, 2021-01-06 (Yiwei Zhang)
-
Minor description update
-
VK_EXT_direct_mode_display
- Name String
-
VK_EXT_direct_mode_display - Extension Type
-
Instance extension
- Registered Extension Number
-
89
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_displayto be enabled
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Liam Middlebrook, NVIDIA
-
Description
This is extension, along with related platform extensions, allows applications to take exclusive control of displays associated with a native windowing system. This is especially useful for virtual reality applications that wish to hide HMDs (head mounted displays) from the native platform’s display management system, desktop, and/or other applications.
New Enum Constants
-
VK_EXT_DIRECT_MODE_DISPLAY_EXTENSION_NAME -
VK_EXT_DIRECT_MODE_DISPLAY_SPEC_VERSION
Issues
1) Should this extension and its related platform-specific extensions
leverage VK_KHR_display, or provide separate equivalent interfaces.
RESOLVED: Use VK_KHR_display concepts and objects.
VK_KHR_display can be used to enumerate all displays on the system,
including those attached to/in use by a window system or native platform,
but VK_KHR_display_swapchain will fail to create a swapchain on
in-use displays.
This extension and its platform-specific children will allow applications to
grab in-use displays away from window systems and/or native platforms,
allowing them to be used with VK_KHR_display_swapchain.
2) Are separate calls needed to acquire displays and enable direct mode?
RESOLVED: No, these operations happen in one combined command. Acquiring a display puts it into direct mode.
VK_EXT_directfb_surface
- Name String
-
VK_EXT_directfb_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
347
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Nicolas Caramelli caramelli
-
Other Extension Metadata
- Last Modified Date
-
2020-06-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Nicolas Caramelli
-
Description
The VK_EXT_directfb_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) that refers to a DirectFB
IDirectFBSurface, as well as a query to determine support for rendering
via DirectFB.
New Enum Constants
-
VK_EXT_DIRECTFB_SURFACE_EXTENSION_NAME -
VK_EXT_DIRECTFB_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DIRECTFB_SURFACE_CREATE_INFO_EXT
-
VK_EXT_discard_rectangles
- Name String
-
VK_EXT_discard_rectangles - Extension Type
-
Device extension
- Registered Extension Number
-
100
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2016-12-22
- Interactions and External Dependencies
-
-
Interacts with
VK_KHR_device_group -
Interacts with Vulkan 1.1
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension provides additional orthogonally aligned “discard rectangles” specified in framebuffer-space coordinates that restrict rasterization of all points, lines and triangles.
From zero to an implementation-dependent limit (specified by
maxDiscardRectangles) number of discard rectangles can be operational
at once.
When one or more discard rectangles are active, rasterized fragments can
either survive if the fragment is within any of the operational discard
rectangles (VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT mode) or be
rejected if the fragment is within any of the operational discard rectangles
(VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT mode).
These discard rectangles operate orthogonally to the existing scissor test functionality. The discard rectangles can be different for each physical device in a device group by specifying the device mask and setting discard rectangle dynamic state.
New Enum Constants
-
VK_EXT_DISCARD_RECTANGLES_EXTENSION_NAME -
VK_EXT_DISCARD_RECTANGLES_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT
-
VK_EXT_display_control
- Name String
-
VK_EXT_display_control - Extension Type
-
Device extension
- Registered Extension Number
-
92
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_display_surface_counterto be enabled for any device-level functionality -
Requires
VK_KHR_swapchainto be enabled for any device-level functionality
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Daniel Vetter, Intel
-
Description
This extension defines a set of utility functions for use with the
VK_KHR_display and VK_KHR_display_swapchain extensions.
New Enum Constants
-
VK_EXT_DISPLAY_CONTROL_EXTENSION_NAME -
VK_EXT_DISPLAY_CONTROL_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_EVENT_INFO_EXT -
VK_STRUCTURE_TYPE_DISPLAY_EVENT_INFO_EXT -
VK_STRUCTURE_TYPE_DISPLAY_POWER_INFO_EXT -
VK_STRUCTURE_TYPE_SWAPCHAIN_COUNTER_CREATE_INFO_EXT
-
Issues
1) Should this extension add an explicit “WaitForVsync” API or a fence signaled at vsync that the application can wait on?
RESOLVED: A fence. A separate API could later be provided that allows exporting the fence to a native object that could be inserted into standard run loops on POSIX and Windows systems.
2) Should callbacks be added for a vsync event, or in general to monitor events in Vulkan?
RESOLVED: No, fences should be used. Some events are generated by interrupts which are managed in the kernel. In order to use a callback provided by the application, drivers would need to have the userspace driver spawn threads that would wait on the kernel event, and hence the callbacks could be difficult for the application to synchronize with its other work given they would arrive on a foreign thread.
3) Should vblank or scanline events be exposed?
RESOLVED: Vblank events. Scanline events could be added by a separate extension, but the latency of processing an interrupt and waking up a userspace event is high enough that the accuracy of a scanline event would be rather low. Further, per-scanline interrupts are not supported by all hardware.
VK_EXT_display_surface_counter
- Name String
-
VK_EXT_display_surface_counter - Extension Type
-
Instance extension
- Registered Extension Number
-
91
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_displayto be enabled
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Daniel Vetter, Intel
-
Description
This extension defines a vertical blanking period counter associated with display surfaces. It provides a mechanism to query support for such a counter from a VkSurfaceKHR object.
New Enum Constants
-
VK_EXT_DISPLAY_SURFACE_COUNTER_EXTENSION_NAME -
VK_EXT_DISPLAY_SURFACE_COUNTER_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES2_EXT -
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_EXT
-
VK_EXT_external_memory_dma_buf
- Name String
-
VK_EXT_external_memory_dma_buf - Extension Type
-
Device extension
- Registered Extension Number
-
126
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_memory_fdto be enabled for any device-level functionality
-
- Contact
-
-
Chad Versace chadversary
-
Other Extension Metadata
- Last Modified Date
-
2017-10-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Chad Versace, Google
-
James Jones, NVIDIA
-
Jason Ekstrand, Intel
-
Description
A dma_buf is a type of file descriptor, defined by the Linux kernel,
that allows sharing memory across kernel device drivers and across
processes.
This extension enables applications to import a dma_buf as
VkDeviceMemory, to export VkDeviceMemory as a dma_buf, and
to create VkBuffer objects that can be bound to that memory.
New Enum Constants
-
VK_EXT_EXTERNAL_MEMORY_DMA_BUF_EXTENSION_NAME -
VK_EXT_EXTERNAL_MEMORY_DMA_BUF_SPEC_VERSION -
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT
-
Issues
1) How does the application, when creating a VkImage that it intends
to bind to dma_buf VkDeviceMemory containing an externally
produced image, specify the memory layout (such as row pitch and DRM format
modifier) of the VkImage? In other words, how does the application
achieve behavior comparable to that provided by
EGL_EXT_image_dma_buf_import
and
EGL_EXT_image_dma_buf_import_modifiers
?
RESOLVED: Features comparable to those in
EGL_EXT_image_dma_buf_import
and
EGL_EXT_image_dma_buf_import_modifiers
will be provided by an extension layered atop this one.
2) Without the ability to specify the memory layout of external dma_buf
images, how is this extension useful?
RESOLVED: This extension provides exactly one new feature: the ability to
import/export between dma_buf and VkDeviceMemory.
This feature, together with features provided by
VK_KHR_external_memory_fd, is sufficient to bind a VkBuffer
to dma_buf.
VK_EXT_external_memory_host
- Name String
-
VK_EXT_external_memory_host - Extension Type
-
Device extension
- Registered Extension Number
-
179
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_memoryto be enabled for any device-level functionality
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2017-11-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Jaakko Konttinen, AMD
-
David Mao, AMD
-
Daniel Rakos, AMD
-
Tobias Hector, Imagination Technologies
-
Jason Ekstrand, Intel
-
James Jones, NVIDIA
-
Description
This extension enables an application to import host allocations and host mapped foreign device memory to Vulkan memory objects.
New Enum Constants
-
VK_EXT_EXTERNAL_MEMORY_HOST_EXTENSION_NAME -
VK_EXT_EXTERNAL_MEMORY_HOST_SPEC_VERSION -
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT -
VK_STRUCTURE_TYPE_MEMORY_HOST_POINTER_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_HOST_PROPERTIES_EXT
-
Issues
1) What memory type has to be used to import host pointers?
RESOLVED: Depends on the implementation. Applications have to use the new vkGetMemoryHostPointerPropertiesEXT command to query the supported memory types for a particular host pointer. The reported memory types may include memory types that come from a memory heap that is otherwise not usable for regular memory object allocation and thus such a heap’s size may be zero.
2) Can the application still access the contents of the host allocation after importing?
RESOLVED: Yes. However, usual synchronization requirements apply.
3) Can the application free the host allocation?
RESOLVED: No, it violates valid usage conditions. Using the memory object imported from a host allocation that is already freed thus results in undefined behavior.
4) Is vkMapMemory expected to return the same host address which was specified when importing it to the memory object?
RESOLVED: No. Implementations are allowed to return the same address but it is not required. Some implementations might return a different virtual mapping of the allocation, although the same physical pages will be used.
5) Is there any limitation on the alignment of the host pointer and/or size?
RESOLVED: Yes.
Both the address and the size have to be an integer multiple of
minImportedHostPointerAlignment.
In addition, some platforms and foreign devices may have additional
restrictions.
6) Can the same host allocation be imported multiple times into a given physical device?
RESOLVED: No, at least not guaranteed by this extension. Some platforms do not allow locking the same physical pages for device access multiple times, so attempting to do it may result in undefined behavior.
7) Does this extension support exporting the new handle type?
RESOLVED: No.
8) Should we include the possibility to import host mapped foreign device memory using this API?
RESOLVED: Yes, through a separate handle type. Implementations are still allowed to support only one of the handle types introduced by this extension by not returning import support for a particular handle type as returned in VkExternalMemoryPropertiesKHR.
VK_EXT_filter_cubic
- Name String
-
VK_EXT_filter_cubic - Extension Type
-
Device extension
- Registered Extension Number
-
171
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Bill Licea-Kane wwlk
-
Other Extension Metadata
- Last Modified Date
-
2019-12-13
- Contributors
-
-
Bill Licea-Kane, Qualcomm Technologies, Inc.
-
Andrew Garrard, Samsung
-
Daniel Koch, NVIDIA
-
Donald Scorgie, Imagination Technologies
-
Graeme Leese, Broadcom
-
Jan-Herald Fredericksen, ARM
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Tobias Hector, AMD
-
Tom Olson, ARM
-
Stuart Smith, Imagination Technologies
-
Description
VK_EXT_filter_cubic extends VK_IMG_filter_cubic.
It documents cubic filtering of other image view types.
It adds new structures that can be added to the pNext chain of
VkPhysicalDeviceImageFormatInfo2 and VkImageFormatProperties2
that can be used to determine which image types and which image view types
support cubic filtering.
New Enum Constants
-
VK_EXT_FILTER_CUBIC_EXTENSION_NAME -
VK_EXT_FILTER_CUBIC_SPEC_VERSION -
Extending VkFilter:
-
VK_FILTER_CUBIC_EXT
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FILTER_CUBIC_IMAGE_VIEW_IMAGE_FORMAT_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_VIEW_IMAGE_FORMAT_INFO_EXT
-
Version History
-
Revision 3, 2019-12-13 (wwlk)
-
Delete requirement to cubic filter the formats USCALED_PACKED32, SSCALED_PACKED32, UINT_PACK32, and SINT_PACK32 (cut/paste error)
-
-
Revision 2, 2019-06-05 (wwlk)
-
Clarify 1D optional
-
-
Revision 1, 2019-01-24 (wwlk)
-
Initial version
-
VK_EXT_fragment_density_map
- Name String
-
VK_EXT_fragment_density_map - Extension Type
-
Device extension
- Registered Extension Number
-
219
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Matthew Netsch mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2021-09-30
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_fragment_invocation_density -
This extension provides API support for
GL_EXT_fragment_invocation_density
-
- Contributors
-
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Robert VanReenen, Qualcomm Technologies, Inc.
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Tate Hornbeck, Qualcomm Technologies, Inc.
-
Sam Holmes, Qualcomm Technologies, Inc.
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Jan-Harald Fredriksen, ARM
-
Jeff Bolz, NVIDIA
-
Pat Brown, NVIDIA
-
Daniel Rakos, AMD
-
Piers Daniell, NVIDIA
-
Description
This extension allows an application to specify areas of the render target where the fragment shader may be invoked fewer times. These fragments are broadcasted out to multiple pixels to cover the render target.
The primary use of this extension is to reduce workloads in areas where lower quality may not be perceived such as the distorted edges of a lens or the periphery of a user’s gaze.
New Enum Constants
-
VK_EXT_FRAGMENT_DENSITY_MAP_EXTENSION_NAME -
VK_EXT_FRAGMENT_DENSITY_MAP_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageViewCreateFlagBits:
-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
-
-
Extending VkSamplerCreateFlagBits:
-
VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT -
VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT
-
If VK_KHR_format_feature_flags2 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_FRAGMENT_DENSITY_MAP_BIT_EXT
-
Version History
-
Revision 1, 2018-09-25 (Matthew Netsch)
-
Initial version
-
-
Revision 2, 2021-09-30 (Jon Leech)
-
Add interaction with
VK_KHR_format_feature_flags2tovk.xml
-
VK_EXT_fragment_density_map2
- Name String
-
VK_EXT_fragment_density_map2 - Extension Type
-
Device extension
- Registered Extension Number
-
333
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_fragment_density_mapto be enabled for any device-level functionality
-
- Contact
-
-
Matthew Netsch mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2020-06-16
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1
-
- Contributors
-
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Jonathan Tinkham, Qualcomm Technologies, Inc.
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Jan-Harald Fredriksen, ARM
-
Description
This extension adds additional features and properties to
VK_EXT_fragment_density_map in order to reduce fragment density map
host latency as well as improved queries for subsampled sampler
implementation-dependent behavior.
New Enum Constants
-
VK_EXT_FRAGMENT_DENSITY_MAP_EXTENSION_NAME -
VK_EXT_FRAGMENT_DENSITY_MAP_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageViewCreateFlagBits:
-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
-
-
Extending VkSamplerCreateFlagBits:
-
VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT -
VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT
-
If VK_KHR_format_feature_flags2 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_FRAGMENT_DENSITY_MAP_BIT_EXT
-
VK_EXT_fragment_shader_interlock
- Name String
-
VK_EXT_fragment_shader_interlock - Extension Type
-
Device extension
- Registered Extension Number
-
252
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-05-02
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_fragment_shader_interlock -
This extension provides API support for
GL_ARB_fragment_shader_interlock
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, Arm
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Ruihao Zhang, Qualcomm
-
Slawomir Grajewski, Intel
-
Spencer Fricke, Samsung
-
Description
This extension adds support for the FragmentShaderPixelInterlockEXT,
FragmentShaderSampleInterlockEXT, and
FragmentShaderShadingRateInterlockEXT capabilities from the
SPV_EXT_fragment_shader_interlock extension to Vulkan.
Enabling these capabilities provides a critical section for fragment shaders to avoid overlapping pixels being processed at the same time, and certain guarantees about the ordering of fragment shader invocations of fragments of overlapping pixels.
This extension can be useful for algorithms that need to access per-pixel data structures via shader loads and stores. Algorithms using this extension can access per-pixel data structures in critical sections without other invocations accessing the same per-pixel data. Additionally, the ordering guarantees are useful for cases where the API ordering of fragments is meaningful. For example, applications may be able to execute programmable blending operations in the fragment shader, where the destination buffer is read via image loads and the final value is written via image stores.
New Enum Constants
-
VK_EXT_FRAGMENT_SHADER_INTERLOCK_EXTENSION_NAME -
VK_EXT_FRAGMENT_SHADER_INTERLOCK_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_INTERLOCK_FEATURES_EXT
-
VK_EXT_full_screen_exclusive
- Name String
-
VK_EXT_full_screen_exclusive - Extension Type
-
Device extension
- Registered Extension Number
-
256
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_surfaceto be enabled for any device-level functionality -
Requires
VK_KHR_get_surface_capabilities2to be enabled for any device-level functionality -
Requires
VK_KHR_swapchainto be enabled for any device-level functionality
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2019-03-12
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1
-
Interacts with
VK_KHR_device_group -
Interacts with
VK_KHR_win32_surface
-
- Contributors
-
-
Hans-Kristian Arntzen, ARM
-
Slawomir Grajewski, Intel
-
Tobias Hector, AMD
-
James Jones, NVIDIA
-
Daniel Rakos, AMD
-
Jeff Juliano, NVIDIA
-
Joshua Schnarr, NVIDIA
-
Aaron Hagan, AMD
-
Description
This extension allows applications to set the policy for swapchain creation and presentation mechanisms relating to full-screen access. Implementations may be able to acquire exclusive access to a particular display for an application window that covers the whole screen. This can increase performance on some systems by bypassing composition, however it can also result in disruptive or expensive transitions in the underlying windowing system when a change occurs.
Applications can choose between explicitly disallowing or allowing this behavior, letting the implementation decide, or managing this mode of operation directly using the new vkAcquireFullScreenExclusiveModeEXT and vkReleaseFullScreenExclusiveModeEXT commands.
New Structures
-
Extending VkPhysicalDeviceSurfaceInfo2KHR, VkSwapchainCreateInfoKHR:
-
Extending VkSurfaceCapabilities2KHR:
If VK_KHR_win32_surface is supported:
New Enum Constants
-
VK_EXT_FULL_SCREEN_EXCLUSIVE_EXTENSION_NAME -
VK_EXT_FULL_SCREEN_EXCLUSIVE_SPEC_VERSION -
Extending VkResult:
-
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT -
VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT
-
If VK_KHR_win32_surface is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT
-
Issues
1) What should the extension & flag be called?
RESOLVED: VK_EXT_full_screen_exclusive.
Other options considered (prior to the app-controlled mode) were:
-
VK_EXT_smooth_fullscreen_transition
-
VK_EXT_fullscreen_behavior
-
VK_EXT_fullscreen_preference
-
VK_EXT_fullscreen_hint
-
VK_EXT_fast_fullscreen_transition
-
VK_EXT_avoid_fullscreen_exclusive
2) Do we need more than a boolean toggle?
RESOLVED: Yes.
Using an enum with default/allowed/disallowed/app-controlled enables applications to accept driver default behavior, specifically override it in either direction without implying the driver is ever required to use full-screen exclusive mechanisms, or manage this mode explicitly.
3) Should this be a KHR or EXT extension?
RESOLVED: EXT, in order to allow it to be shipped faster.
4) Can the fullscreen hint affect the surface capabilities, and if so, should the hint also be specified as input when querying the surface capabilities?
RESOLVED: Yes on both accounts.
While the hint does not guarantee a particular fullscreen mode will be used when the swapchain is created, it can sometimes imply particular modes will NOT be used. If the driver determines that it will opt-out of using a particular mode based on the policy, and knows it can only support certain capabilities if that mode is used, it would be confusing at best to the application to report those capabilities in such cases. Not allowing implementations to report this state to applications could result in situations where applications are unable to determine why swapchain creation fails when they specify certain hint values, which could result in never- terminating surface creation loops.
5) Should full-screen be one word or two?
RESOLVED: Two words.
"Fullscreen" is not in my dictionary, and web searches did not turn up definitive proof that it is a colloquially accepted compound word. Documentation for the corresponding Windows API mechanisms dithers. The text consistently uses a hyphen, but none-the-less, there is a SetFullscreenState method in the DXGI swapchain object. Given this inconclusive external guidance, it is best to adhere to the Vulkan style guidelines and avoid inventing new compound words.
Version History
-
Revision 4, 2019-03-12 (Tobias Hector)
-
Added application-controlled mode, and related functions
-
Tidied up appendix
-
-
Revision 3, 2019-01-03 (James Jones)
-
Renamed to VK_EXT_full_screen_exclusive
-
Made related adjustments to the tri-state enumerant names.
-
-
Revision 2, 2018-11-27 (James Jones)
-
Renamed to VK_KHR_fullscreen_behavior
-
Switched from boolean flag to tri-state enum
-
-
Revision 1, 2018-11-06 (James Jones)
-
Internal revision
-
VK_EXT_graphics_pipeline_library
- Name String
-
VK_EXT_graphics_pipeline_library - Extension Type
-
Device extension
- Registered Extension Number
-
321
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_pipeline_libraryto be enabled for any device-level functionality
-
- Contact
-
-
Tobias Hector tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-08-17
- Contributors
-
-
Tobias Hector, AMD
-
Chris Glover, Google
-
Jeff Leger, Qualcomm
-
Jan-Harald Fredriksen, Arm
-
Piers Daniell, NVidia
-
Boris Zanin, Mobica
-
Krzysztof Niski, NVidia
-
Dan Ginsburg, Valve
-
Sebastian Aaltonen, Unity
-
Arseny Kapoulkine, Roblox
-
Calle Lejdfors, Ubisoft
-
Tiago Rodrigues, Ubisoft
-
Francois Duranleau, Gameloft
-
Description
This extension allows the separate compilation of four distinct parts of graphics pipelines, with the intent of allowing faster pipeline loading for applications reusing the same shaders or state in multiple pipelines. Each part can be independently compiled into a graphics pipeline library, with a final link step required to create an executable pipeline that can be bound to a command buffer.
New Enum Constants
-
VK_EXT_GRAPHICS_PIPELINE_LIBRARY_EXTENSION_NAME -
VK_EXT_GRAPHICS_PIPELINE_LIBRARY_SPEC_VERSION -
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT -
VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT
-
-
Extending VkPipelineLayoutCreateFlagBits:
-
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_LIBRARY_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GRAPHICS_PIPELINE_LIBRARY_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GRAPHICS_PIPELINE_LIBRARY_PROPERTIES_EXT
-
VK_EXT_hdr_metadata
- Name String
-
VK_EXT_hdr_metadata - Extension Type
-
Device extension
- Registered Extension Number
-
106
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality
-
- Contact
-
-
Courtney Goeltzenleuchter courtney-g
-
Other Extension Metadata
- Last Modified Date
-
2018-12-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, Google
-
Description
This extension defines two new structures and a function to assign SMPTE
(the Society of Motion Picture and Television Engineers) 2086 metadata and
CTA (Consumer Technology Association) 861.3 metadata to a swapchain.
The metadata includes the color primaries, white point, and luminance range
of the reference monitor, which all together define the color volume
containing all the possible colors the reference monitor can produce.
The reference monitor is the display where creative work is done and
creative intent is established.
To preserve such creative intent as much as possible and achieve consistent
color reproduction on different viewing displays, it is useful for the
display pipeline to know the color volume of the original reference monitor
where content was created or tuned.
This avoids performing unnecessary mapping of colors that are not
displayable on the original reference monitor.
The metadata also includes the maxContentLightLevel and
maxFrameAverageLightLevel as defined by CTA 861.3.
While the general purpose of the metadata is to assist in the transformation between different color volumes of different displays and help achieve better color reproduction, it is not in the scope of this extension to define how exactly the metadata should be used in such a process. It is up to the implementation to determine how to make use of the metadata.
New Enum Constants
-
VK_EXT_HDR_METADATA_EXTENSION_NAME -
VK_EXT_HDR_METADATA_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_HDR_METADATA_EXT
-
Issues
1) Do we need a query function?
PROPOSED: No, Vulkan does not provide queries for state that the application can track on its own.
2) Should we specify default if not specified by the application?
PROPOSED: No, that leaves the default up to the display.
Version History
-
Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)
-
Initial version
-
-
Revision 2, 2018-12-19 (Courtney Goeltzenleuchter)
-
Correct implicit validity for VkHdrMetadataEXT structure
-
VK_EXT_headless_surface
- Name String
-
VK_EXT_headless_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
257
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Lisa Wu chengtianww
-
Other Extension Metadata
- Last Modified Date
-
2019-03-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Ray Smith, Arm
-
Description
The VK_EXT_headless_surface extension is an instance extension.
It provides a mechanism to create VkSurfaceKHR objects independently
of any window system or display device.
The presentation operation for a swapchain created from a headless surface
is by default a no-op, resulting in no externally-visible result.
Because there is no real presentation target, future extensions can layer on top of the headless surface to introduce arbitrary or customisable sets of restrictions or features. These could include features like saving to a file or restrictions to emulate a particular presentation target.
This functionality is expected to be useful for application and driver development because it allows any platform to expose an arbitrary or customisable set of restrictions and features of a presentation engine. This makes it a useful portable test target for applications targeting a wide range of presentation engines where the actual target presentation engines might be scarce, unavailable or otherwise undesirable or inconvenient to use for general Vulkan application development.
New Enum Constants
-
VK_EXT_HEADLESS_SURFACE_EXTENSION_NAME -
VK_EXT_HEADLESS_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_HEADLESS_SURFACE_CREATE_INFO_EXT
-
VK_EXT_image_2d_view_of_3d
- Name String
-
VK_EXT_image_2d_view_of_3d - Extension Type
-
Device extension
- Registered Extension Number
-
394
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_maintenance1to be enabled for any device-level functionality -
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Special Use
- Contact
-
-
Mike Blumenkrantz zmike
-
Other Extension Metadata
- Last Modified Date
-
2022-02-22
- IP Status
-
No known IP claims.
- Contributors
-
-
Mike Blumenkrantz, Valve
-
Piers Daniell, NVIDIA
-
Spencer Fricke, Samsung
-
Ricardo Garcia, Igalia
-
Graeme Leese, Broadcom
-
Ralph Potter, Samsung
-
Stu Smith, AMD
-
Shahbaz Youssefi, Google
-
Alex Walters, Imagination
-
Description
This extension allows a single slice of a 3D image to be used as a 2D view
in image descriptors, matching both the functionality of glBindImageTexture
in OpenGL with the layer parameter set to true and 2D view binding
provided by the extension EGL_KHR_gl_texture_3D_image.
It is primarily intended to support GL emulation.
New Enum Constants
-
VK_EXT_IMAGE_2D_VIEW_OF_3D_EXTENSION_NAME -
VK_EXT_IMAGE_2D_VIEW_OF_3D_SPEC_VERSION -
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_2D_VIEW_OF_3D_FEATURES_EXT
-
VK_EXT_image_compression_control
- Name String
-
VK_EXT_image_compression_control - Extension Type
-
Device extension
- Registered Extension Number
-
339
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-05-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Graeme Leese, Broadcom
-
Andrew Garrard, Imagination
-
Lisa Wu, Arm
-
Peter Kohaut, Arm
-
Description
This extension enables fixed-rate image compression and adds the ability to control when this kind of compression can be applied. Many implementations support some form of framebuffer compression. This is typically transparent to applications as lossless compression schemes are used. With fixed-rate compression, the compression is done at a defined bitrate. Such compression algorithms generally produce results that are visually lossless, but the results are typically not bit-exact when compared to a non-compressed result. The implementation may not be able to use the requested compression rate in all cases. This extension adds a query that can be used to determine the compression scheme and rate that was applied to an image.
New Enum Constants
-
VK_EXT_IMAGE_COMPRESSION_CONTROL_EXTENSION_NAME -
VK_EXT_IMAGE_COMPRESSION_CONTROL_SPEC_VERSION -
Extending VkResult:
-
VK_ERROR_COMPRESSION_EXHAUSTED_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_COMPRESSION_CONTROL_EXT -
VK_STRUCTURE_TYPE_IMAGE_COMPRESSION_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_COMPRESSION_CONTROL_FEATURES_EXT -
VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_EXT
-
VK_EXT_image_compression_control_swapchain
- Name String
-
VK_EXT_image_compression_control_swapchain - Extension Type
-
Device extension
- Registered Extension Number
-
438
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_image_compression_controlto be enabled for any device-level functionality
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2022-05-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Graeme Leese, Broadcom
-
Andrew Garrard, Imagination
-
Lisa Wu, Arm
-
Peter Kohaut, Arm
-
Ian Elliott, Google
-
Description
This extension enables fixed-rate image compression and adds the ability to control when this kind of compression can be applied to swapchain images.
New Enum Constants
-
VK_EXT_IMAGE_COMPRESSION_CONTROL_SWAPCHAIN_EXTENSION_NAME -
VK_EXT_IMAGE_COMPRESSION_CONTROL_SWAPCHAIN_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_COMPRESSION_CONTROL_SWAPCHAIN_FEATURES_EXT
-
VK_EXT_image_drm_format_modifier
- Name String
-
VK_EXT_image_drm_format_modifier - Extension Type
-
Device extension
- Registered Extension Number
-
159
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_bind_memory2to be enabled for any device-level functionality -
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_image_format_listto be enabled for any device-level functionality -
Requires
VK_KHR_sampler_ycbcr_conversionto be enabled for any device-level functionality
-
- Contact
-
-
Chad Versace chadversary
-
Other Extension Metadata
- Last Modified Date
-
2021-09-30
- IP Status
-
No known IP claims.
- Contributors
-
-
Antoine Labour, Google
-
Bas Nieuwenhuizen, Google
-
Chad Versace, Google
-
James Jones, NVIDIA
-
Jason Ekstrand, Intel
-
Jőrg Wagner, ARM
-
Kristian Høgsberg Kristensen, Google
-
Ray Smith, ARM
-
Description
This extension provides the ability to use DRM format modifiers with images, enabling Vulkan to better integrate with the Linux ecosystem of graphics, video, and display APIs.
Its functionality closely overlaps with
EGL_EXT_image_dma_buf_import_modifiers2
and
EGL_MESA_image_dma_buf_export3.
Unlike the EGL extensions, this extension does not require the use of a
specific handle type (such as a dma_buf) for external memory and provides
more explicit control of image creation.
Introduction to DRM Format Modifiers
A DRM format modifier is a 64-bit, vendor-prefixed, semi-opaque unsigned
integer.
Most modifiers represent a concrete, vendor-specific tiling format for
images.
Some exceptions are DRM_FORMAT_MOD_LINEAR (which is not
vendor-specific); DRM_FORMAT_MOD_NONE (which is an alias of
DRM_FORMAT_MOD_LINEAR due to historical accident); and
DRM_FORMAT_MOD_INVALID (which does not represent a tiling format).
The modifier’s vendor prefix consists of the 8 most significant bits.
The canonical list of modifiers and vendor prefixes is found in
drm_fourcc.h
in the Linux kernel source.
The other dominant source of modifiers are vendor kernel trees.
One goal of modifiers in the Linux ecosystem is to enumerate for each vendor a reasonably sized set of tiling formats that are appropriate for images shared across processes, APIs, and/or devices, where each participating component may possibly be from different vendors. A non-goal is to enumerate all tiling formats supported by all vendors. Some tiling formats used internally by vendors are inappropriate for sharing; no modifiers should be assigned to such tiling formats.
Modifier values typically do not describe memory layouts. More precisely, a modifier's lower 56 bits usually have no structure. Instead, modifiers name memory layouts; they name a small set of vendor-preferred layouts for image sharing. As a consequence, in each vendor namespace the modifier values are often sequentially allocated starting at 1.
Each modifier is usually supported by a single vendor and its name matches
the pattern {VENDOR}_FORMAT_MOD_* or DRM_FORMAT_MOD_{VENDOR}_*.
Examples are I915_FORMAT_MOD_X_TILED and
DRM_FORMAT_MOD_BROADCOM_VC4_T_TILED.
An exception is DRM_FORMAT_MOD_LINEAR, which is supported by most
vendors.
Many APIs in Linux use modifiers to negotiate and specify the memory
layout of shared images.
For example, a Wayland compositor and Wayland client may, by relaying
modifiers over the Wayland protocol zwp_linux_dmabuf_v1, negotiate a
vendor-specific tiling format for a shared wl_buffer.
The client may allocate the underlying memory for the wl_buffer with
GBM, providing the chosen modifier to gbm_bo_create_with_modifiers.
The client may then import the wl_buffer into Vulkan for producing
image content, providing the resource’s dma_buf to
VkImportMemoryFdInfoKHR and its modifier to
VkImageDrmFormatModifierExplicitCreateInfoEXT.
The compositor may then import the wl_buffer into OpenGL for sampling,
providing the resource’s dma_buf and modifier to eglCreateImage.
The compositor may also bypass OpenGL and submit the wl_buffer directly
to the kernel’s display API, providing the dma_buf and modifier through
drm_mode_fb_cmd2.
Format Translation
Modifier-capable APIs often pair modifiers with DRM formats, which are
defined in
drm_fourcc.h.
However, VK_EXT_image_drm_format_modifier uses VkFormat instead of
DRM formats.
The application must convert between VkFormat and DRM format when it
sends or receives a DRM format to or from an external API.
The mapping from VkFormat to DRM format is lossy. Therefore, when receiving a DRM format from an external API, often the application must use information from the external API to accurately map the DRM format to a VkFormat. For example, DRM formats do not distinguish between RGB and sRGB (as of 2018-03-28); external information is required to identify the image’s colorspace.
The mapping between VkFormat and DRM format is also incomplete. For some DRM formats there exist no corresponding Vulkan format, and for some Vulkan formats there exist no corresponding DRM format.
Usage Patterns
Three primary usage patterns are intended for this extension:
-
Negotiation. The application negotiates with modifier-aware, external components to determine sets of image creation parameters supported among all components.
In the Linux ecosystem, the negotiation usually assumes the image is a 2D, single-sampled, non-mipmapped, non-array image; this extension permits that assumption but does not require it. The result of the negotiation usually resembles a set of tuples such as (drmFormat, drmFormatModifier), where each participating component supports all tuples in the set.
Many details of this negotiation—such as the protocol used during negotiation, the set of image creation parameters expressable in the protocol, and how the protocol chooses which process and which API will create the image—are outside the scope of this specification.
In this extension, vkGetPhysicalDeviceFormatProperties2 with VkDrmFormatModifierPropertiesListEXT serves a primary role during the negotiation, and vkGetPhysicalDeviceImageFormatProperties2 with VkPhysicalDeviceImageDrmFormatModifierInfoEXT serves a secondary role.
-
Import. The application imports an image with a modifier.
In this pattern, the application receives from an external source the image’s memory and its creation parameters, which are often the result of the negotiation described above. Some image creation parameters are implicitly defined by the external source; for example,
VK_IMAGE_TYPE_2Dis often assumed. Some image creation parameters are usually explicit, such as the image’sformat,drmFormatModifier, andextent; and each plane’soffsetandrowPitch.Before creating the image, the application first verifies that the physical device supports the received creation parameters by querying vkGetPhysicalDeviceFormatProperties2 with VkDrmFormatModifierPropertiesListEXT and vkGetPhysicalDeviceImageFormatProperties2 with VkPhysicalDeviceImageDrmFormatModifierInfoEXT. Then the application creates the image by chaining VkImageDrmFormatModifierExplicitCreateInfoEXT and VkExternalMemoryImageCreateInfo onto VkImageCreateInfo.
-
Export. The application creates an image and allocates its memory. Then the application exports to modifier-aware consumers the image’s memory handles; its creation parameters; its modifier; and the
offset,size, androwPitchof each memory plane.In this pattern, the Vulkan device is the authority for the image; it is the allocator of the image’s memory and the decider of the image’s creation parameters. When choosing the image’s creation parameters, the application usually chooses a tuple (format, drmFormatModifier) from the result of the negotiation described above. The negotiation’s result often contains multiple tuples that share the same format but differ in their modifier. In this case, the application should defer the choice of the image’s modifier to the Vulkan implementation by providing all such modifiers to VkImageDrmFormatModifierListCreateInfoEXT::
pDrmFormatModifiers; and the implementation should choose frompDrmFormatModifiersthe optimal modifier in consideration with the other image parameters.The application creates the image by chaining VkImageDrmFormatModifierListCreateInfoEXT and VkExternalMemoryImageCreateInfo onto VkImageCreateInfo. The protocol and APIs by which the application will share the image with external consumers will likely determine the value of VkExternalMemoryImageCreateInfo::
handleTypes. The implementation chooses for the image an optimal modifier from VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers. The application then queries the implementation-chosen modifier with vkGetImageDrmFormatModifierPropertiesEXT, and queries the memory layout of each plane with vkGetImageSubresourceLayout.The application then allocates the image’s memory with VkMemoryAllocateInfo, adding chained extending structures for external memory; binds it to the image; and exports the memory, for example, with vkGetMemoryFdKHR.
Finally, the application sends the image’s creation parameters, its modifier, its per-plane memory layout, and the exported memory handle to the external consumers. The details of how the application transmits this information to external consumers is outside the scope of this specification.
Prior Art
Extension
EGL_EXT_image_dma_buf_import1
introduced the ability to create an EGLImage by importing for each
plane a dma_buf, offset, and row pitch.
Later, extension
EGL_EXT_image_dma_buf_import_modifiers2
introduced the ability to query which combination of formats and modifiers
the implementation supports and to specify modifiers during creation of
the EGLImage.
Extension
EGL_MESA_image_dma_buf_export3
is the inverse of EGL_EXT_image_dma_buf_import_modifiers.
The Linux kernel modesetting API (KMS), when configuring the display’s
framebuffer with struct
drm_mode_fb_cmd24, allows one to
specify the frambuffer’s modifier as well as a per-plane memory handle,
offset, and row pitch.
GBM, a graphics buffer manager for Linux, allows creation of a gbm_bo
(that is, a graphics buffer object) by importing data similar to that in
EGL_EXT_image_dma_buf_import_modifiers1;
and symmetrically allows exporting the same data from the gbm_bo.
See the references to modifier and plane in
gbm.h5.
New Structures
-
Extending VkFormatProperties2:
-
Extending VkImageCreateInfo:
-
Extending VkPhysicalDeviceImageFormatInfo2:
If VK_KHR_format_feature_flags2 is supported:
New Enum Constants
-
VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_EXTENSION_NAME -
VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_SPEC_VERSION -
Extending VkImageAspectFlagBits:
-
VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT -
VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT -
VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT -
VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT
-
-
Extending VkImageTiling:
-
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
-
-
Extending VkResult:
-
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT -
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
-
If VK_KHR_format_feature_flags2 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_2_EXT
-
Issues
1) Should this extension define a single DRM format modifier per
VkImage? Or define one per plane?
+
RESOLVED: There exists a single DRM format modifier per VkImage.
DISCUSSION: Prior art, such as
EGL_EXT_image_dma_buf_import_modifiers2,
struct drm_mode_fb_cmd24, and
struct
gbm_import_fd_modifier_data5,
allows defining one modifier per plane.
However, developers of the GBM and kernel APIs concede it was a mistake.
Beginning in Linux 4.10, the kernel requires that the application provide
the same DRM format modifier for each plane.
(See Linux commit
bae781b259269590109e8a4a8227331362b88212).
And GBM provides an entry point, gbm_bo_get_modifier, for querying the
modifier of the image but does not provide one to query the modifier of
individual planes.
2) When creating an image with VkImageDrmFormatModifierExplicitCreateInfoEXT, which is typically used when importing an image, should the application explicitly provide the size of each plane?
+
RESOLVED: No.
The application must not provide the size.
To enforce this, the API requires that
VkImageDrmFormatModifierExplicitCreateInfoEXT::pPlaneLayouts->size
must be 0.
DISCUSSION: Prior art, such as
EGL_EXT_image_dma_buf_import_modifiers2,
struct drm_mode_fb_cmd24, and
struct
gbm_import_fd_modifier_data5,
omits from the API the size of each plane.
Instead, the APIs infer each plane’s size from the import parameters, which
include the image’s pixel format and a dma_buf, offset, and row pitch for
each plane.
However, Vulkan differs from EGL and GBM with regards to image creation in the following ways:
-
Undedicated allocation by default. When importing or exporting a set of dma_bufs as an
EGLImageorgbm_bo, common practice mandates that each dma_buf’s memory be dedicated (in the sense ofVK_KHR_dedicated_allocation) to the image (though not necessarily dedicated to a single plane). In particular, neither the GBM documentation nor the EGL extension specifications explicitly state this requirement, but in light of common practice this is likely due to under-specification rather than intentional omission. In contrast,VK_EXT_image_drm_format_modifierpermits, but does not require, the implementation to require dedicated allocations for images created withVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. -
Separation of image creation and memory allocation. When importing a set of dma_bufs as an
EGLImageorgbm_bo, EGL and GBM create the image resource and bind it to memory (the dma_bufs) simultaneously. This allows EGL and GBM to query each dma_buf’s size during image creation. In Vulkan, image creation and memory allocation are independent unless a dedicated allocation is used (as inVK_KHR_dedicated_allocation). Therefore, without requiring dedicated allocation, Vulkan cannot query the size of each dma_buf (or other external handle) when calculating the image’s memory layout. Even if dedication allocation were required, Vulkan cannot calculate the image’s memory layout until after the image is bound to its dma_ufs.
The above differences complicate the potential inference of plane size in Vulkan. Consider the following problematic cases:
-
Padding. Some plane of the image may require implementation-dependent padding.
-
Metadata. For some modifiers, the image may have a metadata plane which requires a non-trivial calculation to determine its size.
-
Mipmapped, array, and 3D images. The implementation may support
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXTfor images whosemipLevels,arrayLayers, ordepthis greater than 1. For such images with certain modifiers, the calculation of each plane’s size may be non-trivial.
However, an application-provided plane size solves none of the above problems.
For simplicity, consider an external image with a single memory plane.
The implementation is obviously capable calculating the image’s size when
its tiling is VK_IMAGE_TILING_OPTIMAL.
Likewise, any reasonable implementation is capable of calculating the
image’s size when its tiling uses a supported modifier.
Suppose that the external image’s size is smaller than the
implementation-calculated size.
If the application provided the external image’s size to
vkCreateImage, the implementation would observe the mismatched size
and recognize its inability to comprehend the external image’s layout
(unless the implementation used the application-provided size to select a
refinement of the tiling layout indicated by the modifier, which is
strongly discouraged).
The implementation would observe the conflict, and reject image creation
with VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT.
On the other hand, if the application did not provide the external image’s
size to vkCreateImage, then the application would observe after
calling vkGetImageMemoryRequirements that the external image’s size is
less than the size required by the implementation.
The application would observe the conflict and refuse to bind the
VkImage to the external memory.
In both cases, the result is explicit failure.
Suppose that the external image’s size is larger than the
implementation-calculated size.
If the application provided the external image’s size to
vkCreateImage, for reasons similar to above the implementation would
observe the mismatched size and recognize its inability to comprehend the
image data residing in the extra size.
The implementation, however, must assume that image data resides in the
entire size provided by the application.
The implementation would observe the conflict and reject image creation with
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT.
On the other hand, if the application did not provide the external image’s
size to vkCreateImage, then the application would observe after
calling vkGetImageMemoryRequirements that the external image’s size is
larger than the implementation-usable size.
The application would observe the conflict and refuse to bind the
VkImage to the external memory.
In both cases, the result is explicit failure.
Therefore, an application-provided size provides no benefit, and this
extension should not require it.
This decision renders VkSubresourceLayout::size an unused field
during image creation, and thus introduces a risk that implementations may
require applications to submit sideband creation parameters in the unused
field.
To prevent implementations from relying on sideband data, this extension
requires the application to set size to 0.
Version History
-
Revision 1, 2018-08-29 (Chad Versace)
-
First stable revision
-
-
Revision 2, 2021-09-30 (Jon Leech)
-
Add interaction with
VK_KHR_format_feature_flags2tovk.xml
-
VK_EXT_image_view_min_lod
- Name String
-
VK_EXT_image_view_min_lod - Extension Type
-
Device extension
- Registered Extension Number
-
392
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Joshua Ashton Joshua-Ashton
-
Other Extension Metadata
- Last Modified Date
-
2021-11-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Ashton, Valve
-
Hans-Kristian Arntzen, Valve
-
Samuel Iglesias Gonsalvez, Igalia
-
Tobias Hector, AMD
-
Jason Ekstrand, Intel
-
Tom Olson, ARM
-
Description
This extension allows applications to clamp the minimum LOD value during
Image Level(s) Selection and
Integer Texel Coordinate
Operations with a given VkImageView by
VkImageViewMinLodCreateInfoEXT::minLod.
This extension may be useful to restrict a VkImageView to only mips
which have been uploaded, and the use of fractional minLod can be
useful for smoothly introducing new mip levels when using linear mipmap
filtering.
New Enum Constants
-
VK_EXT_IMAGE_VIEW_MIN_LOD_EXTENSION_NAME -
VK_EXT_IMAGE_VIEW_MIN_LOD_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_VIEW_MIN_LOD_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_VIEW_MIN_LOD_FEATURES_EXT
-
VK_EXT_index_type_uint8
- Name String
-
VK_EXT_index_type_uint8 - Extension Type
-
Device extension
- Registered Extension Number
-
266
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-05-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension allows uint8_t indices to be used with
vkCmdBindIndexBuffer.
New Enum Constants
-
VK_EXT_INDEX_TYPE_UINT8_EXTENSION_NAME -
VK_EXT_INDEX_TYPE_UINT8_SPEC_VERSION -
Extending VkIndexType:
-
VK_INDEX_TYPE_UINT8_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_EXT
-
VK_EXT_line_rasterization
- Name String
-
VK_EXT_line_rasterization - Extension Type
-
Device extension
- Registered Extension Number
-
260
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Special Use
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-05-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Allen Jensen, NVIDIA
-
Jason Ekstrand, Intel
-
Description
This extension adds some line rasterization features that are commonly used in CAD applications and supported in other APIs like OpenGL. Bresenham-style line rasterization is supported, smooth rectangular lines (coverage to alpha) are supported, and stippled lines are supported for all three line rasterization modes.
New Enum Constants
-
VK_EXT_LINE_RASTERIZATION_EXTENSION_NAME -
VK_EXT_LINE_RASTERIZATION_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_LINE_STIPPLE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_EXT
-
Issues
(1) Do we need to support Bresenham-style and smooth lines with more than one rasterization sample? i.e. the equivalent of glDisable(GL_MULTISAMPLE) in OpenGL when the framebuffer has more than one sample?
RESOLVED: Yes. For simplicity, Bresenham line rasterization carries forward a few restrictions from OpenGL, such as not supporting per-sample shading, alpha to coverage, or alpha to one.
VK_EXT_load_store_op_none
- Name String
-
VK_EXT_load_store_op_none - Extension Type
-
Device extension
- Registered Extension Number
-
401
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Shahbaz Youssefi syoussefi
-
Other Extension Metadata
- Last Modified Date
-
2021-06-06
- Contributors
-
-
Shahbaz Youssefi, Google
-
Bill Licea-Kane, Qualcomm Technologies, Inc.
-
Tobias Hector, AMD
-
Description
This extension incorporates VK_ATTACHMENT_STORE_OP_NONE_EXT from
VK_QCOM_render_pass_store_ops, enabling applications to avoid
unnecessary synchronization when an attachment is not written during a
render pass.
Additionally, VK_ATTACHMENT_LOAD_OP_NONE_EXT is introduced to avoid
unnecessary synchronization when an attachment is not used during a render
pass at all.
In combination with VK_ATTACHMENT_STORE_OP_NONE_EXT, this is useful as
an alternative to preserve attachments in applications that cannot decide if
an attachment will be used in a render pass until after the necessary
pipelines have been created.
New Enum Constants
-
VK_EXT_LOAD_STORE_OP_NONE_EXTENSION_NAME -
VK_EXT_LOAD_STORE_OP_NONE_SPEC_VERSION -
Extending VkAttachmentLoadOp:
-
VK_ATTACHMENT_LOAD_OP_NONE_EXT
-
-
Extending VkAttachmentStoreOp:
-
VK_ATTACHMENT_STORE_OP_NONE_EXT
-
Version History
-
Revision 1, 2021-06-06 (Shahbaz Youssefi)
-
Initial revision, based on VK_QCOM_render_pass_store_ops.
-
Added VK_ATTACHMENT_LOAD_OP_NONE_EXT.
-
VK_EXT_memory_budget
- Name String
-
VK_EXT_memory_budget - Extension Type
-
Device extension
- Registered Extension Number
-
238
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2018-10-08
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jeff Juliano, NVIDIA
-
Description
While running a Vulkan application, other processes on the machine might also be attempting to use the same device memory, which can pose problems. This extension adds support for querying the amount of memory used and the total memory budget for a memory heap. The values returned by this query are implementation-dependent and can depend on a variety of factors including operating system and system load.
The VkPhysicalDeviceMemoryBudgetPropertiesEXT::heapBudget values
can be used as a guideline for how much total memory from each heap the
current process can use at any given time, before allocations may start
failing or causing performance degradation.
The values may change based on other activity in the system that is outside
the scope and control of the Vulkan implementation.
The VkPhysicalDeviceMemoryBudgetPropertiesEXT::heapUsage will
display the current process estimated heap usage.
With this information, the idea is for an application at some interval (once
per frame, per few seconds, etc) to query heapBudget and
heapUsage.
From here the application can notice if it is over budget and decide how it
wants to handle the memory situation (free it, move to host memory, changing
mipmap levels, etc).
This extension is designed to be used in concert with
VK_EXT_memory_priority to help with this part of memory management.
New Enum Constants
-
VK_EXT_MEMORY_BUDGET_EXTENSION_NAME -
VK_EXT_MEMORY_BUDGET_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_BUDGET_PROPERTIES_EXT
-
VK_EXT_memory_priority
- Name String
-
VK_EXT_memory_priority - Extension Type
-
Device extension
- Registered Extension Number
-
239
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2018-10-08
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jeff Juliano, NVIDIA
-
Description
This extension adds a priority value specified at memory allocation
time.
On some systems with both device-local and non-device-local memory heaps,
the implementation may transparently move memory from one heap to another
when a heap becomes full (for example, when the total memory used across all
processes exceeds the size of the heap).
In such a case, this priority value may be used to determine which
allocations are more likely to remain in device-local memory.
New Enum Constants
-
VK_EXT_MEMORY_PRIORITY_EXTENSION_NAME -
VK_EXT_MEMORY_PRIORITY_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MEMORY_PRIORITY_ALLOCATE_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PRIORITY_FEATURES_EXT
-
VK_EXT_metal_objects
- Name String
-
VK_EXT_metal_objects - Extension Type
-
Device extension
- Registered Extension Number
-
312
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Bill Hollings billhollings
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-05-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Bill Hollings, The Brenwill Workshop Ltd.
-
Dzmitry Malyshau, Mozilla Corp.
-
Description
In a Vulkan implementation that is layered on top of Metal on Apple device platforms, this extension provides the ability to import and export the underlying Metal objects associated with specific Vulkan objects.
As detailed in the extension proposal document, this extension adds one new Vulkan command, vkExportMetalObjectsEXT, to export underlying Metal objects from Vulkan objects, and supports importing the appropriate existing Metal objects when creating Vulkan objects of types VkDeviceMemory, VkImage, VkSemaphore, and VkEvent,
The intent is that this extension will be advertised and supported only on implementations that are layered on top of Metal on Apple device platforms.
New Base Types
-
IOSurfaceRef -
MTLBuffer_id -
MTLCommandQueue_id -
MTLDevice_id -
MTLSharedEvent_id -
MTLTexture_id
New Structures
-
Extending VkExportMetalObjectsInfoEXT:
-
Extending VkImageCreateInfo:
-
Extending VkInstanceCreateInfo, VkMemoryAllocateInfo, VkImageCreateInfo, VkImageViewCreateInfo, VkBufferViewCreateInfo, VkSemaphoreCreateInfo, VkEventCreateInfo:
-
Extending VkMemoryAllocateInfo:
-
Extending VkSemaphoreCreateInfo, VkEventCreateInfo:
New Enum Constants
-
VK_EXT_METAL_OBJECTS_EXTENSION_NAME -
VK_EXT_METAL_OBJECTS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_METAL_BUFFER_INFO_EXT -
VK_STRUCTURE_TYPE_EXPORT_METAL_COMMAND_QUEUE_INFO_EXT -
VK_STRUCTURE_TYPE_EXPORT_METAL_DEVICE_INFO_EXT -
VK_STRUCTURE_TYPE_EXPORT_METAL_IO_SURFACE_INFO_EXT -
VK_STRUCTURE_TYPE_EXPORT_METAL_OBJECTS_INFO_EXT -
VK_STRUCTURE_TYPE_EXPORT_METAL_OBJECT_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_EXPORT_METAL_SHARED_EVENT_INFO_EXT -
VK_STRUCTURE_TYPE_EXPORT_METAL_TEXTURE_INFO_EXT -
VK_STRUCTURE_TYPE_IMPORT_METAL_BUFFER_INFO_EXT -
VK_STRUCTURE_TYPE_IMPORT_METAL_IO_SURFACE_INFO_EXT -
VK_STRUCTURE_TYPE_IMPORT_METAL_SHARED_EVENT_INFO_EXT -
VK_STRUCTURE_TYPE_IMPORT_METAL_TEXTURE_INFO_EXT
-
Version History
-
Revision 1, 2022-05-28 (Bill Hollings)
-
Initial draft.
-
Incorported feedback from review by the Vulkan Working Group. Renamed many structures, moved import/export of MTLBuffer to VkDeviceMemory, added export of MTLSharedEvent, added import of MTLSharedEvent for VkSemaphore and VkEvent, and changed used bit mask fields to individual bit fields to simplify Valid Usage rules.
-
VK_EXT_metal_surface
- Name String
-
VK_EXT_metal_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
218
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Dzmitry Malyshau kvark
-
Other Extension Metadata
- Last Modified Date
-
2018-10-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Dzmitry Malyshau, Mozilla Corp.
-
Description
The VK_EXT_metal_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) from CAMetalLayer, which is
the native rendering surface of Apple’s Metal framework.
New Enum Constants
-
VK_EXT_METAL_SURFACE_EXTENSION_NAME -
VK_EXT_METAL_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_METAL_SURFACE_CREATE_INFO_EXT
-
VK_EXT_multi_draw
- Name String
-
VK_EXT_multi_draw - Extension Type
-
Device extension
- Registered Extension Number
-
393
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Mike Blumenkrantz zmike
-
Other Extension Metadata
- Last Modified Date
-
2021-05-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Mike Blumenkrantz, VALVE
-
Piers Daniell, NVIDIA
-
Jason Ekstrand, INTEL
-
Spencer Fricke, SAMSUNG
-
Ricardo Garcia, IGALIA
-
Jon Leech, KHRONOS
-
Stu Smith, AMD
-
Description
Processing multiple draw commands in sequence incurs measurable overhead
within drivers due to repeated state checks and updates during dispatch.
This extension enables passing the entire sequence of draws directly to the
driver in order to avoid any such overhead, using an array of
VkMultiDrawInfoEXT or VkMultiDrawIndexedInfoEXT structs with
vkCmdDrawMultiEXT or vkCmdDrawMultiIndexedEXT, respectively.
These functions could be used any time multiple draw commands are being
recorded without any state changes between them in order to maximize
performance.
New Enum Constants
-
VK_EXT_MULTI_DRAW_EXTENSION_NAME -
VK_EXT_MULTI_DRAW_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTI_DRAW_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTI_DRAW_PROPERTIES_EXT
-
VK_EXT_multisampled_render_to_single_sampled
- Name String
-
VK_EXT_multisampled_render_to_single_sampled - Extension Type
-
Device extension
- Registered Extension Number
-
377
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_create_renderpass2to be enabled for any device-level functionality -
Requires
VK_KHR_depth_stencil_resolveto be enabled for any device-level functionality
-
- Contact
-
-
Shahbaz Youssefi syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-04-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Shahbaz Youssefi, Google
-
Jan-Harald Fredriksen, Arm
-
Jörg Wagner, Arm
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Jarred Davies, Imagination Technologies
-
Description
With careful usage of resolve attachments, multisampled image memory
allocated with VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT, loadOp
not equal to VK_ATTACHMENT_LOAD_OP_LOAD and storeOp not equal to
VK_ATTACHMENT_STORE_OP_STORE, a Vulkan application is able to
efficiently perform multisampled rendering without incurring any additional
memory penalty on some implementations.
Under certain circumstances however, the application may not be able to
complete its multisampled rendering within a single render pass; for example
if it does partial rasterization from frame to frame, blending on an image
from a previous frame, or in emulation of
GL_EXT_multisampled_render_to_texture.
In such cases, the application can use an initial subpass to effectively
load single-sampled data from the next subpass’s resolve attachment and fill
in the multisampled attachment which otherwise uses loadOp equal to
VK_ATTACHMENT_LOAD_OP_DONT_CARE.
However, this is not always possible (for example for stencil in the absence
of VK_EXT_shader_stencil_export) and has multiple drawbacks.
Some implementations are able to perform said operation efficiently in hardware, effectively loading a multisampled attachment from the contents of a single sampled one. Together with the ability to perform a resolve operation at the end of a subpass, these implementations are able to perform multisampled rendering on single-sampled attachments with no extra memory or bandwidth overhead. This extension exposes this capability by allowing a framebuffer and render pass to include single-sampled attachments while rendering is done with a specified number of samples.
New Enum Constants
-
VK_EXT_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_EXTENSION_NAME -
VK_EXT_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_SPEC_VERSION -
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_FEATURES_EXT -
VK_STRUCTURE_TYPE_SUBPASS_RESOLVE_PERFORMANCE_QUERY_EXT
-
Issues
1) Could the multisampled attachment be initialized through some form of copy?
RESOLVED: No. Some implementations do not support copying between attachments in general, and find expressing this operation through a copy unnatural.
2) Another way to achieve this is by introducing a new loadOp to load
the contents of the multisampled image from a single-sampled one.
Why is this extension preferred?
RESOLVED: Using this extension simplifies the application, as it does not
need to manage a secondary lazily-allocated image.
Additionally, using this extension leaves less room for error; for example a
single mistake in loadOp or storeOp would result in the
lazily-allocated image to actually take up memory, and remain so until
destruction.
3) There is no guarantee that multisampled data between two subpasses with the same number of samples will be retained as the implementation may be forced to split the render pass implicitly for various reasons. Should this extension require that every subpass that uses multisampled-render-to-single-sampled end in an implicit render pass split (which results in a resolve operation)?
RESOLVED: No. Not requiring this allows render passes with multiple multisampled-render-to-single-sampled subpasses to potentially execute more efficiently (though there is no guarantee).
VK_EXT_non_seamless_cube_map
- Name String
-
VK_EXT_non_seamless_cube_map - Extension Type
-
Device extension
- Registered Extension Number
-
423
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Uses
- Contact
-
-
Georg Lehmann DadSchoorse
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-09-04
- IP Status
-
No known IP claims.
- Contributors
-
-
Georg Lehmann
-
Description
This extension provides functionality to disable cube map edge handling on a per sampler level which matches the behavior of other graphics APIs.
This extension may be useful for building translation layers for those APIs or for porting applications that rely on this cube map behavior.
New Enum Constants
-
VK_EXT_NON_SEAMLESS_CUBE_MAP_EXTENSION_NAME -
VK_EXT_NON_SEAMLESS_CUBE_MAP_SPEC_VERSION -
Extending VkSamplerCreateFlagBits:
-
VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_NON_SEAMLESS_CUBE_MAP_FEATURES_EXT
-
VK_EXT_pageable_device_local_memory
- Name String
-
VK_EXT_pageable_device_local_memory - Extension Type
-
Device extension
- Registered Extension Number
-
413
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_memory_priorityto be enabled for any device-level functionality
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2021-08-24
- Contributors
-
-
Hans-Kristian Arntzen, Valve
-
Axel Gneiting, id Software
-
Billy Khan, id Software
-
Daniel Koch, NVIDIA
-
Chris Lentini, NVIDIA
-
Joshua Schnarr, NVIDIA
-
Stu Smith, AMD
-
Description
Vulkan is frequently implemented on multi-user and multi-process operating systems where the device-local memory can be shared by more than one process. On such systems the size of the device-local memory available to the application may not be the full size of the memory heap at all times. In order for these operating systems to support multiple applications the device-local memory is virtualized and paging is used to move memory between device-local and host-local memory heaps, transparent to the application.
The current Vulkan specification does not expose this behavior well and may cause applications to make suboptimal memory choices when allocating memory. For example, in a system with multiple applications running, the application may think that device-local memory is full and revert to making performance-sensitive allocations from host-local memory. In reality the memory heap might not have been full, it just appeared to be at the time memory consumption was queried, and a device-local allocation would have succeeded. A well designed operating system that implements pageable device-local memory will try to have all memory allocations for the foreground application paged into device-local memory, and paged out for other applications as needed when not in use.
When this extension is exposed by the Vulkan implementation it indicates to the application that the operating system implements pageable device-local memory and the application should adjust its memory allocation strategy accordingly. The extension also exposes a new vkSetDeviceMemoryPriorityEXT function to allow the application to dynamically adjust the priority of existing memory allocations based on its current needs. This will help the operating system page out lower priority memory allocations before higher priority allocations when needed. It will also help the operating system decide which memory allocations to page back into device-local memory first.
To take best advantage of pageable device-local memory the application must
create the Vulkan device with the
VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT::pageableDeviceLocalMemory
feature enabled.
When enabled the Vulkan implementation will allow device-local memory
allocations to be paged in and out by the operating system, and may not
return VK_ERROR_OUT_OF_DEVICE_MEMORY even if device-local memory appears to
be full, but will instead page this, or other allocations, out to make room.
The Vulkan implementation will also ensure that host-local memory
allocations will never be promoted to device-local memory by the operating
system, or consume device-local memory.
New Enum Constants
-
VK_EXT_PAGEABLE_DEVICE_LOCAL_MEMORY_EXTENSION_NAME -
VK_EXT_PAGEABLE_DEVICE_LOCAL_MEMORY_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PAGEABLE_DEVICE_LOCAL_MEMORY_FEATURES_EXT
-
VK_EXT_pci_bus_info
- Name String
-
VK_EXT_pci_bus_info - Extension Type
-
Device extension
- Registered Extension Number
-
213
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2018-12-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Daniel Rakos, AMD
-
Description
This extension adds a new query to obtain PCI bus information about a physical device.
Not all physical devices have PCI bus information, either due to the device not being connected to the system through a PCI interface or due to platform specific restrictions and policies. Thus this extension is only expected to be supported by physical devices which can provide the information.
As a consequence, applications should always check for the presence of the extension string for each individual physical device for which they intend to issue the new query for and should not have any assumptions about the availability of the extension on any given platform.
New Enum Constants
-
VK_EXT_PCI_BUS_INFO_EXTENSION_NAME -
VK_EXT_PCI_BUS_INFO_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PCI_BUS_INFO_PROPERTIES_EXT
-
Version History
-
Revision 2, 2018-12-10 (Daniel Rakos)
-
Changed all members of the new structure to have the uint32_t type
-
-
Revision 1, 2018-10-11 (Daniel Rakos)
-
Initial revision
-
VK_EXT_physical_device_drm
- Name String
-
VK_EXT_physical_device_drm - Extension Type
-
Device extension
- Registered Extension Number
-
354
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Simon Ser emersion
-
Other Extension Metadata
- Last Modified Date
-
2021-06-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Simon Ser
-
Description
This extension provides new facilities to query DRM properties for physical devices, enabling users to match Vulkan physical devices with DRM nodes on Linux.
Its functionality closely overlaps with
EGL_EXT_device_drm1.
Unlike the EGL extension, this extension does not expose a string containing
the name of the device file and instead exposes device minor numbers.
DRM defines multiple device node types. Each physical device may have one primary node and one render node associated. Physical devices may have no primary node (e.g. if the device does not have a display subsystem), may have no render node (e.g. if it is a software rendering engine), or may have neither (e.g. if it is a software rendering engine without a display subsystem).
To query DRM properties for a physical device, chain VkPhysicalDeviceDrmPropertiesEXT to VkPhysicalDeviceProperties2.
New Enum Constants
-
VK_EXT_PHYSICAL_DEVICE_DRM_EXTENSION_NAME -
VK_EXT_PHYSICAL_DEVICE_DRM_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRM_PROPERTIES_EXT
-
VK_EXT_pipeline_properties
- Name String
-
VK_EXT_pipeline_properties - Extension Type
-
Device extension
- Registered Extension Number
-
373
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Mukund Keshava mkeshavanv
-
Other Extension Metadata
- Last Modified Date
-
2022-04-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Mukund Keshava, NVIDIA
-
Daniel Koch, NVIDIA
-
Mark Bellamy, Arm
-
Description
Vulkan SC requires offline compilation of pipelines. In order to support this, the pipeline state is represented in a JSON schema that is read by an offline tool for compilation.
One method of developing a Vulkan SC application is to author a Vulkan
application and use a layer to record and serialize the pipeline state and
shaders for offline compilation.
Each pipeline is represented by a separate JSON file, and can be identified
with a pipelineIdentifier.
Once the pipelines have been compiled by the offline pipeline cache
compiler, the Vulkan SC application can then use this
pipelineIdentifier for identifying the pipeline via Vulkan SC’s
VkPipelineIdentifierInfo structure.
This extension allows the Vulkan application to query the
pipelineIdentifier associated with each pipeline so that the
application can store this with its pipeline metadata and the Vulkan SC
application will then use to map the same state to an entry in the Vulkan SC
pipeline cache.
It is expected that this extension will initially be implemented in the json generation layer, although we can envision that there might be future uses for it in native Vulkan drivers as well.
New Enum Constants
-
VK_EXT_PIPELINE_PROPERTIES_EXTENSION_NAME -
VK_EXT_PIPELINE_PROPERTIES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_PROPERTIES_FEATURES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_INFO_EXT -
VK_STRUCTURE_TYPE_PIPELINE_PROPERTIES_IDENTIFIER_EXT
-
Issues
(1) This extension does not make sense on a strict Vulkan SC implementation. It may however be of potential use in a non-strict Vulkan SC implementation. Should this extension be enabled as part of Vulkan SC as well?
RESOLVED: No. This extension will not be enabled for Vulkan SC.
(2) This is intended to be a general pipeline properties query, but is currently only retrieving the pipeline identifier. Should the pipeline identifier query be mandatory for this extension and for all queries using this entry point?
RESOLVED: Use VkBaseOutStructure for the return parameter. Currently this is required to actually be a VkPipelinePropertiesIdentifierEXT structure, but that could be relaxed in the future to allow other structure types or to allow other structures to be chained in along with this one.
(3) Should there be a feature structure? Should it be required?
RESOLVED: Add a feature structure, and a feature for querying pipeline identifier, but allow it to be optional so that this extension can be used as the basis for other pipeline property queries without requiring the pipeline identfier to be supported.
VK_EXT_pipeline_robustness
- Name String
-
VK_EXT_pipeline_robustness - Extension Type
-
Device extension
- Registered Extension Number
-
69
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Jarred Davies
-
Other Extension Metadata
- Last Modified Date
-
2022-07-12
- Interactions and External Dependencies
-
-
Interacts with
VK_EXT_robustness2 -
Interacts with
VK_EXT_image_robustness -
Interacts with
VK_KHR_ray_tracing_pipeline
-
- Contributors
-
-
Jarred Davies, Imagination Technologies
-
Alex Walters, Imagination Technologies
-
Piers Daniell, NVIDIA
-
Graeme Leese, Broadcom Corporation
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Jason Ekstrand, Intel
-
Lionel Landwerlin, Intel
-
Shahbaz Youssefi, Google, Inc.
-
Description
VK_EXT_pipeline_robustness allows users to request robustness on a
per-pipeline stage basis.
As robustBufferAccess and other
robustness features may have an adverse effect on performance, this
extension is designed to allow users to request robust behavior only where
it may be needed.
New Enum Constants
-
VK_EXT_PIPELINE_ROBUSTNESS_EXTENSION_NAME -
VK_EXT_PIPELINE_ROBUSTNESS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_ROBUSTNESS_CREATE_INFO_EXT
-
VK_EXT_post_depth_coverage
- Name String
-
VK_EXT_post_depth_coverage - Extension Type
-
Device extension
- Registered Extension Number
-
156
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-07-17
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_post_depth_coverage -
This extension provides API support for
GL_ARB_post_depth_coverageandGL_EXT_post_depth_coverage
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_post_depth_coverage
which allows the fragment shader to control whether values in the
SampleMask built-in input variable reflect the coverage after early
depth and stencil tests are applied.
This extension adds a new PostDepthCoverage execution mode under the
SampleMaskPostDepthCoverage capability.
When this mode is specified along with EarlyFragmentTests, the value of
an input variable decorated with the
SampleMask built-in
reflects the coverage after the early fragment tests are applied.
Otherwise, it reflects the coverage before the depth and stencil tests.
When using GLSL source-based shading languages, the post_depth_coverage
layout qualifier from GL_ARB_post_depth_coverage or
GL_EXT_post_depth_coverage maps to the PostDepthCoverage execution
mode.
New Enum Constants
-
VK_EXT_POST_DEPTH_COVERAGE_EXTENSION_NAME -
VK_EXT_POST_DEPTH_COVERAGE_SPEC_VERSION
VK_EXT_primitive_topology_list_restart
- Name String
-
VK_EXT_primitive_topology_list_restart - Extension Type
-
Device extension
- Registered Extension Number
-
357
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Use
- Contact
-
-
Shahbaz Youssefi syoussefi
-
Other Extension Metadata
- Last Modified Date
-
2021-01-11
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, Google
-
Shahbaz Youssefi, Google
-
Description
This extension allows list primitives to use the primitive restart index value. This provides a more efficient implementation when layering OpenGL functionality on Vulkan by avoiding emulation which incurs data copies.
New Enum Constants
-
VK_EXT_PRIMITIVE_TOPOLOGY_LIST_RESTART_EXTENSION_NAME -
VK_EXT_PRIMITIVE_TOPOLOGY_LIST_RESTART_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIMITIVE_TOPOLOGY_LIST_RESTART_FEATURES_EXT
-
Version History
-
Revision 0, 2020-09-14 (Courtney Goeltzenleuchter)
-
Internal revisions
-
-
Revision 1, 2021-01-11 (Shahbaz Youssefi)
-
Add the
primitiveTopologyPatchListRestartfeature -
Internal revisions
-
VK_EXT_primitives_generated_query
- Name String
-
VK_EXT_primitives_generated_query - Extension Type
-
Device extension
- Registered Extension Number
-
383
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_transform_feedbackto be enabled for any device-level functionality
-
- Special Use
- Contact
-
-
Shahbaz Youssefi syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-01-24
- Contributors
-
-
Shahbaz Youssefi, Google
-
Piers Daniell, NVIDIA
-
Jason Ekstrand, Collabora
-
Jan-Harald Fredriksen, Arm
-
Description
This extension adds support for a new query type to match OpenGL’s
GL_PRIMITIVES_GENERATED to support layering.
New Enum Constants
-
VK_EXT_PRIMITIVES_GENERATED_QUERY_EXTENSION_NAME -
VK_EXT_PRIMITIVES_GENERATED_QUERY_SPEC_VERSION -
Extending VkQueryType:
-
VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIMITIVES_GENERATED_QUERY_FEATURES_EXT
-
Issues
1) Can the query from VK_EXT_transform_feedback be used instead?
RESOLVED: No.
While the query from VK_EXT_transform_feedback can produce the same results
as in this extension, it is only available while transform feedback is
active.
The OpenGL GL_PRIMITIVES_GENERATED query is independent from transform
feedback.
Emulation through artificial transform feedback is unnecessarily
inefficient.
2) Can VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT be used
instead?
RESOLVED: It could, but we prefer the extension for simplicity.
Vulkan requires that only one query be active at a time.
If both the GL_PRIMITIVES_GENERATED and the
GL_CLIPPING_INPUT_PRIMITIVES_ARB queries need to be simultaneously
enabled, emulation of both through
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT is inconvenient.
3) On some hardware, this query cannot be implemented if
VkPipelineRasterizationStateCreateInfo::rasterizerDiscardEnable
is enabled.
How will this be handled?
RESOLVED: A feature flag is exposed by this extension for this. On said hardware, the GL implementation disables rasterizer-discard and achieves the same effect through other means. It will not be able to do the same in Vulkan due to lack of state information. A feature flag is exposed by this extension so the OpenGL implementation on top of Vulkan would be able to implement a similar workaround.
4) On some hardware, this query cannot be implemented for non-zero query indices. How will this be handled?
RESOLVED: A feature flag is exposed by this extension for this.
If this feature is not present, the query from VK_EXT_transform_feedback
can be used to the same effect.
5) How is the interaction of this extension with
transformFeedbackRasterizationStreamSelect handled?
RESOLVED: Disallowed for non-zero streams. In OpenGL, the rasterization stream is always stream zero.
VK_EXT_provoking_vertex
- Name String
-
VK_EXT_provoking_vertex - Extension Type
-
Device extension
- Registered Extension Number
-
255
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Special Use
- Contact
-
-
Jesse Hall jessehall
-
Other Extension Metadata
- Last Modified Date
-
2021-02-22
- IP Status
-
No known IP claims.
- Contributors
-
-
Alexis Hétu, Google
-
Bill Licea-Kane, Qualcomm
-
Daniel Koch, Nvidia
-
Jamie Madill, Google
-
Jan-Harald Fredriksen, Arm
-
Jason Ekstrand, Intel
-
Jeff Bolz, Nvidia
-
Jeff Leger, Qualcomm
-
Jesse Hall, Google
-
Jörg Wagner, Arm
-
Matthew Netsch, Qualcomm
-
Mike Blumenkrantz, Valve
-
Piers Daniell, Nvidia
-
Tobias Hector, AMD
-
Description
This extension allows changing the provoking vertex convention between Vulkan’s default convention (first vertex) and OpenGL’s convention (last vertex).
This extension is intended for use by API-translation layers that implement APIs like OpenGL on top of Vulkan, and need to match the source API’s provoking vertex convention. Applications using Vulkan directly should use Vulkan’s default convention.
New Enum Constants
-
VK_EXT_PROVOKING_VERTEX_EXTENSION_NAME -
VK_EXT_PROVOKING_VERTEX_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROVOKING_VERTEX_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROVOKING_VERTEX_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_PROVOKING_VERTEX_STATE_CREATE_INFO_EXT
-
Issues
1) At what granularity should this state be set?
RESOLVED: At pipeline bind, with an optional per-render pass restriction.
The most natural place to put this state is in the graphics pipeline object. Some implementations require it to be known when creating the pipeline, and pipeline state is convenient for implementing OpenGL 3.2’s glProvokingVertex, which can change the state between draw calls. However, some implementations can only change it approximately render pass granularity. To accommodate both, provoking vertex will be pipeline state, but implementations can require that only one mode is used within a render pass instance; the render pass’s mode is chosen implicitly when the first pipeline is bound.
2) Does the provoking vertex mode affect the order that vertices are written to transform feedback buffers?
RESOLVED: Yes, to enable layered implementations of OpenGL and D3D.
All of OpenGL, OpenGL ES, and Direct3D 11 require that vertices are written to transform feedback buffers such that flat-shaded attributes have the same value when drawing the contents of the transform feedback buffer as they did in the original drawing when the transform feedback buffer was written (assuming the provoking vertex mode has not changed, in APIs that support more than one mode).
Version History
-
Revision 1, (1c) 2021-02-22 (Jesse Hall)
-
Added VkPhysicalDeviceProvokingVertexPropertiesEXT::transformFeedbackPreservesTriangleFanProvokingVertex to accommodate implementations that cannot change the transform feedback vertex order for triangle fans.
-
-
Revision 1, (1b) 2020-06-14 (Jesse Hall)
-
Added VkPhysicalDeviceProvokingVertexFeaturesEXT::transformFeedbackPreservesProvokingVertex and required that transform feedback write vertices so as to preserve the provoking vertex of each primitive.
-
-
Revision 1, (1a) 2019-10-23 (Jesse Hall)
-
Initial draft, based on a proposal by Alexis Hétu
-
VK_EXT_queue_family_foreign
- Name String
-
VK_EXT_queue_family_foreign - Extension Type
-
Device extension
- Registered Extension Number
-
127
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_memoryto be enabled for any device-level functionality
-
- Contact
-
-
Chad Versace chadversary
-
Other Extension Metadata
- Last Modified Date
-
2017-11-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Chad Versace, Google
-
James Jones, NVIDIA
-
Jason Ekstrand, Intel
-
Jesse Hall, Google
-
Daniel Rakos, AMD
-
Ray Smith, ARM
-
Description
This extension defines a special queue family,
VK_QUEUE_FAMILY_FOREIGN_EXT, which can be used to transfer ownership
of resources backed by external memory to foreign, external queues.
This is similar to VK_QUEUE_FAMILY_EXTERNAL_KHR, defined in
VK_KHR_external_memory.
The key differences between the two are:
-
The queues represented by
VK_QUEUE_FAMILY_EXTERNAL_KHRmust share the same physical device and the same driver version as the current VkInstance.VK_QUEUE_FAMILY_FOREIGN_EXThas no such restrictions. It can represent devices and drivers from other vendors, and can even represent non-Vulkan-capable devices. -
All resources backed by external memory support
VK_QUEUE_FAMILY_EXTERNAL_KHR. Support forVK_QUEUE_FAMILY_FOREIGN_EXTis more restrictive. -
Applications should expect transitions to/from
VK_QUEUE_FAMILY_FOREIGN_EXTto be more expensive than transitions to/fromVK_QUEUE_FAMILY_EXTERNAL_KHR.
New Enum Constants
-
VK_EXT_QUEUE_FAMILY_FOREIGN_EXTENSION_NAME -
VK_EXT_QUEUE_FAMILY_FOREIGN_SPEC_VERSION -
VK_QUEUE_FAMILY_FOREIGN_EXT
VK_EXT_rgba10x6_formats
- Name String
-
VK_EXT_rgba10x6_formats - Extension Type
-
Device extension
- Registered Extension Number
-
345
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_sampler_ycbcr_conversionto be enabled for any device-level functionality
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2021-09-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Graeme Leese, Broadcom
-
Spencer Fricke, Samsung
-
Description
This extension enables the
VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 format to be used without
a sampler Y′CBCR conversion enabled.
New Enum Constants
-
VK_EXT_RGBA10X6_FORMATS_EXTENSION_NAME -
VK_EXT_RGBA10X6_FORMATS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RGBA10X6_FORMATS_FEATURES_EXT
-
Issues
1) Should we reuse the existing format enumeration or introduce a new one?
RESOLVED: We reuse an existing format enumeration,
VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16, that was previously
exclusively used for YCbCr and therefore had a set of limitations related to
that usage.
The alternative was to introduce a new format token with exactly the same
bit representation as the existing token, but without the limitations.
2) Should we only introduce
VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16 or also 1-3 component
variations?
RESOLVED: Only the 4-component format is introduced because the 1- and 2- component variations are already not exclusive to YCbCr, and the 3-component variation is not a good match for hardware capabilities.
VK_EXT_robustness2
- Name String
-
VK_EXT_robustness2 - Extension Type
-
Device extension
- Registered Extension Number
-
287
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Liam Middlebrook liam-middlebrook
-
Other Extension Metadata
- Last Modified Date
-
2020-01-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Liam Middlebrook, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension adds stricter requirements for how out of bounds reads and writes are handled. Most accesses must be tightly bounds-checked, out of bounds writes must be discarded, out of bound reads must return zero. Rather than allowing multiple possible (0,0,0,x) vectors, the out of bounds values are treated as zero, and then missing components are inserted based on the format as described in Conversion to RGBA and vertex input attribute extraction.
These additional requirements may be expensive on some implementations, and should only be enabled when truly necessary.
This extension also adds support for “null descriptors”, where VK_NULL_HANDLE can be used instead of a valid handle. Accesses to null descriptors have well-defined behavior, and do not rely on robustness.
New Enum Constants
-
VK_EXT_ROBUSTNESS_2_EXTENSION_NAME -
VK_EXT_ROBUSTNESS_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_PROPERTIES_EXT
-
Issues
-
Why do VkPhysicalDeviceRobustness2PropertiesEXT::
robustUniformBufferAccessSizeAlignmentand VkPhysicalDeviceRobustness2PropertiesEXT::robustStorageBufferAccessSizeAlignmentexist?
RESOLVED: Some implementations cannot efficiently tightly bounds-check all buffer accesses. Rather, the size of the bound range is padded to some power of two multiple, up to 256 bytes for uniform buffers and up to 4 bytes for storage buffers, and that padded size is bounds-checked. This is sufficient to implement D3D-like behavior, because D3D only allows binding whole uniform buffers or ranges that are a multiple of 256 bytes, and D3D raw and structured buffers only support 32-bit accesses.
VK_EXT_sample_locations
- Name String
-
VK_EXT_sample_locations - Extension Type
-
Device extension
- Registered Extension Number
-
144
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2017-08-02
- Contributors
-
-
Mais Alnasser, AMD
-
Matthaeus G. Chajdas, AMD
-
Maciej Jesionowski, AMD
-
Daniel Rakos, AMD
-
Slawomir Grajewski, Intel
-
Jeff Bolz, NVIDIA
-
Bill Licea-Kane, Qualcomm
-
Description
This extension allows an application to modify the locations of samples within a pixel used in rasterization. Additionally, it allows applications to specify different sample locations for each pixel in a group of adjacent pixels, which can increase antialiasing quality (particularly if a custom resolve shader is used that takes advantage of these different locations).
It is common for implementations to optimize the storage of depth values by storing values that can be used to reconstruct depth at each sample location, rather than storing separate depth values for each sample. For example, the depth values from a single triangle may be represented using plane equations. When the depth value for a sample is needed, it is automatically evaluated at the sample location. Modifying the sample locations causes the reconstruction to no longer evaluate the same depth values as when the samples were originally generated, thus the depth aspect of a depth/stencil attachment must be cleared before rendering to it using different sample locations.
Some implementations may need to evaluate depth image values while performing image layout transitions. To accommodate this, instances of the VkSampleLocationsInfoEXT structure can be specified for each situation where an explicit or automatic layout transition has to take place. VkSampleLocationsInfoEXT can be chained from VkImageMemoryBarrier structures to provide sample locations for layout transitions performed by vkCmdWaitEvents and vkCmdPipelineBarrier calls, and VkRenderPassSampleLocationsBeginInfoEXT can be chained from VkRenderPassBeginInfo to provide sample locations for layout transitions performed implicitly by a render pass instance.
New Enum Constants
-
VK_EXT_SAMPLE_LOCATIONS_EXTENSION_NAME -
VK_EXT_SAMPLE_LOCATIONS_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT -
VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT
-
VK_EXT_shader_atomic_float
- Name String
-
VK_EXT_shader_atomic_float - Extension Type
-
Device extension
- Registered Extension Number
-
261
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Vikram Kushwaha vkushwaha-nv
-
Other Extension Metadata
- Last Modified Date
-
2020-07-15
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_shader_atomic_float_add -
This extension provides API support for
GL_EXT_shader_atomic_float
-
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension allows a shader to contain floating-point atomic operations
on buffer, workgroup, and image memory.
It also advertises the SPIR-V AtomicFloat32AddEXT and
AtomicFloat64AddEXT capabilities that allows atomic addition on
floating-points numbers.
The supported operations include OpAtomicFAddEXT,
OpAtomicExchange, OpAtomicLoad and OpAtomicStore.
New Enum Constants
-
VK_EXT_SHADER_ATOMIC_FLOAT_EXTENSION_NAME -
VK_EXT_SHADER_ATOMIC_FLOAT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_FEATURES_EXT
-
VK_EXT_shader_atomic_float2
- Name String
-
VK_EXT_shader_atomic_float2 - Extension Type
-
Device extension
- Registered Extension Number
-
274
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_shader_atomic_floatto be enabled for any device-level functionality
-
- Contact
-
-
Jason Ekstrand jekstrand
-
Other Extension Metadata
- Last Modified Date
-
2020-08-14
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires the VK_EXT_shader_atomic_float extension.
-
This extension requires
SPV_EXT_shader_atomic_float_min_maxandSPV_EXT_shader_atomic_float16_add -
This extension provides API support for
GLSL_EXT_shader_atomic_float2
-
- Contributors
-
-
Jason Ekstrand, Intel
-
Description
This extension allows a shader to perform 16-bit floating-point atomic
operations on buffer and workgroup memory as well as floating-point atomic
minimum and maximum operations on buffer, workgroup, and image memory.
It advertises the SPIR-V AtomicFloat16AddEXT capability which allows
atomic add operations on 16-bit floating-point numbers and the SPIR-V
AtomicFloat16MinMaxEXT, AtomicFloat32MinMaxEXT and
AtomicFloat64MinMaxEXT capabilities which allow atomic minimum and
maximum operations on floating-point numbers.
The supported operations include OpAtomicFAddEXT, OpAtomicFMinEXT
and OpAtomicFMaxEXT.
New Enum Constants
-
VK_EXT_SHADER_ATOMIC_FLOAT_2_EXTENSION_NAME -
VK_EXT_SHADER_ATOMIC_FLOAT_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_2_FEATURES_EXT
-
Issues
1) Should this extension add support for 16-bit image atomics?
RESOLVED: No.
While Vulkan supports creating storage images with
VK_FORMAT_R16_SFLOAT and doing load and store on them, the data in the
shader has a 32-bit representation.
Vulkan currently has no facility for even basic reading or writing such
images using 16-bit float values in the shader.
Adding such functionality would be required before 16-bit image atomics
would make sense and is outside the scope of this extension.
VK_EXT_shader_image_atomic_int64
- Name String
-
VK_EXT_shader_image_atomic_int64 - Extension Type
-
Device extension
- Registered Extension Number
-
235
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2020-07-14
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_shader_image_int64 -
This extension provides API support for
GLSL_EXT_shader_image_int64
-
- Contributors
-
-
Matthaeus Chajdas, AMD
-
Graham Wihlidal, Epic Games
-
Tobias Hector, AMD
-
Jeff Bolz, Nvidia
-
Jason Ekstrand, Intel
-
Description
This extension extends existing 64-bit integer atomic support to enable these operations on images as well.
When working with large 2- or 3-dimensional data sets (e.g. rasterization or screen-space effects), image accesses are generally more efficient than equivalent buffer accesses. This extension allows applications relying on 64-bit integer atomics in this manner to quickly improve performance with only relatively minor code changes.
64-bit integer atomic support is guaranteed for optimally tiled images with
the VK_FORMAT_R64_UINT and VK_FORMAT_R64_SINT formats.
New Enum Constants
-
VK_EXT_SHADER_IMAGE_ATOMIC_INT64_EXTENSION_NAME -
VK_EXT_SHADER_IMAGE_ATOMIC_INT64_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_IMAGE_ATOMIC_INT64_FEATURES_EXT
-
VK_EXT_shader_module_identifier
- Name String
-
VK_EXT_shader_module_identifier - Extension Type
-
Device extension
- Registered Extension Number
-
463
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_EXT_pipeline_creation_cache_controlto be enabled for any device-level functionality
-
- Contact
-
-
Hans-Kristian Arntzen HansKristian-Work
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-05-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Hans-Kristian Arntzen, Valve
-
Ricardo Garcia, Igalia
-
Piers Daniell, NVIDIA
-
Jan-Harald Fredriksen, Arm
-
Tom Olson, Arm
-
Jason Ekstrand, Collabora
-
Description
Some applications generate SPIR-V code at runtime. When pipeline caches are primed, either explicitly through e.g. VkPipelineCache mechanisms, or implicitly through driver managed caches, having to re-generate SPIR-V modules is redundant. SPIR-V modules could be cached on disk by an application, but the extra disk size requirement might be prohibitive in some use cases.
This extension adds the ability for an application to query a small identifier associated with a VkShaderModule. On subsequent runs of the application, the same identifier can be provided in lieu of a VkShaderModule object. A pipeline creation call with such a module may succeed if a pipeline could be created without invoking compilation, and information inside the SPIR-V module is not required by the implementation.
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT must be used
if only the identifier is provided, and this use case is intended to work
like a non-blocking, speculative compile.
Applications can fallback as necessary.
The main motivation for identifying the module itself and not the entire pipeline is that pipeline identifiers change when a driver is updated, but module identifiers are expected to be stable for any particular driver implementation. This approach is helpful for shader pre-compilation systems which can prime pipeline caches ahead of time. When on-disk pipeline caches are updated, the same shader identifiers could lead to a pipeline cache hit.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineShaderStageCreateInfo:
New Enum Constants
-
VK_EXT_SHADER_MODULE_IDENTIFIER_EXTENSION_NAME -
VK_EXT_SHADER_MODULE_IDENTIFIER_SPEC_VERSION -
VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_MODULE_IDENTIFIER_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_MODULE_IDENTIFIER_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_MODULE_IDENTIFIER_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_SHADER_MODULE_IDENTIFIER_EXT
-
VK_EXT_shader_stencil_export
- Name String
-
VK_EXT_shader_stencil_export - Extension Type
-
Device extension
- Registered Extension Number
-
141
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2017-07-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_shader_stencil_export -
This extension provides API support for
GL_ARB_shader_stencil_export
-
- Contributors
-
-
Dominik Witczak, AMD
-
Daniel Rakos, AMD
-
Rex Xu, AMD
-
Description
This extension adds support for the SPIR-V extension
SPV_EXT_shader_stencil_export, providing a mechanism whereby a shader may
generate the stencil reference value per invocation.
When stencil testing is enabled, this allows the test to be performed
against the value generated in the shader.
New Enum Constants
-
VK_EXT_SHADER_STENCIL_EXPORT_EXTENSION_NAME -
VK_EXT_SHADER_STENCIL_EXPORT_SPEC_VERSION
VK_EXT_subpass_merge_feedback
- Name String
-
VK_EXT_subpass_merge_feedback - Extension Type
-
Device extension
- Registered Extension Number
-
459
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Ting Wei catweiting
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-05-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Jorg Wagner, Arm
-
Ting Wei, Arm
-
Description
This extension adds a mechanism to provide feedback to an application about whether the subpasses specified on render pass creation are merged by the implementation. Additionally, it provides a control to enable or disable subpass merging in the render pass.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkRenderPassCreateInfo2:
-
Extending VkRenderPassCreateInfo2, VkSubpassDescription2:
-
Extending VkSubpassDescription2:
New Enum Constants
-
VK_EXT_SUBPASS_MERGE_FEEDBACK_EXTENSION_NAME -
VK_EXT_SUBPASS_MERGE_FEEDBACK_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBPASS_MERGE_FEEDBACK_FEATURES_EXT -
VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_CONTROL_EXT -
VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_FEEDBACK_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_RENDER_PASS_SUBPASS_FEEDBACK_CREATE_INFO_EXT
-
Version History
-
Revision 1, 2022-03-10
-
Initial draft.
-
-
Revision 2, 2022-05-24
-
Fix structextends and constness issues.
-
VK_EXT_swapchain_colorspace
- Name String
-
VK_EXT_swapchain_colorspace - Extension Type
-
Instance extension
- Registered Extension Number
-
105
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Courtney Goeltzenleuchter courtney-g
-
Other Extension Metadata
- Last Modified Date
-
2019-04-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, Google
-
New Enum Constants
-
VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME -
VK_EXT_SWAPCHAIN_COLOR_SPACE_SPEC_VERSION -
Extending VkColorSpaceKHR:
-
VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT -
VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT -
VK_COLOR_SPACE_BT2020_LINEAR_EXT -
VK_COLOR_SPACE_BT709_LINEAR_EXT -
VK_COLOR_SPACE_BT709_NONLINEAR_EXT -
VK_COLOR_SPACE_DCI_P3_LINEAR_EXT -
VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT -
VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT -
VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT -
VK_COLOR_SPACE_DOLBYVISION_EXT -
VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT -
VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT -
VK_COLOR_SPACE_HDR10_HLG_EXT -
VK_COLOR_SPACE_HDR10_ST2084_EXT -
VK_COLOR_SPACE_PASS_THROUGH_EXT
-
Issues
1) Does the spec need to specify which kinds of image formats support the color spaces?
RESOLVED: Pixel format is independent of color space (though some color spaces really want / need floating point color components to be useful). Therefore, do not plan on documenting what formats support which colorspaces. An application can call vkGetPhysicalDeviceSurfaceFormatsKHR to query what a particular implementation supports.
2) How does application determine if HW supports appropriate transfer function for a colorspace?
RESOLVED: Extension indicates that implementation must not do the OETF encoding if it is not sRGB. That responsibility falls to the application shaders. Any other native OETF / EOTF functions supported by an implementation can be described by separate extension.
Version History
-
Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)
-
Initial version
-
-
Revision 2, 2017-01-19 (Courtney Goeltzenleuchter)
-
Add pass through and multiple options for BT2020.
-
Clean up some issues with equations not displaying properly.
-
-
Revision 3, 2017-06-23 (Courtney Goeltzenleuchter)
-
Add extended sRGB non-linear enum.
-
-
Revision 4, 2019-04-26 (Graeme Leese)
-
Clarify colorspace transfer function usage.
-
Refer to normative definitions in the Data Format Specification.
-
Clarify DCI-P3 and Display P3 usage.
-
VK_EXT_transform_feedback
- Name String
-
VK_EXT_transform_feedback - Extension Type
-
Device extension
- Registered Extension Number
-
29
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Special Uses
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2018-10-09
- Contributors
-
-
Baldur Karlsson, Valve
-
Boris Zanin, Mobica
-
Daniel Rakos, AMD
-
Donald Scorgie, Imagination
-
Henri Verbeet, CodeWeavers
-
Jan-Harald Fredriksen, Arm
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Jesse Barker, Unity
-
Jesse Hall, Google
-
Pierre-Loup Griffais, Valve
-
Philip Rebohle, DXVK
-
Ruihao Zhang, Qualcomm
-
Samuel Pitoiset, Valve
-
Slawomir Grajewski, Intel
-
Stu Smith, Imagination Technologies
-
Description
This extension adds transform feedback to the Vulkan API by exposing the
SPIR-V TransformFeedback and GeometryStreams capabilities to
capture vertex, tessellation or geometry shader outputs to one or more
buffers.
It adds API functionality to bind transform feedback buffers to capture the
primitives emitted by the graphics pipeline from SPIR-V outputs decorated
for transform feedback.
The transform feedback capture can be paused and resumed by way of storing
and retrieving a byte counter.
The captured data can be drawn again where the vertex count is derived from
the byte counter without CPU intervention.
If the implementation is capable, a vertex stream other than zero can be
rasterized.
All these features are designed to match the full capabilities of OpenGL core transform feedback functionality and beyond. Many of the features are optional to allow base OpenGL ES GPUs to also implement this extension.
The primary purpose of the functionality exposed by this extension is to support translation layers from other 3D APIs. This functionality is not considered forward looking, and is not expected to be promoted to a KHR extension or to core Vulkan. Unless this is needed for translation, it is recommended that developers use alternative techniques of using the GPU to process and capture vertex data.
New Enum Constants
-
VK_EXT_TRANSFORM_FEEDBACK_EXTENSION_NAME -
VK_EXT_TRANSFORM_FEEDBACK_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT -
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT -
VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT -
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_STREAM_CREATE_INFO_EXT
-
Issues
1) Should we include pause/resume functionality?
RESOLVED: Yes, this is needed to ease layering other APIs which have this
functionality.
To pause use vkCmdEndTransformFeedbackEXT and provide valid buffer
handles in the pCounterBuffers array and offsets in the
pCounterBufferOffsets array for the implementation to save the resume
points.
Then to resume use vkCmdBeginTransformFeedbackEXT with the previous
pCounterBuffers and pCounterBufferOffsets values.
Between the pause and resume there needs to be a memory barrier for the
counter buffers with a source access of
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT at pipeline stage
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT to a destination access
of VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT at pipeline stage
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT.
2) How does this interact with multiview?
RESOLVED: Transform feedback cannot be made active in a render pass with multiview enabled.
3) How should queries be done?
RESOLVED: There is a new query type
VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT.
A query pool created with this type will capture 2 integers -
numPrimitivesWritten and numPrimitivesNeeded - for the specified vertex
stream output from the last
pre-rasterization shader
stage.
The vertex stream output queried is zero by default, but can be specified
with the new vkCmdBeginQueryIndexedEXT and
vkCmdEndQueryIndexedEXT commands.
VK_EXT_validation_cache
- Name String
-
VK_EXT_validation_cache - Extension Type
-
Device extension
- Registered Extension Number
-
161
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Cort Stratton cdwfs
-
Other Extension Metadata
- Last Modified Date
-
2017-08-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Cort Stratton, Google
-
Chris Forbes, Google
-
Description
This extension provides a mechanism for caching the results of potentially expensive internal validation operations across multiple runs of a Vulkan application. At the core is the VkValidationCacheEXT object type, which is managed similarly to the existing VkPipelineCache.
The new struct VkShaderModuleValidationCacheCreateInfoEXT can be
included in the pNext chain at vkCreateShaderModule time.
It contains a VkValidationCacheEXT to use when validating the
VkShaderModule.
New Enum Constants
-
VK_EXT_VALIDATION_CACHE_EXTENSION_NAME -
VK_EXT_VALIDATION_CACHE_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_VALIDATION_CACHE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT
-
VK_EXT_validation_features
- Name String
-
VK_EXT_validation_features - Extension Type
-
Instance extension
- Registered Extension Number
-
248
- Revision
-
5
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Use
- Contact
-
-
Karl Schultz karl-lunarg
-
Other Extension Metadata
- Last Modified Date
-
2018-11-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Karl Schultz, LunarG
-
Dave Houlton, LunarG
-
Mark Lobodzinski, LunarG
-
Camden Stocker, LunarG
-
Tony Barbour, LunarG
-
John Zulauf, LunarG
-
Description
This extension provides the VkValidationFeaturesEXT struct that can be
included in the pNext chain of the VkInstanceCreateInfo
structure passed as the pCreateInfo parameter of
vkCreateInstance.
The structure contains an array of VkValidationFeatureEnableEXT enum
values that enable specific validation features that are disabled by
default.
The structure also contains an array of VkValidationFeatureDisableEXT
enum values that disable specific validation layer features that are enabled
by default.
|
Note
The |
New Structures
-
Extending VkInstanceCreateInfo:
New Enum Constants
-
VK_EXT_VALIDATION_FEATURES_EXTENSION_NAME -
VK_EXT_VALIDATION_FEATURES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT
-
Version History
-
Revision 1, 2018-11-14 (Karl Schultz)
-
Initial revision
-
-
Revision 2, 2019-08-06 (Mark Lobodzinski)
-
Add Best Practices enable
-
-
Revision 3, 2020-03-04 (Tony Barbour)
-
Add Debug Printf enable
-
-
Revision 4, 2020-07-29 (John Zulauf)
-
Add Synchronization Validation enable
-
-
Revision 5, 2021-05-18 (Tony Barbour)
-
Add Shader Validation Cache disable
-
VK_EXT_vertex_attribute_divisor
- Name String
-
VK_EXT_vertex_attribute_divisor - Extension Type
-
Device extension
- Registered Extension Number
-
191
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Vikram Kushwaha vkushwaha
-
Other Extension Metadata
- Last Modified Date
-
2018-08-03
- IP Status
-
No known IP claims.
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Jason Ekstrand, Intel
-
Description
This extension allows instance-rate vertex attributes to be repeated for certain number of instances instead of advancing for every instance when instanced rendering is enabled.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineVertexInputStateCreateInfo:
New Enum Constants
-
VK_EXT_VERTEX_ATTRIBUTE_DIVISOR_EXTENSION_NAME -
VK_EXT_VERTEX_ATTRIBUTE_DIVISOR_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT
-
Issues
1) What is the effect of a non-zero value for firstInstance?
RESOLVED: The Vulkan API should follow the OpenGL convention and offset
attribute fetching by firstInstance while computing vertex attribute
offsets.
2) Should zero be an allowed divisor?
RESOLVED: Yes. A zero divisor means the vertex attribute is repeated for all instances.
Examples
To create a vertex binding such that the first binding uses instanced rendering and the same attribute is used for every 4 draw instances, an application could use the following set of structures:
const VkVertexInputBindingDivisorDescriptionEXT divisorDesc =
{
0,
4
};
const VkPipelineVertexInputDivisorStateCreateInfoEXT divisorInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT, // sType
NULL, // pNext
1, // vertexBindingDivisorCount
&divisorDesc // pVertexBindingDivisors
}
const VkVertexInputBindingDescription binding =
{
0, // binding
sizeof(Vertex), // stride
VK_VERTEX_INPUT_RATE_INSTANCE // inputRate
};
const VkPipelineVertexInputStateCreateInfo viInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO, // sType
&divisorInfo, // pNext
...
};
//...
Version History
-
Revision 1, 2017-12-04 (Vikram Kushwaha)
-
First Version
-
-
Revision 2, 2018-07-16 (Jason Ekstrand)
-
Adjust the interaction between
divisorandfirstInstanceto match the OpenGL convention. -
Disallow divisors of zero.
-
-
Revision 3, 2018-08-03 (Vikram Kushwaha)
-
Allow a zero divisor.
-
Add a physical device features structure to query/enable this feature.
-
VK_EXT_vertex_input_dynamic_state
- Name String
-
VK_EXT_vertex_input_dynamic_state - Extension Type
-
Device extension
- Registered Extension Number
-
353
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2020-08-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Spencer Fricke, Samsung
-
Stu Smith, AMD
-
Description
One of the states that contributes to the combinatorial explosion of pipeline state objects that need to be created, is the vertex input binding and attribute descriptions. By allowing them to be dynamic applications may reduce the number of pipeline objects they need to create.
This extension adds dynamic state support for what is normally static state in VkPipelineVertexInputStateCreateInfo.
New Enum Constants
-
VK_EXT_VERTEX_INPUT_DYNAMIC_STATE_EXTENSION_NAME -
VK_EXT_VERTEX_INPUT_DYNAMIC_STATE_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_VERTEX_INPUT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_INPUT_DYNAMIC_STATE_FEATURES_EXT -
VK_STRUCTURE_TYPE_VERTEX_INPUT_ATTRIBUTE_DESCRIPTION_2_EXT -
VK_STRUCTURE_TYPE_VERTEX_INPUT_BINDING_DESCRIPTION_2_EXT
-
Version History
-
Revision 2, 2020-11-05 (Piers Daniell)
-
Make VkVertexInputBindingDescription2EXT extensible
-
Add new VkVertexInputAttributeDescription2EXT struct for the
pVertexAttributeDescriptionsparameter to vkCmdSetVertexInputEXT so it is also extensible
-
-
Revision 1, 2020-08-21 (Piers Daniell)
-
Internal revisions
-
VK_EXT_ycbcr_image_arrays
- Name String
-
VK_EXT_ycbcr_image_arrays - Extension Type
-
Device extension
- Registered Extension Number
-
253
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_sampler_ycbcr_conversionto be enabled for any device-level functionality
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Description
This extension allows images of a format that requires Y′CBCR conversion to be created with multiple array layers, which is otherwise restricted.
New Enum Constants
-
VK_EXT_YCBCR_IMAGE_ARRAYS_EXTENSION_NAME -
VK_EXT_YCBCR_IMAGE_ARRAYS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_IMAGE_ARRAYS_FEATURES_EXT
-
VK_AMD_buffer_marker
- Name String
-
VK_AMD_buffer_marker - Extension Type
-
Device extension
- Registered Extension Number
-
180
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Use
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2018-01-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Jaakko Konttinen, AMD
-
Daniel Rakos, AMD
-
Description
This extension adds a new operation to execute pipelined writes of small
marker values into a VkBuffer object.
The primary purpose of these markers is to facilitate the development of debugging tools for tracking which pipelined command contributed to device loss.
VK_AMD_device_coherent_memory
- Name String
-
VK_AMD_device_coherent_memory - Extension Type
-
Device extension
- Registered Extension Number
-
230
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2019-02-04
- Contributors
-
-
Ping Fu, AMD
-
Timothy Lottes, AMD
-
Tobias Hector, AMD
-
Description
This extension adds the device coherent and device uncached memory types. Any device accesses to device coherent memory are automatically made visible to any other device access. Device uncached memory indicates to applications that caches are disabled for a particular memory type, which guarantees device coherence.
Device coherent and uncached memory are expected to have lower performance for general access than non-device coherent memory, but can be useful in certain scenarios; particularly so for debugging.
New Enum Constants
-
VK_AMD_DEVICE_COHERENT_MEMORY_EXTENSION_NAME -
VK_AMD_DEVICE_COHERENT_MEMORY_SPEC_VERSION -
Extending VkMemoryPropertyFlagBits:
-
VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD -
VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COHERENT_MEMORY_FEATURES_AMD
-
VK_AMD_display_native_hdr
- Name String
-
VK_AMD_display_native_hdr - Extension Type
-
Device extension
- Registered Extension Number
-
214
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_get_surface_capabilities2to be enabled for any device-level functionality -
Requires
VK_KHR_swapchainto be enabled for any device-level functionality
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2018-12-18
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Aaron Hagan, AMD
-
Aric Cyr, AMD
-
Timothy Lottes, AMD
-
Derrick Owens, AMD
-
Daniel Rakos, AMD
-
Description
This extension introduces the following display native HDR features to Vulkan:
-
A new VkColorSpaceKHR enum for setting the native display colorspace. For example, this color space would be set by the swapchain to use the native color space in Freesync2 displays.
-
Local dimming control
New Enum Constants
-
VK_AMD_DISPLAY_NATIVE_HDR_EXTENSION_NAME -
VK_AMD_DISPLAY_NATIVE_HDR_SPEC_VERSION -
Extending VkColorSpaceKHR:
-
VK_COLOR_SPACE_DISPLAY_NATIVE_AMD
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_NATIVE_HDR_SURFACE_CAPABILITIES_AMD -
VK_STRUCTURE_TYPE_SWAPCHAIN_DISPLAY_NATIVE_HDR_CREATE_INFO_AMD
-
VK_AMD_gcn_shader
- Name String
-
VK_AMD_gcn_shader - Extension Type
-
Device extension
- Registered Extension Number
-
26
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2016-05-30
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_gcn_shader -
This extension provides API support for
GL_AMD_gcn_shader
-
- Contributors
-
-
Dominik Witczak, AMD
-
Daniel Rakos, AMD
-
Rex Xu, AMD
-
Graham Sellers, AMD
-
VK_AMD_memory_overallocation_behavior
- Name String
-
VK_AMD_memory_overallocation_behavior - Extension Type
-
Device extension
- Registered Extension Number
-
190
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Martin Dinkov mdinkov
-
Other Extension Metadata
- Last Modified Date
-
2018-09-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Martin Dinkov, AMD
-
Matthaeus Chajdas, AMD
-
Daniel Rakos, AMD
-
Jon Campbell, AMD
-
Description
This extension allows controlling whether explicit overallocation beyond the device memory heap sizes (reported by VkPhysicalDeviceMemoryProperties) is allowed or not. Overallocation may lead to performance loss and is not supported for all platforms.
New Enum Constants
-
VK_AMD_MEMORY_OVERALLOCATION_BEHAVIOR_EXTENSION_NAME -
VK_AMD_MEMORY_OVERALLOCATION_BEHAVIOR_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_MEMORY_OVERALLOCATION_CREATE_INFO_AMD
-
VK_AMD_mixed_attachment_samples
- Name String
-
VK_AMD_mixed_attachment_samples - Extension Type
-
Device extension
- Registered Extension Number
-
137
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2017-07-24
- Contributors
-
-
Mais Alnasser, AMD
-
Matthaeus G. Chajdas, AMD
-
Maciej Jesionowski, AMD
-
Daniel Rakos, AMD
-
Description
This extension enables applications to use multisampled rendering with a depth/stencil sample count that is larger than the color sample count. Having a depth/stencil sample count larger than the color sample count allows maintaining geometry and coverage information at a higher sample rate than color information. All samples are depth/stencil tested, but only the first color sample count number of samples get a corresponding color output.
New Enum Constants
-
VK_AMD_MIXED_ATTACHMENT_SAMPLES_EXTENSION_NAME -
VK_AMD_MIXED_ATTACHMENT_SAMPLES_SPEC_VERSION
VK_AMD_pipeline_compiler_control
- Name String
-
VK_AMD_pipeline_compiler_control - Extension Type
-
Device extension
- Registered Extension Number
-
184
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2019-07-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Daniel Rakos, AMD
-
Maciej Jesionowski, AMD
-
Tobias Hector, AMD
-
Description
This extension introduces VkPipelineCompilerControlCreateInfoAMD structure that can be chained to a pipeline’s creation information to specify additional flags that affect pipeline compilation.
New Enum Constants
-
VK_AMD_PIPELINE_COMPILER_CONTROL_EXTENSION_NAME -
VK_AMD_PIPELINE_COMPILER_CONTROL_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_COMPILER_CONTROL_CREATE_INFO_AMD
-
VK_AMD_rasterization_order
- Name String
-
VK_AMD_rasterization_order - Extension Type
-
Device extension
- Registered Extension Number
-
19
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2016-04-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Jaakko Konttinen, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Dominik Witczak, AMD
-
Description
This extension introduces the possibility for the application to control the order of primitive rasterization. In unextended Vulkan, the following stages are guaranteed to execute in API order:
-
depth bounds test
-
stencil test, stencil op, and stencil write
-
depth test and depth write
-
occlusion queries
-
blending, logic op, and color write
This extension enables applications to opt into a relaxed, implementation defined primitive rasterization order that may allow better parallel processing of primitives and thus enabling higher primitive throughput. It is applicable in cases where the primitive rasterization order is known to not affect the output of the rendering or any differences caused by a different rasterization order are not a concern from the point of view of the application’s purpose.
A few examples of cases when using the relaxed primitive rasterization order would not have an effect on the final rendering:
-
If the primitives rendered are known to not overlap in framebuffer space.
-
If depth testing is used with a comparison operator of
VK_COMPARE_OP_LESS,VK_COMPARE_OP_LESS_OR_EQUAL,VK_COMPARE_OP_GREATER, orVK_COMPARE_OP_GREATER_OR_EQUAL, and the primitives rendered are known to not overlap in clip space. -
If depth testing is not used and blending is enabled for all attachments with a commutative blend operator.
New Enum Constants
-
VK_AMD_RASTERIZATION_ORDER_EXTENSION_NAME -
VK_AMD_RASTERIZATION_ORDER_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_RASTERIZATION_ORDER_AMD
-
Issues
1) How is this extension useful to application developers?
RESOLVED: Allows them to increase primitive throughput for cases when strict API order rasterization is not important due to the nature of the content, the configuration used, or the requirements towards the output of the rendering.
2) How does this extension interact with content optimizations aiming to reduce overdraw by appropriately ordering the input primitives?
RESOLVED: While the relaxed rasterization order might somewhat limit the effectiveness of such content optimizations, most of the benefits of it are expected to be retained even when the relaxed rasterization order is used, so applications should still apply these optimizations even if they intend to use the extension.
3) Are there any guarantees about the primitive rasterization order when using the new relaxed mode?
RESOLVED: No. In this case the rasterization order is completely implementation-dependent, but in practice it is expected to partially still follow the order of incoming primitives.
4) Does the new relaxed rasterization order have any adverse effect on repeatability and other invariance rules of the API?
RESOLVED: Yes, in the sense that it extends the list of exceptions when the repeatability requirement does not apply.
VK_AMD_shader_ballot
- Name String
-
VK_AMD_shader_ballot - Extension Type
-
Device extension
- Registered Extension Number
-
38
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2016-09-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_ballot -
This extension provides API support for
GL_AMD_shader_ballot
-
- Contributors
-
-
Qun Lin, AMD
-
Graham Sellers, AMD
-
Daniel Rakos, AMD
-
Rex Xu, AMD
-
Dominik Witczak, AMD
-
Matthäus G. Chajdas, AMD
-
VK_AMD_shader_core_properties
- Name String
-
VK_AMD_shader_core_properties - Extension Type
-
Device extension
- Registered Extension Number
-
186
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Martin Dinkov mdinkov
-
Other Extension Metadata
- Last Modified Date
-
2019-06-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Martin Dinkov, AMD
-
Matthaeus G. Chajdas, AMD
-
Description
This extension exposes shader core properties for a target physical device
through the VK_KHR_get_physical_device_properties2 extension.
Please refer to the example below for proper usage.
New Enum Constants
-
VK_AMD_SHADER_CORE_PROPERTIES_EXTENSION_NAME -
VK_AMD_SHADER_CORE_PROPERTIES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_AMD
-
Examples
This example retrieves the shader core properties for a physical device.
extern VkInstance instance;
PFN_vkGetPhysicalDeviceProperties2 pfnVkGetPhysicalDeviceProperties2 =
reinterpret_cast<PFN_vkGetPhysicalDeviceProperties2>
(vkGetInstanceProcAddr(instance, "vkGetPhysicalDeviceProperties2") );
VkPhysicalDeviceProperties2 general_props;
VkPhysicalDeviceShaderCorePropertiesAMD shader_core_properties;
shader_core_properties.pNext = nullptr;
shader_core_properties.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_AMD;
general_props.pNext = &shader_core_properties;
general_props.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2;
// After this call, shader_core_properties has been populated
pfnVkGetPhysicalDeviceProperties2(device, &general_props);
printf("Number of shader engines: %d\n",
m_shader_core_properties.shader_engine_count =
shader_core_properties.shaderEngineCount;
printf("Number of shader arrays: %d\n",
m_shader_core_properties.shader_arrays_per_engine_count =
shader_core_properties.shaderArraysPerEngineCount;
printf("Number of CUs per shader array: %d\n",
m_shader_core_properties.compute_units_per_shader_array =
shader_core_properties.computeUnitsPerShaderArray;
printf("Number of SIMDs per compute unit: %d\n",
m_shader_core_properties.simd_per_compute_unit =
shader_core_properties.simdPerComputeUnit;
printf("Number of wavefront slots in each SIMD: %d\n",
m_shader_core_properties.wavefronts_per_simd =
shader_core_properties.wavefrontsPerSimd;
printf("Number of threads per wavefront: %d\n",
m_shader_core_properties.wavefront_size =
shader_core_properties.wavefrontSize;
printf("Number of physical SGPRs per SIMD: %d\n",
m_shader_core_properties.sgprs_per_simd =
shader_core_properties.sgprsPerSimd;
printf("Minimum number of SGPRs that can be allocated by a wave: %d\n",
m_shader_core_properties.min_sgpr_allocation =
shader_core_properties.minSgprAllocation;
printf("Number of available SGPRs: %d\n",
m_shader_core_properties.max_sgpr_allocation =
shader_core_properties.maxSgprAllocation;
printf("SGPRs are allocated in groups of this size: %d\n",
m_shader_core_properties.sgpr_allocation_granularity =
shader_core_properties.sgprAllocationGranularity;
printf("Number of physical VGPRs per SIMD: %d\n",
m_shader_core_properties.vgprs_per_simd =
shader_core_properties.vgprsPerSimd;
printf("Minimum number of VGPRs that can be allocated by a wave: %d\n",
m_shader_core_properties.min_vgpr_allocation =
shader_core_properties.minVgprAllocation;
printf("Number of available VGPRs: %d\n",
m_shader_core_properties.max_vgpr_allocation =
shader_core_properties.maxVgprAllocation;
printf("VGPRs are allocated in groups of this size: %d\n",
m_shader_core_properties.vgpr_allocation_granularity =
shader_core_properties.vgprAllocationGranularity;
Version History
-
Revision 2, 2019-06-25 (Matthaeus G. Chajdas)
-
Clarified the meaning of a few fields.
-
-
Revision 1, 2018-02-15 (Martin Dinkov)
-
Initial draft.
-
VK_AMD_shader_core_properties2
- Name String
-
VK_AMD_shader_core_properties2 - Extension Type
-
Device extension
- Registered Extension Number
-
228
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_AMD_shader_core_propertiesto be enabled for any device-level functionality
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2019-07-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Tobias Hector, AMD
-
Description
This extension exposes additional shader core properties for a target
physical device through the VK_KHR_get_physical_device_properties2
extension.
New Enum Constants
-
VK_AMD_SHADER_CORE_PROPERTIES_2_EXTENSION_NAME -
VK_AMD_SHADER_CORE_PROPERTIES_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_2_AMD
-
VK_AMD_shader_early_and_late_fragment_tests
- Name String
-
VK_AMD_shader_early_and_late_fragment_tests - Extension Type
-
Device extension
- Registered Extension Number
-
322
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-09-14
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_early_and_late_fragment_tests -
This extension interacts with
VK_EXT_shader_stencil_export
-
- Contributors
-
-
Tobias Hector, AMD
-
Description
This extension adds support for the
SPV_AMD_shader_early_and_late_fragment_tests
extension, allowing shaders to explicitly opt in to allowing both early
and late fragment tests with the EarlyAndLateFragmentTestsAMD
execution mode.
If VK_EXT_shader_stencil_export is supported, additional execution
modes allowing early depth tests similar to DepthUnchanged,
DepthLess, and DepthGreater are provided.
New Enum Constants
-
VK_AMD_SHADER_EARLY_AND_LATE_FRAGMENT_TESTS_EXTENSION_NAME -
VK_AMD_SHADER_EARLY_AND_LATE_FRAGMENT_TESTS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_EARLY_AND_LATE_FRAGMENT_TESTS_FEATURES_AMD
-
VK_AMD_shader_explicit_vertex_parameter
- Name String
-
VK_AMD_shader_explicit_vertex_parameter - Extension Type
-
Device extension
- Registered Extension Number
-
22
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Qun Lin linqun
-
Other Extension Metadata
- Last Modified Date
-
2016-05-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_explicit_vertex_parameter -
This extension provides API support for
GL_AMD_shader_explicit_vertex_parameter
-
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Qun Lin, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Rex Xu, AMD
-
New Enum Constants
-
VK_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER_EXTENSION_NAME -
VK_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER_SPEC_VERSION
VK_AMD_shader_fragment_mask
- Name String
-
VK_AMD_shader_fragment_mask - Extension Type
-
Device extension
- Registered Extension Number
-
138
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Aaron Hagan AaronHaganAMD
-
Other Extension Metadata
- Last Modified Date
-
2017-08-16
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_fragment_mask -
This extension provides API support for
GL_AMD_shader_fragment_mask
-
- Contributors
-
-
Aaron Hagan, AMD
-
Daniel Rakos, AMD
-
Timothy Lottes, AMD
-
Description
This extension provides efficient read access to the fragment mask in compressed multisampled color surfaces. The fragment mask is a lookup table that associates color samples with color fragment values.
From a shader, the fragment mask can be fetched with a call to
fragmentMaskFetchAMD, which returns a single uint where each
subsequent four bits specify the color fragment index corresponding to the
color sample, starting from the least significant bit.
For example, when eight color samples are used, the color fragment index for
color sample 0 will be in bits 0-3 of the fragment mask, for color sample 7
the index will be in bits 28-31.
The color fragment for a particular color sample may then be fetched with
the corresponding fragment mask value using the fragmentFetchAMD shader
function.
New Enum Constants
-
VK_AMD_SHADER_FRAGMENT_MASK_EXTENSION_NAME -
VK_AMD_SHADER_FRAGMENT_MASK_SPEC_VERSION
Examples
This example shows a shader that queries the fragment mask from a multisampled compressed surface and uses it to query fragment values.
#version 450 core
#extension GL_AMD_shader_fragment_mask: enable
layout(binding = 0) uniform sampler2DMS s2DMS;
layout(binding = 1) uniform isampler2DMSArray is2DMSArray;
layout(binding = 2, input_attachment_index = 0) uniform usubpassInputMS usubpassMS;
layout(location = 0) out vec4 fragColor;
void main()
{
vec4 fragOne = vec4(0.0);
uint fragMask = fragmentMaskFetchAMD(s2DMS, ivec2(2, 3));
uint fragIndex = (fragMask & 0xF0) >> 4;
fragOne += fragmentFetchAMD(s2DMS, ivec2(2, 3), 1);
fragMask = fragmentMaskFetchAMD(is2DMSArray, ivec3(2, 3, 1));
fragIndex = (fragMask & 0xF0) >> 4;
fragOne += fragmentFetchAMD(is2DMSArray, ivec3(2, 3, 1), fragIndex);
fragMask = fragmentMaskFetchAMD(usubpassMS);
fragIndex = (fragMask & 0xF0) >> 4;
fragOne += fragmentFetchAMD(usubpassMS, fragIndex);
fragColor = fragOne;
}
VK_AMD_shader_image_load_store_lod
- Name String
-
VK_AMD_shader_image_load_store_lod - Extension Type
-
Device extension
- Registered Extension Number
-
47
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2017-08-21
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_image_load_store_lod -
This extension provides API support for
GL_AMD_shader_image_load_store_lod
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Dominik Witczak, AMD
-
Qun Lin, AMD
-
Rex Xu, AMD
-
New Enum Constants
-
VK_AMD_SHADER_IMAGE_LOAD_STORE_LOD_EXTENSION_NAME -
VK_AMD_SHADER_IMAGE_LOAD_STORE_LOD_SPEC_VERSION
VK_AMD_shader_info
- Name String
-
VK_AMD_shader_info - Extension Type
-
Device extension
- Registered Extension Number
-
43
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Use
- Contact
-
-
Jaakko Konttinen jaakkoamd
-
Other Extension Metadata
- Last Modified Date
-
2017-10-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Jaakko Konttinen, AMD
-
Description
This extension adds a way to query certain information about a compiled shader which is part of a pipeline. This information may include shader disassembly, shader binary and various statistics about a shader’s resource usage.
While this extension provides a mechanism for extracting this information, the details regarding the contents or format of this information are not specified by this extension and may be provided by the vendor externally.
Furthermore, all information types are optionally supported, and users should not assume every implementation supports querying every type of information.
Examples
This example extracts the register usage of a fragment shader within a particular graphics pipeline:
extern VkDevice device;
extern VkPipeline gfxPipeline;
PFN_vkGetShaderInfoAMD pfnGetShaderInfoAMD = (PFN_vkGetShaderInfoAMD)vkGetDeviceProcAddr(
device, "vkGetShaderInfoAMD");
VkShaderStatisticsInfoAMD statistics = {};
size_t dataSize = sizeof(statistics);
if (pfnGetShaderInfoAMD(device,
gfxPipeline,
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_INFO_TYPE_STATISTICS_AMD,
&dataSize,
&statistics) == VK_SUCCESS)
{
printf("VGPR usage: %d\n", statistics.resourceUsage.numUsedVgprs);
printf("SGPR usage: %d\n", statistics.resourceUsage.numUsedSgprs);
}
The following example continues the previous example by subsequently attempting to query and print shader disassembly about the fragment shader:
// Query disassembly size (if available)
if (pfnGetShaderInfoAMD(device,
gfxPipeline,
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD,
&dataSize,
nullptr) == VK_SUCCESS)
{
printf("Fragment shader disassembly:\n");
void* disassembly = malloc(dataSize);
// Query disassembly and print
if (pfnGetShaderInfoAMD(device,
gfxPipeline,
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD,
&dataSize,
disassembly) == VK_SUCCESS)
{
printf((char*)disassembly);
}
free(disassembly);
}
VK_AMD_shader_trinary_minmax
- Name String
-
VK_AMD_shader_trinary_minmax - Extension Type
-
Device extension
- Registered Extension Number
-
21
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Qun Lin linqun
-
Other Extension Metadata
- Last Modified Date
-
2016-05-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_trinary_minmax -
This extension provides API support for
GL_AMD_shader_trinary_minmax
-
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Qun Lin, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Rex Xu, AMD
-
New Enum Constants
-
VK_AMD_SHADER_TRINARY_MINMAX_EXTENSION_NAME -
VK_AMD_SHADER_TRINARY_MINMAX_SPEC_VERSION
VK_AMD_texture_gather_bias_lod
- Name String
-
VK_AMD_texture_gather_bias_lod - Extension Type
-
Device extension
- Registered Extension Number
-
42
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Rex Xu amdrexu
-
Other Extension Metadata
- Last Modified Date
-
2017-03-21
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_texture_gather_bias_lod -
This extension provides API support for
GL_AMD_texture_gather_bias_lod
-
- Contributors
-
-
Dominik Witczak, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Matthaeus G. Chajdas, AMD
-
Qun Lin, AMD
-
Rex Xu, AMD
-
Timothy Lottes, AMD
-
Description
This extension adds two related features.
Firstly, support for the following SPIR-V extension in Vulkan is added:
-
SPV_AMD_texture_gather_bias_lod
Secondly, the extension allows the application to query which formats can be used together with the new function prototypes introduced by the SPIR-V extension.
New Enum Constants
-
VK_AMD_TEXTURE_GATHER_BIAS_LOD_EXTENSION_NAME -
VK_AMD_TEXTURE_GATHER_BIAS_LOD_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_TEXTURE_LOD_GATHER_FORMAT_PROPERTIES_AMD
-
Examples
struct VkTextureLODGatherFormatPropertiesAMD
{
VkStructureType sType;
const void* pNext;
VkBool32 supportsTextureGatherLODBiasAMD;
};
// ----------------------------------------------------------------------------------------
// How to detect if an image format can be used with the new function prototypes.
VkPhysicalDeviceImageFormatInfo2 formatInfo;
VkImageFormatProperties2 formatProps;
VkTextureLODGatherFormatPropertiesAMD textureLODGatherSupport;
textureLODGatherSupport.sType = VK_STRUCTURE_TYPE_TEXTURE_LOD_GATHER_FORMAT_PROPERTIES_AMD;
textureLODGatherSupport.pNext = nullptr;
formatInfo.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2;
formatInfo.pNext = nullptr;
formatInfo.format = ...;
formatInfo.type = ...;
formatInfo.tiling = ...;
formatInfo.usage = ...;
formatInfo.flags = ...;
formatProps.sType = VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2;
formatProps.pNext = &textureLODGatherSupport;
vkGetPhysicalDeviceImageFormatProperties2(physical_device, &formatInfo, &formatProps);
if (textureLODGatherSupport.supportsTextureGatherLODBiasAMD == VK_TRUE)
{
// physical device supports SPV_AMD_texture_gather_bias_lod for the specified
// format configuration.
}
else
{
// physical device does not support SPV_AMD_texture_gather_bias_lod for the
// specified format configuration.
}
VK_ANDROID_external_memory_android_hardware_buffer
- Name String
-
VK_ANDROID_external_memory_android_hardware_buffer - Extension Type
-
Device extension
- Registered Extension Number
-
130
- Revision
-
5
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_sampler_ycbcr_conversionto be enabled for any device-level functionality -
Requires
VK_KHR_external_memoryto be enabled for any device-level functionality -
Requires
VK_EXT_queue_family_foreignto be enabled for any device-level functionality -
Requires
VK_KHR_dedicated_allocationto be enabled for any device-level functionality
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2021-09-30
- IP Status
-
No known IP claims.
- Contributors
-
-
Ray Smith, ARM
-
Chad Versace, Google
-
Jesse Hall, Google
-
Tobias Hector, Imagination
-
James Jones, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Matthew Netsch, Qualcomm
-
Andrew Garrard, Samsung
-
Description
This extension enables an application to import Android
AHardwareBuffer objects created outside of the Vulkan device into
Vulkan memory objects, where they can be bound to images and buffers.
It also allows exporting an AHardwareBuffer from a Vulkan memory
object for symmetry with other operating systems.
But since not all AHardwareBuffer usages and formats have Vulkan
equivalents, exporting from Vulkan provides strictly less functionality than
creating the AHardwareBuffer externally and importing it.
Some AHardwareBuffer images have implementation-defined external
formats that may not correspond to Vulkan formats.
Sampler Y′CBCR conversion can be used to sample from these images and
convert them to a known color space.
New Enum Constants
-
VK_ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_EXTENSION_NAME -
VK_ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_SPEC_VERSION -
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID -
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_PROPERTIES_ANDROID -
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_USAGE_ANDROID -
VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID -
VK_STRUCTURE_TYPE_IMPORT_ANDROID_HARDWARE_BUFFER_INFO_ANDROID -
VK_STRUCTURE_TYPE_MEMORY_GET_ANDROID_HARDWARE_BUFFER_INFO_ANDROID
-
If VK_KHR_format_feature_flags2 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_2_ANDROID
-
Issues
1) Other external memory objects are represented as weakly-typed handles
(e.g. Win32 HANDLE or POSIX file descriptor), and require a handle type
parameter along with handles.
AHardwareBuffer is strongly typed, so naming the handle type is
redundant.
Does symmetry justify adding handle type parameters/fields anyway?
RESOLVED: No.
The handle type is already provided in places that treat external memory
objects generically.
In the places we would add it, the application code that would have to
provide the handle type value is already dealing with
AHardwareBuffer-specific commands/structures; the extra symmetry
would not be enough to make that code generic.
2) The internal layout and therefore size of a AHardwareBuffer
image may depend on native usage flags that do not have corresponding Vulkan
counterparts.
Do we provide this information to vkCreateImage somehow, or allow the
allocation size reported by vkGetImageMemoryRequirements to be
approximate?
RESOLVED: Allow the allocation size to be unspecified when allocating the
memory.
It has to work this way for exported image memory anyway, since
AHardwareBuffer allocation happens in vkAllocateMemory, and
internally is performed by a separate HAL, not the Vulkan implementation
itself.
There is a similar issue with vkGetImageSubresourceLayout: the layout
is determined by the allocator HAL, so it is not known until the image is
bound to memory.
3) Should the result of sampling an external-format image with the suggested
Y′CBCR conversion parameters yield the same results as using a
samplerExternalOES in OpenGL ES?
RESOLVED: This would be desirable, so that apps converting from OpenGL ES to Vulkan could get the same output given the same input. But since sampling and conversion from Y′CBCR images is so loosely defined in OpenGL ES, multiple implementations do it in a way that does not conform to Vulkan’s requirements. Modifying the OpenGL ES implementation would be difficult, and would change the output of existing unmodified applications. Changing the output only for applications that are being modified gives developers the chance to notice and mitigate any problems. Implementations are encouraged to minimize differences as much as possible without causing compatibility problems for existing OpenGL ES applications or violating Vulkan requirements.
4) Should an AHardwareBuffer with AHARDWAREBUFFER_USAGE_CPU_*
usage be mappable in Vulkan? Should it be possible to export an
AHardwareBuffers with such usage?
RESOLVED: Optional, and mapping in Vulkan is not the same as
AHardwareBuffer_lock.
The semantics of these are different: mapping in memory is persistent, just
gives a raw view of the memory contents, and does not involve ownership.
AHardwareBuffer_lock gives the host exclusive access to the buffer, is
temporary, and allows for reformatting copy-in/copy-out.
Implementations are not required to support host-visible memory types for
imported Android hardware buffers or resources backed by them.
If a host-visible memory type is supported and used, the memory can be
mapped in Vulkan, but doing so follows Vulkan semantics: it is just a raw
view of the data and does not imply ownership (this means implementations
must not internally call AHardwareBuffer_lock to implement
vkMapMemory, or assume the application has done so).
Implementations are not required to support linear-tiled images backed by
Android hardware buffers, even if the AHardwareBuffer has CPU
usage.
There is no reliable way to allocate memory in Vulkan that can be exported
to a AHardwareBuffer with CPU usage.
5) Android may add new AHardwareBuffer formats and usage flags over
time.
Can reference to them be added to this extension, or do they need a new
extension?
RESOLVED: This extension can document the interaction between the new AHB
formats/usages and existing Vulkan features.
No new Vulkan features or implementation requirements can be added.
The extension version number will be incremented when this additional
documentation is added, but the version number does not indicate that an
implementation supports Vulkan memory or resources that map to the new
AHardwareBuffer features: support for that must be queried with
vkGetPhysicalDeviceImageFormatProperties2 or is implied by
successfully allocating a AHardwareBuffer outside of Vulkan that
uses the new feature and has a GPU usage flag.
In essence, these are new features added to a new Android API level, rather than new Vulkan features. The extension will only document how existing Vulkan features map to that new Android feature.
Version History
-
Revision 5, 2022-02-04 (Chris Forbes)
-
Describe mapping of flags for storage image support
-
-
Revision 4, 2021-09-30 (Jon Leech)
-
Add interaction with
VK_KHR_format_feature_flags2tovk.xml
-
-
Revision 3, 2019-08-27 (Jon Leech)
-
Update revision history to correspond to XML version number
-
-
Revision 2, 2018-04-09 (Petr Kraus)
-
Markup fixes and remove incorrect Draft status
-
-
Revision 1, 2018-03-04 (Jesse Hall)
-
Initial version
-
VK_ARM_rasterization_order_attachment_access
- Name String
-
VK_ARM_rasterization_order_attachment_access - Extension Type
-
Device extension
- Registered Extension Number
-
343
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2021-11-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Tobias Hector, AMD
-
Jan-Harald Fredriksen, Arm
-
Description
Renderpasses, and specifically subpass self-dependencies enable much of the same functionality as the framebuffer fetch and pixel local storage extensions did for OpenGL ES. But certain techniques such as programmable blending are awkward or impractical to implement with these alone, in part because a self-dependency is required every time a fragment will read a value at a given sample coordinate.
This extension extends the mechanism of input attachments to allow access to framebuffer attachments when used as both input and color, or depth/stencil, attachments from one fragment to the next, in rasterization order, without explicit synchronization.
See renderpass feedback loops for more information.
New Enum Constants
-
VK_ARM_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_EXTENSION_NAME -
VK_ARM_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_SPEC_VERSION -
Extending VkPipelineColorBlendStateCreateFlagBits:
-
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM
-
-
Extending VkPipelineDepthStencilStateCreateFlagBits:
-
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM -
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_FEATURES_ARM
-
-
Extending VkSubpassDescriptionFlagBits:
-
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARM -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM
-
Issues
1) Is there any interaction with the VK_KHR_dynamic_rendering
extension?
No. This extension only affects reads from input attachments. Render pass instances begun with vkCmdBeginRenderingKHR do not have input attachments and a different mechanism will be needed to provide similar functionality in this case.
VK_FUCHSIA_buffer_collection
- Name String
-
VK_FUCHSIA_buffer_collection - Extension Type
-
Device extension
- Registered Extension Number
-
367
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_FUCHSIA_external_memoryto be enabled for any device-level functionality -
Requires
VK_KHR_sampler_ycbcr_conversionto be enabled for any device-level functionality
-
- Contact
-
-
John Rosasco rosasco
-
Other Extension Metadata
- Last Modified Date
-
2021-09-23
- IP Status
-
No known IP claims.
- Contributors
-
-
Craig Stout, Google
-
John Bauman, Google
-
John Rosasco, Google
-
Description
A buffer collection is a collection of one or more buffers which were allocated together as a group and which all have the same properties. These properties describe the buffers' internal representation such as its dimensions and memory layout. This ensures that all of the buffers can be used interchangeably by tasks that require swapping among multiple buffers, such as double-buffered graphics rendering.
By sharing such a collection of buffers between components, communication about buffer lifecycle can be made much simpler and more efficient. For example, when a content producer finishes writing to a buffer, it can message the consumer of the buffer with the buffer index, rather than passing a handle to the shared memory.
On Fuchsia, the Sysmem service uses buffer collections as a core construct in its design. VK_FUCHSIA_buffer_collection is the Vulkan extension that allows Vulkan applications to interoperate with the Sysmem service on Fuchsia.
New Structures
-
Extending VkBufferCreateInfo:
-
Extending VkImageCreateInfo:
-
Extending VkMemoryAllocateInfo:
New Enum Constants
-
VK_FUCHSIA_BUFFER_COLLECTION_EXTENSION_NAME -
VK_FUCHSIA_BUFFER_COLLECTION_SPEC_VERSION -
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_COLLECTION_FUCHSIA_EXT
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_BUFFER_COLLECTION_FUCHSIA
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_BUFFER_CREATE_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_CONSTRAINTS_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_CREATE_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_IMAGE_CREATE_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_PROPERTIES_FUCHSIA -
VK_STRUCTURE_TYPE_BUFFER_CONSTRAINTS_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_IMAGE_CONSTRAINTS_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_IMAGE_FORMAT_CONSTRAINTS_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_IMPORT_MEMORY_BUFFER_COLLECTION_FUCHSIA -
VK_STRUCTURE_TYPE_SYSMEM_COLOR_SPACE_FUCHSIA
-
Issues
1) When configuring a VkImageConstraintsInfoFUCHSIA structure for
constraint setting, should a NULL pFormatConstraints parameter be
allowed ?
RESOLVED: No.
Specifying a NULL pFormatConstraints results in logical complexity of
interpreting the relationship between the
VkImageCreateInfo::usage settings of the elements of the
pImageCreateInfos array and the implied or desired
VkFormatFeatureFlags.
The explicit requirement for pFormatConstraints to be non-NULL
simplifies the implied logic of the implementation and expectations for the
Vulkan application.
Version History
-
Revision 2, 2021-09-23 (John Rosasco)
-
Review passes
-
-
Revision 1, 2021-03-09 (John Rosasco)
-
Initial revision
-
VK_FUCHSIA_external_memory
- Name String
-
VK_FUCHSIA_external_memory - Extension Type
-
Device extension
- Registered Extension Number
-
365
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_memory_capabilitiesto be enabled for any device-level functionality -
Requires
VK_KHR_external_memoryto be enabled for any device-level functionality
-
- Contact
-
-
John Rosasco rosasco
-
Other Extension Metadata
- Last Modified Date
-
2021-03-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Craig Stout, Google
-
John Bauman, Google
-
John Rosasco, Google
-
Description
Vulkan apps may wish to export or import device memory handles to or from other logical devices, instances or APIs.
This memory sharing can eliminate copies of memory buffers when different subsystems need to interoperate on them. Sharing memory buffers may also facilitate a better distribution of processing workload for more complex memory manipulation pipelines.
New Enum Constants
-
VK_FUCHSIA_EXTERNAL_MEMORY_EXTENSION_NAME -
VK_FUCHSIA_EXTERNAL_MEMORY_SPEC_VERSION -
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_ZIRCON_HANDLE_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_MEMORY_GET_ZIRCON_HANDLE_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_MEMORY_ZIRCON_HANDLE_PROPERTIES_FUCHSIA
-
Issues
See VK_KHR_external_memory issues list for further information.
VK_FUCHSIA_external_semaphore
- Name String
-
VK_FUCHSIA_external_semaphore - Extension Type
-
Device extension
- Registered Extension Number
-
366
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_semaphore_capabilitiesto be enabled for any device-level functionality -
Requires
VK_KHR_external_semaphoreto be enabled for any device-level functionality
-
- Contact
-
-
John Rosasco rosasco
-
Other Extension Metadata
- Last Modified Date
-
2021-03-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Craig Stout, Google
-
John Bauman, Google
-
John Rosasco, Google
-
Description
An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to export semaphore payload to and import semaphore payload from Zircon event handles.
New Enum Constants
-
VK_FUCHSIA_EXTERNAL_SEMAPHORE_EXTENSION_NAME -
VK_FUCHSIA_EXTERNAL_SEMAPHORE_SPEC_VERSION -
Extending VkExternalSemaphoreHandleTypeFlagBits:
-
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_ZIRCON_HANDLE_INFO_FUCHSIA -
VK_STRUCTURE_TYPE_SEMAPHORE_GET_ZIRCON_HANDLE_INFO_FUCHSIA
-
Issues
1) Does the application need to close the Zircon event handle returned by vkGetSemaphoreZirconHandleFUCHSIA?
RESOLVED: Yes, unless it is passed back in to a driver instance to import the semaphore. A successful get call transfers ownership of the Zircon event handle to the application, and a successful import transfers it back to the driver. Destroying the original semaphore object will not close the Zircon event handle nor remove its reference to the underlying semaphore resource associated with it.
VK_FUCHSIA_imagepipe_surface
- Name String
-
VK_FUCHSIA_imagepipe_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
215
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Craig Stout cdotstout
-
Other Extension Metadata
- Last Modified Date
-
2018-07-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Craig Stout, Google
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Description
The VK_FUCHSIA_imagepipe_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) that refers to a Fuchsia
imagePipeHandle.
New Enum Constants
-
VK_FUCHSIA_IMAGEPIPE_SURFACE_EXTENSION_NAME -
VK_FUCHSIA_IMAGEPIPE_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA
-
VK_GGP_frame_token
- Name String
-
VK_GGP_frame_token - Extension Type
-
Device extension
- Registered Extension Number
-
192
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality -
Requires
VK_GGP_stream_descriptor_surfaceto be enabled for any device-level functionality
-
- Contact
-
-
Jean-Francois Roy jfroy
-
Other Extension Metadata
- Last Modified Date
-
2019-01-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Jean-Francois Roy, Google
-
Richard O’Grady, Google
-
Description
This extension allows an application that uses the VK_KHR_swapchain
extension in combination with a Google Games Platform surface provided by
the VK_GGP_stream_descriptor_surface extension to associate a
Google Games Platform frame token with a present operation.
New Structures
-
Extending VkPresentInfoKHR:
New Enum Constants
-
VK_GGP_FRAME_TOKEN_EXTENSION_NAME -
VK_GGP_FRAME_TOKEN_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_FRAME_TOKEN_GGP
-
VK_GGP_stream_descriptor_surface
- Name String
-
VK_GGP_stream_descriptor_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
50
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Jean-Francois Roy jfroy
-
Other Extension Metadata
- Last Modified Date
-
2019-01-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Jean-Francois Roy, Google
-
Brad Grantham, Google
-
Connor Smith, Google
-
Cort Stratton, Google
-
Hai Nguyen, Google
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Jim Ray, Google
-
Katherine Wu, Google
-
Kaye Mason, Google
-
Kuangye Guo, Google
-
Mark Segal, Google
-
Nicholas Vining, Google
-
Paul Lalonde, Google
-
Richard O’Grady, Google
-
Description
The VK_GGP_stream_descriptor_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) that refers to a Google Games
Platform GgpStreamDescriptor.
New Enum Constants
-
VK_GGP_STREAM_DESCRIPTOR_SURFACE_EXTENSION_NAME -
VK_GGP_STREAM_DESCRIPTOR_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_STREAM_DESCRIPTOR_SURFACE_CREATE_INFO_GGP
-
VK_GOOGLE_decorate_string
- Name String
-
VK_GOOGLE_decorate_string - Extension Type
-
Device extension
- Registered Extension Number
-
225
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Hai Nguyen chaoticbob
-
Other Extension Metadata
- Last Modified Date
-
2018-07-09
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_GOOGLE_decorate_string
-
- Contributors
-
-
Hai Nguyen, Google
-
Neil Henning, AMD
-
Description
The VK_GOOGLE_decorate_string extension allows use of the
SPV_GOOGLE_decorate_string extension in SPIR-V shader modules.
VK_GOOGLE_display_timing
- Name String
-
VK_GOOGLE_display_timing - Extension Type
-
Device extension
- Registered Extension Number
-
93
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality
-
- Contact
-
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2017-02-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Description
This device extension allows an application that uses the
VK_KHR_swapchain extension to obtain information about the
presentation engine’s display, to obtain timing information about each
present, and to schedule a present to happen no earlier than a desired time.
An application can use this to minimize various visual anomalies (e.g.
stuttering).
Traditional game and real-time animation applications need to correctly position their geometry for when the presentable image will be presented to the user. To accomplish this, applications need various timing information about the presentation engine’s display. They need to know when presentable images were actually presented, and when they could have been presented. Applications also need to tell the presentation engine to display an image no sooner than a given time. This allows the application to avoid stuttering, so the animation looks smooth to the user.
This extension treats variable-refresh-rate (VRR) displays as if they are fixed-refresh-rate (FRR) displays.
New Enum Constants
-
VK_GOOGLE_DISPLAY_TIMING_EXTENSION_NAME -
VK_GOOGLE_DISPLAY_TIMING_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE
-
Examples
|
Note
The example code for the this extension (like the |
VK_GOOGLE_hlsl_functionality1
- Name String
-
VK_GOOGLE_hlsl_functionality1 - Extension Type
-
Device extension
- Registered Extension Number
-
224
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Hai Nguyen chaoticbob
-
Other Extension Metadata
- Last Modified Date
-
2018-07-09
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_GOOGLE_hlsl_functionality1
-
- Contributors
-
-
Hai Nguyen, Google
-
Neil Henning, AMD
-
Description
The VK_GOOGLE_hlsl_functionality1 extension allows use of the
SPV_GOOGLE_hlsl_functionality1 extension in SPIR-V shader modules.
New Enum Constants
-
VK_GOOGLE_HLSL_FUNCTIONALITY1_EXTENSION_NAME -
VK_GOOGLE_HLSL_FUNCTIONALITY1_SPEC_VERSION -
VK_GOOGLE_HLSL_FUNCTIONALITY_1_EXTENSION_NAME -
VK_GOOGLE_HLSL_FUNCTIONALITY_1_SPEC_VERSION
VK_GOOGLE_surfaceless_query
- Name String
-
VK_GOOGLE_surfaceless_query - Extension Type
-
Instance extension
- Registered Extension Number
-
434
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Special Use
- Contact
-
-
Shahbaz Youssefi syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-12-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
Shahbaz Youssefi, Google
-
James Jones, NVIDIA
-
Description
This extension allows the vkGetPhysicalDeviceSurfaceFormatsKHR and
vkGetPhysicalDeviceSurfacePresentModesKHR functions to accept
VK_NULL_HANDLE as their surface parameter, allowing potential
surface formats, colorspaces and present modes to be queried without
providing a surface.
Identically, vkGetPhysicalDeviceSurfaceFormats2KHR and
vkGetPhysicalDeviceSurfacePresentModes2EXT would accept
VK_NULL_HANDLE in
VkPhysicalDeviceSurfaceInfo2KHR::surface.
This can only be supported on platforms where the results of these queries
are surface-agnostic and a single presentation engine is the implicit target
of all present operations.
New Enum Constants
-
VK_GOOGLE_SURFACELESS_QUERY_EXTENSION_NAME -
VK_GOOGLE_SURFACELESS_QUERY_SPEC_VERSION
VK_GOOGLE_user_type
- Name String
-
VK_GOOGLE_user_type - Extension Type
-
Device extension
- Registered Extension Number
-
290
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Kaye Mason chaleur
-
Other Extension Metadata
- Last Modified Date
-
2019-07-09
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_GOOGLE_user_type
-
- Contributors
-
-
Kaye Mason, Google
-
Hai Nguyen, Google
-
Description
The VK_GOOGLE_user_type extension allows use of the SPV_GOOGLE_user_type
extension in SPIR-V shader modules.
VK_HUAWEI_invocation_mask
- Name String
-
VK_HUAWEI_invocation_mask - Extension Type
-
Device extension
- Registered Extension Number
-
371
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_ray_tracing_pipelineto be enabled for any device-level functionality -
Requires
VK_KHR_synchronization2to be enabled for any device-level functionality
-
- Contact
-
-
Yunpeng Zhu yunxingzhu
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-05-27
- Interactions and External Dependencies
-
-
This extension requires
VK_KHR_ray_tracing_pipeline, which allow to bind an invocation mask image before the ray tracing command -
This extension requires
VK_KHR_synchronization2, which allows new pipeline stage for the invocation mask image
-
- Contributors
-
-
Yunpeng Zhu, HuaWei
-
Description
The rays to trace may be sparse in some use cases. For example, the scene only have a few regions to reflect. Providing an invocation mask image to the ray tracing commands could potentially give the hardware the hint to do certain optimization without invoking an additional pass to compact the ray buffer.
New Enum Constants
-
VK_HUAWEI_INVOCATION_MASK_EXTENSION_NAME -
VK_HUAWEI_INVOCATION_MASK_SPEC_VERSION -
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INVOCATION_MASK_FEATURES_HUAWEI
-
Examples
RT mask is updated before each traceRay.
Step 1. Generate InvocationMask.
//the rt mask image bind as color attachment in the fragment shader
Layout(location = 2) out vec4 outRTmask
vec4 mask = vec4(x,x,x,x);
outRTmask = mask;
Step 2. traceRay with InvocationMask
vkCmdBindPipeline(
commandBuffers[imageIndex],
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, m_rtPipeline);
vkCmdBindDescriptorSets(commandBuffers[imageIndex],
VK_PIPELINE_BIND_POINT_RAY_TRACING_NV,
m_rtPipelineLayout, 0, 1, &m_rtDescriptorSet,
0, nullptr);
vkCmdBindInvocationMaskHUAWEI(
commandBuffers[imageIndex],
InvocationMaskimageView,
InvocationMaskimageLayout);
vkCmdTraceRaysKHR(commandBuffers[imageIndex],
pRaygenShaderBindingTable,
pMissShaderBindingTable,
swapChainExtent.width,
swapChainExtent.height, 1);
VK_HUAWEI_subpass_shading
- Name String
-
VK_HUAWEI_subpass_shading - Extension Type
-
Device extension
- Registered Extension Number
-
370
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_create_renderpass2to be enabled for any device-level functionality -
Requires
VK_KHR_synchronization2to be enabled for any device-level functionality
-
- Contact
-
-
Hueilong Wang wyvernathuawei
-
Other Extension Metadata
- Last Modified Date
-
2021-06-01
- Interactions and External Dependencies
-
-
This extension requires
SPV_HUAWEI_subpass_shading. -
This extension provides API support for
GL_HUAWEI_subpass_shading.
-
- Contributors
-
-
Hueilong Wang
-
Description
This extension allows applications to execute a subpass shading pipeline in a subpass of a render pass in order to save memory bandwidth for algorithms like tile-based deferred rendering and forward plus. A subpass shading pipeline is a pipeline with the compute pipeline ability, allowed to read values from input attachments, and only allowed to be dispatched inside a stand-alone subpass. Its work dimension is defined by the render pass’s render area size. Its workgroup size (width, height) shall be a power-of-two number in width or height, with minimum value from 8, and maximum value shall be decided from the render pass attachments and sample counts but depends on implementation.
The GlobalInvocationId.xy of a subpass shading pipeline is equal to the
FragCoord.xy of a graphic pipeline in the same render pass subtracted
the offset of the
VkRenderPassBeginInfo::renderArea.
GlobalInvocationId.z is mapped to the Layer if
VK_EXT_shader_viewport_index_layer is supported.
The GlobalInvocationId.xy is equal to the index of the local workgroup
multiplied by the size of the local workgroup plus the
LocalInvocationId and the offset of the
VkRenderPassBeginInfo::renderArea.
This extension allows a subpass’s pipeline bind point to be
VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI.
New Enum Constants
-
VK_HUAWEI_SUBPASS_SHADING_EXTENSION_NAME -
VK_HUAWEI_SUBPASS_SHADING_SPEC_VERSION -
Extending VkPipelineBindPoint:
-
VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI
-
-
Extending VkShaderStageFlagBits:
-
VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBPASS_SHADING_FEATURES_HUAWEI -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBPASS_SHADING_PROPERTIES_HUAWEI -
VK_STRUCTURE_TYPE_SUBPASS_SHADING_PIPELINE_CREATE_INFO_HUAWEI
-
Sample Code
Example of subpass shading in a GLSL shader
#extension GL_HUAWEI_subpass_shading: enable
#extension GL_KHR_shader_subgroup_arithmetic: enable
layout(constant_id = 0) const uint tileWidth = 8;
layout(constant_id = 1) const uint tileHeight = 8;
layout(local_size_x_id = 0, local_size_y_id = 1, local_size_z = 1) in;
layout (set=0, binding=0, input_attachment_index=0) uniform subpassInput depth;
void main()
{
float d = subpassLoad(depth).x;
float minD = subgroupMin(d);
float maxD = subgroupMax(d);
}
Example of subpass shading dispatching in a subpass
vkCmdNextSubpass(commandBuffer, VK_SUBPASS_CONTENTS_INLINE);
vkCmdBindPipeline(commandBuffer, VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, subpassShadingPipeline);
vkCmdBindDescriptorSets(commandBuffer, VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, subpassShadingPipelineLayout,
firstSet, descriptorSetCount, pDescriptorSets, dynamicOffsetCount, pDynamicOffsets);
vkCmdSubpassShadingHUAWEI(commandBuffer)
vkCmdEndRenderPass(commandBuffer);
Example of subpass shading render pass creation
VkAttachmentDescription2 attachments[] = {
{
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2, NULL,
0, VK_FORMAT_R8G8B8A8_UNORM, VK_SAMPLE_COUNT_1_BIT,
VK_ATTACHMENT_LOAD_OP_CLEAR, VK_ATTACHMENT_STORE_OP_DONT_CARE,
VK_ATTACHMENT_LOAD_OP_DONT_CARE, VK_ATTACHMENT_LOAD_OP_DONT_CARE,
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
},
{
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2, NULL,
0, VK_FORMAT_R8G8B8A8_UNORM, VK_SAMPLE_COUNT_1_BIT,
VK_ATTACHMENT_LOAD_OP_CLEAR, VK_ATTACHMENT_STORE_OP_DONT_CARE,
VK_ATTACHMENT_LOAD_OP_DONT_CARE, VK_ATTACHMENT_LOAD_OP_DONT_CARE,
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
},
{
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2, NULL,
0, VK_FORMAT_R8G8B8A8_UNORM, VK_SAMPLE_COUNT_1_BIT,
VK_ATTACHMENT_LOAD_OP_CLEAR, VK_ATTACHMENT_STORE_OP_DONT_CARE,
VK_ATTACHMENT_LOAD_OP_DONT_CARE, VK_ATTACHMENT_LOAD_OP_DONT_CARE,
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
},
{
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2, NULL,
0, VK_FORMAT_D24_UNORM_S8_UINT, VK_SAMPLE_COUNT_1_BIT,
VK_ATTACHMENT_LOAD_OP_CLEAR, VK_ATTACHMENT_STORE_OP_DONT_CARE,
VK_ATTACHMENT_LOAD_OP_CLEAR, VK_ATTACHMENT_LOAD_OP_DONT_CARE,
VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL
},
{
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2, NULL,
0, VK_FORMAT_R8G8B8A8_UNORM, VK_SAMPLE_COUNT_1_BIT,
VK_ATTACHMENT_LOAD_OP_CLEAR, VK_ATTACHMENT_STORE_OP_STORE,
VK_ATTACHMENT_LOAD_OP_DONT_CARE, VK_ATTACHMENT_LOAD_OP_DONT_CARE,
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
}
};
VkAttachmentReference2 gBufferAttachmentReferences[] = {
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 0, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_COLOR_BIT },
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 1, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_COLOR_BIT },
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 2, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_COLOR_BIT }
};
VkAttachmentReference2 gBufferDepthStencilAttachmentReferences =
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 3, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_DEPTH_BIT|VK_IMAGE_ASPECT_STENCIL_BIT };
VkAttachmentReference2 depthInputAttachmentReferences[] = {
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 3, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_ASPECT_DEPTH_BIT|VK_IMAGE_ASPECT_STENCIL_BIT };
};
VkAttachmentReference2 preserveAttachmentReferences[] = {
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 0, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_COLOR_BIT },
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 1, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_COLOR_BIT },
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 2, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_COLOR_BIT },
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 3, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_DEPTH_BIT|VK_IMAGE_ASPECT_STENCIL_BIT }
}; // G buffer including depth/stencil
VkAttachmentReference2 colorAttachmentReferences[] = {
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 4, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_COLOR_BIT }
};
VkAttachmentReference2 resolveAttachmentReference =
{ VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, NULL, 4, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_ASPECT_COLOR_BIT };
VkSubpassDescription2 subpasses[] = {
{
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2, NULL, 0, VK_PIPELINE_BIND_POINT_GRAPHICS, 0,
0, NULL, // input
sizeof(gBufferAttachmentReferences)/sizeof(gBufferAttachmentReferences[0]), gBufferAttachmentReferences, // color
NULL, &gBufferDepthStencilAttachmentReferences, // resolve & DS
0, NULL
},
{
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2, NULL, 0, VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI , 0,
sizeof(depthInputAttachmentReferences)/sizeof(depthInputAttachmentReferences[0]), depthInputAttachmentReferences, // input
0, NULL, // color
NULL, NULL, // resolve & DS
sizeof(preserveAttachmentReferences)/sizeof(preserveAttachmentReferences[0]), preserveAttachmentReferences,
},
{
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2, NULL, 0, VK_PIPELINE_BIND_POINT_GRAPHICS, 0,
sizeof(gBufferAttachmentReferences)/sizeof(gBufferAttachmentReferences[0]), gBufferAttachmentReferences, // input
sizeof(colorAttachmentReferences)/sizeof(colorAttachmentReferences[0]), colorAttachmentReferences, // color
&resolveAttachmentReference, &gBufferDepthStencilAttachmentReferences, // resolve & DS
0, NULL
},
};
VkMemoryBarrier2KHR fragmentToSubpassShading = {
VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR, NULL,
VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT_KHR, VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT|VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI, VK_ACCESS_INPUT_ATTACHMENT_READ_BIT
};
VkMemoryBarrier2KHR subpassShadingToFragment = {
VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR, NULL,
VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI, VK_ACCESS_SHADER_WRITE_BIT,
VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT_KHR, VK_ACCESS_SHADER_READ_BIT
};
VkSubpassDependency2 dependencies[] = {
{
VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2, &fragmentToSubpassShading,
0, 1,
0, 0, 0, 0,
0, 0
},
{
VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2, &subpassShadingToFragment,
1, 2,
0, 0, 0, 0,
0, 0
},
};
VkRenderPassCreateInfo2 renderPassCreateInfo = {
VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2, NULL, 0,
sizeof(attachments)/sizeof(attachments[0]), attachments,
sizeof(subpasses)/sizeof(subpasses[0]), subpasses,
sizeof(dependencies)/sizeof(dependencies[0]), dependencies,
0, NULL
};
VKRenderPass renderPass;
vkCreateRenderPass2(device, &renderPassCreateInfo, NULL, &renderPass);
Example of subpass shading pipeline creation
VkExtent2D maxWorkgroupSize;
VkSpecializationMapEntry subpassShadingConstantMapEntries[] = {
{ 0, 0 * sizeof(uint32_t), sizeof(uint32_t) },
{ 1, 1 * sizeof(uint32_t), sizeof(uint32_t) }
};
VkSpecializationInfo subpassShadingConstants = {
2, subpassShadingConstantMapEntries,
sizeof(VkExtent2D), &maxWorkgroupSize
};
VkSubpassShadingPipelineCreateInfoHUAWEI subpassShadingPipelineCreateInfo {
VK_STRUCTURE_TYPE_SUBPASSS_SHADING_PIPELINE_CREATE_INFO_HUAWEI, NULL,
renderPass, 1
};
VkPipelineShaderStageCreateInfo subpassShadingPipelineStageCreateInfo {
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO, NULL,
0, VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI,
shaderModule, "main",
&subpassShadingConstants
};
VkComputePipelineCreateInfo subpassShadingComputePipelineCreateInfo = {
VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO, &subpassShadingPipelineCreateInfo,
0, &subpassShadingPipelineStageCreateInfo,
pipelineLayout, basePipelineHandle, basePipelineIndex
};
VKPipeline pipeline;
vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI(device, renderPass, &maxWorkgroupSize);
vkCreateComputePipelines(device, pipelineCache, 1, &subpassShadingComputePipelineCreateInfo, NULL, &pipeline);
Version History
-
Revision 2, 2021-06-28 (Hueilong Wang)
-
Change vkGetSubpassShadingMaxWorkgroupSizeHUAWEI to vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI to resolve issue
pub1564
-
-
Revision 1, 2020-12-15 (Hueilong Wang)
-
Initial draft.
-
VK_IMG_filter_cubic
- Name String
-
VK_IMG_filter_cubic - Extension Type
-
Device extension
- Registered Extension Number
-
16
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2016-02-23
- Contributors
-
-
Tobias Hector, Imagination Technologies
-
Description
VK_IMG_filter_cubic adds an additional, high quality cubic filtering mode
to Vulkan, using a Catmull-Rom bicubic filter.
Performing this kind of filtering can be done in a shader by using 16
samples and a number of instructions, but this can be inefficient.
The cubic filter mode exposes an optimized high quality texture sampling
using fixed texture sampling functionality.
New Enum Constants
-
VK_IMG_FILTER_CUBIC_EXTENSION_NAME -
VK_IMG_FILTER_CUBIC_SPEC_VERSION -
Extending VkFilter:
-
VK_FILTER_CUBIC_IMG
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG
-
Example
Creating a sampler with the new filter for both magnification and minification
VkSamplerCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO // sType
// Other members set to application-desired values
};
createInfo.magFilter = VK_FILTER_CUBIC_IMG;
createInfo.minFilter = VK_FILTER_CUBIC_IMG;
VkSampler sampler;
VkResult result = vkCreateSampler(
device,
&createInfo,
&sampler);
VK_IMG_format_pvrtc
- Name String
-
VK_IMG_format_pvrtc - Extension Type
-
Device extension
- Registered Extension Number
-
55
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Stuart Smith
-
Other Extension Metadata
- Last Modified Date
-
2019-09-02
- IP Status
-
Imagination Technologies Proprietary
- Contributors
-
-
Stuart Smith, Imagination Technologies
-
Description
VK_IMG_format_pvrtc provides additional texture compression functionality
specific to Imagination Technologies PowerVR Texture compression format
(called PVRTC).
New Enum Constants
-
VK_IMG_FORMAT_PVRTC_EXTENSION_NAME -
VK_IMG_FORMAT_PVRTC_SPEC_VERSION -
Extending VkFormat:
-
VK_FORMAT_PVRTC1_2BPP_SRGB_BLOCK_IMG -
VK_FORMAT_PVRTC1_2BPP_UNORM_BLOCK_IMG -
VK_FORMAT_PVRTC1_4BPP_SRGB_BLOCK_IMG -
VK_FORMAT_PVRTC1_4BPP_UNORM_BLOCK_IMG -
VK_FORMAT_PVRTC2_2BPP_SRGB_BLOCK_IMG -
VK_FORMAT_PVRTC2_2BPP_UNORM_BLOCK_IMG -
VK_FORMAT_PVRTC2_4BPP_SRGB_BLOCK_IMG -
VK_FORMAT_PVRTC2_4BPP_UNORM_BLOCK_IMG
-
VK_INTEL_performance_query
- Name String
-
VK_INTEL_performance_query - Extension Type
-
Device extension
- Registered Extension Number
-
211
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Use
- Contact
-
-
Lionel Landwerlin llandwerlin
-
Other Extension Metadata
- Last Modified Date
-
2018-05-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Lionel Landwerlin, Intel
-
Piotr Maciejewski, Intel
-
Description
This extension allows an application to capture performance data to be interpreted by a external application or library.
Such a library is available at : https://github.com/intel/metrics-discovery
Performance analysis tools such as Graphics Performance Analyzers make use of this extension and the metrics-discovery library to present the data in a human readable way.
New Enum Constants
-
VK_INTEL_PERFORMANCE_QUERY_EXTENSION_NAME -
VK_INTEL_PERFORMANCE_QUERY_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_PERFORMANCE_CONFIGURATION_INTEL
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL -
VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL -
VK_STRUCTURE_TYPE_PERFORMANCE_MARKER_INFO_INTEL -
VK_STRUCTURE_TYPE_PERFORMANCE_OVERRIDE_INFO_INTEL -
VK_STRUCTURE_TYPE_PERFORMANCE_STREAM_MARKER_INFO_INTEL -
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL -
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_QUERY_CREATE_INFO_INTEL
-
Example Code
// A previously created device
VkDevice device;
// A queue derived from the device
VkQueue queue;
VkInitializePerformanceApiInfoINTEL performanceApiInfoIntel = {
VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL,
NULL,
NULL
};
vkInitializePerformanceApiINTEL(
device,
&performanceApiInfoIntel);
VkQueryPoolPerformanceQueryCreateInfoINTEL queryPoolIntel = {
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL,
NULL,
VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL,
};
VkQueryPoolCreateInfo queryPoolCreateInfo = {
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
&queryPoolIntel,
0,
VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL,
1,
0
};
VkQueryPool queryPool;
VkResult result = vkCreateQueryPool(
device,
&queryPoolCreateInfo,
NULL,
&queryPool);
assert(VK_SUCCESS == result);
// A command buffer we want to record counters on
VkCommandBuffer commandBuffer;
VkCommandBufferBeginInfo commandBufferBeginInfo = {
VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
NULL,
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
NULL
};
result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo);
assert(VK_SUCCESS == result);
vkCmdResetQueryPool(
commandBuffer,
queryPool,
0,
1);
vkCmdBeginQuery(
commandBuffer,
queryPool,
0,
0);
// Perform the commands you want to get performance information on
// ...
// Perform a barrier to ensure all previous commands were complete before
// ending the query
vkCmdPipelineBarrier(commandBuffer,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
0,
0,
NULL,
0,
NULL,
0,
NULL);
vkCmdEndQuery(
commandBuffer,
queryPool,
0);
result = vkEndCommandBuffer(commandBuffer);
assert(VK_SUCCESS == result);
VkPerformanceConfigurationAcquireInfoINTEL performanceConfigurationAcquireInfo = {
VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL,
NULL,
VK_PERFORMANCE_CONFIGURATION_TYPE_COMMAND_QUEUE_METRICS_DISCOVERY_ACTIVATED_INTEL
};
VkPerformanceConfigurationINTEL performanceConfigurationIntel;
result = vkAcquirePerformanceConfigurationINTEL(
device,
&performanceConfigurationAcquireInfo,
&performanceConfigurationIntel);
vkQueueSetPerformanceConfigurationINTEL(queue, performanceConfigurationIntel);
assert(VK_SUCCESS == result);
// Submit the command buffer and wait for its completion
// ...
result = vkReleasePerformanceConfigurationINTEL(
device,
performanceConfigurationIntel);
assert(VK_SUCCESS == result);
// Get the report size from metrics-discovery's QueryReportSize
result = vkGetQueryPoolResults(
device,
queryPool,
0, 1, QueryReportSize,
data, QueryReportSize, 0);
assert(VK_SUCCESS == result);
// The data can then be passed back to metrics-discovery from which
// human readable values can be queried.
Version History
-
Revision 2, 2020-03-06 (Lionel Landwerlin)
-
Rename VkQueryPoolCreateInfoINTEL in VkQueryPoolPerformanceQueryCreateInfoINTEL
-
-
Revision 1, 2018-05-16 (Lionel Landwerlin)
-
Initial revision
-
VK_INTEL_shader_integer_functions2
- Name String
-
VK_INTEL_shader_integer_functions2 - Extension Type
-
Device extension
- Registered Extension Number
-
210
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Ian Romanick ianromanick
-
Other Extension Metadata
- Last Modified Date
-
2019-04-30
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_INTEL_shader_integer_functions2. -
This extension provides API support for
GL_INTEL_shader_integer_functions2.
-
- Contributors
-
-
Ian Romanick, Intel
-
Ben Ashbaugh, Intel
-
Description
This extension adds support for several new integer instructions in SPIR-V for use in graphics shaders. Many of these instructions have pre-existing counterparts in the Kernel environment.
The added integer functions are defined by the
SPV_INTEL_shader_integer_functions2
SPIR-V extension and can be used with the GL_INTEL_shader_integer_functions2
GLSL extension.
New Enum Constants
-
VK_INTEL_SHADER_INTEGER_FUNCTIONS_2_EXTENSION_NAME -
VK_INTEL_SHADER_INTEGER_FUNCTIONS_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_FUNCTIONS_2_FEATURES_INTEL
-
VK_NN_vi_surface
- Name String
-
VK_NN_vi_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
63
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Mathias Heyer mheyer
-
Other Extension Metadata
- Last Modified Date
-
2016-12-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Mathias Heyer, NVIDIA
-
Michael Chock, NVIDIA
-
Yasuhiro Yoshioka, Nintendo
-
Daniel Koch, NVIDIA
-
Description
The VK_NN_vi_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) associated with an
nn::vi::Layer.
New Enum Constants
-
VK_NN_VI_SURFACE_EXTENSION_NAME -
VK_NN_VI_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VI_SURFACE_CREATE_INFO_NN
-
Issues
1) Does VI need a way to query for compatibility between a particular physical device (and queue family?) and a specific VI display?
RESOLVED: No. It is currently always assumed that the device and display will always be compatible.
2) VkViSurfaceCreateInfoNN::pWindow is intended to store an
nn::vi::NativeWindowHandle, but its declared type is a bare
void* to store the window handle.
Why the discrepancy?
RESOLVED: It is for C compatibility.
The definition for the VI native window handle type is defined inside the
nn::vi C++ namespace.
This prevents its use in C source files.
nn::vi::NativeWindowHandle is always defined to be
void*, so this extension uses void* to match.
VK_NV_acquire_winrt_display
- Name String
-
VK_NV_acquire_winrt_display - Extension Type
-
Device extension
- Registered Extension Number
-
346
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_direct_mode_displayto be enabled for any device-level functionality
-
- Contact
-
-
Jeff Juliano jjuliano
-
Other Extension Metadata
- Last Modified Date
-
2020-09-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Juliano, NVIDIA
-
Description
This extension allows an application to take exclusive control of a display on Windows 10 provided that the display is not already controlled by a compositor. Examples of compositors include the Windows desktop compositor, other applications using this Vulkan extension, and applications that “Acquire” a “DisplayTarget” using a “WinRT” command such as “winrt::Windows::Devices::Display::Core::DisplayManager.TryAcquireTarget()”.
When control is acquired the application has exclusive access to the display until control is released or the application terminates. An application’s attempt to acquire is denied if a different application has already acquired the display.
New Enum Constants
-
VK_NV_ACQUIRE_WINRT_DISPLAY_EXTENSION_NAME -
VK_NV_ACQUIRE_WINRT_DISPLAY_SPEC_VERSION
Issues
1) What should the platform substring be for this extension:
RESOLVED: The platform substring is “Winrt”.
The substring “Winrt” matches the fact that the OS API exposing the acquire and release functionality is called “WinRT”.
The substring “Win32” is wrong because the related “WinRT” API is explicitly not a “Win32” API. “WinRT” is a competing API family to the “Win32” API family.
The substring “Windows” is suboptimal because there could be more than one relevant API on the Windows platform. There is preference to use the more-specific substring “Winrt”.
2) Should vkAcquireWinrtDisplayNV take a winRT DisplayTarget, or a Vulkan display handle as input?
RESOLVED: A Vulkan display handle. This matches the design of vkAcquireXlibDisplayEXT.
3) Should the acquire command be platform-independent named “vkAcquireDisplayNV”, or platform-specific named “vkAcquireWinrtDisplayNV”?
RESOLVED: Add a platform-specific command.
The inputs to the Acquire command are all Vulkan types. None are WinRT types. This opens the possibility of the winrt extension defining a platform-independent acquire command.
The X11 acquire command does need to accept a platform-specific parameter.
This could be handled by adding to a platform-independent acquire command a
params struct to which platform-dependent types can be chained by
pNext pointer.
The prevailing opinion is that it would be odd to create a second platform-independent function that is used on the Windows 10 platform, but that is not used for the X11 platform. Since a Windows 10 platform-specific command is needed anyway for converting between vkDisplayKHR and platform-native handles, opinion was to create a platform-specific acquire function.
4) Should the vkGetWinrtDisplayNV parameter identifying a display be named “deviceRelativeId” or “adapterRelativeId”?
RESOLVED: The WinRT name is “AdapterRelativeId”.
The name “adapter” is the Windows analog to a Vulkan “physical device”.
Vulkan already has precedent to use the name deviceLUID for the
concept that Windows APIs call “AdapterLuid”.
Keeping form with this precedent, the name “deviceRelativeId” is chosen.
5) Does vkAcquireWinrtDisplayNV cause the Windows desktop compositor to release a display?
RESOLVED: No. vkAcquireWinrtDisplayNV does not itself cause the Windows desktop compositor to release a display. This action must be performed outside of Vulkan.
Beginning with Windows 10 version 2004 it is possible to cause the Windows desktop compositor to release a display by using the “Advanced display settings” sub-page of the “Display settings” control panel. See https://docs.microsoft.com/en-us/windows-hardware/drivers/display/specialized-monitors
6) Where can one find additional information about custom compositors for Windows 10?
RESOLVED: Relevant references are as follows.
According to Microsoft’s documentation on "building a custom compositor", the ability to write a custom compositor is not a replacement for a fullscreen desktop window. The feature is for writing compositor apps that drive specialized hardware.
Only certain editions of Windows 10 support custom compositors, "documented here". The product type can be queried from Windows 10. See https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getproductinfo
VK_NV_clip_space_w_scaling
- Name String
-
VK_NV_clip_space_w_scaling - Extension Type
-
Device extension
- Registered Extension Number
-
88
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Eric Werness ewerness-nv
-
Other Extension Metadata
- Last Modified Date
-
2017-02-15
- Contributors
-
-
Eric Werness, NVIDIA
-
Kedarnath Thangudu, NVIDIA
-
Description
Virtual Reality (VR) applications often involve a post-processing step to apply a “barrel” distortion to the rendered image to correct the “pincushion” distortion introduced by the optics in a VR device. The barrel distorted image has lower resolution along the edges compared to the center. Since the original image is rendered at high resolution, which is uniform across the complete image, a lot of pixels towards the edges do not make it to the final post-processed image.
This extension provides a mechanism to render VR scenes at a non-uniform resolution, in particular a resolution that falls linearly from the center towards the edges. This is achieved by scaling the w coordinate of the vertices in the clip space before perspective divide. The clip space w coordinate of the vertices can be offset as of a function of x and y coordinates as follows:
w' = w + Ax + By
In the intended use case for viewport position scaling, an application should use a set of four viewports, one for each of the four quadrants of a Cartesian coordinate system. Each viewport is set to the dimension of the image, but is scissored to the quadrant it represents. The application should specify A and B coefficients of the w-scaling equation above, that have the same value, but different signs, for each of the viewports. The signs of A and B should match the signs of x and y for the quadrant that they represent such that the value of w' will always be greater than or equal to the original w value for the entire image. Since the offset to w, (Ax + By), is always positive, and increases with the absolute values of x and y, the effective resolution will fall off linearly from the center of the image to its edges.
New Enum Constants
-
VK_NV_CLIP_SPACE_W_SCALING_EXTENSION_NAME -
VK_NV_CLIP_SPACE_W_SCALING_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_W_SCALING_STATE_CREATE_INFO_NV
-
Issues
1) Is the pipeline struct name too long?
RESOLVED: It fits with the naming convention.
2) Separate W scaling section or fold into coordinate transformations?
RESOLVED: Leaving it as its own section for now.
Examples
VkViewport viewports[4];
VkRect2D scissors[4];
VkViewportWScalingNV scalings[4];
for (int i = 0; i < 4; i++) {
int x = (i & 2) ? 0 : currentWindowWidth / 2;
int y = (i & 1) ? 0 : currentWindowHeight / 2;
viewports[i].x = 0;
viewports[i].y = 0;
viewports[i].width = currentWindowWidth;
viewports[i].height = currentWindowHeight;
viewports[i].minDepth = 0.0f;
viewports[i].maxDepth = 1.0f;
scissors[i].offset.x = x;
scissors[i].offset.y = y;
scissors[i].extent.width = currentWindowWidth/2;
scissors[i].extent.height = currentWindowHeight/2;
const float factor = 0.15;
scalings[i].xcoeff = ((i & 2) ? -1.0 : 1.0) * factor;
scalings[i].ycoeff = ((i & 1) ? -1.0 : 1.0) * factor;
}
VkPipelineViewportWScalingStateCreateInfoNV vpWScalingStateInfo = { VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_W_SCALING_STATE_CREATE_INFO_NV };
vpWScalingStateInfo.viewportWScalingEnable = VK_TRUE;
vpWScalingStateInfo.viewportCount = 4;
vpWScalingStateInfo.pViewportWScalings = &scalings[0];
VkPipelineViewportStateCreateInfo vpStateInfo = { VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO };
vpStateInfo.viewportCount = 4;
vpStateInfo.pViewports = &viewports[0];
vpStateInfo.scissorCount = 4;
vpStateInfo.pScissors = &scissors[0];
vpStateInfo.pNext = &vpWScalingStateInfo;
Example shader to read from a w-scaled texture:
// Vertex Shader
// Draw a triangle that covers the whole screen
const vec4 positions[3] = vec4[3](vec4(-1, -1, 0, 1),
vec4( 3, -1, 0, 1),
vec4(-1, 3, 0, 1));
out vec2 uv;
void main()
{
vec4 pos = positions[ gl_VertexID ];
gl_Position = pos;
uv = pos.xy;
}
// Fragment Shader
uniform sampler2D tex;
uniform float xcoeff;
uniform float ycoeff;
out vec4 Color;
in vec2 uv;
void main()
{
// Handle uv as if upper right quadrant
vec2 uvabs = abs(uv);
// unscale: transform w-scaled image into an unscaled image
// scale: transform unscaled image int a w-scaled image
float unscale = 1.0 / (1 + xcoeff * uvabs.x + xcoeff * uvabs.y);
//float scale = 1.0 / (1 - xcoeff * uvabs.x - xcoeff * uvabs.y);
vec2 P = vec2(unscale * uvabs.x, unscale * uvabs.y);
// Go back to the right quadrant
P *= sign(uv);
Color = texture(tex, P * 0.5 + 0.5);
}
VK_NV_compute_shader_derivatives
- Name String
-
VK_NV_compute_shader_derivatives - Extension Type
-
Device extension
- Registered Extension Number
-
202
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Pat Brown nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2018-07-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_compute_shader_derivatives -
This extension provides API support for
GL_NV_compute_shader_derivatives
-
- Contributors
-
-
Pat Brown, NVIDIA
-
Description
This extension adds Vulkan support for the
SPV_NV_compute_shader_derivatives
SPIR-V extension.
The SPIR-V extension provides two new execution modes, both of which allow
compute shaders to use built-ins that evaluate compute derivatives
explicitly or implicitly.
Derivatives will be computed via differencing over a 2x2 group of shader
invocations.
The DerivativeGroupQuadsNV execution mode assembles shader invocations
into 2x2 groups, where each group has x and y coordinates of the local
invocation ID of the form (2m+{0,1}, 2n+{0,1}).
The DerivativeGroupLinearNV execution mode assembles shader invocations
into 2x2 groups, where each group has local invocation index values of the
form 4m+{0,1,2,3}.
New Enum Constants
-
VK_NV_COMPUTE_SHADER_DERIVATIVES_EXTENSION_NAME -
VK_NV_COMPUTE_SHADER_DERIVATIVES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_NV
-
Issues
(1) Should we specify that the groups of four shader invocations used for derivatives in a compute shader are the same groups of four invocations that form a “quad” in shader subgroups?
RESOLVED: Yes.
VK_NV_cooperative_matrix
- Name String
-
VK_NV_cooperative_matrix - Extension Type
-
Device extension
- Registered Extension Number
-
250
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-02-05
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_cooperative_matrix -
This extension provides API support for
GL_NV_cooperative_matrix
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Markus Tavenrath, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
This extension adds support for using cooperative matrix types in SPIR-V. Cooperative matrix types are medium-sized matrices that are primarily supported in compute shaders, where the storage for the matrix is spread across all invocations in some scope (usually a subgroup) and those invocations cooperate to efficiently perform matrix multiplies.
Cooperative matrix types are defined by the
SPV_NV_cooperative_matrix
SPIR-V extension and can be used with the
GL_NV_cooperative_matrix
GLSL extension.
This extension includes support for enumerating the matrix types and dimensions that are supported by the implementation.
New Enum Constants
-
VK_NV_COOPERATIVE_MATRIX_EXTENSION_NAME -
VK_NV_COOPERATIVE_MATRIX_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_PROPERTIES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_PROPERTIES_NV
-
Issues
(1) What matrix properties will be supported in practice?
RESOLVED: In NVIDIA’s initial implementation, we will support:
-
AType = BType = fp16 CType = DType = fp16 MxNxK = 16x8x16 scope = Subgroup
-
AType = BType = fp16 CType = DType = fp16 MxNxK = 16x8x8 scope = Subgroup
-
AType = BType = fp16 CType = DType = fp32 MxNxK = 16x8x16 scope = Subgroup
-
AType = BType = fp16 CType = DType = fp32 MxNxK = 16x8x8 scope = Subgroup
VK_NV_corner_sampled_image
- Name String
-
VK_NV_corner_sampled_image - Extension Type
-
Device extension
- Registered Extension Number
-
51
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2018-08-13
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Pat Brown, NVIDIA
-
Chris Lentini, NVIDIA
-
Description
This extension adds support for a new image organization, which this extension refers to as “corner-sampled” images. A corner-sampled image differs from a conventional image in the following ways:
-
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 Miplevel Sizing.
-
The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. See Image Miplevel Sizing.
This image organization is designed to facilitate a system like Ptex with separate textures for each face of a subdivision or polygon mesh. Placing sample locations at pixel corners allows applications to maintain continuity between adjacent patches by duplicating values along shared edges. Additionally, using the modified mipmapping logic along with texture dimensions of the form 2n+1 allows continuity across shared edges even if the adjacent patches use different level-of-detail values.
New Enum Constants
-
VK_NV_CORNER_SAMPLED_IMAGE_EXTENSION_NAME -
VK_NV_CORNER_SAMPLED_IMAGE_SPEC_VERSION -
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CORNER_SAMPLED_IMAGE_FEATURES_NV
-
Issues
-
What should this extension be named?
DISCUSSION: While naming this extension, we chose the most distinctive aspect of the image organization and referred to such images as “corner-sampled images”. As a result, we decided to name the extension NV_corner_sampled_image.
-
Do we need a format feature flag so formats can advertise if they support corner-sampling?
DISCUSSION: Currently NVIDIA supports this for all 2D and 3D formats, but not for cube maps or depth-stencil formats. A format feature might be useful if other vendors would only support this on some formats.
-
Do integer texel coordinates have a different range for corner-sampled images?
RESOLVED: No, these are unchanged.
-
Do unnormalized sampler coordinates work with corner-sampled images? Are there any functional differences?
RESOLVED: Yes. Unnormalized coordinates are treated as already scaled for corner-sample usage.
-
Should we have a diagram in the “Image Operations” chapter demonstrating different texel sampling locations?
UNRESOLVED: Probaby, but later.
Version History
-
Revision 1, 2018-08-14 (Daniel Koch)
-
Internal revisions
-
-
Revision 2, 2018-08-14 (Daniel Koch)
-
???
-
VK_NV_coverage_reduction_mode
- Name String
-
VK_NV_coverage_reduction_mode - Extension Type
-
Device extension
- Registered Extension Number
-
251
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_NV_framebuffer_mixed_samplesto be enabled for any device-level functionality
-
- Contact
-
-
Kedarnath Thangudu kthangudu
-
Other Extension Metadata
- Last Modified Date
-
2019-01-29
- Contributors
-
-
Kedarnath Thangudu, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
When using a framebuffer with mixed samples, a per-fragment coverage reduction operation is performed which generates color sample coverage from the pixel coverage. This extension defines the following modes to control how this reduction is performed.
-
Merge: When there are more samples in the pixel coverage than color samples, there is an implementation-dependent association of each pixel coverage sample to a color sample. In the merge mode, the color sample coverage is computed such that only if any associated sample in the pixel coverage is covered, the color sample is covered. This is the default mode.
-
Truncate: When there are more raster samples (N) than color samples(M), there is one to one association of the first M raster samples to the M color samples; other raster samples are ignored.
When the number of raster samples is equal to the color samples, there is a one to one mapping between them in either of the above modes.
The new command
vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV can
be used to query the various raster, color, depth/stencil sample count and
reduction mode combinations that are supported by the implementation.
This extension would allow an implementation to support the behavior of both
VK_NV_framebuffer_mixed_samples and VK_AMD_mixed_attachment_samples
extensions simultaneously.
New Enum Constants
-
VK_NV_COVERAGE_REDUCTION_MODE_EXTENSION_NAME -
VK_NV_COVERAGE_REDUCTION_MODE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FRAMEBUFFER_MIXED_SAMPLES_COMBINATION_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COVERAGE_REDUCTION_MODE_FEATURES_NV -
VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_REDUCTION_STATE_CREATE_INFO_NV
-
VK_NV_dedicated_allocation_image_aliasing
- Name String
-
VK_NV_dedicated_allocation_image_aliasing - Extension Type
-
Device extension
- Registered Extension Number
-
241
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_dedicated_allocationto be enabled for any device-level functionality
-
- Contact
-
-
Nuno Subtil nsubtil
-
Other Extension Metadata
- Last Modified Date
-
2019-01-04
- Contributors
-
-
Nuno Subtil, NVIDIA
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Axel Gneiting, id Software
-
Description
This extension allows applications to alias images on dedicated allocations, subject to specific restrictions: the extent and the number of layers in the image being aliased must be smaller than or equal to those of the original image for which the allocation was created, and every other image parameter must match.
New Enum Constants
-
VK_NV_DEDICATED_ALLOCATION_IMAGE_ALIASING_EXTENSION_NAME -
VK_NV_DEDICATED_ALLOCATION_IMAGE_ALIASING_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEDICATED_ALLOCATION_IMAGE_ALIASING_FEATURES_NV
-
VK_NV_device_diagnostic_checkpoints
- Name String
-
VK_NV_device_diagnostic_checkpoints - Extension Type
-
Device extension
- Registered Extension Number
-
207
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Nuno Subtil nsubtil
-
Other Extension Metadata
- Last Modified Date
-
2018-07-16
- Contributors
-
-
Oleg Kuznetsov, NVIDIA
-
Alex Dunn, NVIDIA
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
This extension allows applications to insert markers in the command stream and associate them with custom data.
If a device lost error occurs, the application may then query the implementation for the last markers to cross specific implementation-defined pipeline stages, in order to narrow down which commands were executing at the time and might have caused the failure.
New Enum Constants
-
VK_NV_DEVICE_DIAGNOSTIC_CHECKPOINTS_EXTENSION_NAME -
VK_NV_DEVICE_DIAGNOSTIC_CHECKPOINTS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CHECKPOINT_DATA_NV -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_NV
-
Version History
-
Revision 1, 2018-07-16 (Nuno Subtil)
-
Internal revisions
-
-
Revision 2, 2018-07-16 (Nuno Subtil)
-
???
-
VK_NV_device_diagnostics_config
- Name String
-
VK_NV_device_diagnostics_config - Extension Type
-
Device extension
- Registered Extension Number
-
301
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Kedarnath Thangudu kthangudu
-
Other Extension Metadata
- Last Modified Date
-
2022-04-06
- Contributors
-
-
Kedarnath Thangudu, NVIDIA
-
Thomas Klein, NVIDIA
-
Description
Applications using Nvidia Nsight™ Aftermath SDK for Vulkan to integrate device crash dumps into their error reporting mechanisms, may use this extension to configure options related to device crash dump creation.
Version 2 of this extension adds
VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_ERROR_REPORTING_BIT_NV
which when set enables enhanced reporting of shader execution errors.
New Enum Constants
-
VK_NV_DEVICE_DIAGNOSTICS_CONFIG_EXTENSION_NAME -
VK_NV_DEVICE_DIAGNOSTICS_CONFIG_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_DIAGNOSTICS_CONFIG_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DIAGNOSTICS_CONFIG_FEATURES_NV
-
Version History
-
Revision 1, 2019-11-21 (Kedarnath Thangudu)
-
Internal revisions
-
-
Revision 2, 2022-04-06 (Kedarnath Thangudu)
-
Added a config bit
VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_ERROR_REPORTING_BIT_NV
-
VK_NV_device_generated_commands
- Name String
-
VK_NV_device_generated_commands - Extension Type
-
Device extension
- Registered Extension Number
-
278
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
Requires
VK_KHR_buffer_device_addressto be enabled for any device-level functionality
-
- Contact
-
-
Christoph Kubisch pixeljetstream
-
Other Extension Metadata
- Last Modified Date
-
2020-02-20
- Interactions and External Dependencies
-
-
This extension requires Vulkan 1.1
-
This extension requires
VK_EXT_buffer_device_addressorVK_KHR_buffer_device_addressor Vulkan 1.2 for the ability to bind vertex and index buffers on the device. -
This extension interacts with
VK_NV_mesh_shader. If the latter extension is not supported, remove the command token to initiate mesh tasks drawing in this extension.
-
- Contributors
-
-
Christoph Kubisch, NVIDIA
-
Pierre Boudier, NVIDIA
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Yuriy O’Donnell, Epic Games
-
Baldur Karlsson, Valve
-
Mathias Schott, NVIDIA
-
Tyson Smith, NVIDIA
-
Ingo Esser, NVIDIA
-
Description
This extension allows the device to generate a number of critical graphics commands for command buffers.
When rendering a large number of objects, the device can be leveraged to implement a number of critical functions, like updating matrices, or implementing occlusion culling, frustum culling, front to back sorting, etc. Implementing those on the device does not require any special extension, since an application is free to define its own data structures, and just process them using shaders.
However, if the application desires to quickly kick off the rendering of the final stream of objects, then unextended Vulkan forces the application to read back the processed stream and issue graphics command from the host. For very large scenes, the synchronization overhead and cost to generate the command buffer can become the bottleneck. This extension allows an application to generate a device side stream of state changes and commands, and convert it efficiently into a command buffer without having to read it back to the host.
Furthermore, it allows incremental changes to such command buffers by manipulating only partial sections of a command stream — for example pipeline bindings. Unextended Vulkan requires re-creation of entire command buffers in such a scenario, or updates synchronized on the host.
The intended usage for this extension is for the application to:
-
create
VkBufferobjects and retrieve physical addresses from them via vkGetBufferDeviceAddressEXT -
create a graphics pipeline using
VkGraphicsPipelineShaderGroupsCreateInfoNVfor the ability to change shaders on the device. -
create a VkIndirectCommandsLayoutNV, which lists the VkIndirectCommandsTokenTypeNV it wants to dynamically execute as an atomic command sequence. This step likely involves some internal device code compilation, since the intent is for the GPU to generate the command buffer in the pipeline.
-
fill the input stream buffers with the data for each of the inputs it needs. Each input is an array that will be filled with token-dependent data.
-
set up a preprocess
VkBufferthat uses memory according to the information retrieved via vkGetGeneratedCommandsMemoryRequirementsNV. -
optionally preprocess the generated content using vkCmdPreprocessGeneratedCommandsNV, for example on an asynchronous compute queue, or for the purpose of re-using the data in multiple executions.
-
call vkCmdExecuteGeneratedCommandsNV to create and execute the actual device commands for all sequences based on the inputs provided.
For each draw in a sequence, the following can be specified:
-
a different shader group
-
a number of vertex buffer bindings
-
a different index buffer, with an optional dynamic offset and index type
-
a number of different push constants
-
a flag that encodes the primitive winding
While the GPU can be faster than a CPU to generate the commands, it will not happen asynchronously to the device, therefore the primary use-case is generating “less” total work (occlusion culling, classification to use specialized shaders, etc.).
New Structures
-
Extending VkGraphicsPipelineCreateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
New Enum Constants
-
VK_NV_DEVICE_GENERATED_COMMANDS_EXTENSION_NAME -
VK_NV_DEVICE_GENERATED_COMMANDS_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV -
VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NV
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NV
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_INFO_NV -
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_MEMORY_REQUIREMENTS_INFO_NV -
VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_SHADER_GROUPS_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_GRAPHICS_SHADER_GROUP_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_TOKEN_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_PROPERTIES_NV
-
Issues
1) How to name this extension ?
VK_NV_device_generated_commands
As usual, one of the hardest issues ;)
Alternatives: VK_gpu_commands, VK_execute_commands,
VK_device_commands, VK_device_execute_commands, VK_device_execute,
VK_device_created_commands, VK_device_recorded_commands,
VK_device_generated_commands VK_indirect_generated_commands
2) Should we use a serial stateful token stream or stateless sequence descriptions?
Similarly to VkPipeline, fixed layouts have the most likelihood to be
cross-vendor adoptable.
They also benefit from being processable in parallel.
This is a different design choice compared to the serial command stream
generated through GL_NV_command_list.
3) How to name a sequence description?
VkIndirectCommandsLayout as in the NVX extension predecessor.
Alternative: VkGeneratedCommandsLayout
4) Do we want to provide indirectCommands inputs with layout or at
indirectCommands time?
Separate layout from data as Vulkan does.
Provide full flexibility for indirectCommands.
5) Should the input be provided as SoA or AoS?
Both ways are desireable. AoS can provide portability to other APIs and easier to setup, while SoA allows to update individual inputs in a cache-efficient manner, when others remain static.
6) How do we make developers aware of the memory requirements of implementation-dependent data used for the generated commands?
Make the API explicit and introduce a preprocess VkBuffer.
Developers have to allocate it using
vkGetGeneratedCommandsMemoryRequirementsNV.
In the NVX version the requirements were hidden implicitly as part of the
command buffer reservation process, however as the memory requirements can
be substantial, we want to give developers the ability to budget the memory
themselves.
By lowering the maxSequencesCount the memory consumption can be reduced.
Furthermore reuse of the memory is possible, for example for doing explicit
preprocessing and execution in a ping-pong fashion.
The actual buffer size is implementation-dependent and may be zero, i.e. not always required.
When making use of Graphics Shader Groups, the programs should behave similar with regards to vertex inputs, clipping and culling outputs of the geometry stage, as well as sample shading behavior in fragment shaders, to reduce the amount of the worst-case memory approximation.
7) Should we allow additional per-sequence dynamic state changes?
Yes
Introduced a lightweight indirect state flag VkIndirectStateFlagBitsNV. So far only switching front face winding state is exposed. Especially in CAD/DCC mirrored transforms that require such changes are common, and similar flexibility is given in the ray tracing instance description.
The flag could be extended further, for example to switch between primitive-lists or -strips, or make other state modifications.
Furthermore, as new tokens can be added easily, future extension could add the ability to change any VkDynamicState.
8) How do we allow re-using already “generated” indirectCommands?
Expose a preprocessBuffer to reuse implementation-dependencyFlags data.
Set the isPreprocessed to true in vkCmdExecuteGeneratedCommandsNV.
9) Under which conditions is vkCmdExecuteGeneratedCommandsNV legal?
It behaves like a regular draw call command.
10) Is vkCmdPreprocessGeneratedCommandsNV copying the input data or referencing it?
There are multiple implementations possible:
-
one could have some emulation code that parses the inputs, and generates an output command buffer, therefore copying the inputs.
-
one could just reference the inputs, and have the processing done in pipe at execution time.
If the data is mandated to be copied, then it puts a penalty on implementation that could process the inputs directly in pipe. If the data is “referenced”, then it allows both types of implementation.
The inputs are “referenced”, and must not be modified after the call to vkCmdExecuteGeneratedCommandsNV has completed.
11) Which buffer usage flags are required for the buffers referenced by
VkGeneratedCommandsInfoNV ?
Reuse existing VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT
-
VkGeneratedCommandsInfoNV::
preprocessBuffer -
VkGeneratedCommandsInfoNV::
sequencesCountBuffer -
VkGeneratedCommandsInfoNV::
sequencesIndexBuffer -
VkIndirectCommandsStreamNV::
buffer
12) In which pipeline stage does the device generated command expansion happen?
vkCmdPreprocessGeneratedCommandsNV is treated as if it occurs in a
separate logical pipeline from either graphics or compute, and that pipeline
only includes VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT, a new stage
VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV, and
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT.
This new stage has two corresponding new access types,
VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV and
VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NV, used to synchronize reading
the buffer inputs and writing the preprocess memory output.
The generated output written in the preprocess buffer memory by
vkCmdExecuteGeneratedCommandsNV is considered to be consumed by the
VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT pipeline stage.
Thus, to synchronize from writing the input buffers to preprocessing via vkCmdPreprocessGeneratedCommandsNV, use:
-
dstStageMask=VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV -
dstAccessMask=VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV
To synchronize from vkCmdPreprocessGeneratedCommandsNV to executing the generated commands by vkCmdExecuteGeneratedCommandsNV, use:
-
srcStageMask=VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV -
srcAccessMask=VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NV -
dstStageMask=VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT -
dstAccessMask=VK_ACCESS_INDIRECT_COMMAND_READ_BIT
When vkCmdExecuteGeneratedCommandsNV is used with a
isPreprocessed of VK_FALSE, the generated commands are implicitly
preprocessed, therefore one only needs to synchronize the inputs via:
-
dstStageMask=VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT -
dstAccessMask=VK_ACCESS_INDIRECT_COMMAND_READ_BIT
13) What if most token data is “static”, but we frequently want to render a subsection?
Added “sequencesIndexBuffer”. This allows to easier sort and filter what should actually be executed.
14) What are the changes compared to the previous NVX extension?
-
Compute dispatch support was removed (was never implemented in drivers). There are different approaches how dispatching from the device should work, hence we defer this to a future extension.
-
The
ObjectTableNVXwas replaced by using physical buffer addresses and introducing Shader Groups for the graphics pipeline. -
Less state changes are possible overall, but the important operations are still there (reduces complexity of implementation).
-
The API was redesigned so all inputs must be passed at both preprocessing and execution time (this was implicit in NVX, now it is explicit)
-
The reservation of intermediate command space is now mandatory and explicit through a preprocess buffer.
-
The VkIndirectStateFlagBitsNV were introduced
15) When porting from other APIs, their indirect buffers may use different enums, for example for index buffer types. How to solve this?
Added “pIndexTypeValues” to map custom uint32_t values to corresponding
VkIndexType.
16) Do we need more shader group state overrides?
The NVX version allowed all PSO states to be different, however as the goal is not to replace all state setup, but focus on highly-frequent state changes for drawing lots of objects, we reduced the amount of state overrides. Especially VkPipelineLayout as well as VkRenderPass configuration should be left static, the rest is still open for discussion.
The current focus is just to allow VertexInput changes as well as shaders, while all shader groups use the same shader stages.
Too much flexibility will increase the test coverage requirement as well. However, further extensions could allow more dynamic state as well.
17) Do we need more detailed physical device feature queries/enables?
An EXT version would need detailed implementor feedback to come up with a good set of features. Please contact us if you are interested, we are happy to make more features optional, or add further restrictions to reduce the minimum feature set of an EXT.
18) Is there an interaction with VK_KHR_pipeline_library planned?
Yes, a future version of this extension will detail the interaction, once VK_KHR_pipeline_library is no longer provisional.
Example Code
Open-Source samples illustrating the usage of the extension can be found at the following location (may not yet exist at time of writing):
Version History
-
Revision 1, 2020-02-20 (Christoph Kubisch)
-
Initial version
-
-
Revision 2, 2020-03-09 (Christoph Kubisch)
-
Remove VK_EXT_debug_report interactions
-
-
Revision 3, 2020-03-09 (Christoph Kubisch)
-
Fix naming VkPhysicalDeviceGenerated to VkPhysicalDeviceDeviceGenerated
-
VK_NV_external_memory_rdma
- Name String
-
VK_NV_external_memory_rdma - Extension Type
-
Device extension
- Registered Extension Number
-
372
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_memoryto be enabled for any device-level functionality
-
- Contact
-
-
Carsten Rohde crohde
-
Other Extension Metadata
- Last Modified Date
-
2021-04-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Carsten Rohde, NVIDIA
-
Description
This extension adds support for allocating memory which can be used for remote direct memory access (RDMA) from other devices.
New Enum Constants
-
VK_NV_EXTERNAL_MEMORY_RDMA_EXTENSION_NAME -
VK_NV_EXTERNAL_MEMORY_RDMA_SPEC_VERSION -
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV
-
-
Extending VkMemoryPropertyFlagBits:
-
VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MEMORY_GET_REMOTE_ADDRESS_INFO_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_RDMA_FEATURES_NV
-
Examples
VkPhysicalDeviceMemoryBudgetPropertiesEXT memoryBudgetProperties = { VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_BUDGET_PROPERTIES_EXT };
VkPhysicalDeviceMemoryProperties2 memoryProperties2 = { VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2, &memoryBudgetProperties };
vkGetPhysicalDeviceMemoryProperties2(physicalDevice, &memoryProperties2);
uint32_t heapIndex = (uint32_t)-1;
for (uint32_t memoryType = 0; memoryType < memoryProperties2.memoryProperties.memoryTypeCount; memoryType++) {
if (memoryProperties2.memoryProperties.memoryTypes[memoryType].propertyFlags & VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV) {
heapIndex = memoryProperties2.memoryProperties.memoryTypes[memoryType].heapIndex;
break;
}
}
if ((heapIndex == (uint32_t)-1) ||
(memoryBudgetProperties.heapBudget[heapIndex] < size)) {
return;
}
VkPhysicalDeviceExternalBufferInfo externalBufferInfo = { VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO };
externalBufferInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
externalBufferInfo.handleType = VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV;
VkExternalBufferProperties externalBufferProperties = { VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES };
vkGetPhysicalDeviceExternalBufferProperties(physicalDevice, &externalBufferInfo, &externalBufferProperties);
if (!(externalBufferProperties.externalMemoryProperties.externalMemoryFeatures & VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT)) {
return;
}
VkExternalMemoryBufferCreateInfo externalMemoryBufferCreateInfo = { VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO };
externalMemoryBufferCreateInfo.handleTypes = VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV;
VkBufferCreateInfo bufferCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO, &externalMemoryBufferCreateInfo };
bufferCreateInfo.size = size;
bufferCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
VkMemoryRequirements mem_reqs;
vkCreateBuffer(device, &bufferCreateInfo, NULL, &buffer);
vkGetBufferMemoryRequirements(device, buffer, &mem_reqs);
VkExportMemoryAllocateInfo exportMemoryAllocateInfo = { VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO };
exportMemoryAllocateInfo.handleTypes = VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV;
// Find memory type index
uint32_t i = 0;
for (; i < VK_MAX_MEMORY_TYPES; i++) {
if ((mem_reqs.memoryTypeBits & (1 << i)) &&
(memoryProperties.memoryTypes[i].propertyFlags & VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV)) {
break;
}
}
VkMemoryAllocateInfo memAllocInfo = { VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO, &exportMemoryAllocateInfo };
memAllocInfo.allocationSize = mem_reqs.size;
memAllocInfo.memoryTypeIndex = i;
vkAllocateMemory(device, &memAllocInfo, NULL, &mem);
vkBindBufferMemory(device, buffer, mem, 0);
VkMemoryGetRemoteAddressInfoNV getMemoryRemoteAddressInfo = { VK_STRUCTURE_TYPE_MEMORY_GET_REMOTE_ADDRESS_INFO_NV };
getMemoryRemoteAddressInfo.memory = mem;
getMemoryRemoteAddressInfo.handleType = VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV;
VkRemoteAddressNV rdmaAddress;
vkGetMemoryRemoteAddressNV(device, &getMemoryRemoteAddressInfo, &rdmaAddress);
// address returned in 'rdmaAddress' can be used by external devices to initiate RDMA transfers
VK_NV_fill_rectangle
- Name String
-
VK_NV_fill_rectangle - Extension Type
-
Device extension
- Registered Extension Number
-
154
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Description
This extension adds a new VkPolygonMode enum where a triangle is
rasterized by computing and filling its axis-aligned screen-space bounding
box, disregarding the actual triangle edges.
This can be useful for drawing a rectangle without being split into two
triangles with an internal edge.
It is also useful to minimize the number of primitives that need to be
drawn, particularly for a user interface.
New Enum Constants
-
VK_NV_FILL_RECTANGLE_EXTENSION_NAME -
VK_NV_FILL_RECTANGLE_SPEC_VERSION -
Extending VkPolygonMode:
-
VK_POLYGON_MODE_FILL_RECTANGLE_NV
-
VK_NV_fragment_coverage_to_color
- Name String
-
VK_NV_fragment_coverage_to_color - Extension Type
-
Device extension
- Registered Extension Number
-
150
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Description
This extension allows the fragment coverage value, represented as an integer
bitmask, to be substituted for a color output being written to a
single-component color attachment with integer components (e.g.
VK_FORMAT_R8_UINT).
The functionality provided by this extension is different from simply
writing the SampleMask fragment shader output, in that the coverage
value written to the framebuffer is taken after stencil test and depth test,
as well as after fragment operations such as alpha-to-coverage.
This functionality may be useful for deferred rendering algorithms, where the second pass needs to know which samples belong to which original fragments.
New Enum Constants
-
VK_NV_FRAGMENT_COVERAGE_TO_COLOR_EXTENSION_NAME -
VK_NV_FRAGMENT_COVERAGE_TO_COLOR_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_TO_COLOR_STATE_CREATE_INFO_NV
-
VK_NV_fragment_shading_rate_enums
- Name String
-
VK_NV_fragment_shading_rate_enums - Extension Type
-
Device extension
- Registered Extension Number
-
327
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_fragment_shading_rateto be enabled for any device-level functionality
-
- Contact
-
-
Pat Brown nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2020-09-02
- Contributors
-
-
Pat Brown, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension builds on the fragment shading rate functionality provided by the VK_KHR_fragment_shading_rate extension, adding support for “supersample” fragment shading rates that trigger multiple fragment shader invocations per pixel as well as a “no invocations” shading rate that discards any portions of a primitive that would use that shading rate.
New Enum Constants
-
VK_NV_FRAGMENT_SHADING_RATE_ENUMS_EXTENSION_NAME -
VK_NV_FRAGMENT_SHADING_RATE_ENUMS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_ENUMS_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_ENUMS_PROPERTIES_NV -
VK_STRUCTURE_TYPE_PIPELINE_FRAGMENT_SHADING_RATE_ENUM_STATE_CREATE_INFO_NV
-
Issues
-
Why was this extension created? How should it be named?
RESOLVED: The primary goal of this extension was to expose support for supersample and “no invocations” shading rates, which are supported by the VK_NV_shading_rate_image extension but not by VK_KHR_fragment_shading_rate. Because VK_KHR_fragment_shading_rate specifies the primitive shading rate using a fragment size in pixels, it lacks a good way to specify supersample rates. To deal with this, we defined enums covering shading rates supported by the KHR extension as well as the new shading rates and added structures and APIs accepting shading rate enums instead of fragment sizes.
Since this extension adds two different types of shading rates, both expressed using enums, we chose the extension name VK_NV_fragment_shading_rate_enums.
-
Is this a standalone extension?
RESOLVED: No, this extension requires VK_KHR_fragment_shading_rate. In order to use the features of this extension, applications must enable the relevant features of KHR extension.
-
How are the shading rate enums used, and how were the enum values assigned?
RESOLVED: The shading rates supported by the enums in this extension are accepted as pipeline, primitive, and attachment shading rates and behave identically. For the shading rates also supported by the KHR extension, the values assigned to the corresponding enums are identical to the values already used for the primitive and attachment shading rates in the KHR extension. For those enums, bits 0 and 1 specify the base two logarithm of the fragment height and bits 2 and 3 specify the base two logarithm of the fragment width. For the new shading rates added by this extension, we chose to use 11 through 14 (10 plus the base two logarithm of the invocation count) for the supersample rates and 15 for the “no invocations” rate. None of those values are supported as primitive or attachment shading rates by the KHR extension.
-
Between this extension, VK_KHR_fragment_shading_rate, and VK_NV_shading_rate_image, there are three different ways to specify shading rate state in a pipeline. How should we handle this?
RESOLVED: We do not allow the concurrent use of VK_NV_shading_rate_image and VK_KHR_fragment_shading_rate; it is an error to enable shading rate features from both extensions. But we do allow applications to enable this extension together with VK_KHR_fragment_shading_rate together. While we expect that applications will never attach pipeline CreateInfo structures for both this extension and the KHR extension concurrently, Vulkan does not have any precedent forbidding such behavior and instead typically treats a pipeline created without an extension-specific CreateInfo structure as equivalent to one containing default values specified by the extension. Rather than adding such a rule considering the presence or absence of our new CreateInfo structure, we instead included a
shadingRateTypemember to VkPipelineFragmentShadingRateEnumStateCreateInfoNV that selects between using state specified by that structure and state specified by VkPipelineFragmentShadingRateStateCreateInfoKHR.
VK_NV_framebuffer_mixed_samples
- Name String
-
VK_NV_framebuffer_mixed_samples - Extension Type
-
Device extension
- Registered Extension Number
-
153
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Description
This extension allows multisample rendering with a raster and depth/stencil sample count that is larger than the color sample count. Rasterization and the results of the depth and stencil tests together determine the portion of a pixel that is “covered”. It can be useful to evaluate coverage at a higher frequency than color samples are stored. This coverage is then “reduced” to a collection of covered color samples, each having an opacity value corresponding to the fraction of the color sample covered. The opacity can optionally be blended into individual color samples.
Rendering with fewer color samples than depth/stencil samples greatly reduces the amount of memory and bandwidth consumed by the color buffer. However, converting the coverage values into opacity introduces artifacts where triangles share edges and may not be suitable for normal triangle mesh rendering.
One expected use case for this functionality is Stencil-then-Cover path rendering (similar to the OpenGL GL_NV_path_rendering extension). The stencil step determines the coverage (in the stencil buffer) for an entire path at the higher sample frequency, and then the cover step draws the path into the lower frequency color buffer using the coverage information to antialias path edges. With this two-step process, internal edges are fully covered when antialiasing is applied and there is no corruption on these edges.
The key features of this extension are:
-
It allows render pass and framebuffer objects to be created where the number of samples in the depth/stencil attachment in a subpass is a multiple of the number of samples in the color attachments in the subpass.
-
A coverage reduction step is added to Fragment Operations which converts a set of covered raster/depth/stencil samples to a set of color samples that perform blending and color writes. The coverage reduction step also includes an optional coverage modulation step, multiplying color values by a fractional opacity corresponding to the number of associated raster/depth/stencil samples covered.
New Enum Constants
-
VK_NV_FRAMEBUFFER_MIXED_SAMPLES_EXTENSION_NAME -
VK_NV_FRAMEBUFFER_MIXED_SAMPLES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_MODULATION_STATE_CREATE_INFO_NV
-
VK_NV_geometry_shader_passthrough
- Name String
-
VK_NV_geometry_shader_passthrough - Extension Type
-
Device extension
- Registered Extension Number
-
96
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-02-15
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_geometry_shader_passthrough -
This extension provides API support for
GL_NV_geometry_shader_passthrough -
This extension requires the
geometryShaderfeature.
-
- Contributors
-
-
Piers Daniell, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_geometry_shader_passthrough
Geometry shaders provide the ability for applications to process each
primitive sent through the graphics pipeline using a programmable shader.
However, one common use case treats them largely as a “passthrough”.
In this use case, the bulk of the geometry shader code simply copies inputs
from each vertex of the input primitive to corresponding outputs in the
vertices of the output primitive.
Such shaders might also compute values for additional built-in or
user-defined per-primitive attributes (e.g., Layer) to be assigned to
all the vertices of the output primitive.
This extension provides access to the PassthroughNV decoration under
the GeometryShaderPassthroughNV capability.
Adding this to a geometry shader input variable specifies that the values of
this input are copied to the corresponding vertex of the output primitive.
When using GLSL source-based shading languages, the passthrough layout
qualifier from GL_NV_geometry_shader_passthrough maps to the
PassthroughNV decoration.
To use the passthrough layout, in GLSL the
GL_NV_geometry_shader_passthrough extension must be enabled.
Behaviour is described in the GL_NV_geometry_shader_passthrough extension
specification.
New Enum Constants
-
VK_NV_GEOMETRY_SHADER_PASSTHROUGH_EXTENSION_NAME -
VK_NV_GEOMETRY_SHADER_PASSTHROUGH_SPEC_VERSION
Issues
1) Should we require or allow a passthrough geometry shader to specify the output layout qualifiers for the output primitive type and maximum vertex count in the SPIR-V?
RESOLVED: Yes they should be required in the SPIR-V. Per GL_NV_geometry_shader_passthrough they are not permitted in the GLSL source shader, but SPIR-V is lower-level. It is straightforward for the GLSL compiler to infer them from the input primitive type and to explicitly emit them in the SPIR-V according to the following table.
| Input Layout | Implied Output Layout |
|---|---|
points |
|
lines |
|
triangles |
|
2) How does interface matching work with passthrough geometry shaders?
RESOLVED: This is described in Passthrough Interface Matching.
In GL when using passthough geometry shaders in separable mode, all inputs
must also be explicitly assigned location layout qualifiers.
In Vulkan all SPIR-V shader inputs (except built-ins) must also have
location decorations specified.
Redeclarations of built-in varables that add the passthrough layout
qualifier are exempted from the rule requiring location assignment because
built-in variables do not have locations and are matched by BuiltIn
decoration.
Sample Code
Consider the following simple geometry shader in unextended GLSL:
layout(triangles) in;
layout(triangle_strip) out;
layout(max_vertices=3) out;
in Inputs {
vec2 texcoord;
vec4 baseColor;
} v_in[];
out Outputs {
vec2 texcoord;
vec4 baseColor;
};
void main()
{
int layer = compute_layer();
for (int i = 0; i < 3; i++) {
gl_Position = gl_in[i].gl_Position;
texcoord = v_in[i].texcoord;
baseColor = v_in[i].baseColor;
gl_Layer = layer;
EmitVertex();
}
}
In this shader, the inputs gl_Position, Inputs.texcoord, and
Inputs.baseColor are simply copied from the input vertex to the
corresponding output vertex.
The only “interesting” work done by the geometry shader is computing and
emitting a gl_Layer value for the primitive.
The following geometry shader, using this extension, is equivalent:
#extension GL_NV_geometry_shader_passthrough : require
layout(triangles) in;
// No output primitive layout qualifiers required.
// Redeclare gl_PerVertex to pass through "gl_Position".
layout(passthrough) in gl_PerVertex {
vec4 gl_Position;
} gl_in[];
// Declare "Inputs" with "passthrough" to automatically copy members.
layout(passthrough) in Inputs {
vec2 texcoord;
vec4 baseColor;
} v_in[];
// No output block declaration required.
void main()
{
// The shader simply computes and writes gl_Layer. We do not
// loop over three vertices or call EmitVertex().
gl_Layer = compute_layer();
}
VK_NV_inherited_viewport_scissor
- Name String
-
VK_NV_inherited_viewport_scissor - Extension Type
-
Device extension
- Registered Extension Number
-
279
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
David Zhao Akeley akeley98
-
Other Extension Metadata
- Last Modified Date
-
2021-02-04
- Contributors
-
-
David Zhao Akeley, NVIDIA
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Description
This extension adds the ability for a secondary command buffer to inherit the dynamic viewport and scissor state from a primary command buffer, or a previous secondary command buffer executed within the same vkCmdExecuteCommands call. It addresses a frequent scenario in applications that deal with window resizing and want to improve utilization of re-usable secondary command buffers. The functionality is provided through VkCommandBufferInheritanceViewportScissorInfoNV. Viewport inheritance is effectively limited to the 2D rectangle; secondary command buffers must re-specify the inherited depth range values.
New Enum Constants
-
VK_NV_INHERITED_VIEWPORT_SCISSOR_EXTENSION_NAME -
VK_NV_INHERITED_VIEWPORT_SCISSOR_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_VIEWPORT_SCISSOR_INFO_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INHERITED_VIEWPORT_SCISSOR_FEATURES_NV
-
Issues
(1) Why are viewport depth values configured in the
VkCommandBufferInheritanceViewportScissorInfoNV struct, rather than by
a vkCmd… function?
DISCUSSION:
We considered both adding a new vkCmdSetViewportDepthNV function, and
modifying vkCmdSetViewport to ignore the x, y,
width, and height values when called with a secondary command
buffer that activates this extension.
The primary design considerations for this extension are debuggability and
easy integration into existing applications.
The main issue with adding a new vkCmdSetViewportDepthNV function is
reducing ease-of-integration.
A new function pointer will have to be loaded, but more importantly, a new
function would require changes to be supported in graphics debuggers; this
would delay widespread adoption of the extension.
The proposal to modify vkCmdSetViewport would avoid these issues. However, we expect that the intent of applications using this extension is to have the viewport values used for drawing exactly match the inherited values; thus, it would be better for debuggability if no function for modifying the viewport depth alone is provided. By specifying viewport depth values when starting secondary command buffer recording, and requiring the specified depth values to match the inherited depth values, we allow for validation layers that flag depth changes as errors.
This design also better matches the hardware model. In fact, there is no need to re-execute a depth-setting command. The graphics device retains the viewport depth state; it is the CPU-side state of VkCommandBuffer that must be re-initialized.
(2) Why are viewport depth values specified as a partial VkViewport struct, rather than a leaner depth-only struct?
DISCUSSION:
We considered adding a new VkViewportDepthNV struct containing only
minDepth and maxDepth.
However, as application developers would need to maintain both a
VK_NV_inherited_viewport_scissor code path and a fallback code path (at
least in the short term), we ultimately chose to continue using the existing
VkViewport structure.
Doing so would allow application developers to reuse the same
VkViewport array for both code paths, rather than constructing
separate VkViewportDepthNV and VkViewport arrays for each code
path.
VK_NV_linear_color_attachment
- Name String
-
VK_NV_linear_color_attachment - Extension Type
-
Device extension
- Registered Extension Number
-
431
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
sourav parmar souravpNV
-
Other Extension Metadata
- Last Modified Date
-
2021-12-02
- Interactions and External Dependencies
-
-
This extension requires VK_KHR_format_feature_flags2
-
- Contributors
-
-
Pat Brown, NVIDIA
-
Piers Daniell, NVIDIA
-
Sourav Parmar, NVIDIA
-
Description
This extension expands support for using VK_IMAGE_TILING_LINEAR images
as color attachments when all the color attachments in the render pass
instance have VK_IMAGE_TILING_LINEAR tiling.
This extension adds a new flag bit
VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV that extends the
existing VkFormatFeatureFlagBits2KHR bits.
This flag can be set for renderable color formats in the
VkFormatProperties3KHR::linearTilingFeatures format properties
structure member.
Formats with the VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV
flag may be used as color attachments as long as all the color attachments
in the render pass instance have VK_IMAGE_TILING_LINEAR tiling, and
the formats their images views are created with have
VkFormatProperties3KHR::linearTilingFeatures which include
VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV.
This extension supports both dynamic rendering and traditional render
passes.
New Enum Constants
-
VK_NV_LINEAR_COLOR_ATTACHMENT_EXTENSION_NAME -
VK_NV_LINEAR_COLOR_ATTACHMENT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINEAR_COLOR_ATTACHMENT_FEATURES_NV
-
If VK_KHR_format_feature_flags2 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV
-
VK_NV_mesh_shader
- Name String
-
VK_NV_mesh_shader - Extension Type
-
Device extension
- Registered Extension Number
-
203
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Christoph Kubisch pixeljetstream
-
Other Extension Metadata
- Last Modified Date
-
2018-07-19
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_mesh_shader -
This extension provides API support for
GLSL_NV_mesh_shader
-
- Contributors
-
-
Pat Brown, NVIDIA
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Piers Daniell, NVIDIA
-
Pierre Boudier, NVIDIA
-
Description
This extension provides a new mechanism allowing applications to generate collections of geometric primitives via programmable mesh shading. It is an alternative to the existing programmable primitive shading pipeline, which relied on generating input primitives by a fixed function assembler as well as fixed function vertex fetch.
There are new programmable shader types — the task and mesh shader — to generate these collections to be processed by fixed-function primitive assembly and rasterization logic. When task and mesh shaders are dispatched, they replace the core pre-rasterization stages, including vertex array attribute fetching, vertex shader processing, tessellation, and geometry shader processing.
This extension also adds support for the following SPIR-V extension in Vulkan:
New Enum Constants
-
VK_NV_MESH_SHADER_EXTENSION_NAME -
VK_NV_MESH_SHADER_SPEC_VERSION -
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV -
VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV
-
-
Extending VkShaderStageFlagBits:
-
VK_SHADER_STAGE_MESH_BIT_NV -
VK_SHADER_STAGE_TASK_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_PROPERTIES_NV
-
New or Modified Built-In Variables
-
(modified)
Position -
(modified)
PointSize -
(modified)
ClipDistance -
(modified)
CullDistance -
(modified)
PrimitiveId -
(modified)
Layer -
(modified)
ViewportIndex -
(modified)
WorkgroupSize -
(modified)
WorkgroupId -
(modified)
LocalInvocationId -
(modified)
GlobalInvocationId -
(modified)
LocalInvocationIndex -
(modified)
DrawIndex -
(modified)
ViewportMaskNV -
(modified)
PositionPerViewNV -
(modified)
ViewportMaskPerViewNV
Issues
-
How to name this extension?
RESOLVED: VK_NV_mesh_shader
Other options considered:
-
VK_NV_mesh_shading
-
VK_NV_programmable_mesh_shading
-
VK_NV_primitive_group_shading
-
VK_NV_grouped_drawing
-
-
Do we need a new VkPrimitiveTopology?
RESOLVED: No. We skip the InputAssembler stage.
-
Should we allow Instancing?
RESOLVED: No. There is no fixed function input, other than the IDs. However, allow offsetting with a “first” value.
-
Should we use existing vkCmdDraw or introduce new functions?
RESOLVED: Introduce new functions.
New functions make it easier to separate from “programmable primitive shading” chapter, less “dual use” language about existing functions having alternative behavior. The text around the existing “draws” is heavily based around emitting vertices.
-
If new functions, how to name?
RESOLVED: CmdDrawMeshTasks*
Other options considered:
-
CmdDrawMeshed
-
CmdDrawTasked
-
CmdDrawGrouped
-
-
Should VK_SHADER_STAGE_ALL_GRAPHICS be updated to include the new stages?
RESOLVED: No. If an application were to be recompiled with headers that include additional shader stage bits in VK_SHADER_STAGE_ALL_GRAPHICS, then the previously valid application would no longer be valid on implementations that do not support mesh or task shaders. This means the change would not be backwards compatible. It is too bad VkShaderStageFlagBits does not have a dedicated “all supported graphics stages” bit like VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT, which would have avoided this problem.
VK_NV_ray_tracing
- Name String
-
VK_NV_ray_tracing - Extension Type
-
Device extension
- Registered Extension Number
-
166
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_get_memory_requirements2to be enabled for any device-level functionality
-
- Contact
-
-
Eric Werness ewerness-nv
-
Other Extension Metadata
- Last Modified Date
-
2018-11-20
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_ray_tracing -
This extension provides API support for
GL_NV_ray_tracing
-
- Contributors
-
-
Eric Werness, NVIDIA
-
Ashwin Lele, NVIDIA
-
Robert Stepinski, NVIDIA
-
Nuno Subtil, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Martin Stich, NVIDIA
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Joshua Barczak, Intel
-
Tobias Hector, AMD
-
Henrik Rydgard, NVIDIA
-
Pascal Gautron, NVIDIA
-
Description
Rasterization has been the dominant method to produce interactive graphics, but increasing performance of graphics hardware has made ray tracing a viable option for interactive rendering. Being able to integrate ray tracing with traditional rasterization makes it easier for applications to incrementally add ray traced effects to existing applications or to do hybrid approaches with rasterization for primary visibility and ray tracing for secondary queries.
To enable ray tracing, this extension adds a few different categories of new functionality:
-
Acceleration structure objects and build commands
-
A new pipeline type with new shader domains
-
An indirection table to link shader groups with acceleration structure items
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_ray_tracing
New Structures
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkWriteDescriptorSet:
New Enum Constants
-
VK_NV_RAY_TRACING_EXTENSION_NAME -
VK_NV_RAY_TRACING_SPEC_VERSION -
VK_SHADER_UNUSED_NV -
Extending VkAccelerationStructureTypeKHR:
-
VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV -
VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV
-
-
Extending VkAccessFlagBits:
-
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NV -
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NV
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_RAY_TRACING_BIT_NV
-
-
Extending VkBuildAccelerationStructureFlagBitsKHR:
-
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV -
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV -
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV -
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV
-
-
Extending VkCopyAccelerationStructureModeKHR:
-
VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NV -
VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV
-
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV_EXT
-
-
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV
-
-
Extending VkGeometryFlagBitsKHR:
-
VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_NV -
VK_GEOMETRY_OPAQUE_BIT_NV
-
-
Extending VkGeometryInstanceFlagBitsKHR:
-
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV -
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV -
VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV -
VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_NV
-
-
Extending VkGeometryTypeKHR:
-
VK_GEOMETRY_TYPE_AABBS_NV -
VK_GEOMETRY_TYPE_TRIANGLES_NV
-
-
Extending VkIndexType:
-
VK_INDEX_TYPE_NONE_NV
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV
-
-
Extending VkPipelineBindPoint:
-
VK_PIPELINE_BIND_POINT_RAY_TRACING_NV
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV -
VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV
-
-
Extending VkRayTracingShaderGroupTypeKHR:
-
VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV -
VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV -
VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV
-
-
Extending VkShaderStageFlagBits:
-
VK_SHADER_STAGE_ANY_HIT_BIT_NV -
VK_SHADER_STAGE_CALLABLE_BIT_NV -
VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV -
VK_SHADER_STAGE_INTERSECTION_BIT_NV -
VK_SHADER_STAGE_MISS_BIT_NV -
VK_SHADER_STAGE_RAYGEN_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_INFO_NV -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_NV -
VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NV -
VK_STRUCTURE_TYPE_GEOMETRY_AABB_NV -
VK_STRUCTURE_TYPE_GEOMETRY_NV -
VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PROPERTIES_NV -
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_NV
-
Sample Code
Example ray generation GLSL shader
#version 450 core
#extension GL_NV_ray_tracing : require
layout(set = 0, binding = 0, rgba8) uniform image2D image;
layout(set = 0, binding = 1) uniform accelerationStructureNV as;
layout(location = 0) rayPayloadNV float payload;
void main()
{
vec4 col = vec4(0, 0, 0, 1);
vec3 origin = vec3(float(gl_LaunchIDNV.x)/float(gl_LaunchSizeNV.x), float(gl_LaunchIDNV.y)/float(gl_LaunchSizeNV.y), 1.0);
vec3 dir = vec3(0.0, 0.0, -1.0);
traceNV(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0);
col.y = payload;
imageStore(image, ivec2(gl_LaunchIDNV.xy), col);
}
Version History
-
Revision 1, 2018-09-11 (Robert Stepinski, Nuno Subtil, Eric Werness)
-
Internal revisions
-
-
Revision 2, 2018-10-19 (Eric Werness)
-
rename to VK_NV_ray_tracing, add support for callables.
-
too many updates to list
-
-
Revision 3, 2018-11-20 (Daniel Koch)
-
update to use InstanceId instead of InstanceIndex as implemented.
-
VK_NV_ray_tracing_motion_blur
- Name String
-
VK_NV_ray_tracing_motion_blur - Extension Type
-
Device extension
- Registered Extension Number
-
328
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_ray_tracing_pipelineto be enabled for any device-level functionality
-
- Contact
-
-
Eric Werness
-
Other Extension Metadata
- Last Modified Date
-
2021-06-16
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_ray_tracing_motion_blur -
This extension provides API support for
GL_NV_ray_tracing_motion_blur
-
- Contributors
-
-
Eric Werness, NVIDIA
-
Ashwin Lele, NVIDIA
-
Description
Ray tracing support in the API provides an efficient mechanism to intersect rays against static geometry, but rendering algorithms often want to support motion, which is more efficiently supported with motion-specific algorithms. This extension adds a set of mechanisms to support fast tracing of moving geometry:
-
A ray pipeline trace call which takes a time parameter
-
Flags to enable motion support in an acceleration structure
-
Support for time-varying vertex positions in a geometry
-
Motion instances to move existing instances over time
The motion represented here is parameterized across a normalized timestep
between 0.0 and 1.0.
A motion trace using OpTraceRayMotionNV provides a time within that
normalized range to be used when intersecting that ray with geometry.
The geometry can be provided with motion by a combination of adding a second
vertex position for time of 1.0 using
VkAccelerationStructureGeometryMotionTrianglesDataNV and providing
multiple transforms in the instance using
VkAccelerationStructureMotionInstanceNV.
New Structures
-
Extending VkAccelerationStructureCreateInfoKHR:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
New Enum Constants
-
VK_NV_RAY_TRACING_MOTION_BLUR_EXTENSION_NAME -
VK_NV_RAY_TRACING_MOTION_BLUR_SPEC_VERSION -
Extending VkAccelerationStructureCreateFlagBitsKHR:
-
VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV
-
-
Extending VkBuildAccelerationStructureFlagBitsKHR:
-
VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_MOTION_TRIANGLES_DATA_NV -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MOTION_INFO_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_MOTION_BLUR_FEATURES_NV
-
Issues
(1) What size is VkAccelerationStructureMotionInstanceNV?
-
Added a note on the structure size and made the stride explicit in the language.
(2) Allow arrayOfPointers for motion TLAS?
-
Yes, with a packed encoding to minimize the amount of data sent for metadata.
VK_NV_representative_fragment_test
- Name String
-
VK_NV_representative_fragment_test - Extension Type
-
Device extension
- Registered Extension Number
-
167
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Kedarnath Thangudu kthangudu
-
Other Extension Metadata
- Last Modified Date
-
2018-09-13
- Contributors
-
-
Kedarnath Thangudu, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Pierre Boudier, NVIDIA
-
Pat Brown, NVIDIA
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Description
This extension provides a new representative fragment test that allows implementations to reduce the amount of rasterization and fragment processing work performed for each point, line, or triangle primitive. For any primitive that produces one or more fragments that pass all other early fragment tests, the implementation is permitted to choose one or more “representative” fragments for processing and discard all other fragments. For draw calls rendering multiple points, lines, or triangles arranged in lists, strips, or fans, the representative fragment test is performed independently for each of those primitives.
This extension is useful for applications that use an early render pass to determine the full set of primitives that would be visible in the final scene. In this render pass, such applications would set up a fragment shader that enables early fragment tests and writes to an image or shader storage buffer to record the ID of the primitive that generated the fragment. Without this extension, the shader would record the ID separately for each visible fragment of each primitive. With this extension, fewer stores will be performed, particularly for large primitives.
The representative fragment test has no effect if early fragment tests are not enabled via the fragment shader. The set of fragments discarded by the representative fragment test is implementation-dependent and may vary from frame to frame. In some cases, the representative fragment test may not discard any fragments for a given primitive.
New Enum Constants
-
VK_NV_REPRESENTATIVE_FRAGMENT_TEST_EXTENSION_NAME -
VK_NV_REPRESENTATIVE_FRAGMENT_TEST_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_REPRESENTATIVE_FRAGMENT_TEST_FEATURES_NV -
VK_STRUCTURE_TYPE_PIPELINE_REPRESENTATIVE_FRAGMENT_TEST_STATE_CREATE_INFO_NV
-
Issues
(1) Is the representative fragment test guaranteed to have any effect?
RESOLVED: No. As specified, we only guarantee that each primitive with at least one fragment that passes prior tests will have one fragment passing the representative fragment tests. We do not guarantee that any particular fragment will fail the test.
In the initial implementation of this extension, the representative fragment test is treated as an optimization that may be completely disabled for some pipeline states. This feature was designed for a use case where the fragment shader records information on individual primitives using shader storage buffers or storage images, with no writes to color or depth buffers.
(2) Will the set of fragments that pass the representative fragment test be repeatable if you draw the same scene over and over again?
RESOLVED: No. The set of fragments that pass the representative fragment test is implementation-dependent and may vary due to the timing of operations performed by the GPU.
(3) What happens if you enable the representative fragment test with writes to color and/or depth render targets enabled?
RESOLVED: If writes to the color or depth buffer are enabled, they will be performed for any fragments that survive the relevant tests. Any fragments that fail the representative fragment test will not update color buffers. For the use cases intended for this feature, we do not expect color or depth writes to be enabled.
(4) How do derivatives and automatic texture level of detail computations work with the representative fragment test enabled?
RESOLVED: If a fragment shader uses derivative functions or texture lookups using automatic level of detail computation, derivatives will be computed identically whether or not the representative fragment test is enabled. For the use cases intended for this feature, we do not expect the use of derivatives in the fragment shader.
Version History
-
Revision 2, 2018-09-13 (pbrown)
-
Add issues.
-
-
Revision 1, 2018-08-22 (Kedarnath Thangudu)
-
Internal Revisions
-
VK_NV_sample_mask_override_coverage
- Name String
-
VK_NV_sample_mask_override_coverage - Extension Type
-
Device extension
- Registered Extension Number
-
95
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2016-12-08
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_sample_mask_override_coverage -
This extension provides API support for
GL_NV_sample_mask_override_coverage
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_sample_mask_override_coverage
The extension provides access to the OverrideCoverageNV decoration
under the SampleMaskOverrideCoverageNV capability.
Adding this decoration to a variable with the SampleMask builtin
decoration allows the shader to modify the coverage mask and affect which
samples are used to process the fragment.
When using GLSL source-based shader languages, the override_coverage
layout qualifier from GL_NV_sample_mask_override_coverage maps to the
OverrideCoverageNV decoration.
To use the override_coverage layout qualifier in GLSL the
GL_NV_sample_mask_override_coverage extension must be enabled.
Behavior is described in the GL_NV_sample_mask_override_coverage extension
spec.
New Enum Constants
-
VK_NV_SAMPLE_MASK_OVERRIDE_COVERAGE_EXTENSION_NAME -
VK_NV_SAMPLE_MASK_OVERRIDE_COVERAGE_SPEC_VERSION
VK_NV_scissor_exclusive
- Name String
-
VK_NV_scissor_exclusive - Extension Type
-
Device extension
- Registered Extension Number
-
206
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Pat Brown nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2018-07-31
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
None
- Contributors
-
-
Pat Brown, NVIDIA
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
This extension adds support for an exclusive scissor test to Vulkan. The exclusive scissor test behaves like the scissor test, except that the exclusive scissor test fails for pixels inside the corresponding rectangle and passes for pixels outside the rectangle. If the same rectangle is used for both the scissor and exclusive scissor tests, the exclusive scissor test will pass if and only if the scissor test fails.
New Enum Constants
-
VK_NV_SCISSOR_EXCLUSIVE_EXTENSION_NAME -
VK_NV_SCISSOR_EXCLUSIVE_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXCLUSIVE_SCISSOR_FEATURES_NV -
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_EXCLUSIVE_SCISSOR_STATE_CREATE_INFO_NV
-
Issues
1) For the scissor test, the viewport state must be created with a matching number of scissor and viewport rectangles. Should we have the same requirement for exclusive scissors?
RESOLVED: For exclusive scissors, we relax this requirement and allow an exclusive scissor rectangle count that is either zero or equal to the number of viewport rectangles. If you pass in an exclusive scissor count of zero, the exclusive scissor test is treated as disabled.
VK_NV_shader_image_footprint
- Name String
-
VK_NV_shader_image_footprint - Extension Type
-
Device extension
- Registered Extension Number
-
205
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Pat Brown nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2018-09-13
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_shader_image_footprint -
This extension provides API support for
GL_NV_shader_texture_footprint
-
- Contributors
-
-
Pat Brown, NVIDIA
-
Chris Lentini, NVIDIA
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension adds Vulkan support for the
SPV_NV_shader_image_footprint
SPIR-V extension.
That SPIR-V extension provides a new instruction
OpImageSampleFootprintNV allowing shaders to determine the set of
texels that would be accessed by an equivalent filtered texture lookup.
Instead of returning a filtered texture value, the instruction returns a structure that can be interpreted by shader code to determine the footprint of a filtered texture lookup. This structure includes integer values that identify a small neighborhood of texels in the image being accessed and a bitfield that indicates which texels in that neighborhood would be used. The structure also includes a bitfield where each bit identifies whether any texel in a small aligned block of texels would be fetched by the texture lookup. The size of each block is specified by an access granularity provided by the shader. The minimum granularity supported by this extension is 2x2 (for 2D textures) and 2x2x2 (for 3D textures); the maximum granularity is 256x256 (for 2D textures) or 64x32x32 (for 3D textures). Each footprint query returns the footprint from a single texture level. When using minification filters that combine accesses from multiple mipmap levels, shaders must perform separate queries for the two levels accessed (“fine” and “coarse”). The footprint query also returns a flag indicating if the texture lookup would access texels from only one mipmap level or from two neighboring levels.
This extension should be useful for multi-pass rendering operations that do an initial expensive rendering pass to produce a first image that is then used as a texture for a second pass. If the second pass ends up accessing only portions of the first image (e.g., due to visbility), the work spent rendering the non-accessed portion of the first image was wasted. With this feature, an application can limit this waste using an initial pass over the geometry in the second image that performs a footprint query for each visible pixel to determine the set of pixels that it needs from the first image. This pass would accumulate an aggregate footprint of all visible pixels into a separate “footprint image” using shader atomics. Then, when rendering the first image, the application can kill all shading work for pixels not in this aggregate footprint.
This extension has a number of limitations.
The OpImageSampleFootprintNV instruction only supports for two- and
three-dimensional textures.
Footprint evaluation only supports the CLAMP_TO_EDGE wrap mode; results are
undefined for all other wrap modes.
Only a limited set of granularity values and that set does not support
separate coverage information for each texel in the original image.
When using SPIR-V generated from the OpenGL Shading Language, the new
instruction will be generated from code using the new
textureFootprint*NV built-in functions from the
GL_NV_shader_texture_footprint shading language extension.
New Enum Constants
-
VK_NV_SHADER_IMAGE_FOOTPRINT_EXTENSION_NAME -
VK_NV_SHADER_IMAGE_FOOTPRINT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_IMAGE_FOOTPRINT_FEATURES_NV
-
Issues
(1) The footprint returned by the SPIR-V instruction is a structure that includes an anchor, an offset, and a mask that represents a 8x8 or 4x4x4 neighborhood of texel groups. But the bits of the mask are not stored in simple pitch order. Why is the footprint built this way?
RESOLVED: We expect that applications using this feature will want to use a fixed granularity and accumulate coverage information from the returned footprints into an aggregate “footprint image” that tracks the portions of an image that would be needed by regular texture filtering. If an application is using a two-dimensional image with 4x4 pixel granularity, we expect that the footprint image will use 64-bit texels where each bit in an 8x8 array of bits corresponds to coverage for a 4x4 block in the original image. Texel (0,0) in the footprint image would correspond to texels (0,0) through (31,31) in the original image.
In the usual case, the footprint for a single access will fully contained in a 32x32 aligned region of the original texture, which corresponds to a single 64-bit texel in the footprint image. In that case, the implementation will return an anchor coordinate pointing at the single footprint image texel, an offset vector of (0,0), and a mask whose bits are aligned with the bits in the footprint texel. For this case, the shader can simply atomically OR the mask bits into the contents of the footprint texel to accumulate footprint coverage.
In the worst case, the footprint for a single access spans multiple 32x32 aligned regions and may require updates to four separate footprint image texels. In this case, the implementation will return an anchor coordinate pointing at the lower right footprint image texel and an offset will identify how many “columns” and “rows” of the returned 8x8 mask correspond to footprint texels to the left and above the anchor texel. If the anchor is (2,3), the 64 bits of the returned mask are arranged spatially as follows, where each 4x4 block is assigned a bit number that matches its bit number in the footprint image texels:
+-------------------------+-------------------------+
| -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- |
| -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- |
| -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- |
| -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- |
| -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- |
| -- -- -- -- -- -- 46 47 | 40 41 42 43 44 45 -- -- |
| -- -- -- -- -- -- 54 55 | 48 49 50 51 52 53 -- -- |
| -- -- -- -- -- -- 62 63 | 56 57 58 59 60 61 -- -- |
+-------------------------+-------------------------+
| -- -- -- -- -- -- 06 07 | 00 01 02 03 04 05 -- -- |
| -- -- -- -- -- -- 14 15 | 08 09 10 11 12 13 -- -- |
| -- -- -- -- -- -- 22 23 | 16 17 18 19 20 21 -- -- |
| -- -- -- -- -- -- 30 31 | 24 25 26 27 28 29 -- -- |
| -- -- -- -- -- -- 38 39 | 32 33 34 35 36 37 -- -- |
| -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- |
| -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- |
| -- -- -- -- -- -- -- -- | -- -- -- -- -- -- -- -- |
+-------------------------+-------------------------+
To accumulate coverage for each of the four footprint image texels, a shader can AND the returned mask with simple masks derived from the x and y offset values and then atomically OR the updated mask bits into the contents of the corresponding footprint texel.
uint64_t returnedMask = (uint64_t(footprint.mask.x) | (uint64_t(footprint.mask.y) << 32));
uint64_t rightMask = ((0xFF >> footprint.offset.x) * 0x0101010101010101UL);
uint64_t bottomMask = 0xFFFFFFFFFFFFFFFFUL >> (8 * footprint.offset.y);
uint64_t bottomRight = returnedMask & bottomMask & rightMask;
uint64_t bottomLeft = returnedMask & bottomMask & (~rightMask);
uint64_t topRight = returnedMask & (~bottomMask) & rightMask;
uint64_t topLeft = returnedMask & (~bottomMask) & (~rightMask);
(2) What should an application do to ensure maximum performance when accumulating footprints into an aggregate footprint image?
RESOLVED: We expect that the most common usage of this feature will be to accumulate aggregate footprint coverage, as described in the previous issue. Even if you ignore the anisotropic filtering case where the implementation may return a granularity larger than that requested by the caller, each shader invocation will need to use atomic functions to update up to four footprint image texels for each level of detail accessed. Having each active shader invocation perform multiple atomic operations can be expensive, particularly when neighboring invocations will want to update the same footprint image texels.
Techniques can be used to reduce the number of atomic operations performed when accumulating coverage include:
-
Have logic that detects returned footprints where all components of the returned offset vector are zero. In that case, the mask returned by the footprint function is guaranteed to be aligned with the footprint image texels and affects only a single footprint image texel.
-
Have fragment shaders communicate using built-in functions from the
VK_NV_shader_subgroup_partitionedextension or other shader subgroup extensions. If you have multiple invocations in a subgroup that need to update the same texel (x,y) in the footprint image, compute an aggregate footprint mask across all invocations in the subgroup updating that texel and have a single invocation perform an atomic operation using that aggregate mask. -
When the returned footprint spans multiple texels in the footprint image, each invocation need to perform four atomic operations. In the previous issue, we had an example that computed separate masks for “topLeft”, “topRight”, “bottomLeft”, and “bottomRight”. When the invocations in a subgroup have good locality, it might be the case the “top left” for some invocations might refer to footprint image texel (10,10), while neighbors might have their “top left” texels at (11,10), (10,11), and (11,11). If you compute separate masks for even/odd x and y values instead of left/right or top/bottom, the “odd/odd” mask for all invocations in the subgroup hold coverage for footprint image texel (11,11), which can be updated by a single atomic operation for the entire subgroup.
Version History
-
Revision 2, 2018-09-13 (Pat Brown)
-
Add issue (2) with performance tips.
-
-
Revision 1, 2018-08-12 (Pat Brown)
-
Initial draft
-
VK_NV_shader_sm_builtins
- Name String
-
VK_NV_shader_sm_builtins - Extension Type
-
Device extension
- Registered Extension Number
-
155
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2019-05-28
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_shader_sm_builtins. -
This extension provides API support for
GL_NV_shader_sm_builtins
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Description
This extension provides the ability to determine device-specific properties on NVIDIA GPUs. It provides the number of streaming multiprocessors (SMs), the maximum number of warps (subgroups) that can run on an SM, and shader builtins to enable invocations to identify which SM and warp a shader invocation is executing on.
This extension enables support for the SPIR-V ShaderSMBuiltinsNV
capability.
These properties and built-ins should typically only be used for debugging purposes.
New Enum Constants
-
VK_NV_SHADER_SM_BUILTINS_EXTENSION_NAME -
VK_NV_SHADER_SM_BUILTINS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SM_BUILTINS_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SM_BUILTINS_PROPERTIES_NV
-
Issues
-
What should we call this extension?
RESOLVED:
NV_shader_sm_builtins. Other options considered included:-
NV_shader_smid- but SMID is really easy to typo/confuse as SIMD. -
NV_shader_sm_info- but Info is typically reserved for input structures
-
VK_NV_shader_subgroup_partitioned
- Name String
-
VK_NV_shader_subgroup_partitioned - Extension Type
-
Device extension
- Registered Extension Number
-
199
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2018-03-17
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_shader_subgroup_partitioned -
This extension provides API support for
GL_NV_shader_subgroup_partitioned
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension enables support for a new class of
group operations on subgroups via the
GL_NV_shader_subgroup_partitioned
GLSL extension and
SPV_NV_shader_subgroup_partitioned
SPIR-V extension.
Support for these new operations is advertised via the
VK_SUBGROUP_FEATURE_PARTITIONED_BIT_NV bit.
This extension requires Vulkan 1.1, for general subgroup support.
New Enum Constants
-
VK_NV_SHADER_SUBGROUP_PARTITIONED_EXTENSION_NAME -
VK_NV_SHADER_SUBGROUP_PARTITIONED_SPEC_VERSION -
Extending VkSubgroupFeatureFlagBits:
-
VK_SUBGROUP_FEATURE_PARTITIONED_BIT_NV
-
VK_NV_shading_rate_image
- Name String
-
VK_NV_shading_rate_image - Extension Type
-
Device extension
- Registered Extension Number
-
165
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Contact
-
-
Pat Brown nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2019-07-18
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_shading_rate -
This extension provides API support for
GL_NV_shading_rate_image
-
- Contributors
-
-
Pat Brown, NVIDIA
-
Carsten Rohde, NVIDIA
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Mathias Schott, NVIDIA
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Description
This extension allows applications to use a variable shading rate when processing fragments of rasterized primitives. By default, Vulkan will spawn one fragment shader for each pixel covered by a primitive. In this extension, applications can bind a shading rate image that can be used to vary the number of fragment shader invocations across the framebuffer. Some portions of the screen may be configured to spawn up to 16 fragment shaders for each pixel, while other portions may use a single fragment shader invocation for a 4x4 block of pixels. This can be useful for use cases like eye tracking, where the portion of the framebuffer that the user is looking at directly can be processed at high frequency, while distant corners of the image can be processed at lower frequency. Each texel in the shading rate image represents a fixed-size rectangle in the framebuffer, covering 16x16 pixels in the initial implementation of this extension. When rasterizing a primitive covering one of these rectangles, the Vulkan implementation reads a texel in the bound shading rate image and looks up the fetched value in a palette to determine a base shading rate.
In addition to the API support controlling rasterization, this extension
also adds Vulkan support for the
SPV_NV_shading_rate extension to
SPIR-V.
That extension provides two fragment shader variable decorations that allow
fragment shaders to determine the shading rate used for processing the
fragment:
-
FragmentSizeNV, which indicates the width and height of the set of pixels processed by the fragment shader. -
InvocationsPerPixel, which indicates the maximum number of fragment shader invocations that could be spawned for the pixel(s) covered by the fragment.
When using SPIR-V in conjunction with the OpenGL Shading Language (GLSL),
the fragment shader capabilities are provided by the
GL_NV_shading_rate_image language extension and correspond to the built-in
variables gl_FragmentSizeNV and gl_InvocationsPerPixelNV,
respectively.
New Enum Constants
-
VK_NV_SHADING_RATE_IMAGE_EXTENSION_NAME -
VK_NV_SHADING_RATE_IMAGE_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_SHADING_RATE_IMAGE_READ_BIT_NV
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV -
VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_PROPERTIES_NV -
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_COARSE_SAMPLE_ORDER_STATE_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SHADING_RATE_IMAGE_STATE_CREATE_INFO_NV
-
Issues
(1) When using shading rates specifying “coarse” fragments covering multiple pixels, we will generate a combined coverage mask that combines the coverage masks of all pixels covered by the fragment. By default, these masks are combined in an implementation-dependent order. Should we provide a mechanism allowing applications to query or specify an exact order?
RESOLVED: Yes, this feature is useful for cases where most of the fragment shader can be evaluated once for an entire coarse fragment, but where some per-pixel computations are also required. For example, a per-pixel alpha test may want to kill all the samples for some pixels in a coarse fragment. This sort of test can be implemented using an output sample mask, but such a shader would need to know which bit in the mask corresponds to each sample in the coarse fragment. We are including a mechanism to allow aplications to specify the orders of coverage samples for each shading rate and sample count, either as static pipeline state or dynamically via a command buffer. This portion of the extension has its own feature bit.
We will not be providing a query to determine the implementation-dependent default ordering. The thinking here is that if an application cares enough about the coarse fragment sample ordering to perform such a query, it could instead just set its own order, also using custom per-pixel sample locations if required.
(2) For the pipeline stage
VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV, should we specify a
precise location in the pipeline the shading rate image is accessed (after
geometry shading, but before the early fragment tests) or leave it
under-specified in case there are other implementations that access the
image in a different pipeline location?
RESOLVED We are specifying the pipeline stage to be between the final
pre-rasterization shader
stage (VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT) and before the first
stage used for fragment processing
(VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT), which seems to be the
natural place to access the shading rate image.
(3) How do centroid-sampled variables work with fragments larger than one pixel?
RESOLVED For single-pixel fragments, fragment shader inputs decorated with
Centroid are sampled at an implementation-dependent location in the
intersection of the area of the primitive being rasterized and the area of
the pixel that corresponds to the fragment.
With multi-pixel fragments, we follow a similar pattern, using the
intersection of the primitive and the set of pixels corresponding to the
fragment.
One important thing to keep in mind when using such “coarse” shading rates is that fragment attributes are sampled at the center of the fragment by default, regardless of the set of pixels/samples covered by the fragment. For fragments with a size of 4x4 pixels, this center location will be more than two pixels (1.5 * sqrt(2)) away from the center of the pixels at the corners of the fragment. When rendering a primitive that covers only a small part of a coarse fragment, sampling a color outside the primitive can produce overly bright or dark color values if the color values have a large gradient. To deal with this, an application can use centroid sampling on attributes where “extrapolation” artifacts can lead to overly bright or dark pixels. Note that this same problem also exists for multisampling with single-pixel fragments, but is less severe because it only affects certain samples of a pixel and such bright/dark samples may be averaged with other samples that do not have a similar problem.
Version History
-
Revision 3, 2019-07-18 (Mathias Schott)
-
Fully list extension interfaces in this appendix.
-
-
Revision 2, 2018-09-13 (Pat Brown)
-
Miscellaneous edits preparing the specification for publication.
-
-
Revision 1, 2018-08-08 (Pat Brown)
-
Internal revisions
-
VK_NV_viewport_array2
- Name String
-
VK_NV_viewport_array2 - Extension Type
-
Device extension
- Registered Extension Number
-
97
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-02-15
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_viewport_array2 -
This extension provides API support for
GL_NV_viewport_array2 -
This extension requires the
geometryShaderandmultiViewportfeatures. -
This extension interacts with the
tessellationShaderfeature.
-
- Contributors
-
-
Piers Daniell, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_viewport_array2
which allows a single primitive to be broadcast to multiple viewports and/or
multiple layers.
A new shader built-in output ViewportMaskNV is provided, which allows a
single primitive to be output to multiple viewports simultaneously.
Also, a new SPIR-V decoration is added to control whether the effective
viewport index is added into the variable decorated with the Layer
built-in decoration.
These capabilities allow a single primitive to be output to multiple layers
simultaneously.
This extension allows variables decorated with the Layer and
ViewportIndex built-ins to be exported from vertex or tessellation
shaders, using the ShaderViewportIndexLayerNV capability.
This extension adds a new ViewportMaskNV built-in decoration that is
available for output variables in vertex, tessellation evaluation, and
geometry shaders, and a new ViewportRelativeNV decoration that can be
added on variables decorated with Layer when using the
ShaderViewportMaskNV capability.
When using GLSL source-based shading languages, the gl_ViewportMask[]
built-in output variable and viewport_relative layout qualifier from
GL_NV_viewport_array2 map to the ViewportMaskNV and
ViewportRelativeNV decorations, respectively.
Behaviour is described in the GL_NV_viewport_array2 extension
specificiation.
|
Note
The |
New Enum Constants
-
VK_NV_VIEWPORT_ARRAY2_EXTENSION_NAME -
VK_NV_VIEWPORT_ARRAY2_SPEC_VERSION -
VK_NV_VIEWPORT_ARRAY_2_EXTENSION_NAME -
VK_NV_VIEWPORT_ARRAY_2_SPEC_VERSION
New or Modified Built-In Variables
-
(modified)
Layer -
(modified)
ViewportIndex
VK_NV_viewport_swizzle
- Name String
-
VK_NV_viewport_swizzle - Extension Type
-
Device extension
- Registered Extension Number
-
99
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2016-12-22
- Interactions and External Dependencies
-
-
This extension requires
multiViewportandgeometryShaderfeatures to be useful.
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension provides a new per-viewport swizzle that can modify the position of primitives sent to each viewport. New viewport swizzle state is added for each viewport, and a new position vector is computed for each vertex by selecting from and optionally negating any of the four components of the original position vector.
This new viewport swizzle is useful for a number of algorithms, including single-pass cube map rendering (broadcasting a primitive to multiple faces and reorienting the vertex position for each face) and voxel rasterization. The per-viewport component remapping and negation provided by the swizzle allows application code to re-orient three-dimensional geometry with a view along any of the X, Y, or Z axes. If a perspective projection and depth buffering is required, 1/W buffering should be used, as described in the single-pass cube map rendering example in the “Issues” section below.
New Enum Constants
-
VK_NV_VIEWPORT_SWIZZLE_EXTENSION_NAME -
VK_NV_VIEWPORT_SWIZZLE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SWIZZLE_STATE_CREATE_INFO_NV
-
Issues
1) Where does viewport swizzling occur in the pipeline?
RESOLVED: Despite being associated with the viewport, viewport swizzling must happen prior to the viewport transform. In particular, it needs to be performed before clipping and perspective division.
The viewport mask expansion (VK_NV_viewport_array2) and the
viewport swizzle could potentially be performed before or after transform
feedback, but feeding back several viewports worth of primitives with
different swizzles does not seem particularly useful.
This specification applies the viewport mask and swizzle after transform
feedback, and makes primitive queries only count each primitive once.
2) Any interesting examples of how this extension,
VK_NV_viewport_array2, and
VK_NV_geometry_shader_passthrough can be used together in practice?
RESOLVED: One interesting use case for this extension is for single-pass
rendering to a cube map.
In this example, the application would attach a cube map texture to a
layered FBO where the six cube faces are treated as layers.
Vertices are sent through the vertex shader without applying a projection
matrix, where the gl_Position output is (x,y,z,1) and the center
of the cube map is at (0,0,0).
With unextended Vulkan, one could have a conventional instanced geometry
shader that looks something like the following:
layout(invocations = 6) in; // separate invocation per face
layout(triangles) in;
layout(triangle_strip) out;
layout(max_vertices = 3) out;
in Inputs {
vec2 texcoord;
vec3 normal;
vec4 baseColor;
} v[];
out Outputs {
vec2 texcoord;
vec3 normal;
vec4 baseColor;
};
void main()
{
int face = gl_InvocationID; // which face am I?
// Project gl_Position for each vertex onto the cube map face.
vec4 positions[3];
for (int i = 0; i < 3; i++) {
positions[i] = rotate(gl_in[i].gl_Position, face);
}
// If the primitive does not project onto this face, we are done.
if (shouldCull(positions)) {
return;
}
// Otherwise, emit a copy of the input primitive to the
// appropriate face (using gl_Layer).
for (int i = 0; i < 3; i++) {
gl_Layer = face;
gl_Position = positions[i];
texcoord = v[i].texcoord;
normal = v[i].normal;
baseColor = v[i].baseColor;
EmitVertex();
}
}
With passthrough geometry shaders, this can be done using a much simpler shader:
layout(triangles) in;
layout(passthrough) in Inputs {
vec2 texcoord;
vec3 normal;
vec4 baseColor;
}
layout(passthrough) in gl_PerVertex {
vec4 gl_Position;
} gl_in[];
layout(viewport_relative) out int gl_Layer;
void main()
{
// Figure out which faces the primitive projects onto and
// generate a corresponding viewport mask.
uint mask = 0;
for (int i = 0; i < 6; i++) {
if (!shouldCull(face)) {
mask |= 1U << i;
}
}
gl_ViewportMask = mask;
gl_Layer = 0;
}
The application code is set up so that each of the six cube faces has a
separate viewport (numbered 0 to 5).
Each face also has a separate swizzle, programmed via the
VkPipelineViewportSwizzleStateCreateInfoNV pipeline state.
The viewport swizzle feature performs the coordinate transformation handled
by the rotate() function in the original shader.
The viewport_relative layout qualifier says that the viewport number (0
to 5) is added to the base gl_Layer value of 0 to determine which layer
(cube face) the primitive should be sent to.
Note that the use of the passed through input normal in this example
suggests that the fragment shader in this example would perform an operation
like per-fragment lighting.
The viewport swizzle would transform the position to be face-relative, but
normal would remain in the original coordinate system.
It seems likely that the fragment shader in either version of the example
would want to perform lighting in the original coordinate system.
It would likely do this by reconstructing the position of the fragment in
the original coordinate system using gl_FragCoord, a constant or
uniform holding the size of the cube face, and the input
gl_ViewportIndex (or gl_Layer), which identifies the cube face.
Since the value of normal is in the original coordinate system, it
would not need to be modified as part of this coordinate transformation.
Note that while the rotate() operation in the regular geometry shader
above could include an arbitrary post-rotation projection matrix, the
viewport swizzle does not support arbitrary math.
To get proper projection, 1/W buffering should be used.
To do this:
-
Program the viewport swizzles to move the pre-projection W eye coordinate (typically 1.0) into the Z coordinate of the swizzle output and the eye coordinate component used for depth into the W coordinate. For example, the viewport corresponding to the +Z face might use a swizzle of (+X, -Y, +W, +Z). The Z normalized device coordinate computed after swizzling would then be z'/w' = 1/Zeye.
-
On NVIDIA implementations supporting floating-point depth buffers with values outside [0,1], prevent unwanted near plane clipping by enabling
depthClampEnable. Ensure that the depth clamp does not mess up depth testing by programming the depth range to very large values, such asminDepthBounds=-z,maxDepthBounds=+z, where z = 2127. It should be possible to use IEEE infinity encodings also (0xFF800000for-INF,0x7F800000for+INF). Even when near/far clipping is disabled, primitives extending behind the eye will still be clipped because one or more vertices will have a negative W coordinate and fail X/Y clipping tests.On other implementations, scale X, Y, and Z eye coordinates so that vertices on the near plane have a post-swizzle W coordinate of 1.0. For example, if the near plane is at Zeye = 1/256, scale X, Y, and Z by 256.
-
Adjust depth testing to reflect the fact that 1/W values are large near the eye and small away from the eye. Clear the depth buffer to zero (infinitely far away) and use a depth test of
VK_COMPARE_OP_GREATERinstead ofVK_COMPARE_OP_LESS.
VK_NVX_binary_import
- Name String
-
VK_NVX_binary_import - Extension Type
-
Device extension
- Registered Extension Number
-
30
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Eric Werness ewerness-nv
-
Liam Middlebrook liam-middlebrook
-
Other Extension Metadata
- Last Modified Date
-
2021-04-09
- Contributors
-
-
Eric Werness, NVIDIA
-
Liam Middlebrook, NVIDIA
-
Description
This extension allows applications to import CuBIN binaries and execute them.
|
Note
There is currently no specification language written for this extension. The links to APIs defined by the extension are to stubs that only include generated content such as API declarations and implicit valid usage statements. |
New Enum Constants
-
VK_NVX_BINARY_IMPORT_EXTENSION_NAME -
VK_NVX_BINARY_IMPORT_SPEC_VERSION -
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_CU_FUNCTION_NVX_EXT -
VK_DEBUG_REPORT_OBJECT_TYPE_CU_MODULE_NVX_EXT
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_CU_FUNCTION_NVX -
VK_OBJECT_TYPE_CU_MODULE_NVX
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CU_FUNCTION_CREATE_INFO_NVX -
VK_STRUCTURE_TYPE_CU_LAUNCH_INFO_NVX -
VK_STRUCTURE_TYPE_CU_MODULE_CREATE_INFO_NVX
-
Stub API References
There is currently no specification language written for this type. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCuFunctionNVX)
There is currently no specification language written for this type. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCuModuleNVX)
There is currently no specification language written for this command. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
VkResult vkCreateCuFunctionNVX(
VkDevice device,
const VkCuFunctionCreateInfoNVX* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkCuFunctionNVX* pFunction);
There is currently no specification language written for this type. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
typedef struct VkCuFunctionCreateInfoNVX {
VkStructureType sType;
const void* pNext;
VkCuModuleNVX module;
const char* pName;
} VkCuFunctionCreateInfoNVX;
There is currently no specification language written for this command. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
void vkDestroyCuFunctionNVX(
VkDevice device,
VkCuFunctionNVX function,
const VkAllocationCallbacks* pAllocator);
There is currently no specification language written for this command. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
VkResult vkCreateCuModuleNVX(
VkDevice device,
const VkCuModuleCreateInfoNVX* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkCuModuleNVX* pModule);
There is currently no specification language written for this type. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
typedef struct VkCuModuleCreateInfoNVX {
VkStructureType sType;
const void* pNext;
size_t dataSize;
const void* pData;
} VkCuModuleCreateInfoNVX;
There is currently no specification language written for this command. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
void vkDestroyCuModuleNVX(
VkDevice device,
VkCuModuleNVX module,
const VkAllocationCallbacks* pAllocator);
There is currently no specification language written for this command. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
void vkCmdCuLaunchKernelNVX(
VkCommandBuffer commandBuffer,
const VkCuLaunchInfoNVX* pLaunchInfo);
There is currently no specification language written for this type. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_NVX_binary_import
typedef struct VkCuLaunchInfoNVX {
VkStructureType sType;
const void* pNext;
VkCuFunctionNVX function;
uint32_t gridDimX;
uint32_t gridDimY;
uint32_t gridDimZ;
uint32_t blockDimX;
uint32_t blockDimY;
uint32_t blockDimZ;
uint32_t sharedMemBytes;
size_t paramCount;
const void* const * pParams;
size_t extraCount;
const void* const * pExtras;
} VkCuLaunchInfoNVX;
VK_NVX_image_view_handle
- Name String
-
VK_NVX_image_view_handle - Extension Type
-
Device extension
- Registered Extension Number
-
31
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Eric Werness ewerness-nv
-
Other Extension Metadata
- Last Modified Date
-
2020-04-03
- Contributors
-
-
Eric Werness, NVIDIA
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
This extension allows applications to query an opaque handle from an image view for use as a sampled image or storage image. This provides no direct functionality itself.
New Enum Constants
-
VK_NVX_IMAGE_VIEW_HANDLE_EXTENSION_NAME -
VK_NVX_IMAGE_VIEW_HANDLE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_VIEW_ADDRESS_PROPERTIES_NVX -
VK_STRUCTURE_TYPE_IMAGE_VIEW_HANDLE_INFO_NVX
-
Version History
-
Revision 2, 2020-04-03 (Piers Daniell)
-
Revision 1, 2018-12-07 (Eric Werness)
-
Internal revisions
-
VK_NVX_multiview_per_view_attributes
- Name String
-
VK_NVX_multiview_per_view_attributes - Extension Type
-
Device extension
- Registered Extension Number
-
98
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_multiviewto be enabled for any device-level functionality
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-01-13
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_NVX_multiview_per_view_attributes -
This extension provides API support for
GL_NVX_multiview_per_view_attributes -
This extension interacts with
VK_NV_viewport_array2.
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
This extension adds a new way to write shaders to be used with multiview
subpasses, where the attributes for all views are written out by a single
invocation of the
pre-rasterization shader
stages.
Related SPIR-V and GLSL extensions SPV_NVX_multiview_per_view_attributes
and GL_NVX_multiview_per_view_attributes introduce per-view position and
viewport mask attributes arrays, and this extension defines how those
per-view attribute arrays are interpreted by Vulkan.
Pipelines using per-view attributes may only execute the
pre-rasterization shader
stages once for all views rather than once per-view, which reduces
redundant shading work.
A subpass creation flag controls whether the subpass uses this extension. A subpass must either exclusively use this extension or not use it at all.
Some Vulkan implementations only support the position attribute varying between views in the X component. A subpass can declare via a second creation flag whether all pipelines compiled for this subpass will obey this restriction.
Shaders that use the new per-view outputs (e.g. gl_PositionPerViewNV)
must also write the non-per-view output (gl_Position), and the values
written must be such that gl_Position =
gl_PositionPerViewNV[gl_ViewIndex] for all views in the subpass.
Implementations are free to either use the per-view outputs or the
non-per-view outputs, whichever would be more efficient.
If VK_NV_viewport_array2 is not also supported and enabled, the
per-view viewport mask must not be used.
New Enum Constants
-
VK_NVX_MULTIVIEW_PER_VIEW_ATTRIBUTES_EXTENSION_NAME -
VK_NVX_MULTIVIEW_PER_VIEW_ATTRIBUTES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PER_VIEW_ATTRIBUTES_PROPERTIES_NVX
-
-
Extending VkSubpassDescriptionFlagBits:
-
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX -
VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX
-
Examples
#version 450 core
#extension GL_KHX_multiview : enable
#extension GL_NVX_multiview_per_view_attributes : enable
layout(location = 0) in vec4 position;
layout(set = 0, binding = 0) uniform Block { mat4 mvpPerView[2]; } buf;
void main()
{
// Output both per-view positions and gl_Position as a function
// of gl_ViewIndex
gl_PositionPerViewNV[0] = buf.mvpPerView[0] * position;
gl_PositionPerViewNV[1] = buf.mvpPerView[1] * position;
gl_Position = buf.mvpPerView[gl_ViewIndex] * position;
}
VK_QCOM_fragment_density_map_offset
- Name String
-
VK_QCOM_fragment_density_map_offset - Extension Type
-
Device extension
- Registered Extension Number
-
426
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_EXT_fragment_density_mapto be enabled for any device-level functionality
-
- Contact
-
-
Matthew Netsch mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2021-09-03
- Contributors
-
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Jonathan Tinkham, Qualcomm Technologies, Inc.
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Description
This extension allows an application to specify offsets to a fragment density map attachment, changing the framebuffer location where density values are applied to without having to regenerate the fragment density map.
New Enum Constants
-
VK_QCOM_FRAGMENT_DENSITY_MAP_OFFSET_EXTENSION_NAME -
VK_QCOM_FRAGMENT_DENSITY_MAP_OFFSET_SPEC_VERSION -
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_FEATURES_QCOM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_PROPERTIES_QCOM -
VK_STRUCTURE_TYPE_SUBPASS_FRAGMENT_DENSITY_MAP_OFFSET_END_INFO_QCOM
-
VK_QCOM_render_pass_shader_resolve
- Name String
-
VK_QCOM_render_pass_shader_resolve - Extension Type
-
Device extension
- Registered Extension Number
-
172
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Bill Licea-Kane wwlk
-
Other Extension Metadata
- Last Modified Date
-
2019-11-07
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
None.
- Contributors
-
-
Srihari Babu Alla, Qualcomm
-
Bill Licea-Kane, Qualcomm
-
Jeff Leger, Qualcomm
-
Description
This extension allows a shader resolve to replace fixed-function resolve.
Fixed-function resolve is limited in function to simple filters of multisample buffers to a single sample buffer.
Fixed-function resolve is more performance efficient and/or power efficient than shader resolve for such simple filters.
Shader resolve allows a shader writer to create complex, non-linear filtering of a multisample buffer in the last subpass of a subpass dependency chain.
This extension also provides a bit which can be used to enlarge a sample region dependency to a fragment region dependency, so that a framebuffer-region dependency can replace a framebuffer-global dependency in some cases.
New Enum Constants
-
VK_QCOM_RENDER_PASS_SHADER_RESOLVE_EXTENSION_NAME -
VK_QCOM_RENDER_PASS_SHADER_RESOLVE_SPEC_VERSION -
Extending VkSubpassDescriptionFlagBits:
-
VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM -
VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM
-
Issues
1) Should this extension be named render_pass_shader_resolve?
RESOLVED Yes.
This is part of suite of small extensions to render pass.
Following the style guide, instead of following VK_KHR_create_renderpass2.
2) Should the VK_SAMPLE_COUNT_1_BIT be required for each pColorAttachment and the DepthStencilAttachent?
RESOLVED No.
While this may not be a common use case, and while most fixed-function resolve hardware has this limitation, there is little reason to require a shader resolve to resolve to a single sample buffer.
3) Should a shader resolve subpass be the last subpass in a render pass?
RESOLVED Yes.
To be more specific, it should be the last subpass in a subpass dependency chain.
4) Do we need the VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM bit?
RESOLVED Yes.
This applies when an input attachment’s sample count is equal to
rasterizationSamples.
Further, if sampleShading is enabled (explicitly or implicitly) then
minSampleShading must equal 0.0.
However, this bit may be set on any subpass, it is not restricted to a shader resolve subpass.
Version History
-
Revision 1, 2019-06-28 (wwlk)
-
Initial draft
-
-
Revision 2, 2019-11-06 (wwlk)
-
General clean-up/spec updates
-
Added issues
-
-
Revision 3, 2019-11-07 (wwlk)
-
Typos
-
Additional issues
-
Clarified that a shader resolve subpass is the last subpass in a subpass dependency chain
-
-
Revision 4, 2020-01-06 (wwlk)
-
Change resolution of Issue 1 (render_pass, not renderpass)
-
VK_QCOM_render_pass_store_ops
- Name String
-
VK_QCOM_render_pass_store_ops - Extension Type
-
Device extension
- Registered Extension Number
-
302
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Contact
-
-
Bill Licea-Kane wwlk
-
Other Extension Metadata
- Last Modified Date
-
2020-03-25
- Contributors
-
-
Bill Licea-Kane, Qualcomm Technologies, Inc.
-
Description
Renderpass attachments can be read-only for the duration of a render pass.
Examples include input attachments and depth attachments where depth tests are enabled but depth writes are not enabled.
In such cases, there can be no contents generated for an attachment within the render area.
This extension adds a new VkAttachmentStoreOp
VK_ATTACHMENT_STORE_OP_NONE_QCOM specifying that the contents within
the render area may not be written to memory, but that the prior contents
of the attachment in memory are preserved.
However, if any contents were generated within the render area during
rendering, the contents of the attachment will be undefined inside the
render area.
|
Note
The VkAttachmentStoreOp |
New Enum Constants
-
VK_QCOM_RENDER_PASS_STORE_OPS_EXTENSION_NAME -
VK_QCOM_RENDER_PASS_STORE_OPS_SPEC_VERSION -
Extending VkAttachmentStoreOp:
-
VK_ATTACHMENT_STORE_OP_NONE_QCOM
-
Version History
-
Revision 1, 2019-12-20 (wwlk)
-
Initial version
-
-
Revision 2, 2020-03-25 (wwlk)
-
Minor renaming
-
VK_QCOM_render_pass_transform
- Name String
-
VK_QCOM_render_pass_transform - Extension Type
-
Device extension
- Registered Extension Number
-
283
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality -
Requires
VK_KHR_surfaceto be enabled for any device-level functionality
-
- Contact
-
-
Jeff Leger jackohound
-
Other Extension Metadata
- Last Modified Date
-
2021-03-09
- Interactions and External Dependencies
-
-
This extension requires
VK_KHR_swapchain -
This extension interacts with
VK_EXT_fragment_density_map -
This extension interacts with
VK_KHR_fragment_shading_rate
-
- Contributors
-
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Brandon Light, Qualcomm Technologies, Inc.
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Description
This extension provides a mechanism for applications to enable driver support for render pass transform.
Mobile devices can be rotated and mobile applications need to render properly when a device is held in a landscape or portrait orientation. When the current orientation differs from the device’s native orientation, a rotation is required so that the “up” direction of the rendered scene matches the current orientation.
If the Display Processing Unit (DPU) doesnt natively support rotation, the Vulkan presentation engine can handle this rotation in a separate composition pass. Alternatively, the application can render frames “pre-rotated” to avoid this extra pass. The latter is preferred to reduce power consumption and achieve the best performance because it avoids tasking the GPU with extra work to perform the copy/rotate operation.
Unlike OpenGL ES, the burden of pre-rotation in Vulkan falls on the application. To implement pre-rotation, applications render into swapchain images matching the device native aspect ratio of the display and “pre-rotate” the rendering content to match the device’s current orientation. The burden is more than adjusting the Model View Projection (MVP) matrix in the vertex shader to account for rotation and aspect ratio. The coordinate systems of scissors, viewports, derivatives and several shader built-ins may need to be adapted to produce the correct result.
It is difficult for some game engines to manage this burden; many chose to simply accept the performance/power overhead of performing rotation in the presentation engine.
This extension allows applications to achieve the performance benefits of pre-rotated rendering by moving much of the above-mentioned burden to the graphics driver. The following is unchanged with this extension:
-
Applications create a swapchain matching the native orientation of the display. Applications must also set the VkSwapchainCreateInfoKHR::
preTransformequal to thecurrentTransformas returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR.
The following is changed with this extension:
-
At vkCmdBeginRenderPass, the application provides extension struct VkRenderPassTransformBeginInfoQCOM specifying the render pass transform parameters.
-
At vkBeginCommandBuffer for secondary command buffers, the application provides extension struct VkCommandBufferInheritanceRenderPassTransformInfoQCOM specifying the render pass transform parameters.
-
The
renderArea, viewports, scissors, andfragmentSizeare all provided in the current (non-rotated) coordinate system. The implementation will transform those into the native (rotated) coordinate system. -
The implementation is responsible for transforming shader built-ins (
FragCoord,PointCoord,SamplePosition,PrimitiveShadingRateKHR, interpolateAt(), dFdx, dFdy, fWidth) into the rotated coordinate system. -
The implementation is responsible for transforming
positionto the rotated coordinate system.
New Enum Constants
-
VK_QCOM_RENDER_PASS_TRANSFORM_EXTENSION_NAME -
VK_QCOM_RENDER_PASS_TRANSFORM_SPEC_VERSION -
Extending VkRenderPassCreateFlagBits:
-
VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDER_PASS_TRANSFORM_INFO_QCOM -
VK_STRUCTURE_TYPE_RENDER_PASS_TRANSFORM_BEGIN_INFO_QCOM
-
Issues
1) Some early Adreno drivers (October 2019 through March 2020) advertised support for this extension but expected VK_STRUCTURE_TYPE values different from those in the vukan headers. To cover all Adreno devices on the market, applications need to detect the driver version and use the appropriate VK_STRUCTURE_TYPE values from the table below.
The driver version reported in VkPhysicalDeviceProperties.driverVersion is a
uint32_t type.
You can decode the uint32_t value into a major.minor.patch version as
shown below:
uint32_t major = ((driverVersion) >> 22);
uint32_t minor = ((driverVersion) >> 12) & 0x3ff);
uint32_t patch = ((driverVersion) & 0xfff);
If the Adreno major.minor.patch version is greater than or equal to to 512.469.0, then simply use the VK_STRUCTURE_TYPE values as defined in vulkan_core.h. If the version is less than or equal to to 512.468.0, then use the alternate values for the two VK_STRUCTURE_TYPEs in the table below.
| Adreno Driver Version | ||
|---|---|---|
512.468.0 and earlier |
512.469.0 and later |
|
VK_STRUCTURE_TYPE_ RENDER_PASS_TRANSFORM_BEGIN_INFO_QCOM |
1000282000 |
1000282001 |
VK_STRUCTURE_TYPE_ COMMAND_BUFFER_INHERITANCE_RENDER_PASS_TRANSFORM_INFO_QCOM |
1000282001 |
1000282000 |
2) Should the extension support only rotations (e.g. 90, 180, 270-degrees), or also mirror transforms (e.g. vertical flips)? Mobile use-cases only require rotation. Other display systems such as projectors might require a flipped transform.
RESOLVED: In this version of the extension, the functionality is restricted to 90, 180, and 270-degree rotations to address mobile use-cases.
3) How does this extension interact with VK_EXT_fragment_density_map?
RESOLVED Some implementations may not be able to support a render pass that enables both render pass transform and fragment density maps. For simplicity, this extension disallows enabling both features within a single render pass.
4) What should this extension be named?
We considered names such as “rotated_rendering”, “pre_rotation” and others. Since the functionality is limited to a render pass, it seemed the name should include “render_pass”. While the current extension is limited to rotations, it could be extended to other transforms (like mirror) in the future.
RESOLVED The name “render_pass_transform” seems like the most accurate description of the introduced functionality.
5) How does this extension interact with VK_KHR_fragment_shading_rate?
RESOLVED: For the same reasons as issue 3, this extension disallows
enabling both pFragmentShadingRateAttachment and render pass transform
within a single render pass.
However, pipeline shading rate and primitive shading rate are supported, and
their respective fragmentSize and PrimitiveShadingRateKHR are
provided in the current (non-rotated) coordinate system.
The implementation is responsible for transforming them to the rotated
coordinate system.
The set of supported shading rates may be different per transform. Supported rates queried from vkGetPhysicalDeviceFragmentShadingRatesKHR are in the native (rotated) coordinate system. This means that the application must swap the x/y of the reported rates to get the set of rates supported for 90 and 270 degree rotation.
Version History
-
Revision 1, 2020-02-05 (Jeff Leger)
-
Revision 2, 2021-03-09 (Matthew Netsch)
-
Adds interactions with VK_KHR_fragment_shading_rate
-
VK_QCOM_rotated_copy_commands
- Name String
-
VK_QCOM_rotated_copy_commands - Extension Type
-
Device extension
- Registered Extension Number
-
334
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_swapchainto be enabled for any device-level functionality -
Requires
VK_KHR_copy_commands2to be enabled for any device-level functionality
-
- Contact
-
-
Jeff Leger jackohound
-
Other Extension Metadata
- Last Modified Date
-
2020-09-18
- Interactions and External Dependencies
-
-
None
-
- Contributors
-
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Description
This extension extends adds an optional rotation transform to copy commands vkCmdBlitImage2KHR, vkCmdCopyImageToBuffer2KHR and vkCmdCopyBufferToImage2KHR. When copying between two resources, where one resource contains rotated content and the other does not, a rotated copy may be desired. This extension may be used in combination with VK_QCOM_render_pass_transform which adds rotated render passes.
This extension adds an extension structure to the following commands: vkCmdBlitImage2KHR, vkCmdCopyImageToBuffer2KHR and vkCmdCopyBufferToImage2KHR
Issues
1) What is an appropriate name for the added extension structure? The style
guide says “Structures which extend other structures through the
pNext chain should reflect the name of the base structure they
extend.”, but in this case a single extension structure is used to extend
three base structures (vkCmdBlitImage2KHR, vkCmdCopyImageToBuffer2KHR and
vkCmdCopyBufferToImage2KHR).
Creating three identical structures with unique names seemed undesirable.
RESOLVED: Deviate from the style guide for extension structure naming.
2) Should this extension add a rotation capability to vkCmdCopyImage2KHR?
RESOLVED: No. Use of rotated vkCmdBlitImage2KHR can fully address this use-case.
3) Should this extension add a rotation capability to vkCmdResolveImage2KHR?
RESOLVED No. Use of vkCmdResolveImage2KHR is very slow and extremely bandwidth intensive on Qualcomm’s GPU architecture and use of pResolveAttachments in vkRenderPass is the strongly preferred approach. Therefore, we choose not to introduce a rotation capability to vkCmdResolveImage2KHR.
New Enum Constants
-
VK_QCOM_ROTATED_COPY_COMMANDS_EXTENSION_NAME -
VK_QCOM_ROTATED_COPY_COMMANDS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COPY_COMMAND_TRANSFORM_INFO_QCOM
-
VK_QNX_screen_surface
- Name String
-
VK_QNX_screen_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
379
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Contact
-
-
Mike Gorchak mgorchak-blackberry
-
Other Extension Metadata
- Last Modified Date
-
2021-01-11
- IP Status
-
No known IP claims.
- Contributors
-
-
Mike Gorchak, BlackBerry Limited
-
Description
The VK_QNX_screen_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) that refers to a QNX Screen
window, as well as a query to determine support for rendering to a QNX
Screen compositor.
New Enum Constants
-
VK_QNX_SCREEN_SURFACE_EXTENSION_NAME -
VK_QNX_SCREEN_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SCREEN_SURFACE_CREATE_INFO_QNX
-
VK_VALVE_descriptor_set_host_mapping
- Name String
-
VK_VALVE_descriptor_set_host_mapping - Extension Type
-
Device extension
- Registered Extension Number
-
421
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Special Use
- Contact
-
-
Hans-Kristian Arntzen HansKristian-Work
-
Other Extension Metadata
- Last Modified Date
-
2022-02-22
- IP Status
-
No known IP claims.
- Contributors
-
-
Hans-Kristian Arntzen, Valve
-
Description
This extension allows applications to directly query a host pointer for a VkDescriptorSet which can be used to copy descriptors between descriptor sets without the use of an API command. Memory offsets and sizes for descriptors can be queried from a VkDescriptorSetLayout as well.
|
Note
There is currently no specification language written for this extension. The links to APIs defined by the extension are to stubs that only include generated content such as API declarations and implicit valid usage statements. |
|
Note
This extension is only intended for use in specific embedded environments with known implementation details, and is therefore undocumented. |
New Enum Constants
-
VK_VALVE_DESCRIPTOR_SET_HOST_MAPPING_EXTENSION_NAME -
VK_VALVE_DESCRIPTOR_SET_HOST_MAPPING_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_BINDING_REFERENCE_VALVE -
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_HOST_MAPPING_INFO_VALVE -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_SET_HOST_MAPPING_FEATURES_VALVE
-
Stub API References
There is currently no specification language written for this command. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_VALVE_descriptor_set_host_mapping
void vkGetDescriptorSetLayoutHostMappingInfoVALVE(
VkDevice device,
const VkDescriptorSetBindingReferenceVALVE* pBindingReference,
VkDescriptorSetLayoutHostMappingInfoVALVE* pHostMapping);
There is currently no specification language written for this command. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_VALVE_descriptor_set_host_mapping
void vkGetDescriptorSetHostMappingVALVE(
VkDevice device,
VkDescriptorSet descriptorSet,
void** ppData);
There is currently no specification language written for this type. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_VALVE_descriptor_set_host_mapping
typedef struct VkPhysicalDeviceDescriptorSetHostMappingFeaturesVALVE {
VkStructureType sType;
void* pNext;
VkBool32 descriptorSetHostMapping;
} VkPhysicalDeviceDescriptorSetHostMappingFeaturesVALVE;
There is currently no specification language written for this type. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_VALVE_descriptor_set_host_mapping
typedef struct VkDescriptorSetBindingReferenceVALVE {
VkStructureType sType;
const void* pNext;
VkDescriptorSetLayout descriptorSetLayout;
uint32_t binding;
} VkDescriptorSetBindingReferenceVALVE;
There is currently no specification language written for this type. This section acts only as placeholder and to avoid dead links in the specification and reference pages.
// Provided by VK_VALVE_descriptor_set_host_mapping
typedef struct VkDescriptorSetLayoutHostMappingInfoVALVE {
VkStructureType sType;
void* pNext;
size_t descriptorOffset;
uint32_t descriptorSize;
} VkDescriptorSetLayoutHostMappingInfoVALVE;
VK_VALVE_mutable_descriptor_type
- Name String
-
VK_VALVE_mutable_descriptor_type - Extension Type
-
Device extension
- Registered Extension Number
-
352
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_maintenance3to be enabled for any device-level functionality
-
- Special Use
- Contact
-
-
Joshua Ashton Joshua-Ashton
-
Hans-Kristian Arntzen HansKristian-Work
-
Other Extension Metadata
- Last Modified Date
-
2020-12-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Ashton, Valve
-
Hans-Kristian Arntzen, Valve
-
Description
This extension allows applications to reduce descriptor memory footprint by allowing a descriptor to be able to mutate to a given list of descriptor types depending on which descriptor types are written into, or copied into a descriptor set.
The main use case this extension intends to address is descriptor indexing
with VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT where the
descriptor types are completely generic, as this means applications can
allocate one large descriptor set, rather than having one large descriptor
set per descriptor type, which significantly bloats descriptor memory usage
and causes performance issues.
This extension also adds a mechanism to declare that a descriptor pool, and therefore the descriptor sets that are allocated from it, reside only in host memory; as such these descriptors can only be updated/copied, but not bound.
These features together allow much more efficient emulation of the raw D3D12 binding model. This extension is primarily intended to be useful for API layering efforts.
New Enum Constants
-
VK_VALVE_MUTABLE_DESCRIPTOR_TYPE_EXTENSION_NAME -
VK_VALVE_MUTABLE_DESCRIPTOR_TYPE_SPEC_VERSION -
Extending VkDescriptorPoolCreateFlagBits:
-
VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE
-
-
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE
-
-
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_MUTABLE_VALVE
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MUTABLE_DESCRIPTOR_TYPE_CREATE_INFO_VALVE -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MUTABLE_DESCRIPTOR_TYPE_FEATURES_VALVE
-
List of Provisional Extensions
VK_KHR_portability_subset
- Name String
-
VK_KHR_portability_subset - Extension Type
-
Device extension
- Registered Extension Number
-
164
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Contact
-
-
Bill Hollings billhollings
-
Other Extension Metadata
- Last Modified Date
-
2020-07-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Bill Hollings, The Brenwill Workshop Ltd.
-
Daniel Koch, NVIDIA
-
Dzmitry Malyshau, Mozilla
-
Chip Davis, CodeWeavers
-
Dan Ginsburg, Valve
-
Mike Weiblen, LunarG
-
Neil Trevett, NVIDIA
-
Alexey Knyazev, Independent
-
Description
The `VK_KHR_portability_subset extension allows a non-conformant Vulkan implementation to be built on top of another non-Vulkan graphics API, and identifies differences between that implementation and a fully-conformant native Vulkan implementation.
This extension provides Vulkan implementations with the ability to mark otherwise-required capabilities as unsupported, or to establish additional properties and limits that the application should adhere to in order to guarantee portable behaviour and operation across platforms, including platforms where Vulkan is not natively supported.
The goal of this specification is to document, and make queryable, capabilities which are required to be supported by a fully-conformant Vulkan 1.0 implementation, but may be optional for an implementation of the Vulkan 1.0 Portability Subset.
The intent is that this extension will be advertised only on implementations of the Vulkan 1.0 Portability Subset, and not on conformant implementations of Vulkan 1.0. Fully-conformant Vulkan implementations provide all the required capabilies, and so will not provide this extension. Therefore, the existence of this extension can be used to determine that an implementation is likely not fully conformant with the Vulkan spec.
If this extension is supported by the Vulkan implementation, the application must enable this extension.
This extension defines several new structures that can be chained to the existing structures used by certain standard Vulkan calls, in order to query for non-conformant portable behavior.
New Enum Constants
-
VK_KHR_PORTABILITY_SUBSET_EXTENSION_NAME -
VK_KHR_PORTABILITY_SUBSET_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PORTABILITY_SUBSET_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PORTABILITY_SUBSET_PROPERTIES_KHR
-
VK_KHR_video_decode_queue
- Name String
-
VK_KHR_video_decode_queue - Extension Type
-
Device extension
- Registered Extension Number
-
25
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_video_queueto be enabled for any device-level functionality -
Requires
VK_KHR_synchronization2to be enabled for any device-level functionality -
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Contact
Other Extension Metadata
- Last Modified Date
-
2022-03-31
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Jake Beju, AMD
-
Olivier Lapicque, NVIDIA
-
Peter Fang, AMD
-
Piers Daniell, NVIDIA
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
New Enum Constants
-
VK_KHR_VIDEO_DECODE_QUEUE_EXTENSION_NAME -
VK_KHR_VIDEO_DECODE_QUEUE_SPEC_VERSION -
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR -
VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR -
VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_VIDEO_DECODE_DPB_BIT_KHR -
VK_FORMAT_FEATURE_VIDEO_DECODE_OUTPUT_BIT_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR -
VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR -
VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR
-
-
Extending VkQueueFlagBits:
-
VK_QUEUE_VIDEO_DECODE_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_DECODE_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR
-
If VK_KHR_format_feature_flags2 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_VIDEO_DECODE_DPB_BIT_KHR -
VK_FORMAT_FEATURE_2_VIDEO_DECODE_OUTPUT_BIT_KHR
-
Version History
-
Revision 1, 2018-6-11 (Peter Fang)
-
Initial draft
-
-
Revision 1.5, Nov 09 2018 (Tony Zlatinski)
-
API Updates
-
-
Revision 1.6, Jan 08 2020 (Tony Zlatinski)
-
API unify with the video_encode_queue spec
-
-
Revision 1.7, March 29 2021 (Tony Zlatinski)
-
Spec and API updates.
-
-
Revision 2, September 30 2021 (Jon Leech)
-
Add interaction with
VK_KHR_format_feature_flags2tovk.xml
-
-
Revision 3, 2022-02-25 (Ahmed Abdelkhalek)
-
Add VkVideoDecodeCapabilitiesKHR with new flags to report support for decode DPB and output coinciding in the same image, or in distinct images.
-
-
Revision 4, 2022-03-31 (Ahmed Abdelkhalek)
-
Remove redundant VkVideoDecodeInfoKHR.coded{Offset|Extent}
-
VK_KHR_video_encode_queue
- Name String
-
VK_KHR_video_encode_queue - Extension Type
-
Device extension
- Registered Extension Number
-
300
- Revision
-
5
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_video_queueto be enabled for any device-level functionality -
Requires
VK_KHR_synchronization2to be enabled for any device-level functionality -
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Contact
-
-
Ahmed Abdelkhalek aabdelkh
-
Other Extension Metadata
- Last Modified Date
-
2022-03-31
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Damien Kessler, NVIDIA
-
Daniel Rakos, AMD
-
George Hao, AMD
-
Jake Beju, AMD
-
Peter Fang, AMD
-
Piers Daniell, NVIDIA
-
Srinath Kumarapuram, NVIDIA
-
Thomas J. Meier, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Yang Liu, AMD
-
New Enum Constants
-
VK_KHR_VIDEO_ENCODE_QUEUE_EXTENSION_NAME -
VK_KHR_VIDEO_ENCODE_QUEUE_SPEC_VERSION -
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR -
VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR -
VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_VIDEO_ENCODE_DPB_BIT_KHR -
VK_FORMAT_FEATURE_VIDEO_ENCODE_INPUT_BIT_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_VIDEO_ENCODE_BITSTREAM_BUFFER_RANGE_KHR
-
-
Extending VkQueueFlagBits:
-
VK_QUEUE_VIDEO_ENCODE_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_ENCODE_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_LAYER_INFO_KHR
-
If VK_KHR_format_feature_flags2 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_DPB_BIT_KHR -
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_INPUT_BIT_KHR
-
Version History
-
Revision 1, 2018-07-23 (Ahmed Abdelkhalek)
-
Initial draft
-
-
Revision 1.1, 10/29/2019 (Tony Zlatinski)
-
Updated the reserved spec tokens and renamed VkVideoEncoderKHR to VkVideoSessionKHR
-
-
Revision 1.6, Jan 08 2020 (Tony Zlatinski)
-
API unify with the video_decode_queue spec
-
-
Revision 2, March 29 2021 (Tony Zlatinski)
-
Spec and API updates.
-
-
Revision 3, 2021-09-30 (Jon Leech)
-
Add interaction with
VK_KHR_format_feature_flags2tovk.xml
-
-
Revision 4, 2022-02-10 (Ahmed Abdelkhalek)
-
Updates to encode capability interface
-
-
Revision 5, 2022-03-31 (Ahmed Abdelkhalek)
-
Remove redundant VkVideoEncodeInfoKHR.codedExtent
-
VK_KHR_video_queue
- Name String
-
VK_KHR_video_queue - Extension Type
-
Device extension
- Registered Extension Number
-
24
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_synchronization2to be enabled for any device-level functionality -
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Contact
-
-
Tony Zlatinski tzlatinski
-
Other Extension Metadata
- Last Modified Date
-
2022-05-30
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
George Hao, AMD
-
Jake Beju, AMD
-
Piers Daniell, NVIDIA
-
Srinath Kumarapuram, NVIDIA
-
Tobias Hector, AMD
-
Tony Zlatinski, NVIDIA
-
Daniel Rakos, RasterGrid
-
New Structures
-
Extending VkPhysicalDeviceImageFormatInfo2, VkPhysicalDeviceVideoFormatInfoKHR, VkImageCreateInfo, VkBufferCreateInfo:
-
Extending VkQueryPoolCreateInfo:
-
Extending VkQueueFamilyProperties2:
New Enum Constants
-
VK_KHR_VIDEO_QUEUE_EXTENSION_NAME -
VK_KHR_VIDEO_QUEUE_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_VIDEO_SESSION_KHR -
VK_OBJECT_TYPE_VIDEO_SESSION_PARAMETERS_KHR
-
-
Extending VkQueryResultFlagBits:
-
VK_QUERY_RESULT_WITH_STATUS_BIT_KHR
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR
-
-
Extending VkResult:
-
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR -
VK_ERROR_VIDEO_PICTURE_LAYOUT_NOT_SUPPORTED_KHR -
VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHR -
VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHR -
VK_ERROR_VIDEO_PROFILE_OPERATION_NOT_SUPPORTED_KHR -
VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_FORMAT_INFO_KHR -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_QUERY_RESULT_STATUS_PROPERTIES_2_KHR -
VK_STRUCTURE_TYPE_VIDEO_BEGIN_CODING_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_BIND_MEMORY_KHR -
VK_STRUCTURE_TYPE_VIDEO_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_CODING_CONTROL_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_END_CODING_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_FORMAT_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_GET_MEMORY_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_PICTURE_RESOURCE_KHR -
VK_STRUCTURE_TYPE_VIDEO_PROFILES_KHR -
VK_STRUCTURE_TYPE_VIDEO_PROFILE_KHR -
VK_STRUCTURE_TYPE_VIDEO_QUEUE_FAMILY_PROPERTIES_2_KHR -
VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_KHR -
VK_STRUCTURE_TYPE_VIDEO_SESSION_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_UPDATE_INFO_KHR
-
Version History
-
Revision 0.1, 2019-11-21 (Tony Zlatinski)
-
Initial draft
-
-
Revision 0.2, 2019-11-27 (Tony Zlatinski)
-
Make vulkan video core common between decode and encode
-
-
Revision 1, March 29 2021 (Tony Zlatinski)
-
Spec and API updates.
-
-
Revision 2, August 1 2021 (Srinath Kumarapuram)
-
Rename
VkVideoCapabilitiesFlagBitsKHRtoVkVideoCapabilityFlagBitsKHR(along with the names of enumerants it defines) andVkVideoCapabilitiesFlagsKHRtoVkVideoCapabilityFlagsKHR, following Vulkan naming conventions.
-
-
Revision 3, 2022-03-16 (Ahmed Abdelkhalek)
-
Relocate Std header version reporting/requesting from codec-operation specific extensions to this extension.
-
Make Std header versions codec-operation specific instead of only codec-specific.
-
-
Revision 4, 2022-05-30 (Daniel Rakos)
-
Refactor the video format query APIs and related language
-
Extend VkResult with video-specific error codes
-
VK_EXT_video_decode_h264
- Name String
-
VK_EXT_video_decode_h264 - Extension Type
-
Device extension
- Registered Extension Number
-
41
- Revision
-
5
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_video_decode_queueto be enabled for any device-level functionality -
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Contact
Other Extension Metadata
- Last Modified Date
-
2022-03-31
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Chunbo Chen, Intel
-
HoHin Lau, AMD
-
Jake Beju, AMD
-
Peter Fang, AMD
-
Ping Liu, Intel
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
New Structures
-
Extending VkVideoDecodeCapabilitiesKHR:
-
Extending VkVideoDecodeH264PictureInfoEXT:
-
Extending VkVideoDecodeInfoKHR:
-
Extending VkVideoProfileKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoReferenceSlotKHR:
-
Extending VkVideoSessionParametersCreateInfoKHR:
-
Extending VkVideoSessionParametersUpdateInfoKHR:
New Enum Constants
-
VK_EXT_VIDEO_DECODE_H264_EXTENSION_NAME -
VK_EXT_VIDEO_DECODE_H264_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_CAPABILITIES_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_DPB_SLOT_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_MVC_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PICTURE_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PROFILE_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_ADD_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_CREATE_INFO_EXT
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_EXT
-
Version History
-
Revision 1, 2018-6-11 (Peter Fang)
-
Initial draft
-
-
Revision 2, March 29 2021 (Tony Zlatinski)
-
Spec and API Updates
-
-
Revision 3, August 1 2021 (Srinath Kumarapuram)
-
Rename
VkVideoDecodeH264FieldLayoutFlagsEXTtoVkVideoDecodeH264PictureLayoutFlagsEXT,VkVideoDecodeH264FieldLayoutFlagBitsEXTtoVkVideoDecodeH264PictureLayoutFlagBitsEXT(along with the names of enumerants it defines), andVkVideoDecodeH264ProfileEXT.fieldLayouttoVkVideoDecodeH264ProfileEXT.pictureLayout, following Vulkan naming conventions.
-
-
Revision 4, 2022-03-16 (Ahmed Abdelkhalek)
-
Relocate Std header version reporting/requesting from this extension to VK_KHR_video_queue extension.
-
Remove the now empty VkVideoDecodeH264SessionCreateInfoEXT.
-
-
Revision 5, 2022-03-31 (Ahmed Abdelkhalek)
-
Use type StdVideoH264Level for VkVideoDecodeH264Capabilities.maxLevel
-
VK_EXT_video_decode_h265
- Name String
-
VK_EXT_video_decode_h265 - Extension Type
-
Device extension
- Registered Extension Number
-
188
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_video_decode_queueto be enabled for any device-level functionality -
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Contact
Other Extension Metadata
- Last Modified Date
-
2022-03-31
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
HoHin Lau, AMD
-
Jake Beju, AMD
-
Peter Fang, AMD
-
Ping Liu, Intel
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
New Structures
-
Extending VkVideoDecodeCapabilitiesKHR:
-
Extending VkVideoDecodeInfoKHR:
-
Extending VkVideoProfileKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoReferenceSlotKHR:
-
Extending VkVideoSessionParametersCreateInfoKHR:
-
Extending VkVideoSessionParametersUpdateInfoKHR:
New Enum Constants
-
VK_EXT_VIDEO_DECODE_H265_EXTENSION_NAME -
VK_EXT_VIDEO_DECODE_H265_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_CAPABILITIES_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_DPB_SLOT_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PICTURE_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PROFILE_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_ADD_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_CREATE_INFO_EXT
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_EXT
-
Version History
-
Revision 1, 2018-6-11 (Peter Fang)
-
Initial draft
-
-
Revision 1.6, March 29 2021 (Tony Zlatinski)
-
Spec and API updates.
-
-
Revision 2, 2022-03-16 (Ahmed Abdelkhalek)
-
Relocate Std header version reporting/requesting from this extension to VK_KHR_video_queue extension.
-
Remove the now empty VkVideoDecodeH265SessionCreateInfoEXT.
-
-
Revision 3, 2022-03-31 (Ahmed Abdelkhalek)
-
Use type StdVideoH265Level for VkVideoDecodeH265Capabilities.maxLevel
-
VK_EXT_video_encode_h264
- Name String
-
VK_EXT_video_encode_h264 - Extension Type
-
Device extension
- Registered Extension Number
-
39
- Revision
-
7
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_video_encode_queueto be enabled for any device-level functionality -
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Contact
-
-
Ahmed Abdelkhalek aabdelkh
-
Other Extension Metadata
- Last Modified Date
-
2022-04-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Daniel Rakos, AMD
-
George Hao, AMD
-
Jake Beju, AMD
-
Peter Fang, AMD
-
Ping Liu, Intel
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Yang Liu, AMD
-
Description
This extension allows applications to compress a raw video sequence by using the H.264/AVC video compression standard.
New Structures
-
Extending VkVideoEncodeCapabilitiesKHR:
-
Extending VkVideoEncodeInfoKHR:
-
Extending VkVideoEncodeRateControlInfoKHR:
-
Extending VkVideoEncodeRateControlLayerInfoKHR:
-
Extending VkVideoProfileKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoSessionParametersCreateInfoKHR:
-
Extending VkVideoSessionParametersUpdateInfoKHR:
New Enum Constants
-
VK_EXT_VIDEO_ENCODE_H264_EXTENSION_NAME -
VK_EXT_VIDEO_ENCODE_H264_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_CAPABILITIES_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_DPB_SLOT_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_EMIT_PICTURE_PARAMETERS_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_NALU_SLICE_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PROFILE_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_LAYER_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_REFERENCE_LISTS_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_ADD_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_VCL_FRAME_INFO_EXT
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT
-
Version History
-
Revision 0, 2018-7-23 (Ahmed Abdelkhalek)
-
Initial draft
-
-
Revision 0.5, 2020-02-13 (Tony Zlatinski)
-
General Spec cleanup
-
Added DPB structures
-
Change the VCL frame encode structure
-
Added a common Non-VCL Picture Paramarameters structure
-
-
Revision 1, 2021-03-29 (Tony Zlatinski)
-
Spec and API updates
-
-
Revision 2, August 1 2021 (Srinath Kumarapuram)
-
Rename
VkVideoEncodeH264CapabilitiesFlagsEXTtoVkVideoEncodeH264CapabilityFlagsEXTandVkVideoEncodeH264CapabilitiesFlagsEXTtoVkVideoEncodeH264CapabilityFlagsEXT, following Vulkan naming conventions.
-
-
Revision 3, 2021-12-08 (Ahmed Abdelkhalek)
-
Rate control updates
-
-
Revision 4, 2022-02-04 (Ahmed Abdelkhalek)
-
Align VkVideoEncodeH264VclFrameInfoEXT structure to similar one in VK_EXT_video_encode_h265 extension
-
-
Revision 5, 2022-02-10 (Ahmed Abdelkhalek)
-
Updates to encode capability interface
-
-
Revision 6, 2022-03-16 (Ahmed Abdelkhalek)
-
Relocate Std header version reporting/requesting from this extension to VK_KHR_video_queue extension.
-
Remove redundant maxPictureSizeInMbs from VkVideoEncodeH264SessionCreateInfoEXT.
-
Remove the now empty VkVideoEncodeH264SessionCreateInfoEXT.
-
-
Revision 7, 2022-04-06 (Ahmed Abdelkhalek)
-
Add capability flag to report support to use B frame in L1 reference list.
-
Add capability flag to report support for disabling SPS direct_8x8_inference_flag.
-
VK_EXT_video_encode_h265
- Name String
-
VK_EXT_video_encode_h265 - Extension Type
-
Device extension
- Registered Extension Number
-
40
- Revision
-
7
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_video_encode_queueto be enabled for any device-level functionality -
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Contact
-
-
Ahmed Abdelkhalek aabdelkh
-
Other Extension Metadata
- Last Modified Date
-
2022-03-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
George Hao, AMD
-
Jake Beju, AMD
-
Chunbo Chen, Intel
-
Ping Liu, Intel
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Description
This extension allows applications to compress a raw video sequence by using the H.265/HEVC video compression standard.
New Structures
-
Extending VkVideoEncodeCapabilitiesKHR:
-
Extending VkVideoEncodeInfoKHR:
-
Extending VkVideoEncodeRateControlInfoKHR:
-
Extending VkVideoEncodeRateControlLayerInfoKHR:
-
Extending VkVideoProfileKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoSessionParametersCreateInfoKHR:
-
Extending VkVideoSessionParametersUpdateInfoKHR:
New Enum Constants
-
VK_EXT_VIDEO_ENCODE_H265_EXTENSION_NAME -
VK_EXT_VIDEO_ENCODE_H265_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_CAPABILITIES_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_DPB_SLOT_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_EMIT_PICTURE_PARAMETERS_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_NALU_SLICE_SEGMENT_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PROFILE_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_LAYER_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_REFERENCE_LISTS_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_ADD_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_VCL_FRAME_INFO_EXT
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT
-
Version History
-
Revision 0, 2019-11-14 (Ahmed Abdelkhalek)
-
Initial draft
-
-
Revision 0.5, 2020-02-13 (Tony Zlatinski)
-
General Spec cleanup
-
Added DPB structures
-
Change the VCL frame encode structure
-
Added a common Non-VCL Picture Paramarameters structure
-
-
Revision 2, Oct 10 2021 (Srinath Kumarapuram)
-
Vulkan Video Encode h.265 update and spec edits
-
-
Revision 3, 2021-12-08 (Ahmed Abdelkhalek)
-
Rate control updates
-
-
Revision 4, 2022-01-11 (Ahmed Abdelkhalek)
-
Replace occurrences of “slice” by “slice segment” and rename structures/enums to reflect this.
-
-
Revision 5, 2022-02-10 (Ahmed Abdelkhalek)
-
Updates to encode capability interface
-
-
Revision 6, 2022-03-16 (Ahmed Abdelkhalek)
-
Relocate Std header version reporting/requesting from this extension to VK_KHR_video_queue extension.
-
Remove the now empty VkVideoEncodeH265SessionCreateInfoEXT.
-
-
Revision 7, 2022-03-24 (Ahmed Abdelkhalek)
-
Add capability flags to report support to disable transform skip and support to use B frame in L1 reference list.
-
List of Deprecated Extensions
VK_KHR_16bit_storage
- Name String
-
VK_KHR_16bit_storage - Extension Type
-
Device extension
- Registered Extension Number
-
84
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_storage_buffer_storage_classto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
This extension requires
SPV_KHR_16bit_storage -
This extension provides API support for
GL_EXT_shader_16bit_storage
-
- Contributors
-
-
Alexander Galazin, ARM
-
Jan-Harald Fredriksen, ARM
-
Joerg Wagner, ARM
-
Neil Henning, Codeplay
-
Jeff Bolz, Nvidia
-
Daniel Koch, Nvidia
-
David Neto, Google
-
John Kessenich, Google
-
Description
The VK_KHR_16bit_storage extension allows use of 16-bit types in shader
input and output interfaces, and push constant blocks.
This extension introduces several new optional features which map to SPIR-V
capabilities and allow access to 16-bit data in Block-decorated objects
in the Uniform and the StorageBuffer storage classes, and objects
in the PushConstant storage class.
This extension allows 16-bit variables to be declared and used as
user-defined shader inputs and outputs but does not change location
assignment and component assignment rules.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
However, if Vulkan 1.1 is supported and this extension is not, the
storageBuffer16BitAccess capability is optional.
The original type, enum and command names are still available as aliases of
the core functionality.
New Enum Constants
-
VK_KHR_16BIT_STORAGE_EXTENSION_NAME -
VK_KHR_16BIT_STORAGE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES_KHR
-
VK_KHR_8bit_storage
- Name String
-
VK_KHR_8bit_storage - Extension Type
-
Device extension
- Registered Extension Number
-
178
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_storage_buffer_storage_classto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Alexander Galazin alegal-arm
-
Other Extension Metadata
- Last Modified Date
-
2018-02-05
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
This extension requires
SPV_KHR_8bit_storage -
This extension provides API support for
GL_EXT_shader_16bit_storage
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Alexander Galazin, Arm
-
Description
The VK_KHR_8bit_storage extension allows use of 8-bit types in uniform and
storage buffers, and push constant blocks.
This extension introduces several new optional features which map to SPIR-V
capabilities and allow access to 8-bit data in Block-decorated objects
in the Uniform and the StorageBuffer storage classes, and objects
in the PushConstant storage class.
The StorageBuffer8BitAccess capability must be supported by all
implementations of this extension.
The other capabilities are optional.
Promotion to Vulkan 1.2
Functionality in this extension is included in core Vulkan 1.2, with the KHR
suffix omitted.
However, if Vulkan 1.2 is supported and this extension is not, the
StorageBuffer8BitAccess capability is optional.
The original type, enum and command names are still available as aliases of
the core functionality.
New Enum Constants
-
VK_KHR_8BIT_STORAGE_EXTENSION_NAME -
VK_KHR_8BIT_STORAGE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES_KHR
-
VK_KHR_bind_memory2
- Name String
-
VK_KHR_bind_memory2 - Extension Type
-
Device extension
- Registered Extension Number
-
158
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Tobias Hector, Imagination Technologies
-
Description
This extension provides versions of vkBindBufferMemory and vkBindImageMemory that allow multiple bindings to be performed at once, and are extensible.
This extension also introduces VK_IMAGE_CREATE_ALIAS_BIT_KHR, which
allows “identical” images that alias the same memory to interpret the
contents consistently, even across image layout changes.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_BIND_MEMORY_2_EXTENSION_NAME -
VK_KHR_BIND_MEMORY_2_SPEC_VERSION -
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_ALIAS_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO_KHR -
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO_KHR
-
Version History
-
Revision 1, 2017-05-19 (Tobias Hector)
-
Pulled bind memory functions into their own extension
-
VK_KHR_buffer_device_address
- Name String
-
VK_KHR_buffer_device_address - Extension Type
-
Device extension
- Registered Extension Number
-
258
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-24
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
This extension requires
SPV_KHR_physical_storage_buffer -
This extension provides API support for
GL_EXT_buffer_referenceandGL_EXT_buffer_reference2andGL_EXT_buffer_reference_uvec2
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Neil Henning, AMD
-
Tobias Hector, AMD
-
Jason Ekstrand, Intel
-
Baldur Karlsson, Valve
-
Jan-Harald Fredriksen, Arm
-
Description
This extension allows the application to query a 64-bit buffer device
address value for a buffer, which can be used to access the buffer memory
via the PhysicalStorageBuffer storage class in the
GL_EXT_buffer_reference
GLSL extension and
SPV_KHR_physical_storage_buffer
SPIR-V extension.
Another way to describe this extension is that it adds “pointers to buffer
memory in shaders”.
By calling vkGetBufferDeviceAddress with a VkBuffer, it will
return a VkDeviceAddress value which represents the address of the
start of the buffer.
vkGetBufferOpaqueCaptureAddress and
vkGetDeviceMemoryOpaqueCaptureAddress allow opaque addresses for
buffers and memory objects to be queried for the current process.
A trace capture and replay tool can then supply these addresses to be used
at replay time to match the addresses used when the trace was captured.
To enable tools to insert these queries, new memory allocation flags must be
specified for memory objects that will be bound to buffers accessed via the
PhysicalStorageBuffer storage class.
Note that this mechanism is intended only to support capture/replay tools,
and is not recommended for use in other applications.
There are various use cases this extension is designed for. It is required for ray tracing, useful for DX12 portability, and by allowing buffer addresses to be stored in memory it enables more complex data structures to be created.
This extension can also be used to hardcode a dedicated debug channel into all shaders by querying a pointer at startup and pushing that into shaders as a run-time constant (e.g. specialization constant) that avoids impacting other descriptor limits.
There are examples of usage in the
GL_EXT_buffer_reference
spec for how to use this in a high-level shading language such as GLSL.
The
GL_EXT_buffer_reference2
and
GL_EXT_buffer_reference_uvec2
extensions were also added to help cover a few additional edge cases.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the
KHR suffix omitted.
However, if Vulkan 1.2 is supported and this extension is not, the
bufferDeviceAddress feature is optional.
The original type, enum and command names are still available as aliases of
the core functionality.
Promotion to Vulkan 1.3
Support for the bufferDeviceAddress feature is mandatory in Vulkan 1.3,
regardless of whether this extension is supported.
New Structures
-
Extending VkBufferCreateInfo:
-
Extending VkMemoryAllocateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
New Enum Constants
-
VK_KHR_BUFFER_DEVICE_ADDRESS_EXTENSION_NAME -
VK_KHR_BUFFER_DEVICE_ADDRESS_SPEC_VERSION -
Extending VkBufferCreateFlagBits:
-
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_KHR
-
-
Extending VkMemoryAllocateFlagBits:
-
VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR -
VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR
-
-
Extending VkResult:
-
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO_KHR -
VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO_KHR -
VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_KHR
-
Version History
-
Revision 1, 2019-06-24 (Jan-Harald Fredriksen)
-
Internal revisions based on VK_EXT_buffer_device_address
-
VK_KHR_copy_commands2
- Name String
-
VK_KHR_copy_commands2 - Extension Type
-
Device extension
- Registered Extension Number
-
338
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Jeff Leger jackohound
-
Other Extension Metadata
- Last Modified Date
-
2020-07-06
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- Interactions and External Dependencies
-
-
None
-
- Contributors
-
-
Jeff Leger, Qualcomm
-
Tobias Hector, AMD
-
Jan-Harald Fredriksen, ARM
-
Tom Olson, ARM
-
Description
This extension provides extensible versions of the Vulkan buffer and image copy commands. The new commands are functionally identical to the core commands, except that their copy parameters are specified using extensible structures that can be used to pass extension-specific information.
The following extensible copy commands are introduced with this extension:
vkCmdCopyBuffer2KHR, vkCmdCopyImage2KHR,
vkCmdCopyBufferToImage2KHR, vkCmdCopyImageToBuffer2KHR,
vkCmdBlitImage2KHR, and vkCmdResolveImage2KHR.
Each command contains an *Info2KHR structure parameter that includes
sType/pNext members.
Lower level structures describing each region to be copied are also extended
with sType/pNext members.
New Enum Constants
-
VK_KHR_COPY_COMMANDS_2_EXTENSION_NAME -
VK_KHR_COPY_COMMANDS_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2_KHR -
VK_STRUCTURE_TYPE_BUFFER_COPY_2_KHR -
VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2_KHR -
VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2_KHR -
VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2_KHR -
VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2_KHR -
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2_KHR -
VK_STRUCTURE_TYPE_IMAGE_BLIT_2_KHR -
VK_STRUCTURE_TYPE_IMAGE_COPY_2_KHR -
VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2_KHR -
VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2_KHR
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
VK_KHR_create_renderpass2
- Name String
-
VK_KHR_create_renderpass2 - Extension Type
-
Device extension
- Registered Extension Number
-
110
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_multiviewto be enabled for any device-level functionality -
Requires
VK_KHR_maintenance2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Tobias Hector tobias
-
Other Extension Metadata
- Last Modified Date
-
2018-02-07
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Tobias Hector
-
Jeff Bolz
-
Description
This extension provides a new entry point to create render passes in a way
that can be easily extended by other extensions through the substructures of
render pass creation.
The Vulkan 1.0 render pass creation sub-structures do not include
sType/pNext members.
Additionally, the render pass begin/next/end commands have been augmented
with new extensible structures for passing additional subpass information.
The VkRenderPassMultiviewCreateInfo and VkInputAttachmentAspectReference structures that extended the original VkRenderPassCreateInfo are not accepted into the new creation functions, and instead their parameters are folded into this extension as follows:
-
Elements of VkRenderPassMultiviewCreateInfo::
pViewMasksare now specified in VkSubpassDescription2KHR::viewMask. -
Elements of VkRenderPassMultiviewCreateInfo::
pViewOffsetsare now specified in VkSubpassDependency2KHR::viewOffset. -
VkRenderPassMultiviewCreateInfo::
correlationMaskCountand VkRenderPassMultiviewCreateInfo::pCorrelationMasksare directly specified in VkRenderPassCreateInfo2KHR. -
VkInputAttachmentAspectReference::
aspectMaskis now specified in the relevant input attachment description in VkAttachmentDescription2KHR::aspectMask
The details of these mappings are explained fully in the new structures.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_CREATE_RENDERPASS_2_EXTENSION_NAME -
VK_KHR_CREATE_RENDERPASS_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2_KHR -
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2_KHR -
VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2_KHR -
VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO_KHR -
VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2_KHR -
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2_KHR -
VK_STRUCTURE_TYPE_SUBPASS_END_INFO_KHR
-
VK_KHR_dedicated_allocation
- Name String
-
VK_KHR_dedicated_allocation - Extension Type
-
Device extension
- Registered Extension Number
-
128
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_memory_requirements2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jason Ekstrand, Intel
-
Description
This extension enables resources to be bound to a dedicated allocation,
rather than suballocated.
For any particular resource, applications can query whether a dedicated
allocation is recommended, in which case using a dedicated allocation may
improve the performance of access to that resource.
Normal device memory allocations must support multiple resources per
allocation, memory aliasing and sparse binding, which could interfere with
some optimizations.
Applications should query the implementation for when a dedicated allocation
may be beneficial by adding a VkMemoryDedicatedRequirementsKHR
structure to the pNext chain of the VkMemoryRequirements2
structure passed as the pMemoryRequirements parameter of a call to
vkGetBufferMemoryRequirements2 or vkGetImageMemoryRequirements2.
Certain external handle types and external images or buffers may also
depend on dedicated allocations on implementations that associate image or
buffer metadata with OS-level memory objects.
This extension adds a two small structures to memory requirements querying and memory allocation: a new structure that flags whether an image/buffer should have a dedicated allocation, and a structure indicating the image or buffer that an allocation will be bound to.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_DEDICATED_ALLOCATION_EXTENSION_NAME -
VK_KHR_DEDICATED_ALLOCATION_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_KHR -
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS_KHR
-
Examples
// Create an image with a dedicated allocation based on the
// implementation's preference
VkImageCreateInfo imageCreateInfo =
{
// Image creation parameters
};
VkImage image;
VkResult result = vkCreateImage(
device,
&imageCreateInfo,
NULL, // pAllocator
&image);
VkMemoryDedicatedRequirementsKHR dedicatedRequirements =
{
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS_KHR,
NULL, // pNext
};
VkMemoryRequirements2 memoryRequirements =
{
VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2,
&dedicatedRequirements, // pNext
};
const VkImageMemoryRequirementsInfo2 imageRequirementsInfo =
{
VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2,
NULL, // pNext
image
};
vkGetImageMemoryRequirements2(
device,
&imageRequirementsInfo,
&memoryRequirements);
if (dedicatedRequirements.prefersDedicatedAllocation) {
// Allocate memory with VkMemoryDedicatedAllocateInfoKHR::image
// pointing to the image we are allocating the memory for
VkMemoryDedicatedAllocateInfoKHR dedicatedInfo =
{
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_KHR, // sType
NULL, // pNext
image, // image
VK_NULL_HANDLE, // buffer
};
VkMemoryAllocateInfo memoryAllocateInfo =
{
VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO, // sType
&dedicatedInfo, // pNext
memoryRequirements.size, // allocationSize
FindMemoryTypeIndex(memoryRequirements.memoryTypeBits), // memoryTypeIndex
};
VkDeviceMemory memory;
vkAllocateMemory(
device,
&memoryAllocateInfo,
NULL, // pAllocator
&memory);
// Bind the image to the memory
vkBindImageMemory(
device,
image,
memory,
0);
} else {
// Take the normal memory sub-allocation path
}
Version History
-
Revision 1, 2017-02-27 (James Jones)
-
Copy content from VK_NV_dedicated_allocation
-
Add some references to external object interactions to the overview.
-
-
Revision 2, 2017-03-27 (Jason Ekstrand)
-
Rework the extension to be query-based
-
-
Revision 3, 2017-07-31 (Jason Ekstrand)
-
Clarify that memory objects allocated with VkMemoryDedicatedAllocateInfoKHR can only have the specified resource bound and no others.
-
VK_KHR_depth_stencil_resolve
- Name String
-
VK_KHR_depth_stencil_resolve - Extension Type
-
Device extension
- Registered Extension Number
-
200
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_create_renderpass2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jan-Harald Fredriksen janharald
-
Other Extension Metadata
- Last Modified Date
-
2018-04-09
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Andrew Garrard, Samsung Electronics
-
Soowan Park, Samsung Electronics
-
Jeff Bolz, NVIDIA
-
Daniel Rakos, AMD
-
Description
This extension adds support for automatically resolving multisampled depth/stencil attachments in a subpass in a similar manner as for color attachments.
Multisampled color attachments can be resolved at the end of a subpass by
specifying pResolveAttachments entries corresponding to the
pColorAttachments array entries.
This does not allow for a way to map the resolve attachments to the
depth/stencil attachment.
The vkCmdResolveImage command does not allow for depth/stencil images.
While there are other ways to resolve the depth/stencil attachment, they can
give sub-optimal performance.
Extending the VkSubpassDescription2 in this extension allows an
application to add a pDepthStencilResolveAttachment, that is similar
to the color pResolveAttachments, that the
pDepthStencilAttachment can be resolved into.
Depth and stencil samples are resolved to a single value based on the
resolve mode.
The set of possible resolve modes is defined in the
VkResolveModeFlagBits enum.
The VK_RESOLVE_MODE_SAMPLE_ZERO_BIT mode is the only mode that is
required of all implementations (that support the extension or support
Vulkan 1.2 or higher).
Some implementations may also support averaging (the same as color sample
resolve) or taking the minimum or maximum sample, which may be more suitable
for depth/stencil resolve.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_DEPTH_STENCIL_RESOLVE_EXTENSION_NAME -
VK_KHR_DEPTH_STENCIL_RESOLVE_SPEC_VERSION -
Extending VkResolveModeFlagBits:
-
VK_RESOLVE_MODE_AVERAGE_BIT_KHR -
VK_RESOLVE_MODE_MAX_BIT_KHR -
VK_RESOLVE_MODE_MIN_BIT_KHR -
VK_RESOLVE_MODE_NONE_KHR -
VK_RESOLVE_MODE_SAMPLE_ZERO_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE_KHR
-
VK_KHR_descriptor_update_template
- Name String
-
VK_KHR_descriptor_update_template - Extension Type
-
Device extension
- Registered Extension Number
-
86
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Markus Tavenrath mtavenrath
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with
VK_KHR_push_descriptor -
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Michael Worcester, Imagination Technologies
-
Description
Applications may wish to update a fixed set of descriptors in a large number of descriptor sets very frequently, i.e. during initializaton phase or if it is required to rebuild descriptor sets for each frame. For those cases it is also not unlikely that all information required to update a single descriptor set is stored in a single struct. This extension provides a way to update a fixed set of descriptors in a single VkDescriptorSet with a pointer to a user defined data structure describing the new descriptors.
Promotion to Vulkan 1.1
vkCmdPushDescriptorSetWithTemplateKHR is included as an interaction
with VK_KHR_push_descriptor.
If Vulkan 1.1 and VK_KHR_push_descriptor are supported, this is included
by VK_KHR_push_descriptor.
The base functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_EXTENSION_NAME -
VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_SPEC_VERSION -
Extending VkDescriptorUpdateTemplateType:
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR
-
If VK_EXT_debug_report is supported:
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT
-
If VK_KHR_push_descriptor is supported:
-
Extending VkDescriptorUpdateTemplateType:
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
-
VK_KHR_device_group
- Name String
-
VK_KHR_device_group - Extension Type
-
Device extension
- Registered Extension Number
-
61
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_device_group_creationto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-10-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_device_group -
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Tobias Hector, Imagination Technologies
-
Description
This extension provides functionality to use a logical device that consists
of multiple physical devices, as created with the
VK_KHR_device_group_creation extension.
A device group can allocate memory across the subdevices, bind memory from
one subdevice to a resource on another subdevice, record command buffers
where some work executes on an arbitrary subset of the subdevices, and
potentially present a swapchain image from one or more subdevices.
Promotion to Vulkan 1.1
The following enums, types and commands are included as interactions with
VK_KHR_swapchain:
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR -
VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR -
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
If Vulkan 1.1 and VK_KHR_swapchain are supported, these are
included by VK_KHR_swapchain.
The base functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Structures
-
Extending VkBindSparseInfo:
-
Extending VkCommandBufferBeginInfo:
-
Extending VkMemoryAllocateInfo:
-
Extending VkRenderPassBeginInfo, VkRenderingInfo:
-
Extending VkSubmitInfo:
If VK_KHR_bind_memory2 is supported:
-
Extending VkBindBufferMemoryInfo:
-
Extending VkBindImageMemoryInfo:
If VK_KHR_surface is supported:
If VK_KHR_swapchain is supported:
New Enums
If VK_KHR_surface is supported:
New Bitmasks
If VK_KHR_surface is supported:
New Enum Constants
-
VK_KHR_DEVICE_GROUP_EXTENSION_NAME -
VK_KHR_DEVICE_GROUP_SPEC_VERSION -
Extending VkDependencyFlagBits:
-
VK_DEPENDENCY_DEVICE_GROUP_BIT_KHR
-
-
Extending VkMemoryAllocateFlagBits:
-
VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT_KHR
-
-
Extending VkPeerMemoryFeatureFlagBits:
-
VK_PEER_MEMORY_FEATURE_COPY_DST_BIT_KHR -
VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT_KHR -
VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT_KHR -
VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT_KHR
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_DISPATCH_BASE_KHR -
VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO_KHR -
VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO_KHR
-
If VK_KHR_bind_memory2 is supported:
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO_KHR -
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO_KHR
-
If VK_KHR_surface is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR
-
If VK_KHR_swapchain is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR -
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
-
-
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
-
Version History
-
Revision 1, 2016-10-19 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2017-05-19 (Tobias Hector)
-
Removed extended memory bind functions to VK_KHR_bind_memory2, added dependency on that extension, and device-group-specific structs for those functions.
-
-
Revision 3, 2017-10-06 (Ian Elliott)
-
Corrected Vulkan 1.1 interactions with the WSI extensions. All Vulkan 1.1 WSI interactions are with the VK_KHR_swapchain extension.
-
-
Revision 4, 2017-10-10 (Jeff Bolz)
-
Rename “SFR” bits and structure members to use the phrase “split instance bind regions”.
-
VK_KHR_device_group_creation
- Name String
-
VK_KHR_device_group_creation - Extension Type
-
Instance extension
- Registered Extension Number
-
71
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2016-10-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension provides instance-level commands to enumerate groups of
physical devices, and to create a logical device from a subset of one of
those groups.
Such a logical device can then be used with new features in the
VK_KHR_device_group extension.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_DEVICE_GROUP_CREATION_EXTENSION_NAME -
VK_KHR_DEVICE_GROUP_CREATION_SPEC_VERSION -
VK_MAX_DEVICE_GROUP_SIZE_KHR -
Extending VkMemoryHeapFlagBits:
-
VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR
-
Examples
VkDeviceCreateInfo devCreateInfo = { VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO };
// (not shown) fill out devCreateInfo as usual.
uint32_t deviceGroupCount = 0;
VkPhysicalDeviceGroupPropertiesKHR *props = NULL;
// Query the number of device groups
vkEnumeratePhysicalDeviceGroupsKHR(g_vkInstance, &deviceGroupCount, NULL);
// Allocate and initialize structures to query the device groups
props = (VkPhysicalDeviceGroupPropertiesKHR *)malloc(deviceGroupCount*sizeof(VkPhysicalDeviceGroupPropertiesKHR));
for (i = 0; i < deviceGroupCount; ++i) {
props[i].sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR;
props[i].pNext = NULL;
}
vkEnumeratePhysicalDeviceGroupsKHR(g_vkInstance, &deviceGroupCount, props);
// If the first device group has more than one physical device. create
// a logical device using all of the physical devices.
VkDeviceGroupDeviceCreateInfoKHR deviceGroupInfo = { VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR };
if (props[0].physicalDeviceCount > 1) {
deviceGroupInfo.physicalDeviceCount = props[0].physicalDeviceCount;
deviceGroupInfo.pPhysicalDevices = props[0].physicalDevices;
devCreateInfo.pNext = &deviceGroupInfo;
}
vkCreateDevice(props[0].physicalDevices[0], &devCreateInfo, NULL, &g_vkDevice);
free(props);
VK_KHR_draw_indirect_count
- Name String
-
VK_KHR_draw_indirect_count - Extension Type
-
Device extension
- Registered Extension Number
-
170
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2017-08-25
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Derrick Owens, AMD
-
Graham Sellers, AMD
-
Daniel Rakos, AMD
-
Dominik Witczak, AMD
-
Piers Daniell, NVIDIA
-
Description
This extension is based off the VK_AMD_draw_indirect_count
extension.
This extension allows an application to source the number of draws for
indirect drawing calls from a buffer.
Applications might want to do culling on the GPU via a compute shader prior to drawing. This enables the application to generate an arbitrary number of drawing commands and execute them without host intervention.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. However, if Vulkan 1.2 is supported and this extension is not, the entry points vkCmdDrawIndirectCount and vkCmdDrawIndexedIndirectCount are optional. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_DRAW_INDIRECT_COUNT_EXTENSION_NAME -
VK_KHR_DRAW_INDIRECT_COUNT_SPEC_VERSION
Version History
-
Revision 1, 2017-08-25 (Piers Daniell)
-
Initial draft based off VK_AMD_draw_indirect_count
-
VK_KHR_driver_properties
- Name String
-
VK_KHR_driver_properties - Extension Type
-
Device extension
- Registered Extension Number
-
197
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2018-04-11
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Baldur Karlsson
-
Matthaeus G. Chajdas, AMD
-
Piers Daniell, NVIDIA
-
Alexander Galazin, Arm
-
Jesse Hall, Google
-
Daniel Rakos, AMD
-
Description
This extension provides a new physical device query which allows retrieving information about the driver implementation, allowing applications to determine which physical device corresponds to which particular vendor’s driver, and which conformance test suite version the driver implementation is compliant with.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_DRIVER_PROPERTIES_EXTENSION_NAME -
VK_KHR_DRIVER_PROPERTIES_SPEC_VERSION -
VK_MAX_DRIVER_INFO_SIZE_KHR -
VK_MAX_DRIVER_NAME_SIZE_KHR -
Extending VkDriverId:
-
VK_DRIVER_ID_AMD_OPEN_SOURCE_KHR -
VK_DRIVER_ID_AMD_PROPRIETARY_KHR -
VK_DRIVER_ID_ARM_PROPRIETARY_KHR -
VK_DRIVER_ID_BROADCOM_PROPRIETARY_KHR -
VK_DRIVER_ID_GGP_PROPRIETARY_KHR -
VK_DRIVER_ID_GOOGLE_SWIFTSHADER_KHR -
VK_DRIVER_ID_IMAGINATION_PROPRIETARY_KHR -
VK_DRIVER_ID_INTEL_OPEN_SOURCE_MESA_KHR -
VK_DRIVER_ID_INTEL_PROPRIETARY_WINDOWS_KHR -
VK_DRIVER_ID_MESA_RADV_KHR -
VK_DRIVER_ID_NVIDIA_PROPRIETARY_KHR -
VK_DRIVER_ID_QUALCOMM_PROPRIETARY_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES_KHR
-
VK_KHR_dynamic_rendering
- Name String
-
VK_KHR_dynamic_rendering - Extension Type
-
Device extension
- Registered Extension Number
-
45
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_depth_stencil_resolveto be enabled for any device-level functionality -
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Tobias Hector tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-10-06
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- Contributors
-
-
Tobias Hector, AMD
-
Arseny Kapoulkine, Roblox
-
François Duranleau, Gameloft
-
Stuart Smith, AMD
-
Hai Nguyen, Google
-
Jean-François Roy, Google
-
Jeff Leger, Qualcomm
-
Jan-Harald Fredriksen, Arm
-
Piers Daniell, Nvidia
-
James Fitzpatrick, Imagination
-
Piotr Byszewski, Mobica
-
Jesse Hall, Google
-
Mike Blumenkrantz, Valve
-
Description
This extension allows applications to create single-pass render pass instances without needing to create render pass objects or framebuffers. Dynamic render passes can also span across multiple primary command buffers, rather than relying on secondary command buffers.
This extension also incorporates VK_ATTACHMENT_STORE_OP_NONE_KHR from
VK_QCOM_render_pass_store_ops, enabling
applications to avoid unnecessary synchronization when an attachment is not
written during a render pass.
New Structures
-
Extending VkCommandBufferInheritanceInfo:
-
Extending VkGraphicsPipelineCreateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
If VK_AMD_mixed_attachment_samples is supported:
If VK_EXT_fragment_density_map is supported:
If VK_KHR_fragment_shading_rate is supported:
If VK_NV_framebuffer_mixed_samples is supported:
If VK_NVX_multiview_per_view_attributes is supported:
New Enum Constants
-
VK_KHR_DYNAMIC_RENDERING_EXTENSION_NAME -
VK_KHR_DYNAMIC_RENDERING_SPEC_VERSION -
Extending VkAttachmentStoreOp:
-
VK_ATTACHMENT_STORE_OP_NONE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES_KHR -
VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO_KHR -
VK_STRUCTURE_TYPE_RENDERING_INFO_KHR
-
If VK_AMD_mixed_attachment_samples is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_AMD
-
If VK_EXT_fragment_density_map is supported:
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT -
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_INFO_EXT
-
If VK_KHR_fragment_shading_rate is supported:
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR
-
If VK_NV_framebuffer_mixed_samples is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_NV
-
If VK_NVX_multiview_per_view_attributes is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_ATTRIBUTES_INFO_NVX
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
VK_KHR_external_fence
- Name String
-
VK_KHR_external_fence - Extension Type
-
Device extension
- Registered Extension Number
-
114
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_fence_capabilitiesto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2017-05-08
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Cass Everitt, Oculus
-
Contributors to
VK_KHR_external_semaphore
-
Description
An application using external memory may wish to synchronize access to that memory using fences. This extension enables an application to create fences from which non-Vulkan handles that reference the underlying synchronization primitive can be exported.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Structures
-
Extending VkFenceCreateInfo:
New Enum Constants
-
VK_KHR_EXTERNAL_FENCE_EXTENSION_NAME -
VK_KHR_EXTERNAL_FENCE_SPEC_VERSION -
Extending VkFenceImportFlagBits:
-
VK_FENCE_IMPORT_TEMPORARY_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO_KHR
-
Issues
This extension borrows concepts, semantics, and language from
VK_KHR_external_semaphore.
That extension’s issues apply equally to this extension.
VK_KHR_external_fence_capabilities
- Name String
-
VK_KHR_external_fence_capabilities - Extension Type
-
Instance extension
- Registered Extension Number
-
113
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2017-05-08
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Cass Everitt, Oculus
-
Contributors to
VK_KHR_external_semaphore_capabilities
-
Description
An application may wish to reference device fences in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension provides a set of capability queries and handle definitions that allow an application to determine what types of “external” fence handles an implementation supports for a given set of use cases.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_EXTERNAL_FENCE_CAPABILITIES_EXTENSION_NAME -
VK_KHR_EXTERNAL_FENCE_CAPABILITIES_SPEC_VERSION -
VK_LUID_SIZE_KHR -
Extending VkExternalFenceFeatureFlagBits:
-
VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT_KHR -
VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT_KHR
-
-
Extending VkExternalFenceHandleTypeFlagBits:
-
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT_KHR -
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR -
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR -
VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR
-
VK_KHR_external_memory
- Name String
-
VK_KHR_external_memory - Extension Type
-
Device extension
- Registered Extension Number
-
73
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_memory_capabilitiesto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-20
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with
VK_KHR_dedicated_allocation. -
Interacts with
VK_NV_dedicated_allocation. -
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jason Ekstrand, Intel
-
Ian Elliot, Google
-
Jesse Hall, Google
-
Tobias Hector, Imagination Technologies
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Daniel Rakos, AMD
-
Carsten Rohde, NVIDIA
-
Ray Smith, ARM
-
Chad Versace, Google
-
Description
An application may wish to reference device memory in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension enables an application to export non-Vulkan handles from Vulkan memory objects such that the underlying resources can be referenced outside the scope of the Vulkan logical device that created them.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_EXTERNAL_MEMORY_EXTENSION_NAME -
VK_KHR_EXTERNAL_MEMORY_SPEC_VERSION -
VK_QUEUE_FAMILY_EXTERNAL_KHR -
Extending VkResult:
-
VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_KHR -
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_KHR
-
Issues
1) How do applications correlate two physical devices across process or Vulkan instance boundaries?
RESOLVED: New device ID fields have been introduced by
VK_KHR_external_memory_capabilities.
These fields, combined with the existing
VkPhysicalDeviceProperties::driverVersion field can be used to
identify compatible devices across processes, drivers, and APIs.
VkPhysicalDeviceProperties::pipelineCacheUUID is not sufficient
for this purpose because despite its description in the specification, it
need only identify a unique pipeline cache format in practice.
Multiple devices may be able to use the same pipeline cache data, and hence
it would be desirable for all of them to have the same pipeline cache UUID.
However, only the same concrete physical device can be used when sharing
memory, so an actual unique device ID was introduced.
Further, the pipeline cache UUID was specific to Vulkan, but correlation
with other, non-extensible APIs is required to enable interoperation with
those APIs.
2) If memory objects are shared between processes and APIs, is this considered aliasing according to the rules outlined in the Memory Aliasing section?
RESOLVED: Yes. Applications must take care to obey all restrictions imposed on aliased resources when using memory across multiple Vulkan instances or other APIs.
3) Are new image layouts or metadata required to specify image layouts and layout transitions compatible with non-Vulkan APIs, or with other instances of the same Vulkan driver?
RESOLVED: Separate instances of the same Vulkan driver running on the same GPU should have identical internal layout semantics, so applications have the tools they need to ensure views of images are consistent between the two instances. Other APIs will fall into two categories: Those that are Vulkan- compatible, and those that are Vulkan-incompatible. Vulkan-incompatible APIs will require the image to be in the GENERAL layout whenever they are accessing them.
Note this does not attempt to address cross-device transitions, nor transitions to engines on the same device which are not visible within the Vulkan API. Both of these are beyond the scope of this extension.
4) Is a new barrier flag or operation of some type needed to prepare external memory for handoff to another Vulkan instance or API and/or receive it from another instance or API?
RESOLVED: Yes. Some implementations need to perform additional cache management when transitioning memory between address spaces and other APIs, instances, or processes which may operate in a separate address space. Options for defining this transition include:
-
A new structure that can be added to the
pNextlist in VkMemoryBarrier, VkBufferMemoryBarrier, and VkImageMemoryBarrier. -
A new bit in VkAccessFlags that can be set to indicate an “external” access.
-
A new bit in VkDependencyFlags
-
A new special queue family that represents an “external” queue.
A new structure has the advantage that the type of external transition can
be described in as much detail as necessary.
However, there is not currently a known need for anything beyond
differentiating between external and internal accesses, so this is likely an
over-engineered solution.
The access flag bit has the advantage that it can be applied at buffer,
image, or global granularity, and semantically it maps pretty well to the
operation being described.
Additionally, the API already includes VK_ACCESS_MEMORY_READ_BIT and
VK_ACCESS_MEMORY_WRITE_BIT which appear to be intended for this
purpose.
However, there is no obvious pipeline stage that would correspond to an
external access, and therefore no clear way to use
VK_ACCESS_MEMORY_READ_BIT or VK_ACCESS_MEMORY_WRITE_BIT.
VkDependencyFlags and VkPipelineStageFlags operate at command
granularity rather than image or buffer granularity, which would make an
entire pipeline barrier an internal→external or external→internal barrier.
This may not be a problem in practice, but seems like the wrong scope.
Another downside of VkDependencyFlags is that it lacks inherent
directionality: there are no src and dst variants of it in the
barrier or dependency description semantics, so two bits might need to be
added to describe both internal→external and external→internal
transitions.
Transitioning a resource to a special queue family corresponds well with the
operation of transitioning to a separate Vulkan instance, in that both
operations ideally include scheduling a barrier on both sides of the
transition: Both the releasing and the acquiring queue or process.
Using a special queue family requires adding an additional reserved queue
family index.
Re-using VK_QUEUE_FAMILY_IGNORED would have left it unclear how to
transition a concurrent usage resource from one process to another, since
the semantics would have likely been equivalent to the currently-ignored
transition of
VK_QUEUE_FAMILY_IGNORED → VK_QUEUE_FAMILY_IGNORED.
Fortunately, creating a new reserved queue family index is not invasive.
Based on the above analysis, the approach of transitioning to a special “external” queue family was chosen.
5) Do internal driver memory arrangements and/or other internal driver image properties need to be exported and imported when sharing images across processes or APIs.
RESOLVED: Some vendors claim this is necessary on their implementations, but it was determined that the security risks of allowing opaque metadata to be passed from applications to the driver were too high. Therefore, implementations which require metadata will need to associate it with the objects represented by the external handles, and rely on the dedicated allocation mechanism to associate the exported and imported memory objects with a single image or buffer.
6) Most prior interoperation and cross-process sharing APIs have been based on image-level sharing. Should Vulkan sharing be based on memory-object sharing or image sharing?
RESOLVED: These extensions have assumed memory-level sharing is the correct granularity. Vulkan is a lower-level API than most prior APIs, and as such attempts to closely align with to the underlying primitives of the hardware and system-level drivers it abstracts. In general, the resource that holds the backing store for both images and buffers of various types is memory. Images and buffers are merely metadata containing brief descriptions of the layout of bits within that memory.
Because memory object-based sharing is aligned with the overall Vulkan API design, it enables the full range of Vulkan capabilities with external objects. External memory can be used as backing for sparse images, for example, whereas such usage would be awkward at best with a sharing mechanism based on higher-level primitives such as images. Further, aligning the mechanism with the API in this way provides some hope of trivial compatibility with future API enhancements. If new objects backed by memory objects are added to the API, they too can be used across processes with minimal additions to the base external memory APIs.
Earlier APIs implemented interop at a higher level, and this necessitated entirely separate sharing APIs for images and buffers. To co-exist and interoperate with those APIs, the Vulkan external sharing mechanism must accommodate their model. However, if it can be agreed that memory-based sharing is the more desirable and forward-looking design, legacy interoperation constraints can be considered another reason to favor memory-based sharing: while native and legacy driver primitives that may be used to implement sharing may not be as low-level as the API here suggests, raw memory is still the least common denominator among the types. Image-based sharing can be cleanly derived from a set of base memory- object sharing APIs with minimal effort, whereas image-based sharing does not generalize well to buffer or raw-memory sharing. Therefore, following the general Vulkan design principle of minimalism, it is better to expose interopability with image-based native and external primitives via the memory sharing API, and place sufficient limits on their usage to ensure they can be used only as backing for equivalent Vulkan images. This provides a consistent API for applications regardless of which platform or external API they are targeting, which makes development of multi-API and multi-platform applications simpler.
7) Should Vulkan define a common external handle type and provide Vulkan functions to facilitate cross-process sharing of such handles rather than relying on native handles to define the external objects?
RESOLVED: No. Cross-process sharing of resources is best left to native platforms. There are myriad security and extensibility issues with such a mechanism, and attempting to re-solve all those issues within Vulkan does not align with Vulkan’s purpose as a graphics API. If desired, such a mechanism could be built as a layer or helper library on top of the opaque native handle defined in this family of extensions.
8) Must implementations provide additional guarantees about state implicitly included in memory objects for those memory objects that may be exported?
RESOLVED: Implementations must ensure that sharing memory objects does not transfer any information between the exporting and importing instances and APIs other than that required to share the data contained in the memory objects explicitly shared. As specific examples, data from previously freed memory objects that used the same underlying physical memory, and data from memory obects using adjacent physical memory must not be visible to applications importing an exported memory object.
9) Must implementations validate external handles the application provides as inputs to memory import operations?
RESOLVED: Implementations must return an error to the application if the provided memory handle cannot be used to complete the requested import operation. However, implementations need not validate handles are of the exact type specified by the application.
VK_KHR_external_memory_capabilities
- Name String
-
VK_KHR_external_memory_capabilities - Extension Type
-
Instance extension
- Registered Extension Number
-
72
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-17
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with
VK_KHR_dedicated_allocation. -
Interacts with
VK_NV_dedicated_allocation. -
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Ian Elliot, Google
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Description
An application may wish to reference device memory in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension provides a set of capability queries and handle definitions that allow an application to determine what types of “external” memory handles an implementation supports for a given set of use cases.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_EXTERNAL_MEMORY_CAPABILITIES_EXTENSION_NAME -
VK_KHR_EXTERNAL_MEMORY_CAPABILITIES_SPEC_VERSION -
VK_LUID_SIZE_KHR -
Extending VkExternalMemoryFeatureFlagBits:
-
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_KHR -
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_KHR -
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_KHR
-
-
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHR -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHR -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR
-
Issues
1) Why do so many external memory capabilities need to be queried on a per-memory-handle-type basis?
PROPOSED RESOLUTION: This is because some handle types are based on OS-native objects that have far more limited capabilities than the very generic Vulkan memory objects. Not all memory handle types can name memory objects that support 3D images, for example. Some handle types cannot even support the deferred image and memory binding behavior of Vulkan and require specifying the image when allocating or importing the memory object.
2) Do the VkExternalImageFormatPropertiesKHR and VkExternalBufferPropertiesKHR structs need to include a list of memory type bits that support the given handle type?
PROPOSED RESOLUTION: No. The memory types that do not support the handle types will simply be filtered out of the results returned by vkGetImageMemoryRequirements and vkGetBufferMemoryRequirements when a set of handle types was specified at image or buffer creation time.
3) Should the non-opaque handle types be moved to their own extension?
PROPOSED RESOLUTION: Perhaps. However, defining the handle type bits does very little and does not require any platform-specific types on its own, and it is easier to maintain the bitfield values in a single extension for now. Presumably more handle types could be added by separate extensions though, and it would be midly weird to have some platform-specific ones defined in the core spec and some in extensions
4) Do we need a D3D11_TILEPOOL type?
PROPOSED RESOLUTION: No. This is technically possible, but the synchronization is awkward. D3D11 surfaces must be synchronized using shared mutexes, and these synchronization primitives are shared by the entire memory object, so D3D11 shared allocations divided among multiple buffer and image bindings may be difficult to synchronize.
5) Should the Windows 7-compatible handle types be named “KMT” handles or “GLOBAL_SHARE” handles?
PROPOSED RESOLUTION: KMT, simply because it is more concise.
6) How do applications identify compatible devices and drivers across instance, process, and API boundaries when sharing memory?
PROPOSED RESOLUTION: New device properties are exposed that allow applications to correctly correlate devices and drivers. A device and driver UUID that must both match to ensure sharing compatibility between two Vulkan instances, or a Vulkan instance and an extensible external API are added. To allow correlating with Direct3D devices, a device LUID is added that corresponds to a DXGI adapter LUID. A driver ID is not needed for Direct3D because mismatched driver component versions are not currently supported on the Windows OS. Should support for such configurations be introduced at the OS level, further Vulkan extensions would be needed to correlate userspace component builds.
VK_KHR_external_semaphore
- Name String
-
VK_KHR_external_semaphore - Extension Type
-
Device extension
- Registered Extension Number
-
78
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_external_semaphore_capabilitiesto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jason Ekstrand, Intel
-
Jesse Hall, Google
-
Tobias Hector, Imagination Technologies
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Ray Smith, ARM
-
Chad Versace, Google
-
Description
An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to create semaphores from which non-Vulkan handles that reference the underlying synchronization primitive can be exported.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_EXTERNAL_SEMAPHORE_EXTENSION_NAME -
VK_KHR_EXTERNAL_SEMAPHORE_SPEC_VERSION -
Extending VkSemaphoreImportFlagBits:
-
VK_SEMAPHORE_IMPORT_TEMPORARY_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO_KHR
-
Issues
1) Should there be restrictions on what side effects can occur when waiting on imported semaphores that are in an invalid state?
RESOLVED: Yes. Normally, validating such state would be the responsibility of the application, and the implementation would be free to enter an undefined state if valid usage rules were violated. However, this could cause security concerns when using imported semaphores, as it would require the importing application to trust the exporting application to ensure the state is valid. Requiring this level of trust is undesirable for many potential use cases.
2) Must implementations validate external handles the application provides as input to semaphore state import operations?
RESOLVED: Implementations must return an error to the application if the provided semaphore state handle cannot be used to complete the requested import operation. However, implementations need not validate handles are of the exact type specified by the application.
VK_KHR_external_semaphore_capabilities
- Name String
-
VK_KHR_external_semaphore_capabilities - Extension Type
-
Instance extension
- Registered Extension Number
-
77
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-20
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Description
An application may wish to reference device semaphores in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension provides a set of capability queries and handle definitions that allow an application to determine what types of “external” semaphore handles an implementation supports for a given set of use cases.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_EXTERNAL_SEMAPHORE_CAPABILITIES_EXTENSION_NAME -
VK_KHR_EXTERNAL_SEMAPHORE_CAPABILITIES_SPEC_VERSION -
VK_LUID_SIZE_KHR -
Extending VkExternalSemaphoreFeatureFlagBits:
-
VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT_KHR -
VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT_KHR
-
-
Extending VkExternalSemaphoreHandleTypeFlagBits:
-
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT_KHR -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT_KHR -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES_KHR
-
VK_KHR_format_feature_flags2
- Name String
-
VK_KHR_format_feature_flags2 - Extension Type
-
Device extension
- Registered Extension Number
-
361
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Lionel Landwerlin llandwerlin
-
Other Extension Metadata
- Last Modified Date
-
2021-07-01
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Lionel Landwerlin, Intel
-
Jason Ekstrand, Intel
-
Tobias Hector, AMD
-
Spencer Fricke, Samsung Electronics
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, ARM
-
Description
This extension adds a new VkFormatFeatureFlagBits2KHR 64bits format feature flag type to extend the existing VkFormatFeatureFlagBits which is limited to 31 flags. At the time of this writing 29 bits of VkFormatFeatureFlagBits are already used.
Because VkFormatProperties2 is already defined to extend the Vulkan 1.0 vkGetPhysicalDeviceFormatProperties entry point, this extension defines a new VkFormatProperties3KHR to extend the VkFormatProperties.
On top of replicating all the bits from VkFormatFeatureFlagBits, VkFormatFeatureFlagBits2KHR adds the following bits :
-
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHRandVK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHRindicate that an implementation supports respectively reading and writing a given VkFormat through storage operations without specifying the format in the shader. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT_KHRindicates that an implementation supports depth comparison performed byOpImage*Dref*instructions on a given VkFormat. Previously the result of executing aOpImage*Dref*instruction on an image view, where theformatwas not one of the depth/stencil formats with a depth component, was undefined. This bit clarifies on which formats such instructions can be used.
New Structures
-
Extending VkFormatProperties2:
New Enum Constants
-
VK_KHR_FORMAT_FEATURE_FLAGS_2_EXTENSION_NAME -
VK_KHR_FORMAT_FEATURE_FLAGS_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3_KHR
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
VK_KHR_get_memory_requirements2
- Name String
-
VK_KHR_get_memory_requirements2 - Extension Type
-
Device extension
- Registered Extension Number
-
147
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jason Ekstrand jekstrand
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Jesse Hall, Google
-
Description
This extension provides new entry points to query memory requirements of
images and buffers in a way that can be easily extended by other extensions,
without introducing any further entry points.
The Vulkan 1.0 VkMemoryRequirements and
VkSparseImageMemoryRequirements structures do not include sType
and pNext members.
This extension wraps them in new structures with these members, so an
application can query a chain of memory requirements structures by
constructing the chain and letting the implementation fill them in.
A new command is added for each vkGet*MemoryRequrements command in
core Vulkan 1.0.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_GET_MEMORY_REQUIREMENTS_2_EXTENSION_NAME -
VK_KHR_GET_MEMORY_REQUIREMENTS_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2_KHR -
VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2_KHR -
VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2_KHR -
VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2_KHR -
VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2_KHR
-
VK_KHR_get_physical_device_properties2
- Name String
-
VK_KHR_get_physical_device_properties2 - Extension Type
-
Instance extension
- Registered Extension Number
-
60
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Ian Elliott, Google
-
Description
This extension provides new entry points to query device features, device
properties, and format properties in a way that can be easily extended by
other extensions, without introducing any further entry points.
The Vulkan 1.0 feature/limit/formatproperty structures do not include
sType/pNext members.
This extension wraps them in new structures with sType/pNext
members, so an application can query a chain of feature/limit/formatproperty
structures by constructing the chain and letting the implementation fill
them in.
A new command is added for each vkGetPhysicalDevice* command in core
Vulkan 1.0.
The new feature structure (and a pNext chain of extending structures)
can also be passed in to device creation to enable features.
This extension also allows applications to use the physical-device components of device extensions before vkCreateDevice is called.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME -
VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2_KHR -
VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2_KHR -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2_KHR -
VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2_KHR
-
Examples
// Get features with a hypothetical future extension.
VkHypotheticalExtensionFeaturesKHR hypotheticalFeatures =
{
VK_STRUCTURE_TYPE_HYPOTHETICAL_FEATURES_KHR, // sType
NULL, // pNext
};
VkPhysicalDeviceFeatures2KHR features =
{
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR, // sType
&hypotheticalFeatures, // pNext
};
// After this call, features and hypotheticalFeatures have been filled out.
vkGetPhysicalDeviceFeatures2KHR(physicalDevice, &features);
// Properties/limits can be chained and queried similarly.
// Enable some features:
VkHypotheticalExtensionFeaturesKHR enabledHypotheticalFeatures =
{
VK_STRUCTURE_TYPE_HYPOTHETICAL_FEATURES_KHR, // sType
NULL, // pNext
};
VkPhysicalDeviceFeatures2KHR enabledFeatures =
{
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR, // sType
&enabledHypotheticalFeatures, // pNext
};
enabledFeatures.features.xyz = VK_TRUE;
enabledHypotheticalFeatures.abc = VK_TRUE;
VkDeviceCreateInfo deviceCreateInfo =
{
VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO, // sType
&enabledFeatures, // pNext
...
NULL, // pEnabledFeatures
};
VkDevice device;
vkCreateDevice(physicalDevice, &deviceCreateInfo, NULL, &device);
Version History
-
Revision 1, 2016-09-12 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2016-11-02 (Ian Elliott)
-
Added ability for applications to use the physical-device components of device extensions before vkCreateDevice is called.
-
VK_KHR_image_format_list
- Name String
-
VK_KHR_image_format_list - Extension Type
-
Device extension
- Registered Extension Number
-
148
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jason Ekstrand jekstrand
-
Other Extension Metadata
- Last Modified Date
-
2017-03-20
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Jason Ekstrand, Intel
-
Jan-Harald Fredriksen, ARM
-
Jeff Bolz, NVIDIA
-
Jeff Leger, Qualcomm
-
Neil Henning, Codeplay
-
Description
On some implementations, setting the
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT on image creation can cause access
to that image to perform worse than an equivalent image created without
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT because the implementation does not
know what view formats will be paired with the image.
This extension allows an application to provide the list of all formats that can be used with an image when it is created. The implementation may then be able to create a more efficient image that supports the subset of formats required by the application without having to support all formats in the format compatibility class of the image format.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_IMAGE_FORMAT_LIST_EXTENSION_NAME -
VK_KHR_IMAGE_FORMAT_LIST_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO_KHR
-
VK_KHR_imageless_framebuffer
- Name String
-
VK_KHR_imageless_framebuffer - Extension Type
-
Device extension
- Registered Extension Number
-
109
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_maintenance2to be enabled for any device-level functionality -
Requires
VK_KHR_image_format_listto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Tobias Hector tobias
-
Other Extension Metadata
- Last Modified Date
-
2018-12-14
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Tobias Hector
-
Graham Wihlidal
-
Description
This extension allows framebuffers to be created without the need for creating images first, allowing more flexibility in how they are used, and avoiding the need for many of the confusing compatibility rules.
Framebuffers are now created with a small amount of additional metadata about the image views that will be used in VkFramebufferAttachmentsCreateInfoKHR, and the actual image views are provided at render pass begin time via VkRenderPassAttachmentBeginInfoKHR.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_IMAGELESS_FRAMEBUFFER_EXTENSION_NAME -
VK_KHR_IMAGELESS_FRAMEBUFFER_SPEC_VERSION -
Extending VkFramebufferCreateFlagBits:
-
VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES_KHR -
VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO_KHR
-
VK_KHR_maintenance1
- Name String
-
VK_KHR_maintenance1 - Extension Type
-
Device extension
- Registered Extension Number
-
70
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2018-03-13
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Dan Ginsburg, Valve
-
Daniel Koch, NVIDIA
-
Daniel Rakos, AMD
-
Jan-Harald Fredriksen, ARM
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Jesse Hall, Google
-
John Kessenich, Google
-
Michael Worcester, Imagination Technologies
-
Neil Henning, Codeplay Software Ltd.
-
Piers Daniell, NVIDIA
-
Slawomir Grajewski, Intel
-
Tobias Hector, Imagination Technologies
-
Tom Olson, ARM
-
Description
VK_KHR_maintenance1 adds a collection of minor features that were
intentionally left out or overlooked from the original Vulkan 1.0 release.
The new features are as follows:
-
Allow 2D and 2D array image views to be created from 3D images, which can then be used as color framebuffer attachments. This allows applications to render to slices of a 3D image.
-
Support vkCmdCopyImage between 2D array layers and 3D slices. This extension allows copying from layers of a 2D array image to slices of a 3D image and vice versa.
-
Allow negative height to be specified in the VkViewport::
heightfield to perform y-inversion of the clip-space to framebuffer-space transform. This allows apps to avoid having to usegl_Position.y = -gl_Position.yin shaders also targeting other APIs. -
Allow implementations to express support for doing just transfers and clears of image formats that they otherwise support no other format features for. This is done by adding new format feature flags
VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHRandVK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR. -
Support vkCmdFillBuffer on transfer-only queues. Previously vkCmdFillBuffer was defined to only work on command buffers allocated from command pools which support graphics or compute queues. It is now allowed on queues that just support transfer operations.
-
Fix the inconsistency of how error conditions are returned between the vkCreateGraphicsPipelines and vkCreateComputePipelines functions and the vkAllocateDescriptorSets and vkAllocateCommandBuffers functions.
-
Add new
VK_ERROR_OUT_OF_POOL_MEMORY_KHRerror so implementations can give a more precise reason for vkAllocateDescriptorSets failures. -
Add a new command vkTrimCommandPoolKHR which gives the implementation an opportunity to release any unused command pool memory back to the system.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_MAINTENANCE1_EXTENSION_NAME -
VK_KHR_MAINTENANCE1_SPEC_VERSION -
VK_KHR_MAINTENANCE_1_EXTENSION_NAME -
VK_KHR_MAINTENANCE_1_SPEC_VERSION -
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR -
VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR
-
-
Extending VkResult:
-
VK_ERROR_OUT_OF_POOL_MEMORY_KHR
-
Version History
-
Revision 1, 2016-10-26 (Piers Daniell)
-
Internal revisions
-
-
Revision 2, 2018-03-13 (Jon Leech)
-
Add issue for zero-height viewports
-
VK_KHR_maintenance2
- Name String
-
VK_KHR_maintenance2 - Extension Type
-
Device extension
- Registered Extension Number
-
118
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Michael Worcester michaelworcester
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Michael Worcester, Imagination Technologies
-
Stuart Smith, Imagination Technologies
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Jan-Harald Fredriksen, ARM
-
Daniel Rakos, AMD
-
Neil Henning, Codeplay
-
Piers Daniell, NVIDIA
-
Description
VK_KHR_maintenance2 adds a collection of minor features that were
intentionally left out or overlooked from the original Vulkan 1.0 release.
The new features are as follows:
-
Allow the application to specify which aspect of an input attachment might be read for a given subpass.
-
Allow implementations to express the clipping behavior of points.
-
Allow creating images with usage flags that may not be supported for the base image’s format, but are supported for image views of the image that have a different but compatible format.
-
Allow creating uncompressed image views of compressed images.
-
Allow the application to select between an upper-left and lower-left origin for the tessellation domain space.
-
Adds two new image layouts for depth stencil images to allow either the depth or stencil aspect to be read-only while the other aspect is writable.
Input Attachment Specification
Input attachment specification allows an application to specify which aspect
of a multi-aspect image (e.g. a combined depth stencil format) will be
accessed via a subpassLoad operation.
On some implementations there may be a performance penalty if the implementation does not know (at vkCreateRenderPass time) which aspect(s) of multi-aspect images can be accessed as input attachments.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Structures
-
Extending VkImageViewCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineTessellationStateCreateInfo:
-
Extending VkRenderPassCreateInfo:
New Enum Constants
-
VK_KHR_MAINTENANCE2_EXTENSION_NAME -
VK_KHR_MAINTENANCE2_SPEC_VERSION -
VK_KHR_MAINTENANCE_2_EXTENSION_NAME -
VK_KHR_MAINTENANCE_2_SPEC_VERSION -
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_KHR -
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR
-
-
Extending VkPointClippingBehavior:
-
VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES_KHR -
VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO_KHR
-
-
Extending VkTessellationDomainOrigin:
-
VK_TESSELLATION_DOMAIN_ORIGIN_LOWER_LEFT_KHR -
VK_TESSELLATION_DOMAIN_ORIGIN_UPPER_LEFT_KHR
-
Input Attachment Specification Example
Consider the case where a render pass has two subpasses and two attachments.
Attachment 0 has the format VK_FORMAT_D24_UNORM_S8_UINT, attachment 1
has some color format.
Subpass 0 writes to attachment 0, subpass 1 reads only the depth information from attachment 0 (using inputAttachmentRead) and writes to attachment 1.
VkInputAttachmentAspectReferenceKHR references[] = {
{
.subpass = 1,
.inputAttachmentIndex = 0,
.aspectMask = VK_IMAGE_ASPECT_DEPTH_BIT
}
};
VkRenderPassInputAttachmentAspectCreateInfoKHR specifyAspects = {
.sType = VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO_KHR,
.pNext = NULL,
.aspectReferenceCount = 1,
.pAspectReferences = references
};
VkRenderPassCreateInfo createInfo = {
...
.pNext = &specifyAspects,
...
};
vkCreateRenderPass(...);
Issues
1) What is the default tessellation domain origin?
RESOLVED: Vulkan 1.0 originally inadvertently documented a lower-left origin, but the conformance tests and all implementations implemented an upper-left origin. This extension adds a control to select between lower-left (for compatibility with OpenGL) and upper-left, and we retroactively fix unextended Vulkan to have a default of an upper-left origin.
VK_KHR_maintenance3
- Name String
-
VK_KHR_maintenance3 - Extension Type
-
Device extension
- Registered Extension Number
-
169
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
VK_KHR_maintenance3 adds a collection of minor features that were
intentionally left out or overlooked from the original Vulkan 1.0 release.
The new features are as follows:
-
A limit on the maximum number of descriptors that are supported in a single descriptor set layout. Some implementations have a limit on the total size of descriptors in a set, which cannot be expressed in terms of the limits in Vulkan 1.0.
-
A limit on the maximum size of a single memory allocation. Some platforms have kernel interfaces that limit the maximum size of an allocation.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_MAINTENANCE3_EXTENSION_NAME -
VK_KHR_MAINTENANCE3_SPEC_VERSION -
VK_KHR_MAINTENANCE_3_EXTENSION_NAME -
VK_KHR_MAINTENANCE_3_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES_KHR
-
VK_KHR_maintenance4
- Name String
-
VK_KHR_maintenance4 - Extension Type
-
Device extension
- Registered Extension Number
-
414
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2021-10-25
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
Requires SPIR-V 1.2 for
LocalSizeId
-
- Contributors
-
-
Lionel Duc, NVIDIA
-
Jason Ekstrand, Intel
-
Spencer Fricke, Samsung
-
Tobias Hector, AMD
-
Lionel Landwerlin, Intel
-
Graeme Leese, Broadcom
-
Tom Olson, Arm
-
Stu Smith, AMD
-
Yiwei Zhang, Google
-
Description
VK_KHR_maintenance4 adds a collection of minor features, none of which
would warrant an entire extension of their own.
The new features are as follows:
-
Allow the application to destroy their VkPipelineLayout object immediately after it was used to create another object. It is no longer necessary to keep its handle valid while the created object is in use.
-
Add a new
maxBufferSizeimplementation-defined limit for the maximum sizeVkBufferthat can be created. -
Add support for the SPIR-V 1.2
LocalSizeIdexecution mode, which can be used as an alternative toLocalSizeto specify the local workgroup size with specialization constants. -
Add a guarantee that images created with identical creation parameters will always have the same alignment requirements.
-
Add new vkGetDeviceBufferMemoryRequirementsKHR, vkGetDeviceImageMemoryRequirementsKHR, and vkGetDeviceImageSparseMemoryRequirementsKHR to allow the application to query the image memory requirements without having to create an image object and query it.
-
Relax the requirement that push constants must be initialized before they are dynamically accessed.
-
Relax the interface matching rules to allow a larger output vector to match with a smaller input vector, with additional values being discarded.
-
Add a guarantee for buffer memory requirement that the size memory requirement is never greater than the result of aligning create size with the alignment memory requirement.
New Enum Constants
-
VK_KHR_MAINTENANCE_4_EXTENSION_NAME -
VK_KHR_MAINTENANCE_4_SPEC_VERSION -
Extending VkImageAspectFlagBits:
-
VK_IMAGE_ASPECT_NONE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_BUFFER_MEMORY_REQUIREMENTS_KHR -
VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_PROPERTIES_KHR
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
Version History
-
Revision 1, 2021-08-18 (Piers Daniell)
-
Internal revisions
-
-
Revision 2, 2021-10-25 (Yiwei Zhang)
-
More guarantees on buffer memory requirements
-
VK_KHR_multiview
- Name String
-
VK_KHR_multiview - Extension Type
-
Device extension
- Registered Extension Number
-
54
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2016-10-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
This extension requires
SPV_KHR_multiview -
This extension provides API support for
GL_EXT_multiview
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension has the same goal as the OpenGL ES GL_OVR_multiview
extension.
Multiview is a rendering technique originally designed for VR where it is
more efficient to record a single set of commands to be executed with
slightly different behavior for each “view”.
It includes a concise way to declare a render pass with multiple views, and
gives implementations freedom to render the views in the most efficient way
possible.
This is done with a multiview configuration specified during render pass creation with the VkRenderPassMultiviewCreateInfo passed
into VkRenderPassCreateInfo::pNext.
This extension enables the use of the
SPV_KHR_multiview shader extension,
which adds a new ViewIndex built-in type that allows shaders to control
what to do for each view.
If using GLSL there is also the
GL_EXT_multiview extension that
introduces a highp int gl_ViewIndex; built-in variable for vertex,
tessellation, geometry, and fragment shaders.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_MULTIVIEW_EXTENSION_NAME -
VK_KHR_MULTIVIEW_SPEC_VERSION -
Extending VkDependencyFlagBits:
-
VK_DEPENDENCY_VIEW_LOCAL_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO_KHR
-
VK_KHR_relaxed_block_layout
- Name String
-
VK_KHR_relaxed_block_layout - Extension Type
-
Device extension
- Registered Extension Number
-
145
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
John Kessenich johnkslang
-
Other Extension Metadata
- Last Modified Date
-
2017-03-26
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
John Kessenich, Google
-
Description
The VK_KHR_relaxed_block_layout extension allows implementations to
indicate they can support more variation in block Offset decorations.
For example, placing a vector of three floats at an offset of
16×N + 4.
See Offset and Stride Assignment for details.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_RELAXED_BLOCK_LAYOUT_EXTENSION_NAME -
VK_KHR_RELAXED_BLOCK_LAYOUT_SPEC_VERSION
VK_KHR_sampler_mirror_clamp_to_edge
- Name String
-
VK_KHR_sampler_mirror_clamp_to_edge - Extension Type
-
Device extension
- Registered Extension Number
-
15
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2019-08-17
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Tobias Hector, Imagination Technologies
-
Jon Leech, Khronos
-
Description
VK_KHR_sampler_mirror_clamp_to_edge extends the set of sampler address
modes to include an additional mode
(VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE) that effectively uses a
texture map twice as large as the original image in which the additional
half of the new image is a mirror image of the original image.
This new mode relaxes the need to generate images whose opposite edges match by using the original image to generate a matching “mirror image”. This mode allows the texture to be mirrored only once in the negative s, t, and r directions.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2.
However, if Vulkan 1.2 is supported and this extension is not, the
VkSamplerAddressMode
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE is optional.
Since the original extension did not use an author suffix on the enum
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE, it is used by both core
and extension implementations.
New Enum Constants
-
VK_KHR_SAMPLER_MIRROR_CLAMP_TO_EDGE_EXTENSION_NAME -
VK_KHR_SAMPLER_MIRROR_CLAMP_TO_EDGE_SPEC_VERSION -
Extending VkSamplerAddressMode:
-
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE -
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE_KHR
-
Example
Creating a sampler with the new address mode in each dimension
VkSamplerCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO // sType
// Other members set to application-desired values
};
createInfo.addressModeU = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
createInfo.addressModeV = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
createInfo.addressModeW = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
VkSampler sampler;
VkResult result = vkCreateSampler(
device,
&createInfo,
&sampler);
Issues
1) Why are both KHR and core versions of the
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE token present?
RESOLVED: This functionality was intended to be required in Vulkan 1.0. We realized shortly before public release that not all implementations could support it, and moved the functionality into an optional extension, but did not apply the KHR extension suffix. Adding a KHR-suffixed alias of the non-suffixed enum has been done to comply with our own naming rules.
In a related change, before spec revision 1.1.121 this extension was hardwiring into the spec Makefile so it was always included with the Specification, even in the core-only versions. This has now been reverted, and it is treated as any other extension.
Version History
-
Revision 1, 2016-02-16 (Tobias Hector)
-
Initial draft
-
-
Revision 2, 2019-08-14 (Jon Leech)
-
Add KHR-suffixed alias of non-suffixed enum.
-
-
Revision 3, 2019-08-17 (Jon Leech)
-
Add an issue explaining the reason for the extension API not being suffixed with KHR.
-
VK_KHR_sampler_ycbcr_conversion
- Name String
-
VK_KHR_sampler_ycbcr_conversion - Extension Type
-
Device extension
- Registered Extension Number
-
157
- Revision
-
14
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_maintenance1to be enabled for any device-level functionality -
Requires
VK_KHR_bind_memory2to be enabled for any device-level functionality -
Requires
VK_KHR_get_memory_requirements2to be enabled for any device-level functionality -
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Andrew Garrard fluppeteer
-
Other Extension Metadata
- Last Modified Date
-
2017-08-11
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Andrew Garrard, Samsung Electronics
-
Tobias Hector, Imagination Technologies
-
James Jones, NVIDIA
-
Daniel Koch, NVIDIA
-
Daniel Rakos, AMD
-
Romain Guy, Google
-
Jesse Hall, Google
-
Tom Cooksey, ARM Ltd
-
Jeff Leger, Qualcomm Technologies, Inc
-
Jan-Harald Fredriksen, ARM Ltd
-
Jan Outters, Samsung Electronics
-
Alon Or-bach, Samsung Electronics
-
Michael Worcester, Imagination Technologies
-
Jeff Bolz, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Matthew Netsch, Qualcomm Technologies, Inc
-
Description
The use of Y′CBCR sampler conversion is an area in 3D graphics not used by most Vulkan developers. It is mainly used for processing inputs from video decoders and cameras. The use of the extension assumes basic knowledge of Y′CBCR concepts.
This extension provides the ability to perform specified color space conversions during texture sampling operations for the Y′CBCR color space natively. It also adds a selection of multi-planar formats, image aspect plane, and the ability to bind memory to the planes of an image collectively or separately.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
However, if Vulkan 1.1 is supported and this extension is not, the
samplerYcbcrConversion capability is optional.
The original type, enum and command names are still available as aliases of
the core functionality.
New Structures
-
Extending VkBindImageMemoryInfo:
-
Extending VkImageFormatProperties2:
-
Extending VkImageMemoryRequirementsInfo2:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkSamplerCreateInfo, VkImageViewCreateInfo:
New Enum Constants
-
VK_KHR_SAMPLER_YCBCR_CONVERSION_EXTENSION_NAME -
VK_KHR_SAMPLER_YCBCR_CONVERSION_SPEC_VERSION -
Extending VkChromaLocation:
-
VK_CHROMA_LOCATION_COSITED_EVEN_KHR -
VK_CHROMA_LOCATION_MIDPOINT_KHR
-
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_KHR_EXT
-
-
Extending VkFormat:
-
VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16_KHR -
VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16_KHR -
VK_FORMAT_B16G16R16G16_422_UNORM_KHR -
VK_FORMAT_B8G8R8G8_422_UNORM_KHR -
VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16_KHR -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16_KHR -
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16_KHR -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16_KHR -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16_KHR -
VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16_KHR -
VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16_KHR -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16_KHR -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16_KHR -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16_KHR -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16_KHR -
VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16_KHR -
VK_FORMAT_G16B16G16R16_422_UNORM_KHR -
VK_FORMAT_G16_B16R16_2PLANE_420_UNORM_KHR -
VK_FORMAT_G16_B16R16_2PLANE_422_UNORM_KHR -
VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM_KHR -
VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM_KHR -
VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM_KHR -
VK_FORMAT_G8B8G8R8_422_UNORM_KHR -
VK_FORMAT_G8_B8R8_2PLANE_420_UNORM_KHR -
VK_FORMAT_G8_B8R8_2PLANE_422_UNORM_KHR -
VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM_KHR -
VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM_KHR -
VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM_KHR -
VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16_KHR -
VK_FORMAT_R10X6G10X6_UNORM_2PACK16_KHR -
VK_FORMAT_R10X6_UNORM_PACK16_KHR -
VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16_KHR -
VK_FORMAT_R12X4G12X4_UNORM_2PACK16_KHR -
VK_FORMAT_R12X4_UNORM_PACK16_KHR
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR -
VK_FORMAT_FEATURE_DISJOINT_BIT_KHR -
VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT_KHR -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR -
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR
-
-
Extending VkImageAspectFlagBits:
-
VK_IMAGE_ASPECT_PLANE_0_BIT_KHR -
VK_IMAGE_ASPECT_PLANE_1_BIT_KHR -
VK_IMAGE_ASPECT_PLANE_2_BIT_KHR
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_DISJOINT_BIT_KHR
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_KHR
-
-
Extending VkSamplerYcbcrModelConversion:
-
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020_KHR -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601_KHR -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709_KHR -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY_KHR
-
-
Extending VkSamplerYcbcrRange:
-
VK_SAMPLER_YCBCR_RANGE_ITU_FULL_KHR -
VK_SAMPLER_YCBCR_RANGE_ITU_NARROW_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO_KHR -
VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES_KHR -
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_IMAGE_FORMAT_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO_KHR
-
If VK_EXT_debug_report is supported:
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_EXT
-
Version History
-
Revision 1, 2017-01-24 (Andrew Garrard)
-
Initial draft
-
-
Revision 2, 2017-01-25 (Andrew Garrard)
-
After initial feedback
-
-
Revision 3, 2017-01-27 (Andrew Garrard)
-
Higher bit depth formats, renaming, swizzle
-
-
Revision 4, 2017-02-22 (Andrew Garrard)
-
Added query function, formats as RGB, clarifications
-
-
Revision 5, 2017-04-?? (Andrew Garrard)
-
Simplified query and removed output conversions
-
-
Revision 6, 2017-04-24 (Andrew Garrard)
-
Tidying, incorporated new image query, restored transfer functions
-
-
Revision 7, 2017-04-25 (Andrew Garrard)
-
Added cosited option/midpoint requirement for formats, “bypassConversion”
-
-
Revision 8, 2017-04-25 (Andrew Garrard)
-
Simplified further
-
-
Revision 9, 2017-04-27 (Andrew Garrard)
-
Disjoint no more
-
-
Revision 10, 2017-04-28 (Andrew Garrard)
-
Restored disjoint
-
-
Revision 11, 2017-04-29 (Andrew Garrard)
-
Now Ycbcr conversion, and KHR
-
-
Revision 12, 2017-06-06 (Andrew Garrard)
-
Added conversion to image view creation
-
-
Revision 13, 2017-07-13 (Andrew Garrard)
-
Allowed cosited-only chroma samples for formats
-
-
Revision 14, 2017-08-11 (Andrew Garrard)
-
Reflected quantization changes in BT.2100-1
-
VK_KHR_separate_depth_stencil_layouts
- Name String
-
VK_KHR_separate_depth_stencil_layouts - Extension Type
-
Device extension
- Registered Extension Number
-
242
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_create_renderpass2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-25
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Jesse Barker, Unity
-
Tobias Hector, AMD
-
Description
This extension allows image memory barriers for depth/stencil images to have
just one of the VK_IMAGE_ASPECT_DEPTH_BIT or
VK_IMAGE_ASPECT_STENCIL_BIT aspect bits set, rather than require both.
This allows their layouts to be set independently.
To support depth/stencil images with different layouts for the depth and
stencil aspects, the depth/stencil attachment interface has been updated to
support a separate layout for stencil.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_SEPARATE_DEPTH_STENCIL_LAYOUTS_EXTENSION_NAME -
VK_KHR_SEPARATE_DEPTH_STENCIL_LAYOUTS_SPEC_VERSION -
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL_KHR -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR -
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR -
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT_KHR -
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES_KHR
-
VK_KHR_shader_atomic_int64
- Name String
-
VK_KHR_shader_atomic_int64 - Extension Type
-
Device extension
- Registered Extension Number
-
181
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Aaron Hagan ahagan
-
Other Extension Metadata
- Last Modified Date
-
2018-07-05
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
This extension provides API support for
GL_ARB_gpu_shader_int64andGL_EXT_shader_atomic_int64
-
- Contributors
-
-
Aaron Hagan, AMD
-
Daniel Rakos, AMD
-
Jeff Bolz, NVIDIA
-
Neil Henning, Codeplay
-
Description
This extension advertises the SPIR-V Int64Atomics capability for Vulkan, which allows a shader to contain 64-bit atomic operations on signed and unsigned integers. The supported operations include OpAtomicMin, OpAtomicMax, OpAtomicAnd, OpAtomicOr, OpAtomicXor, OpAtomicAdd, OpAtomicExchange, and OpAtomicCompareExchange.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the
KHR suffix omitted.
However, if Vulkan 1.2 is supported and this extension is not, the
shaderBufferInt64Atomics capability is optional.
The original type, enum and command names are still available as aliases of
the core functionality.
New Enum Constants
-
VK_KHR_SHADER_ATOMIC_INT64_EXTENSION_NAME -
VK_KHR_SHADER_ATOMIC_INT64_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES_KHR
-
VK_KHR_shader_draw_parameters
- Name String
-
VK_KHR_shader_draw_parameters - Extension Type
-
Device extension
- Registered Extension Number
-
64
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_shader_draw_parameters -
This extension provides API support for
GL_ARB_shader_draw_parameters -
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Daniel Koch, NVIDIA Corporation
-
Jeff Bolz, NVIDIA
-
Daniel Rakos, AMD
-
Jan-Harald Fredriksen, ARM
-
John Kessenich, Google
-
Stuart Smith, IMG
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_shader_draw_parameters
The extension provides access to three additional built-in shader variables in Vulkan:
-
BaseInstance, containing thefirstInstanceparameter passed to drawing commands, -
BaseVertex, containing thefirstVertexorvertexOffsetparameter passed to drawing commands, and -
DrawIndex, containing the index of the draw call currently being processed from an indirect drawing call.
When using GLSL source-based shader languages, the following variables from
GL_ARB_shader_draw_parameters can map to these SPIR-V built-in
decorations:
-
in int gl_BaseInstanceARB;→BaseInstance, -
in int gl_BaseVertexARB;→BaseVertex, and -
in int gl_DrawIDARB;→DrawIndex.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1.
However, the shaderDrawParameters
feature bit was added to distinguish whether it is actually available or
not.
New Enum Constants
-
VK_KHR_SHADER_DRAW_PARAMETERS_EXTENSION_NAME -
VK_KHR_SHADER_DRAW_PARAMETERS_SPEC_VERSION
Issues
1) Is this the same functionality as GL_ARB_shader_draw_parameters?
RESOLVED: It is actually a superset, as it also adds in support for arrayed drawing commands.
In GL for GL_ARB_shader_draw_parameters, gl_BaseVertexARB holds the
integer value passed to the parameter to the command that resulted in the
current shader invocation.
In the case where the command has no baseVertex parameter, the value of
gl_BaseVertexARB is zero.
This means that gl_BaseVertexARB = baseVertex (for
glDrawElements commands with baseVertex) or 0.
In particular there are no glDrawArrays commands that take a
baseVertex parameter.
Now in Vulkan, we have BaseVertex = vertexOffset (for indexed
drawing commands) or firstVertex (for arrayed drawing commands), and
so Vulkan’s version is really a superset of GL functionality.
VK_KHR_shader_float16_int8
- Name String
-
VK_KHR_shader_float16_int8 - Extension Type
-
Device extension
- Registered Extension Number
-
83
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Alexander Galazin alegal-arm
-
Other Extension Metadata
- Last Modified Date
-
2018-03-07
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
This extension interacts with
VK_KHR_8bit_storage -
This extension interacts with
VK_KHR_16bit_storage -
This extension interacts with
VK_KHR_shader_float_controls -
This extension provides API support for
GL_EXT_shader_explicit_arithmetic_types
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Alexander Galazin, Arm
-
Jan-Harald Fredriksen, Arm
-
Jeff Bolz, NVIDIA
-
Graeme Leese, Broadcom
-
Daniel Rakos, AMD
-
Description
The VK_KHR_shader_float16_int8 extension allows use of 16-bit
floating-point types and 8-bit integer types in shaders for arithmetic
operations.
It introduces two new optional features shaderFloat16 and
shaderInt8 which directly map to the Float16 and the Int8
SPIR-V capabilities.
The VK_KHR_shader_float16_int8 extension also specifies precision
requirements for half-precision floating-point SPIR-V operations.
This extension does not enable use of 8-bit integer types or 16-bit
floating-point types in any shader input and
output interfaces and therefore does not supersede the
VK_KHR_8bit_storage or VK_KHR_16bit_storage extensions.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the
KHR suffix omitted.
However, if Vulkan 1.2 is supported and this extension is not, both the
shaderFloat16 and shaderInt8 capabilities are optional.
The original type, enum and command names are still available as aliases of
the core functionality.
New Enum Constants
-
VK_KHR_SHADER_FLOAT16_INT8_EXTENSION_NAME -
VK_KHR_SHADER_FLOAT16_INT8_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT16_INT8_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES_KHR
-
VK_KHR_shader_float_controls
- Name String
-
VK_KHR_shader_float_controls - Extension Type
-
Device extension
- Registered Extension Number
-
198
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Alexander Galazin alegal-arm
-
Other Extension Metadata
- Last Modified Date
-
2018-09-11
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
This extension requires
SPV_KHR_float_controls
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Alexander Galazin, Arm
-
Jan-Harald Fredriksen, Arm
-
Jeff Bolz, NVIDIA
-
Graeme Leese, Broadcom
-
Daniel Rakos, AMD
-
Description
The VK_KHR_shader_float_controls extension enables efficient use of
floating-point computations through the ability to query and override the
implementation’s default behavior for rounding modes, denormals, signed
zero, and infinity.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_SHADER_FLOAT_CONTROLS_EXTENSION_NAME -
VK_KHR_SHADER_FLOAT_CONTROLS_SPEC_VERSION -
Extending VkShaderFloatControlsIndependence:
-
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_32_BIT_ONLY_KHR -
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_ALL_KHR -
VK_SHADER_FLOAT_CONTROLS_INDEPENDENCE_NONE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES_KHR
-
Issues
1) Which instructions must flush denorms?
RESOLVED: Only floating-point conversion, floating-point arithmetic,
floating-point relational (except OpIsNaN, OpIsInf), and
floating-point GLSL.std.450 extended instructions must flush denormals.
2) What is the denorm behavior for intermediate results?
RESOLVED: When a SPIR-V instruction is implemented as a sequence of other instructions:
-
in the
DenormFlushToZeroexecution mode, the intermediate instructions may flush denormals, the final result of the sequence must not be denormal. -
in the
DenormPreserveexecution mode, denormals must be preserved throughout the whole sequence.
3) Do denorm and rounding mode controls apply to OpSpecConstantOp?
RESOLVED: Yes, except when the opcode is OpQuantizeToF16.
4) The SPIR-V specification says that OpConvertFToU and
OpConvertFToS unconditionally round towards zero.
Do the rounding mode controls specified through the execution modes apply to
them?
RESOLVED: No, these instructions unconditionally round towards zero.
5) Do any of the “Pack” GLSL.std.450 instructions count as conversion instructions and have the rounding mode applied?
RESOLVED: No, only instructions listed in “section 3.32.11. Conversion Instructions” of the SPIR-V specification count as conversion instructions.
6) When using inf/nan-ignore mode, what is expected of OpIsNan and
OpIsInf?
RESOLVED: These instructions must always accurately detect inf/nan if it is passed to them.
Version 4 API incompatibility
The original versions of VK_KHR_shader_float_controls shipped with
booleans named “separateDenormSettings” and
“separateRoundingModeSettings”, which at first glance could have indicated
“they can all be set independently, or not”.
However the spec language as written indicated that the 32-bit value could
always be set independently, and only the 16- and 64-bit controls needed to
be the same if these values were VK_FALSE.
As a result of this slight disparity, and lack of test coverage for this facet of the extension, we ended up with two different behaviors in the wild, where some implementations worked as written, and others worked based on the naming. As these are hard limits in hardware with reasons for exposure as written, it was not possible to standardise on a single way to make this work within the existing API.
No known users of this part of the extension exist in the wild, and as such the Vulkan WG took the unusual step of retroactively changing the once boolean value into a tri-state enum, breaking source compatibility. This was however done in such a way as to retain ABI compatibility, in case any code using this did exist; with the numerical values 0 and 1 retaining their original specified meaning, and a new value signifying the additional “all need to be set together” state. If any applications exist today, compiled binaries will continue to work as written in most cases, but will need changes before the code can be recompiled.
Version History
-
Revision 4, 2019-06-18 (Tobias Hector)
-
Modified settings restrictions, see Version 4 API incompatibility
-
-
Revision 3, 2018-09-11 (Alexander Galazin)
-
Minor restructuring
-
-
Revision 2, 2018-04-17 (Alexander Galazin)
-
Added issues and resolutions
-
-
Revision 1, 2018-04-11 (Alexander Galazin)
-
Initial draft
-
VK_KHR_shader_integer_dot_product
- Name String
-
VK_KHR_shader_integer_dot_product - Extension Type
-
Device extension
- Registered Extension Number
-
281
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Kevin Petit kevinpetit
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-06-16
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
This extension requires
SPV_KHR_integer_dot_product. -
This extension interacts with
VK_KHR_shader_float16_int8.
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Kévin Petit, Arm Ltd.
-
Jeff Bolz, NVidia
-
Spencer Fricke, Samsung
-
Jesse Hall, Google
-
John Kessenich, Google
-
Graeme Leese, Broadcom
-
Einar Hov, Arm Ltd.
-
Stuart Brady, Arm Ltd.
-
Pablo Cascon, Arm Ltd.
-
Tobias Hector, AMD
-
Jeff Leger, Qualcomm
-
Ruihao Zhang, Qualcomm
-
Pierre Boudier, NVidia
-
Jon Leech, The Khronos Group
-
Tom Olson, Arm Ltd.
-
Description
This extension adds support for the integer dot product SPIR-V instructions defined in SPV_KHR_integer_dot_product. These instructions are particularly useful for neural network inference and training but find uses in other general purpose compute applications as well.
New Enum Constants
-
VK_KHR_SHADER_INTEGER_DOT_PRODUCT_EXTENSION_NAME -
VK_KHR_SHADER_INTEGER_DOT_PRODUCT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_PROPERTIES_KHR
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
VK_KHR_shader_non_semantic_info
- Name String
-
VK_KHR_shader_non_semantic_info - Extension Type
-
Device extension
- Registered Extension Number
-
294
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Baldur Karlsson baldurk
-
Other Extension Metadata
- Last Modified Date
-
2019-10-16
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
This extension requires
SPV_KHR_non_semantic_info
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Baldur Karlsson, Valve
-
Description
This extension allows the use of the SPV_KHR_non_semantic_info extension
in SPIR-V shader modules.
New Enum Constants
-
VK_KHR_SHADER_NON_SEMANTIC_INFO_EXTENSION_NAME -
VK_KHR_SHADER_NON_SEMANTIC_INFO_SPEC_VERSION
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3 Because the extension has no API controlling its functionality, this results only in a change to the SPIR-V Extensions table.
VK_KHR_shader_subgroup_extended_types
- Name String
-
VK_KHR_shader_subgroup_extended_types - Extension Type
-
Device extension
- Registered Extension Number
-
176
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Neil Henning sheredom
-
Other Extension Metadata
- Last Modified Date
-
2019-01-08
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
This extension provides API support for
GLSL_EXT_shader_subgroup_extended_types
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jan-Harald Fredriksen, Arm
-
Neil Henning, AMD
-
Daniel Koch, NVIDIA
-
Jeff Leger, Qualcomm
-
Graeme Leese, Broadcom
-
David Neto, Google
-
Daniel Rakos, AMD
-
Description
This extension enables the Non Uniform Group Operations in SPIR-V to support 8-bit integer, 16-bit integer, 64-bit integer, 16-bit floating-point, and vectors of these types.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_SHADER_SUBGROUP_EXTENDED_TYPES_EXTENSION_NAME -
VK_KHR_SHADER_SUBGROUP_EXTENDED_TYPES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES_KHR
-
VK_KHR_shader_terminate_invocation
- Name String
-
VK_KHR_shader_terminate_invocation - Extension Type
-
Device extension
- Registered Extension Number
-
216
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2020-08-11
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
Requires the
SPV_KHR_terminate_invocationSPIR-V extension.
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Alan Baker, Google
-
Jeff Bolz, NVIDIA
-
Jesse Hall, Google
-
Ralph Potter, Samsung
-
Tom Olson, Arm
-
Description
This extension adds Vulkan support for the
SPV_KHR_terminate_invocation
SPIR-V extension.
That SPIR-V extension provides a new instruction,
OpTerminateInvocation, which causes a shader invocation to immediately
terminate and sets the coverage of shaded samples to 0; only previously
executed instructions will have observable effects.
The OpTerminateInvocation instruction, along with the
OpDemoteToHelperInvocation instruction from the
VK_EXT_shader_demote_to_helper_invocation extension, together
replace the OpKill instruction, which could behave like either of these
instructions.
OpTerminateInvocation provides the behavior required by the GLSL
discard statement, and should be used when available by GLSL compilers
and applications that need the GLSL discard behavior.
New Enum Constants
-
VK_KHR_SHADER_TERMINATE_INVOCATION_EXTENSION_NAME -
VK_KHR_SHADER_TERMINATE_INVOCATION_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES_KHR
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
VK_KHR_spirv_1_4
- Name String
-
VK_KHR_spirv_1_4 - Extension Type
-
Device extension
- Registered Extension Number
-
237
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
Requires
VK_KHR_shader_float_controlsto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2019-04-01
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires SPIR-V 1.4.
-
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Alexander Galazin, Arm
-
David Neto, Google
-
Jesse Hall, Google
-
John Kessenich, Google
-
Neil Henning, AMD
-
Tom Olson, Arm
-
Description
This extension allows the use of SPIR-V 1.4 shader modules. SPIR-V 1.4’s new features primarily make it an easier target for compilers from high-level languages, rather than exposing new hardware functionality.
SPIR-V 1.4 incorporates features that are also available separately as
extensions.
SPIR-V 1.4 shader modules do not need to enable those extensions with the
OpExtension opcode, since they are integral parts of SPIR-V 1.4.
SPIR-V 1.4 introduces new floating point execution mode capabilities, also
available via SPV_KHR_float_controls.
Implementations are not required to support all of these new capabilities;
support can be queried using
VkPhysicalDeviceFloatControlsPropertiesKHR from the
VK_KHR_shader_float_controls extension.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
Issues
1. Should we have an extension specific to this SPIR-V version, or add a version-generic query for SPIR-V version? SPIR-V 1.4 does not need any other API changes.
RESOLVED: Just expose SPIR-V 1.4.
Most new SPIR-V versions introduce optionally-required capabilities or have implementation-defined limits, and would need more API and specification changes specific to that version to make them available in Vulkan. For example, to support the subgroup capabilities added in SPIR-V 1.3 required introducing VkPhysicalDeviceSubgroupProperties to allow querying the supported group operation categories, maximum supported subgroup size, etc. While we could expose the parts of a new SPIR-V version that do not need accompanying changes generically, we will still end up writing extensions specific to each version for the remaining parts. Thus the generic mechanism will not reduce future spec-writing effort. In addition, making it clear which parts of a future version are supported by the generic mechanism and which cannot be used without specific support would be difficult to get right ahead of time.
2. Can different stages of the same pipeline use shaders with different SPIR-V versions?
RESOLVED: Yes.
Mixing SPIR-V versions 1.0-1.3 in the same pipeline has not been disallowed, so it would be inconsistent to disallow mixing 1.4 with previous versions.. SPIR-V 1.4 does not introduce anything that should cause new difficulties here.
3. Must Vulkan extensions corresponding to SPIR-V extensions that were promoted to core in 1.4 be enabled in order to use that functionality in a SPIR-V 1.4 module?
RESOLVED: No, with caveats.
The SPIR-V 1.4 module does not need to declare the SPIR-V extensions, since the functionality is now part of core, so there is no need to enable the Vulkan extension that allows SPIR-V modules to declare the SPIR-V extension. However, when the functionality that is now core in SPIR-V 1.4 is optionally supported, the query for support is provided by a Vulkan extension, and that query can only be used if the extension is enabled.
This applies to any SPIR-V version; specifically for SPIR-V 1.4 this only
applies to the functionality from SPV_KHR_float_controls, which was made
available in Vulkan by VK_KHR_shader_float_controls.
Even though the extension was promoted in SPIR-V 1.4, the capabilities are
still optional in implementations that support VK_KHR_spirv_1_4.
A SPIR-V 1.4 module does not need to enable SPV_KHR_float_controls in
order to use the capabilities, so if the application has a priori
knowledge that the implementation supports the capabilities, it does not
need to enable VK_KHR_shader_float_controls.
However, if it does not have this knowledge and has to query for support at
runtime, it must enable VK_KHR_shader_float_controls in order to
use VkPhysicalDeviceFloatControlsPropertiesKHR.
VK_KHR_storage_buffer_storage_class
- Name String
-
VK_KHR_storage_buffer_storage_class - Extension Type
-
Device extension
- Registered Extension Number
-
132
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Alexander Galazin alegal-arm
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_storage_buffer_storage_class -
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
Alexander Galazin, ARM
-
David Neto, Google
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_storage_buffer_storage_class
This extension provides a new SPIR-V StorageBuffer storage class.
A Block-decorated object in this class is equivalent to a
BufferBlock-decorated object in the Uniform storage class.
New Enum Constants
-
VK_KHR_STORAGE_BUFFER_STORAGE_CLASS_EXTENSION_NAME -
VK_KHR_STORAGE_BUFFER_STORAGE_CLASS_SPEC_VERSION
VK_KHR_synchronization2
- Name String
-
VK_KHR_synchronization2 - Extension Type
-
Device extension
- Registered Extension Number
-
315
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2020-12-03
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
Interacts with
VK_KHR_create_renderpass2
-
- Contributors
-
-
Tobias Hector
-
Description
This extension modifies the original core synchronization APIs to simplify the interface and improve usability of these APIs. It also adds new pipeline stage and access flag types that extend into the 64-bit range, as we have run out within the 32-bit range. The new flags are identical to the old values within the 32-bit range, with new stages and bits beyond that.
Pipeline stages and access flags are now specified together in memory
barrier structures, making the connection between the two more obvious.
Additionally, scoping the pipeline stages into the barrier structs allows
the use of the MEMORY_READ and MEMORY_WRITE flags without
sacrificing precision.
The per-stage access flags should be used to disambiguate specific accesses
in a given stage or set of stages - for instance, between uniform reads and
sampling operations.
Layout transitions have been simplified as well; rather than requiring a
different set of layouts for depth/stencil/color attachments, there are
generic VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR and
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR layouts which are contextually
applied based on the image format.
For example, for a depth format image,
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR is equivalent to
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR.
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR also functionally replaces
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL.
Events are now more efficient, because they include memory dependency information when you set them on the device. Previously, this information was only known when waiting on an event, so the dependencies could not be satisfied until the wait occurred. That sometimes meant stalling the pipeline when the wait occurred. The new API provides enough information for implementations to satisfy these dependencies in parallel with other tasks.
Queue submission has been changed to wrap command buffers and semaphores in
extensible structures, which incorporate changes from Vulkan 1.1,
VK_KHR_device_group, and VK_KHR_timeline_semaphore.
This also adds a pipeline stage to the semaphore signal operation, mirroring
the existing pipeline stage specification for wait operations.
Other miscellaneous changes include:
-
Events can now be specified as interacting only with the device, allowing more efficient access to the underlying object.
-
Image memory barriers that do not perform an image layout transition can be specified by setting
oldLayoutequal tonewLayout.-
E.g. the old and new layout can both be set to
VK_IMAGE_LAYOUT_UNDEFINED, without discarding data in the image.
-
-
Queue family ownership transfer parameters are simplified in some cases.
-
Where two synchronization commands need to be matched up (queue transfer operations, events), the dependency information specified in each place must now match completely for consistency.
-
Extensions with commands or functions with a VkPipelineStageFlags or VkPipelineStageFlagBits parameter have had those APIs replaced with equivalents using VkPipelineStageFlags2KHR.
-
The new event and barrier interfaces are now more extensible for future changes.
-
Relevant pipeline stage masks can now be specified as empty with the new
VK_PIPELINE_STAGE_NONE_KHRandVK_PIPELINE_STAGE_2_NONE_KHRvalues. -
VkMemoryBarrier2KHR can be chained to VkSubpassDependency2, overriding the original 32-bit stage and access masks.
New Commands
If VK_AMD_buffer_marker is supported:
If VK_NV_device_diagnostic_checkpoints is supported:
New Enum Constants
-
VK_KHR_SYNCHRONIZATION_2_EXTENSION_NAME -
VK_KHR_SYNCHRONIZATION_2_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_NONE_KHR
-
-
Extending VkEventCreateFlagBits:
-
VK_EVENT_CREATE_DEVICE_ONLY_BIT_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR -
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_NONE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2_KHR -
VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO_KHR -
VK_STRUCTURE_TYPE_DEPENDENCY_INFO_KHR -
VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2_KHR -
VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES_KHR -
VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO_KHR -
VK_STRUCTURE_TYPE_SUBMIT_INFO_2_KHR
-
If VK_EXT_blend_operation_advanced is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT
-
If VK_EXT_conditional_rendering is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT
-
If VK_EXT_fragment_density_map is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT
-
If VK_EXT_transform_feedback is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT -
VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT -
VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT
-
If VK_KHR_acceleration_structure is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR -
VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
-
If VK_KHR_fragment_shading_rate is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
If VK_KHR_ray_tracing_pipeline is supported:
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR
-
If VK_NV_device_diagnostic_checkpoints is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CHECKPOINT_DATA_2_NV -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_2_NV
-
If VK_NV_device_generated_commands is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV -
VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV
-
If VK_NV_mesh_shader is supported:
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV -
VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_NV
-
If VK_NV_ray_tracing is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_NV -
VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_NV
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_NV -
VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_NV
-
If VK_NV_shading_rate_image is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
VK_KHR_timeline_semaphore
- Name String
-
VK_KHR_timeline_semaphore - Extension Type
-
Device extension
- Registered Extension Number
-
208
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jason Ekstrand jekstrand
-
Other Extension Metadata
- Last Modified Date
-
2019-06-12
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension interacts with
VK_KHR_external_semaphore_capabilities -
This extension interacts with
VK_KHR_external_semaphore -
This extension interacts with
VK_KHR_external_semaphore_win32 -
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Yuriy O’Donnell, Epic Games
-
Jason Ekstrand, Intel
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Daniel Rakos, AMD
-
Ray Smith, Arm
-
Description
This extension introduces a new type of semaphore that has an integer payload identifying a point in a timeline. Such timeline semaphores support the following operations:
-
Host query - A host operation that allows querying the payload of the timeline semaphore.
-
Host wait - A host operation that allows a blocking wait for a timeline semaphore to reach a specified value.
-
Host signal - A host operation that allows advancing the timeline semaphore to a specified value.
-
Device wait - A device operation that allows waiting for a timeline semaphore to reach a specified value.
-
Device signal - A device operation that allows advancing the timeline semaphore to a specified value.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkSemaphoreCreateInfo, VkPhysicalDeviceExternalSemaphoreInfo:
-
Extending VkSubmitInfo, VkBindSparseInfo:
New Enum Constants
-
VK_KHR_TIMELINE_SEMAPHORE_EXTENSION_NAME -
VK_KHR_TIMELINE_SEMAPHORE_SPEC_VERSION -
Extending VkSemaphoreType:
-
VK_SEMAPHORE_TYPE_BINARY_KHR -
VK_SEMAPHORE_TYPE_TIMELINE_KHR
-
-
Extending VkSemaphoreWaitFlagBits:
-
VK_SEMAPHORE_WAIT_ANY_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO_KHR -
VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO_KHR -
VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO_KHR
-
Issues
1) Do we need a new object type for this?
RESOLVED: No, we just introduce a new type of semaphore object, as
VK_KHR_external_semaphore_win32 already uses semaphores as the destination
for importing D3D12 fence objects, which are semantically close/identical to
the proposed synchronization primitive.
2) What type of payload the new synchronization primitive has?
RESOLVED: A 64-bit unsigned integer that can only be set to strictly increasing values by signal operations and is not changed by wait operations.
3) Does the new synchronization primitive have the same signal-before-wait requirement as the existing semaphores do?
RESOLVED: No. Timeline semaphores support signaling and waiting entirely asynchronously. It is the responsibility of the client to avoid deadlock.
4) Does the new synchronization primitive allow resetting its payload?
RESOLVED: No, allowing the payload value to “go backwards” is problematic. Applications looking for reset behavior should create a new instance of the sychronization primitive instead.
5) How do we enable host waits on the synchronization primitive?
RESOLVED: Both a non-blocking query of the current payload value of the synchronization primitive, and a blocking wait operation are provided.
6) How do we enable device waits and signals on the synchronization primitive?
RESOLVED: Similar to VK_KHR_external_semaphore_win32, this extension
introduces a new structure that can be chained to VkSubmitInfo to
specify the values signaled semaphores should be set to, and the values
waited semaphores need to reach.
7) Can the new synchronization primitive be used to synchronize presentation and swapchain image acquisition operations?
RESOLVED: Some implementations may have problems with supporting that directly, thus it is not allowed in this extension.
8) Do we want to support external sharing of the new synchronization primitive type?
RESOLVED: Yes.
Timeline semaphore specific external sharing capabilities can be queried
using vkGetPhysicalDeviceExternalSemaphoreProperties by chaining the
new VkSemaphoreTypeCreateInfoKHR structure to its
pExternalSemaphoreInfo structure.
This allows having a different set of external semaphore handle types
supported for timeline semaphores vs binary semaphores.
9) Do we need to add a host signal operation for the new synchronization primitive type?
RESOLVED: Yes. This helps in situations where one host thread submits a workload but another host thread has the information on when the workload is ready to be executed.
10) How should the new synchronization primitive interact with the ordering
requirements of the original VkSemaphore?
RESOLVED: Prior to calling any command which may cause a wait operation on a binary semaphore, the client must ensure that the semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends (if any) must have also been submitted for execution.
11) Should we have separate feature bits for different sub-features of timeline semaphores?
RESOLVED: No.
The only feature which cannot be supported universally is timeline semaphore
import/export.
For import/export, the client is already required to query available
external handle types via
vkGetPhysicalDeviceExternalSemaphoreProperties and provide the
semaphore type by adding a VkSemaphoreTypeCreateInfoKHR structure to
the pNext chain of VkPhysicalDeviceExternalSemaphoreInfo so no
new feature bit is required.
Version History
-
Revision 1, 2018-05-10 (Jason Ekstrand)
-
Initial version
-
-
Revision 2, 2019-06-12 (Jason Ekstrand)
-
Added an initialValue parameter to timeline semaphore creation
-
VK_KHR_uniform_buffer_standard_layout
- Name String
-
VK_KHR_uniform_buffer_standard_layout - Extension Type
-
Device extension
- Registered Extension Number
-
254
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Graeme Leese gnl21
-
Other Extension Metadata
- Last Modified Date
-
2019-01-25
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Graeme Leese, Broadcom
-
Jeff Bolz, NVIDIA
-
Tobias Hector, AMD
-
Jason Ekstrand, Intel
-
Neil Henning, AMD
-
Description
This extension enables tighter array and struct packing to be used with uniform buffers.
It modifies the alignment rules for uniform buffers, allowing for tighter packing of arrays and structures. This allows, for example, the std430 layout, as defined in GLSL to be supported in uniform buffers.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_KHR_UNIFORM_BUFFER_STANDARD_LAYOUT_EXTENSION_NAME -
VK_KHR_UNIFORM_BUFFER_STANDARD_LAYOUT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES_KHR
-
VK_KHR_variable_pointers
- Name String
-
VK_KHR_variable_pointers - Extension Type
-
Device extension
- Registered Extension Number
-
121
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_storage_buffer_storage_classto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_variable_pointers -
Promoted to Vulkan 1.1 Core
-
- Contributors
-
-
John Kessenich, Google
-
Neil Henning, Codeplay
-
David Neto, Google
-
Daniel Koch, Nvidia
-
Graeme Leese, Broadcom
-
Weifeng Zhang, Qualcomm
-
Stephen Clarke, Imagination Technologies
-
Jason Ekstrand, Intel
-
Jesse Hall, Google
-
Description
The VK_KHR_variable_pointers extension allows implementations to indicate
their level of support for the SPV_KHR_variable_pointers SPIR-V extension.
The SPIR-V extension allows shader modules to use invocation-private
pointers into uniform and/or storage buffers, where the pointer values can
be dynamic and non-uniform.
The SPV_KHR_variable_pointers extension introduces two capabilities.
The first, VariablePointersStorageBuffer, must be supported by all
implementations of this extension.
The second, VariablePointers, is optional.
Promotion to Vulkan 1.1
All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted, however support for the
variablePointersStorageBuffer feature is made optional.
The original type, enum and command names are still available as aliases of
the core functionality.
New Enum Constants
-
VK_KHR_VARIABLE_POINTERS_EXTENSION_NAME -
VK_KHR_VARIABLE_POINTERS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES_KHR
-
Issues
1) Do we need an optional property for the SPIR-V
VariablePointersStorageBuffer capability or should it be mandatory when
this extension is advertised?
RESOLVED: Add it as a distinct feature, but make support mandatory. Adding it as a feature makes the extension easier to include in a future core API version. In the extension, the feature is mandatory, so that presence of the extension guarantees some functionality. When included in a core API version, the feature would be optional.
2) Can support for these capabilities vary between shader stages?
RESOLVED: No, if the capability is supported in any stage it must be supported in all stages.
3) Should the capabilities be features or limits?
RESOLVED: Features, primarily for consistency with other similar extensions.
VK_KHR_vulkan_memory_model
- Name String
-
VK_KHR_vulkan_memory_model - Extension Type
-
Device extension
- Registered Extension Number
-
212
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2018-12-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
This extension requires
SPV_KHR_vulkan_memory_model
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Alan Baker, Google
-
Tobias Hector, AMD
-
David Neto, Google
-
Robert Simpson, Qualcomm Technologies, Inc.
-
Brian Sumner, AMD
-
Description
The VK_KHR_vulkan_memory_model extension allows use of the
Vulkan Memory Model, which formally defines how to
synchronize memory accesses to the same memory locations performed by
multiple shader invocations.
|
Note
Version 3 of the spec added a member
( |
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the
KHR suffix omitted.
However, if Vulkan 1.2 is supported and this extension is not, the
vulkanMemoryModel capability is optional.
The original type, enum and command names are still available as aliases of
the core functionality.
New Enum Constants
-
VK_KHR_VULKAN_MEMORY_MODEL_EXTENSION_NAME -
VK_KHR_VULKAN_MEMORY_MODEL_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES_KHR
-
Version History
-
Revision 1, 2018-06-24 (Jeff Bolz)
-
Initial draft
-
-
Revision 3, 2018-12-10 (Jeff Bolz)
-
Add vulkanMemoryModelAvailabilityVisibilityChains member to the VkPhysicalDeviceVulkanMemoryModelFeaturesKHR structure.
-
VK_KHR_zero_initialize_workgroup_memory
- Name String
-
VK_KHR_zero_initialize_workgroup_memory - Extension Type
-
Device extension
- Registered Extension Number
-
326
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Alan Baker alan-baker
-
Other Extension Metadata
- Last Modified Date
-
2020-11-18
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Alan Baker, Google
-
Jeff Bolz, Nvidia
-
Jason Ekstrand, Intel
-
Description
This extension allows the use of a null constant initializer on shader Workgroup memory variables, allowing implementations to expose any special hardware or instructions they may have. Zero initialization is commonly used by applications running untrusted content (e.g. web browsers) as way of defeating memory-scraping attacks.
New Enum Constants
-
VK_KHR_ZERO_INITIALIZE_WORKGROUP_MEMORY_EXTENSION_NAME -
VK_KHR_ZERO_INITIALIZE_WORKGROUP_MEMORY_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES_KHR
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
VK_EXT_4444_formats
- Name String
-
VK_EXT_4444_formats - Extension Type
-
Device extension
- Registered Extension Number
-
341
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Joshua Ashton Joshua-Ashton
-
Other Extension Metadata
- Last Modified Date
-
2020-07-28
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Ashton, Valve
-
Jason Ekstrand, Intel
-
Description
This extension defines the VK_FORMAT_A4R4G4B4_UNORM_PACK16_EXT and
VK_FORMAT_A4B4G4R4_UNORM_PACK16_EXT formats which are defined in other
current graphics APIs.
This extension may be useful for building translation layers for those APIs or for porting applications that use these formats without having to resort to swizzles.
When VK_EXT_custom_border_color is used, these formats are not subject to the same restrictions for border color without format as with VK_FORMAT_B4G4R4A4_UNORM_PACK16.
New Enum Constants
-
VK_EXT_4444_FORMATS_EXTENSION_NAME -
VK_EXT_4444_FORMATS_SPEC_VERSION -
Extending VkFormat:
-
VK_FORMAT_A4B4G4R4_UNORM_PACK16_EXT -
VK_FORMAT_A4R4G4B4_UNORM_PACK16_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_4444_FORMATS_FEATURES_EXT
-
Promotion to Vulkan 1.3
This extension has been partially promoted. The format enumerants introduced by the extension are included in core Vulkan 1.3, with the EXT suffix omitted. However, runtime support for these formats is optional in core Vulkan 1.3, while if this extension is supported, runtime support is mandatory. The feature structure is not promoted. The original enum names are still available as aliases of the core functionality.
VK_EXT_buffer_device_address
- Name String
-
VK_EXT_buffer_device_address - Extension Type
-
Device extension
- Registered Extension Number
-
245
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Deprecated by
VK_KHR_buffer_device_addressextension-
Which in turn was promoted to Vulkan 1.2
-
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-01-06
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_physical_storage_buffer -
This extension provides API support for
GLSL_EXT_buffer_referenceandGLSL_EXT_buffer_reference_uvec2
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Neil Henning, AMD
-
Tobias Hector, AMD
-
Jason Ekstrand, Intel
-
Baldur Karlsson, Valve
-
Description
This extension allows the application to query a 64-bit buffer device
address value for a buffer, which can be used to access the buffer memory
via the PhysicalStorageBufferEXT storage class in the
GL_EXT_buffer_reference
GLSL extension and
SPV_EXT_physical_storage_buffer
SPIR-V extension.
It also allows buffer device addresses to be provided by a trace replay tool, so that it matches the address used when the trace was captured.
New Enum Constants
-
VK_EXT_BUFFER_DEVICE_ADDRESS_EXTENSION_NAME -
VK_EXT_BUFFER_DEVICE_ADDRESS_SPEC_VERSION -
Extending VkBufferCreateFlagBits:
-
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_EXT
-
-
Extending VkResult:
-
VK_ERROR_INVALID_DEVICE_ADDRESS_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_ADDRESS_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT
-
Issues
1) Where is VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_ADDRESS_FEATURES_EXT and VkPhysicalDeviceBufferAddressFeaturesEXT?
RESOLVED: They were renamed as
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT
and VkPhysicalDeviceBufferDeviceAddressFeaturesEXT accordingly for
consistency.
Even though, the old names can still be found in the generated header files
for compatibility.
Version History
-
Revision 1, 2018-11-01 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2019-01-06 (Jon Leech)
-
Minor updates to appendix for publication
-
VK_EXT_debug_marker
- Name String
-
VK_EXT_debug_marker - Extension Type
-
Device extension
- Registered Extension Number
-
23
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_debug_reportto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to
VK_EXT_debug_utilsextension
-
- Special Use
- Contact
-
-
Baldur Karlsson baldurk
-
Other Extension Metadata
- Last Modified Date
-
2017-01-31
- IP Status
-
No known IP claims.
- Contributors
-
-
Baldur Karlsson
-
Dan Ginsburg, Valve
-
Jon Ashburn, LunarG
-
Kyle Spagnoli, NVIDIA
-
Description
The VK_EXT_debug_marker extension is a device extension.
It introduces concepts of object naming and tagging, for better tracking of
Vulkan objects, as well as additional commands for recording annotations of
named sections of a workload to aid organization and offline analysis in
external tools.
New Enum Constants
-
VK_EXT_DEBUG_MARKER_EXTENSION_NAME -
VK_EXT_DEBUG_MARKER_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT -
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT -
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT
-
Examples
Example 1
Associate a name with an image, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages.
extern VkDevice device;
extern VkImage image;
// Must call extension functions through a function pointer:
PFN_vkDebugMarkerSetObjectNameEXT pfnDebugMarkerSetObjectNameEXT = (PFN_vkDebugMarkerSetObjectNameEXT)vkGetDeviceProcAddr(device, "vkDebugMarkerSetObjectNameEXT");
// Set a name on the image
const VkDebugMarkerObjectNameInfoEXT imageNameInfo =
{
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT, // sType
NULL, // pNext
VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT, // objectType
(uint64_t)image, // object
"Brick Diffuse Texture", // pObjectName
};
pfnDebugMarkerSetObjectNameEXT(device, &imageNameInfo);
// A subsequent error might print:
// Image 'Brick Diffuse Texture' (0xc0dec0dedeadbeef) is used in a
// command buffer with no memory bound to it.
Example 2
Annotating regions of a workload with naming information so that offline analysis tools can display a more usable visualisation of the commands submitted.
extern VkDevice device;
extern VkCommandBuffer commandBuffer;
// Must call extension functions through a function pointer:
PFN_vkCmdDebugMarkerBeginEXT pfnCmdDebugMarkerBeginEXT = (PFN_vkCmdDebugMarkerBeginEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerBeginEXT");
PFN_vkCmdDebugMarkerEndEXT pfnCmdDebugMarkerEndEXT = (PFN_vkCmdDebugMarkerEndEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerEndEXT");
PFN_vkCmdDebugMarkerInsertEXT pfnCmdDebugMarkerInsertEXT = (PFN_vkCmdDebugMarkerInsertEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerInsertEXT");
// Describe the area being rendered
const VkDebugMarkerMarkerInfoEXT houseMarker =
{
VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, // sType
NULL, // pNext
"Brick House", // pMarkerName
{ 1.0f, 0.0f, 0.0f, 1.0f }, // color
};
// Start an annotated group of calls under the 'Brick House' name
pfnCmdDebugMarkerBeginEXT(commandBuffer, &houseMarker);
{
// A mutable structure for each part being rendered
VkDebugMarkerMarkerInfoEXT housePartMarker =
{
VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, // sType
NULL, // pNext
NULL, // pMarkerName
{ 0.0f, 0.0f, 0.0f, 0.0f }, // color
};
// Set the name and insert the marker
housePartMarker.pMarkerName = "Walls";
pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker);
// Insert the drawcall for the walls
vkCmdDrawIndexed(commandBuffer, 1000, 1, 0, 0, 0);
// Insert a recursive region for two sets of windows
housePartMarker.pMarkerName = "Windows";
pfnCmdDebugMarkerBeginEXT(commandBuffer, &housePartMarker);
{
vkCmdDrawIndexed(commandBuffer, 75, 6, 1000, 0, 0);
vkCmdDrawIndexed(commandBuffer, 100, 2, 1450, 0, 0);
}
pfnCmdDebugMarkerEndEXT(commandBuffer);
housePartMarker.pMarkerName = "Front Door";
pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker);
vkCmdDrawIndexed(commandBuffer, 350, 1, 1650, 0, 0);
housePartMarker.pMarkerName = "Roof";
pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker);
vkCmdDrawIndexed(commandBuffer, 500, 1, 2000, 0, 0);
}
// End the house annotation started above
pfnCmdDebugMarkerEndEXT(commandBuffer);
Issues
1) Should the tag or name for an object be specified using the pNext
parameter in the object’s Vk*CreateInfo structure?
RESOLVED: No.
While this fits with other Vulkan patterns and would allow more type safety
and future proofing against future objects, it has notable downsides.
In particular passing the name at Vk*CreateInfo time does not allow
renaming, prevents late binding of naming information, and does not allow
naming of implicitly created objects such as queues and swapchain images.
2) Should the command annotation functions vkCmdDebugMarkerBeginEXT and vkCmdDebugMarkerEndEXT support the ability to specify a color?
RESOLVED: Yes. The functions have been expanded to take an optional color which can be used at will by implementations consuming the command buffer annotations in their visualisation.
3) Should the functions added in this extension accept an extensible structure as their parameter for a more flexible API, as opposed to direct function parameters? If so, which functions?
RESOLVED: Yes.
All functions have been modified to take a structure type with extensible
pNext pointer, to allow future extensions to add additional annotation
information in the same commands.
Version History
-
Revision 1, 2016-02-24 (Baldur Karlsson)
-
Initial draft, based on LunarG marker spec
-
-
Revision 2, 2016-02-26 (Baldur Karlsson)
-
Renamed Dbg to DebugMarker in function names
-
Allow markers in secondary command buffers under certain circumstances
-
Minor language tweaks and edits
-
-
Revision 3, 2016-04-23 (Baldur Karlsson)
-
Reorganise spec layout to closer match desired organisation
-
Added optional color to markers (both regions and inserted labels)
-
Changed functions to take extensible structs instead of direct function parameters
-
-
Revision 4, 2017-01-31 (Baldur Karlsson)
-
Added explicit dependency on VK_EXT_debug_report
-
Moved definition of VkDebugReportObjectTypeEXT to debug report chapter.
-
Fixed typo in dates in revision history
-
VK_EXT_debug_report
- Name String
-
VK_EXT_debug_report - Extension Type
-
Instance extension
- Registered Extension Number
-
12
- Revision
-
10
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Deprecated by
VK_EXT_debug_utilsextension
-
- Special Use
- Contact
-
-
Courtney Goeltzenleuchter courtney-g
-
Other Extension Metadata
- Last Modified Date
-
2020-12-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, LunarG
-
Dan Ginsburg, Valve
-
Jon Ashburn, LunarG
-
Mark Lobodzinski, LunarG
-
Description
Due to the nature of the Vulkan interface, there is very little error
information available to the developer and application.
By enabling optional validation layers and using the VK_EXT_debug_report
extension, developers can obtain much more detailed feedback on the
application’s use of Vulkan.
This extension defines a way for layers and the implementation to call back
to the application for events of interest to the application.
New Enum Constants
-
VK_EXT_DEBUG_REPORT_EXTENSION_NAME -
VK_EXT_DEBUG_REPORT_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT
-
-
Extending VkResult:
-
VK_ERROR_VALIDATION_FAILED_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT
-
If Version 1.1 is supported:
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT -
VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_EXT
-
Examples
VK_EXT_debug_report allows an application to register multiple callbacks
with the validation layers.
Some callbacks may log the information to a file, others may cause a debug
break point or other application defined behavior.
An application can register callbacks even when no validation layers are
enabled, but they will only be called for loader and, if implemented, driver
events.
To capture events that occur while creating or destroying an instance an
application can link a VkDebugReportCallbackCreateInfoEXT structure
to the pNext element of the VkInstanceCreateInfo structure given
to vkCreateInstance.
Example uses: Create three callback objects.
One will log errors and warnings to the debug console using Windows
OutputDebugString.
The second will cause the debugger to break at that callback when an error
happens and the third will log warnings to stdout.
VkResult res;
VkDebugReportCallbackEXT cb1, cb2, cb3;
VkDebugReportCallbackCreateInfoEXT callback1 = {
VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, // sType
NULL, // pNext
VK_DEBUG_REPORT_ERROR_BIT_EXT | // flags
VK_DEBUG_REPORT_WARNING_BIT_EXT,
myOutputDebugString, // pfnCallback
NULL // pUserData
};
res = vkCreateDebugReportCallbackEXT(instance, &callback1, &cb1);
if (res != VK_SUCCESS)
/* Do error handling for VK_ERROR_OUT_OF_MEMORY */
callback.flags = VK_DEBUG_REPORT_ERROR_BIT_EXT;
callback.pfnCallback = myDebugBreak;
callback.pUserData = NULL;
res = vkCreateDebugReportCallbackEXT(instance, &callback, &cb2);
if (res != VK_SUCCESS)
/* Do error handling for VK_ERROR_OUT_OF_MEMORY */
VkDebugReportCallbackCreateInfoEXT callback3 = {
VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, // sType
NULL, // pNext
VK_DEBUG_REPORT_WARNING_BIT_EXT, // flags
mystdOutLogger, // pfnCallback
NULL // pUserData
};
res = vkCreateDebugReportCallbackEXT(instance, &callback3, &cb3);
if (res != VK_SUCCESS)
/* Do error handling for VK_ERROR_OUT_OF_MEMORY */
...
/* remove callbacks when cleaning up */
vkDestroyDebugReportCallbackEXT(instance, cb1);
vkDestroyDebugReportCallbackEXT(instance, cb2);
vkDestroyDebugReportCallbackEXT(instance, cb3);
|
Note
In the initial release of the |
|
Note
In the initial release of the |
Issues
1) What is the hierarchy / seriousness of the message flags? E.g.
ERROR > WARN > PERF_WARN …
RESOLVED: There is no specific hierarchy. Each bit is independent and should be checked via bitwise AND. For example:
if (localFlags & VK_DEBUG_REPORT_ERROR_BIT_EXT) {
process error message
}
if (localFlags & VK_DEBUG_REPORT_DEBUG_BIT_EXT) {
process debug message
}
The validation layers do use them in a hierarchical way (ERROR >
WARN > PERF, WARN > DEBUG > INFO) and they (at
least at the time of this writing) only set one bit at a time.
But it is not a requirement of this extension.
It is possible that a layer may intercept and change, or augment the flags with extension values the application’s debug report handler may not be familiar with, so it is important to treat each flag independently.
2) Should there be a VU requiring
VkDebugReportCallbackCreateInfoEXT::flags to be non-zero?
RESOLVED: It may not be very useful, but we do not need VU statement
requiring the VkDebugReportCallbackCreateInfoEXT::msgFlags at
create-time to be non-zero.
One can imagine that apps may prefer it as it allows them to set the mask as
desired - including nothing - at runtime without having to check.
3) What is the difference between VK_DEBUG_REPORT_DEBUG_BIT_EXT and
VK_DEBUG_REPORT_INFORMATION_BIT_EXT?
RESOLVED: VK_DEBUG_REPORT_DEBUG_BIT_EXT specifies information that
could be useful debugging the Vulkan implementation itself.
4) How do you compare handles returned by the debug_report callback to the application’s handles?
RESOLVED: Due to the different nature of dispatchable and nondispatchable handles there is no generic way (that we know of) that works for common compilers with 32bit, 64bit, C and C++. We recommend applications use the same cast that the validation layers use:
+
reinterpret_cast<uint64_t &>(dispatchableHandle)
(uint64_t)(nondispatchableHandle)
+ This does require that the app treat dispatchable and nondispatchable handles differently.
Version History
-
Revision 1, 2015-05-20 (Courtney Goetzenleuchter)
-
Initial draft, based on LunarG KHR spec, other KHR specs
-
-
Revision 2, 2016-02-16 (Courtney Goetzenleuchter)
-
Update usage, documentation
-
-
Revision 3, 2016-06-14 (Courtney Goetzenleuchter)
-
Update VK_EXT_DEBUG_REPORT_SPEC_VERSION to indicate added support for vkCreateInstance and vkDestroyInstance
-
-
Revision 4, 2016-12-08 (Mark Lobodzinski)
-
Added Display_KHR, DisplayModeKHR extension objects
-
Added ObjectTable_NVX, IndirectCommandsLayout_NVX extension objects
-
Bumped spec revision
-
Retroactively added version history
-
-
Revision 5, 2017-01-31 (Baldur Karlsson)
-
Moved definition of VkDebugReportObjectTypeEXT from debug marker chapter
-
-
Revision 6, 2017-01-31 (Baldur Karlsson)
-
Added VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT
-
-
Revision 7, 2017-04-20 (Courtney Goeltzenleuchter)
-
Clarify wording and address questions from developers.
-
-
Revision 8, 2017-04-21 (Courtney Goeltzenleuchter)
-
Remove unused enum VkDebugReportErrorEXT
-
-
Revision 9, 2017-09-12 (Tobias Hector)
-
Added interactions with Vulkan 1.1
-
-
Revision 10, 2020-12-14 (Courtney Goetzenleuchter)
-
Add issue 4 discussing matching handles returned by the extension, based on suggestion in public issue 368.
-
VK_EXT_descriptor_indexing
- Name String
-
VK_EXT_descriptor_indexing - Extension Type
-
Device extension
- Registered Extension Number
-
162
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_maintenance3to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-10-02
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
This extension requires
SPV_EXT_descriptor_indexing -
This extension provides API support for
GL_EXT_nonuniform_qualifier
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Daniel Rakos, AMD
-
Slawomir Grajewski, Intel
-
Tobias Hector, Imagination Technologies
-
Description
This extension adds several small features which together enable
applications to create large descriptor sets containing substantially all of
their resources, and selecting amongst those resources with dynamic
(non-uniform) indexes in the shader.
There are feature enables and SPIR-V capabilities for non-uniform descriptor
indexing in the shader, and non-uniform indexing in the shader requires use
of a new NonUniformEXT decoration defined in the
SPV_EXT_descriptor_indexing SPIR-V extension.
There are descriptor set layout binding creation flags enabling several
features:
-
Descriptors can be updated after they are bound to a command buffer, such that the execution of the command buffer reflects the most recent update to the descriptors.
-
Descriptors that are not used by any pending command buffers can be updated, which enables writing new descriptors for frame N+1 while frame N is executing.
-
Relax the requirement that all descriptors in a binding that is “statically used” must be valid, such that descriptors that are not accessed by a submission need not be valid and can be updated while that submission is executing.
-
The final binding in a descriptor set layout can have a variable size (and unsized arrays of resources are allowed in the
GL_EXT_nonuniform_qualifierandSPV_EXT_descriptor_indexingextensions).
Note that it is valid for multiple descriptor arrays in a shader to use the same set and binding number, as long as they are all compatible with the descriptor type in the pipeline layout. This means a single array binding in the descriptor set can serve multiple texture dimensionalities, or an array of buffer descriptors can be used with multiple different block layouts.
There are new descriptor set layout and descriptor pool creation flags that
are required to opt in to the update-after-bind functionality, and there are
separate maxPerStage* and maxDescriptorSet* limits that apply to
these descriptor set layouts which may be much higher than the pre-existing
limits.
The old limits only count descriptors in non-updateAfterBind descriptor set
layouts, and the new limits count descriptors in all descriptor set layouts
in the pipeline layout.
New Structures
-
Extending VkDescriptorSetAllocateInfo:
-
Extending VkDescriptorSetLayoutCreateInfo:
-
Extending VkDescriptorSetLayoutSupport:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
New Enum Constants
-
VK_EXT_DESCRIPTOR_INDEXING_EXTENSION_NAME -
VK_EXT_DESCRIPTOR_INDEXING_SPEC_VERSION -
Extending VkDescriptorBindingFlagBits:
-
VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT -
VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT -
VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT -
VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT_EXT
-
-
Extending VkDescriptorPoolCreateFlagBits:
-
VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT
-
-
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT
-
-
Extending VkResult:
-
VK_ERROR_FRAGMENTATION_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_ALLOCATE_INFO_EXT -
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_LAYOUT_SUPPORT_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_PROPERTIES_EXT
-
Promotion to Vulkan 1.2
Functionality in this extension is included in core Vulkan 1.2, with the EXT
suffix omitted.
However, if Vulkan 1.2 is supported and this extension is not, the
descriptorIndexing capability is optional.
The original type, enum and command names are still available as aliases of
the core functionality.
Version History
-
Revision 1, 2017-07-26 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2017-10-02 (Jeff Bolz)
-
???
-
VK_EXT_extended_dynamic_state
- Name String
-
VK_EXT_extended_dynamic_state - Extension Type
-
Device extension
- Registered Extension Number
-
268
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-12-09
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Dan Ginsburg, Valve Corporation
-
Graeme Leese, Broadcom
-
Hans-Kristian Arntzen, Valve Corporation
-
Jan-Harald Fredriksen, Arm Limited
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Jesse Hall, Google
-
Philip Rebohle, Valve Corporation
-
Stuart Smith, Imagination Technologies
-
Tobias Hector, AMD
-
Description
This extension adds some more dynamic state to support applications that need to reduce the number of pipeline state objects they compile and bind.
New Enum Constants
-
VK_EXT_EXTENDED_DYNAMIC_STATE_EXTENSION_NAME -
VK_EXT_EXTENDED_DYNAMIC_STATE_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_CULL_MODE_EXT -
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT -
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT -
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT -
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT -
VK_DYNAMIC_STATE_FRONT_FACE_EXT -
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT -
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT -
VK_DYNAMIC_STATE_STENCIL_OP_EXT -
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT -
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT -
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_FEATURES_EXT
-
Promotion to Vulkan 1.3
This extension has been partially promoted. All dynamic state enumerants and entry points in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. The feature structure is not promoted. Extension interfaces that were promoted remain available as aliases of the core functionality.
VK_EXT_extended_dynamic_state2
- Name String
-
VK_EXT_extended_dynamic_state2 - Extension Type
-
Device extension
- Registered Extension Number
-
378
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Vikram Kushwaha vkushwaha-nv
-
Other Extension Metadata
- Last Modified Date
-
2021-04-12
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Piers Daniell, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension adds some more dynamic state to support applications that need to reduce the number of pipeline state objects they compile and bind.
New Enum Constants
-
VK_EXT_EXTENDED_DYNAMIC_STATE_2_EXTENSION_NAME -
VK_EXT_EXTENDED_DYNAMIC_STATE_2_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT -
VK_DYNAMIC_STATE_LOGIC_OP_EXT -
VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT -
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT -
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_2_FEATURES_EXT
-
Promotion to Vulkan 1.3
This extension has been partially promoted.
The dynamic state enumerants VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT,
VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT, and
VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT; and the corresponding
entry points in this extension are included in core Vulkan 1.3, with the EXT
suffix omitted.
The enumerants and entry points for dynamic logic operation and patch
control points are not promoted, nor is the feature structure.
Extension interfaces that were promoted remain available as aliases of the
core functionality.
VK_EXT_global_priority
- Name String
-
VK_EXT_global_priority - Extension Type
-
Device extension
- Registered Extension Number
-
175
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to
VK_KHR_global_priorityextension
-
- Contact
-
-
Andres Rodriguez lostgoat
-
Other Extension Metadata
- Last Modified Date
-
2017-10-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Andres Rodriguez, Valve
-
Pierre-Loup Griffais, Valve
-
Dan Ginsburg, Valve
-
Mitch Singer, AMD
-
Description
In Vulkan, users can specify device-scope queue priorities.
In some cases it may be useful to extend this concept to a system-wide
scope.
This extension provides a mechanism for callers to set their system-wide
priority.
The default queue priority is VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT.
The driver implementation will attempt to skew hardware resource allocation in favour of the higher-priority task. Therefore, higher-priority work may retain similar latency and throughput characteristics even if the system is congested with lower priority work.
The global priority level of a queue shall take precedence over the
per-process queue priority
(VkDeviceQueueCreateInfo::pQueuePriorities).
Abuse of this feature may result in starving the rest of the system from
hardware resources.
Therefore, the driver implementation may deny requests to acquire a priority
above the default priority (VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) if
the caller does not have sufficient privileges.
In this scenario VK_ERROR_NOT_PERMITTED_EXT is returned.
The driver implementation may fail the queue allocation request if resources
required to complete the operation have been exhausted (either by the same
process or a different process).
In this scenario VK_ERROR_INITIALIZATION_FAILED is returned.
New Enum Constants
-
VK_EXT_GLOBAL_PRIORITY_EXTENSION_NAME -
VK_EXT_GLOBAL_PRIORITY_SPEC_VERSION -
Extending VkResult:
-
VK_ERROR_NOT_PERMITTED_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_EXT
-
Version History
-
Revision 2, 2017-11-03 (Andres Rodriguez)
-
Fixed VkQueueGlobalPriorityEXT missing _EXT suffix
-
-
Revision 1, 2017-10-06 (Andres Rodriguez)
-
First version.
-
VK_EXT_global_priority_query
- Name String
-
VK_EXT_global_priority_query - Extension Type
-
Device extension
- Registered Extension Number
-
389
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_EXT_global_priorityto be enabled for any device-level functionality -
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to
VK_KHR_global_priorityextension
-
- Contact
-
-
Yiwei Zhang zhangyiwei
-
Other Extension Metadata
- Last Modified Date
-
2021-03-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Yiwei Zhang, Google
-
Description
This device extension allows applications to query the global queue priorities supported by a queue family. It allows implementations to report which global priority levels are treated differently by the implementation, instead of silently mapping multiple requested global priority levels to the same internal priority, or using device creation failure to signal that a requested priority is not supported. It is intended primarily for use by system integration along with certain platform-specific priority enforcement rules.
New Enum Constants
-
VK_EXT_GLOBAL_PRIORITY_QUERY_EXTENSION_NAME -
VK_EXT_GLOBAL_PRIORITY_QUERY_SPEC_VERSION -
VK_MAX_GLOBAL_PRIORITY_SIZE_EXT -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GLOBAL_PRIORITY_QUERY_FEATURES_EXT -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES_EXT
-
Issues
1) Can we additionally query whether a caller is permitted to acquire a specific global queue priority in this extension?
RESOLVED: No. Whether a caller has enough privilege goes with the OS, and the Vulkan driver cannot really guarantee that the privilege will not change in between this query and the actual queue creation call.
2) If more than 1 queue using global priority is requested, is there a good way to know which queue is failing the device creation?
RESOLVED: No. There is not a good way at this moment, and it is also not quite actionable for the applications to know that because the information may not be accurate. Queue creation can fail because of runtime constraints like insufficient privilege or lack of resource, and the failure is not necessarily tied to that particular queue configuration requested.
VK_EXT_host_query_reset
- Name String
-
VK_EXT_host_query_reset - Extension Type
-
Device extension
- Registered Extension Number
-
262
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Bas Nieuwenhuizen BNieuwenhuizen
-
Other Extension Metadata
- Last Modified Date
-
2019-03-06
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Bas Nieuwenhuizen, Google
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_EXT_HOST_QUERY_RESET_EXTENSION_NAME -
VK_EXT_HOST_QUERY_RESET_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES_EXT
-
VK_EXT_image_robustness
- Name String
-
VK_EXT_image_robustness - Extension Type
-
Device extension
- Registered Extension Number
-
336
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Graeme Leese gnl21
-
Other Extension Metadata
- Last Modified Date
-
2020-04-27
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, ARM
-
Jeff Bolz, NVIDIA
-
Spencer Fricke, Samsung
-
Courtney Goeltzenleuchter, Google
-
Slawomir Cygan, Intel
-
Description
This extension adds stricter requirements for how out of bounds reads from images are handled. Rather than returning undefined values, most out of bounds reads return R, G, and B values of zero and alpha values of either zero or one. Components not present in the image format may be set to zero or to values based on the format as described in Conversion to RGBA.
New Enum Constants
-
VK_EXT_IMAGE_ROBUSTNESS_EXTENSION_NAME -
VK_EXT_IMAGE_ROBUSTNESS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES_EXT
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
Issues
-
How does this extension differ from VK_EXT_robustness2?
The guarantees provided by this extension are a subset of those provided by the robustImageAccess2 feature of VK_EXT_robustness2. Where this extension allows return values of (0, 0, 0, 0) or (0, 0, 0, 1), robustImageAccess2 requires that a particular value dependent on the image format be returned. This extension provides no guarantees about the values returned for an access to an invalid Lod.
VK_EXT_inline_uniform_block
- Name String
-
VK_EXT_inline_uniform_block - Extension Type
-
Device extension
- Registered Extension Number
-
139
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality -
Requires
VK_KHR_maintenance1to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Daniel Rakos aqnuep
-
Other Extension Metadata
- Last Modified Date
-
2018-08-01
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Daniel Rakos, AMD
-
Jeff Bolz, NVIDIA
-
Slawomir Grajewski, Intel
-
Neil Henning, Codeplay
-
Description
This extension introduces the ability to back uniform blocks directly with descriptor sets by storing inline uniform data within descriptor pool storage. Compared to push constants this new construct allows uniform data to be reused across multiple disjoint sets of drawing or dispatching commands and may enable uniform data to be accessed with fewer indirections compared to uniforms backed by buffer memory.
New Structures
-
Extending VkDescriptorPoolCreateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkWriteDescriptorSet:
New Enum Constants
-
VK_EXT_INLINE_UNIFORM_BLOCK_EXTENSION_NAME -
VK_EXT_INLINE_UNIFORM_BLOCK_SPEC_VERSION -
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK_EXT
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
Vulkan 1.3 adds additional functionality
related to this extension in the form of the
maxInlineUniformTotalSize limit.
Issues
1) Do we need a new storage class for inline uniform blocks vs uniform blocks?
RESOLVED: No.
The Uniform storage class is used to allow the same syntax used for
both uniform buffers and inline uniform blocks.
2) Is the descriptor array index and array size expressed in terms of bytes or dwords for inline uniform block descriptors?
RESOLVED: In bytes, but both must be a multiple of 4, similar to how push
constant ranges are specified.
The descriptorCount of VkDescriptorSetLayoutBinding thus
provides the total number of bytes a particular binding with an inline
uniform block descriptor type can hold, while the srcArrayElement,
dstArrayElement, and descriptorCount members of
VkWriteDescriptorSet, VkCopyDescriptorSet, and
VkDescriptorUpdateTemplateEntry (where applicable) specify the byte
offset and number of bytes to write/copy to the binding’s backing store.
Additionally, the stride member of
VkDescriptorUpdateTemplateEntry is ignored for inline uniform blocks
and a default value of one is used, meaning that the data to update inline
uniform block bindings with must be contiguous in memory.
3) What layout rules apply for uniform blocks corresponding to inline constants?
RESOLVED: They use the same layout rules as uniform buffers.
4) Do we need to add non-uniform indexing features/properties as introduced
by VK_EXT_descriptor_indexing for inline uniform blocks?
RESOLVED: No, because inline uniform blocks are not allowed to be “arrayed”. A single binding with an inline uniform block descriptor type corresponds to a single uniform block instance and the array indices inside that binding refer to individual offsets within the uniform block (see issue #2). However, this extension does introduce new features/properties about the level of support for update-after-bind inline uniform blocks.
5) Is the descriptorBindingVariableDescriptorCount feature introduced
by VK_EXT_descriptor_indexing supported for inline uniform blocks?
RESOLVED: Yes, as long as other inline uniform block specific limits are respected.
6) Do the robustness guarantees of robustBufferAccess apply to inline
uniform block accesses?
RESOLVED: No, similarly to push constants, as they are not backed by buffer memory like uniform buffers.
VK_EXT_pipeline_creation_cache_control
- Name String
-
VK_EXT_pipeline_creation_cache_control - Extension Type
-
Device extension
- Registered Extension Number
-
298
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Gregory Grebe grgrebe_amd
-
Other Extension Metadata
- Last Modified Date
-
2020-03-23
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Gregory Grebe, AMD
-
Tobias Hector, AMD
-
Matthaeus Chajdas, AMD
-
Mitch Singer, AMD
-
Spencer Fricke, Samsung Electronics
-
Stuart Smith, Imagination Technologies
-
Jeff Bolz, NVIDIA Corporation
-
Daniel Koch, NVIDIA Corporation
-
Dan Ginsburg, Valve Corporation
-
Jeff Leger, QUALCOMM
-
Michal Pietrasiuk, Intel
-
Jan-Harald Fredriksen, Arm Limited
-
Description
This extension adds flags to Vk*PipelineCreateInfo and
VkPipelineCacheCreateInfo structures with the aim of improving the
predictability of pipeline creation cost.
The goal is to provide information about potentially expensive hazards
within the client driver during pipeline creation to the application before
carrying them out rather than after.
Background
Pipeline creation is a costly operation, and the explicit nature of the Vulkan design means that cost is not hidden from the developer. Applications are also expected to schedule, prioritize, and load balance all calls for pipeline creation. It is strongly advised that applications create pipelines sufficiently ahead of their usage. Failure to do so will result in an unresponsive application, intermittent stuttering, or other poor user experiences. Proper usage of pipeline caches and/or derivative pipelines help mitigate this but is not assured to eliminate disruption in all cases. In the event that an ahead-of-time creation is not possible, considerations should be taken to ensure that the current execution context is suitable for the workload of pipeline creation including possible shader compilation.
Applications making API calls to create a pipeline must be prepared for any of the following to occur:
-
OS/kernel calls to be made by the ICD
-
Internal memory allocation not tracked by the
pAllocatorpassed tovkCreate*Pipelines -
Internal thread synchronization or yielding of the current thread’s core
-
Extremely long (multi-millisecond+), blocking, compilation times
-
Arbitrary call stacks depths and stack memory usage
The job or task based game engines that are being developed to take advantage of explicit graphics APIs like Vulkan may behave exceptionally poorly if any of the above scenarios occur. However, most game engines are already built to “stream” in assets dynamically as the user plays the game. By adding control by way of VkPipelineCreateFlags, we can require an ICD to report back a failure in critical execution paths rather than forcing an unexpected wait.
Applications can prevent unexpected compilation by setting
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT on
Vk*PipelineCreateInfo::flags.
When set, an ICD must not attempt pipeline or shader compilation to create
the pipeline object.
The ICD will return the result VK_PIPELINE_COMPILE_REQUIRED_EXT.
An ICD may still return a valid VkPipeline object by either re-using
existing pre-compiled objects such as those from a pipeline cache, or
derivative pipelines.
By default vkCreate*Pipelines calls must attempt to create all
pipelines before returning.
Setting VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT on
Vk*PipelineCreateInfo::flags can be used as an escape hatch for
batched pipeline creates.
Hidden locks also add to the unpredictability of the cost of pipeline
creation.
The most common case of locks inside the vkCreate*Pipelines is
internal synchronization of the VkPipelineCache object.
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT can be set
when calling vkCreatePipelineCache to state the cache is
externally synchronized.
The hope is that armed with this information application and engine developers can leverage existing asset streaming systems to recover from "just-in-time" pipeline creation stalls.
New Enum Constants
-
VK_EXT_PIPELINE_CREATION_CACHE_CONTROL_EXTENSION_NAME -
VK_EXT_PIPELINE_CREATION_CACHE_CONTROL_SPEC_VERSION -
Extending VkPipelineCacheCreateFlagBits:
-
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT -
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT
-
-
Extending VkResult:
-
VK_ERROR_PIPELINE_COMPILE_REQUIRED_EXT -
VK_PIPELINE_COMPILE_REQUIRED_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES_EXT
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
Version History
-
Revision 1, 2019-11-01 (Gregory Grebe)
-
Initial revision
-
-
Revision 2, 2020-02-24 (Gregory Grebe)
-
Initial public revision
-
-
Revision 3, 2020-03-23 (Tobias Hector)
-
Changed
VK_PIPELINE_COMPILE_REQUIRED_EXTto a success code, adding an alias for the originalVK_ERROR_PIPELINE_COMPILE_REQUIRED_EXT. Also updated the xml to include these codes as return values.
-
VK_EXT_pipeline_creation_feedback
- Name String
-
VK_EXT_pipeline_creation_feedback - Extension Type
-
Device extension
- Registered Extension Number
-
193
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Special Use
- Contact
-
-
Jean-Francois Roy jfroy
-
Other Extension Metadata
- Last Modified Date
-
2019-03-12
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Jean-Francois Roy, Google
-
Hai Nguyen, Google
-
Andrew Ellem, Google
-
Bob Fraser, Google
-
Sujeevan Rajayogam, Google
-
Jan-Harald Fredriksen, ARM
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Neil Henning, AMD
-
Description
This extension adds a mechanism to provide feedback to an application about pipeline creation, with the specific goal of allowing a feedback loop between build systems and in-the-field application executions to ensure effective pipeline caches are shipped to customers.
New Enum Constants
-
VK_EXT_PIPELINE_CREATION_FEEDBACK_EXTENSION_NAME -
VK_EXT_PIPELINE_CREATION_FEEDBACK_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO_EXT
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
VK_EXT_private_data
- Name String
-
VK_EXT_private_data - Extension Type
-
Device extension
- Registered Extension Number
-
296
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Matthew Rusch mattruschnv
-
Other Extension Metadata
- Last Modified Date
-
2020-03-25
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthew Rusch, NVIDIA
-
Nuno Subtil, NVIDIA
-
Piers Daniell, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension is a device extension which enables attaching arbitrary payloads to Vulkan objects. It introduces the idea of private data slots as a means of storing a 64-bit unsigned integer of application defined data. Private data slots can be created or destroyed any time an associated device is available. Private data slots can be reserved at device creation time, and limiting use to the amount reserved will allow the extension to exhibit better performance characteristics.
New Enum Constants
-
VK_EXT_PRIVATE_DATA_EXTENSION_NAME -
VK_EXT_PRIVATE_DATA_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_PRIVATE_DATA_SLOT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES_EXT -
VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO_EXT
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
Issues
(1) If I have to create a VkPrivateDataSlot to store and retrieve data on an object, how does this extension help me? Will I not need to store the VkPrivateDataSlot mapping with each object, and if I am doing that, I might as well just store the original data!
RESOLVED: The VkPrivateDataSlot can be thought of as an opaque index into storage that is reserved in each object. That is, you can use the same VkPrivateDataSlot with each object for a specific piece of information. For example, if a layer wishes to track per-object information, the layer only needs to allocate one VkPrivateDataSlot per device and it can use that private data slot for all of the device’s child objects. This allows multiple layers to store private data without conflicting with each other’s and/or the application’s private data.
(2) What if I need to store more than 64-bits of information per object?
RESOLVED: The data that you store per object could be a pointer to another object or structure of your own allocation.
VK_EXT_sampler_filter_minmax
- Name String
-
VK_EXT_sampler_filter_minmax - Extension Type
-
Device extension
- Registered Extension Number
-
131
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-05-19
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
Description
In unextended Vulkan, minification and magnification filters such as LINEAR allow sampled image lookups to return a filtered texel value produced by computing a weighted average of a collection of texels in the neighborhood of the texture coordinate provided.
This extension provides a new sampler parameter which allows applications to produce a filtered texel value by computing a component-wise minimum (MIN) or maximum (MAX) of the texels that would normally be averaged. The reduction mode is orthogonal to the minification and magnification filter parameters. The filter parameters are used to identify the set of texels used to produce a final filtered value; the reduction mode identifies how these texels are combined.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_EXT_SAMPLER_FILTER_MINMAX_EXTENSION_NAME -
VK_EXT_SAMPLER_FILTER_MINMAX_SPEC_VERSION -
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT
-
-
Extending VkSamplerReductionMode:
-
VK_SAMPLER_REDUCTION_MODE_MAX_EXT -
VK_SAMPLER_REDUCTION_MODE_MIN_EXT -
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO_EXT
-
Version History
-
Revision 2, 2017-05-19 (Piers Daniell)
-
Renamed to EXT
-
-
Revision 1, 2017-03-25 (Jeff Bolz)
-
Internal revisions
-
VK_EXT_scalar_block_layout
- Name String
-
VK_EXT_scalar_block_layout - Extension Type
-
Device extension
- Registered Extension Number
-
222
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2018-11-14
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- Contributors
-
-
Jeff Bolz
-
Jan-Harald Fredriksen
-
Graeme Leese
-
Jason Ekstrand
-
John Kessenich
-
Description
This extension enables C-like structure layout for SPIR-V blocks. It modifies the alignment rules for uniform buffers, storage buffers and push constants, allowing non-scalar types to be aligned solely based on the size of their components, without additional requirements.
Promotion to Vulkan 1.2
Functionality in this extension is included in core Vulkan 1.2, with the EXT
suffix omitted.
However, if Vulkan 1.2 is supported and this extension is not, the
scalarBlockLayout capability is optional.
The original type, enum and command names are still available as aliases of
the core functionality.
New Enum Constants
-
VK_EXT_SCALAR_BLOCK_LAYOUT_EXTENSION_NAME -
VK_EXT_SCALAR_BLOCK_LAYOUT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES_EXT
-
VK_EXT_separate_stencil_usage
- Name String
-
VK_EXT_separate_stencil_usage - Extension Type
-
Device extension
- Registered Extension Number
-
247
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2018-11-08
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Daniel Rakos, AMD
-
Jordan Logan, AMD
-
Description
This extension allows specifying separate usage flags for the stencil aspect of images with a depth-stencil format at image creation time.
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
New Enum Constants
-
VK_EXT_SEPARATE_STENCIL_USAGE_EXTENSION_NAME -
VK_EXT_SEPARATE_STENCIL_USAGE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO_EXT
-
VK_EXT_shader_demote_to_helper_invocation
- Name String
-
VK_EXT_shader_demote_to_helper_invocation - Extension Type
-
Device extension
- Registered Extension Number
-
277
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-01
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_demote_to_helper_invocation -
This extension provides API support for
GL_EXT_demote_to_helper_invocation
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension adds Vulkan support for the
SPV_EXT_demote_to_helper_invocation
SPIR-V extension.
That SPIR-V extension provides a new instruction
OpDemoteToHelperInvocationEXT allowing shaders to “demote” a fragment
shader invocation to behave like a helper invocation for its duration.
The demoted invocation will have no further side effects and will not output
to the framebuffer, but remains active and can participate in computing
derivatives and in group operations.
This is a better match for the “discard” instruction in HLSL.
New Enum Constants
-
VK_EXT_SHADER_DEMOTE_TO_HELPER_INVOCATION_EXTENSION_NAME -
VK_EXT_SHADER_DEMOTE_TO_HELPER_INVOCATION_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES_EXT
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
VK_EXT_shader_subgroup_ballot
- Name String
-
VK_EXT_shader_subgroup_ballot - Extension Type
-
Device extension
- Registered Extension Number
-
65
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Deprecated by Vulkan 1.2
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2016-11-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_shader_ballot -
This extension provides API support for
GL_ARB_shader_ballot
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Neil Henning, Codeplay
-
Daniel Koch, NVIDIA Corporation
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_shader_ballot
This extension provides the ability for a group of invocations, which execute in parallel, to do limited forms of cross-invocation communication via a group broadcast of a invocation value, or broadcast of a bitarray representing a predicate value from each invocation in the group.
This extension provides access to a number of additional built-in shader variables in Vulkan:
-
SubgroupEqMaskKHR, containing the subgroup mask of the current subgroup invocation, -
SubgroupGeMaskKHR, containing the subgroup mask of the invocations greater than or equal to the current invocation, -
SubgroupGtMaskKHR, containing the subgroup mask of the invocations greater than the current invocation, -
SubgroupLeMaskKHR, containing the subgroup mask of the invocations less than or equal to the current invocation, -
SubgroupLtMaskKHR, containing the subgroup mask of the invocations less than the current invocation, -
SubgroupLocalInvocationId, containing the index of an invocation within a subgroup, and -
SubgroupSize, containing the maximum number of invocations in a subgroup.
Additionally, this extension provides access to the new SPIR-V instructions:
-
OpSubgroupBallotKHR, -
OpSubgroupFirstInvocationKHR, and -
OpSubgroupReadInvocationKHR,
When using GLSL source-based shader languages, the following variables and shader functions from GL_ARB_shader_ballot can map to these SPIR-V built-in decorations and instructions:
-
in uint64_t gl_SubGroupEqMaskARB;→SubgroupEqMaskKHR, -
in uint64_t gl_SubGroupGeMaskARB;→SubgroupGeMaskKHR, -
in uint64_t gl_SubGroupGtMaskARB;→SubgroupGtMaskKHR, -
in uint64_t gl_SubGroupLeMaskARB;→SubgroupLeMaskKHR, -
in uint64_t gl_SubGroupLtMaskARB;→SubgroupLtMaskKHR, -
in uint gl_SubGroupInvocationARB;→SubgroupLocalInvocationId, -
uniform uint gl_SubGroupSizeARB;→SubgroupSize, -
ballotARB() →OpSubgroupBallotKHR, -
readFirstInvocationARB() →OpSubgroupFirstInvocationKHR, and -
readInvocationARB() →OpSubgroupReadInvocationKHR.
Deprecated by Vulkan 1.2
Most of the functionality in this extension is superseded by the core Vulkan
1.1 subgroup operations.
However, Vulkan 1.1 required the OpGroupNonUniformBroadcast “Id” to
be constant.
This restriction was removed in Vulkan 1.2 with the addition of the
subgroupBroadcastDynamicId
feature.
New Enum Constants
-
VK_EXT_SHADER_SUBGROUP_BALLOT_EXTENSION_NAME -
VK_EXT_SHADER_SUBGROUP_BALLOT_SPEC_VERSION
VK_EXT_shader_subgroup_vote
- Name String
-
VK_EXT_shader_subgroup_vote - Extension Type
-
Device extension
- Registered Extension Number
-
66
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Deprecated by Vulkan 1.1
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2016-11-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_subgroup_vote -
This extension provides API support for
GL_ARB_shader_group_vote
-
- Contributors
-
-
Neil Henning, Codeplay
-
Daniel Koch, NVIDIA Corporation
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_subgroup_vote
This extension provides new SPIR-V instructions:
-
OpSubgroupAllKHR, -
OpSubgroupAnyKHR, and -
OpSubgroupAllEqualKHR.
to compute the composite of a set of boolean conditions across a group of shader invocations that are running concurrently (a subgroup). These composite results may be used to execute shaders more efficiently on a VkPhysicalDevice.
When using GLSL source-based shader languages, the following shader functions from GL_ARB_shader_group_vote can map to these SPIR-V instructions:
-
anyInvocationARB() →OpSubgroupAnyKHR, -
allInvocationsARB() →OpSubgroupAllKHR, and -
allInvocationsEqualARB() →OpSubgroupAllEqualKHR.
The subgroup across which the boolean conditions are evaluated is implementation-dependent, and this extension provides no guarantee over how individual shader invocations are assigned to subgroups. In particular, a subgroup has no necessary relationship with the compute shader local workgroup — any pair of shader invocations in a compute local workgroup may execute in different subgroups as used by these instructions.
Compute shaders operate on an explicitly specified group of threads (a local workgroup), but many implementations will also group non-compute shader invocations and execute them concurrently. When executing code like
if (condition) {
result = do_fast_path();
} else {
result = do_general_path();
}
where condition diverges between invocations, an implementation might
first execute do_fast_path() for the invocations where condition
is true and leave the other invocations dormant.
Once do_fast_path() returns, it might call do_general_path() for
invocations where condition is false and leave the other
invocations dormant.
In this case, the shader executes both the fast and the general path and
might be better off just using the general path for all invocations.
This extension provides the ability to avoid divergent execution by evaluating a condition across an entire subgroup using code like:
if (allInvocationsARB(condition)) {
result = do_fast_path();
} else {
result = do_general_path();
}
The built-in function allInvocationsARB() will return the same value
for all invocations in the group, so the group will either execute
do_fast_path() or do_general_path(), but never both.
For example, shader code might want to evaluate a complex function
iteratively by starting with an approximation of the result and then
refining the approximation.
Some input values may require a small number of iterations to generate an
accurate result (do_fast_path) while others require a larger number
(do_general_path).
In another example, shader code might want to evaluate a complex function
(do_general_path) that can be greatly simplified when assuming a
specific value for one of its inputs (do_fast_path).
Deprecated by Vulkan 1.1
All functionality in this extension is superseded by the core Vulkan 1.1 subgroup operations.
New Enum Constants
-
VK_EXT_SHADER_SUBGROUP_VOTE_EXTENSION_NAME -
VK_EXT_SHADER_SUBGROUP_VOTE_SPEC_VERSION
VK_EXT_shader_viewport_index_layer
- Name String
-
VK_EXT_shader_viewport_index_layer - Extension Type
-
Device extension
- Registered Extension Number
-
163
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-08-08
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.2 Core
-
This extension requires
SPV_EXT_shader_viewport_index_layer -
This extension provides API support for
GL_ARB_shader_viewport_layer_array,GL_AMD_vertex_shader_layer,GL_AMD_vertex_shader_viewport_index, andGL_NV_viewport_array2 -
This extension requires the
multiViewportfeature. -
This extension interacts with the
tessellationShaderfeature.
-
- Contributors
-
-
Piers Daniell, NVIDIA
-
Jeff Bolz, NVIDIA
-
Jan-Harald Fredriksen, ARM
-
Daniel Rakos, AMD
-
Slawomir Grajeswki, Intel
-
Description
This extension adds support for the ShaderViewportIndexLayerEXT
capability from the SPV_EXT_shader_viewport_index_layer extension in
Vulkan.
This extension allows variables decorated with the Layer and
ViewportIndex built-ins to be exported from vertex or tessellation
shaders, using the ShaderViewportIndexLayerEXT capability.
When using GLSL source-based shading languages, the gl_ViewportIndex
and gl_Layer built-in variables map to the SPIR-V ViewportIndex
and Layer built-in decorations, respectively.
Behaviour of these variables is extended as described in the
GL_ARB_shader_viewport_layer_array (or the precursor
GL_AMD_vertex_shader_layer, GL_AMD_vertex_shader_viewport_index, and
GL_NV_viewport_array2 extensions).
|
Note
The |
Promotion to Vulkan 1.2
All functionality in this extension is included in core Vulkan 1.2.
The single ShaderViewportIndexLayerEXT capability from the
SPV_EXT_shader_viewport_index_layer extension is replaced by the
ShaderViewportIndex and ShaderLayer capabilities from SPIR-V 1.5 which are enabled by the
shaderOutputViewportIndex and
shaderOutputLayer features,
respectively.
Additionally, if Vulkan 1.2 is supported but this extension is not, these
capabilities are optional.
Enabling both features is equivalent to enabling the
VK_EXT_shader_viewport_index_layer extension.
New Enum Constants
-
VK_EXT_SHADER_VIEWPORT_INDEX_LAYER_EXTENSION_NAME -
VK_EXT_SHADER_VIEWPORT_INDEX_LAYER_SPEC_VERSION
New or Modified Built-In Variables
-
(modified)
Layer -
(modified)
ViewportIndex
VK_EXT_subgroup_size_control
- Name String
-
VK_EXT_subgroup_size_control - Extension Type
-
Device extension
- Registered Extension Number
-
226
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.1
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Neil Henning sheredom
-
Other Extension Metadata
- Last Modified Date
-
2019-03-05
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jason Ekstrand, Intel
-
Sławek Grajewski, Intel
-
Jesse Hall, Google
-
Neil Henning, AMD
-
Daniel Koch, NVIDIA
-
Jeff Leger, Qualcomm
-
Graeme Leese, Broadcom
-
Allan MacKinnon, Google
-
Mariusz Merecki, Intel
-
Graham Wihlidal, Electronic Arts
-
Description
This extension enables an implementation to control the subgroup size by allowing a varying subgroup size and also specifying a required subgroup size.
It extends the subgroup support in Vulkan 1.1 to allow an implementation to expose a varying subgroup size. Previously Vulkan exposed a single subgroup size per physical device, with the expectation that implementations will behave as if all subgroups have the same size. Some implementations may dispatch shaders with a varying subgroup size for different subgroups. As a result they could implicitly split a large subgroup into smaller subgroups or represent a small subgroup as a larger subgroup, some of whose invocations were inactive on launch.
To aid developers in understanding the performance characteristics of their
programs, this extension exposes a minimum and maximum subgroup size that a
physical device supports and a pipeline create flag to enable that pipeline
to vary its subgroup size.
If enabled, any SubgroupSize decorated variables in the SPIR-V shader
modules provided to pipeline creation may vary between the
minimum and maximum
subgroup sizes.
An implementation is also optionally allowed to support specifying a
required subgroup size for a given pipeline stage.
Implementations advertise which stages
support a required subgroup size, and any pipeline of a supported stage
can be passed a VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT
structure to set the subgroup size for that shader stage of the pipeline.
For compute shaders, this requires the developer to query the
maxComputeWorkgroupSubgroups
and ensure that:
Developers can also specify a new pipeline shader stage create flag that requires the implementation to have fully populated subgroups within local workgroups. This requires the workgroup size in the X dimension to be a multiple of the subgroup size.
New Enum Constants
-
VK_EXT_SUBGROUP_SIZE_CONTROL_EXTENSION_NAME -
VK_EXT_SUBGROUP_SIZE_CONTROL_SPEC_VERSION -
Extending VkPipelineShaderStageCreateFlagBits:
-
VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT -
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
Version History
-
Revision 1, 2019-03-05 (Neil Henning)
-
Initial draft
-
-
Revision 2, 2019-07-26 (Jason Ekstrand)
-
Add the missing VkPhysicalDeviceSubgroupSizeControlFeaturesEXT for querying subgroup size control features.
-
VK_EXT_texel_buffer_alignment
- Name String
-
VK_EXT_texel_buffer_alignment - Extension Type
-
Device extension
- Registered Extension Number
-
282
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-06
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension adds more expressive alignment requirements for uniform and
storage texel buffers.
Some implementations have single texel alignment requirements that cannot be
expressed via
VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment.
New Enum Constants
-
VK_EXT_TEXEL_BUFFER_ALIGNMENT_EXTENSION_NAME -
VK_EXT_TEXEL_BUFFER_ALIGNMENT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES_EXT
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. However, only the properties structure is promoted. The feature structure is not promoted. The original type name is still available as an alias of the core functionality.
VK_EXT_texture_compression_astc_hdr
- Name String
-
VK_EXT_texture_compression_astc_hdr - Extension Type
-
Device extension
- Registered Extension Number
-
67
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2019-05-28
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known issues.
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Description
This extension adds support for textures compressed using the Adaptive Scalable Texture Compression (ASTC) High Dynamic Range (HDR) profile.
When this extension is enabled, the HDR profile is supported for all ASTC formats listed in ASTC Compressed Image Formats.
New Enum Constants
-
VK_EXT_TEXTURE_COMPRESSION_ASTC_HDR_EXTENSION_NAME -
VK_EXT_TEXTURE_COMPRESSION_ASTC_HDR_SPEC_VERSION -
Extending VkFormat:
-
VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK_EXT -
VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES_EXT
-
Promotion to Vulkan 1.3
This extension has been partially promoted. Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. However, the feature is made optional in Vulkan 1.3. The original type, enum and command names are still available as aliases of the core functionality.
Issues
1) Should we add a feature or limit for this functionality?
Yes. It is consistent with the ASTC LDR support to add a feature like textureCompressionASTC_HDR.
The feature is strictly speaking redundant as long as this is just an extension; it would be sufficient to just enable the extension. But adding the feature is more forward-looking if wanted to make this an optional core feature in the future.
2) Should we introduce new format enums for HDR?
Yes.
Vulkan 1.0 describes the ASTC format enums as UNORM, e.g.
VK_FORMAT_ASTC_4x4_UNORM_BLOCK, so it is confusing to make these
contain HDR data.
Note that the OpenGL (ES) extensions did not make this distinction because a
single ASTC HDR texture may contain both unorm and float blocks.
Implementations may not be able to distinguish between LDR and HDR ASTC
textures internally and just treat them as the same format, i.e. if this
extension is supported then sampling from a
VK_FORMAT_ASTC_4x4_UNORM_BLOCK image format may return HDR results.
Applications can get predictable results by using the appropriate image
format.
VK_EXT_tooling_info
- Name String
-
VK_EXT_tooling_info - Extension Type
-
Device extension
- Registered Extension Number
-
246
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2018-11-05
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- Contributors
-
-
Rolando Caloca
-
Matthaeus Chajdas
-
Baldur Karlsson
-
Daniel Rakos
-
Description
When an error occurs during application development, a common question is "What tools are actually running right now?" This extension adds the ability to query that information directly from the Vulkan implementation.
Outdated versions of one tool might not play nicely with another, or perhaps a tool is not actually running when it should have been. Trying to figure that out can cause headaches as it is necessary to consult each known tool to figure out what is going on — in some cases the tool might not even be known.
Typically, the expectation is that developers will simply print out this information for visual inspection when an issue occurs, however a small amount of semantic information about what the tool is doing is provided to help identify it programmatically. For example, if the advertised limits or features of an implementation are unexpected, is there a tool active which modifies these limits? Or if an application is providing debug markers, but the implementation is not actually doing anything with that information, this can quickly point that out.
New Enum Constants
-
VK_EXT_TOOLING_INFO_EXTENSION_NAME -
VK_EXT_TOOLING_INFO_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES_EXT
-
If VK_EXT_debug_marker is supported:
-
Extending VkToolPurposeFlagBits:
-
VK_TOOL_PURPOSE_DEBUG_MARKERS_BIT_EXT
-
If VK_EXT_debug_report is supported:
-
Extending VkToolPurposeFlagBits:
-
VK_TOOL_PURPOSE_DEBUG_REPORTING_BIT_EXT
-
If VK_EXT_debug_utils is supported:
-
Extending VkToolPurposeFlagBits:
-
VK_TOOL_PURPOSE_DEBUG_MARKERS_BIT_EXT -
VK_TOOL_PURPOSE_DEBUG_REPORTING_BIT_EXT
-
Promotion to Vulkan 1.3
Functionality in this extension is included in core Vulkan 1.3, with the EXT suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
Examples
uint32_t num_tools;
VkPhysicalDeviceToolPropertiesEXT *pToolProperties;
vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, NULL);
pToolProperties = (VkPhysicalDeviceToolPropertiesEXT*)malloc(sizeof(VkPhysicalDeviceToolPropertiesEXT) * num_tools);
vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, pToolProperties);
for (int i = 0; i < num_tools; ++i) {
printf("%s:\n", pToolProperties[i].name);
printf("Version:\n");
printf("%s:\n", pToolProperties[i].version);
printf("Description:\n");
printf("\t%s\n", pToolProperties[i].description);
printf("Purposes:\n");
printf("\t%s\n", VkToolPurposeFlagBitsEXT_to_string(pToolProperties[i].purposes));
if (strnlen_s(pToolProperties[i].layer,VK_MAX_EXTENSION_NAME_SIZE) > 0) {
printf("Corresponding Layer:\n");
printf("\t%s\n", pToolProperties[i].layer);
}
}
Issues
1) Why is this information separate from the layer mechanism?
Some tooling may be built into a driver, or be part of the Vulkan loader etc. Tying this information directly to layers would have been awkward at best.
VK_EXT_validation_flags
- Name String
-
VK_EXT_validation_flags - Extension Type
-
Instance extension
- Registered Extension Number
-
62
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Deprecated by
VK_EXT_validation_featuresextension
-
- Special Use
- Contact
-
-
Tobin Ehlis tobine
-
Other Extension Metadata
- Last Modified Date
-
2019-08-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Tobin Ehlis, Google
-
Courtney Goeltzenleuchter, Google
-
Description
This extension provides the VkValidationFlagsEXT struct that can be
included in the pNext chain of the VkInstanceCreateInfo
structure passed as the pCreateInfo parameter of
vkCreateInstance.
The structure contains an array of VkValidationCheckEXT values that
will be disabled by the validation layers.
Deprecation by VK_EXT_validation_features
Functionality in this extension is subsumed into the
VK_EXT_validation_features extension.
New Structures
-
Extending VkInstanceCreateInfo:
New Enum Constants
-
VK_EXT_VALIDATION_FLAGS_EXTENSION_NAME -
VK_EXT_VALIDATION_FLAGS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VALIDATION_FLAGS_EXT
-
Version History
-
Revision 2, 2019-08-19 (Mark Lobodzinski)
-
Marked as deprecated
-
-
Revision 1, 2016-08-26 (Courtney Goeltzenleuchter)
-
Initial draft
-
VK_EXT_ycbcr_2plane_444_formats
- Name String
-
VK_EXT_ycbcr_2plane_444_formats - Extension Type
-
Device extension
- Registered Extension Number
-
331
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_sampler_ycbcr_conversionto be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Tony Zlatinski tzlatinski
-
Other Extension Metadata
- Last Modified Date
-
2020-07-28
- Interactions and External Dependencies
-
-
Promoted to Vulkan 1.3 Core
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Piers Daniell, NVIDIA
-
Ping Liu, Intel
-
Description
This extension adds some Y′CBCR formats that are in common use for video
encode and decode, but were not part of the
VK_KHR_sampler_ycbcr_conversion extension.
New Enum Constants
-
VK_EXT_YCBCR_2PLANE_444_FORMATS_EXTENSION_NAME -
VK_EXT_YCBCR_2PLANE_444_FORMATS_SPEC_VERSION -
Extending VkFormat:
-
VK_FORMAT_G10X6_B10X6R10X6_2PLANE_444_UNORM_3PACK16_EXT -
VK_FORMAT_G12X4_B12X4R12X4_2PLANE_444_UNORM_3PACK16_EXT -
VK_FORMAT_G16_B16R16_2PLANE_444_UNORM_EXT -
VK_FORMAT_G8_B8R8_2PLANE_444_UNORM_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_2_PLANE_444_FORMATS_FEATURES_EXT
-
Promotion to Vulkan 1.3
This extension has been partially promoted. The format enumerants introduced by the extension are included in core Vulkan 1.3, with the EXT suffix omitted. However, runtime support for these formats is optional in core Vulkan 1.3, while if this extension is supported, runtime support is mandatory. The feature structure is not promoted. The original enum names are still available as aliases of the core functionality.
VK_AMD_draw_indirect_count
- Name String
-
VK_AMD_draw_indirect_count - Extension Type
-
Device extension
- Registered Extension Number
-
34
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Promoted to
VK_KHR_draw_indirect_countextension-
Which in turn was promoted to Vulkan 1.2
-
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2016-08-23
- Interactions and External Dependencies
-
-
Promoted to
VK_KHR_draw_indirect_count
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Derrick Owens, AMD
-
Graham Sellers, AMD
-
Daniel Rakos, AMD
-
Dominik Witczak, AMD
-
Description
This extension allows an application to source the number of draws for indirect drawing commands from a buffer. This enables applications to generate an arbitrary number of drawing commands and execute them without host intervention.
Promotion to VK_KHR_draw_indirect_count
All functionality in this extension is included in
VK_KHR_draw_indirect_count, with the suffix changed to KHR.
The original type, enum and command names are still available as aliases of
the core functionality.
New Enum Constants
-
VK_AMD_DRAW_INDIRECT_COUNT_EXTENSION_NAME -
VK_AMD_DRAW_INDIRECT_COUNT_SPEC_VERSION
Version History
-
Revision 2, 2016-08-23 (Dominik Witczak)
-
Minor fixes
-
-
Revision 1, 2016-07-21 (Matthaeus Chajdas)
-
Initial draft
-
VK_AMD_gpu_shader_half_float
- Name String
-
VK_AMD_gpu_shader_half_float - Extension Type
-
Device extension
- Registered Extension Number
-
37
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Deprecated by
VK_KHR_shader_float16_int8extension-
Which in turn was promoted to Vulkan 1.2
-
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2019-04-11
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_gpu_shader_half_float -
This extension provides API support for
GL_AMD_gpu_shader_half_float
-
- Contributors
-
-
Daniel Rakos, AMD
-
Dominik Witczak, AMD
-
Donglin Wei, AMD
-
Graham Sellers, AMD
-
Qun Lin, AMD
-
Rex Xu, AMD
-
Deprecation by VK_KHR_shader_float16_int8
Functionality in this extension was included in
VK_KHR_shader_float16_int8 extension, when
VkPhysicalDeviceShaderFloat16Int8FeaturesKHR::shaderFloat16 is
enabled.
New Enum Constants
-
VK_AMD_GPU_SHADER_HALF_FLOAT_EXTENSION_NAME -
VK_AMD_GPU_SHADER_HALF_FLOAT_SPEC_VERSION
Version History
-
Revision 2, 2019-04-11 (Tobias Hector)
-
Marked as deprecated
-
-
Revision 1, 2016-09-21 (Dominik Witczak)
-
Initial draft
-
VK_AMD_gpu_shader_int16
- Name String
-
VK_AMD_gpu_shader_int16 - Extension Type
-
Device extension
- Registered Extension Number
-
133
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Deprecated by
VK_KHR_shader_float16_int8extension-
Which in turn was promoted to Vulkan 1.2
-
-
- Contact
-
-
Qun Lin linqun
-
Other Extension Metadata
- Last Modified Date
-
2019-04-11
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_gpu_shader_int16 -
This extension provides API support for
GL_AMD_gpu_shader_int16
-
- Contributors
-
-
Daniel Rakos, AMD
-
Dominik Witczak, AMD
-
Matthaeus G. Chajdas, AMD
-
Rex Xu, AMD
-
Timothy Lottes, AMD
-
Zhi Cai, AMD
-
Deprecation by VK_KHR_shader_float16_int8
Functionality in this extension was included in
VK_KHR_shader_float16_int8 extension, when
VkPhysicalDeviceFeatures::shaderInt16 and
VkPhysicalDeviceShaderFloat16Int8FeaturesKHR::shaderFloat16 are
enabled.
Version History
-
Revision 2, 2019-04-11 (Tobias Hector)
-
Marked as deprecated
-
-
Revision 1, 2017-06-18 (Dominik Witczak)
-
First version
-
VK_AMD_negative_viewport_height
- Name String
-
VK_AMD_negative_viewport_height - Extension Type
-
Device extension
- Registered Extension Number
-
36
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Obsoleted by
VK_KHR_maintenance1extension-
Which in turn was promoted to Vulkan 1.1
-
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2016-09-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Graham Sellers, AMD
-
Baldur Karlsson
-
Description
This extension allows an application to specify a negative viewport height. The result is that the viewport transformation will flip along the y-axis.
-
Allow negative height to be specified in the VkViewport::
heightfield to perform y-inversion of the clip-space to framebuffer-space transform. This allows apps to avoid having to usegl_Position.y = -gl_Position.yin shaders also targeting other APIs.
Obsoletion by VK_KHR_maintenance1 and Vulkan 1.1
Functionality in this extension is included in VK_KHR_maintenance1 and
subsequently Vulkan 1.1.
Due to some slight behavioral differences, this extension must not be
enabled alongside VK_KHR_maintenance1, or in an instance created with
version 1.1 or later requested in VkApplicationInfo::apiVersion.
New Enum Constants
-
VK_AMD_NEGATIVE_VIEWPORT_HEIGHT_EXTENSION_NAME -
VK_AMD_NEGATIVE_VIEWPORT_HEIGHT_SPEC_VERSION
VK_MVK_ios_surface
- Name String
-
VK_MVK_ios_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
123
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Deprecation state
-
-
Deprecated by
VK_EXT_metal_surfaceextension
-
- Contact
-
-
Bill Hollings billhollings
-
Other Extension Metadata
- Last Modified Date
-
2020-07-31
- IP Status
-
No known IP claims.
- Contributors
-
-
Bill Hollings, The Brenwill Workshop Ltd.
-
Description
The VK_MVK_ios_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) based on a UIView, the native
surface type of iOS, which is underpinned by a CAMetalLayer, to
support rendering to the surface using Apple’s Metal framework.
Deprecation by VK_EXT_metal_surface
The VK_MVK_ios_surface extension is considered deprecated and has been
superseded by the VK_EXT_metal_surface extension.
New Enum Constants
-
VK_MVK_IOS_SURFACE_EXTENSION_NAME -
VK_MVK_IOS_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IOS_SURFACE_CREATE_INFO_MVK
-
Version History
-
Revision 1, 2017-02-15 (Bill Hollings)
-
Initial draft.
-
-
Revision 2, 2017-02-24 (Bill Hollings)
-
Minor syntax fix to emphasize firm requirement for
UIViewto be backed by aCAMetalLayer.
-
-
Revision 3, 2020-07-31 (Bill Hollings)
-
Update documentation on requirements for
UIView. -
Mark as deprecated by
VK_EXT_metal_surface.
-
VK_MVK_macos_surface
- Name String
-
VK_MVK_macos_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
124
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_surfaceto be enabled
-
- Deprecation state
-
-
Deprecated by
VK_EXT_metal_surfaceextension
-
- Contact
-
-
Bill Hollings billhollings
-
Other Extension Metadata
- Last Modified Date
-
2020-07-31
- IP Status
-
No known IP claims.
- Contributors
-
-
Bill Hollings, The Brenwill Workshop Ltd.
-
Description
The VK_MVK_macos_surface extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface extension) based on an NSView, the native
surface type of macOS, which is underpinned by a CAMetalLayer, to
support rendering to the surface using Apple’s Metal framework.
Deprecation by VK_EXT_metal_surface
The VK_MVK_macos_surface extension is considered deprecated and has been
superseded by the VK_EXT_metal_surface extension.
New Enum Constants
-
VK_MVK_MACOS_SURFACE_EXTENSION_NAME -
VK_MVK_MACOS_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MACOS_SURFACE_CREATE_INFO_MVK
-
Version History
-
Revision 1, 2017-02-15 (Bill Hollings)
-
Initial draft.
-
-
Revision 2, 2017-02-24 (Bill Hollings)
-
Minor syntax fix to emphasize firm requirement for
NSViewto be backed by aCAMetalLayer.
-
-
Revision 3, 2020-07-31 (Bill Hollings)
-
Update documentation on requirements for
NSView. -
Mark as deprecated by
VK_EXT_metal_surface.
-
VK_NV_dedicated_allocation
- Name String
-
VK_NV_dedicated_allocation - Extension Type
-
Device extension
- Registered Extension Number
-
27
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Deprecated by
VK_KHR_dedicated_allocationextension-
Which in turn was promoted to Vulkan 1.1
-
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2016-05-31
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension allows device memory to be allocated for a particular buffer or image resource, which on some devices can significantly improve the performance of that resource. Normal device memory allocations must support memory aliasing and sparse binding, which could interfere with optimizations like framebuffer compression or efficient page table usage. This is important for render targets and very large resources, but need not (and probably should not) be used for smaller resources that can benefit from suballocation.
This extension adds a few small structures to resource creation and memory allocation: a new structure that flags whether am image/buffer will have a dedicated allocation, and a structure indicating the image or buffer that an allocation will be bound to.
New Enum Constants
-
VK_NV_DEDICATED_ALLOCATION_EXTENSION_NAME -
VK_NV_DEDICATED_ALLOCATION_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_BUFFER_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV
-
Examples
// Create an image with
// VkDedicatedAllocationImageCreateInfoNV::dedicatedAllocation
// set to VK_TRUE
VkDedicatedAllocationImageCreateInfoNV dedicatedImageInfo =
{
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV, // sType
NULL, // pNext
VK_TRUE, // dedicatedAllocation
};
VkImageCreateInfo imageCreateInfo =
{
VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, // sType
&dedicatedImageInfo // pNext
// Other members set as usual
};
VkImage image;
VkResult result = vkCreateImage(
device,
&imageCreateInfo,
NULL, // pAllocator
&image);
VkMemoryRequirements memoryRequirements;
vkGetImageMemoryRequirements(
device,
image,
&memoryRequirements);
// Allocate memory with VkDedicatedAllocationMemoryAllocateInfoNV::image
// pointing to the image we are allocating the memory for
VkDedicatedAllocationMemoryAllocateInfoNV dedicatedInfo =
{
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV, // sType
NULL, // pNext
image, // image
VK_NULL_HANDLE, // buffer
};
VkMemoryAllocateInfo memoryAllocateInfo =
{
VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO, // sType
&dedicatedInfo, // pNext
memoryRequirements.size, // allocationSize
FindMemoryTypeIndex(memoryRequirements.memoryTypeBits), // memoryTypeIndex
};
VkDeviceMemory memory;
vkAllocateMemory(
device,
&memoryAllocateInfo,
NULL, // pAllocator
&memory);
// Bind the image to the memory
vkBindImageMemory(
device,
image,
memory,
0);
VK_NV_external_memory
- Name String
-
VK_NV_external_memory - Extension Type
-
Device extension
- Registered Extension Number
-
57
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_NV_external_memory_capabilitiesto be enabled for any device-level functionality
-
- Deprecation state
-
-
Deprecated by
VK_KHR_external_memoryextension-
Which in turn was promoted to Vulkan 1.1
-
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-08-19
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
Applications may wish to export memory to other Vulkan instances or other APIs, or import memory from other Vulkan instances or other APIs to enable Vulkan workloads to be split up across application module, process, or API boundaries. This extension enables applications to create exportable Vulkan memory objects such that the underlying resources can be referenced outside the Vulkan instance that created them.
New Structures
-
Extending VkImageCreateInfo:
-
Extending VkMemoryAllocateInfo:
New Enum Constants
-
VK_NV_EXTERNAL_MEMORY_EXTENSION_NAME -
VK_NV_EXTERNAL_MEMORY_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV -
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV
-
Issues
1) If memory objects are shared between processes and APIs, is this considered aliasing according to the rules outlined in the Memory Aliasing section?
RESOLVED: Yes, but strict exceptions to the rules are added to allow some forms of aliasing in these cases. Further, other extensions may build upon these new aliasing rules to define specific support usage within Vulkan for imported native memory objects, or memory objects from other APIs.
2) Are new image layouts or metadata required to specify image layouts and layout transitions compatible with non-Vulkan APIs, or with other instances of the same Vulkan driver?
RESOLVED: No.
Separate instances of the same Vulkan driver running on the same GPU should
have identical internal layout semantics, so applictions have the tools they
need to ensure views of images are consistent between the two instances.
Other APIs will fall into two categories: Those that are Vulkan compatible
(a term to be defined by subsequent interopability extensions), or Vulkan
incompatible.
When sharing images with Vulkan incompatible APIs, the Vulkan image must be
transitioned to the VK_IMAGE_LAYOUT_GENERAL layout before handing it
off to the external API.
Note this does not attempt to address cross-device transitions, nor transitions to engines on the same device which are not visible within the Vulkan API. Both of these are beyond the scope of this extension.
VK_NV_external_memory_capabilities
- Name String
-
VK_NV_external_memory_capabilities - Extension Type
-
Instance extension
- Registered Extension Number
-
56
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Deprecated by
VK_KHR_external_memory_capabilitiesextension-
Which in turn was promoted to Vulkan 1.1
-
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-08-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1.
-
Interacts with
VK_KHR_dedicated_allocation. -
Interacts with
VK_NV_dedicated_allocation.
-
- Contributors
-
-
James Jones, NVIDIA
-
Description
Applications may wish to import memory from the Direct 3D API, or export memory to other Vulkan instances. This extension provides a set of capability queries that allow applications determine what types of win32 memory handles an implementation supports for a given set of use cases.
New Enum Constants
-
VK_NV_EXTERNAL_MEMORY_CAPABILITIES_EXTENSION_NAME -
VK_NV_EXTERNAL_MEMORY_CAPABILITIES_SPEC_VERSION
Issues
1) Why do so many external memory capabilities need to be queried on a per-memory-handle-type basis?
RESOLVED: This is because some handle types are based on OS-native objects that have far more limited capabilities than the very generic Vulkan memory objects. Not all memory handle types can name memory objects that support 3D images, for example. Some handle types cannot even support the deferred image and memory binding behavior of Vulkan and require specifying the image when allocating or importing the memory object.
2) Does the VkExternalImageFormatPropertiesNV struct need to include a list of memory type bits that support the given handle type?
RESOLVED: No. The memory types that do not support the handle types will simply be filtered out of the results returned by vkGetImageMemoryRequirements when a set of handle types was specified at image creation time.
3) Should the non-opaque handle types be moved to their own extension?
RESOLVED: Perhaps. However, defining the handle type bits does very little and does not require any platform-specific types on its own, and it is easier to maintain the bitmask values in a single extension for now. Presumably more handle types could be added by separate extensions though, and it would be midly weird to have some platform-specific ones defined in the core spec and some in extensions
VK_NV_external_memory_win32
- Name String
-
VK_NV_external_memory_win32 - Extension Type
-
Device extension
- Registered Extension Number
-
58
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_NV_external_memoryto be enabled for any device-level functionality
-
- Deprecation state
-
-
Deprecated by
VK_KHR_external_memory_win32extension
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-08-19
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
Applications may wish to export memory to other Vulkan instances or other APIs, or import memory from other Vulkan instances or other APIs to enable Vulkan workloads to be split up across application module, process, or API boundaries. This extension enables win32 applications to export win32 handles from Vulkan memory objects such that the underlying resources can be referenced outside the Vulkan instance that created them, and import win32 handles created in the Direct3D API to Vulkan memory objects.
New Enum Constants
-
VK_NV_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME -
VK_NV_EXTERNAL_MEMORY_WIN32_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_NV -
VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_NV
-
Issues
1) If memory objects are shared between processes and APIs, is this considered aliasing according to the rules outlined in the Memory Aliasing section?
RESOLVED: Yes, but strict exceptions to the rules are added to allow some forms of aliasing in these cases. Further, other extensions may build upon these new aliasing rules to define specific support usage within Vulkan for imported native memory objects, or memory objects from other APIs.
2) Are new image layouts or metadata required to specify image layouts and layout transitions compatible with non-Vulkan APIs, or with other instances of the same Vulkan driver?
RESOLVED: No.
Separate instances of the same Vulkan driver running on the same GPU should
have identical internal layout semantics, so applictions have the tools they
need to ensure views of images are consistent between the two instances.
Other APIs will fall into two categories: Those that are Vulkan compatible
(a term to be defined by subsequent interopability extensions), or Vulkan
incompatible.
When sharing images with Vulkan incompatible APIs, the Vulkan image must be
transitioned to the VK_IMAGE_LAYOUT_GENERAL layout before handing it
off to the external API.
Note this does not attempt to address cross-device transitions, nor transitions to engines on the same device which are not visible within the Vulkan API. Both of these are beyond the scope of this extension.
3) Do applications need to call CloseHandle() on the values returned
from vkGetMemoryWin32HandleNV when handleType is
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV?
RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application, while an import transfers ownership to the associated driver. Destroying the memory object will not destroy the handle or the handle’s reference to the underlying memory resource.
Examples
//
// Create an exportable memory object and export an external
// handle from it.
//
// Pick an external format and handle type.
static const VkFormat format = VK_FORMAT_R8G8B8A8_UNORM;
static const VkExternalMemoryHandleTypeFlagsNV handleType =
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV;
extern VkPhysicalDevice physicalDevice;
extern VkDevice device;
VkPhysicalDeviceMemoryProperties memoryProperties;
VkExternalImageFormatPropertiesNV properties;
VkExternalMemoryImageCreateInfoNV externalMemoryImageCreateInfo;
VkDedicatedAllocationImageCreateInfoNV dedicatedImageCreateInfo;
VkImageCreateInfo imageCreateInfo;
VkImage image;
VkMemoryRequirements imageMemoryRequirements;
uint32_t numMemoryTypes;
uint32_t memoryType;
VkExportMemoryAllocateInfoNV exportMemoryAllocateInfo;
VkDedicatedAllocationMemoryAllocateInfoNV dedicatedAllocationInfo;
VkMemoryAllocateInfo memoryAllocateInfo;
VkDeviceMemory memory;
VkResult result;
HANDLE memoryHnd;
// Figure out how many memory types the device supports
vkGetPhysicalDeviceMemoryProperties(physicalDevice,
&memoryProperties);
numMemoryTypes = memoryProperties.memoryTypeCount;
// Check the external handle type capabilities for the chosen format
// Exportable 2D image support with at least 1 mip level, 1 array
// layer, and VK_SAMPLE_COUNT_1_BIT using optimal tiling and supporting
// texturing and color rendering is required.
result = vkGetPhysicalDeviceExternalImageFormatPropertiesNV(
physicalDevice,
format,
VK_IMAGE_TYPE_2D,
VK_IMAGE_TILING_OPTIMAL,
VK_IMAGE_USAGE_SAMPLED_BIT |
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
0,
handleType,
&properties);
if ((result != VK_SUCCESS) ||
!(properties.externalMemoryFeatures &
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_NV)) {
abort();
}
// Set up the external memory image creation info
memset(&externalMemoryImageCreateInfo,
0, sizeof(externalMemoryImageCreateInfo));
externalMemoryImageCreateInfo.sType =
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV;
externalMemoryImageCreateInfo.handleTypes = handleType;
if (properties.externalMemoryFeatures &
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV) {
memset(&dedicatedImageCreateInfo, 0, sizeof(dedicatedImageCreateInfo));
dedicatedImageCreateInfo.sType =
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV;
dedicatedImageCreateInfo.dedicatedAllocation = VK_TRUE;
externalMemoryImageCreateInfo.pNext = &dedicatedImageCreateInfo;
}
// Set up the core image creation info
memset(&imageCreateInfo, 0, sizeof(imageCreateInfo));
imageCreateInfo.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
imageCreateInfo.pNext = &externalMemoryImageCreateInfo;
imageCreateInfo.format = format;
imageCreateInfo.extent.width = 64;
imageCreateInfo.extent.height = 64;
imageCreateInfo.extent.depth = 1;
imageCreateInfo.mipLevels = 1;
imageCreateInfo.arrayLayers = 1;
imageCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;
imageCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;
imageCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT |
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
imageCreateInfo.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
imageCreateInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;
vkCreateImage(device, &imageCreateInfo, NULL, &image);
vkGetImageMemoryRequirements(device,
image,
&imageMemoryRequirements);
// For simplicity, just pick the first compatible memory type.
for (memoryType = 0; memoryType < numMemoryTypes; memoryType++) {
if ((1 << memoryType) & imageMemoryRequirements.memoryTypeBits) {
break;
}
}
// At least one memory type must be supported given the prior external
// handle capability check.
assert(memoryType < numMemoryTypes);
// Allocate the external memory object.
memset(&exportMemoryAllocateInfo, 0, sizeof(exportMemoryAllocateInfo));
exportMemoryAllocateInfo.sType =
VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV;
exportMemoryAllocateInfo.handleTypes = handleType;
if (properties.externalMemoryFeatures &
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV) {
memset(&dedicatedAllocationInfo, 0, sizeof(dedicatedAllocationInfo));
dedicatedAllocationInfo.sType =
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV;
dedicatedAllocationInfo.image = image;
exportMemoryAllocateInfo.pNext = &dedicatedAllocationInfo;
}
memset(&memoryAllocateInfo, 0, sizeof(memoryAllocateInfo));
memoryAllocateInfo.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
memoryAllocateInfo.pNext = &exportMemoryAllocateInfo;
memoryAllocateInfo.allocationSize = imageMemoryRequirements.size;
memoryAllocateInfo.memoryTypeIndex = memoryType;
vkAllocateMemory(device, &memoryAllocateInfo, NULL, &memory);
if (!(properties.externalMemoryFeatures &
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV)) {
vkBindImageMemory(device, image, memory, 0);
}
// Get the external memory opaque FD handle
vkGetMemoryWin32HandleNV(device, memory, &memoryHnd);
VK_NV_fragment_shader_barycentric
- Name String
-
VK_NV_fragment_shader_barycentric - Extension Type
-
Device extension
- Registered Extension Number
-
204
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to
VK_KHR_fragment_shader_barycentricextension
-
- Contact
-
-
Pat Brown nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2018-08-03
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_fragment_shader_barycentric -
This extension provides API support for
GL_NV_fragment_shader_barycentric
-
- Contributors
-
-
Pat Brown, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
The extension provides access to three additional fragment shader variable decorations in SPIR-V:
-
PerVertexNV, which indicates that a fragment shader input will not have interpolated values, but instead must be accessed with an extra array index that identifies one of the vertices of the primitive producing the fragment -
BaryCoordNV, which indicates that the variable is a three-component floating-point vector holding barycentric weights for the fragment produced using perspective interpolation -
BaryCoordNoPerspNV, which indicates that the variable is a three-component floating-point vector holding barycentric weights for the fragment produced using linear interpolation
When using GLSL source-based shader languages, the following variables from
GL_NV_fragment_shader_barycentric maps to these SPIR-V built-in
decorations:
-
in vec3 gl_BaryCoordNV;→BaryCoordNV -
in vec3 gl_BaryCoordNoPerspNV;→BaryCoordNoPerspNV
GLSL variables declared using the __pervertexNV GLSL qualifier are
expected to be decorated with PerVertexNV in SPIR-V.
Promotion to VK_KHR_fragment_shader_barycentric
All functionality in this extension is included in
VK_KHR_fragment_shader_barycentric, with the suffix changed to KHR.
New Enum Constants
-
VK_NV_FRAGMENT_SHADER_BARYCENTRIC_EXTENSION_NAME -
VK_NV_FRAGMENT_SHADER_BARYCENTRIC_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_NV
-
Issues
(1) The AMD_shader_explicit_vertex_parameter extension provides similar functionality. Why write a new extension, and how is this extension different?
RESOLVED: For the purposes of Vulkan/SPIR-V, we chose to implement a separate extension due to several functional differences.
First, the hardware supporting this extension can provide a three-component
barycentric weight vector for variables decorated with BaryCoordNV,
while variables decorated with BaryCoordSmoothAMD provide only two
components.
In some cases, it may be more efficient to explicitly interpolate an
attribute via:
float value = (baryCoordNV.x * v[0].attrib +
baryCoordNV.y * v[1].attrib +
baryCoordNV.z * v[2].attrib);
instead of
float value = (baryCoordSmoothAMD.x * (v[0].attrib - v[2].attrib) +
baryCoordSmoothAMD.y * (v[1].attrib - v[2].attrib) +
v[2].attrib);
Additionally, the semantics of the decoration BaryCoordPullModelAMD do
not appear to map to anything supported by the initial hardware
implementation of this extension.
This extension provides a smaller number of decorations than the AMD
extension, as we expect that shaders could derive variables decorated with
things like BaryCoordNoPerspCentroidAMD with explicit attribute
interpolation instructions.
One other relevant difference is that explicit per-vertex attribute access
using this extension does not require a constant vertex number.
(2) Why do the built-in SPIR-V decorations for this extension include two
separate built-ins BaryCoordNV and BaryCoordNoPerspNV when a “no
perspective” variable could be decorated with BaryCoordNV and
NoPerspective?
RESOLVED: The SPIR-V extension for this feature chose to mirror the behavior of the GLSL extension, which provides two built-in variables. Additionally, it is not clear that its a good idea (or even legal) to have two variables using the “same attribute”, but with different interpolation modifiers.
VK_NV_glsl_shader
- Name String
-
VK_NV_glsl_shader - Extension Type
-
Device extension
- Registered Extension Number
-
13
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
- Deprecation state
-
-
Deprecated without replacement
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2016-02-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Piers Daniell, NVIDIA
-
Description
This extension allows GLSL shaders written to the GL_KHR_vulkan_glsl
extension specification to be used instead of SPIR-V.
The implementation will automatically detect whether the shader is SPIR-V or
GLSL, and compile it appropriately.
Deprecation
Functionality in this extension is outside of the scope of Vulkan and is better served by a compiler library such as glslang. No new implementations will support this extension, so applications should not use it.
New Enum Constants
-
VK_NV_GLSL_SHADER_EXTENSION_NAME -
VK_NV_GLSL_SHADER_SPEC_VERSION -
Extending VkResult:
-
VK_ERROR_INVALID_SHADER_NV
-
Examples
Example 1
Passing in GLSL code
char const vss[] =
"#version 450 core\n"
"layout(location = 0) in vec2 aVertex;\n"
"layout(location = 1) in vec4 aColor;\n"
"out vec4 vColor;\n"
"void main()\n"
"{\n"
" vColor = aColor;\n"
" gl_Position = vec4(aVertex, 0, 1);\n"
"}\n"
;
VkShaderModuleCreateInfo vertexShaderInfo = { VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO };
vertexShaderInfo.codeSize = sizeof vss;
vertexShaderInfo.pCode = vss;
VkShaderModule vertexShader;
vkCreateShaderModule(device, &vertexShaderInfo, 0, &vertexShader);
VK_NV_win32_keyed_mutex
- Name String
-
VK_NV_win32_keyed_mutex - Extension Type
-
Device extension
- Registered Extension Number
-
59
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires support for Vulkan 1.0
-
Requires
VK_NV_external_memory_win32to be enabled for any device-level functionality
-
- Deprecation state
-
-
Promoted to
VK_KHR_win32_keyed_mutexextension
-
- Contact
-
-
Carsten Rohde crohde
-
Other Extension Metadata
- Last Modified Date
-
2016-08-19
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
Applications that wish to import Direct3D 11 memory objects into the Vulkan API may wish to use the native keyed mutex mechanism to synchronize access to the memory between Vulkan and Direct3D. This extension provides a way for an application to access the keyed mutex associated with an imported Vulkan memory object when submitting command buffers to a queue.
New Enum Constants
-
VK_NV_WIN32_KEYED_MUTEX_EXTENSION_NAME -
VK_NV_WIN32_KEYED_MUTEX_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_NV
-
Examples
//
// Import a memory object from Direct3D 11, and synchronize
// access to it in Vulkan using keyed mutex objects.
//
extern VkPhysicalDevice physicalDevice;
extern VkDevice device;
extern HANDLE sharedNtHandle;
static const VkFormat format = VK_FORMAT_R8G8B8A8_UNORM;
static const VkExternalMemoryHandleTypeFlagsNV handleType =
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV;
VkPhysicalDeviceMemoryProperties memoryProperties;
VkExternalImageFormatPropertiesNV properties;
VkExternalMemoryImageCreateInfoNV externalMemoryImageCreateInfo;
VkImageCreateInfo imageCreateInfo;
VkImage image;
VkMemoryRequirements imageMemoryRequirements;
uint32_t numMemoryTypes;
uint32_t memoryType;
VkImportMemoryWin32HandleInfoNV importMemoryInfo;
VkMemoryAllocateInfo memoryAllocateInfo;
VkDeviceMemory mem;
VkResult result;
// Figure out how many memory types the device supports
vkGetPhysicalDeviceMemoryProperties(physicalDevice,
&memoryProperties);
numMemoryTypes = memoryProperties.memoryTypeCount;
// Check the external handle type capabilities for the chosen format
// Importable 2D image support with at least 1 mip level, 1 array
// layer, and VK_SAMPLE_COUNT_1_BIT using optimal tiling and supporting
// texturing and color rendering is required.
result = vkGetPhysicalDeviceExternalImageFormatPropertiesNV(
physicalDevice,
format,
VK_IMAGE_TYPE_2D,
VK_IMAGE_TILING_OPTIMAL,
VK_IMAGE_USAGE_SAMPLED_BIT |
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
0,
handleType,
&properties);
if ((result != VK_SUCCESS) ||
!(properties.externalMemoryFeatures &
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_NV)) {
abort();
}
// Set up the external memory image creation info
memset(&externalMemoryImageCreateInfo,
0, sizeof(externalMemoryImageCreateInfo));
externalMemoryImageCreateInfo.sType =
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV;
externalMemoryImageCreateInfo.handleTypes = handleType;
// Set up the core image creation info
memset(&imageCreateInfo, 0, sizeof(imageCreateInfo));
imageCreateInfo.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
imageCreateInfo.pNext = &externalMemoryImageCreateInfo;
imageCreateInfo.format = format;
imageCreateInfo.extent.width = 64;
imageCreateInfo.extent.height = 64;
imageCreateInfo.extent.depth = 1;
imageCreateInfo.mipLevels = 1;
imageCreateInfo.arrayLayers = 1;
imageCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;
imageCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;
imageCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT |
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
imageCreateInfo.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
imageCreateInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;
vkCreateImage(device, &imageCreateInfo, NULL, &image);
vkGetImageMemoryRequirements(device,
image,
&imageMemoryRequirements);
// For simplicity, just pick the first compatible memory type.
for (memoryType = 0; memoryType < numMemoryTypes; memoryType++) {
if ((1 << memoryType) & imageMemoryRequirements.memoryTypeBits) {
break;
}
}
// At least one memory type must be supported given the prior external
// handle capability check.
assert(memoryType < numMemoryTypes);
// Allocate the external memory object.
memset(&exportMemoryAllocateInfo, 0, sizeof(exportMemoryAllocateInfo));
exportMemoryAllocateInfo.sType =
VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV;
importMemoryInfo.handleTypes = handleType;
importMemoryInfo.handle = sharedNtHandle;
memset(&memoryAllocateInfo, 0, sizeof(memoryAllocateInfo));
memoryAllocateInfo.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
memoryAllocateInfo.pNext = &exportMemoryAllocateInfo;
memoryAllocateInfo.allocationSize = imageMemoryRequirements.size;
memoryAllocateInfo.memoryTypeIndex = memoryType;
vkAllocateMemory(device, &memoryAllocateInfo, NULL, &mem);
vkBindImageMemory(device, image, mem, 0);
...
const uint64_t acquireKey = 1;
const uint32_t timeout = INFINITE;
const uint64_t releaseKey = 2;
VkWin32KeyedMutexAcquireReleaseInfoNV keyedMutex =
{ VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_NV };
keyedMutex.acquireCount = 1;
keyedMutex.pAcquireSyncs = &mem;
keyedMutex.pAcquireKeys = &acquireKey;
keyedMutex.pAcquireTimeoutMilliseconds = &timeout;
keyedMutex.releaseCount = 1;
keyedMutex.pReleaseSyncs = &mem;
keyedMutex.pReleaseKeys = &releaseKey;
VkSubmitInfo submit_info = { VK_STRUCTURE_TYPE_SUBMIT_INFO, &keyedMutex };
submit_info.commandBufferCount = 1;
submit_info.pCommandBuffers = &cmd_buf;
vkQueueSubmit(queue, 1, &submit_info, VK_NULL_HANDLE);
Version History
-
Revision 2, 2016-08-11 (James Jones)
-
Updated sample code based on the NV external memory extensions.
-
Renamed from NVX to NV extension.
-
Added Overview and Description sections.
-
Updated sample code to use the NV external memory extensions.
-
-
Revision 1, 2016-06-14 (Carsten Rohde)
-
Initial draft.
-
Appendix F: Vulkan Roadmap Milestones
Roadmap milestones are intended to be supported by mid-to-high-end smartphones, tablets, laptops, consoles, and desktop devices.
Each milestone indicates support for a set of extensions, features, limits, and formats across these devices, and should be supported by all such new hardware shipping by the end of the target year or shortly thereafter.
Roadmap 2022
The Roadmap 2022 milestone is intended to be supported by newer mid-to-high-end devices shipping in 2022 or shortly thereafter across mainstream smartphone, tablet, laptops, console and desktop devices.
Required Features
The following core optional features are required to be supported:
-
Vulkan 1.0 Optional Features
-
Vulkan 1.1 Optional Features
-
Vulkan 1.2 Optional Features
Required Limits
The following core increased limits are required
| Limit Name | Unsupported Limit | Core Limit | Profile Limit | Limit Type1 |
|---|---|---|---|---|
|
- |
4096 |
8192 |
min |
|
- |
4096 |
8192 |
min |
|
- |
4096 |
8192 |
min |
|
- |
256 |
2048 |
min |
|
- |
16384 |
65536 |
min |
|
- |
131072 |
4096 |
max |
|
- |
16 |
64 |
min |
|
- |
12 |
15 |
min |
|
- |
4 |
30 |
min |
|
- |
16 |
200 |
min |
|
- |
4 |
16 |
min |
|
- |
128 |
200 |
min |
|
- |
96 |
576 |
min, n × PerStage |
|
- |
72 |
90 |
min, n × PerStage |
|
- |
24 |
96 |
min, n × PerStage |
|
- |
96 |
1800 |
min, n × PerStage |
|
- |
24 |
144 |
min, n × PerStage |
|
- |
4 |
16 |
min |
|
- |
128 |
256 |
min |
|
- |
(128,128,64) |
(256,256,64) |
min |
|
- |
4 |
8 |
min |
|
- |
4 |
6 |
min |
|
- |
2 |
14 |
min |
|
0.0 |
1.0 |
0.125 |
max, fixed point increment |
|
0.0 |
1.0 |
0.5 |
max, fixed point increment |
|
- |
- |
|
implementation-dependent |
|
- |
4 |
7 |
min |
| Limit Name | Unsupported Limit | Core Limit | Profile Limit | Limit Type1 |
|---|---|---|---|---|
|
- |
1/4 |
4 |
implementation-dependent |
|
- |
|
|
implementation-dependent |
|
- |
|
|
implementation-dependent |
| Limit Name | Unsupported Limit | Core Limit | Profile Limit | Limit Type1 |
|---|---|---|---|---|
|
- |
- |
|
implementation-dependent |
|
- |
- |
|
implementation-dependent |
|
0 |
4 |
7 |
min |
| Limit Name | Unsupported Limit | Core Limit | Profile Limit | Limit Type1 |
|---|---|---|---|---|
|
- |
- |
4 |
min |
Appendix G: API Boilerplate
This appendix defines Vulkan API features that are infrastructure required for a complete functional description of Vulkan, but do not logically belong elsewhere in the Specification.
Vulkan Header Files
Vulkan is defined as an API in the C99 language.
Khronos provides a corresponding set of header files for applications using
the API, which may be used in either C or C++ code.
The interface descriptions in the specification are the same as the
interfaces defined in these header files, and both are derived from the
vk.xml XML API Registry, which is the canonical machine-readable
description of the Vulkan API.
The Registry, scripts used for processing it into various forms, and
documentation of the registry schema are available as described at
https://www.khronos.org/registry/vulkan/#apiregistry .
Language bindings for other languages can be defined using the information in the Specification and the Registry. Khronos does not provide any such bindings, but third-party developers have created some additional bindings.
Vulkan Combined API Header vulkan.h (Informative)
Applications normally will include the header vulkan.h.
In turn, vulkan.h always includes the following headers:
-
vk_platform.h, defining platform-specific macros and headers. -
vulkan_core.h, defining APIs for the Vulkan core and all registered extensions other than window system-specific and provisional extensions, which are included in separate header files.
In addition, specific preprocessor macros defined at the time
vulkan.h is included cause header files for the corresponding window
system-specific and provisional interfaces to be included, as described
below.
Vulkan Platform-Specific Header vk_platform.h (Informative)
Platform-specific macros and interfaces are defined in vk_platform.h.
These macros are used to control platform-dependent behavior, and their
exact definitions are under the control of specific platforms and Vulkan
implementations.
Platform-Specific Calling Conventions
On many platforms the following macros are empty strings, causing platform- and compiler-specific default calling conventions to be used.
VKAPI_ATTR is a macro placed before the return type in Vulkan API
function declarations.
This macro controls calling conventions for C++11 and GCC/Clang-style
compilers.
VKAPI_CALL is a macro placed after the return type in Vulkan API
function declarations.
This macro controls calling conventions for MSVC-style compilers.
VKAPI_PTR is a macro placed between the '(' and '*' in Vulkan API
function pointer declarations.
This macro also controls calling conventions, and typically has the same
definition as VKAPI_ATTR or VKAPI_CALL, depending on the
compiler.
With these macros, a Vulkan function declaration takes the form of:
VKAPI_ATTR <return_type> VKAPI_CALL <command_name>(<command_parameters>);
Additionally, a Vulkan function pointer type declaration takes the form of:
typedef <return_type> (VKAPI_PTR *PFN_<command_name>)(<command_parameters>);
Platform-Specific Header Control
If the VK_NO_STDINT_H macro is defined by the application at compile
time, extended integer types used by the Vulkan API, such as uint8_t,
must also be defined by the application.
Otherwise, the Vulkan headers will not compile.
If VK_NO_STDINT_H is not defined, the system <stdint.h> is used to
define these types.
There is a fallback path when Microsoft Visual Studio version 2008 and
earlier versions are detected at compile time.
If the VK_NO_STDDEF_H macro is defined by the application at compile
time, size_t, must also be defined by the application.
Otherwise, the Vulkan headers will not compile.
If VK_NO_STDDEF_H is not defined, the system <stddef.h> is used to
define this type.
Vulkan Core API Header vulkan_core.h
Applications that do not make use of window system-specific extensions may
simply include vulkan_core.h instead of vulkan.h, although there is
usually no reason to do so.
In addition to the Vulkan API, vulkan_core.h also defines a small number
of C preprocessor macros that are described below.
Vulkan Header File Version Number
VK_HEADER_VERSION is the version number of the vulkan_core.h header.
This value is kept synchronized with the patch version of the released
Specification.
// Provided by VK_VERSION_1_0
// Version of this file
#define VK_HEADER_VERSION 221
VK_HEADER_VERSION_COMPLETE is the complete version number of the
vulkan_core.h header, comprising the major, minor, and patch versions.
The major/minor values are kept synchronized with the complete version of
the released Specification.
This value is intended for use by automated tools to identify exactly which
version of the header was used during their generation.
Applications should not use this value as their
VkApplicationInfo::apiVersion.
Instead applications should explicitly select a specific fixed major/minor
API version using, for example, one of the VK_API_VERSION_*_* values.
// Provided by VK_VERSION_1_0
// Complete version of this file
#define VK_HEADER_VERSION_COMPLETE VK_MAKE_API_VERSION(0, 1, 3, VK_HEADER_VERSION)
VK_API_VERSION is now commented out of vulkan_core.h and cannot be
used.
// Provided by VK_VERSION_1_0
// DEPRECATED: This define has been removed. Specific version defines (e.g. VK_API_VERSION_1_0), or the VK_MAKE_VERSION macro, should be used instead.
//#define VK_API_VERSION VK_MAKE_VERSION(1, 0, 0) // Patch version should always be set to 0
Vulkan Handle Macros
VK_DEFINE_HANDLE defines a dispatchable handle type.
// Provided by VK_VERSION_1_0
#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;
-
objectis the name of the resulting C type.
The only dispatchable handle types are those related to device and instance management, such as VkDevice.
VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a
non-dispatchable handle type.
// Provided by VK_VERSION_1_0
#ifndef VK_DEFINE_NON_DISPATCHABLE_HANDLE
#if (VK_USE_64_BIT_PTR_DEFINES==1)
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
#else
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
#endif
#endif
-
objectis the name of the resulting C type.
Most Vulkan handle types, such as VkBuffer, are non-dispatchable.
|
Note
The |
VK_NULL_HANDLE is a reserved value representing a non-valid object
handle.
It may be passed to and returned from Vulkan commands only when
specifically allowed.
// Provided by VK_VERSION_1_0
#ifndef VK_DEFINE_NON_DISPATCHABLE_HANDLE
#if (VK_USE_64_BIT_PTR_DEFINES==1)
#if (defined(__cplusplus) && (__cplusplus >= 201103L)) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201103L))
#define VK_NULL_HANDLE nullptr
#else
#define VK_NULL_HANDLE ((void*)0)
#endif
#else
#define VK_NULL_HANDLE 0ULL
#endif
#endif
#ifndef VK_NULL_HANDLE
#define VK_NULL_HANDLE 0
#endif
VK_USE_64_BIT_PTR_DEFINES defines whether the default non-dispatchable
handles are declared using either a 64-bit pointer type or a 64-bit unsigned
integer type.
VK_USE_64_BIT_PTR_DEFINES is set to '1' to use a 64-bit pointer type
or any other value to use a 64-bit unsigned integer type.
// Provided by VK_VERSION_1_0
#ifndef VK_USE_64_BIT_PTR_DEFINES
#if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__) ) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
#define VK_USE_64_BIT_PTR_DEFINES 1
#else
#define VK_USE_64_BIT_PTR_DEFINES 0
#endif
#endif
|
Note
The |
Window System-Specific Header Control (Informative)
To use a Vulkan extension supporting a platform-specific window system, header files for that window systems must be included at compile time, or platform-specific types must be forward-declared. The Vulkan header files cannot determine whether or not an external header is available at compile time, so platform-specific extensions are provided in separate headers from the core API and platform-independent extensions, allowing applications to decide which ones should be defined and how the external headers are included.
Extensions dependent on particular sets of platform headers, or that
forward-declare platform-specific types, are declared in a header named for
that platform.
Before including these platform-specific Vulkan headers, applications must
include both vulkan_core.h and any external native headers the platform
extensions depend on.
As a convenience for applications that do not need the flexibility of
separate platform-specific Vulkan headers, vulkan.h includes
vulkan_core.h, and then conditionally includes platform-specific Vulkan
headers and the external headers they depend on.
Applications control which platform-specific headers are included by
#defining macros before including vulkan.h.
The correspondence between platform-specific extensions, external headers
they require, the platform-specific header which declares them, and the
preprocessor macros which enable inclusion by vulkan.h are shown in
the following table.
| Extension Name | Window System Name | Platform-specific Header | Required External Headers | Controlling vulkan.h Macro |
|---|---|---|---|---|
Android |
|
None |
|
|
Wayland |
|
|
|
|
|
Microsoft Windows |
|
|
|
X11 Xcb |
|
|
|
|
X11 Xlib |
|
|
|
|
DirectFB |
|
|
|
|
X11 XRAndR |
|
|
|
|
Google Games Platform |
|
<ggp_c/vulkan_types.h> |
|
|
iOS |
|
None |
|
|
macOS |
|
None |
|
|
VI |
|
None |
|
|
Fuchsia |
|
|
|
|
Metal on CoreAnimation |
|
None |
|
|
QNX Screen |
|
|
|
|
Note
This section describes the purpose of the headers independently of the specific underlying functionality of the window system extensions themselves. Each extension name will only link to a description of that extension when viewing a specification built with that extension included. |
Provisional Extension Header Control (Informative)
Provisional extensions should not be used in production applications. The functionality defined by such extensions may change in ways that break backwards compatibility between revisions, and before final release of a non-provisional version of that extension.
Provisional extensions are defined in a separate provisional header,
vulkan_beta.h, allowing applications to decide whether or not to include
them.
The mechanism is similar to window system-specific
headers: before including vulkan_beta.h, applications must include
vulkan_core.h.
|
Note
Sometimes a provisional extension will include a subset of its interfaces in
|
As a convenience for applications, vulkan.h conditionally includes
vulkan_beta.h.
Applications can control inclusion of vulkan_beta.h by #defining the
macro VK_ENABLE_BETA_EXTENSIONS before including vulkan.h.
|
Note
Starting in version 1.2.171 of the Specification, all provisional enumerants
are protected by the macro |
|
Note
This section describes the purpose of the provisional header independently of the specific provisional extensions which are contained in that header at any given time. The extension appendices for provisional extensions note their provisional status, and link back to this section for more information. Provisional extensions are intended to provide early access for bleeding-edge developers, with the understanding that extension interfaces may change in response to developer feedback. Provisional extensions are very likely to eventually be updated and released as non-provisional extensions, but there is no guarantee this will happen, or how long it will take if it does happen. |
Appendix H: Invariance
The Vulkan specification is not pixel exact. It therefore does not guarantee an exact match between images produced by different Vulkan implementations. However, the specification does specify exact matches, in some cases, for images produced by the same implementation. The purpose of this appendix is to identify and provide justification for those cases that require exact matches.
Repeatability
The obvious and most fundamental case is repeated issuance of a series of Vulkan commands. For any given Vulkan and framebuffer state vector, and for any Vulkan command, the resulting Vulkan and framebuffer state must be identical whenever the command is executed on that initial Vulkan and framebuffer state. This repeatability requirement does not apply when using shaders containing side effects (image and buffer variable stores and atomic operations), because these memory operations are not guaranteed to be processed in a defined order.
The repeatability requirement does not apply for rendering done using a
graphics pipeline that uses VK_RASTERIZATION_ORDER_RELAXED_AMD.
One purpose of repeatability is avoidance of visual artifacts when a double-buffered scene is redrawn. If rendering is not repeatable, swapping between two buffers rendered with the same command sequence may result in visible changes in the image. Such false motion is distracting to the viewer. Another reason for repeatability is testability.
Repeatability, while important, is a weak requirement. Given only repeatability as a requirement, two scenes rendered with one (small) polygon changed in position might differ at every pixel. Such a difference, while within the law of repeatability, is certainly not within its spirit. Additional invariance rules are desirable to ensure useful operation.
Multi-pass Algorithms
Invariance is necessary for a whole set of useful multi-pass algorithms. Such algorithms render multiple times, each time with a different Vulkan mode vector, to eventually produce a result in the framebuffer. Examples of these algorithms include:
-
“Erasing” a primitive from the framebuffer by redrawing it, either in a different color or using the XOR logical operation.
-
Using stencil operations to compute capping planes.
Invariance Rules
For a given Vulkan device:
Rule 1 For any given Vulkan and framebuffer state vector, and for any given Vulkan command, the resulting Vulkan and framebuffer state must be identical each time the command is executed on that initial Vulkan and framebuffer state.
Rule 2 Changes to the following state values have no side effects (the use of any other state value is not affected by the change):
Required:
-
Color and depth/stencil attachment contents
-
Scissor parameters (other than enable)
-
Write masks (color, depth, stencil)
-
Clear values (color, depth, stencil)
Strongly suggested:
-
Stencil parameters (other than enable)
-
Depth test parameters (other than enable)
-
Blend parameters (other than enable)
-
Logical operation parameters (other than enable)
Corollary 1 Fragment generation is invariant with respect to the state values listed in Rule 2.
Rule 3 The arithmetic of each per-fragment operation is invariant except with respect to parameters that directly control it.
Corollary 2 Images rendered into different color attachments of the same framebuffer, either simultaneously or separately using the same command sequence, are pixel identical.
Rule 4 Identical pipelines will produce the same result when run multiple times with the same input. The wording “Identical pipelines” means VkPipeline objects that have been created with identical SPIR-V binaries and identical state, which are then used by commands executed using the same Vulkan state vector. Invariance is relaxed for shaders with side effects, such as performing stores or atomics.
Rule 5 All fragment shaders that either conditionally or unconditionally
assign FragCoord.z to FragDepth are depth-invariant with
respect to each other, for those fragments where the assignment to
FragDepth actually is done.
If a sequence of Vulkan commands specifies primitives to be rendered with shaders containing side effects (image and buffer variable stores and atomic operations), invariance rules are relaxed. In particular, rule 1, corollary 2, and rule 4 do not apply in the presence of shader side effects.
The following weaker versions of rules 1 and 4 apply to Vulkan commands involving shader side effects:
Rule 6 For any given Vulkan and framebuffer state vector, and for any given Vulkan command, the contents of any framebuffer state not directly or indirectly affected by results of shader image or buffer variable stores or atomic operations must be identical each time the command is executed on that initial Vulkan and framebuffer state.
Rule 7 Identical pipelines will produce the same result when run multiple times with the same input as long as:
-
shader invocations do not use image atomic operations;
-
no framebuffer memory is written to more than once by image stores, unless all such stores write the same value; and
-
no shader invocation, or other operation performed to process the sequence of commands, reads memory written to by an image store.
|
Note
The OpenGL specification has the following invariance rule: Consider a primitive p' obtained by translating a primitive p through an offset (x, y) in window coordinates, where x and y are integers. As long as neither p' nor p is clipped, it must be the case that each fragment f' produced from p' is identical to a corresponding fragment f from p except that the center of f' is offset by (x, y) from the center of f. This rule does not apply to Vulkan and is an intentional difference from OpenGL. |
When any sequence of Vulkan commands triggers shader invocations that perform image stores or atomic operations, and subsequent Vulkan commands read the memory written by those shader invocations, these operations must be explicitly synchronized.
Tessellation Invariance
When using a pipeline containing tessellation evaluation shaders, the fixed-function tessellation primitive generator consumes the input patch specified by an application and emits a new set of primitives. The following invariance rules are intended to provide repeatability guarantees. Additionally, they are intended to allow an application with a carefully crafted tessellation evaluation shader to ensure that the sets of triangles generated for two adjacent patches have identical vertices along shared patch edges, avoiding “cracks” caused by minor differences in the positions of vertices along shared edges.
Rule 1 When processing two patches with identical outer and inner tessellation levels, the tessellation primitive generator will emit an identical set of point, line, or triangle primitives as long as the pipeline used to process the patch primitives has tessellation evaluation shaders specifying the same tessellation mode, spacing, vertex order, and point mode decorations. Two sets of primitives are considered identical if and only if they contain the same number and type of primitives and the generated tessellation coordinates for the vertex numbered m of the primitive numbered n are identical for all values of m and n.
Rule 2 The set of vertices generated along the outer edge of the subdivided primitive in triangle and quad tessellation, and the tessellation coordinates of each, depend only on the corresponding outer tessellation level and the spacing decorations in the tessellation shaders of the pipeline.
Rule 3 The set of vertices generated when subdividing any outer primitive edge is always symmetric. For triangle tessellation, if the subdivision generates a vertex with tessellation coordinates of the form (0, x, 1-x), (x, 0, 1-x), or (x, 1-x, 0), it will also generate a vertex with coordinates of exactly (0, 1-x, x), (1-x, 0, x), or (1-x, x, 0), respectively. For quad tessellation, if the subdivision generates a vertex with coordinates of (x, 0) or (0, x), it will also generate a vertex with coordinates of exactly (1-x, 0) or (0, 1-x), respectively. For isoline tessellation, if it generates vertices at (0, x) and (1, x) where x is not zero, it will also generate vertices at exactly (0, 1-x) and (1, 1-x), respectively.
Rule 4 The set of vertices generated when subdividing outer edges in triangular and quad tessellation must be independent of the specific edge subdivided, given identical outer tessellation levels and spacing. For example, if vertices at (x, 1 - x, 0) and (1-x, x, 0) are generated when subdividing the w = 0 edge in triangular tessellation, vertices must be generated at (x, 0, 1-x) and (1-x, 0, x) when subdividing an otherwise identical v = 0 edge. For quad tessellation, if vertices at (x, 0) and (1-x, 0) are generated when subdividing the v = 0 edge, vertices must be generated at (0, x) and (0, 1-x) when subdividing an otherwise identical u = 0 edge.
Rule 5 When processing two patches that are identical in all respects enumerated in rule 1 except for vertex order, the set of triangles generated for triangle and quad tessellation must be identical except for vertex and triangle order. For each triangle n1 produced by processing the first patch, there must be a triangle n2 produced when processing the second patch each of whose vertices has the same tessellation coordinates as one of the vertices in n1.
Rule 6 When processing two patches that are identical in all respects enumerated in rule 1 other than matching outer tessellation levels and/or vertex order, the set of interior triangles generated for triangle and quad tessellation must be identical in all respects except for vertex and triangle order. For each interior triangle n1 produced by processing the first patch, there must be a triangle n2 produced when processing the second patch each of whose vertices has the same tessellation coordinates as one of the vertices in n1. A triangle produced by the tessellator is considered an interior triangle if none of its vertices lie on an outer edge of the subdivided primitive.
Rule 7 For quad and triangle tessellation, the set of triangles connecting an inner and outer edge depends only on the inner and outer tessellation levels corresponding to that edge and the spacing decorations.
Rule 8 The value of all defined components of TessCoord will be in
the range [0, 1].
Additionally, for any defined component x of TessCoord, the results
of computing 1.0-x in a tessellation evaluation shader will be exact.
If any floating-point values in the range [0, 1] fail to satisfy this
property, such values must not be used as tessellation coordinate
components.
Appendix I: Lexicon
This appendix defines terms, abbreviations, and API prefixes used in the Specification.
Glossary
The terms defined in this section are used consistently throughout the Specification and may be used with or without capitalization.
- Accessible (Descriptor Binding)
-
A descriptor binding is accessible to a shader stage if that stage is included in the
stageFlagsof the descriptor binding. Descriptors using that binding can only be used by stages in which they are accessible. - Acquire Operation (Resource)
-
An operation that acquires ownership of an image subresource or buffer range.
- Active (Descriptor Type)
-
When a descriptor with mutable type is updated with vkUpdateDescriptorSets, the active descriptor type changes. When the descriptor is consumed by shaders, it is the active descriptor type which determines validity, i.e.
VkDescriptorSetLayoutBinding::descriptorTypeis replaced with the active descriptor type. A mismatch in active descriptor type and consumption by shader is considered an undefined descriptor. - Active (Transform Feedback)
-
Transform feedback is made active after vkCmdBeginTransformFeedbackEXT executes and remains active until vkCmdEndTransformFeedbackEXT executes. While transform feedback is active, data written to variables in the output interface of the last pre-rasterization shader stage of the graphics pipeline are captured to the bound transform feedback buffers if those variables are decorated for transform feedback.
- Adjacent Vertex
-
A vertex in an adjacency primitive topology that is not part of a given primitive, but is accessible in geometry shaders.
- Active Object (Ray Tracing)
-
A primitive or instance in a ray tracing acceleration structure which has a corresponding ID, and is not inactive (meaning that it is visible to rays).
- Advanced Blend Operation
-
Blending performed using one of the blend operation enums introduced by the
VK_EXT_blend_operation_advancedextension. See Advanced Blending Operations. - Alias (API type/command)
-
An identical definition of another API type/command with the same behavior but a different name.
- Aliased Range (Memory)
-
A range of a device memory allocation that is bound to multiple resources simultaneously.
- Allocation Scope
-
An association of a host memory allocation to a parent object or command, where the allocation’s lifetime ends before or at the same time as the parent object is freed or destroyed, or during the parent command.
- Aspect (Image)
-
An image may contain multiple kinds, or aspects, of data for each pixel, where each aspect is used in a particular way by the pipeline and may be stored differently or separately from other aspects. For example, the color components of an image format make up the color aspect of the image, and may be used as a framebuffer color attachment. Some operations, like depth testing, operate only on specific aspects of an image.
- Attachment (Render Pass)
-
A zero-based integer index name used in render pass creation to refer to a framebuffer attachment that is accessed by one or more subpasses. The index also refers to an attachment description which includes information about the properties of the image view that will later be attached.
- Availability Operation
-
An operation that causes the values generated by specified memory write accesses to become available for future access.
- Available
-
A state of values written to memory that allows them to be made visible.
- Axis-aligned Bounding Box
-
A box bounding a region in space defined by extents along each axis and thus representing a box where each edge is aligned to one of the major axes.
- Back-Facing
-
See Facingness.
- Batch
-
A single structure submitted to a queue as part of a queue submission command, describing a set of queue operations to execute.
- Backwards Compatibility
-
A given version of the API is backwards compatible with an earlier version if an application, relying only on valid behavior and functionality defined by the earlier specification, is able to correctly run against each version without any modification. This assumes no active attempt by that application to not run when it detects a different version.
- Binary Semaphore
-
A semaphore with a boolean payload indicating whether the semaphore is signaled or unsignaled. Represented by a VkSemaphore object created with a semaphore type of
VK_SEMAPHORE_TYPE_BINARY. - Binding (Memory)
-
An association established between a range of a resource object and a range of a memory object. These associations determine the memory locations affected by operations performed on elements of a resource object. Memory bindings are established using the vkBindBufferMemory command for non-sparse buffer objects, using the vkBindImageMemory command for non-sparse image objects, and using the vkQueueBindSparse command for sparse resources.
- Blend Constant
-
Four floating point (RGBA) values used as an input to blending.
- Blending
-
Arithmetic operations between a fragment color value and a value in a color attachment that produce a final color value to be written to the attachment.
- Buffer
-
A resource that represents a linear array of data in device memory. Represented by a VkBuffer object.
- Buffer Device Address
-
A 64-bit value used in a shader to access buffer memory through the
PhysicalStorageBufferstorage class. - Buffer View
-
An object that represents a range of a specific buffer, and state controlling how the contents are interpreted. Represented by a VkBufferView object.
- Built-In Variable
-
A variable decorated in a shader, where the decoration makes the variable take values provided by the execution environment or values that are generated by fixed-function pipeline stages.
- Built-In Interface Block
-
A block defined in a shader containing only variables decorated with built-in decorations, and is used to match against other shader stages.
- Clip Coordinates
-
The homogeneous coordinate space that vertex positions (
Positiondecoration) are written in by pre-rasterization shader stages. - Clip Distance
-
A built-in output from pre-rasterization shader stages defining a clip half-space against which the primitive is clipped.
- Clip Volume
-
The intersection of the view volume with all clip half-spaces.
- Color Attachment
-
A subpass attachment point, or image view, that is the target of fragment color outputs and blending.
- Color Fragment
-
A unique color value within a pixel of a multisampled color image. The fragment mask will contain indices to the color fragment.
- Color Renderable Format
-
A VkFormat where
VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BITis set in one of the following, depending on the image’s tiling:-
VkFormatProperties::
linearTilingFeatures -
VkFormatProperties::
optimalTilingFeaturesor a VkFormat whereVK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NVis set in VkFormatProperties::linearTilingFeatures -
VkDrmFormatModifierPropertiesEXT::
drmFormatModifierTilingFeatures
-
- Combined Image Sampler
-
A descriptor type that includes both a sampled image and a sampler.
- Command Buffer
-
An object that records commands to be submitted to a queue. Represented by a VkCommandBuffer object.
- Command Pool
-
An object that command buffer memory is allocated from, and that owns that memory. Command pools aid multithreaded performance by enabling different threads to use different allocators, without internal synchronization on each use. Represented by a VkCommandPool object.
- Compatible Allocator
-
When allocators are compatible, allocations from each allocator can be freed by the other allocator.
- Compatible Image Formats
-
When formats are compatible, images created with one of the formats can have image views created from it using any of the compatible formats. Also see Size-Compatible Image Formats.
- Compatible Queues
-
Queues within a queue family. Compatible queues have identical properties.
- Complete Mipmap Chain
-
The entire set of miplevels that can be provided for an image, from the largest application specified miplevel size down to the minimum miplevel size. See Image Miplevel Sizing.
- Completed Operation
-
A deferred operation whose corresponding command has been executed to completion. See Deferred Host Operations
- Component (Format)
-
A distinct part of a format. Color components are represented with
R,G,B, andA. Depth and stencil components are represented withDandS. Formats can have multiple instances of the same component. Some formats have other notations such asEorXwhich are not considered a component of the format. - Compressed Texel Block
-
An element of an image having a block-compressed format, comprising a rectangular block of texel values that are encoded as a single value in memory. Compressed texel blocks of a particular block-compressed format have a corresponding width, height, and depth defining the dimensions of these elements in units of texels, and a size in bytes of the encoding in memory.
- Constant Integral Expressions
-
A SPIR-V constant instruction whose type is
OpTypeInt. See Constant Instruction in section 2.2.1 “Instructions” of the Khronos SPIR-V Specification. - Cooperative Matrix
-
A SPIR-V type where the storage for and computations performed on the matrix are spread across a set of invocations such as a subgroup.
- Corner-Sampled Image
-
A VkImage where unnormalized texel coordinates are centered on integer values instead of half-integer values. Specified by setting the
VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NVbit on VkImageCreateInfo::flagsat image creation. - Coverage Index
-
The index of a sample in the coverage mask.
- Coverage Mask
-
A bitfield associated with a fragment representing the samples that were determined to be covered based on the result of rasterization, and then subsequently modified by fragment operations or the fragment shader.
- Cull Distance
-
A built-in output from pre-rasterization shader stages defining a cull half-space where the primitive is rejected if all vertices have a negative value for the same cull distance.
- Cull Volume
-
The intersection of the view volume with all cull half-spaces.
- Decoration (SPIR-V)
-
Auxiliary information such as built-in variables, stream numbers, invariance, interpolation type, relaxed precision, etc., added to variables or structure-type members through decorations.
- Deferrable Command
-
A command which allows deferred execution of host-side work. See Deferred Host Operations.
- Deferrable Operation
-
A single logical item of host-side work which can be deferred. Represented by the VkDeferredOperationKHR object. See Deferred Host Operations.
- Deprecated (feature)
-
A feature is deprecated if it is no longer recommended as the correct or best way to achieve its intended purpose.
- Depth/Stencil Attachment
-
A subpass attachment point, or image view, that is the target of depth and/or stencil test operations and writes.
- Depth/Stencil Format
-
A VkFormat that includes depth and/or stencil components.
- Depth/Stencil Image (or ImageView)
-
A VkImage (or VkImageView) with a depth/stencil format.
- Depth/Stencil Resolve Attachment
-
A subpass attachment point, or image view, that is the target of a multisample resolve operation from the corresponding depth/stencil attachment at the end of the subpass.
- Derivative Group
-
A set of fragment or compute shader invocations that cooperate to compute derivatives, including implicit derivatives for sampled image operations.
- Descriptor
-
Information about a resource or resource view written into a descriptor set that is used to access the resource or view from a shader.
- Descriptor Binding
-
An entry in a descriptor set layout corresponding to zero or more descriptors of a single descriptor type in a set. Defined by a VkDescriptorSetLayoutBinding structure.
- Descriptor Pool
-
An object that descriptor sets are allocated from, and that owns the storage of those descriptor sets. Descriptor pools aid multithreaded performance by enabling different threads to use different allocators, without internal synchronization on each use. Represented by a VkDescriptorPool object.
- Descriptor Set
-
An object that resource descriptors are written into via the API, and that can be bound to a command buffer such that the descriptors contained within it can be accessed from shaders. Represented by a VkDescriptorSet object.
- Descriptor Set Layout
-
An object defining the set of resources (types and counts) and their relative arrangement (in the binding namespace) within a descriptor set. Used when allocating descriptor sets and when creating pipeline layouts. Represented by a VkDescriptorSetLayout object.
- Device
-
The processor(s) and execution environment that perform tasks requested by the application via the Vulkan API.
- Device Group
-
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 Index
-
A zero-based integer that identifies one physical device from a logical device. A device index is valid if it is less than the number of physical devices in the logical device.
- Device Mask
-
A bitmask where each bit represents one device index. A device mask value is valid if every bit that is set in the mask is at a bit position that is less than the number of physical devices in the logical device.
- Device Memory
-
Memory accessible to the device. Represented by a VkDeviceMemory object.
- Device-Level Command
-
Any command that is dispatched from a logical device, or from a child object of a logical device.
- Device-Level Functionality
-
All device-level commands and objects, and their structures, enumerated types, and enumerants.
- Device-Level Object
-
Logical device objects and their child objects. For example, VkDevice, VkQueue, and VkCommandBuffer objects are device-level objects.
- Device-Local Memory
-
Memory that is connected to the device, and may be more performant for device access than host-local memory.
- Direct Drawing Commands
-
Drawing commands that take all their parameters as direct arguments to the command (and not sourced via structures in buffer memory as the indirect drawing commands). Includes vkCmdDrawMultiIndexedEXT, vkCmdDrawMultiEXT, vkCmdDrawMeshTasksNV, vkCmdDraw, and vkCmdDrawIndexed.
- Disjoint
-
Disjoint planes are image planes to which memory is bound independently.
A disjoint image consists of multiple disjoint planes, and is created with theVK_IMAGE_CREATE_DISJOINT_BITbit set. - Dispatchable Command
-
A non-global command. The first argument to each dispatchable command is a dispatchable handle type.
- Dispatchable Handle
-
A handle of a pointer handle type which may be used by layers as part of intercepting API commands.
- Dispatching Commands
-
Commands that provoke work using a compute pipeline. Includes vkCmdDispatch and vkCmdDispatchIndirect.
- Drawing Commands
-
Commands that provoke work using a graphics pipeline. Includes vkCmdDraw, vkCmdDrawIndexed, vkCmdDrawIndirectCount, vkCmdDrawIndexedIndirectCount, vkCmdDrawIndirectCountKHR, vkCmdDrawIndexedIndirectCountKHR, vkCmdDrawIndirectCountAMD, vkCmdDrawIndexedIndirectCountAMD, vkCmdDrawMultiIndexedEXT, vkCmdDrawMultiEXT, vkCmdDrawMeshTasksNV, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV, vkCmdDrawIndirect, and vkCmdDrawIndexedIndirect.
- Duration (Command)
-
The duration of a Vulkan command refers to the interval between calling the command and its return to the caller.
- Dynamic Storage Buffer
-
A storage buffer whose offset is specified each time the storage buffer is bound to a command buffer via a descriptor set.
- Dynamic Uniform Buffer
-
A uniform buffer whose offset is specified each time the uniform buffer is bound to a command buffer via a descriptor set.
- Dynamically Uniform
-
See Dynamically Uniform in section 2.2 “Terms” of the Khronos SPIR-V Specification.
- Element
-
Arrays are composed of multiple elements, where each element exists at a unique index within that array. Used primarily to describe data passed to or returned from the Vulkan API.
- Explicitly-Enabled Layer
-
A layer enabled by the application by adding it to the enabled layer list in vkCreateInstance or vkCreateDevice.
- Event
-
A synchronization primitive that is signaled when execution of previous commands completes through a specified set of pipeline stages. Events can be waited on by the device and polled by the host. Represented by a VkEvent object.
- Executable State (Command Buffer)
-
A command buffer that has ended recording commands and can be executed. See also Initial State and Recording State.
- Execution Dependency
-
A dependency that guarantees that certain pipeline stages’ work for a first set of commands has completed execution before certain pipeline stages’ work for a second set of commands begins execution. This is accomplished via pipeline barriers, subpass dependencies, events, or implicit ordering operations.
- Execution Dependency Chain
-
A sequence of execution dependencies that transitively act as a single execution dependency.
- Explicit chroma reconstruction
-
An implementation of sampler Y′CBCR conversion which reconstructs reduced-resolution chroma samples to luma resolution and then separately performs texture sample interpolation. This is distinct from an implicit implementation, which incorporates chroma sample reconstruction into texture sample interpolation.
- Extension Scope
-
The set of objects and commands that can be affected by an extension. Extensions are either device scope or instance scope.
- Extending Structure
-
A structure type which may appear in the
pNextchain of another structure, extending the functionality of the other structure. Extending structures may be defined by either core API versions or extensions. - External Handle
-
A resource handle which has meaning outside of a specific Vulkan device or its parent instance. External handles may be used to share resources between multiple Vulkan devices in different instances, or between Vulkan and other APIs. Some external handle types correspond to platform-defined handles, in which case the resource may outlive any particular Vulkan device or instance and may be transferred between processes, or otherwise manipulated via functionality defined by the platform for that handle type.
- External synchronization
-
A type of synchronization required of the application, where parameters defined to be externally synchronized must not be used simultaneously in multiple threads.
- Facingness (Polygon)
-
A classification of a polygon as either front-facing or back-facing, depending on the orientation (winding order) of its vertices.
- Facingness (Fragment)
-
A fragment is either front-facing or back-facing, depending on the primitive it was generated from. If the primitive was a polygon (regardless of polygon mode), the fragment inherits the facingness of the polygon. All other fragments are front-facing.
- Fence
-
A synchronization primitive that is signaled when a set of batches or sparse binding operations complete execution on a queue. Fences can be waited on by the host. Represented by a VkFence object.
- Flat Shading
-
A property of a vertex attribute that causes the value from a single vertex (the provoking vertex) to be used for all vertices in a primitive, and for interpolation of that attribute to return that single value unaltered.
- Format Features
-
A set of features from VkFormatFeatureFlagBits that a VkFormat is capable of using for various commands. The list is determined by factors such as VkImageTiling.
- Fragment
-
A rectangular framebuffer region with associated data produced by rasterization and processed by fragment operations including the fragment shader.
- Fragment Area
-
The width and height, in pixels, of a fragment.
- Fragment Density
-
The ratio of fragments per framebuffer area in the x and y direction.
- Fragment Density Texel Size
-
The (w,h) framebuffer region in pixels that each texel in a fragment density map applies to.
- Fragment Input Attachment Interface
-
Variables with
UniformConstantstorage class and a decoration ofInputAttachmentIndexthat are statically used by a fragment shader’s entry point, which receive values from input attachments. - Fragment Mask
-
A lookup table that associates color samples with color fragment values.
- Fragment Output Interface
-
A fragment shader entry point’s variables with
Outputstorage class, which output to color and/or depth/stencil attachments. - Framebuffer
-
A collection of image views and a set of dimensions that, in conjunction with a render pass, define the inputs and outputs used by drawing commands. Represented by a VkFramebuffer object.
- Framebuffer Attachment
-
One of the image views used in a framebuffer.
- Framebuffer Coordinates
-
A coordinate system in which adjacent pixels’ coordinates differ by 1 in x and/or y, with (0,0) in the upper left corner and pixel centers at half-integers.
- Framebuffer-Space
-
Operating with respect to framebuffer coordinates.
- Framebuffer-Local
-
A framebuffer-local dependency guarantees that only for a single framebuffer region, the first set of operations happens-before the second set of operations.
- Framebuffer-Global
-
A framebuffer-global dependency guarantees that for all framebuffer regions, the first set of operations happens-before the second set of operations.
- Framebuffer Region
-
A framebuffer region is a set of sample (x, y, layer, sample) coordinates that is a subset of the entire framebuffer.
- Front-Facing
-
See Facingness.
- Full Compatibility
-
A given version of the API is fully compatible with another version if an application, relying only on valid behavior and functionality defined by either of those specifications, is able to correctly run against each version without any modification. This assumes no active attempt by that application to not run when it detects a different version.
- Global Command
-
A Vulkan command for which the first argument is not a dispatchable handle type.
- Global Workgroup
-
A collection of local workgroups dispatched by a single dispatching or single mesh task drawing command.
- Handle
-
An opaque integer or pointer value used to refer to a Vulkan object. Each object type has a unique handle type.
- Happen-after, happens-after
-
A transitive, irreflexive and antisymmetric ordering relation between operations. An execution dependency with a source of A and a destination of B enforces that B happens-after A. The inverse relation of happens-before.
- Happen-before, happens-before
-
A transitive, irreflexive and antisymmetric ordering relation between operations. An execution dependency with a source of A and a destination of B enforces that A happens-before B. The inverse relation of happens-after.
- Helper Invocation
-
A fragment shader invocation that is created solely for the purposes of evaluating derivatives for use in non-helper fragment shader invocations, and which does not have side effects.
- Host
-
The processor(s) and execution environment that the application runs on, and that the Vulkan API is exposed on.
- Host Mapped Device Memory
-
Device memory that is mapped for host access using vkMapMemory.
- Host Mapped Foreign Memory
-
Memory owned by a foreign device that is mapped for host access.
- Host Memory
-
Memory not accessible to the device, used to store implementation data structures.
- Host-Accessible Subresource
-
A buffer, or a linear image subresource in either the
VK_IMAGE_LAYOUT_PREINITIALIZEDorVK_IMAGE_LAYOUT_GENERALlayout. Host-accessible subresources have a well-defined addressing scheme which can be used by the host. - Host-Local Memory
-
Memory that is not local to the device, and may be less performant for device access than device-local memory.
- Host-Visible Memory
-
Device memory that can be mapped on the host and can be read and written by the host.
- ICD
-
Installable Client Driver. An ICD is represented as a VkPhysicalDevice.
- Identically Defined Objects
-
Objects of the same type where all arguments to their creation or allocation functions, with the exception of
pAllocator, are-
Vulkan handles which refer to the same object or
-
identical scalar or enumeration values or
-
Host pointers which point to an array of values or structures which also satisfy these three constraints.
-
- Image
-
A resource that represents a multi-dimensional formatted interpretation of device memory. Represented by a VkImage object.
- Image Subresource
-
A specific mipmap level, layer, and set of aspects of an image.
- Image Subresource Range
-
A set of image subresources that are contiguous mipmap levels and layers.
- Image View
-
An object that represents an image subresource range of a specific image, and state controlling how the contents are interpreted. Represented by a VkImageView object.
- Immutable Sampler
-
A sampler descriptor provided at descriptor set layout creation time, and that is used for that binding in all descriptor sets allocated from the layout, and cannot be changed.
- Implicit chroma reconstruction
-
An implementation of sampler Y′CBCR conversion which reconstructs the reduced-resolution chroma samples directly at the sample point, as part of the normal texture sampling operation. This is distinct from an explicit chroma reconstruction implementation, which reconstructs the reduced-resolution chroma samples to the resolution of the luma samples, then filters the result as part of texture sample interpolation.
- Implicitly-Enabled Layer
-
A layer enabled by a loader-defined mechanism outside the Vulkan API, rather than explicitly by the application during instance or device creation.
- Inactive Object (Ray Tracing)
-
A primitive or instance in a ray tracing acceleration structure which has a corresponding ID, but which will never report an intersection with any ray.
- Index Buffer
-
A buffer bound via vkCmdBindIndexBuffer which is the source of index values used to fetch vertex attributes for a vkCmdDrawIndexed or vkCmdDrawIndexedIndirect command.
- Indexed Drawing Commands
-
Drawing commands which use an index buffer as the source of index values used to fetch vertex attributes for a drawing command. Includes vkCmdDrawIndexed, vkCmdDrawIndexedIndirectCount, vkCmdDrawIndexedIndirectCountKHR, vkCmdDrawIndexedIndirectCountAMD, vkCmdDrawMultiIndexedEXT, and vkCmdDrawIndexedIndirect.
- Indirect Commands
-
Drawing or dispatching commands that source some of their parameters from structures in buffer memory. Includes vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, vkCmdDrawIndirectCount, vkCmdDrawIndexedIndirectCount, vkCmdDrawIndirectCountKHR, vkCmdDrawIndexedIndirectCountKHR, vkCmdDrawIndirectCountAMD, vkCmdDrawIndexedIndirectCountAMD, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV, and vkCmdDispatchIndirect.
- Indirect Commands Layout
-
A definition of a sequence of commands, that are generated on the device via vkCmdPreprocessGeneratedCommandsNV and vkCmdExecuteGeneratedCommandsNV. Each sequence is comprised of multiple VkIndirectCommandsTokenTypeNV, which represent a subset of traditional command buffer commands. Represented as VkIndirectCommandsLayoutNV.
- Indirect Drawing Commands
-
Drawing commands that source some of their parameters from structures in buffer memory. Includes vkCmdDrawIndirect, vkCmdDrawIndirectCount, vkCmdDrawIndexedIndirectCount, vkCmdDrawIndirectCountKHR, vkCmdDrawIndexedIndirectCountKHR, vkCmdDrawIndirectCountAMD, vkCmdDrawIndexedIndirectCountAMD, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV, and vkCmdDrawIndexedIndirect.
- Initial State (Command Buffer)
-
A command buffer that has not begun recording commands. See also Recording State and Executable State.
- Inline Uniform Block
-
A descriptor type that represents uniform data stored directly in descriptor sets, and supports read-only access in a shader.
- Input Attachment
-
A descriptor type that represents an image view, and supports unfiltered read-only access in a shader, only at the fragment’s location in the view.
- Instance
-
The top-level Vulkan object, which represents the application’s connection to the implementation. Represented by a VkInstance object.
- Instance-Level Command
-
Any command that is dispatched from an instance, or from a child object of an instance, except for physical devices and their children.
- Instance-Level Functionality
-
All instance-level commands and objects, and their structures, enumerated types, and enumerants.
- Instance-Level Object
-
High-level Vulkan objects, which are not physical devices, nor children of physical devices. For example, VkInstance is an instance-level object.
- Instance (Memory)
-
In a logical device representing more than one physical device, some device memory allocations have the requested amount of memory allocated multiple times, once for each physical device in a device mask. Each such replicated allocation is an instance of the device memory.
- Instance (Resource)
-
In a logical device representing more than one physical device, buffer and image resources exist on all physical devices but can be bound to memory differently on each. Each such replicated resource is an instance of the resource.
- Internal Synchronization
-
A type of synchronization required of the implementation, where parameters not defined to be externally synchronized may require internal mutexing to avoid multithreaded race conditions.
- Invocation (Shader)
-
A single execution of an entry point in a SPIR-V module. For example, a single vertex’s execution of a vertex shader or a single fragment’s execution of a fragment shader.
- Invocation Group
-
A set of shader invocations that are executed in parallel and that must execute the same control flow path in order for control flow to be considered dynamically uniform.
- Invocation Repack Instruction
-
A ray tracing shader call instruction where the implementation may change the set of invocations that are executing.
- Join (Deferred Host Operations)
-
The act of instructing a thread to participate in the execution of a deferred operation. See Deferred Host Operations.
- Linear Color Attachment
-
A color attachment with linear tiling
- Linear Resource
-
A resource is linear if it is one of the following:
-
a VkBuffer
-
a VkImage created with
VK_IMAGE_TILING_LINEAR -
a VkImage created with
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXTand whose Linux DRM format modifier isDRM_FORMAT_MOD_LINEAR
Because a VkAccelerationStructureKHR resource does not have memory bound to it directly, it is considered neither linear nor non-linear. However, the VkBuffer on which a VkAccelerationStructureKHR resource is placed is a linear resource.
A resource is non-linear if it is one of the following:
-
a VkImage created with
VK_IMAGE_TILING_OPTIMAL -
a VkImage created with
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXTand whose Linux DRM format modifier is notDRM_FORMAT_MOD_LINEAR
-
- Linux DRM Format Modifier
-
A 64-bit, vendor-prefixed, semi-opaque unsigned integer describing vendor-specific details of an image’s memory layout. In Linux graphics APIs, modifiers are commonly used to specify the memory layout of externally shared images. An image has a modifier if and only if it is created with
tilingequal toVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. For more details, refer to the appendix for extensionVK_EXT_image_drm_format_modifier. - Local Workgroup
-
A collection of compute shader invocations invoked by a single dispatching command, which share data via
WorkgroupLocalvariables and can synchronize with each other. - Logical Device
-
An object that represents the application’s interface to the physical device. The logical device is the parent of most Vulkan objects. Represented by a VkDevice object.
- Logical Operation
-
Bitwise operations between a fragment color value and a value in a color attachment, that produce a final color value to be written to the attachment.
- Lost Device
-
A state that a logical device may be in as a result of unrecoverable implementation errors, or other exceptional conditions.
- Mappable
-
See Host-Visible Memory.
- Memory Dependency
-
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
-
- Memory Domain
-
A memory domain is an abstract place to which memory writes are made available by availability operations and memory domain operations. The memory domains correspond to the set of agents that the write can then be made visible to. The memory domains are host, device, shader, workgroup instance (for workgroup instance there is a unique domain for each compute workgroup) and subgroup instance (for subgroup instance there is a unique domain for each subgroup).
- Memory Domain Operation
-
An operation that makes the writes that are available to one memory domain available to another memory domain.
- Memory Heap
-
A region of memory from which device memory allocations can be made.
- Memory Type
-
An index used to select a set of memory properties (e.g. mappable, cached) for a device memory allocation.
- Mesh Shading Pipeline
-
A graphics pipeline where the primitives are assembled explicitly in the shader stages. In contrast to the primitive shading pipeline where input primitives are assembled by fixed function processing.
- Mesh Tasks Drawing Commands
-
Drawing commands which create shader invocations organized in workgroups for drawing mesh tasks. Includes vkCmdDrawMeshTasksNV, vkCmdDrawMeshTasksIndirectNV, and vkCmdDrawMeshTasksIndirectCountNV.
- Minimum Miplevel Size
-
The smallest size that is permitted for a miplevel. For conventional images this is 1x1x1. For corner-sampled images, this is 2x2x2. See Image Miplevel Sizing.
- Mip Tail Region
-
The set of mipmap levels of a sparse residency texture that are too small to fill a sparse block, and that must all be bound to memory collectively and opaquely.
- Multi-planar
-
A multi-planar format (or “planar format”) is an image format consisting of more than one plane, identifiable with a
_2PLANEor_3PLANEcomponent to the format name and listed in Formats requiring sampler Y′CBCR conversion forVK_IMAGE_ASPECT_COLOR_BITimage views. A multi-planar image (or “planar image”) is an image of a multi-planar format. - Non-Dispatchable Handle
-
A handle of an integer handle type. Handle values may not be unique, even for two objects of the same type.
- Non-Indexed Drawing Commands
-
Drawing commands for which the vertex attributes are sourced in linear order from the vertex input attributes for a drawing command (i.e. they do not use an index buffer). Includes vkCmdDraw, vkCmdDrawIndirectCount, vkCmdDrawIndirectCountKHR, vkCmdDrawIndirectCountAMD, vkCmdDrawMultiEXT, and vkCmdDrawIndirect.
- Normalized
-
A value that is interpreted as being in the range [0,1] as a result of being implicitly divided by some other value.
- Normalized Device Coordinates
-
A coordinate space after perspective division is applied to clip coordinates, and before the viewport transformation converts to framebuffer coordinates.
- Obsoleted (feature)
-
A feature is obsolete if it can no longer be used.
- Opaque Capture Address
-
A 64-bit value representing the device address of a buffer or memory object that is expected to be used by trace capture/replay tools in combination with the
bufferDeviceAddressfeature. - Overlapped Range (Aliased Range)
-
The aliased range of a device memory allocation that intersects a given image subresource of an image or range of a buffer.
- Ownership (Resource)
-
If an entity (e.g. a queue family) has ownership of a resource, access to that resource is well-defined for access by that entity.
- Packed Format
-
A format whose components are stored as a single texel block in memory, with their relative locations defined within that element.
- Passthrough Geometry Shader
-
A geometry shader which uses the
PassthroughNVdecoration on a variable in its input interface. Output primitives in a passthrough geometry shader always have the same topology as the input primitive and are not produced by emitting vertices. - Payload
-
Importable or exportable reference to the internal data of an object in Vulkan.
- Per-View
-
A variable that has an array of values which are output, one for each view that is being generated. A mesh shader which uses the
PerViewNVdecoration on a variable in its output interface. - Peer Memory
-
An instance of memory corresponding to a different physical device than the physical device performing the memory access, in a logical device that represents multiple physical devices.
- Physical Device
-
An object that represents a single device in the system. Represented by a VkPhysicalDevice object.
- Physical-Device-Level Command
-
Any command that is dispatched from a physical device.
- Physical-Device-Level Functionality
-
All physical-device-level commands and objects, and their structures, enumerated types, and enumerants.
- Physical-Device-Level Object
-
Physical device objects. For example, VkPhysicalDevice is a physical-device-level object.
- Pipeline
-
An object controlling how graphics or compute work is executed on the device. A pipeline includes one or more shaders, as well as state controlling any non-programmable stages of the pipeline. Represented by a VkPipeline object.
- Pipeline Barrier
-
An execution and/or memory dependency recorded as an explicit command in a command buffer, that forms a dependency between the previous and subsequent commands.
- Pipeline Cache
-
An object that can be used to collect and retrieve information from pipelines as they are created, and can be populated with previously retrieved information in order to accelerate pipeline creation. Represented by a VkPipelineCache object.
- Pipeline Layout
-
An object defining the set of resources (via a collection of descriptor set layouts) and push constants used by pipelines that are created using the layout. Used when creating a pipeline and when binding descriptor sets and setting push constant values. Represented by a VkPipelineLayout object.
- Pipeline Library
-
A pipeline that cannot be directly used, instead defining a set of shaders and shader groups which will be linked into other pipelines.
- Pipeline Stage
-
A logically independent execution unit that performs some of the operations defined by an action command.
- Pipeline Trace Ray Instruction
-
A ray tracing instruction which traces a ray into an acceleration structure when using ray tracing pipelines. One of
OpTraceNV,OpTraceRayMotionNV,OpTraceMotionNV,OpTraceRayKHR. pNextChain-
A set of structures chained together through their
pNextmembers. - Planar
-
See multi-planar.
- Plane
-
An image plane is part of the representation of an image, containing a subset of the color components required to represent the texels in the image and with a contiguous mapping of coordinates to bound memory. Most images consist only of a single plane, but some formats spread the components across multiple image planes. The host-accessible properties of each image plane are accessed in a linear layout using vkGetImageSubresourceLayout. If a multi-planar image is created with the
VK_IMAGE_CREATE_DISJOINT_BITbit set, the image is described as disjoint, and its planes are therefore bound to memory independently. - Point Sampling (Rasterization)
-
A rule that determines whether a fragment sample location is covered by a polygon primitive by testing whether the sample location is in the interior of the polygon in framebuffer-space, or on the boundary of the polygon according to the tie-breaking rules.
- Potential Format Features
-
The union of all VkFormatFeatureFlagBits that the implementation supports for a specified VkFormat, over all supported image tilings. For external formats the VkFormatFeatureFlagBits is provided by the implementation.
- Pre-rasterization
-
Operations that execute before rasterization, and any state associated with those operations.
- Presentable image
-
A
VkImageobject obtained from aVkSwapchainKHRused to present to aVkSurfaceKHRobject. - Preserve Attachment
-
One of a list of attachments in a subpass description that is not read or written by the subpass, but that is read or written on earlier and later subpasses and whose contents must be preserved through this subpass.
- Primary Command Buffer
-
A command buffer that can execute secondary command buffers, and can be submitted directly to a queue.
- Primitive Shading Pipeline
-
A graphics pipeline where input primitives are assembled by fixed function processing. It is the counterpart to mesh shading.
- Primitive Topology
-
State controlling how vertices are assembled into primitives, e.g. as lists of triangles, strips of lines, etc..
- Promoted (feature)
-
A feature from an older extension is considered promoted if it is made available as part of a new core version or newer extension with wider support.
- Protected Buffer
-
A buffer to which protected device memory can be bound.
- Protected-capable Device Queue
-
A device queue to which protected command buffers can be submitted.
- Protected Command Buffer
-
A command buffer which can be submitted to a protected-capable device queue.
- Protected Device Memory
-
Device memory which can be visible to the device but must not be visible to the host.
- Protected Image
-
An image to which protected device memory can be bound.
- Provisional
-
A feature is released provisionally in order to get wider feedback on the functionality before it is finalized. Provisional features may change in ways that break backwards compatibility, and thus are not recommended for use in production applications.
- Provoking Vertex
-
The vertex in a primitive from which flat shaded attribute values are taken. This is generally the “first” vertex in the primitive, and depends on the primitive topology.
- Push Constants
-
A small bank of values writable via the API and accessible in shaders. Push constants allow the application to set values used in shaders without creating buffers or modifying and binding descriptor sets for each update.
- Push Constant Interface
-
The set of variables with
PushConstantstorage class that are statically used by a shader entry point, and which receive values from push constant commands. - Push Descriptors
-
Descriptors that are written directly into a command buffer rather than into a descriptor set. Push descriptors allow the application to set descriptors used in shaders without allocating or modifying descriptor sets for each update.
- Descriptor Update Template
-
An object specifying a mapping from descriptor update information in host memory to elements in a descriptor set, which helps enable more efficient descriptor set updates.
- Query Pool
-
An object containing a number of query entries and their associated state and results. Represented by a VkQueryPool object.
- Queue
-
An object that executes command buffers and sparse binding operations on a device. Represented by a VkQueue object.
- Queue Family
-
A set of queues that have common properties and support the same functionality, as advertised in VkQueueFamilyProperties.
- Queue Operation
-
A unit of work to be executed by a specific queue on a device, submitted via a queue submission command. Each queue submission command details the specific queue operations that occur as a result of calling that command. Queue operations typically include work that is specific to each command, and synchronization tasks.
- Queue Submission
-
Zero or more batches and an optional fence to be signaled, passed to a command for execution on a queue. See the Devices and Queues chapter for more information.
- Ray Tracing Command
-
Commands that provoke work using a ray tracing pipeline. Includes vkCmdTraceRaysNV, vkCmdTraceRaysKHR, and vkCmdTraceRaysIndirectKHR .
- Recording State (Command Buffer)
-
A command buffer that is ready to record commands. See also Initial State and Executable State.
- Release Operation (Resource)
-
An operation that releases ownership of an image subresource or buffer range.
- Render Pass
-
An object that represents a set of framebuffer attachments and phases of rendering using those attachments. Represented by a VkRenderPass object.
- Render Pass Instance
-
A use of a render pass in a command buffer.
- Required Extensions
-
Extensions that must be enabled alongside extensions dependent on them (see Extension Dependencies).
- Reset (Command Buffer)
-
Resetting a command buffer discards any previously recorded commands and puts a command buffer in the initial state.
- Residency Code
-
An integer value returned by sparse image instructions, indicating whether any sparse unbound texels were accessed.
- Resolve Attachment
-
A subpass attachment point, or image view, that is the target of a multisample resolve operation from the corresponding color attachment at the end of the subpass.
- Retired Swapchain
-
A swapchain that has been used as the
oldSwapchainparameter to vkCreateSwapchainKHR. Images cannot be acquired from a retired swapchain, however images that were acquired (but not presented) before the swapchain was retired can be presented. - Sample Index
-
The index of a sample within a single set of samples.
- Sample Shading
-
Invoking the fragment shader multiple times per fragment, with the covered samples partitioned among the invocations.
- Sampled Image
-
A descriptor type that represents an image view, and supports filtered (sampled) and unfiltered read-only access in a shader.
- Sampler
-
An object containing state controlling how sampled image data is sampled (or filtered) when accessed in a shader. Also a descriptor type describing the object. Represented by a VkSampler object.
- Secondary Command Buffer
-
A command buffer that can be executed by a primary command buffer, and must not be submitted directly to a queue.
- Self-Dependency
-
A subpass dependency from a subpass to itself, i.e. with
srcSubpassequal todstSubpass. A self-dependency is not automatically performed during a render pass instance, rather a subset of it can be performed via vkCmdPipelineBarrier during the subpass. - Semaphore
-
A synchronization primitive that supports signal and wait operations, and can be used to synchronize operations within a queue or across queues. Represented by a VkSemaphore object.
- Shader
-
Instructions selected (via an entry point) from a shader module, which are executed in a shader stage.
- Shader Call
-
An instruction which may cause execution to continue in a different shader stage.
- Shader Code
-
A stream of instructions used to describe the operation of a shader.
- Shader Group
-
A set of Shader Stages that are part of a VkPipeline containing multiple of such sets. This allows the device to make use of all the shader groups from the bound pipeline independently.
- Shader Module
-
A collection of shader code, potentially including several functions and entry points, that is used to create shaders in pipelines. Represented by a VkShaderModule object.
- Shader Stage
-
A stage of the graphics or compute pipeline that executes shader code.
- Shading Rate
-
The ratio of the number of fragment shader invocations generated in a fully covered framebuffer region to the size (in pixels) of that region.
- Shading Rate Image
-
An image used to establish the shading rate for a framebuffer region, where each pixel controls the shading rate for a corresponding framebuffer region.
- Shared presentable image
-
A presentable image created from a swapchain with VkPresentModeKHR set to either
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHRorVK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR. - Side Effect
-
A store to memory or atomic operation on memory from a shader invocation.
- Single-plane format
-
A format that is not multi-planar.
- Size-Compatible Image Formats
-
When a compressed image format and an uncompressed image format are size-compatible, it means that the texel block size of the uncompressed format must equal the texel block size of the compressed format.
- Sparse Block
-
An element of a sparse resource that can be independently bound to memory. Sparse blocks of a particular sparse resource have a corresponding size in bytes that they use in the bound memory.
- Sparse Image Block
-
A sparse block in a sparse partially-resident image. In addition to the sparse block size in bytes, sparse image blocks have a corresponding width, height, and depth defining the dimensions of these elements in units of texels or compressed texel blocks, the latter being used in case of sparse images having a block-compressed format.
- Sparse Unbound Texel
-
A texel read from a region of a sparse texture that does not have memory bound to it.
- SRT
-
A decomposition of a spatial transform separating out scale, rotation, and translation which has better linear interpolation properties for representing motion.
- Static Use
-
An object in a shader is statically used by a shader entry point if any function in the entry point’s call tree contains an instruction using the object. Static use is used to constrain the set of descriptors used by a shader entry point.
- Storage Buffer
-
A descriptor type that represents a buffer, and supports reads, writes, and atomics in a shader.
- Storage Image
-
A descriptor type that represents an image view, and supports unfiltered loads, stores, and atomics in a shader.
- Storage Texel Buffer
-
A descriptor type that represents a buffer view, and supports unfiltered, formatted reads, writes, and atomics in a shader.
- Subgroup
-
A set of shader invocations that can synchronize and share data with each other efficiently. In compute shaders, the local workgroup is a superset of the subgroup.
- Subgroup Mask
-
A bitmask for all invocations in the current subgroup with one bit per invocation, starting with the least significant bit in the first vector component, continuing to the last bit (less than
SubgroupSize) in the last required vector component. - Subpass
-
A phase of rendering within a render pass, that reads and writes a subset of the attachments.
- Subpass Dependency
-
An execution and/or memory dependency between two subpasses described as part of render pass creation, and automatically performed between subpasses in a render pass instance. A subpass dependency limits the overlap of execution of the pair of subpasses, and can provide guarantees of memory coherence between accesses in the subpasses.
- Subpass Description
-
Lists of attachment indices for input attachments, color attachments, depth/stencil attachment, resolve attachments, depth/stencil resolve, and preserve attachments used by the subpass in a render pass.
- Subset (Self-Dependency)
-
A subset of a self-dependency is a pipeline barrier performed during the subpass of the self-dependency, and whose stage masks and access masks each contain a subset of the bits set in the identically named mask in the self-dependency.
- Texel Block
-
A single addressable element of an image with an uncompressed VkFormat, or a single compressed block of an image with a compressed VkFormat.
- Texel Block Size
-
The size (in bytes) used to store a texel block of a compressed or uncompressed image.
- Texel Coordinate System
-
One of three coordinate systems (normalized, unnormalized, integer) defining how texel coordinates are interpreted in an image or a specific mipmap level of an image.
- Timeline Semaphore
-
A semaphore with a strictly increasing 64-bit unsigned integer payload indicating whether the semaphore is signaled with respect to a particular reference value. Represented by a VkSemaphore object created with a semaphore type of
VK_SEMAPHORE_TYPE_TIMELINE. - Uniform Texel Buffer
-
A descriptor type that represents a buffer view, and supports unfiltered, formatted, read-only access in a shader.
- Uniform Buffer
-
A descriptor type that represents a buffer, and supports read-only access in a shader.
- Units in the Last Place (ULP)
-
A measure of floating-point error loosely defined as the smallest representable step in a floating-point format near a given value. For the precise definition see Precision and Operation of SPIR-V instructions or Jean-Michel Muller, “On the definition of ulp(x)”, RR-5504, INRIA. Other sources may also use the term “unit of least precision”.
- Unnormalized
-
A value that is interpreted according to its conventional interpretation, and is not normalized.
- Unprotected Buffer
-
A buffer to which unprotected device memory can be bound.
- Unprotected Command Buffer
-
A command buffer which can be submitted to an unprotected device queue or a protected-capable device queue.
- Unprotected Device Memory
-
Device memory which can be visible to the device and can be visible to the host.
- Unprotected Image
-
An image to which unprotected device memory can be bound.
- User-Defined Variable Interface
-
A shader entry point’s variables with
InputorOutputstorage class that are not built-in variables. - Vertex Input Attribute
-
A graphics pipeline resource that produces input values for the vertex shader by reading data from a vertex input binding and converting it to the attribute’s format.
- Vertex Stream
-
A vertex stream is where the last pre-rasterization shader stages outputs vertex data, which then goes to the rasterizer, is captured to a transform feedback buffer, or both. Geometry shaders can emit primitives to multiple independent vertex streams. Each vertex emitted by the geometry shader is directed at one of the vertex streams.
- Validation Cache
-
An object that can be used to collect and retrieve validation results from the validation layers, and can be populated with previously retrieved results in order to accelerate the validation process. Represented by a VkValidationCacheEXT object.
- Variable-Sized Descriptor Binding
-
A descriptor binding whose size will be specified when a descriptor set is allocated using this layout.
- Vertex Input Binding
-
A graphics pipeline resource that is bound to a buffer and includes state that affects addressing calculations within that buffer.
- Vertex Input Interface
-
A vertex shader entry point’s variables with
Inputstorage class, which receive values from vertex input attributes. - View Mask
-
When multiview is enabled, a view mask is a property of a subpass controlling which views the rendering commands are broadcast to.
- View Volume
-
A subspace in homogeneous coordinates, corresponding to post-projection x and y values between -1 and +1, and z values between 0 and +1.
- Viewport Transformation
-
A transformation from normalized device coordinates to framebuffer coordinates, based on a viewport rectangle and depth range.
- Visibility Operation
-
An operation that causes available values to become visible to specified memory accesses.
- Visible
-
A state of values written to memory that allows them to be accessed by a set of operations.
Common Abbreviations
The abbreviations and acronyms defined in this section are sometimes used in the Specification and the API where they are considered clear and commonplace.
- Src
-
Source
- Dst
-
Destination
- Min
-
Minimum
- Max
-
Maximum
- Rect
-
Rectangle
- Info
-
Information
- LOD
-
Level of Detail
- ID
-
Identifier
- UUID
-
Universally Unique Identifier
- Op
-
Operation
- R
-
Red color component
- G
-
Green color component
- B
-
Blue color component
- A
-
Alpha color component
- RTZ
-
Round towards zero
- RTE
-
Round to nearest even
Prefixes
Prefixes are used in the API to denote specific semantic meaning of Vulkan names, or as a label to avoid name clashes, and are explained here:
- VK/Vk/vk
-
Vulkan namespace
All types, commands, enumerants and defines in this specification are prefixed with these two characters. - PFN/pfn
-
Function Pointer
Denotes that a type is a function pointer, or that a variable is of a pointer type. - p
-
Pointer
Variable is a pointer. - vkCmd
-
Commands that record commands in command buffers
These API commands do not result in immediate processing on the device. Instead, they record the requested action in a command buffer for execution when the command buffer is submitted to a queue. - s
-
Structure
Used to denote theVK_STRUCTURE_TYPE*member of each structure insType
Appendix J: Credits (Informative)
Vulkan 1.3 is the result of contributions from many people and companies participating in the Khronos Vulkan Working Group, as well as input from the Vulkan Advisory Panel.
Members of the Working Group, including the company that they represented at the time of their most recent contribution, are listed in the following section. Some specific contributions made by individuals are listed together with their name.
Working Group Contributors to Vulkan
-
Aaron Greig, Codeplay Software Ltd. (version 1.1)
-
Aaron Hagan, AMD (version 1.1)
-
Adam Jackson, Red Hat (versions 1.0, 1.1)
-
Adam Śmigielski, Mobica (version 1.0)
-
Aditi Verma, Qualcomm (version 1.3)
-
Ahmed Abdelkhalek, AMD (version 1.3)
-
Aidan Fabius, Core Avionics & Industrial Inc. (version 1.2)
-
Alan Baker, Google (versions 1.1, 1.2, 1.3)
-
Alan Ward, Google (versions 1.1, 1.2)
-
Alejandro Piñeiro, Igalia (version 1.1)
-
Alex Bourd, Qualcomm Technologies, Inc. (versions 1.0, 1.1)
-
Alex Crabb, Caster Communications (versions 1.2, 1.3)
-
Alex Walters, Imagination Technologies (versions 1.2, 1.3)
-
Alexander Galazin, Arm (versions 1.0, 1.1, 1.2, 1.3)
-
Alexey Sachkov, Intel (version 1.3)
-
Allan MacKinnon, Google (version 1.3)
-
Allen Hux, Intel (version 1.0)
-
Alon Or-bach, Google (versions 1.0, 1.1, 1.2, 1.3) (WSI technical sub-group chair)
-
Anastasia Stulova, Arm (versions 1.2, 1.3)
-
Andreas Vasilakis, Think Silicon (version 1.2)
-
Andres Gomez, Igalia (version 1.1)
-
Andrew Cox, Samsung Electronics (version 1.0)
-
Andrew Ellem, Google (version 1.3)
-
Andrew Garrard, Imagination Technologies (versions 1.0, 1.1, 1.2, 1.3) (format wrangler)
-
Andrew Poole, Samsung Electronics (version 1.0)
-
Andrew Rafter, Samsung Electronics (version 1.0)
-
Andrew Richards, Codeplay Software Ltd. (version 1.0)
-
Andrew Woloszyn, Google (versions 1.0, 1.1)
-
Ann Thorsnes, Khronos (versions 1.2, 1.3)
-
Antoine Labour, Google (versions 1.0, 1.1)
-
Aras Pranckevičius, Unity Technologies (version 1.0)
-
Arseny Kapoulkine, Roblox (version 1.3)
-
Ashwin Kolhe, NVIDIA (version 1.0)
-
Baldur Karlsson, Valve Software (versions 1.1, 1.2, 1.3)
-
Barthold Lichtenbelt, NVIDIA (version 1.1)
-
Bas Nieuwenhuizen, Google (versions 1.1, 1.2)
-
Ben Bowman, Imagination Technologies (version 1.0)
-
Benj Lipchak, Unknown (version 1.0)
-
Bill Hollings, Brenwill (versions 1.0, 1.1, 1.2, 1.3)
-
Bill Licea-Kane, Qualcomm Technologies, Inc. (versions 1.0, 1.1)
-
Blaine Kohl, Khronos (versions 1.2, 1.3)
-
Bob Fraser, Google (version 1.3)
-
Boris Zanin, Mobica (versions 1.2, 1.3)
-
Brent E. Insko, Intel (version 1.0)
-
Brian Ellis, Qualcomm Technologies, Inc. (version 1.0)
-
Brian Paul, VMware (versions 1.2, 1.3)
-
Caio Marcelo de Oliveira Filho, Intel (versions 1.2, 1.3)
-
Cass Everitt, Oculus VR (versions 1.0, 1.1)
-
Cemil Azizoglu, Canonical (version 1.0)
-
Chad Versace, Google (versions 1.0, 1.1, 1.2)
-
Chang-Hyo Yu, Samsung Electronics (version 1.0)
-
Charles Giessen, LunarG (version 1.3)
-
Chia-I Wu, LunarG (version 1.0)
-
Chris Frascati, Qualcomm Technologies, Inc. (version 1.0)
-
Chris Glover, Google (version 1.3)
-
Christian Forfang, Arm (version 1.3)
-
Christoph Kubisch, NVIDIA (version 1.3)
-
Christophe Riccio, Unity Technologies (versions 1.0, 1.1)
-
Cody Northrop, LunarG (version 1.0)
-
Colin Riley, AMD (version 1.1)
-
Cort Stratton, Google (versions 1.1, 1.2)
-
Courtney Goeltzenleuchter, Google (versions 1.0, 1.1, 1.3)
-
Craig Davies, Huawei (version 1.2)
-
Dae Kim, Imagination Technologies (version 1.1)
-
Damien Leone, NVIDIA (version 1.0)
-
Dan Baker, Oxide Games (versions 1.0, 1.1)
-
Dan Ginsburg, Valve Software (versions 1.0, 1.1, 1.2, 1.3)
-
Daniel Johnston, Intel (versions 1.0, 1.1)
-
Daniel Koch, NVIDIA (versions 1.0, 1.1, 1.2, 1.3)
-
Daniel Rakos, AMD (versions 1.0, 1.1, 1.2, 1.3)
-
Daniel Stone, Collabora (versions 1.1, 1.2)
-
Daniel Vetter, Intel (version 1.2)
-
David Airlie, Red Hat (versions 1.0, 1.1, 1.2, 1.3)
-
David Mao, AMD (versions 1.0, 1.2)
-
David Miller, Miller & Mattson (versions 1.0, 1.1) (Vulkan reference card)
-
David Neto, Google (versions 1.0, 1.1, 1.2, 1.3)
-
David Pankratz, Huawei (version 1.3)
-
David Wilkinson, AMD (version 1.2)
-
David Yu, Pixar (version 1.0)
-
Dejan Mircevski, Google (version 1.1)
-
Diego Novillo, Google (version 1.3)
-
Dimitris Georgakakis, Think Silicon (version 1.3)
-
Dominik Witczak, AMD (versions 1.0, 1.1, 1.3)
-
Donald Scorgie, Imagination Technologies (version 1.2)
-
Dzmitry Malyshau, Mozilla (versions 1.1, 1.2, 1.3)
-
Ed Hutchins, Oculus (version 1.2)
-
Emily Stearns, Khronos (versions 1.2, 1.3)
-
François Duranleau, Gameloft (version 1.3)
-
Frank (LingJun) Chen, Qualcomm Technologies, Inc. (version 1.0)
-
Fred Liao, Mediatek (version 1.0)
-
Gabe Dagani, Freescale (version 1.0)
-
Gabor Sines, AMD (version 1.2)
-
Graeme Leese, Broadcom (versions 1.0, 1.1, 1.2, 1.3)
-
Graham Connor, Imagination Technologies (version 1.0)
-
Graham Sellers, AMD (versions 1.0, 1.1)
-
Graham Wihlidal, Electronic Arts (version 1.3)
-
Greg Fischer, LunarG (version 1.1)
-
Gregory Grebe, AMD (version 1.3)
-
Hai Nguyen, Google (versions 1.2, 1.3)
-
Hans-Kristian Arntzen, Valve Software (versions 1.1, 1.2, 1.3)
-
Henri Verbeet, Codeweavers (version 1.2)
-
Huei Long Wang, Huawei (version 1.3)
-
Hwanyong Lee, Kyungpook National University (version 1.0)
-
Iago Toral, Igalia (versions 1.1, 1.2)
-
Ian Elliott, Google (versions 1.0, 1.1, 1.2)
-
Ian Romanick, Intel (versions 1.0, 1.1, 1.3)
-
Ivan Briano, Intel (version 1.3)
-
James Fitzpatrick, Imagination (version 1.3)
-
James Hughes, Oculus VR (version 1.0)
-
James Jones, NVIDIA (versions 1.0, 1.1, 1.2, 1.3)
-
James Riordon, Khronos (versions 1.2, 1.3)
-
Jamie Madill, Google (version 1.3)
-
Jan Hermes, Continental Corporation (versions 1.0, 1.1)
-
Jan-Harald Fredriksen, Arm (versions 1.0, 1.1, 1.2, 1.3)
-
Jason Ekstrand, Intel (versions 1.0, 1.1, 1.2, 1.3)
-
Jean-François Roy, Google (versions 1.1, 1.2, 1.3)
-
Jeff Bolz, NVIDIA (versions 1.0, 1.1, 1.2, 1.3)
-
Jeff Juliano, NVIDIA (versions 1.0, 1.1, 1.2)
-
Jeff Leger, Qualcomm Technologies, Inc. (versions 1.1, 1.3)
-
Jeff Phillips, Khronos (version 1.3)
-
Jeff Vigil, Samsung Electronics (versions 1.0, 1.1, 1.2, 1.3)
-
Jens Owen, Google (versions 1.0, 1.1)
-
Jeremy Hayes, LunarG (version 1.0)
-
Jesse Barker, Unity Technologies (versions 1.0, 1.1, 1.2, 1.3)
-
Jesse Hall, Google (versions 1.0, 1.1, 1.2, 1.3)
-
Joe Davis, Samsung Electronics (version 1.1)
-
Johannes van Waveren, Oculus VR (versions 1.0, 1.1)
-
John Anthony, Arm (version 1.2, 1.3)
-
John Kessenich, Google (versions 1.0, 1.1, 1.2, 1.3) (SPIR-V and GLSL for Vulkan spec author)
-
John McDonald, Valve Software (versions 1.0, 1.1, 1.2, 1.3)
-
John Zulauf, LunarG (versions 1.1, 1.2, 1.3)
-
Jon Ashburn, LunarG (version 1.0)
-
Jon Leech, Independent (versions 1.0, 1.1, 1.2, 1.3) (XML toolchain, normative language, release wrangler)
-
Jonas Gustavsson, Samsung Electronics (versions 1.0, 1.1)
-
Jonas Meyer, Epic Games (versions 1.2, 1.3)
-
Jonathan Hamilton, Imagination Technologies (version 1.0)
-
Jordan Justen, Intel (version 1.1)
-
Joshua Ashton, Valve Software (version 1.3)
-
Jungwoo Kim, Samsung Electronics (versions 1.0, 1.1)
-
Jörg Wagner, Arm (version 1.1)
-
Kalle Raita, Google (version 1.1)
-
Karen Ghavam, LunarG (versions 1.1, 1.2, 1.3)
-
Karl Schultz, LunarG (versions 1.1, 1.2)
-
Kathleen Mattson, Khronos (versions 1.0, 1.1, 1.2)
-
Kaye Mason, Google (version 1.2)
-
Keith Packard, Valve (version 1.2)
-
Kenneth Benzie, Codeplay Software Ltd. (versions 1.0, 1.1)
-
Kenneth Russell, Google (version 1.1)
-
Kerch Holt, NVIDIA (versions 1.0, 1.1)
-
Kevin O’Neil, AMD (version 1.1)
-
Kevin Petit, Arm (version 1.3)
-
Kris Rose, Khronos (versions 1.2, 1.3)
-
Kristian Kristensen, Intel (versions 1.0, 1.1)
-
Krzysztof Iwanicki, Samsung Electronics (version 1.0)
-
Larry Seiler, Intel (version 1.0)
-
Laura Shubel, Caster Communications (version 1.3)
-
Lauri Ilola, Nokia (version 1.1)
-
Lei Zhang, Google (version 1.2)
-
Lenny Komow, LunarG (versions 1.1, 1.2)
-
Liam Middlebrook, NVIDIA (version 1.3)
-
Lionel Landwerlin, Intel (versions 1.1, 1.2)
-
Lisie Aartsen, Khronos (version 1.3)
-
Liz Maitral, Khronos (version 1.2)
-
Lou Kramer, AMD (version 1.3)
-
Lutz Latta, Lucasfilm (version 1.0)
-
Maciej Jesionowski, AMD (version 1.1)
-
Mais Alnasser, AMD (version 1.1)
-
Marcin Kantoch, AMD (version 1.3)
-
Marcin Rogucki, Mobica (version 1.1)
-
Maria Rovatsou, Codeplay Software Ltd. (version 1.0)
-
Mariusz Merecki, Intel (version 1.3)
-
Mark Bellamy, Arm (version 1.2, 1.3)
-
Mark Callow, Independent (versions 1.0, 1.1, 1.2, 1.3)
-
Mark Kilgard, NVIDIA (versions 1.1, 1.2)
-
Mark Lobodzinski, LunarG (versions 1.0, 1.1, 1.2)
-
Mark Young, LunarG (versions 1.1, 1.3)
-
Markus Tavenrath, NVIDIA (version 1.1)
-
Marty Johnson, Khronos (version 1.3)
-
Mateusz Przybylski, Intel (version 1.0)
-
Mathias Heyer, NVIDIA (versions 1.0, 1.1)
-
Mathias Schott, NVIDIA (versions 1.0, 1.1)
-
Mathieu Robart, Arm (version 1.2)
-
Matt Netsch, Qualcomm Technologies, Inc. (version 1.1)
-
Matthew Rusch, NVIDIA (version 1.3)
-
Matthäus Chajdas, AMD (versions 1.1, 1.2, 1.3)
-
Maurice Ribble, Qualcomm Technologies, Inc. (versions 1.0, 1.1)
-
Maxim Lukyanov, Samsung Electronics (version 1.0)
-
Michael Blumenkrantz, Self (version 1.3)
-
Michael Lentine, Google (version 1.0)
-
Michael O’Hara, AMD (version 1.1)
-
Michael Phillip, Samsung Electronics (version 1.2)
-
Michael Wong, Codeplay Software Ltd. (version 1.1)
-
Michael Worcester, Imagination Technologies (versions 1.0, 1.1)
-
Michal Pietrasiuk, Intel (versions 1.0, 1.3)
-
Mika Isojarvi, Google (versions 1.0, 1.1)
-
Mike Schuchardt, LunarG (versions 1.1, 1.2)
-
Mike Stroyan, LunarG (version 1.0)
-
Mike Weiblen, LunarG (versions 1.1, 1.2, 1.3)
-
Minyoung Son, Samsung Electronics (version 1.0)
-
Mitch Singer, AMD (versions 1.0, 1.1, 1.2, 1.3)
-
Mythri Venugopal, Samsung Electronics (version 1.0)
-
Naveen Leekha, Google (version 1.0)
-
Neil Henning, AMD (versions 1.0, 1.1, 1.2, 1.3)
-
Neil Hickey, Arm (version 1.2)
-
Neil Trevett, NVIDIA (versions 1.0, 1.1, 1.2, 1.3)
-
Nick Penwarden, Epic Games (version 1.0)
-
Nicolai Hähnle, AMD (version 1.1)
-
Niklas Smedberg, Unity Technologies (version 1.0)
-
Norbert Nopper, Independent (versions 1.0, 1.1)
-
Nuno Subtil, NVIDIA (versions 1.1, 1.2, 1.3)
-
Pat Brown, NVIDIA (version 1.0)
-
Patrick Cozzi, Independent (version 1.1)
-
Patrick Doane, Blizzard Entertainment (version 1.0)
-
Peter Lohrmann, AMD (versions 1.0, 1.2)
-
Petros Bantolas, Imagination Technologies (version 1.1)
-
Philip Rebohle, Valve Software (version 1.3)
-
Pierre Boudier, NVIDIA (versions 1.0, 1.1, 1.2, 1.3)
-
Pierre-Loup Griffais, Valve Software (versions 1.0, 1.1, 1.2, 1.3)
-
Piers Daniell, NVIDIA (versions 1.0, 1.1, 1.2, 1.3)
-
Ping Liu, Intel (version 1.3)
-
Piotr Bialecki, Intel (version 1.0)
-
Piotr Byszewski, Mobica (version 1.3)
-
Prabindh Sundareson, Samsung Electronics (version 1.0)
-
Pyry Haulos, Google (versions 1.0, 1.1) (Vulkan conformance test subcommittee chair)
-
Rachel Bradshaw, Caster Communications (version 1.3)
-
Rajeev Rao, Qualcomm (version 1.2)
-
Ralph Potter, Samsung Electronics (versions 1.1, 1.2, 1.3)
-
Raun Krisch, Samsung Electronics (version 1.3)
-
Ray Smith, Arm (versions 1.0, 1.1, 1.2)
-
Ricardo Garcia, Igalia (version 1.3)
-
Richard Huddy, Samsung Electronics (versions 1.2, 1.3)
-
Rob Barris, NVIDIA (version 1.1)
-
Rob Stepinski, Transgaming (version 1.0)
-
Robert Simpson, Qualcomm Technologies, Inc. (versions 1.0, 1.1, 1.3)
-
Rolando Caloca Olivares, Epic Games (versions 1.0, 1.1, 1.2, 1.3)
-
Ronan Keryell, Xilinx (version 1.3)
-
Roy Ju, Mediatek (version 1.0)
-
Rufus Hamade, Imagination Technologies (version 1.0)
-
Ruihao Zhang, Qualcomm Technologies, Inc. (versions 1.1, 1.2, 1.3)
-
Samuel Huang, Mediatek (version 1.3)
-
Samuel Iglesias Gonsalvez, Igalia (version 1.3)
-
Sascha Willems, Self (version 1.3)
-
Sean Ellis, Arm (version 1.0)
-
Sean Harmer, KDAB Group (versions 1.0, 1.1)
-
Shannon Woods, Google (versions 1.0, 1.1, 1.2, 1.3)
-
Slawomir Cygan, Intel (versions 1.0, 1.1, 1.3)
-
Slawomir Grajewski, Intel (versions 1.0, 1.1, 1.3)
-
Sorel Bosan, AMD (version 1.1)
-
Spencer Fricke, Samsung Electronics (versions 1.2, 1.3)
-
Stefanus Du Toit, Google (version 1.0)
-
Stephen Huang, Mediatek (version 1.1)
-
Steve Hill, Broadcom (versions 1.0, 1.2)
-
Steve Viggers, Core Avionics & Industrial Inc. (versions 1.0, 1.2)
-
Steve Winston, Holochip (version 1.3)
-
Stuart Smith, AMD (versions 1.0, 1.1, 1.2, 1.3)
-
Sujeevan Rajayogam, Google (version 1.3)
-
Tilmann Scheller, Samsung Electronics (version 1.1)
-
Tim Foley, Intel (version 1.0)
-
Tim Lewis, Khronos (version 1.3)
-
Timo Suoranta, AMD (version 1.0)
-
Timothy Lottes, AMD (versions 1.0, 1.1)
-
Tobias Hector, AMD (versions 1.0, 1.1, 1.2, 1.3) (validity language and toolchain)
-
Tobin Ehlis, LunarG (version 1.0)
-
Tom Olson, Arm (versions 1.0, 1.1, 1.2, 1.3) (Working Group chair)
-
Tomasz Bednarz, Independent (version 1.1)
-
Tomasz Kubale, Intel (version 1.0)
-
Tony Barbour, LunarG (versions 1.0, 1.1, 1.2)
-
Tony Zlatinski, NVIDIA (version 1.3)
-
Victor Eruhimov, Unknown (version 1.1)
-
Vikram Kushwaha, NVIDIA (version 1.3)
-
Vincent Hindriksen, Stream HPC (versions 1.2, 1.3)
-
Wasim Abbas, Arm (version 1.3)
-
Wayne Lister, Imagination Technologies (version 1.0)
-
Wolfgang Engel, Unknown (version 1.1)
-
Yanjun Zhang, VeriSilicon (versions 1.0, 1.1, 1.2, 1.3)
-
Yunxing Zhu, Huawei (version 1.3)
Other Credits
The Vulkan Advisory Panel members provided important real-world usage information and advice that helped guide design decisions.
The wider Vulkan community have provided useful feedback, questions and specification changes that have helped improve the quality of the Specification via GitHub.
Administrative support to the Working Group for Vulkan 1.1, 1.2, and 1.3 was provided by Khronos staff including Ann Thorsnes, Blaine Kohl, Dominic Agoro-Ombaka, Emily Stearns, Jeff Phillips, Lisie Aartsen, Liz Maitral, Marty Johnson, Tim Lewis, and Xiao-Yu CHENG; and by Alex Crabb, Laura Shubel, and Rachel Bradshaw of Caster Communications.
Administrative support for Vulkan 1.0 was provided by Andrew Riegel, Elizabeth Riegel, Glenn Fredericks, Kathleen Mattson and Michelle Clark of Gold Standard Group.
Technical support was provided by James Riordon, site administration of Khronos.org and OpenGL.org.