1. Preamble
Copyright 2014-2025 The Khronos Group Inc.
This Specification is protected by copyright laws and contains material proprietary to Khronos. Except as described by these terms, it or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos.
Khronos grants a conditional copyright license to use and reproduce the unmodified Specification for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are granted under these terms.
Khronos makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this Specification, including, without limitation: merchantability, fitness for a particular purpose, non-infringement of any intellectual property, correctness, accuracy, completeness, timeliness, and reliability. Under no circumstances will Khronos, or any of its Promoters, Contributors or Members, or their respective partners, officers, directors, employees, agents or representatives be liable for any damages, whether direct, indirect, special or consequential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials.
This document contains extensions which are not ratified by Khronos, and as such is not a ratified Specification, though it contains text from (and is a superset of) the ratified Specification.
The ratified version of the Vulkan Specification can be found at https://registry.khronos.org/vulkan/specs/latest-ratified/pdf/vkspec.pdf (core with all ratified extensions).
This Specification contains substantially unmodified functionality from, and is a successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL.
The Khronos Intellectual Property Rights Policy defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'.
Some parts of this Specification are purely informative and so are EXCLUDED the Scope of this Specification. The Document Conventions section of the Introduction defines how these parts of the Specification are identified.
Where this Specification uses technical terminology, defined in the Glossary or otherwise, that refer to enabling technologies that are not expressly set forth in this Specification, those enabling technologies are EXCLUDED from the Scope of this Specification. For clarity, enabling technologies not disclosed with particularity in this Specification (e.g. semiconductor manufacturing technology, hardware architecture, processor architecture or microarchitecture, memory architecture, compiler technology, object oriented technology, basic operating system technology, compression technology, algorithms, and so on) are NOT to be considered expressly set forth; only those application program interfaces and data structures disclosed with particularity are included in the Scope of this Specification.
For purposes of the Khronos Intellectual Property Rights Policy as it relates to the definition of Necessary Patent Claims, all recommended or optional features, behaviors and functionality set forth in this Specification, if implemented, are considered to be included as Compliant Portions.
Where this Specification identifies specific sections of external references, only those specifically identified sections define normative functionality. The Khronos Intellectual Property Rights Policy excludes external references to materials and associated enabling technology not created by Khronos from the Scope of this Specification, and any licenses that may be required to implement such referenced materials and associated technologies must be obtained separately and may involve royalty payments.
Khronos and Vulkan are registered trademarks, and SPIR-V is a trademark of The Khronos Group Inc. OpenCL is a trademark of Apple Inc., used under license by Khronos. OpenGL is a registered trademark and the OpenGL ES logo is a trademark of Hewlett Packard Enterprise, used under license by Khronos. ASTC is a trademark of ARM Holdings PLC. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners.
2. Introduction
This document, referred to as the “Vulkan Specification” or just the “Specification” hereafter, describes the Vulkan Application Programming Interface (API). Vulkan is a C99 API designed for explicit control of low-level graphics and compute functionality.
The canonical version of the Specification is available in the official Vulkan Registry (https://registry.khronos.org/vulkan/). The source files used to generate the Vulkan specification are stored in the Vulkan Documentation Repository (https://github.com/KhronosGroup/Vulkan-Docs).
The source repository additionally has a public issue tracker and allows the submission of pull requests that improve the specification.
2.1. Document Conventions
The Vulkan specification is intended for use by both implementors of the API and application developers seeking to make use of the API, forming a contract between these parties. Specification text may address either party; typically the intended audience can be inferred from context, though some sections are defined to address only one of these parties. (For example, Valid Usage sections only address application developers). Any requirements, prohibitions, recommendations or options defined in specification text are imposed only on the audience of that text.
2.1.1. Normative Requirements
The Vulkan Specification uses a combination of normative terminology and normative descriptions to express the requirements that it imposes on applications and implementations. An application which complies with all normative requirements imposed on applications is said to make valid use of the API; failing to comply with such requirements results in undefined behavior, as discussed in the Valid Usage section below. In the context of this document, an implementation which complies with all normative requirements imposed on implementations is said to be conformant.
|
Note
|
The Khronos Group imposes additional requirements on implementors who wish to make public statements describing their Vulkan implementations as conformant. These include signing the Vulkan Adopter’s Agreement, paying the associated fee, and making a successful conformance test submission to the Khronos Conformance Process. For details see the Khronos Trademark Guidelines (https://www.khronos.org/legal/khronos-trademark-guidelines). |
Normative Terminology
Within this specification, the key words must, required, should, 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 to indicate that they are being used in a specific technical sense.
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 refers to something the API provides no way for the application to express or accomplish. Must not describes something that the application is able to express, but that is not valid use of the API, and will have undefined and potentially unrecoverable consequences. |
Normative Descriptions
In the Vulkan Specification, the normative term must is primarily used to describe application behavior, and in particular to constrain what inputs or commands issued by the application to the implementation are considered valid.
To constrain implementation behavior, the specification sometimes uses
must, but more often simply describes the behavior of the implementation in
response to specified commands and inputs.
Unless explicitly stated otherwise, such references to implementation
behavior describe the behavior of conformant implementations, and express
normative requirements which an implementation must satisfy in order to
conform to the specification.
For example, if the specification says “Under specified condition, the
error code VK_ERROR_FEATURE_NOT_PRESENT is returned”, that behavior
is a requirement of the specification, and an implementation which does not
return that error code under that condition is not conformant.
When the normative terms may, should, or optional are used to describe implementation behavior, they define alternative or optional behaviors which a conformant implementation may or may not exhibit. Such statements are also normative. For example, if the specification says "Under specified condition, the implementation should return A but may instead return B", then an implementation that returns either A or B under that condition is conformant (assuming it does not violate other normative requirements), while an implementation that returns anything else is not.
2.1.2. Normative References
References to external documents are considered normative references if the Specification uses normative terminology or normative descriptions to refer to them or their requirements, either as a whole or in part.
The following documents are referenced by normative sections of the specification:
IEEE. August, 2008. IEEE Standard for Floating-Point Arithmetic. IEEE Std 754-2008. https://dx.doi.org/10.1109/IEEESTD.2008.4610935 .
Andrew Garrard. Khronos Data Format Specification, version 1.3. https://registry.khronos.org/DataFormat/specs/1.3/dataformat.1.3.html .
John Kessenich. SPIR-V Extended Instructions for GLSL, Version 1.00 (February 10, 2016). https://registry.khronos.org/spir-v/ .
John Kessenich, Boaz Ouriel, and Raun Krisch. SPIR-V Specification, Version 1.5, Revision 3, Unified (April 24, 2020). https://registry.khronos.org/spir-v/ .
ITU-T. H.264 Advanced Video Coding for Generic Audiovisual Services (August, 2021). https://www.itu.int/rec/T-REC-H.264-202108-I/ .
ITU-T. H.265 High Efficiency Video Coding (August, 2021). https://www.itu.int/rec/T-REC-H.265-202108-S/ .
Google. VP9 Bitstream & Decoding Process Specification (February 22, 2017). https://storage.googleapis.com/downloads.webmproject.org/docs/vp9/vp9-bitstream-specification-v0.7-20170222-draft.pdf .
Alliance for Open Media. AV1 Bitstream & Decoding Process Specification (January 8, 2019). https://aomediacodec.github.io/av1-spec/av1-spec.pdf .
Jon Leech. The Khronos Vulkan API Registry (February 26, 2023). https://registry.khronos.org/vulkan/specs/latest/registry.html .
Jon Leech and Tobias Hector. Vulkan Documentation and Extensions: Procedures and Conventions (February 26, 2023). https://registry.khronos.org/vulkan/specs/latest/styleguide.html .
Architecture of the Vulkan Loader Interfaces (October, 2021). https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderInterfaceArchitecture.md .
2.1.3. Informative Language
Some language in the specification is purely informative, intended to provide background information or make suggestions to implementors or developers. Such language does not impose normative requirements on implementations or applications.
All NOTEs are implicitly informative.
If an entire chapter, section, or appendix contains only informative language, its title will be suffixed with “(Informative)”. Unless so noted in the title, all chapters, sections, and appendices in this document are normative.
2.1.4. Technical Terminology
The Vulkan Specification makes use of common engineering and graphics terms such as Pipeline, Shader, and Host to identify and describe Vulkan API constructs and their attributes, states, and behaviors. The Glossary defines the basic meanings of these terms in the context of the Specification. The Specification text provides fuller definitions of the terms and may elaborate, extend, or clarify the Glossary definitions. When a term defined in the Glossary is used in normative language within the Specification, the definitions within the Specification govern and supersede any meanings the terms may have in other technical contexts (i.e. outside the Specification).
2.1.5. Ratification
Ratification of a Vulkan core version or extension is a status conferred by vote of the Khronos Board of Promoters, bringing that core version or extension under the umbrella of the Khronos IP Rights Policy.
All Vulkan core versions and KHR extensions (including provisional
specifications) are ratified, as are some multi-vendor EXT extensions.
Ratification status of extensions is described in the Layers &
Extensions (Informative) appendix.
|
Note
|
Ratification status is primarily of interest to IHVs developing GPU hardware and Vulkan implementations. For developers, ratification does not necessarily mean that an extension is “better”, has a more stable API, or is more widely supported than alternative ways of achieving that functionality. Interactions between ratified and non-ratified extensions are not themselves ratified. |
3. Fundamentals
This chapter introduces fundamental concepts including the Vulkan architecture and execution model, API syntax, queues, pipeline configurations, numeric representation, state and state queries, and the different types of objects and shaders. It provides a framework for interpreting more specific descriptions of commands and behavior in the remainder of the Specification.
3.1. Host and Device Environment
The Vulkan Specification assumes and requires: the following properties of the host environment with respect to Vulkan implementations:
-
The host must have runtime support for 8, 16, 32 and 64-bit signed and unsigned twos-complement integers, all addressable at the granularity of their size in bytes.
-
The host must have runtime support for 32- and 64-bit floating-point types satisfying the range and precision constraints in the Floating-Point Computation section.
-
The representation and endianness of these types on the host must match the representation and endianness of the same types on every physical device supported.
|
Note
|
Since a variety of data types and structures in Vulkan may be accessible by both host and physical device operations, the implementation should be able to access such data efficiently in both paths in order to facilitate writing portable and performant applications. |
3.2. Execution Model
This section outlines the execution model of a Vulkan system.
Vulkan exposes one or more devices, each of which exposes one or more queues which may process work asynchronously to one another. The set of queues supported by a device is partitioned into families. Each family supports one or more types of functionality and may contain multiple queues with similar characteristics. Queues within a single family are considered compatible with one another, and work produced for a family of queues can be executed on any queue within that family. This specification defines the following types of functionality that queues may support: graphics, compute, video decode, video encode, protected memory management, sparse memory management, and transfer.
|
Note
|
A single device may report multiple similar queue families rather than, or as well as, reporting multiple members of one or more of those families. This indicates that while members of those families have similar capabilities, they are not directly compatible with one another. |
Device memory is explicitly managed by the application. Each device may advertise one or more heaps, representing different areas of memory. Memory heaps are either device-local or host-local, but are always visible to the device. Further detail about memory heaps is exposed via memory types available on that heap. Examples of memory areas that may be available on an implementation include:
-
device-local is memory that is physically connected to the device.
-
device-local, host visible is device-local memory that is visible to the host.
-
host-local, host visible is memory that is local to the host and visible to the device and host.
On other architectures, there may only be a single heap that can be used for any purpose.
3.2.1. Queue Operation
Vulkan queues provide an interface to the execution engines of a device. Commands for these execution engines are recorded into command buffers ahead of execution time, and then submitted to a queue for execution. Once submitted to a queue, command buffers will begin and complete execution without further application intervention, though the order of this execution is dependent on a number of implicit and explicit ordering constraints.
Work is submitted to queues using queue submission commands that typically
take the form vkQueue* (e.g. vkQueueSubmit
, vkQueueBindSparse
), and can take a list of semaphores upon which to wait before work begins
and a list of semaphores to signal once work has completed.
The work itself, as well as signaling and waiting on the semaphores are all
queue operations.
Queue submission commands return control to the application once queue
operations have been submitted - they do not wait for completion.
There are no implicit ordering constraints between queue operations on different queues, or between queues and the host, so these may operate in any order with respect to each other. Explicit ordering constraints between different queues or with the host can be expressed with semaphores and fences.
Command buffer submissions to a single queue respect submission order and other implicit ordering guarantees, but otherwise may overlap or execute out of order. Other types of batches and queue submissions against a single queue (e.g. sparse memory binding) have no implicit ordering constraints with any other queue submission or batch. Additional explicit ordering constraints between queue submissions and individual batches can be expressed with semaphores and fences.
Before a fence or semaphore is signaled, it is guaranteed that any previously submitted queue operations have completed execution, and that memory writes from those queue operations are available to future queue operations. Waiting on a signaled semaphore or fence guarantees that previous writes that are available are also visible to subsequent commands.
Command buffer boundaries, both between primary command buffers of the same or different batches or submissions as well as between primary and secondary command buffers, do not introduce any additional ordering constraints. In other words, submitting the set of command buffers (which can include executing secondary command buffers) between any semaphore or fence operations execute the recorded commands as if they had all been recorded into a single primary command buffer, except that the current state is reset on each boundary. Explicit ordering constraints can be expressed with explicit synchronization primitives.
There are a few implicit ordering guarantees between commands within a command buffer, but only covering a subset of execution. Additional explicit ordering constraints can be expressed with the various explicit synchronization primitives.
|
Note
|
Implementations have significant freedom to overlap execution of work submitted to a queue, and this is common due to deep pipelining and parallelism in Vulkan devices. |
Commands recorded in command buffers can perform actions, set state that persists across commands, synchronize other commands, or indirectly launch other commands, with some commands fulfilling several of these roles. The “Command Properties” section for each such command lists which of these roles the command takes:
- Action
-
Action commands perform operations that can update values in memory. E.g. draw commands, dispatch commands.
- State
-
State setting commands update the current state of a command buffer, affecting the operation of future action commands.
- Synchronization
-
Synchronization commands impose ordering constraints on action commands, by introducing explicit execution and memory dependencies.
- Indirection
-
Indirection commands execute other commands which were not directly recorded in the same command buffer.
|
Note
|
In the absence of explicit synchronization or implicit ordering guarantees, action commands may overlap execution or execute out of order, potentially leading to data races. However, such reordering does not affect the current state observed by any action command. Each action command uses the state in effect at the point where the command occurs in the command buffer, regardless of when it is executed. |
3.3. Object Model
The devices, queues, and other entities in Vulkan are represented by Vulkan objects. At the API level, all objects are referred to by handles. There are two classes of handles, dispatchable and non-dispatchable. Dispatchable handle types are a pointer to an opaque type. This pointer may be used by layers as part of intercepting API commands, and thus each API command takes a dispatchable type as its first parameter. Each object of a dispatchable type must have a unique handle value during its lifetime.
Non-dispatchable handle types are a 64-bit integer type whose meaning is
implementation-dependent.
If the privateData feature is enabled for a
VkDevice, each object of a non-dispatchable type created on that
device must have a handle value that is unique among objects created on
that device, for the duration of the object’s lifetime.
Otherwise, non-dispatchable
handles may encode object information directly in the handle rather than
acting as a reference to an underlying object, and thus may not have unique
handle values.
If handle values are not unique, then destroying one such handle must not
cause identical handles of other types to become invalid, and must not
cause identical handles of the same type to become invalid if that handle
value has been created more times than it has been destroyed.
All objects created or allocated from a VkDevice (i.e. with a
VkDevice as the first parameter) are private to that device, and must
not be used on other devices.
3.3.1. Object Lifetime
Objects are created or allocated by vkCreate* and vkAllocate*
commands, respectively.
Once an object is created or allocated, its “structure” is considered to
be immutable, though the content of certain object types is still free to
change.
When an object is passed to another command, it may be accessed by the
implementation, which may include both read and write access unless
explicitly stated otherwise.
Objects are destroyed or freed by vkDestroy* and vkFree*
commands, respectively.
Objects that are allocated (rather than created) take resources from an existing pool object or memory heap, and when freed return resources to that pool or heap. While object creation and destruction are generally expected to be low-frequency occurrences during runtime, allocating and freeing objects can occur at high frequency. Pool objects help accommodate improved performance of the allocations and frees.
Applications are responsible for managing the lifetimes of Vulkan objects and memory passed into the Vulkan API. The access semantics of different functions in the API follow a typical pattern as laid out below, with any exceptions listed with the commands or objects that have them.
Application-owned memory and Vulkan objects may be accessed at any time
during the execution of a command they are passed to.
Vulkan objects that device addresses are retrieved from may be accessed by
the implementation any time that memory backing the device address is
accessed.
Device addresses and
Vulkan objects passed in during the creation or allocation of another object
may be accessed by the implementation any time that the created/allocated
object is accessed unless explicitly stated otherwise.
Device addresses and
Vulkan objects passed to a recording command (vkCmd*) may be accessed
at any time during the execution of the command, when the command buffer is
subsequently recorded into another command buffer, during any subsequent
command that is recorded to either the command buffer or one it is recorded
into, or while the command buffer is in the pending state, unless explicitly stated otherwise.
If an application is using deferred host
operations in a command, and that operation is successfully deferred,
objects and memory passed to that command may be accessed at any time until
the deferred operation is complete.
Some additional operations hold references to other objects or
application-owned memory beyond the duration of the command; in which case
the access semantics and lifetime of those references are described by that
command.
When destroying or freeing an object, implementations must not access any memory or other objects that may otherwise be accessed when the object is accessed. Applications can free or destroy objects in any order, except that parent objects must be freed only after all child objects are freed. An object is the parent of another child object if the parent was used as the first object parameter in the creation of the child. Once an object is freed or destroyed it must not be accessed again, either directly or via access through another object. Applications must not free or destroy any object while it is being accessed.
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 a non-NULL value, in which case
allocations for the given object are delegated to an application provided
callback.
Refer to the Memory Allocation chapter for further
details.
Commands that allocate Vulkan objects owned by pool objects are of the form
vkAllocate*, and take Vk*AllocateInfo structures.
These Vulkan objects are freed with commands of the form vkFree*.
These objects do not take allocators; if host memory is needed, they will
use the allocator that was specified when their parent pool was created.
Commands are recorded into a command buffer by calling API commands of the
form vkCmd*.
Each such command may have different restrictions on where it can be used:
in a primary and/or secondary command buffer, inside and/or outside a render
pass, and in one or more of the supported queue types.
These restrictions are documented together with the definition of each such
command.
The duration of a Vulkan command refers to the interval between calling the command and its return to the caller.
3.5.1. Lifetime of Retrieved Results
Information is retrieved from the implementation with commands of the form
vkGet* and vkEnumerate*.
Unless otherwise specified for an individual command, the results are invariant; that is, they will remain unchanged when retrieved again by calling the same command with the same parameters, so long as those parameters themselves all remain valid.
3.5.2. Array Results
Some query commands of the form vkGet* and vkEnumerate* enable
retrieving multiple results in the form of a return array.
Such commands typically have two pointer arguments as follows:
-
An element count pointer pointing to an integer variable, conventionally named as
p*Countwhere*is the capitalized singular form of the name of the retrieved values. -
A pointer to an array where the result array is retrieved, conventionally named as
p*where*is the capitalized plural form of the name of the retrieved values.
If such commands are called with the array pointer set to NULL, then the
number of retrievable elements is returned in the variable pointed to by the
element count pointer.
Otherwise, the element count pointer must point to a variable set by the
application to the number of elements in the return array, and on return the
variable is overwritten with the number of elements actually written to the
return array.
If the input element count is less than the number of retrievable array
elements, the query will write only as many elements to the return array as
specified by the element count variable set by the application, and the
command will return VK_INCOMPLETE instead of VK_SUCCESS, to
indicate that not all retrievable array elements were returned.
|
Note
|
In practice, this means that applications will typically call such query commands twice:
|
Query commands that return one or more structures, regardless of whether
they return a single or an array of structures with or without a pNext
chain, may also contain arrays within those structures.
Such return arrays are typically defined in the form of two members as
follows:
-
An integer value specifying the element count, conventionally named as
*Countwhere*is the singular form of the name of the retrieved values. -
A pointer to an array where the result array is retrieved, conventionally named as
p*where*is the capitalized plural form of the name of the retrieved values.
Analogously to query commands that return multiple results, if the command
is called with the array pointer member of the output structure in question
set to NULL, then the number of retrievable elements is returned in the
element count member of that output structure.
Otherwise, the element count must specify the number of elements in the
return array, and on return the element count member is overwritten with the
number of elements actually written to the return array.
If the input element count is less than the number of retrievable array
elements, the query will write only as many elements to the return array as
specified by the input element count, and the command will return
VK_INCOMPLETE instead of VK_SUCCESS, if the query command has a
VkResult return type, to indicate that not all retrievable array
elements were returned.
|
Note
|
Applications need to separately track the value they provided as the input element count member for such arrays and compare those with the returned element counts in order to determine whether the actually returned element count is smaller than the size of the return array. Another side effect of this is that it is impossible for the application to determine if the number of retrievable elements has increased beyond the provided input element count so using return arrays in output structures should be limited to invariant array results. In practice, this means that applications will typically call such query commands multiple times:
|
Regardless of the type of query command, any array pointer member of an
output structure must either be NULL, or point to an
application-allocated array.
Query commands must not return a pointer to implementation allocated
storage in any output structure.
3.5.3. Opaque Binary Data Results
Some query commands of the form vkGet* retrieve opaque binary data in
the form of a byte array and have a possible result code of
VK_ERROR_NOT_ENOUGH_SPACE_KHR.
Such commands always have two pointer arguments as follows:
-
A binary data size pointer pointing to a
size_tvariable, conventionally named asp*Sizewhere*is the capitalized form of the name of the retrieved binary data. -
A pointer to a byte array where the binary data is retrieved, conventionally named as
p*where*is the capitalized form of the name of the retrieved binary data.
If such commands are called with the binary pointer not set to NULL, the
binary size pointer must point to a variable set by the application to the
allocated size of the binary pointer.
If the input binary size is less than the total retrievable binary size, the
query will not write any data to the location pointed to the binary pointer,
and the command will return VK_ERROR_NOT_ENOUGH_SPACE_KHR instead of
VK_SUCCESS.
If the return code is VK_SUCCESS or
VK_ERROR_NOT_ENOUGH_SPACE_KHR, the total size of the binary data that
can be retrieved is returned in the variable pointed to by the binary size
pointer.
If multiple binaries are being retrieved,
VK_ERROR_NOT_ENOUGH_SPACE_KHR will be returned if any input binary
sizes are less than their respective total retrievable binary sizes.
Unless otherwise specified, this command will determine writing data to each
binary individually based on if their input binary sizes are sufficiently
sized, following the behavior for single binary retrieval.
For all other error codes, the contents of the return structures are undefined.
|
Note
|
If |
|
Note
|
Some binary queries do not behave consistently with this pattern for
historical reasons, primarily that the A NOTE is added to each such query, describing such inconsistent behavior. |
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. The implementation may not synchronize accesses to memory parameters or object parameters declared as externally synchronized with other accesses. If two commands access the same object or memory 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). Similarly, if a Vulkan command accesses a non-const memory parameter and the application also accesses that memory, or if the application writes to that memory and the command accesses it as a const memory parameter, the application must ensure the accesses are properly synchronized with a 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. |
Any object 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.
There are also a few instances where a command can take in an application-allocated list whose contents are externally synchronized parameters. In these cases, the caller must guarantee that at most one thread is using a given element within the list at a given time. These parameters are listed below.
In addition, there are some implicit parameters that need to be externally
synchronized.
For example, when a commandBuffer parameter needs to be externally
synchronized, it implies that the commandPool from which that command
buffer was allocated also needs to be externally synchronized.
The implicit parameters and their associated object are listed below.
3.7. Valid Usage
Valid usage defines a set of conditions which must be met in order to achieve well-defined runtime behavior in an application. These conditions depend only on Vulkan state, and the parameters or objects whose usage is constrained by the condition.
The core layer assumes applications are using the API correctly. Except as documented elsewhere in the Specification, the behavior of the core layer to an application using the API incorrectly is undefined, and may include program termination. However, implementations must ensure that incorrect usage by an application does not affect the integrity of the operating system, the Vulkan implementation, or other applications in the system using Vulkan. In particular, any guarantees made by an operating system about whether memory from one process can be visible to another process or not must not be violated by a Vulkan implementation for any memory allocation. Vulkan implementations are not required to make additional security or integrity guarantees beyond those provided by the OS unless explicitly directed by the application’s use of a particular feature or extension.
|
Note
|
For instance, if an operating system guarantees that data in all its memory allocations are set to zero when newly allocated, the Vulkan implementation must make the same guarantees for any allocations it controls (e.g. VkDeviceMemory). Similarly, if an operating system guarantees that use-after-free of host allocations will not result in values written by another process becoming visible, the same guarantees must be made by the Vulkan implementation for device memory. |
If the protectedMemory feature is
supported, the implementation provides additional guarantees when invalid
usage occurs to prevent values in protected memory from being accessed or
inferred outside of protected operations, as described in
Protected Memory Access Rules.
Some valid usage conditions have dependencies on runtime limits or feature availability. It is possible to validate these conditions against Vulkan’s minimum supported values for these limits and features, or some subset of other known values.
Valid usage conditions do not cover conditions where well-defined behavior (including returning an error code) exists.
Valid usage conditions should apply to the command or structure where complete information about the condition would be known during execution of an application. This is such that a validation layer or linter can be written directly against these statements at the point they are specified.
|
Note
|
This does lead to some non-obvious places for valid usage statements. For instance, the valid values for a structure might depend on a separate value in the calling command. In this case, the structure itself will not reference this valid usage as it is impossible to determine validity from the structure that it is invalid - instead this valid usage would be attached to the calling command. Another example is draw state - the state setters are independent, and can cause a legitimately invalid state configuration between draw calls; so the valid usage statements are attached to the place where all state needs to be valid - at the drawing command. |
Valid usage conditions are described in a block labeled “Valid Usage” following each command or structure they apply to.
3.7.1. Usage Validation
Vulkan is a layered API. The lowest layer is the core Vulkan layer, as defined by this Specification. The application can use additional layers above the core for debugging, validation, and other purposes.
One of the core principles of Vulkan is that building and submitting command buffers should be highly efficient. Thus error checking and validation of state in the core layer is minimal, although more rigorous validation can be enabled through the use of layers.
Validation of correct API usage is left to validation layers. Applications should be developed with validation layers enabled, to help catch and eliminate errors. Once validated, released applications should not enable validation layers by default.
3.7.2. Implicit Valid Usage
Some valid usage conditions apply to all commands and structures in the API, unless explicitly denoted otherwise for a specific command or structure. These conditions are considered implicit, and are described in a block labeled “Valid Usage (Implicit)” following each command or structure they apply to. Implicit valid usage conditions are described in detail below.
Valid Usage for Object Handles
Any input parameter to a command that is an object handle must be a valid object handle, unless otherwise specified. An object handle is valid if:
-
It has been created or allocated by a previous, successful call to the API. Such calls are noted in the Specification.
-
It has not been deleted or freed by a previous call to the API. Such calls are noted in the Specification.
-
Any objects used by that object, either as part of creation or execution, must also be valid.
The reserved values VK_NULL_HANDLE and NULL can be used in place of
valid non-dispatchable handles and dispatchable handles, respectively, when
explicitly called out in the Specification.
Any command that creates an object successfully must not return these
values.
It is valid to pass these values to vkDestroy* or vkFree*
commands, which will silently ignore these values.
Valid Usage for Pointers
Any parameter that is a pointer must be a valid pointer only if it is explicitly called out by a Valid Usage statement.
A pointer is “valid” if it points at memory containing values of the number and type(s) expected by the command, and all fundamental types accessed through the pointer (e.g. as elements of an array or as members of a structure) satisfy the alignment requirements of the host processor.
Valid Usage for Strings
Any parameter that is a pointer to char must be a finite sequence of
values terminated by a null character, or if explicitly called out in the
Specification, can be NULL.
Strings specified as UTF-8 encoded must not contain invalid UTF-8 sequences. See String Representation for additional information about strings.
Valid Usage for Enumerated Types
Any parameter of an enumerated type must be a valid enumerant for that type. Use of an enumerant is valid if the following conditions are true:
-
The enumerant is defined as part of the enumerated type.
-
The enumerant is not a value suffixed with
_MAX_ENUM.-
This value exists only to ensure that C
enumtypes are 32 bits in size and must not be used by applications.
-
-
If the enumerant is used in a function that has a VkInstance as its first parameter and either:
-
it was added by a core version that is supported (as reported by vkEnumerateInstanceVersion) and the value of VkApplicationInfo::
apiVersionis greater than or equal to the version that added it; or -
it was added by an instance extension that was enabled for the instance.
-
-
If the enumerant is used in a function that has a VkPhysicalDevice object as its first parameter and either:
-
it was added by a core version that is supported by that device (as reported by VkPhysicalDeviceProperties::
apiVersion); -
it was added by an instance extension that was enabled for the instance; or
-
it was added by a device extension that is supported by that device.
-
-
If the enumerant is used in a function that has any other dispatchable object as its first parameter and either:
-
it was added by a core version that is supported for the device (as reported by VkPhysicalDeviceProperties::
apiVersion); or -
it was added by a device extension that was enabled for the device.
-
Additionally, if the maintenance5 feature is
supported, any integer value representable in the range valid for the
defined type is valid when used in a function that has a
VkPhysicalDevice object as its first parameter.
Physical device queries will either return results indicating lack of
support, or ignore unsupported values when used as a bit flag in a
Vk*Flags* parameter.
Any enumerated type returned from a query command or otherwise output from Vulkan to the application must not have a reserved value. Reserved values are values not defined by any extension for that enumerated type.
|
Note
|
In some special cases, an enumerant is only meaningful if a feature defined by an extension is also enabled, as well as the extension itself. The global “valid enumerant” rule described here does not address such cases. |
|
Note
|
This language is intended to accommodate cases such as “hidden” extensions known only to driver internals, or layers enabling extensions without knowledge of the application, without allowing return of values not defined by any extension. |
|
Note
|
Application developers are encouraged to be careful when using This is particularly true for enums such as VkDriverId, which may have values added that do not belong to a corresponding new extension. |
Valid Usage for Flags
A collection of flags is represented by a bitmask using the type VkFlags:
// Provided by VK_VERSION_1_0
typedef uint32_t VkFlags;
Bitmasks are passed to many commands and structures to compactly represent
options, but VkFlags is not used directly in the API.
Instead, a Vk*Flags type which is an alias of VkFlags, and
whose name matches the corresponding Vk*FlagBits that are valid for
that type, is used.
Any Vk*Flags member or parameter used in the API as an input must be
a valid combination of bit flags.
A valid combination is either zero or the bitwise OR of valid bit flags.
An individual bit flag is valid for a Vk*Flags type if it would be a
valid enumerant when used with the
equivalent Vk*FlagBits type, where the bits type is obtained by taking
the flag type and replacing the trailing Flags with FlagBits.
For example, a flag value of type VkColorComponentFlags must contain
only bit flags defined by VkColorComponentFlagBits.
Any Vk*Flags member or parameter returned from a query command or
otherwise output from Vulkan to the application may contain bit flags
undefined in its corresponding Vk*FlagBits type.
An application cannot rely on the state of these unspecified bits.
Only the low-order 31 bits (bit positions zero through 30) are available for use as flag bits.
|
Note
|
This restriction is due to poorly defined behavior by C compilers given a C
enumerant value of |
A collection of 64-bit flags is represented by a bitmask using the type VkFlags64:
// Provided by VK_VERSION_1_3, VK_KHR_synchronization2
typedef uint64_t VkFlags64;
When the 31 bits available in VkFlags are insufficient, the
VkFlags64 type can be passed to commands and structures to
represent up to 64 options.
VkFlags64 is not used directly in the API.
Instead, a Vk*Flags2 type which is an alias of VkFlags64, and
whose name matches the corresponding Vk*FlagBits2 that are valid for
that type, is used.
Any Vk*Flags2 member or parameter used in the API as an input must be
a valid combination of bit flags.
A valid combination is either zero or the bitwise OR of valid bit flags.
An individual bit flag is valid for a Vk*Flags2 type if it would be a
valid enumerant when used with the
equivalent Vk*FlagBits2 type, where the bits type is obtained by
taking the flag type and replacing the trailing Flags2 with
FlagBits2.
For example, a flag value of type VkAccessFlags2KHR must contain only
bit flags defined by VkAccessFlagBits2KHR.
Any Vk*Flags2 member or parameter returned from a query command or
otherwise output from Vulkan to the application may contain bit flags
undefined in its corresponding Vk*FlagBits2 type.
An application cannot rely on the state of these unspecified bits.
|
Note
|
Both the |
Valid Usage for Structure Types
Any parameter that is a structure containing a sType member must have
a value of sType which is a valid VkStructureType value matching
the type of the structure.
Valid Usage for Structure Pointer Chains
Any parameter that is a structure containing a void* pNext member
must have a value of pNext that is either NULL, or is a pointer to
a valid extending structure, containing sType and pNext
members as described in the Vulkan Documentation and
Extensions document in the section “Extending Structures”.
The set of structures connected by pNext pointers is referred to as a
pNext chain.
Each structure included in the pNext chain must be defined at runtime
by either:
-
a core version which is supported
-
an extension which is enabled
-
a supported device extension in the case of physical-device-level functionality added by the device extension
Each type of extending structure must not appear more than once in a
pNext chain, including any
aliases.
This general rule may be explicitly overridden for specific structures.
Any component of the implementation (the loader, any enabled layers, and
drivers) must skip over, without processing (other than reading the
sType and pNext members) any extending structures in the chain
not defined by core versions or extensions supported by that component.
As a convenience to implementations and layers needing to iterate through a structure pointer chain, the Vulkan API provides two base structures. These structures allow for some type safety, and can be used by Vulkan API functions that operate on generic inputs and outputs.
The VkBaseInStructure structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBaseInStructure {
VkStructureType sType;
const struct VkBaseInStructure* pNext;
} VkBaseInStructure;
-
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 From Device Extensions are met.
Device-level functionality added by a device extension that is dispatched from a VkDevice, or from a child object of a VkDevice must not be used unless that extension is supported by the device as determined by vkEnumerateDeviceExtensionProperties, and that extension is enabled in VkDeviceCreateInfo.
Valid Usage for Newer Core Versions
Instance-level functionality or behavior added by a new core
version of the API must not be used unless it is supported by the
instance as determined by vkEnumerateInstanceVersion and the specified
version of VkApplicationInfo::apiVersion.
Physical-device-level functionality or behavior added by a new
core version of the API must not be used unless it is supported by the
physical device as determined by
VkPhysicalDeviceProperties::apiVersion and the specified version
of VkApplicationInfo::apiVersion.
Device-level functionality or behavior added by a new core
version of the API must not be used unless it is supported by the device
as determined by VkPhysicalDeviceProperties::apiVersion and the
specified version of VkApplicationInfo::apiVersion.
3.8. VkResult Return Codes
While the core Vulkan API is not designed to capture incorrect usage, some circumstances still require return codes. Commands in Vulkan return their status via return codes that are in one of two categories:
-
Successful completion codes are returned when a command needs to communicate success or status information. All successful completion codes are non-negative values.
-
Runtime error codes are returned when a command needs to communicate a failure that could only be detected at runtime. All runtime error codes are negative values.
All return codes in Vulkan are reported via VkResult return values. The possible codes are:
// Provided by VK_VERSION_1_0
typedef enum VkResult {
VK_SUCCESS = 0,
VK_NOT_READY = 1,
VK_TIMEOUT = 2,
VK_EVENT_SET = 3,
VK_EVENT_RESET = 4,
VK_INCOMPLETE = 5,
VK_ERROR_OUT_OF_HOST_MEMORY = -1,
VK_ERROR_OUT_OF_DEVICE_MEMORY = -2,
VK_ERROR_INITIALIZATION_FAILED = -3,
VK_ERROR_DEVICE_LOST = -4,
VK_ERROR_MEMORY_MAP_FAILED = -5,
VK_ERROR_LAYER_NOT_PRESENT = -6,
VK_ERROR_EXTENSION_NOT_PRESENT = -7,
VK_ERROR_FEATURE_NOT_PRESENT = -8,
VK_ERROR_INCOMPATIBLE_DRIVER = -9,
VK_ERROR_TOO_MANY_OBJECTS = -10,
VK_ERROR_FORMAT_NOT_SUPPORTED = -11,
VK_ERROR_FRAGMENTED_POOL = -12,
VK_ERROR_UNKNOWN = -13,
// Provided by VK_VERSION_1_1
VK_ERROR_OUT_OF_POOL_MEMORY = -1000069000,
// Provided by VK_VERSION_1_1
VK_ERROR_INVALID_EXTERNAL_HANDLE = -1000072003,
// Provided by VK_VERSION_1_2
VK_ERROR_FRAGMENTATION = -1000161000,
// Provided by VK_VERSION_1_2
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS = -1000257000,
// Provided by VK_VERSION_1_3
VK_PIPELINE_COMPILE_REQUIRED = 1000297000,
// Provided by VK_VERSION_1_4
VK_ERROR_NOT_PERMITTED = -1000174001,
// Provided by VK_KHR_surface
VK_ERROR_SURFACE_LOST_KHR = -1000000000,
// Provided by VK_KHR_surface
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR = -1000000001,
// Provided by VK_KHR_swapchain
VK_SUBOPTIMAL_KHR = 1000001003,
// Provided by VK_KHR_swapchain
VK_ERROR_OUT_OF_DATE_KHR = -1000001004,
// Provided by VK_KHR_display_swapchain
VK_ERROR_INCOMPATIBLE_DISPLAY_KHR = -1000003001,
// Provided by VK_EXT_debug_report
VK_ERROR_VALIDATION_FAILED_EXT = -1000011001,
// Provided by VK_NV_glsl_shader
VK_ERROR_INVALID_SHADER_NV = -1000012000,
// Provided by VK_KHR_video_queue
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR = -1000023000,
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_PICTURE_LAYOUT_NOT_SUPPORTED_KHR = -1000023001,
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_PROFILE_OPERATION_NOT_SUPPORTED_KHR = -1000023002,
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHR = -1000023003,
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHR = -1000023004,
// Provided by VK_KHR_video_queue
VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHR = -1000023005,
// Provided by VK_EXT_image_drm_format_modifier
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT = -1000158000,
// Provided by VK_EXT_full_screen_exclusive
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT = -1000255000,
// Provided by VK_KHR_deferred_host_operations
VK_THREAD_IDLE_KHR = 1000268000,
// Provided by VK_KHR_deferred_host_operations
VK_THREAD_DONE_KHR = 1000268001,
// Provided by VK_KHR_deferred_host_operations
VK_OPERATION_DEFERRED_KHR = 1000268002,
// Provided by VK_KHR_deferred_host_operations
VK_OPERATION_NOT_DEFERRED_KHR = 1000268003,
// Provided by VK_KHR_video_encode_queue
VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR = -1000299000,
// Provided by VK_EXT_image_compression_control
VK_ERROR_COMPRESSION_EXHAUSTED_EXT = -1000338000,
// Provided by VK_EXT_shader_object
VK_INCOMPATIBLE_SHADER_BINARY_EXT = 1000482000,
// Provided by VK_KHR_pipeline_binary
VK_PIPELINE_BINARY_MISSING_KHR = 1000483000,
// Provided by VK_KHR_pipeline_binary
VK_ERROR_NOT_ENOUGH_SPACE_KHR = -1000483000,
// Provided by VK_KHR_maintenance1
VK_ERROR_OUT_OF_POOL_MEMORY_KHR = VK_ERROR_OUT_OF_POOL_MEMORY,
// Provided by VK_KHR_external_memory
VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR = VK_ERROR_INVALID_EXTERNAL_HANDLE,
// Provided by VK_EXT_descriptor_indexing
VK_ERROR_FRAGMENTATION_EXT = VK_ERROR_FRAGMENTATION,
// Provided by VK_EXT_global_priority
VK_ERROR_NOT_PERMITTED_EXT = VK_ERROR_NOT_PERMITTED,
// Provided by VK_KHR_global_priority
VK_ERROR_NOT_PERMITTED_KHR = VK_ERROR_NOT_PERMITTED,
// Provided by VK_EXT_buffer_device_address
VK_ERROR_INVALID_DEVICE_ADDRESS_EXT = VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS,
// Provided by VK_KHR_buffer_device_address
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR = VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS,
// Provided by VK_EXT_pipeline_creation_cache_control
VK_PIPELINE_COMPILE_REQUIRED_EXT = VK_PIPELINE_COMPILE_REQUIRED,
// Provided by VK_EXT_pipeline_creation_cache_control
VK_ERROR_PIPELINE_COMPILE_REQUIRED_EXT = VK_PIPELINE_COMPILE_REQUIRED,
// Provided by VK_EXT_shader_object
// VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT is a deprecated alias
VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT = VK_INCOMPATIBLE_SHADER_BINARY_EXT,
} VkResult;
-
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_PIPELINE_BINARY_MISSING_KHRThe application attempted to create a pipeline binary by querying an internal cache, but the internal cache entry did not exist. -
VK_INCOMPATIBLE_SHADER_BINARY_EXTThe provided binary shader code is not compatible with this device.NoteIn the initial version of the
VK_EXT_shader_objectextension, this return code was namedVK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXTand improperly described as an error code. The name has been changed, but the old name is retained as an alias for compatibility with old code.
-
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 exclusive full-screen access. This may occur due to implementation-dependent reasons, outside of the application’s control. -
VK_ERROR_VALIDATION_FAILED_EXTA command failed because invalid usage was detected by the implementation or a validation-layer. -
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 VkVideoProfileInfoKHR::videoCodecOperationis not supported. -
VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHRFormat parameters in a requested VkVideoProfileInfoKHR chain are not supported. -
VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHRCodec-specific parameters in a requested VkVideoProfileInfoKHR chain are not supported. -
VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHRThe specified video Std header version is not supported. -
VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHRThe specified Video Std parameters do not adhere to the syntactic or semantic requirements of the used video compression standard, or values derived from parameters according to the rules defined by the used video compression standard do not adhere to the capabilities of the video compression standard or the implementation. -
VK_ERROR_NOT_PERMITTEDThe driver implementation has denied a request to acquire a priority above the default priority (VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) because the application does not have sufficient privileges. -
VK_ERROR_NOT_ENOUGH_SPACE_KHRThe application did not provide enough space to return all the required data. -
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
|
|
Any command returning a VkResult may return
VK_ERROR_VALIDATION_FAILED_EXT
if a violation of valid usage is detected, even though commands do not
explicitly list this as a possible return code.
Performance-critical commands generally do not have return codes.
If a runtime error occurs in such commands, the implementation will defer
reporting the error until a specified point.
For commands that record into command buffers (vkCmd*) runtime errors
are reported by vkEndCommandBuffer.
3.9. Numeric Representation and Computation
Implementations normally perform computations in floating-point, and must meet the range and precision requirements defined under “Floating-Point Computation” below.
These requirements only apply to computations performed in Vulkan operations outside of shader execution, such as texture image specification and sampling, and per-fragment operations. Range and precision requirements during shader execution differ and are specified by the Precision and Operation of SPIR-V Instructions section.
In some cases, the representation and/or precision of operations is implicitly limited by the specified format of vertex or texel data consumed by Vulkan. Specific floating-point formats are described later in this section.
3.9.1. Floating-Point Computation
Most floating-point computation is performed in SPIR-V shader modules. The properties of computation within shaders are constrained as defined by the Precision and Operation of SPIR-V Instructions section.
Some floating-point computation is performed outside of shaders, such as viewport and depth range calculations. For these computations, we do not specify how floating-point numbers are to be represented, or the details of how operations on them are performed, but only place minimal requirements on representation and precision as described in the remainder of this section.
We require simply that numbers’ floating-point parts contain enough bits and that their exponent fields are large enough so that individual results of floating-point operations are accurate to about 1 part in 105. The maximum representable magnitude for all floating-point values must be at least 232.
-
x × 0 = 0 × x = 0 for any non-infinite and non-NaN x.
-
1 × x = x × 1 = x.
-
x + 0 = 0 + x = x.
-
00 = 1.
Occasionally, further requirements will be specified. Most single-precision floating-point formats meet these requirements.
The special values Inf and -Inf encode values with magnitudes too large to be represented; the special value NaN encodes “Not A Number” values resulting from undefined arithmetic operations such as 0 / 0. Implementations may support Inf and NaN in their floating-point computations. Any computation which does not support either Inf or NaN, for which that value is an input or output will yield an undefined value.
3.9.2. Floating-Point Format Conversions
When a value is converted to a defined floating-point representation, finite values falling between two representable finite values are rounded to one or the other. The rounding mode is not defined. Finite values whose magnitude is larger than that of any representable finite value may be rounded either to the closest representable finite value or to the appropriately signed infinity. For unsigned destination formats any negative values are converted to zero. Positive infinity is converted to positive infinity; negative infinity is converted to negative infinity in signed formats and to zero in unsigned formats; and any NaN is converted to a NaN.
3.9.3. 16-Bit Floating-Point Numbers
16-bit floating-point numbers are defined in the “16-bit floating-point numbers” section of the Khronos Data Format Specification.
3.9.4. Unsigned 11-Bit Floating-Point Numbers
Unsigned 11-bit floating-point numbers are defined in the “Unsigned 11-bit floating-point numbers” section of the Khronos Data Format Specification.
3.9.5. Unsigned 10-Bit Floating-Point Numbers
Unsigned 10-bit floating-point numbers are defined in the “Unsigned 10-bit floating-point numbers” section of the Khronos Data Format Specification.
3.9.6. 8-bit booleans
An 8-bit boolean uses the following representation for true and false:
-
Zero to represent
false -
Any non-zero value to represent
true
3.9.7. General Requirements
Any representable floating-point value in the appropriate format is legal as input to a Vulkan command that requires floating-point data. The result of providing a value that is not a floating-point number to such a command is unspecified, but must not lead to Vulkan interruption or termination. For example, providing a negative zero (where applicable) or a denormalized number to a Vulkan command must yield deterministic results, while providing a NaN or Inf yields unspecified results.
Some calculations require division. In such cases (including implied divisions performed by vector normalization), division by zero produces an unspecified result but must not lead to Vulkan interruption or termination.
3.10. Fixed-Point Data Conversions
When generic vertex attributes and pixel color or depth components are represented as integers, they are often (but not always) considered to be normalized. Normalized integer values are treated specially when being converted to and from floating-point values, and are usually referred to as normalized fixed-point.
In the remainder of this section, b denotes the bit width of the fixed-point integer representation. When the integer is one of the types defined by the API, b is the bit width of that type. When the integer comes from an image containing color or depth component texels, b is the number of bits allocated to that component in its specified image format.
The signed and unsigned fixed-point representations are assumed to be b-bit binary two’s-complement integers and binary unsigned integers, respectively.
3.10.1. Conversion From Normalized Fixed-Point to Floating-Point
Unsigned normalized fixed-point integers represent numbers in the range [0,1]. The conversion from an unsigned normalized fixed-point value c to the corresponding floating-point value f is defined as
Signed normalized fixed-point integers represent numbers in the range [-1,1]. The conversion from a signed normalized fixed-point value c to the corresponding floating-point value f is performed using
Only the range [-2b-1 + 1, 2b-1 - 1] is used to represent signed fixed-point values in the range [-1,1]. For example, if b = 8, then the integer value -127 corresponds to -1.0 and the value 127 corresponds to 1.0. This equation is used everywhere that signed normalized fixed-point values are converted to floating-point.
Note that while zero is exactly expressible in this representation, one value (-128 in the example) is outside the representable range, and implementations must clamp it to -1.0. Where the value is subject to further processing by the implementation, e.g. during texture filtering, values less than -1.0 may be used but the result must be clamped before the value is returned to shaders.
3.10.2. Conversion From Floating-Point to Normalized Fixed-Point
The conversion from a floating-point value f to the corresponding unsigned normalized fixed-point value c is defined by first clamping f to the range [0,1], then computing
-
c = convertFloatToUint(f × (2b - 1), b)
where convertFloatToUint(r,b) returns one of the two unsigned binary integer values with exactly b bits which are closest to the floating-point value r. Implementations should round to nearest. If r is equal to an integer, then that integer value must be returned. In particular, if f is equal to 0.0 or 1.0, then c must be assigned 0 or 2b - 1, respectively.
The conversion from a floating-point value f to the corresponding signed normalized fixed-point value c is performed by clamping f to the range [-1,1], then computing
-
c = convertFloatToInt(f × (2b-1 - 1), b)
where convertFloatToInt(r,b) returns one of the two signed two’s-complement binary integer values with exactly b bits which are closest to the floating-point value r. Implementations should round to nearest. If r is equal to an integer, then that integer value must be returned. In particular, if f is equal to -1.0, 0.0, or 1.0, then c must be assigned -(2b-1 - 1), 0, or 2b-1 - 1, respectively.
This equation is used everywhere that floating-point values are converted to signed normalized fixed-point.
3.11. String Representation
Strings passed into and returned from Vulkan API commands are usually defined to be null-terminated and UTF-8 encoded.
|
Note
|
Exceptions to this rule exist only when strings are defined or used by
operating system APIs where that OS has a different convention.
For example, VkExportMemoryWin32HandleInfoKHR:: |
When a UTF-8 string is returned from a Vulkan API query, it is returned in
a fixed-length buffer of C char.
For example, a string returned in
VkPhysicalDeviceProperties::deviceName has maximum length
VK_MAX_PHYSICAL_DEVICE_NAME_SIZE, and a string returned in
VkExtensionProperties::extensionName has maximum length
VK_MAX_EXTENSION_NAME_SIZE.
The string, including its null terminator, will always fit completely
within this buffer.
If the string is shorter than the buffer size, the contents of char in
the buffer following the null terminator are undefined.
When a UTF-8 string is passed into a Vulkan API, such as
VkDeviceCreateInfo::ppEnabledExtensionNames, there is no
explicit limit on the length of that string.
However, the string must contain a valid UTF-8 encoded string and must be
null-terminated.
3.12. Common Object Types
Some types of Vulkan objects are used in many different structures and command parameters, and are described here. These types include offsets, extents, and rectangles.
3.12.1. Offsets
Offsets are used to describe a pixel location within an image or framebuffer, as an (x,y) location for two-dimensional images, or an (x,y,z) location for three-dimensional images.
A two-dimensional offset is defined by the structure:
// Provided by VK_VERSION_1_0
typedef struct VkOffset2D {
int32_t x;
int32_t y;
} VkOffset2D;
-
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.12.2. Extents
Extents are used to describe the size of a rectangular region of pixels within an image or framebuffer, as (width,height) for two-dimensional images, or as (width,height,depth) for three-dimensional images.
A two-dimensional extent is defined by the structure:
// Provided by VK_VERSION_1_0
typedef struct VkExtent2D {
uint32_t width;
uint32_t height;
} VkExtent2D;
-
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.12.3. Rectangles
Rectangles are used to describe a specified rectangular region of pixels within an image or framebuffer. Rectangles include both an offset and an extent of the same dimensionality, as described above. Two-dimensional rectangles are defined by the structure
// Provided by VK_VERSION_1_0
typedef struct VkRect2D {
VkOffset2D offset;
VkExtent2D extent;
} VkRect2D;
-
offsetis a VkOffset2D specifying the rectangle offset. -
extentis a VkExtent2D specifying the rectangle extent.
3.12.4. Structure Types
Each value corresponds to a particular structure with a sType member
with a matching name.
As a general rule, the name of each VkStructureType value is obtained
by taking the name of the structure, stripping the leading Vk,
prefixing each capital letter with _, converting the entire resulting
string to upper case, and prefixing it with VK_STRUCTURE_TYPE_.
For example, structures of type VkImageCreateInfo correspond to a
VkStructureType value of VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO,
and thus a structure of this type must have its sType member set to
this value before it is passed to the API.
The values VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO and
VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO are reserved for internal
use by the loader, and do not have corresponding Vulkan structures in this
Specification.
Structure types supported by the Vulkan API include:
// Provided by VK_VERSION_1_0
typedef enum VkStructureType {
VK_STRUCTURE_TYPE_APPLICATION_INFO = 0,
VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO = 1,
VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO = 2,
VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO = 3,
VK_STRUCTURE_TYPE_SUBMIT_INFO = 4,
VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO = 5,
VK_STRUCTURE_TYPE_MAPPED_MEMORY_RANGE = 6,
VK_STRUCTURE_TYPE_BIND_SPARSE_INFO = 7,
VK_STRUCTURE_TYPE_FENCE_CREATE_INFO = 8,
VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO = 9,
VK_STRUCTURE_TYPE_EVENT_CREATE_INFO = 10,
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO = 11,
VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO = 12,
VK_STRUCTURE_TYPE_BUFFER_VIEW_CREATE_INFO = 13,
VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO = 14,
VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO = 15,
VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO = 16,
VK_STRUCTURE_TYPE_PIPELINE_CACHE_CREATE_INFO = 17,
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO = 18,
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO = 19,
VK_STRUCTURE_TYPE_PIPELINE_INPUT_ASSEMBLY_STATE_CREATE_INFO = 20,
VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_STATE_CREATE_INFO = 21,
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO = 22,
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO = 23,
VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO = 24,
VK_STRUCTURE_TYPE_PIPELINE_DEPTH_STENCIL_STATE_CREATE_INFO = 25,
VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO = 26,
VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO = 27,
VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO = 28,
VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO = 29,
VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO = 30,
VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO = 31,
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO = 32,
VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO = 33,
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO = 34,
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET = 35,
VK_STRUCTURE_TYPE_COPY_DESCRIPTOR_SET = 36,
VK_STRUCTURE_TYPE_FRAMEBUFFER_CREATE_INFO = 37,
VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO = 38,
VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO = 39,
VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO = 40,
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_INFO = 41,
VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO = 42,
VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO = 43,
VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER = 44,
VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER = 45,
VK_STRUCTURE_TYPE_MEMORY_BARRIER = 46,
VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO = 47,
VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO = 48,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_PROPERTIES = 1000094000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO = 1000157000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO = 1000157001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES = 1000083000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS = 1000127000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO = 1000127001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO = 1000060000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO = 1000060003,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO = 1000060004,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO = 1000060005,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO = 1000060006,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO = 1000060013,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO = 1000060014,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES = 1000070000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO = 1000070001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2 = 1000146000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2 = 1000146001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2 = 1000146002,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2 = 1000146003,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2 = 1000146004,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2 = 1000059000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2 = 1000059001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2 = 1000059002,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2 = 1000059003,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2 = 1000059004,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2 = 1000059005,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PROPERTIES_2 = 1000059006,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2 = 1000059007,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2 = 1000059008,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES = 1000117000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO = 1000117001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO = 1000117002,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO = 1000117003,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO = 1000053000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES = 1000053001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PROPERTIES = 1000053002,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES = 1000120000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PROTECTED_SUBMIT_INFO = 1000145000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROTECTED_MEMORY_FEATURES = 1000145001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROTECTED_MEMORY_PROPERTIES = 1000145002,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_DEVICE_QUEUE_INFO_2 = 1000145003,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO = 1000156000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO = 1000156001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO = 1000156002,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO = 1000156003,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES = 1000156004,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_IMAGE_FORMAT_PROPERTIES = 1000156005,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO = 1000085000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO = 1000071000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES = 1000071001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO = 1000071002,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES = 1000071003,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ID_PROPERTIES = 1000071004,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO = 1000072000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO = 1000072001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO = 1000072002,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO = 1000112000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES = 1000112001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO = 1000113000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_CREATE_INFO = 1000077000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO = 1000076000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES = 1000076001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_3_PROPERTIES = 1000168000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_SUPPORT = 1000168001,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETERS_FEATURES = 1000063000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_FEATURES = 49,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_PROPERTIES = 50,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES = 51,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_PROPERTIES = 52,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO = 1000147000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2 = 1000109000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2 = 1000109001,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2 = 1000109002,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2 = 1000109003,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2 = 1000109004,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO = 1000109005,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_SUBPASS_END_INFO = 1000109006,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES = 1000177000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES = 1000196000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES = 1000180000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES = 1000082000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES = 1000197000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO = 1000161000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES = 1000161001,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_PROPERTIES = 1000161002,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_ALLOCATE_INFO = 1000161003,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_LAYOUT_SUPPORT = 1000161004,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES = 1000199000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE = 1000199001,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES = 1000221000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO = 1000246000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES = 1000130000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO = 1000130001,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES = 1000211000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES = 1000108000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO = 1000108001,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO = 1000108002,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO = 1000108003,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES = 1000253000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES = 1000175000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES = 1000241000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT = 1000241001,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT = 1000241002,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES = 1000261000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES = 1000207000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES = 1000207001,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO = 1000207002,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO = 1000207003,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO = 1000207004,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO = 1000207005,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES = 1000257000,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO = 1000244001,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO = 1000257002,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO = 1000257003,
// Provided by VK_VERSION_1_2
VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO = 1000257004,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES = 53,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_PROPERTIES = 54,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO = 1000192000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES = 1000215000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES = 1000245000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES = 1000276000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES = 1000295000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO = 1000295001,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO = 1000295002,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES = 1000297000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_MEMORY_BARRIER_2 = 1000314000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2 = 1000314001,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2 = 1000314002,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_DEPENDENCY_INFO = 1000314003,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_SUBMIT_INFO_2 = 1000314004,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO = 1000314005,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO = 1000314006,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES = 1000314007,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES = 1000325000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES = 1000335000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2 = 1000337000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2 = 1000337001,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2 = 1000337002,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2 = 1000337003,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2 = 1000337004,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2 = 1000337005,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_BUFFER_COPY_2 = 1000337006,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_IMAGE_COPY_2 = 1000337007,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_IMAGE_BLIT_2 = 1000337008,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2 = 1000337009,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2 = 1000337010,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES = 1000225000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO = 1000225001,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES = 1000225002,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES = 1000138000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES = 1000138001,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK = 1000138002,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO = 1000138003,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES = 1000066000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_RENDERING_INFO = 1000044000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO = 1000044001,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO = 1000044002,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES = 1000044003,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO = 1000044004,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_FEATURES = 1000280000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_PROPERTIES = 1000280001,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES = 1000281001,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3 = 1000360000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_FEATURES = 1000413000,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_PROPERTIES = 1000413001,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_DEVICE_BUFFER_MEMORY_REQUIREMENTS = 1000413002,
// Provided by VK_VERSION_1_3
VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS = 1000413003,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_4_FEATURES = 55,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_4_PROPERTIES = 56,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO = 1000174000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GLOBAL_PRIORITY_QUERY_FEATURES = 1000388000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES = 1000388001,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_ROTATE_FEATURES = 1000416000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT_CONTROLS_2_FEATURES = 1000528000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_EXPECT_ASSUME_FEATURES = 1000544000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES = 1000259000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO = 1000259001,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES = 1000259002,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES = 1000525000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO = 1000190001,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES = 1000190002,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES = 1000265000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_MEMORY_MAP_INFO = 1000271000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_MEMORY_UNMAP_INFO = 1000271001,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_FEATURES = 1000470000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_PROPERTIES = 1000470001,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_RENDERING_AREA_INFO = 1000470003,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_DEVICE_IMAGE_SUBRESOURCE_INFO = 1000470004,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2 = 1000338002,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2 = 1000338003,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PIPELINE_CREATE_FLAGS_2_CREATE_INFO = 1000470005,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_BUFFER_USAGE_FLAGS_2_CREATE_INFO = 1000470006,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES = 1000080000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_LOCAL_READ_FEATURES = 1000232000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_LOCATION_INFO = 1000232001,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_RENDERING_INPUT_ATTACHMENT_INDEX_INFO = 1000232002,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_FEATURES = 1000545000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_PROPERTIES = 1000545001,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_BIND_MEMORY_STATUS = 1000545002,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_BIND_DESCRIPTOR_SETS_INFO = 1000545003,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO = 1000545004,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_INFO = 1000545005,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_WITH_TEMPLATE_INFO = 1000545006,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_PROTECTED_ACCESS_FEATURES = 1000466000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PIPELINE_ROBUSTNESS_CREATE_INFO = 1000068000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_FEATURES = 1000068001,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_PROPERTIES = 1000068002,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES = 1000270000,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES = 1000270001,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY = 1000270002,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY = 1000270003,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO = 1000270004,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO = 1000270005,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO = 1000270006,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO = 1000270007,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE = 1000270008,
// Provided by VK_VERSION_1_4
VK_STRUCTURE_TYPE_HOST_IMAGE_COPY_DEVICE_PERFORMANCE_QUERY = 1000270009,
// Provided by VK_KHR_swapchain
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR = 1000001000,
// Provided by VK_KHR_swapchain
VK_STRUCTURE_TYPE_PRESENT_INFO_KHR = 1000001001,
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR = 1000060007,
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR = 1000060008,
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR = 1000060009,
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR = 1000060010,
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR = 1000060011,
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR = 1000060012,
// Provided by VK_KHR_display
VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR = 1000002000,
// Provided by VK_KHR_display
VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR = 1000002001,
// Provided by VK_KHR_display_swapchain
VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR = 1000003000,
// Provided by VK_KHR_xlib_surface
VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR = 1000004000,
// Provided by VK_KHR_xcb_surface
VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR = 1000005000,
// Provided by VK_KHR_wayland_surface
VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR = 1000006000,
// Provided by VK_KHR_android_surface
VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR = 1000008000,
// Provided by VK_KHR_win32_surface
VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR = 1000009000,
// Provided by VK_EXT_debug_report
VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT = 1000011000,
// Provided by VK_AMD_rasterization_order
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_RASTERIZATION_ORDER_AMD = 1000018000,
// Provided by VK_EXT_debug_marker
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT = 1000022000,
// Provided by VK_EXT_debug_marker
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT = 1000022001,
// Provided by VK_EXT_debug_marker
VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT = 1000022002,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_PROFILE_INFO_KHR = 1000023000,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_CAPABILITIES_KHR = 1000023001,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_PICTURE_RESOURCE_INFO_KHR = 1000023002,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_SESSION_MEMORY_REQUIREMENTS_KHR = 1000023003,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_BIND_VIDEO_SESSION_MEMORY_INFO_KHR = 1000023004,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_SESSION_CREATE_INFO_KHR = 1000023005,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000023006,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_UPDATE_INFO_KHR = 1000023007,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_BEGIN_CODING_INFO_KHR = 1000023008,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_END_CODING_INFO_KHR = 1000023009,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_CODING_CONTROL_INFO_KHR = 1000023010,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR = 1000023011,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_QUEUE_FAMILY_VIDEO_PROPERTIES_KHR = 1000023012,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_PROFILE_LIST_INFO_KHR = 1000023013,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_FORMAT_INFO_KHR = 1000023014,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_VIDEO_FORMAT_PROPERTIES_KHR = 1000023015,
// Provided by VK_KHR_video_queue
VK_STRUCTURE_TYPE_QUEUE_FAMILY_QUERY_RESULT_STATUS_PROPERTIES_KHR = 1000023016,
// Provided by VK_KHR_video_decode_queue
VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR = 1000024000,
// Provided by VK_KHR_video_decode_queue
VK_STRUCTURE_TYPE_VIDEO_DECODE_CAPABILITIES_KHR = 1000024001,
// Provided by VK_KHR_video_decode_queue
VK_STRUCTURE_TYPE_VIDEO_DECODE_USAGE_INFO_KHR = 1000024002,
// Provided by VK_NV_dedicated_allocation
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV = 1000026000,
// Provided by VK_NV_dedicated_allocation
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_BUFFER_CREATE_INFO_NV = 1000026001,
// Provided by VK_NV_dedicated_allocation
VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV = 1000026002,
// Provided by VK_EXT_transform_feedback
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_FEATURES_EXT = 1000028000,
// Provided by VK_EXT_transform_feedback
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_PROPERTIES_EXT = 1000028001,
// Provided by VK_EXT_transform_feedback
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_STREAM_CREATE_INFO_EXT = 1000028002,
// Provided by VK_NVX_binary_import
VK_STRUCTURE_TYPE_CU_MODULE_CREATE_INFO_NVX = 1000029000,
// Provided by VK_NVX_binary_import
VK_STRUCTURE_TYPE_CU_FUNCTION_CREATE_INFO_NVX = 1000029001,
// Provided by VK_NVX_binary_import
VK_STRUCTURE_TYPE_CU_LAUNCH_INFO_NVX = 1000029002,
// Provided by VK_NVX_binary_import
VK_STRUCTURE_TYPE_CU_MODULE_TEXTURING_MODE_CREATE_INFO_NVX = 1000029004,
// Provided by VK_NVX_image_view_handle
VK_STRUCTURE_TYPE_IMAGE_VIEW_HANDLE_INFO_NVX = 1000030000,
// Provided by VK_NVX_image_view_handle
VK_STRUCTURE_TYPE_IMAGE_VIEW_ADDRESS_PROPERTIES_NVX = 1000030001,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_CAPABILITIES_KHR = 1000038000,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000038001,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_ADD_INFO_KHR = 1000038002,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PICTURE_INFO_KHR = 1000038003,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_DPB_SLOT_INFO_KHR = 1000038004,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_NALU_SLICE_INFO_KHR = 1000038005,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_GOP_REMAINING_FRAME_INFO_KHR = 1000038006,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PROFILE_INFO_KHR = 1000038007,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_INFO_KHR = 1000038008,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_LAYER_INFO_KHR = 1000038009,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_CREATE_INFO_KHR = 1000038010,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_QUALITY_LEVEL_PROPERTIES_KHR = 1000038011,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_GET_INFO_KHR = 1000038012,
// Provided by VK_KHR_video_encode_h264
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_FEEDBACK_INFO_KHR = 1000038013,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_CAPABILITIES_KHR = 1000039000,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000039001,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_ADD_INFO_KHR = 1000039002,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PICTURE_INFO_KHR = 1000039003,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_DPB_SLOT_INFO_KHR = 1000039004,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_NALU_SLICE_SEGMENT_INFO_KHR = 1000039005,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_GOP_REMAINING_FRAME_INFO_KHR = 1000039006,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PROFILE_INFO_KHR = 1000039007,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_INFO_KHR = 1000039009,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_LAYER_INFO_KHR = 1000039010,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_CREATE_INFO_KHR = 1000039011,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_QUALITY_LEVEL_PROPERTIES_KHR = 1000039012,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_GET_INFO_KHR = 1000039013,
// Provided by VK_KHR_video_encode_h265
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_FEEDBACK_INFO_KHR = 1000039014,
// Provided by VK_KHR_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_CAPABILITIES_KHR = 1000040000,
// Provided by VK_KHR_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PICTURE_INFO_KHR = 1000040001,
// Provided by VK_KHR_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PROFILE_INFO_KHR = 1000040003,
// Provided by VK_KHR_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000040004,
// Provided by VK_KHR_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_ADD_INFO_KHR = 1000040005,
// Provided by VK_KHR_video_decode_h264
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_DPB_SLOT_INFO_KHR = 1000040006,
// Provided by VK_AMD_texture_gather_bias_lod
VK_STRUCTURE_TYPE_TEXTURE_LOD_GATHER_FORMAT_PROPERTIES_AMD = 1000041000,
// Provided by VK_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_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_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_NVX_multiview_per_view_attributes with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_ATTRIBUTES_INFO_NVX = 1000044009,
// Provided by VK_NV_viewport_swizzle
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SWIZZLE_STATE_CREATE_INFO_NV = 1000098000,
// Provided by VK_EXT_discard_rectangles
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT = 1000099000,
// Provided by VK_EXT_discard_rectangles
VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT = 1000099001,
// Provided by VK_EXT_conservative_rasterization
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONSERVATIVE_RASTERIZATION_PROPERTIES_EXT = 1000101000,
// Provided by VK_EXT_conservative_rasterization
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_CONSERVATIVE_STATE_CREATE_INFO_EXT = 1000101001,
// Provided by VK_EXT_depth_clip_enable
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLIP_ENABLE_FEATURES_EXT = 1000102000,
// Provided by VK_EXT_depth_clip_enable
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_DEPTH_CLIP_STATE_CREATE_INFO_EXT = 1000102001,
// Provided by VK_EXT_hdr_metadata
VK_STRUCTURE_TYPE_HDR_METADATA_EXT = 1000105000,
// Provided by VK_IMG_relaxed_line_rasterization
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RELAXED_LINE_RASTERIZATION_FEATURES_IMG = 1000110000,
// Provided by VK_KHR_shared_presentable_image
VK_STRUCTURE_TYPE_SHARED_PRESENT_SURFACE_CAPABILITIES_KHR = 1000111000,
// Provided by VK_KHR_external_fence_win32
VK_STRUCTURE_TYPE_IMPORT_FENCE_WIN32_HANDLE_INFO_KHR = 1000114000,
// Provided by VK_KHR_external_fence_win32
VK_STRUCTURE_TYPE_EXPORT_FENCE_WIN32_HANDLE_INFO_KHR = 1000114001,
// Provided by VK_KHR_external_fence_win32
VK_STRUCTURE_TYPE_FENCE_GET_WIN32_HANDLE_INFO_KHR = 1000114002,
// Provided by VK_KHR_external_fence_fd
VK_STRUCTURE_TYPE_IMPORT_FENCE_FD_INFO_KHR = 1000115000,
// Provided by VK_KHR_external_fence_fd
VK_STRUCTURE_TYPE_FENCE_GET_FD_INFO_KHR = 1000115001,
// Provided by VK_KHR_performance_query
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_FEATURES_KHR = 1000116000,
// Provided by VK_KHR_performance_query
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_PROPERTIES_KHR = 1000116001,
// Provided by VK_KHR_performance_query
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR = 1000116002,
// Provided by VK_KHR_performance_query
VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR = 1000116003,
// Provided by VK_KHR_performance_query
VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR = 1000116004,
// Provided by VK_KHR_performance_query
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_KHR = 1000116005,
// Provided by VK_KHR_performance_query
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_DESCRIPTION_KHR = 1000116006,
// Provided by VK_KHR_get_surface_capabilities2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SURFACE_INFO_2_KHR = 1000119000,
// Provided by VK_KHR_get_surface_capabilities2
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_KHR = 1000119001,
// Provided by VK_KHR_get_surface_capabilities2
VK_STRUCTURE_TYPE_SURFACE_FORMAT_2_KHR = 1000119002,
// Provided by VK_KHR_get_display_properties2
VK_STRUCTURE_TYPE_DISPLAY_PROPERTIES_2_KHR = 1000121000,
// Provided by VK_KHR_get_display_properties2
VK_STRUCTURE_TYPE_DISPLAY_PLANE_PROPERTIES_2_KHR = 1000121001,
// Provided by VK_KHR_get_display_properties2
VK_STRUCTURE_TYPE_DISPLAY_MODE_PROPERTIES_2_KHR = 1000121002,
// Provided by VK_KHR_get_display_properties2
VK_STRUCTURE_TYPE_DISPLAY_PLANE_INFO_2_KHR = 1000121003,
// Provided by VK_KHR_get_display_properties2
VK_STRUCTURE_TYPE_DISPLAY_PLANE_CAPABILITIES_2_KHR = 1000121004,
// Provided by VK_MVK_ios_surface
VK_STRUCTURE_TYPE_IOS_SURFACE_CREATE_INFO_MVK = 1000122000,
// Provided by VK_MVK_macos_surface
VK_STRUCTURE_TYPE_MACOS_SURFACE_CREATE_INFO_MVK = 1000123000,
// Provided by VK_EXT_debug_utils
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT = 1000128000,
// Provided by VK_EXT_debug_utils
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_TAG_INFO_EXT = 1000128001,
// Provided by VK_EXT_debug_utils
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT = 1000128002,
// Provided by VK_EXT_debug_utils
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT = 1000128003,
// Provided by VK_EXT_debug_utils
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT = 1000128004,
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_USAGE_ANDROID = 1000129000,
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_PROPERTIES_ANDROID = 1000129001,
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID = 1000129002,
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VK_STRUCTURE_TYPE_IMPORT_ANDROID_HARDWARE_BUFFER_INFO_ANDROID = 1000129003,
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VK_STRUCTURE_TYPE_MEMORY_GET_ANDROID_HARDWARE_BUFFER_INFO_ANDROID = 1000129004,
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID = 1000129005,
// Provided by VK_ANDROID_external_memory_android_hardware_buffer with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_2_ANDROID = 1000129006,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ENQUEUE_FEATURES_AMDX = 1000134000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ENQUEUE_PROPERTIES_AMDX = 1000134001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue
VK_STRUCTURE_TYPE_EXECUTION_GRAPH_PIPELINE_SCRATCH_SIZE_AMDX = 1000134002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue
VK_STRUCTURE_TYPE_EXECUTION_GRAPH_PIPELINE_CREATE_INFO_AMDX = 1000134003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_NODE_CREATE_INFO_AMDX = 1000134004,
#endif
// Provided by VK_AMD_mixed_attachment_samples with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_AMD = 1000044008,
// Provided by VK_KHR_shader_bfloat16
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_BFLOAT16_FEATURES_KHR = 1000141000,
// Provided by VK_EXT_sample_locations
VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT = 1000143000,
// Provided by VK_EXT_sample_locations
VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT = 1000143001,
// Provided by VK_EXT_sample_locations
VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT = 1000143002,
// Provided by VK_EXT_sample_locations
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT = 1000143003,
// Provided by VK_EXT_sample_locations
VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT = 1000143004,
// Provided by VK_EXT_blend_operation_advanced
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_FEATURES_EXT = 1000148000,
// Provided by VK_EXT_blend_operation_advanced
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_PROPERTIES_EXT = 1000148001,
// Provided by VK_EXT_blend_operation_advanced
VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_ADVANCED_STATE_CREATE_INFO_EXT = 1000148002,
// Provided by VK_NV_fragment_coverage_to_color
VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_TO_COLOR_STATE_CREATE_INFO_NV = 1000149000,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_KHR = 1000150007,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_GEOMETRY_INFO_KHR = 1000150000,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_DEVICE_ADDRESS_INFO_KHR = 1000150002,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_AABBS_DATA_KHR = 1000150003,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_INSTANCES_DATA_KHR = 1000150004,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_TRIANGLES_DATA_KHR = 1000150005,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_KHR = 1000150006,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_INFO_KHR = 1000150009,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_INFO_KHR = 1000150010,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_TO_MEMORY_INFO_KHR = 1000150011,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_ACCELERATION_STRUCTURE_INFO_KHR = 1000150012,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ACCELERATION_STRUCTURE_FEATURES_KHR = 1000150013,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ACCELERATION_STRUCTURE_PROPERTIES_KHR = 1000150014,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_KHR = 1000150017,
// Provided by VK_KHR_acceleration_structure
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_SIZES_INFO_KHR = 1000150020,
// Provided by VK_KHR_ray_tracing_pipeline
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_FEATURES_KHR = 1000347000,
// Provided by VK_KHR_ray_tracing_pipeline
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_PROPERTIES_KHR = 1000347001,
// Provided by VK_KHR_ray_tracing_pipeline
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR = 1000150015,
// Provided by VK_KHR_ray_tracing_pipeline
VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_KHR = 1000150016,
// Provided by VK_KHR_ray_tracing_pipeline
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_INTERFACE_CREATE_INFO_KHR = 1000150018,
// Provided by VK_KHR_ray_query
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_QUERY_FEATURES_KHR = 1000348013,
// Provided by VK_NV_framebuffer_mixed_samples
VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_MODULATION_STATE_CREATE_INFO_NV = 1000152000,
// Provided by VK_NV_shader_sm_builtins
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SM_BUILTINS_FEATURES_NV = 1000154000,
// Provided by VK_NV_shader_sm_builtins
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SM_BUILTINS_PROPERTIES_NV = 1000154001,
// Provided by VK_EXT_image_drm_format_modifier
VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT = 1000158000,
// Provided by VK_EXT_image_drm_format_modifier
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT = 1000158002,
// Provided by VK_EXT_image_drm_format_modifier
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT = 1000158003,
// Provided by VK_EXT_image_drm_format_modifier
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT = 1000158004,
// Provided by VK_EXT_image_drm_format_modifier
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT = 1000158005,
// Provided by VK_EXT_image_drm_format_modifier with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_2_EXT = 1000158006,
// Provided by VK_EXT_validation_cache
VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT = 1000160000,
// Provided by VK_EXT_validation_cache
VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT = 1000160001,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_portability_subset
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PORTABILITY_SUBSET_FEATURES_KHR = 1000163000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_KHR_portability_subset
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PORTABILITY_SUBSET_PROPERTIES_KHR = 1000163001,
#endif
// Provided by VK_NV_shading_rate_image
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SHADING_RATE_IMAGE_STATE_CREATE_INFO_NV = 1000164000,
// Provided by VK_NV_shading_rate_image
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_FEATURES_NV = 1000164001,
// Provided by VK_NV_shading_rate_image
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADING_RATE_IMAGE_PROPERTIES_NV = 1000164002,
// Provided by VK_NV_shading_rate_image
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_COARSE_SAMPLE_ORDER_STATE_CREATE_INFO_NV = 1000164005,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_NV = 1000165000,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV = 1000165001,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_GEOMETRY_NV = 1000165003,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NV = 1000165004,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_GEOMETRY_AABB_NV = 1000165005,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NV = 1000165006,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_NV = 1000165007,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_NV = 1000165008,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PROPERTIES_NV = 1000165009,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_NV = 1000165011,
// Provided by VK_NV_ray_tracing
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_INFO_NV = 1000165012,
// Provided by VK_NV_representative_fragment_test
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_REPRESENTATIVE_FRAGMENT_TEST_FEATURES_NV = 1000166000,
// Provided by VK_NV_representative_fragment_test
VK_STRUCTURE_TYPE_PIPELINE_REPRESENTATIVE_FRAGMENT_TEST_STATE_CREATE_INFO_NV = 1000166001,
// Provided by VK_EXT_filter_cubic
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_VIEW_IMAGE_FORMAT_INFO_EXT = 1000170000,
// Provided by VK_EXT_filter_cubic
VK_STRUCTURE_TYPE_FILTER_CUBIC_IMAGE_VIEW_IMAGE_FORMAT_PROPERTIES_EXT = 1000170001,
// Provided by VK_EXT_external_memory_host
VK_STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT = 1000178000,
// Provided by VK_EXT_external_memory_host
VK_STRUCTURE_TYPE_MEMORY_HOST_POINTER_PROPERTIES_EXT = 1000178001,
// Provided by VK_EXT_external_memory_host
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_HOST_PROPERTIES_EXT = 1000178002,
// Provided by VK_KHR_shader_clock
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CLOCK_FEATURES_KHR = 1000181000,
// Provided by VK_AMD_pipeline_compiler_control
VK_STRUCTURE_TYPE_PIPELINE_COMPILER_CONTROL_CREATE_INFO_AMD = 1000183000,
// Provided by VK_AMD_shader_core_properties
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_AMD = 1000185000,
// Provided by VK_KHR_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_CAPABILITIES_KHR = 1000187000,
// Provided by VK_KHR_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000187001,
// Provided by VK_KHR_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_ADD_INFO_KHR = 1000187002,
// Provided by VK_KHR_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PROFILE_INFO_KHR = 1000187003,
// Provided by VK_KHR_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PICTURE_INFO_KHR = 1000187004,
// Provided by VK_KHR_video_decode_h265
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_DPB_SLOT_INFO_KHR = 1000187005,
// Provided by VK_AMD_memory_overallocation_behavior
VK_STRUCTURE_TYPE_DEVICE_MEMORY_OVERALLOCATION_CREATE_INFO_AMD = 1000189000,
// Provided by VK_EXT_vertex_attribute_divisor
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT = 1000190000,
// Provided by VK_GGP_frame_token
VK_STRUCTURE_TYPE_PRESENT_FRAME_TOKEN_GGP = 1000191000,
// Provided by VK_NV_mesh_shader
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_FEATURES_NV = 1000202000,
// Provided by VK_NV_mesh_shader
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_PROPERTIES_NV = 1000202001,
// Provided by VK_NV_shader_image_footprint
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_IMAGE_FOOTPRINT_FEATURES_NV = 1000204000,
// Provided by VK_NV_scissor_exclusive
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_EXCLUSIVE_SCISSOR_STATE_CREATE_INFO_NV = 1000205000,
// Provided by VK_NV_scissor_exclusive
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXCLUSIVE_SCISSOR_FEATURES_NV = 1000205002,
// Provided by VK_NV_device_diagnostic_checkpoints
VK_STRUCTURE_TYPE_CHECKPOINT_DATA_NV = 1000206000,
// Provided by VK_NV_device_diagnostic_checkpoints
VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_NV = 1000206001,
// Provided by VK_NV_device_diagnostic_checkpoints with VK_VERSION_1_3 or VK_KHR_synchronization2
VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_2_NV = 1000314008,
// Provided by VK_NV_device_diagnostic_checkpoints with VK_VERSION_1_3 or VK_KHR_synchronization2
VK_STRUCTURE_TYPE_CHECKPOINT_DATA_2_NV = 1000314009,
// 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_EXT_fragment_density_map with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_INFO_EXT = 1000044007,
// 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_KHR_fragment_shading_rate with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR = 1000044006,
// 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_KHR_shader_quad_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_QUAD_CONTROL_FEATURES_KHR = 1000235000,
// Provided by VK_EXT_memory_budget
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_BUDGET_PROPERTIES_EXT = 1000237000,
// Provided by VK_EXT_memory_priority
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PRIORITY_FEATURES_EXT = 1000238000,
// Provided by VK_EXT_memory_priority
VK_STRUCTURE_TYPE_MEMORY_PRIORITY_ALLOCATE_INFO_EXT = 1000238001,
// Provided by VK_KHR_surface_protected_capabilities
VK_STRUCTURE_TYPE_SURFACE_PROTECTED_CAPABILITIES_KHR = 1000239000,
// Provided by VK_NV_dedicated_allocation_image_aliasing
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEDICATED_ALLOCATION_IMAGE_ALIASING_FEATURES_NV = 1000240000,
// Provided by VK_EXT_buffer_device_address
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT = 1000244000,
// Provided by VK_EXT_buffer_device_address
VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_CREATE_INFO_EXT = 1000244002,
// Provided by VK_EXT_validation_features
VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT = 1000247000,
// Provided by VK_KHR_present_wait
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_WAIT_FEATURES_KHR = 1000248000,
// Provided by VK_NV_cooperative_matrix
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_FEATURES_NV = 1000249000,
// Provided by VK_NV_cooperative_matrix
VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_PROPERTIES_NV = 1000249001,
// Provided by VK_NV_cooperative_matrix
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_PROPERTIES_NV = 1000249002,
// Provided by VK_NV_coverage_reduction_mode
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COVERAGE_REDUCTION_MODE_FEATURES_NV = 1000250000,
// Provided by VK_NV_coverage_reduction_mode
VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_REDUCTION_STATE_CREATE_INFO_NV = 1000250001,
// Provided by VK_NV_coverage_reduction_mode
VK_STRUCTURE_TYPE_FRAMEBUFFER_MIXED_SAMPLES_COMBINATION_NV = 1000250002,
// Provided by VK_EXT_fragment_shader_interlock
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_INTERLOCK_FEATURES_EXT = 1000251000,
// Provided by VK_EXT_ycbcr_image_arrays
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_IMAGE_ARRAYS_FEATURES_EXT = 1000252000,
// Provided by VK_EXT_provoking_vertex
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROVOKING_VERTEX_FEATURES_EXT = 1000254000,
// Provided by VK_EXT_provoking_vertex
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_PROVOKING_VERTEX_STATE_CREATE_INFO_EXT = 1000254001,
// Provided by VK_EXT_provoking_vertex
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROVOKING_VERTEX_PROPERTIES_EXT = 1000254002,
// Provided by VK_EXT_full_screen_exclusive
VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT = 1000255000,
// Provided by VK_EXT_full_screen_exclusive
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT = 1000255002,
// Provided by VK_KHR_win32_surface with VK_EXT_full_screen_exclusive
VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT = 1000255001,
// Provided by VK_EXT_headless_surface
VK_STRUCTURE_TYPE_HEADLESS_SURFACE_CREATE_INFO_EXT = 1000256000,
// Provided by VK_EXT_shader_atomic_float
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_FEATURES_EXT = 1000260000,
// Provided by VK_EXT_extended_dynamic_state
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_FEATURES_EXT = 1000267000,
// Provided by VK_KHR_pipeline_executable_properties
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_EXECUTABLE_PROPERTIES_FEATURES_KHR = 1000269000,
// Provided by VK_KHR_pipeline_executable_properties
VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR = 1000269001,
// Provided by VK_KHR_pipeline_executable_properties
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR = 1000269002,
// Provided by VK_KHR_pipeline_executable_properties
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR = 1000269003,
// Provided by VK_KHR_pipeline_executable_properties
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR = 1000269004,
// Provided by VK_KHR_pipeline_executable_properties
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR = 1000269005,
// Provided by VK_EXT_map_memory_placed
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_FEATURES_EXT = 1000272000,
// Provided by VK_EXT_map_memory_placed
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_PROPERTIES_EXT = 1000272001,
// Provided by VK_EXT_map_memory_placed
VK_STRUCTURE_TYPE_MEMORY_MAP_PLACED_INFO_EXT = 1000272002,
// Provided by VK_EXT_shader_atomic_float2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_2_FEATURES_EXT = 1000273000,
// Provided by VK_NV_device_generated_commands
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_PROPERTIES_NV = 1000277000,
// Provided by VK_NV_device_generated_commands
VK_STRUCTURE_TYPE_GRAPHICS_SHADER_GROUP_CREATE_INFO_NV = 1000277001,
// Provided by VK_NV_device_generated_commands
VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_SHADER_GROUPS_CREATE_INFO_NV = 1000277002,
// Provided by VK_NV_device_generated_commands
VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_TOKEN_NV = 1000277003,
// Provided by VK_NV_device_generated_commands
VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_CREATE_INFO_NV = 1000277004,
// Provided by VK_NV_device_generated_commands
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_INFO_NV = 1000277005,
// Provided by VK_NV_device_generated_commands
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_MEMORY_REQUIREMENTS_INFO_NV = 1000277006,
// Provided by VK_NV_device_generated_commands
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_FEATURES_NV = 1000277007,
// Provided by VK_NV_inherited_viewport_scissor
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INHERITED_VIEWPORT_SCISSOR_FEATURES_NV = 1000278000,
// Provided by VK_NV_inherited_viewport_scissor
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_VIEWPORT_SCISSOR_INFO_NV = 1000278001,
// Provided by VK_EXT_texel_buffer_alignment
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_FEATURES_EXT = 1000281000,
// Provided by VK_QCOM_render_pass_transform
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDER_PASS_TRANSFORM_INFO_QCOM = 1000282000,
// Provided by VK_QCOM_render_pass_transform
VK_STRUCTURE_TYPE_RENDER_PASS_TRANSFORM_BEGIN_INFO_QCOM = 1000282001,
// Provided by VK_EXT_depth_bias_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_BIAS_CONTROL_FEATURES_EXT = 1000283000,
// Provided by VK_EXT_depth_bias_control
VK_STRUCTURE_TYPE_DEPTH_BIAS_INFO_EXT = 1000283001,
// Provided by VK_EXT_depth_bias_control
VK_STRUCTURE_TYPE_DEPTH_BIAS_REPRESENTATION_INFO_EXT = 1000283002,
// Provided by VK_EXT_device_memory_report
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_MEMORY_REPORT_FEATURES_EXT = 1000284000,
// Provided by VK_EXT_device_memory_report
VK_STRUCTURE_TYPE_DEVICE_DEVICE_MEMORY_REPORT_CREATE_INFO_EXT = 1000284001,
// Provided by VK_EXT_device_memory_report
VK_STRUCTURE_TYPE_DEVICE_MEMORY_REPORT_CALLBACK_DATA_EXT = 1000284002,
// Provided by VK_EXT_custom_border_color
VK_STRUCTURE_TYPE_SAMPLER_CUSTOM_BORDER_COLOR_CREATE_INFO_EXT = 1000287000,
// Provided by VK_EXT_custom_border_color
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_PROPERTIES_EXT = 1000287001,
// Provided by VK_EXT_custom_border_color
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_FEATURES_EXT = 1000287002,
// Provided by VK_KHR_pipeline_library
VK_STRUCTURE_TYPE_PIPELINE_LIBRARY_CREATE_INFO_KHR = 1000290000,
// Provided by VK_NV_present_barrier
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_BARRIER_FEATURES_NV = 1000292000,
// Provided by VK_NV_present_barrier
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_PRESENT_BARRIER_NV = 1000292001,
// Provided by VK_NV_present_barrier
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_BARRIER_CREATE_INFO_NV = 1000292002,
// Provided by VK_KHR_present_id
VK_STRUCTURE_TYPE_PRESENT_ID_KHR = 1000294000,
// Provided by VK_KHR_present_id
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_ID_FEATURES_KHR = 1000294001,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR = 1000299000,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_INFO_KHR = 1000299001,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_LAYER_INFO_KHR = 1000299002,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_VIDEO_ENCODE_CAPABILITIES_KHR = 1000299003,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_VIDEO_ENCODE_USAGE_INFO_KHR = 1000299004,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_QUERY_POOL_VIDEO_ENCODE_FEEDBACK_CREATE_INFO_KHR = 1000299005,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR = 1000299006,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_PROPERTIES_KHR = 1000299007,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR = 1000299008,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_GET_INFO_KHR = 1000299009,
// Provided by VK_KHR_video_encode_queue
VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_FEEDBACK_INFO_KHR = 1000299010,
// Provided by VK_NV_device_diagnostics_config
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DIAGNOSTICS_CONFIG_FEATURES_NV = 1000300000,
// Provided by VK_NV_device_diagnostics_config
VK_STRUCTURE_TYPE_DEVICE_DIAGNOSTICS_CONFIG_CREATE_INFO_NV = 1000300001,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_cuda_kernel_launch
VK_STRUCTURE_TYPE_CUDA_MODULE_CREATE_INFO_NV = 1000307000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_cuda_kernel_launch
VK_STRUCTURE_TYPE_CUDA_FUNCTION_CREATE_INFO_NV = 1000307001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_cuda_kernel_launch
VK_STRUCTURE_TYPE_CUDA_LAUNCH_INFO_NV = 1000307002,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_cuda_kernel_launch
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_FEATURES_NV = 1000307003,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_cuda_kernel_launch
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_PROPERTIES_NV = 1000307004,
#endif
// Provided by VK_QCOM_tile_shading
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_SHADING_FEATURES_QCOM = 1000309000,
// Provided by VK_QCOM_tile_shading
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_SHADING_PROPERTIES_QCOM = 1000309001,
// Provided by VK_QCOM_tile_shading
VK_STRUCTURE_TYPE_RENDER_PASS_TILE_SHADING_CREATE_INFO_QCOM = 1000309002,
// Provided by VK_QCOM_tile_shading
VK_STRUCTURE_TYPE_PER_TILE_BEGIN_INFO_QCOM = 1000309003,
// Provided by VK_QCOM_tile_shading
VK_STRUCTURE_TYPE_PER_TILE_END_INFO_QCOM = 1000309004,
// Provided by VK_QCOM_tile_shading
VK_STRUCTURE_TYPE_DISPATCH_TILE_INFO_QCOM = 1000309005,
// Provided by VK_NV_low_latency
VK_STRUCTURE_TYPE_QUERY_LOW_LATENCY_SUPPORT_NV = 1000310000,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_EXPORT_METAL_OBJECT_CREATE_INFO_EXT = 1000311000,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_EXPORT_METAL_OBJECTS_INFO_EXT = 1000311001,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_EXPORT_METAL_DEVICE_INFO_EXT = 1000311002,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_EXPORT_METAL_COMMAND_QUEUE_INFO_EXT = 1000311003,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_EXPORT_METAL_BUFFER_INFO_EXT = 1000311004,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_IMPORT_METAL_BUFFER_INFO_EXT = 1000311005,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_EXPORT_METAL_TEXTURE_INFO_EXT = 1000311006,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_IMPORT_METAL_TEXTURE_INFO_EXT = 1000311007,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_EXPORT_METAL_IO_SURFACE_INFO_EXT = 1000311008,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_IMPORT_METAL_IO_SURFACE_INFO_EXT = 1000311009,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_EXPORT_METAL_SHARED_EVENT_INFO_EXT = 1000311010,
// Provided by VK_EXT_metal_objects
VK_STRUCTURE_TYPE_IMPORT_METAL_SHARED_EVENT_INFO_EXT = 1000311011,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_PROPERTIES_EXT = 1000316000,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_DENSITY_MAP_PROPERTIES_EXT = 1000316001,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_FEATURES_EXT = 1000316002,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_DESCRIPTOR_ADDRESS_INFO_EXT = 1000316003,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_DESCRIPTOR_GET_INFO_EXT = 1000316004,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_BUFFER_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316005,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_IMAGE_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316006,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_IMAGE_VIEW_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316007,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_SAMPLER_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316008,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_OPAQUE_CAPTURE_DESCRIPTOR_DATA_CREATE_INFO_EXT = 1000316010,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_DESCRIPTOR_BUFFER_BINDING_INFO_EXT = 1000316011,
// Provided by VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_DESCRIPTOR_BUFFER_BINDING_PUSH_DESCRIPTOR_BUFFER_HANDLE_EXT = 1000316012,
// Provided by VK_EXT_descriptor_buffer with VK_KHR_acceleration_structure or VK_NV_ray_tracing
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CAPTURE_DESCRIPTOR_DATA_INFO_EXT = 1000316009,
// Provided by VK_EXT_graphics_pipeline_library
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GRAPHICS_PIPELINE_LIBRARY_FEATURES_EXT = 1000320000,
// Provided by VK_EXT_graphics_pipeline_library
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GRAPHICS_PIPELINE_LIBRARY_PROPERTIES_EXT = 1000320001,
// Provided by VK_EXT_graphics_pipeline_library
VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_LIBRARY_CREATE_INFO_EXT = 1000320002,
// Provided by VK_AMD_shader_early_and_late_fragment_tests
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_EARLY_AND_LATE_FRAGMENT_TESTS_FEATURES_AMD = 1000321000,
// Provided by VK_KHR_fragment_shader_barycentric
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_KHR = 1000203000,
// Provided by VK_KHR_fragment_shader_barycentric
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_PROPERTIES_KHR = 1000322000,
// Provided by VK_KHR_shader_subgroup_uniform_control_flow
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_UNIFORM_CONTROL_FLOW_FEATURES_KHR = 1000323000,
// Provided by VK_NV_fragment_shading_rate_enums
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_ENUMS_PROPERTIES_NV = 1000326000,
// Provided by VK_NV_fragment_shading_rate_enums
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_ENUMS_FEATURES_NV = 1000326001,
// Provided by VK_NV_fragment_shading_rate_enums
VK_STRUCTURE_TYPE_PIPELINE_FRAGMENT_SHADING_RATE_ENUM_STATE_CREATE_INFO_NV = 1000326002,
// Provided by VK_NV_ray_tracing_motion_blur
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_MOTION_TRIANGLES_DATA_NV = 1000327000,
// Provided by VK_NV_ray_tracing_motion_blur
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_MOTION_BLUR_FEATURES_NV = 1000327001,
// Provided by VK_NV_ray_tracing_motion_blur
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MOTION_INFO_NV = 1000327002,
// Provided by VK_EXT_mesh_shader
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_FEATURES_EXT = 1000328000,
// Provided by VK_EXT_mesh_shader
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_PROPERTIES_EXT = 1000328001,
// Provided by VK_EXT_ycbcr_2plane_444_formats
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_2_PLANE_444_FORMATS_FEATURES_EXT = 1000330000,
// Provided by VK_EXT_fragment_density_map2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_2_FEATURES_EXT = 1000332000,
// Provided by VK_EXT_fragment_density_map2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_2_PROPERTIES_EXT = 1000332001,
// Provided by VK_QCOM_rotated_copy_commands
VK_STRUCTURE_TYPE_COPY_COMMAND_TRANSFORM_INFO_QCOM = 1000333000,
// Provided by VK_KHR_workgroup_memory_explicit_layout
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_WORKGROUP_MEMORY_EXPLICIT_LAYOUT_FEATURES_KHR = 1000336000,
// Provided by VK_EXT_image_compression_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_COMPRESSION_CONTROL_FEATURES_EXT = 1000338000,
// Provided by VK_EXT_image_compression_control
VK_STRUCTURE_TYPE_IMAGE_COMPRESSION_CONTROL_EXT = 1000338001,
// Provided by VK_EXT_image_compression_control
VK_STRUCTURE_TYPE_IMAGE_COMPRESSION_PROPERTIES_EXT = 1000338004,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ATTACHMENT_FEEDBACK_LOOP_LAYOUT_FEATURES_EXT = 1000339000,
// Provided by VK_EXT_4444_formats
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_4444_FORMATS_FEATURES_EXT = 1000340000,
// Provided by VK_EXT_device_fault
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FAULT_FEATURES_EXT = 1000341000,
// Provided by VK_EXT_device_fault
VK_STRUCTURE_TYPE_DEVICE_FAULT_COUNTS_EXT = 1000341001,
// Provided by VK_EXT_device_fault
VK_STRUCTURE_TYPE_DEVICE_FAULT_INFO_EXT = 1000341002,
// Provided by VK_EXT_rgba10x6_formats
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RGBA10X6_FORMATS_FEATURES_EXT = 1000344000,
// Provided by VK_EXT_directfb_surface
VK_STRUCTURE_TYPE_DIRECTFB_SURFACE_CREATE_INFO_EXT = 1000346000,
// Provided by VK_EXT_vertex_input_dynamic_state
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_INPUT_DYNAMIC_STATE_FEATURES_EXT = 1000352000,
// Provided by VK_EXT_shader_object, VK_EXT_vertex_input_dynamic_state
VK_STRUCTURE_TYPE_VERTEX_INPUT_BINDING_DESCRIPTION_2_EXT = 1000352001,
// Provided by VK_EXT_shader_object, VK_EXT_vertex_input_dynamic_state
VK_STRUCTURE_TYPE_VERTEX_INPUT_ATTRIBUTE_DESCRIPTION_2_EXT = 1000352002,
// Provided by VK_EXT_physical_device_drm
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRM_PROPERTIES_EXT = 1000353000,
// Provided by VK_EXT_device_address_binding_report
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ADDRESS_BINDING_REPORT_FEATURES_EXT = 1000354000,
// Provided by VK_EXT_device_address_binding_report
VK_STRUCTURE_TYPE_DEVICE_ADDRESS_BINDING_CALLBACK_DATA_EXT = 1000354001,
// Provided by VK_EXT_depth_clip_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLIP_CONTROL_FEATURES_EXT = 1000355000,
// Provided by VK_EXT_depth_clip_control
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_DEPTH_CLIP_CONTROL_CREATE_INFO_EXT = 1000355001,
// Provided by VK_EXT_primitive_topology_list_restart
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIMITIVE_TOPOLOGY_LIST_RESTART_FEATURES_EXT = 1000356000,
// Provided by VK_FUCHSIA_external_memory
VK_STRUCTURE_TYPE_IMPORT_MEMORY_ZIRCON_HANDLE_INFO_FUCHSIA = 1000364000,
// Provided by VK_FUCHSIA_external_memory
VK_STRUCTURE_TYPE_MEMORY_ZIRCON_HANDLE_PROPERTIES_FUCHSIA = 1000364001,
// Provided by VK_FUCHSIA_external_memory
VK_STRUCTURE_TYPE_MEMORY_GET_ZIRCON_HANDLE_INFO_FUCHSIA = 1000364002,
// Provided by VK_FUCHSIA_external_semaphore
VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_ZIRCON_HANDLE_INFO_FUCHSIA = 1000365000,
// Provided by VK_FUCHSIA_external_semaphore
VK_STRUCTURE_TYPE_SEMAPHORE_GET_ZIRCON_HANDLE_INFO_FUCHSIA = 1000365001,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_CREATE_INFO_FUCHSIA = 1000366000,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_IMPORT_MEMORY_BUFFER_COLLECTION_FUCHSIA = 1000366001,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_IMAGE_CREATE_INFO_FUCHSIA = 1000366002,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_PROPERTIES_FUCHSIA = 1000366003,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_BUFFER_CONSTRAINTS_INFO_FUCHSIA = 1000366004,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_BUFFER_CREATE_INFO_FUCHSIA = 1000366005,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_IMAGE_CONSTRAINTS_INFO_FUCHSIA = 1000366006,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_IMAGE_FORMAT_CONSTRAINTS_INFO_FUCHSIA = 1000366007,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_SYSMEM_COLOR_SPACE_FUCHSIA = 1000366008,
// Provided by VK_FUCHSIA_buffer_collection
VK_STRUCTURE_TYPE_BUFFER_COLLECTION_CONSTRAINTS_INFO_FUCHSIA = 1000366009,
// Provided by VK_HUAWEI_subpass_shading
VK_STRUCTURE_TYPE_SUBPASS_SHADING_PIPELINE_CREATE_INFO_HUAWEI = 1000369000,
// Provided by VK_HUAWEI_subpass_shading
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBPASS_SHADING_FEATURES_HUAWEI = 1000369001,
// Provided by VK_HUAWEI_subpass_shading
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBPASS_SHADING_PROPERTIES_HUAWEI = 1000369002,
// Provided by VK_HUAWEI_invocation_mask
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INVOCATION_MASK_FEATURES_HUAWEI = 1000370000,
// Provided by VK_NV_external_memory_rdma
VK_STRUCTURE_TYPE_MEMORY_GET_REMOTE_ADDRESS_INFO_NV = 1000371000,
// Provided by VK_NV_external_memory_rdma
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_RDMA_FEATURES_NV = 1000371001,
// Provided by VK_EXT_pipeline_properties
VK_STRUCTURE_TYPE_PIPELINE_PROPERTIES_IDENTIFIER_EXT = 1000372000,
// Provided by VK_EXT_pipeline_properties
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_PROPERTIES_FEATURES_EXT = 1000372001,
// Provided by VK_EXT_frame_boundary
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAME_BOUNDARY_FEATURES_EXT = 1000375000,
// Provided by VK_EXT_frame_boundary
VK_STRUCTURE_TYPE_FRAME_BOUNDARY_EXT = 1000375001,
// Provided by VK_EXT_multisampled_render_to_single_sampled
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_FEATURES_EXT = 1000376000,
// Provided by VK_EXT_multisampled_render_to_single_sampled
VK_STRUCTURE_TYPE_SUBPASS_RESOLVE_PERFORMANCE_QUERY_EXT = 1000376001,
// Provided by VK_EXT_multisampled_render_to_single_sampled
VK_STRUCTURE_TYPE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_INFO_EXT = 1000376002,
// Provided by VK_EXT_extended_dynamic_state2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_2_FEATURES_EXT = 1000377000,
// Provided by VK_QNX_screen_surface
VK_STRUCTURE_TYPE_SCREEN_SURFACE_CREATE_INFO_QNX = 1000378000,
// Provided by VK_EXT_color_write_enable
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COLOR_WRITE_ENABLE_FEATURES_EXT = 1000381000,
// Provided by VK_EXT_color_write_enable
VK_STRUCTURE_TYPE_PIPELINE_COLOR_WRITE_CREATE_INFO_EXT = 1000381001,
// Provided by VK_EXT_primitives_generated_query
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIMITIVES_GENERATED_QUERY_FEATURES_EXT = 1000382000,
// Provided by VK_KHR_ray_tracing_maintenance1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_MAINTENANCE_1_FEATURES_KHR = 1000386000,
// Provided by VK_EXT_image_view_min_lod
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_VIEW_MIN_LOD_FEATURES_EXT = 1000391000,
// Provided by VK_EXT_image_view_min_lod
VK_STRUCTURE_TYPE_IMAGE_VIEW_MIN_LOD_CREATE_INFO_EXT = 1000391001,
// Provided by VK_EXT_multi_draw
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTI_DRAW_FEATURES_EXT = 1000392000,
// Provided by VK_EXT_multi_draw
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTI_DRAW_PROPERTIES_EXT = 1000392001,
// Provided by VK_EXT_image_2d_view_of_3d
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_2D_VIEW_OF_3D_FEATURES_EXT = 1000393000,
// Provided by VK_EXT_shader_tile_image
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TILE_IMAGE_FEATURES_EXT = 1000395000,
// Provided by VK_EXT_shader_tile_image
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TILE_IMAGE_PROPERTIES_EXT = 1000395001,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_MICROMAP_BUILD_INFO_EXT = 1000396000,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_MICROMAP_VERSION_INFO_EXT = 1000396001,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_COPY_MICROMAP_INFO_EXT = 1000396002,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_COPY_MICROMAP_TO_MEMORY_INFO_EXT = 1000396003,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_MICROMAP_INFO_EXT = 1000396004,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPACITY_MICROMAP_FEATURES_EXT = 1000396005,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPACITY_MICROMAP_PROPERTIES_EXT = 1000396006,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_MICROMAP_CREATE_INFO_EXT = 1000396007,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_MICROMAP_BUILD_SIZES_INFO_EXT = 1000396008,
// Provided by VK_EXT_opacity_micromap
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_OPACITY_MICROMAP_EXT = 1000396009,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_FEATURES_NV = 1000397000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_PROPERTIES_NV = 1000397001,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_DISPLACEMENT_MICROMAP_NV = 1000397002,
#endif
// Provided by VK_HUAWEI_cluster_culling_shader
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_FEATURES_HUAWEI = 1000404000,
// Provided by VK_HUAWEI_cluster_culling_shader
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_PROPERTIES_HUAWEI = 1000404001,
// Provided by VK_HUAWEI_cluster_culling_shader
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_VRS_FEATURES_HUAWEI = 1000404002,
// Provided by VK_EXT_border_color_swizzle
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BORDER_COLOR_SWIZZLE_FEATURES_EXT = 1000411000,
// Provided by VK_EXT_border_color_swizzle
VK_STRUCTURE_TYPE_SAMPLER_BORDER_COLOR_COMPONENT_MAPPING_CREATE_INFO_EXT = 1000411001,
// Provided by VK_EXT_pageable_device_local_memory
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PAGEABLE_DEVICE_LOCAL_MEMORY_FEATURES_EXT = 1000412000,
// Provided by VK_ARM_shader_core_properties
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_ARM = 1000415000,
// Provided by VK_ARM_scheduling_controls
VK_STRUCTURE_TYPE_DEVICE_QUEUE_SHADER_CORE_CONTROL_CREATE_INFO_ARM = 1000417000,
// Provided by VK_ARM_scheduling_controls
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_FEATURES_ARM = 1000417001,
// Provided by VK_ARM_scheduling_controls
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_PROPERTIES_ARM = 1000417002,
// Provided by VK_EXT_image_sliced_view_of_3d
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_SLICED_VIEW_OF_3D_FEATURES_EXT = 1000418000,
// Provided by VK_EXT_image_sliced_view_of_3d
VK_STRUCTURE_TYPE_IMAGE_VIEW_SLICED_CREATE_INFO_EXT = 1000418001,
// Provided by VK_VALVE_descriptor_set_host_mapping
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_SET_HOST_MAPPING_FEATURES_VALVE = 1000420000,
// Provided by VK_VALVE_descriptor_set_host_mapping
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_BINDING_REFERENCE_VALVE = 1000420001,
// Provided by VK_VALVE_descriptor_set_host_mapping
VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_HOST_MAPPING_INFO_VALVE = 1000420002,
// Provided by VK_EXT_non_seamless_cube_map
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_NON_SEAMLESS_CUBE_MAP_FEATURES_EXT = 1000422000,
// Provided by VK_ARM_render_pass_striped
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RENDER_PASS_STRIPED_FEATURES_ARM = 1000424000,
// Provided by VK_ARM_render_pass_striped
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RENDER_PASS_STRIPED_PROPERTIES_ARM = 1000424001,
// Provided by VK_ARM_render_pass_striped
VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_BEGIN_INFO_ARM = 1000424002,
// Provided by VK_ARM_render_pass_striped
VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_INFO_ARM = 1000424003,
// Provided by VK_ARM_render_pass_striped
VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_SUBMIT_INFO_ARM = 1000424004,
// Provided by VK_NV_copy_memory_indirect
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COPY_MEMORY_INDIRECT_FEATURES_NV = 1000426000,
// Provided by VK_NV_copy_memory_indirect
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COPY_MEMORY_INDIRECT_PROPERTIES_NV = 1000426001,
// Provided by VK_NV_memory_decompression
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_DECOMPRESSION_FEATURES_NV = 1000427000,
// Provided by VK_NV_memory_decompression
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_DECOMPRESSION_PROPERTIES_NV = 1000427001,
// Provided by VK_NV_device_generated_commands_compute
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_COMPUTE_FEATURES_NV = 1000428000,
// Provided by VK_NV_device_generated_commands_compute
VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_INDIRECT_BUFFER_INFO_NV = 1000428001,
// Provided by VK_NV_device_generated_commands_compute
VK_STRUCTURE_TYPE_PIPELINE_INDIRECT_DEVICE_ADDRESS_INFO_NV = 1000428002,
// Provided by VK_NV_ray_tracing_linear_swept_spheres
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_LINEAR_SWEPT_SPHERES_FEATURES_NV = 1000429008,
// Provided by VK_NV_ray_tracing_linear_swept_spheres
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_LINEAR_SWEPT_SPHERES_DATA_NV = 1000429009,
// Provided by VK_NV_ray_tracing_linear_swept_spheres
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_SPHERES_DATA_NV = 1000429010,
// Provided by VK_NV_linear_color_attachment
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINEAR_COLOR_ATTACHMENT_FEATURES_NV = 1000430000,
// Provided by VK_KHR_shader_maximal_reconvergence
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_MAXIMAL_RECONVERGENCE_FEATURES_KHR = 1000434000,
// Provided by VK_EXT_image_compression_control_swapchain
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_COMPRESSION_CONTROL_SWAPCHAIN_FEATURES_EXT = 1000437000,
// Provided by VK_QCOM_image_processing
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_FEATURES_QCOM = 1000440000,
// Provided by VK_QCOM_image_processing
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_PROPERTIES_QCOM = 1000440001,
// Provided by VK_QCOM_image_processing
VK_STRUCTURE_TYPE_IMAGE_VIEW_SAMPLE_WEIGHT_CREATE_INFO_QCOM = 1000440002,
// Provided by VK_EXT_nested_command_buffer
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_NESTED_COMMAND_BUFFER_FEATURES_EXT = 1000451000,
// Provided by VK_EXT_nested_command_buffer
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_NESTED_COMMAND_BUFFER_PROPERTIES_EXT = 1000451001,
// Provided by VK_EXT_external_memory_acquire_unmodified
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_ACQUIRE_UNMODIFIED_EXT = 1000453000,
// Provided by VK_EXT_extended_dynamic_state3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_3_FEATURES_EXT = 1000455000,
// Provided by VK_EXT_extended_dynamic_state3
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_3_PROPERTIES_EXT = 1000455001,
// Provided by VK_EXT_subpass_merge_feedback
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBPASS_MERGE_FEEDBACK_FEATURES_EXT = 1000458000,
// Provided by VK_EXT_subpass_merge_feedback
VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_CONTROL_EXT = 1000458001,
// Provided by VK_EXT_subpass_merge_feedback
VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_FEEDBACK_CREATE_INFO_EXT = 1000458002,
// Provided by VK_EXT_subpass_merge_feedback
VK_STRUCTURE_TYPE_RENDER_PASS_SUBPASS_FEEDBACK_CREATE_INFO_EXT = 1000458003,
// Provided by VK_LUNARG_direct_driver_loading
VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_INFO_LUNARG = 1000459000,
// Provided by VK_LUNARG_direct_driver_loading
VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_LIST_LUNARG = 1000459001,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_CREATE_INFO_ARM = 1000460000,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_VIEW_CREATE_INFO_ARM = 1000460001,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_BIND_TENSOR_MEMORY_INFO_ARM = 1000460002,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_TENSOR_ARM = 1000460003,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TENSOR_PROPERTIES_ARM = 1000460004,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_FORMAT_PROPERTIES_ARM = 1000460005,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_DESCRIPTION_ARM = 1000460006,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_MEMORY_REQUIREMENTS_INFO_ARM = 1000460007,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_MEMORY_BARRIER_ARM = 1000460008,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TENSOR_FEATURES_ARM = 1000460009,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_DEVICE_TENSOR_MEMORY_REQUIREMENTS_ARM = 1000460010,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_COPY_TENSOR_INFO_ARM = 1000460011,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_COPY_ARM = 1000460012,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_DEPENDENCY_INFO_ARM = 1000460013,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_TENSOR_ARM = 1000460014,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_TENSOR_INFO_ARM = 1000460015,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_EXTERNAL_TENSOR_PROPERTIES_ARM = 1000460016,
// Provided by VK_ARM_tensors
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_TENSOR_CREATE_INFO_ARM = 1000460017,
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_TENSOR_FEATURES_ARM = 1000460018,
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_TENSOR_PROPERTIES_ARM = 1000460019,
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
VK_STRUCTURE_TYPE_DESCRIPTOR_GET_TENSOR_INFO_ARM = 1000460020,
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_CAPTURE_DESCRIPTOR_DATA_INFO_ARM = 1000460021,
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
VK_STRUCTURE_TYPE_TENSOR_VIEW_CAPTURE_DESCRIPTOR_DATA_INFO_ARM = 1000460022,
// Provided by VK_EXT_frame_boundary with VK_ARM_tensors
VK_STRUCTURE_TYPE_FRAME_BOUNDARY_TENSORS_ARM = 1000460023,
// Provided by VK_EXT_shader_module_identifier
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_MODULE_IDENTIFIER_FEATURES_EXT = 1000462000,
// Provided by VK_EXT_shader_module_identifier
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_MODULE_IDENTIFIER_PROPERTIES_EXT = 1000462001,
// Provided by VK_EXT_shader_module_identifier
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_MODULE_IDENTIFIER_CREATE_INFO_EXT = 1000462002,
// Provided by VK_EXT_shader_module_identifier
VK_STRUCTURE_TYPE_SHADER_MODULE_IDENTIFIER_EXT = 1000462003,
// Provided by VK_EXT_rasterization_order_attachment_access
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_FEATURES_EXT = 1000342000,
// Provided by VK_NV_optical_flow
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPTICAL_FLOW_FEATURES_NV = 1000464000,
// Provided by VK_NV_optical_flow
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPTICAL_FLOW_PROPERTIES_NV = 1000464001,
// Provided by VK_NV_optical_flow
VK_STRUCTURE_TYPE_OPTICAL_FLOW_IMAGE_FORMAT_INFO_NV = 1000464002,
// Provided by VK_NV_optical_flow
VK_STRUCTURE_TYPE_OPTICAL_FLOW_IMAGE_FORMAT_PROPERTIES_NV = 1000464003,
// Provided by VK_NV_optical_flow
VK_STRUCTURE_TYPE_OPTICAL_FLOW_SESSION_CREATE_INFO_NV = 1000464004,
// Provided by VK_NV_optical_flow
VK_STRUCTURE_TYPE_OPTICAL_FLOW_EXECUTE_INFO_NV = 1000464005,
// Provided by VK_NV_optical_flow
VK_STRUCTURE_TYPE_OPTICAL_FLOW_SESSION_CREATE_PRIVATE_DATA_INFO_NV = 1000464010,
// Provided by VK_EXT_legacy_dithering
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_DITHERING_FEATURES_EXT = 1000465000,
// Provided by VK_ANDROID_external_format_resolve
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FORMAT_RESOLVE_FEATURES_ANDROID = 1000468000,
// Provided by VK_ANDROID_external_format_resolve
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FORMAT_RESOLVE_PROPERTIES_ANDROID = 1000468001,
// Provided by VK_ANDROID_external_format_resolve
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_RESOLVE_PROPERTIES_ANDROID = 1000468002,
// Provided by VK_AMD_anti_lag
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ANTI_LAG_FEATURES_AMD = 1000476000,
// Provided by VK_AMD_anti_lag
VK_STRUCTURE_TYPE_ANTI_LAG_DATA_AMD = 1000476001,
// Provided by VK_AMD_anti_lag
VK_STRUCTURE_TYPE_ANTI_LAG_PRESENTATION_INFO_AMD = 1000476002,
// Provided by VK_KHR_present_id2
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_PRESENT_ID_2_KHR = 1000479000,
// Provided by VK_KHR_present_id2
VK_STRUCTURE_TYPE_PRESENT_ID_2_KHR = 1000479001,
// Provided by VK_KHR_present_id2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_ID_2_FEATURES_KHR = 1000479002,
// Provided by VK_KHR_present_wait2
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_PRESENT_WAIT_2_KHR = 1000480000,
// Provided by VK_KHR_present_wait2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_WAIT_2_FEATURES_KHR = 1000480001,
// Provided by VK_KHR_present_wait2
VK_STRUCTURE_TYPE_PRESENT_WAIT_2_INFO_KHR = 1000480002,
// Provided by VK_KHR_ray_tracing_position_fetch
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_POSITION_FETCH_FEATURES_KHR = 1000481000,
// Provided by VK_EXT_shader_object
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_OBJECT_FEATURES_EXT = 1000482000,
// Provided by VK_EXT_shader_object
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_OBJECT_PROPERTIES_EXT = 1000482001,
// Provided by VK_EXT_shader_object
VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT = 1000482002,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_BINARY_FEATURES_KHR = 1000483000,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_PIPELINE_BINARY_CREATE_INFO_KHR = 1000483001,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_PIPELINE_BINARY_INFO_KHR = 1000483002,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_PIPELINE_BINARY_KEY_KHR = 1000483003,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_BINARY_PROPERTIES_KHR = 1000483004,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_RELEASE_CAPTURED_PIPELINE_DATA_INFO_KHR = 1000483005,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_PIPELINE_BINARY_DATA_INFO_KHR = 1000483006,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_PIPELINE_CREATE_INFO_KHR = 1000483007,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_DEVICE_PIPELINE_BINARY_INTERNAL_CACHE_CONTROL_KHR = 1000483008,
// Provided by VK_KHR_pipeline_binary
VK_STRUCTURE_TYPE_PIPELINE_BINARY_HANDLES_INFO_KHR = 1000483009,
// Provided by VK_QCOM_tile_properties
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_PROPERTIES_FEATURES_QCOM = 1000484000,
// Provided by VK_QCOM_tile_properties
VK_STRUCTURE_TYPE_TILE_PROPERTIES_QCOM = 1000484001,
// Provided by VK_SEC_amigo_profiling
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_AMIGO_PROFILING_FEATURES_SEC = 1000485000,
// Provided by VK_SEC_amigo_profiling
VK_STRUCTURE_TYPE_AMIGO_PROFILING_SUBMIT_INFO_SEC = 1000485001,
// Provided by VK_KHR_surface_maintenance1
VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_KHR = 1000274000,
// Provided by VK_KHR_surface_maintenance1
VK_STRUCTURE_TYPE_SURFACE_PRESENT_SCALING_CAPABILITIES_KHR = 1000274001,
// Provided by VK_KHR_surface_maintenance1
VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_COMPATIBILITY_KHR = 1000274002,
// Provided by VK_KHR_swapchain_maintenance1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SWAPCHAIN_MAINTENANCE_1_FEATURES_KHR = 1000275000,
// Provided by VK_KHR_swapchain_maintenance1
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_FENCE_INFO_KHR = 1000275001,
// Provided by VK_KHR_swapchain_maintenance1
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODES_CREATE_INFO_KHR = 1000275002,
// Provided by VK_KHR_swapchain_maintenance1
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODE_INFO_KHR = 1000275003,
// Provided by VK_KHR_swapchain_maintenance1
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_SCALING_CREATE_INFO_KHR = 1000275004,
// Provided by VK_KHR_swapchain_maintenance1
VK_STRUCTURE_TYPE_RELEASE_SWAPCHAIN_IMAGES_INFO_KHR = 1000275005,
// Provided by VK_QCOM_multiview_per_view_viewports
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PER_VIEW_VIEWPORTS_FEATURES_QCOM = 1000488000,
// Provided by VK_NV_ray_tracing_invocation_reorder
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_INVOCATION_REORDER_FEATURES_NV = 1000490000,
// Provided by VK_NV_ray_tracing_invocation_reorder
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_INVOCATION_REORDER_PROPERTIES_NV = 1000490001,
// Provided by VK_NV_cooperative_vector
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_VECTOR_FEATURES_NV = 1000491000,
// Provided by VK_NV_cooperative_vector
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_VECTOR_PROPERTIES_NV = 1000491001,
// Provided by VK_NV_cooperative_vector
VK_STRUCTURE_TYPE_COOPERATIVE_VECTOR_PROPERTIES_NV = 1000491002,
// Provided by VK_NV_cooperative_vector
VK_STRUCTURE_TYPE_CONVERT_COOPERATIVE_VECTOR_MATRIX_INFO_NV = 1000491004,
// Provided by VK_NV_extended_sparse_address_space
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_SPARSE_ADDRESS_SPACE_FEATURES_NV = 1000492000,
// Provided by VK_NV_extended_sparse_address_space
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_SPARSE_ADDRESS_SPACE_PROPERTIES_NV = 1000492001,
// Provided by VK_EXT_mutable_descriptor_type
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MUTABLE_DESCRIPTOR_TYPE_FEATURES_EXT = 1000351000,
// Provided by VK_EXT_mutable_descriptor_type
VK_STRUCTURE_TYPE_MUTABLE_DESCRIPTOR_TYPE_CREATE_INFO_EXT = 1000351002,
// Provided by VK_EXT_legacy_vertex_attributes
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_VERTEX_ATTRIBUTES_FEATURES_EXT = 1000495000,
// Provided by VK_EXT_legacy_vertex_attributes
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_VERTEX_ATTRIBUTES_PROPERTIES_EXT = 1000495001,
// Provided by VK_EXT_layer_settings
VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT = 1000496000,
// Provided by VK_ARM_shader_core_builtins
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_BUILTINS_FEATURES_ARM = 1000497000,
// Provided by VK_ARM_shader_core_builtins
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_BUILTINS_PROPERTIES_ARM = 1000497001,
// Provided by VK_EXT_pipeline_library_group_handles
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_LIBRARY_GROUP_HANDLES_FEATURES_EXT = 1000498000,
// Provided by VK_EXT_dynamic_rendering_unused_attachments
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_UNUSED_ATTACHMENTS_FEATURES_EXT = 1000499000,
// Provided by VK_NV_low_latency2
VK_STRUCTURE_TYPE_LATENCY_SLEEP_MODE_INFO_NV = 1000505000,
// Provided by VK_NV_low_latency2
VK_STRUCTURE_TYPE_LATENCY_SLEEP_INFO_NV = 1000505001,
// Provided by VK_NV_low_latency2
VK_STRUCTURE_TYPE_SET_LATENCY_MARKER_INFO_NV = 1000505002,
// Provided by VK_NV_low_latency2
VK_STRUCTURE_TYPE_GET_LATENCY_MARKER_INFO_NV = 1000505003,
// Provided by VK_NV_low_latency2
VK_STRUCTURE_TYPE_LATENCY_TIMINGS_FRAME_REPORT_NV = 1000505004,
// Provided by VK_NV_low_latency2
VK_STRUCTURE_TYPE_LATENCY_SUBMISSION_PRESENT_ID_NV = 1000505005,
// Provided by VK_NV_low_latency2
VK_STRUCTURE_TYPE_OUT_OF_BAND_QUEUE_TYPE_INFO_NV = 1000505006,
// Provided by VK_NV_low_latency2
VK_STRUCTURE_TYPE_SWAPCHAIN_LATENCY_CREATE_INFO_NV = 1000505007,
// Provided by VK_NV_low_latency2
VK_STRUCTURE_TYPE_LATENCY_SURFACE_CAPABILITIES_NV = 1000505008,
// Provided by VK_KHR_cooperative_matrix
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_FEATURES_KHR = 1000506000,
// Provided by VK_KHR_cooperative_matrix
VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_PROPERTIES_KHR = 1000506001,
// Provided by VK_KHR_cooperative_matrix
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_PROPERTIES_KHR = 1000506002,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_CREATE_INFO_ARM = 1000507000,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SESSION_CREATE_INFO_ARM = 1000507001,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_RESOURCE_INFO_ARM = 1000507002,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_CONSTANT_ARM = 1000507003,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SESSION_MEMORY_REQUIREMENTS_INFO_ARM = 1000507004,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_BIND_DATA_GRAPH_PIPELINE_SESSION_MEMORY_INFO_ARM = 1000507005,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DATA_GRAPH_FEATURES_ARM = 1000507006,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SHADER_MODULE_CREATE_INFO_ARM = 1000507007,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_PROPERTY_QUERY_RESULT_ARM = 1000507008,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_INFO_ARM = 1000507009,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_COMPILER_CONTROL_CREATE_INFO_ARM = 1000507010,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SESSION_BIND_POINT_REQUIREMENTS_INFO_ARM = 1000507011,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SESSION_BIND_POINT_REQUIREMENT_ARM = 1000507012,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_IDENTIFIER_CREATE_INFO_ARM = 1000507013,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_DISPATCH_INFO_ARM = 1000507014,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_DATA_GRAPH_PROCESSING_ENGINE_CREATE_INFO_ARM = 1000507016,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_QUEUE_FAMILY_DATA_GRAPH_PROCESSING_ENGINE_PROPERTIES_ARM = 1000507017,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_QUEUE_FAMILY_DATA_GRAPH_PROPERTIES_ARM = 1000507018,
// Provided by VK_ARM_data_graph
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_QUEUE_FAMILY_DATA_GRAPH_PROCESSING_ENGINE_INFO_ARM = 1000507019,
// Provided by VK_ARM_data_graph with VK_ARM_tensors
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_CONSTANT_TENSOR_SEMI_STRUCTURED_SPARSITY_INFO_ARM = 1000507015,
// Provided by VK_QCOM_multiview_per_view_render_areas
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PER_VIEW_RENDER_AREAS_FEATURES_QCOM = 1000510000,
// Provided by VK_QCOM_multiview_per_view_render_areas
VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_RENDER_AREAS_RENDER_PASS_BEGIN_INFO_QCOM = 1000510001,
// Provided by VK_KHR_compute_shader_derivatives
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_KHR = 1000201000,
// Provided by VK_KHR_compute_shader_derivatives
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_PROPERTIES_KHR = 1000511000,
// Provided by VK_KHR_video_decode_av1
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_CAPABILITIES_KHR = 1000512000,
// Provided by VK_KHR_video_decode_av1
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_PICTURE_INFO_KHR = 1000512001,
// Provided by VK_KHR_video_decode_av1
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_PROFILE_INFO_KHR = 1000512003,
// Provided by VK_KHR_video_decode_av1
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000512004,
// Provided by VK_KHR_video_decode_av1
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_DPB_SLOT_INFO_KHR = 1000512005,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_CAPABILITIES_KHR = 1000513000,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000513001,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_PICTURE_INFO_KHR = 1000513002,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_DPB_SLOT_INFO_KHR = 1000513003,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_AV1_FEATURES_KHR = 1000513004,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_PROFILE_INFO_KHR = 1000513005,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_RATE_CONTROL_INFO_KHR = 1000513006,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_RATE_CONTROL_LAYER_INFO_KHR = 1000513007,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_QUALITY_LEVEL_PROPERTIES_KHR = 1000513008,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_SESSION_CREATE_INFO_KHR = 1000513009,
// Provided by VK_KHR_video_encode_av1
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_GOP_REMAINING_FRAME_INFO_KHR = 1000513010,
// Provided by VK_KHR_video_decode_vp9
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_DECODE_VP9_FEATURES_KHR = 1000514000,
// Provided by VK_KHR_video_decode_vp9
VK_STRUCTURE_TYPE_VIDEO_DECODE_VP9_CAPABILITIES_KHR = 1000514001,
// Provided by VK_KHR_video_decode_vp9
VK_STRUCTURE_TYPE_VIDEO_DECODE_VP9_PICTURE_INFO_KHR = 1000514002,
// Provided by VK_KHR_video_decode_vp9
VK_STRUCTURE_TYPE_VIDEO_DECODE_VP9_PROFILE_INFO_KHR = 1000514003,
// Provided by VK_KHR_video_maintenance1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_MAINTENANCE_1_FEATURES_KHR = 1000515000,
// Provided by VK_KHR_video_maintenance1
VK_STRUCTURE_TYPE_VIDEO_INLINE_QUERY_INFO_KHR = 1000515001,
// Provided by VK_NV_per_stage_descriptor_set
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PER_STAGE_DESCRIPTOR_SET_FEATURES_NV = 1000516000,
// Provided by VK_QCOM_image_processing2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_2_FEATURES_QCOM = 1000518000,
// Provided by VK_QCOM_image_processing2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_2_PROPERTIES_QCOM = 1000518001,
// Provided by VK_QCOM_image_processing2
VK_STRUCTURE_TYPE_SAMPLER_BLOCK_MATCH_WINDOW_CREATE_INFO_QCOM = 1000518002,
// Provided by VK_QCOM_filter_cubic_weights
VK_STRUCTURE_TYPE_SAMPLER_CUBIC_WEIGHTS_CREATE_INFO_QCOM = 1000519000,
// Provided by VK_QCOM_filter_cubic_weights
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUBIC_WEIGHTS_FEATURES_QCOM = 1000519001,
// Provided by VK_QCOM_filter_cubic_weights
VK_STRUCTURE_TYPE_BLIT_IMAGE_CUBIC_WEIGHTS_INFO_QCOM = 1000519002,
// Provided by VK_QCOM_ycbcr_degamma
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_DEGAMMA_FEATURES_QCOM = 1000520000,
// Provided by VK_QCOM_ycbcr_degamma
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_YCBCR_DEGAMMA_CREATE_INFO_QCOM = 1000520001,
// Provided by VK_QCOM_filter_cubic_clamp
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUBIC_CLAMP_FEATURES_QCOM = 1000521000,
// Provided by VK_EXT_attachment_feedback_loop_dynamic_state
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ATTACHMENT_FEEDBACK_LOOP_DYNAMIC_STATE_FEATURES_EXT = 1000524000,
// Provided by VK_KHR_unified_image_layouts
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFIED_IMAGE_LAYOUTS_FEATURES_KHR = 1000527000,
// Provided by VK_KHR_unified_image_layouts with VK_EXT_attachment_feedback_loop_layout and (VK_VERSION_1_3 or VK_KHR_dynamic_rendering)
VK_STRUCTURE_TYPE_ATTACHMENT_FEEDBACK_LOOP_INFO_EXT = 1000527001,
// Provided by VK_QNX_external_memory_screen_buffer
VK_STRUCTURE_TYPE_SCREEN_BUFFER_PROPERTIES_QNX = 1000529000,
// Provided by VK_QNX_external_memory_screen_buffer
VK_STRUCTURE_TYPE_SCREEN_BUFFER_FORMAT_PROPERTIES_QNX = 1000529001,
// Provided by VK_QNX_external_memory_screen_buffer
VK_STRUCTURE_TYPE_IMPORT_SCREEN_BUFFER_INFO_QNX = 1000529002,
// Provided by VK_QNX_external_memory_screen_buffer
VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_QNX = 1000529003,
// Provided by VK_QNX_external_memory_screen_buffer
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_SCREEN_BUFFER_FEATURES_QNX = 1000529004,
// Provided by VK_MSFT_layered_driver
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_DRIVER_PROPERTIES_MSFT = 1000530000,
// Provided by VK_KHR_calibrated_timestamps
VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_KHR = 1000184000,
// Provided by VK_KHR_maintenance6 with VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_SET_DESCRIPTOR_BUFFER_OFFSETS_INFO_EXT = 1000545007,
// Provided by VK_KHR_maintenance6 with VK_EXT_descriptor_buffer
VK_STRUCTURE_TYPE_BIND_DESCRIPTOR_BUFFER_EMBEDDED_SAMPLERS_INFO_EXT = 1000545008,
// Provided by VK_NV_descriptor_pool_overallocation
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_POOL_OVERALLOCATION_FEATURES_NV = 1000546000,
// Provided by VK_QCOM_tile_memory_heap
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_MEMORY_HEAP_FEATURES_QCOM = 1000547000,
// Provided by VK_QCOM_tile_memory_heap
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_MEMORY_HEAP_PROPERTIES_QCOM = 1000547001,
// Provided by VK_QCOM_tile_memory_heap
VK_STRUCTURE_TYPE_TILE_MEMORY_REQUIREMENTS_QCOM = 1000547002,
// Provided by VK_QCOM_tile_memory_heap
VK_STRUCTURE_TYPE_TILE_MEMORY_BIND_INFO_QCOM = 1000547003,
// Provided by VK_QCOM_tile_memory_heap with VK_QCOM_tile_properties
VK_STRUCTURE_TYPE_TILE_MEMORY_SIZE_INFO_QCOM = 1000547004,
// Provided by VK_NV_display_stereo
VK_STRUCTURE_TYPE_DISPLAY_SURFACE_STEREO_CREATE_INFO_NV = 1000551000,
// Provided by VK_NV_display_stereo
VK_STRUCTURE_TYPE_DISPLAY_MODE_STEREO_PROPERTIES_NV = 1000551001,
// Provided by VK_KHR_video_encode_intra_refresh
VK_STRUCTURE_TYPE_VIDEO_ENCODE_INTRA_REFRESH_CAPABILITIES_KHR = 1000552000,
// Provided by VK_KHR_video_encode_intra_refresh
VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_INTRA_REFRESH_CREATE_INFO_KHR = 1000552001,
// Provided by VK_KHR_video_encode_intra_refresh
VK_STRUCTURE_TYPE_VIDEO_ENCODE_INTRA_REFRESH_INFO_KHR = 1000552002,
// Provided by VK_KHR_video_encode_intra_refresh
VK_STRUCTURE_TYPE_VIDEO_REFERENCE_INTRA_REFRESH_INFO_KHR = 1000552003,
// Provided by VK_KHR_video_encode_intra_refresh
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_INTRA_REFRESH_FEATURES_KHR = 1000552004,
// Provided by VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUANTIZATION_MAP_CAPABILITIES_KHR = 1000553000,
// Provided by VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_VIDEO_FORMAT_QUANTIZATION_MAP_PROPERTIES_KHR = 1000553001,
// Provided by VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUANTIZATION_MAP_INFO_KHR = 1000553002,
// Provided by VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUANTIZATION_MAP_SESSION_PARAMETERS_CREATE_INFO_KHR = 1000553005,
// Provided by VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_QUANTIZATION_MAP_FEATURES_KHR = 1000553009,
// Provided by VK_KHR_video_encode_h264 with VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_QUANTIZATION_MAP_CAPABILITIES_KHR = 1000553003,
// Provided by VK_KHR_video_encode_h265 with VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_QUANTIZATION_MAP_CAPABILITIES_KHR = 1000553004,
// Provided by VK_KHR_video_encode_h265 with VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_VIDEO_FORMAT_H265_QUANTIZATION_MAP_PROPERTIES_KHR = 1000553006,
// Provided by VK_KHR_video_encode_av1 with VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_QUANTIZATION_MAP_CAPABILITIES_KHR = 1000553007,
// Provided by VK_KHR_video_encode_av1 with VK_KHR_video_encode_quantization_map
VK_STRUCTURE_TYPE_VIDEO_FORMAT_AV1_QUANTIZATION_MAP_PROPERTIES_KHR = 1000553008,
// Provided by VK_NV_raw_access_chains
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAW_ACCESS_CHAINS_FEATURES_NV = 1000555000,
// Provided by VK_NV_external_compute_queue
VK_STRUCTURE_TYPE_EXTERNAL_COMPUTE_QUEUE_DEVICE_CREATE_INFO_NV = 1000556000,
// Provided by VK_NV_external_compute_queue
VK_STRUCTURE_TYPE_EXTERNAL_COMPUTE_QUEUE_CREATE_INFO_NV = 1000556001,
// Provided by VK_NV_external_compute_queue
VK_STRUCTURE_TYPE_EXTERNAL_COMPUTE_QUEUE_DATA_PARAMS_NV = 1000556002,
// Provided by VK_NV_external_compute_queue
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_COMPUTE_QUEUE_PROPERTIES_NV = 1000556003,
// Provided by VK_KHR_shader_relaxed_extended_instruction
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_RELAXED_EXTENDED_INSTRUCTION_FEATURES_KHR = 1000558000,
// Provided by VK_NV_command_buffer_inheritance
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMMAND_BUFFER_INHERITANCE_FEATURES_NV = 1000559000,
// Provided by VK_KHR_maintenance7
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_7_FEATURES_KHR = 1000562000,
// Provided by VK_KHR_maintenance7
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_7_PROPERTIES_KHR = 1000562001,
// Provided by VK_KHR_maintenance7
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_API_PROPERTIES_LIST_KHR = 1000562002,
// Provided by VK_KHR_maintenance7
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_API_PROPERTIES_KHR = 1000562003,
// Provided by VK_KHR_maintenance7
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_API_VULKAN_PROPERTIES_KHR = 1000562004,
// Provided by VK_NV_shader_atomic_float16_vector
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT16_VECTOR_FEATURES_NV = 1000563000,
// Provided by VK_EXT_shader_replicated_composites
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_REPLICATED_COMPOSITES_FEATURES_EXT = 1000564000,
// Provided by VK_EXT_shader_float8
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT8_FEATURES_EXT = 1000567000,
// Provided by VK_NV_ray_tracing_validation
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_VALIDATION_FEATURES_NV = 1000568000,
// Provided by VK_NV_cluster_acceleration_structure
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_ACCELERATION_STRUCTURE_FEATURES_NV = 1000569000,
// Provided by VK_NV_cluster_acceleration_structure
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_ACCELERATION_STRUCTURE_PROPERTIES_NV = 1000569001,
// Provided by VK_NV_cluster_acceleration_structure
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_CLUSTERS_BOTTOM_LEVEL_INPUT_NV = 1000569002,
// Provided by VK_NV_cluster_acceleration_structure
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_TRIANGLE_CLUSTER_INPUT_NV = 1000569003,
// Provided by VK_NV_cluster_acceleration_structure
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_MOVE_OBJECTS_INPUT_NV = 1000569004,
// Provided by VK_NV_cluster_acceleration_structure
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_INPUT_INFO_NV = 1000569005,
// Provided by VK_NV_cluster_acceleration_structure
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_COMMANDS_INFO_NV = 1000569006,
// Provided by VK_NV_cluster_acceleration_structure
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CLUSTER_ACCELERATION_STRUCTURE_CREATE_INFO_NV = 1000569007,
// Provided by VK_NV_partitioned_acceleration_structure
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PARTITIONED_ACCELERATION_STRUCTURE_FEATURES_NV = 1000570000,
// Provided by VK_NV_partitioned_acceleration_structure
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PARTITIONED_ACCELERATION_STRUCTURE_PROPERTIES_NV = 1000570001,
// Provided by VK_NV_partitioned_acceleration_structure
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_PARTITIONED_ACCELERATION_STRUCTURE_NV = 1000570002,
// Provided by VK_NV_partitioned_acceleration_structure
VK_STRUCTURE_TYPE_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCES_INPUT_NV = 1000570003,
// Provided by VK_NV_partitioned_acceleration_structure
VK_STRUCTURE_TYPE_BUILD_PARTITIONED_ACCELERATION_STRUCTURE_INFO_NV = 1000570004,
// Provided by VK_NV_partitioned_acceleration_structure
VK_STRUCTURE_TYPE_PARTITIONED_ACCELERATION_STRUCTURE_FLAGS_NV = 1000570005,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_FEATURES_EXT = 1000572000,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_PROPERTIES_EXT = 1000572001,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_MEMORY_REQUIREMENTS_INFO_EXT = 1000572002,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_CREATE_INFO_EXT = 1000572003,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_INFO_EXT = 1000572004,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_CREATE_INFO_EXT = 1000572006,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_TOKEN_EXT = 1000572007,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_WRITE_INDIRECT_EXECUTION_SET_PIPELINE_EXT = 1000572008,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_WRITE_INDIRECT_EXECUTION_SET_SHADER_EXT = 1000572009,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_PIPELINE_INFO_EXT = 1000572010,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_SHADER_INFO_EXT = 1000572011,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_SHADER_LAYOUT_INFO_EXT = 1000572012,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_PIPELINE_INFO_EXT = 1000572013,
// Provided by VK_EXT_device_generated_commands
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_SHADER_INFO_EXT = 1000572014,
// Provided by VK_KHR_maintenance8
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_8_FEATURES_KHR = 1000574000,
// Provided by VK_KHR_maintenance8
VK_STRUCTURE_TYPE_MEMORY_BARRIER_ACCESS_FLAGS_3_KHR = 1000574002,
// Provided by VK_MESA_image_alignment_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ALIGNMENT_CONTROL_FEATURES_MESA = 1000575000,
// Provided by VK_MESA_image_alignment_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ALIGNMENT_CONTROL_PROPERTIES_MESA = 1000575001,
// Provided by VK_MESA_image_alignment_control
VK_STRUCTURE_TYPE_IMAGE_ALIGNMENT_CONTROL_CREATE_INFO_MESA = 1000575002,
// Provided by VK_EXT_depth_clamp_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLAMP_CONTROL_FEATURES_EXT = 1000582000,
// Provided by VK_EXT_depth_clamp_control
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_DEPTH_CLAMP_CONTROL_CREATE_INFO_EXT = 1000582001,
// Provided by VK_KHR_maintenance9
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_9_FEATURES_KHR = 1000584000,
// Provided by VK_KHR_maintenance9
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_9_PROPERTIES_KHR = 1000584001,
// Provided by VK_KHR_maintenance9
VK_STRUCTURE_TYPE_QUEUE_FAMILY_OWNERSHIP_TRANSFER_PROPERTIES_KHR = 1000584002,
// Provided by VK_KHR_video_maintenance2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_MAINTENANCE_2_FEATURES_KHR = 1000586000,
// Provided by VK_KHR_video_decode_h264 with VK_KHR_video_maintenance2
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_INLINE_SESSION_PARAMETERS_INFO_KHR = 1000586001,
// Provided by VK_KHR_video_decode_h265 with VK_KHR_video_maintenance2
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_INLINE_SESSION_PARAMETERS_INFO_KHR = 1000586002,
// Provided by VK_KHR_video_decode_av1 with VK_KHR_video_maintenance2
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_INLINE_SESSION_PARAMETERS_INFO_KHR = 1000586003,
// Provided by VK_OHOS_surface
VK_STRUCTURE_TYPE_OH_SURFACE_CREATE_INFO_OHOS = 1000587000,
// Provided by VK_HUAWEI_hdr_vivid
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HDR_VIVID_FEATURES_HUAWEI = 1000590000,
// Provided by VK_HUAWEI_hdr_vivid
VK_STRUCTURE_TYPE_HDR_VIVID_DYNAMIC_METADATA_HUAWEI = 1000590001,
// Provided by VK_NV_cooperative_matrix2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_2_FEATURES_NV = 1000593000,
// Provided by VK_NV_cooperative_matrix2
VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_FLEXIBLE_DIMENSIONS_PROPERTIES_NV = 1000593001,
// Provided by VK_NV_cooperative_matrix2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_2_PROPERTIES_NV = 1000593002,
// Provided by VK_ARM_pipeline_opacity_micromap
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_OPACITY_MICROMAP_FEATURES_ARM = 1000596000,
// Provided by VK_EXT_external_memory_metal
VK_STRUCTURE_TYPE_IMPORT_MEMORY_METAL_HANDLE_INFO_EXT = 1000602000,
// Provided by VK_EXT_external_memory_metal
VK_STRUCTURE_TYPE_MEMORY_METAL_HANDLE_PROPERTIES_EXT = 1000602001,
// Provided by VK_EXT_external_memory_metal
VK_STRUCTURE_TYPE_MEMORY_GET_METAL_HANDLE_INFO_EXT = 1000602002,
// Provided by VK_KHR_depth_clamp_zero_one
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLAMP_ZERO_ONE_FEATURES_KHR = 1000421000,
// Provided by VK_EXT_vertex_attribute_robustness
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_ROBUSTNESS_FEATURES_EXT = 1000608000,
// Provided by VK_ARM_format_pack
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FORMAT_PACK_FEATURES_ARM = 1000609000,
// Provided by VK_VALVE_fragment_density_map_layered
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_LAYERED_FEATURES_VALVE = 1000611000,
// Provided by VK_VALVE_fragment_density_map_layered
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_LAYERED_PROPERTIES_VALVE = 1000611001,
// Provided by VK_VALVE_fragment_density_map_layered
VK_STRUCTURE_TYPE_PIPELINE_FRAGMENT_DENSITY_MAP_LAYERED_CREATE_INFO_VALVE = 1000611002,
// Provided by VK_KHR_robustness2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_FEATURES_KHR = 1000286000,
// Provided by VK_KHR_robustness2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_PROPERTIES_KHR = 1000286001,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_present_metering
VK_STRUCTURE_TYPE_SET_PRESENT_CONFIG_NV = 1000613000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_present_metering
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_METERING_FEATURES_NV = 1000613001,
#endif
// Provided by VK_EXT_fragment_density_map_offset
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_FEATURES_EXT = 1000425000,
// Provided by VK_EXT_fragment_density_map_offset
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_PROPERTIES_EXT = 1000425001,
// Provided by VK_EXT_fragment_density_map_offset
VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_OFFSET_END_INFO_EXT = 1000425002,
// Provided by VK_EXT_fragment_density_map_offset
VK_STRUCTURE_TYPE_RENDERING_END_INFO_EXT = 1000619003,
// Provided by VK_EXT_zero_initialize_device_memory
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_DEVICE_MEMORY_FEATURES_EXT = 1000620000,
// Provided by VK_KHR_present_mode_fifo_latest_ready
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_MODE_FIFO_LATEST_READY_FEATURES_KHR = 1000361000,
// Provided by VK_SEC_pipeline_cache_incremental_mode
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CACHE_INCREMENTAL_MODE_FEATURES_SEC = 1000637000,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES,
// Provided by VK_VERSION_1_1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETER_FEATURES = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETERS_FEATURES,
// Provided by VK_EXT_debug_report
// VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT is a deprecated alias
VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT,
// Provided by VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_RENDERING_INFO_KHR = VK_STRUCTURE_TYPE_RENDERING_INFO,
// Provided by VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO_KHR = VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO,
// Provided by VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO,
// Provided by VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES,
// Provided by VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO_KHR = VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_RENDERING_INFO,
// Provided by VK_KHR_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_EXT_pipeline_robustness
VK_STRUCTURE_TYPE_PIPELINE_ROBUSTNESS_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_ROBUSTNESS_CREATE_INFO,
// Provided by VK_EXT_pipeline_robustness
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_FEATURES,
// Provided by VK_EXT_pipeline_robustness
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_PROPERTIES,
// 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_push_descriptor
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES,
// Provided by VK_KHR_shader_float16_int8
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES,
// Provided by VK_KHR_shader_float16_int8
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT16_INT8_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT16_INT8_FEATURES,
// Provided by VK_KHR_16bit_storage
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_16BIT_STORAGE_FEATURES,
// Provided by VK_KHR_descriptor_update_template
VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO,
// Provided by VK_EXT_display_surface_counter
// VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES2_EXT is a deprecated alias
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES2_EXT = VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_EXT,
// Provided by VK_KHR_imageless_framebuffer
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGELESS_FRAMEBUFFER_FEATURES,
// Provided by VK_KHR_imageless_framebuffer
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO,
// Provided by VK_KHR_imageless_framebuffer
VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO_KHR = VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO,
// Provided by VK_KHR_imageless_framebuffer
VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO_KHR = VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO,
// Provided by VK_KHR_create_renderpass2
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2_KHR = VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2,
// Provided by VK_KHR_create_renderpass2
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2_KHR = VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2,
// Provided by VK_KHR_create_renderpass2
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2_KHR = VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2,
// Provided by VK_KHR_create_renderpass2
VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2_KHR = VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2,
// Provided by VK_KHR_create_renderpass2
VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2_KHR = VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2,
// Provided by VK_KHR_create_renderpass2
VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO_KHR = VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO,
// Provided by VK_KHR_create_renderpass2
VK_STRUCTURE_TYPE_SUBPASS_END_INFO_KHR = VK_STRUCTURE_TYPE_SUBPASS_END_INFO,
// Provided by VK_KHR_external_fence_capabilities
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO,
// Provided by VK_KHR_external_fence_capabilities
VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES_KHR = VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES,
// Provided by VK_KHR_external_fence
VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO,
// Provided by VK_KHR_maintenance2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES,
// Provided by VK_KHR_maintenance2
VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO,
// Provided by VK_KHR_maintenance2
VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO,
// Provided by VK_KHR_maintenance2
VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO,
// Provided by VK_KHR_variable_pointers
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES,
// Provided by VK_KHR_variable_pointers
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES_KHR,
// Provided by VK_KHR_dedicated_allocation
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS_KHR = VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS,
// Provided by VK_KHR_dedicated_allocation
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_KHR = VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO,
// Provided by VK_EXT_sampler_filter_minmax
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES,
// Provided by VK_EXT_sampler_filter_minmax
VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO,
// Provided by VK_EXT_inline_uniform_block
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES,
// Provided by VK_EXT_inline_uniform_block
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES,
// Provided by VK_EXT_inline_uniform_block
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK_EXT = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK,
// Provided by VK_EXT_inline_uniform_block
VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO,
// Provided by VK_KHR_get_memory_requirements2
VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2_KHR = VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2,
// Provided by VK_KHR_get_memory_requirements2
VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2_KHR = VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2,
// Provided by VK_KHR_get_memory_requirements2
VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2_KHR = VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2,
// Provided by VK_KHR_get_memory_requirements2
VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2_KHR = VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2,
// Provided by VK_KHR_get_memory_requirements2
VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2_KHR = VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2,
// Provided by VK_KHR_image_format_list
VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO,
// Provided by VK_NV_framebuffer_mixed_samples with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_NV = VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_AMD,
// 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,
// Provided by VK_KHR_shader_subgroup_extended_types
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_EXTENDED_TYPES_FEATURES,
// Provided by VK_KHR_8bit_storage
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_8BIT_STORAGE_FEATURES,
// Provided by VK_KHR_shader_atomic_int64
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES,
// Provided by VK_EXT_calibrated_timestamps
VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT = VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_KHR,
// Provided by VK_KHR_global_priority
VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO,
// Provided by VK_KHR_global_priority
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GLOBAL_PRIORITY_QUERY_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GLOBAL_PRIORITY_QUERY_FEATURES,
// Provided by VK_KHR_global_priority
VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES_KHR = VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES,
// Provided by VK_EXT_vertex_attribute_divisor
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO,
// Provided by VK_EXT_vertex_attribute_divisor
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES,
// Provided by VK_EXT_pipeline_creation_feedback
VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO,
// Provided by VK_KHR_driver_properties
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES,
// Provided by VK_KHR_shader_float_controls
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES,
// Provided by VK_KHR_depth_stencil_resolve
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_STENCIL_RESOLVE_PROPERTIES,
// Provided by VK_KHR_depth_stencil_resolve
VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE_KHR = VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE,
// Provided by VK_NV_compute_shader_derivatives
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_NV = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_KHR,
// Provided by VK_NV_fragment_shader_barycentric
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_NV = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_BARYCENTRIC_FEATURES_KHR,
// Provided by VK_KHR_timeline_semaphore
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES,
// Provided by VK_KHR_timeline_semaphore
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES,
// Provided by VK_KHR_timeline_semaphore
VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO,
// Provided by VK_KHR_timeline_semaphore
VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO_KHR = VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO,
// Provided by VK_KHR_timeline_semaphore
VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO_KHR = VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO,
// Provided by VK_KHR_timeline_semaphore
VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO_KHR = VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO,
// Provided by VK_INTEL_performance_query
// VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL is a deprecated alias
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL = VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_QUERY_CREATE_INFO_INTEL,
// Provided by VK_KHR_vulkan_memory_model
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES,
// Provided by VK_KHR_shader_terminate_invocation
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES,
// Provided by VK_EXT_scalar_block_layout
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCALAR_BLOCK_LAYOUT_FEATURES,
// Provided by VK_EXT_subgroup_size_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES,
// Provided by VK_EXT_subgroup_size_control
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO,
// Provided by VK_EXT_subgroup_size_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES,
// Provided by VK_KHR_dynamic_rendering_local_read
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_LOCAL_READ_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_LOCAL_READ_FEATURES,
// Provided by VK_KHR_dynamic_rendering_local_read
VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_LOCATION_INFO_KHR = VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_LOCATION_INFO,
// Provided by VK_KHR_dynamic_rendering_local_read
VK_STRUCTURE_TYPE_RENDERING_INPUT_ATTACHMENT_INDEX_INFO_KHR = VK_STRUCTURE_TYPE_RENDERING_INPUT_ATTACHMENT_INDEX_INFO,
// Provided by VK_KHR_separate_depth_stencil_layouts
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES,
// Provided by VK_KHR_separate_depth_stencil_layouts
VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT_KHR = VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT,
// Provided by VK_KHR_separate_depth_stencil_layouts
VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT_KHR = VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT,
// Provided by VK_EXT_buffer_device_address
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_ADDRESS_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT,
// Provided by VK_EXT_buffer_device_address
VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO_EXT = VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO,
// Provided by VK_EXT_tooling_info
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES,
// Provided by VK_EXT_separate_stencil_usage
VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO,
// Provided by VK_KHR_uniform_buffer_standard_layout
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFORM_BUFFER_STANDARD_LAYOUT_FEATURES,
// Provided by VK_KHR_buffer_device_address
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES,
// Provided by VK_KHR_buffer_device_address
VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO_KHR = VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO,
// Provided by VK_KHR_buffer_device_address
VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO,
// Provided by VK_KHR_buffer_device_address
VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO_KHR = VK_STRUCTURE_TYPE_MEMORY_OPAQUE_CAPTURE_ADDRESS_ALLOCATE_INFO,
// Provided by VK_KHR_buffer_device_address
VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO_KHR = VK_STRUCTURE_TYPE_DEVICE_MEMORY_OPAQUE_CAPTURE_ADDRESS_INFO,
// Provided by VK_EXT_line_rasterization
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES,
// Provided by VK_EXT_line_rasterization
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO,
// Provided by VK_EXT_line_rasterization
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES,
// Provided by VK_EXT_host_query_reset
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_QUERY_RESET_FEATURES,
// Provided by VK_EXT_index_type_uint8
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY_EXT = VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY_EXT = VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO_EXT = VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO_EXT = VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO_EXT = VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO_EXT = VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE_EXT = VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE,
// Provided by VK_EXT_host_image_copy
VK_STRUCTURE_TYPE_HOST_IMAGE_COPY_DEVICE_PERFORMANCE_QUERY_EXT = VK_STRUCTURE_TYPE_HOST_IMAGE_COPY_DEVICE_PERFORMANCE_QUERY,
// Provided by VK_KHR_map_memory2
VK_STRUCTURE_TYPE_MEMORY_MAP_INFO_KHR = VK_STRUCTURE_TYPE_MEMORY_MAP_INFO,
// Provided by VK_KHR_map_memory2
VK_STRUCTURE_TYPE_MEMORY_UNMAP_INFO_KHR = VK_STRUCTURE_TYPE_MEMORY_UNMAP_INFO,
// Provided by VK_EXT_surface_maintenance1
VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_EXT = VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_KHR,
// Provided by VK_EXT_surface_maintenance1
VK_STRUCTURE_TYPE_SURFACE_PRESENT_SCALING_CAPABILITIES_EXT = VK_STRUCTURE_TYPE_SURFACE_PRESENT_SCALING_CAPABILITIES_KHR,
// Provided by VK_EXT_surface_maintenance1
VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_COMPATIBILITY_EXT = VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_COMPATIBILITY_KHR,
// Provided by VK_EXT_swapchain_maintenance1
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SWAPCHAIN_MAINTENANCE_1_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SWAPCHAIN_MAINTENANCE_1_FEATURES_KHR,
// Provided by VK_EXT_swapchain_maintenance1
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_FENCE_INFO_EXT = VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_FENCE_INFO_KHR,
// Provided by VK_EXT_swapchain_maintenance1
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODES_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODES_CREATE_INFO_KHR,
// Provided by VK_EXT_swapchain_maintenance1
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODE_INFO_EXT = VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODE_INFO_KHR,
// Provided by VK_EXT_swapchain_maintenance1
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_SCALING_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_SCALING_CREATE_INFO_KHR,
// Provided by VK_EXT_swapchain_maintenance1
VK_STRUCTURE_TYPE_RELEASE_SWAPCHAIN_IMAGES_INFO_EXT = VK_STRUCTURE_TYPE_RELEASE_SWAPCHAIN_IMAGES_INFO_KHR,
// Provided by VK_EXT_shader_demote_to_helper_invocation
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES,
// Provided by VK_KHR_shader_integer_dot_product
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_FEATURES,
// Provided by VK_KHR_shader_integer_dot_product
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_INTEGER_DOT_PRODUCT_PROPERTIES,
// Provided by VK_EXT_texel_buffer_alignment
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES,
// Provided by VK_EXT_robustness2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_FEATURES_KHR,
// Provided by VK_EXT_robustness2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_PROPERTIES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_PROPERTIES_KHR,
// Provided by VK_EXT_private_data
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES,
// Provided by VK_EXT_private_data
VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO,
// Provided by VK_EXT_private_data
VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO,
// Provided by VK_EXT_pipeline_creation_cache_control
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES,
// Provided by VK_KHR_synchronization2
VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR = VK_STRUCTURE_TYPE_MEMORY_BARRIER_2,
// Provided by VK_KHR_synchronization2
VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2_KHR = VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2,
// Provided by VK_KHR_synchronization2
VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2_KHR = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2,
// Provided by VK_KHR_synchronization2
VK_STRUCTURE_TYPE_DEPENDENCY_INFO_KHR = VK_STRUCTURE_TYPE_DEPENDENCY_INFO,
// Provided by VK_KHR_synchronization2
VK_STRUCTURE_TYPE_SUBMIT_INFO_2_KHR = VK_STRUCTURE_TYPE_SUBMIT_INFO_2,
// Provided by VK_KHR_synchronization2
VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO_KHR = VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO,
// Provided by VK_KHR_synchronization2
VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO_KHR = VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO,
// Provided by VK_KHR_synchronization2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES,
// Provided by VK_KHR_zero_initialize_workgroup_memory
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES,
// Provided by VK_EXT_image_robustness
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2_KHR = VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2_KHR = VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2_KHR = VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2_KHR = VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2_KHR = VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2_KHR = VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_BUFFER_COPY_2_KHR = VK_STRUCTURE_TYPE_BUFFER_COPY_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_IMAGE_COPY_2_KHR = VK_STRUCTURE_TYPE_IMAGE_COPY_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_IMAGE_BLIT_2_KHR = VK_STRUCTURE_TYPE_IMAGE_BLIT_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2_KHR = VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2,
// Provided by VK_KHR_copy_commands2
VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2_KHR = VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2,
// Provided by VK_EXT_image_compression_control
VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_EXT = VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2,
// Provided by VK_EXT_image_compression_control
VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_EXT = VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_FEATURES_ARM = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_FEATURES_EXT,
// Provided by VK_VALVE_mutable_descriptor_type
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MUTABLE_DESCRIPTOR_TYPE_FEATURES_VALVE = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MUTABLE_DESCRIPTOR_TYPE_FEATURES_EXT,
// Provided by VK_VALVE_mutable_descriptor_type
VK_STRUCTURE_TYPE_MUTABLE_DESCRIPTOR_TYPE_CREATE_INFO_VALVE = VK_STRUCTURE_TYPE_MUTABLE_DESCRIPTOR_TYPE_CREATE_INFO_EXT,
// Provided by VK_KHR_format_feature_flags2
VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3_KHR = VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3,
// Provided by VK_EXT_present_mode_fifo_latest_ready
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_MODE_FIFO_LATEST_READY_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_MODE_FIFO_LATEST_READY_FEATURES_KHR,
// 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,
// Provided by VK_EXT_global_priority_query
VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES_EXT = VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES,
// Provided by VK_KHR_maintenance4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_FEATURES,
// Provided by VK_KHR_maintenance4
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_4_PROPERTIES,
// Provided by VK_KHR_maintenance4
VK_STRUCTURE_TYPE_DEVICE_BUFFER_MEMORY_REQUIREMENTS_KHR = VK_STRUCTURE_TYPE_DEVICE_BUFFER_MEMORY_REQUIREMENTS,
// Provided by VK_KHR_maintenance4
VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS_KHR = VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS,
// Provided by VK_KHR_shader_subgroup_rotate
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_ROTATE_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_ROTATE_FEATURES,
// Provided by VK_EXT_depth_clamp_zero_one
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLAMP_ZERO_ONE_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLAMP_ZERO_ONE_FEATURES_KHR,
// Provided by VK_QCOM_fragment_density_map_offset
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_FEATURES_QCOM = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_FEATURES_EXT,
// Provided by VK_QCOM_fragment_density_map_offset
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_PROPERTIES_QCOM = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_PROPERTIES_EXT,
// Provided by VK_QCOM_fragment_density_map_offset
VK_STRUCTURE_TYPE_SUBPASS_FRAGMENT_DENSITY_MAP_OFFSET_END_INFO_QCOM = VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_OFFSET_END_INFO_EXT,
// Provided by VK_EXT_pipeline_protected_access
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_PROTECTED_ACCESS_FEATURES_EXT = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_PROTECTED_ACCESS_FEATURES,
// Provided by VK_KHR_maintenance5
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_FEATURES,
// Provided by VK_KHR_maintenance5
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_PROPERTIES,
// Provided by VK_KHR_maintenance5
VK_STRUCTURE_TYPE_RENDERING_AREA_INFO_KHR = VK_STRUCTURE_TYPE_RENDERING_AREA_INFO,
// Provided by VK_KHR_maintenance5
VK_STRUCTURE_TYPE_DEVICE_IMAGE_SUBRESOURCE_INFO_KHR = VK_STRUCTURE_TYPE_DEVICE_IMAGE_SUBRESOURCE_INFO,
// Provided by VK_KHR_maintenance5
VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_KHR = VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2,
// Provided by VK_KHR_maintenance5
VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_KHR = VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2,
// Provided by VK_KHR_maintenance5
VK_STRUCTURE_TYPE_PIPELINE_CREATE_FLAGS_2_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_PIPELINE_CREATE_FLAGS_2_CREATE_INFO,
// Provided by VK_KHR_maintenance5
VK_STRUCTURE_TYPE_BUFFER_USAGE_FLAGS_2_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_BUFFER_USAGE_FLAGS_2_CREATE_INFO,
// Provided by VK_EXT_shader_object
VK_STRUCTURE_TYPE_SHADER_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO,
// Provided by VK_KHR_vertex_attribute_divisor
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES,
// Provided by VK_KHR_vertex_attribute_divisor
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO,
// Provided by VK_KHR_vertex_attribute_divisor
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES,
// Provided by VK_KHR_shader_float_controls2
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT_CONTROLS_2_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT_CONTROLS_2_FEATURES,
// Provided by VK_KHR_index_type_uint8
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES,
// Provided by VK_KHR_line_rasterization
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES,
// Provided by VK_KHR_line_rasterization
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO,
// Provided by VK_KHR_line_rasterization
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES,
// Provided by VK_KHR_shader_expect_assume
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_EXPECT_ASSUME_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_EXPECT_ASSUME_FEATURES,
// Provided by VK_KHR_maintenance6
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_FEATURES,
// Provided by VK_KHR_maintenance6
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_PROPERTIES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_PROPERTIES,
// Provided by VK_KHR_maintenance6
VK_STRUCTURE_TYPE_BIND_MEMORY_STATUS_KHR = VK_STRUCTURE_TYPE_BIND_MEMORY_STATUS,
// Provided by VK_KHR_maintenance6
VK_STRUCTURE_TYPE_BIND_DESCRIPTOR_SETS_INFO_KHR = VK_STRUCTURE_TYPE_BIND_DESCRIPTOR_SETS_INFO,
// Provided by VK_KHR_maintenance6
VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO_KHR = VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO,
// Provided by VK_KHR_maintenance6 with VK_KHR_push_descriptor
VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_INFO_KHR = VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_INFO,
// Provided by VK_KHR_maintenance6 with VK_KHR_push_descriptor
VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_WITH_TEMPLATE_INFO_KHR = VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_WITH_TEMPLATE_INFO,
} VkStructureType;
3.13. API Name Aliases
A small number of APIs did not follow the naming conventions when initially defined. For consistency, when we discover an API name that violates the naming conventions, we rename it in the Specification, XML, and header files. For backwards compatibility, the original (incorrect) name is retained as a “typo alias”. The alias is deprecated and should not be used, but will be retained indefinitely.
|
Note
|
|
4. Initialization
Before using Vulkan, an application must initialize it by loading the
Vulkan commands, and creating a VkInstance object.
4.1. Command Function Pointers
Vulkan commands are not necessarily exposed by static linking on a platform. Commands to query function pointers for Vulkan commands are described below.
|
Note
|
When extensions are promoted or otherwise incorporated into another extension or Vulkan core version, command aliases may be included. Whilst the behavior of each command alias is identical, the behavior of retrieving each alias’s function pointer is not. A function pointer for a given alias can only be retrieved if the extension or version that introduced that alias is supported and enabled, irrespective of whether any other alias is available. |
Function pointers for all Vulkan commands can be obtained by calling:
// Provided by VK_VERSION_1_0
PFN_vkVoidFunction vkGetInstanceProcAddr(
VkInstance instance,
const char* pName);
-
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 by calling:
// Provided by VK_VERSION_1_0
PFN_vkVoidFunction vkGetDeviceProcAddr(
VkDevice device,
const char* pName);
The table below defines the various use cases for vkGetDeviceProcAddr
and expected return value (“fp” is “function pointer”) for each case.
A valid returned function pointer (“fp”) must not be NULL.
The returned function pointer is of type PFN_vkVoidFunction, and must
be cast to the type of the command being queried before use.
The function pointer must only be called with a dispatchable object (the
first parameter) that is device or a child of device.
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. If themaintenance5feature is enabled, core commands beyond that version which are supported by the implementation will returnNULL, otherwise the implementation may either returnNULLor a function pointer. If a function pointer is returned, it must not be called. - 3
-
In this function, device-level excludes all physical-device-level commands.
- 4
-
The returned function pointer must only be called with a dispatchable object (the first parameter) that is
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 both
VkPhysicalDeviceProperties::apiVersion and
VkApplicationInfo::apiVersion are greater than or equal to the
version of Vulkan that added the new functionality.
The Vulkan version supported by a physical device can be obtained by
calling vkGetPhysicalDeviceProperties.
4.1.2. Extending Physical Device From Device Extensions
When the VK_KHR_get_physical_device_properties2 extension is
enabled,
or when both the instance and the physical-device versions are at least 1.1,
physical-device-level functionality of a device extension can be used with
a physical device if the corresponding extension is enumerated by
vkEnumerateDeviceExtensionProperties for that physical device, even
before a logical device has been created.
To obtain a function pointer for a physical-device-level command from a
device extension, an application can use vkGetInstanceProcAddr.
This function pointer may point to dispatch code, which calls a different
real implementation for different VkPhysicalDevice objects.
Applications must not use a VkPhysicalDevice in any command added by
an extension or core version that is not supported by that physical device.
Device extensions may define structures that can be added to the
pNext chain of physical-device-level commands.
4.2. Instances
There is no global state in Vulkan and all per-application state is stored
in a VkInstance object.
Creating a VkInstance object initializes the Vulkan library and allows
the application to pass information about itself to the implementation.
Instances are represented by VkInstance handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkInstance)
To query the version of instance-level functionality supported by the implementation, call:
// Provided by VK_VERSION_1_1
VkResult vkEnumerateInstanceVersion(
uint32_t* pApiVersion);
-
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 behavior 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 a VkStructureType value identifying 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 chain of the VkInstanceCreateInfo structure passed
to vkCreateInstance.
This callback is only valid for the duration of the vkCreateInstance
and the vkDestroyInstance call.
Use
vkCreateDebugReportCallbackEXT
or
vkCreateDebugUtilsMessengerEXT
to create persistent callback objects.
An application can add additional drivers by including the
VkDirectDriverLoadingListLUNARG structure in the pNext chain of
the VkInstanceCreateInfo structure passed to vkCreateInstance.
|
Note
|
VkDirectDriverLoadingListLUNARG allows applications to ship drivers with themselves. Only drivers that are designed to work with it should be used, such as drivers that implement Vulkan in software or that implement Vulkan by translating it to a different API. Any driver that requires installation should not be used, such as hardware drivers. |
// Provided by VK_VERSION_1_0
typedef enum VkInstanceCreateFlagBits {
// Provided by VK_KHR_portability_enumeration
VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR = 0x00000001,
} VkInstanceCreateFlagBits;
-
VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_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 a VkStructureType value identifying 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 a VkStructureType value identifying 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, both runtime and standalone, is disabled. This validation occurs inside VkShaderCreateInfoEXT and VkShaderModuleCreateInfo. This feature is enabled by default. -
VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_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,VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXTis implied. -
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 |
To create a Vulkan instance with a specific configuration of layer settings,
add VkLayerSettingsCreateInfoEXT structures to the pNext chain
of the VkInstanceCreateInfo structure, specifying the settings to be
configured.
// Provided by VK_EXT_layer_settings
typedef struct VkLayerSettingsCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t settingCount;
const VkLayerSettingEXT* pSettings;
} VkLayerSettingsCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
settingCountis the number of settings to configure. -
pSettingsis a pointer to an array ofsettingCountVkLayerSettingEXT values specifying the settings to be configured.
The values of elements of the
VkLayerSettingsCreateInfoEXT::pSettings array, specifying layer
settings to be configured, are:
// Provided by VK_EXT_layer_settings
typedef struct VkLayerSettingEXT {
const char* pLayerName;
const char* pSettingName;
VkLayerSettingTypeEXT type;
uint32_t valueCount;
const void* pValues;
} VkLayerSettingEXT;
-
pLayerNameis a pointer to a null-terminated UTF-8 string naming the layer to configure the setting from. -
pSettingNameis a pointer to a null-terminated UTF-8 string naming the setting to configure. Values ofpSettingNamethat are unknown to the layer are ignored. -
typeis a VkLayerSettingTypeEXT value specifying the type of thepValuesvalues. -
valueCountis the number of values used to configure the layer setting. -
pValuesis a pointer to an array ofvalueCountvalues of the type indicated bytypeto configure the layer setting.
When multiple VkLayerSettingsCreateInfoEXT structures are chained and
the same pSettingName is referenced for the same pLayerName, the
value of the first reference of the layer setting is used.
Possible values of VkLayerSettingEXT::type, specifying the type
of the data returned in VkLayerSettingEXT::pValues, are:
// Provided by VK_EXT_layer_settings
typedef enum VkLayerSettingTypeEXT {
VK_LAYER_SETTING_TYPE_BOOL32_EXT = 0,
VK_LAYER_SETTING_TYPE_INT32_EXT = 1,
VK_LAYER_SETTING_TYPE_INT64_EXT = 2,
VK_LAYER_SETTING_TYPE_UINT32_EXT = 3,
VK_LAYER_SETTING_TYPE_UINT64_EXT = 4,
VK_LAYER_SETTING_TYPE_FLOAT32_EXT = 5,
VK_LAYER_SETTING_TYPE_FLOAT64_EXT = 6,
VK_LAYER_SETTING_TYPE_STRING_EXT = 7,
} VkLayerSettingTypeEXT;
-
VK_LAYER_SETTING_TYPE_BOOL32_EXTspecifies that the layer setting’s type is VkBool32. -
VK_LAYER_SETTING_TYPE_INT32_EXTspecifies that the layer setting’s type is signed 32-bit integer. -
VK_LAYER_SETTING_TYPE_INT64_EXTspecifies that the layer setting’s type is signed 64-bit integer. -
VK_LAYER_SETTING_TYPE_UINT32_EXTspecifies that the layer setting’s type is unsigned 32-bit integer. -
VK_LAYER_SETTING_TYPE_UINT64_EXTspecifies that the layer setting’s type is unsigned 64-bit integer. -
VK_LAYER_SETTING_TYPE_FLOAT32_EXTspecifies that the layer setting’s type is 32-bit floating-point. -
VK_LAYER_SETTING_TYPE_FLOAT64_EXTspecifies that the layer setting’s type is 64-bit floating-point. -
VK_LAYER_SETTING_TYPE_STRING_EXTspecifies that the layer setting’s type is a pointer to a null-terminated UTF-8 string.
The VkDirectDriverLoadingListLUNARG structure is defined as:
// Provided by VK_LUNARG_direct_driver_loading
typedef struct VkDirectDriverLoadingListLUNARG {
VkStructureType sType;
const void* pNext;
VkDirectDriverLoadingModeLUNARG mode;
uint32_t driverCount;
const VkDirectDriverLoadingInfoLUNARG* pDrivers;
} VkDirectDriverLoadingListLUNARG;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
modecontrols the mode in which to load the provided drivers. -
driverCountis the number of driver manifest paths. -
pDriversis a pointer to an array ofdriverCountVkDirectDriverLoadingInfoLUNARG structures.
When creating a Vulkan instance for which additional drivers are to be
included, add a VkDirectDriverLoadingListLUNARG structure to the pNext
chain of the VkInstanceCreateInfo structure, and include in it the
list of VkDirectDriverLoadingInfoLUNARG structures which contain the
information necessary to load additional drivers.
The VkDirectDriverLoadingInfoLUNARG structure is defined as:
// Provided by VK_LUNARG_direct_driver_loading
typedef struct VkDirectDriverLoadingInfoLUNARG {
VkStructureType sType;
void* pNext;
VkDirectDriverLoadingFlagsLUNARG flags;
PFN_vkGetInstanceProcAddrLUNARG pfnGetInstanceProcAddr;
} VkDirectDriverLoadingInfoLUNARG;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
pfnGetInstanceProcAddris a PFN_vkGetInstanceProcAddrLUNARG pointer to the driver vkGetInstanceProcAddr function.
Possible values of VkDirectDriverLoadingListLUNARG::mode,
specifying the mode in which drivers are used, are:
// Provided by VK_LUNARG_direct_driver_loading
typedef enum VkDirectDriverLoadingModeLUNARG {
VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG = 0,
VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG = 1,
} VkDirectDriverLoadingModeLUNARG;
-
VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARGspecifies that the provided drivers are used instead of the system-loaded drivers. -
VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARGspecifies that the provided drivers are used in addition to the system-loaded drivers.
// Provided by VK_LUNARG_direct_driver_loading
typedef VkFlags VkDirectDriverLoadingFlagsLUNARG;
VkDirectDriverLoadingFlagsLUNARG is a bitmask type for setting a mask,
but is currently reserved for future use.
The type of PFN_vkGetInstanceProcAddrLUNARG is:
// Provided by VK_LUNARG_direct_driver_loading
typedef PFN_vkVoidFunction (VKAPI_PTR *PFN_vkGetInstanceProcAddrLUNARG)(
VkInstance instance, const char* pName);
-
instanceis a VkInstance handle. -
pNameis the name of a Vulkan command.
This type is compatible with the type of a pointer to the
vkGetInstanceProcAddr command, but is used only to specify device
driver addresses in
VkDirectDriverLoadingInfoLUNARG::pfnGetInstanceProcAddr.
|
Note
|
This type exists only because of limitations in the XML schema and
processing scripts, and its name may change in the future.
Ideally we would use the |
The VkApplicationInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkApplicationInfo {
VkStructureType sType;
const void* pNext;
const char* pApplicationName;
uint32_t applicationVersion;
const char* pEngineName;
uint32_t engineVersion;
uint32_t apiVersion;
} VkApplicationInfo;
-
sTypeis a VkStructureType value identifying 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. The variant version of the instance must match that requested inapiVersion.
Vulkan 1.0 implementations were required to return
VK_ERROR_INCOMPATIBLE_DRIVER if apiVersion was larger than 1.0.
Implementations that support Vulkan 1.1 or later must not return
VK_ERROR_INCOMPATIBLE_DRIVER for any value of apiVersion
.
|
Note
|
Because Vulkan 1.0 implementations may fail with
|
As long as the instance supports at least Vulkan 1.1, an application can use different versions of Vulkan with an instance than it does with a device or physical device.
|
Note
|
The Khronos validation layers will treat For example, if the instance supports Vulkan 1.1 and three physical devices
support Vulkan 1.0, Vulkan 1.1, and Vulkan 1.2, respectively, and if the
application sets
If we modify the above example so that the application sets |
|
Note
|
Providing a |
To destroy an instance, call:
// Provided by VK_VERSION_1_0
void vkDestroyInstance(
VkInstance instance,
const VkAllocationCallbacks* pAllocator);
-
instanceis the handle of the instance to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
Prior to destroying an instance, an application is responsible for
destroying/freeing any Vulkan objects with explicit vkDestroy* or
vkFree* commands that were created using that instance, or any
VkPhysicalDevice object retrieved from it, as the first parameter of
the corresponding vkCreate* or vkAllocate* command.
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 cannot be independently destroyed, and are instead destroyed with the VkInstance that they were retrieved from.
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
application to the number of elements in the pPhysicalDevices array,
and on return the variable is overwritten with the number of handles
actually written to pPhysicalDevices.
If pPhysicalDeviceCount is less than the number of physical devices
available, at most pPhysicalDeviceCount structures will be written,
and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to
indicate that not all the available physical devices were returned.
To query general properties of physical devices once enumerated, call:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.1. See Deprecated Functionality for more information. |
// 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 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 zero.
Otherwise, the choice of what values to return may be dictated by operating
system or platform policies - but should uniquely identify both the device
version and any major configuration options (for example, core count in the
case of multicore devices).
|
Note
|
The same device ID should be used for all physical implementations of that device version and configuration. For example, all uses of a specific silicon IP GPU version and configuration should use the same device ID, even if those uses occur in different SoCs. |
Khronos vendor IDs which may be returned in
VkPhysicalDeviceProperties::vendorID are:
// Provided by VK_VERSION_1_0
typedef enum VkVendorId {
VK_VENDOR_ID_KHRONOS = 0x10000,
VK_VENDOR_ID_VIV = 0x10001,
VK_VENDOR_ID_VSI = 0x10002,
VK_VENDOR_ID_KAZAN = 0x10003,
VK_VENDOR_ID_CODEPLAY = 0x10004,
VK_VENDOR_ID_MESA = 0x10005,
VK_VENDOR_ID_POCL = 0x10006,
VK_VENDOR_ID_MOBILEYE = 0x10007,
} VkVendorId;
|
Note
|
Khronos vendor IDs may be allocated by vendors at any time.
Only the latest canonical versions of this Specification, of the
corresponding 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 VkMemoryAllocateInfo::allocationSizeis larger the errorVK_ERROR_OUT_OF_DEVICE_MEMORYmay be returned.
If the VkPhysicalDeviceVulkan11Properties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
These properties correspond to Vulkan 1.1 functionality.
The members of VkPhysicalDeviceVulkan11Properties have the same values
as the corresponding members of VkPhysicalDeviceIDProperties,
VkPhysicalDeviceSubgroupProperties,
VkPhysicalDevicePointClippingProperties,
VkPhysicalDeviceMultiviewProperties,
VkPhysicalDeviceProtectedMemoryProperties, and
VkPhysicalDeviceMaintenance3Properties.
|
Note
|
The |
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 a VkStructureType value identifying 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 latest version of the Vulkan conformance test that the implementor has successfully tested this driver against prior to release (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 non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of uniform buffers may execute multiple times in order to access all the descriptors. -
shaderSampledImageArrayNonUniformIndexingNativeis a boolean value indicating whether sampler and image descriptors natively support non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of samplers or images may execute multiple times in order to access all the descriptors. -
shaderStorageBufferArrayNonUniformIndexingNativeis a boolean value indicating whether storage buffer descriptors natively support non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of storage buffers may execute multiple times in order to access all the descriptors. -
shaderStorageImageArrayNonUniformIndexingNativeis a boolean value indicating whether storage image descriptors natively support non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of storage images may execute multiple times in order to access all the descriptors. -
shaderInputAttachmentArrayNonUniformIndexingNativeis a boolean value indicating whether input attachment descriptors natively support non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of input attachments may execute multiple times in order to access all the descriptors. -
robustBufferAccessUpdateAfterBindis a boolean value indicating whetherrobustBufferAccesscan be enabled on 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. Similarly, if this property isVK_FALSE, robustness must not be enabled through the VkPipelineRobustnessCreateInfo mechanism. -
quadDivergentImplicitLodis a boolean value indicating whether implicit LOD calculations for image operations have well-defined results when the image and/or sampler objects used for the instruction are not uniform within a quad. See Derivative Image Operations. -
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 a VkStructureType value identifying 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. -
maxPerStageDescriptorInlineUniformBlocksis 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 VkPhysicalDeviceVulkan14Properties structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceVulkan14Properties {
VkStructureType sType;
void* pNext;
uint32_t lineSubPixelPrecisionBits;
uint32_t maxVertexAttribDivisor;
VkBool32 supportsNonZeroFirstInstance;
uint32_t maxPushDescriptors;
VkBool32 dynamicRenderingLocalReadDepthStencilAttachments;
VkBool32 dynamicRenderingLocalReadMultisampledAttachments;
VkBool32 earlyFragmentMultisampleCoverageAfterSampleCounting;
VkBool32 earlyFragmentSampleMaskTestBeforeSampleCounting;
VkBool32 depthStencilSwizzleOneSupport;
VkBool32 polygonModePointSize;
VkBool32 nonStrictSinglePixelWideLinesUseParallelogram;
VkBool32 nonStrictWideLinesUseParallelogram;
VkBool32 blockTexelViewCompatibleMultipleLayers;
uint32_t maxCombinedImageSamplerDescriptorCount;
VkBool32 fragmentShadingRateClampCombinerInputs;
VkPipelineRobustnessBufferBehavior defaultRobustnessStorageBuffers;
VkPipelineRobustnessBufferBehavior defaultRobustnessUniformBuffers;
VkPipelineRobustnessBufferBehavior defaultRobustnessVertexInputs;
VkPipelineRobustnessImageBehavior defaultRobustnessImages;
uint32_t copySrcLayoutCount;
VkImageLayout* pCopySrcLayouts;
uint32_t copyDstLayoutCount;
VkImageLayout* pCopyDstLayouts;
uint8_t optimalTilingLayoutUUID[VK_UUID_SIZE];
VkBool32 identicalMemoryTypeRequirements;
} VkPhysicalDeviceVulkan14Properties;
-
sTypeis a VkStructureType value identifying 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. -
maxVertexAttribDivisoris the maximum value of the number of instances that will repeat the value of vertex attribute data when instanced rendering is enabled. -
supportsNonZeroFirstInstancespecifies whether a non-zero value for thefirstInstanceparameter of drawing commands is supported when VkVertexInputBindingDivisorDescription::divisoris not1. -
maxPushDescriptorsis the maximum number of descriptors that can be used in a descriptor set layout created withVK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BITset. -
dynamicRenderingLocalReadDepthStencilAttachmentsisVK_TRUEif the implementation supports local reads of depth/stencil attachments,VK_FALSEotherwise. -
dynamicRenderingLocalReadMultisampledAttachmentsisVK_TRUEif the implementation supports local reads of multisampled attachments,VK_FALSEotherwise. -
earlyFragmentMultisampleCoverageAfterSampleCountingis a boolean value indicating whether the fragment shading and multisample coverage operations are performed after sample counting for fragment shaders withEarlyFragmentTestsexecution mode. -
earlyFragmentSampleMaskTestBeforeSampleCountingis a boolean value indicating whether the sample mask test operation is performed before sample counting for fragment shaders using theEarlyFragmentTestsexecution mode. -
depthStencilSwizzleOneSupportis a boolean indicating that depth/stencil texturing operations withVK_COMPONENT_SWIZZLE_ONEhave defined behavior. -
polygonModePointSizeis a boolean value indicating whether the point size of the final rasterization of polygons withVK_POLYGON_MODE_POINTis controlled byPointSize. -
nonStrictSinglePixelWideLinesUseParallelogramis a boolean value indicating whether non-strict lines with a width of 1.0 are rasterized as parallelograms or using Bresenham’s algorithm. -
nonStrictWideLinesUseParallelogramis a boolean value indicating whether non-strict lines with a width greater than 1.0 are rasterized as parallelograms or using Bresenham’s algorithm. -
blockTexelViewCompatibleMultipleLayersis a boolean value indicating that an implementation supports creating image views withVK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BITwhere thelayerCountmember ofsubresourceRangeis greater than1. -
maxCombinedImageSamplerDescriptorCountis the maximum number of combined image sampler descriptors that the implementation uses to access any of the formats that require a sampler Y′CBCR conversion supported by the implementation. -
fragmentShadingRateClampCombinerInputsis a boolean value indicating that an implementation clamps the inputs to combiner operations. -
defaultRobustnessStorageBuffersdescribes the behavior of out of bounds accesses made to storage buffers when no robustness features are enabled -
defaultRobustnessUniformBuffersdescribes the behavior of out of bounds accesses made to uniform buffers when no robustness features are enabled -
defaultRobustnessVertexInputsdescribes the behavior of out of bounds accesses made to vertex input attributes when no robustness features are enabled -
defaultRobustnessImagesdescribes the behavior of out of bounds accesses made to images when no robustness features are enabled -
copySrcLayoutCountis an integer related to the number of image layouts for host copies from images available or queried, as described below. -
pCopySrcLayoutsis a pointer to an array of VkImageLayout in which supported image layouts for use with host copy operations from images are returned. -
copyDstLayoutCountis an integer related to the number of image layouts for host copies to images available or queried, as described below. -
pCopyDstLayoutsis a pointer to an array of VkImageLayout in which supported image layouts for use with host copy operations to images are returned. -
optimalTilingLayoutUUIDis an array ofVK_UUID_SIZEuint8_tvalues representing a universally unique identifier for the implementation’s swizzling layout of images created withVK_IMAGE_TILING_OPTIMAL. -
identicalMemoryTypeRequirementsindicates that specifying theVK_IMAGE_USAGE_HOST_TRANSFER_BITflag in VkImageCreateInfo::usagedoes not affect the memory type requirements of the image.
If the VkPhysicalDeviceVulkan14Properties 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.4 functionality.
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 a VkStructureType value identifying 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 is unable to guarantee that A combination of values unique to the vendor, the driver, and the hardware
environment can be used to provide a
|
|
Note
|
While VkPhysicalDeviceIDProperties:: |
VK_UUID_SIZE is the length in uint8_t values of an array
containing a universally unique device or driver build identifier, as
returned in VkPhysicalDeviceIDProperties::deviceUUID and
VkPhysicalDeviceIDProperties::driverUUID.
#define VK_UUID_SIZE 16U
VK_LUID_SIZE is the length in uint8_t values of an array
containing a locally unique device identifier, as returned in
VkPhysicalDeviceIDProperties::deviceLUID.
#define VK_LUID_SIZE 8U
or the equivalent
#define VK_LUID_SIZE_KHR VK_LUID_SIZE
The VkPhysicalDeviceDriverProperties structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkPhysicalDeviceDriverProperties {
VkStructureType sType;
void* pNext;
VkDriverId driverID;
char driverName[VK_MAX_DRIVER_NAME_SIZE];
char driverInfo[VK_MAX_DRIVER_INFO_SIZE];
VkConformanceVersion conformanceVersion;
} VkPhysicalDeviceDriverProperties;
or the equivalent
// Provided by VK_KHR_driver_properties
typedef VkPhysicalDeviceDriverProperties VkPhysicalDeviceDriverPropertiesKHR;
-
sTypeis a VkStructureType value identifying 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 latest version of the Vulkan conformance test that the implementor has successfully tested this driver against prior to release (see VkConformanceVersion).
If the VkPhysicalDeviceDriverProperties structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
These are properties of the driver corresponding to a physical device.
driverID must be immutable for a given driver across instances,
processes, driver versions, and system reboots.
Khronos driver IDs which may be returned in
VkPhysicalDeviceDriverProperties::driverID are:
// Provided by VK_VERSION_1_2
typedef enum VkDriverId {
VK_DRIVER_ID_AMD_PROPRIETARY = 1,
VK_DRIVER_ID_AMD_OPEN_SOURCE = 2,
VK_DRIVER_ID_MESA_RADV = 3,
VK_DRIVER_ID_NVIDIA_PROPRIETARY = 4,
VK_DRIVER_ID_INTEL_PROPRIETARY_WINDOWS = 5,
VK_DRIVER_ID_INTEL_OPEN_SOURCE_MESA = 6,
VK_DRIVER_ID_IMAGINATION_PROPRIETARY = 7,
VK_DRIVER_ID_QUALCOMM_PROPRIETARY = 8,
VK_DRIVER_ID_ARM_PROPRIETARY = 9,
VK_DRIVER_ID_GOOGLE_SWIFTSHADER = 10,
VK_DRIVER_ID_GGP_PROPRIETARY = 11,
VK_DRIVER_ID_BROADCOM_PROPRIETARY = 12,
VK_DRIVER_ID_MESA_LLVMPIPE = 13,
VK_DRIVER_ID_MOLTENVK = 14,
VK_DRIVER_ID_COREAVI_PROPRIETARY = 15,
VK_DRIVER_ID_JUICE_PROPRIETARY = 16,
VK_DRIVER_ID_VERISILICON_PROPRIETARY = 17,
VK_DRIVER_ID_MESA_TURNIP = 18,
VK_DRIVER_ID_MESA_V3DV = 19,
VK_DRIVER_ID_MESA_PANVK = 20,
VK_DRIVER_ID_SAMSUNG_PROPRIETARY = 21,
VK_DRIVER_ID_MESA_VENUS = 22,
VK_DRIVER_ID_MESA_DOZEN = 23,
VK_DRIVER_ID_MESA_NVK = 24,
VK_DRIVER_ID_IMAGINATION_OPEN_SOURCE_MESA = 25,
VK_DRIVER_ID_MESA_HONEYKRISP = 26,
VK_DRIVER_ID_VULKAN_SC_EMULATION_ON_VULKAN = 27,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_AMD_PROPRIETARY_KHR = VK_DRIVER_ID_AMD_PROPRIETARY,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_AMD_OPEN_SOURCE_KHR = VK_DRIVER_ID_AMD_OPEN_SOURCE,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_MESA_RADV_KHR = VK_DRIVER_ID_MESA_RADV,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_NVIDIA_PROPRIETARY_KHR = VK_DRIVER_ID_NVIDIA_PROPRIETARY,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_INTEL_PROPRIETARY_WINDOWS_KHR = VK_DRIVER_ID_INTEL_PROPRIETARY_WINDOWS,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_INTEL_OPEN_SOURCE_MESA_KHR = VK_DRIVER_ID_INTEL_OPEN_SOURCE_MESA,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_IMAGINATION_PROPRIETARY_KHR = VK_DRIVER_ID_IMAGINATION_PROPRIETARY,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_QUALCOMM_PROPRIETARY_KHR = VK_DRIVER_ID_QUALCOMM_PROPRIETARY,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_ARM_PROPRIETARY_KHR = VK_DRIVER_ID_ARM_PROPRIETARY,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_GOOGLE_SWIFTSHADER_KHR = VK_DRIVER_ID_GOOGLE_SWIFTSHADER,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_GGP_PROPRIETARY_KHR = VK_DRIVER_ID_GGP_PROPRIETARY,
// Provided by VK_KHR_driver_properties
VK_DRIVER_ID_BROADCOM_PROPRIETARY_KHR = VK_DRIVER_ID_BROADCOM_PROPRIETARY,
} VkDriverId;
or the equivalent
// Provided by VK_KHR_driver_properties
typedef VkDriverId VkDriverIdKHR;
|
Note
|
Khronos driver IDs may be allocated by vendors at any time.
There may be multiple driver IDs for the same vendor, representing different
drivers (for e.g. different platforms, proprietary or open source, etc.).
Only the latest canonical versions of this Specification, of the
corresponding 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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. |
The VkPhysicalDeviceImageProcessingPropertiesQCOM structure is defined
as:
// Provided by VK_QCOM_image_processing
typedef struct VkPhysicalDeviceImageProcessingPropertiesQCOM {
VkStructureType sType;
void* pNext;
uint32_t maxWeightFilterPhases;
VkExtent2D maxWeightFilterDimension;
VkExtent2D maxBlockMatchRegion;
VkExtent2D maxBoxFilterBlockSize;
} VkPhysicalDeviceImageProcessingPropertiesQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxWeightFilterPhasesis the maximum value that can be specified for VkImageViewSampleWeightCreateInfoQCOM::numPhasesin weight image sampling operations. -
maxWeightFilterDimensionis a VkExtent2D describing the largest dimensions (widthandheight) that can be specified for VkImageViewSampleWeightCreateInfoQCOM::filterSize. -
maxBlockMatchRegionis a VkExtent2D describing the largest dimensions (widthandheight) that can be specified forblockSizein block matching operations. -
maxBoxFilterBlockSizeis a VkExtent2D describing the maximum dimensions (widthandheight) that can be specified forblocksizein box filter sampling operations.
If the VkPhysicalDeviceImageProcessingPropertiesQCOM structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
These are properties of the image processing information of a physical device.
The VkPhysicalDeviceShaderTileImagePropertiesEXT structure is defined
as:
// Provided by VK_EXT_shader_tile_image
typedef struct VkPhysicalDeviceShaderTileImagePropertiesEXT {
VkStructureType sType;
void* pNext;
VkBool32 shaderTileImageCoherentReadAccelerated;
VkBool32 shaderTileImageReadSampleFromPixelRateInvocation;
VkBool32 shaderTileImageReadFromHelperInvocation;
} VkPhysicalDeviceShaderTileImagePropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderTileImageCoherentReadAcceleratedis a boolean that will beVK_TRUEif coherent reads of tile image data is accelerated. -
shaderTileImageReadSampleFromPixelRateInvocationis a boolean that will beVK_TRUEif reading from samples from a pixel rate fragment invocation is supported when VkPipelineMultisampleStateCreateInfo::rasterizationSamples> 1. -
shaderTileImageReadFromHelperInvocationis a boolean that will beVK_TRUEif reads of tile image data from helper fragment invocations result in valid values.
If the VkPhysicalDeviceShaderTileImagePropertiesEXT structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
These are properties of the tile image information of a physical device.
The VkPhysicalDeviceImageProcessing2PropertiesQCOM structure is
defined as:
// Provided by VK_QCOM_image_processing2
typedef struct VkPhysicalDeviceImageProcessing2PropertiesQCOM {
VkStructureType sType;
void* pNext;
VkExtent2D maxBlockMatchWindow;
} VkPhysicalDeviceImageProcessing2PropertiesQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxBlockMatchWindowis a VkExtent2D describing the largest dimensions (widthandheight) that can be specified for the block match window.
If the VkPhysicalDeviceImageProcessing2PropertiesQCOM structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
These are properties of the image processing2 information of a physical device.
The VkPhysicalDeviceLayeredDriverPropertiesMSFT structure is defined
as:
// Provided by VK_MSFT_layered_driver
typedef struct VkPhysicalDeviceLayeredDriverPropertiesMSFT {
VkStructureType sType;
void* pNext;
VkLayeredDriverUnderlyingApiMSFT underlyingAPI;
} VkPhysicalDeviceLayeredDriverPropertiesMSFT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
underlyingAPIis a VkLayeredDriverUnderlyingApiMSFT value indicating which underlying API is used to implement the layered driver, orVK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFTif the driver is not layered.
These are properties of the driver layering information of a physical device.
Underlying APIs which may be returned in
VkPhysicalDeviceLayeredDriverPropertiesMSFT::underlyingAPI are:
// Provided by VK_MSFT_layered_driver
typedef enum VkLayeredDriverUnderlyingApiMSFT {
VK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFT = 0,
VK_LAYERED_DRIVER_UNDERLYING_API_D3D12_MSFT = 1,
} VkLayeredDriverUnderlyingApiMSFT;
The VkPhysicalDeviceSchedulingControlsPropertiesARM structure is
defined as:
// Provided by VK_ARM_scheduling_controls
typedef struct VkPhysicalDeviceSchedulingControlsPropertiesARM {
VkStructureType sType;
void* pNext;
VkPhysicalDeviceSchedulingControlsFlagsARM schedulingControlsFlags;
} VkPhysicalDeviceSchedulingControlsPropertiesARM;
If the VkPhysicalDeviceSchedulingControlsPropertiesARM structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
Bits which can be set in
VkPhysicalDeviceSchedulingControlsPropertiesARM::schedulingControlsFlags,
specifying supported scheduling controls, are:
// Provided by VK_ARM_scheduling_controls
// Flag bits for VkPhysicalDeviceSchedulingControlsFlagBitsARM
typedef VkFlags64 VkPhysicalDeviceSchedulingControlsFlagBitsARM;
static const VkPhysicalDeviceSchedulingControlsFlagBitsARM VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM = 0x00000001ULL;
-
VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARMspecifies that a VkDeviceQueueShaderCoreControlCreateInfoARM structure may be included in thepNextchain of a VkDeviceQueueCreateInfo or VkDeviceCreateInfo structure.
// Provided by VK_ARM_scheduling_controls
typedef VkFlags64 VkPhysicalDeviceSchedulingControlsFlagsARM;
VkPhysicalDeviceSchedulingControlsFlagsARM is a bitmask type for
setting a mask of zero or more
VkPhysicalDeviceSchedulingControlsFlagBitsARM.
To query properties of queues available on a physical device, call:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.1. See Deprecated Functionality for more information. |
// 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 application to the number of elements in the
pQueueFamilyProperties array, and on return the variable is
overwritten with the number of structures actually written to
pQueueFamilyProperties.
If pQueueFamilyPropertyCount is less than the number of queue families
available, at most pQueueFamilyPropertyCount structures will be
written.
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 to 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,
// Provided by VK_KHR_video_decode_queue
VK_QUEUE_VIDEO_DECODE_BIT_KHR = 0x00000020,
// Provided by VK_KHR_video_encode_queue
VK_QUEUE_VIDEO_ENCODE_BIT_KHR = 0x00000040,
// Provided by VK_NV_optical_flow
VK_QUEUE_OPTICAL_FLOW_BIT_NV = 0x00000100,
// Provided by VK_ARM_data_graph
VK_QUEUE_DATA_GRAPH_BIT_ARM = 0x00000400,
} 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_OPTICAL_FLOW_BIT_NVspecifies that queues in this queue family support optical flow operations. -
VK_QUEUE_DATA_GRAPH_BIT_ARMspecifies that queues in this queue family support data graph 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 protectedMemory
physical device feature is supported, then at least one queue family of at
least one physical device exposed by the implementation must support
graphics operations, compute operations, and protected memory operations.
|
Note
|
All commands that are allowed on a queue that supports transfer operations
are also allowed on a queue that supports either graphics or compute
operations.
Thus, if the capabilities of a queue family include
|
For further details see Queues.
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueueFlags;
VkQueueFlags is a bitmask type for setting a mask of zero or more
VkQueueFlagBits.
To query properties of queues available on a physical device, call:
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceQueueFamilyProperties2(
VkPhysicalDevice physicalDevice,
uint32_t* pQueueFamilyPropertyCount,
VkQueueFamilyProperties2* pQueueFamilyProperties);
or the equivalent command
// Provided by VK_KHR_get_physical_device_properties2
void vkGetPhysicalDeviceQueueFamilyProperties2KHR(
VkPhysicalDevice physicalDevice,
uint32_t* pQueueFamilyPropertyCount,
VkQueueFamilyProperties2* pQueueFamilyProperties);
-
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 a VkStructureType value identifying 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 VkQueueFamilyGlobalPriorityProperties structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkQueueFamilyGlobalPriorityProperties {
VkStructureType sType;
void* pNext;
uint32_t priorityCount;
VkQueueGlobalPriority priorities[VK_MAX_GLOBAL_PRIORITY_SIZE];
} VkQueueFamilyGlobalPriorityProperties;
or the equivalent
// Provided by VK_KHR_global_priority
typedef VkQueueFamilyGlobalPriorityProperties VkQueueFamilyGlobalPriorityPropertiesKHR;
or the equivalent
// Provided by VK_EXT_global_priority_query
typedef VkQueueFamilyGlobalPriorityProperties VkQueueFamilyGlobalPriorityPropertiesEXT;
-
sTypeis a VkStructureType value identifying 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_SIZEVkQueueGlobalPriority enums representing all supported global queue priorities in this queue family. The firstpriorityCountelements of the array will be valid.
If the VkQueueFamilyGlobalPriorityProperties 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
VkQueueGlobalPriority enums in the ascending order.
|
Note
|
For example, returning |
VK_MAX_GLOBAL_PRIORITY_SIZE is the length of an array of
VkQueueGlobalPriority enumerants representing supported queue
priorities, as returned in
VkQueueFamilyGlobalPriorityProperties::priorities.
#define VK_MAX_GLOBAL_PRIORITY_SIZE 16U
or the equivalent
#define VK_MAX_GLOBAL_PRIORITY_SIZE_KHR VK_MAX_GLOBAL_PRIORITY_SIZE
or the equivalent
#define VK_MAX_GLOBAL_PRIORITY_SIZE_EXT VK_MAX_GLOBAL_PRIORITY_SIZE
The VkQueueFamilyCheckpointProperties2NV structure is defined as:
// Provided by VK_NV_device_diagnostic_checkpoints with VK_VERSION_1_3 or VK_KHR_synchronization2
typedef struct VkQueueFamilyCheckpointProperties2NV {
VkStructureType sType;
void* pNext;
VkPipelineStageFlags2 checkpointExecutionStageMask;
} VkQueueFamilyCheckpointProperties2NV;
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying 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.
The VkQueueFamilyVideoPropertiesKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkQueueFamilyVideoPropertiesKHR {
VkStructureType sType;
void* pNext;
VkVideoCodecOperationFlagsKHR videoCodecOperations;
} VkQueueFamilyVideoPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoCodecOperationsis a bitmask of VkVideoCodecOperationFlagBitsKHR that indicates the set of video codec operations supported by the queue family.
If this structure is included in the pNext chain of the
VkQueueFamilyProperties2 structure passed to
vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with the
set of video codec operations supported by the specified queue family.
The VkQueueFamilyQueryResultStatusPropertiesKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkQueueFamilyQueryResultStatusPropertiesKHR {
VkStructureType sType;
void* pNext;
VkBool32 queryResultStatusSupport;
} VkQueueFamilyQueryResultStatusPropertiesKHR;
-
sTypeis a VkStructureType value identifying 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.
If this structure is included in the pNext chain of the
VkQueueFamilyProperties2 structure passed to
vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with
information about whether result status
queries are supported by the specified queue family.
To enumerate the performance query counters available on a queue family of a physical device, call:
// Provided by VK_KHR_performance_query
VkResult vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
uint32_t* pCounterCount,
VkPerformanceCounterKHR* pCounters,
VkPerformanceCounterDescriptionKHR* pCounterDescriptions);
-
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
application to the number of elements in the pCounters,
pCounterDescriptions, or both arrays and on return the variable is
overwritten with the number of structures actually written out.
If pCounterCount is less than the number of counters available, at
most pCounterCount structures will be written, and VK_INCOMPLETE
will be returned instead of VK_SUCCESS, to indicate that not all the
available counters were returned.
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 a VkStructureType value identifying 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 is a deprecated alias
VK_QUERY_SCOPE_COMMAND_BUFFER_KHR = VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR,
// VK_QUERY_SCOPE_RENDER_PASS_KHR is a deprecated alias
VK_QUERY_SCOPE_RENDER_PASS_KHR = VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR,
// VK_QUERY_SCOPE_COMMAND_KHR is a deprecated alias
VK_QUERY_SCOPE_COMMAND_KHR = VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_KHR,
} VkPerformanceCounterScopeKHR;
-
VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR- the performance counter scope is a single complete command buffer. -
VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR- the performance counter scope is zero or more complete render passes. The performance query containing the performance counter must begin and end outside a render pass instance. -
VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_KHR- the performance counter scope is zero or more commands.
Performance counters have an associated storage. This storage describes the payload of a counter result.
The performance counter storage types which may be returned in
VkPerformanceCounterKHR::storage are:
// Provided by VK_KHR_performance_query
typedef enum VkPerformanceCounterStorageKHR {
VK_PERFORMANCE_COUNTER_STORAGE_INT32_KHR = 0,
VK_PERFORMANCE_COUNTER_STORAGE_INT64_KHR = 1,
VK_PERFORMANCE_COUNTER_STORAGE_UINT32_KHR = 2,
VK_PERFORMANCE_COUNTER_STORAGE_UINT64_KHR = 3,
VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32_KHR = 4,
VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64_KHR = 5,
} VkPerformanceCounterStorageKHR;
-
VK_PERFORMANCE_COUNTER_STORAGE_INT32_KHR- the performance counter storage is a 32-bit signed integer. -
VK_PERFORMANCE_COUNTER_STORAGE_INT64_KHR- the performance counter storage is a 64-bit signed integer. -
VK_PERFORMANCE_COUNTER_STORAGE_UINT32_KHR- the performance counter storage is a 32-bit unsigned integer. -
VK_PERFORMANCE_COUNTER_STORAGE_UINT64_KHR- the performance counter storage is a 64-bit unsigned integer. -
VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32_KHR- the performance counter storage is a 32-bit floating-point. -
VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64_KHR- the performance counter storage is a 64-bit floating-point.
The VkPerformanceCounterDescriptionKHR structure is defined as:
// Provided by VK_KHR_performance_query
typedef struct VkPerformanceCounterDescriptionKHR {
VkStructureType sType;
void* pNext;
VkPerformanceCounterDescriptionFlagsKHR flags;
char name[VK_MAX_DESCRIPTION_SIZE];
char category[VK_MAX_DESCRIPTION_SIZE];
char description[VK_MAX_DESCRIPTION_SIZE];
} VkPerformanceCounterDescriptionKHR;
-
sTypeis a VkStructureType value identifying 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 of a performance counter, are:
// Provided by VK_KHR_performance_query
typedef enum VkPerformanceCounterDescriptionFlagBitsKHR {
VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_BIT_KHR = 0x00000001,
VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHR = 0x00000002,
// VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_KHR is a deprecated alias
VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_KHR = VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_BIT_KHR,
// VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_KHR is a deprecated alias
VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_KHR = VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHR,
} VkPerformanceCounterDescriptionFlagBitsKHR;
-
VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_BIT_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.
The VkQueueFamilyOwnershipTransferPropertiesKHR structure is defined as:
// Provided by VK_KHR_maintenance9
typedef struct VkQueueFamilyOwnershipTransferPropertiesKHR {
VkStructureType sType;
void* pNext;
uint32_t optimalImageTransferToQueueFamilies;
} VkQueueFamilyOwnershipTransferPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
optimalImageTransferToQueueFamiliesis a bitmask of queue family indices that indicates which queue families belonging to the same logical device support implicitly acquiring optimal image resources owned by this queue family, without the resources' contents becoming undefined.
If this structure is included in the pNext chain of the
VkQueueFamilyProperties2 structure passed to
vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with the
queue family ownership properties for the specified queue family.
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 application to the number of elements in the
pPhysicalDeviceGroupProperties array, and on return the variable is
overwritten with the number of structures actually written to
pPhysicalDeviceGroupProperties.
If pPhysicalDeviceGroupCount is less than the number of device groups
available, at most pPhysicalDeviceGroupCount structures will be
written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available device groups were
returned.
Every physical device must be in exactly one device group.
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 a VkStructureType value identifying 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;
// enabledLayerCount is deprecated and should not be used
uint32_t enabledLayerCount;
// ppEnabledLayerNames is deprecated and should not be used
const char* const* ppEnabledLayerNames;
uint32_t enabledExtensionCount;
const char* const* ppEnabledExtensionNames;
const VkPhysicalDeviceFeatures* pEnabledFeatures;
} VkDeviceCreateInfo;
-
sTypeis a VkStructureType value identifying 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. This field is deprecated. See Physical Device Queries: Deprecation via version 2.
// 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkDeviceDiagnosticsConfigFlagBitsNV specifying additional parameters for configuring diagnostic tools.
Bits which can be set in
VkDeviceDiagnosticsConfigCreateInfoNV::flags include:
// Provided by VK_NV_device_diagnostics_config
typedef enum VkDeviceDiagnosticsConfigFlagBitsNV {
VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_DEBUG_INFO_BIT_NV = 0x00000001,
VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_RESOURCE_TRACKING_BIT_NV = 0x00000002,
VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_AUTOMATIC_CHECKPOINTS_BIT_NV = 0x00000004,
VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_ERROR_REPORTING_BIT_NV = 0x00000008,
} VkDeviceDiagnosticsConfigFlagBitsNV;
-
VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_DEBUG_INFO_BIT_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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 valid VkDeviceSize value. 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
privateDataSlotRequestCountis the amount of slots to reserve.
To disable the implementation’s internal pipeline cache, add a
VkDevicePipelineBinaryInternalCacheControlKHR structure to the
pNext chain of the VkDeviceCreateInfo structure.
// Provided by VK_KHR_pipeline_binary
typedef struct VkDevicePipelineBinaryInternalCacheControlKHR {
VkStructureType sType;
const void* pNext;
VkBool32 disableInternalCache;
} VkDevicePipelineBinaryInternalCacheControlKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
disableInternalCachespecifies whether or not to disable the implementation’s internal pipeline cache.
If the VkDeviceCreateInfo::pNext chain does not include this
structure, then disableInternalCache defaults to VK_FALSE.
The number of shader cores used by all the queues of a device can be
controlled by adding a VkDeviceQueueShaderCoreControlCreateInfoARM
structure to the pNext chain of the VkDeviceCreateInfo
structure.
5.2.2. Device Use
The following is a high-level list of VkDevice uses along with
references on where to find more information:
-
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 application that a platform issue has occurred, and should be investigated further. For example, underlying hardware may have developed a fault or become physically disconnected from the rest of the system. In many cases, physical device loss may cause other more serious issues such as the operating system crashing; in which case it may not be reported via the Vulkan API. |
When a device is lost, its child objects are not implicitly destroyed and their handles are still valid. Those objects must still be destroyed before their parents or the device can be destroyed (see the Object Lifetime section). The host address space corresponding to device memory mapped using vkMapMemory is still valid, and host memory accesses to these mapped regions are still valid, but the contents are undefined. It is still legal to call any API command on the device and child objects.
Once a device is lost, command execution may fail, and certain commands
that return a VkResult may return VK_ERROR_DEVICE_LOST.
These commands can be identified by the inclusion of
VK_ERROR_DEVICE_LOST in the Return Codes section for each command.
Commands that do not allow runtime errors must still operate correctly for
valid usage and, if applicable, return valid data.
Commands that wait indefinitely for device execution (namely
vkDeviceWaitIdle, vkQueueWaitIdle, vkWaitForFences
or vkAcquireNextImageKHR
with a maximum timeout, and vkGetQueryPoolResults with the
VK_QUERY_RESULT_WAIT_BIT bit set in flags) must return in
finite time even in the case of a lost device, and return either
VK_SUCCESS or VK_ERROR_DEVICE_LOST.
For any command that may return VK_ERROR_DEVICE_LOST, for the purpose
of determining whether a command buffer is in the
pending state, or whether resources are
considered in-use by the device, a return value of
VK_ERROR_DEVICE_LOST is equivalent to VK_SUCCESS.
If a device was created with the maintenance5 feature enabled, and any device command returns
VK_ERROR_DEVICE_LOST, then all device commands for which
VK_ERROR_DEVICE_LOST is a valid return value and which happen-after it
on the same host thread must return VK_ERROR_DEVICE_LOST.
Device commands executing on other threads must begin returning
VK_ERROR_DEVICE_LOST within finite time.
The content of any external memory objects that have been exported from or
imported to a lost device become undefined.
Objects on other logical devices or in other APIs which are associated with
the same underlying memory resource as the external memory objects on the
lost device are unaffected other than their content becoming undefined.
The layout of subresources of images on other logical devices that are bound
to VkDeviceMemory objects associated with the same underlying memory
resources as external memory objects on the lost device becomes
VK_IMAGE_LAYOUT_UNDEFINED.
The state of VkSemaphore objects on other logical devices created by
importing a semaphore payload with
temporary permanence which was exported from the lost device is undefined.
The state of VkSemaphore objects on other logical devices that
permanently share a semaphore payload with a VkSemaphore object on the
lost device is undefined, and remains undefined following any subsequent
signal operations.
Implementations must ensure pending and subsequently submitted wait
operations on such semaphores behave as defined in
Semaphore State Requirements For
Wait Operations for external semaphores not in a valid state for a wait
operation.
5.2.4. Device Destruction
To destroy a device, call:
// Provided by VK_VERSION_1_0
void vkDestroyDevice(
VkDevice device,
const VkAllocationCallbacks* pAllocator);
-
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 with explicit vkDestroy* or
vkFree* commands 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 cannot be independently destroyed, and are instead destroyed with
the VkDevice that they were created from.
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 a VkStructureType value identifying 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
VkDeviceQueueGlobalPriorityCreateInfo structure to the pNext
chain of VkDeviceQueueCreateInfo.
The VkDeviceQueueGlobalPriorityCreateInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkDeviceQueueGlobalPriorityCreateInfo {
VkStructureType sType;
const void* pNext;
VkQueueGlobalPriority globalPriority;
} VkDeviceQueueGlobalPriorityCreateInfo;
or the equivalent
// Provided by VK_KHR_global_priority
typedef VkDeviceQueueGlobalPriorityCreateInfo VkDeviceQueueGlobalPriorityCreateInfoKHR;
or the equivalent
// Provided by VK_EXT_global_priority
typedef VkDeviceQueueGlobalPriorityCreateInfo VkDeviceQueueGlobalPriorityCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
globalPriorityis the system-wide priority associated to these queues as specified by VkQueueGlobalPriority
Queues created without specifying
VkDeviceQueueGlobalPriorityCreateInfo will default to
VK_QUEUE_GLOBAL_PRIORITY_MEDIUM.
Possible values of
VkDeviceQueueGlobalPriorityCreateInfo::globalPriority,
specifying a system-wide priority level are:
// Provided by VK_VERSION_1_4
typedef enum VkQueueGlobalPriority {
VK_QUEUE_GLOBAL_PRIORITY_LOW = 128,
VK_QUEUE_GLOBAL_PRIORITY_MEDIUM = 256,
VK_QUEUE_GLOBAL_PRIORITY_HIGH = 512,
VK_QUEUE_GLOBAL_PRIORITY_REALTIME = 1024,
// Provided by VK_EXT_global_priority
VK_QUEUE_GLOBAL_PRIORITY_LOW_EXT = VK_QUEUE_GLOBAL_PRIORITY_LOW,
// Provided by VK_EXT_global_priority
VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT = VK_QUEUE_GLOBAL_PRIORITY_MEDIUM,
// Provided by VK_EXT_global_priority
VK_QUEUE_GLOBAL_PRIORITY_HIGH_EXT = VK_QUEUE_GLOBAL_PRIORITY_HIGH,
// Provided by VK_EXT_global_priority
VK_QUEUE_GLOBAL_PRIORITY_REALTIME_EXT = VK_QUEUE_GLOBAL_PRIORITY_REALTIME,
// Provided by VK_KHR_global_priority
VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR = VK_QUEUE_GLOBAL_PRIORITY_LOW,
// Provided by VK_KHR_global_priority
VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR = VK_QUEUE_GLOBAL_PRIORITY_MEDIUM,
// Provided by VK_KHR_global_priority
VK_QUEUE_GLOBAL_PRIORITY_HIGH_KHR = VK_QUEUE_GLOBAL_PRIORITY_HIGH,
// Provided by VK_KHR_global_priority
VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR = VK_QUEUE_GLOBAL_PRIORITY_REALTIME,
} VkQueueGlobalPriority;
or the equivalent
// Provided by VK_KHR_global_priority
typedef VkQueueGlobalPriority VkQueueGlobalPriorityKHR;
or the equivalent
// Provided by VK_EXT_global_priority
typedef VkQueueGlobalPriority 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_LOWis below the system default. Useful for non-interactive tasks. -
VK_QUEUE_GLOBAL_PRIORITY_MEDIUMis the system default priority. -
VK_QUEUE_GLOBAL_PRIORITY_HIGHis above the system default. -
VK_QUEUE_GLOBAL_PRIORITY_REALTIMEis 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)
if the caller does not have sufficient privileges.
In this scenario VK_ERROR_NOT_PERMITTED 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
VkQueueFamilyGlobalPriorityProperties, the driver implementation must
fail the queue creation.
In this scenario, VK_ERROR_INITIALIZATION_FAILED is returned.
The number of shader cores used by a queue can be controlled by adding a
VkDeviceQueueShaderCoreControlCreateInfoARM structure to the
pNext chain of VkDeviceQueueCreateInfo structures.
The VkDeviceQueueShaderCoreControlCreateInfoARM structure is defined
as:
// Provided by VK_ARM_scheduling_controls
typedef struct VkDeviceQueueShaderCoreControlCreateInfoARM {
VkStructureType sType;
void* pNext;
uint32_t shaderCoreCount;
} VkDeviceQueueShaderCoreControlCreateInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderCoreCountis the number of shader cores this queue uses.
Queues created without specifying
VkDeviceQueueShaderCoreControlCreateInfoARM will default to using all
the shader cores available.
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 a VkStructureType value identifying 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 behavior will not be observed on any driver that has passed Vulkan
conformance test suite version 1.3.3.0, or any subsequent version.
This information can be found by querying
|
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
-
Other than VkCommandPool objects, destroying or freeing any object or memory that may be accessed when the command buffer is accessed (e.g. an object bound to the command buffer) will transition the state of that command buffer to the invalid state. The command buffer must not be in the pending state when this happens. 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 a VkStructureType value identifying 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 reuse this memory but since total memory requirements fluctuate over time, unused memory can accumulate. In this situation, trimming a command pool may be useful to return unused memory back to the system, returning the total outstanding memory allocated by the pool back to a more “average” value. Implementations utilize many internal allocation strategies that make it impossible to guarantee that all unused memory is released back to the system. For instance, an implementation of a command pool may involve allocating memory in bulk from the system and sub-allocating from that memory. In such an implementation any live command buffer that holds a reference to a bulk allocation would prevent that allocation from being freed, even if only a small proportion of the bulk allocation is in use. In most cases trimming will result in a reduction in allocated but unused memory, but it does not guarantee the “ideal” behavior. Trimming may be an expensive operation, and should not be called frequently. Trimming should be treated as a way to relieve memory pressure after application-known points when there exists enough unused memory that the cost of trimming is “worth” it. |
// Provided by VK_VERSION_1_1
typedef VkFlags VkCommandPoolTrimFlags;
or the equivalent
// Provided by VK_KHR_maintenance1
typedef VkCommandPoolTrimFlags VkCommandPoolTrimFlagsKHR;
VkCommandPoolTrimFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
To reset a command pool, call:
// Provided by VK_VERSION_1_0
VkResult vkResetCommandPool(
VkDevice device,
VkCommandPool commandPool,
VkCommandPoolResetFlags flags);
-
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 a VkCommandBufferAllocateInfo structure describing parameters of the allocation.commandPoolmay be accessed any time one of the resulting command buffers is accessed. -
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 a VkStructureType value identifying 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.
After a command buffer is reset, any objects or memory specified by commands recorded into the command buffer must no longer be accessed when the command buffer is accessed by the implementation.
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 a VkStructureType value identifying 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 a VkCommandBufferInheritanceInfo structure, 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 any queue of the same queue family while it is in the pending state, and recorded into multiple primary command buffers.
// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandBufferUsageFlags;
VkCommandBufferUsageFlags is a bitmask type for setting a mask of zero
or more VkCommandBufferUsageFlagBits.
If the command buffer is a secondary command buffer, then the
VkCommandBufferInheritanceInfo structure defines any state that will
be inherited from the primary command buffer:
// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferInheritanceInfo {
VkStructureType sType;
const void* pNext;
VkRenderPass renderPass;
uint32_t subpass;
VkFramebuffer framebuffer;
VkBool32 occlusionQueryEnable;
VkQueryControlFlags queryFlags;
VkQueryPipelineStatisticFlags pipelineStatistics;
} VkCommandBufferInheritanceInfo;
-
sTypeis a VkStructureType value identifying 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 commandBufferInheritance
feature is enabled, all graphics and compute state including bound pipeline
state, bound shader objects, bound vertex and index buffers, bound
descriptor sets and push constants, and all previously set dynamic state is
inherited by the secondary command buffer from the primary or secondary
command buffer that executes it.
Furthermore, all of the state set by this secondary command buffer is
inherited back to the primary or secondard command buffer that executes it.
If the commandBufferInheritance
feature is not enabled there is a limited amount of inheritance of state
into the secondary command buffer as specified below.
If the pNext chain of VkCommandBufferInheritanceInfo includes a
VkCommandBufferInheritanceConditionalRenderingInfoEXT structure, then
that structure controls whether a command buffer can be executed while
conditional rendering is active in the
primary command buffer.
The VkCommandBufferInheritanceConditionalRenderingInfoEXT structure is
defined as:
// Provided by VK_EXT_conditional_rendering
typedef struct VkCommandBufferInheritanceConditionalRenderingInfoEXT {
VkStructureType sType;
const void* pNext;
VkBool32 conditionalRenderingEnable;
} VkCommandBufferInheritanceConditionalRenderingInfoEXT;
-
sTypeis a VkStructureType value identifying 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;
const void* pNext;
VkSurfaceTransformFlagBitsKHR transform;
VkRect2D renderArea;
} VkCommandBufferInheritanceRenderPassTransformInfoQCOM;
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying 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 -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT
as well as the following state, with restrictions on inherited depth values and viewport count:
-
VK_DYNAMIC_STATE_VIEWPORT -
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT
If viewportScissor2D is VK_FALSE, then the command buffer does
not inherit the listed dynamic state, and should set this state itself.
If this structure is not present, the behavior is as if
viewportScissor2D is VK_FALSE.
If viewportScissor2D is VK_TRUE, then the listed dynamic state
is inherited, and the command buffer must not set this
state, except that the viewport and scissor count may be set by binding a
graphics pipeline that does not specify this state as dynamic.
|
Note
|
Due to this restriction, applications should ensure either all or none of the graphics pipelines bound in this secondary command buffer use dynamic viewport/scissor counts. |
When the command buffer is executed as part of a the execution of a vkCmdExecuteCommands command, the inherited state (if enabled) is determined by the following procedure, performed separately for each dynamic state, and separately for each value for dynamic state that consists of multiple values (e.g. multiple viewports).
-
With i being the index of the executed command buffer in the
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 a VkStructureType value identifying 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
and writes to those attachments are discarded.
The
VkAttachmentSampleCountInfoAMD
or
VkAttachmentSampleCountInfoNV
structure is defined as:
// Provided by VK_AMD_mixed_attachment_samples with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
typedef struct VkAttachmentSampleCountInfoAMD {
VkStructureType sType;
const void* pNext;
uint32_t colorAttachmentCount;
const VkSampleCountFlagBits* pColorAttachmentSamples;
VkSampleCountFlagBits depthStencilAttachmentSamples;
} VkAttachmentSampleCountInfoAMD;
or the equivalent
// Provided by VK_NV_framebuffer_mixed_samples with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
typedef VkAttachmentSampleCountInfoAMD VkAttachmentSampleCountInfoNV;
-
sTypeis a VkStructureType value identifying 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 included in the pNext chain of
VkGraphicsPipelineCreateInfo, it specifies the sample count of
attachments used for rendering.
If this structure is not specified, and the pipeline does not include a
VkRenderPass, the value of
VkPipelineMultisampleStateCreateInfo::rasterizationSamples is
used as the sample count for each attachment.
If a graphics pipeline is created with a valid VkRenderPass,
parameters of this structure are ignored.
Once recording starts, an application records a sequence of commands
(vkCmd*) to set state in the command buffer, draw, dispatch, and other
commands.
Several commands can also be recorded indirectly from VkBuffer
content, see Device-Generated Commands.
To complete recording of a command buffer, call:
// Provided by VK_VERSION_1_0
VkResult vkEndCommandBuffer(
VkCommandBuffer commandBuffer);
-
commandBufferis the command buffer to complete recording.
The command buffer must have been in the recording state, and, if successful, is moved to the executable state.
If there was an error during recording, the application will be notified by
an unsuccessful return code returned by vkEndCommandBuffer, and the
command buffer will be moved to the invalid
state.
In case the application recorded one or more video
encode operations into the command buffer, implementations may return the
VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error if any of the
specified Video Std parameters do not adhere to the syntactic or semantic
requirements of the used video compression standard, or if values derived
from parameters according to the rules defined by the used video compression
standard do not adhere to the capabilities of the video compression standard
or the implementation.
|
Note
|
Applications should not rely on the
|
When a command buffer is in the executable state, it can be submitted to a queue for execution.
6.5. Command Buffer Submission
|
Note
|
Submission can be a high overhead operation, and applications should
attempt to batch work together into as few calls to |
To submit command buffers to a queue, call:
// Provided by VK_VERSION_1_3
VkResult vkQueueSubmit2(
VkQueue queue,
uint32_t submitCount,
const VkSubmitInfo2* pSubmits,
VkFence fence);
or the equivalent command
// Provided by VK_KHR_synchronization2
VkResult vkQueueSubmit2KHR(
VkQueue queue,
uint32_t submitCount,
const VkSubmitInfo2* pSubmits,
VkFence fence);
-
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. Command buffers and semaphores specified in this array may be accessed at any point until the queue operations they define complete execution on the device. -
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. If it is not VK_NULL_HANDLE,fencemay be accessed at any point until this command completes on the device.
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 a VkStructureType value identifying 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,
// Provided by VK_KHR_synchronization2
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
The VkRenderPassStripeSubmitInfoARM structure is defined as:
// Provided by VK_ARM_render_pass_striped
typedef struct VkRenderPassStripeSubmitInfoARM {
VkStructureType sType;
const void* pNext;
uint32_t stripeSemaphoreInfoCount;
const VkSemaphoreSubmitInfo* pStripeSemaphoreInfos;
} VkRenderPassStripeSubmitInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stripeSemaphoreInfoCountis the number of semaphores used to signal stripe completion in the render pass instances in the submitted command buffer. -
pStripeSemaphoreInfosis a pointer to an array ofstripeSemaphoreInfoCountVkSemaphoreSubmitInfo structures describing the semaphores used to signal stripe completion.
This structure can be included in the pNext chain of
VkCommandBufferSubmitInfo to provide a set of semaphores to be
signaled for each striped render pass instance.
The elements of pStripeSemaphoreInfos are mapped to render pass
instances in VkCommandBufferSubmitInfo::commandBuffer in
submission order and in stripe order within each render pass instance.
Each semaphore in pStripeSemaphoreInfos is signaled when the
implementation has completed execution of the associated stripe.
In a render pass instance that has multiview enabled, the stripe includes
all views in the view mask.
In a render pass instance with layerCount greater than 1, the stripe
includes all layers.
Render pass instances that specify the VK_RENDERING_RESUMING_BIT will
not have any elements of pStripeSemaphoreInfos mapped to them.
Instead, for suspending and resuming render pass instances, this mapping is
done for the first suspending render pass instance, and the per-stripe
semaphores are only signaled for the last resuming render pass instance.
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. Command buffers and semaphores specified in this array may be accessed at any point until the queue operations they define complete execution on the device. -
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. If it is not VK_NULL_HANDLE,fencemay be accessed at any point until this command completes on the device.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
If a command buffer submission waits for any events to be signaled, the application must ensure that command buffer submissions will be able to complete without any subsequent operations by the application. Events signaled by the host must be signaled before the command buffer waits on those events.
|
Note
|
The ability for commands to wait on the host to set an events was originally added to allow low-latency updates to resources between host and device. However, to ensure quality of service, implementations would necessarily detect extended stalls in execution and timeout after a short period. As this period is not defined in the Vulkan specification, it is impossible to correctly validate any application with any wait period. Since the original users of this functionality were highly limited and platform-specific, this functionality is now considered defunct and should not be used. |
6.7. Secondary Command Buffer Execution
Secondary command buffers must not be directly submitted to a queue. To record a secondary command buffer to execute as part of a primary command buffer, call:
// Provided by VK_VERSION_1_0
void vkCmdExecuteCommands(
VkCommandBuffer commandBuffer,
uint32_t commandBufferCount,
const VkCommandBuffer* pCommandBuffers);
-
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.
If the nestedCommandBuffer feature
is enabled it is valid usage for vkCmdExecuteCommands to also be
recorded to a secondary command buffer.
6.8. Nested Command Buffers
In addition to secondary command buffer execution from primary command
buffers, an implementation may support nested command
buffers, which enable secondary command buffers to be executed from other
secondary command buffers.
If the nestedCommandBuffer feature
is enabled, the implementation supports nested command
buffers.
Nested command buffer execution works the same as primary-to-secondary execution, except that it is subject to some additional implementation-defined limits.
Each secondary command buffer has a command buffer nesting
level, which is determined at vkEndCommandBuffer time and evaluated
at vkCmdExecuteCommands time.
A secondary command buffer that executes no other secondary command buffers
has a command buffer nesting level of zero.
Otherwise, the command buffer nesting level of a secondary
command buffer is equal to the maximum nesting level of all secondary
command buffers executed by that command buffer plus one.
Some implementations may have a limit on the maximum nesting level of
secondary command buffers that can be recorded.
This limit is advertised in maxCommandBufferNestingLevel.
If the nestedCommandBufferRendering feature is enabled, the implementation
supports calling vkCmdExecuteCommands inside secondary command buffers
recorded with VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT.
If the nestedCommandBufferSimultaneousUse feature is enabled, the
implementation supports calling vkCmdExecuteCommands with secondary
command buffers recorded with
VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.
Whenever vkCmdExecuteCommands is recorded inside a secondary command
buffer recorded with VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT,
each member of pCommandBuffers must have been recorded with a
VkCommandBufferBeginInfo with VkCommandBufferInheritanceInfo
compatible with the VkCommandBufferInheritanceInfo of the command
buffer into which the vkCmdExecuteCommands call is being recorded.
The VkCommandBufferInheritanceRenderingInfo structures are compatible
when the VkCommandBufferInheritanceRenderingInfo::renderpass are
compatible, or if they are
VK_NULL_HANDLE then the VkCommandBufferInheritanceRenderingInfo
members match, and all other members of
VkCommandBufferInheritanceRenderingInfo match.
This requirement applies recursively, down to the most nested command buffer
and up to the command buffer where the render pass was originally begun.
6.9. Command Buffer Device Mask
Each command buffer has a piece of state storing the current device mask of the command buffer. This mask controls which physical devices within the logical device all subsequent commands will execute on, including state-setting commands, action commands, and synchronization commands.
Scissor, exclusive scissor, and viewport state (excluding the count of each) can be 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 a VkStructureType value identifying 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 includes 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, controlling resource access between host and device.
- Semaphores
-
Semaphores can be used to control resource access across multiple queues.
- Events
-
Events provide a fine-grained synchronization primitive which can be signaled either within a command buffer or by the host, and can be waited upon within a command buffer or queried on the host. Events can be used to control resource access within a single queue.
- Pipeline Barriers
-
Pipeline barriers also provide synchronization control within a command buffer, but at a single point, rather than with separate signal and wait operations. Pipeline barriers can be used to control resource access within a single queue.
- Render Pass Objects
-
Render pass objects provide a synchronization framework for rendering tasks, built upon the concepts in this chapter. Many cases that would otherwise need an application to use other synchronization primitives can be expressed more efficiently as part of a render pass. Render pass objects can be used to control resource access within a single queue.
7.1. Execution and Memory Dependencies
An operation is an arbitrary amount of work to be executed on the host, a device, or an external entity such as a presentation engine. Synchronization commands introduce explicit execution dependencies, and memory dependencies between two sets of operations defined by the command’s two synchronization scopes.
The synchronization scopes define which other operations a synchronization command is able to create execution dependencies with. Any type of operation that is not in a synchronization command’s synchronization scopes will not be included in the resulting dependency. For example, for many synchronization commands, the synchronization scopes can be limited to just operations executing in specific pipeline stages, which allows other pipeline stages to be excluded from a dependency. Other scoping options are possible, depending on the particular command.
An execution dependency is a guarantee that for two sets of operations, the first set must happen-before the second set. If an operation happens-before another operation, then the first operation must complete before the second operation is initiated. More precisely:
-
Let Ops1 and Ops2 be separate sets of operations.
-
Let Sync be a synchronization command.
-
Let Scope1st and Scope2nd be the synchronization scopes of Sync.
-
Let ScopedOps1 be the intersection of sets Ops1 and Scope1st.
-
Let ScopedOps2 be the intersection of sets Ops2 and Scope2nd.
-
Submitting Ops1, Sync and Ops2 for execution, in that order, will result in execution dependency ExeDep between ScopedOps1 and ScopedOps2.
-
Execution dependency ExeDep guarantees that ScopedOps1 happen-before ScopedOps2.
An execution dependency chain is a sequence of execution dependencies that form a happens-before relation between the first dependency’s ScopedOps1 and the final dependency’s ScopedOps2. For each consecutive pair of execution dependencies, a chain exists if the intersection of Scope2nd in the first dependency and Scope1st in the second dependency is not an empty set. The formation of a single execution dependency from an execution dependency chain can be described by substituting the following in the description of execution dependencies:
-
Let Sync be a set of synchronization commands that generate an execution dependency chain.
-
Let Scope1st be the first synchronization scope of the first command in Sync.
-
Let Scope2nd be the second synchronization scope of the last command in Sync.
Execution dependencies alone are not sufficient to guarantee that values resulting from writes in one set of operations can be read from another set of operations.
Three additional types of operations are used to control memory access. Availability operations cause the values generated by specified memory write accesses to become available to a memory domain for future access. Any available value remains available until a subsequent write to the same memory location occurs (whether it is made available or not) or the memory is freed. Memory domain operations cause writes that are available to a source memory domain to become available to a destination memory domain (an example of this is making writes available to the host domain available to the device domain). Visibility operations cause values available to a memory domain to become visible to specified memory accesses.
Availability, visibility, memory domains, and memory domain operations are formally defined in the Availability and Visibility section of the Memory Model chapter. Which API operations perform each of these operations is defined in Availability, Visibility, and Domain Operations.
A memory dependency is an execution dependency which includes availability and visibility operations such that:
-
The first set of operations happens-before the availability operation.
-
The availability operation happens-before the visibility operation.
-
The visibility operation happens-before the second set of operations.
Once written values are made visible to a particular type of memory access, they can be read or written by that type of memory access. Most synchronization commands in Vulkan define a memory dependency.
The specific memory accesses that are made available and visible are defined by the access scopes of a memory dependency. Any type of access that is in a memory dependency’s first access scope and occurs in ScopedOps1 is made available. Any type of access that is in a memory dependency’s second access scope and occurs in ScopedOps2 has any available writes made visible to it. Any type of operation that is not in a synchronization command’s access scopes will not be included in the resulting dependency.
A memory dependency enforces availability and visibility of memory accesses and execution order between two sets of operations. Adding to the description of execution dependency chains:
-
Let MemOps1 be the set of memory accesses performed by ScopedOps1.
-
Let MemOps2 be the set of memory accesses performed by ScopedOps2.
-
Let AccessScope1st be the first access scope of the first command in the Sync chain.
-
Let AccessScope2nd be the second access scope of the last command in the Sync chain.
-
Let ScopedMemOps1 be the intersection of sets MemOps1 and AccessScope1st.
-
Let ScopedMemOps2 be the intersection of sets MemOps2 and AccessScope2nd.
-
Submitting Ops1, Sync, and Ops2 for execution, in that order, will result in a memory dependency MemDep between ScopedOps1 and ScopedOps2.
-
Memory dependency MemDep guarantees that:
-
Memory writes in ScopedMemOps1 are made available.
-
Available memory writes, including those from ScopedMemOps1, are made visible to ScopedMemOps2.
-
|
Note
|
Execution and memory dependencies are used to solve data hazards, i.e. to ensure that read and write operations occur in a well-defined order. Write-after-read hazards can be solved with just an execution dependency, but read-after-write and write-after-write hazards need appropriate memory dependencies to be included between them. If an application does not include dependencies to solve these hazards, the results and execution orders of memory accesses are undefined. |
7.1.1. Image Layout Transitions
Image subresources can be transitioned from one layout to another as part of a memory dependency (e.g. by using an image memory barrier). When a layout transition is specified in a memory dependency, it happens-after the availability operations in the memory dependency, and happens-before the visibility operations. Image layout transitions may perform read and write accesses on all memory bound to the image subresource range, so applications must ensure that all memory writes have been made available before a layout transition is executed. Available memory is automatically made visible to a layout transition, and writes performed by a layout transition are automatically made available.
Layout transitions always apply to a particular image subresource range, and
specify both an old layout and new layout.
The old layout must either be VK_IMAGE_LAYOUT_UNDEFINED, or match the
current layout of the image subresource range.
If the old layout matches the current layout of the image subresource range,
the transition preserves the contents of that range.
If the old layout is VK_IMAGE_LAYOUT_UNDEFINED, the contents of that
range may be discarded.
|
Note
|
Image layout transitions with If the contents of an attachment are not needed after a render pass
completes, then applications should use
|
As image layout transitions may perform read and write accesses on the
memory bound to the image, if the image subresource affected by the layout
transition is bound to peer memory for any device in the current device mask
then the memory heap the bound memory comes from must support the
VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT and
VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT capabilities as returned by
vkGetDeviceGroupPeerMemoryFeatures.
|
Note
|
Applications must ensure that layout transitions happen-after all operations accessing the image with the old layout, and happen-before any operations that will access the image with the new layout. Layout transitions are potentially read/write operations, so not defining appropriate memory dependencies to guarantee this will result in a data race. |
Image layout transitions interact with memory aliasing.
Layout transitions that are performed via image memory barriers execute in their entirety in submission order, relative to other image layout transitions submitted to the same queue, including those performed by render passes. In effect there is an implicit execution dependency from each such layout transition to all layout transitions previously submitted to the same queue.
The image layout of each image subresource of a depth/stencil image created
with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is
dependent on the last sample locations used to render to the image
subresource as a depth/stencil attachment, thus when the image member
of an image memory barrier is an
image created with this flag the application can chain a
VkSampleLocationsInfoEXT structure to the pNext chain of
VkImageMemoryBarrier2 or
VkImageMemoryBarrier to specify the sample locations to use during any
image layout transition.
If the VkSampleLocationsInfoEXT structure does not match the sample
location state last used to render to the image subresource range specified
by subresourceRange, or if no VkSampleLocationsInfoEXT structure
is present, then the contents of the given image subresource range becomes
undefined as if oldLayout would equal
VK_IMAGE_LAYOUT_UNDEFINED.
7.1.2. Pipeline Stages
The work performed by an action command consists of multiple operations, which are performed as a sequence of logically independent steps known as pipeline stages. The exact pipeline stages executed depend on the particular command that is used, and current command buffer state when the command was recorded.
|
Note
|
Operations performed by synchronization commands (e.g. availability and visibility operations) are not executed by a defined pipeline stage. However other commands can still synchronize with them by using the synchronization scopes to create a dependency chain. |
Execution of operations across pipeline stages must adhere to implicit ordering guarantees, particularly including pipeline stage order. Otherwise, execution across pipeline stages may overlap or execute out of order with regards to other stages, unless otherwise enforced by an execution dependency.
Several of the synchronization commands include pipeline stage parameters, restricting the synchronization scopes for that command to just those stages. This allows fine grained control over the exact execution dependencies and accesses performed by action commands. Implementations should use these pipeline stages to avoid unnecessary stalls or cache flushing.
Bits which can be set in a VkPipelineStageFlags2 mask, specifying stages of execution, are:
// 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_TOP_OF_PIPE_BIT = 0x00000001ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT = 0x00000002ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT = 0x00000004ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT = 0x00000008ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT = 0x00000010ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT = 0x00000020ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT = 0x00000040ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT = 0x00000080ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT = 0x00000100ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT = 0x00000200ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT = 0x00000400ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT = 0x00000800ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT = 0x00001000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TRANSFER_BIT = 0x00001000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BIT = 0x00002000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_HOST_BIT = 0x00004000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT = 0x00008000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT = 0x00010000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COPY_BIT = 0x100000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_RESOLVE_BIT = 0x200000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_BLIT_BIT = 0x400000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_CLEAR_BIT = 0x800000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT = 0x1000000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT = 0x2000000000ULL;
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT = 0x4000000000ULL;
// Provided by VK_KHR_video_decode_queue
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR = 0x04000000ULL;
// Provided by VK_KHR_video_encode_queue
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR = 0x08000000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_NONE_KHR = 0ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT_KHR = 0x00000001ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT_KHR = 0x00000002ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT_KHR = 0x00000004ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT_KHR = 0x00000020ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT_KHR = 0x00000080ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT_KHR = 0x00000200ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT_KHR = 0x00000400ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT_KHR = 0x00000800ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT_KHR = 0x00001000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TRANSFER_BIT_KHR = 0x00001000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_HOST_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT_KHR = 0x00010000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COPY_BIT_KHR = 0x100000000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_RESOLVE_BIT_KHR = 0x200000000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_BLIT_BIT_KHR = 0x400000000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_CLEAR_BIT_KHR = 0x800000000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT_KHR = 0x1000000000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT_KHR = 0x2000000000ULL;
// Provided by VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT_KHR = 0x4000000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_transform_feedback
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT = 0x01000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_conditional_rendering
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT = 0x00040000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_device_generated_commands
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV = 0x00020000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_device_generated_commands
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT = 0x00020000ULL;
// Provided by VK_KHR_fragment_shading_rate with VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00400000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_shading_rate_image
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV = 0x00400000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR = 0x02000000ULL;
// Provided by VK_KHR_ray_tracing_pipeline with VK_KHR_synchronization2
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR = 0x00200000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_ray_tracing
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_NV = 0x00200000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_ray_tracing
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_NV = 0x02000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_fragment_density_map
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_mesh_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_NV = 0x00080000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_mesh_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV = 0x00100000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_mesh_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT = 0x00080000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_mesh_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT = 0x00100000ULL;
// Provided by VK_HUAWEI_subpass_shading
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI = 0x8000000000ULL;
// VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI is a deprecated alias
// Provided by VK_HUAWEI_subpass_shading
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI = 0x8000000000ULL;
// Provided by VK_HUAWEI_invocation_mask
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI = 0x10000000000ULL;
// Provided by VK_KHR_ray_tracing_maintenance1 with VK_KHR_synchronization2 or VK_VERSION_1_3
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR = 0x10000000ULL;
// Provided by VK_EXT_opacity_micromap
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT = 0x40000000ULL;
// Provided by VK_HUAWEI_cluster_culling_shader
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI = 0x20000000000ULL;
// Provided by VK_NV_optical_flow
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV = 0x20000000ULL;
// Provided by VK_NV_cooperative_vector
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_CONVERT_COOPERATIVE_VECTOR_MATRIX_BIT_NV = 0x100000000000ULL;
// Provided by VK_ARM_data_graph
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_DATA_GRAPH_BIT_ARM = 0x40000000000ULL;
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. This stage also includes reading commands written by vkCmdPreprocessGeneratedCommandsEXT. -
VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXTspecifies the task shader stage. -
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXTspecifies 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_EXT -
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT -
VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI
-
-
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 render pass 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 render pass store operations for framebuffer attachments with a depth/stencil format. -
VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BITspecifies the stage of the pipeline where final color values are output from the pipeline. This stage includes blending, logic operations, render pass load and store operations for color attachments, render pass multisample resolve operations, and vkCmdClearAttachments. -
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_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 or acceleration structure copy 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_EXT -
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT -
VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT -
VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT -
VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT -
VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT -
VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT -
VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT -
VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT -
VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT -
VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT -
VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT -
VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI -
VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI -
VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI
-
-
VK_PIPELINE_STAGE_2_ALL_COMMANDS_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_COMMAND_PREPROCESS_BIT_EXTspecifies the stage of the pipeline where device-side generation of commands via vkCmdPreprocessGeneratedCommandsEXT 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 execution of video decode operations. -
VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHRspecifies the execution of video encode operations. -
VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NVspecifies the stage of the pipeline where optical flow operation are performed. -
VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEIspecifies the subpass shading shader stage. -
VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXTspecifies the execution of micromap commands. -
VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEIspecifies the cluster culling shader stage. -
VK_PIPELINE_STAGE_2_CONVERT_COOPERATIVE_VECTOR_MATRIX_BIT_NVspecifies the execution of vkCmdConvertCooperativeVectorMatrixNV. -
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_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_EXT_mesh_shader
VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT = 0x00080000,
// Provided by VK_EXT_mesh_shader
VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT = 0x00100000,
// Provided by VK_EXT_device_generated_commands
VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT = 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_NV_mesh_shader
VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV = VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT,
// Provided by VK_NV_mesh_shader
VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV = VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT,
// Provided by VK_NV_device_generated_commands
VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV = VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT,
// Provided by VK_KHR_synchronization2
VK_PIPELINE_STAGE_NONE_KHR = VK_PIPELINE_STAGE_NONE,
} VkPipelineStageFlagBits;
These values all have the same meaning as the equivalently named values for VkPipelineStageFlags2.
-
VK_PIPELINE_STAGE_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. This stage also includes reading commands written by vkCmdExecuteGeneratedCommandsEXT. -
VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXTspecifies the task shader stage. -
VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXTspecifies 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 render pass 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 render pass 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 includes blending, logic operations, render pass load and store operations for color attachments, render pass multisample resolve operations, and vkCmdClearAttachments. -
VK_PIPELINE_STAGE_COMPUTE_SHADER_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_EXT -
VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT -
VK_PIPELINE_STAGE_VERTEX_INPUT_BIT -
VK_PIPELINE_STAGE_VERTEX_SHADER_BIT -
VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT -
VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT -
VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT -
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT -
VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT -
VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT -
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT -
VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
-
-
VK_PIPELINE_STAGE_ALL_COMMANDS_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_COMMAND_PREPROCESS_BIT_EXTspecifies the stage of the pipeline where device-side preprocessing for generated commands via vkCmdPreprocessGeneratedCommandsEXT 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 any logically earlier stages. Its first access scope only includes memory accesses performed by pipeline stages explicitly specified in the source stage mask.
If a synchronization command includes a destination stage mask, its second synchronization scope only includes execution of the pipeline stages specified in that mask and any logically later stages. Its second access scope only includes memory accesses performed by pipeline stages explicitly specified in the destination stage mask.
|
Note
|
Note that access scopes do not interact with the logically earlier or later stages for either scope - only the stages the application specifies are considered part of each access scope. |
Certain pipeline stages are only available on queues that support a particular set of operations. The following table lists, for each pipeline stage flag, which queue capability flag must be supported by the queue. When multiple flags are enumerated in the second column of the table, it means that the pipeline stage is supported on the queue if it supports any of the listed capability flags. For further details on queue capabilities see Physical Device Enumeration and Queues.
| Pipeline stage flag | Required queue capability flag |
|---|---|
|
None required |
|
None required |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
None required |
|
None required |
|
|
|
None required |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Pipeline stages that execute as a result of a command logically complete execution in a specific order, such that completion of a logically later pipeline stage must not happen-before completion of a logically earlier stage. This means that including any stage in the source stage mask for a particular synchronization command also implies that any logically earlier stages are included in Scope1st for that command.
Similarly, initiation of a logically earlier pipeline stage must not happen-after initiation of a logically later pipeline stage. Including any given stage in the destination stage mask for a particular synchronization command also implies that any logically later stages are included in Scope2nd for that command.
|
Note
|
Implementations may not support synchronization at every pipeline stage for every synchronization operation. If a pipeline stage that an implementation does not support synchronization for appears in a source stage mask, it may substitute any logically later stage in its place for the first synchronization scope. If a pipeline stage that an implementation does not support synchronization for appears in a destination stage mask, it may substitute any logically earlier stage in its place for the second synchronization scope. For example, if an implementation is unable to signal an event immediately after vertex shader execution is complete, it may instead signal the event after color attachment output has completed. If an implementation makes such a substitution, it must not affect the semantics of execution or memory dependencies or image and buffer memory barriers. |
Graphics pipelines are executable on queues
supporting VK_QUEUE_GRAPHICS_BIT.
Stages executed by graphics pipelines can only be specified in commands
recorded for queues supporting VK_QUEUE_GRAPHICS_BIT.
The graphics primitive pipeline executes the following stages, with the logical ordering of the stages matching the order specified here:
-
VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT -
VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT -
VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT -
VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT -
VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT -
VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT -
VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT -
VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT -
VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT -
VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT
The graphics mesh pipeline executes the following stages, with the logical ordering of the stages matching the order specified here:
-
VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT -
VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT -
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT -
VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT -
VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT -
VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT
For the compute pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT -
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT
For the subpass shading pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI
For graphics pipeline commands executing in a render pass with a fragment
density map attachment, the following pipeline stage where the fragment
density map read happens has no particular order relative to the other
stages, except that it is logically earlier than
VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT:
-
VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT -
VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT
The conditional rendering stage is formally part of both the graphics, and the compute pipeline. The pipeline stage where the predicate read happens has unspecified order relative to other stages of these pipelines:
-
VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
For the transfer pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_2_TRANSFER_BIT
For host operations, only one pipeline stage occurs, so no order is guaranteed:
-
VK_PIPELINE_STAGE_2_HOST_BIT
For the command preprocessing pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXT
For acceleration structure build operations, only one pipeline stage occurs, so no order is guaranteed:
-
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
For acceleration structure copy operations, only one pipeline stage occurs, so no order is guaranteed:
-
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
For opacity micromap build operations, only one pipeline stage occurs, so no order is guaranteed:
-
VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
For the ray tracing pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT -
VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR
For the video decode pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR
For the video encode pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR
For the data graph pipeline, the following stages occur in this order:
-
VK_PIPELINE_STAGE_2_DATA_GRAPH_BIT_ARM
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_INDIRECT_COMMAND_READ_BIT = 0x00000001ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_INDEX_READ_BIT = 0x00000002ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT = 0x00000004ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_UNIFORM_READ_BIT = 0x00000008ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT = 0x00000010ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_READ_BIT = 0x00000020ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_WRITE_BIT = 0x00000040ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT = 0x00000080ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT = 0x00000100ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT = 0x00000200ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT = 0x00000400ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFER_READ_BIT = 0x00000800ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFER_WRITE_BIT = 0x00001000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_HOST_READ_BIT = 0x00002000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_HOST_WRITE_BIT = 0x00004000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_MEMORY_READ_BIT = 0x00008000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_MEMORY_WRITE_BIT = 0x00010000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_SAMPLED_READ_BIT = 0x100000000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_STORAGE_READ_BIT = 0x200000000ULL;
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT = 0x400000000ULL;
// Provided by VK_KHR_video_decode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR = 0x800000000ULL;
// Provided by VK_KHR_video_decode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR = 0x1000000000ULL;
// Provided by VK_KHR_video_encode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR = 0x2000000000ULL;
// Provided by VK_KHR_video_encode_queue
static const VkAccessFlagBits2 VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR = 0x4000000000ULL;
// Provided by VK_QCOM_tile_shading
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_TILE_ATTACHMENT_READ_BIT_QCOM = 0x8000000000000ULL;
// Provided by VK_QCOM_tile_shading
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_TILE_ATTACHMENT_WRITE_BIT_QCOM = 0x10000000000000ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_NONE_KHR = 0ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT_KHR = 0x00000001ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_INDEX_READ_BIT_KHR = 0x00000002ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT_KHR = 0x00000004ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_UNIFORM_READ_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_READ_BIT_KHR = 0x00000020ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_WRITE_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT_KHR = 0x00000080ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT_KHR = 0x00000200ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT_KHR = 0x00000400ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFER_READ_BIT_KHR = 0x00000800ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFER_WRITE_BIT_KHR = 0x00001000ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_HOST_READ_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_HOST_WRITE_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_MEMORY_READ_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_MEMORY_WRITE_BIT_KHR = 0x00010000ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_SAMPLED_READ_BIT_KHR = 0x100000000ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_STORAGE_READ_BIT_KHR = 0x200000000ULL;
// Provided by VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT_KHR = 0x400000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_transform_feedback
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT = 0x02000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_transform_feedback
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_transform_feedback
static const VkAccessFlagBits2 VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT = 0x08000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_conditional_rendering
static const VkAccessFlagBits2 VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT = 0x00100000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_device_generated_commands
static const VkAccessFlagBits2 VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV = 0x00020000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_device_generated_commands
static const VkAccessFlagBits2 VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV = 0x00040000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_device_generated_commands
static const VkAccessFlagBits2 VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_EXT = 0x00020000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_device_generated_commands
static const VkAccessFlagBits2 VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_EXT = 0x00040000ULL;
// Provided by VK_KHR_fragment_shading_rate with VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR = 0x00800000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_shading_rate_image
static const VkAccessFlagBits2 VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV = 0x00800000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR = 0x00200000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_synchronization2
static const VkAccessFlagBits2 VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR = 0x00400000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_ray_tracing
static const VkAccessFlagBits2 VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_NV = 0x00200000ULL;
// Provided by VK_KHR_synchronization2 with VK_NV_ray_tracing
static const VkAccessFlagBits2 VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_NV = 0x00400000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_fragment_density_map
static const VkAccessFlagBits2 VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT = 0x01000000ULL;
// Provided by VK_KHR_synchronization2 with VK_EXT_blend_operation_advanced
static const VkAccessFlagBits2 VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT = 0x00080000ULL;
// Provided by VK_EXT_descriptor_buffer
static const VkAccessFlagBits2 VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT = 0x20000000000ULL;
// Provided by VK_HUAWEI_invocation_mask
static const VkAccessFlagBits2 VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI = 0x8000000000ULL;
// Provided by VK_KHR_ray_tracing_maintenance1 with (VK_KHR_synchronization2 or VK_VERSION_1_3) and VK_KHR_ray_tracing_pipeline
static const VkAccessFlagBits2 VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR = 0x10000000000ULL;
// Provided by VK_EXT_opacity_micromap
static const VkAccessFlagBits2 VK_ACCESS_2_MICROMAP_READ_BIT_EXT = 0x100000000000ULL;
// Provided by VK_EXT_opacity_micromap
static const VkAccessFlagBits2 VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT = 0x200000000000ULL;
// Provided by VK_NV_optical_flow
static const VkAccessFlagBits2 VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV = 0x40000000000ULL;
// Provided by VK_NV_optical_flow
static const VkAccessFlagBits2 VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV = 0x80000000000ULL;
// Provided by VK_ARM_data_graph
static const VkAccessFlagBits2 VK_ACCESS_2_DATA_GRAPH_READ_BIT_ARM = 0x800000000000ULL;
// Provided by VK_ARM_data_graph
static const VkAccessFlagBits2 VK_ACCESS_2_DATA_GRAPH_WRITE_BIT_ARM = 0x1000000000000ULL;
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 vkCmdBindIndexBuffer2 and 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_SHADER_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_SHADER_SAMPLED_READ_BIT -
VK_ACCESS_2_SHADER_STORAGE_READ_BIT -
VK_ACCESS_2_SHADER_TILE_ATTACHMENT_READ_BIT_QCOM
-
-
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 (other than advanced blend operations), logic operations or certain render pass load operations in theVK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage or via fragment shader tile image reads in theVK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BITpipeline stage. -
VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BITspecifies write access to a color attachment during a render pass or via certain render pass load, store, and multisample resolve operations. Such access occurs in theVK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage. -
VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BITspecifies read access to a depth/stencil attachment, via depth or stencil operations or certain render pass load operations in theVK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BITorVK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BITpipeline stages or via fragment shader tile image reads in theVK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BITpipeline stage. -
VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BITspecifies write access to a depth/stencil attachment, via depth or stencil operations or certain render pass load and store operations. Such access occurs in theVK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_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_COMMAND_PREPROCESS_READ_BIT_EXTspecifies reads from buffer inputs to vkCmdPreprocessGeneratedCommandsEXT. Such access occurs in theVK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXTpipeline stage. -
VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_EXTspecifies writes to the target command buffer preprocess outputs. Such access occurs in theVK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_EXTpipeline 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 an 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 in 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 in 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 in 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 in a video encode operation. Such access occurs in theVK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHRpipeline stage. -
VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXTspecifies read access to a descriptor buffer in any shader pipeline stage. -
VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NVspecifies read access to an image or buffer resource as part of a optical flow operation. Such access occurs in theVK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NVpipeline stage. -
VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NVspecifies write access to an image or buffer resource as part of a optical flow operation. Such access occurs in theVK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NVpipeline stage. -
VK_ACCESS_2_MICROMAP_WRITE_BIT_EXTspecifies write access to a micromap object. Such access occurs in theVK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXTpipeline stage. -
VK_ACCESS_2_MICROMAP_READ_BIT_EXTspecifies read access to a micromap object. Such access occurs in theVK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXTandVK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHRpipeline stages. -
VK_ACCESS_2_SHADER_TILE_ATTACHMENT_READ_BIT_QCOMspecifies read access to a tile attachment. Such access occurs in theVK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BITorVK_PIPELINE_STAGE_2_COMPUTE_SHADER_BITpipeline stages. -
VK_ACCESS_2_SHADER_TILE_ATTACHMENT_WRITE_BIT_QCOMspecifies write access to a tile attachment. Such access occurs in theVK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BITorVK_PIPELINE_STAGE_2_COMPUTE_SHADER_BITpipeline stages. -
VK_ACCESS_2_DATA_GRAPH_READ_BIT_ARMspecifies read access to resources in theVK_PIPELINE_STAGE_2_DATA_GRAPH_BIT_ARMpipeline stage. -
VK_ACCESS_2_DATA_GRAPH_WRITE_BIT_ARMspecifies write access to resources in theVK_PIPELINE_STAGE_2_DATA_GRAPH_BIT_ARMpipeline 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;
An application can link a VkMemoryBarrierAccessFlags3KHR structure in
the pNext chain of VkMemoryBarrier2,
VkBufferMemoryBarrier2, or VkImageMemoryBarrier2 to provide
additional access flags beyond those available in VkAccessFlagBits2.
The VkMemoryBarrierAccessFlags3KHR structure is defined as:
// Provided by VK_KHR_maintenance8
typedef struct VkMemoryBarrierAccessFlags3KHR {
VkStructureType sType;
const void* pNext;
VkAccessFlags3KHR srcAccessMask3;
VkAccessFlags3KHR dstAccessMask3;
} VkMemoryBarrierAccessFlags3KHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcAccessMask3is a VkAccessFlags3KHR mask of access flags to be included in the first access scope. -
dstAccessMask3is a VkAccessFlags3KHR mask of access flags to be included in the second access scope.
Bits which can be set in the srcAccessMask3 and dstAccessMask3
members of VkMemoryBarrierAccessFlags3KHR, specifying access behavior,
are:
// Provided by VK_KHR_maintenance8
// Flag bits for VkAccessFlagBits3KHR
typedef VkFlags64 VkAccessFlagBits3KHR;
static const VkAccessFlagBits3KHR VK_ACCESS_3_NONE_KHR = 0ULL;
-
VK_ACCESS_3_NONE_KHRspecifies no additional accesses.
VkAccessFlags3KHR is a bitmask type for setting a mask of zero or more
VkAccessFlagBits3KHR:
// Provided by VK_KHR_maintenance8
typedef VkFlags64 VkAccessFlags3KHR;
When a VkMemoryBarrierAccessFlags3KHR structure is linked in the
pNext field of VkMemoryBarrier2, VkBufferMemoryBarrier2,
or VkImageMemoryBarrier2, the flags specified in the
srcAccessMask3 and dstAccessMask3 fields are considered in
addition to the flags in the srcAccessMask and dstAccessMask
fields, respectively, to allow up to 128 total access types to be specified
for the first or second access
scope.
|
Note
|
When VkAccessFlagBits3KHR and VkAccessFlagBits2 are used together, the two sets of 64 flags bits are combined together into 128 flag bits (effectively OR’ing them together). This is different from VkAccessFlagBits2 and VkAccessFlagBits, where the 64 bit VkAccessFlagBits2 extends and replaces the 32 bit VkAccessFlagBits. |
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_EXT_device_generated_commands
VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_EXT = 0x00020000,
// Provided by VK_EXT_device_generated_commands
VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_EXT = 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_NV_device_generated_commands
VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV = VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_EXT,
// Provided by VK_NV_device_generated_commands
VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_NV = VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_EXT,
// 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 vkCmdBindIndexBuffer2 and 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_SHADER_BIT_HUAWEIorVK_PIPELINE_STAGE_FRAGMENT_SHADER_BITpipeline stage. -
VK_ACCESS_SHADER_READ_BITspecifies read access to a uniform texel buffer, sampled image, storage buffer, physical storage buffer, shader binding table, storage tensor, 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 tensor, 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 (other than advanced blend operations), logic operations or certain render pass load operations in theVK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BITpipeline stage or via fragment shader tile image reads in theVK_PIPELINE_STAGE_FRAGMENT_SHADER_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 render pass 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 certain render pass load operations in theVK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BITorVK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BITpipeline stages or via fragment shader tile image reads in theVK_PIPELINE_STAGE_FRAGMENT_SHADER_BITpipeline stage. -
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BITspecifies write access to a depth/stencil attachment, via depth or stencil operations or certain render pass load and store operations. Such access occurs in theVK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BITorVK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BITpipeline stages. -
VK_ACCESS_TRANSFER_READ_BITspecifies read access to an image, tensor, 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, tensor, 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 preprocess outputs in vkCmdPreprocessGeneratedCommandsNV. Such access occurs in theVK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NVpipeline stage. -
VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_EXTspecifies reads from buffer inputs to vkCmdPreprocessGeneratedCommandsEXT. Such access occurs in theVK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXTpipeline stage. -
VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_EXTspecifies writes to the target command buffer preprocess outputs in vkCmdPreprocessGeneratedCommandsEXT. Such access occurs in theVK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXTpipeline 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 an 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 |
|
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 commands recorded where the
per-tile execution model is enabled,
the VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT and
VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT are included as framebuffer-space
pipeline stages.
For these pipeline stages, an execution or memory dependency from the first set of operations to the second set can either be a single framebuffer-global dependency, or split into multiple framebuffer-local dependencies. A dependency with non-framebuffer-space pipeline stages is neither framebuffer-global nor framebuffer-local.
A framebuffer region is a subset of the entire framebuffer, and can either be:
-
A sample region, which is set of sample (x, y, layer, sample) coordinates that is a subset of the entire framebuffer, or
-
A fragment region, which is a set of fragment (x, y, layer) coordinates that is a subset of the entire framebuffer.
Both synchronization scopes of a framebuffer-local dependency include only the operations performed within corresponding framebuffer regions (as defined below). No ordering guarantees are made between different framebuffer regions for a framebuffer-local dependency.
Both synchronization scopes of a framebuffer-global dependency include operations on all framebuffer-regions.
If the first synchronization scope includes operations on pixels/fragments
with N samples and the second synchronization scope includes operations on
pixels/fragments with M samples, where N does not equal M, then a
framebuffer region containing all samples at a given (x, y, layer)
coordinate in the first synchronization scope corresponds to a region
containing all samples at the same coordinate in the second synchronization
scope.
In other words, the framebuffer region is a fragment region and it is a
pixel granularity dependency.
If N equals M,
and if the VkSubpassDescription::flags does not specify the
VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM flag,
then a framebuffer region containing a single (x, y, layer, sample)
coordinate in the first synchronization scope corresponds to a region
containing the same sample at the same coordinate in the second
synchronization scope.
In other words, the framebuffer region is a sample region and it is a sample
granularity dependency.
If the pipeline performing the operation was created with
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT,
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT,
or
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT,
the framebuffer region is a fragment region and it is a pixel granularity
dependency.
For commands recorded within a render pass that enables tile shading, the framebuffer region is a tile region and it is a tile granularity dependency.
|
Note
|
For commands recorded within a render pass instance that enables tile shading, the fragment shader invocations for a given tile will be grouped together, but the tiles do not run in any particular order, and the fragment shader invocations within a tile do not run in any particular order. Otherwise, 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
For a tile granularity dependency, a fragment shader can use tile attachment variables to access any pixel or sample within the active tile for color, depth/stencil or input attachments even if only framebuffer-local dependencies are used. |
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 outside of a render pass were recorded to a command buffer on the host, from first to last.
-
The order in which commands inside a single subpass were recorded to a command buffer on the host, from first to last.
|
Note
|
When using a render pass object with multiple subpasses, commands in different subpasses have no defined submission order relative to each other, regardless of the order in which the subpasses were recorded. Commands within a subpass are still ordered relative to other commands in the same subpass, and those outside of the render pass. |
State commands do not execute any operations on the device, instead they set the state of the command buffer when they execute on the host, in the order that they are recorded. Action commands consume the current state of the command buffer when they are recorded, and will execute state changes on the device as required to match the recorded state.
The order of primitives passing through the graphics pipeline and image layout transitions as part of an image memory barrier provide additional guarantees based on submission order.
Execution of pipeline stages within a given command also has a loose ordering, dependent only on a single command.
Signal operation order is a fundamental ordering in Vulkan, giving meaning to the order in which semaphore and fence signal operations occur when submitted to a single queue. The signal operation order for queue operations is determined as follows:
-
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 or vkQueueSubmit2 or vkQueueBindSparse command is ordered after all semaphore signal operations defined by that command.
Semaphore signal operations defined by a single VkSubmitInfo or VkSubmitInfo2 or VkBindSparseInfo structure are unordered with respect to other semaphore signal operations defined within the same structure.
The vkSignalSemaphore command does not execute on a queue but instead performs the signal operation from the host. The semaphore signal operation defined by executing a vkSignalSemaphore command happens-after the vkSignalSemaphore command is invoked and happens-before the command returns.
|
Note
|
When signaling timeline semaphores, it is the responsibility of the application to ensure that they are ordered such that the semaphore value is strictly increasing. Because the first synchronization scope for a semaphore signal operation contains all semaphore signal operations which occur earlier in submission order, all semaphore signal operations contained in any given batch are guaranteed to happen-after all semaphore signal operations contained in any previous batches. However, no ordering guarantee is provided between the semaphore signal operations defined within a single batch. This, combined with the requirement that timeline semaphore values strictly increase, means that it is invalid to signal the same timeline semaphore twice within a single batch. If an application wishes to ensure that some semaphore signal operation happens-after some other semaphore signal operation, it can submit a separate batch containing only semaphore signal operations, which will happen-after the semaphore signal operations in any earlier batches. When signaling a semaphore from the host, the only ordering guarantee is
that the signal operation happens-after when vkSignalSemaphore is
called and happens-before it returns.
Therefore, it is invalid to call |
7.3. Fences
Fences are a synchronization primitive that can be used to insert a dependency from a queue to the host. Fences have two states - signaled and unsignaled. A fence can be signaled as part of the execution of a queue submission command. Fences can be unsignaled on the host with vkResetFences. Fences can be waited on by the host with the vkWaitForFences command, and the current state can be queried with vkGetFenceStatus.
The internal data of a fence may include a reference to any resources and pending work associated with signal or unsignal operations performed on that fence object, collectively referred to as the fence’s payload. Mechanisms to import and export that internal data to and from fences are provided below. These mechanisms indirectly enable applications to share fence state between two or more fences and other synchronization primitives across process and API boundaries.
Fences are represented by VkFence handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkFence)
To create a fence, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateFence(
VkDevice device,
const VkFenceCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkFence* pFence);
-
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 included in the same pNext
chain, this structure is ignored.
If VkExportFenceCreateInfo is included in the pNext chain of
VkFenceCreateInfo with a Windows handleType, but either
VkExportFenceWin32HandleInfoKHR is not included in the pNext
chain, or it is included but pAttributes is 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 or vkQueueSubmit2 or vkQueueBindSparse additionally include in the first synchronization scope any semaphore and fence signal operations that occur earlier in signal operation order.
The second synchronization scope only includes the fence signal operation.
The first access scope includes all memory access performed by the device.
The second access scope is empty.
To wait for one or more fences to enter the signaled state on the host, call:
// Provided by VK_VERSION_1_0
VkResult vkWaitForFences(
VkDevice device,
uint32_t fenceCount,
const VkFence* pFences,
VkBool32 waitAll,
uint64_t timeout);
-
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceEventis a VkDeviceEventTypeEXT value specifying when the fence will be signaled.
Possible values of VkDeviceEventInfoEXT::deviceEvent, 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 it is included but pAttributes is 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 a VkStructureType value identifying 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.
The VkQueryLowLatencySupportNV structure is defined as:
// Provided by VK_NV_low_latency
typedef struct VkQueryLowLatencySupportNV {
VkStructureType sType;
const void* pNext;
void* pQueriedLowLatencyData;
} VkQueryLowLatencySupportNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pQueriedLowLatencyDatais used for NVIDIA Reflex Support.
To export a POSIX file descriptor representing the payload of a semaphore, call:
// Provided by VK_KHR_external_semaphore_fd
VkResult vkGetSemaphoreFdKHR(
VkDevice device,
const VkSemaphoreGetFdInfoKHR* pGetFdInfo,
int* pFd);
-
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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
or vkQueueSubmit2
or vkQueueBindSparse
additionally include in the first synchronization scope any semaphore and
fence signal operations that occur earlier in
signal operation order.
The second synchronization scope includes only the semaphore signal operation.
The first access scope includes all memory access performed by the device.
The second access scope is empty.
7.4.2. Semaphore Waiting
When a batch is submitted to a queue via a queue submission, and it includes semaphores to be waited on, it defines a memory dependency between prior semaphore signal operations and the batch, and defines semaphore wait operations.
Such semaphore wait operations set the semaphores
created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY
to the unsignaled state.
In case of semaphores created with a VkSemaphoreType of
VK_SEMAPHORE_TYPE_TIMELINE a prior semaphore signal operation defines
a memory dependency with a semaphore wait operation if the value the
semaphore is signaled with is greater than or equal to the value the
semaphore is waited with, thus the semaphore will continue to be considered
signaled with respect to the counter value waited on as specified in
VkTimelineSemaphoreSubmitInfo.
The first synchronization scope includes one semaphore signal operation for each semaphore waited on by this batch. The specific signal operation waited on for each semaphore must meet the following criteria:
-
for binary semaphores, the signal operation is either earlier in submission order on the same queue, or is submitted by a command whose host operation happens-before this batch is submitted on the host
-
for binary semaphores, no wait operation exists that happens-after the signal operation and happens-before this wait operation
-
the signal operation is not guaranteed to happen-after the semaphore wait operation in this batch
-
for timeline semaphores, the signal value is greater than or equal to the wait value
If multiple semaphore signal operations meet these criteria, any of those operations may be included in the first synchronization scope. When waiting on a binary semaphore, applications must ensure that exactly one semaphore signal operation meets these criteria.
The second synchronization scope
includes every command submitted in the same batch.
In the case of vkQueueSubmit, the second synchronization scope is
limited to operations on the pipeline stages determined by the
destination stage mask specified
by the corresponding element of pWaitDstStageMask.
In the case of vkQueueSubmit2, the second synchronization scope is
limited to the pipeline stage specified by
VkSemaphoreSubmitInfo::stageMask.
Also, in the case of
either vkQueueSubmit2 or
vkQueueSubmit, the second synchronization scope additionally includes
all commands that occur later in
submission order.
The first access scope is empty.
The second access scope includes all memory access performed by the device.
The semaphore wait operation happens-after the first set of operations in the execution dependency, and happens-before the second set of operations in the execution dependency.
|
Note
|
Unlike timeline semaphores, fences or events, waiting for a binary semaphore also unsignals that semaphore when the wait completes. Applications must ensure that between two such wait operations, the semaphore is signaled again, with execution dependencies used to ensure these occur in order. Binary semaphore waits and signals should thus occur in discrete 1:1 pairs. |
|
Note
|
A common scenario for using 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
|
Note
|
If a command buffer is waiting for an event to be signaled from the host, the application must signal the event before submitting the command buffer, as described in the queue forward progress section. |
To set the state of an event to unsignaled from the host, call:
// Provided by VK_VERSION_1_0
VkResult vkResetEvent(
VkDevice device,
VkEvent event);
-
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.
If VK_DEPENDENCY_ASYMMETRIC_EVENT_BIT_KHR is not set in
pDependencyInfo->dependencyFlags, future
vkCmdWaitEvents2 commands rely on all values of each element in
pDependencyInfo matching exactly with those used to signal the
corresponding event.
If VK_DEPENDENCY_ASYMMETRIC_EVENT_BIT_KHR is set, vkCmdSetEvent2
must only include the source stage
mask of the first synchronization scope in
pDependencyInfo->pMemoryBarriers[0].srcStageMask.
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 a VkStructureType value identifying 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 ownership 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 to the same queue before it, and those submitted to the same queue after it.
The first synchronization scope and
access scope of each memory
dependency defined by pDependencyInfo are applied to operations that
occurred earlier in submission order.
The second synchronization scope
and access scope of each
memory dependency defined by pDependencyInfo are applied to operations
that occurred later in submission
order.
If vkCmdPipelineBarrier2 is recorded within a render pass instance,
the synchronization scopes are limited to a subset of operations within the
same subpass or render pass instance.
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 a VkDependencyInfo.
When vkCmdPipelineBarrier is submitted to a queue, it defines a memory dependency between commands that were submitted to the same queue before it, and those submitted to the same queue after it.
If vkCmdPipelineBarrier was recorded outside a render pass instance,
the first synchronization scope
includes all commands that occur earlier in
submission order.
If vkCmdPipelineBarrier was recorded inside a render pass instance,
the first synchronization scope includes only commands that occur earlier in
submission order within the same
subpass.
In either case, the first synchronization scope is limited to operations on
the pipeline stages determined by the
source stage mask specified by
srcStageMask.
If vkCmdPipelineBarrier was recorded outside a render pass instance,
the second synchronization scope
includes all commands that occur later in
submission order.
If vkCmdPipelineBarrier was recorded inside a render pass instance,
the second synchronization scope includes only commands that occur later in
submission order within the same
subpass.
In either case, the second synchronization scope is limited to operations on
the pipeline stages determined by the
destination stage mask specified
by dstStageMask.
The first access scope is
limited to accesses in the pipeline stages determined by the
source stage mask specified by
srcStageMask.
Within that, the first access scope only includes the first access scopes
defined by elements of the pMemoryBarriers,
pBufferMemoryBarriers and pImageMemoryBarriers arrays, which
each define a set of memory barriers.
If no memory barriers are specified, then the first access scope includes no
accesses.
The second access scope is
limited to accesses in the pipeline stages determined by the
destination stage mask specified
by dstStageMask.
Within that, the second access scope only includes the second access scopes
defined by elements of the pMemoryBarriers,
pBufferMemoryBarriers and pImageMemoryBarriers arrays, which
each define a set of memory barriers.
If no memory barriers are specified, then the second access scope includes
no accesses.
If dependencyFlags includes VK_DEPENDENCY_BY_REGION_BIT, then
any dependency between framebuffer-space pipeline stages is
framebuffer-local - otherwise it is
framebuffer-global.
Bits which can be set in vkCmdPipelineBarrier::dependencyFlags,
specifying how execution and memory dependencies are formed, are:
// Provided by VK_VERSION_1_0
typedef enum VkDependencyFlagBits {
VK_DEPENDENCY_BY_REGION_BIT = 0x00000001,
// Provided by VK_VERSION_1_1
VK_DEPENDENCY_DEVICE_GROUP_BIT = 0x00000004,
// Provided by VK_VERSION_1_1
VK_DEPENDENCY_VIEW_LOCAL_BIT = 0x00000002,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_DEPENDENCY_FEEDBACK_LOOP_BIT_EXT = 0x00000008,
// Provided by VK_KHR_maintenance8
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR = 0x00000020,
// Provided by VK_KHR_maintenance9
VK_DEPENDENCY_ASYMMETRIC_EVENT_BIT_KHR = 0x00000040,
// 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 dependencies will be view-local. -
VK_DEPENDENCY_DEVICE_GROUP_BITspecifies that dependencies are non-device-local. -
VK_DEPENDENCY_FEEDBACK_LOOP_BIT_EXTspecifies that the render pass will write to and read from the same image with feedback loop enabled. -
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHRspecifies that source and destination stages are not ignored when performing a queue family ownership transfer.
// Provided by VK_VERSION_1_0
typedef VkFlags VkDependencyFlags;
VkDependencyFlags is a bitmask type for setting a mask of zero or more
VkDependencyFlagBits.
7.7. Memory Barriers
Memory barriers are used to explicitly control access to buffer and image subresource ranges. Memory barriers are used to transfer ownership between queue families, change image layouts, and define availability and visibility operations. They explicitly define the access types and buffer and image subresource ranges that are included in the access scopes of a memory dependency that is created by a synchronization command that includes them.
7.7.1. Global Memory Barriers
Global memory barriers apply to memory accesses involving all memory objects that exist at the time of its execution.
The VkMemoryBarrier2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkMemoryBarrier2 {
VkStructureType sType;
const void* pNext;
VkPipelineStageFlags2 srcStageMask;
VkAccessFlags2 srcAccessMask;
VkPipelineStageFlags2 dstStageMask;
VkAccessFlags2 dstAccessMask;
} VkMemoryBarrier2;
or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkMemoryBarrier2 VkMemoryBarrier2KHR;
-
sTypeis a VkStructureType value identifying 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 the source stage mask and source access mask.
The second synchronization scope and access scope described by this structure include only operations and memory accesses specified by destination stage mask and destination access mask.
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 a VkStructureType value identifying 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 and, if a VkMemoryBarrierAccessFlags3KHR is passed
in pNext, srcAccessMask3.
The second access scope is
limited to access types in the destination
access mask specified by
dstAccessMask and, if a VkMemoryBarrierAccessFlags3KHR is passed
in pNext, dstAccessMask3.
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 a VkStructureType value identifying 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 ownership transfer operation for that range.
The first synchronization scope and access scope described by this structure include only operations and memory accesses specified by the source stage mask and the source access mask.
The second synchronization scope and access scope described by this structure include only operations and memory accesses specified by the destination stage mask and the destination access mask.
Both access scopes are
limited to only memory accesses to buffer in the range defined by
offset and size.
If buffer was created with VK_SHARING_MODE_EXCLUSIVE, and
srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, this
memory barrier defines a queue family
ownership transfer operation.
When executed on a queue in the family identified by
srcQueueFamilyIndex, this barrier defines a
queue family release operation
for the specified buffer range, and
if VkDependencyInfoKHR::dependencyFlags did not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
the second synchronization scope does not apply to this operation.
When executed on a queue in the family identified by
dstQueueFamilyIndex, this barrier defines a
queue family acquire operation
for the specified buffer range, and
if VkDependencyInfoKHR::dependencyFlags did not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
the first synchronization scope does not apply to this operation.
A queue family ownership transfer
operation is also defined if the values are not equal, and either is one
of the special queue family values reserved for external memory ownership
transfers, as described in Queue Family Ownership Transfer.
A queue family release
operation is defined when dstQueueFamilyIndex is one of those
values, and a queue family
acquire operation is defined when srcQueueFamilyIndex is one of
those values.
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 a VkStructureType value identifying 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 and, if a VkMemoryBarrierAccessFlags3KHR is passed
in pNext, srcAccessMask3.
If the source access mask includes VK_ACCESS_HOST_WRITE_BIT, a
memory domain
operation is performed where available memory in the host domain is also
made available to the device domain.
The second access scope is
limited to access to memory through the specified buffer range, via access
types in the destination access mask
specified by
dstAccessMask and, if a VkMemoryBarrierAccessFlags3KHR is passed
in pNext, dstAccessMask3.
If the destination access mask includes VK_ACCESS_HOST_WRITE_BIT or
VK_ACCESS_HOST_READ_BIT, a
memory domain
operation is performed where available memory in the device domain is also
made available to the host domain.
|
Note
|
When |
If srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, and
srcQueueFamilyIndex is equal to the current queue family, then the
memory barrier defines a queue
family release operation for the specified buffer range, and
if dependencyFlags did not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
the second synchronization scope of the calling command does not apply to
this operation.
If dstQueueFamilyIndex is not equal to srcQueueFamilyIndex, and
dstQueueFamilyIndex is equal to the current queue family, then the
memory barrier defines a queue
family acquire operation for the specified buffer range, and
if dependencyFlags did not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
the first synchronization scope of the calling command does not apply to
this operation.
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 a VkStructureType value identifying 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 ownership transfer operation and image layout transition for that subresource range.
The first synchronization scope and access scope described by this structure include only operations and memory accesses specified by the source stage mask and the source access mask.
The second synchronization scope and access scope described by this structure include only operations and memory accesses specified by the destination stage mask and the destination access mask.
Both access scopes are
limited to only memory accesses to image in the subresource range
defined by subresourceRange.
If image was created with VK_SHARING_MODE_EXCLUSIVE, and
srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, this
memory barrier defines a queue family
ownership transfer operation.
When executed on a queue in the family identified by
srcQueueFamilyIndex, this barrier defines a
queue family release operation
for the specified image subresource range, and
if VkDependencyInfoKHR::dependencyFlags did not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
the second synchronization scope does not apply to this operation.
When executed on a queue in the family identified by
dstQueueFamilyIndex, this barrier defines a
queue family acquire operation
for the specified image subresource range, and
if VkDependencyInfoKHR::dependencyFlags did not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
the first synchronization scope does not apply to this operation.
A queue family ownership transfer
operation is also defined if the values are not equal, and either is one
of the special queue family values reserved for external memory ownership
transfers, as described in Queue Family Ownership Transfer.
A queue family release
operation is defined when dstQueueFamilyIndex is one of those
values, and a queue family
acquire operation is defined when srcQueueFamilyIndex is one of
those values.
If oldLayout is not equal to newLayout, then the memory barrier
defines an image layout
transition for the specified image subresource range.
If this memory barrier defines a queue
family ownership transfer operation, the layout transition is only
executed once between the queues.
|
Note
|
When the old and new layout are equal, the layout values are ignored - data is preserved no matter what values are specified, or what layout the image is currently in. |
If image is a 3D image created with
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT and the
maintenance9 feature is enabled, the
baseArrayLayer and layerCount members of subresourceRange
specify the subset of slices of the 3D image affected by the memory barrier,
including the layout transition.
Any slices of a 3D image not included in subresourceRange are not
affected by the memory barrier and remain in their existing layout.
|
Note
|
Enabling 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.
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 a VkStructureType value identifying 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
if dependencyFlags did not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
the second synchronization scope of the calling command does not apply to
this operation.
If dstQueueFamilyIndex is not equal to srcQueueFamilyIndex, and
dstQueueFamilyIndex is equal to the current queue family, then the
memory barrier defines a queue
family acquire operation for the specified image subresource range, and
if dependencyFlags did not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
the first synchronization scope of the calling command does not apply to
this operation.
If the synchronization2 feature is not
enabled or oldLayout is not equal to newLayout,
oldLayout and newLayout define an
image layout transition for
the specified image subresource range.
|
Note
|
If the |
If image is a 3D image created with
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT and the
maintenance9 feature is enabled, the
baseArrayLayer and layerCount members of subresourceRange
specify the subset of slices of the 3D image affected by the memory barrier,
including the layout transition.
Any slices of a 3D image not included in subresourceRange are not
affected by the memory barrier and remain in their existing layout.
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.
To facilitate usage of images whose memory is initialized on the host, Vulkan allows image layout transitions to be performed by the host as well, albeit supporting limited layouts.
To perform an image layout transition on the host, call:
// Provided by VK_VERSION_1_4
VkResult vkTransitionImageLayout(
VkDevice device,
uint32_t transitionCount,
const VkHostImageLayoutTransitionInfo* pTransitions);
or the equivalent command
// Provided by VK_EXT_host_image_copy
VkResult vkTransitionImageLayoutEXT(
VkDevice device,
uint32_t transitionCount,
const VkHostImageLayoutTransitionInfo* pTransitions);
-
deviceis the device which ownspTransitions[i].image. -
transitionCountis the number of image layout transitions to perform. -
pTransitionsis a pointer to an array of VkHostImageLayoutTransitionInfo structures specifying the image and subresource ranges within them to transition.
The VkHostImageLayoutTransitionInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkHostImageLayoutTransitionInfo {
VkStructureType sType;
const void* pNext;
VkImage image;
VkImageLayout oldLayout;
VkImageLayout newLayout;
VkImageSubresourceRange subresourceRange;
} VkHostImageLayoutTransitionInfo;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkHostImageLayoutTransitionInfo VkHostImageLayoutTransitionInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis a handle to the image affected by this layout transition. -
oldLayoutis the old layout in an image layout transition. -
newLayoutis the new layout in an image layout transition. -
subresourceRangedescribes the image subresource range withinimagethat is affected by this layout transition.
vkTransitionImageLayout does not check whether the device memory
associated with an image is currently in use before performing the layout
transition.
The application must guarantee that any previously submitted command that
reads from or writes to this subresource has completed before the host
performs the layout transition.
The memory of image is accessed by the host as if coherent.
If image is a 3D image created with
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT and the
maintenance9 feature is enabled, the
baseArrayLayer and layerCount members of subresourceRange
specify the subset of slices of the 3D image affected by the memory barrier,
including the layout transition.
Any slices of a 3D image not included in subresourceRange are not
affected by the memory barrier and remain in their existing layout.
|
Note
|
Image layout transitions performed on the host do not require queue family ownership transfers as the physical layout of the image will not vary between queue families for the layouts supported by this function. |
|
Note
|
If the device has written to the image memory, it is not automatically made
available to the host.
Before this command can be called, a memory barrier for this image must
have been issued on the device with the second
synchronization scope including
Because queue submissions automatically make host memory visible to the device, there would not be a need for a memory barrier before using the results of this layout transition on the device. |
7.7.4. Tensor Memory Barriers
Tensor memory barriers only apply to memory accesses involving a specific tensor. That is, a memory dependency formed from a tensor memory barrier is scoped to access via the specified tensor. Tensor memory barriers can also be used to define a queue family ownership transfer for the specified tensor.
The VkTensorMemoryBarrierARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkTensorMemoryBarrierARM {
VkStructureType sType;
const void* pNext;
VkPipelineStageFlags2 srcStageMask;
VkAccessFlags2 srcAccessMask;
VkPipelineStageFlags2 dstStageMask;
VkAccessFlags2 dstAccessMask;
uint32_t srcQueueFamilyIndex;
uint32_t dstQueueFamilyIndex;
VkTensorARM tensor;
} VkTensorMemoryBarrierARM;
-
sTypeis a VkStructureType value identifying 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. -
tensoris a handle to the tensor whose backing memory is affected by the barrier.
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 tensor.
If tensor 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 tensor, 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 tensor, 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 VkTensorDependencyInfoARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkTensorDependencyInfoARM {
VkStructureType sType;
const void* pNext;
uint32_t tensorMemoryBarrierCount;
const VkTensorMemoryBarrierARM* pTensorMemoryBarriers;
} VkTensorDependencyInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensorMemoryBarrierCountis the length of thepTensorMemoryBarriersarray. -
pTensorMemoryBarriersis a pointer to an array of VkTensorMemoryBarrierARM structures defining memory dependencies between tensors.
7.7.5. 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 the source
queue family index, and the dstQueueFamilyIndex parameter to the
destination queue family index.
The destination access mask 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.
If dependencyFlags does not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
dstStageMask is also ignored for such a barrier as defined by
buffer memory ownership
transfer and image memory
ownership transfer.
An acquire operation is used
to acquire exclusive ownership of a range of a buffer or image subresource
range.
An acquire operation is defined by executing a
buffer memory barrier (for a
buffer range) or an image memory
barrier (for an image subresource range) using a pipeline barrier command,
on a queue from the destination queue family.
The buffer range or image subresource range specified in an acquire
operation must match exactly that of a previous release operation.
The srcQueueFamilyIndex parameter of the barrier must be the source
queue family index, and the dstQueueFamilyIndex parameter to the
destination queue family index.
The source access mask is ignored for such a barrier, such that no
availability operation is executed - the value of this mask does not affect
the validity of the barrier.
The acquire operation happens-before the visibility operation.
If dependencyFlags does not include
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR,
srcStageMask is also ignored for such a barrier as defined by
buffer memory ownership
transfer and image memory
ownership transfer.
|
Note
|
Whilst it is not invalid to provide destination or source access masks for memory barriers used for release or acquire operations, respectively, they have no practical effect. Access after a release operation has undefined results, and so visibility for those accesses has no practical effect. Similarly, write access before an acquire operation will produce undefined results for future access, so availability of those writes has no practical use. In an earlier version of the specification, these were required to match on both sides - but this was subsequently relaxed. These masks should be set to 0. |
|
Note
|
To ensure that an acquire and release operation are valid, the release
operation must happen-before the acquire operation.
Often, semaphores are used for this directly, with the semaphore signaling
after a release and then waiting before an acquire.
Prior to the introduction of
|
If the transfer is via an image memory barrier, and an
image layout transition is
desired, then the values of oldLayout and newLayout in the
release operation's memory barrier must be equal to values of
oldLayout and newLayout in the acquire operation's memory
barrier.
Although the image layout transition is submitted twice, it will only be
executed once.
A layout transition specified in this way happens-after the release
operation and happens-before the acquire operation.
If the values of srcQueueFamilyIndex and dstQueueFamilyIndex are
equal, no ownership transfer is performed, and the barrier operates as if
they were both set to VK_QUEUE_FAMILY_IGNORED.
Queue family ownership transfers may perform read and write accesses on all memory bound to the image subresource or buffer range, so applications must ensure that all memory writes have been made available before a queue family ownership transfer is executed. Available memory is automatically made visible to queue family release and acquire operations, and writes performed by those operations are automatically made available.
Once a queue family has acquired ownership of a buffer range or image
subresource range of a VK_SHARING_MODE_EXCLUSIVE resource, its
contents are undefined to other queue families unless ownership is
transferred.
The contents of any portion of another resource which aliases memory that is
bound to the transferred buffer or image subresource range are undefined
after a release or acquire operation.
|
Note
|
Because events cannot be used directly for inter-queue synchronization, and because vkCmdSetEvent does not have the queue family index or memory barrier parameters needed by a release operation, the release and acquire operations of a queue family ownership transfer can only be performed using vkCmdPipelineBarrier. |
An acquire operation may have a performance penalty when acquiring
ownership of a subresource range from one of the special queue families
reserved for external memory ownership transfers described above.
The application can reduce the performance penalty in some cases by adding
a VkExternalMemoryAcquireUnmodifiedEXT structure to the pNext
chain of the acquire operation's memory barrier structure.
The VkExternalMemoryAcquireUnmodifiedEXT structure is defined as:
// Provided by VK_EXT_external_memory_acquire_unmodified
typedef struct VkExternalMemoryAcquireUnmodifiedEXT {
VkStructureType sType;
const void* pNext;
VkBool32 acquireUnmodifiedMemory;
} VkExternalMemoryAcquireUnmodifiedEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
acquireUnmodifiedMemoryspecifies, ifVK_TRUE, that no range of VkDeviceMemory bound to the resource of the memory barrier’s subresource range was modified at any time since the resource’s most recent release of ownership to the queue family specified by the memory barrier’ssrcQueueFamilyIndex. IfVK_FALSE, it specifies nothing.
If the application releases ownership of the subresource range to one of the
special queue families reserved for external memory ownership transfers with
a memory barrier structure, and later re-acquires ownership from the same
queue family with a memory barrier structure, and if no range of
VkDeviceMemory bound to the resource was modified at any time between
the release operation and the acquire operation, then the application
should add a VkExternalMemoryAcquireUnmodifiedEXT structure to the
pNext chain of the acquire operation's memory barrier structure
because this may reduce the performance penalty.
This structure is ignored if acquireUnmodifiedMemory is
VK_FALSE.
In particular, VK_FALSE does not specify that memory was modified.
This structure is ignored if the memory barrier’s srcQueueFamilyIndex
is not a special queue family reserved for external memory ownership
transfers.
|
Note
|
The method by which the application determines whether memory was modified between the release operation and acquire operation is outside the scope of Vulkan. For any Vulkan operation that accesses a resource, the application must not assume the implementation accesses the resource’s memory as read-only, even for apparently read-only operations such as transfer commands and shader reads. The validity of
VkExternalMemoryAcquireUnmodifiedEXT:: |
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 includes execution of vkQueueSubmit on the host and anything that happened-before it, as defined by the host memory model.
|
Note
|
Some systems allow writes that do not directly integrate with the host
memory model; these have to be synchronized by the application manually.
One example of this is non-temporal store instructions on x86; to ensure
these happen-before submission, applications should call |
The second synchronization scope includes all commands submitted in the same queue submission, and all commands that occur later in submission order.
The first access scope includes all host writes to mappable device memory that are available to the host memory domain.
The second access scope includes all memory access performed by the device.
7.10. Synchronization and Multiple Physical Devices
If a logical device includes more than one physical device, then fences, semaphores, and events all still have a single instance of the signaled state.
A fence becomes signaled when all physical devices complete the necessary queue operations.
Semaphore wait and signal operations all include a device index that is the sole physical device that performs the operation. These indices are provided in the VkDeviceGroupSubmitInfo and VkDeviceGroupBindSparseInfo structures. Semaphores are not exclusively owned by any physical device. For example, a semaphore can be signaled by one physical device and then waited on by a different physical device.
An event can only be waited on by the same physical device that signaled it (or the host).
7.11. Calibrated Timestamps
In order to be able to correlate the time a particular operation took place at on timelines of different time domains (e.g. a device operation vs. a host operation), Vulkan allows querying calibrated timestamps from multiple time domains.
To query calibrated timestamps from a set of time domains, call:
// Provided by VK_KHR_calibrated_timestamps
VkResult vkGetCalibratedTimestampsKHR(
VkDevice device,
uint32_t timestampCount,
const VkCalibratedTimestampInfoKHR* pTimestampInfos,
uint64_t* pTimestamps,
uint64_t* pMaxDeviation);
or the equivalent command
// Provided by VK_EXT_calibrated_timestamps
VkResult vkGetCalibratedTimestampsEXT(
VkDevice device,
uint32_t timestampCount,
const VkCalibratedTimestampInfoKHR* pTimestampInfos,
uint64_t* pTimestamps,
uint64_t* pMaxDeviation);
-
deviceis the logical device used to perform the query. -
timestampCountis the number of timestamps to query. -
pTimestampInfosis a pointer to an array oftimestampCountVkCalibratedTimestampInfoKHR 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 VkCalibratedTimestampInfoKHR structure is defined as:
// Provided by VK_KHR_calibrated_timestamps
typedef struct VkCalibratedTimestampInfoKHR {
VkStructureType sType;
const void* pNext;
VkTimeDomainKHR timeDomain;
} VkCalibratedTimestampInfoKHR;
or the equivalent
// Provided by VK_EXT_calibrated_timestamps
typedef VkCalibratedTimestampInfoKHR VkCalibratedTimestampInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
timeDomainis a VkTimeDomainKHR 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_KHR_calibrated_timestamps
typedef enum VkTimeDomainKHR {
VK_TIME_DOMAIN_DEVICE_KHR = 0,
VK_TIME_DOMAIN_CLOCK_MONOTONIC_KHR = 1,
VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_KHR = 2,
VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_KHR = 3,
// Provided by VK_EXT_calibrated_timestamps
VK_TIME_DOMAIN_DEVICE_EXT = VK_TIME_DOMAIN_DEVICE_KHR,
// Provided by VK_EXT_calibrated_timestamps
VK_TIME_DOMAIN_CLOCK_MONOTONIC_EXT = VK_TIME_DOMAIN_CLOCK_MONOTONIC_KHR,
// Provided by VK_EXT_calibrated_timestamps
VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_EXT = VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_KHR,
// Provided by VK_EXT_calibrated_timestamps
VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_EXT = VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_KHR,
} VkTimeDomainKHR;
or the equivalent
// Provided by VK_EXT_calibrated_timestamps
typedef VkTimeDomainKHR VkTimeDomainEXT;
-
VK_TIME_DOMAIN_DEVICE_KHRspecifies 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_KHRspecifies 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_KHRspecifies 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_KHRspecifies 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.
If there is an instance of VkTileMemorySizeInfoQCOM included in the
pNext chain of VkRenderingInfo, the structure is ignored.
The VkRenderingInfo structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkRenderingInfo {
VkStructureType sType;
const void* pNext;
VkRenderingFlags flags;
VkRect2D renderArea;
uint32_t layerCount;
uint32_t viewMask;
uint32_t colorAttachmentCount;
const VkRenderingAttachmentInfo* pColorAttachments;
const VkRenderingAttachmentInfo* pDepthAttachment;
const VkRenderingAttachmentInfo* pStencilAttachment;
} VkRenderingInfo;
or the equivalent
// Provided by VK_KHR_dynamic_rendering, VK_QCOM_tile_properties with VK_KHR_dynamic_rendering or VK_VERSION_1_3
typedef VkRenderingInfo VkRenderingInfoKHR;
-
sTypeis a VkStructureType value identifying 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 deviceRenderAreaCount member is not
0, then renderArea is ignored, and the render area is defined
per-device by that structure.
If multiview is enabled, and the multiviewPerViewRenderAreas feature is enabled, and there is an
instance of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM
included in the pNext chain with perViewRenderAreaCount not
equal to 0, then the elements of
VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas
override renderArea and define a render area for each view.
In this case, renderArea must be an area at least as large as the
union of all the per-view render areas.
Each element of the pColorAttachments array corresponds to an output
location in the shader, i.e. if the shader declares an output variable
decorated with a Location value of X, then it uses the attachment
provided in pColorAttachments[X].
If the imageView member of any element of pColorAttachments is
VK_NULL_HANDLE,
and resolveMode is not
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROID,
writes to the corresponding location by a fragment are discarded.
Bits which can be set in VkRenderingInfo::flags describing
additional properties of the render pass are:
// Provided by VK_VERSION_1_3
typedef enum VkRenderingFlagBits {
VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT = 0x00000001,
VK_RENDERING_SUSPENDING_BIT = 0x00000002,
VK_RENDERING_RESUMING_BIT = 0x00000004,
// Provided by VK_EXT_legacy_dithering with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and (VK_KHR_maintenance5 or VK_VERSION_1_4)
VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x00000008,
// Provided by VK_KHR_maintenance7
VK_RENDERING_CONTENTS_INLINE_BIT_KHR = 0x00000010,
// Provided by VK_VALVE_fragment_density_map_layered
VK_RENDERING_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVE = 0x00000020,
// Provided by VK_KHR_dynamic_rendering
VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR = VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT,
// Provided by VK_KHR_dynamic_rendering
VK_RENDERING_SUSPENDING_BIT_KHR = VK_RENDERING_SUSPENDING_BIT,
// Provided by VK_KHR_dynamic_rendering
VK_RENDERING_RESUMING_BIT_KHR = VK_RENDERING_RESUMING_BIT,
// Provided by VK_EXT_nested_command_buffer
VK_RENDERING_CONTENTS_INLINE_BIT_EXT = VK_RENDERING_CONTENTS_INLINE_BIT_KHR,
} VkRenderingFlagBits;
or the equivalent
// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingFlagBits VkRenderingFlagBitsKHR;
-
VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BITspecifies that draw calls for the render pass instance will be recorded in secondary command buffers. If thenestedCommandBufferfeature is enabled, the draw calls can come from both inline and vkCmdExecuteCommands. -
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. -
VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXTspecifies that Legacy Dithering is enabled for the render pass instance. -
VK_RENDERING_CONTENTS_INLINE_BIT_KHRspecifies that draw calls for the render pass instance can be recorded inline within the current command buffer. This can be combined with theVK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BITbit to allow draw calls to be recorded both inline and in secondary command buffers. -
VK_RENDERING_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVEspecifies that the render pass can be used with layered fragment density maps.
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 a VkStructureType value identifying 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 data written toimageViewwill be resolved intoresolveImageView. -
resolveImageViewis an image view used to write resolved data at the end of rendering. -
resolveImageLayoutis the layout thatresolveImageViewwill be in during rendering. -
loadOpis a VkAttachmentLoadOp value defining the load operation for the attachment. -
storeOpis a VkAttachmentStoreOp value defining the store operation for the attachment. -
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,
and resolveMode is not
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROID,
other members of this structure are ignored; writes to this attachment will
be discarded, and no load,
store, or multisample resolve operations will be performed.
If resolveMode is VK_RESOLVE_MODE_NONE, then
resolveImageView is ignored.
If resolveMode is not VK_RESOLVE_MODE_NONE, and
resolveImageView is not VK_NULL_HANDLE, a
render pass multisample resolve operation
is defined for the attachment subresource.
If resolveMode is
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROID, and the
nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE,
values are only undefined once load
operations have completed.
|
Note
|
The resolve mode and store operation are independent; it is valid to write both resolved and unresolved values, and equally valid to discard the unresolved values while writing the resolved ones. |
Store and resolve operations are only performed at the end of a render pass
instance that does not specify the VK_RENDERING_SUSPENDING_BIT_KHR
flag.
Load operations are only performed at the beginning of a render pass
instance that does not specify the VK_RENDERING_RESUMING_BIT_KHR flag.
Image contents at the end of a suspended render pass instance remain defined for access by a resuming render pass instance.
If the nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE,
and resolveMode is
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROID, values in the
color attachment will be loaded from the resolve attachment at the start of
rendering, and may also be reloaded any time after a resolve occurs or the
resolve attachment is written to; if this occurs it must happen-before any
writes to the color attachment are performed which happen-after the resolve
that triggers this.
If any color component in the external format is subsampled, values will be
read from the nearest sample in the image when they are loaded.
To enable feedback loop for an attachment, the
VkAttachmentFeedbackLoopInfoEXT structure can be added to the
pNext chain of VkRenderingAttachmentInfo.
The VkAttachmentFeedbackLoopInfoEXT structure is defined as:
// Provided by VK_KHR_unified_image_layouts with VK_EXT_attachment_feedback_loop_layout and (VK_VERSION_1_3 or VK_KHR_dynamic_rendering)
typedef struct VkAttachmentFeedbackLoopInfoEXT {
VkStructureType sType;
const void* pNext;
VkBool32 feedbackLoopEnable;
} VkAttachmentFeedbackLoopInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
feedbackLoopEnablespecifies that feedback loop is enabled for the attachment identified by VkRenderingAttachmentInfo::imageView.
The VkRenderingFragmentShadingRateAttachmentInfoKHR structure is
defined as:
// Provided by VK_KHR_fragment_shading_rate with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
typedef struct VkRenderingFragmentShadingRateAttachmentInfoKHR {
VkStructureType sType;
const void* pNext;
VkImageView imageView;
VkImageLayout imageLayout;
VkExtent2D shadingRateAttachmentTexelSize;
} VkRenderingFragmentShadingRateAttachmentInfoKHR;
-
sTypeis a VkStructureType value identifying 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_EXT_fragment_density_map with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
typedef struct VkRenderingFragmentDensityMapAttachmentInfoEXT {
VkStructureType sType;
const void* pNext;
VkImageView imageView;
VkImageLayout imageLayout;
} VkRenderingFragmentDensityMapAttachmentInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis the image view that will be used as a fragment density map 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 query the render area granularity for a render pass instance, call:
// Provided by VK_VERSION_1_4
void vkGetRenderingAreaGranularity(
VkDevice device,
const VkRenderingAreaInfo* pRenderingAreaInfo,
VkExtent2D* pGranularity);
or the equivalent command
// Provided by VK_KHR_maintenance5
void vkGetRenderingAreaGranularityKHR(
VkDevice device,
const VkRenderingAreaInfo* pRenderingAreaInfo,
VkExtent2D* pGranularity);
-
deviceis the logical device that owns the render pass instance. -
pRenderingAreaInfois a pointer to a VkRenderingAreaInfo structure specifying details of the render pass instance to query the render area granularity for. -
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 each attachment used in the render pass instance. -
either the
extent.heightmember inrenderAreais a multiple of the vertical granularity oroffset.y+extent.heightis equal to theheightof each attachment used in the render pass instance.
The VkRenderingAreaInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkRenderingAreaInfo {
VkStructureType sType;
const void* pNext;
uint32_t viewMask;
uint32_t colorAttachmentCount;
const VkFormat* pColorAttachmentFormats;
VkFormat depthAttachmentFormat;
VkFormat stencilAttachmentFormat;
} VkRenderingAreaInfo;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkRenderingAreaInfo VkRenderingAreaInfoKHR;
-
sTypeis a VkStructureType value identifying 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 the render pass instance. -
depthAttachmentFormatis a VkFormat value defining the format of the depth attachment used in the render pass instance. -
stencilAttachmentFormatis a VkFormat value defining the format of the stencil attachment used in the render pass instance.
The VkRenderPassStripeBeginInfoARM structure is defined as:
// Provided by VK_ARM_render_pass_striped
typedef struct VkRenderPassStripeBeginInfoARM {
VkStructureType sType;
const void* pNext;
uint32_t stripeInfoCount;
const VkRenderPassStripeInfoARM* pStripeInfos;
} VkRenderPassStripeBeginInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stripeInfoCountis the number of stripes in this render pass instance -
pStripeInfosis a pointer to an array ofstripeInfoCountVkRenderPassStripeInfoARM structures describing the stripes used by the render pass instance.
This structure can be included in the pNext chain of
VkRenderPassBeginInfo
or VkRenderingInfo
to define how the render pass instance is split into stripes.
The VkRenderPassStripeInfoARM structure is defined as:
// Provided by VK_ARM_render_pass_striped
typedef struct VkRenderPassStripeInfoARM {
VkStructureType sType;
const void* pNext;
VkRect2D stripeArea;
} VkRenderPassStripeInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stripeAreais the stripe area, and is described in more detail below.
stripeArea is the render area that is affected by this stripe of the
render pass instance.
It must be a subregion of the renderArea of the render pass instance.
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.
Alternatively, to end a render pass instance, call:
// Provided by VK_EXT_fragment_density_map_offset
void vkCmdEndRendering2EXT(
VkCommandBuffer commandBuffer,
const VkRenderingEndInfoEXT* pRenderingEndInfo);
-
commandBufferis the command buffer in which to record the command. -
pRenderingEndInfoisNULLor a pointer to a VkRenderingEndInfoEXT structure containing information about how the render pass will be ended.
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.
The VkRenderingEndInfoEXT structure is defined as:
// Provided by VK_EXT_fragment_density_map_offset
typedef struct VkRenderingEndInfoEXT {
VkStructureType sType;
const void* pNext;
} VkRenderingEndInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
|
Note
|
For more complex rendering graphs, it is possible to pre-define a static render pass object, which as well as allowing draw commands, allows the definition of framebuffer-local dependencies between multiple subpasses. These objects have a lot of setup cost compared to vkCmdBeginRendering, but use of subpass dependencies can confer important performance benefits on some devices. |
The VkTilePropertiesQCOM structure is defined as:
// Provided by VK_QCOM_tile_properties
typedef struct VkTilePropertiesQCOM {
VkStructureType sType;
void* pNext;
VkExtent3D tileSize;
VkExtent2D apronSize;
VkOffset2D origin;
} VkTilePropertiesQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tileSizeis the dimensions of a tile, with width and height describing the width and height of a tile in pixels, and depth corresponding to the number of slices the tile spans. -
apronSizeis the dimension of the apron. -
originis the top-left corner of the first tile in attachment space.
All tiles will be tightly packed around the first tile, with edges being multiples of tile width and/or height from the origin.
The tileSize is guaranteed to be a multiple of
tileGranularity.
To query the tile properties when using dynamic rendering, call:
// Provided by VK_QCOM_tile_properties
VkResult vkGetDynamicRenderingTilePropertiesQCOM(
VkDevice device,
const VkRenderingInfo* pRenderingInfo,
VkTilePropertiesQCOM* pProperties);
-
deviceis a logical device associated with the render pass. -
pRenderingInfois a pointer to the VkRenderingInfo structure specifying details of the render pass instance in dynamic rendering. -
pPropertiesis a pointer to a VkTilePropertiesQCOM structure in which the properties are returned.
8.1. Render Pass Objects
A render pass object represents a collection of attachments, subpasses, and dependencies between the subpasses, and describes how the attachments are used over the course of the subpasses.
Render passes are represented by VkRenderPass handles:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkRenderPass)
An attachment description describes the properties of an attachment including its format, sample count, and how its contents are treated at the beginning and end of each render pass instance.
A subpass represents a phase of rendering that reads and writes a subset of the attachments in a render pass. Rendering commands are recorded into a particular subpass of a render pass instance.
A subpass description describes the subset of attachments that is involved in the execution of a subpass. Each subpass can read from some attachments as input attachments, write to some as color attachments or depth/stencil attachments, perform shader resolve operations to color_attachments or depth/stencil_attachments, and perform multisample resolve operations to resolve attachments. A subpass description can also include a set of preserve attachments, which are attachments that are not read or written by the subpass but whose contents must be preserved throughout the subpass.
A subpass uses an attachment if the attachment is a color, depth/stencil,
resolve,
depth/stencil resolve,
fragment shading rate,
or input attachment for that subpass (as determined by the
pColorAttachments, pDepthStencilAttachment,
pResolveAttachments,
VkSubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment,
VkFragmentShadingRateAttachmentInfoKHR::pFragmentShadingRateAttachment->attachment,
and pInputAttachments members of VkSubpassDescription,
respectively).
A subpass does not use an attachment if that attachment is preserved by the
subpass.
The first use of an attachment is in the lowest numbered subpass that uses
that attachment.
Similarly, the last use of an attachment is in the highest numbered
subpass that uses that attachment.
The subpasses in a render pass all render to the same dimensions, and fragments for pixel (x,y,layer) in one subpass can only read attachment contents written by previous subpasses at that same (x,y,layer) location. For multi-pixel fragments, the pixel read from an input attachment is selected from the pixels covered by that fragment in an implementation-dependent manner. However, this selection must be made consistently for any fragment with the same shading rate for the lifetime of the VkDevice.
|
Note
|
By describing a complete set of subpasses in advance, render passes provide the implementation an opportunity to optimize the storage and transfer of attachment data between subpasses. In practice, this means that subpasses with a simple framebuffer-space dependency may be merged into a single tiled rendering pass, keeping the attachment data on-chip for the duration of a render pass instance. However, it is also quite common for a render pass to only contain a single subpass. |
Subpass dependencies describe execution and memory dependencies between subpasses.
A subpass dependency chain is a sequence of subpass dependencies in a render pass, where the source subpass of each subpass dependency (after the first) equals the destination subpass of the previous dependency.
Execution of subpasses may overlap or execute out of order with regards to other subpasses, unless otherwise enforced by an execution dependency. Each subpass only respects submission order for commands recorded in the same subpass, and the vkCmdBeginRenderPass and vkCmdEndRenderPass commands that delimit the render pass - commands within other subpasses are not included. This affects most other implicit ordering guarantees.
A render pass describes the structure of subpasses and attachments
independent of any specific image views for the attachments.
The specific image views that will be used for the attachments, and their
dimensions, are specified in VkFramebuffer objects.
Framebuffers are created with respect to a specific render pass that the
framebuffer is compatible with (see Render Pass
Compatibility).
Collectively, a render pass and a framebuffer define the complete render
target state for one or more subpasses as well as the algorithmic
dependencies between the subpasses.
The various pipeline stages of the drawing commands for a given subpass may execute concurrently and/or out of order, both within and across drawing commands, whilst still respecting pipeline order. However for a given (x,y,layer,sample) sample location, certain per-sample operations are performed in rasterization order.
VK_ATTACHMENT_UNUSED is a constant indicating that a render pass
attachment is not used.
#define VK_ATTACHMENT_UNUSED (~0U)
8.2. Render Pass Creation
To create a render pass, call:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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,
// Provided by VK_VALVE_fragment_density_map_layered
VK_RENDER_PASS_CREATE_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVE = 0x00000004,
} VkRenderPassCreateFlagBits;
-
VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOMspecifies that the created render pass is compatible with render pass transform. -
VK_RENDER_PASS_CREATE_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVEspecifies that the created render pass is usable with layered fragment density maps.
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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 mesh shaders, geometry shaders or tessellation shaders.
When multiview is enabled, the VK_DEPENDENCY_VIEW_LOCAL_BIT bit in a
dependency can be used to express a view-local dependency, meaning that
each view in the destination subpass depends on a single view in the source
subpass.
Unlike pipeline barriers, a subpass dependency can potentially have a
different view mask in the source subpass and the destination subpass.
If the dependency is view-local, then each view (dstView) in the
destination subpass depends on the view dstView +
pViewOffsets[dependency] in the source subpass.
If there is not such a view in the source subpass, then this dependency does
not affect that view in the destination subpass.
If the dependency is not view-local, then all views in the destination
subpass depend on all views in the source subpass, and the view offset is
ignored.
A non-zero view offset is not allowed in a self-dependency.
The elements of pCorrelationMasks are a set of masks of views
indicating that views in the same mask may exhibit spatial coherency
between the views, making it more efficient to render them concurrently.
Correlation masks must not have a functional effect on the results of the
multiview rendering.
When multiview is enabled, at the beginning of each subpass all non-render pass state is undefined. In particular, each time vkCmdBeginRenderPass or vkCmdNextSubpass is called the graphics pipeline must be bound, any relevant descriptor sets or vertex/index buffers must be bound, and any relevant dynamic state or push constants must be set before they are used.
A multiview subpass can declare that its shaders will write per-view
attributes for all views in a single invocation, by setting the
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit in the subpass
description.
The only supported per-view attributes are position and viewport mask, and
per-view position and viewport masks are written to output array variables
decorated with PositionPerViewNV and ViewportMaskPerViewNV,
respectively.
If the VK_NV_viewport_array2 extension 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_NVX_multiview_per_view_attributes with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
typedef struct VkMultiviewPerViewAttributesInfoNVX {
VkStructureType sType;
const void* pNext;
VkBool32 perViewAttributes;
VkBool32 perViewAttributesPositionXOnly;
} VkMultiviewPerViewAttributesInfoNVX;
-
sTypeis a VkStructureType value identifying 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// Provided by VK_EXT_fragment_density_map
typedef struct VkRenderPassFragmentDensityMapCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkAttachmentReference fragmentDensityMapAttachment;
} VkRenderPassFragmentDensityMapCreateInfoEXT;
-
sTypeis a VkStructureType value identifying 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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 for the attachment.
storeOp and stencilStoreOp define the
store operations for the attachment.
If an attachment is not used by any subpass, loadOp, storeOp,
stencilStoreOp, and stencilLoadOp will be ignored for that
attachment, and no load or store ops will be performed.
However, any transition specified by initialLayout and
finalLayout will still be executed.
If flags includes VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then
the attachment is treated as if it shares physical memory with another
attachment in the same render pass.
This information limits the ability of the implementation to reorder certain
operations (like layout transitions and the loadOp) such that it is
not improperly reordered against other uses of the same physical memory via
a different attachment.
This is described in more detail below.
If a render pass uses multiple attachments that alias the same device
memory, those attachments must each include the
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment
description flags.
Attachments aliasing the same memory occurs in multiple ways:
-
Multiple attachments being assigned the same image view as part of framebuffer creation.
-
Attachments using distinct image views that correspond to the same image subresource of an image.
-
Attachments using views of distinct image subresources which are bound to overlapping memory ranges.
|
Note
|
Render passes must include subpass dependencies (either directly or via a
subpass dependency chain) between any two subpasses that operate on the same
attachment or aliasing attachments and those subpass dependencies must
include execution and memory dependencies separating uses of the aliases, if
at least one of those subpasses writes to one of the aliases.
These dependencies must not include the |
Multiple attachments that alias the same memory must not be used in a single subpass. A given attachment index must not be used multiple times in a single subpass, with one exception: two subpass attachments can use the same attachment index if at least one use is as an input attachment and neither use is as a resolve or preserve attachment. In other words, the same view can be used simultaneously as an input and color or depth/stencil attachment, but must not be used as multiple color or depth/stencil attachments nor as resolve or preserve attachments.
If a set of attachments alias each other, then all except the first to be
used in the render pass must use an initialLayout of
VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases
make their contents undefined.
Once an alias has been used and a different alias has been used after it,
the first alias must not be used in any later subpasses.
However, an application can assign the same image view to multiple aliasing
attachment indices, which allows that image view to be used multiple times
even if other aliases are used in between.
|
Note
|
Once an attachment needs the |
Bits which can be set in VkAttachmentDescription::flags,
describing additional properties of the attachment, are:
// Provided by VK_VERSION_1_0
typedef enum VkAttachmentDescriptionFlagBits {
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT = 0x00000001,
} VkAttachmentDescriptionFlagBits;
-
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BITspecifies that the attachment aliases the same device memory as other attachments.
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// Provided by VK_VERSION_1_0
typedef VkFlags VkAttachmentDescriptionFlags;
VkAttachmentDescriptionFlags is a bitmask type for setting a mask of
zero or more VkAttachmentDescriptionFlagBits.
The VkRenderPassInputAttachmentAspectCreateInfo structure is defined
as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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 (xf,yf) framebuffer
coordinates and layer.
Input attachments must not be used by any subpasses within a render pass
that enables render pass transform.
Each element of the pColorAttachments array corresponds to an output
location in the shader, i.e. if the shader declares an output variable
decorated with a Location value of X, then it uses the attachment
provided in pColorAttachments[X].
If the attachment member of any element of pColorAttachments is
VK_ATTACHMENT_UNUSED,
or if Color Write Enable has been
disabled for the corresponding attachment index,
then writes to the corresponding location by a fragment shader are
discarded.
If
flags does not include
VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if
pResolveAttachments is not NULL, each of its elements corresponds to
a color attachment (the element in pColorAttachments at the same
index), and a multisample resolve
operation is defined for each attachment unless the resolve attachment
index is VK_ATTACHMENT_UNUSED.
Similarly, if
flags does not include
VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and
VkSubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment
is not NULL and does not have the value VK_ATTACHMENT_UNUSED, it
corresponds to the depth/stencil attachment in
pDepthStencilAttachment, and
multisample resolve operation for depth
and stencil are defined by
VkSubpassDescriptionDepthStencilResolve::depthResolveMode and
VkSubpassDescriptionDepthStencilResolve::stencilResolveMode,
respectively.
If VkSubpassDescriptionDepthStencilResolve::depthResolveMode is
VK_RESOLVE_MODE_NONE or the pDepthStencilResolveAttachment does
not have a depth aspect, no resolve operation is performed for the depth
attachment.
If VkSubpassDescriptionDepthStencilResolve::stencilResolveMode
is VK_RESOLVE_MODE_NONE or the pDepthStencilResolveAttachment
does not have a stencil aspect, no resolve operation is performed for the
stencil attachment.
If the image subresource range referenced by the depth/stencil attachment is
created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT, then the
multisample resolve operation uses the
sample locations state specified in the sampleLocationsInfo member of
the element of the
VkRenderPassSampleLocationsBeginInfoEXT::pPostSubpassSampleLocations
for the subpass.
If pDepthStencilAttachment is NULL, or if its attachment index is
VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil attachment
will be used in the subpass.
The contents of an attachment within the render area become undefined at the start of a subpass S if all of the following conditions are true:
-
The attachment is used as a color, depth/stencil, or resolve attachment in any subpass in the render pass.
-
There is a subpass S1 that uses or preserves the attachment, and a subpass dependency from S1 to S.
-
The attachment is not used or preserved in subpass S.
In addition, the contents of an attachment within the render area become undefined at the start of a subpass S if all of the following conditions are true:
-
VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_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_QCOM_tile_shading
VK_SUBPASS_DESCRIPTION_TILE_SHADING_APRON_BIT_QCOM = 0x00000100,
// Provided by VK_EXT_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT = 0x00000010,
// Provided by VK_EXT_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT = 0x00000020,
// Provided by VK_EXT_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT = 0x00000040,
// Provided by VK_EXT_legacy_dithering
VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x00000080,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT,
} VkSubpassDescriptionFlagBits;
-
VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_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_EXTspecifies that this subpass supports pipelines created withVK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT. -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXTspecifies that this subpass supports pipelines created withVK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT. -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXTspecifies that this subpass supports pipelines created withVK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT. -
VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXTspecifies that Legacy Dithering is enabled for this subpass. -
VK_SUBPASS_DESCRIPTION_TILE_SHADING_APRON_BIT_QCOMspecifies that apron regions can be read within this subpass when tile shading is enabled.
|
Note
|
Shader resolve operations allow for custom resolve operations, but overdrawing pixels may have a performance and/or power cost. Furthermore, since the content of any depth stencil attachment or color attachment is undefined at the beginning of a shader resolve subpass, any depth testing, stencil testing, or blending operation which sources these undefined values also has undefined result value. |
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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. If set toVK_PIPELINE_STAGE_ALL_COMMANDS_BIT, it is equivalent to setting it toVK_PIPELINE_STAGE_ALL_GRAPHICS_BIT. -
dstStageMaskis a bitmask of VkPipelineStageFlagBits specifying the destination stage mask If set toVK_PIPELINE_STAGE_ALL_COMMANDS_BIT, it is equivalent to setting it toVK_PIPELINE_STAGE_ALL_GRAPHICS_BIT. -
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 does not directly define a
dependency.
Instead, it enables pipeline barriers to be used in a render pass instance
within the identified subpass, where the scopes of one pipeline barrier
must be a subset of those described by one subpass dependency.
Subpass dependencies specified in this way that include
framebuffer-space stages in the
srcStageMask must only include
framebuffer-space stages in
dstStageMask, and must include VK_DEPENDENCY_BY_REGION_BIT.
When a subpass dependency is specified in this way for a subpass that has
more than one view in its view mask, its dependencyFlags must include
VK_DEPENDENCY_VIEW_LOCAL_BIT.
If srcSubpass and dstSubpass are not equal, when a render pass
instance which includes a subpass dependency is submitted to a queue, it
defines a dependency between the subpasses
identified by srcSubpass and dstSubpass.
If srcSubpass is equal to VK_SUBPASS_EXTERNAL, the first
synchronization scope includes
commands that occur earlier in submission
order than the vkCmdBeginRenderPass used to begin the render pass
instance.
Otherwise, the first set of commands includes all commands submitted as part
of the subpass instance identified by srcSubpass and any
load, store, or multisample resolve
operations on attachments used in srcSubpass.
In either case, the first synchronization scope is limited to operations on
the pipeline stages determined by the
source stage mask specified by
srcStageMask.
If dstSubpass is equal to VK_SUBPASS_EXTERNAL, the second
synchronization scope includes
commands that occur later in submission
order than the vkCmdEndRenderPass used to end the render pass
instance.
Otherwise, the second set of commands includes all commands submitted as
part of the subpass instance identified by dstSubpass and any
load, store, and multisample resolve
operations on attachments used in dstSubpass.
In either case, the second synchronization scope is limited to operations on
the pipeline stages determined by the
destination stage mask specified
by dstStageMask.
The first access scope is
limited to accesses in the pipeline stages determined by the
source stage mask specified by
srcStageMask.
It is also limited to access types in the source access mask specified by srcAccessMask.
The second access scope is
limited to accesses in the pipeline stages determined by the
destination stage mask specified
by dstStageMask.
It is also limited to access types in the destination access mask specified by dstAccessMask.
The availability and visibility operations defined by a subpass dependency affect the execution of image layout transitions within the render pass.
|
Note
|
For non-attachment resources, the memory dependency expressed by subpass
dependency is nearly identical to that of a VkMemoryBarrier (with
matching For attachments however, subpass dependencies work more like a
VkImageMemoryBarrier defined similarly to the VkMemoryBarrier
above, the queue family indices set to
|
When multiview is enabled, the execution of the multiple views of one
subpass may not occur simultaneously or even back-to-back, and rather may
be interleaved with the execution of other subpasses.
The load and store operations apply to attachments on a per-view basis.
For example, an attachment using VK_ATTACHMENT_LOAD_OP_CLEAR will have
each view cleared on first use, but the first use of one view may be
temporally distant from the first use of another view.
|
Note
|
A good mental model for multiview is to think of a multiview subpass as if it were a collection of individual (per-view) subpasses that are logically grouped together and described as a single multiview subpass in the API. Similarly, a multiview attachment can be thought of like several individual attachments that happen to be layers in a single image. A view-local dependency between two multiview subpasses acts like a set of one-to-one dependencies between corresponding pairs of per-view subpasses. A view-global dependency between two multiview subpasses acts like a set of N × M dependencies between all pairs of per-view subpasses in the source and destination. Thus, it is a more compact representation which also makes clear the commonality and reuse that is present between views in a subpass. This interpretation motivates the answers to questions like “when does the load op apply” - it is on the first use of each view of an attachment, as if each view was a separate attachment. The content of each view follows the description in attachment content behavior. In particular, if an attachment is preserved, all views within the attachment are preserved. |
If any two subpasses of a render pass activate transform feedback to the same bound transform feedback buffers, a subpass dependency must be included (either directly or via some intermediate subpasses) between them.
If there is no subpass dependency from VK_SUBPASS_EXTERNAL to the
first subpass that uses an attachment, then an implicit subpass dependency
exists from VK_SUBPASS_EXTERNAL to the first subpass it is used in.
The implicit subpass dependency only exists if there exists an automatic
layout transition away from initialLayout.
The subpass dependency operates as if defined with the following parameters:
VkSubpassDependency implicitDependency = {
.srcSubpass = VK_SUBPASS_EXTERNAL,
.dstSubpass = firstSubpass, // First subpass attachment is used in
.srcStageMask = VK_PIPELINE_STAGE_NONE,
.dstStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
.srcAccessMask = 0,
.dstAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT |
VK_ACCESS_COLOR_ATTACHMENT_READ_BIT |
VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT |
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
.dependencyFlags = 0
};
Similarly, if there is no subpass dependency from the last subpass that uses
an attachment to VK_SUBPASS_EXTERNAL, then an implicit subpass
dependency exists from the last subpass it is used in to
VK_SUBPASS_EXTERNAL.
The implicit subpass dependency only exists if there exists an automatic
layout transition into finalLayout.
The subpass dependency operates as if defined with the following parameters:
VkSubpassDependency implicitDependency = {
.srcSubpass = lastSubpass, // Last subpass attachment is used in
.dstSubpass = VK_SUBPASS_EXTERNAL,
.srcStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
.dstStageMask = VK_PIPELINE_STAGE_NONE,
.srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
.dstAccessMask = 0,
.dependencyFlags = 0
};
As subpasses may overlap or execute out of order with regards to other subpasses unless a subpass dependency chain describes otherwise, the layout transitions required between subpasses cannot be known to an application. Instead, an application provides the layout that each attachment must be in at the start and end of a render pass, and the layout it must be in during each subpass it is used in. The implementation then must execute layout transitions between subpasses in order to guarantee that the images are in the layouts required by each subpass, and in the final layout at the end of the render pass.
Automatic layout transitions apply to the entire image subresource attached
to the framebuffer.
If
multiview is not enabled and
the attachment is a view of a 1D or 2D image, the automatic layout
transitions apply to the number of layers specified by
VkFramebufferCreateInfo::layers.
If multiview is enabled and the attachment is a view of a 1D or 2D image,
the automatic layout transitions apply to the layers corresponding to views
which are used by some subpass in the render pass, even if that subpass does
not reference the given attachment.
If the attachment view is a 2D or 2D array view of a 3D image, even if the
attachment view only refers to a subset of the slices of the selected mip
level of the 3D image, automatic layout transitions apply to the entire
subresource referenced which is the entire mip level in this case.
Automatic layout transitions away from the layout used in a subpass
happen-after the availability operations for all dependencies with that
subpass as the srcSubpass.
Automatic layout transitions into the layout used in a subpass happen-before
the visibility operations for all dependencies with that subpass as the
dstSubpass.
Automatic layout transitions away from initialLayout happen-after the
availability operations for all dependencies with a srcSubpass equal
to VK_SUBPASS_EXTERNAL, where dstSubpass uses the attachment
that will be transitioned.
For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT,
automatic layout transitions away from initialLayout happen-after the
availability operations for all dependencies with a srcSubpass equal
to VK_SUBPASS_EXTERNAL, where dstSubpass uses any aliased
attachment.
Automatic layout transitions into finalLayout happen-before the
visibility operations for all dependencies with a dstSubpass equal to
VK_SUBPASS_EXTERNAL, where srcSubpass uses the attachment that
will be transitioned.
For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT,
automatic layout transitions into finalLayout happen-before the
visibility operations for all dependencies with a dstSubpass equal to
VK_SUBPASS_EXTERNAL, where srcSubpass uses any aliased
attachment.
The image layout of the depth aspect of a depth/stencil attachment referring
to an image created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent
on the last sample locations used to render to the attachment, thus
automatic layout transitions use the sample locations state specified in
VkRenderPassSampleLocationsBeginInfoEXT.
Automatic layout transitions of an attachment referring to a depth/stencil
image created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT use the
sample locations the image subresource range referenced by the attachment
was last rendered with.
If the current render pass does not use the attachment as a depth/stencil
attachment in any subpass that happens-before, the automatic layout
transition uses the sample locations state specified in the
sampleLocationsInfo member of the element of the
VkRenderPassSampleLocationsBeginInfoEXT::pAttachmentInitialSampleLocations
array for which the attachmentIndex member equals the attachment index
of the attachment, if one is specified.
Otherwise, the automatic layout transition uses the sample locations state
specified in the sampleLocationsInfo member of the element of the
VkRenderPassSampleLocationsBeginInfoEXT::pPostSubpassSampleLocations
array for which the subpassIndex member equals the index of the
subpass that last used the attachment as a depth/stencil attachment, if one
is specified.
If no sample locations state has been specified for an automatic layout
transition performed on an attachment referring to a depth/stencil image
created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
the contents of the depth aspect of the depth/stencil attachment become
undefined as if the layout of the attachment was transitioned from the
VK_IMAGE_LAYOUT_UNDEFINED layout.
If two subpasses use the same attachment, and both subpasses use the attachment in a read-only layout, no subpass dependency needs to be specified between those subpasses. If an implementation treats those layouts separately, it must insert an implicit subpass dependency between those subpasses to separate the uses in each layout. The subpass dependency operates as if defined with the following parameters:
// Used for input attachments
VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
VkAccessFlags inputAttachmentDstAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT;
// Used for depth/stencil attachments
VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT;
VkAccessFlags depthStencilAttachmentDstAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT;
VkSubpassDependency implicitDependency = {
.srcSubpass = firstSubpass;
.dstSubpass = secondSubpass;
.srcStageMask = inputAttachmentStages | depthStencilAttachmentStages;
.dstStageMask = inputAttachmentStages | depthStencilAttachmentStages;
.srcAccessMask = 0;
.dstAccessMask = inputAttachmentDstAccess | depthStencilAttachmentDstAccess;
.dependencyFlags = 0;
};
When
drawing using shader objects,
or when
the graphics pipeline is created with
VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates, the
application must specify which types of attachments that are written to
during a render pass will also be accessed as non-attachments in the render
pass.
To dynamically set whether a pipeline can access a resource as a non-attachment while it is also used as an attachment that is written to, call:
// Provided by VK_EXT_attachment_feedback_loop_dynamic_state
void vkCmdSetAttachmentFeedbackLoopEnableEXT(
VkCommandBuffer commandBuffer,
VkImageAspectFlags aspectMask);
-
commandBufferis the command buffer into which the command will be recorded. -
aspectMaskspecifies the types of attachments for which feedback loops will be enabled. Attachment types whose aspects are not included inaspectMaskwill have feedback loops disabled.
For attachments that are written to in a render pass, only attachments with
the aspects specified in aspectMask can be accessed as
non-attachments by subsequent drawing commands.
A more extensible version of render pass creation is also defined below.
To create a render pass, call:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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.
loadOp and storeOp are ignored for fragment shading rate
attachments.
No access to the shading rate attachment is performed in loadOp and
storeOp.
Instead, access to
VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR is performed
as fragments are rasterized.
The VkAttachmentDescriptionStencilLayout structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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 any element of pResolveAttachments is an image specified with an
VkExternalFormatANDROID, values in the corresponding color attachment
will be resolved to the resolve attachment in the same manner as specified
for VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROID.
If the nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE,
values in the color attachment will be loaded from the resolve attachment at
the start of rendering, and may also be reloaded any time after a resolve
occurs or the resolve attachment is written to; if this occurs it must
happen-before any writes to the color attachment are performed which
happen-after the resolve that triggers this.
If any color component in the external format is subsampled, values will be
read from the nearest sample in the image when they are loaded.
If the color attachment is also used as an input attachment, the same
behavior applies.
Setting the color attachment to VK_ATTACHMENT_UNUSED when an external
resolve attachment is used and the
nullColorAttachmentWithExternalFormatResolve limit is VK_TRUE
will not result in color attachment writes to be discarded for that
attachment.
When nullColorAttachmentWithExternalFormatResolve is VK_TRUE, the
color output from the subpass can still be read via an input attachment; but
the application cannot bind an image view for the color attachment as there
is no such image view bound.
Instead to access the data as an input attachment applications can use the
resolve attachment in its place - using the resolve attachment image for the
descriptor, and setting the corresponding element of pInputAttachments
to the index of the resolve attachment.
Loads or input attachment reads from the resolve attachment are performed as if using a VkSamplerYcbcrConversionCreateInfo with the following parameters:
VkSamplerYcbcrConversionCreateInfo createInfo = {
.sType = VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO,
.pNext = NULL,
.format = VK_FORMAT_UNDEFINED,
.ycbcrModel = VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY,
.ycbcrRange = VK_SAMPLER_YCBCR_RANGE_ITU_FULL,
.components = {
.r = VK_COMPONENT_SWIZZLE_B
.g = VK_COMPONENT_SWIZZLE_R
.b = VK_COMPONENT_SWIZZLE_G
.a = VK_COMPONENT_SWIZZLE_IDENTITY},
.xChromaOffset = properties.chromaOffsetX,
.yChromaOffset = properties.chromaOffsetY,
.chromaFilter = VK_FILTER_NEAREST,
.forceExplicitReconstruction = ... };
where properties is equal to
VkPhysicalDeviceExternalFormatResolvePropertiesANDROID returned by the
device and forceExplicitReconstruction is effectively ignored as the
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY model is used.
The applied swizzle is the same effective swizzle that would be applied by
the VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY model, but no
range expansion is applied.
The VkSubpassDescriptionDepthStencilResolve structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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 the pNext chain of VkSubpassDescription2 includes a
VkSubpassDescriptionDepthStencilResolve structure, then that structure
describes multisample resolve operations
for the depth/stencil attachment in a subpass.
If this structure is not included in the pNext chain of
VkSubpassDescription2, or if it is and either
pDepthStencilResolveAttachment is NULL or its attachment index is
VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil resolve
attachment will be used in the subpass.
The VkFragmentShadingRateAttachmentInfoKHR structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// Provided by VK_KHR_fragment_shading_rate
typedef struct VkFragmentShadingRateAttachmentInfoKHR {
VkStructureType sType;
const void* pNext;
const VkAttachmentReference2* pFragmentShadingRateAttachment;
VkExtent2D shadingRateAttachmentTexelSize;
} VkFragmentShadingRateAttachmentInfoKHR;
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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. If set toVK_PIPELINE_STAGE_ALL_COMMANDS_BIT, it is equivalent to setting it toVK_PIPELINE_STAGE_ALL_GRAPHICS_BIT. -
dstStageMaskis a bitmask of VkPipelineStageFlagBits specifying the destination stage mask If set toVK_PIPELINE_STAGE_ALL_COMMANDS_BIT, it is equivalent to setting it toVK_PIPELINE_STAGE_ALL_GRAPHICS_BIT. -
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.
If either srcStageMask or dstStageMask are set to
VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, it is equivalent to setting
VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT.
To destroy a render pass, call:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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.3. Render Pass Compatibility
Framebuffers and graphics pipelines are created based on a specific render pass object. They must only be used with that render pass object, or one compatible with it.
Two attachment references are compatible if they have matching format and
sample count, or are both VK_ATTACHMENT_UNUSED.
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.
If the pointer that would contain the reference is NULL, the attachment
reference is treated as VK_ATTACHMENT_UNUSED.
Two render passes are compatible if their corresponding color, input, resolve, and depth/stencil attachment references are compatible and if they are otherwise identical except for:
-
Initial and final image layout in attachment descriptions
-
Load and store operations in attachment descriptions
-
Image layout in attachment references
As an additional special case, if two render passes have a single subpass, the resolve attachment reference and depth/stencil resolve mode compatibility requirements are ignored.
A framebuffer is compatible with a render pass if it was created using the same render pass or a compatible render pass.
8.4. Framebuffers
Render passes operate in conjunction with framebuffers. Framebuffers represent a collection of specific memory attachments that a render pass instance uses.
Framebuffers are represented by VkFramebuffer handles:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkFramebuffer)
To create a framebuffer, call:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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. The implementation must not access this object outside of the duration of the command this structure is passed to. -
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.
It is legal for a subpass to use no color or depth/stencil attachments,
either because it has no attachment references or because all of them are
VK_ATTACHMENT_UNUSED.
This kind of subpass can use shader side effects such as image stores and
atomics to produce an output.
In this case, the subpass continues to use the width, height,
and layers of the framebuffer to define the dimensions of the
rendering area, and the rasterizationSamples from each pipeline’s
VkPipelineMultisampleStateCreateInfo to define the number of samples
used in rasterization; however, if
VkPhysicalDeviceFeatures::variableMultisampleRate is
VK_FALSE, then all pipelines to be bound with the subpass must have
the same value for
VkPipelineMultisampleStateCreateInfo::rasterizationSamples.
In all such cases, rasterizationSamples must be a valid
VkSampleCountFlagBits value that is set in
VkPhysicalDeviceLimits::framebufferNoAttachmentsSampleCounts.
The VkFramebufferAttachmentsCreateInfo structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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.
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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.5. Render Pass Load Operations
Render pass load operations define the initial values of an attachment during a render pass instance.
Load operations for attachments with a depth/stencil format execute in the
VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage.
Load operations for attachments with a color format execute in the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
The load operation for each sample in an attachment happens-before any
recorded command which accesses the sample in that render pass instance via
that attachment or an alias.
|
Note
|
Because load operations always happen first, external synchronization with
attachment access only needs to synchronize the load operations with
previous commands; not the operations within the render pass instance.
This does not apply when using |
Load operations only update values within the defined render area for the
render pass instance.
However, any writes performed by a load operation (as defined by its access
masks) to a given attachment may read and write back any memory locations
within the image subresource bound for that attachment.
For depth/stencil images,
if the maintenance7 feature is not enabled or
separateDepthStencilAttachmentAccess
is VK_FALSE,
writes to one aspect may also result in read-modify-write operations for
the other aspect.
If the subresource is bound to an attachment with
feedback loop enabled, implementations must not
access pixels outside of the render area.
|
Note
|
As entire subresources could be accessed by load operations, applications cannot safely access values outside of the render area during a render pass instance when a load operation that modifies values is used. |
Load operations that can be used for a render pass are:
// Provided by VK_VERSION_1_0
typedef enum VkAttachmentLoadOp {
VK_ATTACHMENT_LOAD_OP_LOAD = 0,
VK_ATTACHMENT_LOAD_OP_CLEAR = 1,
VK_ATTACHMENT_LOAD_OP_DONT_CARE = 2,
// Provided by VK_VERSION_1_4
VK_ATTACHMENT_LOAD_OP_NONE = 1000400000,
// Provided by VK_EXT_load_store_op_none
VK_ATTACHMENT_LOAD_OP_NONE_EXT = VK_ATTACHMENT_LOAD_OP_NONE,
// Provided by VK_KHR_load_store_op_none
VK_ATTACHMENT_LOAD_OP_NONE_KHR = VK_ATTACHMENT_LOAD_OP_NONE,
} VkAttachmentLoadOp;
-
VK_ATTACHMENT_LOAD_OP_LOADspecifies that the previous contents of the image within the render area will be preserved as the initial values. For attachments with a depth/stencil format, this uses the access typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT. For attachments with a color format, this uses the access typeVK_ACCESS_COLOR_ATTACHMENT_READ_BIT. -
VK_ATTACHMENT_LOAD_OP_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_NONEspecifies that the previous contents of the image will be undefined inside the render pass. No access type is used as the image is not accessed.
During a render pass instance, input and color attachments with color
formats that have a component size of 8, 16, or 32 bits must be represented
in the attachment’s format throughout the instance.
Attachments with other floating- or fixed-point color formats, or with depth
components may be represented in a format with a precision higher than the
attachment format, but must be represented with the same range.
When such a component is loaded via the loadOp, it will be converted
into an implementation-dependent format used by the render pass.
Such components must be converted from the render pass format, to the
format of the attachment, before they are resolved or stored at the end of a
render pass instance via storeOp.
Conversions occur as described in Numeric
Representation and Computation and Fixed-Point
Data Conversions.
8.6. Render Pass Store Operations
Render pass store operations define how values written to an attachment during a render pass instance are stored to memory.
Store operations for attachments with a depth/stencil format execute in the
VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage.
Store operations for attachments with a color format execute in the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
The store operation for each sample in an attachment happens-after any
recorded command which accesses the sample via that attachment or an alias.
|
Note
|
Because store operations always happen after other accesses in a render pass
instance, external synchronization with attachment access in an earlier
render pass only needs to synchronize with the store operations; not the
operations within the render pass instance.
This does not apply when using |
Store operations only update values within the defined render area for the
render pass instance.
However, any writes performed by a store operation (as defined by its access
masks) to a given attachment may read and write back any memory locations
within the image subresource bound for that attachment.
For depth/stencil images,
if
separateDepthStencilAttachmentAccess
is VK_FALSE,
writes to one aspect may also result in read-modify-write operations for
the other aspect.
If the subresource is bound to an attachment with
feedback loop enabled, implementations must not
access pixels outside of the render area.
|
Note
|
As entire subresources could be accessed by store operations, applications cannot safely access values outside of the render area via aliased resources during a render pass instance when a store operation that modifies values is used. |
Possible values of VkAttachmentDescription::storeOp and
stencilStoreOp, specifying how the contents of the attachment are
treated, are:
// Provided by VK_VERSION_1_0
typedef enum VkAttachmentStoreOp {
VK_ATTACHMENT_STORE_OP_STORE = 0,
VK_ATTACHMENT_STORE_OP_DONT_CARE = 1,
// Provided by VK_VERSION_1_3
VK_ATTACHMENT_STORE_OP_NONE = 1000301000,
// Provided by VK_KHR_dynamic_rendering, VK_KHR_load_store_op_none
VK_ATTACHMENT_STORE_OP_NONE_KHR = VK_ATTACHMENT_STORE_OP_NONE,
// Provided by VK_QCOM_render_pass_store_ops
VK_ATTACHMENT_STORE_OP_NONE_QCOM = VK_ATTACHMENT_STORE_OP_NONE,
// Provided by VK_EXT_load_store_op_none
VK_ATTACHMENT_STORE_OP_NONE_EXT = VK_ATTACHMENT_STORE_OP_NONE,
} VkAttachmentStoreOp;
-
VK_ATTACHMENT_STORE_OP_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 as long as no values are written to the attachment during the render pass. If values are written during the render pass, this behaves identically toVK_ATTACHMENT_STORE_OP_DONT_CAREand with matching access semantics.
|
Note
|
|
8.7. Render Pass Multisample Resolve Operations
Render pass multisample resolve operations combine sample values from a single pixel in a multisample attachment and store the result to the corresponding pixel in a single sample attachment.
Multisample resolve operations for attachments execute in the
VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
A final resolve operation for all pixels in the render area happens-after
any recorded command which writes a pixel via the multisample attachment to
be resolved or an explicit alias of it in the subpass that it is specified.
Any single sample attachment specified for use in a multisample resolve
operation may have its contents modified at any point once rendering begins
for the render pass instance.
Reads from the multisample attachment can be synchronized with
VK_ACCESS_COLOR_ATTACHMENT_READ_BIT.
Access to the single sample attachment can be synchronized with
VK_ACCESS_COLOR_ATTACHMENT_READ_BIT and
VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
These pipeline stage and access types are used whether the attachments are
color or depth/stencil attachments.
When using render pass objects, a subpass dependency specified with the above pipeline stages and access flags will ensure synchronization with multisample resolve operations for any attachments that were last accessed by that subpass. This allows later subpasses to read resolved values as input attachments.
Resolve operations only update values within the defined render area for the
render pass instance.
However, any writes performed by a resolve operation (as defined by its
access masks) to a given attachment may read and write back any memory
locations within the image subresource bound for that attachment.
For depth/stencil images,
if
separateDepthStencilAttachmentAccess
is VK_FALSE,
writes to one aspect may also result in read-modify-write operations for
the other aspect.
If the subresource is bound to an attachment with
feedback loop enabled, implementations must not
access pixels outside of the render area.
|
Note
|
As entire subresources could be accessed by multisample resolve operations, applications cannot safely access values outside of the render area via aliased resources during a render pass instance when a multisample resolve operation is performed. |
Multisample values in a multisample attachment are combined according to the resolve mode used:
// Provided by VK_VERSION_1_2
typedef enum VkResolveModeFlagBits {
VK_RESOLVE_MODE_NONE = 0,
VK_RESOLVE_MODE_SAMPLE_ZERO_BIT = 0x00000001,
VK_RESOLVE_MODE_AVERAGE_BIT = 0x00000002,
VK_RESOLVE_MODE_MIN_BIT = 0x00000004,
VK_RESOLVE_MODE_MAX_BIT = 0x00000008,
// Provided by VK_ANDROID_external_format_resolve with VK_KHR_dynamic_rendering or VK_VERSION_1_3
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROID = 0x00000010,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_NONE_KHR = VK_RESOLVE_MODE_NONE,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_SAMPLE_ZERO_BIT_KHR = VK_RESOLVE_MODE_SAMPLE_ZERO_BIT,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_AVERAGE_BIT_KHR = VK_RESOLVE_MODE_AVERAGE_BIT,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_MIN_BIT_KHR = VK_RESOLVE_MODE_MIN_BIT,
// Provided by VK_KHR_depth_stencil_resolve
VK_RESOLVE_MODE_MAX_BIT_KHR = VK_RESOLVE_MODE_MAX_BIT,
// Provided by VK_ANDROID_external_format_resolve with VK_KHR_dynamic_rendering or VK_VERSION_1_3
// VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID is a deprecated alias
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID = VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROID,
} VkResolveModeFlagBits;
or the equivalent
// Provided by VK_KHR_depth_stencil_resolve
typedef VkResolveModeFlagBits VkResolveModeFlagBitsKHR;
-
VK_RESOLVE_MODE_NONEspecifies that no resolve operation is done. -
VK_RESOLVE_MODE_SAMPLE_ZERO_BITspecifies that result of the resolve operation is equal to the value of sample 0. -
VK_RESOLVE_MODE_AVERAGE_BITspecifies that result of the resolve operation is the average of the sample values. -
VK_RESOLVE_MODE_MIN_BITspecifies that result of the resolve operation is the minimum of the sample values. -
VK_RESOLVE_MODE_MAX_BITspecifies that result of the resolve operation is the maximum of the sample values. -
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROIDspecifies that rather than a multisample resolve, a single sampled color attachment will be downsampled into a Y′CBCR format image specified by an external Android format. Unlike other resolve modes, implementations can resolve multiple times during rendering, or even bypass writing to the color attachment altogether, as long as the final value is resolved to the resolve attachment. Values in the G, B, and R channels of the color attachment will be written to the Y, CB, and CR channels of the external format image, respectively. Chroma values are calculated as if sampling with a linear filter from the color attachment at full rate, at the location the chroma values sit according to VkPhysicalDeviceExternalFormatResolvePropertiesANDROID::externalFormatResolveChromaOffsetX, VkPhysicalDeviceExternalFormatResolvePropertiesANDROID::externalFormatResolveChromaOffsetY, and the chroma sample rate of the resolved image.
If no resolve mode is otherwise specified, VK_RESOLVE_MODE_AVERAGE_BIT
is used.
If VK_RESOLVE_MODE_AVERAGE_BIT is used, and the source format is a
floating-point or normalized type, the sample values for each pixel are
resolved with implementation-defined numerical precision.
If the numeric format of the resolve attachment uses sRGB encoding, the implementation should convert samples from nonlinear to linear before averaging samples as described in the “sRGB EOTF” section of the Khronos Data Format Specification. In this case, the implementation must convert the linear averaged value to nonlinear before writing the resolved result to resolve attachment.
|
Note
|
No range compression or Y′CBCR model conversion is performed by
|
// Provided by VK_VERSION_1_2
typedef VkFlags VkResolveModeFlags;
or the equivalent
// Provided by VK_KHR_depth_stencil_resolve
typedef VkResolveModeFlags VkResolveModeFlagsKHR;
VkResolveModeFlags is a bitmask type for setting a mask of zero or
more VkResolveModeFlagBits.
8.8. Render Pass Commands
An application records the commands for a render pass instance one subpass at a time, by beginning a render pass instance, iterating over the subpasses to record commands for that subpass, and then ending the render pass instance.
To begin a render pass instance, call:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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. After recording this command, the render pass and framebuffer may be accessed at any point thatcommandBufferis in the recording or pending state until it is reset. -
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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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 multiview is enabled in renderPass, and
multiviewPerViewRenderAreas
feature is enabled, and there is an instance of
VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM included in the
pNext chain with perViewRenderAreaCount not equal to 0, then
the elements of
VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas
override renderArea and define a render area for each view.
In this case, renderArea must be an area at least as large as the
union of all the per-view render areas.
If the subpassShading feature is enabled,
then renderArea must equal the framebuffer dimensions.
|
Note
|
There may be a performance cost for using a render area smaller than the framebuffer, unless it matches the render area granularity for the render pass. |
The image layout of the depth aspect of a depth/stencil attachment referring
to an image created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent
on the last sample locations used to render to the image subresource, thus
preserving the contents of such depth/stencil attachments across subpass
boundaries requires the application to specify these sample locations
whenever a layout transition of the attachment may occur.
This information can be provided by adding a
VkRenderPassSampleLocationsBeginInfoEXT structure to the pNext
chain of VkRenderPassBeginInfo.
The VkRenderPassSampleLocationsBeginInfoEXT structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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;
const void* pNext;
VkSurfaceTransformFlagBitsKHR transform;
} VkRenderPassTransformBeginInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
transformis a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to rasterization.
The tile properties queried using VK_QCOM_tile_properties depend on the size of the reserved tile memory by the application. This size can be specified by the following structure to VkRenderPassCreateInfo, VkRenderPassCreateInfo2 , or VkRenderingInfo to specify the reserved tile memory size for the render pass object.
For dynamic render passes, this structure can be attached to the
pNext member of VkRenderingInfo passed to
vkGetDynamicRenderingTilePropertiesQCOM.
The VkTileMemorySizeInfoQCOM structure is defined as:
// Provided by VK_QCOM_tile_memory_heap with VK_QCOM_tile_properties
typedef struct VkTileMemorySizeInfoQCOM {
VkStructureType sType;
const void* pNext;
VkDeviceSize size;
} VkTileMemorySizeInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sizeis the size in bytes of tile memory used by the render pass or preserved for later use.
The returned tile properties are invalid if the size is not equal to
the bound tile memory’s allocation size when
the render pass is executed.
If this structure is not provided, the size of the reserved region
defaults to 0.
|
Note
|
Tile memory is reserved for application use by binding tile memory objects to the command buffer. The size provided by this command is informational only for use when evaluating tile properties. If the application does not need to query the tile properties, then this size can be safely omitted. |
The VkSubpassBeginInfo structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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,
// Provided by VK_KHR_maintenance7
VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR = 1000451000,
// Provided by VK_EXT_nested_command_buffer
VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT = VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR,
} VkSubpassContents;
-
VK_SUBPASS_CONTENTS_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 in the command buffer until vkCmdNextSubpass or vkCmdEndRenderPass. -
VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHRspecifies that the contents of the subpass can be recorded both inline and in secondary command buffers executed from this command buffer with vkCmdExecuteCommands.
If the pNext chain of VkRenderPassBeginInfo
or VkRenderingInfo
includes a VkDeviceGroupRenderPassBeginInfo structure, then that
structure includes a device mask and set of render areas for the render pass
instance.
The VkDeviceGroupRenderPassBeginInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupRenderPassBeginInfo {
VkStructureType sType;
const void* pNext;
uint32_t deviceMask;
uint32_t deviceRenderAreaCount;
const VkRect2D* pDeviceRenderAreas;
} VkDeviceGroupRenderPassBeginInfo;
or the equivalent
// Provided by VK_KHR_device_group
typedef VkDeviceGroupRenderPassBeginInfo VkDeviceGroupRenderPassBeginInfoKHR;
-
sTypeis a VkStructureType value identifying 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 load,
store, and multisample resolve operations and subpass dependencies corresponding to
the render pass instance, are executed on the physical devices included in
the device mask provided here.
If deviceRenderAreaCount is not zero, then the elements of
pDeviceRenderAreas override the value of
VkRenderPassBeginInfo::renderArea, and provide a render area
specific to each physical device.
These render areas serve the same purpose as
VkRenderPassBeginInfo::renderArea, including controlling the
region of attachments that are cleared by VK_ATTACHMENT_LOAD_OP_CLEAR
and that are resolved into resolve attachments.
If this structure is not present, the render pass instance’s device mask is
the value of VkDeviceGroupCommandBufferBeginInfo::deviceMask.
If this structure is not present or if deviceRenderAreaCount is zero,
VkRenderPassBeginInfo::renderArea is used for all physical
devices.
The VkRenderPassAttachmentBeginInfo structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying 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.
If a render pass instance enables multiview and if the
multiviewPerViewRenderAreas
feature is enabled, the
VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure can be
included in the pNext chain of VkRenderPassBeginInfo
or VkRenderingInfo
The VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure is
defined as:
// Provided by VK_QCOM_multiview_per_view_render_areas
typedef struct VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM {
VkStructureType sType;
const void* pNext;
uint32_t perViewRenderAreaCount;
const VkRect2D* pPerViewRenderAreas;
} VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
perViewRenderAreaCountis the number of elements in thepPerViewRenderAreasarray. -
pPerViewRenderAreasis a pointer to an array of VkRect2D structures defining the render area for each view.
If perViewRenderAreaCount is not zero, then the elements of
pPerViewRenderAreas override the value of
VkRenderPassBeginInfo::renderArea
or VkRenderingInfo::renderArea
and define per-view render areas for the individual views of a multiview
render pass.
The render area for the view with view index i is specified by
pPerViewRenderAreas[i].
The per-view render areas define per-view regions of attachments that are
loaded, stored, and resolved according to the loadOp, storeOp,
and resolveMode values of the render pass instance.
When per-view render areas are defined, the value of
VkRenderPassBeginInfo::renderArea
or VkRenderingInfo::renderArea
must be a render area that includes the union of all per-view render areas,
may be used by the implementation for optimizations, but does not affect
loads, stores, or resolves.
If this structure is present and if perViewRenderAreaCount is not
zero, then perViewRenderAreaCount must be at least one greater than
the most significant bit set in any element of
VkRenderPassMultiviewCreateInfo::pViewMasks.
or VkRenderingInfo::viewMask
If this structure is not present or if perViewRenderAreaCount is zero,
VkRenderPassBeginInfo::renderArea
or VkRenderingInfo::renderArea
is used for all views.
To query the render area granularity, call:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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.
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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.2. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 last subpass will be ended.
vkCmdEndRenderPass2 is semantically identical to
vkCmdEndRenderPass, except that it is extensible.
The VkSubpassEndInfo structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkSubpassEndInfo::pNext chain
or VkRenderingEndInfoEXT::pNext chain
includes a VkRenderPassFragmentDensityMapOffsetEndInfoEXT structure,
then that structure includes an array of fragment density map offsets per
layer for the render pass.
The VkRenderPassFragmentDensityMapOffsetEndInfoEXT structure is
defined as:
// Provided by VK_EXT_fragment_density_map_offset
typedef struct VkRenderPassFragmentDensityMapOffsetEndInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t fragmentDensityOffsetCount;
const VkOffset2D* pFragmentDensityOffsets;
} VkRenderPassFragmentDensityMapOffsetEndInfoEXT;
or the equivalent:
// Provided by VK_QCOM_fragment_density_map_offset
typedef VkRenderPassFragmentDensityMapOffsetEndInfoEXT VkSubpassFragmentDensityMapOffsetEndInfoQCOM;
-
sTypeis a VkStructureType value identifying 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.
If neither the VkSubpassEndInfo::pNext chain for the last
subpass of a render pass nor the VkRenderingEndInfoEXT::pNext
chain of a dynamic render pass include
VkRenderPassFragmentDensityMapOffsetEndInfoEXT, or if
fragmentDensityOffsetCount is zero, then the offset (0,0) is
used for Fetch Density Value.
8.9. Render Pass Creation Feedback
A VkRenderPassCreationControlEXT structure can be included in the
pNext chain of VkRenderPassCreateInfo2 or pNext chain of
VkSubpassDescription2.
The VkRenderPassCreationControlEXT structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationControlEXT {
VkStructureType sType;
const void* pNext;
VkBool32 disallowMerging;
} VkRenderPassCreationControlEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationFeedbackCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkRenderPassCreationFeedbackInfoEXT* pRenderPassFeedback;
} VkRenderPassCreationFeedbackCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pRenderPassFeedbackis a pointer to a VkRenderPassCreationFeedbackInfoEXT structure in which feedback is returned.
The VkRenderPassCreationFeedbackInfoEXT structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassSubpassFeedbackCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkRenderPassSubpassFeedbackInfoEXT* pSubpassFeedback;
} VkRenderPassSubpassFeedbackCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pSubpassFeedbackis a pointer to a VkRenderPassSubpassFeedbackInfoEXT structure in which feedback is returned.
The VkRenderPassSubpassFeedbackInfoEXT structure is defined as:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.4. See Deprecated Functionality for more information. |
// 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 the 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 that the subpass is merged with a previous subpass. -
VK_SUBPASS_MERGE_STATUS_DISALLOWED_EXTspecifies that the subpass is not merged because merging was disabled using VkRenderPassCreationControlEXT. 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 that the subpass is not merged because it contains side effects. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SAMPLES_MISMATCH_EXTspecifies that the subpass is not merged because sample count is not compatible with the previous subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_VIEWS_MISMATCH_EXTspecifies that the subpass is not merged because view masks do not match with previous subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_ALIASING_EXTspecifies that the subpass is not merged because of attachments aliasing between them. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPENDENCIES_EXTspecifies that the subpass is not merged because subpass dependencies do not allow merging. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INCOMPATIBLE_INPUT_ATTACHMENT_EXTspecifies that 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 that the subpass is not merged because of too many attachments. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INSUFFICIENT_STORAGE_EXTspecifies that the subpass is not merged because of insufficient memory. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPTH_STENCIL_COUNT_EXTspecifies that the subpass is not merged because of too many depth/stencil attachments. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_RESOLVE_ATTACHMENT_REUSE_EXTspecifies that 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 that the subpass is not merged because the render pass has only one subpass. -
VK_SUBPASS_MERGE_STATUS_NOT_MERGED_UNSPECIFIED_EXTspecifies that the subpass is not merged for unspecified reasons. Implementations should return this value when no otherVkSubpassMergeStatusEXTvalue is appropriate.
8.10. Common Render Pass Data Races (Informative)
Due to the complexity of how rendering is performed, there are several ways an application can accidentally introduce a data race, usually by doing something that may seem benign but actually cannot be supported. This section indicates a number of the more common cases as guidelines to help avoid them.
8.10.1. Sampling From a Read-Only Attachment
Vulkan includes read-only layouts for depth/stencil images, that allow the images to be both read during a render pass for the purposes of depth/stencil tests, and read as a non-attachment.
However, because VK_ATTACHMENT_STORE_OP_STORE and
VK_ATTACHMENT_STORE_OP_DONT_CARE may perform write operations, even if
no recorded command writes to an attachment, reading from an image while
also using it as an attachment with these store operations can result in a
data race.
If the reads from the non-attachment are performed in a fragment shader
where the accessed samples match those covered by the fragment shader, no
data race will occur as store operations are guaranteed to operate after
fragment shader execution for the set of samples the fragment covers.
Notably, input attachments can also be used for this case.
Reading other samples or in any other shader stage can result in unexpected
behavior due to the potential for a data race, and validation errors should
be generated for doing so.
In practice, many applications have shipped reading samples outside of the
covered fragment without any observable issue, but there is no guarantee
that this will always work, and it is not advisable to rely on this in new
or re-worked code bases.
As VK_ATTACHMENT_STORE_OP_NONE is guaranteed to perform no writes,
applications wishing to read an image as both an attachment and a
non-attachment should make use of this store operation, coupled with a load
operation that also performs no writes.
8.10.2. Non-Overlapping Access Between Resources
When relying on non-overlapping accesses between attachments and other resources, it is important to note that load and store operations have fairly wide alignment requirements - potentially affecting entire subresources and adjacent depth/stencil aspects. This makes it invalid to access a non-attachment subresource that is simultaneously being used as an attachment where either access performs a write operation.
The only exception to this is if a subresource is explicitly specified for use as a feedback loop attachment. Feedback loop is enabled for an attachment if either of the following conditions are satisfied:
-
The corresponding image is in the
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXTlayout -
For the attachment identified by VkRenderingAttachmentInfo::
imageView, VkAttachmentFeedbackLoopInfoEXT::feedbackLoopEnableisVK_TRUE
In that case the overlap is defined to occur at a per-pixel granularity, and applications can read data from pixels outside the render area without introducing a data race.
8.10.3. Depth/Stencil and Input Attachments
When rendering to only the depth OR stencil aspect of an image, an input
attachment accessing the other aspect will
not cause a data race only under very specific conditions.
To avoid a data race, the aspect not being written must be in a read-only
layout, and writes to it must be disabled in the draw state.
For example, to read from stencil while writing depth, the attachment must
be in VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL (or
equivalent), and the stencil write mask must be 0.
Similarly to read from depth while writing stencil, the attachment must be
in VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL (or
equivalent), and depth write enable must be VK_FALSE.
8.10.4. Synchronization Options
There are several synchronization options available to synchronize between accesses to resources within a render pass. Some of the options are outlined below:
-
A VkSubpassDependency in a render pass object can synchronize attachment writes and multisample resolve operations from a prior subpass for subsequent input attachment reads.
-
A vkCmdPipelineBarrier inside a subpass can synchronize prior attachment writes in the subpass with subsequent input attachment reads.
-
A vkCmdPipelineBarrier inside a subpass can synchronize prior attachment writes in the subpass with subsequent non-attachment reads if feedback loop is enabled for the attachment.
-
If a subresource is used as a color and input attachment, and the pipeline performing the read was created with
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT -
If a subresource is used as a depth and input attachment, and the pipeline performing the read was created with
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT -
If a subresource is used as a stencil and input attachment, and the pipeline performing the read was created with
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT -
If a subresource is used as two separate non-attachment resources, writes to a pixel or individual sample in a fragment shader can be synchronized with access to the same pixel or sample in another fragment shader by using one of the fragment interlock execution modes.
8.11. Tile Shading Render Pass
Tile shading can be enabled within a render pass.
To enable tile shading for a render pass object, add a
VkRenderPassTileShadingCreateInfoQCOM to the pNext chain of
VkRenderPassCreateInfo
or VkRenderPassCreateInfo2
.
To enable tile shading for a dynamic render pass, add a
VkRenderPassTileShadingCreateInfoQCOM to the pNext chain of
VkRenderingInfo.
To execute a secondary command buffer within a render pass, add a
VkRenderPassTileShadingCreateInfoQCOM to the pNext chain of
VkCommandBufferInheritanceInfo when the secondary command buffer is
recorded.
The VkRenderPassTileShadingCreateInfoQCOM structure is defined as:
// Provided by VK_QCOM_tile_shading
typedef struct VkRenderPassTileShadingCreateInfoQCOM {
VkStructureType sType;
const void* pNext;
VkTileShadingRenderPassFlagsQCOM flags;
VkExtent2D tileApronSize;
} VkRenderPassTileShadingCreateInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkTileShadingRenderPassFlagBitsQCOM. -
tileApronSizeis a VkExtent2D describing the is size of the tiling apron in each dimension.
If this structure is not present, the render pass will have flags set
to 0 and tileApronSize is set to (0,0).
Bits which can be set in
VkRenderPassTileShadingCreateInfoQCOM::flags describing
additional properties of the render pass are:
// Provided by VK_QCOM_tile_shading
typedef enum VkTileShadingRenderPassFlagBitsQCOM {
VK_TILE_SHADING_RENDER_PASS_ENABLE_BIT_QCOM = 0x00000001,
VK_TILE_SHADING_RENDER_PASS_PER_TILE_EXECUTION_BIT_QCOM = 0x00000002,
} VkTileShadingRenderPassFlagBitsQCOM;
-
VK_TILE_SHADING_RENDER_PASS_ENABLE_BIT_QCOMspecifies that the render pass has tile shading enabled. -
VK_TILE_SHADING_RENDER_PASS_PER_TILE_EXECUTION_BIT_QCOMspecifies that the secondary command buffer will be executed within a per-tile execution block.
// Provided by VK_QCOM_tile_shading
typedef VkFlags VkTileShadingRenderPassFlagsQCOM;
VkTileShadingRenderPassFlagsQCOM is a bitmask type for setting a mask
of zero or more VkTileShadingRenderPassFlagBitsQCOM.
8.11.1. Tile Attachment Variables
Within a tile shading render pass, fragment and compute shader invocations can use the Tile Attachment Interface to perform load/store, operations on storage tile attachment variables, to perform load operations on input tile attachment variables, and to perform sampling operations on sampled tile attachment variables. Storage tile attachment, sampled tile attachment, and input tile attachment variables must be declared and used as described in the tile attachment interface.
8.11.2. Tiling Aprons
In a render pass that enables tile shading, a
tiling apron can be enabled by setting
VkRenderPassTileShadingCreateInfoQCOM::tileApronSize to a value
other than (0,0).
Additionally, subpass flags must include
VK_SUBPASS_DESCRIPTION_TILE_SHADING_APRON_BIT_QCOM
if the render pass is not a dynamic render pass
or the apron size for that subpass will be (0,0).
The tile apron enables shader invocations to load from tile attachment
variables at a location that is outside the current tile.
The width and height value of tileApronSize specifies the
number of pixels in the horizontal and vertical directions that are included
in the apron region.
For example, (1,1) means that the apron region extends the top, bottom, left
and right margins of the tile by 1 pixel.
The tileApronSize must not exceed
VkPhysicalDeviceTileShadingPropertiesQCOM::maxApronSize.
|
Note
|
A good mental model for the tiling apron is to think of it as enabling
"overlapping tiles".
The top/bottom and left/right margins of each tile are extended to include a
few pixels of the adjacent tiles.
Those pixels that are outside the original tile extents, but within the
apron extents are "apron pixels".
In a render pass that enables tile shading, apron pixels will be initialized
by the For image processing use-cases, the tiling apron allows fragment and compute shader invocations to read or sample color attachment pixels within the neighborhood of a given fragment, even if the given fragment is close to a tile edge. Enabling the apron may reduce the GPU efficiency, with larger apron sizes having a greater potential impact. Aprons should be enabled only when needing to access pixels outside the tile. |
8.11.3. Tile Attachment Coordinate Validation
Image operations that access a tile attachment can use normalized,
unnormalized, or integer texel coordinates, but the final set of (i,j,[k])
integer texel coordinates accessed in texel
filtering must be within the extents of the current tile and apron as
well as within the render pass renderArea.
Any out of bounds access will result in undefined values.
The robustImageAccess and robustImageAccess2 features do not apply to tile attachment accesses.
The built-in variables
TileOffsetQCOM,
TileApronSizeQCOM, and
TileDimensionQCOM define the
extent of the current tile and apron.
For storage tile attachment stores using OpImageWrite and with an
Image operand from storage class TileAttachmentQCOM, the
Coordinate operand must specify a framebuffer location
within the render pass renderArea and within the extent of the tile.
For storage tile attachment using OpImageRead or
OpImageSparseRead, or input tile attachment loads using
OpImageRead, and with an Image operand from storage class
TileAttachmentQCOM, the Coordinate operand must
specify a framebuffer location within the render pass renderArea and
within the combined extent of the tile and apron.
where:
-
represents
offsetoperand toOpImageWrite -
represents
offsetoperand toOpImageRead -
represents TileOffsetQCOM
-
represents TileDimensionQCOM
-
represents the render pass
renderArea.offset -
represents the render pass
renderArea.extent -
represents TileApronSizeQCOM
For storage tile attachment atomic operations using
OpImageTexelPointer, the Coordinate operand must specify a
framebuffer location within the render pass RenderArea and within the
extent of the tile.
The Coordinate must not point to the apron region.
When accessing a sampled tile attachment using OpImageSample*,
OpImageSparseSample*, OpImageFetch, OpImageSparseFetch*,
OpImageSampleWeightedQCOM, OpImageBoxFilterQCOM,
OpImageBlockMatch*QCOM,
OpImage*Gather, or OpImageSparse*Gather, and with an Image
operand from storage class TileAttachmentQCOM, the Coordinate
operand must not result in a any texels accessed that are outside the
renderArea or outside the combined extent of the tile and apron.
|
Note
|
It is the application’s responsibility to guarantee that the instruction and texture coordinates do not cause any out of bounds texels to be accessed as a result of loads, stores, atomics, or the sampling filter. In practice, this may require that the coordinates are clamped in the shader code. |
8.11.4. Tile Shading Fragment Regions
If tile shading is enabled for a render pass
instance, then framebuffer-local
dependencies defined using VK_DEPENDENCY_BY_REGION_BIT specify a
framebuffer region equal to the
region covered by the active tile.
When per-tile execution model is
enabled an active tile is associated with each of the per-tile command
invocations with an extent described by shader built-in variables
TileOffsetQCOM,
TileDimensionQCOM, and
TileApronSizeQCOM.
Otherwise, the extent of the active tile is defined by the tile exposed by
VK_QCOM_tile_properties that contains the framebuffer coordinate
of the fragment being processed.
|
Note
|
Without tile shading the framebuffer
region described by The larger tile-sized framebuffer region provided by tile shading allows applications to achieve increased rendering efficiency on some tiling architectures. It enables synchronization commands with a framebuffer-local dependency to be used for a dependency across fragments with different framebuffer coordinates, as long as the fragments are located within the same tile. In this situation, it avoids an otherwise required framebuffer-global dependency and corresponding data flushing to memory as noted in the synchronization chapter. |
8.11.5. Per-Tile Execution Model
Within a tile shading render pass instance, the per-tile execution model can be enabled.
To enable the per-tile execution model, call:
// Provided by VK_QCOM_tile_shading
void vkCmdBeginPerTileExecutionQCOM(
VkCommandBuffer commandBuffer,
const VkPerTileBeginInfoQCOM* pPerTileBeginInfo);
-
commandBufferis the command buffer in which to record the command. -
pPerTileBeginInfois a pointer to a VkPerTileBeginInfoQCOM structure containing information about how the per-tile execution model is started.
When per-tile execution model is enabled, recorded vkCmdDraw* or
vkCmdDispatch* commands are invoked per tile.
That is, the recorded draw or dispatch is invoked exactly once for each
covered tile.
The set of covered tiles for a given render pass instance consists of the
set of render pass tiles, which can be queried with
VK_QCOM_tile_properties, that are completely or partially covered
by the renderArea for the render pass instance.
The draw or dispatch commands may be invoked for uncovered tiles.
Each per-tile command invocation is associated with a single tile, the active tile. These per-tile invocations are not specified to execute in any particular order, but the size and offset of the active tile is available via shader built-ins.
When per-tile execution model is enabled, the following restrictions apply:
-
Transform feedback commands such as vkCmdBeginTransformFeedbackEXT, vkCmdEndTransformFeedbackEXT, vkCmdBeginQueryIndexedEXT, and vkCmdEndQueryIndexedEXT, must not be recorded.
-
Query commands such as vkCmdWriteTimestamp, vkCmdDebugMarkerBeginEXT, vkCmdDebugMarkerEndEXT, vkCmdDebugMarkerInsertEXT, vkCmdBeginQuery, and vkCmdEndQuery, must not be recorded.
-
Event commands such as vkCmdWaitEvents2 and vkCmdWaitEvents must not be recorded.
-
Render pass clears like vkCmdClearAttachments must not be recorded
-
Access of an attachment with layout
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXTas provided byVK_EXT_attachment_feedback_loop_layoutis disallowed -
Any commands that would cause a invocations of one of the following shader stages are not allowed
-
tessellation
-
geometry
-
ray tracing
-
mesh shading
-
The VkPerTileBeginInfoQCOM structure is defined as:
// Provided by VK_QCOM_tile_shading
typedef struct VkPerTileBeginInfoQCOM {
VkStructureType sType;
const void* pNext;
} VkPerTileBeginInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
To disable per-tile execution model, call:
// Provided by VK_QCOM_tile_shading
void vkCmdEndPerTileExecutionQCOM(
VkCommandBuffer commandBuffer,
const VkPerTileEndInfoQCOM* pPerTileEndInfo);
-
commandBufferis the command buffer in which to record the command. -
pPerTileEndInfois a pointer to a VkPerTileEndInfoQCOM structure containing information about how the per-tile execution model is ended.
This command disables per-tile execution model.
The VkPerTileEndInfoQCOM structure is defined as:
// Provided by VK_QCOM_tile_shading
typedef struct VkPerTileEndInfoQCOM {
VkStructureType sType;
const void* pNext;
} VkPerTileEndInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
8.11.6. Area-Based Dispatch
When the per-tile execution model is enabled, the command vkCmdDispatchTileQCOM can be used to provide an area-based dispatch, where the implementation determines the work group count and size based on the tile size and a given shading rate.
9. Shaders
A shader specifies programmable operations that execute for each vertex, control point, tessellated vertex, primitive, fragment, or workgroup in the corresponding stage(s) of the graphics and compute pipelines.
Graphics pipelines include vertex shader execution as a result of primitive assembly, followed, if enabled, by tessellation control and evaluation shaders operating on patches, geometry shaders, if enabled, operating on primitives, and fragment shaders, if present, operating on fragments generated by Rasterization. In this specification, vertex, tessellation control, tessellation evaluation and geometry shaders are collectively referred to as pre-rasterization shader stages and occur in the logical pipeline before rasterization. The fragment shader occurs logically after rasterization.
Only the compute shader stage is included in a compute pipeline. Compute shaders operate on compute invocations in a workgroup.
Shaders can read from input variables, and read from and write to output variables. Input and output variables can be used to transfer data between shader stages, or to allow the shader to interact with values that exist in the execution environment. Similarly, the execution environment provides constants describing capabilities.
Shader variables are associated with execution environment-provided inputs and outputs using built-in decorations in the shader. The available decorations for each stage are documented in the following subsections.
9.1. Shader Objects
Shaders may be compiled and linked into pipeline objects as described in
Pipelines chapter, or if the shaderObject feature is enabled they may be compiled into
individual per-stage shader objects which can be bound on a command
buffer independently from one another.
Unlike pipelines, shader objects are not intrinsically tied to any specific
set of state.
Instead, state is specified dynamically in the command buffer.
Each shader object represents a single compiled shader stage, which may optionally be linked with one or more other stages.
Shader objects are represented by VkShaderEXT handles:
// Provided by VK_EXT_shader_object
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkShaderEXT)
9.1.1. Shader Object Creation
Shader objects may be created from shader code provided as SPIR-V, or in an opaque, implementation-defined binary format specific to the physical device.
To create one or more shader objects, call:
// Provided by VK_EXT_shader_object
VkResult vkCreateShadersEXT(
VkDevice device,
uint32_t createInfoCount,
const VkShaderCreateInfoEXT* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkShaderEXT* pShaders);
-
deviceis the logical device that creates the shader objects. -
createInfoCountis the length of thepCreateInfosandpShadersarrays. -
pCreateInfosis a pointer to an array of VkShaderCreateInfoEXT structures. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pShadersis a pointer to an array of VkShaderEXT handles in which the resulting shader objects are returned.
When this function returns, whether or not it succeeds, it is guaranteed
that every element of pShaders will have been overwritten by either
VK_NULL_HANDLE or a valid VkShaderEXT handle.
This means that whenever shader creation fails, the application can
determine which shader the returned error pertains to by locating the first
VK_NULL_HANDLE element in pShaders.
It also means that an application can reliably clean up from a failed call
by iterating over the pShaders array and destroying every element that
is not VK_NULL_HANDLE.
The VkShaderCreateInfoEXT structure is defined as:
// Provided by VK_EXT_shader_object
typedef struct VkShaderCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkShaderCreateFlagsEXT flags;
VkShaderStageFlagBits stage;
VkShaderStageFlags nextStage;
VkShaderCodeTypeEXT codeType;
size_t codeSize;
const void* pCode;
const char* pName;
uint32_t setLayoutCount;
const VkDescriptorSetLayout* pSetLayouts;
uint32_t pushConstantRangeCount;
const VkPushConstantRange* pPushConstantRanges;
const VkSpecializationInfo* pSpecializationInfo;
} VkShaderCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkShaderCreateFlagBitsEXT describing additional parameters of the shader. -
stageis a VkShaderStageFlagBits value specifying a single shader stage. -
nextStageis a bitmask of VkShaderStageFlagBits specifying which stages may be used as a logically next bound stage when drawing with the shader bound. A value of zero indicates this shader stage must be the last one. -
codeTypeis a VkShaderCodeTypeEXT value specifying the type of the shader code pointed to bepCode. -
codeSizeis the size in bytes of the shader code pointed to bepCode. -
pCodeis a pointer to the shader code to use to create the shader. -
pNameis a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage. -
setLayoutCountis the number of descriptor set layouts pointed to bypSetLayouts. -
pSetLayoutsis a pointer to an array of VkDescriptorSetLayout objects used by the shader stage. The implementation must not access these objects outside of the duration of the command this structure is passed to. -
pushConstantRangeCountis the number of push constant ranges pointed to bypPushConstantRanges. -
pPushConstantRangesis a pointer to an array of VkPushConstantRange structures used by the shader stage. -
pSpecializationInfois a pointer to a VkSpecializationInfo structure, as described in Specialization Constants, orNULL.
// Provided by VK_EXT_shader_object
typedef VkFlags VkShaderCreateFlagsEXT;
VkShaderCreateFlagsEXT is a bitmask type for setting a mask of zero or
more VkShaderCreateFlagBitsEXT.
Possible values of the flags member of VkShaderCreateInfoEXT
specifying how a shader object is created, are:
// Provided by VK_EXT_shader_object
typedef enum VkShaderCreateFlagBitsEXT {
VK_SHADER_CREATE_LINK_STAGE_BIT_EXT = 0x00000001,
// Provided by VK_EXT_shader_object with VK_EXT_subgroup_size_control or VK_VERSION_1_3
VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT = 0x00000002,
// Provided by VK_EXT_shader_object with VK_EXT_subgroup_size_control or VK_VERSION_1_3
VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT = 0x00000004,
// Provided by VK_EXT_shader_object with VK_EXT_mesh_shader or VK_NV_mesh_shader
VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT = 0x00000008,
// Provided by VK_EXT_shader_object with VK_KHR_device_group or VK_VERSION_1_1
VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT = 0x00000010,
// Provided by VK_KHR_fragment_shading_rate with VK_EXT_shader_object
VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT = 0x00000020,
// Provided by VK_EXT_fragment_density_map with VK_EXT_shader_object
VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00000040,
// Provided by VK_EXT_device_generated_commands
VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT = 0x00000080,
} VkShaderCreateFlagBitsEXT;
-
VK_SHADER_CREATE_LINK_STAGE_BIT_EXTspecifies that a shader is linked to all other shaders created in the same vkCreateShadersEXT call whose VkShaderCreateInfoEXT structures'flagsincludeVK_SHADER_CREATE_LINK_STAGE_BIT_EXT. -
VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXTspecifies that theSubgroupSizemay vary in a task, mesh, or compute shader. -
VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXTspecifies that the subgroup sizes must be launched with all invocations active in a task, mesh, or compute shader. -
VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXTspecifies that a mesh shader must only be used without a task shader. Otherwise, the mesh shader must only be used with a task shader. -
VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXTspecifies that a compute shader can be used with vkCmdDispatchBase with a non-zero base workgroup. -
VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXTspecifies that a fragment shader can be used with a fragment shading rate attachment. -
VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXTspecifies that a fragment shader can be used with a fragment density map attachment. -
VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXTspecifies that the shader can be used in combination with Device-Generated Commands.
|
Note
|
The behavior of
|
Shader objects can be created using different types of shader code.
Possible values of VkShaderCreateInfoEXT::codeType, are:
// Provided by VK_EXT_shader_object
typedef enum VkShaderCodeTypeEXT {
VK_SHADER_CODE_TYPE_BINARY_EXT = 0,
VK_SHADER_CODE_TYPE_SPIRV_EXT = 1,
} VkShaderCodeTypeEXT;
-
VK_SHADER_CODE_TYPE_BINARY_EXTspecifies shader code in an opaque, implementation-defined binary format specific to the physical device. -
VK_SHADER_CODE_TYPE_SPIRV_EXTspecifies shader code in SPIR-V format.
9.1.2. Binary Shader Code
Binary shader code can be retrieved from a shader object using the command:
// Provided by VK_EXT_shader_object
VkResult vkGetShaderBinaryDataEXT(
VkDevice device,
VkShaderEXT shader,
size_t* pDataSize,
void* pData);
-
deviceis the logical device that shader object was created from. -
shaderis the shader object to retrieve binary shader code from. -
pDataSizeis a pointer to asize_tvalue related to the size of the binary shader code, as described below. -
pDatais eitherNULLor a pointer to a buffer.
If pData is NULL, then the size of the binary shader code of the
shader object, in bytes, is returned in pDataSize.
Otherwise, pDataSize must point to a variable set by the application
to the size of the buffer, in bytes, pointed to by pData, and on
return the variable is overwritten with the amount of data actually written
to pData.
If pDataSize is less than the size of the binary shader code, nothing
is written to pData, and VK_INCOMPLETE will be returned instead
of VK_SUCCESS.
|
Note
|
The behavior of this command when This behavior is not consistent with the behavior described in Opaque Binary Data Results, for historical reasons. If the amount of data available is larger than the passed |
Binary shader code retrieved using vkGetShaderBinaryDataEXT can be
passed to a subsequent call to vkCreateShadersEXT on a compatible
physical device by specifying VK_SHADER_CODE_TYPE_BINARY_EXT in the
codeType member of VkShaderCreateInfoEXT.
The shader code returned by repeated calls to this function with the same
VkShaderEXT is guaranteed to be invariant for the lifetime of the
VkShaderEXT object.
9.1.3. Binary Shader Compatibility
Binary shader compatibility means that binary shader code returned from a call to vkGetShaderBinaryDataEXT can be passed to a later call to vkCreateShadersEXT, potentially on a different logical and/or physical device, and that this will result in the successful creation of a shader object functionally equivalent to the shader object that the code was originally queried from.
Binary shader code queried from vkGetShaderBinaryDataEXT is not guaranteed to be compatible across all devices, but implementations are required to provide some compatibility guarantees. Applications may determine binary shader compatibility using either (or both) of two mechanisms.
Guaranteed compatibility of shader binaries is expressed through a
combination of the shaderBinaryUUID and shaderBinaryVersion
members of the VkPhysicalDeviceShaderObjectPropertiesEXT structure
queried from a physical device.
Binary shaders retrieved from a physical device with a certain
shaderBinaryUUID are guaranteed to be compatible with all other
physical devices reporting the same shaderBinaryUUID and the same or
higher shaderBinaryVersion.
Whenever a new version of an implementation incorporates any changes that
affect the output of vkGetShaderBinaryDataEXT, the implementation
should either increment shaderBinaryVersion if binary shader code
retrieved from older versions remains compatible with the new
implementation, or else replace shaderBinaryUUID with a new value if
backward compatibility has been broken.
Binary shader code queried from a device with a matching
shaderBinaryUUID and lower shaderBinaryVersion relative to the
device on which vkCreateShadersEXT is being called may be suboptimal
for the new device in ways that do not change shader functionality, but it
is still guaranteed to be usable to successfully create the shader
object(s).
|
Note
|
Implementations are encouraged to share |
In addition to the shader compatibility guarantees described above, it is
valid for an application to call vkCreateShadersEXT with binary shader
code created on a device with a different or unknown shaderBinaryUUID
and/or higher shaderBinaryVersion.
In this case, the implementation may use any unspecified means of its
choosing to determine whether the provided binary shader code is usable.
If it is, vkCreateShadersEXT must return VK_SUCCESS, and the
created shader object is guaranteed to be valid.
Otherwise, in the absence of some error, vkCreateShadersEXT must
return VK_INCOMPATIBLE_SHADER_BINARY_EXT to indicate that the provided
binary shader code is not compatible with the device.
9.1.4. Binding Shader Objects
Once shader objects have been created, they can be bound to the command buffer using the command:
// Provided by VK_EXT_shader_object
void vkCmdBindShadersEXT(
VkCommandBuffer commandBuffer,
uint32_t stageCount,
const VkShaderStageFlagBits* pStages,
const VkShaderEXT* pShaders);
-
commandBufferis the command buffer that the shader object will be bound to. -
stageCountis the length of thepStagesandpShadersarrays. -
pStagesis a pointer to an array of VkShaderStageFlagBits values specifying one stage per array index that is affected by the corresponding value in thepShadersarray. -
pShadersis a pointer to an array ofVkShaderEXThandles and/or VK_NULL_HANDLE values describing the shader binding operations to be performed on each stage inpStages.
When binding linked shaders, an application may bind them in any
combination of one or more calls to vkCmdBindShadersEXT (i.e., shaders
that were created linked together do not need to be bound in the same
vkCmdBindShadersEXT call).
Any shader object bound to a particular stage may be unbound by setting its
value in pShaders to VK_NULL_HANDLE.
If pShaders is NULL, vkCmdBindShadersEXT behaves as if
pShaders was an array of stageCount VK_NULL_HANDLE values
(i.e., any shaders bound to the stages specified in pStages are
unbound).
9.1.5. Setting State
Whenever shader objects are used to issue drawing commands, the appropriate dynamic state setting commands must have been called to set the relevant state in the command buffer prior to drawing:
If a shader is bound to the VK_SHADER_STAGE_VERTEX_BIT stage, the
following commands must have been called in the command buffer prior to
drawing:
If a shader is bound to the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT
stage, the following command must have been called in the command buffer
prior to drawing:
-
vkCmdSetPatchControlPointsEXT, if
primitiveTopologyisVK_PRIMITIVE_TOPOLOGY_PATCH_LIST
If a shader is bound to the
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage, the following
command must have been called in the command buffer prior to drawing:
If rasterizerDiscardEnable is VK_FALSE, the following commands
must have been called in the command buffer prior to drawing:
-
vkCmdSetAlphaToOneEnableEXT, if the alphaToOne feature is enabled
-
vkCmdSetLineWidth, if
polygonModeisVK_POLYGON_MODE_LINE, or if a shader is bound to theVK_SHADER_STAGE_VERTEX_BITstage andprimitiveTopologyis a line topology, or if a shader which outputs line primitives is bound to theVK_SHADER_STAGE_TESSELLATION_EVALUATION_BITorVK_SHADER_STAGE_GEOMETRY_BITstage -
vkCmdSetDepthWriteEnable, if
depthTestEnableisVK_TRUE -
vkCmdSetDepthCompareOp, if
depthTestEnableisVK_TRUE -
vkCmdSetDepthBoundsTestEnable, if the depthBounds feature is enabled
-
vkCmdSetDepthBounds, if
depthBoundsTestEnableisVK_TRUE -
vkCmdSetDepthBias or vkCmdSetDepthBias2EXT, if
depthBiasEnableisVK_TRUE -
vkCmdSetDepthClampEnableEXT, if the depthClamp feature is enabled
-
vkCmdSetStencilOp, if
stencilTestEnableisVK_TRUE -
vkCmdSetStencilCompareMask, if
stencilTestEnableisVK_TRUE -
vkCmdSetStencilWriteMask, if
stencilTestEnableisVK_TRUE -
vkCmdSetStencilReference, if
stencilTestEnableisVK_TRUE
If a shader is bound to the VK_SHADER_STAGE_FRAGMENT_BIT stage, and
rasterizerDiscardEnable is VK_FALSE, the following commands
must have been called in the command buffer prior to drawing:
-
vkCmdSetLogicOpEnableEXT, if the
logicOpfeature is enabled -
vkCmdSetLogicOpEXT, if
logicOpEnableisVK_TRUE -
vkCmdSetColorBlendEnableEXT and vkCmdSetColorWriteMaskEXT, if color attachments are bound, with values set for every color attachment in the render pass instance active at draw time
-
vkCmdSetColorBlendEquationEXT or vkCmdSetColorBlendAdvancedEXT, if color attachments are bound, for every attachment whose index in
pColorBlendEnablesis a pointer to a value ofVK_TRUE -
vkCmdSetBlendConstants, if any index in
pColorBlendEnablesisVK_TRUE, and the same index inpColorBlendEquationsis aVkColorBlendEquationEXTstructure with any VkBlendFactor member with a value ofVK_BLEND_FACTOR_CONSTANT_COLOR,VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR,VK_BLEND_FACTOR_CONSTANT_ALPHA, orVK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA
If the pipelineFragmentShadingRate feature is enabled, and a shader is
bound to the VK_SHADER_STAGE_FRAGMENT_BIT stage, and
rasterizerDiscardEnable is VK_FALSE, the following command must
have been called in the command buffer prior to drawing:
If the geometryStreams feature is
enabled, and a shader is bound to the VK_SHADER_STAGE_GEOMETRY_BIT
stage, the following command must have been called in the command buffer
prior to drawing:
If the VK_EXT_discard_rectangles extension is enabled, and
rasterizerDiscardEnable is VK_FALSE, the following commands
must have been called in the command buffer prior to drawing:
-
vkCmdSetDiscardRectangleModeEXT, if
discardRectangleEnableisVK_TRUE -
vkCmdSetDiscardRectangleEXT, if
discardRectangleEnableisVK_TRUE
If the VK_EXT_conservative_rasterization extension is enabled, and
rasterizerDiscardEnable is VK_FALSE, the following commands
must have been called in the command buffer prior to drawing:
-
vkCmdSetExtraPrimitiveOverestimationSizeEXT, if
conservativeRasterizationModeisVK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT
If the depthClipEnable feature is
enabled, the following command must have been called in the command buffer
prior to drawing:
If the VK_EXT_sample_locations extension is enabled, and
rasterizerDiscardEnable is VK_FALSE, the following commands
must have been called in the command buffer prior to drawing:
-
vkCmdSetSampleLocationsEXT, if
sampleLocationsEnableisVK_TRUE
If the VK_EXT_provoking_vertex extension is enabled, and
rasterizerDiscardEnable is VK_FALSE, and a shader is bound to
the VK_SHADER_STAGE_VERTEX_BIT stage, the following command must have
been called in the command buffer prior to drawing:
If any of the stippledRectangularLines, stippledBresenhamLines, or stippledSmoothLines features are enabled, and
rasterizerDiscardEnable is VK_FALSE, and if polygonMode is
VK_POLYGON_MODE_LINE or a shader is bound to the
VK_SHADER_STAGE_VERTEX_BIT stage and primitiveTopology is a line
topology or a shader which outputs line primitives is bound to the
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT or
VK_SHADER_STAGE_GEOMETRY_BIT stage, the following commands must have
been called in the command buffer prior to drawing:
-
vkCmdSetLineStipple, if
stippledLineEnableisVK_TRUE
If the depthClipControl feature is
enabled, the following command must have been called in the command buffer
prior to drawing:
If the colorWriteEnable feature is
enabled, and a shader is bound to the VK_SHADER_STAGE_FRAGMENT_BIT
stage, and rasterizerDiscardEnable is VK_FALSE, the following
command must have been called in the command buffer prior to drawing:
-
vkCmdSetColorWriteEnableEXT, with values set for every color attachment in the render pass instance active at draw time
If the attachmentFeedbackLoopDynamicState feature is enabled, and a shader is
bound to the VK_SHADER_STAGE_FRAGMENT_BIT stage, and
rasterizerDiscardEnable is VK_FALSE, the following command must
have been called in the command buffer prior to drawing:
If the VK_NV_clip_space_w_scaling extension is enabled, the
following commands must have been called in the command buffer prior to
drawing:
-
vkCmdSetViewportWScalingNV, if
viewportWScalingEnableisVK_TRUE
If the depthClamp and depthClampControl features are enabled, and depthClampEnable
is VK_TRUE, the following command must have been called in the
command buffer prior to drawing:
If the VK_NV_viewport_swizzle extension is enabled, the following
command must have been called in the command buffer prior to drawing:
If the VK_NV_fragment_coverage_to_color extension is enabled, and a
shader is bound to the VK_SHADER_STAGE_FRAGMENT_BIT stage, and
rasterizerDiscardEnable is VK_FALSE, the following commands
must have been called in the command buffer prior to drawing:
-
vkCmdSetCoverageToColorLocationNV, if
coverageToColorEnableisVK_TRUE
If the VK_NV_framebuffer_mixed_samples extension is enabled, and
rasterizerDiscardEnable is VK_FALSE, the following commands
must have been called in the command buffer prior to drawing:
-
vkCmdSetCoverageModulationTableEnableNV, if
coverageModulationModeis notVK_COVERAGE_MODULATION_MODE_NONE_NV -
vkCmdSetCoverageModulationTableNV, if
coverageModulationTableEnableisVK_TRUE
If the coverageReductionMode
feature is enabled, and rasterizerDiscardEnable is VK_FALSE, the
following command must have been called in the command buffer prior to
drawing:
If the representativeFragmentTest feature is enabled, and
rasterizerDiscardEnable is VK_FALSE, the following command must
have been called in the command buffer prior to drawing:
If the shadingRateImage feature is
enabled, and rasterizerDiscardEnable is VK_FALSE, the following
commands must have been called in the command buffer prior to drawing:
-
vkCmdSetViewportShadingRatePaletteNV, if
shadingRateImageEnableisVK_TRUE
If the exclusiveScissor feature is
enabled, the following commands must have been called in the command buffer
prior to drawing:
-
vkCmdSetExclusiveScissorNV, if any value in
pExclusiveScissorEnablesisVK_TRUE
State can be set either at any time before or after shader objects are bound, but all required state must be set prior to issuing drawing commands.
If the commandBufferInheritance
feature is enabled, graphics and compute state is inherited from the
previously executed command buffer in the queue.
Any valid state inherited in this way does not need to be set again in the
current command buffer.
9.1.6. Interaction With Pipelines
Calling vkCmdBindShadersEXT causes the pipeline bind points
corresponding to each stage in pStages to be
disturbed, meaning that any pipelines that had previously
been bound to those pipeline bind points are no longer bound.
If VK_PIPELINE_BIND_POINT_GRAPHICS is disturbed (i.e., if
pStages contains any graphics stage), any graphics pipeline state that
the previously bound pipeline did not specify as dynamic becomes undefined, and must be set in the command buffer before
issuing drawing commands using shader objects.
Calls to vkCmdBindPipeline likewise disturb the shader stage(s)
corresponding to pipelineBindPoint, meaning that any shaders that had
previously been bound to any of those stages are no longer bound, even if
the pipeline was created without shaders for some of those stages.
9.1.7. Shader Object Destruction
To destroy a shader object, call:
// Provided by VK_EXT_shader_object
void vkDestroyShaderEXT(
VkDevice device,
VkShaderEXT shader,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the shader object. -
shaderis the handle of the shader object to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
Destroying a shader object used by one or more command buffers in the recording or executable state causes those command buffers to move into the invalid state.
9.2. Shader Modules
Shader modules contain shader code and one or more entry points. Shaders are selected from a shader module by specifying an entry point as part of pipeline creation. The stages of a pipeline can use shaders that come from different modules. The shader code defining a shader module must be in the SPIR-V format, as described by the Vulkan Environment for SPIR-V appendix.
Shader modules are represented by VkShaderModule handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkShaderModule)
To create a shader module, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateShaderModule(
VkDevice device,
const VkShaderModuleCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkShaderModule* pShaderModule);
-
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.
|
Note
|
If
the |
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 a VkStructureType value identifying 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 structure is defined
as:
// Provided by VK_EXT_validation_cache
typedef struct VkShaderModuleValidationCacheCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkValidationCacheEXT validationCache;
} VkShaderModuleValidationCacheCreateInfoEXT;
-
sTypeis a VkStructureType value identifying 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). The implementation must not access this object outside of the duration of the command this structure is passed to.
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.3. Shader Module Identifiers
Shader modules have unique identifiers associated with them. To query an implementation provided identifier, call:
// Provided by VK_EXT_shader_module_identifier
void vkGetShaderModuleIdentifierEXT(
VkDevice device,
VkShaderModule shaderModule,
VkShaderModuleIdentifierEXT* pIdentifier);
-
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 a VkStructureType value identifying 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.
VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT is the length in bytes of a
shader module identifier, as returned in
VkShaderModuleIdentifierEXT::identifierSize.
#define VK_MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT 32U
9.4. Binding Shaders
Before a shader can be used it must be first bound to the command buffer.
Calling vkCmdBindPipeline binds all stages corresponding to the
VkPipelineBindPoint.
Calling vkCmdBindShadersEXT binds all stages in pStages
The following table describes the relationship between shader stages and pipeline bind points:
| Shader stage | Pipeline bind point | behavior controlled |
|---|---|---|
|
|
all drawing commands |
|
|
|
|
|
vkCmdTraceRaysNV vkCmdTraceRaysKHR and vkCmdTraceRaysIndirectKHR |
|
|
|
|
|
9.5. Shader Execution
At each stage of the pipeline, multiple invocations of a shader may execute simultaneously. Further, invocations of a single shader produced as the result of different commands may execute simultaneously. The relative execution order of invocations of the same shader type is undefined. Shader invocations may complete in a different order than that in which the primitives they originated from were drawn or dispatched by the application. However, fragment shader outputs are written to attachments in rasterization order.
The relative execution order of invocations of different shader types is largely undefined. However, when invoking a shader whose inputs are generated from a previous pipeline stage, the shader invocations from the previous stage are guaranteed to have executed far enough to generate input values for all required inputs.
9.5.1. Shader Termination
A shader invocation that is terminated has finished executing instructions.
Executing OpReturn in the entry point, or executing
OpTerminateInvocation in any function will terminate an invocation.
Implementations may also terminate a shader invocation when OpKill is
executed in any function; otherwise it becomes a
helper invocation.
In addition to the above conditions, helper invocations may be terminated when all non-helper invocations in the same derivative group either terminate or become helper invocations.
A shader stage for a given command completes execution when all invocations for that stage have terminated.
|
Note
|
Depending on the implementation, |
9.6. Shader Out-of-Bounds Memory Access
Shader accesses to memory are not automatically bounds checked by the implementation. Applications must not execute operations that would access out of bounds memory locations unless some form of bounds checking is enabled. An access is considered out of bounds if any part of the access is outside of any specified memory range, whether that is the array length specified in a shader or a range specified in the API (e.g. descriptor size).
|
Note
|
External tooling such as the Vulkan Validation Layers can be used to help validate that accesses are not out of bounds. |
An access can be independently out of bounds for each range that applies; if one is bounds checked and the others are not, behavior is still undefined.
|
Note
|
For example, given the following shader declaration
accessing |
Vulkan provides functionality that enables automatic bounds checking in some cases, as outlined below.
|
Note
|
Automatic bounds checking can be used to ensure that accesses outside of certain bounds have predictable results, acting as a safety net for untrusted code, or simply as a way for applications to avoid their own bounds checks. While there may be a performance cost for enabling these features, they should not be slower than an application performing equivalent checks. Automatic checks do not necessarily account for all possible bounds - e.g. Robust Buffer Access will not prevent undefined behavior in the buffer access example in the prior note. |
9.6.1. Robust Buffer Access
Robust buffer access can be enabled by
specifying VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS
in VkPipelineRobustnessCreateInfo, or specifying
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT and enabling the
the robustBufferAccess feature.
When robust buffer access is enabled, access to a buffer via a descriptor is bounds checked against the range specified for the descriptor, and access to vertex input data is bounds checked against the bound vertex buffer range. Reads from a vertex input may instead be bounds checked against a range rounded down to the nearest multiple of the stride of its binding.
|
Note
|
The range of a descriptor is not necessarily equivalent to the size of the underlying resource; applications may suballocate descriptors from larger buffers, for instance. The APIs specifying the descriptor range vary between resource types and descriptor interfaces, but for example include the ranges specified by VkDescriptorBufferInfo or VkBufferViewCreateInfo. |
If any vertex input read is outside of the checked range, all other vertex input reads through the same binding in the same shader invocation may behave as if they were outside of the checked range.
If any access to a uniform, storage, uniform texel, or storage texel buffer is outside of the checked range, any access of the same type (write, read-modify-write, or read) to the same buffer that is less than 16 bytes away from the first access may behave as if it is also outside of the checked range.
Any non-atomic access to a uniform, storage, uniform texel, or storage texel buffer wider than 32-bits may be treated as multiple 32-bit accesses that are separately bounds checked.
Writes to a storage or storage texel buffer outside of the checked range will either be discarded, or modify values within the memory range(s) bound to the underlying buffer (including outside of the checked range). They will not modify any other memory.
|
Note
|
Non-atomic writes outside of the checked range can lead to data races, as the application has no control over where the data will be written. |
Atomic read-modify-write operations to a storage or storage texel buffer outside of the checked range will behave the same as a write outside of the checked range, but will return an undefined value.
Reading a uniform, storage, uniform texel, or storage texel buffer outside of the checked range will return one of the following values:
-
Values from anywhere within the memory range(s) bound to the underlying buffer object, which may include bytes beyond the size of the buffer itself.
-
Zero values
-
For 4-component vectors, a value of (0,0,0,x), where x is any of
-
0, 1, or the maximum positive integer value for integer components
-
0.0 or 1.0 for floating-point components
-
-
The value of the last store to the same out-of-bounds location in the same shader invocation.
-
Using the
Volatile/VolatileTexelmemory/image operand, theVolatilememory semantic, or theVolatiledecoration to load the value will prevent prior stored values from being returned.
-
|
Note
|
Getting the value of the previous store is possible as implementations are free to optimize multiple accesses in the general case. There are several ways this can be prevented, but using volatile loads is by far the simplest. |
Reads from a vertex input outside of the checked range will produce one of the following values:
-
Values from anywhere within the memory range(s) bound to the underlying buffer object, which may include bytes beyond the size of the buffer itself, converted via input extraction.
-
Zero values, converted via input extraction.
-
Zero values
-
For 4-component vectors, a value of (0,0,0,x), where x is any of
-
0, 1, or the maximum positive integer value for integer components
-
0.0 or 1.0 for floating-point components
-
Accesses via OpCooperativeMatrixLoadNV and
OpCooperativeMatrixStoreNV are only bounds checked in the above manner
if the VkPhysicalDeviceCooperativeMatrixFeaturesNV::cooperativeMatrixRobustBufferAccess
feature is enabled.
Accesses via OpCooperativeMatrixLoadKHR and
OpCooperativeMatrixStoreKHR are only bounds checked in the above manner
if the VkPhysicalDeviceCooperativeMatrixFeaturesKHR::cooperativeMatrixRobustBufferAccess
feature is enabled.
Accesses using OpCooperativeVector* instructions are not
bounds-checked.
9.6.2. Robust Buffer Access 2
Robust buffer access 2 can be enabled by
specifying
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2 in
VkPipelineRobustnessCreateInfo, or specifying
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT and enabling the
the robustBufferAccess2 feature.
When robust buffer access 2 is enabled, access to a buffer via a descriptor is bounds checked against the range specified for the descriptor, and access to vertex input data is bounds checked against the bound vertex buffer range, similarly to Robust Buffer Access, but with tighter bounds on the results.
Accesses to a uniform buffer may instead be bounds checked against a range
rounded up to robustUniformBufferAccessSizeAlignment.
Accesses inside the aligned range may behave as if they are in bounds, even
if they are outside of the unaligned descriptor range, and access memory
accordingly.
The same is true for accesses to a storage buffer, using the
robustStorageBufferAccessSizeAlignment limit instead.
|
Note
|
To avoid unexpected data races between neighboring descriptor ranges, applications may wish to ensure suballocated ranges of buffers are aligned to these limits. |
Any access to a uniform, storage, uniform texel, or storage texel buffer wider than 32-bits may be treated as multiple 32-bit accesses that are separately bounds checked.
|
Note
|
Accesses to null descriptors are not considered out-of-bounds and have
separate behavior controlled by the |
Writes to a storage or storage texel buffer outside of the checked range will not modify any memory.
Atomic read-modify-write operations to a storage or storage texel buffer outside of the checked range will behave the same as a write outside of the checked range, but will return an undefined value.
Reads from a uniform or storage buffer outside of the checked range will
return zero values.
If a value was previously written to the same out of bounds location in the
same shader invocation, that value may be returned instead; using
the Volatile/VolatileTexel memory/image operand, the Volatile
memory semantic, or
the Volatile decoration to load the value will prevent prior stored
values from being returned.
Reading a uniform texel or storage texel buffer outside of the checked range
will produce zero values, but conversion to
RGBA will still be applied based on the buffer view’s format, with the
resulting value returned to the shader.
If a value was previously written to the same out of bounds location in the
same shader invocation, that value may be returned instead; using
the Volatile/VolatileTexel memory/image operand, the Volatile
memory semantic, or
the Volatile decoration to load the value will prevent prior stored
values from being returned.
Reads from a vertex input outside of the checked range will produce zero values, but input extraction will still be applied, filling missing G, B, or A components with (0,0,1).
Accesses via OpCooperativeMatrixLoadNV and
OpCooperativeMatrixStoreNV are only bounds checked in the above manner
if the VkPhysicalDeviceCooperativeMatrixFeaturesNV::cooperativeMatrixRobustBufferAccess
feature is enabled.
Accesses via OpCooperativeMatrixLoadKHR and
OpCooperativeMatrixStoreKHR are only bounds checked in the above manner
if the VkPhysicalDeviceCooperativeMatrixFeaturesKHR::cooperativeMatrixRobustBufferAccess
feature is enabled.
Accesses using OpCooperativeVector* instructions are not
bounds-checked.
9.6.3. Image Sampling
Sampling operations on an image descriptor are always well-defined when coordinates exceeding the dimensions specified for the descriptor are accessed, as described in the Wrapping Operation section.
9.6.4. Robust Image Access
Robust image access can be enabled by
specifying VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS
in VkPipelineRobustnessCreateInfo, or specifying
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT and enabling the
the robustImageAccess feature.
If robust image access is enabled, accesses to image descriptors are bounds checked against the image view dimensions specified for the descriptor.
Writes or atomic read-modify-write operations to a storage image outside of the checked dimensions will not modify any memory.
Reads, atomic read-modify-write operations, or fetches from images outside of the checked dimensions will return zero values, with (0,0,1) or [eq]#(0,0,0) values inserted for missing G, B, or A components based on the format.
If a value was previously written to the same out of bounds location in the
same shader invocation, that value may be returned instead; using
the VolatileTexel image operand, the Volatile memory semantic, or
the Volatile decoration to load the value will prevent prior stored
values from being returned.
9.6.5. Robust Image Access 2
|
Note
|
This is largely identical to Robust Image Access; the only difference being that the alpha channel must be replaced with 1, rather than 1 or 0, for out of bounds texel access. |
Robust image access 2 can be enabled by
specifying VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2
in VkPipelineRobustnessCreateInfo, or specifying
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT and enabling the
the robustImageAccess2 feature.
If robust image access 2 is enabled, accesses to image descriptors are bounds checked against the image view dimensions specified for the descriptor.
Writes or atomic read-modify-write operations to a storage image outside of the checked dimensions will not modify any memory.
Reads, atomic read-modify-write operations, or fetches from images outside of the checked dimensions will return zero values, with (0,0,1) values inserted for missing G, B, or A components based on the format.
If a value was previously written to the same out of bounds location in the
same shader invocation, that value may be returned instead; using
the VolatileTexel image operand, the Volatile memory semantic, or
the Volatile decoration to load the value will prevent prior stored
values from being returned.
9.7. 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.8. 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.9. Task Shaders
Task shaders operate in conjunction with the mesh shaders to produce a collection of primitives that will be processed by subsequent stages of the graphics pipeline. Its primary purpose is to create a variable amount of subsequent mesh shader invocations.
Task shaders are invoked via the execution of the programmable mesh shading pipeline.
The task shader has no fixed-function inputs other than variables
identifying the specific workgroup and invocation.
In the TaskNV Execution Model the number of mesh shader workgroups to
create is specified via a TaskCountNV decorated output variable.
In the TaskEXT Execution Model the number of mesh shader workgroups to
create is specified via the OpEmitMeshTasksEXT instruction.
The task shader can write additional outputs to task memory, which can be read by all of the mesh shader workgroups it created.
9.9.1. Task Shader Execution
Task workloads are formed from groups of work items called workgroups and
processed by the task shader in the current graphics pipeline.
A workgroup is a collection of shader invocations that execute the same
shader, potentially in parallel.
Task shaders execute in global workgroups which are divided into a number
of local workgroups with a size that can be set by assigning a value to
the LocalSize
or LocalSizeId
execution mode or via an object decorated by the WorkgroupSize
decoration.
An invocation within a local workgroup can share data with other members of
the local workgroup through shared variables and issue memory and control
flow barriers to synchronize with other members of the local workgroup.
If the subpass includes multiple views in its view mask, a Task shader using
TaskEXT Execution Model may be invoked separately for each view.
9.10. 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.10.1. Mesh Shader Execution
Mesh workloads are formed from groups of work items called workgroups and
processed by the mesh shader in the current graphics pipeline.
A workgroup is a collection of shader invocations that execute the same
shader, potentially in parallel.
Mesh shaders execute in global workgroups which are divided into a number
of local workgroups with a size that can be set by assigning a value to
the LocalSize
or LocalSizeId
execution mode or via an object decorated by the WorkgroupSize
decoration.
An invocation within a local workgroup can share data with other members of
the local workgroup through shared variables and issue memory and control
flow barriers to synchronize with other members of the local workgroup.
The global workgroups may be generated explicitly via the API, or
implicitly through the task shader’s work creation mechanism.
If the subpass includes multiple views in its view mask, a Mesh shader using
MeshEXT Execution Model may be invoked separately for each view.
9.11. Cluster Culling Shaders
Cluster Culling shaders are invoked via the execution of the Programmable Cluster Culling Shading pipeline.
The only inputs available to the cluster culling shader are variables identifying the specific workgroup and invocation.
Cluster Culling shaders operate in workgroups to perform cluster-based culling and produce zero or more cluster drawing command that will be processed by subsequent stages of the graphics pipeline.
The Cluster Drawing Command(CDC) is very similar to the MDI command, invocations in workgroup can emit zero of more CDC to draw zero or more visible cluster.
9.11.1. Cluster Culling Shader Execution
Cluster Culling workloads are formed from groups of work items called
workgroups and processed by the cluster culling shader in the current
graphics pipeline.
A workgroup is a collection of shader invocations that execute the same
shader, potentially in parallel.
Cluster Culling shaders execute in global workgroups which are divided
into a number of local workgroups with a size that can be set by
assigning a value to the LocalSize
or LocalSizeId
execution mode or via an object decorated by the WorkgroupSize
decoration.
An invocation within a local workgroup can share data with other members of
the local workgroup through shared variables and issue memory and control
flow barriers to synchronize with other members of the local workgroup.
9.12. 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.12.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.13. Tessellation Control Shaders
The tessellation control shader is used to read an input patch provided by
the application and to produce an output patch.
Each tessellation control shader invocation operates on an input patch
(after all control points in the patch are processed by a vertex shader) and
its associated data, and outputs a single control point of the output patch
and its associated data, and can also output additional per-patch data.
The input patch is sized according to the patchControlPoints member of
VkPipelineTessellationStateCreateInfo, as part of input assembly.
The input patch can also be dynamically sized with patchControlPoints
parameter of vkCmdSetPatchControlPointsEXT.
To dynamically set the number of control points per patch, call:
// Provided by VK_EXT_extended_dynamic_state2, VK_EXT_shader_object
void vkCmdSetPatchControlPointsEXT(
VkCommandBuffer commandBuffer,
uint32_t patchControlPoints);
-
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 drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineTessellationStateCreateInfo::patchControlPoints value
used to create the currently active pipeline.
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.13.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.14. 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.15. 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.15.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.16. 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.17. Compute Shaders
Compute shaders are invoked via dispatching 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.18. Ray Generation Shaders
A ray generation shader is similar to a compute shader.
Its main purpose is to execute ray tracing queries using
pipeline trace ray instructions (such as
OpTraceRayKHR) and process the results.
9.18.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.19. 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.19.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.20. 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.20.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.21. Closest Hit Shaders
Closest hit shaders have read-only access to the attributes generated by the corresponding intersection shader, and can read or modify the ray payload. They also have access to a number of system-generated values. Closest hit shaders can call pipeline trace ray instructions to recursively trace rays.
9.22. Miss Shaders
Miss shaders can access the ray payload and can trace new rays through the pipeline trace ray instructions, but cannot access attributes since they are not associated with an intersection.
9.23. Callable Shaders
Callable shaders can access a callable payload that works similarly to ray payloads to do subroutine work.
9.24. Interpolation Decorations
Variables in the Input storage class in a fragment shader’s interface
are interpolated from the values specified by the primitive being
rasterized.
|
Note
|
Interpolation decorations can be present on input and output variables in pre-rasterization shaders but have no effect on the interpolation performed. |
An undecorated input variable will be interpolated with perspective-correct
interpolation according to the primitive type being rasterized.
Lines and
polygons are interpolated in the same
way as the primitive’s clip coordinates.
If the NoPerspective decoration is present, linear interpolation is
instead used for lines and
polygons.
For points, as there is only a single vertex, input values are never
interpolated and instead take the value written for the single vertex.
If the Flat decoration is present on an input variable, the value is
not interpolated, and instead takes its value directly from the
provoking vertex.
Fragment shader inputs that are signed or unsigned integers, integer
vectors, or any double-precision floating-point type must be decorated with
Flat.
Interpolation of input variables is performed at an implementation-defined position within the fragment area being shaded. The position is further constrained as follows:
-
If the
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.25. Static Use
A SPIR-V module declares a global object in memory using the OpVariable
instruction, which results in a pointer x to that object.
A specific entry point in a SPIR-V module is said to statically use that
object if that entry point’s call tree contains a function containing a
instruction with x as an id operand.
A shader entry point also statically uses any variables explicitly
declared in its interface.
9.26. 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.26.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.26.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.26.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.26.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.26.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.26.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.26.7. Workgroup
A local workgroup is a set of invocations that can synchronize and share
data with each other using memory in the Workgroup storage class.
The Workgroup Scope can be used as both an Execution
Scope and Memory Scope for barrier and atomic operations.
Each invocation in a local workgroup must be in the same command scope instance.
Only task, mesh, and compute shaders have defined workgroups - other shader types cannot use workgroup functionality. For shaders that have defined workgroups, this set of invocations forms an invocation group as defined in the SPIR-V specification.
When variables declared with the Workgroup storage class are explicitly
laid out (hence they are also decorated with Block), the amount of
storage consumed is the size of the largest Block variable, not counting any
padding at the end.
The amount of storage consumed by the
non-Block
variables declared with the Workgroup storage class is
implementation-dependent.
However, the amount of storage consumed may not exceed the largest block
size that would be obtained if all active
non-Block
variables declared with Workgroup storage class were assigned offsets
in an arbitrary order by successively taking the smallest valid offset
according to the Standard Storage
Buffer Layout rules, and with Boolean values considered as 32-bit
integer values for the purpose of this calculation.
(This is equivalent to using the GLSL std430 layout rules.)
9.26.8. Subgroup
A subgroup (see the subsection “Control Flow” of section 2 of the SPIR-V 1.3 Revision 1 specification) is a set of invocations that can synchronize and share data with each other efficiently.
The Subgroup Scope can be used as both an Execution
Scope and Memory Scope for barrier and atomic operations.
Other subgroup features allow the use of
group operations with subgroup scope.
If the shaderSubgroupClock feature
is enabled, using the Subgroup Scope with the OpReadClockKHR
instruction will read from a clock that is consistent across invocations in
the same subgroup.
For shaders that have defined workgroups, each invocation in a subgroup must be in the same local workgroup.
In other shader stages, each invocation in a subgroup must be in the same device scope instance.
Only shader stages that support subgroup operations have defined subgroups.
|
Note
|
Subgroups are not guaranteed to be a subset of a single command in shaders that do not have defined workgroups. Values that are guaranteed to be uniform for a given command or sub command may then not be uniform for the subgroup, and vice versa. As such, applications must take care when dealing with mixed uniformity. A somewhat common example of this would something like trying to optimize access to per-draw data using subgroup operations:
This can be done in an attempt to optimize the shader to only perform the loads once per subgroup. However, if the implementation packs multiple draws into a single subgroup, invocations from draws with a different drawID are now receiving data from the wrong invocation. Applications should rely on implementations to do this kind of optimization automatically where the implementation can, rather than trying to force it. |
9.26.9. Quad
A quad scope instance is formed of four shader invocations.
In a fragment shader, each invocation in a quad scope instance is formed of invocations in neighboring framebuffer locations (xi, yi), where:
-
i is the index of the invocation within the scope instance.
-
w and h are the number of pixels the fragment covers in the x and y axes.
-
w and h are identical for all participating invocations.
-
(x0) = (x1 - w) = (x2) = (x3 - w)
-
(y0) = (y1) = (y2 - h) = (y3 - h)
-
Each invocation has the same layer and sample indices.
In a
mesh, task, or
compute shader, if the DerivativeGroupQuadsKHR execution mode is
specified, each invocation in a quad scope instance is formed of invocations
with adjacent local invocation IDs (xi, yi), where:
-
i is the index of the invocation within the quad scope instance.
-
(x0) = (x1 - 1) = (x2) = (x3 - 1)
-
(y0) = (y1) = (y2 - 1) = (y3 - 1)
-
x0 and y0 are integer multiples of 2.
-
Each invocation has the same z coordinate.
In a
mesh, task, or
compute shader, if the DerivativeGroupLinearKHR execution mode is
specified, each invocation in a quad scope instance is formed of invocations
with adjacent local invocation indices (li), where:
-
i is the index of the invocation within the quad scope instance.
-
(l0) = (l1 - 1) = (l2 - 2) = (l3 - 3)
-
l0 is an integer multiple of 4.
In all shaders, each invocation in a quad scope instance is formed of invocations in adjacent subgroup invocation indices (si), where:
-
i is the index of the invocation within the quad scope instance.
-
(s0) = (s1 - 1) = (s2 - 2) = (s3 - 3)
-
s0 is an integer multiple of 4.
Each invocation in a quad scope instance must be in the same subgroup.
In a fragment shader, each invocation in a quad scope instance must be in the same primitive scope instance.
Fragment
, mesh, task,
and compute
shaders have defined quad scope instances.
If the quadOperationsInAllStages limit is supported, any
shader stages that support subgroup
operations also have defined quad scope instances.
9.26.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 neighboring framebuffer locations are also included. The shading rate image or fragment shading rate determines these fragments.
Only fragment shaders with one of the above execution modes have defined fragment interlock scope instances.
There is no specific Scope value for communication across invocations
in a fragment interlock scope instance.
However, this is implicitly used as a memory scope by
OpBeginInvocationInterlockEXT and OpEndInvocationInterlockEXT.
Each invocation in a fragment interlock scope instance must be in the same queue family scope instance.
9.26.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.27. 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.27.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.27.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.27.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.27.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.27.5. Shuffle Group Operations
The shuffle group operations allow invocations to read values from other invocations within a group.
9.27.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.27.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.27.8. Rotate Group Operations
The rotate group operations allow invocations to read values from other invocations within the group relative to the current invocation and modulo the size of the group. Clustered rotate group operations perform the same operation within individual partitions of a group.
The partitions for clustered rotate group operations are consecutive power-of-two size groups of invocations and the cluster size must be known at pipeline creation time.
9.28. Quad Group Operations
Quad group operations (OpGroupNonUniformQuad*) are a specialized type
of group operations that only operate on
quad scope instances.
Whilst these instructions do include a Scope parameter, this scope is
always overridden; only the quad scope instance is
included in its execution scope.
Fragment shaders that statically execute either
OpGroupNonUniformQuadBroadcast or OpGroupNonUniformQuadSwap must
launch sufficient invocations to ensure their correct operation; additional
helper invocations are launched for
framebuffer locations not covered by rasterized fragments if necessary.
The index used to select participating invocations is i, as described for a quad scope instance, defined as the quad index in the SPIR-V specification.
For OpGroupNonUniformQuadBroadcast this value is equal to Index.
For OpGroupNonUniformQuadSwap, it is equal to the implicit Index
used by each participating invocation.
9.29. Derivative Operations
Derivative operations calculate the partial derivative for an expression P as a function of an invocation’s x and y coordinates.
Derivative operations operate on a set of invocations known as a derivative group as defined in the SPIR-V specification.
A derivative group in a fragment shader is equivalent to the
quad scope instance if the QuadDerivativesKHR
execution mode is specified, otherwise it is equivalent to the
primitive scope instance.
A derivative group in a
mesh, task, or
compute shader is equivalent to the quad scope
instance.
Derivatives are calculated assuming that P is piecewise linear and continuous within the derivative group.
The following control-flow restrictions apply to derivative operations:
-
If the
QuadDerivativesKHRexecution mode is specified, dynamic instances of any derivative operations must be executed in control flow that is uniform within the current quad scope instance. -
If the
QuadDerivativesKHRexecution mode is not specified:-
dynamic instances of explicit derivative instructions (
OpDPdx*,OpDPdy*, andOpFwidth*) must be executed in control flow that is uniform within a derivative group. -
dynamic instances of implicit derivative operations can be executed in control flow that is not uniform within the derivative group, but results are undefined.
-
Fragment shaders that statically execute derivative operations must launch sufficient invocations to ensure their correct operation; additional helper invocations are launched for framebuffer locations not covered by rasterized fragments if necessary.
|
Note
|
In a mesh, task, or compute shader, it is the application’s responsibility to ensure that sufficient invocations are launched. |
Derivative operations calculate their results as the difference between the
result of P across invocations in the quad.
For fine derivative operations (OpDPdxFine and OpDPdyFine), the
values of DPdx(Pi) are calculated as
-
DPdx(P0) = DPdx(P1) = P1 - P0
-
DPdx(P2) = DPdx(P3) = P3 - P2
and the values of DPdy(Pi) are calculated as
-
DPdy(P0) = DPdy(P2) = P2 - P0
-
DPdy(P1) = DPdy(P3) = P3 - P1
where i is the index of each invocation as described in Quad.
Coarse derivative operations (OpDPdxCoarse and OpDPdyCoarse),
calculate their results in roughly the same manner, but may only calculate
two values instead of four (one for each of DPdx and DPdy),
reusing the same result no matter the originating invocation.
If an implementation does this, it should use the fine derivative
calculations described for P0.
|
Note
|
Derivative values are calculated between fragments rather than pixels. If the fragment shader invocations involved in the calculation cover multiple pixels, these operations cover a wider area, resulting in larger derivative values. This in turn will result in a coarser LOD being selected for image sampling operations using derivatives. Applications may want to account for this when using multi-pixel fragments; if pixel derivatives are desired, applications should use explicit derivative operations and divide the results by the size of the fragment in each dimension as follows:
where w and h are the size of the fragments in the quad, and DPdx(Pn)' and DPdy(Pn)' are the pixel derivatives. |
The results for OpDPdx and OpDPdy may be calculated as either
fine or coarse derivatives, with implementations favoring the most efficient
approach.
Implementations must choose coarse or fine consistently between the two.
Executing OpFwidthFine, OpFwidthCoarse, or OpFwidth is
equivalent to executing the corresponding OpDPdx* and OpDPdy*
instructions, taking the absolute value of the results, and summing them.
Executing an OpImage*Sample*ImplicitLod instruction is equivalent to
executing OpDPdx(Coordinate) and OpDPdy(Coordinate), and
passing the results as the Grad operands dx and dy.
|
Note
|
It is expected that using the |
9.30. Helper Invocations
When performing derivative
or quad group
operations in a fragment shader, additional invocations may be spawned in
order to ensure correct results.
These additional invocations are known as helper invocations and can be
identified by a non-zero value in the HelperInvocation built-in.
Stores and atomics performed by helper invocations must not have any effect
on memory except for the Function, Private and Output storage
classes, and values returned by atomic instructions in helper invocations
are undefined.
|
Note
|
While storage to |
If the MaximallyReconvergesKHR execution mode is applied to the entry
point, helper invocations must remain active for all instructions for the
lifetime of the quad scope instance they are a part of.
If the MaximallyReconvergesKHR execution mode is not applied to the
entry point, helper
invocations may be considered inactive for group operations other than derivative
and quad group operations.
All invocations in a quad scope instance may become permanently inactive at
any point once the only remaining invocations in that quad scope instance
are helper invocations.
9.31. Cooperative Matrices
A cooperative matrix type is a SPIR-V type where the storage for and computations performed on the matrix are spread across the invocations in a scope instance. These types give the implementation freedom in how to optimize matrix multiplies.
SPIR-V defines the types and instructions, but does not specify rules about what sizes/combinations are valid, and it is expected that different implementations may support different sizes.
To enumerate the supported cooperative matrix types and operations, call:
// Provided by VK_KHR_cooperative_matrix
VkResult vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkCooperativeMatrixPropertiesKHR* pProperties);
-
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 VkCooperativeMatrixPropertiesKHR structures.
If pProperties is NULL, then the number of cooperative matrix
properties available is returned in pPropertyCount.
Otherwise, pPropertyCount must point to a variable set by the
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If pPropertyCount is less than the number of cooperative matrix
properties available, at most pPropertyCount structures will be
written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available cooperative matrix
properties were returned.
To enumerate additional supported cooperative matrix types and operations, call:
// Provided by VK_NV_cooperative_matrix2
VkResult vkGetPhysicalDeviceCooperativeMatrixFlexibleDimensionsPropertiesNV(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkCooperativeMatrixFlexibleDimensionsPropertiesNV* 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 VkCooperativeMatrixFlexibleDimensionsPropertiesNV structures.
If pProperties is NULL, then the number of flexible dimensions
properties available is returned in pPropertyCount.
Otherwise, pPropertyCount must point to a variable set by the
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If pPropertyCount is less than the number flexible dimensions
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 flexible dimensions
properties were returned.
If the
cooperativeMatrixFlexibleDimensions
feature is not supported, the implementation must advertise zero
properties.
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
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If pPropertyCount is less than the number of cooperative matrix
properties available, at most pPropertyCount structures will be
written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available cooperative matrix
properties were returned.
Each
VkCooperativeMatrixPropertiesKHR
or
VkCooperativeMatrixPropertiesNV
structure describes a single supported combination of types for a matrix
multiply/add operation (
OpCooperativeMatrixMulAddKHR
or
OpCooperativeMatrixMulAddNV
).
The multiply can be described in terms of the following variables and types
(in SPIR-V pseudocode):
%A is of type OpTypeCooperativeMatrixKHR %AType %scope %MSize %KSize %MatrixAKHR
%B is of type OpTypeCooperativeMatrixKHR %BType %scope %KSize %NSize %MatrixBKHR
%C is of type OpTypeCooperativeMatrixKHR %CType %scope %MSize %NSize %MatrixAccumulatorKHR
%Result is of type OpTypeCooperativeMatrixKHR %ResultType %scope %MSize %NSize %MatrixAccumulatorKHR
%Result = %A * %B + %C // using OpCooperativeMatrixMulAddKHR
%A is of type OpTypeCooperativeMatrixNV %AType %scope %MSize %KSize
%B is of type OpTypeCooperativeMatrixNV %BType %scope %KSize %NSize
%C is of type OpTypeCooperativeMatrixNV %CType %scope %MSize %NSize
%D is of type OpTypeCooperativeMatrixNV %DType %scope %MSize %NSize
%D = %A * %B + %C // using OpCooperativeMatrixMulAddNV
A matrix multiply with these dimensions is known as an MxNxK matrix multiply.
The VkCooperativeMatrixPropertiesKHR structure is defined as:
// Provided by VK_KHR_cooperative_matrix
typedef struct VkCooperativeMatrixPropertiesKHR {
VkStructureType sType;
void* pNext;
uint32_t MSize;
uint32_t NSize;
uint32_t KSize;
VkComponentTypeKHR AType;
VkComponentTypeKHR BType;
VkComponentTypeKHR CType;
VkComponentTypeKHR ResultType;
VkBool32 saturatingAccumulation;
VkScopeKHR scope;
} VkCooperativeMatrixPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
MSizeis the number of rows in matricesA,C, andResult. -
KSizeis the number of columns in matrixAand rows in matrixB. -
NSizeis the number of columns in matricesB,C,Result. -
ATypeis the component type of matrixA, of type VkComponentTypeKHR. -
BTypeis the component type of matrixB, of type VkComponentTypeKHR. -
CTypeis the component type of matrixC, of type VkComponentTypeKHR. -
ResultTypeis the component type of matrixResult, of type VkComponentTypeKHR. -
saturatingAccumulationindicates whether theSaturatingAccumulationoperand toOpCooperativeMatrixMulAddKHRmust be present or not. If it isVK_TRUE, theSaturatingAccumulationoperand must be present. If it isVK_FALSE, theSaturatingAccumulationoperand must not be present. -
scopeis the scope of all the matrix types, of type VkScopeKHR.
If some types are preferred over other types (e.g. for performance), they should appear earlier in the list enumerated by vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR.
At least one entry in the list must have power of two values for all of
MSize, KSize, and NSize.
If the
cooperativeMatrixWorkgroupScope
feature is not supported,
scope must be VK_SCOPE_SUBGROUP_KHR.
The VkCooperativeMatrixFlexibleDimensionsPropertiesNV structure is
defined as:
// Provided by VK_NV_cooperative_matrix2
typedef struct VkCooperativeMatrixFlexibleDimensionsPropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t MGranularity;
uint32_t NGranularity;
uint32_t KGranularity;
VkComponentTypeKHR AType;
VkComponentTypeKHR BType;
VkComponentTypeKHR CType;
VkComponentTypeKHR ResultType;
VkBool32 saturatingAccumulation;
VkScopeKHR scope;
uint32_t workgroupInvocations;
} VkCooperativeMatrixFlexibleDimensionsPropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
MGranularityis the granularity of the number of rows in matricesA,C, andResult. The rows must be an integer multiple of this value. -
KGranularityis the granularity of columns in matrixAand rows in matrixB. The columns/rows must be an integer multiple of this value. -
NGranularityis the granularity of columns in matricesB,C,Result. The columns must be an integer multiple of this value. -
ATypeis the component type of matrixA, of type VkComponentTypeKHR. -
BTypeis the component type of matrixB, of type VkComponentTypeKHR. -
CTypeis the component type of matrixC, of type VkComponentTypeKHR. -
ResultTypeis the component type of matrixResult, of type VkComponentTypeKHR. -
saturatingAccumulationindicates whether theSaturatingAccumulationoperand toOpCooperativeMatrixMulAddKHRmust be present or not. If it isVK_TRUE, theSaturatingAccumulationoperand must be present. If it isVK_FALSE, theSaturatingAccumulationoperand must not be present. -
scopeis the scope of all the matrix types, of type VkScopeKHR. -
workgroupInvocationsis the number of invocations in the local workgroup when this combination of values is supported.
Rather than explicitly enumerating a list of supported sizes,
VkCooperativeMatrixFlexibleDimensionsPropertiesNV advertises size
granularities, where the matrix must be a multiple of the advertised size.
The M and K granularities apply to rows and columns of matrices with
Use of MatrixA, K, and N apply to rows and columns of matrices
with Use of MatrixB, M, and N apply to rows and columns of
matrices with Use of MatrixAccumulator.
For a given type combination, if multiple workgroup sizes are supported
there may be multiple
VkCooperativeMatrixFlexibleDimensionsPropertiesNV structures with
different granularities.
All granularity values must be powers of two.
|
Note
|
Different A/B types may require different granularities but share the same accumulator type. In such a case, the supported granularity for a matrix with the accumulator type would be the smallest advertised granularity. |
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 a VkStructureType value identifying 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 VkScopeKHR include:
// Provided by VK_KHR_cooperative_matrix
typedef enum VkScopeKHR {
VK_SCOPE_DEVICE_KHR = 1,
VK_SCOPE_WORKGROUP_KHR = 2,
VK_SCOPE_SUBGROUP_KHR = 3,
VK_SCOPE_QUEUE_FAMILY_KHR = 5,
// Provided by VK_NV_cooperative_matrix
VK_SCOPE_DEVICE_NV = VK_SCOPE_DEVICE_KHR,
// Provided by VK_NV_cooperative_matrix
VK_SCOPE_WORKGROUP_NV = VK_SCOPE_WORKGROUP_KHR,
// Provided by VK_NV_cooperative_matrix
VK_SCOPE_SUBGROUP_NV = VK_SCOPE_SUBGROUP_KHR,
// Provided by VK_NV_cooperative_matrix
VK_SCOPE_QUEUE_FAMILY_NV = VK_SCOPE_QUEUE_FAMILY_KHR,
} VkScopeKHR;
or the equivalent
// Provided by VK_NV_cooperative_matrix
typedef VkScopeKHR VkScopeNV;
-
VK_SCOPE_DEVICE_KHRcorresponds to SPIR-VDevicescope. -
VK_SCOPE_WORKGROUP_KHRcorresponds to SPIR-VWorkgroupscope. -
VK_SCOPE_SUBGROUP_KHRcorresponds to SPIR-VSubgroupscope. -
VK_SCOPE_QUEUE_FAMILY_KHRcorresponds to SPIR-VQueueFamilyscope.
All enum values match the corresponding SPIR-V value.
Possible values for VkComponentTypeKHR include:
// Provided by VK_KHR_cooperative_matrix, VK_NV_cooperative_vector
typedef enum VkComponentTypeKHR {
VK_COMPONENT_TYPE_FLOAT16_KHR = 0,
VK_COMPONENT_TYPE_FLOAT32_KHR = 1,
VK_COMPONENT_TYPE_FLOAT64_KHR = 2,
VK_COMPONENT_TYPE_SINT8_KHR = 3,
VK_COMPONENT_TYPE_SINT16_KHR = 4,
VK_COMPONENT_TYPE_SINT32_KHR = 5,
VK_COMPONENT_TYPE_SINT64_KHR = 6,
VK_COMPONENT_TYPE_UINT8_KHR = 7,
VK_COMPONENT_TYPE_UINT16_KHR = 8,
VK_COMPONENT_TYPE_UINT32_KHR = 9,
VK_COMPONENT_TYPE_UINT64_KHR = 10,
// Provided by VK_KHR_cooperative_matrix with VK_KHR_shader_bfloat16
VK_COMPONENT_TYPE_BFLOAT16_KHR = 1000141000,
// Provided by VK_NV_cooperative_vector
VK_COMPONENT_TYPE_SINT8_PACKED_NV = 1000491000,
// Provided by VK_NV_cooperative_vector
VK_COMPONENT_TYPE_UINT8_PACKED_NV = 1000491001,
// Provided by VK_KHR_cooperative_matrix with VK_EXT_shader_float8
VK_COMPONENT_TYPE_FLOAT8_E4M3_EXT = 1000491002,
// Provided by VK_KHR_cooperative_matrix with VK_EXT_shader_float8
VK_COMPONENT_TYPE_FLOAT8_E5M2_EXT = 1000491003,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_FLOAT16_NV = VK_COMPONENT_TYPE_FLOAT16_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_FLOAT32_NV = VK_COMPONENT_TYPE_FLOAT32_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_FLOAT64_NV = VK_COMPONENT_TYPE_FLOAT64_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_SINT8_NV = VK_COMPONENT_TYPE_SINT8_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_SINT16_NV = VK_COMPONENT_TYPE_SINT16_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_SINT32_NV = VK_COMPONENT_TYPE_SINT32_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_SINT64_NV = VK_COMPONENT_TYPE_SINT64_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_UINT8_NV = VK_COMPONENT_TYPE_UINT8_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_UINT16_NV = VK_COMPONENT_TYPE_UINT16_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_UINT32_NV = VK_COMPONENT_TYPE_UINT32_KHR,
// Provided by VK_NV_cooperative_matrix
VK_COMPONENT_TYPE_UINT64_NV = VK_COMPONENT_TYPE_UINT64_KHR,
// Provided by VK_NV_cooperative_vector
VK_COMPONENT_TYPE_FLOAT_E4M3_NV = VK_COMPONENT_TYPE_FLOAT8_E4M3_EXT,
// Provided by VK_NV_cooperative_vector
VK_COMPONENT_TYPE_FLOAT_E5M2_NV = VK_COMPONENT_TYPE_FLOAT8_E5M2_EXT,
} VkComponentTypeKHR;
or the equivalent
// Provided by VK_NV_cooperative_matrix
typedef VkComponentTypeKHR VkComponentTypeNV;
-
VK_COMPONENT_TYPE_FLOAT16_KHRcorresponds to SPIR-VOpTypeFloat16. -
VK_COMPONENT_TYPE_FLOAT32_KHRcorresponds to SPIR-VOpTypeFloat32. -
VK_COMPONENT_TYPE_FLOAT64_KHRcorresponds to SPIR-VOpTypeFloat64. -
VK_COMPONENT_TYPE_SINT8_KHRcorresponds to SPIR-VOpTypeInt8 0/1. -
VK_COMPONENT_TYPE_SINT16_KHRcorresponds to SPIR-VOpTypeInt16 0/1. -
VK_COMPONENT_TYPE_SINT32_KHRcorresponds to SPIR-VOpTypeInt32 0/1. -
VK_COMPONENT_TYPE_SINT64_KHRcorresponds to SPIR-VOpTypeInt64 0/1. -
VK_COMPONENT_TYPE_UINT8_KHRcorresponds to SPIR-VOpTypeInt8 0/1. -
VK_COMPONENT_TYPE_UINT16_KHRcorresponds to SPIR-VOpTypeInt16 0/1. -
VK_COMPONENT_TYPE_UINT32_KHRcorresponds to SPIR-VOpTypeInt32 0/1. -
VK_COMPONENT_TYPE_UINT64_KHRcorresponds to SPIR-VOpTypeInt64 0/1. -
VK_COMPONENT_TYPE_BFLOAT16_KHRcorresponds to SPIR-VOpTypeFloat16 BFloat16KHR. -
VK_COMPONENT_TYPE_SINT8_PACKED_NVcorresponds to four 8-bit signed integers packed in a 32-bit unsigned integer. -
VK_COMPONENT_TYPE_UINT8_PACKED_NVcorresponds to four 8-bit unsigned integers packed in a 32-bit unsigned integer. -
VK_COMPONENT_TYPE_FLOAT_E4M3_NVcorresponds to a floating-point type with a sign bit in the most significant bit, followed by four exponent bits, followed by three mantissa bits. -
VK_COMPONENT_TYPE_FLOAT_E5M2_NVcorresponds to a floating-point type with a sign bit in the most significant bit, followed by five exponent bits, followed by two mantissa bits. -
VK_COMPONENT_TYPE_FLOAT8_E4M3_EXTcorresponds to SPIR-VOpTypeFloat8 Float8E4M3EXT. -
VK_COMPONENT_TYPE_FLOAT8_E5M2_EXTcorresponds to SPIR-VOpTypeFloat8 Float8E5M2EXT.
9.32. Cooperative Vectors
A cooperative vector type is a SPIR-V vector type optimized for the evaluation of small neural networks.
SPIR-V defines the types and instructions, but does not specify rules about what combinations of types are valid, and it is expected that different implementations may support different combinations.
To enumerate the supported cooperative vector type combinations, call:
// Provided by VK_NV_cooperative_vector
VkResult vkGetPhysicalDeviceCooperativeVectorPropertiesNV(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkCooperativeVectorPropertiesNV* pProperties);
-
physicalDeviceis the physical device. -
pPropertyCountis a pointer to an integer related to the number of cooperative vector properties available or queried. -
pPropertiesis eitherNULLor a pointer to an array of VkCooperativeVectorPropertiesNV structures.
If pProperties is NULL, then the number of cooperative vector
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 vector
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 vector
properties were returned.
Each VkCooperativeVectorPropertiesNV structure describes a single
supported combination of types for a matrix-vector multiply (or
multiply-add) operation (OpCooperativeVectorMatrixMulNV or
OpCooperativeVectorMatrixMulAddNV).
The VkCooperativeVectorPropertiesNV structure is defined as:
// Provided by VK_NV_cooperative_vector
typedef struct VkCooperativeVectorPropertiesNV {
VkStructureType sType;
void* pNext;
VkComponentTypeKHR inputType;
VkComponentTypeKHR inputInterpretation;
VkComponentTypeKHR matrixInterpretation;
VkComponentTypeKHR biasInterpretation;
VkComponentTypeKHR resultType;
VkBool32 transpose;
} VkCooperativeVectorPropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
inputTypeis the component type of vectorInput, of type VkComponentTypeKHR. -
inputInterpretationis the value ofInputInterpretation, of type VkComponentTypeKHR. -
matrixInterpretationis the value ofMatrixInterpretation, of type VkComponentTypeKHR. -
biasInterpretationis the value ofBiasInterpretation, of type VkComponentTypeKHR. -
resultTypeis the component type ofResultType, of type VkComponentTypeKHR. -
transposeis a boolean indicating whether opaque layout matrices with this combination of input and output types supports transposition.
VK_COMPONENT_TYPE_SINT8_PACKED_NV and
VK_COMPONENT_TYPE_UINT8_PACKED_NV must not be used for members other
than inputInterpretation.
The following combinations must be supported (each row is a required combination):
| inputType | inputInterpretation | matrixInterpretation | biasInterpretation | resultType |
|---|---|---|---|---|
FLOAT16 |
FLOAT16 |
FLOAT16 |
FLOAT16 |
FLOAT16 |
UINT32 |
SINT8_PACKED |
SINT8 |
SINT32 |
SINT32 |
SINT8 |
SINT8 |
SINT8 |
SINT32 |
SINT32 |
FLOAT32 |
SINT8 |
SINT8 |
SINT32 |
SINT32 |
FLOAT16 |
FLOAT_E4M3 |
FLOAT_E4M3 |
FLOAT16 |
FLOAT16 |
FLOAT16 |
FLOAT_E5M2 |
FLOAT_E5M2 |
FLOAT16 |
FLOAT16 |
To query the size of a cooperative vector matrix, or to convert a matrix to another layout and type, call:
// Provided by VK_NV_cooperative_vector
VkResult vkConvertCooperativeVectorMatrixNV(
VkDevice device,
const VkConvertCooperativeVectorMatrixInfoNV* pInfo);
-
deviceis the device. -
pInfois a pointer to a VkConvertCooperativeVectorMatrixInfoNV structure containing information about the layout conversion.
If pInfo->dstData is NULL, then the number of bytes required to
store the converted matrix is returned in pDstSize.
Otherwise, pInfo->pDstSize must point to a variable set by the user
to the number of bytes in pInfo->dstData, and on return the variable
is overwritten with the number of bytes actually written to
pInfo->dstData.
pInfo->srcData can be NULL when pInfo->dstData is NULL.
If pInfo->pDstSize is less than the number of bytes required to store
the converted matrix, no bytes will be written, and VK_INCOMPLETE will
be returned instead of VK_SUCCESS, to indicate that not enough space
was provided.
Each VkConvertCooperativeVectorMatrixInfoNV structure describes a
request to convert the layout and type of a cooperative vector matrix.
The VkConvertCooperativeVectorMatrixInfoNV structure is defined as:
// Provided by VK_NV_cooperative_vector
typedef struct VkConvertCooperativeVectorMatrixInfoNV {
VkStructureType sType;
const void* pNext;
size_t srcSize;
VkDeviceOrHostAddressConstKHR srcData;
size_t* pDstSize;
VkDeviceOrHostAddressKHR dstData;
VkComponentTypeKHR srcComponentType;
VkComponentTypeKHR dstComponentType;
uint32_t numRows;
uint32_t numColumns;
VkCooperativeVectorMatrixLayoutNV srcLayout;
size_t srcStride;
VkCooperativeVectorMatrixLayoutNV dstLayout;
size_t dstStride;
} VkConvertCooperativeVectorMatrixInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcSizeis the length in bytes ofsrcData. -
srcDatais eitherNULLor a pointer to the source data in the source layout. -
pDstSizeis a pointer to an integer related to the number of bytes required or requested to convert. -
dstDatais eitherNULLor a pointer to the destination data in the destination layout. -
srcComponentTypeis the type of a source matrix element. -
dstComponentTypeis the type of a destination matrix element. -
numRowsis the number of rows in the matrix. -
numColumnsis the number of columns in the matrix. -
srcLayoutis the layout of the source matrix. -
srcStrideis the number of bytes between a consecutive row or column (depending onsrcLayout) of the source matrix, if it is row-major or column-major. -
dstLayoutis the layout the matrix is converted to. -
dstStrideis the number of bytes between a consecutive row or column (depending ondstLayout) of destination matrix, if it is row-major or column-major.
When called from vkCmdConvertCooperativeVectorMatrixNV, the
deviceAddress members of srcData and dstData are used.
When called from vkConvertCooperativeVectorMatrixNV, the
hostAddress members of srcData and dstData are used.
For each of the source and destination matrix, if the layout is not either
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_ROW_MAJOR_NV or
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_COLUMN_MAJOR_NV, then the
corresponding stride parameter is ignored.
The size of the destination is only a function of the destination layout information, and does not depend on the source layout information.
Conversion can be used to convert between
VK_COMPONENT_TYPE_FLOAT32_KHR or VK_COMPONENT_TYPE_FLOAT16_KHR
and any supported lower-precision floating-point type.
In this case, the conversion uses round-to-nearest-even rounding.
Possible values for VkCooperativeVectorMatrixLayoutNV include:
// Provided by VK_NV_cooperative_vector
typedef enum VkCooperativeVectorMatrixLayoutNV {
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_ROW_MAJOR_NV = 0,
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_COLUMN_MAJOR_NV = 1,
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_INFERENCING_OPTIMAL_NV = 2,
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_TRAINING_OPTIMAL_NV = 3,
} VkCooperativeVectorMatrixLayoutNV;
-
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_ROW_MAJOR_NVcorresponds to SPIR-VRowMajorNVlayout. -
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_COLUMN_MAJOR_NVcorresponds to SPIR-VColumnMajorNVlayout. -
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_INFERENCING_OPTIMAL_NVcorresponds to SPIR-VInferencingOptimalNVlayout. -
VK_COOPERATIVE_VECTOR_MATRIX_LAYOUT_TRAINING_OPTIMAL_NVcorresponds to SPIR-VTrainingOptimalNVlayout.
All enum values match the corresponding SPIR-V value.
Row-major layout has elements of each row stored consecutively in memory,
with a controllable stride from the start of one row to the start of the
next row.
Column-major layout has elements of each column stored consecutively in
memory, with a controllable stride from the start of one column to the start
of the next column.
Inferencing-optimal and Training-optimal layouts are
implementation-dependent, and the application can convert a matrix to those
layouts using vkConvertCooperativeVectorMatrixNV or
vkCmdConvertCooperativeVectorMatrixNV.
Training-optimal layout with VK_COMPONENT_TYPE_FLOAT16_KHR or
VK_COMPONENT_TYPE_FLOAT32_KHR type has the additional guarantee that
the application can reinterpret the data as an array of elements and
perform element-wise operations on the data, and finite values in any
padding elements do not affect the result of a matrix-vector multiply
(inf/NaN values may still cause NaN values in the result).
To convert a matrix to another layout and type, call:
// Provided by VK_NV_cooperative_vector
void vkCmdConvertCooperativeVectorMatrixNV(
VkCommandBuffer commandBuffer,
uint32_t infoCount,
const VkConvertCooperativeVectorMatrixInfoNV* pInfos);
-
commandBufferis the command buffer into which the command will be recorded. -
infoCountis the number of layout conversions to perform. -
pInfosis a pointer to an array of VkConvertCooperativeVectorMatrixInfoNV structures containing information about the layout conversion.
This command does the same conversions as
vkConvertCooperativeVectorMatrixNV, but executes on the device.
One conversion is performed for each of the infoCount elements of
pInfos.
This command’s execution is synchronized using
VK_PIPELINE_STAGE_2_CONVERT_COOPERATIVE_VECTOR_MATRIX_BIT_NV.
9.33. 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 a VkStructureType value identifying 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 application
to the size of the buffer, in bytes, pointed to by pData, and on
return the variable is overwritten with the amount of data actually written
to pData.
If pDataSize is less than the maximum size that can be retrieved by
the validation cache, at most pDataSize bytes will be written to
pData, and vkGetValidationCacheDataEXT will return
VK_INCOMPLETE instead of VK_SUCCESS, to indicate that not all of
the validation cache was returned.
Any data written to pData is valid and can be provided as the
pInitialData member of the VkValidationCacheCreateInfoEXT
structure passed to vkCreateValidationCacheEXT.
Two calls to vkGetValidationCacheDataEXT with the same parameters
must retrieve the same data unless a command that modifies the contents of
the cache is called between them.
Applications can store the data retrieved from the validation cache, and
use these data, possibly in a future run of the application, to populate new
validation cache objects.
The results of validation, however, may depend on the vendor ID, device ID,
driver version, and other details of the device.
To enable applications to detect when previously retrieved data is
incompatible with the device, the initial bytes written to pData must
be a header consisting of the following members:
| 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.
|
Note
|
This query does not behave consistently with the behavior described in Opaque Binary Data Results, for historical reasons. If the amount of data available is larger than the passed |
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.
9.34. CUDA Modules
9.34.1. Creating a CUDA Module
CUDA modules must contain some kernel code and must expose at least one function entry point.
CUDA modules are represented by VkCudaModuleNV handles:
// Provided by VK_NV_cuda_kernel_launch
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCudaModuleNV)
To create a CUDA module, call:
// Provided by VK_NV_cuda_kernel_launch
VkResult vkCreateCudaModuleNV(
VkDevice device,
const VkCudaModuleCreateInfoNV* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkCudaModuleNV* pModule);
-
deviceis the logical device that creates the shader module. -
pCreateInfois a pointer to a VkCudaModuleCreateInfoNV structure. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pModuleis a pointer to a VkCudaModuleNV handle in which the resulting CUDA module object is returned.
Once a CUDA module has been created, the application may create the function entry point, which must refer to one function in the module.
The VkCudaModuleCreateInfoNV structure is defined as:
// Provided by VK_NV_cuda_kernel_launch
typedef struct VkCudaModuleCreateInfoNV {
VkStructureType sType;
const void* pNext;
size_t dataSize;
const void* pData;
} VkCudaModuleCreateInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextmay beNULLor may be a pointer to a structure extending this structure. -
dataSizeis the length of thepDataarray. -
pDatais a pointer to CUDA code
9.34.2. Creating a CUDA Function Handle
CUDA functions are represented by VkCudaFunctionNV handles.
Handles to global functions may then be used to issue a kernel launch
(i.e. dispatch) from a commandbuffer.
See Dispatching Command for CUDA PTX kernel.
// Provided by VK_NV_cuda_kernel_launch
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCudaFunctionNV)
To create a CUDA function, call:
// Provided by VK_NV_cuda_kernel_launch
VkResult vkCreateCudaFunctionNV(
VkDevice device,
const VkCudaFunctionCreateInfoNV* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkCudaFunctionNV* pFunction);
-
deviceis the logical device that creates the shader module. -
pCreateInfois a pointer to a VkCudaFunctionCreateInfoNV structure. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pFunctionis a pointer to a VkCudaFunctionNV handle in which the resulting CUDA function object is returned.
The VkCudaFunctionCreateInfoNV structure is defined as:
// Provided by VK_NV_cuda_kernel_launch
typedef struct VkCudaFunctionCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkCudaModuleNV module;
const char* pName;
} VkCudaFunctionCreateInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
moduleis the CUDA VkCudaModuleNV module in which the function resides. -
pNameis a null-terminated UTF-8 string containing the name of the shader entry point for this stage.
9.34.3. Destroying a CUDA Function
To destroy a CUDA function handle, call:
// Provided by VK_NV_cuda_kernel_launch
void vkDestroyCudaFunctionNV(
VkDevice device,
VkCudaFunctionNV function,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the Function. -
functionis the handle of the CUDA function to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
9.34.4. Destroying a CUDA Module
To destroy a CUDA shader module, call:
// Provided by VK_NV_cuda_kernel_launch
void vkDestroyCudaModuleNV(
VkDevice device,
VkCudaModuleNV module,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the shader module. -
moduleis the handle of the CUDA module to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
9.34.5. Reading back CUDA Module Cache
After uploading the PTX kernel code, the module compiles the code to generate a binary cache with all the necessary information for the device to execute it. It is possible to read back this cache for later use, such as accelerating the initialization of further executions.
To get the CUDA module cache call:
// Provided by VK_NV_cuda_kernel_launch
VkResult vkGetCudaModuleCacheNV(
VkDevice device,
VkCudaModuleNV module,
size_t* pCacheSize,
void* pCacheData);
-
deviceis the logical device that destroys the Function. -
moduleis the CUDA module. -
pCacheSizeis a pointer containing the amount of bytes to be copied inpCacheData -
pCacheDatais a pointer to a buffer in which to copy the binary cache
If pCacheData is NULL, then the size of the binary cache, in bytes,
is returned in pCacheSize.
Otherwise, pCacheSize must point to a variable set by the application
to the size of the buffer, in bytes, pointed to by pCacheData, and on
return the variable is overwritten with the amount of data actually written
to pCacheData.
If pCacheSize is less than the size of the binary shader code, nothing
is written to pCacheData, and VK_INCOMPLETE will be returned
instead of VK_SUCCESS.
The returned cache may then be used later for further initialization of the CUDA module, by sending this cache instead of the PTX code when using vkCreateCudaModuleNV.
|
Note
|
Using the binary cache instead of the original PTX code should significantly speed up initialization of the CUDA module, given that the whole compilation and validation will not be necessary. As with VkPipelineCache, the binary cache depends on the specific implementation. The application must assume the cache upload might fail in many circumstances and thus may have to get ready for falling back to the original PTX code if necessary. Most often, the cache may succeed if the same device driver and architecture is used between the cache generation from PTX and the use of this cache. In the event of a new driver version or if using a different device architecture, this cache may become invalid. |
|
Note
|
This query does not behave consistently with the behavior described in Opaque Binary Data Results, for historical reasons. If the amount of data available is larger than the passed |
9.34.6. Limitations
CUDA and Vulkan do not use the device in the same configuration. The following limitations must be taken into account:
-
It is not possible to read or write global parameters from Vulkan. The only way to share resources or send values to the PTX kernel is to pass them as arguments of the function. See Resources sharing between CUDA Kernel and Vulkan for more details.
-
No calls to functions external to the module PTX are supported.
-
Vulkan disables some shader/kernel exceptions, which could break CUDA kernels relying on exceptions.
-
CUDA kernels submitted to Vulkan are limited to the amount of shared memory, which can be queried from the physical capabilities. It may be less than what CUDA can offer.
-
CUDA instruction-level preemption (CILP) does not work.
-
CUDA Unified Memory will not work in this extension.
-
CUDA Dynamic parallelism is not supported.
-
vk*DispatchIndirectis not available.
10. Pipelines
The following figure shows a block diagram of the Vulkan pipelines. Some Vulkan commands specify geometric objects to be drawn or computational work to be performed, while others specify state controlling how objects are handled by the various pipeline stages, or control data transfer between memory organized as images and buffers. Commands are effectively sent through a processing pipeline, either a graphics pipeline, a ray tracing pipeline, or a compute pipeline.
The graphics pipeline can be operated in two modes, as either primitive shading or mesh shading pipeline.
Primitive Shading
The first stage of the graphics pipeline (Input Assembler) assembles vertices to form geometric primitives such as points, lines, and triangles, based on a requested primitive topology. In the next stage (Vertex Shader) vertices can be transformed, computing positions and attributes for each vertex. If tessellation and/or geometry shaders are supported, they can then generate multiple primitives from a single input primitive, possibly changing the primitive topology or generating additional attribute data in the process.
Cluster Culling Shading
When using the Cluster Culling Shader, a compute-like shader will perform cluster-based culling, a set of new built-in output variables are used to express visible cluster, in addition, a new built-in function is used to emit these variables from the cluster culling shader to the Input Assembler(IA) stage, then IA can use these variables to fetch vertices of visible cluster and drive vertex shader to work.
Mesh Shading
When using the mesh shading pipeline input primitives are not assembled implicitly, but explicitly through the (Mesh Shader). The work on the mesh pipeline is initiated by the application drawing a set of mesh tasks.
If an optional (Task Shader) is active, each task triggers the execution of a task shader workgroup that will generate a new set of tasks upon completion. Each of these spawned tasks, or each of the original dispatched tasks if no task shader is present, triggers the execution of a mesh shader workgroup that produces an output mesh with a variable-sized number of primitives assembled from vertices stored in the output mesh.
Common
The final resulting primitives are clipped to a clip volume in preparation for the next stage, Rasterization. The rasterizer produces a series of fragments associated with a region of the framebuffer, from a two-dimensional description of a point, line segment, or triangle. These fragments are processed by fragment operations to determine whether generated values will be written to the framebuffer. Fragment shading determines the values to be written to the framebuffer attachments. Framebuffer operations then read and write the color and depth/stencil attachments of the framebuffer for a given subpass of a render pass instance. The attachments can be used as input attachments in the fragment shader in a later subpass of the same render pass.
The compute pipeline is a separate pipeline from the graphics pipeline, which operates on one-, two-, or three-dimensional workgroups which can read from and write to buffer and image memory.
This ordering is meant only as a tool for describing Vulkan, not as a strict rule of how Vulkan is implemented, and we present it only as a means to organize the various operations of the pipelines. Actual ordering guarantees between pipeline stages are explained in detail in the synchronization chapter.
Each pipeline is controlled by a monolithic object created from a description of all of the shader stages and any relevant fixed-function stages. Linking the whole pipeline together allows the optimization of shaders based on their input/outputs and eliminates expensive draw time state validation.
A pipeline object is bound to the current state using vkCmdBindPipeline. Any pipeline object state that is specified as dynamic is not applied to the current state when the pipeline object is bound, but is instead set by dynamic state setting commands.
If the commandBufferInheritance
feature is not enabled, then no
state, including dynamic state, is inherited from one command buffer to
another.
If the commandBufferInheritance
feature is enabled, then all graphics and compute state that is valid at the
end of the command buffer executed in a queue is inherited and valid at
beginning of the command buffer next executed in the same queue.
This applies to both primary and secondary command buffers, where a primary
command buffer submitted to a queue will inherit state from the previously
submitted command buffer to that queue, secondary command buffers will
inherit state from the primary or seconard command buffer they are executed
in, and after a seconard command buffer is executed, its state inherited by
the primary or secondary command buffer that executed it.
Command buffers executed in one queue do not inherit state from any command
buffers executed in another queue.
Compute,
ray tracing,
and graphics pipelines are each represented by VkPipeline handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipeline)
10.1. Multiple Pipeline Creation
Multiple pipelines can be created in a single call by commands such as vkCreateExecutionGraphPipelinesAMDX, vkCreateRayTracingPipelinesKHR, vkCreateRayTracingPipelinesNV, vkCreateDataGraphPipelinesARM, vkCreateComputePipelines, and vkCreateGraphicsPipelines.
The creation commands are passed an array pCreateInfos of
Vk*PipelineCreateInfo structures specifying parameters of each
pipeline to be created, and return a corresponding array of handles in
pPipelines.
Each element index i of pPipelines is created based on the
corresponding element i of pCreateInfos.
Applications can group together similar pipelines to be created in a single call, and implementations are encouraged to look for reuse opportunities when creating a group.
When attempting to create many pipelines in a single command, it is possible
that creation may fail for a subset of them.
In this case, the corresponding elements of pPipelines will be
VK_NULL_HANDLE.
If creation fails for a pipeline despite valid arguments (for example, due
to out of memory errors), the VkResult code returned by the pipeline
creation command will indicate why.
The implementation will attempt to create all pipelines, and only return
VK_NULL_HANDLE values for those that actually failed.
If creation fails for a pipeline that has the
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT set in its
Vk*PipelineCreateInfo, pipelines at an index in the pPipelines
array greater than or equal to that of the failing pipeline will be
VK_NULL_HANDLE.
If creation fails for multiple pipelines, the returned VkResult must
be the return value of any one of the pipelines which did not succeed.
An application can reliably clean up from a failed call by iterating over
the pPipelines array and destroying every element that is not
VK_NULL_HANDLE.
If the entire command fails and no pipelines are created, all elements of
pPipelines will be VK_NULL_HANDLE.
10.2. Compute Pipelines
Compute pipelines consist of a single static compute shader stage and the pipeline layout.
The compute pipeline represents a compute shader and is created by calling
vkCreateComputePipelines
with module and pName selecting an entry point from a shader
module, where that entry point defines a valid compute shader, in the
VkPipelineShaderStageCreateInfo structure contained within the
VkComputePipelineCreateInfo structure.
To create compute pipelines, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateComputePipelines(
VkDevice device,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkComputePipelineCreateInfo* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
deviceis the logical device that creates the compute pipelines. -
pipelineCacheis either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or to enable caching, the handle of a valid VkPipelineCache object. The implementation must not access this object outside of the duration of this 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.
Pipelines are created and returned as described for Multiple Pipeline Creation.
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 a VkStructureType value identifying 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. If VkPhysicalDeviceProperties::apiVersionis greater than or equal to Vulkan 1.3 or VK_KHR_maintenance4 is enabledlayoutmust not be accessed outside of the duration of the command this structure is passed to. -
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 the pNext chain includes a VkPipelineCreateFlags2CreateInfo
structure, VkPipelineCreateFlags2CreateInfo::flags from that
structure is used instead of flags from this structure.
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 a VkStructureType value identifying 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. The implementation must not access this object outside of the duration of the command this structure is passed to. -
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 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 structure 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 task, mesh, or compute stage.
|
Note
|
If |
Bits which can be set by commands and structures, specifying one or more shader stages, are:
// Provided by VK_VERSION_1_0
typedef enum VkShaderStageFlagBits {
VK_SHADER_STAGE_VERTEX_BIT = 0x00000001,
VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT = 0x00000002,
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT = 0x00000004,
VK_SHADER_STAGE_GEOMETRY_BIT = 0x00000008,
VK_SHADER_STAGE_FRAGMENT_BIT = 0x00000010,
VK_SHADER_STAGE_COMPUTE_BIT = 0x00000020,
VK_SHADER_STAGE_ALL_GRAPHICS = 0x0000001F,
VK_SHADER_STAGE_ALL = 0x7FFFFFFF,
// Provided by VK_KHR_ray_tracing_pipeline
VK_SHADER_STAGE_RAYGEN_BIT_KHR = 0x00000100,
// Provided by VK_KHR_ray_tracing_pipeline
VK_SHADER_STAGE_ANY_HIT_BIT_KHR = 0x00000200,
// Provided by VK_KHR_ray_tracing_pipeline
VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR = 0x00000400,
// Provided by VK_KHR_ray_tracing_pipeline
VK_SHADER_STAGE_MISS_BIT_KHR = 0x00000800,
// Provided by VK_KHR_ray_tracing_pipeline
VK_SHADER_STAGE_INTERSECTION_BIT_KHR = 0x00001000,
// Provided by VK_KHR_ray_tracing_pipeline
VK_SHADER_STAGE_CALLABLE_BIT_KHR = 0x00002000,
// Provided by VK_EXT_mesh_shader
VK_SHADER_STAGE_TASK_BIT_EXT = 0x00000040,
// Provided by VK_EXT_mesh_shader
VK_SHADER_STAGE_MESH_BIT_EXT = 0x00000080,
// Provided by VK_HUAWEI_subpass_shading
VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI = 0x00004000,
// Provided by VK_HUAWEI_cluster_culling_shader
VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI = 0x00080000,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_RAYGEN_BIT_NV = VK_SHADER_STAGE_RAYGEN_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_ANY_HIT_BIT_NV = VK_SHADER_STAGE_ANY_HIT_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV = VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_MISS_BIT_NV = VK_SHADER_STAGE_MISS_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_INTERSECTION_BIT_NV = VK_SHADER_STAGE_INTERSECTION_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_SHADER_STAGE_CALLABLE_BIT_NV = VK_SHADER_STAGE_CALLABLE_BIT_KHR,
// Provided by VK_NV_mesh_shader
VK_SHADER_STAGE_TASK_BIT_NV = VK_SHADER_STAGE_TASK_BIT_EXT,
// Provided by VK_NV_mesh_shader
VK_SHADER_STAGE_MESH_BIT_NV = VK_SHADER_STAGE_MESH_BIT_EXT,
} VkShaderStageFlagBits;
-
VK_SHADER_STAGE_VERTEX_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_EXTspecifies the task stage. -
VK_SHADER_STAGE_MESH_BIT_EXTspecifies the mesh stage. -
VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEIspecifies the cluster culling 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;
or the equiavlent
// Provided by VK_EXT_shader_object
typedef VkPipelineShaderStageRequiredSubgroupSizeCreateInfo VkShaderRequiredSubgroupSizeCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
requiredSubgroupSizeis an unsigned integer value specifying the required subgroup size for the newly created pipeline shader stage.
If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is
included in the pNext chain of VkPipelineShaderStageCreateInfo,
it specifies that the pipeline shader stage being compiled has a required
subgroup size.
If a VkShaderRequiredSubgroupSizeCreateInfoEXT structure is included
in the pNext chain of VkShaderCreateInfoEXT, it specifies that
the shader being compiled has a required subgroup size.
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 a VkStructureType value identifying 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. The implementation must not access this object outside of the duration of the command this structure is passed to. -
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 VkPipelineRobustnessCreateInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPipelineRobustnessCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineRobustnessBufferBehavior storageBuffers;
VkPipelineRobustnessBufferBehavior uniformBuffers;
VkPipelineRobustnessBufferBehavior vertexInputs;
VkPipelineRobustnessImageBehavior images;
} VkPipelineRobustnessCreateInfo;
or the equivalent
// Provided by VK_EXT_pipeline_robustness
typedef VkPipelineRobustnessCreateInfo VkPipelineRobustnessCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
storageBufferssets the behavior of out of bounds accesses made to resources bound as:-
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER -
VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER -
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
-
-
uniformBuffersdescribes the behavior of out of bounds accesses made to resources bound as:-
VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER -
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER -
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC -
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK
-
-
vertexInputsdescribes the behavior of out of bounds accesses made to vertex input attributes -
imagesdescribes the behavior of out of bounds accesses made to resources bound as:-
VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE -
VK_DESCRIPTOR_TYPE_STORAGE_IMAGE
-
Resources bound as VK_DESCRIPTOR_TYPE_MUTABLE_EXT will have the
robustness behavior that covers its active descriptor type.
The scope of the effect of VkPipelineRobustnessCreateInfo depends on
which structure’s pNext chain it is included in.
-
VkGraphicsPipelineCreateInfo,VkRayTracingPipelineCreateInfoKHR,VkComputePipelineCreateInfo:
The robustness behavior described byVkPipelineRobustnessCreateInfoapplies to all accesses through this pipeline -
VkPipelineShaderStageCreateInfo:
The robustness behavior described byVkPipelineRobustnessCreateInfoapplies to all accesses emanating from the shader code of this shader stage
If VkPipelineRobustnessCreateInfo is specified for both a pipeline and
a pipeline stage, the VkPipelineRobustnessCreateInfo specified for the
pipeline stage will take precedence.
When VkPipelineRobustnessCreateInfo is specified for a pipeline, it
only affects the subset of the pipeline that is specified by the create
info, as opposed to subsets linked from pipeline libraries.
For VkGraphicsPipelineCreateInfo, that subset is specified by
VkGraphicsPipelineLibraryCreateInfoEXT::flags.
For VkRayTracingPipelineCreateInfoKHR, that subset is specified by the
specific stages in VkRayTracingPipelineCreateInfoKHR::pStages.
Possible values of the storageBuffers, uniformBuffers, and
vertexInputs members of VkPipelineRobustnessCreateInfo are:
// Provided by VK_VERSION_1_4
typedef enum VkPipelineRobustnessBufferBehavior {
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT = 0,
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED = 1,
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS = 2,
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2 = 3,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT = VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED_EXT = VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT = VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT = VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2,
} VkPipelineRobustnessBufferBehavior;
or the equivalent
// Provided by VK_EXT_pipeline_robustness
typedef VkPipelineRobustnessBufferBehavior VkPipelineRobustnessBufferBehaviorEXT;
-
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULTspecifies that out of bounds buffer accesses follow the behavior of robust buffer access features enabled for the device. -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLEDspecifies that buffer accesses must not be out of bounds. -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESSspecifies that buffer accesses conform to Robust Buffer Access guarantees. -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2specifies that buffer accesses conform to Robust Buffer Access 2 guarantees.
Possible values of the images member of
VkPipelineRobustnessCreateInfo are:
// Provided by VK_VERSION_1_4
typedef enum VkPipelineRobustnessImageBehavior {
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT = 0,
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED = 1,
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS = 2,
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2 = 3,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT_EXT = VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED_EXT = VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_EXT = VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS,
// Provided by VK_EXT_pipeline_robustness
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2_EXT = VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2,
} VkPipelineRobustnessImageBehavior;
or the equivalent
// Provided by VK_EXT_pipeline_robustness
typedef VkPipelineRobustnessImageBehavior VkPipelineRobustnessImageBehaviorEXT;
-
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULTspecifies that out of bounds image accesses follow the behavior of robust image access features enabled for the device. -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLEDspecifies that image accesses must not be out of bounds. -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESSspecifies that image accesses conform to Robust Image Access guarantees. -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2specifies that image accesses conform to Robust Image Access 2 guarantees.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
identifierSizeis the size, in bytes, of the buffer pointed to bypIdentifier. -
pIdentifieris a pointer to a buffer of opaque data specifying an identifier.
Any identifier can be used.
If the pipeline being created with identifier requires compilation to
complete the pipeline creation call, pipeline compilation must fail as
defined by VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT.
pIdentifier and identifierSize can be obtained from an
VkShaderModuleIdentifierEXT queried earlier.
If a compute pipeline is going to be used in Device-Generated Commands by specifying its pipeline token with
VkBindPipelineIndirectCommandNV, then that pipeline’s associated
metadata must be saved at a specified buffer device address for later use
in indirect command generation.
The buffer device address must be specified at the time of compute pipeline
creation with VkComputePipelineIndirectBufferInfoNV structure in the
pNext chain of VkComputePipelineCreateInfo.
The VkComputePipelineIndirectBufferInfoNV structure is defined as:
// Provided by VK_NV_device_generated_commands_compute
typedef struct VkComputePipelineIndirectBufferInfoNV {
VkStructureType sType;
const void* pNext;
VkDeviceAddress deviceAddress;
VkDeviceSize size;
VkDeviceAddress pipelineDeviceAddressCaptureReplay;
} VkComputePipelineIndirectBufferInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceAddressis the address where the pipeline’s metadata will be stored. -
sizeis the size of pipeline’s metadata that was queried using vkGetPipelineIndirectMemoryRequirementsNV. -
pipelineDeviceAddressCaptureReplayis the device address where pipeline’s metadata was originally saved and can now be used to re-populatedeviceAddressfor replay.
If pipelineDeviceAddressCaptureReplay is zero, no specific address is
requested.
If pipelineDeviceAddressCaptureReplay is not zero, then it must be an
address retrieved from an identically created pipeline on the same
implementation.
The pipeline metadata must also be placed on an identically created buffer
and at the same offset using the vkCmdUpdatePipelineIndirectBufferNV
command.
To save a compute pipeline’s metadata at a device address call:
// Provided by VK_NV_device_generated_commands_compute
void vkCmdUpdatePipelineIndirectBufferNV(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipeline pipeline);
-
commandBufferis the command buffer into which the command will be recorded. -
pipelineBindPointis a VkPipelineBindPoint value specifying the type of pipeline whose metadata will be saved. -
pipelineis the pipeline whose metadata will be saved.
vkCmdUpdatePipelineIndirectBufferNV is only allowed outside of a
render pass.
This command is treated as a “transfer” operation for the purposes of
synchronization barriers.
The writes to the address must be synchronized using stages
VK_PIPELINE_STAGE_2_COPY_BIT and
VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_NV and with access masks
VK_ACCESS_MEMORY_WRITE_BIT and
VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_NV respectively before using the
results in preprocessing.
10.3. Graphics Pipelines
Graphics pipelines consist of multiple shader stages, multiple fixed-function pipeline stages, and a pipeline layout.
To create graphics pipelines, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateGraphicsPipelines(
VkDevice device,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkGraphicsPipelineCreateInfo* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
deviceis the logical device that creates the graphics pipelines. -
pipelineCacheis either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or to enable caching, the handle of a valid VkPipelineCache object. The implementation must not access this object outside of the duration of this 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.
Pipelines are created and returned as described for Multiple Pipeline Creation.
|
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 a VkStructureType value identifying 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. It is ignored if the pipeline includes a mesh shader stage. It can beNULLif the pipeline is created with theVK_DYNAMIC_STATE_VERTEX_INPUT_EXTdynamic state set. -
pInputAssemblyStateis a pointer to a VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior for vertex shading, as described in Drawing Commands. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif the pipeline is created with bothVK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE, andVK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGYdynamic states set anddynamicPrimitiveTopologyUnrestrictedisVK_TRUE. It is ignored if the pipeline includes a mesh shader stage. -
pTessellationStateis a pointer to a VkPipelineTessellationStateCreateInfo structure defining tessellation state used by tessellation shaders. It can beNULLif the pipeline is created with theVK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXTdynamic state set. -
pViewportStateis a pointer to a VkPipelineViewportStateCreateInfo structure defining viewport state used when rasterization is enabled. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif the pipeline is created with bothVK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT, andVK_DYNAMIC_STATE_SCISSOR_WITH_COUNTdynamic states set. -
pRasterizationStateis a pointer to a VkPipelineRasterizationStateCreateInfo structure defining rasterization state. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif the pipeline is created with all ofVK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT,VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE,VK_DYNAMIC_STATE_POLYGON_MODE_EXT,VK_DYNAMIC_STATE_CULL_MODE,VK_DYNAMIC_STATE_FRONT_FACE,VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE,VK_DYNAMIC_STATE_DEPTH_BIAS, andVK_DYNAMIC_STATE_LINE_WIDTHdynamic states set. -
pMultisampleStateis a pointer to a VkPipelineMultisampleStateCreateInfo structure defining multisample state used when rasterization is enabled. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif the pipeline is created with all ofVK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT,VK_DYNAMIC_STATE_SAMPLE_MASK_EXT, andVK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXTdynamic states set, and either the alphaToOne feature is not enabled orVK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXTis set, in which case VkPipelineMultisampleStateCreateInfo::sampleShadingEnableis assumed to beVK_FALSE. -
pDepthStencilStateis a pointer to a VkPipelineDepthStencilStateCreateInfo structure defining depth/stencil state used when rasterization is enabled for depth or stencil attachments accessed during rendering. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif the pipeline is created with all ofVK_DYNAMIC_STATE_DEPTH_TEST_ENABLE,VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE,VK_DYNAMIC_STATE_DEPTH_COMPARE_OP,VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE,VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE,VK_DYNAMIC_STATE_STENCIL_OP, andVK_DYNAMIC_STATE_DEPTH_BOUNDSdynamic states set. -
pColorBlendStateis a pointer to a VkPipelineColorBlendStateCreateInfo structure defining color blend state used when rasterization is enabled for any color attachments accessed during rendering. If theVK_EXT_extended_dynamic_state3extension is enabled, it can beNULLif the pipeline is created with all ofVK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT,VK_DYNAMIC_STATE_LOGIC_OP_EXT,VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT,VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT,VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT, andVK_DYNAMIC_STATE_BLEND_CONSTANTSdynamic states set. -
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. If VkPhysicalDeviceProperties::apiVersionis greater than or equal to Vulkan 1.3 or VK_KHR_maintenance4 is enabledlayoutmust not be accessed outside of the duration of the command this structure is passed to. -
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. The implementation must not access this object outside of the duration of the command this structure is passed to. -
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.
|
Note
|
With |
The state required for a graphics pipeline is divided into vertex input state, pre-rasterization shader state, fragment shader state, and fragment output state.
Vertex input state is defined by:
If
this pipeline specifies
pre-rasterization state
either directly or by including it as a pipeline library and its
pStages includes a vertex shader, this state must be specified to
create a complete graphics pipeline.
If a pipeline includes
VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT in
VkGraphicsPipelineLibraryCreateInfoEXT::flags either explicitly
or as a default, and either the conditions requiring this state for a
complete graphics pipeline are met
or this pipeline does not specify
pre-rasterization state in
any way, that pipeline must specify this state directly.
Pre-rasterization shader state is defined by:
-
VkPipelineShaderStageCreateInfo entries for:
-
Vertex shaders
-
Tessellation control shaders
-
Tessellation evaluation shaders
-
Geometry shaders
-
Task shaders
-
Mesh shaders
-
-
Within the VkPipelineLayout, all descriptor sets with pre-rasterization shader bindings if
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_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) -
Inclusion/omission of the
VK_PIPELINE_CREATE_2_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVEflag
This state must be specified to create a complete graphics pipeline.
If either the pNext chain includes a
VkGraphicsPipelineLibraryCreateInfoEXT structure with
VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT
included in flags, or it is not specified and would default to include
that value, this state must be specified in the pipeline.
Fragment shader state is defined by:
-
A VkPipelineShaderStageCreateInfo entry for the fragment shader
-
Within the VkPipelineLayout, all descriptor sets with fragment shader bindings if
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_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 -
Inclusion/omission of the
VK_PIPELINE_CREATE_2_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVEflag
If
a pipeline specifies
pre-rasterization state
either directly or by including it as a pipeline library and
rasterizerDiscardEnable is VK_FALSE
or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE is used,
this state must be specified to create a
complete graphics pipeline.
If a pipeline includes
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT in
VkGraphicsPipelineLibraryCreateInfoEXT::flags either explicitly
or as a default, and either the conditions requiring this state for a
complete graphics pipeline are met
or this pipeline does not specify
pre-rasterization state in
any way, that pipeline must specify this state directly.
Fragment output state is defined by:
-
VkRenderPass and
subpassparameter -
Inclusion/omission of the
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTandVK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTflags -
Inclusion/omission of the
VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXTflag
If
a pipeline specifies
pre-rasterization state
either directly or by including it as a pipeline library and
rasterizerDiscardEnable is VK_FALSE
or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE is used,
this state must be specified to create a
complete graphics pipeline.
If a pipeline includes
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT in
VkGraphicsPipelineLibraryCreateInfoEXT::flags either explicitly
or as a default, and either the conditions requiring this state for a
complete graphics pipeline are met
or this pipeline does not specify
pre-rasterization state in
any way, that pipeline must specify this state directly.
Dynamic state values set via pDynamicState must be ignored if the
state they correspond to is not otherwise statically set by one of the state
subsets used to create the pipeline.
Additionally, setting dynamic state values must not modify whether state in
a linked library is static or dynamic; this is set and unchangeable when the
library is created.
For example, if a pipeline only included
pre-rasterization shader
state, then any dynamic state value corresponding to depth or stencil
testing has no effect.
Any linked library that has dynamic state enabled that same dynamic state
must also be enabled in all the other linked libraries to which that
dynamic state applies.
A complete graphics pipeline always includes pre-rasterization shader state, with other subsets included depending on that state as specified in the above sections.
If different subsets are linked together with pipeline layouts created with
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, the final
effective pipeline layout is effectively the union of the linked pipeline
layouts.
When binding descriptor sets for this pipeline, the pipeline layout used
must be compatible with this union.
This pipeline layout can be overridden when linking with
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT by providing a
VkPipelineLayout that is compatible
with this union other than
VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, or when linking
without VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT by providing
a VkPipelineLayout that is fully
compatible with this union.
If the pNext chain includes a VkPipelineCreateFlags2CreateInfo
structure, VkPipelineCreateFlags2CreateInfo::flags from that
structure is used instead of flags from this structure.
The VkPipelineFragmentDensityMapLayeredCreateInfoVALVE structure is
defined as:
// Provided by VK_VALVE_fragment_density_map_layered
typedef struct VkPipelineFragmentDensityMapLayeredCreateInfoVALVE {
VkStructureType sType;
const void* pNext;
uint32_t maxFragmentDensityMapLayers;
} VkPipelineFragmentDensityMapLayeredCreateInfoVALVE;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxFragmentDensityMapLayersis the maximum number of layers which can be used with a fragment density map.
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 a VkStructureType value identifying 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 the pNext
chain of VkGraphicsPipelineCreateInfo includes this structure, it
specifies the view mask and format of attachments used for rendering.
If this structure is not specified, and the pipeline does not include a
VkRenderPass, viewMask and colorAttachmentCount are 0,
and depthAttachmentFormat and stencilAttachmentFormat are
VK_FORMAT_UNDEFINED.
If a graphics pipeline is created with a valid VkRenderPass,
parameters of this structure are ignored.
If depthAttachmentFormat, stencilAttachmentFormat, or any
element of pColorAttachmentFormats is VK_FORMAT_UNDEFINED, it
indicates that the corresponding attachment is unused within the render
pass.
Valid formats indicate that an attachment can be used - but it is still
valid to set the attachment to NULL when beginning rendering.
If the render pass is going to be used with an external format resolve
attachment, a VkExternalFormatANDROID structure must also be included
in the pNext chain of VkGraphicsPipelineCreateInfo, defining the
external format of the resolve attachment that will be used.
The VkPipelineCreateFlags2CreateInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPipelineCreateFlags2CreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags2 flags;
} VkPipelineCreateFlags2CreateInfo;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkPipelineCreateFlags2CreateInfo VkPipelineCreateFlags2CreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits2 specifying how a pipeline will be generated.
If this structure is included in the pNext chain of a pipeline
creation structure, flags is used instead of the corresponding
flags value passed in that creation structure, allowing additional
creation flags to be specified.
Bits which can be set in
VkPipelineCreateFlags2CreateInfo::flags, specifying how a
pipeline is created, are:
// Provided by VK_VERSION_1_4
// Flag bits for VkPipelineCreateFlagBits2
typedef VkFlags64 VkPipelineCreateFlagBits2;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BIT = 0x00000001ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT = 0x00000002ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DERIVATIVE_BIT = 0x00000004ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BIT = 0x00000008ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISPATCH_BASE_BIT = 0x00000010ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT = 0x00000100ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BIT = 0x00000200ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BIT = 0x08000000ULL;
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT = 0x40000000ULL;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue with VK_KHR_maintenance5 or VK_VERSION_1_4
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDX = 0x100000000ULL;
#endif
// Provided by VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_BUILT_IN_PRIMITIVES_BIT_KHR = 0x00001000ULL;
// Provided by VK_NV_ray_tracing_linear_swept_spheres
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_SPHERES_AND_LINEAR_SWEPT_SPHERES_BIT_NV = 0x200000000ULL;
// Provided by VK_EXT_legacy_dithering with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and (VK_KHR_maintenance5 or VK_VERSION_1_4)
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x400000000ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BIT_KHR = 0x00000001ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT_KHR = 0x00000002ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DERIVATIVE_BIT_KHR = 0x00000004ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_maintenance5
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISPATCH_BASE_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DEFER_COMPILE_BIT_NV = 0x00000020ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_executable_properties
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_CAPTURE_STATISTICS_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_executable_properties
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR = 0x00000080ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_3 or VK_EXT_pipeline_creation_cache_control
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_3 or VK_EXT_pipeline_creation_cache_control
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BIT_KHR = 0x00000200ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_graphics_pipeline_library
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_graphics_pipeline_library
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_pipeline_library
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_LIBRARY_BIT_KHR = 0x00000800ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR = 0x00001000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR = 0x00010000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR = 0x00020000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR = 0x00080000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_device_generated_commands
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_NV = 0x00040000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing_motion_blur
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_MOTION_BIT_NV = 0x00100000ULL;
// Provided by VK_KHR_maintenance5 with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and VK_KHR_fragment_shading_rate
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00200000ULL;
// Provided by VK_KHR_maintenance5 with (VK_KHR_dynamic_rendering or VK_VERSION_1_3) and VK_EXT_fragment_density_map
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00400000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT = 0x01000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_attachment_feedback_loop_layout
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x02000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_attachment_feedback_loop_layout
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_4 or VK_EXT_pipeline_protected_access
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BIT_EXT = 0x08000000ULL;
// Provided by VK_KHR_maintenance5 with VK_VERSION_1_4 or VK_EXT_pipeline_protected_access
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT_EXT = 0x40000000ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_displacement_micromap
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV = 0x10000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DESCRIPTOR_BUFFER_BIT_EXT = 0x20000000ULL;
// Provided by VK_KHR_maintenance5 with VK_ARM_pipeline_opacity_micromap, VK_ARM_pipeline_opacity_micromap
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_DISALLOW_OPACITY_MICROMAP_BIT_ARM = 0x2000000000ULL;
// Provided by VK_KHR_pipeline_binary
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR = 0x80000000ULL;
// Provided by VK_EXT_device_generated_commands
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT = 0x4000000000ULL;
// Provided by VK_VALVE_fragment_density_map_layered
static const VkPipelineCreateFlagBits2 VK_PIPELINE_CREATE_2_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVE = 0x10000000000ULL;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkPipelineCreateFlagBits2 VkPipelineCreateFlagBits2KHR;
-
VK_PIPELINE_CREATE_2_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_2_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_2_DERIVATIVE_BITspecifies that the pipeline to be created will be a child of a previously created parent pipeline. -
VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BITspecifies that any shader input variables decorated asViewIndexwill be assigned values as if they were decorated asDeviceIndex. -
VK_PIPELINE_CREATE_2_DISPATCH_BASE_BITspecifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup. -
VK_PIPELINE_CREATE_2_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_2_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_2_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_2_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_2_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_2_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_2_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_2_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_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHRspecifies that all built-in primitives including triangles, spheres and LSS primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_BUILT_IN_PRIMITIVES_BIT_KHRis an alias forVK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR. -
VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHRspecifies that AABB primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_2_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_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_2_RAY_TRACING_ALLOW_SPHERES_AND_LINEAR_SWEPT_SPHERES_BIT_NVspecifies that the pipeline is allowed to use spheres or linear swept spheres as a geometry type in the acceleration structures. Using this flag may affect performance. -
VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_NVspecifies that the pipeline can be used in combination with Device-Generated Commands. -
VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXTspecifies that the pipeline can be used in aVkIndirectExecutionSetEXT. -
VK_PIPELINE_CREATE_2_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 VK_NULL_HANDLE. -
When creating multiple pipelines,
VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BITspecifies that control will be returned to the application if any individual pipeline returns a result which is notVK_SUCCESSrather than continuing to create additional pipelines. -
VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_MOTION_BIT_NVspecifies that the pipeline is allowed to useOpTraceRayMotionNV. -
VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies that the pipeline will be used with a fragment shading rate attachment. -
VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXTspecifies that the pipeline will be used with a fragment density map attachment. -
VK_PIPELINE_CREATE_2_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVEspecifies that the pipeline can be used with layered fragment density maps. -
VK_PIPELINE_CREATE_2_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_2_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXTspecifies that pipeline libraries should retain any information necessary to later perform an optimal link withVK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT. -
VK_PIPELINE_CREATE_2_DESCRIPTOR_BUFFER_BIT_EXTspecifies that a pipeline will be used with descriptor buffers, rather than descriptor sets. -
VK_PIPELINE_CREATE_2_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies that the pipeline may be used with an attachment feedback loop including color attachments. -
VK_PIPELINE_CREATE_2_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies that the pipeline may be used with an attachment feedback loop including depth-stencil attachments. -
VK_PIPELINE_CREATE_2_RAY_TRACING_OPACITY_MICROMAP_BIT_EXTspecifies that the ray tracing pipeline can be used with acceleration structures which reference an opacity micromap array. -
VK_PIPELINE_CREATE_2_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NVspecifies that the ray tracing pipeline can be used with acceleration structures which reference a displacement micromap array. -
VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BITspecifies that the pipeline must not be bound to a protected command buffer. -
VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BITspecifies that the pipeline must not be bound to an unprotected command buffer. -
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHRspecifies thatVkPipelineBinaryKHRobjects can be created from the pipeline. IfVK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHRis used, implementations should not store pipeline data to an internal cache, if such a cache exists as stated bypipelineBinaryInternalCache. IfpipelineBinaryPrefersInternalCacheisVK_TRUE, applications should not useVK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR. -
VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXTspecifies that the pipeline will be used in a render pass that is begun withVK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT. -
VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDXspecifies that the pipeline will be used in an execution graph -
VK_PIPELINE_CREATE_2_DISALLOW_OPACITY_MICROMAP_BIT_ARMspecifies that the pipeline must not be used with acceleration structures which reference an opacity micromap array.
It is valid to set both VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT and
VK_PIPELINE_CREATE_2_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_2_LINK_TIME_OPTIMIZATION_BIT_EXT if available,
whether or not that bit was specified.
|
Note
|
Using |
// Provided by VK_VERSION_1_4
typedef VkFlags64 VkPipelineCreateFlags2;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkPipelineCreateFlags2 VkPipelineCreateFlags2KHR;
VkPipelineCreateFlags2 is a bitmask type for setting a mask of zero or
more VkPipelineCreateFlagBits2.
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_VERSION_1_4
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT = 0x08000000,
// Provided by VK_VERSION_1_4
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT = 0x40000000,
// 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_EXT_fragment_density_map with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = 0x00400000,
// Provided by VK_KHR_fragment_shading_rate with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00200000,
// Provided by VK_KHR_pipeline_executable_properties
VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR = 0x00000040,
// Provided by VK_KHR_pipeline_executable_properties
VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR = 0x00000080,
// Provided by VK_NV_device_generated_commands
VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV = 0x00040000,
// Provided by VK_KHR_pipeline_library
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR = 0x00000800,
// Provided by VK_EXT_descriptor_buffer
VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT = 0x20000000,
// Provided by VK_EXT_graphics_pipeline_library
VK_PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT = 0x00800000,
// Provided by VK_EXT_graphics_pipeline_library
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT = 0x00000400,
// Provided by VK_NV_ray_tracing_motion_blur
VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV = 0x00100000,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x02000000,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x04000000,
// Provided by VK_EXT_opacity_micromap
VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT = 0x01000000,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV = 0x10000000,
#endif
// Provided by VK_VERSION_1_1
// VK_PIPELINE_CREATE_DISPATCH_BASE is a deprecated alias
VK_PIPELINE_CREATE_DISPATCH_BASE = VK_PIPELINE_CREATE_DISPATCH_BASE_BIT,
// 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_BIT_KHR = VK_PIPELINE_CREATE_DISPATCH_BASE_BIT,
// Provided by VK_KHR_device_group
// VK_PIPELINE_CREATE_DISPATCH_BASE_KHR is a deprecated alias
VK_PIPELINE_CREATE_DISPATCH_BASE_KHR = VK_PIPELINE_CREATE_DISPATCH_BASE_BIT,
// Provided by VK_EXT_fragment_density_map with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
// VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT is a deprecated alias
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT = VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT,
// Provided by VK_KHR_fragment_shading_rate with VK_VERSION_1_3 or VK_KHR_dynamic_rendering
// VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR is a deprecated alias
VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,
// Provided by VK_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,
// Provided by VK_EXT_pipeline_protected_access
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT = VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT,
// Provided by VK_EXT_pipeline_protected_access
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT = VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_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_BASE_BITspecifies 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 sphere, LSS and triangle primitives will be skipped during traversal using pipeline trace ray instructions. -
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHRspecifies that AABB primitives will be skipped during traversal using pipeline trace ray instructions. -
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 VK_NULL_HANDLE. -
When creating multiple pipelines,
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BITspecifies that control will be returned to the application if any individual pipeline returns a result which is notVK_SUCCESSrather 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 and dynamic rendering. -
VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXTspecifies that the pipeline will be used with a fragment density map attachment and dynamic rendering. -
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. -
VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXTspecifies that a pipeline will be used with descriptor buffers, rather than descriptor sets. -
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies that the pipeline may be used with an attachment feedback loop including color attachments. It is ignored ifVK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXTis set inpDynamicStates. -
VK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies that the pipeline may be used with an attachment feedback loop including depth-stencil attachments. It is ignored ifVK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXTis set inpDynamicStates. -
VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXTspecifies that the ray tracing pipeline can be used with acceleration structures which reference an opacity micromap array. -
VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NVspecifies that the ray tracing pipeline can be used with acceleration structures which reference a displacement micromap array. -
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BITspecifies that the pipeline must not be bound to a protected command buffer. -
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BITspecifies that the pipeline must not be bound to an unprotected command buffer.
It is valid to set both VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and
VK_PIPELINE_CREATE_DERIVATIVE_BIT.
This allows a pipeline to be both a parent and possibly a child in a
pipeline hierarchy.
See Pipeline Derivatives for more
information.
When an implementation is looking up a pipeline in a
pipeline cache, if that pipeline is being created using
linked libraries, implementations should always return an equivalent
pipeline created with
VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT if available,
whether or not that bit was specified.
|
Note
|
Using |
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCreateFlags;
VkPipelineCreateFlags is a bitmask type for setting a mask of zero or
more VkPipelineCreateFlagBits.
The VkPipelineBinaryInfoKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t binaryCount;
const VkPipelineBinaryKHR* pPipelineBinaries;
} VkPipelineBinaryInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
binaryCountis the number of elements in thepPipelineBinariesarray. -
pPipelineBinariesis a pointer to an array of VkPipelineBinaryKHR handles.
If a VkPipelineBinaryInfoKHR structure with a binaryCount
greater than 0 is included in the pNext chain of any
Vk*PipelineCreateInfo structure when creating a pipeline,
implementations must use the data in pPipelineBinaries instead of
recalculating it.
Any shader module identifiers or shader modules declared in
VkPipelineShaderStageCreateInfo instances are ignored.
If this structure is not included in the pNext chain, it is equivalent
to specifying this structure with a binaryCount of 0.
The VkGraphicsPipelineLibraryCreateInfoEXT structure is defined as:
// Provided by VK_EXT_graphics_pipeline_library
typedef struct VkGraphicsPipelineLibraryCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkGraphicsPipelineLibraryFlagsEXT flags;
} VkGraphicsPipelineLibraryCreateInfoEXT;
-
sTypeis a VkStructureType value identifying 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, excluding any subsets from linked pipeline libraries.
If the pipeline is created with pipeline libraries, state from those
libraries is aggregated with said subset.
If this structure is omitted, and either
VkGraphicsPipelineCreateInfo::flags includes
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR or the
VkGraphicsPipelineCreateInfo::pNext chain includes a
VkPipelineLibraryCreateInfoKHR structure with a libraryCount
greater than 0, it is as if flags is 0.
Otherwise if this structure is omitted, it is as if flags includes all
possible subsets of the graphics pipeline (i.e. a
complete graphics pipeline).
// Provided by VK_EXT_graphics_pipeline_library
typedef VkFlags VkGraphicsPipelineLibraryFlagsEXT;
VkGraphicsPipelineLibraryFlagsEXT is a bitmask type for setting a mask
of zero or more VkGraphicsPipelineLibraryFlagBitsEXT.
Possible values of the flags member of
VkGraphicsPipelineLibraryCreateInfoEXT, specifying the subsets of a
graphics pipeline to compile are:
// Provided by VK_EXT_graphics_pipeline_library
typedef enum VkGraphicsPipelineLibraryFlagBitsEXT {
VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_EXT = 0x00000001,
VK_GRAPHICS_PIPELINE_LIBRARY_PRE_RASTERIZATION_SHADERS_BIT_EXT = 0x00000002,
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_SHADER_BIT_EXT = 0x00000004,
VK_GRAPHICS_PIPELINE_LIBRARY_FRAGMENT_OUTPUT_INTERFACE_BIT_EXT = 0x00000008,
} VkGraphicsPipelineLibraryFlagBitsEXT;
-
VK_GRAPHICS_PIPELINE_LIBRARY_VERTEX_INPUT_INTERFACE_BIT_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 a VkStructureType value identifying 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_VERSION_1_4
VK_DYNAMIC_STATE_LINE_STIPPLE = 1000259000,
// Provided by VK_NV_clip_space_w_scaling
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV = 1000087000,
// Provided by VK_EXT_discard_rectangles
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT = 1000099000,
// Provided by VK_EXT_discard_rectangles
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT = 1000099001,
// Provided by VK_EXT_discard_rectangles
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT = 1000099002,
// Provided by VK_EXT_sample_locations
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT = 1000143000,
// Provided by VK_KHR_ray_tracing_pipeline
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR = 1000347000,
// Provided by VK_NV_shading_rate_image
VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV = 1000164004,
// Provided by VK_NV_shading_rate_image
VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV = 1000164006,
// Provided by VK_NV_scissor_exclusive
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV = 1000205000,
// Provided by VK_NV_scissor_exclusive
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV = 1000205001,
// Provided by VK_KHR_fragment_shading_rate
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR = 1000226000,
// Provided by VK_EXT_vertex_input_dynamic_state
VK_DYNAMIC_STATE_VERTEX_INPUT_EXT = 1000352000,
// Provided by VK_EXT_extended_dynamic_state2
VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT = 1000377000,
// Provided by VK_EXT_extended_dynamic_state2
VK_DYNAMIC_STATE_LOGIC_OP_EXT = 1000377003,
// Provided by VK_EXT_color_write_enable
VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT = 1000381000,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT = 1000455003,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_POLYGON_MODE_EXT = 1000455004,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT = 1000455005,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_SAMPLE_MASK_EXT = 1000455006,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT = 1000455007,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT = 1000455008,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT = 1000455009,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT = 1000455010,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT = 1000455011,
// Provided by VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT = 1000455012,
// Provided by VK_EXT_extended_dynamic_state3 with VK_KHR_maintenance2 or VK_VERSION_1_1
VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT = 1000455002,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_transform_feedback
VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT = 1000455013,
// Provided by VK_EXT_conservative_rasterization with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT = 1000455014,
// Provided by VK_EXT_conservative_rasterization with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT = 1000455015,
// Provided by VK_EXT_depth_clip_enable with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT = 1000455016,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_sample_locations
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT = 1000455017,
// Provided by VK_EXT_blend_operation_advanced with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT = 1000455018,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_provoking_vertex
VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT = 1000455019,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization
VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT = 1000455020,
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization
VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT = 1000455021,
// Provided by VK_EXT_depth_clip_control with VK_EXT_extended_dynamic_state3
VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT = 1000455022,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_clip_space_w_scaling
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV = 1000455023,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_viewport_swizzle
VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV = 1000455024,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_fragment_coverage_to_color
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV = 1000455025,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_fragment_coverage_to_color
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV = 1000455026,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples
VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV = 1000455027,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV = 1000455028,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV = 1000455029,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_shading_rate_image
VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV = 1000455030,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_representative_fragment_test
VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV = 1000455031,
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_coverage_reduction_mode
VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV = 1000455032,
// Provided by VK_EXT_attachment_feedback_loop_dynamic_state
VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT = 1000524000,
// Provided by VK_EXT_depth_clamp_control
VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT = 1000582000,
// Provided by VK_EXT_line_rasterization
VK_DYNAMIC_STATE_LINE_STIPPLE_EXT = VK_DYNAMIC_STATE_LINE_STIPPLE,
// 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,
// Provided by VK_KHR_line_rasterization
VK_DYNAMIC_STATE_LINE_STIPPLE_KHR = VK_DYNAMIC_STATE_LINE_STIPPLE,
} 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 any instance of VkDepthBiasRepresentationInfoEXT included in thepNextchain of VkPipelineRasterizationStateCreateInfo as well as thedepthBiasConstantFactor,depthBiasClampanddepthBiasSlopeFactorstates in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthBias or vkCmdSetDepthBias2EXT before any draws are performed with depth bias enabled. -
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 thepViewportWScalingsstate 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. -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXTspecifies that the presence of the VkPipelineDiscardRectangleStateCreateInfoEXT structure in the VkGraphicsPipelineCreateInfo chain with adiscardRectangleCountgreater than zero does not implicitly enable discard rectangles and they must be enabled dynamically with vkCmdSetDiscardRectangleEnableEXT before any draw commands. This is available on implementations that support at leastspecVersion2of theVK_EXT_discard_rectanglesextension. -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXTspecifies that thediscardRectangleModestate in VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDiscardRectangleModeEXT before any draw commands. This is available on implementations that support at leastspecVersion2of theVK_EXT_discard_rectanglesextension. -
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. -
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NVspecifies that the exclusive scissors must be explicitly enabled with vkCmdSetExclusiveScissorEnableNV and theexclusiveScissorCountvalue in VkPipelineViewportExclusiveScissorStateCreateInfoNV will not implicitly enable them. This is available on implementations that support at leastspecVersion2of theVK_NV_scissor_exclusiveextension. -
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_STIPPLEspecifies that thelineStippleFactorandlineStipplePatternstate in VkPipelineRasterizationLineStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLineStipple before any draws are performed with a pipeline state with VkPipelineRasterizationLineStateCreateInfo 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. -
VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXTspecifies that thedomainOriginstate in VkPipelineTessellationDomainOriginStateCreateInfo will be ignored and must be set dynamically with vkCmdSetTessellationDomainOriginEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXTspecifies that thedepthClampEnablestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetDepthClampEnableEXT before any draw call. -
VK_DYNAMIC_STATE_POLYGON_MODE_EXTspecifies that thepolygonModestate in VkPipelineRasterizationStateCreateInfo will be ignored and must be set dynamically with vkCmdSetPolygonModeEXT before any draw call. -
VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXTspecifies that therasterizationSamplesstate in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetRasterizationSamplesEXT before any draw call. -
VK_DYNAMIC_STATE_SAMPLE_MASK_EXTspecifies that thepSampleMaskstate in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetSampleMaskEXT before any draw call. -
VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXTspecifies that thealphaToCoverageEnablestate in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetAlphaToCoverageEnableEXT before any draw call. -
VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXTspecifies that thealphaToOneEnablestate in VkPipelineMultisampleStateCreateInfo will be ignored and must be set dynamically with vkCmdSetAlphaToOneEnableEXT before any draw call. -
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXTspecifies that thelogicOpEnablestate in VkPipelineColorBlendStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLogicOpEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXTspecifies that theblendEnablestate in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorBlendEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXTspecifies that thesrcColorBlendFactor,dstColorBlendFactor,colorBlendOp,srcAlphaBlendFactor,dstAlphaBlendFactor, andalphaBlendOpstates in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorBlendEquationEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXTspecifies that thecolorWriteMaskstate in VkPipelineColorBlendAttachmentState will be ignored and must be set dynamically with vkCmdSetColorWriteMaskEXT before any draw call. -
VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXTspecifies that therasterizationStreamstate in VkPipelineRasterizationStateStreamCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetRasterizationStreamEXT before any draw call. -
VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXTspecifies that theconservativeRasterizationModestate in VkPipelineRasterizationConservativeStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetConservativeRasterizationModeEXT before any draw call. -
VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXTspecifies that theextraPrimitiveOverestimationSizestate in VkPipelineRasterizationConservativeStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetExtraPrimitiveOverestimationSizeEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXTspecifies that thedepthClipEnablestate in VkPipelineRasterizationDepthClipStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClipEnableEXT before any draw call. -
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXTspecifies that thesampleLocationsEnablestate in VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetSampleLocationsEnableEXT before any draw call. -
VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXTspecifies that thecolorBlendOpstate in VkPipelineColorBlendAttachmentState, andsrcPremultiplied,dstPremultiplied, andblendOverlapstates in VkPipelineColorBlendAdvancedStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetColorBlendAdvancedEXT before any draw call. -
VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXTspecifies that theprovokingVertexModestate in VkPipelineRasterizationProvokingVertexStateCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetProvokingVertexModeEXT before any draw call. -
VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXTspecifies that thelineRasterizationModestate in VkPipelineRasterizationLineStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLineRasterizationModeEXT before any draw call. -
VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXTspecifies that thestippledLineEnablestate in VkPipelineRasterizationLineStateCreateInfo will be ignored and must be set dynamically with vkCmdSetLineStippleEnableEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXTspecifies that thenegativeOneToOnestate in VkPipelineViewportDepthClipControlCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClipNegativeOneToOneEXT before any draw call. -
VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXTspecifies that thedepthClampModeandpDepthClampRangestate in VkPipelineViewportDepthClampControlCreateInfoEXT will be ignored and must be set dynamically with vkCmdSetDepthClampRangeEXT before any draw call. -
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NVspecifies that theviewportWScalingEnablestate in VkPipelineViewportWScalingStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportWScalingEnableNV before any draw call. -
VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NVspecifies that theviewportCount, andpViewportSwizzlesstates in VkPipelineViewportSwizzleStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetViewportSwizzleNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NVspecifies that thecoverageToColorEnablestate in VkPipelineCoverageToColorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageToColorEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NVspecifies that thecoverageToColorLocationstate in VkPipelineCoverageToColorStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageToColorLocationNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NVspecifies that thecoverageModulationModestate in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationModeNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NVspecifies that thecoverageModulationTableEnablestate in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationTableEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NVspecifies that thecoverageModulationTableCount, andpCoverageModulationTablestates in VkPipelineCoverageModulationStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageModulationTableNV before any draw call. -
VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NVspecifies that theshadingRateImageEnablestate in VkPipelineViewportShadingRateImageStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetShadingRateImageEnableNV before any draw call. -
VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NVspecifies that therepresentativeFragmentTestEnablestate in VkPipelineRepresentativeFragmentTestStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetRepresentativeFragmentTestEnableNV before any draw call. -
VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NVspecifies that thecoverageReductionModestate in VkPipelineCoverageReductionStateCreateInfoNV will be ignored and must be set dynamically with vkCmdSetCoverageReductionModeNV before any draw call. -
VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXTspecifies that theVK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTandVK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTflags will be ignored and must be set dynamically with vkCmdSetAttachmentFeedbackLoopEnableEXT before any draw call.
10.3.1. Valid Combinations of Stages for Graphics Pipelines
Primitive processing can be handled either on a per primitive basis by the vertex, tessellation, and geometry shader stages, or on a per mesh basis using task and mesh shader stages. If the pipeline includes a mesh shader stage, it uses the mesh pipeline, otherwise it uses the primitive pipeline.
If a task shader is omitted, the task shading stage is skipped.
If tessellation shader stages are omitted, the tessellation shading and fixed-function stages of the pipeline are skipped.
If a geometry shader is omitted, the geometry shading stage is skipped.
If a fragment shader is omitted, fragment color outputs have undefined values, and the fragment depth value is determined by Fragment Operations state. This can be useful for depth-only rendering.
Presence of a shader stage in a pipeline is indicated by including a valid
VkPipelineShaderStageCreateInfo with module and pName
selecting an entry point from a shader module, where that entry point is
valid for the stage specified by stage.
Presence of some of the fixed-function stages in the pipeline is implicitly derived from enabled shaders and provided state. For example, the fixed-function tessellator is always present when the pipeline has valid Tessellation Control and Tessellation Evaluation shaders.
-
Depth/stencil-only rendering in a subpass with no color attachments
-
Active Pipeline Shader Stages
-
Vertex Shader
-
-
Required: Fixed-Function Pipeline Stages
-
-
Color-only rendering in a subpass with no depth/stencil attachment
-
Active Pipeline Shader Stages
-
Vertex Shader
-
Fragment Shader
-
-
Required: Fixed-Function Pipeline Stages
-
-
Rendering pipeline with tessellation and geometry shaders
-
Active Pipeline Shader Stages
-
Vertex Shader
-
Tessellation Control Shader
-
Tessellation Evaluation Shader
-
Geometry Shader
-
Fragment Shader
-
-
Required: Fixed-Function Pipeline Stages
-
-
Rendering pipeline with task and mesh shaders
-
Active Pipeline Shader Stages
-
Task Shader
-
Mesh Shader
-
Fragment Shader
-
-
Required: Fixed-Function Pipeline Stages
-
10.3.2. Graphics Pipeline Shader Groups
Graphics pipelines can contain multiple shader groups that can be bound
individually.
Each shader group behaves as if it was a pipeline using the shader group’s
state.
When the pipeline is bound by regular means, it behaves as if the state of
group 0 is active, use vkCmdBindPipelineShaderGroupNV to bind an
individual shader group.
The primary purpose of shader groups is allowing the device to bind different pipeline state using Device-Generated Commands.
The VkGraphicsPipelineShaderGroupsCreateInfoNV structure is defined
as:
// Provided by VK_NV_device_generated_commands
typedef struct VkGraphicsPipelineShaderGroupsCreateInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t groupCount;
const VkGraphicsShaderGroupCreateInfoNV* pGroups;
uint32_t pipelineCount;
const VkPipeline* pPipelines;
} VkGraphicsPipelineShaderGroupsCreateInfoNV;
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying 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.4. Ray Tracing Pipelines
Ray tracing pipelines consist of multiple shader stages, fixed-function traversal stages, and a pipeline layout.
VK_SHADER_UNUSED_KHR is a special shader index used to indicate that a
ray generation, miss, or callable shader member is not used.
#define VK_SHADER_UNUSED_KHR (~0U)
or the equivalent
#define VK_SHADER_UNUSED_NV VK_SHADER_UNUSED_KHR
To create ray tracing pipelines, call:
// Provided by VK_NV_ray_tracing
VkResult vkCreateRayTracingPipelinesNV(
VkDevice device,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkRayTracingPipelineCreateInfoNV* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
deviceis the logical device that creates the ray tracing pipelines. -
pipelineCacheis either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or to enable caching, the handle of a valid VkPipelineCache object. The implementation must not access this object outside of the duration of this 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.
Pipelines are created and returned as described for Multiple Pipeline Creation.
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 to enable caching, the handle of a valid VkPipelineCache object. The implementation must not access this object outside of the duration of this 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 reuse the shader group handles provided in
VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle
when
VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay
is enabled.
Pipelines are created and returned as described for Multiple Pipeline Creation.
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 a VkStructureType value identifying 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. If VkPhysicalDeviceProperties::apiVersionis greater than or equal to Vulkan 1.3 or VK_KHR_maintenance4 is enabledlayoutmust not be accessed outside of the duration of the command this structure is passed to. -
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 the pNext chain includes a VkPipelineCreateFlags2CreateInfo
structure, VkPipelineCreateFlags2CreateInfo::flags from that
structure is used instead of flags from this structure.
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 a VkStructureType value identifying 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. If VkPhysicalDeviceProperties::apiVersionis greater than or equal to Vulkan 1.3 or VK_KHR_maintenance4 is enabledlayoutmust not be accessed outside of the duration of the command this structure is passed to. -
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.
If the pNext chain includes a VkPipelineCreateFlags2CreateInfo
structure, VkPipelineCreateFlags2CreateInfo::flags from that
structure is used instead of flags from this structure.
If the pNext chain includes a
VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV
structure, then that structure controls whether cluster acceleration
structures are allowed in this ray tracing pipeline.
The VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV structure is defined as:
// Provided by VK_KHR_ray_tracing_pipeline with VK_NV_cluster_acceleration_structure
typedef struct VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV {
VkStructureType sType;
void* pNext;
VkBool32 allowClusterAccelerationStructure;
} VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
allowClusterAccelerationStructurecontrols if cluster acceleration structures are allowed in the ray tracing pipeline.
If no cluster acceleration structures are present in the ray tracing
pipeline, allowClusterAccelerationStructure should not be used to
prevent traversal penalty on some implementations.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 queried from vkGetRayTracingCaptureReplayShaderGroupHandlesKHR, as described in Ray Tracing Capture Replay. Ignored if VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayisVK_FALSE.
If the pipeline is created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and
the pipelineLibraryGroupHandles
feature is enabled, pShaderGroupCaptureReplayHandle is inherited by
all pipelines which link against this pipeline and remains bitwise identical
for any pipeline which references this pipeline library.
The VkRayTracingShaderGroupTypeKHR enumeration is defined as:
// 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_KHRspecifies that 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 that 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 that 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 a VkStructureType value identifying 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 size of the
block (in bytes) declared in the RayPayloadKHR or
IncomingRayPayloadKHR storage classes.
maxPipelineRayHitAttributeSize is calculated as the maximum size of
any block (in bytes) 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 an application-allocated buffer where the results will be written.
On success, an array of groupCount shader handles will be written to
pData, with each element being of size
VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleSize.
If pipeline was created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
and the pipelineLibraryGroupHandles
feature is enabled applications can query group handles from that pipeline,
even if the pipeline is a library and is never bound to a command buffer.
These group handles remain bitwise identical for any pipeline which
references the pipeline library.
Group indices are assigned as-if the pipeline was created without
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR.
To query the opaque capture data of shader groups in a ray tracing pipeline, call:
// Provided by VK_KHR_ray_tracing_pipeline
VkResult vkGetRayTracingCaptureReplayShaderGroupHandlesKHR(
VkDevice device,
VkPipeline pipeline,
uint32_t firstGroup,
uint32_t groupCount,
size_t dataSize,
void* pData);
-
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 an application-allocated buffer where the results will be written.
On success, an array of groupCount shader handles will be written to
pData, with each element being of size
VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleCaptureReplaySize.
Once queried, this opaque data can be provided at pipeline creation time
(in a subsequent execution), using
VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle,
as described in Ray Tracing Capture Replay.
If pipeline was created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
and the pipelineLibraryGroupHandles
feature is enabled applications can query capture replay group handles from
that pipeline.
The capture replay handle remains bitwise identical for any pipeline
which references the pipeline library.
Group indices are assigned as-if the pipeline was created without
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR.
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.5. 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.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, vkCreateDataGraphPipelinesARM, 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 a VkStructureType value identifying 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_KHR_maintenance8
VK_PIPELINE_CACHE_CREATE_INTERNALLY_SYNCHRONIZED_MERGE_BIT_KHR = 0x00000008,
// 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. -
VK_PIPELINE_CACHE_CREATE_INTERNALLY_SYNCHRONIZED_MERGE_BIT_KHRspecifies that when the created VkPipelineCache is used as thedstCacheparameter of vkMergePipelineCaches, it does not need to be externally synchronized. This flag is mutually exclusive withVK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT.
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 application
to the size of the buffer, in bytes, pointed to by pData, and on
return the variable is overwritten with the amount of data actually written
to pData.
If pDataSize is less than the maximum size that can be retrieved by
the pipeline cache, at most pDataSize bytes will be written to
pData, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all of the pipeline cache was
returned.
Any data written to pData is valid and can be provided as the
pInitialData member of the VkPipelineCacheCreateInfo structure
passed to vkCreatePipelineCache.
Two calls to vkGetPipelineCacheData with the same parameters must
retrieve the same data unless a command that modifies the contents of the
cache is called between them.
The initial bytes written to pData must be a header as described in
the Pipeline Cache Header section.
If pDataSize is less than what is necessary to store this header,
nothing will be written to pData and zero will be written to
pDataSize.
|
Note
|
This query does not behave consistently with the behavior described in Opaque Binary Data Results, for historical reasons. If the amount of data available is larger than the passed |
10.7.4. Pipeline Cache Header
Applications can store the data retrieved from the pipeline cache, and use these data, possibly in a future run of the application, to populate new pipeline cache objects. The results of pipeline compiles, however, may depend on the vendor ID, device ID, driver version, and other details of the device. To enable applications to detect when previously retrieved data is incompatible with the device, the pipeline cache data must begin with a valid pipeline cache header.
|
Note
|
Structures described in this section are not part of the Vulkan API and are only used to describe the representation of data elements in pipeline cache data. Accordingly, the valid usage clauses defined for structures defined in this section do not define valid usage conditions for APIs accepting pipeline cache data as input, as providing invalid pipeline cache data as input to any Vulkan API commands will result in the provided pipeline cache data being ignored. |
Version one of the pipeline cache header is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineCacheHeaderVersionOne {
uint32_t headerSize;
VkPipelineCacheHeaderVersion headerVersion;
uint32_t vendorID;
uint32_t deviceID;
uint8_t pipelineCacheUUID[VK_UUID_SIZE];
} VkPipelineCacheHeaderVersionOne;
-
headerSizeis the length in bytes of the pipeline cache header. -
headerVersionis a VkPipelineCacheHeaderVersion value specifying the version of the header. A consumer of the pipeline cache should use the cache version to interpret the remainder of the cache header.headerVersionmust be written as exactly 4 bytes. -
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, described by VkPipelineCacheHeaderVersionOne.
10.7.5. Destroying a Pipeline Cache
To destroy a pipeline cache, call:
// Provided by VK_VERSION_1_0
void vkDestroyPipelineCache(
VkDevice device,
VkPipelineCache pipelineCache,
const VkAllocationCallbacks* pAllocator);
-
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. Pipeline Binaries
Pipeline binary objects allow the result of pipeline construction to be
reused between pipelines and between runs of an application.
Reuse is achieved by extracting pipeline binaries from a VkPipeline
object, associating them with a corresponding VkPipelineBinaryKeyKHR
and then adding a VkPipelineBinaryInfoKHR to the pNext chain of
any Vk*PipelineCreateInfo when creating a pipeline.
Pipeline binaries can be reused between runs by extracting
VkPipelineBinaryDataKHR from VkPipelineBinaryKHR objects, saving
the contents, and then using them to create a VkPipelineBinaryKHR
object on subsequent runs.
When creating a pipeline that includes VkPipelineBinaryInfoKHR in the
pNext chain, or has the
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag set, the use of
VkPipelineCache objects is not allowed.
Pipeline binary objects are represented by VkPipelineBinaryKHR
handles:
// Provided by VK_KHR_pipeline_binary
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineBinaryKHR)
10.8.1. Generating the Pipeline Key
To generate the key for a particular pipeline creation info, call:
// Provided by VK_KHR_pipeline_binary
VkResult vkGetPipelineKeyKHR(
VkDevice device,
const VkPipelineCreateInfoKHR* pPipelineCreateInfo,
VkPipelineBinaryKeyKHR* pPipelineKey);
-
deviceis the logical device that creates the pipeline object. -
pPipelineCreateInfoisNULLor a pointer to a VkPipelineCreateInfoKHR structure. -
pPipelineKeyis a pointer to a VkPipelineBinaryKeyKHR structure in which the resulting key is returned.
If pPipelineCreateInfo is NULL, then the implementation must return
the global key that applies to all pipelines.
If the key obtained in this way changes between saving and restoring data
obtained from vkGetPipelineBinaryDataKHR in a different
VkDevice, then the application must assume that the restored data is
invalid and cannot be passed to vkCreatePipelineBinariesKHR.
Otherwise the application can assume the data is still valid.
If pPipelineCreateInfo is not NULL, the key obtained functions as a
method to compare two pipeline creation info structures.
Implementations may not compare parts of a pipeline creation info which
would not contribute to the final binary output.
If a shader module identifier is used instead of a shader module, the
pPipelineKey generated must be equal to the key generated when using
the shader module from which the identifier was queried.
If the content of two pPipelineKey are equal, pipelines created with
the two pPipelineCreateInfo->pNext create infos must produce the same
VkPipelineBinaryKHR contents.
The pipeline key is distinct from pipeline binary key. Pipeline binary keys can only be obtained after compilation. The pipeline key is intended to optionally allow associating pipeline create info with multiple pipeline binary keys.
The VkPipelineCreateInfoKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineCreateInfoKHR {
VkStructureType sType;
void* pNext;
} VkPipelineCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextis a pointer to a structure extending this structure.
The VkPipelineBinaryKeyKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryKeyKHR {
VkStructureType sType;
void* pNext;
uint32_t keySize;
uint8_t key[VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR];
} VkPipelineBinaryKeyKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
keySizeis the size, in bytes, of valid data returned inkey. -
keyis a buffer of opaque data specifying a pipeline binary key.
Any returned values beyond the first keySize bytes are undefined.
Implementations must return a keySize greater than 0, and
less-or-equal to VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR.
Two keys are considered equal if keySize is equal and the first
keySize bytes of key compare equal.
Implementations may return a different keySize for different
binaries.
Implementations should ensure that keySize is large enough to
uniquely identify a pipeline binary.
VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR is the length in bytes of a binary
key, as returned in VkPipelineBinaryKeyKHR::keySize.
#define VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR 32U
10.8.2. Creating Pipeline Binaries
To create pipeline binary objects, call:
// Provided by VK_KHR_pipeline_binary
VkResult vkCreatePipelineBinariesKHR(
VkDevice device,
const VkPipelineBinaryCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkPipelineBinaryHandlesInfoKHR* pBinaries);
-
deviceis the logical device that creates the pipeline binary objects. -
pCreateInfois a pointer to a VkPipelineBinaryCreateInfoKHR structure that contains the data to create the pipeline binaries from. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pBinariesis a pointer to a VkPipelineBinaryHandlesInfoKHR structure in which the resulting pipeline binaries are returned.
The implementation will attempt to create all pipeline binaries. If creation fails for any pipeline binary, then:
-
The corresponding entry in the
pPipelineBinariesoutput array will be filled with VK_NULL_HANDLE. -
The
VkResultreturned by vkCreatePipelineBinariesKHR will contain the error value for the first entry in the output array inpBinariescontaining VK_NULL_HANDLE.
The VkPipelineBinaryHandlesInfoKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryHandlesInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t pipelineBinaryCount;
VkPipelineBinaryKHR* pPipelineBinaries;
} VkPipelineBinaryHandlesInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBinaryCountis the number of binaries associated with this pipeline or the number of entries in thepPipelineBinariesarray. -
pPipelineBinariesisNULLor a pointer to an array of VkPipelineBinaryKHR handles in which the resulting pipeline binaries are returned.
If pPipelineBinaries is NULL, the number of binaries that would be
created is returned in pipelineBinaryCount.
Otherwise, pipelineBinaryCount must be the number of entries in the
pPipelineBinaries array, and on return from
vkCreatePipelineBinariesKHR pipelineBinaryCount is overwritten
with the number of handles actually written to pPipelineBinaries.
If the value of pipelineBinaryCount is less than the number of
binaries that would have been created, at most pipelineBinaryCount
handles will be written to pPipelineBinaries and VK_INCOMPLETE
will be returned instead of VK_SUCCESS, to indicate that
pPipelineBinaries was not large enough to create all the binaries.
The VkPipelineBinaryCreateInfoKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryCreateInfoKHR {
VkStructureType sType;
const void* pNext;
const VkPipelineBinaryKeysAndDataKHR* pKeysAndDataInfo;
VkPipeline pipeline;
const VkPipelineCreateInfoKHR* pPipelineCreateInfo;
} VkPipelineBinaryCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pKeysAndDataInfoisNULLor a pointer to a VkPipelineBinaryKeysAndDataKHR structure that contains keys and data to create the pipeline binaries from. -
pipelineis VK_NULL_HANDLE or aVkPipelinethat contains data to create the pipeline binaries from. -
pPipelineCreateInfoisNULLor a pointer to a VkPipelineCreateInfoKHR structure with the pipeline creation info. This is used to probe the implementation’s internal cache for pipeline binaries.
When pPipelineCreateInfo is not NULL, an implementation will attempt
to retrieve pipeline binary data from an internal cache external to the
application if
pipelineBinaryInternalCache is
VK_TRUE.
Applications can use this to determine if a pipeline can be created
without compilation.
If the implementation fails to create a pipeline binary due to missing an
internal cache entry, VK_PIPELINE_BINARY_MISSING_KHR is returned.
If creation succeeds, the resulting binary can be used to create a
pipeline.
VK_PIPELINE_BINARY_MISSING_KHR may be returned for any reason in this
situation, even if creating a pipeline binary with the same parameters that
succeeded earlier.
If
pipelineBinaryPrecompiledInternalCache
is VK_TRUE, the implementation may be able to create pipeline
binaries even when pPipelineCreateInfo has not been used to create
binaries before by the application.
|
Note
|
On some platforms, internal pipeline caches may be pre-populated before running the application. |
The VkPipelineBinaryKeysAndDataKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryKeysAndDataKHR {
uint32_t binaryCount;
const VkPipelineBinaryKeyKHR* pPipelineBinaryKeys;
const VkPipelineBinaryDataKHR* pPipelineBinaryData;
} VkPipelineBinaryKeysAndDataKHR;
-
binaryCountis the size of thepPipelineBinaryKeysandpPipelineBinaryDataarrays -
pPipelineBinaryKeysis a pointer to an array of VkPipelineBinaryKeyKHR structures containing the pipeline binary keys -
pPipelineBinaryDatais a pointer to an array of VkPipelineBinaryDataKHR structures containing the pipeline binary data
The VkPipelineBinaryDataKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryDataKHR {
size_t dataSize;
void* pData;
} VkPipelineBinaryDataKHR;
-
dataSizeis the size of thepDatabuffer in bytes. -
pDatais a pointer to a buffer ofsizebytes that contains pipeline binary data obtained fromvkGetPipelineBinaryDataKHR.
10.8.3. Retrieving Pipeline Binary Data
Data can be retrieved from a pipeline binary object using the command:
// Provided by VK_KHR_pipeline_binary
VkResult vkGetPipelineBinaryDataKHR(
VkDevice device,
const VkPipelineBinaryDataInfoKHR* pInfo,
VkPipelineBinaryKeyKHR* pPipelineBinaryKey,
size_t* pPipelineBinaryDataSize,
void* pPipelineBinaryData);
-
deviceis the logical device that created the pipeline binary. -
pInfois a pointer to a VkPipelineBinaryDataInfoKHR structure which describes the pipeline binary to get data from. -
pPipelineBinaryKeyis a pointer to a VkPipelineBinaryKeyKHR structure where the key for this binary will be written. -
pPipelineBinaryDataSizeis a pointer to asize_tvalue related to the amount of data in the pipeline binary, as described below. -
pPipelineBinaryDatais eitherNULLor a pointer to a buffer.
If pPipelineBinaryData is NULL, then the size of the data, in bytes,
that is required to store the binary is returned in
pPipelineBinaryDataSize.
Otherwise, pPipelineBinaryDataSize must contain the size of the
buffer, in bytes, pointed to by pPipelineBinaryData, and on return
pPipelineBinaryDataSize is overwritten with the size of the data, in
bytes, that is required to store the binary.
If pPipelineBinaryDataSize is less than the size that is required to
store the binary, nothing is written to pPipelineBinaryData and
VK_ERROR_NOT_ENOUGH_SPACE_KHR will be returned, instead of
VK_SUCCESS.
If the call returns one of the success return codes, the pipeline binary key
is written to pPipelineBinaryKey, regardless of whether
pPipelineBinaryData is NULL or not.
If pipelineBinaryCompressedData is
VK_FALSE, implementations should not return compressed pipeline
binary data to the application.
The VkPipelineBinaryDataInfoKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPipelineBinaryDataInfoKHR {
VkStructureType sType;
void* pNext;
VkPipelineBinaryKHR pipelineBinary;
} VkPipelineBinaryDataInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBinaryis the pipeline binary to get data from.
10.8.4. Releasing Captured Pipeline Binary Data
To release pipeline resources captured with
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR, call:
// Provided by VK_KHR_pipeline_binary
VkResult vkReleaseCapturedPipelineDataKHR(
VkDevice device,
const VkReleaseCapturedPipelineDataInfoKHR* pInfo,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that created the pipeline object. -
pInfois a pointer to a VkReleaseCapturedPipelineDataInfoKHR structure which describes the pipeline to release the data from. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
The implementation may free any resources captured as a result of creating
the pipeline with VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR and put
the pipeline into a state as if
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR had not been provided at
pipeline creation time.
|
Note
|
Any resources captured as a result of creating the pipeline with
|
The VkReleaseCapturedPipelineDataInfoKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkReleaseCapturedPipelineDataInfoKHR {
VkStructureType sType;
void* pNext;
VkPipeline pipeline;
} VkReleaseCapturedPipelineDataInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelinethe handle of the pipeline object to release the data from.
10.8.5. Destroying Pipeline Binaries
To destroy a VkPipelineBinaryKHR, call:
// Provided by VK_KHR_pipeline_binary
void vkDestroyPipelineBinaryKHR(
VkDevice device,
VkPipelineBinaryKHR pipelineBinary,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that created the pipeline binary object. -
pipelineBinaryis the handle of the pipeline binary object to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
10.9. Specialization Constants
Specialization constants are a mechanism whereby constants in a SPIR-V
module can have their constant value specified at the time the
VkPipeline is created.
This allows a SPIR-V module to have constants that can be modified while
executing an application that uses the Vulkan API.
|
Note
|
Specialization constants are useful to allow a compute shader to have its local workgroup size changed at runtime by the user, for example. |
Each VkPipelineShaderStageCreateInfo structure contains a
pSpecializationInfo member, which can be NULL to indicate no
specialization constants, or point to a VkSpecializationInfo
structure.
The VkSpecializationInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSpecializationInfo {
uint32_t mapEntryCount;
const VkSpecializationMapEntry* pMapEntries;
size_t dataSize;
const void* pData;
} VkSpecializationInfo;
-
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 and z elements of the WorkgroupSize vector.
Now to specialize the above via the specialization constants mechanism:
const VkSpecializationMapEntry entries[] =
{
{
.constantID = 13,
.offset = 0 * sizeof(uint32_t),
.size = sizeof(uint32_t)
},
{
.constantID = 42,
.offset = 1 * sizeof(uint32_t),
.size = sizeof(uint32_t)
},
{
.constantID = 3,
.offset = 2 * sizeof(uint32_t),
.size = sizeof(uint32_t)
}
};
const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4
const VkSpecializationInfo info =
{
.mapEntryCount = 3,
.pMapEntries = entries,
.dataSize = 3 * sizeof(uint32_t),
.pData = data,
};
Then when calling vkCreateComputePipelines, and passing the
VkSpecializationInfo we defined as the pSpecializationInfo
parameter of VkPipelineShaderStageCreateInfo, we will create a compute
pipeline with the runtime specified local workgroup size.
Another example would be that an application has a SPIR-V module that has some platform-dependent constants they wish to use.
In human readable SPIR-V:
OpDecorate %1 SpecId 0 ; decorate our signed 32-bit integer constant
OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant
%i32 = OpTypeInt 32 1 ; declare a signed 32-bit type
%float = OpTypeFloat 32 ; declare a 32-bit floating-point type
%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant
%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant
From the above we have two specialization constants, one is a signed 32-bit integer and the second is a 32-bit floating-point value.
Now to specialize the above via the specialization constants mechanism:
struct SpecializationData {
int32_t data0;
float data1;
};
const VkSpecializationMapEntry entries[] =
{
{
.constantID = 0,
.offset = offsetof(SpecializationData, data0),
.size = sizeof(SpecializationData::data0)
},
{
.constantID = 12,
.offset = offsetof(SpecializationData, data1),
.size = sizeof(SpecializationData::data1)
}
};
SpecializationData data;
data.data0 = -42; // set the data for the 32-bit integer
data.data1 = 42.0f; // set the data for the 32-bit floating-point
const VkSpecializationInfo info =
{
.mapEntryCount = 2,
.pMapEntries = entries,
.dataSize = sizeof(data),
.pdata = &data,
};
It is legal for a SPIR-V module with specializations to be compiled into a pipeline where no specialization information was provided. SPIR-V specialization constants contain default values such that if a specialization is not provided, the default value will be used. In the examples above, it would be valid for an application to only specialize some of the specialization constants within the SPIR-V module, and let the other constants use their default values encoded within the OpSpecConstant declarations.
10.10. Pipeline Libraries
A pipeline library is a special pipeline that was created using the
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and cannot be bound, instead it
defines a set of pipeline state which can be linked into other pipelines.
For ray tracing pipelines this includes shaders and shader groups.
For graphics pipelines this includes distinct library types defined by
VkGraphicsPipelineLibraryFlagBitsEXT.
The application must maintain the lifetime of a pipeline library based on
the pipelines that link with it.
This linkage is achieved by using the following structure within the appropriate creation mechanisms:
The VkPipelineLibraryCreateInfoKHR structure is defined as:
// Provided by VK_KHR_pipeline_library
typedef struct VkPipelineLibraryCreateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t libraryCount;
const VkPipeline* pLibraries;
} VkPipelineLibraryCreateInfoKHR;
-
sTypeis a VkStructureType value identifying 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.11. Pipeline Binding
Once a pipeline has been created, it can be bound to the command buffer using the command:
// Provided by VK_VERSION_1_0
void vkCmdBindPipeline(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipeline pipeline);
-
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, or until the pipeline bind point is disturbed by binding a shader object as described in Interaction with Pipelines. Commands that do not interact with the given pipeline type must not be affected by the pipeline state.
Possible values of vkCmdBindPipeline::pipelineBindPoint,
specifying the bind point of a pipeline object, are:
// Provided by VK_VERSION_1_0
typedef enum VkPipelineBindPoint {
VK_PIPELINE_BIND_POINT_GRAPHICS = 0,
VK_PIPELINE_BIND_POINT_COMPUTE = 1,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue
VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDX = 1000134000,
#endif
// Provided by VK_KHR_ray_tracing_pipeline
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR = 1000165000,
// Provided by VK_HUAWEI_subpass_shading
VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI = 1000369003,
// Provided by VK_ARM_data_graph
VK_PIPELINE_BIND_POINT_DATA_GRAPH_ARM = 1000507000,
// 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. -
VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDXspecifies binding as an execution graph pipeline.
For pipelines that were created with the support of multiple shader groups
(see Graphics Pipeline Shader Groups), the regular
vkCmdBindPipeline command will bind Shader Group 0.
To explicitly bind a shader group use:
// Provided by VK_NV_device_generated_commands
void vkCmdBindPipelineShaderGroupNV(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipeline pipeline,
uint32_t groupIndex);
-
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.1. Interaction With Shader Objects
If the shaderObject feature is enabled,
applications can use both pipelines and shader objects
at the same time.
The interaction between pipelines and shader objects is described in
Interaction with Pipelines.
10.12. Dynamic State
When a pipeline object is bound, any pipeline object state that is not specified as dynamic is applied to the command buffer state. Pipeline object state that is specified as dynamic is not applied to the command buffer state at this time.
Instead, dynamic state can be modified at any time and persists for the lifetime of the command buffer, or until modified by another dynamic state setting command, or made invalid by binding a pipeline in which that state is statically specified.
If the commandBufferInheritance
feature is enabled, all valid state from the previously executed command
buffer in the queue is inherited into the next command buffer executed in
the same queue.
This inherited state does not need to be set again before draw or dispatch
commands.
When a pipeline object is bound, the following applies to each state parameter:
-
If the state is not specified as dynamic in the new pipeline object, then that command buffer state is overwritten by the state in the new pipeline object. Before any draw or dispatch call with this pipeline there must not have been any calls to any of the corresponding dynamic state setting commands after this pipeline was bound.
-
If the state is specified as dynamic in the new pipeline object, then that command buffer state is not disturbed. Before any draw or dispatch call with this pipeline there must have been at least one call to each of the corresponding dynamic state setting commands. The state-setting commands must be recorded after command buffer recording was begun, or after the last command binding a pipeline object with that state specified as static, whichever was the latter.
-
If the state is not included (corresponding pointer in VkGraphicsPipelineCreateInfo was
NULLor was ignored) in the new pipeline object, then that command buffer state is not disturbed. For example, mesh shading pipelines do not include vertex input state and therefore do not disturb any such command buffer state.
Dynamic state that does not affect the result of operations can be left undefined.
|
Note
|
For example, if blending is disabled by the pipeline object state then the dynamic color blend constants do not need to be specified in the command buffer, even if this state is specified as dynamic in the pipeline object. |
|
Note
|
Applications running on Vulkan implementations advertising a
VkPhysicalDeviceDriverProperties:: |
10.13. Pipeline Properties and Shader Information
When a pipeline is created, its state and shaders are compiled into zero or more device-specific executables, which are used when executing commands against that pipeline. To query the properties of these pipeline executables, call:
// Provided by VK_KHR_pipeline_executable_properties
VkResult vkGetPipelineExecutablePropertiesKHR(
VkDevice device,
const VkPipelineInfoKHR* pPipelineInfo,
uint32_t* pExecutableCount,
VkPipelineExecutablePropertiesKHR* pProperties);
-
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
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If pExecutableCount is less than the number of pipeline executables
associated with the pipeline, at most pExecutableCount structures will
be written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available properties were
returned.
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 a VkStructureType value identifying 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this 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 a VkStructureType value identifying 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
application to the number of elements in the pStatistics array, and on
return the variable is overwritten with the number of structures actually
written to pStatistics.
If pStatisticCount is less than the number of statistics associated
with the pipeline executable, at most pStatisticCount structures will
be written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available statistics were
returned.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 application to the number of elements in the
pInternalRepresentations array, and on return the variable is
overwritten with the number of structures actually written to
pInternalRepresentations.
If pInternalRepresentationCount is less than the number of internal
representations associated with the pipeline executable, at most
pInternalRepresentationCount structures will be written, and
VK_INCOMPLETE will be returned instead of VK_SUCCESS, to
indicate that not all the available representations were returned.
While the details of the internal representations remain implementation-dependent, the implementation should order the internal representations in the order in which they occur in the compiled pipeline with the final shader assembly (if any) last.
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 a VkStructureType value identifying 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 application
to the size of the buffer, in bytes, pointed to by pInfo, and on
return the variable is overwritten with the amount of data actually written
to pInfo.
If pInfoSize is less than the maximum size that can be retrieved by
the pipeline cache, then at most pInfoSize bytes will be written to
pInfo, and VK_INCOMPLETE will be returned, instead of
VK_SUCCESS, to indicate that not all required of the pipeline cache
was returned.
Not all information is available for every shader and implementations may
not support all kinds of information for any shader.
When a certain type of information is unavailable, the function returns
VK_ERROR_FEATURE_NOT_PRESENT.
If information is successfully and fully queried, the function will return
VK_SUCCESS.
For infoType VK_SHADER_INFO_TYPE_STATISTICS_AMD, a
VkShaderStatisticsInfoAMD structure will be written to the buffer
pointed to by pInfo.
This structure will be populated with statistics regarding the physical
device resources used by that shader along with other miscellaneous
information and is described in further detail below.
For infoType VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD, pInfo is
a pointer to a null-terminated UTF-8 string containing human-readable
disassembly.
The exact formatting and contents of the disassembly string are
vendor-specific.
The formatting and contents of all other types of information, including
infoType VK_SHADER_INFO_TYPE_BINARY_AMD, are left to the vendor
and are not further specified by this extension.
|
Note
|
This query does not behave consistently with the behavior described in Opaque Binary Data Results, for historical reasons. If the amount of data available is larger than the passed |
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 disassembly of a shader.
The VkShaderStatisticsInfoAMD structure is defined as:
// Provided by VK_AMD_shader_info
typedef struct VkShaderStatisticsInfoAMD {
VkShaderStageFlags shaderStageMask;
VkShaderResourceUsageAMD resourceUsage;
uint32_t numPhysicalVgprs;
uint32_t numPhysicalSgprs;
uint32_t numAvailableVgprs;
uint32_t numAvailableSgprs;
uint32_t computeWorkGroupSize[3];
} VkShaderStatisticsInfoAMD;
-
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.14. Pipeline Compiler Control
The compilation of a pipeline can be tuned by adding a
VkPipelineCompilerControlCreateInfoAMD structure to the pNext
chain of VkGraphicsPipelineCreateInfo or
VkComputePipelineCreateInfo.
// Provided by VK_AMD_pipeline_compiler_control
typedef struct VkPipelineCompilerControlCreateInfoAMD {
VkStructureType sType;
const void* pNext;
VkPipelineCompilerControlFlagsAMD compilerControlFlags;
} VkPipelineCompilerControlCreateInfoAMD;
-
sTypeis a VkStructureType value identifying 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.15. Pipeline Creation Feedback
Feedback about the creation of a particular pipeline object can be obtained
by adding a VkPipelineCreationFeedbackCreateInfo structure to the
pNext chain of VkGraphicsPipelineCreateInfo,
VkRayTracingPipelineCreateInfoKHR,
VkRayTracingPipelineCreateInfoNV,
VkDataGraphPipelineCreateInfoARM,
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 a VkStructureType value identifying 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,
// Provided by VK_EXT_pipeline_creation_feedback
VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT,
// Provided by VK_EXT_pipeline_creation_feedback
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT,
// Provided by VK_EXT_pipeline_creation_feedback
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_BITspecifies that the feedback information is valid. -
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BITspecifies 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, vkCreateDataGraphPipelinesARM, 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_BITspecifies 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.
If the reallocation was successful, pfnReallocation must return an
allocation with enough space for size bytes, and the contents of the
original allocation from bytes zero to min(original size, new size) -
1 must be preserved in the returned allocation.
If size is larger than the old size, the contents of the additional
space are undefined.
If satisfying these requirements involves creating a new allocation, then
the old allocation should be freed.
If pOriginal is NULL, then pfnReallocation must behave
equivalently to a call to PFN_vkAllocationFunction with the same
parameter values (without pOriginal).
If size is zero, then pfnReallocation must behave equivalently
to a call to PFN_vkFreeFunction with the same pUserData
parameter value, and pMemory equal to pOriginal.
If pOriginal is non-NULL, the implementation must ensure that
alignment is equal to the alignment used to originally allocate
pOriginal.
If this function fails and pOriginal is non-NULL the application
must not free the old allocation.
pfnReallocation must follow the same
rules for return values as
PFN_vkAllocationFunction.
The type of pfnFree is:
// Provided by VK_VERSION_1_0
typedef void (VKAPI_PTR *PFN_vkFreeFunction)(
void* pUserData,
void* pMemory);
-
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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.1. See Deprecated Functionality for more information. |
// 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.
Memory contents within a tile memory heap, denoted by
VK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOM, are only visible across the
command buffers executed in a single command buffer submission batch within
a vkQueueSubmit or vkQueueSubmit2 call.
If the
VkPhysicalDeviceTileMemoryHeapPropertiesQCOM::queueSubmitBoundary
property is set, the visibility is extended across all batches in the submit
call.
Memory contents are discarded and made undefined after the respective
submission batch or submit call.
Tile memory may have different performance characteristics than non tile
memory.
Tile memory can be used simultaneously by command buffers in other queues
without invalidating each others contents.
Collectively, these rules define the tile memory scope.
|
Note
|
Tile memory heaps work differently than most heaps as it is allowing addressing on device cache memory. Therefore, the heap’s address space is aliased across the different queues, with each queue retaining its individual copy of the heap. The implementation takes care of any required saving and restoring of the tile memory contents. Effectively, this means that the same address in the heap in different queues have simultaneously different defined contents and the contents has a lifespan scoped to the submit or batch for that specific queues. |
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 a VkStructureType value identifying 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_QCOM_tile_memory_heap
VK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOM = 0x00000008,
// 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. -
VK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOMbit specifies that the heap corresponds to tile memory.
// 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 type, are:
// Provided by VK_VERSION_1_0
typedef enum VkMemoryPropertyFlagBits {
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT = 0x00000001,
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT = 0x00000002,
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT = 0x00000004,
VK_MEMORY_PROPERTY_HOST_CACHED_BIT = 0x00000008,
VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT = 0x00000010,
// Provided by VK_VERSION_1_1
VK_MEMORY_PROPERTY_PROTECTED_BIT = 0x00000020,
// Provided by VK_AMD_device_coherent_memory
VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD = 0x00000040,
// Provided by VK_AMD_device_coherent_memory
VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD = 0x00000080,
// Provided by VK_NV_external_memory_rdma
VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV = 0x00000100,
} VkMemoryPropertyFlagBits;
-
VK_MEMORY_PROPERTY_DEVICE_LOCAL_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 manage availability and visibility on the host. -
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 on the device. If paired withVK_MEMORY_PROPERTY_HOST_COHERENT_BIT, memory domain operations are also performed automatically between host and device. -
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 neighboring memory locations over a short time period (e.g. within a frame) may be slower than it would be for the equivalent cached memory type. As such, it is generally inadvisable to use device coherent or device uncached memory except when really needed. |
// Provided by VK_VERSION_1_0
typedef VkFlags VkMemoryPropertyFlags;
VkMemoryPropertyFlags is a bitmask type for setting a mask of zero or
more VkMemoryPropertyFlagBits.
If the VkPhysicalDeviceMemoryBudgetPropertiesEXT structure is included
in the pNext chain of VkPhysicalDeviceMemoryProperties2, it is
filled with the current memory budgets and usages.
The VkPhysicalDeviceMemoryBudgetPropertiesEXT structure is defined as:
// Provided by VK_EXT_memory_budget
typedef struct VkPhysicalDeviceMemoryBudgetPropertiesEXT {
VkStructureType sType;
void* pNext;
VkDeviceSize heapBudget[VK_MAX_MEMORY_HEAPS];
VkDeviceSize heapUsage[VK_MAX_MEMORY_HEAPS];
} VkPhysicalDeviceMemoryBudgetPropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
heapBudgetis an array ofVK_MAX_MEMORY_HEAPSVkDeviceSize values in which memory budgets are returned, with one element for each memory heap. A heap’s budget is a rough estimate of how much memory the process can allocate from that heap before allocations may fail or cause performance degradation. The budget includes any currently allocated device memory. -
heapUsageis an array ofVK_MAX_MEMORY_HEAPSVkDeviceSize values in which memory usages are returned, with one element for each memory heap. A heap’s usage is an estimate of how much memory the process is currently using in that heap.
The values returned in this structure are not invariant.
The heapBudget and heapUsage values must be zero for array
elements greater than or equal to
VkPhysicalDeviceMemoryProperties::memoryHeapCount.
The heapBudget value must be non-zero for array elements less than
VkPhysicalDeviceMemoryProperties::memoryHeapCount.
The heapBudget value must be less than or equal to
VkMemoryHeap::size for each heap.
11.2.2. Device Memory Objects
A Vulkan device operates on data in device memory via memory objects that
are represented in the API by a VkDeviceMemory handle:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDeviceMemory)
11.2.3. Device Memory Allocation
To allocate memory objects, call:
// Provided by VK_VERSION_1_0
VkResult vkAllocateMemory(
VkDevice device,
const VkMemoryAllocateInfo* pAllocateInfo,
const VkAllocationCallbacks* pAllocator,
VkDeviceMemory* pMemory);
-
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 memoryTypeIndex belongs to a heap with the
VK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOM bit included in its properties,
this allocation is backed by tile memory, which is an on device cache.
Unlike other heaps, allocations out of the tile memory will always have a
starting address at the start of the heap and its contents are aliased with
all other VkDeviceMemory objects bound to the same range while
executing within the same tile memory scope.
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 a VkStructureType value identifying 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 -
VkImportScreenBufferInfoQNX with a non-
NULLbuffervalue -
VkImportMemoryMetalHandleInfoEXT 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.
If the parameters define an import operation and the external handle type is
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT,
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:
-
VkPhysicalDeviceLimits::
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
application 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 a VkStructureType value identifying 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.
To bind a range of tile memory to the command buffer, call:
// Provided by VK_QCOM_tile_memory_heap
void vkCmdBindTileMemoryQCOM(
VkCommandBuffer commandBuffer,
const VkTileMemoryBindInfoQCOM* pTileMemoryBindInfo);
-
commandBufferis the command buffer that the tile memory will be bound to. -
pTileMemoryBindInfois VK_NULL_HANDLE or a pointer to a VkTileMemoryBindInfoQCOM structure defining how tile memory is bound.
Calling vkCmdBindTileMemoryQCOM when pTileMemoryBindInfo is
VK_NULL_HANDLE is equivalent to binding no tile memory to the command
buffer.
The VkTileMemoryBindInfoQCOM structure is defined as:
// Provided by VK_QCOM_tile_memory_heap
typedef struct VkTileMemoryBindInfoQCOM {
VkStructureType sType;
const void* pNext;
VkDeviceMemory memory;
} VkTileMemoryBindInfoQCOM;
-
memoryis the tile memory object to be bound.
memory is used to bind this memory object to tile memory for all
subsequent commands in the commandBuffer.
Tile memory contents for ranges in the heap outside the bound memory
are discarded and become undefined for the active
tile memory scope if an action command is executed.
For secondary command buffers executing within a render pass instance, the
active bound tile memory object is provided with this structure included in
the pNext chain of VkCommandBufferInheritanceInfo.
If this structure was not specified since recording started for
commandBuffer, no tile memory is bound to the command buffer and all
contents become undefined for the tile memory scope if an action command
is executed.
If the pNext chain includes a
VkMemoryDedicatedAllocateInfoTensorARM structure, then that structure
includes a handle of the sole tensor resource that the memory can be bound
to.
The VkMemoryDedicatedAllocateInfoTensorARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkMemoryDedicatedAllocateInfoTensorARM {
VkStructureType sType;
const void* pNext;
VkTensorARM tensor;
} VkMemoryDedicatedAllocateInfoTensorARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensoris a handle of a tensor 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 it is included but pAttributes is set to NULL, default
security descriptor values will be used, and child processes created by the
application will not inherit the handle, as described in the MSDN
documentation for “Synchronization Object Security and Access Rights”1.
Further, if the structure is not present, the access rights used depend on
the handle type.
For handles of the following types:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT
The implementation must ensure the access rights allow read and write access to the memory.
To import memory from a Windows handle, add a
VkImportMemoryWin32HandleInfoKHR structure to the pNext chain of
the VkMemoryAllocateInfo structure.
The VkImportMemoryWin32HandleInfoKHR structure is defined as:
// Provided by VK_KHR_external_memory_win32
typedef struct VkImportMemoryWin32HandleInfoKHR {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlagBits handleType;
HANDLE handle;
LPCWSTR name;
} VkImportMemoryWin32HandleInfoKHR;
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 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 a VkStructureType value identifying 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().
// 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. -
pHandleis 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
Implementations may support importing host pointers for memory types which
are not host-visible.
In this case, after a successful call to vkAllocateMemory, the memory
range imported from pHostPointer must not be accessed by the
application until the VkDeviceMemory has been destroyed.
Memory contents for the host memory becomes undefined on import, and is
left undefined after the VkDeviceMemory has been destroyed.
Applications must also not access host memory which is mapped to the same
physical memory as pHostPointer, but mapped to a different host
pointer while the VkDeviceMemory handle is valid.
Implementations running on general-purpose operating systems should not
support importing host pointers for memory types which are not host-visible.
|
Note
|
Using host pointers to back non-host visible allocations is a platform-specific use case, and applications should not attempt to do this unless instructed by the platform. |
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 a VkStructureType value identifying 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 should only include bits that
identify memory types which are host visible.
Implementations may include bits that identify memory types which are not
host visible.
Behavior for imported pointers of such types is defined by
VkImportMemoryHostPointerInfoEXT.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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_ANDROID_external_memory_android_hardware_buffer with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
typedef struct VkAndroidHardwareBufferFormatProperties2ANDROID {
VkStructureType sType;
void* pNext;
VkFormat format;
uint64_t externalFormat;
VkFormatFeatureFlags2 formatFeatures;
VkComponentMapping samplerYcbcrConversionComponents;
VkSamplerYcbcrModelConversion suggestedYcbcrModel;
VkSamplerYcbcrRange suggestedYcbcrRange;
VkChromaLocation suggestedXChromaOffset;
VkChromaLocation suggestedYChromaOffset;
} VkAndroidHardwareBufferFormatProperties2ANDROID;
-
sTypeis a VkStructureType value identifying 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.
The VkAndroidHardwareBufferFormatResolvePropertiesANDROID structure is defined as:
// Provided by VK_ANDROID_external_format_resolve
typedef struct VkAndroidHardwareBufferFormatResolvePropertiesANDROID {
VkStructureType sType;
void* pNext;
VkFormat colorAttachmentFormat;
} VkAndroidHardwareBufferFormatResolvePropertiesANDROID;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
colorAttachmentFormatis a VkFormat specifying the format of color attachment images that must be used for color attachments when resolving to the specified external format. If the implementation supports external format resolves for the specified external format, this value will be a color format supporting theVK_FORMAT_FEATURE_COLOR_ATTACHMENT_BITin VkFormatProperties::optimalTilingFeaturesas returned by vkGetPhysicalDeviceFormatProperties withformatequal tocolorAttachmentFormatIf external format resolves are not supported, this value will beVK_FORMAT_UNDEFINED.
Any Android hardware buffer created with the GRALLOC_USAGE_HW_RENDER
flag must be renderable in some way in Vulkan, either:
-
VkAndroidHardwareBufferFormatPropertiesANDROID::
formatmust be a format that supportsVK_FORMAT_FEATURE_COLOR_ATTACHMENT_BITorVK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BITin VkFormatProperties::optimalTilingFeatures; or -
colorAttachmentFormatmust be a format that supportsVK_FORMAT_FEATURE_COLOR_ATTACHMENT_BITin VkFormatProperties::optimalTilingFeatures.
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. -
pAddressis a pointer to a VkRemoteAddressNV value in which an address representing the payload of the device memory object is returned.
More communication may be required between the kernel-mode drivers of the devices involved. This information is out of scope of this documentation and should be requested from the vendors of the devices.
The VkMemoryGetRemoteAddressInfoNV structure is defined as:
// Provided by VK_NV_external_memory_rdma
typedef struct VkMemoryGetRemoteAddressInfoNV {
VkStructureType sType;
const void* pNext;
VkDeviceMemory memory;
VkExternalMemoryHandleTypeFlagBits handleType;
} VkMemoryGetRemoteAddressInfoNV;
-
sTypeis a VkStructureType value identifying 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.
VkRemoteAddressNV represents an address of a memory object
accessible by remote devices, as returned in
vkGetMemoryRemoteAddressNV::pAddress.
// Provided by VK_NV_external_memory_rdma
typedef void* VkRemoteAddressNV;
11.2.9. Fuchsia External Memory
On Fuchsia, when allocating memory that may be imported from another
device, process or Vulkan instance, add a
VkImportMemoryZirconHandleInfoFUCHSIA structure to the pNext
chain of the VkMemoryAllocateInfo structure.
External memory on Fuchsia is imported and exported using VMO handles of
type zx_handle_t.
VMO handles to external memory are canonically obtained from Fuchsia’s
Sysmem service or from syscalls such as zx_vmo_create().
VMO handles for import can also be obtained by exporting them from another
Vulkan instance as described in exporting
fuchsia device memory.
Importing VMO handles to the Vulkan instance transfers ownership of the handle to the instance from the application. The application must not perform any operations on the handle after successful import.
Applications can import the same underlying memory into multiple instances
of Vulkan, into the same instance from which it was exported, and multiple
times into a given Vulkan instance.
In all cases, each import operation must create a distinct
VkDeviceMemory object.
Importing Fuchsia External Memory
The VkImportMemoryZirconHandleInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_external_memory
typedef struct VkImportMemoryZirconHandleInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlagBits handleType;
zx_handle_t handle;
} VkImportMemoryZirconHandleInfoFUCHSIA;
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying 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, retrieve the handle to the VkDeviceMemory using the command:
// Provided by VK_FUCHSIA_external_memory
VkResult vkGetMemoryZirconHandleFUCHSIA(
VkDevice device,
const VkMemoryGetZirconHandleInfoFUCHSIA* pGetZirconHandleInfo,
zx_handle_t* pZirconHandle);
-
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 a VkStructureType value identifying 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 application must first
indicate the intention to do so during the creation of the Vulkan object, by
including one or more VkExportMetalObjectCreateInfoEXT structures in
the pNext chain of the VkInstanceCreateInfo,
VkMemoryAllocateInfo, VkImageCreateInfo,
VkImageViewCreateInfo, VkBufferViewCreateInfo,
VkSemaphoreCreateInfo, or VkEventCreateInfo, in the
corresponding Vulkan object creation command.
The VkExportMetalObjectCreateInfoEXT structure is defined as:
// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalObjectCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkExportMetalObjectTypeFlagBitsEXT exportObjectType;
} VkExportMetalObjectCreateInfoEXT;
-
sTypeis a VkStructureType value identifying 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_EXTspecifies that a MetalMTLDevicemay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_COMMAND_QUEUE_BIT_EXTspecifies that a MetalMTLCommandQueuemay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXTspecifies that a MetalMTLBuffermay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXTspecifies that a MetalMTLTexturemay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_IOSURFACE_BIT_EXTspecifies that a MetalIOSurfacemay be exported. -
VK_EXPORT_METAL_OBJECT_TYPE_METAL_SHARED_EVENT_BIT_EXTspecifies that 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 __unsafe_unretained id<MTLDevice> MTLDevice_id;
#else
typedef void* MTLDevice_id;
#endif
To export the Metal MTLCommandQueue object underlying a VkQueue
object, include a VkExportMetalCommandQueueInfoEXT structure in the
pNext chain of the pMetalObjectsInfo parameter of a
vkExportMetalObjectsEXT call.
The VkExportMetalCommandQueueInfoEXT structure is defined as:
// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalCommandQueueInfoEXT {
VkStructureType sType;
const void* pNext;
VkQueue queue;
MTLCommandQueue_id mtlCommandQueue;
} VkExportMetalCommandQueueInfoEXT;
-
sTypeis a VkStructureType value identifying 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 __unsafe_unretained id<MTLCommandQueue> MTLCommandQueue_id;
#else
typedef void* MTLCommandQueue_id;
#endif
To export the Metal MTLBuffer object underlying a VkDeviceMemory
object, include a VkExportMetalBufferInfoEXT structure in the
pNext chain of the pMetalObjectsInfo parameter of a
vkExportMetalObjectsEXT call.
The VkExportMetalBufferInfoEXT structure is defined as:
// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalBufferInfoEXT {
VkStructureType sType;
const void* pNext;
VkDeviceMemory memory;
MTLBuffer_id mtlBuffer;
} VkExportMetalBufferInfoEXT;
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
mtlBufferis the Metalid<MTLBuffer>object that is to underlie the VkDeviceMemory.
The application must ensure that the configuration of the id<MTLBuffer>
object is compatible with the configuration of the VkDeviceMemory.
Failure to do so results in undefined behavior.
The type id<MTLBuffer> is defined in Apple’s Metal framework, but to
remove an unnecessary compile time dependency, an incomplete type definition
of MTLBuffer_id is provided in the Vulkan headers:
// Provided by VK_EXT_metal_objects
#ifdef __OBJC__
@protocol MTLBuffer;
typedef __unsafe_unretained id<MTLBuffer> MTLBuffer_id;
#else
typedef void* MTLBuffer_id;
#endif
To export a Metal MTLTexture object underlying a VkImage,
VkImageView, or VkBufferView object, include a
VkExportMetalTextureInfoEXT structure in the pNext chain of the
pMetalObjectsInfo parameter of a vkExportMetalObjectsEXT call.
The VkExportMetalTextureInfoEXT structure is defined as:
// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalTextureInfoEXT {
VkStructureType sType;
const void* pNext;
VkImage image;
VkImageView imageView;
VkBufferView bufferView;
VkImageAspectFlagBits plane;
MTLTexture_id mtlTexture;
} VkExportMetalTextureInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis VK_NULL_HANDLE or a VkImage. -
imageViewis VK_NULL_HANDLE or a VkImageView. -
bufferViewis VK_NULL_HANDLE or a VkBufferView. -
planespecifies 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;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
planespecifies the plane of the VkImage that theid<MTLTexture>object should be attached to. -
mtlTextureis a the Metalid<MTLTexture>object that is to underlie the VkImage plane.
The type id<MTLTexture> is defined in Apple’s Metal framework, but to
remove an unnecessary compile time dependency, an incomplete type definition
of MTLTexture_id is provided in the Vulkan headers:
// Provided by VK_EXT_metal_objects
#ifdef __OBJC__
@protocol MTLTexture;
typedef __unsafe_unretained id<MTLTexture> MTLTexture_id;
#else
typedef void* MTLTexture_id;
#endif
To export the Metal IOSurfaceRef object underlying a VkImage
object, include a VkExportMetalIOSurfaceInfoEXT structure in the
pNext chain of the pMetalObjectsInfo parameter of a
vkExportMetalObjectsEXT call.
The VkExportMetalIOSurfaceInfoEXT structure is defined as:
// Provided by VK_EXT_metal_objects
typedef struct VkExportMetalIOSurfaceInfoEXT {
VkStructureType sType;
const void* pNext;
VkImage image;
IOSurfaceRef ioSurface;
} VkExportMetalIOSurfaceInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis a VkImage. -
ioSurfaceis the Metal IOSurfaceRef object underlying the VkImage object inimage. The implementation will return the IOSurfaceRef in this member, or it will returnNULLif no IOSurfaceRef could be found underlying the VkImage object.
To import, or create, a Metal IOSurfaceRef object to underlie a
VkImage object, include a VkImportMetalIOSurfaceInfoEXT
structure in the pNext chain of the VkImageCreateInfo structure
in a vkCreateImage command.
The VkImportMetalIOSurfaceInfoEXT structure is defined as:
// Provided by VK_EXT_metal_objects
typedef struct VkImportMetalIOSurfaceInfoEXT {
VkStructureType sType;
const void* pNext;
IOSurfaceRef ioSurface;
} VkImportMetalIOSurfaceInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
ioSurfaceis VK_NULL_HANDLE or the Metal IOSurfaceRef object that is to underlie the VkImage.
If ioSurface is not VK_NULL_HANDLE, it will be used to underlie
the VkImage.
If ioSurface is VK_NULL_HANDLE, the implementation will create a
new IOSurface to underlie the VkImage.
If provided, the application must ensure that the configuration of the IOSurfaceRef object is compatible with the configuration of the VkImage. Failure to do so results in undefined behavior.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
semaphoreis VK_NULL_HANDLE or a VkSemaphore. -
eventis VK_NULL_HANDLE or 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 id<MTLSharedEvent> object to underlie a
VkSemaphore or VkEvent object, include a
VkImportMetalSharedEventInfoEXT structure in the pNext chain of
the VkSemaphoreCreateInfo or VkEventCreateInfo structure in a
vkCreateSemaphore or vkCreateEvent command, respectively.
The VkImportMetalSharedEventInfoEXT structure is defined as:
-
sTypeis a VkStructureType value identifying 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 id<MTLSharedEvent> object will be set to
VkSemaphoreTypeCreateInfo::initialValue.
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. QNX Screen Buffer External Memory
To import memory created outside of the current Vulkan instance from a QNX
Screen buffer, add a VkImportScreenBufferInfoQNX structure to the
pNext chain of the VkMemoryAllocateInfo structure.
The VkImportScreenBufferInfoQNX structure is defined as:
// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkImportScreenBufferInfoQNX {
VkStructureType sType;
const void* pNext;
struct _screen_buffer* buffer;
} VkImportScreenBufferInfoQNX;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferis a pointer to astruct_screen_buffer, the QNX Screen buffer to import
The implementation may not acquire a reference to the imported Screen
buffer.
Therefore, the application must ensure that the object referred to by
buffer stays valid as long as the device memory to which it is
imported is being used.
To determine the memory parameters to use when importing a QNX Screen buffer, call:
// Provided by VK_QNX_external_memory_screen_buffer
VkResult vkGetScreenBufferPropertiesQNX(
VkDevice device,
const struct _screen_buffer* buffer,
VkScreenBufferPropertiesQNX* pProperties);
-
deviceis the logical device that will be importingbuffer. -
bufferis the QNX Screen buffer which will be imported. -
pPropertiesis a pointer to a VkScreenBufferPropertiesQNX structure in which the properties ofbufferare returned.
The VkScreenBufferPropertiesQNX structure returned is defined as:
// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkScreenBufferPropertiesQNX {
VkStructureType sType;
void* pNext;
VkDeviceSize allocationSize;
uint32_t memoryTypeBits;
} VkScreenBufferPropertiesQNX;
-
sTypeis a VkStructureType value identifying 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 Screen buffer can be imported as.
To obtain format properties of a QNX Screen buffer, include a
VkScreenBufferFormatPropertiesQNX structure in the pNext chain
of the VkScreenBufferPropertiesQNX structure passed to
vkGetScreenBufferPropertiesQNX.
This structure is defined as:
// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkScreenBufferFormatPropertiesQNX {
VkStructureType sType;
void* pNext;
VkFormat format;
uint64_t externalFormat;
uint64_t screenUsage;
VkFormatFeatureFlags formatFeatures;
VkComponentMapping samplerYcbcrConversionComponents;
VkSamplerYcbcrModelConversion suggestedYcbcrModel;
VkSamplerYcbcrRange suggestedYcbcrRange;
VkChromaLocation suggestedXChromaOffset;
VkChromaLocation suggestedYChromaOffset;
} VkScreenBufferFormatPropertiesQNX;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatis the Vulkan format corresponding to the Screen buffer’s format orVK_FORMAT_UNDEFINEDif there is not an equivalent Vulkan format. -
externalFormatis an implementation-defined external format identifier for use with VkExternalFormatQNX. It must not be zero. -
screenUsageis an implementation-defined external usage identifier for the QNX Screen buffer. -
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 QNX Screen buffer has one of the formats listed in the
QNX Screen Format Equivalence
table, then format must have the equivalent Vulkan format listed in
the table.
Otherwise, format may be VK_FORMAT_UNDEFINED, indicating the
QNX Screen buffer can only be used with an external format.
The formatFeatures member must include
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT and should include
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT and
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT.
11.2.12. Metal External Memory
To import memory from a Metal handle, add a
VkImportMemoryMetalHandleInfoEXT structure to the pNext chain of
the VkMemoryAllocateInfo structure.
The VkImportMemoryMetalHandleInfoEXT structure is defined as:
// Provided by VK_EXT_external_memory_metal
typedef struct VkImportMemoryMetalHandleInfoEXT {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlagBits handleType;
void* handle;
} VkImportMemoryMetalHandleInfoEXT;
-
sTypeis a VkStructureType value identifying 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.
Importing memory object payloads from Metal handles shares the ownership of the handle to the Vulkan implementation.
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 Metal handle representing the payload of a Vulkan device memory object, call:
// Provided by VK_EXT_external_memory_metal
VkResult vkGetMemoryMetalHandleEXT(
VkDevice device,
const VkMemoryGetMetalHandleInfoEXT* pGetMetalHandleInfo,
void** pHandle);
-
deviceis the logical device that created the device memory being exported. -
pGetMetalHandleInfois a pointer to a VkMemoryGetMetalHandleInfoEXT structure containing parameters of the export operation. -
pHandlewill return the Metal handle representing the payload of the device memory object.
Unless the app retains the handle object returned by the call, the lifespan
will be the same as the associated VkDeviceMemory.
The VkMemoryGetMetalHandleInfoEXT structure is defined as:
// Provided by VK_EXT_external_memory_metal
typedef struct VkMemoryGetMetalHandleInfoEXT {
VkStructureType sType;
const void* pNext;
VkDeviceMemory memory;
VkExternalMemoryHandleTypeFlagBits handleType;
} VkMemoryGetMetalHandleInfoEXT;
-
sTypeis a VkStructureType value identifying 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.
Metal 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_EXT_external_memory_metal
VkResult vkGetMemoryMetalHandlePropertiesEXT(
VkDevice device,
VkExternalMemoryHandleTypeFlagBits handleType,
const void* pHandle,
VkMemoryMetalHandlePropertiesEXT* pMemoryMetalHandleProperties);
-
deviceis the logical device that will be importingpHandle. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the type of the handlepHandle. -
pHandleis the handle which will be imported. -
pMemoryMetalHandlePropertiesis a pointer to a VkMemoryMetalHandlePropertiesEXT structure in which properties ofpHandleare returned.
The VkMemoryMetalHandlePropertiesEXT structure returned is defined as:
// Provided by VK_EXT_external_memory_metal
typedef struct VkMemoryMetalHandlePropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t memoryTypeBits;
} VkMemoryMetalHandlePropertiesEXT;
-
sTypeis a VkStructureType value identifying 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 Metal handle can be imported as.
11.2.13. 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 a VkStructureType value identifying 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_EXT_zero_initialize_device_memory
VK_MEMORY_ALLOCATE_ZERO_INITIALIZE_BIT_EXT = 0x00000008,
// 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. -
VK_MEMORY_ALLOCATE_ZERO_INITIALIZE_BIT_EXTspecifies that the memory will be zeroed automatically by the implementation before application is able to access it.
// 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.14. 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 a VkStructureType value identifying 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.15. 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.16. 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 a bitmask of VkMemoryMapFlagBits specifying additional parameters of the memory map operation. -
ppDatais a pointer to avoid*variable in which a host-accessible pointer to the beginning of the mapped range is returned. The value of the returned pointer minusoffsetmust be aligned to 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. |
Calling vkMapMemory is equivalent to calling vkMapMemory2 with
an empty pNext chain.
Bits which can be set in vkMapMemory::flags and
VkMemoryMapInfo::flags, specifying additional properties of a
memory map, are:
// Provided by VK_VERSION_1_0
typedef enum VkMemoryMapFlagBits {
// Provided by VK_EXT_map_memory_placed
VK_MEMORY_MAP_PLACED_BIT_EXT = 0x00000001,
} VkMemoryMapFlagBits;
-
VK_MEMORY_MAP_PLACED_BIT_EXTrequests that the implementation place the memory map at the virtual address specified by the application via VkMemoryMapPlacedInfoEXT::pPlacedAddress, replacing any existing mapping at that address. This flag must not be used with vkMapMemory as there is no way to specify the placement address.
// Provided by VK_VERSION_1_0
typedef VkFlags VkMemoryMapFlags;
VkMemoryMapFlags is a bitmask type for setting a mask of zero or more
VkMemoryMapFlagBits.
Alternatively, to retrieve a host virtual address pointer to a region of a mappable memory object, call:
// Provided by VK_VERSION_1_4
VkResult vkMapMemory2(
VkDevice device,
const VkMemoryMapInfo* pMemoryMapInfo,
void** ppData);
or the equivalent command
// Provided by VK_KHR_map_memory2
VkResult vkMapMemory2KHR(
VkDevice device,
const VkMemoryMapInfo* pMemoryMapInfo,
void** ppData);
-
deviceis the logical device that owns the memory. -
pMemoryMapInfois a pointer to a VkMemoryMapInfo structure describing parameters of the map. -
ppDatais a pointer to avoid *variable in which is returned a host-accessible pointer to the beginning of the mapped range. This pointer minus VkMemoryMapInfo::offsetmust be aligned to at least VkPhysicalDeviceLimits::minMemoryMapAlignment.
This function behaves identically to vkMapMemory except that it gets its parameters via an extensible structure pointer rather than directly as function arguments.
The VkMemoryMapInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkMemoryMapInfo {
VkStructureType sType;
const void* pNext;
VkMemoryMapFlags flags;
VkDeviceMemory memory;
VkDeviceSize offset;
VkDeviceSize size;
} VkMemoryMapInfo;
or the equivalent
// Provided by VK_KHR_map_memory2
typedef VkMemoryMapInfo VkMemoryMapInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkMemoryMapFlagBits specifying additional parameters of the memory map operation. -
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.
If VK_MEMORY_MAP_PLACED_BIT_EXT is set in
VkMemoryMapInfo::flags and the pNext chain of
VkMemoryMapInfo includes a VkMemoryMapPlacedInfoEXT structure,
then that structure specifies the placement address of the memory map.
The implementation will place the memory map at the specified address,
replacing any existing maps in the specified memory range.
Replacing memory maps in this way does not implicitly unmap Vulkan memory
objects.
Instead, the application must ensure no other Vulkan memory objects are
mapped anywhere in the specified virtual address range.
If successful, ppData will be set to the same value as
VkMemoryMapPlacedInfoEXT::pPlacedAddress and vkMapMemory2
will return VK_SUCCESS.
If it cannot place the map at the requested address for any reason, the
memory object is left unmapped and vkMapMemory2 will return
VK_ERROR_MEMORY_MAP_FAILED.
The VkMemoryMapPlacedInfoEXT structure is defined as:
// Provided by VK_EXT_map_memory_placed
typedef struct VkMemoryMapPlacedInfoEXT {
VkStructureType sType;
const void* pNext;
void* pPlacedAddress;
} VkMemoryMapPlacedInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pPlacedAddressis the virtual address at which to place the address. IfVkMemoryMapInfo::flagsdoes not containVK_MEMORY_MAP_PLACED_BIT_EXT, this value is ignored.
Two commands are provided to enable applications to work with non-coherent
memory allocations: vkFlushMappedMemoryRanges and
vkInvalidateMappedMemoryRanges.
|
Note
|
If the memory object was created with the
|
|
Note
|
While memory objects imported from a handle type of
|
After a successful call to vkMapMemory
or vkMapMemory2
the memory object memory is considered to be currently host mapped.
To flush ranges of non-coherent memory from the host caches, call:
// Provided by VK_VERSION_1_0
VkResult vkFlushMappedMemoryRanges(
VkDevice device,
uint32_t memoryRangeCount,
const VkMappedMemoryRange* pMemoryRanges);
-
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.
The first synchronization scope includes all host operations that happened-before it, as defined by the host memory model.
|
Note
|
Some systems allow writes that do not directly integrate with the host
memory model; these have to be synchronized by the application manually.
One example of this is non-temporal store instructions on x86; to ensure
these happen-before submission, applications should call |
The second synchronization scope is empty.
The first access scope includes host writes to the specified memory ranges.
|
Note
|
When a host write to a memory location is made available in this way, each
whole aligned set of |
The second access scope is empty.
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.
The first synchronization scope includes all host operations that happened-before it, as defined by the host memory model.
|
Note
|
This function does not synchronize with device operations directly - other host synchronization operations that depend on device operations such as vkWaitForFences must be executed beforehand. So for any non-coherent device write to be made visible to the host, there has to be a dependency chain along the following lines:
|
The second synchronization scope includes all host operations that happen-after it, as defined by the host memory model.
The first access scope is empty.
The second access scope includes host reads to the specified memory ranges.
|
Note
|
When a device write to a memory location is made visible to the host in this
way, each whole aligned set of |
|
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 a VkStructureType value identifying 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.
Calling vkUnmapMemory is equivalent to calling vkUnmapMemory2
with an empty pNext chain and flags set to zero.
Alternatively, to unmap a memory object once host access to it is no longer needed by the application, call:
// Provided by VK_VERSION_1_4
VkResult vkUnmapMemory2(
VkDevice device,
const VkMemoryUnmapInfo* pMemoryUnmapInfo);
or the equivalent command
// Provided by VK_KHR_map_memory2
VkResult vkUnmapMemory2KHR(
VkDevice device,
const VkMemoryUnmapInfo* pMemoryUnmapInfo);
-
deviceis the logical device that owns the memory. -
pMemoryUnmapInfois a pointer to a VkMemoryUnmapInfo structure describing parameters of the unmap.
This function behaves identically to vkUnmapMemory except that it gets its parameters via an extensible structure pointer rather than directly as function arguments.
The VkMemoryUnmapInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkMemoryUnmapInfo {
VkStructureType sType;
const void* pNext;
VkMemoryUnmapFlags flags;
VkDeviceMemory memory;
} VkMemoryUnmapInfo;
or the equivalent
// Provided by VK_KHR_map_memory2
typedef VkMemoryUnmapInfo VkMemoryUnmapInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkMemoryUnmapFlagBits specifying additional parameters of the memory map operation. -
memoryis the VkDeviceMemory object to be unmapped.
Bits which can be set in VkMemoryUnmapInfo::flags, specifying
additional properties of a memory unmap, are:
// Provided by VK_VERSION_1_4
typedef enum VkMemoryUnmapFlagBits {
// Provided by VK_EXT_map_memory_placed
VK_MEMORY_UNMAP_RESERVE_BIT_EXT = 0x00000001,
} VkMemoryUnmapFlagBits;
or the equivalent
// Provided by VK_KHR_map_memory2
typedef VkMemoryUnmapFlagBits VkMemoryUnmapFlagBitsKHR;
-
VK_MEMORY_UNMAP_RESERVE_BIT_EXTrequests that virtual address range currently occupied by the memory map remain reserved after the vkUnmapMemory2 call completes. Future system memory map operations or calls to vkMapMemory or vkMapMemory2 will not return addresses in that range unless the range has since been unreserved by the client or the mapping is explicitly placed in that range by calling vkMapMemory2 withVK_MEMORY_MAP_PLACED_BIT_EXT, or doing the system memory map equivalent. WhenVK_MEMORY_UNMAP_RESERVE_BIT_EXTis set, the memory unmap operation may fail, in which case the memory object will remain host mapped and vkUnmapMemory2 will returnVK_ERROR_MEMORY_MAP_FAILED.
// Provided by VK_VERSION_1_4
typedef VkFlags VkMemoryUnmapFlags;
or the equivalent
// Provided by VK_KHR_map_memory2
typedef VkMemoryUnmapFlags VkMemoryUnmapFlagsKHR;
VkMemoryUnmapFlags is a bitmask type for setting a mask of zero or
more VkMemoryUnmapFlagBits.
11.2.17. 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 a VkDeviceSize value in which the number of bytes currently committed is returned, on success.
The implementation may update the commitment at any time, and the value returned by this query may be out of date.
The implementation guarantees to allocate any committed memory from the
heapIndex indicated by the memory type that the memory object was
created with.
11.2.18. 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 , unprotected tensors, and unprotected buffers, to which unprotected memory can be bound
-
Protected images , protected tensors, and protected buffers, to which protected memory can be bound
-
-
Command buffers:
-
Unprotected command buffers, which can be submitted to a device queue to execute unprotected queue operations
-
Protected command buffers, which can be submitted to a protected-capable device queue to execute protected queue operations
-
-
Device queues:
-
Unprotected device queues, to which unprotected command buffers can be submitted
-
Protected-capable device queues, to which unprotected command buffers or protected command buffers can be submitted
-
-
Queue submissions
-
Unprotected queue submissions, through which unprotected command buffers can be submitted
-
Protected queue submissions, through which protected command buffers can be submitted
-
-
Queue operations
-
Unprotected queue operations
-
Protected queue operations
-
|
Note
|
When the |
Protected Memory Access Rules
If VkPhysicalDeviceProtectedMemoryProperties::protectedNoFault
is VK_FALSE, applications must not perform any of the following
operations:
-
Write to unprotected memory within protected queue operations.
-
Access protected memory within protected queue operations other than in framebuffer-space pipeline stages, the compute shader stage, or the transfer stage.
-
Perform a query within protected queue operations.
If VkPhysicalDeviceProtectedMemoryProperties::protectedNoFault
is VK_TRUE, these operations are valid, but reads will return
undefined values, and writes will either be dropped or store undefined
values.
Additionally, indirect operations must not be performed within protected queue operations.
Whether these operations are valid or not, or if any other invalid usage is performed, the implementation must guarantee that:
-
Protected device memory must never be visible to the host.
-
Values written to unprotected device memory must not be a function of values from protected memory.
11.2.19. 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
or VkTensorARM
can be bound to the imported or exported VkDeviceMemory object if it
is created with
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.
To remove an unnecessary compile time dependency, an incomplete type definition of AHardwareBuffer is provided in the Vulkan headers:
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
struct AHardwareBuffer;
The actual AHardwareBuffer type is defined in Android NDK headers.
|
Note
|
The NDK format, usage, and size/dimensions of an AHardwareBuffer
object can be obtained with the |
Android hardware buffer objects are reference-counted using Android NDK
functions outside of the scope of this specification.
A VkDeviceMemory imported from an Android hardware buffer or that can
be exported to an Android hardware buffer must acquire a reference to its
AHardwareBuffer object, and must release this reference when the
device memory is freed.
During the host execution of a Vulkan command that has an Android hardware
buffer as a parameter (including indirect parameters via pNext
chains), the application must not decrement the Android hardware buffer’s
reference count to zero.
Android hardware buffers can be mapped and unmapped for CPU access using the NDK functions. These lock and unlock APIs are considered to acquire and release ownership of the Android hardware buffer, and applications must follow the rules described in External Resource Sharing to transfer ownership between the Vulkan instance and these native APIs.
Android hardware buffers can be shared with external APIs and Vulkan instances on the same device, and also with foreign devices. When transferring ownership of the Android hardware buffer, the external and foreign special queue families described in Queue Family Ownership Transfer are not identical. All APIs which produce or consume Android hardware buffers are considered to use foreign devices, except OpenGL ES contexts and Vulkan logical devices that have matching device and driver UUIDs. Implementations may treat a transfer to or from the foreign queue family as if it were a transfer to or from the external queue family when the Android hardware buffer’s usage only permits it to be used on the same physical device.
Android Hardware Buffer Optimal Usages
Vulkan buffer and image usage flags do not correspond exactly to Android
hardware buffer usage flags.
When allocating Android hardware buffers with non-Vulkan APIs, if any
AHARDWAREBUFFER_USAGE_GPU_* usage bits are included, by default the
allocator must allocate the memory in such a way that it supports Vulkan
usages and creation flags in the
usage equivalence table
which do not have Android hardware buffer equivalents.
An VkAndroidHardwareBufferUsageANDROID structure can be included in
the pNext chain of a VkImageFormatProperties2 structure passed
to vkGetPhysicalDeviceImageFormatProperties2 to obtain optimal Android
hardware buffer usage flags for specific Vulkan resource creation
parameters.
Some usage flags returned by these commands are required based on the input
parameters, but additional vendor-specific usage flags
(AHARDWAREBUFFER_USAGE_VENDOR_*) may also be returned.
Any Android hardware buffer allocated with these vendor-specific usage flags
and imported to Vulkan must only be bound to resources created with
parameters that are a subset of the parameters used to obtain the Android
hardware buffer usage, since the memory may have been allocated in a way
incompatible with other parameters.
If an Android hardware buffer is successfully allocated with additional
non-vendor-specific usage flags in addition to the recommended usage, it
must support being used in the same ways as an Android hardware buffer
allocated with only the recommended usage, and also in ways indicated by the
additional usage.
Android Hardware Buffer External Formats
Android hardware buffers may represent images using implementation-specific formats, layouts, color models, etc., which do not have Vulkan equivalents. Such external formats are commonly used by external image sources such as video decoders or cameras. Vulkan can import Android hardware buffers that have external formats, but since the image contents are in a possibly proprietary representation, images with external formats must have optimal tiling, and their use is restricted. Images with external formats must only be sampled with a sampler that has Y′CBCR conversion enabled.
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 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.
QNX Screen Buffer
The QNX SDP defines _screen_buffer objects, which represent a buffer
that the QNX Screen graphics subsystem can use directly in its windowing
system APIs.
More specifically, a Screen buffer is an area of memory that stores pixel
data.
It can be attached to Screen windows, streams, or pixmaps.
These QNX Screen buffer objects may be imported into VkDeviceMemory
objects for access via Vulkan.
An VkImage or VkBuffer can be bound to the imported
VkDeviceMemory object if it is created with
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX.
struct _screen_buffer is strongly typed, so naming the handle type
is redundant.
The internal layout and therefore size of a struct _screen_buffer
image may depend on native usage flags that do not have corresponding Vulkan
counterparts.
QNX Screen Buffer Validity
The design of Screen in the QNX SDP makes it difficult to determine the validity of objects from outside of Screen. Therefore, applications must ensure that QNX Screen buffer objects provided used in various Vulkan interfaces are ones created explicitly with QNX Screen APIs. See QNX SDP documentation for more information.
A VkDeviceMemory imported from a QNX Screen buffer has no way to
acquire a reference to its _screen_buffer object.
Therefore, during the host execution of a Vulkan command that has a QNX
Screen buffer as a parameter (including indirect parameters via pNext
chains), the application must ensure that the QNX Screen buffer resource
remains valid.
Generally, for a _screen_buffer object to be valid for use within a
Vulkan implementation, the buffer object should have a
_screen_buffer::SCREEN_PROPERTY_USAGE that includes at least one
of: SCREEN_USAGE_VULKAN, SCREEN_USAGE_OPENGL_ES2,
SCREEN_USAGE_OPENGL_ES3, or SCREEN_USAGE_NATIVE.
The exact Screen-native usage flags required depends on the Vulkan
implementation, and QNX Screen itself will not necessarily enforce these
requirements.
Note that Screen-native usage flags are in no way related to usage flags in
the Vulkan specification.
QNX Screen Buffer External Formats
QNX Screen 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 QNX Screen 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 a QNX Screen buffer can use an external
format by setting VkImageCreateInfo::format to
VK_FORMAT_UNDEFINED and including a VkExternalFormatQNX
structure in the pNext chain.
Images can be created with an external format even if the QNX Screen 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.
The external format of a QNX Screen buffer can be obtained by passing a
VkScreenBufferFormatPropertiesQNX structure to
vkGetScreenBufferPropertiesQNX.
QNX Screen Buffer Image Resources
QNX Screen buffers have intrinsic width, height, format, and usage
properties, so Vulkan images bound to memory imported from a QNX Screen
buffer must use dedicated allocations:
VkMemoryDedicatedRequirements::requiresDedicatedAllocation must
be VK_TRUE for images created with
VkExternalMemoryImageCreateInfo::handleTypes that includes
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX.
When creating an image that will be bound to an imported QNX Screen buffer,
the image creation parameters must be equivalent to the _screen_buffer
properties as described by the valid usage of VkMemoryAllocateInfo.
| QNX Screen Format | Vulkan Format |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- 1
-
Vulkan does not differentiate between
SCREEN_FORMAT_RGBA8888andSCREEN_FORMAT_RGBX8888: they both behave asVK_FORMAT_R8G8B8A8_UNORM. After an external entity writes to aSCREEN_FORMAT_RGBX8888QNX Screen 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. The same behavior applies to the following pairs:SCREEN_FORMAT_BGRA8888andSCREEN_FORMAT_BGRX8888,SCREEN_FORMAT_RGBA1010102andSCREEN_FORMAT_RGBX1010102,SCREEN_FORMAT_BGRA1010102andSCREEN_FORMAT_BGRX1010102,SCREEN_FORMAT_RGBA5551andSCREEN_FORMAT_RGBX5551
11.2.20. 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.21. 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryspecifies the memory whose address is being queried.
12. Resource Creation
Vulkan supports three primary resource types: buffers, images, and tensors. 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. Tensors can be multidimensional, contain format information like images and may have associated metadata.
Other resource types, such as acceleration structures and micromaps use buffers as the backing store for opaque data structures.
12.1. Buffers
Buffers represent linear arrays of data which are used for various purposes by binding them to a graphics or compute pipeline via descriptor sets or certain commands, or by directly specifying them as parameters to certain commands.
Buffers are represented by VkBuffer handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBuffer)
To create buffers, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateBuffer(
VkDevice device,
const VkBufferCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkBuffer* pBuffer);
-
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 a VkStructureType value identifying 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.
If the pNext chain includes a VkBufferUsageFlags2CreateInfo
structure, VkBufferUsageFlags2CreateInfo::usage from that
structure is used instead of usage from this structure.
The VkBufferUsageFlags2CreateInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkBufferUsageFlags2CreateInfo {
VkStructureType sType;
const void* pNext;
VkBufferUsageFlags2 usage;
} VkBufferUsageFlags2CreateInfo;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkBufferUsageFlags2CreateInfo VkBufferUsageFlags2CreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
usageis a bitmask of VkBufferUsageFlagBits2 specifying allowed usages of the buffer.
If this structure is included in the pNext chain of a buffer creation
structure, usage is used instead of the corresponding usage
value passed in that creation structure, allowing additional usage flags to
be specified.
If this structure is included in the pNext chain of a buffer query
structure, the usage flags of the buffer are returned in usage of this
structure, and the usage flags representable in usage of the buffer
query structure are also returned in that field.
Bits which can be set in VkBufferUsageFlags2CreateInfo::usage,
specifying usage behavior of a buffer, are:
// Provided by VK_VERSION_1_4
// Flag bits for VkBufferUsageFlagBits2
typedef VkFlags64 VkBufferUsageFlagBits2;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT = 0x00000001ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_DST_BIT = 0x00000002ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT = 0x00000008ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT = 0x00000010ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT = 0x00000020ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT = 0x00000040ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT = 0x00000080ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT = 0x00000100ULL;
// Provided by VK_VERSION_1_4
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT = 0x00020000ULL;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue with VK_KHR_maintenance5 or VK_VERSION_1_4
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_EXECUTION_GRAPH_SCRATCH_BIT_AMDX = 0x02000000ULL;
#endif
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT_KHR = 0x00000001ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_DST_BIT_KHR = 0x00000002ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR = 0x00000004ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT_KHR = 0x00000020ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT_KHR = 0x00000080ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_conditional_rendering
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_CONDITIONAL_RENDERING_BIT_EXT = 0x00000200ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SHADER_BINDING_TABLE_BIT_KHR = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_RAY_TRACING_BIT_NV = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_transform_feedback
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT = 0x00000800ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_transform_feedback
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT = 0x00001000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_decode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_DECODE_SRC_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_decode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_DECODE_DST_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_encode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_ENCODE_DST_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_encode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_ENCODE_SRC_BIT_KHR = 0x00010000ULL;
// Provided by VK_KHR_maintenance5 with (VK_VERSION_1_2 or VK_KHR_buffer_device_address) or VK_EXT_buffer_device_address
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT_KHR = 0x00020000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR = 0x00080000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR = 0x00100000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT = 0x00200000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00400000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_MICROMAP_STORAGE_BIT_EXT = 0x01000000ULL;
// Provided by VK_ARM_data_graph
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_DATA_GRAPH_FOREIGN_DESCRIPTOR_BIT_ARM = 0x20000000ULL;
// Provided by VK_QCOM_tile_memory_heap
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TILE_MEMORY_BIT_QCOM = 0x08000000ULL;
// Provided by VK_EXT_device_generated_commands
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_PREPROCESS_BUFFER_BIT_EXT = 0x80000000ULL;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkBufferUsageFlagBits2 VkBufferUsageFlagBits2KHR;
-
VK_BUFFER_USAGE_2_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_2_TRANSFER_DST_BITspecifies that the buffer can be used as the destination of a transfer command. -
VK_BUFFER_USAGE_2_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_2_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_2_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_2_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_2_INDEX_BUFFER_BITspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdBindIndexBuffer2 and vkCmdBindIndexBuffer. -
VK_BUFFER_USAGE_2_VERTEX_BUFFER_BITspecifies that the buffer is suitable for passing as an element of thepBuffersarray to vkCmdBindVertexBuffers. -
VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BITspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV,vkCmdDrawMeshTasksIndirectEXT,vkCmdDrawMeshTasksIndirectCountEXT, vkCmdDrawClusterIndirectHUAWEI, or vkCmdDispatchIndirect. It is also suitable for passing as thebuffermember ofVkIndirectCommandsStreamNV, orsequencesCountBufferorsequencesIndexBufferorpreprocessedBuffermember ofVkGeneratedCommandsInfoNV. It is also suitable for passing as the underlying buffer of either thepreprocessAddressorsequenceCountAddressmembers ofVkGeneratedCommandsInfoEXT. -
VK_BUFFER_USAGE_2_CONDITIONAL_RENDERING_BIT_EXTspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdBeginConditionalRenderingEXT. -
VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_BUFFER_BIT_EXTspecifies that the buffer is suitable for using for binding as a transform feedback buffer with vkCmdBindTransformFeedbackBuffersEXT. -
VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXTspecifies that the buffer is suitable for using as a counter buffer with vkCmdBeginTransformFeedbackEXT and vkCmdEndTransformFeedbackEXT. -
VK_BUFFER_USAGE_2_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer is suitable to contain sampler and combined image sampler descriptors when bound as a descriptor buffer. Buffers containing combined image sampler descriptors must also specifyVK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT. -
VK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer is suitable to contain resource descriptors when bound as a descriptor buffer. -
VK_BUFFER_USAGE_2_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer, when bound, can be used by the implementation to support push descriptors when using descriptor buffers. -
VK_BUFFER_USAGE_2_TILE_MEMORY_BIT_QCOMspecifies that the buffer can be bound toVkDeviceMemoryallocated from a VkMemoryHeap with theVK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOMproperty. -
VK_BUFFER_USAGE_2_RAY_TRACING_BIT_NVspecifies that the buffer is suitable for use in vkCmdTraceRaysNV. -
VK_BUFFER_USAGE_2_SHADER_BINDING_TABLE_BIT_KHRspecifies that the buffer is suitable for use as a Shader Binding Table. -
VK_BUFFER_USAGE_2_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_2_ACCELERATION_STRUCTURE_STORAGE_BIT_KHRspecifies that the buffer is suitable for storage space for a VkAccelerationStructureKHR. -
VK_BUFFER_USAGE_2_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_2_VIDEO_DECODE_SRC_BIT_KHRspecifies that the buffer can be used as the source video bitstream buffer in a video decode operation. -
VK_BUFFER_USAGE_2_VIDEO_DECODE_DST_BIT_KHRis reserved for future use. -
VK_BUFFER_USAGE_2_VIDEO_ENCODE_DST_BIT_KHRspecifies that the buffer can be used as the destination video bitstream buffer in a video encode operation. -
VK_BUFFER_USAGE_2_VIDEO_ENCODE_SRC_BIT_KHRis reserved for future use. -
VK_BUFFER_USAGE_2_EXECUTION_GRAPH_SCRATCH_BIT_AMDXspecifies that the buffer can be used for as scratch memory for execution graph dispatch. -
VK_BUFFER_USAGE_2_PREPROCESS_BUFFER_BIT_EXTspecifies that the buffer can be used as a preprocess buffer for Device-Generated Commands. -
VK_BUFFER_USAGE_2_DATA_GRAPH_FOREIGN_DESCRIPTOR_BIT_ARMspecifies that the buffer is suitable to contain resource descriptors when bound as a descriptor buffer in command buffers allocated from a command pool that can target foreign data graph processing engines.
// Provided by VK_VERSION_1_4
typedef VkFlags64 VkBufferUsageFlags2;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkBufferUsageFlags2 VkBufferUsageFlags2KHR;
VkBufferUsageFlags2 is a bitmask type for setting a mask of zero or
more VkBufferUsageFlagBits2.
Bits which can be set in VkBufferCreateInfo::usage, specifying
usage behavior of a buffer, are:
// Provided by VK_VERSION_1_0
typedef enum VkBufferUsageFlagBits {
VK_BUFFER_USAGE_TRANSFER_SRC_BIT = 0x00000001,
VK_BUFFER_USAGE_TRANSFER_DST_BIT = 0x00000002,
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004,
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT = 0x00000008,
VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT = 0x00000010,
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT = 0x00000020,
VK_BUFFER_USAGE_INDEX_BUFFER_BIT = 0x00000040,
VK_BUFFER_USAGE_VERTEX_BUFFER_BIT = 0x00000080,
VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT = 0x00000100,
// Provided by VK_VERSION_1_2
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT = 0x00020000,
// Provided by VK_KHR_video_decode_queue
VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00002000,
// Provided by VK_KHR_video_decode_queue
VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00004000,
// Provided by VK_EXT_transform_feedback
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT = 0x00000800,
// Provided by VK_EXT_transform_feedback
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT = 0x00001000,
// Provided by VK_EXT_conditional_rendering
VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT = 0x00000200,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue
VK_BUFFER_USAGE_EXECUTION_GRAPH_SCRATCH_BIT_AMDX = 0x02000000,
#endif
// Provided by VK_KHR_acceleration_structure
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR = 0x00080000,
// Provided by VK_KHR_acceleration_structure
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR = 0x00100000,
// Provided by VK_KHR_ray_tracing_pipeline
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR = 0x00000400,
// Provided by VK_KHR_video_encode_queue
VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR = 0x00008000,
// Provided by VK_KHR_video_encode_queue
VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR = 0x00010000,
// Provided by VK_EXT_descriptor_buffer
VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT = 0x00200000,
// Provided by VK_EXT_descriptor_buffer
VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00400000,
// Provided by VK_EXT_descriptor_buffer
VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT = 0x04000000,
// Provided by VK_EXT_opacity_micromap
VK_BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT = 0x00800000,
// Provided by VK_EXT_opacity_micromap
VK_BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT = 0x01000000,
// Provided by VK_QCOM_tile_memory_heap
VK_BUFFER_USAGE_TILE_MEMORY_BIT_QCOM = 0x08000000,
// 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 vkCmdBindIndexBuffer2 and 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,vkCmdDrawMeshTasksIndirectEXT,vkCmdDrawMeshTasksIndirectCountEXT, vkCmdDrawClusterIndirectHUAWEI, or vkCmdDispatchIndirect. It is also suitable for passing as thebuffermember ofVkIndirectCommandsStreamNV, orsequencesCountBufferorsequencesIndexBufferorpreprocessedBuffermember ofVkGeneratedCommandsInfoNV. It is also suitable for passing as the underlying buffer of either thepreprocessAddressorsequenceCountAddressmembers ofVkGeneratedCommandsInfoEXT. -
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_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer is suitable to contain sampler and combined image sampler descriptors when bound as a descriptor buffer. Buffers containing combined image sampler descriptors must also specifyVK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT. -
VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer is suitable to contain resource descriptors when bound as a descriptor buffer. -
VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer, when bound, can be used by the implementation to support push descriptors when using descriptor buffers. -
VK_BUFFER_USAGE_TILE_MEMORY_BIT_QCOMspecifies that the buffer can be bound toVkDeviceMemoryallocated from a VkMemoryHeap with theVK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOMproperty. -
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 video bitstream buffer in a video decode operation. -
VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHRis reserved for future use. -
VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHRspecifies that the buffer can be used as the destination video bitstream buffer in a video encode operation. -
VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHRis reserved for future use. -
VK_BUFFER_USAGE_EXECUTION_GRAPH_SCRATCH_BIT_AMDXspecifies that the buffer can be used for as scratch memory for execution graph dispatch.
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferUsageFlags;
VkBufferUsageFlags is a bitmask type for setting a mask of zero or
more VkBufferUsageFlagBits.
Bits which can be set in VkBufferCreateInfo::flags, specifying
additional parameters of a buffer, are:
// Provided by VK_VERSION_1_0
typedef enum VkBufferCreateFlagBits {
VK_BUFFER_CREATE_SPARSE_BINDING_BIT = 0x00000001,
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
VK_BUFFER_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
// Provided by VK_VERSION_1_1
VK_BUFFER_CREATE_PROTECTED_BIT = 0x00000008,
// Provided by VK_VERSION_1_2
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT = 0x00000010,
// Provided by VK_EXT_descriptor_buffer
VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000020,
// Provided by VK_KHR_video_maintenance1
VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR = 0x00000040,
// 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. -
VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTspecifies that the buffer can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. -
VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHRspecifies that the buffer can be used in video coding operations without having to specify at buffer creation time the set of video profiles the buffer will be used with.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
Applications should avoid creating buffers with application-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.
Applications and tools should avoid mixing application-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 a VkStructureType value identifying 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.
Applications should avoid creating buffers with application-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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
The buffer view has a buffer view usage identifying which descriptor types
can be created from it.
This usage
can be defined by including the VkBufferUsageFlags2CreateInfo
structure in the pNext chain, and specifying the usage value
there.
If this structure is not included, it
is equal to the VkBufferCreateInfo::usage value used to create
buffer.
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferViewCreateFlags;
VkBufferViewCreateFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
To destroy a buffer view, call:
// Provided by VK_VERSION_1_0
void vkDestroyBufferView(
VkDevice device,
VkBufferView bufferView,
const VkAllocationCallbacks* pAllocator);
-
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.2.1. Buffer View Format Features
Valid uses of a VkBufferView may depend on the buffer view’s format features, defined below. Such constraints are documented in the affected valid usage statement.
-
If Vulkan 1.3 is supported or the
VK_KHR_format_feature_flags2extension is supported, then the buffer view’s set of format features is the value of VkFormatProperties3::bufferFeaturesfound by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkBufferViewCreateInfo::format.
12.3. Buffer Device Addresses
To query a 64-bit buffer device address value which can be used to identify a buffer to API commands or through which buffer memory can be accessed, 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, bufferBaseAddress, is an address of the
start of pInfo->buffer.
Addresses in the range [bufferBaseAddress, bufferBaseAddress
+ VkBufferCreateInfo::size) can be used to access the
memory bound to this buffer on the device.
A value of zero is reserved as a “null” pointer and must not be returned as a valid buffer device address.
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 returned address must satisfy the alignment requirement specified by
VkMemoryRequirements::alignment for the buffer in
VkBufferDeviceAddressInfo::buffer.
If multiple VkBuffer objects are bound to overlapping ranges of VkDeviceMemory, implementations may return address ranges which overlap. In this case, it is ambiguous which VkBuffer is associated with any given device address. For purposes of valid usage, if multiple VkBuffer objects can be attributed to a device address, a VkBuffer is selected such that valid usage passes, if it exists.
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 a VkStructureType value identifying 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.
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.
12.4. 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 a VkStructureType value identifying 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 texels/pixels 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, unless theycbcrImageArraysfeature is enabled, or otherwise indicated by VkImageFormatProperties::maxArrayLayers, as returned by vkGetPhysicalDeviceImageFormatProperties -
samplesisVK_SAMPLE_COUNT_1_BIT
Images created with usage including
VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM have further restrictions on their
limits and capabilities compared to images created without this bit.
Creation of images with usage including
VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM may not be supported unless
parameters meet all of the constraints:
-
flagsis 0 or only includesVK_IMAGE_CREATE_ALIAS_BIT -
imageTypeisVK_IMAGE_TYPE_2D -
mipLevelsis 1 -
arrayLayersis 1 -
samplesisVK_SAMPLE_COUNT_1_BIT -
tilingisVK_IMAGE_TILING_OPTIMAL -
usageincludesVK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOMand any valid combination of the followingVK_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
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.
If the implementation reports VK_TRUE in
VkPhysicalDeviceHostImageCopyProperties::identicalMemoryTypeRequirements,
usage of VK_IMAGE_USAGE_HOST_TRANSFER_BIT must not affect the memory
type requirements of the image as described in
Sparse Resource Memory Requirements and
Resource Memory Association.
|
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalFormatis an implementation-defined identifier for the external format
When included in the pNext chain of another structure, it indicates
additional
format information beyond what is provided by VkFormat values for an
Android hardware buffer.
If externalFormat is zero, it indicates that no external format is
used, and implementations should rely only on other format information.
If this structure is not present, it is equivalent to setting
externalFormat to zero.
To create an image with an
QNX Screen external
format, add a VkExternalFormatQNX structure in the pNext chain
of VkImageCreateInfo.
VkExternalFormatQNX is defined as:
// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkExternalFormatQNX {
VkStructureType sType;
void* pNext;
uint64_t externalFormat;
} VkExternalFormatQNX;
-
sTypeis a VkStructureType value identifying 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
VkExternalFormatQNX 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 VkImageCompressionFlagsEXT;
VkImageCompressionFlagsEXT is a bitmask type for setting a mask of
zero or more VkImageCompressionFlagBitsEXT.
// Provided by VK_EXT_image_compression_control
typedef VkFlags VkImageCompressionFixedRateFlagsEXT;
VkImageCompressionFixedRateFlagsEXT is a bitmask type for setting a
mask of zero or more VkImageCompressionFixedRateFlagBitsEXT.
Bits which can be set in
VkImageCompressionControlEXT::pFixedRateFlags, specifying
allowed compression rates for an image plane, are:
// Provided by VK_EXT_image_compression_control
typedef enum VkImageCompressionFixedRateFlagBitsEXT {
VK_IMAGE_COMPRESSION_FIXED_RATE_NONE_EXT = 0,
VK_IMAGE_COMPRESSION_FIXED_RATE_1BPC_BIT_EXT = 0x00000001,
VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT = 0x00000002,
VK_IMAGE_COMPRESSION_FIXED_RATE_3BPC_BIT_EXT = 0x00000004,
VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXT = 0x00000008,
VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXT = 0x00000010,
VK_IMAGE_COMPRESSION_FIXED_RATE_6BPC_BIT_EXT = 0x00000020,
VK_IMAGE_COMPRESSION_FIXED_RATE_7BPC_BIT_EXT = 0x00000040,
VK_IMAGE_COMPRESSION_FIXED_RATE_8BPC_BIT_EXT = 0x00000080,
VK_IMAGE_COMPRESSION_FIXED_RATE_9BPC_BIT_EXT = 0x00000100,
VK_IMAGE_COMPRESSION_FIXED_RATE_10BPC_BIT_EXT = 0x00000200,
VK_IMAGE_COMPRESSION_FIXED_RATE_11BPC_BIT_EXT = 0x00000400,
VK_IMAGE_COMPRESSION_FIXED_RATE_12BPC_BIT_EXT = 0x00000800,
VK_IMAGE_COMPRESSION_FIXED_RATE_13BPC_BIT_EXT = 0x00001000,
VK_IMAGE_COMPRESSION_FIXED_RATE_14BPC_BIT_EXT = 0x00002000,
VK_IMAGE_COMPRESSION_FIXED_RATE_15BPC_BIT_EXT = 0x00004000,
VK_IMAGE_COMPRESSION_FIXED_RATE_16BPC_BIT_EXT = 0x00008000,
VK_IMAGE_COMPRESSION_FIXED_RATE_17BPC_BIT_EXT = 0x00010000,
VK_IMAGE_COMPRESSION_FIXED_RATE_18BPC_BIT_EXT = 0x00020000,
VK_IMAGE_COMPRESSION_FIXED_RATE_19BPC_BIT_EXT = 0x00040000,
VK_IMAGE_COMPRESSION_FIXED_RATE_20BPC_BIT_EXT = 0x00080000,
VK_IMAGE_COMPRESSION_FIXED_RATE_21BPC_BIT_EXT = 0x00100000,
VK_IMAGE_COMPRESSION_FIXED_RATE_22BPC_BIT_EXT = 0x00200000,
VK_IMAGE_COMPRESSION_FIXED_RATE_23BPC_BIT_EXT = 0x00400000,
VK_IMAGE_COMPRESSION_FIXED_RATE_24BPC_BIT_EXT = 0x00800000,
} VkImageCompressionFixedRateFlagBitsEXT;
-
VK_IMAGE_COMPRESSION_FIXED_RATE_NONE_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 VkSubresourceLayout2 structure in a call to
vkGetImageSubresourceLayout2 or
vkGetImageSubresourceLayout2.
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 a VkStructureType value identifying 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.
If the pNext list of VkImageCreateInfo includes a
VkImageAlignmentControlCreateInfoMESA structure, then that structure
describes desired alignment for this image.
The VkImageAlignmentControlCreateInfoMESA structure is defined as:
// Provided by VK_MESA_image_alignment_control
typedef struct VkImageAlignmentControlCreateInfoMESA {
VkStructureType sType;
const void* pNext;
uint32_t maximumRequestedAlignment;
} VkImageAlignmentControlCreateInfoMESA;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maximumRequestedAlignmentspecifies the maximum alignment for the image.
If maximumRequestedAlignment is not 0, the implementation should
choose an image memory layout that requires an alignment no larger than
maximumRequestedAlignment as reported in
VkMemoryRequirements::alignment.
If such a layout does not exist for the given image creation parameters, the
implementation should return the smallest alignment which is supported in
VkMemoryRequirements.
If an implementation needs to disable image compression for
maximumRequestedAlignment to be honored - where a larger alignment
would enable image compression - the implementation should not use
maximumRequestedAlignment, and should return the smallest alignment
which does not compromise compression.
If the imageCompressionControl
feature is enabled, the application can chain a
VkImageCompressionControlEXT with
VK_IMAGE_COMPRESSION_DISABLED_EXT.
In this case, image compression considerations should not apply when
implementation decides alignment.
Bits which can be set in
-
VkImageViewUsageCreateInfo::
usage -
VkImageStencilUsageCreateInfo::
stencilUsage -
VkImageCreateInfo::
usage
specify intended usage of an image, and are:
// Provided by VK_VERSION_1_0
typedef enum VkImageUsageFlagBits {
VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
// Provided by VK_VERSION_1_4
VK_IMAGE_USAGE_HOST_TRANSFER_BIT = 0x00400000,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00000400,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00000800,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR = 0x00001000,
// Provided by VK_EXT_fragment_density_map
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x00000200,
// Provided by VK_KHR_fragment_shading_rate
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00000100,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR = 0x00002000,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR = 0x00004000,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR = 0x00008000,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x00080000,
// Provided by VK_HUAWEI_invocation_mask
VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI = 0x00040000,
// Provided by VK_QCOM_image_processing
VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM = 0x00100000,
// Provided by VK_QCOM_image_processing
VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM = 0x00200000,
// Provided by VK_ARM_tensors
VK_IMAGE_USAGE_TENSOR_ALIASING_BIT_ARM = 0x00800000,
// Provided by VK_QCOM_tile_memory_heap
VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM = 0x08000000,
// Provided by VK_KHR_video_encode_quantization_map
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR = 0x02000000,
// Provided by VK_KHR_video_encode_quantization_map
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR = 0x04000000,
// Provided by VK_NV_shading_rate_image
VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV = VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,
// Provided by VK_EXT_host_image_copy
VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT = VK_IMAGE_USAGE_HOST_TRANSFER_BIT,
} 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 the image can be used as a decode output picture in a video decode operation. -
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHRis reserved for future use. -
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHRspecifies that the image can be used as an output reconstructed picture or an input reference picture in a video decode operation. -
VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHRis reserved for future use. -
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHRspecifies that the image can be used as an encode input picture in a video encode operation. -
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHRspecifies that the image can be used as an output reconstructed picture or an input reference picture in a video encode operation. -
VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies that the image can be used as a color or depth/stencil attachment with feedback loop enabled. -
VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOMspecifies that the image can be bound toVkDeviceMemoryallocated from a VkMemoryHeap with theVK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOMproperty. -
VK_IMAGE_USAGE_HOST_TRANSFER_BITspecifies that the image can be used with host copy commands and host layout transitions. -
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHRspecifies that the image can be used as a quantization delta map in a video encode operation. -
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHRspecifies that the image can be used as an emphasis map in a video encode operation. -
VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXTspecifies that the image can be used with host copy commands and host layout transitions. -
VK_IMAGE_USAGE_TENSOR_ALIASING_BIT_ARMspecifies that the image can be transitioned to theVK_IMAGE_LAYOUT_TENSOR_ALIASING_ARMlayout. See Memory Aliasing for a complete set of rules for tensor/image aliasing.
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageUsageFlags;
VkImageUsageFlags is a bitmask type for setting a mask of zero or more
VkImageUsageFlagBits.
When creating a VkImageView one of the following
VkImageUsageFlagBits must be set:
-
VK_IMAGE_USAGE_SAMPLED_BIT -
VK_IMAGE_USAGE_STORAGE_BIT -
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT -
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT -
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT -
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT -
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT -
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR -
VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM -
VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM -
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_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_descriptor_buffer
VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00010000,
// Provided by VK_EXT_multisampled_render_to_single_sampled
VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT = 0x00040000,
// Provided by VK_EXT_image_2d_view_of_3d
VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT = 0x00020000,
// Provided by VK_KHR_video_maintenance1
VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR = 0x00100000,
// Provided by VK_EXT_fragment_density_map_offset
VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_EXT = 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,
// Provided by VK_QCOM_fragment_density_map_offset
VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM = VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_EXT,
} 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_2D_VIEW_COMPATIBLE_BIT_EXTspecifies that the image can be used to create aVkImageViewof typeVK_IMAGE_VIEW_TYPE_2D. -
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_EXTspecifies that an image can be used in a render pass with non-zero fragment density map offsets. In a render pass with non-zero offsets, fragment density map attachments, input attachments, color attachments, depth/stencil attachment, resolve attachments, and preserve attachments must be created withVK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM. -
VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTspecifies that the image can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. -
VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXTspecifies that an image can be used with multisampled rendering as a single-sampled framebuffer attachment -
VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHRspecifies that the image can be used in video coding operations without having to specify at image creation time the set of video profiles the image will be used with, except for images used only as DPB pictures, as long as the image is otherwise compatible with the video profile in question.NoteThis enables exchanging video picture data without additional copies or conversions when used as:
-
Decode output pictures, indifferent of the video profile used to produce them.
-
Encode input pictures, indifferent of the video profile used to consume them.
This includes images created with both
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHRandVK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, which is necessary to use the same video picture as the reconstructed picture and decode output picture in a video decode operation on implementations supportingVK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR.However, images with only DPB usage remain tied to the video profiles the image was created with, as the data layout of such DPB-only images may be implementation- and codec-dependent.
If an application would like to share or reuse the device memory backing such images (e.g. for the purposes of temporal aliasing), then it should create separate image objects for each video profile and bind them to the same underlying device memory range, similar to how memory resources can be shared across separate video sessions or any other memory-backed resource.
-
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_EXTspecifies 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 or QNX
Screen buffer external memory is not known until the image has been bound to
memory, so applications must not call vkGetImageSubresourceLayout for
such an image before it has been bound.
The VkImageSubresource structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageSubresource {
VkImageAspectFlags aspectMask;
uint32_t mipLevel;
uint32_t arrayLayer;
} VkImageSubresource;
-
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_VERSION_1_4
void vkGetImageSubresourceLayout2(
VkDevice device,
VkImage image,
const VkImageSubresource2* pSubresource,
VkSubresourceLayout2* pLayout);
or the equivalent command
// Provided by VK_KHR_maintenance5
void vkGetImageSubresourceLayout2KHR(
VkDevice device,
VkImage image,
const VkImageSubresource2* pSubresource,
VkSubresourceLayout2* pLayout);
or the equivalent command
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
void vkGetImageSubresourceLayout2EXT(
VkDevice device,
VkImage image,
const VkImageSubresource2* pSubresource,
VkSubresourceLayout2* pLayout);
-
deviceis the logical device that owns the image. -
imageis the image whose layout is being queried. -
pSubresourceis a pointer to a VkImageSubresource2 structure selecting a specific image for the image subresource. -
pLayoutis a pointer to a VkSubresourceLayout2 structure in which the layout is returned.
vkGetImageSubresourceLayout2 behaves similarly to
vkGetImageSubresourceLayout, with the ability to specify extended
inputs via chained input structures, and to return extended information via
chained output structures.
It is legal to call vkGetImageSubresourceLayout2 with an image
created with tiling equal to VK_IMAGE_TILING_OPTIMAL, but the
members of VkSubresourceLayout2::subresourceLayout will have
undefined values in this case.
|
Note
|
Structures chained from VkImageSubresource2:: |
The VkImageSubresource2 structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkImageSubresource2 {
VkStructureType sType;
void* pNext;
VkImageSubresource imageSubresource;
} VkImageSubresource2;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkImageSubresource2 VkImageSubresource2KHR;
or the equivalent
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
typedef VkImageSubresource2 VkImageSubresource2EXT;
-
sTypeis a VkStructureType value identifying 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
VkSubresourceLayout2 structure:
// Provided by VK_VERSION_1_4
typedef struct VkSubresourceLayout2 {
VkStructureType sType;
void* pNext;
VkSubresourceLayout subresourceLayout;
} VkSubresourceLayout2;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkSubresourceLayout2 VkSubresourceLayout2KHR;
or the equivalent
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
typedef VkSubresourceLayout2 VkSubresourceLayout2EXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
subresourceLayoutis a VkSubresourceLayout structure.
To query the memory size needed to copy to or from an image using
vkCopyMemoryToImage or vkCopyImageToMemory when the
VK_HOST_IMAGE_COPY_MEMCPY_BIT flag is specified, add a
VkSubresourceHostMemcpySize structure to the pNext chain of the
VkSubresourceLayout2 structure in a call to
vkGetImageSubresourceLayout2.
The VkSubresourceHostMemcpySize structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkSubresourceHostMemcpySize {
VkStructureType sType;
void* pNext;
VkDeviceSize size;
} VkSubresourceHostMemcpySize;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkSubresourceHostMemcpySize VkSubresourceHostMemcpySizeEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sizeis the size in bytes of the image subresource.
To query the memory layout of an image subresource, without an image object, call:
// Provided by VK_VERSION_1_4
void vkGetDeviceImageSubresourceLayout(
VkDevice device,
const VkDeviceImageSubresourceInfo* pInfo,
VkSubresourceLayout2* pLayout);
or the equivalent command
// Provided by VK_KHR_maintenance5
void vkGetDeviceImageSubresourceLayoutKHR(
VkDevice device,
const VkDeviceImageSubresourceInfo* pInfo,
VkSubresourceLayout2* pLayout);
-
deviceis the logical device that owns the image. -
pInfois a pointer to a VkDeviceImageSubresourceInfo structure containing parameters required for the subresource layout query. -
pLayoutis a pointer to a VkSubresourceLayout2 structure in which the layout is returned.
vkGetDeviceImageSubresourceLayout behaves similarly to
vkGetImageSubresourceLayout2, but uses a VkImageCreateInfo
structure to specify the image rather than a VkImage object.
The VkDeviceImageSubresourceInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkDeviceImageSubresourceInfo {
VkStructureType sType;
const void* pNext;
const VkImageCreateInfo* pCreateInfo;
const VkImageSubresource2* pSubresource;
} VkDeviceImageSubresourceInfo;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkDeviceImageSubresourceInfo VkDeviceImageSubresourceInfoKHR;
-
sTypeis a VkStructureType value identifying 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. -
pSubresourcepSubresource is a pointer to a VkImageSubresource2 structure selecting a specific image subresource for the query.
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 a VkStructureType value identifying 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.4.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 a QNX Screen 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 an QNX Screen buffer external format, then its set of format features is the value of VkScreenBufferFormatPropertiesQNX::
formatFeaturesfound by calling vkGetScreenBufferPropertiesQNX on the QNX Screen 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.4.2. Corner-Sampled Images
A corner-sampled image is an image where unnormalized texel coordinates are centered on integer values rather than half-integer values.
A corner-sampled image has a number of differences compared to conventional texture image:
-
Texels are centered on integer coordinates. See Unnormalized Texel Coordinate Operations
-
Normalized coordinates are scaled using coord × (dim - 1) rather than coord × dim, where dim is the size of one dimension of the image. See normalized texel coordinate transform.
-
Partial derivatives are scaled using coord × (dim - 1) rather than coord × dim. See Scale Factor Operation.
-
Calculation of the next higher LOD size goes according to ⌈dim / 2⌉ rather than ⌊dim / 2⌋. See Image Mip Level Sizing.
-
The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. See Image Mip Level Sizing.
Corner-sampling is only supported for 2D and 3D images.
When sampling a corner-sampled image, the sampler addressing mode must be
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
Corner-sampled images are not supported as cube maps or depth/stencil
images.
12.4.3. Image Mip Level Sizing
A complete mipmap chain is the full set of mip levels, from the largest mip level provided, down to the minimum mip level size.
Conventional Images
For conventional images, the dimensions of each successive mip level, n+1, are:
-
widthn+1 = max(⌊widthn/2⌋, 1) -
heightn+1 = max(⌊heightn/2⌋, 1) -
depthn+1 = max(⌊depthn/2⌋, 1)
where widthn, heightn, and depthn
are the dimensions of the next larger mip level, n.
The minimum mip level size is:
-
1 for one-dimensional images,
-
1x1 for two-dimensional images, and
-
1x1x1 for three-dimensional images.
The number of levels in a complete mipmap chain is:
-
⌊log2(max(
width0,height0,depth0))⌋ + 1
where width0, height0, and depth0
are the dimensions of the largest (most detailed) mip level, 0.
Corner-Sampled Images
For corner-sampled images, the dimensions of each successive mip level, n+1, are:
-
widthn+1 = max(⌈widthn/2⌉, 2) -
heightn+1 = max(⌈heightn/2⌉, 2) -
depthn+1 = max(⌈depthn/2⌉, 2)
where widthn, heightn, and depthn
are the dimensions of the next larger mip level, n.
The minimum mip level size is:
-
2x2 for two-dimensional images, and
-
2x2x2 for three-dimensional images.
The number of levels in a complete mipmap chain is:
-
⌈log2(max(
width0,height0,depth0))⌉
where width0, height0, and depth0
are the dimensions of the largest (most detailed) mip level, 0.
12.5. 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.
When an VkImageView descriptor is accessed on the device, all image
subresources must be in a valid image layout.
|
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_ZERO_INITIALIZED_EXT 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_ZERO_INITIALIZED_EXT, then the image data is
interpreted to be zeroed.
If the memory bound to this image is not fully zeroed when the image is
transitioned to a different layout, the results are undefined.
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 any of the following layouts:
-
VK_IMAGE_LAYOUT_PREINITIALIZED -
VK_IMAGE_LAYOUT_GENERAL -
VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT
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_VERSION_1_4
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ = 1000232000,
// Provided by VK_KHR_swapchain
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR = 1000001002,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR = 1000024000,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR = 1000024001,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR = 1000024002,
// Provided by VK_KHR_shared_presentable_image
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR = 1000111000,
// Provided by VK_EXT_fragment_density_map
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT = 1000218000,
// Provided by VK_KHR_fragment_shading_rate
VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR = 1000164003,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR = 1000299000,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR = 1000299001,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR = 1000299002,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT = 1000339000,
// Provided by VK_ARM_tensors
VK_IMAGE_LAYOUT_TENSOR_ALIASING_ARM = 1000460000,
// Provided by VK_KHR_video_encode_quantization_map
VK_IMAGE_LAYOUT_VIDEO_ENCODE_QUANTIZATION_MAP_KHR = 1000553000,
// Provided by VK_EXT_zero_initialize_device_memory
VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT = 1000620000,
// 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_dynamic_rendering_local_read
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR = VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ,
// 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, unless specified otherwise. -
VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXTspecifies that an image’s memory is in a defined layout and is zeroed, 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 already zeroed, either from being explicitly set to zero by an application or from being allocated withVK_MEMORY_ALLOCATE_ZERO_INITIALIZE_BIT_EXT. -
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. -
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 picture in a video decode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_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 an output reconstructed picture or an input reference picture in a video decode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_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 an encode input picture in a video encode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHRmust only be used as an output reconstructed picture or an input reference picture in a video encode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXTmust only be used as either a color attachment or depth/stencil attachment and/or read-only access in a shader as a sampled image, combined image/sampler, or input attachment. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTusage bit enabled and either theVK_IMAGE_USAGE_COLOR_ATTACHMENT_BITorVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BITand either theVK_IMAGE_USAGE_INPUT_ATTACHMENT_BITorVK_IMAGE_USAGE_SAMPLED_BITusage bits enabled. -
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READmust only be used as either a storage image, or a color or depth/stencil attachment and an input attachment. This layout is valid only for image subresources of images created with eitherVK_IMAGE_USAGE_STORAGE_BIT, or bothVK_IMAGE_USAGE_INPUT_ATTACHMENT_BITand either ofVK_IMAGE_USAGE_COLOR_ATTACHMENT_BITorVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT. -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_QUANTIZATION_MAP_KHRmust only be used as a quantization map in a video encode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHRorVK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_TENSOR_ALIASING_ARMspecifies the layout that an image created withVK_IMAGE_TILING_OPTIMALmust be in for it and a tensor bound to the same aliased range of memory to consistently interpret the data in memory. See Memory Aliasing for a complete set of rules for tensor/image aliasing. This layout is valid only for image subresources of images created withVK_IMAGE_USAGE_TENSOR_ALIASING_BIT_ARM.
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).
If the unifiedImageLayouts feature
is enabled, the VK_IMAGE_LAYOUT_GENERAL image layout may be used in
place of the other layouts where allowed with no loss of performance.
|
Note
|
|
|
Note
|
While |
12.5.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 any of:
-
VK_IMAGE_LAYOUT_UNDEFINED -
VK_IMAGE_LAYOUT_PREINITIALIZED -
VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT
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.6. 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 a VkImageViewCreateInfo structure 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkImageViewCreateFlagBits specifying 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 specifying the format and type used to interpret texel blocks of 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 overridden by adding a
VkImageViewUsageCreateInfo structure to the pNext chain, but the
view usage must be a subset of the image usage.
If image has a depth-stencil format and was created with a
VkImageStencilUsageCreateInfo structure included in the pNext
chain of VkImageCreateInfo, the usage is calculated based on the
subresource.aspectMask provided:
-
If
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 is a 3D image, its Z range can be restricted to a subset by
adding a VkImageViewSlicedCreateInfoEXT to the pNext chain.
If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
flag,
and if the format of the image is not multi-planar
format can be different from the image’s format, but if
image was created without the
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and
they are not equal they must be compatible.
Image format compatibility is defined in the
Format Compatibility Classes section.
Views of compatible formats will have the same mapping between texel
coordinates and memory locations irrespective of the format, with only
the interpretation of the bit pattern changing.
If image was created with a multi-planar
format, and the image view’s aspectMask is one of
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or
VK_IMAGE_ASPECT_PLANE_2_BIT, the view’s aspect mask is considered to
be equivalent to VK_IMAGE_ASPECT_COLOR_BIT when used as a framebuffer
attachment.
|
Note
|
Values intended to be used with one view format may not be exactly preserved when written or read through a different format. For example, an integer value that happens to have the bit pattern of a floating-point denorm or NaN may be flushed or canonicalized when written or read through a view with a floating-point format. Similarly, a value written through a signed normalized format that has a bit pattern exactly equal to -2b may be changed to -2b + 1 as described in Conversion from Normalized Fixed-Point to Floating-Point. |
If image was created with the
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, format
must be compatible with the image’s format as described above; or must
be an uncompressed format, in which case it must be
size-compatible with the image’s format.
In this case, the resulting image view’s texel dimensions equal the
dimensions of the selected mip level divided by the compressed texel block
size and rounded up.
The VkComponentMapping components member describes a remapping
from components of the image to components of the vector returned by shader
image instructions.
This remapping must be the identity swizzle for storage image descriptors,
input attachment descriptors,
framebuffer attachments, and any VkImageView used with a combined
image sampler that enables sampler Y′CBCR
conversion.
If the image view is to be used with a sampler which supports
sampler Y′CBCR conversion, an identically
defined object of type VkSamplerYcbcrConversion to that used to
create the sampler must be passed to vkCreateImageView in a
VkSamplerYcbcrConversionInfo included in the pNext chain of
VkImageViewCreateInfo.
Conversely, if a VkSamplerYcbcrConversion object is passed to
vkCreateImageView, an identically
defined VkSamplerYcbcrConversion object must be used when sampling
the image.
If the image has a multi-planar format,
subresourceRange.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, and
usage includes VK_IMAGE_USAGE_SAMPLED_BIT, then the format
must be identical to the image format and the sampler to be used with
the image view must enable sampler Y′CBCR
conversion.
When such an image is used in a video coding operation, the sampler Y′CBCR conversion has no effect.
If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
and the image has a multi-planar format, and if
subresourceRange.aspectMask is VK_IMAGE_ASPECT_PLANE_0_BIT,
VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT,
format must be compatible with the
corresponding plane of the image, and the sampler to be used with the image
view must not enable sampler Y′CBCR
conversion.
The width and height of the single-plane image view must be
derived from the multi-planar image’s dimensions in the manner listed for
plane compatibility for the plane.
Any view of an image plane will have the same mapping between texel coordinates and memory locations as used by the components of the color aspect, subject to the formulae relating texel coordinates to lower-resolution planes as described in Chroma Reconstruction. That is, if an R or B plane has a reduced resolution relative to the G plane of the multi-planar image, the image view operates using the (uplane, vplane) unnormalized coordinates of the reduced-resolution plane, and these coordinates access the same memory locations as the (ucolor, vcolor) unnormalized coordinates of the color aspect for which chroma reconstruction operations operate on the same (uplane, vplane) or (iplane, jplane) coordinates.
| Image View Type | Compatible Image Types |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Bits which can be set in VkImageViewCreateInfo::flags,
specifying additional parameters of an image view, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageViewCreateFlagBits {
// Provided by VK_EXT_fragment_density_map
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT = 0x00000001,
// Provided by VK_EXT_descriptor_buffer
VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000004,
// Provided by VK_EXT_fragment_density_map2
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT = 0x00000002,
} VkImageViewCreateFlagBits;
-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_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 -
VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTspecifies that the image view can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail.
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageViewCreateFlags;
VkImageViewCreateFlags is a bitmask type for setting a mask of zero or
more VkImageViewCreateFlagBits.
The set of usages for the created image view can be restricted compared to
the parent image’s usage flags by adding a
VkImageViewUsageCreateInfo structure to the pNext chain of
VkImageViewCreateInfo.
The VkImageViewUsageCreateInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImageViewUsageCreateInfo {
VkStructureType sType;
const void* pNext;
VkImageUsageFlags usage;
} VkImageViewUsageCreateInfo;
or the equivalent
// Provided by VK_KHR_maintenance2
typedef VkImageViewUsageCreateInfo VkImageViewUsageCreateInfoKHR;
-
sTypeis a VkStructureType value identifying 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 range of 3D slices for the created image view can be restricted to a
subset of the parent image’s Z range by adding a
VkImageViewSlicedCreateInfoEXT structure to the pNext chain of
VkImageViewCreateInfo.
The VkImageViewSlicedCreateInfoEXT structure is defined as:
// Provided by VK_EXT_image_sliced_view_of_3d
typedef struct VkImageViewSlicedCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t sliceOffset;
uint32_t sliceCount;
} VkImageViewSlicedCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sliceOffsetis the Z-offset for the first 3D slice accessible to the image view. -
sliceCountis the number of 3D slices accessible to the image view.
When this structure is chained to VkImageViewCreateInfo the
sliceOffset field is treated as a Z-offset for the sliced view and
sliceCount specifies the range.
Shader accesses using a Z coordinate of 0 will access the depth slice
corresponding to sliceOffset in the image, and in a shader, the
maximum in-bounds Z coordinate for the view is sliceCount - 1.
A sliced 3D view must only be used with a single mip level.
The slice coordinates are integer coordinates within the
subresourceRange.baseMipLevel used to create the image view.
The effective view depth is equal to extent.depth used to create the
image for this view adjusted by subresourceRange.baseMipLevel as
specified in Image Mip Level Sizing.
Shader access to this image view is only affected by
VkImageViewSlicedCreateInfoEXT if it uses a descriptor of type
VK_DESCRIPTOR_TYPE_STORAGE_IMAGE.
For access using any other descriptor type, the contents of
VkImageViewSlicedCreateInfoEXT are ignored; instead, sliceOffset
is treated as being equal to 0, and sliceCount is treated as being
equal to VK_REMAINING_3D_SLICES_EXT.
VK_REMAINING_3D_SLICES_EXT is a special constant value used for
VkImageViewSlicedCreateInfoEXT::sliceCount to indicate that all
remaining 3D slices in an image after the first slice offset specified
should be included in the view.
#define VK_REMAINING_3D_SLICES_EXT (~0U)
The VkImageSubresourceRange structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageSubresourceRange {
VkImageAspectFlags aspectMask;
uint32_t baseMipLevel;
uint32_t levelCount;
uint32_t baseArrayLayer;
uint32_t layerCount;
} VkImageSubresourceRange;
-
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.
If the maintenance9 feature is not enabled,
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 format, 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 a VkStructureType value identifying 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.
If the pNext chain includes a
VkImageViewSampleWeightCreateInfoQCOM structure, then that structure
includes a parameter specifying the parameters for weight image views used
in weight image sampling.
The VkImageViewSampleWeightCreateInfoQCOM structure is defined as:
// Provided by VK_QCOM_image_processing
typedef struct VkImageViewSampleWeightCreateInfoQCOM {
VkStructureType sType;
const void* pNext;
VkOffset2D filterCenter;
VkExtent2D filterSize;
uint32_t numPhases;
} VkImageViewSampleWeightCreateInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
filterCenteris a VkOffset2D describing the location of the weight filter origin. -
filterSizeis a VkExtent2D specifying weight filter dimensions. -
numPhasesis number of sub-pixel filter phases.
The filterCenter specifies the origin or center of the filter kernel,
as described in Weight Sampling
Operation.
The numPhases describes the number of sub-pixel filter phases as
described in Weight Sampling Phases.
To destroy an image view, call:
// Provided by VK_VERSION_1_0
void vkDestroyImageView(
VkDevice device,
VkImageView imageView,
const VkAllocationCallbacks* pAllocator);
-
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.
To get the 64-bit handle for an image view, call:
// Provided by VK_NVX_image_view_handle
uint64_t vkGetImageViewHandle64NVX(
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.6.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 supported, 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 supported, 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 and theshaderStorageImageReadWithoutFormatfeature is enabled. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITif the format is one of the extended storage formats and theshaderStorageImageWriteWithoutFormatfeature is enabled.
-
-
If Vulkan 1.3 is supported or the
VK_KHR_format_feature_flags2extension is supported, and VkImageViewCreateInfo::imagewas created withVK_IMAGE_TILING_OPTIMAL, but without an Android hardware buffer external format, or a QNX Screen 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 supported, and VkImageViewCreateInfo::imagewas created withVK_IMAGE_TILING_OPTIMAL, but without an Android hardware buffer external format, or a QNX Screen 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 and theshaderStorageImageReadWithoutFormatfeature is enabled. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITif the format is one of the extended storage formats and theshaderStorageImageWriteWithoutFormatfeature is enabled.
-
-
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 QNX Screen buffer external format, then the image views’s set of format features is the value of VkScreenBufferFormatPropertiesQNX::formatFeaturesfound by calling vkGetScreenBufferPropertiesQNX on the QNX Screen 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.
-
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minLodis the value to clamp the minimum LOD accessible by this VkImageView.
If the pNext chain includes a VkImageViewMinLodCreateInfoEXT
structure, then that structure includes a parameter specifying a value to
clamp the minimum LOD value during Image
Level(s) Selection, Texel Gathering and
Integer Texel Coordinate
Operations.
If the image view contains VkImageViewMinLodCreateInfoEXT and it is
used as part of a sampling operation:
minLodFloatimageView = minLod
otherwise:
minLodFloatimageView = 0.0
An integer variant of this parameter is also defined for sampling operations which access integer mipmap levels:
minLodIntegerimageView = ⌊minLodFloatimageView⌋
12.7. 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 these extensions, 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 for the VK_KHR_acceleration_structure
extension are represented by VkAccelerationStructureKHR handles:
// Provided by VK_KHR_acceleration_structure
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkAccelerationStructureKHR)
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.
The acceleration structure data is stored in the object referred to by
VkAccelerationStructureCreateInfoKHR::buffer.
Once memory has been bound to that buffer, it must be populated by
acceleration structure build or acceleration structure copy commands such as
vkCmdBuildAccelerationStructuresKHR,
vkBuildAccelerationStructuresKHR,
vkCmdCopyAccelerationStructureKHR, and
vkCopyAccelerationStructureKHR.
|
Note
|
The expected usage for a trace capture/replay tool is that it will serialize
and later deserialize the acceleration structure data using acceleration
structure copy commands.
During capture the tool will use
vkCopyAccelerationStructureToMemoryKHR or
vkCmdCopyAccelerationStructureToMemoryKHR with a |
|
Note
|
Memory does not need to be bound to the underlying buffer when vkCreateAccelerationStructureKHR is called. |
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 can reuse 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 a VkStructureType value identifying 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, obtained from vkGetAccelerationStructureDeviceAddressKHR, if theaccelerationStructureCaptureReplayfeature is being used. IfdeviceAddressis zero, no specific address is requested.
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.
Applications and tools should avoid mixing application-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.
|
Note
|
|
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 createFlags
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 a VkStructureType value identifying 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 or VkDeviceOrHostAddressConstKHR
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 element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, if thepNextchain contains VkAccelerationStructureTrianglesOpacityMicromapEXT the corresponding member ofpBuildInfoalso contains VkAccelerationStructureTrianglesOpacityMicromapEXT and with an equivalentmicromap. -
For each element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, if thepNextchain contains VkAccelerationStructureTrianglesDisplacementMicromapNV the corresponding member ofpBuildInfoalso contains VkAccelerationStructureTrianglesDisplacementMicromapNV and with an equivalentmicromap.
-
-
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 a VkStructureType value identifying 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.
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.
Once memory has been bound to the acceleration structure using vkBindAccelerationStructureMemoryNV, that memory is populated by calls to vkCmdBuildAccelerationStructureNV and vkCmdCopyAccelerationStructureNV.
Acceleration structure creation uses the count and type information from the geometries, but does not use the data references in the structures.
The VkAccelerationStructureCreateInfoNV structure is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkDeviceSize compactedSize;
VkAccelerationStructureInfoNV info;
} VkAccelerationStructureCreateInfoNV;
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying 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.
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. In these cases, the acceleration structure type is not known at creation time, but must be specified at build time as either top or bottom.
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_EXT_descriptor_buffer
VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000008,
// 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. -
VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTspecifies that the acceleration structure can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. -
VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NVspecifies that the acceleration structure will be used with motion information, see VkAccelerationStructureMotionInfoNV for more detail.
// 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_EXT_opacity_micromap
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_EXT = 0x00000040,
// Provided by VK_EXT_opacity_micromap
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_EXT = 0x00000080,
// Provided by VK_EXT_opacity_micromap
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT = 0x00000100,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_BIT_NV = 0x00000200,
#endif
// Provided by VK_KHR_ray_tracing_position_fetch
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_BIT_KHR = 0x00000800,
// 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,
// Provided by VK_EXT_opacity_micromap
// VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT is a deprecated alias
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_EXT,
// Provided by VK_EXT_opacity_micromap
// VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXT is a deprecated alias
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXT = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_EXT,
// Provided by VK_EXT_opacity_micromap
// VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT is a deprecated alias
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
// VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV is a deprecated alias
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_BIT_NV,
#endif
// Provided by VK_KHR_ray_tracing_position_fetch
// VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR is a deprecated alias
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_BIT_KHR,
} VkBuildAccelerationStructureFlagBitsKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkBuildAccelerationStructureFlagBitsKHR VkBuildAccelerationStructureFlagBitsNV;
-
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHRspecifies that the specified acceleration structure can be updated with amodeofVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHRin VkAccelerationStructureBuildGeometryInfoKHR or anupdateofVK_TRUEin vkCmdBuildAccelerationStructureNV . For sphere and LSS primitives, only positions and radii may be updated, the provided index buffers and flags must remain unchanged from the initial build. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHRspecifies 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_KHRspecifies that the given acceleration structure build should prioritize trace performance over build time. -
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHRspecifies that the given acceleration structure build should prioritize build time over trace performance. -
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHRspecifies 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. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_EXTspecifies that the opacity micromaps associated with the specified acceleration structure may change with an acceleration structure update. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXTspecifies that the data of the opacity micromaps associated with the specified acceleration structure may change with an acceleration structure update. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_EXTspecifies that the specified acceleration structure may be referenced in an instance withVK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_BIT_EXTset. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_BIT_KHRspecifies that the specified acceleration structure can be used when fetching the vertex and radius positions of a hit LSS or sphere primitive, or vertex positions of a hit triangle. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_BIT_NVspecifies that the displacement micromaps associated with the specified acceleration structure may change with an acceleration structure update.
|
Note
|
|
|
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 a VkStructureType value identifying 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_linear_swept_spheres
VK_GEOMETRY_TYPE_SPHERES_NV = 1000429004,
// Provided by VK_NV_ray_tracing_linear_swept_spheres
VK_GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV = 1000429005,
// 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. -
VK_GEOMETRY_TYPE_SPHERES_NVspecifies a geometry type consisting of spheres. -
VK_GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NVspecifies a geometry type consisting of linear swept spheres.
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_KHRspecifies 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_KHRspecifies 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 specifies 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 an 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 an application-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.
The returned address must be aligned to 256 bytes.
|
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructurespecifies the acceleration structure whose address is being queried.
12.8. Micromaps
Micromaps are opaque data structures that are built by the implementation to encode sub-triangle data to be included in an acceleration structure.
Micromaps are represented by VkMicromapEXT handles:
// Provided by VK_EXT_opacity_micromap
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkMicromapEXT)
To create a micromap, call:
// Provided by VK_EXT_opacity_micromap
VkResult vkCreateMicromapEXT(
VkDevice device,
const VkMicromapCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkMicromapEXT* pMicromap);
-
deviceis the logical device that creates the micromap object. -
pCreateInfois a pointer to a VkMicromapCreateInfoEXT structure containing parameters affecting creation of the micromap. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pMicromapis a pointer to a VkMicromapEXT handle in which the resulting micromap object is returned.
Similar to other objects in Vulkan, the micromap creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into a micromap is determined by the parameters of VkMicromapCreateInfoEXT.
The micromap data is stored in the object referred to by
VkMicromapCreateInfoEXT::buffer.
Once memory has been bound to that buffer, it must be populated by micromap
build or micromap copy commands such as vkCmdBuildMicromapsEXT,
vkBuildMicromapsEXT, vkCmdCopyMicromapEXT, and
vkCopyMicromapEXT.
|
Note
|
The expected usage for a trace capture/replay tool is that it will serialize
and later deserialize the micromap data using micromap copy commands.
During capture the tool will use vkCopyMicromapToMemoryEXT or
vkCmdCopyMicromapToMemoryEXT with a |
The input buffers passed to micromap build commands will be referenced by the implementation for the duration of the command. Micromaps must be fully self-contained. The application can reuse or free any memory which was used by the command as an input or as scratch without affecting the results of a subsequent acceleration structure build using the micromap or traversal of that acceleration structure.
The VkMicromapCreateInfoEXT structure is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkMicromapCreateFlagsEXT createFlags;
VkBuffer buffer;
VkDeviceSize offset;
VkDeviceSize size;
VkMicromapTypeEXT type;
VkDeviceAddress deviceAddress;
} VkMicromapCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
createFlagsis a bitmask of VkMicromapCreateFlagBitsEXT specifying additional creation parameters of the micromap. -
bufferis the buffer on which the micromap will be stored. -
offsetis an offset in bytes from the base address of the buffer at which the micromap will be stored, and must be a multiple of256. -
sizeis the size required for the micromap. -
typeis a VkMicromapTypeEXT value specifying the type of micromap that will be created. -
deviceAddressis the device address requested for the micromap if themicromapCaptureReplayfeature 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 micromap on the same implementation.
The micromap must also be placed on an identically created buffer and
at the same offset.
Applications should avoid creating micromaps 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.
Applications and tools should avoid mixing application-provided and
implementation-provided addresses for buffers created with
|
If the micromap will be the target of a build operation, the required size for a micromap can be queried with vkGetMicromapBuildSizesEXT.
To get the build sizes for a micromap, call:
// Provided by VK_EXT_opacity_micromap
void vkGetMicromapBuildSizesEXT(
VkDevice device,
VkAccelerationStructureBuildTypeKHR buildType,
const VkMicromapBuildInfoEXT* pBuildInfo,
VkMicromapBuildSizesInfoEXT* pSizeInfo);
-
deviceis the logical device that will be used for creating the micromap. -
buildTypedefines whether host or device operations (or both) are being queried for. -
pBuildInfois a pointer to a VkMicromapBuildInfoEXT structure describing parameters of a build operation. -
pSizeInfois a pointer to a VkMicromapBuildSizesInfoEXT structure which returns the size required for a micromap and the sizes required for the scratch buffers, given the build parameters.
The dstMicromap and mode members of pBuildInfo are
ignored.
Any VkDeviceOrHostAddressKHR members of pBuildInfo are ignored
by this command.
A micromap created with the micromapSize returned by this command
supports any build with a VkMicromapBuildInfoEXT structure 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 -
-
Its
type, andflagsmembers are equal topBuildInfo->typeandpBuildInfo->flags, respectively. -
The sum of usage information in either
pUsageCountsorppUsageCountsis equal to the sum of usage information in eitherpBuildInfo->pUsageCountsorpBuildInfo->ppUsageCounts.
-
Similarly, the buildScratchSize value will support any build command
specifying the VK_BUILD_MICROMAP_MODE_BUILD_EXT mode under the
above conditions.
The VkMicromapBuildSizesInfoEXT structure describes the required build
sizes for a micromap and scratch buffers and is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapBuildSizesInfoEXT {
VkStructureType sType;
const void* pNext;
VkDeviceSize micromapSize;
VkDeviceSize buildScratchSize;
VkBool32 discardable;
} VkMicromapBuildSizesInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
micromapSizeis the size in bytes required in a VkMicromapEXT for a build or update operation. -
buildScratchSizeis the size in bytes required in a scratch buffer for a build operation. -
discardableindicates whether or not the micromap object may be destroyed after an acceleration structure build or update. A false value means that acceleration structures built with this micromap may contain references to the data contained therein, and the application must not destroy the micromap until ray traversal has concluded. A true value means that the information in the micromap will be copied by value into the acceleration structure, and the micromap may be destroyed after the acceleration structure build concludes.
Values which can be set in VkMicromapCreateInfoEXT::type
specifying the type of micromap, are:
// Provided by VK_EXT_opacity_micromap
typedef enum VkMicromapTypeEXT {
VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT = 0,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV = 1000397000,
#endif
} VkMicromapTypeEXT;
-
VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXTis a micromap containing data to control the opacity of a triangle. -
VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NVis a micromap containing data to control the displacement of subtriangles within a triangle.
Bits which can be set in VkMicromapCreateInfoEXT::createFlags,
specifying additional creation parameters for micromaps, are:
// Provided by VK_EXT_opacity_micromap
typedef enum VkMicromapCreateFlagBitsEXT {
VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT = 0x00000001,
} VkMicromapCreateFlagBitsEXT;
-
VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXTspecifies that the micromap’s address can be saved and reused on a subsequent run.
// Provided by VK_EXT_opacity_micromap
typedef VkFlags VkMicromapCreateFlagsEXT;
VkMicromapCreateFlagsEXT is a bitmask type for setting a mask of zero
or more VkMicromapCreateFlagBitsEXT.
Bits which can be set in VkMicromapBuildInfoEXT::flags
specifying additional parameters for micromap builds, are:
// Provided by VK_EXT_opacity_micromap
typedef enum VkBuildMicromapFlagBitsEXT {
VK_BUILD_MICROMAP_PREFER_FAST_TRACE_BIT_EXT = 0x00000001,
VK_BUILD_MICROMAP_PREFER_FAST_BUILD_BIT_EXT = 0x00000002,
VK_BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT = 0x00000004,
} VkBuildMicromapFlagBitsEXT;
-
VK_BUILD_MICROMAP_PREFER_FAST_TRACE_BIT_EXTspecifies that the given micromap build should prioritize trace performance over build time. -
VK_BUILD_MICROMAP_PREFER_FAST_BUILD_BIT_EXTspecifies that the given micromap build should prioritize build time over trace performance.
// Provided by VK_EXT_opacity_micromap
typedef VkFlags VkBuildMicromapFlagsEXT;
VkBuildMicromapFlagsEXT is a bitmask type for setting a mask of zero
or more VkBuildMicromapFlagBitsEXT.
To destroy a micromap, call:
// Provided by VK_EXT_opacity_micromap
void vkDestroyMicromapEXT(
VkDevice device,
VkMicromapEXT micromap,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the micromap. -
micromapis the micromap to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
12.9. 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 buffer, image, or tensor 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.
To determine the memory requirements for a tensor resource, call:
// Provided by VK_ARM_tensors
void vkGetTensorMemoryRequirementsARM(
VkDevice device,
const VkTensorMemoryRequirementsInfoARM* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device that owns the tensor. -
pInfois a pointer to a VkTensorMemoryRequirementsInfoARM structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the tensor object are returned.
The VkTensorMemoryRequirementsInfoARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkTensorMemoryRequirementsInfoARM {
VkStructureType sType;
const void* pNext;
VkTensorARM tensor;
} VkTensorMemoryRequirementsInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensoris the tensor to query.
To determine the memory requirements for a tensor resource without creating an object, call:
// Provided by VK_ARM_tensors
void vkGetDeviceTensorMemoryRequirementsARM(
VkDevice device,
const VkDeviceTensorMemoryRequirementsARM* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device intended to own the tensor. -
pInfois a pointer to a VkDeviceTensorMemoryRequirementsARM structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the tensor object are returned.
The VkDeviceTensorMemoryRequirementsARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkDeviceTensorMemoryRequirementsARM {
VkStructureType sType;
const void* pNext;
const VkTensorCreateInfoARM* pCreateInfo;
} VkDeviceTensorMemoryRequirementsARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pCreateInfois a pointer to a VkTensorCreateInfoARM structure containing parameters affecting the creation of the tensor to query.
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 a 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.
The value of size has no meaning and should be ignored if the
resource being queried was created with any of the following external memory
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_MTLTEXTURE_BIT_EXT
The implementation guarantees certain properties about the memory requirements returned by vkGetBufferMemoryRequirements2, vkGetImageMemoryRequirements2, vkGetDeviceBufferMemoryRequirements, vkGetDeviceImageMemoryRequirements, vkGetDeviceTensorMemoryRequirementsARM, vkGetTensorMemoryRequirementsARM, vkGetBufferMemoryRequirements and vkGetImageMemoryRequirements:
-
The
memoryTypeBitsmember always contains at least one bit set. -
If
bufferis aVkBuffernot created with theVK_BUFFER_CREATE_SPARSE_BINDING_BITorVK_BUFFER_CREATE_PROTECTED_BITbits set, or ifimageis a linear image that was not created with theVK_IMAGE_CREATE_PROTECTED_BITbit set, or iftensoris aVkTensorARMnot created with theVK_TENSOR_CREATE_PROTECTED_BIT_ARM, 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, ortensorwas created with VkExternalMemoryTensorCreateInfoARM::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 andVK_IMAGE_CREATE_PROTECTED_BITbit of theflagsmember, theVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BITbit of theflagsmember, theVK_IMAGE_USAGE_HOST_TRANSFER_BITbit of theusagemember if the VkPhysicalDeviceHostImageCopyProperties::identicalMemoryTypeRequirementsproperty isVK_FALSE,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 andVK_IMAGE_CREATE_PROTECTED_BITbit of theflagsmember, theVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BITbit of theflagsmember, theVK_IMAGE_USAGE_HOST_TRANSFER_BITbit of theusagemember if the VkPhysicalDeviceHostImageCopyProperties::identicalMemoryTypeRequirementsproperty isVK_FALSE,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. -
If the memory requirements are for a
VkTensorARM, 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. -
The
sizemember is identical for allVkTensorARMobjects created with the same combination of creation parameters specified inVkTensorCreateInfoARMand 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. -
The memory requirements returned by vkGetDeviceTensorMemoryRequirementsARM are identical to those that would be returned by vkGetTensorMemoryRequirementsARM if it were called with a
VkTensorARMcreated with the same VkTensorCreateInfoARM values, including additional values provided via a VkExternalMemoryTensorCreateInfoARM structure.
-
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
To determine the tile memory allocation requirements of a buffer or image
resource, add a VkTileMemoryRequirementsQCOM structure to the
pNext chain of the VkMemoryRequirements2 structure passed as the
pMemoryRequirements parameter of vkGetBufferMemoryRequirements2
or vkGetImageMemoryRequirements2, respectively.
The VkTileMemoryRequirementsQCOM structure is defined as:
// Provided by VK_QCOM_tile_memory_heap
typedef struct VkTileMemoryRequirementsQCOM {
VkStructureType sType;
void* pNext;
VkDeviceSize size;
VkDeviceSize alignment;
} VkTileMemoryRequirementsQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sizesize is the size, in bytes, of the tile memory allocation required for the resource. -
alignmentis the alignment, in bytes, of the offset within the tile memory allocation required for the resource.
The size and alignment must be used when the resource is bound
to a VkDeviceMemory object that was allocated from a
VkMemoryType that has a heapIndex that corresponds to a
VkMemoryHeap with the VK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOM
property.
If the resource cannot be bound to tile memory, then size and
alignment is filled with zero by the implementation.
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 with VK_KHR_get_memory_requirements2 or VK_VERSION_1_1
typedef VkMemoryRequirements2 VkMemoryRequirements2KHR;
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying 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
or tensor
resource, add a VkMemoryDedicatedRequirements structure to the
pNext chain of the VkMemoryRequirements2 structure passed as the
pMemoryRequirements parameter of vkGetBufferMemoryRequirements2
or vkGetImageMemoryRequirements2,
or vkGetTensorMemoryRequirementsARM,
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. -
requiresDedicatedAllocationmay beVK_TRUEif the image’s tiling isVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. -
requiresDedicatedAllocationwill otherwise beVK_FALSE -
If
VK_IMAGE_CREATE_SPARSE_BINDING_BITwas set in VkImageCreateInfo::flagswhenimagewas created, then bothprefersDedicatedAllocationandrequiresDedicatedAllocationwill beVK_FALSE.
Constraints on the values returned for tensor resources are:
-
requiresDedicatedAllocationmay beVK_TRUEif thepNextchain of VkTensorCreateInfoARM for the call tovkCreateTensorARMused to create the tensor being queried included a VkExternalMemoryTensorCreateInfoARM structure, and any of the handle types specified in VkExternalMemoryTensorCreateInfoARM::handleTypesrequires dedicated allocation, as reported by vkGetPhysicalDeviceExternalTensorPropertiesARM inVkExternalTensorPropertiesARM::externalMemoryProperties.externalMemoryFeatures. -
requiresDedicatedAllocationwill otherwise beVK_FALSE. -
When the implementation sets
requiresDedicatedAllocationtoVK_TRUE, it must also setprefersDedicatedAllocationtoVK_TRUE.
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.
If the maintenance6 feature is enabled,
this command must attempt to perform all of the memory binding operations
described by pBindInfos, and must not early exit on the first
failure.
If any of the memory binding operations described by pBindInfos fail,
the VkResult returned by this command must be the return value of any
one of the memory binding operations which did not return VK_SUCCESS.
|
Note
|
If the Applications should destroy these buffers. |
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
The VkBindMemoryStatus structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkBindMemoryStatus {
VkStructureType sType;
const void* pNext;
VkResult* pResult;
} VkBindMemoryStatus;
or the equivalent
// Provided by VK_KHR_maintenance6
typedef VkBindMemoryStatus VkBindMemoryStatusKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pResultis a pointer to aVkResultvalue.
If the pNext chain of VkBindBufferMemoryInfo or
VkBindImageMemoryInfo includes a VkBindMemoryStatus structure,
then the VkBindMemoryStatus::pResult will be populated with a
value describing the result of the corresponding memory binding operation.
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.
If the maintenance6 feature is enabled,
this command must attempt to perform all of the memory binding operations
described by pBindInfos, and must not early exit on the first
failure.
If any of the memory binding operations described by pBindInfos fail,
the VkResult returned by this command must be the return value of any
one of the memory binding operations which did not return VK_SUCCESS.
|
Note
|
If the Applications should destroy these images. |
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
planeAspectis aVkImageAspectFlagBitsvalue specifying the aspect of the disjoint image plane to bind.
To attach memory to tensor objects call:
// Provided by VK_ARM_tensors
VkResult vkBindTensorMemoryARM(
VkDevice device,
uint32_t bindInfoCount,
const VkBindTensorMemoryInfoARM* pBindInfos);
-
deviceis the logical device that owns the buffers and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array of structures of type VkBindTensorMemoryInfoARM, describing tensors and memory to bind.
On some implementations, it may be more efficient to batch memory bindings into a single command.
The VkBindTensorMemoryInfoARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkBindTensorMemoryInfoARM {
VkStructureType sType;
const void* pNext;
VkTensorARM tensor;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
} VkBindTensorMemoryInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensoris the tensor 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 tensor. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified tensor.
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.
|
Note
|
The implementation-dependent limit, |
12.10. 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,
unless the maintenance9 feature is enabled,
the application must perform a queue
family ownership transfer if it wishes to make the memory contents of a
range or image subresource accessible to a different queue family.
VK_SHARING_MODE_EXCLUSIVE resources that are already owned by a queue
family may be acquired by a different queue family without a queue family
ownership transfer, but
unless the maintenance9 feature is enabled,
their contents become undefined.
If the maintenance9 feature is enabled, the
contents of buffer resources, and of linear image resources (i.e., those
created with tiling set to VK_IMAGE_TILING_LINEAR) are always
preserved when they are implicitly acquired by a different queue family on
the same logical device (i.e., neither queue family is
VK_QUEUE_FAMILY_FOREIGN_EXT or
VK_QUEUE_FAMILY_EXTERNAL).
This means that whenever the maintenance9
feature is enabled, explicit queue family ownership transfers of buffer and
linear image resources between different queue families on the same logical
device are optional.
Additionally, if the maintenance9 feature
is enabled, the contents of some optimal image resources (i.e., those
created with VK_IMAGE_TILING_OPTIMAL) are always preserved when they
are implicitly acquired by a different queue family on the same logical
device (i.e., neither queue family is
VK_QUEUE_FAMILY_FOREIGN_EXT or
VK_QUEUE_FAMILY_EXTERNAL).
This applies only to optimal images that are being implicitly acquired by a
queue family whose index bit is set in the current queue family’s
VkQueueFamilyOwnershipTransferPropertiesKHR::optimalImageTransferToQueueFamilies,
and that were created without any of the following bits set in usage:
-
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT -
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT -
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT -
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT -
VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT -
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
This means that whenever the maintenance9
feature is enabled, explicit queue family ownership transfers of such image
resources between such combinations of queue families are optional.
For all other optimal images and/or combinations of queue families, the
application must still perform an explicit queue family ownership transfer
if it wishes to make the memory contents of an optimal image subresource
already owned by a queue family accessible to a different queue family.
|
Note
|
Applications are allowed to perform explicit queue family ownership transfers in circumstances where they are not required, but there is no functional nor performance advantage in doing so. Performing explicit transfers in such cases remains supported for backward compatibility and is not recommended for new applications. |
|
Note
|
Before being used on the first queue, images still require a layout transition from these layouts:
|
A queue family can take ownership of an
image subresource, tensor 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, tensor subresources of tensor objects,
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.10.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 family 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.11. 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,
vkBindTensorMemoryARM,
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
|
The implementation-dependent limit |
|
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, linear tensors, and linear image subresources are considered host-accessible subresources when they are in any of these layouts:
-
VK_IMAGE_LAYOUT_PREINITIALIZED -
VK_IMAGE_LAYOUT_GENERAL -
VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT
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, non-linear tensors, 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.
Aliases created by binding the same memory to a tensor and an image subresource interpret the contents of the memory in consistent ways if and only if:
-
The image was created with
VK_IMAGE_TILING_LINEARand the tensor was created withVK_TENSOR_TILING_LINEAR_ARM. The strides for the image subresource, as reported by vkGetImageSubresourceLayout, are compatible with strides passed when creating the tensor, i.e. VkTensorDescriptionARM::pStrides[dimensionCount-3] must be equal to VkSubresourceLayout::rowPitchif VkTensorDescriptionARM::dimensionCountis greater than 2 and VkTensorDescriptionARM::pStrides[dimensionCount-4] must be equal to VkSubresourceLayout::depthPitchif VkTensorDescriptionARM::dimensionCountis greater than 3. -
The image was created with
VK_IMAGE_TILING_OPTIMALand the tensor was created withVK_TENSOR_TILING_OPTIMAL_ARM. The image was created withVK_IMAGE_USAGE_TENSOR_ALIASING_BIT_ARMand the tensor was created withVK_TENSOR_USAGE_IMAGE_ALIASING_BIT_ARM. -
The format of the tensor must be compatible with that of the individual components of the format of the image.
-
The number of dimensions of the tensor (VkTensorDescriptionARM::
dimensionCount) is greater than or equal to the number of dimensions of the image (as specified by VkImageCreateInfo::imageType) plus 1. -
The size of the tensor along its innermost dimension (VkTensorDescriptionARM::
pDimensions[dimensionCount-1]) is equal to the number of components of the format of the image (VkImageCreateInfo::format). -
The size of the tensor along all dimensions other than the N innermost dimensions necessary to represent the image (i.e. the number of dimensions of the image plus 1) must be 1.
-
The image subresource is in the
VK_IMAGE_LAYOUT_TENSOR_ALIASING_ARMlayout if the image was created withVK_IMAGE_TILING_OPTIMAL. The image must be transitioned toVK_IMAGE_LAYOUT_TENSOR_ALIASING_ARMprior to any reads via the tensor resource for those reads to return data consistent with that provided to the image writes. The image must be transitioned toVK_IMAGE_LAYOUT_TENSOR_ALIASING_ARMprior to any writes performed via the tensor resource for reads performed via the image resource to return data consistent with that provided to the tensor writes.
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,
from VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT if it is zeroed,
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.11.1. Resource Memory Overlap
Applications can safely access resources concurrently via separate device and host operations as long as the accessed memory locations are guaranteed to not overlap, as defined in Memory Location, and the operation, resource, and access are otherwise independently valid.
Some operations have alignment requirements or access ambiguous
memory locations, so the semantics of a
particular operation should be considered when determining the overlap.
Such requirements will be described alongside the operation.
Operations between host and device when using non-coherent memory are
aligned to nonCoherentAtomSize, as
defined by vkFlushMappedMemoryRanges and
vkInvalidateMappedMemoryRanges.
|
Note
|
The intent is that buffers (or linear images) can be accessed concurrently, even when they share cache lines, but otherwise do not access the same memory range. The concept of a device cache line size is not exposed in the memory model. |
12.12. 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.12.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.12.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.12.3. Create the Buffer Collection
To create a 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 -
pCollectionis 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
collectionTokenis azx_handle_tcontaining the Sysmem client’s buffer collection token
12.12.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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
createInfoa 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.12.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 a VkStructureType value identifying 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 structure 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.12.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 a VkStructureType value identifying 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
12.13. Tensors
Tensors represent multidimensional arrays of data. Tensors can be used by binding them to pipelines via descriptor sets, or by directly specifying them as parameters to certain commands.
Tensors are represented by VkTensorARM handles:
// Provided by VK_ARM_tensors
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkTensorARM)
To create tensors, call:
// Provided by VK_ARM_tensors
VkResult vkCreateTensorARM(
VkDevice device,
const VkTensorCreateInfoARM* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkTensorARM* pTensor);
-
deviceis the logical device that creates the tensor. -
pCreateInfois a pointer to a VkTensorCreateInfoARM structure containing parameters to be used to create the tensor. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pTensoris a pointer to a VkTensorARM handle in which the resulting tensor object is returned.
The VkTensorCreateInfoARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkTensorCreateInfoARM {
VkStructureType sType;
const void* pNext;
VkTensorCreateFlagsARM flags;
const VkTensorDescriptionARM* pDescription;
VkSharingMode sharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
} VkTensorCreateInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkTensorCreateFlagBitsARM describing additional parameters of the tensor. -
pDescriptionis a pointer to an instance of VkTensorDescriptionARM describing the tensor. -
sharingModeis a VkSharingMode value specifying the sharing mode of the tensor when it will be accessed by multiple queue families. -
queueFamilyIndexCountis the number of entries in thepQueueFamilyIndicesarray. -
pQueueFamilyIndicesis a list of queue families that will access this tensor (ignored ifsharingModeis notVK_SHARING_MODE_CONCURRENT).
To determine the set of valid usage bits for a given tensor format,
call vkGetPhysicalDeviceFormatProperties2 with
VkTensorFormatPropertiesARM in the pNext chain.
Bits which can be set in VkTensorCreateInfoARM::flags,
specifying additional parameters of a tensor, are:
// Provided by VK_ARM_tensors
// Flag bits for VkTensorCreateFlagBitsARM
typedef VkFlags64 VkTensorCreateFlagBitsARM;
static const VkTensorCreateFlagBitsARM VK_TENSOR_CREATE_MUTABLE_FORMAT_BIT_ARM = 0x00000001ULL;
static const VkTensorCreateFlagBitsARM VK_TENSOR_CREATE_PROTECTED_BIT_ARM = 0x00000002ULL;
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
static const VkTensorCreateFlagBitsARM VK_TENSOR_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_ARM = 0x00000004ULL;
-
VK_TENSOR_CREATE_MUTABLE_FORMAT_BIT_ARMspecifies that the tensor can be used to create aVkTensorViewARMwith a different format from the tensor. -
VK_TENSOR_CREATE_PROTECTED_BIT_ARMspecifies that the tensor is a protected tensor. -
VK_TENSOR_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_ARMspecifies that the tensor can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail.
// Provided by VK_ARM_tensors
typedef VkFlags64 VkTensorCreateFlagsARM;
VkTensorCreateFlagsARM is a bitmask type for setting a mask of zero or
more VkTensorCreateFlagBitsARM.
To define a set of external memory handle types that may be used as backing
store for a tensor, add a VkExternalMemoryTensorCreateInfoARM
structure to the pNext chain of the VkTensorCreateInfoARM
structure.
The VkExternalMemoryTensorCreateInfoARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkExternalMemoryTensorCreateInfoARM {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlags handleTypes;
} VkExternalMemoryTensorCreateInfoARM;
|
Note
|
A |
-
sTypeis a VkStructureType value identifying 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 destroy a tensor, call:
// Provided by VK_ARM_tensors
void vkDestroyTensorARM(
VkDevice device,
VkTensorARM tensor,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the tensor. -
tensoris the tensor to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
12.13.1. Tensor Description
The VkTensorDescriptionARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkTensorDescriptionARM {
VkStructureType sType;
const void* pNext;
VkTensorTilingARM tiling;
VkFormat format;
uint32_t dimensionCount;
const int64_t* pDimensions;
const int64_t* pStrides;
VkTensorUsageFlagsARM usage;
} VkTensorDescriptionARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tilingis a VkTensorTilingARM value specifying the tiling of the tensor -
formatis a one component VkFormat describing the format and type of the data elements that will be contained in the tensor. -
dimensionCountis the number of dimensions for the tensor. -
pDimensionsis a pointer to an array of integers of sizedimensionCountproviding the number of data elements in each dimension. -
pStridesis eitherNULLor is an array of sizedimensionCountproviding the strides in bytes for the tensor in each dimension. -
usageis a bitmask of VkTensorUsageFlagBitsARM specifying the usage of the tensor.
When describing a tensor created with VK_TENSOR_TILING_OPTIMAL_ARM,
pStrides must be equal to NULL.
When describing a tensor created with VK_TENSOR_TILING_LINEAR_ARM,
pStrides is either an array of size dimensionCount or NULL.
The formats that must be supported for format are documented in
Mandatory tensor format support.
Each element in the pStrides array describes the offset in bytes
between increments of the given dimension.
For example, pStrides[0] describes the offset between element
[x0,x1,x2,x3] and element [x0+1,x1,x2,x3].
The pStrides array can be used to determine whether a tensor is
packed or not.
If pStrides[dimensionCount-1] is equal to the size of a tensor
element and for each dimension n greater than 0 and less than
dimensionCount, pStrides[n-1] is equal to pStrides[n] *
pDimensions[n], then the tensor is a packed tensor.
If the tensorNonPacked feature is not enabled,
the tensor must be a packed tensor.
When a tensor is created with VK_TENSOR_TILING_LINEAR_ARM and
pStrides equal to NULL the tensor strides are calculated by the
vulkan implementation such that the resulting tensor is a packed tensor.
Expressed as an addressing formula, the starting byte of an element in a 4-dimensional, for example, linear tensor has address:
// Assume (x0,x1,x2,x3) are in units of elements.
address(x0,x1,x2,x3) = x0*pStrides[0] + x1*pStrides[1] + x2*pStrides[2] + x3*pStrides[3]
Bits which can be set in VkTensorDescriptionARM::usage,
specifying usage behavior of a tensor, are:
// Provided by VK_ARM_tensors
// Flag bits for VkTensorUsageFlagBitsARM
typedef VkFlags64 VkTensorUsageFlagBitsARM;
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_SHADER_BIT_ARM = 0x00000002ULL;
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_TRANSFER_SRC_BIT_ARM = 0x00000004ULL;
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_TRANSFER_DST_BIT_ARM = 0x00000008ULL;
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_IMAGE_ALIASING_BIT_ARM = 0x00000010ULL;
// Provided by VK_ARM_data_graph
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_DATA_GRAPH_BIT_ARM = 0x00000020ULL;
-
VK_TENSOR_USAGE_SHADER_BIT_ARMspecifies that the tensor can be used to create aVkTensorViewARMsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_TENSOR_ARMaccessed by shader stages. -
VK_TENSOR_USAGE_TRANSFER_SRC_BIT_ARMspecifies that the tensor can be used as the source of a transfer command (see the definition ofVK_PIPELINE_STAGE_TRANSFER_BIT). -
VK_TENSOR_USAGE_TRANSFER_DST_BIT_ARMspecifies that the tensor can be used as the destination of a transfer command. -
VK_TENSOR_USAGE_IMAGE_ALIASING_BIT_ARMspecifies that the tensor can be bound to a range of memory aliased with an image created withVK_IMAGE_TILING_OPTIMAL. See Memory Aliasing for a complete set of rules for tensor/image aliasing. -
VK_TENSOR_USAGE_DATA_GRAPH_BIT_ARMspecifies that the tensor can be used to create aVkTensorViewARMsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_TENSOR_ARMaccessed by data graph pipelines.
// Provided by VK_ARM_tensors
typedef VkFlags64 VkTensorUsageFlagsARM;
VkTensorUsageFlags is a bitmask type for setting a mask of zero or
more VkTensorUsageFlagBitsARM.
Possible values of VkTensorCreateInfoARM::tiling, specifying the
tiling arrangement of elements in the tensor, are:
// Provided by VK_ARM_tensors
typedef enum VkTensorTilingARM {
VK_TENSOR_TILING_OPTIMAL_ARM = 0,
VK_TENSOR_TILING_LINEAR_ARM = 1,
} VkTensorTilingARM;
-
VK_TENSOR_TILING_OPTIMAL_ARMspecifies optimal tiling (elements are laid out in an implementation-dependent arrangement, for more efficient memory access). -
VK_TENSOR_TILING_LINEAR_ARMspecifies linear tiling (elements are laid out linearly and the offset between each element is determined by the strides of the tensor).
12.14. Tensor Views
Tensor objects are not directly accessed by pipelines for reading or writing tensor data. Instead, tensor views representing the tensor subresources and containing additional metadata are used for that purpose. Views must be created on tensors of compatible types.
Tensor views are represented by VkTensorViewARM handles:
// Provided by VK_ARM_tensors
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkTensorViewARM)
To create a tensor view, call:
// Provided by VK_ARM_tensors
VkResult vkCreateTensorViewARM(
VkDevice device,
const VkTensorViewCreateInfoARM* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkTensorViewARM* pView);
-
deviceis the logical device that creates the tensor view. -
pCreateInfois a pointer to an instance of theVkTensorViewCreateInfoARMstructure containing parameters to be used to create the tensor view. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pViewis a pointer to a VkTensorViewARM handle in which the resulting tensor view object is returned.
Some of the tensor creation parameters are inherited by the view. In particular, other than format, the tensor view creation inherits all other parameters from the tensor.
The remaining parameters are contained in pCreateInfo.
The VkTensorViewCreateInfoARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkTensorViewCreateInfoARM {
VkStructureType sType;
const void* pNext;
VkTensorViewCreateFlagsARM flags;
VkTensorARM tensor;
VkFormat format;
} VkTensorViewCreateInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
tensoris a VkTensorARM on which the view will be created. -
formatis a VkFormat describing the format and type used to interpret elements in the tensor.
If tensor was created with the
VK_TENSOR_CREATE_MUTABLE_FORMAT_BIT_ARM flag, format can be
different from the tensor’s format, but if they are not equal they must be
compatible.
Tensor format compatibility is defined in the
Format Compatibility Classes section.
Views of compatible formats will have the same mapping between element
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. |
Bits which can be set in VkTensorViewCreateInfoARM::flags,
specifying additional parameters of an tensor, are:
// Provided by VK_ARM_tensors
// Flag bits for VkTensorViewCreateFlagBitsARM
typedef VkFlags64 VkTensorViewCreateFlagBitsARM;
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
static const VkTensorViewCreateFlagBitsARM VK_TENSOR_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_ARM = 0x00000001ULL;
-
VK_TENSOR_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_ARMspecifies that the tensor view can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail.
// Provided by VK_ARM_tensors
typedef VkFlags64 VkTensorViewCreateFlagsARM;
VkTensorViewCreateFlagsARM is a bitmask type for setting a mask of
zero or more VkTensorViewCreateFlagBitsARM.
To destroy a tensor view, call:
// Provided by VK_ARM_tensors
void vkDestroyTensorViewARM(
VkDevice device,
VkTensorViewARM tensorView,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the tensor view. -
tensorViewis the tensor view to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
12.14.1. Tensor View Format Features
Valid usage of a VkTensorViewARM may be constrained by the tensor view’s format features, defined below. Such constraints are documented in the affected valid usage statement.
-
If the view’s tensor was created with
VK_TENSOR_TILING_LINEAR_ARM, then the tensor view’s set of format features is the value of VkTensorFormatPropertiesARM::linearTilingTensorFeaturesfound by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkTensorViewCreateInfoARM::format. -
If the view’s tensor was created with
VK_TENSOR_TILING_OPTIMAL_ARM, then the tensor view’s set of format features is the value of VkTensorFormatPropertiesARM::optimalTilingTensorFeaturesfound by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkTensorViewCreateInfoARM::format.
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 a VkStructureType value identifying 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 calculation and bias provided by image sampling functions in SPIR-V, as described in the LOD 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. WhenunnormalizedCoordinatesisVK_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. WhenunnormalizedCoordinatesisVK_FALSE, the 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.
-
|
Note
|
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_descriptor_buffer
VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000008,
// Provided by VK_EXT_non_seamless_cube_map
VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT = 0x00000004,
// Provided by VK_QCOM_image_processing
VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM = 0x00000010,
} 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. -
VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOMspecifies that the sampler will read from images using onlyOpImageWeightedSampleQCOM,OpImageBoxFilterQCOM,OpImageBlockMatchGatherSSDQCOM,OpImageBlockMatchGatherSADQCOM,OpImageBlockMatchWindowSSDQCOM,OpImageBlockMatchWindowSADQCOM,OpImageBlockMatchSSDQCOM, orOpImageBlockMatchSADQCOM.
|
Note
|
The approximations used when
|
-
VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTspecifies that the sampler can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail.
// Provided by VK_VERSION_1_0
typedef VkFlags 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 a VkStructureType value identifying 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_QCOM_filter_cubic_clamp
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_RANGECLAMP_QCOM = 1000521000,
// 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. -
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_RANGECLAMP_QCOMspecifies values are combined as described byVK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE, followed by a texel range clamp.
The VkSamplerCubicWeightsCreateInfoQCOM structure is defined as:
// Provided by VK_QCOM_filter_cubic_weights
typedef struct VkSamplerCubicWeightsCreateInfoQCOM {
VkStructureType sType;
const void* pNext;
VkCubicFilterWeightsQCOM cubicWeights;
} VkSamplerCubicWeightsCreateInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cubicWeightsis a VkCubicFilterWeightsQCOM value controlling which cubic weights are used.
If the pNext chain of VkSamplerCreateInfo includes a
VkSamplerCubicWeightsCreateInfoQCOM structure, then that structure
specifies which cubic weights are used.
If that structure is not present, cubicWeights is considered to be
VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM.
Possible values of the
VkSamplerCubicWeightsCreateInfoQCOM::cubicWeights, specifying
cubic weights used in Texel Cubic
Filtering are:
// Provided by VK_QCOM_filter_cubic_weights
typedef enum VkCubicFilterWeightsQCOM {
VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM = 0,
VK_CUBIC_FILTER_WEIGHTS_ZERO_TANGENT_CARDINAL_QCOM = 1,
VK_CUBIC_FILTER_WEIGHTS_B_SPLINE_QCOM = 2,
VK_CUBIC_FILTER_WEIGHTS_MITCHELL_NETRAVALI_QCOM = 3,
} VkCubicFilterWeightsQCOM;
-
VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOMspecifies Catmull-Rom weights. -
VK_CUBIC_FILTER_WEIGHTS_ZERO_TANGENT_CARDINAL_QCOMspecifies Zero Tangent Cardinal weights. -
VK_CUBIC_FILTER_WEIGHTS_B_SPLINE_QCOMspecifies B-Spline weights. -
VK_CUBIC_FILTER_WEIGHTS_MITCHELL_NETRAVALI_QCOMspecifies Mitchell-Netravali 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 is a deprecated alias
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 if thesamplerMirrorClampToEdgefeature is 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_EXTspecifies that a VkSamplerCustomBorderColorCreateInfoEXT structure is included in the VkSamplerCreateInfo::pNextchain containing the color data in floating-point format. -
VK_BORDER_COLOR_INT_CUSTOM_EXTspecifies 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
Applications can enable sRGB to linear conversion for the R, G, and B
components of a Y′CBCR image during format
conversion by including
VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM structure in the
pNext chain of VkSamplerYcbcrConversionCreateInfo.
The VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM structure is
defined as:
// Provided by VK_QCOM_ycbcr_degamma
typedef struct VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM {
VkStructureType sType;
void* pNext;
VkBool32 enableYDegamma;
VkBool32 enableCbCrDegamma;
} VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
enableYDegammaindicates sRGB to linear conversion is enabled for the G component. -
enableCbCrDegammaindicates sRGB to linear conversion is enabled for the R and B components.
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 a VkStructureType value identifying 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.
|
Note
|
If If |
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 a VkStructureType value identifying 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.
The VkSamplerBlockMatchWindowCreateInfoQCOM structure is defined as:
// Provided by VK_QCOM_image_processing2
typedef struct VkSamplerBlockMatchWindowCreateInfoQCOM {
VkStructureType sType;
const void* pNext;
VkExtent2D windowExtent;
VkBlockMatchWindowCompareModeQCOM windowCompareMode;
} VkSamplerBlockMatchWindowCreateInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
windowExtentis a VkExtent2D specifying a the width and height of the block match window. -
windowCompareModeis a VkBlockMatchWindowCompareModeQCOM specifying the compare mode.
The VkBlockMatchWindowCompareModeQCOM enum describes how block match values within the window are compared. VkBlockMatchWindowCompareModeQCOM is defined as:
// Provided by VK_QCOM_image_processing2
typedef enum VkBlockMatchWindowCompareModeQCOM {
VK_BLOCK_MATCH_WINDOW_COMPARE_MODE_MIN_QCOM = 0,
VK_BLOCK_MATCH_WINDOW_COMPARE_MODE_MAX_QCOM = 1,
} VkBlockMatchWindowCompareModeQCOM;
-
VK_BLOCK_MATCH_WINDOW_COMPARE_MODE_MIN_QCOMspecifies that windowed block match operations return the minimum error within the window. -
VK_BLOCK_MATCH_WINDOW_COMPARE_MODE_MAX_QCOMspecifies that windowed block match operations return the maximum error within the window.
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.
If the descriptorBuffer feature is
enabled, the implementation supports placing descriptors into
descriptor buffers which are bound during command
recording in a similar way to 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
task, mesh and
compute shaders for image views whose
format features contain
VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT.
Atomic operations on storage images are supported in
task, mesh and
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.
When the tileShadingColorAttachments feature is enabled, loads using
OpImageRead or OpImageSparseRead are supported for color
tile attachments in fragment and compute
shaders for image views whose format
features contain VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT.
Additionally, when the tileShadingColorAttachments feature is enabled, stores using
OpImageWrite are supported for color attachments in compute shaders
with the same set of image formats as for loads.
When the tileShadingAtomicOps
feature is enabled, tile atomic operations are supported for color
attachments in compute shaders with the same set of image formats as for
loads.
When the tileShadingInputAttachments feature is enabled, loads using
OpImageRead are supported for input tile
attachments in fragment and compute shaders with the same set of image
formats as for color attachments.
Stores to input attachments are not supported.
When the tileShadingDepthAttachments or
tileShadingStencilAttachments feature is enabled, loads using
OpImageRead or OpImageSparseRead are supported for depth or
stencil aspects of a depth/stencil tile
attachment in fragment and compute shaders with the same set of image
formats as for color attachments.
Stores to depth/stencil attachments are not supported.
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 -
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT
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 -
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT
|
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 buffer view formats which report
format features support for
VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT
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 view formats which report
format features support for
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT
Stores to storage texel buffers are supported in
task, mesh and
compute shaders for texel buffer formats which report
format features support for
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT
Atomic operations on storage texel buffers are supported in
task, mesh and
compute shaders for texel buffer formats which report
format features support for
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT
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. Sample Weight Image
A sample weight image (VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM)
is a descriptor type associated with an image resource
via an image view that can be used in
weight image sampling.
The image view must have been created with
VkImageViewSampleWeightCreateInfoQCOM.
Shaders can combine a weight image variable, a sampled image variable, and a sampler variable to perform weight image sampling.
Weight image sampling is supported in all shader stages if the weight image
view specifies a format that supports
format feature
VK_FORMAT_FEATURE_2_WEIGHT_IMAGE_BIT_QCOM and
the sampled image view specifies a format that supports
format feature
VK_FORMAT_FEATURE_2_WEIGHT_SAMPLED_IMAGE_BIT_QCOM
The image subresources for the weight image must be in the
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or
VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a
shader.
14.1.13. Block Matching Image
A block matching image (VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM)
is a descriptor type associated with an image resource
via an image view that can be used in
block matching.
Shaders can combine a target image variable, a reference image variable, and a sampler variable to perform block matching.
Block matching is supported in all shader stages for if both the target view
and reference view specifies a format that supports
format feature
VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM
The image subresources for block matching must be in the
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or
VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a
shader.
14.1.14. 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 -
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT -
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ
14.1.15. 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.16. Mutable
A descriptor of mutable (VK_DESCRIPTOR_TYPE_MUTABLE_EXT) type
indicates that this descriptor can mutate to any of the descriptor types
given in the VkMutableDescriptorTypeListEXT::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_EXT 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_EXT.
An active descriptor type of VK_DESCRIPTOR_TYPE_MUTABLE_EXT 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.1.17. Storage Tensor
A storage tensor (VK_DESCRIPTOR_TYPE_TENSOR_ARM) is a descriptor
type associated with a tensor resource via a
tensor view that read and write operations can
be performed on.
Storage tensor reads and writes are supported in shaders for tensor views
whose format features contain
VK_FORMAT_FEATURE_2_TENSOR_SHADER_BIT_ARM.
Storage tensor reads and writes are supported in graph pipelines for tensor
views whose format features
contain
VK_FORMAT_FEATURE_2_TENSOR_DATA_GRAPH_BIT_ARM.
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 a VkStructureType value identifying 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.
If the pNext chain of a VkDescriptorSetLayoutCreateInfo or
VkDescriptorPoolCreateInfo structure includes a
VkMutableDescriptorTypeCreateInfoEXT structure, then that structure
specifies Information about the possible descriptor types for mutable
descriptor types.
The VkMutableDescriptorTypeCreateInfoEXT structure is defined as:
// Provided by VK_EXT_mutable_descriptor_type
typedef struct VkMutableDescriptorTypeCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t mutableDescriptorTypeListCount;
const VkMutableDescriptorTypeListEXT* pMutableDescriptorTypeLists;
} VkMutableDescriptorTypeCreateInfoEXT;
or the equivalent
// Provided by VK_VALVE_mutable_descriptor_type
typedef VkMutableDescriptorTypeCreateInfoEXT VkMutableDescriptorTypeCreateInfoVALVE;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
mutableDescriptorTypeListCountis the number of elements inpMutableDescriptorTypeLists. -
pMutableDescriptorTypeListsis a pointer to an array ofVkMutableDescriptorTypeListEXTstructures.
If mutableDescriptorTypeListCount is zero or if this structure is not
included in the pNext chain, the VkMutableDescriptorTypeListEXT
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
VkMutableDescriptorTypeCreateInfoEXT::pMutableDescriptorTypeLists[i].
The list of potential descriptor types a given mutable descriptor can
mutate to is passed in a VkMutableDescriptorTypeListEXT structure.
The VkMutableDescriptorTypeListEXT structure is defined as:
// Provided by VK_EXT_mutable_descriptor_type
typedef struct VkMutableDescriptorTypeListEXT {
uint32_t descriptorTypeCount;
const VkDescriptorType* pDescriptorTypes;
} VkMutableDescriptorTypeListEXT;
or the equivalent
// Provided by VK_VALVE_mutable_descriptor_type
typedef VkMutableDescriptorTypeListEXT 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_VERSION_1_4
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT = 0x00000001,
// Provided by VK_EXT_descriptor_buffer
VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00000010,
// Provided by VK_EXT_descriptor_buffer
VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT = 0x00000020,
// Provided by VK_NV_device_generated_commands_compute
VK_DESCRIPTOR_SET_LAYOUT_CREATE_INDIRECT_BINDABLE_BIT_NV = 0x00000080,
// Provided by VK_EXT_mutable_descriptor_type
VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT = 0x00000004,
// Provided by VK_NV_per_stage_descriptor_set
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NV = 0x00000040,
// Provided by VK_KHR_push_descriptor
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR = VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT,
// 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,
// Provided by VK_VALVE_mutable_descriptor_type
VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE = VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT,
} VkDescriptorSetLayoutCreateFlagBits;
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BITspecifies that descriptor sets must not be allocated using this layout, and descriptors are instead pushed by vkCmdPushDescriptorSet. -
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_INDIRECT_BINDABLE_BIT_NVspecifies that descriptor sets using this layout allows them to be bound with compute pipelines that are created withVK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NVflag set to be used in Device-Generated Commands. -
VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXTspecifies that this layout must only be used with descriptor buffers. -
VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXTspecifies that this is a layout only containing immutable samplers that can be bound by vkCmdBindDescriptorBufferEmbeddedSamplersEXT. Unlike normal immutable samplers, embedded immutable samplers do not require the application to provide them in a descriptor buffer. -
VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXTspecifies that descriptor sets using this layout must be allocated from a descriptor pool created with theVK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXTbit set. Descriptor set layouts created with this bit have no expressible 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. -
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NVspecifies that binding numbers in descriptor sets using this layout may represent different resources and/or types of resources in each stage.
// 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 a VkStructureType value identifying 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_BITspecifies 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_BITspecifies 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_BITspecifies 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. Descriptor bindings created with this flag are also partially exempt from the external synchronization requirement in vkUpdateDescriptorSetWithTemplateKHR and vkUpdateDescriptorSets in the same way as forVK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT. 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_BITspecifies 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, when VkDescriptorSetLayoutCreateInfo::flagsdoes not containVK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT. 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
supportedspecifies whether the descriptor set layout can be created.
supported will be VK_TRUE if the descriptor set can be created,
or else 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 a VkStructureType value identifying 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 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 zero.
For the purposes of this command, a variable-sized descriptor binding with a
descriptorCount of zero is treated as having a descriptorCount
of
four if descriptorType is
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, or one otherwise,
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
{
.binding = 0,
.descriptorType = VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,
.descriptorCount = 1,
.stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT,
.pImmutableSamplers = NULL
},
// binding to an array of image descriptors
{
.binding = 1,
.descriptorType = VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,
.descriptorCount = 12,
.stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT,
.pImmutableSamplers = NULL
},
// binding to a single uniform buffer descriptor
{
.binding = 0,
.descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER,
.descriptorCount = 1,
.stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT,
.pImmutableSamplers = NULL
}
};
const VkDescriptorSetLayoutCreateInfo myDescriptorSetLayoutCreateInfo[] =
{
// Information for first descriptor set with two descriptor bindings
{
.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO,
.pNext = NULL,
.flags = 0,
.bindingCount = 2,
.pBindings = &myDescriptorSetLayoutBinding[0]
},
// Information for second descriptor set with one descriptor binding
{
.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO,
.pNext = NULL,
.flags = 0,
.bindingCount = 1,
.pBindings = &myDescriptorSetLayoutBinding[2]
}
};
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 a VkStructureType value identifying 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. The implementation must not access these objects outside of the duration of the command this structure is passed to. -
pushConstantRangeCountis the number of push constant ranges included in the pipeline layout. -
pPushConstantRangesis a pointer to an array of VkPushConstantRange structures 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_EXTspecifies 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 withoutVK_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.
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.
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 |
|
storage tensor |
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, a previously bound descriptor set bound with lower index M than N is disturbed if the pipeline layouts for set M and N are not compatible for set M. Otherwise, the bound descriptor set in M is not disturbed.
If, additionally, the previously bound descriptor set for set N was bound using a pipeline layout not compatible for set N, then all bindings in sets numbered greater than N are disturbed.
When binding a pipeline, the pipeline can correctly access any previously bound descriptor set N if it was bound with compatible pipeline layout for set N, and it was not disturbed.
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.
When a descriptor set is disturbed by binding descriptor sets, the disturbed set is considered to contain undefined descriptors bound with the same pipeline layout as the disturbing descriptor set.
|
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[] =
{
{
.stageFlags = VK_SHADER_STAGE_VERTEX_BIT,
.offset = 0,
.size = 4
},
{
.stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT,
.offset = 4,
.size = 4
},
};
const VkPipelineLayoutCreateInfo createInfo =
{
.sType = VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO,
.pNext = NULL,
.flags = 0,
.setLayoutCount = 2,
.pSetLayouts = layouts,
.pushConstantRangeCount = 2,
.pPushConstantRanges = ranges
};
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 a VkStructureType value identifying 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_EXT, a
VkMutableDescriptorTypeCreateInfoEXT structure in the pNext
chain can be used to specify which mutable descriptor types can be
allocated from the pool.
If included in the pNext chain,
VkMutableDescriptorTypeCreateInfoEXT::pMutableDescriptorTypeLists[i]
specifies which kind of VK_DESCRIPTOR_TYPE_MUTABLE_EXT descriptors
can be allocated from this pool entry.
If VkMutableDescriptorTypeCreateInfoEXT does not exist in the
pNext chain, or
VkMutableDescriptorTypeCreateInfoEXT::pMutableDescriptorTypeLists[i]
is out of range, the descriptor pool allocates enough memory to be able to
allocate a VK_DESCRIPTOR_TYPE_MUTABLE_EXT 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_EXT
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 VkMutableDescriptorTypeListEXT assigned to it
is considered to partially overlap any other pool entry which has a
VkMutableDescriptorTypeListEXT 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 a VkStructureType value identifying 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_EXT_mutable_descriptor_type
VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT = 0x00000004,
// Provided by VK_NV_descriptor_pool_overallocation
VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_SETS_BIT_NV = 0x00000008,
// Provided by VK_NV_descriptor_pool_overallocation
VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_POOLS_BIT_NV = 0x00000010,
// Provided by VK_EXT_descriptor_indexing
VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT = VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT,
// Provided by VK_VALVE_mutable_descriptor_type
VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE = VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT,
} 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_EXTspecifies that this descriptor pool and the descriptor sets allocated from it reside entirely in host memory and cannot be bound. Similar to descriptor sets allocated without this flag, applications can copy-from and copy-to descriptors sets allocated from this descriptor pool. 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. -
VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_SETS_BIT_NVspecifies that the implementation should allow the application to allocate more than VkDescriptorPoolCreateInfo::maxSetsdescriptor set objects from the descriptor pool as available resources allow. The implementation may use themaxSetsvalue to allocate the initial available sets, but using zero is permitted. -
VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_POOLS_BIT_NVspecifies that the implementation should allow the application to allocate more descriptors from the pool than was specified by the VkDescriptorPoolSize::descriptorCountfor any descriptor type as specified by VkDescriptorPoolCreateInfo::poolSizeCountand VkDescriptorPoolCreateInfo::pPoolSizes, as available resources allow. The implementation may use thedescriptorCountfor each descriptor type to allocate the initial pool, but the application is allowed to set thepoolSizeCountto zero, or any of thedescriptorCountvalues in thepPoolSizesarray to zero.
// 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 For simplicity the application can use the
VkPhysicalDeviceMaintenance6Properties:: |
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, with the exception that
samplers with a non-null pImmutableSamplers are initialized on
allocation.
Descriptors also become undefined if the underlying resource or view object
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
Copying a descriptor from a descriptor set does not constitute a use of the referenced resource or view, as it is the reference itself that is copied. Applications can copy a descriptor referencing a destroyed resource, and it can copy an undefined descriptor. The destination descriptor becomes undefined in both cases.
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 a VkStructureType value identifying 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 or VkWriteDescriptorSetAccelerationStructureNV structure in thepNextchain -
a value matching the
descriptorCountof a VkWriteDescriptorSetTensorARM 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_EXT,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,
or if descriptorType is VK_DESCRIPTOR_TYPE_TENSOR_ARM, in which
case the source data for the descriptor writes is taken from the instance of
VkWriteDescriptorSetTensorARM in the pNext chain of
VkWriteDescriptorSet,
as specified below.
If the nullDescriptor feature is enabled,
the buffer,
acceleration structure,
tensor,
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_EXT, the supported descriptor types in
VkMutableDescriptorTypeCreateInfoEXT 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_QCOM_image_processing
VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM = 1000440000,
// Provided by VK_QCOM_image_processing
VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM = 1000440001,
// Provided by VK_ARM_tensors
VK_DESCRIPTOR_TYPE_TENSOR_ARM = 1000460000,
// Provided by VK_EXT_mutable_descriptor_type
VK_DESCRIPTOR_TYPE_MUTABLE_EXT = 1000351000,
// Provided by VK_NV_partitioned_acceleration_structure
VK_DESCRIPTOR_TYPE_PARTITIONED_ACCELERATION_STRUCTURE_NV = 1000570000,
// Provided by VK_EXT_inline_uniform_block
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT = VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK,
// Provided by VK_VALVE_mutable_descriptor_type
VK_DESCRIPTOR_TYPE_MUTABLE_VALVE = VK_DESCRIPTOR_TYPE_MUTABLE_EXT,
} 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_EXTspecifies a descriptor of mutable type. -
VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOMspecifies a sampled weight image descriptor. -
VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOMspecifies a block matching image descriptor. -
VK_DESCRIPTOR_TYPE_TENSOR_ARMspecifies a storage tensor descriptor.
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.
When updating descriptors with a descriptorType of
VK_DESCRIPTOR_TYPE_TENSOR_ARM, none of the pImageInfo,
pBufferInfo, or pTexelBufferView members are accessed, instead
the source data of the descriptor update operation is taken from the
instance of VkWriteDescriptorSetTensorARM 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.NoteWhen setting
rangetoVK_WHOLE_SIZE, the effective range must not be larger than the maximum range for the descriptor type (maxUniformBufferRangeormaxStorageBufferRange). This means thatVK_WHOLE_SIZEis not typically useful in the common case where uniform buffer descriptors are suballocated from a buffer that is much larger thanmaxUniformBufferRange.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
If the descriptorType member of VkWriteDescriptorSet is
VK_DESCRIPTOR_TYPE_PARTITIONED_ACCELERATION_STRUCTURE_NV, then the
data to write to the descriptor set is specified through a
VkWriteDescriptorSetPartitionedAccelerationStructureNV structure
included in the pNext chain of VkWriteDescriptorSet.
The VkWriteDescriptorSetPartitionedAccelerationStructureNV structure
is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkWriteDescriptorSetPartitionedAccelerationStructureNV {
VkStructureType sType;
void* pNext;
uint32_t accelerationStructureCount;
const VkDeviceAddress* pAccelerationStructures;
} VkWriteDescriptorSetPartitionedAccelerationStructureNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructureCountis the number of elements inpAccelerationStructures. -
pAccelerationStructuresis a pointer to an array ofaccelerationStructureCountdevice addresses pointing to previously built PTLAS.
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 a VkStructureType value identifying 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 VkWriteDescriptorSetTensorARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkWriteDescriptorSetTensorARM {
VkStructureType sType;
const void* pNext;
uint32_t tensorViewCount;
const VkTensorViewARM* pTensorViews;
} VkWriteDescriptorSetTensorARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensorViewCountis the number of elements inpTensorViews. -
pTensorViewsare the tensor views that will be used to update the descriptor set.
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 a VkStructureType value identifying 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_EXT and srcBinding is not
VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the new active descriptor type becomes
the descriptor type of srcBinding.
If both VkDescriptorSetLayoutBinding for srcBinding and
dstBinding are VK_DESCRIPTOR_TYPE_MUTABLE_EXT, 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.
In conjunction with
vkCmdPushDescriptorSetWithTemplate or
vkUpdateDescriptorSetWithTemplate, this can be more efficient
compared to calling
vkCmdPushDescriptorSet or
vkUpdateDescriptorSets.
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
vkCmdPushDescriptorSetWithTemplate or
vkUpdateDescriptorSetWithTemplate.
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 vkCmdPushDescriptorSetWithTemplate 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 a VkStructureType value identifying 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_DESCRIPTORSit 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. The implementation must not access this object outside of the duration of the command this structure is passed to. -
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 -
pipelineLayoutis a VkPipelineLayout object used to program the bindings. This parameter is ignored iftemplateTypeis notVK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS -
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
// 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_4
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS = 1,
// Provided by VK_KHR_descriptor_update_template with VK_KHR_push_descriptor, VK_KHR_push_descriptor with VK_VERSION_1_1 or VK_KHR_descriptor_update_template
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR = VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS,
// 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_DESCRIPTORSspecifies 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 information 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
{
.binding = 0,
.dstArrayElement = 0,
.descriptorCount = 1,
.descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
.offset = offsetof(AppDataStructure, imageInfo),
.stride = 0 // stride not required if descriptorCount is 1
},
// binding to an array of buffer descriptors
{
.binding = 1,
.dstArrayElement = 0,
.descriptorCount = 3,
.descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER,
.offset = offsetof(AppDataStructure, bufferInfoArray),
.stride = sizeof(VkDescriptorBufferInfo) // descriptor buffer infos are compact
},
// binding to an array of buffer views
{
.binding = 2,
.dstArrayElement = 0,
.descriptorCount = 2,
.descriptorType = VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER,
.offset = offsetof(AppDataStructure, bufferView) +
offsetof(AppBufferView, bufferView),
.stride = sizeof(AppBufferView) // bufferViews do not have to be compact
},
};
// create a descriptor update template for descriptor set updates
const VkDescriptorUpdateTemplateCreateInfo createInfo =
{
.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO,
.pNext = NULL,
.flags = 0,
.descriptorUpdateEntryCount = 3,
.pDescriptorUpdateEntries = descriptorUpdateTemplateEntries,
.templateType = VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET,
.descriptorSetLayout = myLayout,
.pipelineBindPoint = 0, // ignored by given templateType
.pipelineLayout = 0, // ignored by given templateType
.set = 0, // 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
, or calls to vkCmdSetDescriptorBufferOffsetsEXT or
vkCmdBindDescriptorBufferEmbeddedSamplersEXT,
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.
When consuming a descriptor, a descriptor is considered valid if the
descriptor is not undefined as described by
descriptor set allocation.
If the nullDescriptor feature is enabled,
a null descriptor is also considered valid.
A descriptor that was disturbed by Pipeline
Layout Compatibility, or was never bound by vkCmdBindDescriptorSets
is not considered valid.
If a pipeline accesses a descriptor either statically or dynamically
depending on the VkDescriptorBindingFlagBits, the consuming descriptor
type in the pipeline must match the VkDescriptorType in
VkDescriptorSetLayoutCreateInfo for the descriptor to be considered
valid.
If a descriptor is a mutable descriptor, the consuming descriptor type in
the pipeline must match the active descriptor type for the descriptor to be
considered valid.
|
Note
|
Further validation may be carried out beyond validation for descriptor types, e.g. Texel Input Validation. |
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.
Alternatively, to bind one or more descriptor sets to a command buffer, call:
// Provided by VK_VERSION_1_4
void vkCmdBindDescriptorSets2(
VkCommandBuffer commandBuffer,
const VkBindDescriptorSetsInfo* pBindDescriptorSetsInfo);
or the equivalent command
// Provided by VK_KHR_maintenance6
void vkCmdBindDescriptorSets2KHR(
VkCommandBuffer commandBuffer,
const VkBindDescriptorSetsInfo* pBindDescriptorSetsInfo);
-
commandBufferis the command buffer that the descriptor sets will be bound to. -
pBindDescriptorSetsInfois a pointer to aVkBindDescriptorSetsInfostructure.
The VkBindDescriptorSetsInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkBindDescriptorSetsInfo {
VkStructureType sType;
const void* pNext;
VkShaderStageFlags stageFlags;
VkPipelineLayout layout;
uint32_t firstSet;
uint32_t descriptorSetCount;
const VkDescriptorSet* pDescriptorSets;
uint32_t dynamicOffsetCount;
const uint32_t* pDynamicOffsets;
} VkBindDescriptorSetsInfo;
or the equivalent
// Provided by VK_KHR_maintenance6
typedef VkBindDescriptorSetsInfo VkBindDescriptorSetsInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stageFlagsis a bitmask of VkShaderStageFlagBits specifying the shader stages the descriptor sets will be bound to. -
layoutis a VkPipelineLayout object used to program the bindings. If thedynamicPipelineLayoutfeature is enabled,layoutcan be VK_NULL_HANDLE and the layout must be specified by chaining the VkPipelineLayoutCreateInfo structure off thepNext -
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.
If stageFlags specifies a subset of all stages corresponding to one or
more pipeline bind points, the binding operation still affects all stages
corresponding to the given pipeline bind point(s) as if the equivalent
original version of this command had been called with the same parameters.
For example, specifying a stageFlags value of
VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT |
VK_SHADER_STAGE_COMPUTE_BIT is equivalent to calling the original
version of this command once with VK_PIPELINE_BIND_POINT_GRAPHICS and
once with VK_PIPELINE_BIND_POINT_COMPUTE.
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_VERSION_1_4
void vkCmdPushDescriptorSet(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipelineLayout layout,
uint32_t set,
uint32_t descriptorWriteCount,
const VkWriteDescriptorSet* pDescriptorWrites);
or the equivalent command
// 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.
Alternatively, to push descriptor updates into a command buffer, call:
// Provided by VK_VERSION_1_4
void vkCmdPushDescriptorSet2(
VkCommandBuffer commandBuffer,
const VkPushDescriptorSetInfo* pPushDescriptorSetInfo);
or the equivalent command
// Provided by VK_KHR_maintenance6 with VK_KHR_push_descriptor
void vkCmdPushDescriptorSet2KHR(
VkCommandBuffer commandBuffer,
const VkPushDescriptorSetInfo* pPushDescriptorSetInfo);
-
commandBufferis the command buffer that the descriptors will be recorded in. -
pPushDescriptorSetInfois a pointer to aVkPushDescriptorSetInfostructure.
The VkPushDescriptorSetInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPushDescriptorSetInfo {
VkStructureType sType;
const void* pNext;
VkShaderStageFlags stageFlags;
VkPipelineLayout layout;
uint32_t set;
uint32_t descriptorWriteCount;
const VkWriteDescriptorSet* pDescriptorWrites;
} VkPushDescriptorSetInfo;
or the equivalent
// Provided by VK_KHR_maintenance6 with VK_KHR_push_descriptor
typedef VkPushDescriptorSetInfo VkPushDescriptorSetInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stageFlagsis a bitmask of VkShaderStageFlagBits specifying the shader stages that will use the descriptors. -
layoutis a VkPipelineLayout object used to program the bindings. If thedynamicPipelineLayoutfeature is enabled,layoutcan be VK_NULL_HANDLE and the layout must be specified by chaining VkPipelineLayoutCreateInfo structure off thepNext -
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.
If stageFlags specifies a subset of all stages corresponding to one or
more pipeline bind points, the binding operation still affects all stages
corresponding to the given pipeline bind point(s) as if the equivalent
original version of this command had been called with the same parameters.
For example, specifying a stageFlags value of
VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT |
VK_SHADER_STAGE_COMPUTE_BIT is equivalent to calling the original
version of this command once with VK_PIPELINE_BIND_POINT_GRAPHICS and
once with VK_PIPELINE_BIND_POINT_COMPUTE.
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_4
void vkCmdPushDescriptorSetWithTemplate(
VkCommandBuffer commandBuffer,
VkDescriptorUpdateTemplate descriptorUpdateTemplate,
VkPipelineLayout layout,
uint32_t set,
const void* pData);
or the equivalent command
// Provided by VK_KHR_descriptor_update_template with VK_KHR_push_descriptor, VK_KHR_push_descriptor with VK_VERSION_1_1 or VK_KHR_descriptor_update_template
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
{
.binding = 0,
.dstArrayElement = 0,
.descriptorCount = 1,
.descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
.offset = offsetof(AppDataStructure, imageInfo),
.stride = 0 // not required if descriptorCount is 1
}
};
// create a descriptor update template for push descriptor set updates
const VkDescriptorUpdateTemplateCreateInfo createInfo =
{
.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO,
.pNext = NULL,
.flags = 0,
.descriptorUpdateEntryCount = 1,
.pDescriptorUpdateEntries = descriptorUpdateTemplateEntries,
.templateType = VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS,
.descriptorSetLayout = 0, // ignored by given templateType
.pipelineBindPoint = VK_PIPELINE_BIND_POINT_GRAPHICS,
.pipelineLayout = myPipelineLayout,
.set = 0,
};
VkDescriptorUpdateTemplate myDescriptorUpdateTemplate;
myResult = vkCreateDescriptorUpdateTemplate(
myDevice,
&createInfo,
NULL,
&myDescriptorUpdateTemplate);
AppDataStructure appData;
// fill appData here or cache it in your engine
vkCmdPushDescriptorSetWithTemplate(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData);
Alternatively, to use a descriptor update template to specify the push descriptors to update, call:
// Provided by VK_VERSION_1_4
void vkCmdPushDescriptorSetWithTemplate2(
VkCommandBuffer commandBuffer,
const VkPushDescriptorSetWithTemplateInfo* pPushDescriptorSetWithTemplateInfo);
or the equivalent command
// Provided by VK_KHR_maintenance6 with VK_KHR_push_descriptor
void vkCmdPushDescriptorSetWithTemplate2KHR(
VkCommandBuffer commandBuffer,
const VkPushDescriptorSetWithTemplateInfo* pPushDescriptorSetWithTemplateInfo);
-
commandBufferis the command buffer that the descriptors will be recorded in. -
pPushDescriptorSetWithTemplateInfois a pointer to aVkPushDescriptorSetWithTemplateInfostructure.
The VkPushDescriptorSetWithTemplateInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPushDescriptorSetWithTemplateInfo {
VkStructureType sType;
const void* pNext;
VkDescriptorUpdateTemplate descriptorUpdateTemplate;
VkPipelineLayout layout;
uint32_t set;
const void* pData;
} VkPushDescriptorSetWithTemplateInfo;
or the equivalent
// Provided by VK_KHR_maintenance6 with VK_KHR_push_descriptor
typedef VkPushDescriptorSetWithTemplateInfo VkPushDescriptorSetWithTemplateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
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. If thedynamicPipelineLayoutfeature is enabled,layoutcan be VK_NULL_HANDLE and the layout must be specified by chaining VkPipelineLayoutCreateInfo structure off thepNext -
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.
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 |
Alternatively, to update push constants, call:
// Provided by VK_VERSION_1_4
void vkCmdPushConstants2(
VkCommandBuffer commandBuffer,
const VkPushConstantsInfo* pPushConstantsInfo);
or the equivalent command
// Provided by VK_KHR_maintenance6
void vkCmdPushConstants2KHR(
VkCommandBuffer commandBuffer,
const VkPushConstantsInfo* pPushConstantsInfo);
-
commandBufferis the command buffer in which the push constant update will be recorded. -
pPushConstantsInfois a pointer to a VkPushConstantsInfo structure.
The VkPushConstantsInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPushConstantsInfo {
VkStructureType sType;
const void* pNext;
VkPipelineLayout layout;
VkShaderStageFlags stageFlags;
uint32_t offset;
uint32_t size;
const void* pValues;
} VkPushConstantsInfo;
or the equivalent
// Provided by VK_KHR_maintenance6
typedef VkPushConstantsInfo VkPushConstantsInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
layoutis the pipeline layout used to program the push constant updates. If thedynamicPipelineLayoutfeature is enabled,layoutcan be VK_NULL_HANDLE and the layout must be specified by chaining VkPipelineLayoutCreateInfo structure off thepNext -
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.
14.3. Physical Storage Buffer Access
Buffer device addresses can also be
used to access buffer memory in a shader, 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.
All loads, stores, and atomics in a shader through
PhysicalStorageBuffer pointers must access addresses in the address
range of some buffer.
14.4. Descriptor Buffers
If the descriptorBuffer feature is
enabled, an alternative way to specify descriptor sets is via buffers,
rather than descriptor set objects.
14.4.1. Putting Descriptors in Memory
Commands are provided to retrieve descriptor data, and also to locate where in memory that data must be written to match the given descriptor set layout.
To determine the amount of memory needed to store all descriptors with a given layout, call:
// Provided by VK_EXT_descriptor_buffer
void vkGetDescriptorSetLayoutSizeEXT(
VkDevice device,
VkDescriptorSetLayout layout,
VkDeviceSize* pLayoutSizeInBytes);
-
deviceis the logical device that gets the size. -
layoutis the descriptor set layout being queried. -
pLayoutSizeInBytesis a pointer to VkDeviceSize where the size in bytes will be written.
The size of a descriptor set layout will be at least as large as the sum total of the size of all descriptors in the layout, and may be larger. This size represents the amount of memory that will be required to store all of the descriptors for this layout in memory, when placed according to the layout’s offsets as obtained by vkGetDescriptorSetLayoutBindingOffsetEXT.
If any binding in layout is
VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, the returned size
includes space for the maximum descriptorCount descriptors as declared
for that binding.
To compute the required size of a descriptor set with a
VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT:
-
size = offset + descriptorSize × variableDescriptorCount
where offset is obtained by
vkGetDescriptorSetLayoutBindingOffsetEXT and descriptorSize is
the size of the relevant descriptor as obtained from
VkPhysicalDeviceDescriptorBufferPropertiesEXT, and
variableDescriptorCount is the equivalent of
VkDescriptorSetVariableDescriptorCountAllocateInfo::pDescriptorCounts.
For VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK,
variableDescriptorCount is the size in bytes for the inline uniform
block, and descriptorSize is 1.
If
VkPhysicalDeviceDescriptorBufferPropertiesEXT::combinedImageSamplerDescriptorSingleArray
is VK_FALSE and the variable descriptor type is
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
variableDescriptorCount is always considered to be the upper bound.
To get the offset of a binding within a descriptor set layout in memory, call:
// Provided by VK_EXT_descriptor_buffer
void vkGetDescriptorSetLayoutBindingOffsetEXT(
VkDevice device,
VkDescriptorSetLayout layout,
uint32_t binding,
VkDeviceSize* pOffset);
-
deviceis the logical device that gets the offset. -
layoutis the descriptor set layout being queried. -
bindingis the binding number being queried. -
pOffsetis a pointer to VkDeviceSize where the byte offset of the binding will be written.
Each binding in a descriptor set layout is assigned an offset in memory by the implementation. When a shader accesses a resource with that binding, it will access the bound descriptor buffer from that offset to look for its descriptor. This command provides an application with that offset, so that descriptors can be placed in the correct locations. The precise location accessed by a shader for a given descriptor is as follows:
-
location = bufferAddress + setOffset + descriptorOffset + (arrayElement × descriptorSize)
where bufferAddress and setOffset are the base address and
offset for the identified descriptor set as specified by
vkCmdBindDescriptorBuffersEXT and
vkCmdSetDescriptorBufferOffsetsEXT, descriptorOffset is the
offset for the binding returned by this command, arrayElement is the
index into the array specified in the shader, and descriptorSize is
the size of the relevant descriptor as obtained from
VkPhysicalDeviceDescriptorBufferPropertiesEXT.
Applications are responsible for placing valid descriptors at the expected
location in order for a shader to access it.
The overall offset added to bufferAddress to calculate location
must be less than
VkPhysicalDeviceDescriptorBufferPropertiesEXT::maxSamplerDescriptorBufferRange
for samplers and
VkPhysicalDeviceDescriptorBufferPropertiesEXT::maxResourceDescriptorBufferRange
for resources.
If any binding in layout is
VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, that
binding must have the largest offset of any binding.
A descriptor binding with type VK_DESCRIPTOR_TYPE_MUTABLE_VALVE
can be used.
Any potential types in
VkMutableDescriptorTypeCreateInfoVALVE::pDescriptorTypes for
binding share the same offset.
If the size of the mutable descriptor is larger
than the size of a concrete descriptor type being accessed, the padding area
is ignored by the implementation.
To get descriptor data to place in a buffer, call:
// Provided by VK_EXT_descriptor_buffer
void vkGetDescriptorEXT(
VkDevice device,
const VkDescriptorGetInfoEXT* pDescriptorInfo,
size_t dataSize,
void* pDescriptor);
-
deviceis the logical device that gets the descriptor. -
pDescriptorInfois a pointer to a VkDescriptorGetInfoEXT structure specifying the parameters of the descriptor to get. -
dataSizeis the amount of the descriptor data to get in bytes. -
pDescriptoris a pointer to an application-allocated buffer where the descriptor will be written.
The size of the data for each descriptor type is determined by the value in VkPhysicalDeviceDescriptorBufferPropertiesEXT. This value also defines the stride in bytes for arrays of that descriptor type.
If the
VkPhysicalDeviceDescriptorBufferPropertiesEXT::combinedImageSamplerDescriptorSingleArray
property is VK_FALSE the implementation requires an array of
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptors to be written
into a descriptor buffer as an array of image descriptors, immediately
followed by an array of sampler descriptors.
Applications must write the first
VkPhysicalDeviceDescriptorBufferPropertiesEXT::sampledImageDescriptorSize
bytes of the data returned through pDescriptor to the first array, and
the remaining
VkPhysicalDeviceDescriptorBufferPropertiesEXT::samplerDescriptorSize
bytes of the data to the second array.
For variable-sized descriptor bindings of
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptors, the two arrays
each have a size equal to the upper bound descriptorCount of that
binding.
A descriptor obtained by this command references the underlying VkImageView or VkSampler, and these objects must not be destroyed before the last time a descriptor is dynamically accessed. For descriptor types which consume an address instead of an object, the underlying VkBuffer is referenced instead.
Information about the descriptor to get is passed in a
VkDescriptorGetInfoEXT structure:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkDescriptorGetInfoEXT {
VkStructureType sType;
const void* pNext;
VkDescriptorType type;
VkDescriptorDataEXT data;
} VkDescriptorGetInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis the type of descriptor to get. -
datais a structure containing the information needed to get the descriptor.
Data describing the descriptor is passed in a VkDescriptorDataEXT
structure:
// Provided by VK_EXT_descriptor_buffer
typedef union VkDescriptorDataEXT {
const VkSampler* pSampler;
const VkDescriptorImageInfo* pCombinedImageSampler;
const VkDescriptorImageInfo* pInputAttachmentImage;
const VkDescriptorImageInfo* pSampledImage;
const VkDescriptorImageInfo* pStorageImage;
const VkDescriptorAddressInfoEXT* pUniformTexelBuffer;
const VkDescriptorAddressInfoEXT* pStorageTexelBuffer;
const VkDescriptorAddressInfoEXT* pUniformBuffer;
const VkDescriptorAddressInfoEXT* pStorageBuffer;
VkDeviceAddress accelerationStructure;
} VkDescriptorDataEXT;
-
pSampleris a pointer to a VkSampler handle specifying the parameters of aVK_DESCRIPTOR_TYPE_SAMPLERdescriptor. -
pCombinedImageSampleris a pointer to a VkDescriptorImageInfo structure specifying the parameters of aVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERdescriptor. -
pInputAttachmentImageis a pointer to a VkDescriptorImageInfo structure specifying the parameters of aVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTdescriptor. -
pSampledImageis a pointer to a VkDescriptorImageInfo structure specifying the parameters of aVK_DESCRIPTOR_TYPE_SAMPLED_IMAGEdescriptor. -
pStorageImageis a pointer to a VkDescriptorImageInfo structure specifying the parameters of aVK_DESCRIPTOR_TYPE_STORAGE_IMAGEdescriptor. -
pUniformTexelBufferis a pointer to a VkDescriptorAddressInfoEXT structure specifying the parameters of aVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERdescriptor. -
pStorageTexelBufferis a pointer to a VkDescriptorAddressInfoEXT structure specifying the parameters of aVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERdescriptor. -
pUniformBufferis a pointer to a VkDescriptorAddressInfoEXT structure specifying the parameters of aVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERdescriptor. -
pStorageBufferis a pointer to a VkDescriptorAddressInfoEXT structure specifying the parameters of aVK_DESCRIPTOR_TYPE_STORAGE_BUFFERdescriptor. -
accelerationStructureis the address of a VkAccelerationStructureKHR specifying the parameters of aVK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHRdescriptor , or a VkAccelerationStructureNV handle specifying the parameters of aVK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NVdescriptor.
If the nullDescriptor feature is enabled,
pSampledImage, pStorageImage, pUniformTexelBuffer,
pStorageTexelBuffer, pUniformBuffer, and pStorageBuffer
can each be NULL.
Loads from a null descriptor return zero values and stores and atomics to a
null descriptor are discarded.
If the nullDescriptor feature is enabled,
accelerationStructure can be 0.
A null acceleration structure descriptor results in the miss shader being
invoked.
Data describing a VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER,
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER,
VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, or
VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER descriptor is passed in a
VkDescriptorAddressInfoEXT structure:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkDescriptorAddressInfoEXT {
VkStructureType sType;
void* pNext;
VkDeviceAddress address;
VkDeviceSize range;
VkFormat format;
} VkDescriptorAddressInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
addressis either0or a device address at an offset in a buffer, where the base address can be queried from vkGetBufferDeviceAddress. -
rangeis the size in bytes of the buffer or buffer view used by the descriptor. -
formatis the format of the data elements in the buffer view and is ignored for buffers.
If the nullDescriptor feature is enabled,
address can be zero.
Loads from a null descriptor return zero values and stores and atomics to a
null descriptor are discarded.
Immutable samplers specified in a descriptor set layout through
pImmutableSamplers must be provided by applications when obtaining
descriptor data.
Immutable samplers written in a descriptor buffer must have identical
parameters to the immutable samplers in the descriptor set layout that
consumes the sampler.
|
Note
|
If the descriptor set layout was created with
|
|
Note
|
As descriptors are now in regular memory, drivers cannot hide copies of immutable samplers that end up in descriptor sets from the application. As such, applications are required to provide these samplers as if they were not provided immutably. |
The VkDescriptorGetTensorInfoARM is defined as:
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
typedef struct VkDescriptorGetTensorInfoARM {
VkStructureType sType;
const void* pNext;
VkTensorViewARM tensorView;
} VkDescriptorGetTensorInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensorViewis a VkTensorViewARM handle specifying the parameters of aVK_DESCRIPTOR_TYPE_TENSOR_ARMdescriptor.
14.4.2. Binding Descriptor Buffers
Descriptor buffers have their own separate binding point on the command buffer, with buffers bound using vkCmdBindDescriptorBuffersEXT. vkCmdSetDescriptorBufferOffsetsEXT assigns pairs of buffer binding indices and buffer offsets to the same binding point on the command buffer as vkCmdBindDescriptorSets, allowing subsequent bound pipeline commands to use the specified descriptor buffers. Bindings applied via vkCmdBindDescriptorSets cannot exist simultaneously with those applied via calls to vkCmdSetDescriptorBufferOffsetsEXT or vkCmdBindDescriptorBufferEmbeddedSamplersEXT, as calls to vkCmdSetDescriptorBufferOffsetsEXT or vkCmdBindDescriptorBufferEmbeddedSamplersEXT invalidate any bindings by previous calls to vkCmdBindDescriptorSets and vice-versa.
To bind descriptor buffers to a command buffer, call:
// Provided by VK_EXT_descriptor_buffer
void vkCmdBindDescriptorBuffersEXT(
VkCommandBuffer commandBuffer,
uint32_t bufferCount,
const VkDescriptorBufferBindingInfoEXT* pBindingInfos);
-
commandBufferis the command buffer that the descriptor buffers will be bound to. -
bufferCountis the number of elements in thepBindingInfosarray. -
pBindingInfosis a pointer to an array of VkDescriptorBufferBindingInfoEXT structures.
vkCmdBindDescriptorBuffersEXT causes any offsets previously set by
vkCmdSetDescriptorBufferOffsetsEXT that use the bindings numbered
[0..
bufferCount-1] to be no longer valid for subsequent bound pipeline
commands.
Any previously bound buffers at binding points greater than or equal to
bufferCount are unbound.
Data describing a descriptor buffer binding is passed in a
VkDescriptorBufferBindingInfoEXT structure:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkDescriptorBufferBindingInfoEXT {
VkStructureType sType;
const void* pNext;
VkDeviceAddress address;
VkBufferUsageFlags usage;
} VkDescriptorBufferBindingInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
addressis a VkDeviceAddress specifying the device address defining the descriptor buffer to be bound. -
usageis a bitmask of VkBufferUsageFlagBits specifying the VkBufferCreateInfo::usagefor the buffer from whichaddresswas queried.
If the pNext chain includes a VkBufferUsageFlags2CreateInfo
structure, VkBufferUsageFlags2CreateInfo::usage from that
structure is used instead of usage from this structure.
When the VkPhysicalDeviceDescriptorBufferPropertiesEXT::bufferlessPushDescriptors
property is VK_FALSE, the VkBuffer handle of the buffer for push
descriptors is passed in a
VkDescriptorBufferBindingPushDescriptorBufferHandleEXT structure:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkDescriptorBufferBindingPushDescriptorBufferHandleEXT {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
} VkDescriptorBufferBindingPushDescriptorBufferHandleEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferis theVkBufferhandle of the buffer for push descriptors.
To set descriptor buffer offsets in a command buffer, call:
// Provided by VK_EXT_descriptor_buffer
void vkCmdSetDescriptorBufferOffsetsEXT(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipelineLayout layout,
uint32_t firstSet,
uint32_t setCount,
const uint32_t* pBufferIndices,
const VkDeviceSize* pOffsets);
-
commandBufferis the command buffer in which the descriptor buffer offsets will be set. -
pipelineBindPointis a VkPipelineBindPoint indicating the type of the pipeline that will use the descriptors. -
layoutis a VkPipelineLayout object used to program the bindings. -
firstSetis the number of the first set to be bound. -
setCountis the number of elements in thepBufferIndicesandpOffsetsarrays. -
pBufferIndicesis a pointer to an array of indices into the descriptor buffer binding points set by vkCmdBindDescriptorBuffersEXT. -
pOffsetsis a pointer to an array of VkDeviceSize offsets to apply to the bound descriptor buffers.
vkCmdSetDescriptorBufferOffsetsEXT binds setCount pairs of
descriptor buffers, specified by indices into the binding points bound using
vkCmdBindDescriptorBuffersEXT, and buffer offsets to set numbers
[firstSet..firstSet+descriptorSetCount-1] for subsequent
bound pipeline commands set by
pipelineBindPoint.
Set [firstSet + i] is bound to the descriptor buffer at binding
pBufferIndices[i] at an offset of pOffsets[i].
Any bindings that were previously applied via these sets, or calls to
vkCmdBindDescriptorSets, are no longer valid.
Other sets will also be invalidated upon calling this command if
layout differs from the pipeline layout used to bind those other sets,
as described in Pipeline Layout
Compatibility.
After binding descriptors, applications can modify descriptor memory either
by performing writes on the host or with device commands.
When descriptor memory is updated with device commands, visibility for the
shader stage accessing a descriptor is ensured with the
VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT access flag.
Implementations must not access resources referenced by these descriptors
unless they are dynamically accessed by shaders.
Descriptors bound with this call can be undefined if they are not
dynamically accessed by shaders.
Implementations may read descriptor data for any statically accessed
descriptor if the binding in layout is not declared with the
VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT flag.
If the binding in layout is declared with
VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, implementations
must not read descriptor data that is not dynamically accessed.
Applications must ensure that any descriptor which the implementation may read must be in-bounds of the underlying descriptor buffer binding.
|
Note
|
Applications can freely decide how large a variable descriptor buffer binding is, so it may not be safe to read such descriptor payloads statically. The intention of these rules is to allow implementations to speculatively prefetch descriptor payloads where feasible. |
Dynamically accessing a resource through descriptor data from an unbound region of a sparse partially-resident buffer will result in invalid descriptor data being read, and therefore undefined behavior.
|
Note
|
For descriptors written by the host, visibility is implied through the
automatic visibility operation on queue submit, and there is no need to
consider |
|
Note
|
The requirements above imply that all descriptor bindings have been defined
with the equivalent of |
Alternatively, to set descriptor buffer offsets in a command buffer, call:
// Provided by VK_KHR_maintenance6 with VK_EXT_descriptor_buffer
void vkCmdSetDescriptorBufferOffsets2EXT(
VkCommandBuffer commandBuffer,
const VkSetDescriptorBufferOffsetsInfoEXT* pSetDescriptorBufferOffsetsInfo);
-
commandBufferis the command buffer in which the descriptor buffer offsets will be set. -
pSetDescriptorBufferOffsetsInfois a pointer to aVkSetDescriptorBufferOffsetsInfoEXTstructure.
The VkSetDescriptorBufferOffsetsInfoEXT structure is defined as:
// Provided by VK_KHR_maintenance6 with VK_EXT_descriptor_buffer
typedef struct VkSetDescriptorBufferOffsetsInfoEXT {
VkStructureType sType;
const void* pNext;
VkShaderStageFlags stageFlags;
VkPipelineLayout layout;
uint32_t firstSet;
uint32_t setCount;
const uint32_t* pBufferIndices;
const VkDeviceSize* pOffsets;
} VkSetDescriptorBufferOffsetsInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stageFlagsis a bitmask of VkShaderStageFlagBits specifying the shader stages the descriptor sets will be bound to -
layoutis a VkPipelineLayout object used to program the bindings. If thedynamicPipelineLayoutfeature is enabled,layoutcan be VK_NULL_HANDLE and the layout must be specified by chaining VkPipelineLayoutCreateInfo structure off thepNext -
firstSetis the number of the first set to be bound. -
setCountis the number of elements in thepBufferIndicesandpOffsetsarrays. -
pBufferIndicesis a pointer to an array of indices into the descriptor buffer binding points set by vkCmdBindDescriptorBuffersEXT. -
pOffsetsis a pointer to an array of VkDeviceSize offsets to apply to the bound descriptor buffers.
If stageFlags specifies a subset of all stages corresponding to one or
more pipeline bind points, the binding operation still affects all stages
corresponding to the given pipeline bind point(s) as if the equivalent
original version of this command had been called with the same parameters.
For example, specifying a stageFlags value of
VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT |
VK_SHADER_STAGE_COMPUTE_BIT is equivalent to calling the original
version of this command once with VK_PIPELINE_BIND_POINT_GRAPHICS and
once with VK_PIPELINE_BIND_POINT_COMPUTE.
To bind an embedded immutable sampler set to a command buffer, call:
// Provided by VK_EXT_descriptor_buffer
void vkCmdBindDescriptorBufferEmbeddedSamplersEXT(
VkCommandBuffer commandBuffer,
VkPipelineBindPoint pipelineBindPoint,
VkPipelineLayout layout,
uint32_t set);
-
commandBufferis the command buffer that the embedded immutable samplers will be bound to. -
pipelineBindPointis a VkPipelineBindPoint indicating the type of the pipeline that will use the embedded immutable samplers. -
layoutis a VkPipelineLayout object used to program the bindings. -
setis the number of the set to be bound.
vkCmdBindDescriptorBufferEmbeddedSamplersEXT binds the embedded immutable
samplers in set of layout to set for the command buffer
for subsequent bound pipeline commands set
by pipelineBindPoint.
Any previous binding to this set by vkCmdSetDescriptorBufferOffsetsEXT
or this command is overwritten.
Any sets that were last bound by a call to vkCmdBindDescriptorSets are
invalidated upon calling this command.
Other sets will also be invalidated upon calling this command if
layout differs from the pipeline layout used to bind those other sets,
as described in Pipeline Layout
Compatibility.
Alternatively, to bind an embedded immutable sampler set to a command buffer, call:
// Provided by VK_KHR_maintenance6 with VK_EXT_descriptor_buffer
void vkCmdBindDescriptorBufferEmbeddedSamplers2EXT(
VkCommandBuffer commandBuffer,
const VkBindDescriptorBufferEmbeddedSamplersInfoEXT* pBindDescriptorBufferEmbeddedSamplersInfo);
-
commandBufferis the command buffer that the embedded immutable samplers will be bound to. -
pBindDescriptorBufferEmbeddedSamplersInfois a pointer to aVkBindDescriptorBufferEmbeddedSamplersInfoEXTstructure.
The VkBindDescriptorBufferEmbeddedSamplersInfoEXT structure is defined
as:
// Provided by VK_KHR_maintenance6 with VK_EXT_descriptor_buffer
typedef struct VkBindDescriptorBufferEmbeddedSamplersInfoEXT {
VkStructureType sType;
const void* pNext;
VkShaderStageFlags stageFlags;
VkPipelineLayout layout;
uint32_t set;
} VkBindDescriptorBufferEmbeddedSamplersInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stageFlagsis a bitmask of VkShaderStageFlagBits specifying the shader stages that will use the embedded immutable samplers. -
layoutis a VkPipelineLayout object used to program the bindings. If thedynamicPipelineLayoutfeature is enabled,layoutcan be VK_NULL_HANDLE and the layout must be specified by chaining VkPipelineLayoutCreateInfo structure off thepNext -
setis the number of the set to be bound.
If stageFlags specifies a subset of all stages corresponding to one or
more pipeline bind points, the binding operation still affects all stages
corresponding to the given pipeline bind point(s) as if the equivalent
original version of this command had been called with the same parameters.
For example, specifying a stageFlags value of
VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT |
VK_SHADER_STAGE_COMPUTE_BIT is equivalent to calling the original
version of this command once with VK_PIPELINE_BIND_POINT_GRAPHICS and
once with VK_PIPELINE_BIND_POINT_COMPUTE.
14.4.3. Updating Descriptor Buffers
Updates to descriptor data in buffers can be performed by any operation on either the host or device that can access memory.
Descriptor buffer reads can be synchronized using
VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT in the relevant shader
stage.
14.4.4. Push Descriptors With Descriptor Buffers
If the descriptorBufferPushDescriptors feature is enabled, push descriptors
can be used with descriptor buffers in the same way as with descriptor
sets.
The VkPhysicalDeviceDescriptorBufferPropertiesEXT::bufferlessPushDescriptors
property indicates whether the implementation requires a buffer to back push
descriptors.
If the property is VK_FALSE then before recording any push descriptors
the application must bind exactly 1 descriptor buffer that was created
with the VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT
bit set.
When this buffer is bound any previously recorded push descriptors that are
required for a subsequent command must be recorded again.
14.4.5. Capture and Replay
In a similar way to bufferDeviceAddressCaptureReplay, the
descriptorBufferCaptureReplay feature allows the creation of opaque
handles for objects at capture time that can be passed into object creation
calls in a future replay, causing descriptors to be created with the same
data.
The opaque memory address for any memory used by these resources must have
been captured using vkGetDeviceMemoryOpaqueCaptureAddress and be
replayed using VkMemoryOpaqueCaptureAddressAllocateInfo.
To get the opaque descriptor data for a buffer, call:
// Provided by VK_EXT_descriptor_buffer
VkResult vkGetBufferOpaqueCaptureDescriptorDataEXT(
VkDevice device,
const VkBufferCaptureDescriptorDataInfoEXT* pInfo,
void* pData);
-
deviceis the logical device that gets the data. -
pInfois a pointer to a VkBufferCaptureDescriptorDataInfoEXT structure specifying the buffer. -
pDatais a pointer to an application-allocated buffer where the data will be written.
Information about the buffer to get descriptor buffer capture data for is
passed in a VkBufferCaptureDescriptorDataInfoEXT structure:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkBufferCaptureDescriptorDataInfoEXT {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
} VkBufferCaptureDescriptorDataInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferis theVkBufferhandle of the buffer to get opaque capture data for.
To get the opaque capture descriptor data for an image, call:
// Provided by VK_EXT_descriptor_buffer
VkResult vkGetImageOpaqueCaptureDescriptorDataEXT(
VkDevice device,
const VkImageCaptureDescriptorDataInfoEXT* pInfo,
void* pData);
-
deviceis the logical device that gets the data. -
pInfois a pointer to a VkImageCaptureDescriptorDataInfoEXT structure specifying the image. -
pDatais a pointer to an application-allocated buffer where the data will be written.
Information about the image to get descriptor buffer capture data for is
passed in a VkImageCaptureDescriptorDataInfoEXT structure:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkImageCaptureDescriptorDataInfoEXT {
VkStructureType sType;
const void* pNext;
VkImage image;
} VkImageCaptureDescriptorDataInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis theVkImagehandle of the image to get opaque capture data for.
To get the opaque capture descriptor data for an image view, call:
// Provided by VK_EXT_descriptor_buffer
VkResult vkGetImageViewOpaqueCaptureDescriptorDataEXT(
VkDevice device,
const VkImageViewCaptureDescriptorDataInfoEXT* pInfo,
void* pData);
-
deviceis the logical device that gets the data. -
pInfois a pointer to a VkImageViewCaptureDescriptorDataInfoEXT structure specifying the image view. -
pDatais a pointer to an application-allocated buffer where the data will be written.
Information about the image view to get descriptor buffer capture data for
is passed in a VkImageViewCaptureDescriptorDataInfoEXT structure:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkImageViewCaptureDescriptorDataInfoEXT {
VkStructureType sType;
const void* pNext;
VkImageView imageView;
} VkImageViewCaptureDescriptorDataInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis theVkImageViewhandle of the image view to get opaque capture data for.
To get the opaque capture descriptor data for a sampler, call:
// Provided by VK_EXT_descriptor_buffer
VkResult vkGetSamplerOpaqueCaptureDescriptorDataEXT(
VkDevice device,
const VkSamplerCaptureDescriptorDataInfoEXT* pInfo,
void* pData);
-
deviceis the logical device that gets the data. -
pInfois a pointer to a VkSamplerCaptureDescriptorDataInfoEXT structure specifying the sampler. -
pDatais a pointer to an application-allocated buffer where the data will be written.
Information about the sampler to get descriptor buffer capture data for is
passed in a VkSamplerCaptureDescriptorDataInfoEXT structure:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkSamplerCaptureDescriptorDataInfoEXT {
VkStructureType sType;
const void* pNext;
VkSampler sampler;
} VkSamplerCaptureDescriptorDataInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sampleris theVkSamplerhandle of the sampler to get opaque capture data for.
To get the opaque capture descriptor data for an acceleration structure, call:
// Provided by VK_EXT_descriptor_buffer with VK_KHR_acceleration_structure or VK_NV_ray_tracing
VkResult vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT(
VkDevice device,
const VkAccelerationStructureCaptureDescriptorDataInfoEXT* pInfo,
void* pData);
-
deviceis the logical device that gets the data. -
pInfois a pointer to a VkAccelerationStructureCaptureDescriptorDataInfoEXT structure specifying the acceleration structure. -
pDatais a pointer to an application-allocated buffer where the data will be written.
Information about the acceleration structure to get descriptor buffer
capture data for is passed in a
VkAccelerationStructureCaptureDescriptorDataInfoEXT structure:
// Provided by VK_EXT_descriptor_buffer with VK_KHR_acceleration_structure or VK_NV_ray_tracing
typedef struct VkAccelerationStructureCaptureDescriptorDataInfoEXT {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureKHR accelerationStructure;
VkAccelerationStructureNV accelerationStructureNV;
} VkAccelerationStructureCaptureDescriptorDataInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructureis theVkAccelerationStructureKHRhandle of the acceleration structure to get opaque capture data for. -
accelerationStructureNVis theVkAccelerationStructureNVhandle of the acceleration structure to get opaque capture data for.
The VkOpaqueCaptureDescriptorDataCreateInfoEXT structure is defined
as:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkOpaqueCaptureDescriptorDataCreateInfoEXT {
VkStructureType sType;
const void* pNext;
const void* opaqueCaptureDescriptorData;
} VkOpaqueCaptureDescriptorDataCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
opaqueCaptureDescriptorDatais a pointer to an application-allocated buffer containing opaque capture data retrieved using vkGetBufferOpaqueCaptureDescriptorDataEXT, vkGetImageOpaqueCaptureDescriptorDataEXT, vkGetImageViewOpaqueCaptureDescriptorDataEXT, vkGetTensorOpaqueCaptureDescriptorDataARM, vkGetTensorViewOpaqueCaptureDescriptorDataARM, vkGetSamplerOpaqueCaptureDescriptorDataEXT, or vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT.
During replay, opaque descriptor capture data can be specified by adding a
VkOpaqueCaptureDescriptorDataCreateInfoEXT structure to the relevant
pNext chain of a VkBufferCreateInfo, VkImageCreateInfo,
VkImageViewCreateInfo, VkSamplerCreateInfo,
VkTensorCreateInfoARM, VkTensorViewCreateInfoARM,
VkAccelerationStructureCreateInfoNV or
VkAccelerationStructureCreateInfoKHR structure.
To get the opaque capture descriptor data for a tensor, call:
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
VkResult vkGetTensorOpaqueCaptureDescriptorDataARM(
VkDevice device,
const VkTensorCaptureDescriptorDataInfoARM* pInfo,
void* pData);
-
deviceis the logical device that gets the data. -
pInfois a pointer to a VkTensorCaptureDescriptorDataInfoARM structure specifying the tensor. -
pDatais a pointer to a user-allocated buffer where the data will be written.
Information about the tensor to get descriptor buffer capture data for is
passed in a VkTensorCaptureDescriptorDataInfoARM structure:
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
typedef struct VkTensorCaptureDescriptorDataInfoARM {
VkStructureType sType;
const void* pNext;
VkTensorARM tensor;
} VkTensorCaptureDescriptorDataInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensoris theVkTensorARMhandle of the tensor to get opaque capture data for.
To get the opaque capture descriptor data for a tensor view, call:
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
VkResult vkGetTensorViewOpaqueCaptureDescriptorDataARM(
VkDevice device,
const VkTensorViewCaptureDescriptorDataInfoARM* pInfo,
void* pData);
-
deviceis the logical device that gets the data. -
pInfois a pointer to a VkTensorViewCaptureDescriptorDataInfoARM structure specifying the tensor view. -
pDatais a pointer to a user-allocated buffer where the data will be written.
Information about the tensor view to get descriptor buffer capture data for
is passed in a VkTensorViewCaptureDescriptorDataInfoARM structure:
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
typedef struct VkTensorViewCaptureDescriptorDataInfoARM {
VkStructureType sType;
const void* pNext;
VkTensorViewARM tensorView;
} VkTensorViewCaptureDescriptorDataInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensorViewis theVkTensorViewARMhandle of the tensor view to get opaque capture data for.
15. Shader Interfaces
When a pipeline is created, the set of shaders specified in the
corresponding VkPipelineCreateInfo 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
, except for the mesh output interface where there must be at most one
built-in interface block decorated with the PerPrimitiveEXT decoration
and at most one built-in interface block without this decoration
.
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 numeric type or, recursively,
composite types of such types.
If an implementation supports storageInputOutput16, components can 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 and Component Assignment
User-defined variables in interfaces
between shader stages in the graphics pipeline consume a unique set of
Location and Component values.
Available space for user-defined interface variables is partitioned into a
number of 32-bit four-component vectors, each identified by a Location
value.
Each individual 32-bit component of a vector is then further identified by a
Component value.
16-bit scalar or vector values consume one Component slot per 16-bit
component and must be specified within a single Location.
32-bit scalar or vector values consume one Component slot per 32-bit
component and must be specified within a single Location.
64-bit scalar or vector values consume two consecutive Component slots
per 64-bit component from up to two consecutive Location slots.
For any shader interface variable where one level of the array is disregarded for type matching, the outer array
level is also disregarded when assigning Location slots.
An array of size n with elements consuming l Location slots
each will consume l × n Location slots.
Each element of the array will consume Component slots in each
Location slot identically to a declaration using the element type.
Matrices of size n × m are assigned locations identically to
arrays of size n of vectors of length 4 (consuming all Component
slots) with an identical element type.
When an OpVariable with a structure type 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.
The Location slots consumed by 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.
An OpVariable with a structure type that is not decorated with
Block must be decorated with a Location.
When an OpVariable with a structure type decorated with Block is
declared without a Location decoration, each member in the structure
must be decorated with a Location.
Types nested deeper than the top-level members must not have Location
decorations.
Multiple variable declarations in the same storage class must not have
overlapping Component slots within the same Location.
The number of input and output locations available for a shader input or
output interface depend 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
Location slots 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 |
|
cluster culling output |
|
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 Location slots 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.
Components and locations are consumed as defined for
Location and Component Assignment.
Multiple user-defined input variable
declarations must not have overlapping Component slots within the same
Location.
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 color attachment indicated by
VkRenderingInfo::pColorAttachments[i].
When using render pass objects, it is associated with
the color attachment indicated by
VkSubpassDescription::pColorAttachments[i].
Values are written to those attachments after passing through the blending
unit as described in Blending, if enabled.
The number of available fragment output Location slots is given by the
maxFragmentOutputAttachments member of the
VkPhysicalDeviceLimits structure.
If the
dynamicRenderingLocalRead
feature is supported, fragment output locations can be remapped when using
dynamic rendering.
To set the fragment output location mappings during rendering, call:
// Provided by VK_VERSION_1_4
void vkCmdSetRenderingAttachmentLocations(
VkCommandBuffer commandBuffer,
const VkRenderingAttachmentLocationInfo* pLocationInfo);
or the equivalent command
// Provided by VK_KHR_dynamic_rendering_local_read
void vkCmdSetRenderingAttachmentLocationsKHR(
VkCommandBuffer commandBuffer,
const VkRenderingAttachmentLocationInfo* pLocationInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pLocationInfois a VkRenderingAttachmentLocationInfo structure indicating the new mappings.
This command sets the attachment location mappings for subsequent drawing commands, and must match the mappings provided to the bound pipeline, if one is bound, which can be set by chaining VkRenderingAttachmentLocationInfo to VkGraphicsPipelineCreateInfo.
Until this command is called, mappings in the command buffer state are
treated as each color attachment specified in vkCmdBeginRendering
having a location equal to its index in
VkRenderingInfo::pColorAttachments.
This state is reset whenever vkCmdBeginRendering is called.
The VkRenderingAttachmentLocationInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkRenderingAttachmentLocationInfo {
VkStructureType sType;
const void* pNext;
uint32_t colorAttachmentCount;
const uint32_t* pColorAttachmentLocations;
} VkRenderingAttachmentLocationInfo;
or the equivalent
// Provided by VK_KHR_dynamic_rendering_local_read
typedef VkRenderingAttachmentLocationInfo VkRenderingAttachmentLocationInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
colorAttachmentCountis the number of elements inpColorAttachmentLocations. -
pColorAttachmentLocationsis a pointer to an array ofcolorAttachmentCountuint32_tvalues defining remapped locations for color attachments.
This structure allows applications to remap the locations of color attachments to different fragment shader output locations.
Each element of pColorAttachmentLocations set to
VK_ATTACHMENT_UNUSED will be inaccessible to this pipeline as a color
attachment; no location will map to it.
Each element of pColorAttachmentLocations set to any other value will
map the specified location value to the color attachment specified in the
render pass at the corresponding index in the
pColorAttachmentLocations array.
Any writes to a fragment output location that is not mapped to an attachment
must be discarded.
If pColorAttachmentLocations is NULL, it is equivalent to setting
each element to its index within the array.
This structure can be included in the pNext chain of a
VkGraphicsPipelineCreateInfo structure to set this state for a
pipeline.
If this structure is not included in the pNext chain of
VkGraphicsPipelineCreateInfo, it is equivalent to specifying this
structure with the following properties:
-
colorAttachmentCountset to VkPipelineRenderingCreateInfo::colorAttachmentCount. -
pColorAttachmentLocationsset toNULL.
This structure can be included in the pNext chain of a
VkCommandBufferInheritanceInfo structure to specify inherited state
from the primary command buffer.
If VkCommandBufferInheritanceInfo::renderPass is not
VK_NULL_HANDLE, or
VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in
VkCommandBufferBeginInfo::flags, members of this structure are
ignored.
If this structure is not included in the pNext chain of
VkCommandBufferInheritanceInfo, it is equivalent to specifying this
structure with the following properties:
-
colorAttachmentCountset to VkCommandBufferInheritanceRenderingInfo::colorAttachmentCount. -
pColorAttachmentLocationsset toNULL.
When an active fragment shader invocation finishes, the values of all
fragment shader outputs are copied out and used as blend inputs or color
attachments writes.
If the invocation does not set a value for them, the input values to those
blending or color attachment writes are undefined.
If there is no color attachment indicated by Location, the values that
would have been written to the color attachments are discarded.
Output Component words 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).
Component words which do not correspond to any fragment shader output
will also result in undefined values for blending or color attachment
writes.
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.
Components and locations are consumed as defined for
Location and Component Assignment.
Output variable declarations must not consume any of the same
Component slots within the same Location and with the same
Index value as any other output variable declaration.
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. Legacy Dithering
The application can enable dithering to be applied to the color output of a
subpass, by using the
VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT flag.
For use in a dynamic render pass, the
VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT flag must be used.
In that case, the pipelines used must have been created with
VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXT.
When dithering is enabled, the implementation may modify the output color value c by one ULP. This modification must only depend on the framebuffer coordinates (xf,yf) of the sample, as well as on the value of c.
The exact details of the dithering algorithm are unspecified, including the algorithm itself, the formats dithering is applied to, and the stage in which it is applied.
|
Note
|
This extension is intended only for use by OpenGL emulation layers, and as such the dithering algorithm applied to the subpass should be equivalent to the vendor’s OpenGL implementation, if any. |
15.5. Fragment Tile Image Interface
When a fragment stage is present in a pipeline, the fragment shader tile
image variables decorated with Location form an interface with the
color attachments defined by the render pass instance.
The fragment shader tile image variables are matched by Location
decorations to the color attachments specified in the
pColorAttachments array of the VkRenderingInfoKHR structure
describing the render pass instance the fragment shader is executed in.
The fragment shader variables listed by OpEntryPoint with the
TileImageEXT storage class and a decoration of Location form the
fragment tile image interface.
These variables must be declared with a type of OpTypeImage, and a
Dim operand of TileImageDataEXT.
The Component decoration is not supported for these variables.
Reading from a tile image variable with a Location decoration of i
reads from the color attachment identified by the element of
VkRenderingInfoKHR::pColorAttachments with a location
equal to i.
If the tile image variable is declared as an array of size N, it consumes N
consecutive tile image locations, starting with the index specified.
There must not be more than one tile image variable with the same
Location whether explicitly declared or implied by an array
declaration.
The number of available tile image locations is the same as the number of
available fragment output locations as given by the
maxFragmentOutputAttachments member of the
VkPhysicalDeviceLimits structure.
The basic data type (floating-point, integer, unsigned integer) of the tile image variable must match the basic format of the corresponding color attachment, or the values read from the tile image variables are undefined.
15.6. Tile Attachment Interface
The image variables declared with TileAttachmentQCOM storage class form
the tile attachment interface.
These tile attachment variables correspond to a per-tile view of the color, depth, or input attachment of the current subpass or render pass instance.
Such variables must only be declared and accessed in compute and fragment shaders invoked within a render pass instance that enables tile shading. Access of such variables in a fragment shader, additionally requires that the tileShadingFragmentStage feature must be enabled.
Tile attachment variables must not include a Component decoration.
Tile attachment variables must not be consumed by OpImageQuery*
instructions.
Tile attachment variables can be declared as either single-sampled with
MS operand of 0, or as multi-sampled with MS operand of 1.
The image subresources of the tile attachment image must not be in
VK_IMAGE_LAYOUT_UNDEFINED
or VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT
layout in order to access its data in a shader.
Tile attachment variables statically accessed by a fragment or compute
shader must be backed by a descriptor that is equivalent to the
VkImageView in the VkFramebuffer
or the VkRenderingAttachmentInfo
except for subresourceRange.aspectMask.
The aspectMask must be equal to the aspect accessed by the shader.
Tile attachment variables are further subdivided into storage tile attachment, sampled tile attachment, and input tile attachment variables.
-
Sampled tile attachment variables must be declared with a
Sampledoperand of1, must be backed by a descriptor of typeVK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM,VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM, orVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and can be used withOpImageFetch,OpImageSparseFetch, or used to construct anOpTypeSampledImagethat is subsequently consumed byOpImageSample*,OpImageSparseSample*,OpImageSampleWeightedQCOM,OpImageBoxFilterQCOM,OpImageBlockMatch*QCOM,OpImage*Gather, orOpImageSparse*Gather. Sampled tile attachment variables are managed by the Descriptor Set Interface as sampled images. -
Storage tile attachment variables must be declared with a
Sampledoperand of2, must be backed by a descriptor of typeVK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and can be used withOpImageRead,OpImageSparseRead, andOpImageWriteinstructions. Storage tile attachment variables can be consumed byOpImageTexelPointerfor compatibility with atomic operations. Sampled tile attachment variables are managed by the Descriptor Set Interface as storage images. -
Input tile attachment variables must be declared with a
Sampledoperand of2, must be backed by a descriptor of typeVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, and can be used withOpImageReadinstructions. Input tile attachment variables are managed by the Descriptor Set Interface as input attachment images.
Tile attachment access using OpImageWrite instructions must be used
only in the compute stage.
Tile attachment access using OpImageWrite instructions must not be
used on a variable whose underlying descriptor references the same
VkImageView bound as a depth or stencil attachment.
The basic data type (floating-point, integer, unsigned integer) of the tile attachment variable must match the basic format of the corresponding input, depth, or color attachment, otherwise the result of loads/stores for tile attachment variables is undefined. If the render pass attachment contains both depth and stencil aspects, the basic data type of the tile attachment variable determines if depth or stencil aspect is accessed by the shader.
15.7. 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
multisampled-render-to-single-sampled
is not enabled, 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 per image aspect.
A multi-aspect image (e.g. a depth/stencil format) can use the same input
variable.
The number of available input attachment indices is given by the
maxPerStageDescriptorInputAttachments member of the
VkPhysicalDeviceLimits structure.
When using dynamic rendering with the dynamicRenderingLocalRead feature enabled, a subpass input variable
with a InputAttachmentIndex decoration of i can be mapped to a color,
depth, or stencil attachment.
To set the input attachment index mappings during dynamic rendering, call:
// Provided by VK_VERSION_1_4
void vkCmdSetRenderingInputAttachmentIndices(
VkCommandBuffer commandBuffer,
const VkRenderingInputAttachmentIndexInfo* pInputAttachmentIndexInfo);
or the equivalent command
// Provided by VK_KHR_dynamic_rendering_local_read
void vkCmdSetRenderingInputAttachmentIndicesKHR(
VkCommandBuffer commandBuffer,
const VkRenderingInputAttachmentIndexInfo* pInputAttachmentIndexInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pInputAttachmentIndexInfois a VkRenderingInputAttachmentIndexInfo structure indicating the new mappings.
This command sets the input attachment index mappings for subsequent drawing commands, and must match the mappings provided to the bound pipeline, if one is bound, which can be set by chaining VkRenderingInputAttachmentIndexInfo to VkGraphicsPipelineCreateInfo.
Until this command is called, mappings in the command buffer state are
treated as each color attachment specified in vkCmdBeginRendering
mapping to subpass inputs with a InputAttachmentIndex equal to its
index in VkRenderingInfo::pColorAttachments, and depth/stencil
attachments mapping to input attachments without these decorations.
This state is reset whenever vkCmdBeginRendering is called.
The VkRenderingInputAttachmentIndexInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkRenderingInputAttachmentIndexInfo {
VkStructureType sType;
const void* pNext;
uint32_t colorAttachmentCount;
const uint32_t* pColorAttachmentInputIndices;
const uint32_t* pDepthInputAttachmentIndex;
const uint32_t* pStencilInputAttachmentIndex;
} VkRenderingInputAttachmentIndexInfo;
or the equivalent
// Provided by VK_KHR_dynamic_rendering_local_read
typedef VkRenderingInputAttachmentIndexInfo VkRenderingInputAttachmentIndexInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
colorAttachmentCountis the number of elements inpColorAttachmentInputIndices. -
pColorAttachmentInputIndicesis a pointer to an array ofcolorAttachmentCountuint32_tvalues defining indices for color attachments to be used as input attachments. -
pDepthInputAttachmentIndexis eitherNULL, or a pointer to auint32_tvalue defining the index for the depth attachment to be used as an input attachment. -
pStencilInputAttachmentIndexis eitherNULL, or a pointer to auint32_tvalue defining the index for the stencil attachment to be used as an input attachment.
This structure allows applications to remap attachments to different input attachment indices.
Each element of pColorAttachmentInputIndices set to a value of
VK_ATTACHMENT_UNUSED indicates that the corresponding attachment will
not be used as an input attachment in this pipeline.
Any other value in each of those elements will map the corresponding
attachment to a InputAttachmentIndex value defined in shader code.
If pColorAttachmentInputIndices is NULL, it is equivalent to setting
each element to its index within the array.
If pDepthInputAttachmentIndex or pStencilInputAttachmentIndex
are set to NULL, they map to input attachments without a
InputAttachmentIndex decoration.
If they point to a value of VK_ATTACHMENT_UNUSED, it indicates that
the corresponding attachment will not be used as an input attachment in this
pipeline.
If they point to any other value it maps the corresponding attachment to a
InputAttachmentIndex value defined in shader code.
This structure can be included in the pNext chain of a
VkGraphicsPipelineCreateInfo structure to set this state for a
pipeline.
If this structure is not included in the pNext chain of
VkGraphicsPipelineCreateInfo, it is equivalent to specifying this
structure with the following properties:
-
colorAttachmentCountset to VkPipelineRenderingCreateInfo::colorAttachmentCount. -
pColorAttachmentInputIndicesset toNULL. -
pDepthInputAttachmentIndexset toNULL. -
pStencilInputAttachmentIndexset toNULL.
This structure can be included in the pNext chain of a
VkCommandBufferInheritanceInfo structure to specify inherited state
from the primary command buffer.
If this structure is not included in the pNext chain of
VkCommandBufferInheritanceInfo, it is equivalent to specifying this
structure with the following properties:
-
colorAttachmentCountset to VkCommandBufferInheritanceRenderingInfo::colorAttachmentCount. -
pColorAttachmentInputIndicesset toNULL. -
pDepthInputAttachmentIndexset toNULL. -
pStencilInputAttachmentIndexset toNULL.
Variables identified with the InputAttachmentIndex must only be used
by a fragment stage.
The numeric format of the subpass input must
match the format of the corresponding input attachment, or the values of
subpass loads from these variables are undefined.
If the framebuffer attachment contains both depth and stencil aspects, the
numeric format of the subpass input determines if depth or stencil aspect is
accessed by the shader.
See Input Attachment for more details.
15.7.1. Fragment Input Attachment Compatibility
An input attachment that is statically accessed by a fragment shader must
be backed by a descriptor that is equivalent to the VkImageView in the
VkFramebuffer, except for subresourceRange.aspectMask.
The aspectMask must be equal to the aspect accessed by the shader.
15.8. 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.9. Shader Resource Interface
When a shader stage accesses buffer, tensor, 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.9.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.9.2. Descriptor Set Interface
The descriptor set interface is comprised of the shader variables with the
storage class of
StorageBuffer,
TileAttachmentQCOM,
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).
Storage tile attachment and sampled tile attachment variables declared as described in the tile attachment interface are also managed by this interface. The requirements in this section for storage image variables also applies to storage tile attachment variables. The requirements in this section for sampled image variables also applies to sampled tile attachment variables. The requirements in this section for input attachment variables also applies to input tile attachment variables.
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.
When accessing a resource through such a variable, the resource must be selected via compile time constant expressions unless features are enabled to allow dynamically uniform or non-uniform expressions, as described below:
-
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.
-
-
-
Dynamically uniform: Always supported.
-
Non-uniform: Never supported.
-
-
-
Dynamically uniform: Always supported.
-
Non-uniform: Never supported.
-
-
Storage tensors:
-
Dynamically uniform:
shaderStorageTensorArrayDynamicIndexingandStorageTensorArrayDynamicIndexingARM -
Non-uniform:
shaderStorageTensorArrayNonUniformIndexingandStorageTensorArrayNonUniformIndexingARM
-
|
Note
|
Implementations must take care when implementing this if subgroups are not necessarily a subset of the invocation group for their hardware (e.g. if multiple draw calls are packed together). If such an implementation needs uniformity across the subgroup for any resource access, the implementation is responsible for ensuring that indices that are only dynamically uniform across the invocation group still function as expected if they advertise the respective feature. |
A combined image sampler in an array that enables sampler Y′CBCR conversion or samples a subsampled image must only be indexed by constant integral expressions.
| 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 |
|
weight image |
|
block matching image |
|
storage tensor |
|
| 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 |
|
|
|
sample weight image |
|
|
|
block matching image |
|
|
|
storage tensor |
|
|
- 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.9.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_EXT 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
VkMutableDescriptorTypeListEXT.
If multiple descriptor types in VkMutableDescriptorTypeListEXT 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 |
|
sample weight image |
|
block matching image |
|
|
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.9.4. Offset and Stride Assignment
When a SPIR-V object is declared using an explicit layout, it must be laid out according to the following additional requirements.
|
Note
|
The numeric order of |
Alignment Requirements
There are different alignment requirements depending on the specific resources and on the features enabled.
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 structure 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 structure 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 and the storage class isUniform,StorageBuffer,PhysicalStorageBuffer,ShaderRecordBufferKHR, orPushConstantthen every member must be aligned according to its scalar alignment. -
If the
workgroupMemoryExplicitLayoutScalarBlockLayoutfeature is enabled 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, 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. -
The storage class is
Workgroup, and either the structure member is not part of aBlockor theworkgroupMemoryExplicitLayoutScalarBlockLayoutfeature is not enabled. -
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.10. 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.
Any two Input storage class OpVariable declarations listed as
operands on the same OpEntryPoint must not have the same BuiltIn
decoration.
Any two Output storage class OpVariable declarations listed as
operands on the same OpEntryPoint must not have the same BuiltIn
decoration.
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.
ClusterIDHUAWEI-
The
ClusterIDHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this variable will contain an integer value that specifies the id of cluster being rendered by this drawing command. When Cluster Culling Shader enable,ClusterIDHUAWEIwill replace gl_DrawID pass to vertex shader for cluster-related information fetching.
ClusterShadingRateHUAWEI-
The
ClusterShadingRateHUAWEIdecoration can be used to decorate a cluster culling shader output variable. This variable will contain an integer value specifying the shading rate of a rendering cluster.
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.
CullPrimitiveEXT-
Decorating a variable with the
CullPrimitiveEXTbuilt-in decoration will make that variable contain the culling state of output primitives. If the per-primitive boolean value istrue, the primitive will be culled, if it isfalseit will not be culled.
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 draw that invoked the current task, mesh, or vertex shader invocation. For indirect drawing commands,DrawIndexbegins at zero and increments by one for each draw executed. The number of draws 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. 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.
FirstIndexHUAWEI-
The
FirstIndexHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this indexed mode specific variable will contain an integer value that specifies the base index within the index buffer corresponding to a cluster.
FragCoord-
Decorating a variable with the
FragCoordbuilt-in decoration will make that variable contain the coordinates (x,y,z,1/w) of the fragment being processed.The (x,y) values are the framebuffer coordinates (xf,yf) of the fragment.
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.
FirstInstanceHUAWEI-
The
FirstInstanceHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this variable will contain an integer value that specifies the instance ID of the first instance to draw.
FirstVertexHUAWEI-
The
FirstVertexHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this non-indexed mode specific variable will contain an integer value that specifies the index of the first vertex in a cluster to draw.
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.
HitTriangleVertexPositionsKHR-
A variable decorated with the
HitTriangleVertexPositionsKHRdecoration will specify the object space vertices of the triangle at the current intersection in application-provided order. The positions returned are transformed by the geometry transform, which is performed at standard floating-point precision, but without a specifically defined order of floating-point operations to perform the matrix multiplication.
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 ray tracing pipeline must not cause any corresponding flags to be set in variables with this decoration.
IndexCountHUAWEI-
The
IndexCountHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this indexed mode specific variable will contain an integer value that specifies the number of indexed vertices in a cluster to draw.
InstanceCountHUAWEI-
The
InstanceCountHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this variable will contain an integer value that specifies the number of instance to draw in a cluster.
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 or vkCmdTraceRaysNV 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 or vkCmdTraceRaysNV 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. In a mesh shader this also applies when theLayervalue is greater than or equal to themaxMeshOutputLayerslimit.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 decorated
ViewportMaskNV, 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 cluster culling, 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 or the final rasterization of polygons if polygon mode isVK_POLYGON_MODE_POINTwhenVkPhysicalDeviceMaintenance5Properties::polygonModePointSizeis set toVK_TRUE. 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. If themaintenance5feature is enabled and a value is not written to a variable decorated withPointSize, a value of 1.0 is used as the size of points.
|
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 (OutputTrianglesNV) indices and each group generates a primitive.
PrimitivePointIndicesEXT-
Decorating a variable with the
PrimitivePointIndicesEXTdecoration will make that variable contain the output array of vertex index values for point primitives.
PrimitiveLineIndicesEXT-
Decorating a variable with the
PrimitiveLineIndicesEXTdecoration will make that variable contain the output array of vertex index values for line primitives.
PrimitiveTriangleIndicesEXT-
Decorating a variable with the
PrimitiveTriangleIndicesEXTdecoration will make that variable contain the output array of vertex index values for triangle primitives.
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 into the pipeline trace ray instruction.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 into the pipeline trace ray instruction.
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 into the pipeline trace ray instruction.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 shader object was created with theVK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXTflag 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, or the shader object was created with a chained VkShaderRequiredSubgroupSizeCreateInfoEXT structure, the
SubgroupSizedecorated variable will matchrequiredSubgroupSize.If SPIR-V
moduleis less than version 1.6 and the pipeline was not created with theVK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BITflag set and no VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure was chained, and the shader was not created with theVK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXTflag set and no VkShaderRequiredSubgroupSizeCreateInfoEXT 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.
TileOffsetQCOM-
The
TileOffsetQCOMdecoration can be applied to a shader input which will be filled with the framebuffer coordinates of the active tile.When per-tile execution model is enabled, for the current shader invocation x and y components of
TileOffsetQCOMreflect the framebuffer integer coordinates of the top-left texel of the tile corresponding to the shader invocation.Otherwise, the x and y components of
TileOffsetQCOMare filled with (0,0).
TileDimensionQCOM-
The
TileDimensionQCOMdecoration can be applied to a shader input which will be filled with the width and height of the active tile.When per-tile execution model is enabled, for the current shader invocation x and y components of
TileDimensionQCOMreflect the with and height of the tile corresponding to the shader invocation.Otherwise, the x and y components of
TileDimensionQCOMare filled with (0,0).
TileApronSizeQCOM-
The
TileApronSizeQCOMdecoration can be applied to a shader input which will be filled with the width and height of the active tile’s apron.If per-tile execution model is enabled for the current shader invocation, and is executing in a dynamic render pass or is executing in a subpass where
VK_SUBPASS_DESCRIPTION_TILE_SHADING_APRON_BIT_QCOMis included in itsflags, x and y components ofTileApronSizeQCOMreflect the with and height of the tile apron corresponding to the shader invocation.Otherwise, the x and y components of
TileApronSizeQCOMare filled with (0,0).
VertexCountHUAWEI-
The
VertexCountHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this non-indexed mode specific variable will contain an integer value that specifies the number of vertices in a cluster to draw.
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
|
|
VertexOffsetHUAWEI-
The
VertexOffsetHUAWEIdecoration can be used to decorate a cluster culling shader output variable,this indexed mode specific variable will contain an integer value that specifies an offset value added to the vertex index of a cluster before indexing into the vertex buffer.
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 the index of 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, and if the multiviewPerViewViewports feature is not enabled, 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.If the
multiviewPerViewViewportsfeature is enabled, and if the last active pre-rasterization shader stage shader entry point’s interface does not include a variable decorated withViewportIndex, then the value ofViewIndexis used as an index to select the viewport transform and scissor rectangle, and the value ofViewportIndexin the fragment shader is undefined.
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 coordinate of the local workgroup that the current invocation is a member of. Each component is in the range [base,base + count), where base and count are based on the parameters passed into the dispatching or drawing commands in each dimension.
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 into the pipeline trace ray instruction.
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 into the pipeline trace ray instruction.
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.
HitIsSphereNV-
A variable decorated with the
HitIsSphereNVdecoration will contain a non-zero value if the current ray hit a sphere primitive or zero otherwise.
HitIsLSSNV-
A variable decorated with the
HitIsLSSNVdecoration will contain a non-zero value if the current ray hit a LSS primitive or zero otherwise.
HitSpherePositionNV-
A variable decorated with the
HitSpherePositionNVdecoration will contain the position of sphere primitive intersected by current ray.
HitSphereRadiusNV-
A variable decorated with the
HitSphereRadiusNVdecoration will contain the radius of sphere primitive intersected by current ray.
HitLSSPositionsNV-
A variable decorated with the
HitLSSPositionsNVdecoration will contain the position of the LSS primitive intersected by current ray.
HitLSSRadiiNV-
A variable decorated with the
HitLSSRadiiNVdecoration will contain the radii of LSS primitive intersected by current ray.
CoreCountARM-
Decorating a variable with the
CoreCountARMbuilt-in decoration will make that variable contain the number of cores on the device.
CoreMaxIDARM-
Decorating a variable with the
CoreMaxIDARMbuilt-in decoration will make that variable contain the max ID of any shader core on the device on which the current shader invocation is running.
CoreIDARM-
Decorating a variable with the
CoreIDARMbuilt-in decoration will make that variable contain the ID of the core on which the current shader invocation is running. This variable is in the range [0,CoreMaxIDARM].
WarpMaxIDARM-
Decorating a variable with the
WarpMaxIDARMbuilt-in decoration will make that variable contain the maximum warp ID for the core on which the current invocation is running.
WarpIDARM-
Decorating a variable with the
WarpIDARMbuilt-in decoration will make that variable contain the ID of the warp on a core on which the current shader invocation is running. This variable is in the range [0,WarpMaxIDARM].
CoalescedInputCountAMDX-
Decorating a variable with the
CoalescedInputCountAMDXbuilt-in decoration will make that variable contain the number of node dispatches that the implementation coalesced into the input for the current shader. This variable will take a value in the range [1, arraySize), where arraySize is the maximum size of the input payload array for the shader.
ShaderIndexAMDX-
Decorating a variable with the
ShaderIndexAMDXbuilt-in decoration will make that variable contain the index of the shader specified when it was compiled, either via VkPipelineShaderStageNodeCreateInfoAMDX::indexor by theShaderIndexAMDXexecution mode.
ClusterIDNV-
A variable decorated with the
ClusterIDNVdecoration will contain the triangle cluster ID of a hit triangle in a cluster acceleration structure if the current ray hit a triangle primitive or-1otherwise.
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. -
OpImageWeightedSampleQCOMreads a 2D neighborhood of texels and computes a weighted average using weight values from a separate weight texture. -
opImageBlockMatchSADQCOMandopTextureBlockMatchSSDcompare 2D neighborhoods of texels from two textures. -
OpImageBoxFilterQCOMreads a 2D neighborhood of texels and computes a weighted average of the texels. -
opImageBlockMatchWindowSADQCOMandopImageBlockMatchWindowSSDQCOMcompare 2D neighborhoods of texels from two textures with the comparison repeated across a window region in the target texture. -
opImageBlockMatchGatherSADQCOMandopImageBlockMatchWindowSSDQCOMcompares four 2D neighborhoods of texels from a target texture with a single 2D neighborhood in the reference texture. The R component of each comparison is gathered and returned in the output.
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,
opImageBlockMatchSADQCOM, opImageBlockMatchSSDQCOM,
opImageBlockMatchWindowSADQCOM, opImageBlockMatchWindowSSDQCOM,
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.
If an accessed image was created from a view using
VkImageViewSlicedCreateInfoEXT and accessed through a
VK_DESCRIPTOR_TYPE_STORAGE_IMAGE descriptor, then the value of k
is incremented by VkImageViewSlicedCreateInfoEXT::sliceOffset,
giving k ← sliceOffset + k.
The image’s accessible range in the third dimension is k < sliceOffset
+ sliceCount.
If VkImageViewSlicedCreateInfoEXT::sliceCount is
VK_REMAINING_3D_SLICES_EXT, the range is inherited from the image’s
depth extent as specified by Image Mip
Level Sizing.
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
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 |
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.
The operations described in block matching and weight image sampling are performed before Conversion to RGBA and Component swizzle.
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:
-
If the image view’s
viewTypeis one ofVK_IMAGE_VIEW_TYPE_1D_ARRAY,VK_IMAGE_VIEW_TYPE_2D_ARRAY, orVK_IMAGE_VIEW_TYPE_CUBE_ARRAYthen the instruction must haveArrayed= 1. Otherwise the instruction must haveArrayed= 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 SPIR-V Type. -
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.
If the underlying VkImage format has an X component in its format
description, undefined values are read from those bits.
|
Note
|
If the |
|
Note
|
Some implementations will return undefined values in the case where a
sampler uses a VkSamplerAddressMode of
This behavior was not tested prior to Vulkan conformance test suite version 1.3.8.0. Affected implementations will have a conformance test waiver for this issue. |
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
VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM::enableYDegamma
is equal to VK_TRUE, then sRGB to linear conversion is applied to the
G component as described in the “sRGB EOTF” section of the
Khronos Data Format Specification.
If
VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM::enableCbCrDegamma
is equal to VK_TRUE, then sRGB to linear conversion is applied to the
R 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] |
Single component alpha format |
[Colorr,Colorg,Colorb, Colora] = [0,0,0,Ba] |
† S = Bg may be substituted as the replacement method by the
implementation when VkSamplerCreateInfo::borderColor is
VK_BORDER_COLOR_INT_CUSTOM_EXT and
VkSamplerCustomBorderColorCreateInfoEXT::format is
VK_FORMAT_UNDEFINED.
Implementations should use S = Br as the replacement method.
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 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.
If the value of magFilter is VK_FILTER_LINEAR, or the value of
minFilter is VK_FILTER_LINEAR, then D 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.
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] |
One alpha component color format |
[Colorr,Colorg,Colorb, Colora] = [0,0,0,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.
If the image view has a depth/stencil format and the
VkComponentSwizzle is VK_COMPONENT_SWIZZLE_ONE, and
VkPhysicalDeviceMaintenance5Properties::depthStencilSwizzleOneSupport
is not VK_TRUE, 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 are 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 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 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.
The input values to this stage may have been converted using sRGB to linear
conversion if the ycbcrDegamma feature is
enabled.
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
SPIR-V Type, 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.
If the VkImageView format has an X component in its format
description, undefined values are written to those bits.
If the underlying VkImage format has an X component in its format
description, undefined values are also written to those bits, even if
result format conversion produces a valid value for those bits because the
VkImageView format is different.
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
mesh, task,
compute, or
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 LOD 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
The partial derivatives of the Cube Map Coordinate Transformations can be computed as:
The other derivatives are simplified similarly, resulting in
16.5.7. Scale Factor Operation, LOD 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:
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 η.
LOD 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.
minLodimageView 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.
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.
If levelbase < minLodIntegerimageView, then any values fetched are
zero if the robustImageAccess2
feature is enabled.
Otherwise values are
undefined.
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, Zero Tangent Cardinal, B-Spline, or Mitchell-Netravali weights
as specified by VkSamplerCubicWeightsCreateInfoQCOM.
Catmull-Rom weights
specified by VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM
are derived from the fractions computed earlier.
Zero Tangent Cardinal weights specified by
VK_CUBIC_FILTER_WEIGHTS_ZERO_TANGENT_CARDINAL_QCOM are derived from
the fractions computed earlier.
B-Spline weights specified by VK_CUBIC_FILTER_WEIGHTS_B_SPLINE_QCOM
are derived from the fractions computed earlier.
Mitchell-Netravali weights specified by
VK_CUBIC_FILTER_WEIGHTS_MITCHELL_NETRAVALI_QCOM 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
or VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_RANGECLAMP_QCOM
, 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 Range Clamp
When reductionMode is
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_RANGECLAMP_QCOM, the
weighted average is clamped to be within the component-wise minimum and
maximum 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:
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.
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.
|
Note
|
For historical reasons, vendor implementations of anisotropic filtering
interpret these sampler parameters in different ways, particularly in corner
cases such as The following describes one particular approach to implementing anisotropic filtering for the 2D Image case; implementations may choose other methods: Given a 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:: |
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 false; an empty
footprint would be returned when Coarse is 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 mip level 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 mip level 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. Weight Image Sampling
The SPIR-V instruction OpImageWeightedSampleQCOM specifies a texture
sampling operation involving two images: the sampled image and the weight
image.
It is similar to bilinear filtering except more than 2x2 texels may
participate in the filter and the filter weights are application-specified
rather than computed by fixed-function hardware.
The weight image view defines a 2D kernel weights used during sampling.
The OpImageWeightedSampleQCOM support normalized or unnormalized texel
coordinates.
In addition to the inputs that would be accepted by an equivalent
OpImageSample* instruction, OpImageWeightedSampleQCOM accepts a
weight input that specifies the view of a sample weight image
The input weight must be a view of a 2D or 1D image with
miplevels equal to 1, samples equal to
VK_SAMPLE_COUNT_1_BIT, created with an identity swizzle, and created
with usage that includes VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM.
The VkImageViewSampleWeightCreateInfoQCOM specifies additional
parameters of the view: filterCenter, filterSize, and
numPhases.
described in more detail below.
The weight input must be bound using a
sample weight image descriptor type.
The weight view defines a filtering kernel that is a region of view’s
subresource range.
The kernel spans a region from integer texel coordinate (0,0) to
(filterSize.x-1, filterSize.y-1).
It is valid for the view’s subresource to have dimensions larger than the
kernel but the texels with integer coordinates greater than
(filterSize.width-1, filterSize.height-1) are ignored by
weight sampling.
The value returned by queries OpImageQuerySize,
OpImageQuerySizeLod, OpImageQueryLevels, and
OpImageQuerySamples return for a weight image is undefined.
filterCenter designates an integer texel coordinate within the filter
kernel as being the 'center' of the kernel.
The center must be in the range (0,0) to (filterSize.x-1,
filterSize.y-1).
numPhases describes the number of filter phases used to provide
sub-pixel filtering.
Both are described in more detail below.
16.10.1. Weight Image Layout
The weight image specifies filtering kernel weight values. A 2D image view can be used to specify a 2D matrix of filter weights. For separable filters, a 1D image view can be used to specify the horizontal and vertical weights.
2D Non-Separable Weight Filters
A 2D image view defined with VkImageViewSampleWeightCreateInfoQCOM
describes a 2D matrix (filterSize.width ×
filterSize.height) of weight elements with filter’s center point at
filterCenter.
Note that filterSize can be smaller than the view’s subresource, but
the filter will always be located starting at integer texel coordinate
(0,0).
The following figure illustrates a 2D convolution filter having
filterSize of (4,3) and filterCenter at (1, 1).
For a 2D weight filter, the phases are stored as layers of a 2D array image.
The width and height of the view’s subresource range must be less than or
equal to
VkPhysicalDeviceImageProcessingPropertiesQCOM::maxWeightFilterDimension.
The layers are stored in horizontal phase major order.
Expressed as a formula, the layer index for each filter phase is computed
as:
layerIndex(horizPhase,vertPhase,horizPhaseCount) = (vertPhase * horizPhaseCount) + horizPhase
1D Separable Weight Filters
A separable weight filter is a 2D filter that can be specified by two 1D filters in the x and y directions such that their product yields the 2D filter. The following example shows a 2D filter and its associated separable 1D horizontal and vertical filters.
A 1D array image view defined with
VkImageViewSampleWeightCreateInfoQCOM and with layerCount equal
to '2' describes a separable weight filter.
The horizontal weights are specified in slice '0' and the vertical weights
in slice '1'.
The filterSize and filterCenter specify the size and origin of
the of the horizontal and vertical filters.
For many use cases, 1D separable filters can offer a performance advantage
over 2D filters.
For a 1D separable weight filter, the phases are arranged into a 1D array image with two layers. The horizontal weights are stored in layer 0 and the vertical weights in layer 1. Within each layer of the 1D array image, the weights are arranged into groups of 4, and then arranged by phase. Expressed as a formula, the 1D texel offset for each weight within each layer is computed as:
// Let horizontal weights have a weightIndex of [0, filterSize.width - 1]
// Let vertical weights have a weightIndex of [0, filterSize.height - 1]
// Let phaseCount be the number of phases in either the vertical or horizontal direction.
texelOffset(phaseIndex,weightIndex,phaseCount) = (phaseCount * 4 * (weightIndex / 4)) + (phaseIndex * 4) + (weightIndex % 4)
16.10.2. Weight Sampling Phases
When using weight image sampling, the texture coordinates may not align with a texel center in the sampled image. In this case, the filter weights can be adjusted based on the subpixel location. This is termed “subpixel filtering” to indicate that the origin of the filter lies at a subpixel location other than the texel center. Conceptually, this means that the weight filter is positioned such that filter taps do not align with sampled texels exactly. In such a case, modified filter weights may be needed to adjust for the off-center filter taps. Unlike bilinear filtering where the subpixel weights are computed by the implementation, subpixel weight image sampling requires that the per-phase filter weights are pre-computed by the application and stored in an array where each slice of the array is a “filter phase”. The array is indexed by the implementation based on subpixel positioning. Rather than a single 2D kernel of filter weights, the application provides an array of kernels, one set of filter weights per phase.
The number of phases are restricted by following requirements, which apply to both separable and non-separable filters:
-
The number of phases in the vertical direction, phaseCountvert, must be a power of two (i.e., 1, 2, 4, etc.).
-
The number of phases in the horizontal direction phaseCounthoriz, must equal phaseCountvert.
-
The total number of phases, phaseCountvert × phaseCounthoriz, must be less than or equal to VkPhysicalDeviceImageProcessingPropertiesQCOM::
maxWeightFilterPhases.
16.10.3. Weight Sampler Parameters
Weight sampling requires VkSamplerCreateInfo addressModeU and
addressModeV must be VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER.
If VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER is used, then the border
color must be VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK.
16.10.4. Weight Sampling Operation
The 2D unnormalized texel coordinates are transformed by to specify coordinates .
where is specified by
VkImageViewSampleWeightCreateInfoQCOM::filterCenter.
Two sets of neighboring integer 2D texel coordinates are generated. The first set is used for selecting texels from the sampled image and the second set used for selecting texels from the weight image . The first set of neighboring coordinates are combinations of to and to . The second set of neighboring coordinates are combinations of to and to . The first and second sets each contain of pairs of and coordinates respectively.
where and are specified by
VkImageViewSampleWeightCreateInfoQCOM::filterSize.
Each of the generated integer coordinates is transformed by texture wrapping operation, followed by integer texel coordinate validation, If any coordinate fails coordinate validation, it is a Border Texel and texel replacement is performed.
The phase index is computed from the fraction bits of the unnormalized 2D texel coordinates:
where the number of fraction bits retained is
specified by
VkImageViewSampleWeightCreateInfoQCOM::numPhases
Each pair of texel coordinates in the first set selects a single texel value from the sampled image. Each pair of texel coordinates in the second set, combined with phaseIndex , selects a single weight from the weight image .
If is a 2D array view, then non-separable filtering is specified, and integer coordinates are used to select texels from layer of . If is a 1D array view, then separable filtering is specified and integer coordinates are transformed to , and used to select horizontal weight and vertical weight texels from layer 0 and layer 1 of respectively.
Where refers to the integer modulo operator.
The values of multiple texels, together with their weights, are combined to produce a filtered value.
When VkSamplerReductionModeCreateInfo::reductionMode is
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, computing a component-wise minimum or maximum of the texels with
non-zero weights.
If the reduction mode is VK_SAMPLER_REDUCTION_MODE_MIN or
VK_SAMPLER_REDUCTION_MODE_MAX, each weight
must be equal to 0.0 or 1.0, otherwise the undefined values are returned.
Finally, the operations described in Conversion to RGBA and Component swizzle are performed and the final result is returned to the shader.
16.11. Block Matching
The SPIR-V instruction opImageBlockMatchSAD and
opImageBlockMatchSSD specify texture block matching operations where a
block or region of texels within a target image is compared with a
same-sized region in a reference image.
The instructions make use of two image views: the target view and the
reference view.
The target view and reference view can be the same view, allowing block
matching of two blocks within a single image.
Similar to an equivalent OpImageFetch instruction,
opImageBlockMatchSAD and opImageBlockMatchSAD specify an
image and an integer texel coordinate which describes the
bottom-left texel of the target block.
There are three additional inputs.
The reference and refCoodinate specifies bottom-left texel of the
reference block.
The blockSize specifies the integer width and height of the target and
reference blocks to be compared, and must not be greater than
VkPhysicalDeviceImageProcessingPropertiesQCOM.maxBlockMatchRegion.
opImageBlockMatchWindowSAD and opImageBlockMatchWindowSAD take the
same input parameters as the corresponding non-window instructions.
The block matching comparison is performed for all pixel values within a 2D
window whose dimensions are specified in the sampler.
16.11.1. Block Matching Sampler Parameters
For opImageBlockMatchSAD and opImageBlockMatchSSD, the input
sampler must be created with addressModeU and addressModeV,
equal to VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE, or
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER with
VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK.
The input sampler must be created with unnormalizedCoordinates
equal to VK_TRUE.
The input sampler must be created with components equal to
VK_COMPONENT_SWIZZLE_IDENTITY.
For opImageBlockMatchWindowSAD and opImageBlockMatchWindowSSD
instructions, the target sampler must have been created with
VkSamplerBlockMatchWindowCreateInfoQCOM in the pNext chain.
For opImageBlockMatchWindowSAD, opImageBlockMatchWindowSSD,
opImageBlockMatchGatherSAD, or
opImageBlockMatchGatherSSDinstructions, the input sampler must be
created with addressModeU and addressModeV, equal to
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER with
VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK.
Other sampler states are ignored.
16.11.2. Block Matching Operation
Block matching SPIR-V instructions opImageBlockMatchSAD and
opImageBlockMatchSSD specify two sets of 2D integer texel coordinates:
target coordinates and reference coordinates
.
The coordinates define the bottom-left texel of the target block and the reference block .
For the target block, a set of neighboring integer texel coordinates are generated. The neighboring coordinates are combinations of to and to . The set is of size .
where and is specified by the
blockSize operand.
If any target integer texel coordinate in the set fails integer texel coordinate validation, then the texel is an invalid texel and texel replacement is performed.
Similarly for the reference block, a set of neighboring integer texel coordinates are generated.
Each reference texel coordinate in the set must not fail integer texel coordinate validation. To avoid undefined behavior, application shader should guarantee that the reference block is fully within the bounds of the reference image.
Each pair of texel coordinates in the set selects a single texel value from the target image . Each pair of texel coordinates in the set selects a single texel value from the reference image .
The difference between target and reference texel values is summed to
compute a difference metric.
The opTextureBlockMatchSAD computes the sum of absolute differences.
The opImageBlockMatchSSD computes the sum of the squared differences.
When VkSamplerReductionModeCreateInfo::reductionMode is
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, computing a component-wise minimum or maximum of
, respectively.
For , the minimum or maximum difference is computed
and for , the square of the minimum or maximum is
computed.
Finally, the operations described in Conversion to RGBA and Component swizzle are performed and the final result is returned to the shader. The component swizzle is specified by the target image descriptor; any swizzle specified by the reference image descriptor is ignored.
Block Matching Window Operation
Window block matching SPIR-V instructions opImageBlockMatchWindowSAD
and opImageBlockMatchWindowSSD specify two sets of 2D integer texel
coordinates: target coordinates and reference coordinates
.
The block matching operation is
performed repeatedly, for multiple sets of target integer coordinates within
the specified window.
These instructions effectively search a region or “window” within the
target texture and identify the window coordinates where the minimum or
maximum error metric is found.
These instructions only support single component image formats.
The target coordinates are combinations of coordinates from
to
where and are specified by
VkSamplerBlockMatchWindowCreateInfoQCOM::windowExtent.
At each target coordinate, a block
matching operation is performed, resulting in a difference metric.
The reference coordinate is fixed.
The block matching operation is repeated times.
The resulting minimum or maximum error is returned in the R component of the
output.
The integer window coordinates are returned in the G and B
components of the output.
The A component is 0.
The minimum or maximum behavior is selected by
VkSamplerBlockMatchWindowCreateInfoQCOM::windowCompareMode.
The following pseudocode describes the operation
opImageBlockMatchWindowSAD.
The pseudocode for opImageBlockMatchWindowSSD follows an identical
pattern.
vec4 opImageBlockMatchGatherSAD( sampler2D target,
uvec2 targetCoord,
samler2D reference,
uvec2 refCoord,
uvec2 blocksize) {
// Two parameters are sourced from the VkSampler associated with
// `target`:
// compareMode (which can be either `MIN` or `MAX`)
// uvec2 window (which defines the search window)
minSAD = INF;
maxSAD = -INF;
uvec2 minCoord;
uvec2 maxCoord;
for (uint x=0, x<window.width; x++) {
for (uint y=0; y<window.height; y++) {
float SAD = textureBlockMatchSAD(target,
targetCoord + uvec2(x, y),
reference,
refCoord,
blocksize).x;
if (SAD < minSAD) {
minSAD = SAD;
minCoord = uvec2(x,y);
}
if (SAD > maxSAD) {
maxSAD = SAD;
maxCoord = uvec2(x,y);
}
}
}
if (compareMode==MIN) {
return vec4(minSAD, minCoord.x, minCoord.y, 0.0);
} else {
return vec4(maxSAD, maxCoord.x, maxCoord.y, 0.0);
}
}
Block Matching Gather Operation
Block matching Gather SPIR-V instructions opImageBlockMatchGatherSAD
and opImageBlockMatchGatherSSD specify two sets of 2D integer texel
coordinates: target coordinates and reference coordinates
.
These instructions perform the block matching operation 4 times, using integer target coordinates , , , and . The R component from each of those 4 operations is gathered and returned in the R, G, B, and A components of the output respectively. For each block match operation, the reference coordinate is . For each block match operation, only the R component of the target and reference images are compared. The following pseudocode describes the operation opImageBlockMatchGatherSAD. The pseudocode for opImageBlockMatchGatherSSD follows an identical pattern.
vec4 opImageBlockMatchGatherSAD(sampler2D target,
uvec2 targetCoord,
samler2D reference,
uvec2 refCoord,
uvec2 blocksize) {
vec4 out;
for (uint x=0, x<4; x++) {
float SAD = textureBlockMatchSAD(target,
targetCoord + uvec2(x, 0),
reference,
refCoord,
blocksize).x;
if (x == 0) {
out.x = SAD;
}
if (x == 1) {
out.y = SAD;
}
if (x == 2) {
out.z = SAD;
}
if (x == 3) {
out.w = SAD;
}
}
return out;
}
16.12. Box Filter Sampling
The SPIR-V instruction OpImageBoxFilterQCOM specifies texture box
filtering operation where a weighted average of a region of texels is
computed, with the weights proportional to the coverage of each of the
texels.
In addition to the inputs that would be accepted by an equivalent
OpImageSample* instruction, OpImageBoxFilterQCOM accepts one
additional input, boxSize which specifies the width and height in
texels of the region to be averaged.
The figure below shows an example of using OpImageBoxFilterQCOM to
sample from a 8 × 4 texel two-dimensional image, with
unnormalized texture coordinates (4.125, 2.625) and boxSize of
(2.75, 2.25).
The filter will read 12 texel values and compute a weights based portion of
each texel covered by the box.
If boxSize has height and width both equal to 1.0, then this
instruction will behave as traditional bilinear filtering.
The boxSize parameter must be greater than or equal to 1.0 and must
not be greater than
VkPhysicalDeviceImageProcessingPropertiesQCOM.maxBoxFilterBlockSize.
16.12.1. Box Filter Sampler Parameters
The input sampler must be created with addressModeU and
addressModeV, equal to VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE, or
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER with
VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK.
16.12.2. Box Filter Operation
The 2D unnormalized texel coordinates are transformed by to specify integer texel coordinates of the bottom left texel for the filter.
where and are specified by the
code:(x,y) components of the boxSize operand.
The filter dimensions are computed from the fractional portion of the coordinates and the .
where the number of fraction bits retained by is
specified by VkPhysicalDeviceLimits::subTexelPrecisionBits.
A set of neighboring integer texel coordinates are generated. The neighboring coordinates are combinations of to and to , with being the top-left coordinate of this set. The set is of size .
Each of the generated integer coordinates is transformed by texture wrapping operation, followed by integer texel coordinate validation, If any coordinate fails coordinate validation, it is a Border Texel and texel replacement is performed.
Horizontal weights to and vertical weights to are computed. Texels that are fully covered by the box will have a horizontal and vertical weight of 1. Texels partially covered by the box will have will have a reduced weights proportional to the coverage.
The values of multiple texels, together with their horizontal and vertical weights, are combined to produce a box filtered value.
When VkSamplerReductionModeCreateInfo::reductionMode is
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, computing a component-wise minimum or maximum of the texels.
16.13. 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, LOD 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. -
(s,t,r,q,a) to (u,v,w,a) Transformation, Wrapping, and Weight Image Sampling: Performed by
OpImageWeightedSample*instructions. -
(s,t,r,q,a) to (u,v,w,a) Transformation, Wrapping, and Block Matching: Performed by
opImageBlockMatch*instructions. -
(s,t,r,q,a) to (u,v,w,a) Transformation, Wrapping, and Box Filter Sampling: Performed by
OpImageBoxFilter*instructions.
16.14. Image Query Instructions
16.14.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.14.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, LOD Operation and Image Level(s) Selection.
The return value is the vector (λ', dl - levelbase).
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 VkRenderPassFragmentDensityMapOffsetEndInfoEXT. If no offset is specified, then the default offset (0,0) is used. The offsetted coordinate (x',y') is computed as follows:
|
Note
|
The offset is relative to the fragment density map, so it is subtracted from the framebuffer coordinates to make the adjustment relative to the framebuffer. In other words, applying a positive offset in the x component will shift the fragment density map to the right relative to the framebuffer. This means the framebuffer coordinates need to undergo a shift to the left. |
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, if the render pass was created with
VK_RENDER_PASS_CREATE_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVE specified,
or the dynamic render pass was begun with
VK_RENDERING_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVE specified,
then the layer used 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. Tensor Operations
18.1. Tensor Operations Overview
Vulkan Tensor Operations are operations performed by those SPIR-V Tensor
Instructions which take an OpTypeTensorARM (representing a
VkTensorViewARM).
Read and write operations take tensor element coordinates as operands, and
return elements from the tensor.
Query operations return properties of the bound tensor.
Tensor Operations include the functionality of the following SPIR-V Tensor Instructions:
-
OpTensorReadARMreads one or more elements from the tensor. -
OpTensorWriteARMwrites one or more elements to the tensor. -
OpTensorQuerySizeARMreturns the size of the tensor descriptor that would be accessed. The tensor itself is not accessed.
18.2. Tensor Element Input Operations
Tensor element input instructions are SPIR-V tensor instructions that read from a tensor. Tensor element input operations are a set of steps that are performed on state, coordinates, and tensor element values while processing a tensor element input instruction, and which are common to some or all tensor element input instructions. They include the following steps, which are performed in the listed order:
For tensor element input instructions involving multiple tensor elements, these steps are applied for each tensor element that is used in the instruction.
18.2.1. Tensor Element Input Validation Operations
Tensor element input validation operations inspect instruction/tensor state or coordinates, and in certain circumstances cause the tensor element value to be replaced or become undefined. There are a series of validations that the tensor element undergoes.
Instruction/Tensor View Validation
There are a number of cases where a SPIR-V instruction can mismatch with the tensor view. In such cases the value of the tensor element returned is undefined.
These cases include:
-
The SPIR-V instruction’s tensor variable’s properties are not compatible with the tensor view:
-
The SPIR-V Tensor
ElementTypeis not compatible with the tensor view’sformat. -
The SPIR-V Tensor
Rankis not present. -
The SPIR-V Tensor
Rankis not the same as the value provided for VkTensorDescriptionARM::dimensionCountwhen creating the tensor used by the tensor view. -
The SPIR-V Tensor
Shape, if present, does not match the set of values provided for VkTensorDescriptionARM::pDimensionswhen creating the tensor used by the tensor view.
-
Tensor Element Coordinate Validation
Tensor element coordinates are validated against the size of the tensor.
If the tensor element coordinates do not satisfy all of the conditions
-
0 ≤ Coordinates[i] < Size[i] for 0 ≤ i < dimensionCount
where:
-
Size[i] is the size of the tensor along dimension i as provided via VkTensorDescriptionARM::
pDimensions[i] when the tensor was created. -
dimensionCount is the number of dimensions of the tensor as provided via VkTensorDescriptionARM::
dimensionCountwhen the tensor was created.
, or the tensor descriptor is a null descriptor,
then the tensor element fails coordinate validation.
There are two cases to consider:
-
Valid Tensor Element Coordinates
-
If the tensor element coordinates pass validation (that is, the coordinates lie within the tensor),
then the tensor element value comes from the value in tensor memory.
-
-
Out-of-Bounds Tensor Element
-
If the tensor element coordinates fail validation,
then the tensor element is an invalid tensor element and tensor element replacement is performed.
-
18.2.2. Format Conversion
If required, tensor elements undergo a format conversion from the VkFormat of the tensor view to the element type of the tensor resource variable on which a read operation is performed.
Each element 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 8-bit booleans.
The compatibility between SPIR-V tensor element types and VkFormat is specified under Compatibility Between SPIR-V Tensor Element Types And Vulkan Formats.
18.2.3. Tensor Element Replacement
A tensor element is replaced if it is an invalid tensor element.
Invalid tensor elements are replaced as follows:
-
If the
OpTensorReadARMinstruction that caused an invalid tensor element to be accessed did not have aOutOfBoundsValueARMtensor operand present, then the value returned is the same as that produced byOpConstantNullfor the type returned. -
If the
OpTensorReadARMinstruction that caused an invalid tensor element to be accessed had aOutOfBoundsValueARMtensor operand present, then the value provided usingOutOfBoundsValueARMis returned.
18.3. Tensor Element Output Operations
Tensor element output instructions are SPIR-V tensor instructions that write to a tensor. Tensor element output operations are a set of steps that are performed on state, coordinates, and tensor element values while processing a tensor element output instruction, and which are common to some or all tensor element output instructions. They include the following steps, which are performed in the listed order:
18.3.1. Tensor Element Output Validation Operations
Tensor element output validation operations inspect instruction/tensor state or coordinates, and in certain circumstances cause the write to have no effect. There are a series of validations that the tensor element undergoes.
Tensor Element Format Validation
If one of the following conditions is met, then an operation writing to the tensor causes the tensor’s memory to become undefined .
-
The SPIR-V instruction’s tensor variable’s properties are not compatible with the tensor view:
-
The SPIR-V Tensor Element Type is not compatible with the tensor view’s
format. -
The SPIR-V Tensor Rank is not present.
-
The SPIR-V Tensor Rank is not the same as the value provided for VkTensorDescriptionARM::
dimensionCountwhen creating the tensor used by the tensor view. -
The SPIR-V Tensor Shape, if present, does not match the set of values provided for VkTensorDescriptionARM::
pDimensionswhen creating the tensor used by the tensor view.
-
18.3.2. Tensor Element Coordinate Validation
The tensor element coordinates are validated according to the same rules as for tensor element input coordinate validation.
If the tensor element fails coordinate validation, then the write has no effect.
18.3.3. Tensor Element Output Format Conversion
If required, tensor elements undergo a format conversion from the element type of the tensor resource variable on which a write operation is performed to the VkFormat of the tensor view.
Each element 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. Boolean outputs are converted as described in 8-bit boolean. Integer outputs are converted such that their value is preserved.
The compatibility between SPIR-V tensor element types and VkFormat is specified under Compatibility Between SPIR-V Tensor Element Types And Vulkan Formats.
19. 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 Feedback 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. Mesh Shader 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.
19.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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkQueryPoolCreateFlagBits -
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.
Bits which can be set in VkQueryPoolCreateInfo::flags,
specifying options for query pools, are:
// Provided by VK_VERSION_1_0
typedef enum VkQueryPoolCreateFlagBits {
// Provided by VK_KHR_maintenance9
VK_QUERY_POOL_CREATE_RESET_BIT_KHR = 0x00000001,
} VkQueryPoolCreateFlagBits;
-
VK_QUERY_POOL_CREATE_RESET_BIT_KHRspecifies that queries in the query pool are initialized on creation and do not need to be reset before first use.
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueryPoolCreateFlags;
VkQueryPoolCreateFlags is a bitmask type for setting a mask of zero or
more VkQueryPoolCreateFlagBits.
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 a VkStructureType value identifying 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,
// Provided by VK_KHR_video_queue
VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR = 1000023000,
// 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,
// Provided by VK_KHR_video_encode_queue
VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR = 1000299000,
// Provided by VK_EXT_mesh_shader
VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT = 1000328000,
// 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,
// Provided by VK_EXT_opacity_micromap
VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT = 1000396000,
// Provided by VK_EXT_opacity_micromap
VK_QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT = 1000396001,
} 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_FEEDBACK_KHRspecifies a video encode feedback query. -
VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXTspecifies a generated mesh primitives query.
19.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,
where VK_QUERY_POOL_CREATE_RESET_BIT_KHR was not set in
VkQueryPoolCreateInfo::flags
each query is in an uninitialized state and 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.
A query must either begin and end inside the same video coding scope, or must both begin and end outside of a video coding scope and must not contain entire video coding scopes.
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.
Furthermore, if the query is started within a video coding scope, the following command buffer states are initialized for the query type:
Each video coding operation stores a result to the query corresponding to the current active query index, followed by incrementing the active query index. If the active query index gets incremented past the last activatable query index, issuing any further video coding operations results in undefined behavior.
|
Note
|
In practice, this means that currently no more than a single video coding operation must be issued between a begin and end query pair. |
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, mesh shader queries, video encode feedback 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. Mesh shader queries write a single integer. Video encode feedback queries write one or more integer values for each bit that is enabled in VkQueryPoolVideoEncodeFeedbackCreateInfoKHR::encodeFeedbackFlagswhen the pool is created, and the feedback values are written in bit order starting from the least significant bit, as described here. -
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 an application-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.
If no bits are set in flags, and all requested queries are in the
available state, results are written as an array of 32-bit unsigned integer
values.
Behavior when not all queries are available is described
below.
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
or status
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.
The size of the availability
or status
values is 64 bits if VK_QUERY_RESULT_64_BIT is set in flags.
Otherwise, it is 32 bits.
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.
If the status value written is negative, indicating that the operations within the query completed unsuccessfully, then all other results written by this command are undefined unless otherwise specified for any of the results of the used query type.
|
Note
|
If |
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, if returned,
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 the maintenance7 feature is enabled, for
an unsigned integer query, the 32-bit result value must be equal to the 32
least significant bits of the equivalent 64-bit result value.
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.
If VK_QUERY_RESULT_WAIT_BIT is not set, vkGetQueryPoolResults
may return VK_NOT_READY if there are queries in the unavailable
state.
|
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,
// Provided by VK_KHR_video_queue
VK_QUERY_RESULT_WITH_STATUS_BIT_KHR = 0x00000010,
} 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,
// Provided by VK_KHR_video_encode_queue
VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR = -1000299000,
} 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. -
VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHRspecifies that a video encode operation did not complete successfully due to the destination video bitstream buffer range not being sufficiently large to fit the encoded bitstream data.
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.
If the status value written is negative, indicating that the operations within the query completed unsuccessfully, then all other results written by this command are undefined unless otherwise specified for any of the results of the used query type.
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 the maintenance7 feature is enabled, for
an unsigned integer query, the 32-bit result value must be equal to the 32
least significant bits of the equivalent 64-bit result value.
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.
19.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 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. |
19.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, or the counter corresponds to a shading stage
which is missing from any of the pipelines used while the query is active,
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,
// Provided by VK_EXT_mesh_shader
VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT = 0x00000800,
// Provided by VK_EXT_mesh_shader
VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT = 0x00001000,
// Provided by VK_HUAWEI_cluster_culling_shader
VK_QUERY_PIPELINE_STATISTIC_CLUSTER_CULLING_SHADER_INVOCATIONS_BIT_HUAWEI = 0x00002000,
} 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. -
VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXTspecifies that queries managed by the pool will count the number of task shader invocations. The counter’s value is incremented every time the task shader is invoked. -
VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXTspecifies that queries managed by the pool will count the number of mesh shader invocations. The counter’s value is incremented every time the mesh shader is invoked.
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.
This counting difference is especially true if the pipeline contains mesh or task shaders, which may affect several of the counters in unexpected ways.
|
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.
19.5. Timestamp Queries
Timestamps provide applications with a mechanism for monotonically
tracking 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 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.
|
Note
|
Implementations may write the timestamp at any stage that is
logically later than |
Any timestamp write that happens-after another timestamp write in the same submission must not
have a lower value unless its value overflows the maximum supported integer
bit width of the query.
If
VK_KHR_calibrated_timestamps
or
VK_EXT_calibrated_timestamps
is enabled, this extends to timestamp writes across all submissions on the
same logical device: any timestamp write that
happens-after another must not
have a lower value unless its value overflows the maximum supported integer
bit width of the query.
Timestamps written by this command must be in the
VK_TIME_DOMAIN_DEVICE_KHR
time domain.
If an overflow occurs, the timestamp value must wrap back to zero.
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
or dynamic render pass
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.
-
All N queries are timestamp values.
Either way, if two timestamps are written in the same subpass or dynamic render pass with multiview enabled, each of the N consecutive queries written for a timestamp must not have a lower value than the queries with corresponding indices written by the timestamp that happens-before unless the value overflows the maximum supported integer bit width of the query.
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.
|
Note
|
Implementations may write the timestamp at any stage that is
logically later than |
Any timestamp write that happens-after another timestamp write in the same submission must not
have a lower value unless its value overflows the maximum supported integer
bit width of the query.
If
VK_KHR_calibrated_timestamps
or
VK_EXT_calibrated_timestamps
is enabled, this extends to timestamp writes across all submissions on the
same logical device: any timestamp write that
happens-after another must not
have a lower value unless its value overflows the maximum supported integer
bit width of the query.
Timestamps written by this command must be in the
VK_TIME_DOMAIN_DEVICE_KHR
time domain.
If an overflow occurs, the timestamp value must wrap back to zero.
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
or dynamic render pass
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.
-
All N queries are timestamp values.
Either way, if two timestamps are written in the same subpass or dynamic render pass with multiview enabled, each of the N consecutive queries written for a timestamp must not have a lower value than the queries with corresponding indices written by the timestamp that happens-before unless the value overflows the maximum supported integer bit width of the query.
19.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:
// 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;
-
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.
VkPerformanceCounterKHR::storage specifies how to parse the
counter data.
19.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 a VkAcquireProfilingLockInfoKHR structure 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 a VkStructureType value identifying 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 profiling 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.
19.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).
19.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
|
19.9. Mesh Shader Queries
When a generated mesh primitives query is active, the mesh-primitives-generated count is incremented every time a primitive emitted from the mesh shader stage reaches the fragment shader stage. When a generated mesh primitives query begins, the mesh-primitives-generated count starts from zero.
Mesh and task shader pipeline statistics queries function the same way that invocation queries work for other shader stages, counting the number of times the respective shader stage has been run. When the statistics query begins, the invocation counters start from zero.
19.10. 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 capable 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pUserDatais a pointer for application data.
Once performance query operations have completed, uninitialize 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 that VkBool32 data 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;
-
value32represents 32-bit integer data. -
value64represents 64-bit integer data. -
valueFloatrepresents floating-point data. -
valueBoolrepresents VkBool32 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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);
-
commandBufferis a VkCommandBuffer into which a stream marker is added. -
pMarkerInfois a pointer to a VkPerformanceStreamMarkerInfoINTEL structure describing the marker to insert.
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 a VkStructureType value identifying 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;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
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 a VkStructureType value identifying 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.
19.11. Result Status Queries
Result status queries serve a single purpose: allowing the application to
determine whether a set of operations have completed successfully or not, as
indicated by the VkQueryResultStatusKHR value written when retrieving
the result of a query using the VK_QUERY_RESULT_WITH_STATUS_BIT_KHR
flag.
Unlike other query types, result status queries do not track or maintain any other data beyond the completion status, thus no other data is written when retrieving their results.
Support for result status queries is indicated by
VkQueueFamilyQueryResultStatusPropertiesKHR::queryResultStatusSupport
, as returned by vkGetPhysicalDeviceQueueFamilyProperties2 for the
queue family in question.
19.12. Video Encode Feedback Queries
Video encode feedback queries allow the application to capture feedback
values generated by video encode operations.
As such, video encode feedback queries are available on queue families
supporting video encode operations.
The availability of individual video encode feedback values is indicated by
the bits of
VkVideoEncodeCapabilitiesKHR::supportedEncodeFeedbackFlags, as
returned by vkGetPhysicalDeviceVideoCapabilitiesKHR for the
video profile the queries are intended to be used with.
The set of enabled video encode feedback values must be configured on the
query pool when it is created using the encodeFeedbackFlags member of
the VkQueryPoolVideoEncodeFeedbackCreateInfoKHR included in the
pNext chain of VkQueryPoolCreateInfo.
The VkQueryPoolVideoEncodeFeedbackCreateInfoKHR structure is defined
as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkQueryPoolVideoEncodeFeedbackCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeFeedbackFlagsKHR encodeFeedbackFlags;
} VkQueryPoolVideoEncodeFeedbackCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
encodeFeedbackFlagsis a bitmask of VkVideoEncodeFeedbackFlagBitsKHR values specifying the set of enabled video encode feedback values captured by queries of the new pool.
Bits which can be set in
VkQueryPoolVideoEncodeFeedbackCreateInfoKHR::encodeFeedbackFlags
for video encode feedback query pools are:
// Provided by VK_KHR_video_encode_queue
typedef enum VkVideoEncodeFeedbackFlagBitsKHR {
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR = 0x00000004,
} VkVideoEncodeFeedbackFlagBitsKHR;
-
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHRspecifies that queries managed by the pool will capture the byte offset of the bitstream data written by the video encode operation to the bitstream buffer specified in VkVideoEncodeInfoKHR::dstBufferrelative to the offset specified in VkVideoEncodeInfoKHR::dstBufferOffset. For the first video encode operation issued by any video encode command, this value will always be zero, meaning that bitstream data is always written to the buffer specified in VkVideoEncodeInfoKHR::dstBufferstarting from the offset specified in VkVideoEncodeInfoKHR::dstBufferOffset. -
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHRspecifies that queries managed by the pool will capture the number of bytes written by the video encode operation to the bitstream buffer specified in VkVideoEncodeInfoKHR::dstBuffer. -
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHRspecifies that queries managed by the pool will capture a boolean value indicating that the data written to the bitstream buffer specified in VkVideoEncodeInfoKHR::dstBuffercontains overridden parameters.
When retrieving the results of video encode feedback queries, the values
corresponding to each enabled video encode feedback are written in the order
of the bits defined above, followed by an optional value indicating
availability or result status if VK_QUERY_RESULT_WITH_AVAILABILITY_BIT
or VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is specified, respectively.
If the result status of a video encode feedback query is negative, then the results of all enabled video encode feedback values will be undefined.
|
Note
|
Applications should always specify |
// Provided by VK_KHR_video_encode_queue
typedef VkFlags VkVideoEncodeFeedbackFlagsKHR;
VkVideoEncodeFeedbackFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoEncodeFeedbackFlagBitsKHR.
20. Clear Commands
20.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.
20.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. -
rectCountis the number of entries in thepRectsarray. -
pRectsis a pointer to an array of VkClearRect structures defining regions to clear for every attachment inpAttachments.
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
|
If any attachment’s aspectMask to be cleared is not backed by an image
view, the clear has no effect on that aspect.
If an attachment being cleared refers to an image view created with an
aspectMask equal to one of VK_IMAGE_ASPECT_PLANE_0_BIT,
VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT, it
is considered to be VK_IMAGE_ASPECT_COLOR_BIT for purposes of this
command, and must be cleared with the VK_IMAGE_ASPECT_COLOR_BIT
aspect as specified by image view creation.
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 bound color attachments. -
clearValueis the color or depth/stencil value to clear the attachment to, as described in Clear Values below.
20.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 numeric formats with a numeric type that is floating-point. 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 has a numeric type that 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 has a numeric type that 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.
If the image or attachment format has a 64-bit component width, the first 2 array elements of each of the arrays above are reinterpreted as a single 64-bit element for the R component. The next 2 array elements are used in the same way for the G component. In other words, the union behaves as if it had the following additional members:
double float64[2];
int64_t int64[2];
uint64_t uint64[2];
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.
20.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.
20.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 should only be used for very small
amounts of data, and is why it is limited to at most 65536 bytes.
Applications can work around this restriction by issuing multiple
|
The source data is copied from pData 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 |
21. Copy Commands
An application can copy buffer and image data using several methods described in this chapter, depending on the type of data transfer.
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.
21.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 source region specified by pRegions is copied from the source
buffer to the destination region of the destination buffer.
If any of the specified regions in srcBuffer overlaps in memory with
any of the specified regions in dstBuffer, values read from those
overlapping regions are undefined.
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.
Each source region specified by pCopyBufferInfo->pRegions is copied
from the source buffer to the destination region of the destination buffer.
If any of the specified regions in pCopyBufferInfo->srcBuffer overlaps
in memory with any of the specified regions in
pCopyBufferInfo->dstBuffer, values read from those overlapping regions
are undefined.
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 a VkStructureType value identifying 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.
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 a VkStructureType value identifying 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.
21.2. Copying Data Between Images
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 source region specified by pRegions is copied from the source
image to the destination region of the destination image.
If any of the specified regions in srcImage overlaps in memory with
any of the specified regions in dstImage, values read from those
overlapping regions are undefined.
If any region accesses a depth aspect in dstImage
and the VK_EXT_depth_range_unrestricted extension is not enabled,
values copied from srcBuffer outside of the range [0,1] will be
written as undefined values to the destination image.
Multi-planar images can only be copied on a per-plane basis, and the subresources used in each region when copying to or from such images must specify only one plane, though different regions can specify different planes. When copying planes of multi-planar images, the format considered is the compatible format for that plane, rather than the format of the multi-planar image.
If the format of the destination image has a different block extent than the source image (e.g. one is a compressed format), the offset and extent for each of the regions specified is scaled according to the block extents of each format to match in size. Copy regions for each image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
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.
If the maintenance5 feature is enabled, all
other combinations are allowed and function as if 1D images are 2D images
with a height of 1.
Otherwise, other combinations of image types are disallowed.
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.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
21.3. Copying Data Between Buffers and Images
Data can be copied between buffers and images, enabling applications to load and store data between images and application-defined offsets in buffer memory.
When copying between a buffer and an image, texels in the image and bytes in the buffer are accessed as follows.
Texels at each coordinate (x,y,z,layer) in the image subresource are accessed, where:
-
x is in the range [
imageOffset.x,imageOffset.x+imageExtent.width), -
y is in the range [
imageOffset.y,imageOffset.y+imageExtent.height), -
z is in the range [
imageOffset.z,imageOffset.z+imageExtent.depth), -
layer is in the range [
imageSubresource.baseArrayLayer,imageSubresource.baseArrayLayer+imageSubresource.layerCount)
For each (x,y,z,layer) coordinate in the image, bytes in the buffer are accessed at offsets in the range [texelOffset, texelOffset + blockSize), where:
-
texelOffset =
bufferOffset+ (⌊(x - imageOffset.x) / blockWidth⌋ × blockSize) + (⌊(y - imageOffset.y) / blockHeight⌋ × rowExtent) + (⌊(z - imageOffset.z) / blockDepth⌋ × sliceExtent) + ((layer -imageSubresource.baseArrayLayer) × layerExtent) -
rowExtent = ⌈ max(
bufferRowLength,imageExtent.width) / blockWidth ⌉ × blockSize -
sliceExtent = ⌈ max(
bufferImageHeight,imageExtent.height) / blockHeight ⌉ × rowExtent -
layerExtent = ⌈
imageExtent.depth/ blockDepth ⌉ × sliceExtent
and where blockSize, blockWidth, blockHeight, and blockDepth are the texel block size and extents of the image’s format.
If a rotation is specified by VkCopyCommandTransformInfoQCOM, the 2D region of the image being addressed is rotated around the offset, and texels at each coordinate (x',y',z',layer) are accessed in the image subresource instead, where:
-
If
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHRis specified, no rotation is performed:-
x' is in the same range as x
-
y' is in the same range as y
-
-
If
VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHRis specified-
x' is in the range [
imageOffset.x-imageExtent.height,imageOffset.x) -
y' is in the range [
imageOffset.y,imageOffset.y+imageExtent.width)
-
-
If
VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHRis specified:-
x' is in the range [
imageOffset.x-imageExtent.width,imageOffset.x) -
y' is in the range [
imageOffset.y-imageExtent.height,imageOffset.y)
-
-
If
VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHRis specified:-
x' is in the range [
imageOffset.x,imageOffset.x+imageExtent.height) -
y' is in the range [
imageOffset.y-imageExtent.width,imageOffset.y)
-
Buffer addressing calculations are unaffected by this rotation.
When copying between a buffer and the depth or stencil aspect of an image, data in the buffer is assumed to be laid out as separate planes rather than interleaved. Addressing calculations are thus performed for a different format than the base image, according to the aspect, as described in the following table:
| Base Format | Depth Aspect Format | Stencil Aspect Format |
|---|---|---|
|
|
- |
|
|
- |
|
|
- |
|
- |
|
|
|
|
|
|
|
|
|
|
When copying between a buffer and any plane of a multi-planar image, addressing calculations are performed using the compatible format for that plane, rather than the format of the multi-planar image.
Each texel block is copied from one resource to the other according to the above addressing equations.
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 source region specified by pRegions is copied from the source
buffer to the destination region of the destination image according to the
addressing calculations for each
resource.
If any of the specified regions in srcBuffer overlaps in memory with
any of the specified regions in dstImage, values read from those
overlapping regions are undefined.
If any region accesses a depth aspect in dstImage
and the VK_EXT_depth_range_unrestricted extension is not enabled,
values copied from srcBuffer outside of the range [0,1] will be
written as undefined values to the destination image.
Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
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 source region specified by pRegions is copied from the source
image to the destination region of the destination buffer according to the
addressing calculations for each
resource.
If any of the specified regions in srcImage overlaps in memory with
any of the specified regions in dstBuffer, values read from those
overlapping regions are undefined.
Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
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.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
The VkCopyCommandTransformInfoQCOM structure is defined as:
// Provided by VK_QCOM_rotated_copy_commands
typedef struct VkCopyCommandTransformInfoQCOM {
VkStructureType sType;
const void* pNext;
VkSurfaceTransformFlagBitsKHR transform;
} VkCopyCommandTransformInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
transformis a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied.
Including this structure in the pNext chain of
VkBufferImageCopy2 defines a rotation to be performed when copying
between an image and a buffer.
Including this structure in the pNext chain of VkBlitImageInfo2
defines a rotation to be performed when blitting between two images.
If this structure is not specified in either case, the implementation
behaves as if it was specified with a transform equal to
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR.
Specifying a transform for a copy between an image and a buffer rotates the region accessed in the image around the offset. Specifying a transform for a blit performs a similar transform as described in Image Blits with Scaling and Rotation.
Rotations other than VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR can only
be specified for single-plane 2D images with a 1x1x1
texel block extent.
The following commands can be used to copy between host memory and images. Bytes in host memory and texels in images are accessed as specified in Copying Data Between Buffers and Images, with buffers replaced with host memory.
|
Note
|
Copies to and from an image on the host are not internally synchronized. Simultaneous access (involving writes) to overlapping image memory on the host constitutes a data race. |
To copy data from host memory to an image object, call:
// Provided by VK_VERSION_1_4
VkResult vkCopyMemoryToImage(
VkDevice device,
const VkCopyMemoryToImageInfo* pCopyMemoryToImageInfo);
or the equivalent command
// Provided by VK_EXT_host_image_copy
VkResult vkCopyMemoryToImageEXT(
VkDevice device,
const VkCopyMemoryToImageInfo* pCopyMemoryToImageInfo);
-
deviceis the device which ownspCopyMemoryToImageInfo->dstImage. -
pCopyMemoryToImageInfois a pointer to a VkCopyMemoryToImageInfo structure describing the copy parameters.
This command is functionally similar to vkCmdCopyBufferToImage2,
except it is executed on the host and reads from host memory instead of a
buffer.
The memory of pCopyMemoryToImageInfo->dstImage is accessed by the host
as if coherent.
|
Note
|
Because queue submissions automatically make host memory visible to the device, there would not be a need for a memory barrier before using the results of this copy operation on the device. |
The VkCopyMemoryToImageInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkCopyMemoryToImageInfo {
VkStructureType sType;
const void* pNext;
VkHostImageCopyFlags flags;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkMemoryToImageCopy* pRegions;
} VkCopyMemoryToImageInfo;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkCopyMemoryToImageInfo VkCopyMemoryToImageInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkHostImageCopyFlagBits values describing additional copy parameters. -
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 VkMemoryToImageCopy structures specifying the regions to copy.
vkCopyMemoryToImage does not check whether the device memory
associated with dstImage is currently in use before performing the
copy.
The application must guarantee that any previously submitted command that
reads from or writes to the copy regions has completed before the host
performs the copy.
Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
Each element of VkCopyMemoryToImageInfo::pRegions is a structure
defined as:
// Provided by VK_VERSION_1_4
typedef struct VkMemoryToImageCopy {
VkStructureType sType;
const void* pNext;
const void* pHostPointer;
uint32_t memoryRowLength;
uint32_t memoryImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkMemoryToImageCopy;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkMemoryToImageCopy VkMemoryToImageCopyEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pHostPointeris the host memory address which is the source of the copy. -
memoryRowLengthandmemoryImageHeightspecify in texels a subregion of a larger two- or three-dimensional image in host memory, and control the addressing calculations. If either of these values is zero, that aspect of the host 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 destination image data. -
imageExtentis the size in texels of the image to copy inwidth,heightanddepth.
This structure is functionally similar to VkBufferImageCopy2, except it defines host memory as the source of copy instead of a buffer. In particular, the same data packing rules and restrictions as that structure apply here as well.
To copy data from an image object to host memory, call:
// Provided by VK_VERSION_1_4
VkResult vkCopyImageToMemory(
VkDevice device,
const VkCopyImageToMemoryInfo* pCopyImageToMemoryInfo);
or the equivalent command
// Provided by VK_EXT_host_image_copy
VkResult vkCopyImageToMemoryEXT(
VkDevice device,
const VkCopyImageToMemoryInfo* pCopyImageToMemoryInfo);
-
deviceis the device which ownspCopyImageToMemoryInfo->srcImage. -
pCopyImageToMemoryInfois a pointer to a VkCopyImageToMemoryInfo structure describing the copy parameters.
This command is functionally similar to vkCmdCopyImageToBuffer2,
except it is executed on the host and writes to host memory instead of a
buffer.
The memory of pCopyImageToMemoryInfo->srcImage is accessed by the host
as if coherent.
|
Note
|
If the device has written to the image memory, it is not automatically made
available to the host.
Before this copy command can be called, a memory barrier for this image
must have been issued on the device with the second
synchronization scope including
|
The VkCopyImageToMemoryInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkCopyImageToMemoryInfo {
VkStructureType sType;
const void* pNext;
VkHostImageCopyFlags flags;
VkImage srcImage;
VkImageLayout srcImageLayout;
uint32_t regionCount;
const VkImageToMemoryCopy* pRegions;
} VkCopyImageToMemoryInfo;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkCopyImageToMemoryInfo VkCopyImageToMemoryInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkHostImageCopyFlagBits values describing additional copy parameters. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the copy. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkImageToMemoryCopy structures specifying the regions to copy.
vkCopyImageToMemory does not check whether the device memory
associated with srcImage is currently in use before performing the
copy.
The application must guarantee that any previously submitted command that
writes to the copy regions has completed before the host performs the copy.
Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
Each element of VkCopyImageToMemoryInfo::pRegions is a structure
defined as:
// Provided by VK_VERSION_1_4
typedef struct VkImageToMemoryCopy {
VkStructureType sType;
const void* pNext;
void* pHostPointer;
uint32_t memoryRowLength;
uint32_t memoryImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkImageToMemoryCopy;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkImageToMemoryCopy VkImageToMemoryCopyEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pHostPointeris the host memory address which is the destination of the copy. -
memoryRowLengthandmemoryImageHeightspecify in texels a subregion of a larger two- or three-dimensional image in host memory, and control the addressing calculations. If either of these values is zero, that aspect of the host 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 image data. -
imageExtentis the size in texels of the image to copy inwidth,heightanddepth.
This structure is functionally similar to VkBufferImageCopy2, except it defines host memory as the target of copy instead of a buffer. In particular, the same data packing rules and restrictions as that structure apply here as well.
Bits which can be set in VkCopyMemoryToImageInfo::flags,
VkCopyImageToMemoryInfo::flags, and
VkCopyImageToImageInfo::flags, specifying additional copy
parameters are:
// Provided by VK_VERSION_1_4
typedef enum VkHostImageCopyFlagBits {
VK_HOST_IMAGE_COPY_MEMCPY_BIT = 0x00000001,
// VK_HOST_IMAGE_COPY_MEMCPY is a deprecated alias
VK_HOST_IMAGE_COPY_MEMCPY = VK_HOST_IMAGE_COPY_MEMCPY_BIT,
// Provided by VK_EXT_host_image_copy
VK_HOST_IMAGE_COPY_MEMCPY_BIT_EXT = VK_HOST_IMAGE_COPY_MEMCPY_BIT,
// Provided by VK_EXT_host_image_copy
// VK_HOST_IMAGE_COPY_MEMCPY_EXT is a deprecated alias
VK_HOST_IMAGE_COPY_MEMCPY_EXT = VK_HOST_IMAGE_COPY_MEMCPY_BIT,
} VkHostImageCopyFlagBits;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkHostImageCopyFlagBits VkHostImageCopyFlagBitsEXT;
-
VK_HOST_IMAGE_COPY_MEMCPY_BITspecifies that no memory layout swizzling is to be applied during data copy. For copies between memory and images, this flag indicates that image data in host memory is swizzled in exactly the same way as the image data on the device. Using this flag indicates that the implementations may use a simple memory copy to transfer the data between the host memory and the device memory. The format of the swizzled data in host memory is platform dependent and is not defined in this specification.
// Provided by VK_VERSION_1_4
typedef VkFlags VkHostImageCopyFlags;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkHostImageCopyFlags VkHostImageCopyFlagsEXT;
VkHostImageCopyFlags is a bitmask type for setting a mask of zero or
more VkHostImageCopyFlagBits.
To copy data from an image object to another image object using the host, call:
// Provided by VK_VERSION_1_4
VkResult vkCopyImageToImage(
VkDevice device,
const VkCopyImageToImageInfo* pCopyImageToImageInfo);
or the equivalent command
// Provided by VK_EXT_host_image_copy
VkResult vkCopyImageToImageEXT(
VkDevice device,
const VkCopyImageToImageInfo* pCopyImageToImageInfo);
-
deviceis the device which ownspCopyImageToImageInfo->srcImageandpCopyImageToImageInfo->dstImage. -
pCopyImageToImageInfois a pointer to a VkCopyImageToImageInfo structure describing the copy parameters.
This command is functionally similar to vkCmdCopyImage2, except it is
executed on the host.
The memory of pCopyImageToImageInfo->srcImage and
pCopyImageToImageInfo->dstImage is accessed by the host as if
coherent.
|
Note
|
If the device has written to the memory of
Because queue submissions automatically make host memory visible to the device, there would not be a
need for a memory barrier before using the results of this copy operation in
|
The VkCopyImageToImageInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkCopyImageToImageInfo {
VkStructureType sType;
const void* pNext;
VkHostImageCopyFlags flags;
VkImage srcImage;
VkImageLayout srcImageLayout;
VkImage dstImage;
VkImageLayout dstImageLayout;
uint32_t regionCount;
const VkImageCopy2* pRegions;
} VkCopyImageToImageInfo;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkCopyImageToImageInfo VkCopyImageToImageInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkHostImageCopyFlagBits values describing additional copy parameters. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the copy. -
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 VkImageCopy2 structures specifying the regions to copy.
vkCopyImageToImage does not check whether the device memory associated
with srcImage or dstImage is currently in use before performing
the copy.
The application must guarantee that any previously submitted command that
writes to the copy regions has completed before the host performs the copy.
21.4. Indirect Copies
An application can use indirect copies when the copy parameters are not known during the command buffer creation time.
To copy data between two memory regions by specifying copy parameters indirectly in a buffer, call:
// Provided by VK_NV_copy_memory_indirect
void vkCmdCopyMemoryIndirectNV(
VkCommandBuffer commandBuffer,
VkDeviceAddress copyBufferAddress,
uint32_t copyCount,
uint32_t stride);
-
commandBufferis the command buffer into which the command will be recorded. -
copyBufferAddressis the buffer address specifying the copy parameters. This buffer is laid out in memory as an array of VkCopyMemoryIndirectCommandNV structures. -
copyCountis the number of copies to execute, and can be zero. -
strideis the stride in bytes between successive sets of copy parameters.
Each region read from copyBufferAddress is copied from the source
region to the specified destination region.
The results are undefined if any of the source and destination regions
overlap in memory.
The structure describing source and destination memory regions,
VkCopyMemoryIndirectCommandNV is defined as:
// Provided by VK_NV_copy_memory_indirect
typedef struct VkCopyMemoryIndirectCommandNV {
VkDeviceAddress srcAddress;
VkDeviceAddress dstAddress;
VkDeviceSize size;
} VkCopyMemoryIndirectCommandNV;
-
srcAddressis the starting address of the source device memory to copy from. -
dstAddressis the starting address of the destination device memory to copy to. -
sizeis the size of the copy in bytes.
To copy data from a memory region to an image object by specifying copy parameters in a buffer, call:
// Provided by VK_NV_copy_memory_indirect
void vkCmdCopyMemoryToImageIndirectNV(
VkCommandBuffer commandBuffer,
VkDeviceAddress copyBufferAddress,
uint32_t copyCount,
uint32_t stride,
VkImage dstImage,
VkImageLayout dstImageLayout,
const VkImageSubresourceLayers* pImageSubresources);
-
commandBufferis the command buffer into which the command will be recorded. -
copyBufferAddressis the buffer address specifying the copy parameters. This buffer is laid out in memory as an array of VkCopyMemoryToImageIndirectCommandNV structures. -
copyCountis the number of copies to execute, and can be zero. -
strideis the byte stride between successive sets of copy parameters. -
dstImageis the destination image. -
dstImageLayoutis the layout of the destination image subresources for the copy. -
pImageSubresourcesis a pointer to an array of sizecopyCountof VkImageSubresourceLayers used to specify the specific image subresource of the destination image data for that copy.
Each region in copyBufferAddress is copied from the source memory
region to an image region in the destination image.
If the destination image is of type VK_IMAGE_TYPE_3D, the starting
slice and number of slices to copy are specified in
pImageSubresources->baseArrayLayer and
pImageSubresources->layerCount respectively.
The copy must be performed on a queue that supports indirect copy
operations, see VkPhysicalDeviceCopyMemoryIndirectPropertiesNV.
The VkCopyMemoryToImageIndirectCommandNV is defined as:
// Provided by VK_NV_copy_memory_indirect
typedef struct VkCopyMemoryToImageIndirectCommandNV {
VkDeviceAddress srcAddress;
uint32_t bufferRowLength;
uint32_t bufferImageHeight;
VkImageSubresourceLayers imageSubresource;
VkOffset3D imageOffset;
VkExtent3D imageExtent;
} VkCopyMemoryToImageIndirectCommandNV;
-
srcAddressis the starting address of the source device memory to copy from. -
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 destination image data, which must match the values specified inpImageSubresourcesparameter of vkCmdCopyMemoryToImageIndirectNV during command recording. -
imageOffsetselects the initialx,y,zoffsets in texels of the sub-region of the destination image data. -
imageExtentis the size in texels of the destination image inwidth,heightanddepth.
21.5. 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 a VkStructureType value identifying 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.
If filter is VK_FILTER_CUBIC_EXT and if the pNext chain of
VkBlitImageInfo2 includes a VkBlitImageCubicWeightsInfoQCOM
structure, then that structure specifies cubic weights are used in the blit.
If that structure is not present, then cubic weights are considered to be
VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM.
The VkBlitImageCubicWeightsInfoQCOM structure is defined as:
// Provided by VK_QCOM_filter_cubic_weights
typedef struct VkBlitImageCubicWeightsInfoQCOM {
VkStructureType sType;
const void* pNext;
VkCubicFilterWeightsQCOM cubicWeights;
} VkBlitImageCubicWeightsInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cubicWeightsis a VkCubicFilterWeightsQCOM value controlling cubic filter weights for the blit.
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 a VkStructureType value identifying 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, have a 1x1x1 texel block
extent, and only one plane.
21.5.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.
21.6. 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 format is a floating-point or normalized type, the resolve mode is chosen as implementation-dependent behavior. If the resolve mode requires to calculate the result from multiple samples, such as by computing an average or weighted average of the samples, the values for each pixel are resolved with implementation-defined numerical precision.
If the numeric format of srcImage uses sRGB
encoding and the resolve mode requires the implementation to convert the
samples to floating-point to perform the calculations, the implementation
should convert samples from nonlinear to linear before resolving the
samples as described in the “sRGB EOTF” section of the
Khronos Data Format Specification.
In this case, the implementation must convert the linear averaged value to
nonlinear before writing the resolved result to dstImage.
If the source format is an integer type, 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
21.7. Buffer Markers
To write a 32-bit marker value into a buffer as a pipelined operation, call:
// Provided by VK_AMD_buffer_marker with VK_VERSION_1_3 or VK_KHR_synchronization2
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.8. Copying Data Between Tensors
vkCmdCopyTensorARM performs tensor copies in a similar manner to a host memcpy. It does not perform general-purpose conversions such as scaling, resizing, or format conversions. Rather, it simply copies raw tensor data. vkCmdCopyTensorARM can copy between tensors with different formats, provided the formats are compatible. Tensor formats are compatible if they share the same class, as shown in the Compatible Formats.
To copy data between tensor objects, call:
// Provided by VK_ARM_tensors
void vkCmdCopyTensorARM(
VkCommandBuffer commandBuffer,
const VkCopyTensorInfoARM* pCopyTensorInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pCopyTensorInfois a pointer to VkCopyTensorInfoARM structure describing the copy parameters.
The VkCopyTensorInfoARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkCopyTensorInfoARM {
VkStructureType sType;
const void* pNext;
VkTensorARM srcTensor;
VkTensorARM dstTensor;
uint32_t regionCount;
const VkTensorCopyARM* pRegions;
} VkCopyTensorInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextis NULL or a pointer to a structure extending this structure. -
srcTensoris the source tensor. -
dstTensoris the destination tensor. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkTensorCopyARM structures specifying the regions to copy.
Each region in pRegions describes a region to be copied from the
source tensor to a corresponding region of the destination tensor.
srcTensor and dstTensor can be the same tensor or alias the
same memory.
The formats of srcTensor and dstTensor must be compatible.
Formats are compatible if they share the same class, as shown in the
Compatible Formats table.
|
Note
|
editing-note
The valid usage rules restrict copies to copying whole tensors of equal sizes. That is, only a single region can be copied and this region must be the entire tensor. This means the entire tensor must be copied. These restrictions may be relaxed in future extensions. |
vkCmdCopyTensorARM allows copying between size-compatible internal
formats.
The VkTensorCopyARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkTensorCopyARM {
VkStructureType sType;
const void* pNext;
uint32_t dimensionCount;
const uint64_t* pSrcOffset;
const uint64_t* pDstOffset;
const uint64_t* pExtent;
} VkTensorCopyARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dimensionCountis the number of elements in thepSrcOffset,pDstOffsetandpExtentarrays. -
pSrcOffsetisNULLor an array of sizedimensionCountproviding an offset into the source tensor. WhenpSrcOffsetisNULL, the offset into the source tensor is0in all dimensions. -
pDstOffsetisNULLor an array of sizedimensionCountproviding an offset into the destination tensor. WhenpDstOffsetisNULL, the offset into the destination tensor is0in all dimensions. -
pExtentisNULLor an array of sizedimensionCountproviding the number of elements to copy in each dimension. WhenpExtentisNULL, the number of elements to copy is taken as the total number of elements in each dimension of the source tensor.
22. 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, or if the shaderObject feature is
enabled, any shader objects bound to graphics stages.
A graphics pipeline
or a combination of one or more graphics shader objects
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 a VkStructureType value identifying 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 of Vulkan 1.4 orvkCmdBindIndexBuffer2orvkCmdBindIndexBufferis equal toVK_INDEX_TYPE_UINT32; 0xFF whenindexTypeis equal toVK_INDEX_TYPE_UINT8; 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, VK_EXT_shader_object
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 drawing using shader objects, or
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.
22.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, VK_EXT_shader_object
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 drawing using shader objects, or
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.
22.1.1. Topology Class
The primitive topologies are grouped into the following topology classes:
| Topology Class | Primitive Topology |
|---|---|
Point |
|
Line |
|
Triangle |
|
Patch |
|
22.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.
22.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.
22.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.
22.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.
22.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. |
22.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 |
22.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.
22.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.
22.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.
22.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.
22.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.
22.2. Effective Primitive Topology
The effective primitive topology is the primitive topology that is consumed or produced by a given stage of the graphics pipeline. The interpretation of this topology depends on the active shader stages and other state set in the graphics pipeline.
22.2.1. Vertex Input Assembler Topology
This is the topology set when the VK_SHADER_STAGE_VERTEX_BIT stage is
used and Programmable Primitive Shading
occurs.
It can be set with
VkPipelineInputAssemblyStateCreateInfo::topology
or vkCmdSetPrimitiveTopology.
22.2.2. Clip Space Topology
This is the output of the last pre-rasterization shader stage involved.
-
If
VK_SHADER_STAGE_VERTEX_BITis the last pre-rasterization stage, the topology is not changed from what was set in the input assembly. -
If
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BITis the last pre-rasterization stage, the topology depends on theOpExecutionModefound in either tessellation stage.-
The
IsolinesExecutionModeis in line topology class. -
The
TrianglesandQuadsExecutionModeis in triangle topology class. -
The
PointModeExecutionModeis in point topology class and will take precedence over the other tessellation stageExecutionMode.
-
-
If
VK_SHADER_STAGE_GEOMETRY_BITis the last pre-rasterization stage, the topology depends on theOpExecutionModefound in this shader stage.-
The
OutputPointsExecutionModeis in point topology class. -
The
OutputLineStripExecutionModeis in line topology class. -
The
OutputTriangleStripExecutionModeis in triangle topology class.
-
-
If
VK_SHADER_STAGE_MESH_BIT_EXTis the last pre-rasterization stage, the topology depends on theOpExecutionModefound in this shader stage.-
The
OutputPointsExecutionModeis in point topology class. -
The
OutputLinesEXTExecutionModeis in line topology class. -
The
OutputTrianglesEXTExecutionModeis in triangle topology class.
-
22.2.3. Rasterization Input Topology
After clipping and viewport transformations, the Polygon Mode can set a topology as an input for rasterization. This can be different from what was used in Clip Space Topology.
If
VkPipelineRasterizationStateCreateInfo::rasterizerDiscardEnable
or vkCmdSetRasterizerDiscardEnableEXT::rasterizerDiscardEnable
is set to VK_FALSE, then this Rasterization Input Topology is not
observed.
If the clip space topology is in triangle
topology class then
VK_POLYGON_MODE_LINE will turn it into line topology and
VK_POLYGON_MODE_POINT will turn it into point topology.
If the clip space topology is in line
topology class then
VK_POLYGON_MODE_POINT will turn it into point topology.
22.3. 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.
-
For draws using cluster culling shaders, the order is provided by cluster culling 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.
22.4. 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.
If the maintenance6 feature is enabled,
buffer can be VK_NULL_HANDLE.
If buffer is VK_NULL_HANDLE and the nullDescriptor feature is enabled, every index fetched results in a
value of zero.
To bind an index buffer, along with its size, to a command buffer, call:
// Provided by VK_VERSION_1_4
void vkCmdBindIndexBuffer2(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkDeviceSize size,
VkIndexType indexType);
or the equivalent command
// Provided by VK_KHR_maintenance5
void vkCmdBindIndexBuffer2KHR(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset,
VkDeviceSize size,
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. -
sizeis the size in bytes of index data bound frombuffer. -
indexTypeis a VkIndexType value specifying the size of the indices.
size specifies the bound size of the index buffer starting from
offset.
If size is VK_WHOLE_SIZE then the bound size is from
offset to the end of the buffer.
If the maintenance6 feature is enabled,
buffer can be VK_NULL_HANDLE.
If buffer is VK_NULL_HANDLE and the nullDescriptor feature is enabled, every index fetched results in a
value of zero.
Possible values of
vkCmdBindIndexBuffer2::indexType and
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_VERSION_1_4
VK_INDEX_TYPE_UINT8 = 1000265000,
// Provided by VK_KHR_acceleration_structure
VK_INDEX_TYPE_NONE_KHR = 1000165000,
// Provided by VK_NV_ray_tracing
VK_INDEX_TYPE_NONE_NV = VK_INDEX_TYPE_NONE_KHR,
// Provided by VK_EXT_index_type_uint8
VK_INDEX_TYPE_UINT8_EXT = VK_INDEX_TYPE_UINT8,
// Provided by VK_KHR_index_type_uint8
VK_INDEX_TYPE_UINT8_KHR = VK_INDEX_TYPE_UINT8,
} 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_UINT8specifies 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
vkCmdBindIndexBuffer2::indexType or 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
or vkCmdBindIndexBuffer2,
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 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 draws 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 per draw. -
firstInstanceis the instance ID of the first instance in each draw. -
strideis the byte stride between consecutive elements ofpVertexInfo.
The number of draws recorded is drawCount, with each draw reading,
sequentially, a firstVertex and a vertexCount from
pVertexInfo.
For each recorded draw, primitives are assembled as for vkCmdDraw, and
drawn instanceCount times with instanceIndex starting with
firstInstance and sequentially for each instance.
To record an ordered sequence of indexed draws 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 per draw. -
firstInstanceis the instance ID of the first instance in each 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.
The number of draws recorded is drawCount, with each draw reading,
sequentially, a firstIndex and an indexCount from
pIndexInfo.
For each recorded draw, primitives are assembled as for
vkCmdDrawIndexed, and drawn instanceCount times with
instanceIndex starting with firstInstance and sequentially for
each instance.
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.
22.4.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.
22.5. 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 a VkStructureType value identifying 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.
22.6. 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 mesh tasks drawing command, 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 drawing command, 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 drawing command with the draw count sourced from a buffer, call:
// Provided by VK_NV_mesh_shader with VK_KHR_draw_indirect_count or VK_VERSION_1_2
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.
To record a mesh tasks drawing command, call:
// Provided by VK_EXT_mesh_shader
void vkCmdDrawMeshTasksEXT(
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 mesh tasks drawing command, call:
// Provided by VK_EXT_mesh_shader
void vkCmdDrawMeshTasksIndirectEXT(
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.
vkCmdDrawMeshTasksIndirectEXT behaves similarly to
vkCmdDrawMeshTasksEXT 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
VkDrawMeshTasksIndirectCommandEXT structures.
If drawCount is less than or equal to one, stride is ignored.
The VkDrawMeshTasksIndirectCommandEXT structure is defined as:
// Provided by VK_EXT_mesh_shader
typedef struct VkDrawMeshTasksIndirectCommandEXT {
uint32_t groupCountX;
uint32_t groupCountY;
uint32_t groupCountZ;
} VkDrawMeshTasksIndirectCommandEXT;
-
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.
The members of VkDrawMeshTasksIndirectCommandEXT have the same meaning
as the similarly named parameters of vkCmdDrawMeshTasksEXT.
To record an indirect mesh tasks drawing command with the draw count sourced from a buffer, call:
// Provided by VK_EXT_mesh_shader with VK_KHR_draw_indirect_count or VK_VERSION_1_2
void vkCmdDrawMeshTasksIndirectCountEXT(
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.
vkCmdDrawMeshTasksIndirectCountEXT behaves similarly to
vkCmdDrawMeshTasksIndirectEXT 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.7. Programmable Cluster Culling Shading
In this drawing approach, cluster are generated by the cluster culling shader stage. It operates similarly to dispatching compute as the shaders make use of workgroups.
To record a cluster culling shader drawing command, call:
// Provided by VK_HUAWEI_cluster_culling_shader
void vkCmdDrawClusterHUAWEI(
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 workgroup is assembled.
Note that the cluster culling shader pipeline only accepts
vkCmdDrawClusterHUAWEI and vkCmdDrawClusterIndirectHUAWEI as
drawing commands.
To record an indirect cluster culling drawing command, call:
// Provided by VK_HUAWEI_cluster_culling_shader
void vkCmdDrawClusterIndirectHUAWEI(
VkCommandBuffer commandBuffer,
VkBuffer buffer,
VkDeviceSize offset);
-
commandBufferis the command buffer into which the command is recorded. -
bufferis the buffer containing draw parameters. -
offsetis the byte offset intobufferwhere parameters begin.
vkCmdDrawClusterIndirectHUAWEI behaves similarly to
vkCmdDrawClusterHUAWEI 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.
Note the cluster culling shader pipeline only accepts
vkCmdDrawClusterHUAWEI and vkCmdDrawClusterIndirectHUAWEI as
drawing commands.
23. Fixed-Function Vertex Processing
Vertex fetching is controlled via configurable state, as a logically distinct graphics pipeline stage.
23.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
...
23.1.1. Attribute Location and Component Assignment
The Location decoration specifies which vertex input attribute is used
to read and interpret the data that a variable will consume.
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.
If an implementation supports storageInputOutput16, vertex shader input variables can have a
width of 16 bits.
In all the following component assignment specifications, if
the vertexAttributeRobustness
feature is enabled,
or
the maintenance9 feature is enabled,
and there is no VkVertexInputAttributeDescription::location
specified for the shader vertex attribute Location being read, the
value (0,0,0,0) or (0,0,0,1) is used for each of the equivalent (x,y,z,w)
components consumed entries as specified 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 Location slots and Component words 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 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.
Two variables are allowed to share the same Location slot only if their
Component words do not overlap.
If multiple variables share the same Location slot, they must all have
the same SPIR-V floating-point component type or all have the same width
scalar type components.
23.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 a VkStructureType value identifying 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 of VkVertexInputBindingDescription structures. -
vertexAttributeDescriptionCountis the number of vertex attribute descriptions provided inpVertexAttributeDescriptions. -
pVertexAttributeDescriptionsis a pointer to an array of VkVertexInputAttributeDescription structures.
// 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_shader_object, 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 of VkVertexInputBindingDescription2EXT structures. -
vertexAttributeDescriptionCountis the number of vertex attribute descriptions provided inpVertexAttributeDescriptions. -
pVertexAttributeDescriptionsis a pointer to an array of VkVertexInputAttributeDescription2EXT structures.
This command sets the vertex input attribute and vertex input binding
descriptions state for subsequent drawing commands
when drawing using shader objects, or
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
drawing using shader objects,
or 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 vertex attribute description for any location in the range
[0,VkPhysicalDeviceLimits::maxVertexInputAttributes) not
specified in the pVertexAttributeDescriptions array becomes
undefined.
The VkVertexInputBindingDescription2EXT structure is defined as:
// Provided by VK_EXT_shader_object, 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 a VkStructureType value identifying 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 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_shader_object, 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 a VkStructureType value identifying 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, VK_EXT_shader_object
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].
If pSizes[i] is VK_WHOLE_SIZE then the bound size is from
pBuffers[i] plus pOffsets[i] to the end 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).
This command also dynamically sets the byte
strides between consecutive elements within buffer pBuffers[i] to the
corresponding pStrides[i] value
when drawing using shader objects, or
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
drawing using shader objects
or 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.
|
Note
|
Unlike the static state to set the same, |
23.3. Vertex Attribute Divisor in Instanced Rendering
If the vertexAttributeInstanceRateDivisor feature is enabled and the
pNext chain of VkPipelineVertexInputStateCreateInfo includes a
VkPipelineVertexInputDivisorStateCreateInfo structure, then that
structure controls how vertex attributes are assigned to an instance when
instanced rendering is enabled.
The VkPipelineVertexInputDivisorStateCreateInfo structure is defined
as:
// Provided by VK_VERSION_1_4
typedef struct VkPipelineVertexInputDivisorStateCreateInfo {
VkStructureType sType;
const void* pNext;
uint32_t vertexBindingDivisorCount;
const VkVertexInputBindingDivisorDescription* pVertexBindingDivisors;
} VkPipelineVertexInputDivisorStateCreateInfo;
or the equivalent
// Provided by VK_KHR_vertex_attribute_divisor
typedef VkPipelineVertexInputDivisorStateCreateInfo VkPipelineVertexInputDivisorStateCreateInfoKHR;
or the equivalent
// Provided by VK_EXT_vertex_attribute_divisor
typedef VkPipelineVertexInputDivisorStateCreateInfo VkPipelineVertexInputDivisorStateCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexBindingDivisorCountis the number of elements in thepVertexBindingDivisorsarray. -
pVertexBindingDivisorsis a pointer to an array of VkVertexInputBindingDivisorDescription structures specifying the divisor value for each binding.
The individual divisor values per binding are specified using the
VkVertexInputBindingDivisorDescription structure which is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkVertexInputBindingDivisorDescription {
uint32_t binding;
uint32_t divisor;
} VkVertexInputBindingDivisorDescription;
or the equivalent
// Provided by VK_KHR_vertex_attribute_divisor
typedef VkVertexInputBindingDivisorDescription VkVertexInputBindingDivisorDescriptionKHR;
or the equivalent
// Provided by VK_EXT_vertex_attribute_divisor
typedef VkVertexInputBindingDivisorDescription 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 using VkPhysicalDeviceVertexAttributeDivisorProperties::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.
23.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::pVertexAttributeDescriptionswith VkVertexInputAttributeDescription::locationequal to the vertex input attribute number. -
Let
bindingDescbe the member of VkPipelineVertexInputStateCreateInfo::pVertexBindingDescriptionswith VkVertexInputAttributeDescription::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 bound vertex buffers specified duringvkCmdBindVertexBuffersorvkCmdBindVertexBuffers2withpOffsets. -
Let
divisorbe the member of VkPipelineVertexInputDivisorStateCreateInfo::pVertexBindingDivisorswith VkVertexInputBindingDivisorDescription::bindingequal toattribDesc.binding. If the vertex binding state is dynamically set, instead letdivisorbe the member of thepVertexBindingDescriptionsparameter to the vkCmdSetVertexInputEXT call with VkVertexInputBindingDescription2EXT::bindingequal toattribDesc.binding. -
Let
stridebe the member of VkPipelineVertexInputStateCreateInfo::pVertexBindingDescriptions->strideunless there is dynamic state causing the value to be ignored. In this case the value is set from the last value from one of the following-
vkCmdSetVertexInputEXT::
pVertexBindingDescriptions->stride -
vkCmdBindVertexBuffers2::
pStrides, if notNULL
-
bufferBindingAddress = buffer[binding].baseAddress + offset[binding];
if (bindingDesc.inputRate == VK_VERTEX_INPUT_RATE_VERTEX)
effectiveVertexOffset = vertexIndex * stride;
else
if (divisor == 0)
effectiveVertexOffset = firstInstance * stride;
else
effectiveVertexOffset = (firstInstance + ((instanceIndex - firstInstance) / divisor)) * stride;
attribAddress = bufferBindingAddress + effectiveVertexOffset + attribDesc.offset;
23.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
numeric type of format.
The numeric type of format must match the numeric 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
either format is a 64-bit format or the
legacyVertexAttributes feature is
not enabled, and
format is a packed format, attribAddress must be a multiple of the
size in bytes of the size of the format as described in
Packed Formats.
Otherwise,
if either format is a 64-bit format or the
legacyVertexAttributes feature is
not enabled,
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.
24. 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.
24.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 using one of the Triangles,
Quads, or IsoLines execution modes.
When using shader objects, this instruction must be
specified in the tessellation evaluation shader, and may also be specified
in the tessellation control shader.
When using pipelines, this
instruction may be specified in either the tessellation evaluation or
tessellation control shader.
When using shader objects, tessellation-related modes that are required
must be specified in the tessellation evaluation shader, and may also be
specified in the tessellation control shader.
Other tessellation-related modes may be specified in the tessellation
evaluation shader.
When using pipelines, other
tessellation-related execution modes can also be specified in either the
tessellation control or tessellation evaluation shaders.
Any tessellation-related modes specified in both the tessellation control and tessellation evaluation shaders must be the same.
Tessellation execution modes include:
-
Triangles,Quads, andIsoLines. These control the type of subdivision and topology of the output primitives. When using shader objects, one mode must be set in at least the tessellation evaluation stage. When using pipelines, 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. When using shader objects, one mode must be set in at least the tessellation evaluation stage. When using pipelines, 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. When using shader objects, ifPointModeis set in the tessellation control stage, it must be identically set in the tessellation evaluation stage. 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. When using shader objects, one mode must be set in at least the tessellation evaluation stage. When using pipelines, 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. When using shader objects, one value must be set in at least the tessellation control stage. When using pipelines, 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.
24.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.
24.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.
24.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.
24.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 |
24.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.
24.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.
24.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 |
24.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 |
24.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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
To dynamically set the origin of the tessellation domain space, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_KHR_maintenance2 or VK_VERSION_1_1, VK_EXT_shader_object
void vkCmdSetTessellationDomainOriginEXT(
VkCommandBuffer commandBuffer,
VkTessellationDomainOrigin domainOrigin);
-
commandBufferis the command buffer into which the command will be recorded. -
domainOriginspecifies the origin of the tessellation domain space.
This command sets the origin of the tessellation domain space for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineTessellationDomainOriginStateCreateInfo::domainOrigin
value used to create the currently active pipeline.
25. 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.
25.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.
25.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.
25.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.
25.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.
25.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.
25.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.
25.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.
26. 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.
26.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.
26.2. Task Shader Output
The task shader can emit zero or more mesh workgroups to be generated.
Shaders using the TaskNV Execution Model can do so using the
built-in variable TaskCountNV.
This value must be less than or equal to
VkPhysicalDeviceMeshShaderPropertiesNV::maxTaskOutputCount.
Shaders using the TaskEXT Execution Model can do so using the
OpEmitMeshTasksEXT instruction.
The groupCountX, groupCountY and groupCountZ arguments passed
to this instruction must be less than or equal to the respective dimension
within
VkPhysicalDeviceMeshShaderPropertiesEXT::maxMeshWorkGroupCount.
The product of these arguments must be less than or equal to
VkPhysicalDeviceMeshShaderPropertiesEXT::maxMeshWorkGroupTotalCount.
The task shader can also pass user-defined data to all mesh shader
invocations that it creates.
Shaders using the TaskNV Execution Model can do so by writing to
output variables that are decorated with PerTaskNV.
They are available as inputs in mesh shaders.
Shaders using the TaskEXT Execution Model can do so by writing to a
payload variable with TaskPayloadWorkgroupEXT storage class that is
passed to the OpEmitMeshTasksEXT instruction.
26.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.
26.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
or
the payload variable passed to the OpEmitMeshTasksEXT instruction
by the task shader that spawned the mesh shader’s workgroup.
The mesh shader can operate without a task shader as well.
26.5. Mesh Shader Output
A mesh shader generates primitives in one of three output modes: points,
lines, or triangles.
For shaders using the MeshNV Execution Model the primitive mode is
specified in the shader using an OpExecutionMode instruction with the
OutputPoints, OutputLinesNV, or OutputTrianglesNV modes,
respectively.
For shaders using the MeshEXT Execution Model the primitive mode is
specified in the shader using an OpExecutionMode instruction with the
OutputPoints, OutputLinesEXT, or OutputTrianglesEXT modes,
respectively.
Each mesh shader must include exactly one output primitive mode.
For shaders using the MeshNV Execution Model 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.
For shaders using the MeshEXT Execution Model 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
VkPhysicalDeviceMeshShaderPropertiesEXT::maxMeshOutputVertices.
For shaders using the MeshNV Execution Model 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.
For shaders using the MeshEXT Execution Model the maximum output
primitive count is specified as a literal in the shader using an
OpExecutionMode instruction with the mode set to
OutputPrimitivesEXT, and must be less than or equal to
VkPhysicalDeviceMeshShaderPropertiesEXT::maxMeshOutputPrimitives.
For shaders using the MeshNV Execution Model 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.
For shaders using the MeshEXT Execution Model the number of vertices
and primitives output by the mesh shader is provided via calling the
OpSetMeshOutputsEXT instruction.
The vertexCount argument must be less than or equal to the maximum
output vertex count specified in the shader.
The primitiveCount argument must be less than or equal to the maximum
output primitive count specified in the shader.
Depending on the output primitive mode an appropriately-decorated variable is the output array of local index values into the vertex output arrays from which primitives are assembled according to the output primitive type:
-
OutputPointsuses thePrimitivePointIndicesEXTdecoration. -
OutputLinesEXTuses thePrimitiveLineIndicesEXTdecoration. -
OutputTrianglesEXTuses thePrimitiveTriangleIndicesEXTdecoration.
These resulting primitives are then further processed as described in Rasterization.
With the exception of primitive indices, all output built-ins and custom
attributes count towards the total storage size occupied by output variables
in mesh shaders.
This size can be calculated as follows, taking into account the fact that
the number of effective scalar attributes is 4 times the number of effective
locations used according to the location
assignment rules.
Let be the number of views, be the number of
effective scalar per-vertex attributes not dependent on ViewIndex,
be the number of effective scalar per-vertex attributes
dependent on ViewIndex, be the maximum number of
vertices specified by the OutputVertices Execution Mode,
be meshOutputPerVertexGranularity, be
the number of effective scalar per-primitive attributes not dependent on
ViewIndex, be the number of effective scalar
per-primitive attributes dependent on ViewIndex, be the
maximum number of primitives specified by the OutputPrimitivesEXT
Execution Mode and be
meshOutputPerPrimitiveGranularity:
26.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.
These per-view outputs are available only in shaders using the MeshNV
Execution Model.
They are not available in shaders using the MeshEXT Execution Model.
26.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).
27. Cluster Culling Shading
This shader type has an execution environment similar to that of a compute shader, where a collection of shader invocations form a workgroup and cooperate to perform coarse level geometry culling and LOD selection. A shader invocation can emit a set of built-in output variables via a new built-in function. The cluster culling shader organizes these emitted variables into a drawing command used by the subsequent rendering pipeline.
27.1. Cluster Culling Shader Input
The only inputs available to the cluster culling shader are variables identifying the specific workgroup and invocation.
27.2. Cluster Culling Shader Output
If a cluster survives after culling in a cluster culling shader invocation, a drawing command to draw this cluster should be emitted by this shader invocation for further rendering processing. There are two types of drawing command, indexed mode and non-indexed mode. Both type of drawing commands consist of a set of built-in output variables which have a similar definition to VkDrawIndexedIndirectCommand and VkDrawIndirectCommand members.
Cluster culling shaders have the following built-in output variables:
-
built-in variable
IndexCountHUAWEIis the number of vertices to draw. -
built-in variable
VertexCountHUAWEIis the number of vertices to draw. -
built-in variable
InstanceCountHUAWEIis the number of instances to draw. -
built-in variable
FirstIndexHUAWEIis the base index within the index buffer. -
built-in variable
FirstVertexHUAWEIis the index of the first vertex to draw -
built-in variable
VertexOffsetHUAWEIis the value added to the vertex index before indexing into the vertex buffer. -
built-in variable
FirstInstanceHUAWEIis the instance ID of the first instance to draw. -
built-in variable
ClusterIDHUAWEIis the index of cluster being rendered by this drawing command. When cluster culling shader is enabled,ClusterIDHUAWEIwill replacegl_DrawIDpass to vertex shader. -
built-in variable
ClusterShadingRateis the shading rate of cluster being rendered by this drawing command.
27.3. Cluster Culling Shader Cluster Ordering
-
When a cluster culling shader is used, all output clusters generated by
DispatchClusterHUAWEI() in a given workgroup are passed to subsequent pipeline stage before any cluster generated from subsequent workgroup. -
In a workgroup, the order of output clusters generated by
DispatchClusterHUAWEI() is specified by the local invocation id, from lower to higher values. -
If any cluster culling invocation in the workgroup does not call
DispatchClusterHUAWEI(), no cluster will be sent to the subsequent rendering pipeline. -
Any cluster culling shader invocation may also call
DispatchClusterHUAWEI() many times as shown below:
// Cluster Culling Shader sample code:
......
DispatchClusterHUAWEI(); // dispatch 0
......
DispatchClusterHUAWEI(); // dispatch 1
......
DispatchClusterHUAWEI(); // dispatch 2
......
In this case, the output sequence of clusters in a workgroup are specified as shown below ( in case of 32 shader invocations in a workgroup):
1. shader invocation0.dispatch0
2. shader invocation1.dispatch0,
..........
32. shader invocation31.dispatch0
33. shader invocation0.dispatch1
34. shader invocation1.dispatch1
..........
64. shader invocation31.dispatch1
65. shader invocation0.dispatch2
66. shader invocation1.dispatch2
..........
96. shader Invocation31.dispatch2
27.4. Cluster Culling Shader Primitive Ordering
Following guarantees are provided for the relative ordering of primitives produced by a cluster culling shader, as they pertain to primitive order.
-
Limited guarantees are provided for the relative ordering of primitives produced by a cluster culling shader, as they pertain to primitive order.
-
The order of primitives in a given cluster is specified by the content of
-
DispatchClusterHUAWEI() with indexed output built-in variables, vertices sourced from a lower index buffer addresses to higher addresses. -
DispatchClusterHUAWEI() with non-indexed output built-in variables, from vertices with a lower numbered vertexIndex to a higher numbered vertexIndex.
-
28. 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 application-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).
Next, rasterization is performed on primitives as described in chapter Rasterization.
28.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 the transformFeedbackPreservesProvokingVertex feature 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,OutputLineStrip, orOutputTriangleStripexecution 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 the transformFeedbackPreservesProvokingVertex feature 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
the transformFeedbackPreservesProvokingVertex feature 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, and the primitives needed and primitives written counts in the
corresponding VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT query will
increment as normal.
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 of VkDeviceSize buffer 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. In that case, a pipeline barrier is required between the calls tovkCmdEndTransformFeedbackEXTandvkCmdBeginTransformFeedbackEXT, withVK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXTas the source and destination stages,VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXTas the source access andVK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXTas the destination access. 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 of VkDeviceSize values 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 of VkDeviceSize values 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.
28.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 a VkStructureType value identifying 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.
To dynamically set the viewport swizzle state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_viewport_swizzle, VK_EXT_shader_object with VK_NV_viewport_swizzle
void vkCmdSetViewportSwizzleNV(
VkCommandBuffer commandBuffer,
uint32_t firstViewport,
uint32_t viewportCount,
const VkViewportSwizzleNV* pViewportSwizzles);
-
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. -
pViewportSwizzlesis a pointer to an array of VkViewportSwizzleNV structures specifying viewport swizzles.
This command sets the viewport swizzle state for subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportSwizzleStateCreateInfoNV::viewportCount, and
VkPipelineViewportSwizzleStateCreateInfoNV::pViewportSwizzles
values used to create the currently active pipeline.
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.
28.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
mesh,
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 a shader using MeshNV Execution Model is active, the provoking
vertex is determined by the primitive
topology defined by the OutputPoints,
OutputLinesNV, or OutputTrianglesNV execution mode.
If a shader using MeshEXT Execution Model is active, the provoking
vertex is determined by the primitive
topology defined by the OutputPoints,
OutputLinesEXT, or OutputTrianglesEXT execution mode.
If geometry shading is active, the provoking vertex is
determined by the primitive topology
defined by the OutputPoints,
OutputLineStrip, or OutputTriangleStrip 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
provokingVertexModeis a VkProvokingVertexModeEXT value selecting the provoking vertex mode.
If this structure 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.
To dynamically set the
provokingVertexMode state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_provoking_vertex, VK_EXT_provoking_vertex with VK_EXT_shader_object
void vkCmdSetProvokingVertexModeEXT(
VkCommandBuffer commandBuffer,
VkProvokingVertexModeEXT provokingVertexMode);
-
commandBufferis the command buffer into which the command will be recorded. -
provokingVertexModespecifies theprovokingVertexModestate.
This command sets the provokingVertexMode state for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::provokingVertexMode
value used to create the currently active pipeline.
28.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 application-defined
half-spaces.
The cull volume is the intersection of up to
VkPhysicalDeviceLimits::maxCullDistances application-defined
half-spaces (if no application-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 application-defined
half-spaces with the view volume (if no application-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 application-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.
To dynamically set enable or disable depth clamping, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetDepthClampEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 depthClampEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
depthClampEnablespecifies whether depth clamping is enabled.
This command sets whether depth clamping is enabled or disabled for
subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationStateCreateInfo::depthClampEnable value
used to create the currently active pipeline.
If the depth clamping state is changed dynamically, and the pipeline was not
created with VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT enabled, then
depth clipping is enabled when depth clamping is disabled and vice versa.
To dynamically set enable or disable depth clipping, call:
// Provided by VK_EXT_depth_clip_enable with VK_EXT_extended_dynamic_state3, VK_EXT_depth_clip_enable with VK_EXT_shader_object
void vkCmdSetDepthClipEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 depthClipEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
depthClipEnablespecifies whether depth clipping is enabled.
This command sets whether depth clipping is enabled or disabled for
subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationDepthClipStateCreateInfoEXT::depthClipEnable
value used to create the currently active pipeline, or by the inverse of
VkPipelineRasterizationStateCreateInfo::depthClampEnable if
VkPipelineRasterizationDepthClipStateCreateInfoEXT is not specified.
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 application-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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
negativeOneToOnesets the zm in the view volume to -wc
To dynamically set negativeOneToOne,
call:
// Provided by VK_EXT_depth_clip_control with VK_EXT_extended_dynamic_state3, VK_EXT_depth_clip_control with VK_EXT_shader_object
void vkCmdSetDepthClipNegativeOneToOneEXT(
VkCommandBuffer commandBuffer,
VkBool32 negativeOneToOne);
-
commandBufferis the command buffer into which the command will be recorded. -
negativeOneToOnespecifies thenegativeOneToOnestate.
This command sets the negativeOneToOne state for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportDepthClipControlCreateInfoEXT::negativeOneToOne
value used to create the currently active pipeline.
28.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.
28.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 a VkStructureType value identifying 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 of VkViewportWScalingNV structures 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
viewportWScalingEnable state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_clip_space_w_scaling, VK_EXT_shader_object with VK_NV_clip_space_w_scaling
void vkCmdSetViewportWScalingEnableNV(
VkCommandBuffer commandBuffer,
VkBool32 viewportWScalingEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
viewportWScalingEnablespecifies theviewportWScalingEnablestate.
This command sets the viewportWScalingEnable state for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportWScalingStateCreateInfoNV::viewportWScalingEnable
value used to create the currently active pipeline.
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 drawing using shader objects, or
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.
28.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
28.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.
28.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) and depth 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
VkPhysicalDeviceLineRasterizationProperties::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 a VkStructureType value identifying 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, VK_EXT_shader_object
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 drawing using shader objects, or
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, VK_EXT_shader_object
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
subsequent drawing commands
when drawing using shader objects, or
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 drawing using shader objects, or
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.
29. 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 a VkStructureType value identifying 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 frustum 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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. This value is ignored for the purposes of setting the number of samples used in rasterization if the pipeline is created with theVK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXTdynamic state set, but ifVK_DYNAMIC_STATE_SAMPLE_MASK_EXTdynamic state is not set, it is still used to define the size of thepSampleMaskarray as described below. -
sampleShadingEnablecan be used to enable Sample Shading. -
minSampleShadingspecifies a minimum fraction of sample shading ifsampleShadingEnableisVK_TRUE. -
pSampleMaskis a pointer to an array of VkSampleMask values 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.
29.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, VK_EXT_shader_object
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 drawing using shader objects, or
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.
29.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 a VkStructureType value identifying 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.
To dynamically set the
rasterizationStream state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_transform_feedback, VK_EXT_shader_object with VK_EXT_transform_feedback
void vkCmdSetRasterizationStreamEXT(
VkCommandBuffer commandBuffer,
uint32_t rasterizationStream);
-
commandBufferis the command buffer into which the command will be recorded. -
rasterizationStreamspecifies therasterizationStreamstate.
This command sets the rasterizationStream state for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationStateStreamCreateInfoEXT::rasterizationStream
value used to create the currently active pipeline.
29.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 a VkStructureType value identifying 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.
29.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).
To dynamically set the
rasterizationSamples, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetRasterizationSamplesEXT(
VkCommandBuffer commandBuffer,
VkSampleCountFlagBits rasterizationSamples);
-
commandBufferis the command buffer into which the command will be recorded. -
rasterizationSamplesspecifiesrasterizationSamples.
This command sets the rasterizationSamples for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineMultisampleStateCreateInfo::rasterizationSamples value
used to create the currently active pipeline.
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 tables below illustrate 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.
29.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 a VkStructureType value identifying 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 a VkStructureType value identifying 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
sampleLocationsEnable state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_sample_locations, VK_EXT_sample_locations with VK_EXT_shader_object
void vkCmdSetSampleLocationsEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 sampleLocationsEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
sampleLocationsEnablespecifies thesampleLocationsEnablestate.
This command sets the sampleLocationsEnable state for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable
value used to create the currently active pipeline.
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 drawing using shader objects, or
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.
29.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 application 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 a VkStructureType value identifying 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.
29.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 a VkStructureType value identifying 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 drawing using shader objects, or
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.
29.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.
If the last pre-rasterization
shader stage is using the MeshEXT Execution Model, the rate
associated with a given primitive is sourced from the value written to the
per-primitive PrimitiveShadingRateKHR.
Otherwise the
rate associated with a given primitive is sourced from the value written to
PrimitiveShadingRateKHR by that primitive’s
provoking vertex.
29.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 using layer =
ViewIndex.
If multiview is disabled, and both the
shading rate attachment and the framebuffer have multiple layers, the
shading rate attachment texel is selected using layer =
Layer.
Otherwise, layer = 0.
The texel is read from the fragment shading rate attachment image as a texture input operation without a sampler, using integer coordinates i = x', j = y', k = 0, l = layer, and s = 0. The fragment size is encoded into the first component of the result of that operation as follows:
-
sizew = 2((texel/4)&3)
-
sizeh = 2(texel&3)
where texel is the value in the first component of the returned value, 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.
29.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' is set to {1,1} by the implementation:
-
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. -
The fragment shader declares any of the
TileImageColorReadAccessEXT,TileImageDepthReadAccessEXT, orTileImageStencilReadAccessEXTcapabilities.
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 should clamp the inputs to the combiner operations
Axy and Bxy, and must
do so if
VkPhysicalDeviceMaintenance6Properties::fragmentShadingRateClampCombinerInputs
is VK_TRUE.
All implementations must
clamp the result of the second combiner operation.
A fragment shading rate Rxy representing any of Axy, Bxy or Cxy is clamped as follows. If Rxy is one of the rates returned by vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count and render pass transform used by rasterization, the clamped shading rate Rxy' is Rxy. Otherwise, the clamped shading rate 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 Rx' ≤ Rx and Ry' ≤ Ry.
-
Implementations may also keep rates where Rx' ≤ Ry and Ry' ≤ Rx.
-
-
Keep only rates with the highest area (Rx' × Ry').
-
Keep only rates with the lowest aspect ratio (Rx' + Ry').
-
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.
29.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 a VkStructureType value identifying 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 drawing using shader objects, or
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.
29.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 a VkStructureType value identifying 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 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
shadingRateImageEnable state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_shading_rate_image, VK_EXT_shader_object with VK_NV_shading_rate_image
void vkCmdSetShadingRateImageEnableNV(
VkCommandBuffer commandBuffer,
VkBool32 shadingRateImageEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
shadingRateImageEnablespecifies theshadingRateImageEnablestate.
This command sets the shadingRateImageEnable state for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportShadingRateImageStateCreateInfoNV::shadingRateImageEnable
value used to create the currently active pipeline.
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 drawing using shader objects, or
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 a VkStructureType value identifying 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 drawing using shader objects, or
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.
29.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 VkPipelineMultisampleStateCreateInfo::sampleShadingEnable is
VK_TRUE, sample shading is enabled.
If a fragment shader entry point statically uses an
input variable decorated with a BuiltIn of SampleId or
SamplePosition, sample shading is enabled and a value of 1.0 is used
instead of minSampleShading.
If a fragment shader entry point statically uses an
input variable decorated with Sample, sample shading may be enabled
and a value of 1.0 will be used instead of minSampleShading if it
is.
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.
|
Note
|
If a shader decorates an input variable with |
If there are fewer fragment 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, and each invocation that is not a helper invocation covers at least one sample.
29.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.
29.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.
If the maintenance5 feature is enabled, and
a value is not written to PointSize, the point size takes a default
value of 1.0.
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.
29.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.
29.11. Line Segments
Line segment rasterization options are controlled by the VkPipelineRasterizationLineStateCreateInfo structure.
The VkPipelineRasterizationLineStateCreateInfo structure is defined
as:
// Provided by VK_VERSION_1_4
typedef struct VkPipelineRasterizationLineStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkLineRasterizationMode lineRasterizationMode;
VkBool32 stippledLineEnable;
uint32_t lineStippleFactor;
uint16_t lineStipplePattern;
} VkPipelineRasterizationLineStateCreateInfo;
or the equivalent
// Provided by VK_KHR_line_rasterization
typedef VkPipelineRasterizationLineStateCreateInfo VkPipelineRasterizationLineStateCreateInfoKHR;
or the equivalent
// Provided by VK_EXT_line_rasterization
typedef VkPipelineRasterizationLineStateCreateInfo VkPipelineRasterizationLineStateCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
lineRasterizationModeis a VkLineRasterizationMode 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
VkPipelineRasterizationLineStateCreateInfo::lineRasterizationMode,
specifying the line rasterization mode, are:
// Provided by VK_VERSION_1_4
typedef enum VkLineRasterizationMode {
VK_LINE_RASTERIZATION_MODE_DEFAULT = 0,
VK_LINE_RASTERIZATION_MODE_RECTANGULAR = 1,
VK_LINE_RASTERIZATION_MODE_BRESENHAM = 2,
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH = 3,
// Provided by VK_EXT_line_rasterization
VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT = VK_LINE_RASTERIZATION_MODE_DEFAULT,
// Provided by VK_EXT_line_rasterization
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT = VK_LINE_RASTERIZATION_MODE_RECTANGULAR,
// Provided by VK_EXT_line_rasterization
VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT = VK_LINE_RASTERIZATION_MODE_BRESENHAM,
// Provided by VK_EXT_line_rasterization
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT = VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH,
// Provided by VK_KHR_line_rasterization
VK_LINE_RASTERIZATION_MODE_DEFAULT_KHR = VK_LINE_RASTERIZATION_MODE_DEFAULT,
// Provided by VK_KHR_line_rasterization
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR = VK_LINE_RASTERIZATION_MODE_RECTANGULAR,
// Provided by VK_KHR_line_rasterization
VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR = VK_LINE_RASTERIZATION_MODE_BRESENHAM,
// Provided by VK_KHR_line_rasterization
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR = VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH,
} VkLineRasterizationMode;
or the equivalent
// Provided by VK_KHR_line_rasterization
typedef VkLineRasterizationMode VkLineRasterizationModeKHR;
or the equivalent
// Provided by VK_EXT_line_rasterization
typedef VkLineRasterizationMode VkLineRasterizationModeEXT;
-
VK_LINE_RASTERIZATION_MODE_DEFAULTis equivalent toVK_LINE_RASTERIZATION_MODE_RECTANGULARif 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_RECTANGULARspecifies lines drawn as if they were rectangles extruded from the line -
VK_LINE_RASTERIZATION_MODE_BRESENHAMspecifies lines drawn by determining which pixel diamonds the line intersects and exits, as defined in Bresenham Line Segment Rasterization. -
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTHspecifies lines drawn if they were rectangles extruded from the line, with alpha falloff, as defined in Smooth Lines.
To dynamically set the
lineRasterizationMode state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization, VK_EXT_line_rasterization with VK_EXT_shader_object
void vkCmdSetLineRasterizationModeEXT(
VkCommandBuffer commandBuffer,
VkLineRasterizationModeEXT lineRasterizationMode);
-
commandBufferis the command buffer into which the command will be recorded. -
lineRasterizationModespecifies thelineRasterizationModestate.
This command sets the lineRasterizationMode state for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationLineStateCreateInfo::lineRasterizationMode
value used to create the currently active pipeline.
To dynamically set the stippledLineEnable
state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization, VK_EXT_line_rasterization with VK_EXT_shader_object
void vkCmdSetLineStippleEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 stippledLineEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
stippledLineEnablespecifies thestippledLineEnablestate.
This command sets the stippledLineEnable state for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationLineStateCreateInfo::stippledLineEnable
value used to create the currently active pipeline.
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 drawing using shader objects, or
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.
29.11.1. Basic Line Segment Rasterization
If the lineRasterizationMode member of
VkPipelineRasterizationLineStateCreateInfo is
VK_LINE_RASTERIZATION_MODE_RECTANGULAR, 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.
By default, when
strictLines is VK_FALSE,
or the relaxedLineRasterization
feature is enabled,
and when the lineRasterizationMode is
VK_LINE_RASTERIZATION_MODE_DEFAULT,
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.
When
strictLines is VK_FALSE
or when the relaxedLineRasterization feature is enabled,
and lineRasterizationMode is
VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT
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.
If
VkPhysicalDeviceMaintenance5Properties::nonStrictSinglePixelWideLinesUseParallelogram
is VK_TRUE,
the lineRasterizationMode is
VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT,
and strictLines is VK_FALSE, non-strict lines of width 1.0 are
rasterized as parallelograms, otherwise they are rasterized using
Bresenham’s algorithm.
If
VkPhysicalDeviceMaintenance5Properties::nonStrictWideLinesUseParallelogram
is VK_TRUE,
the lineRasterizationMode is
VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT,
and strictLines is VK_FALSE, non-strict lines of width greater
than 1.0 are rasterized as parallelograms, otherwise they are rasterized
using Bresenham’s algorithm.
29.11.2. Bresenham Line Segment Rasterization
If lineRasterizationMode is
VK_LINE_RASTERIZATION_MODE_BRESENHAM, 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.
If the relaxedLineRasterization
feature is enabled,
and lineRasterizationMode is
VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT
implementations must follow these rasterization rules for non-antialised
lines of width 1.0.
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 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). |
29.11.3. Line Stipple
If the stippledLineEnable member of
VkPipelineRasterizationLineStateCreateInfo 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 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 and
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH 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_VERSION_1_4
void vkCmdSetLineStipple(
VkCommandBuffer commandBuffer,
uint32_t lineStippleFactor,
uint16_t lineStipplePattern);
or the equivalent command
// Provided by VK_KHR_line_rasterization
void vkCmdSetLineStippleKHR(
VkCommandBuffer commandBuffer,
uint32_t lineStippleFactor,
uint16_t lineStipplePattern);
or the equivalent command
// 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 drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_LINE_STIPPLE set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationLineStateCreateInfo::lineStippleFactor
and
VkPipelineRasterizationLineStateCreateInfo::lineStipplePattern
values used to create the currently active pipeline.
29.11.4. Smooth Lines
If the lineRasterizationMode member of
VkPipelineRasterizationLineStateCreateInfo is
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH, then lines are
considered to be rectangles using the same geometry as for
VK_LINE_RASTERIZATION_MODE_RECTANGULAR 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. |
29.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.
29.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, VK_EXT_shader_object
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 drawing using shader objects, or
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, VK_EXT_shader_object
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 drawing using shader objects, or
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). |
29.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.
If VkPhysicalDeviceMaintenance5Properties::polygonModePointSize
is VK_TRUE, the point size of the final rasterization of polygons is
taken from PointSize when polygon mode is
VK_POLYGON_MODE_POINT.
Otherwise, if
VkPhysicalDeviceMaintenance5Properties::polygonModePointSize is
VK_FALSE, the point size of the final rasterization of polygons is 1.0
when polygon mode is VK_POLYGON_MODE_POINT.
To dynamically set the polygon mode, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetPolygonModeEXT(
VkCommandBuffer commandBuffer,
VkPolygonMode polygonMode);
-
commandBufferis the command buffer into which the command will be recorded. -
polygonModespecifies polygon mode.
This command sets the polygon mode for subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_POLYGON_MODE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationStateCreateInfo::polygonMode value used
to create the currently active pipeline.
29.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, VK_EXT_shader_object
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 drawing using shader objects, or
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 parameter 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
and vkCmdSetDepthBias2EXT
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
In a pipeline with a depth bias representation of
VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXT, r, for the given
primitive is defined as
-
r = 1
Otherwise
r is the minimum resolvable difference that depends on the depth
attachment representation.
If VkDepthBiasRepresentationInfoEXT::depthBiasExact is
VK_FALSE it
is the smallest difference in a sample’s depth zf 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,
or in a pipeline with a depth bias representation of
VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXT,
r is constant throughout the range of the entire depth attachment.
If VkDepthBiasRepresentationInfoEXT::depthBiasExact is
VK_TRUE, then its value must be
-
r = 2-n
Otherwise its value is implementation-dependent but must be at most
-
r = 2 × 2-n
where n is the number of bits used for the depth aspect when using a fixed-point attachment, or the number of mantissa bits plus one when using a floating-point attachment.
Otherwise 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 drawing using shader objects, or
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.
Calling this function is equivalent to calling vkCmdSetDepthBias2EXT
without a VkDepthBiasRepresentationInfoEXT in the pNext chain of
VkDepthBiasInfoEXT.
The VkDepthBiasRepresentationInfoEXT structure is defined as:
// Provided by VK_EXT_depth_bias_control
typedef struct VkDepthBiasRepresentationInfoEXT {
VkStructureType sType;
const void* pNext;
VkDepthBiasRepresentationEXT depthBiasRepresentation;
VkBool32 depthBiasExact;
} VkDepthBiasRepresentationInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
depthBiasRepresentationis a VkDepthBiasRepresentationEXT value specifying the depth bias representation. -
depthBiasExactspecifies that the implementation is not allowed to scale the depth bias value to ensure a minimum resolvable distance.
Possible values of
VkDepthBiasRepresentationInfoEXT::depthBiasRepresentation,
specifying the depth bias representation are:
// Provided by VK_EXT_depth_bias_control
typedef enum VkDepthBiasRepresentationEXT {
VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORMAT_EXT = 0,
VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXT = 1,
VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXT = 2,
} VkDepthBiasRepresentationEXT;
-
VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORMAT_EXTspecifies that the depth bias representation is a factor of the format’s r as described in Depth Bias Computation. -
VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXTspecifies that the depth bias representation is a factor of a constant r defined by the bit-size or mantissa of the format as described in Depth Bias Computation. -
VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXTspecifies that the depth bias representation is a factor of constant r equal to 1.
The VkDepthBiasInfoEXT structure is defined as:
// Provided by VK_EXT_depth_bias_control
typedef struct VkDepthBiasInfoEXT {
VkStructureType sType;
const void* pNext;
float depthBiasConstantFactor;
float depthBiasClamp;
float depthBiasSlopeFactor;
} VkDepthBiasInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
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.
If pNext does not contain a VkDepthBiasRepresentationInfoEXT
structure, then this command is equivalent to including a
VkDepthBiasRepresentationInfoEXT with depthBiasExact set to
VK_FALSE and depthBiasRepresentation set to
VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORMAT_EXT.
To dynamically set the depth bias parameters, call:
// Provided by VK_EXT_depth_bias_control
void vkCmdSetDepthBias2EXT(
VkCommandBuffer commandBuffer,
const VkDepthBiasInfoEXT* pDepthBiasInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pDepthBiasInfois a pointer to a VkDepthBiasInfoEXT structure specifying depth bias parameters.
This command is functionally identical to vkCmdSetDepthBias, but
includes extensible sub-structures that include sType and pNext
parameters, allowing them to be more easily extended.
29.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 a VkStructureType value identifying 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 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.
To dynamically set the
conservativeRasterizationMode, call:
// Provided by VK_EXT_conservative_rasterization with VK_EXT_extended_dynamic_state3, VK_EXT_conservative_rasterization with VK_EXT_shader_object
void vkCmdSetConservativeRasterizationModeEXT(
VkCommandBuffer commandBuffer,
VkConservativeRasterizationModeEXT conservativeRasterizationMode);
-
commandBufferis the command buffer into which the command will be recorded. -
conservativeRasterizationModespecifies theconservativeRasterizationModestate.
This command sets the conservativeRasterizationMode state for
subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationConservativeStateCreateInfoEXT::conservativeRasterizationMode
value used to create the currently active pipeline.
To dynamically set the
extraPrimitiveOverestimationSize, call:
// Provided by VK_EXT_conservative_rasterization with VK_EXT_extended_dynamic_state3, VK_EXT_conservative_rasterization with VK_EXT_shader_object
void vkCmdSetExtraPrimitiveOverestimationSizeEXT(
VkCommandBuffer commandBuffer,
float extraPrimitiveOverestimationSize);
-
commandBufferis the command buffer into which the command will be recorded. -
extraPrimitiveOverestimationSizespecifies theextraPrimitiveOverestimationSize.
This command sets the extraPrimitiveOverestimationSize for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRasterizationConservativeStateCreateInfoEXT::extraPrimitiveOverestimationSize
value used to create the currently active pipeline.
When overestimate conservative rasterization is enabled, rather than evaluating coverage at individual sample locations, a determination is made 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 may 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 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.
30. 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.
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 there is a fragment shader and it declares the
PostDepthCoverage execution mode, the sample mask
test is instead performed after the depth test.
If
VkPhysicalDeviceMaintenance5Properties::earlyFragmentMultisampleCoverageAfterSampleCounting
is VK_TRUE and there is a fragment shader which
declares the EarlyFragmentTests execution mode, fragment shading and multisample coverage operations
must be performed after sample counting.
Otherwise, if
VkPhysicalDeviceMaintenance5Properties::earlyFragmentMultisampleCoverageAfterSampleCounting
is VK_FALSE and there is a fragment shader which
declares the EarlyFragmentTests execution mode, fragment shading and multisample coverage operations
should instead be performed after sample counting,
but may be performed before sample counting.
If
VkPhysicalDeviceMaintenance5Properties::earlyFragmentSampleMaskTestBeforeSampleCounting
is VK_TRUE and there is a fragment shader which
declares the EarlyFragmentTests execution mode sample mask test operations must follow the order of fragment operations
from above.
Otherwise, if
VkPhysicalDeviceMaintenance5Properties::earlyFragmentSampleMaskTestBeforeSampleCounting
is VK_FALSE and there is a fragment shader which
declares the EarlyFragmentTests execution mode, sample mask test operations should follow the order of fragment
operations from above but may instead be performed after
sample counting.
If there is a fragment shader which declares the
EarlyAndLateFragmentTestsAMD execution mode, and it does not declare
the DepthReplacing
or StencilRefReplacingEXT
execution mode, fragment shading and multisample coverage operations are instead be performed after
sample counting.
For a pipeline with the following properties:
-
a fragment shader is specified
-
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
StencilRefLessFrontAMDexecution mode and the pipeline uses a VkPipelineDepthStencilStateCreateInfo::front.compareOpofVK_COMPARE_OP_GREATERorVK_COMPARE_OP_GREATER_OR_EQUAL; or -
the fragment shader specifies the
StencilRefGreaterFrontAMDexecution 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
StencilRefLessBackAMDexecution mode and the pipeline uses a VkPipelineDepthStencilStateCreateInfo::back.compareOpofVK_COMPARE_OP_GREATERorVK_COMPARE_OP_GREATER_OR_EQUAL; or -
the fragment shader specifies the
StencilRefGreaterBackAMDexecution 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:
-
a fragment shader is specified
-
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
DepthLessexecution mode and the pipeline uses a VkPipelineDepthStencilStateCreateInfo::depthCompareOpofVK_COMPARE_OP_GREATERorVK_COMPARE_OP_GREATER_OR_EQUAL; or -
the fragment shader specifies the
DepthGreaterexecution 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.
30.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 a VkStructureType value identifying 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.
If the VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT dynamic state is
not enabled for the pipeline the presence of this structure in the
VkGraphicsPipelineCreateInfo chain, and a discardRectangleCount
greater than zero, implicitly enables discard rectangles in the pipeline,
otherwise discard rectangles must enabled or disabled by
vkCmdSetDiscardRectangleEnableEXT.
If the VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT dynamic state is
enabled for the pipeline, the discardRectangleMode member is ignored,
and the discard rectangle mode must be set by
vkCmdSetDiscardRectangleModeEXT.
When this structure is included in the pNext chain of
VkGraphicsPipelineCreateInfo, it defines parameters of the discard
rectangle test.
If the VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is not
enabled, and this structure is not included in the pNext chain, it is
equivalent to specifying this structure with a discardRectangleCount
of 0.
If all VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT,
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT, and
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT dynamic states are
enabled, the application can omit this structure from the pNext chain
of VkGraphicsPipelineCreateInfo and still use discard rectangles by
setting all state dynamically.
In this case vkCmdSetDiscardRectangleEXT must be called to set the
discard rectangle for all indices [0, maxDiscardRectangles)
before drawing with discard rectangles enabled.
Individual discard rectangles can be made ineffective by setting their
VkRect2D::extent.width and VkRect2D::extent.height
to zero.
// 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 drawing using shader objects, or
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.
To dynamically set whether discard rectangles are enabled, call:
// Provided by VK_EXT_discard_rectangles
void vkCmdSetDiscardRectangleEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 discardRectangleEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
discardRectangleEnablespecifies whether discard rectangles are enabled or not.
This command sets the discard rectangle enable for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is implied by the
VkPipelineDiscardRectangleStateCreateInfoEXT::discardRectangleCount
value used to create the currently active pipeline, where a non-zero
discardRectangleCount implicitly enables discard rectangles, otherwise
they are disabled.
To dynamically set the discard rectangle mode, call:
// Provided by VK_EXT_discard_rectangles
void vkCmdSetDiscardRectangleModeEXT(
VkCommandBuffer commandBuffer,
VkDiscardRectangleModeEXT discardRectangleMode);
-
commandBufferis the command buffer into which the command will be recorded. -
discardRectangleModespecifies the discard rectangle mode for all discard rectangles, either inclusive or exclusive.
This command sets the discard rectangle mode for subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineDiscardRectangleStateCreateInfoEXT::discardRectangleMode
value used to create the currently active pipeline.
30.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 drawing using shader objects, or
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.
30.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 a VkStructureType value identifying 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 an 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 drawing using shader objects, or
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.
To dynamically set whether an exclusive scissor is enabled or not, call:
// Provided by VK_NV_scissor_exclusive
void vkCmdSetExclusiveScissorEnableNV(
VkCommandBuffer commandBuffer,
uint32_t firstExclusiveScissor,
uint32_t exclusiveScissorCount,
const VkBool32* pExclusiveScissorEnables);
-
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. -
pExclusiveScissorEnablesis a pointer to an array of VkBool32 values defining whether the exclusive scissor is enabled.
The exclusive scissor enables taken from element i of
pExclusiveScissorEnables replace the current state for the scissor
index firstExclusiveScissor + i, for i in [0,
exclusiveScissorCount).
This command sets the exclusive scissor enable for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is implied by the
VkPipelineViewportExclusiveScissorStateCreateInfoNV::exclusiveScissorCount
value used to create the currently active pipeline, where all
exclusiveScissorCount exclusive scissors are implicitly enabled and
the remainder up to VkPhysicalDeviceLimits::maxViewports are
implicitly disabled.
30.4. Sample Mask Test
The sample mask test compares the coverage mask for a fragment with the sample mask defined by
VkPipelineMultisampleStateCreateInfo::pSampleMask.
To dynamically set the sample mask, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetSampleMaskEXT(
VkCommandBuffer commandBuffer,
VkSampleCountFlagBits samples,
const VkSampleMask* pSampleMask);
-
commandBufferis the command buffer into which the command will be recorded. -
samplesspecifies the number of sample bits in thepSampleMask. -
pSampleMaskis a pointer to an array of VkSampleMask values, where the array size is based on thesamplesparameter.
This command sets the sample mask for subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_SAMPLE_MASK_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineMultisampleStateCreateInfo::pSampleMask value used to
create the currently active pipeline.
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.
30.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.
-
If a fragment shader statically computes the same values for different framebuffer locations, and does not write to any storage resources, multiple fragments may be shaded by one fragment shader invocation. This may affect
VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BITresults, but must otherwise not be visible behavior to applications.
-
-
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.
-
If no fragment shader is included in the pipeline, no fragment shader is executed, and undefined values may be written to all color attachment outputs during this fragment operation.
|
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
|
30.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.
30.5.2. Shader Termination and Demotion
If a fragment shader is terminated early or
demoted to a helper invocation by using
OpKill, OpTerminateInvocation, or OpDemoteToHelperInvocation,
samples covered by that shader invocation have their coverage mask bits set
to 0.
30.5.3. Fragment Shader Tile Image Reads
If the VK_EXT_shader_tile_image extension is enabled,
implementations divide the framebuffer into a grid of tiles.
A tile image is a view of a framebuffer attachment
tile for fragments with locations within the tile.
Within a render pass instance initiated by vkCmdBeginRenderingKHR, fragment shader invocations can read the framebuffer color, depth, and stencil values at the fragment location via tile images.
|
Note
|
Even though fragment shader invocation can only read from the corresponding fragment location, the abstraction of a tile image is introduced for the following reasons:
|
Enabling shaderTileImageColorReadAccess, shaderTileImageDepthReadAccess, shaderTileImageStencilReadAccess enables fragment shader invocations to read from color, depth, and stencil, respectively.
Color values are read from tile image variables with
OpColorAttachmentReadEXT.
Tile image variables are linked to specific color attachments using
Location decoration.
See Fragment Tile Image Interface for more
details.
Depth values are read with OpDepthAttachmentReadEXT.
Stencil values are read with OpStencilAttachmentReadEXT.
The sample to read is specified by a
sample index value specified as
the Sample operand to OpColorAttachmentReadEXT,
OpDepthAttachmentReadEXT, or OpStencilAttachmentReadEXT.
If sample shading is disabled, a fragment
invocation can read from all sample locations associated with the fragment
regardless of the fragment’s coverage.
This functionality is supported for
VkPipelineMultisampleStateCreateInfo::rasterizationSamples > 1
when
VkPhysicalDeviceShaderTileImagePropertiesEXT::shaderTileImageReadSampleFromPixelRateInvocation
is VK_TRUE.
If sample shading is enabled, and
minSampleShading is 1.0, a fragment invocation must only read from
the coverage index sample.
Tile image access must not be used if the value of minSampleShading
is not 1.0.
If the fragment shader declares the
EarlyFragmentTests execution mode, depth reads are allowed only if
depth writes are disabled and stencil reads are allowed only if stencil
writes are disabled.
If
VkPhysicalDeviceShaderTileImagePropertiesEXT::shaderTileImageReadFromHelperInvocation
is VK_FALSE, values read from helper invocations are undefined
otherwise the values read are subject to the coherency guarantees described
below.
OpDepthAttachmentReadEXT returns an undefined value if no depth
attachment is present.
OpStencilAttachmentReadEXT returns an undefined value if no stencil
attachment is present.
Tile image reads from color, depth and stencil attachments are said to be coherent when the accesses happen in raster order and without data race with respect to accesses to the attachments from framebuffer-space pipeline stages. The samples which qualify for coherent access and the enabling conditions are described below.
-
Let Rc be the set of components being read from an attachment A in a draw call
-
Let Wc be the set of components being written to A by the draw call
The samples which qualify for coherent tile image reads from an attachment A are:
-
All samples in a pixel when Rc is disjoint with Wc.
-
The samples with coverage in a fragment when Rc is not disjoint with Wc. The samples with coverage are determined by the coverage mask for the fragment as calculated by fragment operations that executed prior to fragment shading, including early fragment tests if enabled for the draw call.
A fragment shader can declare NonCoherentColorAttachmentReadEXT,
NonCoherentDepthAttachmentReadEXT, or
NonCoherentStencilAttachmentReadEXT execution modes to enable
non-coherent tile image reads which require an explicit
vkCmdPipelineBarrier2 call for the writes to an attachment to be made
visible via tile image reads.
When
VkPhysicalDeviceShaderTileImagePropertiesEXT::shaderTileImageCoherentReadAccelerated
is VK_TRUE, the implementation prefers that coherent tile image reads
are used, otherwise the implementation prefers that non-coherent tile image
reads are used.
|
Note
|
In practice, the most common tile image reads usage patterns fall under one of the following:
All of the above use cases are supported by coherent tile image reads, but only the latter three are supported when non-coherent reads are used as there is no mechanism to synchronize non-coherent reads with writes within a draw call. |
30.5.4. 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.
30.5.5. 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.
30.5.6. 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.
30.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, and the
alphaToCoverageEnable and alphaToOneEnable members of the
VkPipelineMultisampleStateCreateInfo structure.
To dynamically set the
alphaToCoverageEnable state, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetAlphaToCoverageEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 alphaToCoverageEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
alphaToCoverageEnablespecifies thealphaToCoverageEnablestate.
This command sets the alphaToCoverageEnable state for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineMultisampleStateCreateInfo::alphaToCoverageEnable
value used to create the currently active pipeline.
To dynamically set the alphaToOneEnable
state, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetAlphaToOneEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 alphaToOneEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
alphaToOneEnablespecifies thealphaToOneEnablestate.
This command sets the alphaToOneEnable state for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineMultisampleStateCreateInfo::alphaToOneEnable value
used to create the currently active pipeline.
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 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.
30.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 a VkStructureType value identifying 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. -
frontandbackare VkStencilOpState values controlling the corresponding 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.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineDepthStencilStateCreateFlags;
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_EXT_rasterization_order_attachment_access
typedef enum VkPipelineDepthStencilStateCreateFlagBits {
// Provided by VK_EXT_rasterization_order_attachment_access
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT = 0x00000001,
// Provided by VK_EXT_rasterization_order_attachment_access
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT = 0x00000002,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM = VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM = VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT,
} VkPipelineDepthStencilStateCreateFlagBits;
-
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXTspecifies that access to the depth aspects of depth/stencil and input attachments will have implicit framebuffer-local memory dependencies. -
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXTspecifies that access to the stencil aspects of depth/stencil and input attachments will have implicit framebuffer-local memory dependencies.
When
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT
is included in a pipeline, it forms a framebuffer-local memory dependency
for each fragment generated by draw commands for that pipeline with the
following scopes:
-
The first synchronization scope includes
VK_PIPELINE_STAGE_FRAGMENT_SHADER_BITandVK_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_BITstage 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.
When
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT
is included in a pipeline, it forms a framebuffer-local memory dependency
for each fragment generated by draw commands for that pipeline with the
following scopes:
-
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.
30.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, VK_EXT_shader_object
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 drawing using shader objects, or
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 drawing using shader objects, or
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.
30.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
writeMask in VkPipelineDepthStencilStateCreateInfo::front
and VkPipelineDepthStencilStateCreateInfo::back 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, VK_EXT_shader_object
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 drawing using shader objects, or
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, VK_EXT_shader_object
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
when drawing using shader objects, or
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 drawing using shader objects, or
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 is a deprecated alias
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 drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_STENCIL_WRITE_MASK set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the writeMask value used to
create the currently active pipeline, for both
VkPipelineDepthStencilStateCreateInfo::front and
VkPipelineDepthStencilStateCreateInfo::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 drawing using shader objects, or
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.
30.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.
30.10.1. Depth Clamping and Range Adjustment
If VkPipelineRasterizationStateCreateInfo::depthClampEnable is
enabled, zf is clamped to [zmin, zmax], where zmin
= min(n,f), zmax = max(n,f), and n and f are the
minDepth and maxDepth depth range values of the viewport used by
this fragment, respectively.
If the depthClampControl feature is
enabled and
VkPipelineViewportDepthClampControlCreateInfoEXT::depthClampMode
is VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT, then zmin and
zmax are equal to the minDepthClamp and maxDepthClamp
values of the VkDepthClampRangeEXT structure pointed to by
pDepthClampRange.
If
VkPhysicalDeviceDepthClampZeroOneFeaturesKHR::depthClampZeroOne
is enabled:
-
If the depth attachment has a floating-point format and VK_EXT_depth_range_unrestricted is enabled then zf is unchanged.
-
Otherwise, zf is clamped to the range [0, 1].
Otherwise:
-
If zf is not in the range [zmin, zmax], then zf is undefined following this step.
-
If the depth attachment has a fixed-point format and zf is not in the range [0, 1], then zf is undefined following this step.
The VkPipelineViewportDepthClampControlCreateInfoEXT structure is
defined as:
// Provided by VK_EXT_depth_clamp_control
typedef struct VkPipelineViewportDepthClampControlCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkDepthClampModeEXT depthClampMode;
const VkDepthClampRangeEXT* pDepthClampRange;
} VkPipelineViewportDepthClampControlCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
depthClampModedetermines how the clamp range is determined for each viewport. -
pDepthClampRangesets the depth clamp range for all viewports ifdepthClampModeisVK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT.
This structure extends VkPipelineViewportStateCreateInfo and specifies
the depth clamp range used in the pipeline.
If this structure is not provided in the next chain then
depthClampMode defaults to
VK_DEPTH_CLAMP_MODE_VIEWPORT_RANGE_EXT.
Possible values of
VkPipelineViewportDepthClampControlCreateInfoEXT::depthClampMode,
specifying which range should be used for depth clamping, are:
// Provided by VK_EXT_depth_clamp_control
typedef enum VkDepthClampModeEXT {
VK_DEPTH_CLAMP_MODE_VIEWPORT_RANGE_EXT = 0,
VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT = 1,
} VkDepthClampModeEXT;
-
VK_DEPTH_CLAMP_MODE_VIEWPORT_RANGE_EXTspecifies that the depth clamp range follows the viewport depth range. The depth clamp range of each viewport will implicitly be set to zmin = min(n,f) and zmax = max(n,f), where n and f are theminDepthandmaxDepthdepth range values of the viewport. -
VK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXTspecifies that a single user-defined depth clamp range will be used for all viewports. The user-defined depth clamp range is defined by theminDepthClampandmaxDepthClampmembers of VkDepthClampRangeEXT.
To dynamically set the viewport depth clamp range parameters, call:
// Provided by VK_EXT_depth_clamp_control, VK_EXT_depth_clamp_control with VK_EXT_shader_object
void vkCmdSetDepthClampRangeEXT(
VkCommandBuffer commandBuffer,
VkDepthClampModeEXT depthClampMode,
const VkDepthClampRangeEXT* pDepthClampRange);
-
commandBufferis the command buffer into which the command will be recorded. -
depthClampModedetermines how the clamp range is determined for each viewport. -
pDepthClampRangesets the depth clamp range for all viewports ifdepthClampModeisVK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT.
This command sets the viewport depth clamp range for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineViewportDepthClampControlCreateInfoEXT::depthClampMode
value used to create the currently active pipeline.
Both VkPipelineViewportDepthClampControlCreateInfoEXT and
vkCmdSetDepthClampRangeEXT use VkDepthClampRangeEXT to set the
viewport depth clamp range parameters.
The VkDepthClampRangeEXT structure is defined as:
// Provided by VK_EXT_depth_clamp_control
typedef struct VkDepthClampRangeEXT {
float minDepthClamp;
float maxDepthClamp;
} VkDepthClampRangeEXT;
-
minDepthClampsets zmin in the depth clamp range of the viewport. -
maxDepthClampsets zmax in the depth clamp range of the viewport.
30.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.
30.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, VK_EXT_shader_object
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 drawing using shader objects, or
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, VK_EXT_shader_object
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 drawing using shader objects, or
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, VK_EXT_shader_object
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 drawing using shader objects, or
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.
30.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 a VkStructureType value identifying 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.
To dynamically set the
representativeFragmentTestEnable state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_representative_fragment_test, VK_EXT_shader_object with VK_NV_representative_fragment_test
void vkCmdSetRepresentativeFragmentTestEnableNV(
VkCommandBuffer commandBuffer,
VkBool32 representativeFragmentTestEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
representativeFragmentTestEnablespecifies therepresentativeFragmentTestEnablestate.
This command sets the representativeFragmentTestEnable state for
subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineRepresentativeFragmentTestStateCreateInfoNV::representativeFragmentTestEnable
value used to create the currently active pipeline.
30.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.
30.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 a VkStructureType value identifying 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.
To dynamically set the
coverageToColorEnable state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_fragment_coverage_to_color, VK_EXT_shader_object with VK_NV_fragment_coverage_to_color
void vkCmdSetCoverageToColorEnableNV(
VkCommandBuffer commandBuffer,
VkBool32 coverageToColorEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
coverageToColorEnablespecifies thecoverageToColorEnablestate.
This command sets the coverageToColorEnable state for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineCoverageToColorStateCreateInfoNV::coverageToColorEnable
value used to create the currently active pipeline.
To dynamically set the
coverageToColorLocation state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_fragment_coverage_to_color, VK_EXT_shader_object with VK_NV_fragment_coverage_to_color
void vkCmdSetCoverageToColorLocationNV(
VkCommandBuffer commandBuffer,
uint32_t coverageToColorLocation);
-
commandBufferis the command buffer into which the command will be recorded. -
coverageToColorLocationspecifies thecoverageToColorLocationstate.
This command sets the coverageToColorLocation state for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineCoverageToColorStateCreateInfoNV::coverageToColorLocation
value used to create the currently active pipeline.
30.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.
30.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.
30.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 coverageReductionMode
feature 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 a VkStructureType value identifying 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 dynamically set the
coverageReductionMode state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_coverage_reduction_mode, VK_EXT_shader_object with VK_NV_coverage_reduction_mode
void vkCmdSetCoverageReductionModeNV(
VkCommandBuffer commandBuffer,
VkCoverageReductionModeNV coverageReductionMode);
-
commandBufferis the command buffer into which the command will be recorded. -
coverageReductionModespecifies thecoverageReductionModestate.
This command sets the coverageReductionMode state for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineCoverageReductionStateCreateInfoNV::coverageReductionMode
value used to create the currently active pipeline.
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
application 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 a VkStructureType value identifying 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.
30.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 a VkStructureType value identifying 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.
To dynamically set the
coverageModulationMode state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples, VK_EXT_shader_object with VK_NV_framebuffer_mixed_samples
void vkCmdSetCoverageModulationModeNV(
VkCommandBuffer commandBuffer,
VkCoverageModulationModeNV coverageModulationMode);
-
commandBufferis the command buffer into which the command will be recorded. -
coverageModulationModespecifies thecoverageModulationModestate.
This command sets the coverageModulationMode state for subsequent
drawing commands
when drawing using shader objects, or
the graphics pipeline is created with
VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineCoverageModulationStateCreateInfoNV::coverageModulationMode
value used to create the currently active pipeline.
To dynamically set the
coverageModulationTableEnable state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples, VK_EXT_shader_object with VK_NV_framebuffer_mixed_samples
void vkCmdSetCoverageModulationTableEnableNV(
VkCommandBuffer commandBuffer,
VkBool32 coverageModulationTableEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
coverageModulationTableEnablespecifies thecoverageModulationTableEnablestate.
This command sets the coverageModulationTableEnable state for
subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineCoverageModulationStateCreateInfoNV::coverageModulationTableEnable
value used to create the currently active pipeline.
To dynamically set the
pCoverageModulationTable state, call:
// Provided by VK_EXT_extended_dynamic_state3 with VK_NV_framebuffer_mixed_samples, VK_EXT_shader_object with VK_NV_framebuffer_mixed_samples
void vkCmdSetCoverageModulationTableNV(
VkCommandBuffer commandBuffer,
uint32_t coverageModulationTableCount,
const float* pCoverageModulationTable);
-
commandBufferis the command buffer into which the command will be recorded. -
coverageModulationTableCountspecifies the number of elements inpCoverageModulationTable. -
pCoverageModulationTablespecifies the table of modulation factors containing a value for each number of covered samples.
This command sets the table of modulation factors for subsequent drawing
commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineCoverageModulationStateCreateInfoNV::coverageModulationTableCount,
and
VkPipelineCoverageModulationStateCreateInfoNV::pCoverageModulationTable
values used to create the currently active pipeline.
31. The Framebuffer
31.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 a VkStructureType value identifying 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. It is ignored if the pipeline is created withVK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT,VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, andVK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXTdynamic states set, and eitherVK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXTset or the advancedBlendCoherentOperations feature is not enabled. -
pAttachmentsis a pointer to an array of VkPipelineColorBlendAttachmentState structures defining blend state for each color attachment. It is ignored if the pipeline is created withVK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT,VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, andVK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXTdynamic states set, and eitherVK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXTset or the advancedBlendCoherentOperations feature is not enabled. -
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_EXT_rasterization_order_attachment_access
typedef enum VkPipelineColorBlendStateCreateFlagBits {
// Provided by VK_EXT_rasterization_order_attachment_access
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT = 0x00000001,
// Provided by VK_ARM_rasterization_order_attachment_access
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM = VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT,
} VkPipelineColorBlendStateCreateFlagBits;
-
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXTspecifies 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.
When
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT
is included in a pipeline, it forms a framebuffer-local memory dependency
for each fragment generated by draw commands for that pipeline with the
following scopes:
-
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.
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 used 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.
To dynamically set blendEnable, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetColorBlendEnableEXT(
VkCommandBuffer commandBuffer,
uint32_t firstAttachment,
uint32_t attachmentCount,
const VkBool32* pColorBlendEnables);
-
commandBufferis the command buffer into which the command will be recorded. -
firstAttachmentthe first color attachment the color blending enable applies. -
attachmentCountthe number of color blending enables in thepColorBlendEnablesarray. -
pColorBlendEnablesan array of booleans to indicate whether color blending is enabled for the corresponding attachment.
This command sets the color blending enable of the specified color
attachments for subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineColorBlendAttachmentState::blendEnable values used to
create the currently active pipeline.
To dynamically set color blend factors and operations, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetColorBlendEquationEXT(
VkCommandBuffer commandBuffer,
uint32_t firstAttachment,
uint32_t attachmentCount,
const VkColorBlendEquationEXT* pColorBlendEquations);
-
commandBufferis the command buffer into which the command will be recorded. -
firstAttachmentthe first color attachment the color blend factors and operations apply to. -
attachmentCountthe number of VkColorBlendEquationEXT elements in thepColorBlendEquationsarray. -
pColorBlendEquationsan array of VkColorBlendEquationEXT structs that specify the color blend factors and operations for the corresponding attachments.
This command sets the color blending factors and operations of the specified
attachments for subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineColorBlendAttachmentState::srcColorBlendFactor,
VkPipelineColorBlendAttachmentState::dstColorBlendFactor,
VkPipelineColorBlendAttachmentState::colorBlendOp,
VkPipelineColorBlendAttachmentState::srcAlphaBlendFactor,
VkPipelineColorBlendAttachmentState::dstAlphaBlendFactor, and
VkPipelineColorBlendAttachmentState::alphaBlendOp values used to
create the currently active pipeline.
The VkColorBlendEquationEXT structure is defined as:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
typedef struct VkColorBlendEquationEXT {
VkBlendFactor srcColorBlendFactor;
VkBlendFactor dstColorBlendFactor;
VkBlendOp colorBlendOp;
VkBlendFactor srcAlphaBlendFactor;
VkBlendFactor dstAlphaBlendFactor;
VkBlendOp alphaBlendOp;
} VkColorBlendEquationEXT;
-
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.
To dynamically set the color write masks, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetColorWriteMaskEXT(
VkCommandBuffer commandBuffer,
uint32_t firstAttachment,
uint32_t attachmentCount,
const VkColorComponentFlags* pColorWriteMasks);
-
commandBufferis the command buffer into which the command will be recorded. -
firstAttachmentthe first color attachment the color write masks apply to. -
attachmentCountthe number of VkColorComponentFlags values in thepColorWriteMasksarray. -
pColorWriteMasksan array of VkColorComponentFlags values that specify the color write masks of the corresponding attachments.
This command sets the color write masks of the specified attachments for
subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineColorBlendAttachmentState::colorWriteMask values used
to create the currently active pipeline.
|
Note
|
Formats with bits that are shared between components specified by
VkColorComponentFlagBits, such as
|
31.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
when drawing using shader objects, or
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.
31.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.
Color outputs can be 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 value of the second
input is undefined.
31.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.
31.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 a VkStructureType value identifying 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.
To dynamically set the advanced blend state, call:
// Provided by VK_EXT_blend_operation_advanced with VK_EXT_extended_dynamic_state3, VK_EXT_blend_operation_advanced with VK_EXT_shader_object
void vkCmdSetColorBlendAdvancedEXT(
VkCommandBuffer commandBuffer,
uint32_t firstAttachment,
uint32_t attachmentCount,
const VkColorBlendAdvancedEXT* pColorBlendAdvanced);
-
commandBufferis the command buffer into which the command will be recorded. -
firstAttachmentthe first color attachment the advanced blend parameters apply to. -
attachmentCountthe number of VkColorBlendAdvancedEXT elements in thepColorBlendAdvancedarray. -
pColorBlendAdvancedan array of VkColorBlendAdvancedEXT structs that specify the advanced color blend parameters for the corresponding attachments.
This command sets the advanced blend operation parameters of the specified
attachments for subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineColorBlendAdvancedStateCreateInfoEXT::srcPremultiplied,
VkPipelineColorBlendAdvancedStateCreateInfoEXT::dstPremultiplied,
and VkPipelineColorBlendAdvancedStateCreateInfoEXT::blendOverlap
values used to create the currently active pipeline.
The VkColorBlendAdvancedEXT structure is defined as:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
typedef struct VkColorBlendAdvancedEXT {
VkBlendOp advancedBlendOp;
VkBool32 srcPremultiplied;
VkBool32 dstPremultiplied;
VkBlendOverlapEXT blendOverlap;
VkBool32 clampResults;
} VkColorBlendAdvancedEXT;
-
advancedBlendOpselects which blend operation is used to calculate the RGB values to write to the color attachment. -
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. -
clampResultsspecifies that results must be clamped to the [0,1] range before writing to the attachment, which is useful when the attachment format is not normalized fixed-point.
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 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 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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
31.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.
The logicOpEnable state can also be controlled by
vkCmdSetLogicOpEnableEXT if graphics pipeline is created with
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
The logicOp state 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 whether logical operations are enabled, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetLogicOpEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 logicOpEnable);
-
commandBufferis the command buffer into which the command will be recorded. -
logicOpEnablespecifies whether logical operations are enabled.
This command sets whether logical operations are enabled for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT set in
VkPipelineDynamicStateCreateInfo::pDynamicStates.
Otherwise, this state is specified by the
VkPipelineColorBlendStateCreateInfo::logicOpEnable value used to
create the currently active pipeline.
To dynamically set the logical operation to apply for blend state, call:
// Provided by VK_EXT_extended_dynamic_state2, VK_EXT_shader_object
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 drawing using shader objects, or
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.
31.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.
31.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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentCountis the number of VkBool32 elements 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, 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 of VkBool32 elements 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 drawing using shader objects, or
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.
31.5. Framebuffer Query Instructions
To query the tile properties from the attachments in framebuffer, call:
// Provided by VK_QCOM_tile_properties
VkResult vkGetFramebufferTilePropertiesQCOM(
VkDevice device,
VkFramebuffer framebuffer,
uint32_t* pPropertiesCount,
VkTilePropertiesQCOM* pProperties);
-
deviceis a logical device associated with the framebuffer. -
framebufferis a handle of the framebuffer to query. -
pPropertiesCountis a pointer to an integer related to the number of tile properties available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array of VkTilePropertiesQCOM structures.
If pProperties is NULL, then the number of tile properties available
is returned in pPropertiesCount.
Otherwise, pPropertiesCount must point to a variable set by the
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of properties actually
written to pProperties.
If pPropertiesCount is less than the number of tile properties
available, at most pPropertiesCount 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 number of tile properties available is determined by the number of
merged subpasses, and each tile property is associated with a merged
subpass.
There will be at most as many properties as there are subpasses within the
render pass.
To obtain the tile properties for a given merged subpass, the pProperties
array can be indexed using the postMergeIndex value provided in
VkRenderPassSubpassFeedbackInfoEXT.
32. Dispatching Commands
The dispatching commands described in this chapter 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).
To record an area-based dispatch, call:
// Provided by VK_QCOM_tile_shading
void vkCmdDispatchTileQCOM(
VkCommandBuffer commandBuffer,
const VkDispatchTileInfoQCOM* pDispatchTileInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pDispatchTileInfois a pointer to a VkDispatchTileInfoQCOM structure containing information about the area-based dispatch.
This command operates in the per-tile execution model, invoking a separate dispatch for each covered tile. The global workgroup count and local workgroup size of each dispatch are defined by the implementation to efficiently iterate over a uniform grid of pixel blocks within the area of its active tile.
Each shader invocation operates on a single pixel block and its size is
determined by the shader’s tiling rate, which must be defined by shaders
executed by this command.
The TileShadingRateQCOM execution mode operand defines the shader’s
tiling rate.
Its x and y must be a power of two and less than or equal to
the maxTileShadingRate limit.
Its z must be less than or equal to the active tile’s depth as
reported by VK_QCOM_tile_properties, and
VkTilePropertiesQCOM::tileSize::z %
TileShadingRateQCOM::z must equal 0.
The start location of the shader invocation’s pixel block is
vec3(TileOffsetQCOM, 0) + (GlobalInvocationId *
TileShadingRateQCOM)
Shader invocations can perform tile attachment load/store operations at any location within the active tile, but the most efficient access may be limited to fragment locations within and local to the shader invocation’s pixel block.
The VkDispatchTileInfoQCOM structure is defined as:
// Provided by VK_QCOM_tile_shading
typedef struct VkDispatchTileInfoQCOM {
VkStructureType sType;
const void* pNext;
} VkDispatchTileInfoQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
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 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.
32.1. Dispatch Command for CUDA PTX Kernels
Compute kernels can be provided in SPIR-V or PTX code. When using PTX kernels the dispatch mechanism is different than with regular compute pipelines.
The way to create a PTX assembly file is beyond the scope of this documentation. For mode information, please refer to the CUDA toolkit documentation at https://docs.nvidia.com/cuda/.
Prior to using this command, you must initialize a CUDA module, and create a function handle that will serve as the entry point of the kernel to dispatch. See CUDA Modules.
The dispatching of a CUDA kernel is recorded into a command buffer, and when executed by a queue submit, will produce work which executes according to the bound compute pipeline.
To record a CUDA kernel launch, call:
// Provided by VK_NV_cuda_kernel_launch
void vkCmdCudaLaunchKernelNV(
VkCommandBuffer commandBuffer,
const VkCudaLaunchInfoNV* pLaunchInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pLaunchInfois a pointer to a VkCudaLaunchInfoNV structure in which the grid (similar to workgroup) dimension, function handle and related arguments are defined.
When the command is executed, a global workgroup consisting of
gridDimX × gridDimY × gridDimZ local
workgroups is assembled.
32.1.1. Passing Dispatch Parameters and Arguments
The VkCudaLaunchInfoNV structure is very close to the parameters of
the CUDA-Driver function
cuLaunchKernel
documented in section
6.19
Execution Control of CUDA Driver API.
The structure is defined as:
// Provided by VK_NV_cuda_kernel_launch
typedef struct VkCudaLaunchInfoNV {
VkStructureType sType;
const void* pNext;
VkCudaFunctionNV 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;
} VkCudaLaunchInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
functionis the CUDA-Driver handle to the function being launched. -
gridDimXis the number of local workgroups to dispatch in the X dimension. It must be less than or equal toVkPhysicalDeviceLimits::maxComputeWorkGroupCount[0] -
gridDimYis the number of local workgroups to dispatch in the Y dimension. It must be less than or equal toVkPhysicalDeviceLimits::maxComputeWorkGroupCount[1] -
gridDimZis the number of local workgroups to dispatch in the Z dimension. It must be less than or equal toVkPhysicalDeviceLimits::maxComputeWorkGroupCount[2] -
blockDimXis block size in the X dimension. -
blockDimYis block size in the Y dimension. -
blockDimZis block size in the Z dimension. -
sharedMemBytesis the dynamic shared-memory size per thread block in bytes. -
paramCountis the length of thepParamstable. -
pParamsis a pointer to an array ofparamCountpointers, corresponding to the arguments offunction. -
extraCountis reserved for future use. -
pExtrasis reserved for future use.
Kernel parameters of function are specified via pParams, very
much the same way as described in
cuLaunchKernel
If function has N parameters, then pParams must be an array of
N pointers and paramCount must be N. Each of kernelParams[0]
through kernelParams[N-1] must point to a region of memory from which
the actual kernel parameter will be copied.
The number of kernel parameters and their offsets and sizes are not
specified here as that information is stored in the VkCudaFunctionNV
object.
The application-owned memory pointed to by pParams and
kernelParams[0] through kernelParams[N-1] are consumed
immediately, and may be altered or freed after
vkCmdCudaLaunchKernelNV has returned.
32.1.2. Resource Sharing from Vulkan to the CUDA Kernel
Given that one key limitation of this extension is that Vulkan cannot access, nor bind any global resource of CUDA modules, the only way to exchange data with the kernel must be to pass resources via the arguments of the function.
You can use VK_KHR_buffer_device_address to write/read to/from a
VkBuffer object.
VK_KHR_buffer_device_address allows you to get the device address of
the buffer to pass it as an argument into pParams.
Application-side pointer arithmetic on the device address is legal, but will
not be bounds-checked on the device.
The corresponding argument of the CUDA function should be declared as a pointer of the same type as the referenced buffer. CUDA code may simply read or write to this buffer in the typical C way.
You may also use VK_NVX_image_view_handle as another convenient way to read/write from/to a VkImage.
The corresponding argument of the CUDA function must be typed as
cudaSurfaceObject_t.
-
You may read from it by using CUDA surface-read functions such as
surf3Dread,surf2Dread, andsurf1Dread -
You may write to it by using CUDA surface-write functions such as
surf3Dwrite,surf2Dwrite, andsurf1Dwrite
Please refer to CUDA surface object documentation for more details
On Vulkan side, here is an example on how to setup
VkImageViewHandleInfoNVX to query the handle for
cudaSurfaceObject_t:
VkImageViewHandleInfoNVX imageViewHandleInfo = {VK_STRUCTURE_TYPE_IMAGE_VIEW_HANDLE_INFO_NVX};
imageViewHandleInfo.sampler = VK_NULL_HANDLE;
imageViewHandleInfo.descriptorType = VK_DESCRIPTOR_TYPE_STORAGE_IMAGE;
imageViewHandleInfo.imageView = imageViewIn; // the VkImageView we want to access
uint32_t myViewHandleIn = vkGetImageViewHandleNVX(m_device, &imageViewHandleInfo);
imageViewHandleInfo.imageView = imageViewOut; // the VkImageView we want to access
uint32_t myViewHandleOut = vkGetImageViewHandleNVX(m_device, &imageViewHandleInfo);
Here is an example of how to declare parameters for pParams
VkCudaLaunchInfoNV launchInfo = { VK_STRUCTURE_TYPE_CUDA_LAUNCH_INFO_NV };
int block_size = 8;
float dt = 1.0f / 60.0f;
const void* params[] =
{
&dt,
&uint32_t myViewHandleIn,
&uint32_t myViewHandleOut
};
launchInfo.function = cudaFunction; // CUDA function previously created
launchInfo.gridDimX = (volumeTexDimensionNonBoundary / block_size);
launchInfo.gridDimY = (volumeTexDimensionNonBoundary / block_size);
launchInfo.gridDimZ = (volumeTexDimensionNonBoundary / block_size);
launchInfo.blockDimX = block_size;
launchInfo.blockDimY = block_size;
launchInfo.blockDimZ = block_size;
launchInfo.sharedMemBytes = 0;
launchInfo.paramCount = 3;
launchInfo.pParams = ¶ms[0];
launchInfo.extraCount = 0;
launchInfo.pExtras = nullptr;
vkCmdCudaLaunchKernelNV(commandBuffer, &launchInfo);
In the CUDA kernel source code, here is an example on how arguments match
pParams and how we can use Surface object:
extern "C" __global__ void cudaFunction(
float dt,
cudaSurfaceObject_t volumeTexIn,
cudaSurfaceObject_t volumeTexOut
)
{
int i = 1 + blockIdx.x * blockDim.x + threadIdx.x;
int j = 1 + blockIdx.y * blockDim.y + threadIdx.y;
int k = 1 + blockIdx.z * blockDim.z + threadIdx.z;
float val;
surf3Dread(&val, volumeTexIn, i * sizeof(float), j, k);
...
float result = ...;
// write result
surf3Dwrite(result, volumeTexOut, i * sizeof(float), j, k);
}
33. 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 a layout describing the sequence of commands which should be generated.
-
Optionally set up device-bindable shaders.
-
Retrieve device addresses by vkGetBufferDeviceAddressEXT for setting buffers on the device.
-
Fill one or more
VkBufferwith the appropriate content that gets interpreted by the command layout. -
Create a
preprocessVkBufferusing the device-queried allocation information. -
Optionally preprocess the input data in a separate action.
-
Generate and execute the actual commands.
The preprocessing step 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 in a separate step, the preprocessing is automatically synchronized against the command execution.
33.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_EXT_device_generated_commands
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectCommandsLayoutEXT)
or:
// Provided by VK_NV_device_generated_commands
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectCommandsLayoutNV)
Each indirect command layout must have exactly one action command token and it must be the last token in the sequence.
|
Note
|
If the indirect commands layout contains only 1 token, it will be an action command token, and the contents of the indirect buffer will be a sequence of indirect command structures, similar to the ones used for indirect draws and dispatches. On some implementations, using indirect draws and dispatches for these cases will result in increased performance compared to using device-generated commands, due to the overhead that results from using the latter. |
33.1.1. Creation and Deletion
Indirect command layouts for VK_EXT_device_generated_commands are
created by:
// Provided by VK_EXT_device_generated_commands
VkResult vkCreateIndirectCommandsLayoutEXT(
VkDevice device,
const VkIndirectCommandsLayoutCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkIndirectCommandsLayoutEXT* pIndirectCommandsLayout);
-
deviceis the logical device that creates the indirect command layout. -
pCreateInfois a pointer to a VkIndirectCommandsLayoutCreateInfoEXT structure containing parameters affecting creation of the indirect command layout. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pIndirectCommandsLayoutis a pointer to aVkIndirectCommandsLayoutEXThandle in which the resulting indirect command layout is returned.
The VkIndirectCommandsLayoutCreateInfoEXT structure is defined as:
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsLayoutCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkIndirectCommandsLayoutUsageFlagsEXT flags;
VkShaderStageFlags shaderStages;
uint32_t indirectStride;
VkPipelineLayout pipelineLayout;
uint32_t tokenCount;
const VkIndirectCommandsLayoutTokenEXT* pTokens;
} VkIndirectCommandsLayoutCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkIndirectCommandsLayoutUsageFlagBitsEXT specifying usage rules for this layout. -
shaderStagesis the VkShaderStageFlags that this layout supports. -
indirectStrideis the distance in bytes between sequences in the indirect buffer -
pipelineLayoutis the optional VkPipelineLayout that tokens in this layout use. If thedynamicGeneratedPipelineLayoutfeature is enabled,pipelineLayoutcan be VK_NULL_HANDLE and the layout must be specified by chaining the VkPipelineLayoutCreateInfo structure off thepNext -
tokenCountis the length of the individual command sequence. -
pTokensis a pointer to an array of VkIndirectCommandsLayoutTokenEXT describing each command token in detail.
The following code illustrates some of the flags:
void cmdProcessAllSequences(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sequencesCount)
{
for (s = 0; s < sequencesCount; s++)
{
sUsed = s;
if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT) {
sUsed = incoherent_implementation_dependent_permutation[ sUsed ];
}
cmdProcessSequence( cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, 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 4, whichever is lower.
Bits which can be set in
VkIndirectCommandsLayoutCreateInfoEXT::flags, specifying usage
hints of an indirect command layout, are:
// Provided by VK_EXT_device_generated_commands
typedef enum VkIndirectCommandsLayoutUsageFlagBitsEXT {
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXT = 0x00000001,
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT = 0x00000002,
} VkIndirectCommandsLayoutUsageFlagBitsEXT;
-
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_EXPLICIT_PREPROCESS_BIT_EXTspecifies that the layout is always used with the manual preprocessing step through calling vkCmdPreprocessGeneratedCommandsEXT and executed by vkCmdExecuteGeneratedCommandsEXT withisPreprocessedset toVK_TRUE. -
VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXTspecifies that the processing of sequences will happen at an implementation-dependent order, which is not guaranteed to be deterministic using the same input data. This flag is ignored when theshaderStagesisVK_SHADER_STAGE_COMPUTE_BITas it is implied that the dispatch sequence is always unordered.
// Provided by VK_EXT_device_generated_commands
typedef VkFlags VkIndirectCommandsLayoutUsageFlagsEXT;
VkIndirectCommandsLayoutUsageFlagsEXT is a bitmask type for setting a
mask of zero or more VkIndirectCommandsLayoutUsageFlagBitsEXT.
Indirect command layouts for VK_EXT_device_generated_commands are
destroyed by:
// Provided by VK_EXT_device_generated_commands
void vkDestroyIndirectCommandsLayoutEXT(
VkDevice device,
VkIndirectCommandsLayoutEXT 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.
Indirect command layouts for VK_NV_device_generated_commands 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 a VkIndirectCommandsLayoutCreateInfoNV structure 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 a VkStructureType value identifying 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 an application-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. This flag is ignored when thepipelineBindPointisVK_PIPELINE_BIND_POINT_COMPUTEas it is implied that the dispatch sequence is always unordered.
// 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 for VK_NV_device_generated_commands 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.
33.1.2. Token Input Streams
For VK_EXT_device_generated_commands, 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 VkBindIndexBufferIndirectCommandEXT structure specifies the input
data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT token.
// Provided by VK_EXT_device_generated_commands
typedef struct VkBindIndexBufferIndirectCommandEXT {
VkDeviceAddress bufferAddress;
uint32_t size;
VkIndexType indexType;
} VkBindIndexBufferIndirectCommandEXT;
-
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.
The VkBindVertexBufferIndirectCommandEXT structure specifies the input
data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT token.
// Provided by VK_EXT_device_generated_commands
typedef struct VkBindVertexBufferIndirectCommandEXT {
VkDeviceAddress bufferAddress;
uint32_t size;
uint32_t stride;
} VkBindVertexBufferIndirectCommandEXT;
-
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.
The VkDrawIndirectCountIndirectCommandEXT structure specifies the
input data for all draw-type tokens.
// Provided by VK_EXT_device_generated_commands
typedef struct VkDrawIndirectCountIndirectCommandEXT {
VkDeviceAddress bufferAddress;
uint32_t stride;
uint32_t commandCount;
} VkDrawIndirectCountIndirectCommandEXT;
-
bufferAddressspecifies a physical address of the VkBuffer used for draw commands. -
strideis the byte size stride for the command arguments -
commandCountis the number of commands to execute
The corresponding indirect draw structure data will be read from the buffer address.
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.
For VK_NV_device_generated_commands, 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;
-
groupIndexspecifies 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 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 drawing commands.
// Provided by VK_NV_device_generated_commands
typedef VkFlags VkIndirectStateFlagsNV;
VkIndirectStateFlagsNV is a bitmask type for setting a mask of zero or
more VkIndirectStateFlagBitsNV.
The VkBindPipelineIndirectCommandNV structure specifies the input data
for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV token.
// Provided by VK_NV_device_generated_commands_compute
typedef struct VkBindPipelineIndirectCommandNV {
VkDeviceAddress pipelineAddress;
} VkBindPipelineIndirectCommandNV;
-
pipelineAddressspecifies the pipeline address of the compute pipeline that will be used in device generated rendering.
33.1.3. Tokenized Command Processing
The processing for VK_EXT_device_generated_commands is in principle
illustrated below:
void cmdProcessSequence(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, s)
{
for (t = 0; t < indirectCommandsLayout.tokenCount; t++)
{
uint32_t offset = indirectCommandsLayout.pTokens[t].offset;
uint32_t stride = indirectCommandsLayout.indirectStride;
VkDeviceAddress streamData = indirectAddress;
const void* input = streamData + stride * s + offset;
// further details later
indirectCommandsLayout.pTokens[t].command (cmd, indirectExecutionSet, input, s);
}
}
void cmdProcessAllSequences(cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sequencesCount)
{
for (s = 0; s < sequencesCount; s++)
{
sUsed = s;
if (indirectCommandsLayout.flags & VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT) {
sUsed = incoherent_implementation_dependent_permutation[ sUsed ];
}
cmdProcessSequence( cmd, indirectExecutionSet, indirectCommandsLayout, indirectAddress, sUsed );
}
}
The processing of each sequence is considered stateless, therefore all state changes must occur prior to action commands within the sequence. A single sequence is strictly targeting the VkShaderStageFlags it was created with.
The primary input data for each token is provided through VkBuffer
content at preprocessing using vkCmdPreprocessGeneratedCommandsEXT or
execution time using vkCmdExecuteGeneratedCommandsEXT, however some
functional arguments, for example push constant layouts, are specified at
layout creation time.
The input size is different for each token.
Possible values of those elements of the
VkIndirectCommandsLayoutCreateInfoEXT::pTokens array specifying
command tokens (other elements of the array specify command parameters) are:
// Provided by VK_EXT_device_generated_commands
typedef enum VkIndirectCommandsTokenTypeEXT {
VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT = 0,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT = 1,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT = 2,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT = 3,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT = 4,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT = 5,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT = 6,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT = 7,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT = 8,
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT = 9,
// Provided by VK_EXT_device_generated_commands with VK_NV_mesh_shader
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT = 1000202002,
// Provided by VK_EXT_device_generated_commands with VK_NV_mesh_shader
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT = 1000202003,
// Provided by VK_EXT_device_generated_commands with VK_EXT_mesh_shader
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT = 1000328000,
// Provided by VK_EXT_device_generated_commands with VK_EXT_mesh_shader
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT = 1000328001,
// Provided by VK_KHR_ray_tracing_maintenance1 with VK_EXT_device_generated_commands
VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT = 1000386004,
} VkIndirectCommandsTokenTypeEXT;
| Common Tokens | Command Data |
|---|---|
|
|
|
|
|
|
Compute Tokens |
|
|
|
Ray Tracing Tokens |
|
|
|
Graphics State Tokens |
|
|
|
|
|
Graphics Draw Tokens |
|
|
|
|
|
|
|
|
|
Graphics Draw Count Tokens |
|
|
VkDrawIndirectCountIndirectCommandEXT with VkDrawIndexedIndirectCommand |
|
VkDrawIndirectCountIndirectCommandEXT with VkDrawIndirectCommand |
|
VkDrawIndirectCountIndirectCommandEXT with VkDrawMeshTasksIndirectCommandEXT |
|
VkDrawIndirectCountIndirectCommandEXT with VkDrawMeshTasksIndirectCommandNV |
The VkIndirectCommandsLayoutTokenEXT structure specifies details to
the function arguments that need to be known at layout creation time:
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsLayoutTokenEXT {
VkStructureType sType;
const void* pNext;
VkIndirectCommandsTokenTypeEXT type;
VkIndirectCommandsTokenDataEXT data;
uint32_t offset;
} VkIndirectCommandsLayoutTokenEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typespecifies the VkIndirectCommandsTokenTypeEXT fordata. -
dataspecifies a VkIndirectCommandsTokenDataEXT containing token-specific details for command execution. It is ignored iftypedoes not match any member of the VkIndirectCommandsTokenDataEXT union. -
offsetis the relative byte offset for the token within one sequence of the indirect buffer. The data stored at that offset is the command data for the token, e.g.VkDispatchIndirectCommand.
The VkIndirectCommandsTokenDataEXT structure provides token-specific
details used to generate the indirect execution layout.
// Provided by VK_EXT_device_generated_commands
typedef union VkIndirectCommandsTokenDataEXT {
const VkIndirectCommandsPushConstantTokenEXT* pPushConstant;
const VkIndirectCommandsVertexBufferTokenEXT* pVertexBuffer;
const VkIndirectCommandsIndexBufferTokenEXT* pIndexBuffer;
const VkIndirectCommandsExecutionSetTokenEXT* pExecutionSet;
} VkIndirectCommandsTokenDataEXT;
-
pPushConstantis a pointer to a VkIndirectCommandsPushConstantTokenEXT structure needed forVK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXTandVK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXTtokens -
pVertexBufferis a pointer to a VkIndirectCommandsVertexBufferTokenEXT structure needed forVK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXTtokens -
pIndexBufferis a pointer to a VkIndirectCommandsIndexBufferTokenEXT structure needed forVK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXTtokens -
pExecutionSetis a pointer to a VkIndirectCommandsExecutionSetTokenEXT structure needed forVK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXTtokens
The appropriate member of the union must be set for each token.
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, indirectExecutionSet, indirectCommandsLayout, indirectAddress, s)
{
for (uint32_t t = 0; t < indirectCommandsLayout.tokenCount; t++) {
VkIndirectCommandsLayoutTokenEXT *token = &indirectCommandsLayout.pTokens[t];
uint32_t offset = token->offset;
uint32_t stride = indirectCommandsLayout.indirectStride;
VkDeviceAddress streamData = indirectAddress;
const void* input = streamData + stride * s + offset;
switch (token->tokenType) {
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT:
uint32_t *bind = input;
VkIndirectCommandsExecutionSetTokenEXT *info = token->data.pExecutionSet;
if (info->type == VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT) {
vkCmdBindPipeline(cmd, indirectExecutionSet.pipelineBindPoint, indirectExecutionSet.pipelines[*bind]);
} else {
VkShaderStageFlagBits stages[];
VkShaderEXT shaders[];
uint32_t i = 0;
IterateBitmaskLSBToMSB(iter, info->shaderStages) {
stages[i] = iter;
shaders[i] = indirectExecutionSet.shaders[bind[i]].shaderObject;
i++;
}
vkCmdBindShadersEXT(cmd, i, stages, shaders);
}
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT:
uint32_t* data = input;
VkPushConstantsInfoKHR info = {
VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO_KHR,
// this can also use `dynamicGeneratedPipelineLayout' to pass a VkPipelineLayoutCreateInfo from pNext
indirectCommandsLayout.pipelineLayout,
token->token.pushConstant.updateRange.shaderStages,
token->token.pushConstant.updateRange.offset,
token->token.pushConstant.updateRange.size,
data
};
vkCmdPushConstants2KHR(cmd, &info);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT:
VkPushConstantsInfoKHR info = {
VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO_KHR,
// this can also use `dynamicGeneratedPipelineLayout' to pass a VkPipelineLayoutCreateInfo from pNext
indirectCommandsLayout.pipelineLayout,
token->token.pushConstant.updateRange.shaderStages,
token->token.pushConstant.updateRange.offset,
// this must be 4
token->token.pushConstant.updateRange.size,
// this just updates the sequence index
&s
};
vkCmdPushConstants2KHR(cmd, &info);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT:
VkBindIndexBufferIndirectCommandEXT* data = input;
vkCmdBindIndexBuffer(cmd, deriveBuffer(data->bufferAddress), deriveOffset(data->bufferAddress), data->indexType);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT:
VkBindVertexBufferIndirectCommandEXT* data = input;
vkCmdBindVertexBuffers2(cmd, token->token.vertexBuffer->vertexBindingUnit, 1, &deriveBuffer(data->bufferAddress),
&deriveOffset(data->bufferAddress), data->size, data->stride);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_EXT:
VkDrawIndexedIndirectCommand *data = input;
vkCmdDrawIndexed(cmd, data->indexCount, data->instanceCount, data->firstIndex, data->vertexOffset, data->firstInstance);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_COUNT_EXT:
VkDrawIndirectCountIndirectCommandEXT* data = input;
vkCmdDrawIndexedIndirect(cmd, deriveBuffer(data->bufferAddress), deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_EXT:
VkDrawIndirectCommand* data = input;
vkCmdDraw(cmd, data->vertex_count, data->instanceCount, data->firstVertex, data->firstIndex);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_COUNT_EXT:
VkDrawIndirectCountIndirectCommandEXT* data = input;
vkCmdDrawIndirect(cmd, deriveBuffer(data->bufferAddress), deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride);
break;
// only available if VK_NV_mesh_shader is enabled
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT:
VkDrawMeshTasksIndirectCommandNV *data = input;
vkCmdDrawMeshTasksNV(cmd, data->taskCount, data->firstTask);
break;
// only available if VK_NV_mesh_shader is enabled
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT:
VkDrawIndirectCountIndirectCommandEXT* data = input;
vkCmdDrawMeshTasksIndirectCountNV(cmd, deriveBuffer(data->bufferAddress), deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride);
break;
// only available if VK_EXT_mesh_shader is enabled
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT:
VkDrawMeshTasksIndirectCommandEXT *data = input;
vkCmdDrawMeshTasksEXT(cmd, data->groupCountX, data->groupCountY, data->groupCountZ);
break;
// only available if VK_EXT_mesh_shader is enabled
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT:
VkDrawIndirectCountIndirectCommandEXT* data = input;
vkCmdDrawMeshTasksIndirectCountEXT(cmd, deriveBuffer(data->bufferAddress), deriveoffset(data->bufferAddress), min(data->commandCount, indirectCommandsLayout.maxDrawCount), data->stride);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT:
VkDispatchIndirectCommand *data = input;
vkCmdDispatch(cmd, data->x, data->y, data->z);
break;
// only available if VK_KHR_ray_tracing_maintenance1 is enabled
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT:
vkCmdTraceRaysIndirect2KHR(cmd, deriveBuffer(input));
break;
}
}
}
The processing for VK_NV_device_generated_commands 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 before any action command tokens 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.
The VkIndirectCommandsPushConstantTokenEXT structure specifies the
layout token info for
VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT and
VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT tokens.
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsPushConstantTokenEXT {
VkPushConstantRange updateRange;
} VkIndirectCommandsPushConstantTokenEXT;
-
updateRangeis the push constant range that will be updated by the token.
The stageFlags member of updateRange is ignored.
The VkIndirectCommandsVertexBufferTokenEXT structure specifies the
layout token info for the
VK_INDIRECT_COMMANDS_TOKEN_TYPE_VERTEX_BUFFER_EXT token.
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsVertexBufferTokenEXT {
uint32_t vertexBindingUnit;
} VkIndirectCommandsVertexBufferTokenEXT;
-
vertexBindingUnitis the vertex input binding number to be bound.
The VkIndirectCommandsIndexBufferTokenEXT structure specifies the
layout token info for the
VK_INDIRECT_COMMANDS_TOKEN_TYPE_INDEX_BUFFER_EXT token.
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsIndexBufferTokenEXT {
VkIndirectCommandsInputModeFlagBitsEXT mode;
} VkIndirectCommandsIndexBufferTokenEXT;
-
modespecifies the mode to use with this token.
This allows for easy layering of Vulkan atop other APIs.
When VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT is
specified, the indirect buffer can contain a D3D12_INDEX_BUFFER_VIEW
instead of VkBindIndexBufferIndirectCommandEXT as D3D’s DXGI format
value is mapped to the VkIndexType.
It works as both structs are otherwise binary compatible.
Bits which are set in
VkIndirectCommandsIndexBufferTokenEXT::mode, specifying how an
index buffer is used, are:
// Provided by VK_EXT_device_generated_commands
typedef enum VkIndirectCommandsInputModeFlagBitsEXT {
VK_INDIRECT_COMMANDS_INPUT_MODE_VULKAN_INDEX_BUFFER_EXT = 0x00000001,
VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXT = 0x00000002,
} VkIndirectCommandsInputModeFlagBitsEXT;
-
VK_INDIRECT_COMMANDS_INPUT_MODE_VULKAN_INDEX_BUFFER_EXTspecifies that the indirect buffer contains VkBindIndexBufferIndirectCommandEXT. -
VK_INDIRECT_COMMANDS_INPUT_MODE_DXGI_INDEX_BUFFER_EXTspecifies that the indirect buffer containsD3D12_INDEX_BUFFER_VIEW.
// Provided by VK_EXT_device_generated_commands
typedef VkFlags VkIndirectCommandsInputModeFlagsEXT;
VkIndirectCommandsInputModeFlagsEXT is a bitmask type for setting a
mask of zero or more VkIndirectCommandsInputModeFlagBitsEXT.
The VkIndirectCommandsExecutionSetTokenEXT structure specifies the
input data for the VK_INDIRECT_COMMANDS_TOKEN_TYPE_EXECUTION_SET_EXT
token.
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectCommandsExecutionSetTokenEXT {
VkIndirectExecutionSetInfoTypeEXT type;
VkShaderStageFlags shaderStages;
} VkIndirectCommandsExecutionSetTokenEXT;
-
typedescribes the type of indirect execution set in use. -
shaderStagesspecifies the shaders that will be changed by this 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,
// Provided by VK_EXT_mesh_shader with VK_NV_device_generated_commands
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV = 1000328000,
// Provided by VK_NV_device_generated_commands_compute
VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV = 1000428003,
// Provided by VK_NV_device_generated_commands_compute
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV = 1000428004,
} 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tokenTypeis a VkIndirectCommandsTokenTypeNV specifying 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. -
indirectStateFlagsis a VkIndirectStateFlagsNV bitfield indicating 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 specific VkIndexType. -
pIndexTypesis the used VkIndexType for 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){
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_SHADER_GROUP_NV:
VkBindShaderGroupIndirectCommandNV* bind = input;
vkCmdBindPipelineShaderGroupNV(cmd, indirectCommandsLayout.pipelineBindPoint,
pipeline, bind->groupIndex);
break;
case 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;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV:
uint32_t* data = input;
vkCmdPushConstants(cmd,
token.pushconstantPipelineLayout
token.pushconstantStageFlags,
token.pushconstantOffset,
token.pushconstantSize, data);
break;
case 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;
case 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;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_INDEXED_NV:
vkCmdDrawIndexedIndirect(cmd,
stream.buffer, offset, 1, 0);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_NV:
vkCmdDrawIndirect(cmd,
stream.buffer,
offset, 1, 0);
break;
// only available if VK_NV_mesh_shader is supported
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_TASKS_NV:
vkCmdDrawMeshTasksIndirectNV(cmd,
stream.buffer, offset, 1, 0);
break;
// only available if VK_EXT_mesh_shader is supported
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV:
vkCmdDrawMeshTasksIndirectEXT(cmd,
stream.buffer, offset, 1, 0);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV:
VkBindPipelineIndirectCommandNV *data = input;
VkPipeline computePipeline = deriveFromDeviceAddress(data->pipelineAddress);
vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, computePipeline);
break;
case VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV:
vkCmdDispatchIndirect(cmd, stream.buffer, offset);
break;
}
}
}
33.2. Indirect Commands Generation and Execution
The generation of commands on the device requires a preprocess buffer.
With VK_EXT_device_generated_commands, to retrieve the memory size
and alignment requirements of a particular execution state call:
// Provided by VK_EXT_device_generated_commands
void vkGetGeneratedCommandsMemoryRequirementsEXT(
VkDevice device,
const VkGeneratedCommandsMemoryRequirementsInfoEXT* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device that owns the buffer. -
pInfois a pointer to a VkGeneratedCommandsMemoryRequirementsInfoEXT 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.
If the size returned is zero, the preprocessing step can be skipped for this layout.
// Provided by VK_EXT_device_generated_commands
typedef struct VkGeneratedCommandsMemoryRequirementsInfoEXT {
VkStructureType sType;
const void* pNext;
VkIndirectExecutionSetEXT indirectExecutionSet;
VkIndirectCommandsLayoutEXT indirectCommandsLayout;
uint32_t maxSequenceCount;
uint32_t maxDrawCount;
} VkGeneratedCommandsMemoryRequirementsInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
indirectExecutionSetis the indirect execution set to be used for binding shaders. -
indirectCommandsLayoutis the VkIndirectCommandsLayoutEXT that this buffer memory is intended to be used with. -
maxSequenceCountis the maximum number of sequences that this buffer memory can be used with. -
maxDrawCountis the maximum number of indirect draws that can be executed by any COUNT-type multi-draw indirect tokens. The draw count in the indirect buffer is clamped to this value for these token types.
If the action command token for the layout is not a COUNT-type multi-draw
indirect token, maxDrawCount is ignored.
// Provided by VK_EXT_device_generated_commands
typedef struct VkGeneratedCommandsPipelineInfoEXT {
VkStructureType sType;
void* pNext;
VkPipeline pipeline;
} VkGeneratedCommandsPipelineInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineis a valid pipeline object.
// Provided by VK_EXT_device_generated_commands
typedef struct VkGeneratedCommandsShaderInfoEXT {
VkStructureType sType;
void* pNext;
uint32_t shaderCount;
const VkShaderEXT* pShaders;
} VkGeneratedCommandsShaderInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderCountis the size of thepShadersarray. -
pShadersis a pointer to an array of shader objects.
With VK_NV_device_generated_commands, 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 a VkGeneratedCommandsMemoryRequirementsInfoNV 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.
// 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 a VkStructureType value identifying 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.
With VK_NV_device_generated_commands, to bind a compute pipeline in
Device-Generated Commands, an application
must query the pipeline’s device address.
To query a compute pipeline’s 64-bit device address, call:
// Provided by VK_NV_device_generated_commands_compute
VkDeviceAddress vkGetPipelineIndirectDeviceAddressNV(
VkDevice device,
const VkPipelineIndirectDeviceAddressInfoNV* pInfo);
-
deviceis the logical device on which the pipeline was created. -
pInfois a pointer to a VkPipelineIndirectDeviceAddressInfoNV structure specifying the pipeline to retrieve the address for.
The VkPipelineIndirectDeviceAddressInfoNV structure is defined as:
// Provided by VK_NV_device_generated_commands_compute
typedef struct VkPipelineIndirectDeviceAddressInfoNV {
VkStructureType sType;
const void* pNext;
VkPipelineBindPoint pipelineBindPoint;
VkPipeline pipeline;
} VkPipelineIndirectDeviceAddressInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBindPointis a VkPipelineBindPoint value specifying the type of pipeline whose device address is being queried. -
pipelinespecifies the pipeline whose device address is being queried.
To determine the memory requirements for a compute pipeline’s metadata, call:
// Provided by VK_NV_device_generated_commands_compute
void vkGetPipelineIndirectMemoryRequirementsNV(
VkDevice device,
const VkComputePipelineCreateInfo* pCreateInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device that owns the buffer. -
pCreateInfois a VkComputePipelineCreateInfo structure specifying the creation parameters of the compute pipeline whose memory requirements are being queried. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the requested pipeline’s memory requirements are returned.
If pCreateInfo->pNext chain includes a pointer to a
VkComputePipelineIndirectBufferInfoNV structure, then the contents of
that structure are ignored.
33.2.1. Indirect Execution Sets
Indirect Execution Sets contain sets of pipelines or shader objects which can be bound individually.
// Provided by VK_EXT_device_generated_commands
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkIndirectExecutionSetEXT)
Indirect Execution Sets allow the device to bind different shaders and pipeline states using Device-Generated Commands.
Indirect Execution Sets are created by calling:
// Provided by VK_EXT_device_generated_commands
VkResult vkCreateIndirectExecutionSetEXT(
VkDevice device,
const VkIndirectExecutionSetCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkIndirectExecutionSetEXT* pIndirectExecutionSet);
-
deviceis the logical device that creates the indirect execution set. -
pCreateInfois a pointer to a VkIndirectExecutionSetCreateInfoEXT structure containing parameters affecting creation of the indirect execution set. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pIndirectExecutionSetis a pointer to a VkIndirectExecutionSetEXT handle in which the resulting indirect execution set is returned.
The VkIndirectExecutionSetCreateInfoEXT structure is defined as:
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectExecutionSetCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkIndirectExecutionSetInfoTypeEXT type;
VkIndirectExecutionSetInfoEXT info;
} VkIndirectExecutionSetCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis a VkIndirectExecutionSetInfoTypeEXT describing the type of set being created and determining which field of theinfounion will be used. -
infois a VkIndirectExecutionSetInfoEXT union containing layout information for the set.
Values which can be set in
VkIndirectExecutionSetCreateInfoEXT::type, specifying contents
of an indirect execution set, are:
// Provided by VK_EXT_device_generated_commands
typedef enum VkIndirectExecutionSetInfoTypeEXT {
VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXT = 0,
VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXT = 1,
} VkIndirectExecutionSetInfoTypeEXT;
-
VK_INDIRECT_EXECUTION_SET_INFO_TYPE_PIPELINES_EXTspecifies that the indirect execution set contains VkPipeline objects. -
VK_INDIRECT_EXECUTION_SET_INFO_TYPE_SHADER_OBJECTS_EXTspecifies that the indirect execution set contains VkShaderEXT objects.
The VkIndirectExecutionSetInfoEXT union is defined as:
// Provided by VK_EXT_device_generated_commands
typedef union VkIndirectExecutionSetInfoEXT {
const VkIndirectExecutionSetPipelineInfoEXT* pPipelineInfo;
const VkIndirectExecutionSetShaderInfoEXT* pShaderInfo;
} VkIndirectExecutionSetInfoEXT;
-
pPipelineInfois a pointer to a VkIndirectExecutionSetPipelineInfoEXT structure containing pipeline layout information for the set. -
pShaderInfois a pointer to a VkIndirectExecutionSetShaderInfoEXT structure containing shader object layout information for the set.
The VkIndirectExecutionSetPipelineInfoEXT structure is defined as:
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectExecutionSetPipelineInfoEXT {
VkStructureType sType;
const void* pNext;
VkPipeline initialPipeline;
uint32_t maxPipelineCount;
} VkIndirectExecutionSetPipelineInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
initialPipelineis the initial pipeline for the set. This pipeline will be automatically added to the set at index0. -
maxPipelineCountis the maximum number of pipelines stored in the set.
The characteristics of initialPipeline will be used to validate all
pipelines added to the set even if they are removed from the set or
destroyed.
When an Indirect Execution Set created with pipelines is used,
initialPipeline constitutes the initial shader state.
The VkIndirectExecutionSetShaderInfoEXT structure is defined as:
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectExecutionSetShaderInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t shaderCount;
const VkShaderEXT* pInitialShaders;
const VkIndirectExecutionSetShaderLayoutInfoEXT* pSetLayoutInfos;
uint32_t maxShaderCount;
uint32_t pushConstantRangeCount;
const VkPushConstantRange* pPushConstantRanges;
} VkIndirectExecutionSetShaderInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderCountis the number of members in thepInitialShadersandpSetLayoutInfosarrays. -
pInitialShadersis a pointer to an array containing a VkShaderEXT object for each shader stage that will be used in the set. These shaders will be automatically added to the set beginning at index0. -
pSetLayoutInfosis a pointer to an array containing a VkIndirectExecutionSetShaderLayoutInfoEXT used by each correspondingpInitialShadersshader stage in the set. -
maxShaderCountis the maximum number of shader objects stored in the set. -
pushConstantRangeCountis the number of members in thepPushConstantRangesarray. -
pPushConstantRangesis a pointer to the array of VkPushConstantRange ranges used by all shaders in the set.
The characteristics of pInitialShaders will be used to validate all
shaders added to the set even if they are removed from the set or destroyed.
When an Indirect Execution Set created with shader objects is used,
pInitialShaders constitutes the initial shader state.
The VkIndirectExecutionSetShaderLayoutInfoEXT structure is defined as:
// Provided by VK_EXT_device_generated_commands
typedef struct VkIndirectExecutionSetShaderLayoutInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t setLayoutCount;
const VkDescriptorSetLayout* pSetLayouts;
} VkIndirectExecutionSetShaderLayoutInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
setLayoutCountis the number of members in thepSetLayoutsarray -
pSetLayoutsis a pointer to an array containing VkDescriptorSetLayout objects used by the shader stage. The implementation must not access these objects outside of the duration of the command this structure is passed to.
Destroy an Indirect Execution Set by calling:
// Provided by VK_EXT_device_generated_commands
void vkDestroyIndirectExecutionSetEXT(
VkDevice device,
VkIndirectExecutionSetEXT indirectExecutionSet,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that owns the indirect execution set. -
indirectExecutionSetis the indirect execution set to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
The VkWriteIndirectExecutionSetPipelineEXT structure is defined as:
// Provided by VK_EXT_device_generated_commands
typedef struct VkWriteIndirectExecutionSetPipelineEXT {
VkStructureType sType;
const void* pNext;
uint32_t index;
VkPipeline pipeline;
} VkWriteIndirectExecutionSetPipelineEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
indexis the element of the set to update -
pipelineis the pipeline to store in the indirect execution set
The VkWriteIndirectExecutionSetShaderEXT structure is defined as:
// Provided by VK_EXT_device_generated_commands with VK_EXT_shader_object
typedef struct VkWriteIndirectExecutionSetShaderEXT {
VkStructureType sType;
const void* pNext;
uint32_t index;
VkShaderEXT shader;
} VkWriteIndirectExecutionSetShaderEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
indexis the element of the set to update -
shaderis the shader to store in the indirect execution set
Shaders need not be stored in the Indirect Execution Set according to their stage. The only restriction for shader indices within a set is that the value of the index must be less than the maximum number of shaders in the set.
Pipeline elements in an Indirect Execution Set can be updated by calling:
// Provided by VK_EXT_device_generated_commands
void vkUpdateIndirectExecutionSetPipelineEXT(
VkDevice device,
VkIndirectExecutionSetEXT indirectExecutionSet,
uint32_t executionSetWriteCount,
const VkWriteIndirectExecutionSetPipelineEXT* pExecutionSetWrites);
-
deviceis the logical device that owns the indirect execution set. -
indirectExecutionSetis the indirect execution set being updated. -
executionSetWriteCountis the number of elements in thepExecutionSetWritesarray. -
pExecutionSetWritesis a pointer to an array of VkWriteIndirectExecutionSetPipelineEXT structures describing the elements to update.
Shader object elements in an Indirect Execution Set can be updated by calling:
// Provided by VK_EXT_device_generated_commands
void vkUpdateIndirectExecutionSetShaderEXT(
VkDevice device,
VkIndirectExecutionSetEXT indirectExecutionSet,
uint32_t executionSetWriteCount,
const VkWriteIndirectExecutionSetShaderEXT* pExecutionSetWrites);
-
deviceis the logical device that owns the indirect execution set. -
indirectExecutionSetis the indirect execution set being updated. -
executionSetWriteCountis the number of elements in thepExecutionSetWritesarray. -
pExecutionSetWritesis a pointer to an array of VkWriteIndirectExecutionSetShaderEXT structures describing the elements to update.
It is legal to update an Indirect Execution Set that is in flight as long as
the element indices in pExecutionSetWrites are not in use.
Any change to an indirect execution set requires recalculating memory
requirements by calling vkGetGeneratedCommandsMemoryRequirementsEXT
for commands that use that modified state.
Commands that are in flight or those not using updated elements require no
changes.
The lifetimes of pipelines and shader objects contained in a set must match or exceed the lifetime of the set.
With VK_NV_device_generated_commands, 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.
If the VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_NV
flag was used to create the
VkGeneratedCommandsInfoNV::indirectCommandsLayout then the order
of execution of individual draws through this command may execute in any
order, and may not necessarily be in the same order as specified in
VkGeneratedCommandsInfoNV::pStreams.
The order of execution of individual dispatches through this command may
execute in any order and may not necessarily be in the same order as
specified in VkGeneratedCommandsInfoNV::pStreams.
The VkGeneratedCommandsInfoNV is defined as:
// 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 a VkStructureType value identifying 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 in this buffer will not be modified. The contents and the layout of this buffer are opaque to applications and must not be modified outside functions related to device-generated commands or copied to another buffer for reuse. -
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.
The bound descriptor sets and push constants that will be used with indirect command generation for the compute pipelines must already be specified at the time of preprocessing commands with vkCmdPreprocessGeneratedCommandsNV. They must not change until the execution of indirect commands is submitted with vkCmdExecuteGeneratedCommandsNV.
If push constants for the compute pipeline are also specified in the
VkGeneratedCommandsInfoNV::indirectCommandsLayout with
VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_NV token, then those
values override the push constants that were previously pushed for the
compute pipeline.
With VK_EXT_device_generated_commands, the actual generation of
commands as well as their execution on the device is handled as single
action with:
// Provided by VK_EXT_device_generated_commands
void vkCmdExecuteGeneratedCommandsEXT(
VkCommandBuffer commandBuffer,
VkBool32 isPreprocessed,
const VkGeneratedCommandsInfoEXT* 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 VkGeneratedCommandsInfoEXT structure containing parameters affecting the generation of commands.
If the VK_INDIRECT_COMMANDS_LAYOUT_USAGE_UNORDERED_SEQUENCES_BIT_EXT
flag was used to create the
VkGeneratedCommandsInfoEXT::indirectCommandsLayout then the
execution of sequences through this command may use implementation-defined
ordering which is not guaranteed to be coherent using the same input data.
It does not affect the order of token processing within a sequence.
This is the implied ordering with
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_EXT.
After a call to vkCmdExecuteGeneratedCommandsEXT, command buffer state
will become undefined according to the tokens executed.
This table specifies the relationship between tokens used and state
invalidation.
| Common Tokens | States Invalidated |
|---|---|
|
Bound shaders and pipelines |
|
Push constant data |
|
Push constant data |
|
Index buffer |
|
Vertex buffer |
The VkGeneratedCommandsInfoEXT is defined as:
// Provided by VK_EXT_device_generated_commands
typedef struct VkGeneratedCommandsInfoEXT {
VkStructureType sType;
const void* pNext;
VkShaderStageFlags shaderStages;
VkIndirectExecutionSetEXT indirectExecutionSet;
VkIndirectCommandsLayoutEXT indirectCommandsLayout;
VkDeviceAddress indirectAddress;
VkDeviceSize indirectAddressSize;
VkDeviceAddress preprocessAddress;
VkDeviceSize preprocessSize;
uint32_t maxSequenceCount;
VkDeviceAddress sequenceCountAddress;
uint32_t maxDrawCount;
} VkGeneratedCommandsInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderStagesis the mask of shader stages used by the commands. -
indirectExecutionSetis the indirect execution set to be used for binding shaders. -
indirectCommandsLayoutis the VkIndirectCommandsLayoutEXT that specifies the command sequence data. -
indirectAddressis an address that holds the indirect buffer data. -
indirectAddressSizeis the size in bytes of indirect buffer data starting atindirectAddress. -
preprocessAddressspecifies a physical address of theVkBufferused for preprocessing the input data for execution. If this structure is used with vkCmdExecuteGeneratedCommandsEXT with itsisPreprocessedset toVK_TRUE, then the preprocessing step is skipped but data in this address may still be modified. The contents and the layout of this address are opaque to applications and must not be modified outside functions related to device-generated commands or copied to another buffer for reuse. -
preprocessSizeis the maximum byte size withinpreprocessAddressthat is available for preprocessing. -
maxSequenceCountis used to determine the number of sequences to execute. -
sequenceCountAddressspecifies an optional physical address of a singleuint32_tvalue containing the requested number of sequences to execute. -
maxDrawCountis the maximum number of indirect draws that can be executed by any COUNT-type multi-draw indirect tokens. The draw count in the indirect buffer is clamped to this value for these token types.
If sequenceCountAddress is not NULL, then maxSequenceCount is
the maximum number of sequences that can be executed.
The actual number is min(maxSequenceCount, *sequenceCountAddress).
If sequenceCountAddress is NULL, then maxSequenceCount is the
exact number of sequences to execute.
If the action command token for the layout is not a COUNT-type multi-draw
indirect token, maxDrawCount is ignored.
Referencing the functions defined in Indirect Commands Layout,
vkCmdExecuteGeneratedCommandsEXT behaves as:
uint32_t sequencesCount = sequenceCountAddress ?
min(maxSequenceCount, sequenceCountAddress.load_uint32()) :
maxSequenceCount;
cmdProcessAllSequences(commandBuffer, indirectExecutionSet,
indirectCommandsLayout, indirectAddress,
sequencesCount);
// 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 affected values of all state related to the
|
Commands can be preprocessed prior execution using the following command:
// Provided by VK_EXT_device_generated_commands
void vkCmdPreprocessGeneratedCommandsEXT(
VkCommandBuffer commandBuffer,
const VkGeneratedCommandsInfoEXT* pGeneratedCommandsInfo,
VkCommandBuffer stateCommandBuffer);
-
commandBufferis the command buffer which does the preprocessing. -
pGeneratedCommandsInfois a pointer to a VkGeneratedCommandsInfoEXT structure containing parameters affecting the preprocessing step. -
stateCommandBufferis a command buffer from which to snapshot current states affecting the preprocessing step. When a graphics command action token is used, graphics state is snapshotted. When a compute action command token is used, compute state is snapshotted. When a ray tracing action command token is used, ray tracing state is snapshotted. It can be deleted at any time after this command has been recorded.
|
Note
|
|
The bound descriptor sets and push constants that will be used with indirect
command generation must already be specified on stateCommandBuffer at
the time of preprocessing commands with
vkCmdPreprocessGeneratedCommandsEXT.
They must match the bound descriptor sets and push constants used in the
execution of indirect commands with vkCmdExecuteGeneratedCommandsEXT.
If push constants for shader stages are also specified in the
VkGeneratedCommandsInfoEXT::indirectCommandsLayout with a
VK_INDIRECT_COMMANDS_TOKEN_TYPE_PUSH_CONSTANT_EXT or
VK_INDIRECT_COMMANDS_TOKEN_TYPE_SEQUENCE_INDEX_EXT token, then those
values override the push constants that were previously pushed.
All state bound on stateCommandBuffer will be used.
All state bound on stateCommandBuffer must be identical to the state
bound at the time vkCmdExecuteGeneratedCommandsEXT is recorded.
The queue family index stateCommandBuffer was allocated from must be
the same as the queue family index of the command buffer used in
vkCmdExecuteGeneratedCommandsEXT.
On some implementations, preprocessing may have no effect on performance.
vkCmdExecuteGeneratedCommandsEXT may write to the preprocess buffer, no matter the isPreprocess parameter. In this case, the implementation must insert appropriate synchronization automatically, which corresponds to the following pseudocode:
-
Barrier
-
srcStageMask = DRAW_INDIRECT
-
srcAccesMask = 0
-
dstStageMask = COMMAND_PREPROCESS_BIT
-
dstAccessMask = COMMAND_PREPROCESS_WRITE_BIT | COMMAND_PREPROCESS_READ_BIT
-
-
Do internal writes
-
Barrier
-
srcStageMask = COMMAND_PREPROCESS_BIT
-
srcAccesMask = COMMAND_PREPROCESS_WRITE_BIT
-
dstStageMask = DRAW_INDIRECT
-
dstAccessMask = INDIRECT_COMMAND_READ_BIT
-
-
Execute
34. 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.
34.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.
34.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.
34.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.
34.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.
After creating a VkBuffer with
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, the entire buffer region is
considered unbound.
34.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.
After creating a VkImage with
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, all image subresources are
considered unbound.
|
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. |
34.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.
If a value was previously written to the same unbound sparse memory location
in the same shader invocation, that value may be returned instead; using
the VolatileTexel image operand, the Volatile memory semantic, or
the Volatile decoration to load the value will prevent prior stored
values from being returned.
|
Note
|
Getting the value of the previous store is possible as implementations are free to optimize multiple accesses in the general case. There are other ways this can be prevented, but using volatile loads is by far the simplest. |
See Physical Device Enumeration for instructions for retrieving physical device properties.
34.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.
34.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.
34.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.
34.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.
34.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. |
34.7. Sparse Resource API
The APIs related to sparse resources are grouped into the following categories:
34.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.
34.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.
34.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 describes properties for one set of image aspects that are
bound simultaneously for a VkImage created with the provided image
creation parameters.
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.
|
Warning
|
This functionality is deprecated by Vulkan Version 1.1. See Deprecated Functionality for more information. |
// 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 the 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
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If pPropertyCount is less than the number of 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 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 describes properties for one set of image aspects that are
bound simultaneously for a VkImage created with the provided image
creation parameters.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatis the image format. -
typeis the dimensionality of the 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 a VkStructureType value identifying 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.
34.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 |
34.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 binding granularity in bytes and the 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 binding
granularity 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 application 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 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 a VkImageSparseMemoryRequirementsInfo2 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.
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 a VkStructureType value identifying 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryRequirementsis a VkSparseImageMemoryRequirements structure describing the memory requirements of the sparse image.
34.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 structure 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. If the If the |
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
35. 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.
35.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.
35.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 |
35.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 a VkAndroidSurfaceCreateInfoKHR 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.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
windowis a pointer to the ANativeWindow to 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.
35.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 a VkStructureType value identifying 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
The wl_surface.attach, wl_surface.damage, and
wl_surface.commit requests 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.
The implementation must ensure that no wp_color_management_surface_v1
object exists for a surface, which has no swapchains, or only swapchains
with a imageColorSpace of VK_COLOR_SPACE_PASS_THROUGH_EXT
associated with it.
// 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.
35.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 a VkWin32SurfaceCreateInfoKHR 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.
Some Vulkan functions may call the SendMessage system API when
interacting with a VkSurfaceKHR through a VkSwapchainKHR.
In a multithreaded environment, calling SendMessage from a thread that is
not the thread associated with pCreateInfo->hwnd will block until the
application has processed the window message.
Thus, applications should either call these Vulkan functions on the message
pump thread, or make sure their message pump is actively running.
Failing to do so may result in deadlocks.
The functions subject to this requirement are:
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 a VkStructureType value identifying 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,
unless VkSwapchainPresentScalingCreateInfoKHR is used to specify
handling of disparities between surface and swapchain dimensions,
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.
35.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 a VkXcbSurfaceCreateInfoKHR 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 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 a VkStructureType value identifying 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,
unless VkSwapchainPresentScalingCreateInfoKHR is used to specify
handling of disparities between surface and swapchain dimensions,
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.
35.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 a VkXlibSurfaceCreateInfoKHR structure 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 a VkStructureType value identifying 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,
unless VkSwapchainPresentScalingCreateInfoKHR is used to specify
handling of disparities between surface and swapchain dimensions,
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.
35.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 a VkDirectFBSurfaceCreateInfoEXT 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 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 a VkStructureType value identifying 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.
35.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 a VkStructureType value identifying 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.
35.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 a VkStructureType value identifying 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.
35.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);
-
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.
|
Note
|
The |
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
pViewis a reference to either a CAMetalLayer object 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.
35.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);
-
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.
|
Note
|
The |
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
pViewis a reference to either a CAMetalLayer object 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.
35.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 a VkViSurfaceCreateInfoNN 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.
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 a VkStructureType value identifying 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.
35.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 a VkSurfaceKHR handle 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
pLayeris a reference to a CAMetalLayer object 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.
35.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 a VkStructureType value identifying 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.
35.2.14. Open Harmony OS Platform Surface Creation
To create a VkSurfaceKHR object on Open Harmony OS platform, call:
// Provided by VK_OHOS_surface
VkResult vkCreateSurfaceOHOS(
VkInstance instance,
const VkSurfaceCreateInfoOHOS* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instanceis the instance to associate the surface with. -
pCreateInfois a pointer to a VkOHSurfaceCreateInfoOHOS 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 VkOHSurfaceCreateInfoOHOS structure is defined as:
// Provided by VK_OHOS_surface
typedef struct VkOHSurfaceCreateInfoOHOS {
VkStructureType sType;
const void* pNext;
VkSurfaceCreateFlagsOHOS flags;
OHNativeWindow* window;
} VkOHSurfaceCreateInfoOHOS;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
window: the pointer to a OHNativeWindow to associate the surface with.
or the equivalent
// Provided by VK_OHOS_surface
typedef VkOHSurfaceCreateInfoOHOS VkSurfaceCreateInfoOHOS;
The VkSurfaceCreateInfoOHOS structure is an alias to
VkOHSurfaceCreateInfoOHOS.
The OHNativeWindow structure is defined as:
// Provided by VK_OHOS_surface
typedef struct NativeWindow OHNativeWindow;
It is the native window structure on Open Harmony OS platform. It is exposed by the Open Harmony OS NDK.
// Provided by VK_OHOS_surface
typedef VkFlags VkSurfaceCreateFlagsOHOS;
The VkSurfaceCreateFlagsOHOS a bitmask type for setting a mask, but is
currently a reserved flag for future use.
35.2.15. 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.
35.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.
35.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 of VkDisplayPropertiesKHR structures.
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
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If 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 a VkStructureType value identifying 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 appropriate 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 behavior.
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
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
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If 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 a VkStructureType value identifying 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
application 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
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If 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 a VkStructureType value identifying 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 |
The VkDisplayModeStereoPropertiesNV structure is defined as:
// Provided by VK_NV_display_stereo
typedef struct VkDisplayModeStereoPropertiesNV {
VkStructureType sType;
const void* pNext;
VkBool32 hdmi3DSupported;
} VkDisplayModeStereoPropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
hdmi3DSupportedindicates whether this display mode can be used for a display surface configured forVK_DISPLAY_SURFACE_STEREO_TYPE_HDMI_3D_NV.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
capabilitiesis a VkDisplayPlaneCapabilitiesKHR structure.
35.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 a VkStructureType value identifying 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.
35.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 a VkStructureType value identifying 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.
The VkDisplaySurfaceStereoCreateInfoNV structure is defined as:
// Provided by VK_NV_display_stereo
typedef struct VkDisplaySurfaceStereoCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkDisplaySurfaceStereoTypeNV stereoType;
} VkDisplaySurfaceStereoCreateInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stereoTypeis a VkDisplaySurfaceStereoTypeNV value specifying the type of 3D stereo presentation the display will be configured for.
Possible values of
VkDisplaySurfaceStereoCreateInfoNV::stereoType, specifying the
type of 3D stereo presentation the display will be configured for, are:
// Provided by VK_NV_display_stereo
typedef enum VkDisplaySurfaceStereoTypeNV {
VK_DISPLAY_SURFACE_STEREO_TYPE_NONE_NV = 0,
VK_DISPLAY_SURFACE_STEREO_TYPE_ONBOARD_DIN_NV = 1,
VK_DISPLAY_SURFACE_STEREO_TYPE_HDMI_3D_NV = 2,
VK_DISPLAY_SURFACE_STEREO_TYPE_INBAND_DISPLAYPORT_NV = 3,
} VkDisplaySurfaceStereoTypeNV;
-
VK_DISPLAY_SURFACE_STEREO_TYPE_NONE_NVspecifies no configuration for stereo presentation. This is the default behavior if VkDisplaySurfaceStereoCreateInfoNV is not provided. -
VK_DISPLAY_SURFACE_STEREO_TYPE_ONBOARD_DIN_NVspecifies configuration for glasses that connect via a DIN connector on the back of the graphics card. -
VK_DISPLAY_SURFACE_STEREO_TYPE_HDMI_3D_NVspecifies configuration for HDMI 3D compatible display devices with their own stereo emitters. This is also known as HDMI Frame Packed Stereo, where the left and right eye images are stacked into a single frame with a doubled pixel clock and refresh rate. -
VK_DISPLAY_SURFACE_STEREO_TYPE_INBAND_DISPLAYPORT_NVspecifies configuration for DisplayPort display devices with in-band stereo signaling and emitters.
35.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 customizable 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 a VkSurfaceKHR handle 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 a VkStructureType value identifying 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.
35.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 a VkBool32.VK_TRUEindicates support, andVK_FALSEindicates no support.
35.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.
35.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.
35.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.
35.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.
35.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.
35.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.
35.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.
35.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.
35.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.
35.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.
35.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.
35.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.
35.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. |
35.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_FIFO_LATEST_READY_KHR,VK_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 a VkStructureType value identifying 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 a VkStructureType value identifying 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_EXTspecifies that the implementation should determine the appropriate full-screen method by whatever means it deems appropriate. -
VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXTspecifies that 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_EXTspecifies that the implementation should avoid using full-screen mechanisms which rely on disruptive transitions. -
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXTspecifies that 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 a VkStructureType value identifying 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
surfaceCapabilitiesis a VkSurfaceCapabilitiesKHR structure describing the capabilities of the specified surface.
If the VK_GOOGLE_surfaceless_query extension is enabled and
VkPhysicalDeviceSurfaceInfo2KHR::surface in the
vkGetPhysicalDeviceSurfaceCapabilities2KHR call is
VK_NULL_HANDLE, the values returned in minImageCount,
maxImageCount, currentExtent, and currentTransform will
not reflect that of any surface and will instead be as such:
-
minImageCountandmaxImageCountwill be 0xFFFFFFFF -
currentExtentwill be (0xFFFFFFFF, 0xFFFFFFFF) -
currentTransformwill beVK_SURFACE_TRANSFORM_INHERIT_BIT_KHR
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 a VkStructureType value identifying 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 structure chained to it will be undefined.
The VkSurfacePresentScalingCapabilitiesKHR structure is defined as:
// Provided by VK_KHR_surface_maintenance1
typedef struct VkSurfacePresentScalingCapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkPresentScalingFlagsKHR supportedPresentScaling;
VkPresentGravityFlagsKHR supportedPresentGravityX;
VkPresentGravityFlagsKHR supportedPresentGravityY;
VkExtent2D minScaledImageExtent;
VkExtent2D maxScaledImageExtent;
} VkSurfacePresentScalingCapabilitiesKHR;
or the equivalent
// Provided by VK_EXT_surface_maintenance1
typedef VkSurfacePresentScalingCapabilitiesKHR VkSurfacePresentScalingCapabilitiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
supportedPresentScalingis a bitmask of VkPresentScalingFlagBitsKHR representing the scaling methods supported by the surface, or0if application-defined scaling is not supported. -
supportedPresentGravityXis a bitmask of VkPresentGravityFlagBitsKHR representing the X-axis pixel gravity supported by the surface, or0if Vulkan-defined pixel gravity is not supported for the X axis. -
supportedPresentGravityYis a bitmask of VkPresentGravityFlagBitsKHR representing the Y-axis pixel gravity supported by the surface, or0if Vulkan-defined pixel gravity is not supported for the Y axis. -
minScaledImageExtentcontains the smallest valid swapchain extent for the surface on the specified device when one of the scaling methods specified insupportedPresentScalingis used, or the special value (0xFFFFFFFF, 0xFFFFFFFF) indicating that the surface size will be determined by the extent of a swapchain targeting the surface. Thewidthandheightof the extent will each be smaller than or equal to the correspondingwidthandheightof VkSurfaceCapabilitiesKHR::minImageExtent. -
maxScaledImageExtentcontains the largest valid swapchain extent for the surface on the specified device when one of the scaling methods specified insupportedPresentScalingis used, or the special value described above forminScaledImageExtent. Thewidthandheightof the extent will each be greater than or equal to the correspondingwidthandheightof VkSurfaceCapabilitiesKHR::maxImageExtent.
To query the set of supported scaling modes for a given present mode, add a
VkSurfacePresentModeKHR structure in the pNext chain of
VkPhysicalDeviceSurfaceInfo2KHR when calling
vkGetPhysicalDeviceSurfaceCapabilities2KHR.
The implementation must return the same values in
VkSurfacePresentScalingCapabilitiesKHR for any of the compatible
present modes as obtained through
VkSurfacePresentModeCompatibilityKHR.
The application can specify the scaling mode when creating a swapchain through the use of VkSwapchainPresentScalingCreateInfoKHR.
Bits which may be set in
VkSurfacePresentScalingCapabilitiesKHR::supportedPresentScaling,
specifying scaling modes supported by the surface, are:
// Provided by VK_KHR_surface_maintenance1
typedef enum VkPresentScalingFlagBitsKHR {
VK_PRESENT_SCALING_ONE_TO_ONE_BIT_KHR = 0x00000001,
VK_PRESENT_SCALING_ASPECT_RATIO_STRETCH_BIT_KHR = 0x00000002,
VK_PRESENT_SCALING_STRETCH_BIT_KHR = 0x00000004,
VK_PRESENT_SCALING_ONE_TO_ONE_BIT_EXT = VK_PRESENT_SCALING_ONE_TO_ONE_BIT_KHR,
VK_PRESENT_SCALING_ASPECT_RATIO_STRETCH_BIT_EXT = VK_PRESENT_SCALING_ASPECT_RATIO_STRETCH_BIT_KHR,
VK_PRESENT_SCALING_STRETCH_BIT_EXT = VK_PRESENT_SCALING_STRETCH_BIT_KHR,
} VkPresentScalingFlagBitsKHR;
or the equivalent
// Provided by VK_EXT_surface_maintenance1
typedef VkPresentScalingFlagBitsKHR VkPresentScalingFlagBitsEXT;
-
VK_PRESENT_SCALING_ONE_TO_ONE_BIT_KHRspecifies that no scaling occurs, and pixels in the swapchain image are mapped to one and only one pixel in the surface. The mapping between pixels is defined by the chosen presentation gravity. -
VK_PRESENT_SCALING_ASPECT_RATIO_STRETCH_BIT_KHRspecifies that the swapchain image will be minified or magnified such that at least one of the resulting width or height is equal to the corresponding surface dimension, and the other resulting dimension is less than or equal to the corresponding surface dimension, with the aspect ratio of the resulting image being identical to that of the original swapchain image. -
VK_PRESENT_SCALING_STRETCH_BIT_KHRspecifies that the swapchain image will be minified or magnified such that the resulting image dimensions are equal to those of the surface.
// Provided by VK_KHR_surface_maintenance1
typedef VkFlags VkPresentScalingFlagsKHR;
or the equivalent
// Provided by VK_EXT_surface_maintenance1
typedef VkPresentScalingFlagsKHR VkPresentScalingFlagsEXT;
VkPresentScalingFlagsKHR is a bitmask type for setting a mask of zero
or more VkPresentScalingFlagBitsKHR.
Bits which may be set in the
VkSurfacePresentScalingCapabilitiesKHR::supportedPresentGravityX
or supportedPresentGravityY fields, specifying the gravity of
presented pixels supported by the surface, are:
// Provided by VK_KHR_surface_maintenance1
typedef enum VkPresentGravityFlagBitsKHR {
VK_PRESENT_GRAVITY_MIN_BIT_KHR = 0x00000001,
VK_PRESENT_GRAVITY_MAX_BIT_KHR = 0x00000002,
VK_PRESENT_GRAVITY_CENTERED_BIT_KHR = 0x00000004,
VK_PRESENT_GRAVITY_MIN_BIT_EXT = VK_PRESENT_GRAVITY_MIN_BIT_KHR,
VK_PRESENT_GRAVITY_MAX_BIT_EXT = VK_PRESENT_GRAVITY_MAX_BIT_KHR,
VK_PRESENT_GRAVITY_CENTERED_BIT_EXT = VK_PRESENT_GRAVITY_CENTERED_BIT_KHR,
} VkPresentGravityFlagBitsKHR;
or the equivalent
// Provided by VK_EXT_surface_maintenance1
typedef VkPresentGravityFlagBitsKHR VkPresentGravityFlagBitsEXT;
-
VK_PRESENT_GRAVITY_MIN_BIT_KHRmeans that the pixels will gravitate towards the top or left side of the surface. -
VK_PRESENT_GRAVITY_MAX_BIT_KHRmeans that the pixels will gravitate towards the bottom or right side of the surface. -
VK_PRESENT_GRAVITY_CENTERED_BIT_KHRmeans that the pixels will be centered in the surface.
If the value in VkSurfaceCapabilitiesKHR::currentTransform is
not VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, it is
implementation-defined whether the gravity configuration applies to the
presented image before or after transformation.
// Provided by VK_KHR_surface_maintenance1
typedef VkFlags VkPresentGravityFlagsKHR;
or the equivalent
// Provided by VK_EXT_surface_maintenance1
typedef VkPresentGravityFlagsKHR VkPresentGravityFlagsEXT;
VkPresentGravityFlagsKHR is a bitmask type for setting a mask of zero
or more VkPresentGravityFlagBitsKHR.
The VkSurfacePresentModeKHR structure is defined as:
// Provided by VK_KHR_surface_maintenance1
typedef struct VkSurfacePresentModeKHR {
VkStructureType sType;
void* pNext;
VkPresentModeKHR presentMode;
} VkSurfacePresentModeKHR;
or the equivalent
// Provided by VK_EXT_surface_maintenance1
typedef VkSurfacePresentModeKHR VkSurfacePresentModeEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentModeis the presentation mode the swapchain will use.
If the VkSurfacePresentModeKHR structure is included in the
pNext chain of VkPhysicalDeviceSurfaceInfo2KHR, the values
returned in VkSurfaceCapabilitiesKHR::minImageCount,
VkSurfaceCapabilitiesKHR::maxImageCount,
VkSurfacePresentScalingCapabilitiesKHR::minScaledImageExtent,
and VkSurfacePresentScalingCapabilitiesKHR::maxScaledImageExtent
are valid only for the specified presentMode.
If presentMode is VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, the per-present mode
image counts must both be one.
The per-present mode image counts may be less-than or greater-than the
image counts returned when VkSurfacePresentModeKHR is not provided.
|
Note
|
If VkSwapchainPresentModesCreateInfoKHR is provided to swapchain
creation, the requirements for forward progress may be less strict.
For example, a FIFO swapchain might only require 2 images to guarantee
forward progress, but a MAILBOX one might require 4.
Without the per-present image counts, such an implementation would have to
return 4 in VkSurfaceCapabilitiesKHR:: VkSwapchainPresentModesCreateInfoKHR is required for the specification to be backwards compatible with applications that do not know about, or make use of this feature. |
The VkSurfacePresentModeCompatibilityKHR structure is defined as:
// Provided by VK_KHR_surface_maintenance1
typedef struct VkSurfacePresentModeCompatibilityKHR {
VkStructureType sType;
void* pNext;
uint32_t presentModeCount;
VkPresentModeKHR* pPresentModes;
} VkSurfacePresentModeCompatibilityKHR;
or the equivalent
// Provided by VK_EXT_surface_maintenance1
typedef VkSurfacePresentModeCompatibilityKHR VkSurfacePresentModeCompatibilityEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentModeCountis an integer related to the number of present modes available or queried, as described below. -
pPresentModesis a pointer to an array of VkPresentModeKHR in which present modes compatible with a given present mode are returned.
If pPresentModes is NULL, then the number of present modes that are
compatible with the one specified in VkSurfacePresentModeKHR is
returned in presentModeCount.
Otherwise, presentModeCount must point to a variable set by the
application 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 presentModeCount is less than the number of compatible
present modes that are supported, at most presentModeCount values will
be written to pPresentModes.
The implementation must include the present mode passed to
VkSurfacePresentModeKHR in pPresentModes, unless
presentModeCount is zero.
To query the set of present modes compatible with a given initial present
mode, add a VkSurfacePresentModeKHR structure in the pNext chain
of VkPhysicalDeviceSurfaceInfo2KHR when calling
vkGetPhysicalDeviceSurfaceCapabilities2KHR.
The application can create a swapchain whose present mode can be modified through the use of VkSwapchainPresentModesCreateInfoKHR.
The VkSharedPresentSurfaceCapabilitiesKHR structure is defined as:
-
sTypeis a VkStructureType value identifying 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 a VkStructureType value identifying 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 overridden 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fullScreenExclusiveSupportedis 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.
The VkSurfaceCapabilitiesPresentBarrierNV structure is defined as:
// Provided by VK_NV_present_barrier
typedef struct VkSurfaceCapabilitiesPresentBarrierNV {
VkStructureType sType;
void* pNext;
VkBool32 presentBarrierSupported;
} VkSurfaceCapabilitiesPresentBarrierNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentBarrierSupportedis a boolean describing whether the surface is able to make use of the present barrier feature.
This structure can be included in the pNext chain of
VkSurfaceCapabilities2KHR to determine support for present barrier
access.
If presentBarrierSupported is VK_FALSE, it indicates that the
present barrier feature is not obtainable for this surface.
The VkSurfaceCapabilitiesPresentId2KHR structure is defined as:
// Provided by VK_KHR_present_id2
typedef struct VkSurfaceCapabilitiesPresentId2KHR {
VkStructureType sType;
void* pNext;
VkBool32 presentId2Supported;
} VkSurfaceCapabilitiesPresentId2KHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentId2Supportedis a boolean describing whether the surface is able to support the present-ID extension
This structure can be included in the pNext chain of
VkSurfaceCapabilities2KHR to determine support for present-wait.
If presentId2Supported is VK_FALSE, it indicates that attaching
an ID to presentation requests is not possible for this surface.
Applications must not attempt to include VkPresentId2KHR in the
pNext chain of a VkPresentInfoKHR if presentId2Supported
is VK_FALSE.
The VkSurfaceCapabilitiesPresentWait2KHR structure is defined as:
// Provided by VK_KHR_present_wait2
typedef struct VkSurfaceCapabilitiesPresentWait2KHR {
VkStructureType sType;
void* pNext;
VkBool32 presentWait2Supported;
} VkSurfaceCapabilitiesPresentWait2KHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentWait2Supportedis a boolean describing whether the surface is able to support the present-wait extension
This structure can be included in the pNext chain of
VkSurfaceCapabilities2KHR to determine support for present-wait.
If presentWait2Supported is VK_FALSE, it indicates that waiting
for presentation is not possible for this surface.
Applications must not attempt to call vkWaitForPresent2KHR on a
swapchain if presentWait2Supported 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 a VkStructureType value identifying 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_FIFO_LATEST_READY_KHR,VK_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 is a deprecated alias
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.
35.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
application 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
application 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 a VkStructureType value identifying 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
transfer functions indicating the mapping between the image data and the
colorimetry with respect to the given color space.
Possible values of VkSurfaceFormatKHR::colorSpace, specifying
the color spaces that a presentation engine can accept, 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 is deprecated, but no reason was given in the API XML
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 is a deprecated alias
VK_COLORSPACE_SRGB_NONLINEAR_KHR = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR,
// Provided by VK_EXT_swapchain_colorspace
// VK_COLOR_SPACE_DCI_P3_LINEAR_EXT is a deprecated alias
VK_COLOR_SPACE_DCI_P3_LINEAR_EXT = VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT,
} VkColorSpaceKHR;
-
VK_COLOR_SPACE_SRGB_NONLINEAR_KHRspecifies support for the images in sRGB color space, encoded according to the sRGB specification. -
VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXTspecifies support for the images in Display-P3 color space, encoded using a Display-P3 transfer function. -
VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXTspecifies support for the images in extended sRGB color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXTspecifies support for the images in extended sRGB color space, encoded according to the scRGB specification. -
VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXTspecifies support for the images in Display-P3 color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXTspecifies support for the images in DCI-P3 color space, encoded according to the DCI-P3 specification. 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 images in BT709 color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_BT709_NONLINEAR_EXTspecifies support for the images in BT709 color space, encoded according to the BT709 specification. -
VK_COLOR_SPACE_BT2020_LINEAR_EXTspecifies support for the images in BT2020 color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_HDR10_ST2084_EXTspecifies support for the images in HDR10 (BT2020) color space, encoded according to SMPTE ST2084 Perceptual Quantizer (PQ) specification. -
VK_COLOR_SPACE_HDR10_HLG_EXTspecifies support for the images in HDR10 (BT2020) color space, encoded according to the Hybrid Log Gamma (HLG) specification. -
VK_COLOR_SPACE_ADOBERGB_LINEAR_EXTspecifies support for images in Adobe RGB color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXTspecifies support for the images in Adobe RGB color space, encoded according to the Adobe RGB specification (approximately Gamma 2.2). -
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
|
In older versions of the |
|
Note
|
For a traditional “Linear” or non-gamma transfer function color space use
|
|
Note
|
On Wayland, |
The presentation engine interprets the pixel values of the R, G, and B components as having been encoded using an appropriate transfer function. Applications should ensure that the appropriate transfer function has been applied. Textures Output Format Conversion requires that all implementations implicitly apply the sRGB EOTF-1 on R, G, and B components when shaders write to an sRGB pixel format image, which is useful for sRGB color spaces. For sRGB color spaces with other pixel formats, or other non-linear color spaces, applications can apply the transfer function explicitly in a shader. The A channel is always interpreted as linearly encoded.
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) |
BT709 |
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) |
scRGB |
HDR10_ST2084 |
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 |
Adobe RGB |
0.640, 0.330 |
0.210, 0.710 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
Adobe RGB |
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. |
35.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
application 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 and
surface is VK_NULL_HANDLE, the values returned in
pPresentModes will only indicate support for
VK_PRESENT_MODE_FIFO_KHR,
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR, and
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR.
To query support for any other present mode, a valid handle must be
provided in surface.
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,
// Provided by VK_KHR_present_mode_fifo_latest_ready
VK_PRESENT_MODE_FIFO_LATEST_READY_KHR = 1000361000,
// Provided by VK_EXT_present_mode_fifo_latest_ready
VK_PRESENT_MODE_FIFO_LATEST_READY_EXT = VK_PRESENT_MODE_FIFO_LATEST_READY_KHR,
} 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 reuse 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_FIFO_LATEST_READY_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. At each vertical blanking period, the presentation engine dequeues all successive requests that are ready to be presented from the beginning of the queue. If usingVK_GOOGLE_display_timingto provide a target present time, the presentation engine will check the specified time for each image. If the target present time is less-than or equal-to the current time, the presentation engine will dequeue the image and check the next one. The image of the last dequeued request will be presented. The other dequeued requests will be dropped. -
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:: |
|
VkSurfaceCapabilitiesKHR:: |
|
VkSharedPresentSurfaceCapabilitiesKHR:: |
|
VkSharedPresentSurfaceCapabilitiesKHR:: |
|
Note
|
For reference, the mode indicated by |
35.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 |
35.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 a VkStructureType value identifying 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_EXT_full_screen_exclusive with VK_KHR_device_group or VK_VERSION_1_1
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 application
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.
35.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_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.
ifndef::VK_KHR_present_wait2
35.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.
endif::VK_KHR_present_wait2
35.10. 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_wait2 extension allows applications to tell the
presentation engine at the vkQueuePresentKHR call that it plans on
waiting for presentation by passing a VkPresentId2KHR structure.
The presentId passed in that structure may then be passed to a future
vkWaitForPresent2KHR call to cause the application to block until that
presentation is finished.
This functionality was originally provided by the
VK_KHR_present_wait extension, which has been deprecated and
replaced by VK_KHR_present_wait2.
The VkPresentWait2InfoKHR structure is defined as:
// Provided by VK_KHR_present_wait2
typedef struct VkPresentWait2InfoKHR {
VkStructureType sType;
const void* pNext;
uint64_t presentId;
uint64_t timeout;
} VkPresentWait2InfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
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.
35.11. 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 application can also release the acquisition of the image through vkReleaseSwapchainImagesKHR, if the image is not in use by the device, and skip the present operation.
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 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 oldSwapchain is a valid swapchain and there are outstanding calls
to vkWaitForPresent2KHR, then vkCreateSwapchainKHR may block
until those calls complete.
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 |
If the pNext chain of VkSwapchainCreateInfoKHR includes a
VkSwapchainPresentBarrierCreateInfoNV structure, then that structure
includes additional swapchain creation parameters specific to the present
barrier.
Swapchain creation may fail if the state of the current system restricts
the usage of the present barrier feature
VkSurfaceCapabilitiesPresentBarrierNV, or a swapchain itself does not
satisfy all the required conditions.
In this scenario VK_ERROR_INITIALIZATION_FAILED is returned.
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 a VkStructureType value identifying 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 , unless scaling is selected through VkSwapchainPresentScalingCreateInfoKHR, if supported . -
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
clippedisVK_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
clippedisVK_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,
// Provided by VK_KHR_present_id2
VK_SWAPCHAIN_CREATE_PRESENT_ID_2_BIT_KHR = 0x00000040,
// Provided by VK_KHR_present_wait2
VK_SWAPCHAIN_CREATE_PRESENT_WAIT_2_BIT_KHR = 0x00000080,
// Provided by VK_KHR_swapchain_maintenance1
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR = 0x00000008,
// Provided by VK_EXT_swapchain_maintenance1
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT = VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR,
} 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. -
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHRspecifies that the implementation may defer allocation of memory associated with each swapchain image until its index is to be returned from vkAcquireNextImageKHR or vkAcquireNextImage2KHR for the first time. -
VK_SWAPCHAIN_CREATE_PRESENT_ID_2_BIT_KHRspecifies that applications can include theVkPresentId2KHRstructure in thepNextchain of the VkPresentInfoKHR structure to associate an identifier with each presentation request. -
VK_SWAPCHAIN_CREATE_PRESENT_WAIT_2_BIT_KHRspecifies that applications can usevkWaitForPresent2KHRto wait for the presentation engine to have begun presentation of the presentation request associated with VkPresentWait2InfoKHR::presentIdonswapchain.
// 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
Applications can modify the presentation mode used by the swapchain on a
per-presentation basis.
However, all presentation modes the application intends to use with the
swapchain must be specified at swapchain creation time.
To specify more than one presentation mode when creating a swapchain,
include the VkSwapchainPresentModesCreateInfoKHR structure in the
pNext chain of the VkSwapchainCreateInfoKHR structure.
The VkSwapchainPresentModesCreateInfoKHR structure is defined as:
// Provided by VK_KHR_swapchain_maintenance1
typedef struct VkSwapchainPresentModesCreateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t presentModeCount;
const VkPresentModeKHR* pPresentModes;
} VkSwapchainPresentModesCreateInfoKHR;
or the equivalent
// Provided by VK_EXT_swapchain_maintenance1
typedef VkSwapchainPresentModesCreateInfoKHR VkSwapchainPresentModesCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentModeCountis the number of presentation modes provided. -
pPresentModesis a list of presentation modes withpresentModeCountentries
When an application presents a swapchain image with dimensions different than those of the target surface, different behavior is possible on different platforms per their respective specifications:
-
Presentation fails and
VK_ERROR_OUT_OF_DATE_KHRis returned -
Scaling is done and
VK_SUCCESSorVK_SUBOPTIMAL_KHRis returned -
Unspecified scaling using an arbitrary combination of stretching, centering and/or clipping.
Applications can define specific behavior when creating a swapchain by
including the VkSwapchainPresentScalingCreateInfoKHR structure in the
pNext chain of the VkSwapchainCreateInfoKHR structure.
The VkSwapchainPresentScalingCreateInfoKHR structure is defined as:
// Provided by VK_KHR_swapchain_maintenance1
typedef struct VkSwapchainPresentScalingCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkPresentScalingFlagsKHR scalingBehavior;
VkPresentGravityFlagsKHR presentGravityX;
VkPresentGravityFlagsKHR presentGravityY;
} VkSwapchainPresentScalingCreateInfoKHR;
or the equivalent
// Provided by VK_EXT_swapchain_maintenance1
typedef VkSwapchainPresentScalingCreateInfoKHR VkSwapchainPresentScalingCreateInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
scalingBehavioris0or the scaling method to use when the dimensions of the surface and swapchain images differ. -
presentGravityXis0or the x-axis direction in which swapchain image pixels gravitate relative to the surface whenscalingBehaviordoes not result in a one-to-one pixel mapping between the scaled swapchain image and the surface. -
presentGravityYis0or the y-axis direction in which swapchain image pixels gravitate relative to the surface whenscalingBehaviordoes not result in a one-to-one pixel mapping between the scaled swapchain image and the surface.
If scalingBehavior is 0, the result of presenting a swapchain image
with dimensions that do not match the surface dimensions is implementation
and platform-dependent.
If presentGravityX or presentGravityY are 0, the presentation
gravity must match that defined by the native platform surface on platforms
which define surface gravity.
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
application 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.
However, command buffers are not allowed to reference presentable images
created with |
Images returned by vkGetSwapchainImagesKHR are fully backed by memory
before they are passed to the application, as if they are each bound
completely and contiguously to a single VkDeviceMemory object
, unless the swapchain is created with the
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR flag
.
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.
If the swapchain has been created with the
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR flag, the image
whose index is returned in pImageIndex will be fully backed by memory
before this call returns to the application, as if it is bound completely
and contiguously to a single VkDeviceMemory object.
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.
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.
Once vkAcquireNextImageKHR successfully acquires an image, the
semaphore signal operation referenced by semaphore, if not
VK_NULL_HANDLE, and the fence signal operation referenced by
fence, if not VK_NULL_HANDLE, are submitted for execution.
If vkAcquireNextImageKHR does not successfully acquire an image,
semaphore and fence are unaffected.
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.
Let S be the number of images in swapchain.
If swapchain is created with
VkSwapchainPresentModesCreateInfoKHR, let M be the maximum of
the values in VkSurfaceCapabilitiesKHR::minImageCount when
queried with each present mode in
VkSwapchainPresentModesCreateInfoKHR::pPresentModes in
VkSurfacePresentModeKHR.
Otherwise, let M be the value of
VkSurfaceCapabilitiesKHR::minImageCount without a
VkSurfacePresentModeKHR as part of the query input.
vkAcquireNextImageKHR should not be called if the number of images
that the application has currently acquired is greater than S-M.
If vkAcquireNextImageKHR is called when the number of images that the
application has currently acquired is less than or equal to S-M,
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 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.
|
Note
|
|
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
unless the swapchain is created with a non-zero value in
VkSwapchainPresentScalingCreateInfoKHR::scalingBehavior
.
If presentation does succeed, the mapping from the presented image to the
native surface is
defined by the VkSwapchainPresentScalingCreateInfoKHR structure if
provided.
Otherwise it 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_tvalue specifying the index of the next image to use.
If the swapchain has been created with the
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR flag, the image
whose index is returned in pImageIndex will be fully backed by memory
before this call returns to the application.
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 a VkStructureType value identifying 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. |
|
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
|
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 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.
If multiple swapchains are presented, the result code is determined by
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.
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.
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.
Calls to vkQueuePresentKHR may block, but must return in finite
time.
The processing of the presentation happens in issue order with other queue
operations, but semaphores must 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.
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.
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.
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.
|
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 |
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 a VkStructureType value identifying 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. -
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 the appropriate layout, there is no need to
delay subsequent processing, or perform any visibility operations (as
vkQueuePresentKHR performs automatic visibility operations).
To achieve this, the |
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 ofuint64_twithswapchainCountentries. 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 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 next image being presented 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 could not be 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.
The VkPresentId2KHR structure is defined as:
// Provided by VK_KHR_present_id2
typedef struct VkPresentId2KHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const uint64_t* pPresentIds;
} VkPresentId2KHR;
-
sTypeis a VkStructureType value identifying 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 VkSurfaceCapabilitiesPresentId2KHR surface capability is
present for a surface, applications can include the VkPresentId2KHR
structure in the pNext chain of the VkPresentInfoKHR structure
to associate an identifier with each presentation request.
The pPresentIds provides an identifier for the swapchain present at
the corresponding index in VkPresentInfoKHR’s 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.
If a non-zero presentId was provided, this may be used with vkWaitForPresent2KHR for the application to synchronize against the presentation engine’s processing of the presentation request.
|
Note
|
The ID namespace used by this extension must be shared with other extensions that allow the application to provide a 64-bit monotonically increasing presentation ID, such as the original VK_KHR_present_id. This is to allow existing extensions that depend on VK_KHR_present_id to use VK_KHR_present_id2 provided IDs without change, as well as to simplify writing future extensions that require application provided presentation IDs. |
When the VkSurfaceCapabilitiesPresentWait2KHR surface capability is
present for a given surface, 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 VkPresentId2KHR structure to the pNext
chain of the VkPresentInfoKHR structure and then waiting for that
presentation to complete by calling:
// Provided by VK_KHR_present_wait2
VkResult vkWaitForPresent2KHR(
VkDevice device,
VkSwapchainKHR swapchain,
const VkPresentWait2InfoKHR* pPresentWait2Info);
-
deviceis the device associated withswapchain. -
swapchainis the non-retired swapchain on which an image was queued for presentation. -
pPresentWait2Infois a pointer to a VkPresentWait2InfoKHR structure specifying the parameters of the wait.
vkWaitForPresent2KHR waits for the presentation engine to have begun
presentation of the presentation request associated with the
VkPresentWait2InfoKHR::presentId on swapchain, or for
VkPresentWait2InfoKHR::timeout to have expired.
The wait request will complete when the timeout expires, or after the corresponding presentation request has either taken effect within the presentation engine or has been replaced without presentation.
The timing relationship between the presentation of the image to the user and the wait request completing is implementation-dependent due to variations in window system implementations.
If the swapchain becomes VK_ERROR_OUT_OF_DATE_KHR either before
or during this call, the call may either return VK_SUCCESS (if the
image was delivered to the presentation engine and may have been presented
to the user) or return early with status VK_ERROR_OUT_OF_DATE_KHR (if
the image could not be presented to the user).
As an exception to the normal rules for objects which are externally
synchronized, the swapchain passed to vkWaitForPresent2KHR 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
frameTokenis the Google Games Platform frame token.
The VkSwapchainPresentModeInfoKHR structure is defined as:
// Provided by VK_KHR_swapchain_maintenance1
typedef struct VkSwapchainPresentModeInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const VkPresentModeKHR* pPresentModes;
} VkSwapchainPresentModeInfoKHR;
or the equivalent
// Provided by VK_EXT_swapchain_maintenance1
typedef VkSwapchainPresentModeInfoKHR VkSwapchainPresentModeInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainCountis the number of swapchains being presented to by this command. -
pPresentModesis a list of presentation modes withswapchainCountentries.
If the pNext chain of VkPresentInfoKHR includes a
VkSwapchainPresentModeInfoKHR structure, then that structure defines
the presentation modes used for the current and subsequent presentation
operations.
When the application changes present modes with VkSwapchainPresentModeInfoKHR, images that have already been queued for presentation will continue to be presented according to the previous present mode. The current image being queued for presentation and subsequent images will be presented according to the new present mode. The behavior during the transition between the two modes is defined as follows.
-
Transition from
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHRtoVK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR: the presentation engine updates the shared presentable image according to the behavior ofVK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR. -
Transition from
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHRtoVK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR: the presentation engine may update the shared presentable image or defer that to its regular refresh cycle, according to the behavior ofVK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR. -
Transition between
VK_PRESENT_MODE_FIFO_KHRandVK_PRESENT_MODE_FIFO_RELAXED_KHR: Images continue to be appended to the same FIFO queue, and the behavior with respect to waiting for vertical blanking period will follow the new mode for current and subsequent images. -
Transition from
VK_PRESENT_MODE_IMMEDIATE_KHRtoVK_PRESENT_MODE_FIFO_KHRorVK_PRESENT_MODE_FIFO_RELAXED_KHRorVK_PRESENT_MODE_FIFO_LATEST_READY_KHR: As all prior present requests in theVK_PRESENT_MODE_IMMEDIATE_KHRmode are applied immediately, there are no outstanding present operations in this mode, and current and subsequent images are appended to the FIFO queue and presented according to the new mode. -
Transition from
VK_PRESENT_MODE_MAILBOX_KHRtoVK_PRESENT_MODE_FIFO_KHRorVK_PRESENT_MODE_FIFO_RELAXED_KHRorVK_PRESENT_MODE_FIFO_LATEST_READY_KHR: Presentation in FIFO modes require waiting for the next vertical blanking period, withVK_PRESENT_MODE_MAILBOX_KHRallowing the pending present operation to be replaced by a new one. In this case, the current present operation will replace the pending present operation and is applied according to the new mode. -
Transition from
VK_PRESENT_MODE_FIFO_KHRorVK_PRESENT_MODE_FIFO_RELAXED_KHRorVK_PRESENT_MODE_FIFO_LATEST_READY_KHRtoVK_PRESENT_MODE_IMMEDIATE_KHRorVK_PRESENT_MODE_MAILBOX_KHR: If the FIFO queue is empty, presentation is done according to the behavior of the new mode. If there are present operations in the FIFO queue, once the last present operation is performed based on the respective vertical blanking period, the current and subsequent updates are applied according to the new mode. -
Transition between
VK_PRESENT_MODE_FIFO_KHRorVK_PRESENT_MODE_FIFO_RELAXED_KHR, andVK_PRESENT_MODE_FIFO_LATEST_READY_KHR: Images continue to be appended to the same FIFO queue, and the behavior with respect to waiting for vertical blanking period and dequeuing requests will follow the new mode for current and subsequent images. -
The behavior during transition between any other present modes, if possible, is implementation defined.
The VkSwapchainPresentFenceInfoKHR structure is defined as:
// Provided by VK_KHR_swapchain_maintenance1
typedef struct VkSwapchainPresentFenceInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const VkFence* pFences;
} VkSwapchainPresentFenceInfoKHR;
or the equivalent
// Provided by VK_EXT_swapchain_maintenance1
typedef VkSwapchainPresentFenceInfoKHR VkSwapchainPresentFenceInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainCountis the number of swapchains being presented to by this command. -
pFencesis a list of fences withswapchainCountentries. Each entry must be VK_NULL_HANDLE or the handle of a fence to signal when the relevant operations on the associated swapchain have completed.
The set of queue operations defined by queuing an image for presentation, as well as operations performed by the presentation engine access the payloads of objects associated with the presentation operation. The associated objects include:
-
The swapchain image, its implicitly bound memory, and any other resources bound to that memory.
-
The wait semaphores specified when queuing the image for presentation.
The application can provide a fence that the implementation will signal when all such queue operations have completed and the presentation engine has taken a reference to the payload of any objects it accesses as part of the present operation. For all binary wait semaphores imported by the presentation engine using the equivalent of reference transference, as described in Importing Semaphore Payloads, this fence must not signal until all such semaphore payloads have been reset by the presentation engine.
The application can destroy the wait semaphores associated with a given presentation operation when at least one of the associated fences is signaled, and can destroy the swapchain when the fences associated with all past presentation requests referring to that swapchain have signaled.
Fences associated with presentations to the same swapchain on the same VkQueue must be signaled in the same order as the present operations.
To specify a fence for each swapchain in a present operation, include the
VkSwapchainPresentFenceInfoKHR structure in the pNext chain of
the VkPresentInfoKHR structure.
To release images previously acquired through vkAcquireNextImage2KHR or vkAcquireNextImageKHR, call:
// Provided by VK_KHR_swapchain_maintenance1
VkResult vkReleaseSwapchainImagesKHR(
VkDevice device,
const VkReleaseSwapchainImagesInfoKHR* pReleaseInfo);
or the equivalent
// Provided by VK_EXT_swapchain_maintenance1
VkResult vkReleaseSwapchainImagesEXT(
VkDevice device,
const VkReleaseSwapchainImagesInfoKHR* pReleaseInfo);
-
deviceis the device associated with VkReleaseSwapchainImagesInfoKHR::swapchain. -
pReleaseInfois a pointer to a VkReleaseSwapchainImagesInfoKHR structure containing parameters of the release.
Only images that are not in use by the device can be released.
Releasing images is a read-only operation that will not affect the content of the released images. Upon reacquiring the image, the image contents and its layout will be the same as they were prior to releasing 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
|
This functionality is useful during swapchain recreation, where acquired images from the old swapchain can be released instead of presented. |
The VkReleaseSwapchainImagesInfoKHR structure is defined as:
// Provided by VK_KHR_swapchain_maintenance1
typedef struct VkReleaseSwapchainImagesInfoKHR {
VkStructureType sType;
const void* pNext;
VkSwapchainKHR swapchain;
uint32_t imageIndexCount;
const uint32_t* pImageIndices;
} VkReleaseSwapchainImagesInfoKHR;
or the equivalent
// Provided by VK_EXT_swapchain_maintenance1
typedef VkReleaseSwapchainImagesInfoKHR VkReleaseSwapchainImagesInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainis a swapchain to which images are being released. -
imageIndexCountis the number of image indices to be released. -
pImageIndicesis a pointer to an array of indices into the array ofswapchain’s presentable images, withimageIndexCountentries.
35.12. HDR Metadata
This section describes how to improve color reproduction of content to better reproduce colors as seen on the display used to originally optimize the content.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
displayPrimaryRedis a VkXYColorEXT structure specifying the red primary of the display used to optimize the content -
displayPrimaryGreenis a VkXYColorEXT structure specifying the green primary of the display used to optimize the content -
displayPrimaryBlueis a VkXYColorEXT structure specifying the blue primary of the display used to optimize the content -
whitePointis a VkXYColorEXT structure specifying the white-point of the display used to optimize the content -
maxLuminanceis the maximum luminance of the display used to optimize the content in nits -
minLuminanceis the minimum luminance of the display used to optimize the content in nits -
maxContentLightLevelis the value in nits of the desired luminance for the brightest pixels in the displayed image. -
maxFrameAverageLightLevelis the value in nits of the average luminance of the frame which has the brightest average luminance anywhere in the content.
If any of the above values are unknown, they can be set to 0.
|
Note
|
The meta-data provided here is intended to be used as defined in the SMPTE 2086, CTA 861.3 and CIE 15:2004 specifications. The validity and use of this data is outside the scope of Vulkan. |
When hdrVivid feature is enabled, HDR Vivid
dynamic metadata can be set to control the reproduction of content by
including the VkHdrVividDynamicMetadataHUAWEI in the pNext chain
of VkHdrMetadataEXT.
The VkHdrVividDynamicMetadataHUAWEI structure is defined as:
// Provided by VK_HUAWEI_hdr_vivid
typedef struct VkHdrVividDynamicMetadataHUAWEI {
VkStructureType sType;
const void* pNext;
size_t dynamicMetadataSize;
const void* pDynamicMetadata;
} VkHdrVividDynamicMetadataHUAWEI;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dynamicMetadataSizeis the size in bytes of the dynamic metadata. -
pDynamicMetadatais a pointer to the dynamic metadata.
|
Note
|
The HDR Vivid metadata is intended to be used as defined in the T/UWA 005.1-2022 specification. 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.
35.13. Lag Control
Some implementations support extensions to reduce display latency and control the swapchain present interval, as described in the remainder of this section.
35.13.1. Anti-Lag
The VK_AMD_anti_lag extension lowers latency between receiving input and displaying on the screen. It adds a command to indicate when input is being processed for a frame, and when that frame’s images are presented.
To lower latency, call:
// Provided by VK_AMD_anti_lag
void vkAntiLagUpdateAMD(
VkDevice device,
const VkAntiLagDataAMD* pData);
-
deviceis the logical device -
pDatais a pointer to a VkAntiLagDataAMD structure containing latency reduction parameters.
This command should be executed immediately before the application processes
user input.
If pData is not NULL and
VkAntiLagDataAMD::pPresentationInfo is not NULL, this command
should be executed again before vkQueuePresentKHR, with
pPresentationInfo set to matching values.
The VkAntiLagDataAMD structure is defined as:
// Provided by VK_AMD_anti_lag
typedef struct VkAntiLagDataAMD {
VkStructureType sType;
const void* pNext;
VkAntiLagModeAMD mode;
uint32_t maxFPS;
const VkAntiLagPresentationInfoAMD* pPresentationInfo;
} VkAntiLagDataAMD;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
modeis a VkAntiLagModeAMD value specifying the anti-lag status. -
maxFPSis the framerate limit, in frames per second, used by the application. This limit will be imposed if anti-lag is enabled. If the application tries to render faster, the framerate will be reduced to match this limit. A value of 0 will disable the limit. -
pPresentationInfois a pointer to a VkAntiLagPresentationInfoAMD structure containing information about the application stage.
This structure specifies anti-lag parameters.
Possible values of VkAntiLagDataAMD::mode, specifying the
anti-lag status, are:
// Provided by VK_AMD_anti_lag
typedef enum VkAntiLagModeAMD {
VK_ANTI_LAG_MODE_DRIVER_CONTROL_AMD = 0,
VK_ANTI_LAG_MODE_ON_AMD = 1,
VK_ANTI_LAG_MODE_OFF_AMD = 2,
} VkAntiLagModeAMD;
-
VK_ANTI_LAG_MODE_DRIVER_CONTROL_AMDspecifies that anti-lag will be enabled or disabled depending on driver settings. -
VK_ANTI_LAG_MODE_ON_AMDspecifies that anti-lag will be enabled. -
VK_ANTI_LAG_MODE_OFF_AMDspecifies that anti-lag will be disabled.
The VkAntiLagPresentationInfoAMD structure is defined as:
// Provided by VK_AMD_anti_lag
typedef struct VkAntiLagPresentationInfoAMD {
VkStructureType sType;
void* pNext;
VkAntiLagStageAMD stage;
uint64_t frameIndex;
} VkAntiLagPresentationInfoAMD;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stageis a VkAntiLagStageAMD value specifying the current application stage. -
frameIndexis set just before the application processes input data (VK_ANTI_LAG_STAGE_INPUT_AMD). The sameframeIndexvalue should be set before the frame with current input data will be presented by vkQueuePresentKHR (VK_ANTI_LAG_STAGE_PRESENT_AMD). This should be done for each frame.
This structure specifies information about the presentation stage for which anti-lag parameters are being set.
Possible values of VkAntiLagPresentationInfoAMD::stage,
specifying the current application stage, are:
// Provided by VK_AMD_anti_lag
typedef enum VkAntiLagStageAMD {
VK_ANTI_LAG_STAGE_INPUT_AMD = 0,
VK_ANTI_LAG_STAGE_PRESENT_AMD = 1,
} VkAntiLagStageAMD;
-
VK_ANTI_LAG_STAGE_INPUT_AMDspecifies the stage before processing input. -
VK_ANTI_LAG_STAGE_PRESENT_AMDspecifies the stage before vkQueuePresentKHR.
35.13.2. Latency Reduction
To enable or disable low latency mode on a swapchain, call:
// Provided by VK_NV_low_latency2
VkResult vkSetLatencySleepModeNV(
VkDevice device,
VkSwapchainKHR swapchain,
const VkLatencySleepModeInfoNV* pSleepModeInfo);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to enable or disable low latency mode on. -
pSleepModeInfoisNULLor a pointer to a VkLatencySleepModeInfoNV structure specifying the parameters of the latency sleep mode.
If pSleepModeInfo is NULL, vkSetLatencySleepModeNV will
disable low latency mode, low latency boost, and set the minimum present
interval previously specified by VkLatencySleepModeInfoNV to zero on
swapchain.
As an exception to the normal rules for objects which are externally
synchronized, the swapchain passed to vkSetLatencySleepModeNV 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.
The VkLatencySleepModeInfoNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkLatencySleepModeInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 lowLatencyMode;
VkBool32 lowLatencyBoost;
uint32_t minimumIntervalUs;
} VkLatencySleepModeInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
lowLatencyModeis the toggle to enable or disable low latency mode. -
lowLatencyBoostallows an application to hint to the GPU to increase performance to provide additional latency savings at a cost of increased power consumption. -
minimumIntervalUsis the microseconds between vkQueuePresentKHR calls for a given swapchain that vkLatencySleepNV will enforce.
If lowLatencyMode is VK_FALSE, lowLatencyBoost will still
hint to the GPU to increase its power state and vkLatencySleepNV will
still enforce minimumIntervalUs between vkQueuePresentKHR calls.
To provide the synchronization primitive used to delay host CPU work for lower latency rendering, call:
// Provided by VK_NV_low_latency2
VkResult vkLatencySleepNV(
VkDevice device,
VkSwapchainKHR swapchain,
const VkLatencySleepInfoNV* pSleepInfo);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to delay associated CPU work based on VkLatencySubmissionPresentIdNV submissions. -
pSleepInfois a pointer to a VkLatencySleepInfoNV structure specifying the parameters of the latency sleep.
vkLatencySleepNV returns immediately.
Applications should use vkWaitSemaphores with
pSleepInfo->signalSemaphore to delay host CPU work.
CPU work refers to application work done before presenting which includes
but is not limited to: input sampling, simulation, command buffer recording,
command buffer submission, and present submission.
Applications should call this function before input sampling, and exactly
once between presents.
The VkLatencySleepInfoNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkLatencySleepInfoNV {
VkStructureType sType;
const void* pNext;
VkSemaphore signalSemaphore;
uint64_t value;
} VkLatencySleepInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
signalSemaphoreis a semaphore that is signaled to indicate that the application should resume input sampling work. -
valueis the value thatsignalSemaphoreis set to for resuming sampling work.
An application can provide timestamps at various stages of its frame generation work by calling:
// Provided by VK_NV_low_latency2
void vkSetLatencyMarkerNV(
VkDevice device,
VkSwapchainKHR swapchain,
const VkSetLatencyMarkerInfoNV* pLatencyMarkerInfo);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to capture timestamps on. -
pSetLatencyMarkerInfois a pointer to a VkSetLatencyMarkerInfoNV structure specifying the parameters of the marker to set.
At the beginning and end of simulation and render threads and beginning and
end of vkQueuePresentKHR calls, vkSetLatencyMarkerNV can be
called to provide timestamps for the application’s reference.
These timestamps are returned with a call to vkGetLatencyTimingsNV
alongside driver provided timestamps at various points of interest with
regards to latency within the application.
As an exception to the normal rules for objects which are externally
synchronized, the swapchain passed to vkSetLatencyMarkerNV 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.
The VkSetLatencyMarkerInfoNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkSetLatencyMarkerInfoNV {
VkStructureType sType;
const void* pNext;
uint64_t presentID;
VkLatencyMarkerNV marker;
} VkSetLatencyMarkerInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentIDis an application provided value that is used to associate the timestamp with avkQueuePresentKHRcommand using VkPresentIdKHR::pPresentIdsor VkPresentId2KHR::pPresentIdsfor a given present. -
markeris the type of timestamp to be recorded.
The VkLatencyMarkerNV enum is defined as:
// Provided by VK_NV_low_latency2
typedef enum VkLatencyMarkerNV {
VK_LATENCY_MARKER_SIMULATION_START_NV = 0,
VK_LATENCY_MARKER_SIMULATION_END_NV = 1,
VK_LATENCY_MARKER_RENDERSUBMIT_START_NV = 2,
VK_LATENCY_MARKER_RENDERSUBMIT_END_NV = 3,
VK_LATENCY_MARKER_PRESENT_START_NV = 4,
VK_LATENCY_MARKER_PRESENT_END_NV = 5,
VK_LATENCY_MARKER_INPUT_SAMPLE_NV = 6,
VK_LATENCY_MARKER_TRIGGER_FLASH_NV = 7,
VK_LATENCY_MARKER_OUT_OF_BAND_RENDERSUBMIT_START_NV = 8,
VK_LATENCY_MARKER_OUT_OF_BAND_RENDERSUBMIT_END_NV = 9,
VK_LATENCY_MARKER_OUT_OF_BAND_PRESENT_START_NV = 10,
VK_LATENCY_MARKER_OUT_OF_BAND_PRESENT_END_NV = 11,
} VkLatencyMarkerNV;
The members of the VkLatencyMarkerNV are used as arguments for vkSetLatencyMarkerNV in the use cases described below:
-
VK_LATENCY_MARKER_SIMULATION_START_NVshould be called at the start of the simulation execution each frame, but after the call tovkLatencySleepNV. -
VK_LATENCY_MARKER_SIMULATION_END_NVshould be called at the end of the simulation execution each frame. -
VK_LATENCY_MARKER_RENDERSUBMIT_START_NVshould be called at the beginning of the render submission execution each frame. This should be wherever Vulkan API calls are made and must not span into asynchronous rendering. -
VK_LATENCY_MARKER_RENDERSUBMIT_END_NVshould be called at the end of the render submission execution each frame. -
VK_LATENCY_MARKER_PRESENT_START_NVshould be called just beforevkQueuePresentKHR. -
VK_LATENCY_MARKER_PRESENT_END_NVshould be called whenvkQueuePresentKHRreturns. -
VK_LATENCY_MARKER_INPUT_SAMPLE_NVshould be called just before the application gathers input data. -
VK_LATENCY_MARKER_TRIGGER_FLASH_NVshould be called anywhere betweenVK_LATENCY_MARKER_SIMULATION_START_NVandVK_LATENCY_MARKER_SIMULATION_END_NVwhenever a left mouse click occurs.
To get an array containing the newest collected latency data, call:
// Provided by VK_NV_low_latency2
void vkGetLatencyTimingsNV(
VkDevice device,
VkSwapchainKHR swapchain,
VkGetLatencyMarkerInfoNV* pLatencyMarkerInfo);
-
deviceis the device associated withswapchain. -
swapchainis the swapchain to return data from. -
pLatencyMarkerInfois a pointer to a VkGetLatencyMarkerInfoNV structure specifying the parameters for returning latency information.
The timings returned by vkGetLatencyTimingsNV contain the timestamps
requested from vkSetLatencyMarkerNV and additional
implementation-specific markers defined in
VkLatencyTimingsFrameReportNV.
The VkGetLatencyMarkerInfoNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkGetLatencyMarkerInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t timingCount;
VkLatencyTimingsFrameReportNV* pTimings;
} VkGetLatencyMarkerInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextis eitherNULLor a pointer to a structure extending this structure. -
timingCountis an integer related to the number of previous frames of latency data available or queried, as described below. -
pTimingsis eitherNULLor a pointer to an array of VkLatencyTimingsFrameReportNV structures.
If pTimings is NULL then the maximum number of queryable frame data
is returned in timingCount.
Otherwise, timingCount must be set by the application to the number
of elements in the pTimings array, and on return the variable is
overwritten with the number of values actually written to pTimings.
The elements of pTimings are arranged in the order they were requested
in, with the oldest data in the first entry.
The VkLatencyTimingsFrameReportNV structure describes latency data returned by vkGetLatencyTimingsNV
// Provided by VK_NV_low_latency2
typedef struct VkLatencyTimingsFrameReportNV {
VkStructureType sType;
const void* pNext;
uint64_t presentID;
uint64_t inputSampleTimeUs;
uint64_t simStartTimeUs;
uint64_t simEndTimeUs;
uint64_t renderSubmitStartTimeUs;
uint64_t renderSubmitEndTimeUs;
uint64_t presentStartTimeUs;
uint64_t presentEndTimeUs;
uint64_t driverStartTimeUs;
uint64_t driverEndTimeUs;
uint64_t osRenderQueueStartTimeUs;
uint64_t osRenderQueueEndTimeUs;
uint64_t gpuRenderStartTimeUs;
uint64_t gpuRenderEndTimeUs;
} VkLatencyTimingsFrameReportNV;
The members of the VkLatencyTimingsFrameReportNV structure describe the following:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentIDis the application provided value that is used to associate the timestamp with avkQueuePresentKHRcommand using VkPresentIdKHR::pPresentIdsor VkPresentId2KHR::pPresentIdsfor a given present. -
simStartTimeUsis the timestamp written whenvkSetLatencyMarkerNVis called with theVkLatencyMarkerNVenumVK_LATENCY_MARKER_SIMULATION_START_NV. -
simEndTimeUsis the timestamp written whenvkSetLatencyMarkerNVis called with theVkLatencyMarkerNVenumVK_LATENCY_MARKER_SIMULATION_END_NV -
renderStartTimeUsis the timestamp written whenvkSetLatencyMarkerNVis called with theVkLatencyMarkerNVenumVK_LATENCY_MARKER_RENDERSUBMIT_START_NV. -
renderEndTimeUsis the timestamp written whenvkSetLatencyMarkerNVis called with theVkLatencyMarkerNVenumVK_LATENCY_MARKER_RENDERSUBMIT_END_NV. -
presentStartTimeUsis the timestamp written whenvkSetLatencyMarkerNVis called with theVkLatencyMarkerNVenumVK_LATENCY_MARKER_PRESENT_START_NV. -
presentEndTimeUsis the timestamp written whenvkSetLatencyMarkerNVis called with theVkLatencyMarkerNVenumVK_LATENCY_MARKER_PRESENT_END_NV. -
driverStartTimeUsis the timestamp written when the firstvkQueueSubmitfor the frame is called. -
driverEndTimeUsis the timestamp written when the finalvkQueueSubmithands off from the Vulkan Driver. -
osRenderQueueStartTimeUsis the timestamp written when the finalvkQueueSubmithands off from the Vulkan Driver. -
osRenderQueueEndTimeUsis the timestamp written when the first submission reaches the GPU. -
gpuRenderStartTimeUsis the timestamp written when the first submission reaches the GPU. -
gpuRenderEndTimeUsis the timestamp written when the final submission finishes on the GPU for the frame.
The VkLatencySubmissionPresentIdNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkLatencySubmissionPresentIdNV {
VkStructureType sType;
const void* pNext;
uint64_t presentID;
} VkLatencySubmissionPresentIdNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentIDis used to associate thevkQueueSubmitwith the presentId used for a givenvkQueuePresentKHRvia VkPresentIdKHR::pPresentIdsor VkPresentId2KHR::pPresentIds.
For any submission to be tracked with low latency mode pacing, it needs to
be associated with other submissions in a given present.
To associate a submission with presentID for low latency mode, the
pNext chain of vkQueueSubmit must include a
VkLatencySubmissionPresentIdNV structure.
To mark a queue as out of band, so that all vkQueueSubmit calls on
the queue are ignored for latency evaluation, call:
// Provided by VK_NV_low_latency2
void vkQueueNotifyOutOfBandNV(
VkQueue queue,
const VkOutOfBandQueueTypeInfoNV* pQueueTypeInfo);
-
queueis the VkQueue to be marked as out of band. -
pQueueTypeInfois a pointer to a VkOutOfBandQueueTypeInfoNV structure specifying the queue type.
The VkOutOfBandQueueTypeInfoNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkOutOfBandQueueTypeInfoNV {
VkStructureType sType;
const void* pNext;
VkOutOfBandQueueTypeNV queueType;
} VkOutOfBandQueueTypeInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queueTypedescribes the usage of the queue to be marked as out of band.
The VkOutOfBandQueueTypeNV enum is defined as:
// Provided by VK_NV_low_latency2
typedef enum VkOutOfBandQueueTypeNV {
VK_OUT_OF_BAND_QUEUE_TYPE_RENDER_NV = 0,
VK_OUT_OF_BAND_QUEUE_TYPE_PRESENT_NV = 1,
} VkOutOfBandQueueTypeNV;
The members of the VkOutOfBandQueueTypeNV are used to describe the queue type in VkOutOfBandQueueTypeInfoNV as described below:
-
VK_OUT_OF_BAND_QUEUE_TYPE_RENDER_NVspecifies that work will be submitted to this queue. -
VK_OUT_OF_BAND_QUEUE_TYPE_PRESENT_NVspecifies that this queue will be presented from.
To allow low latency mode to be used by a swapchain, add a
VkSwapchainLatencyCreateInfoNV structure to the pNext chain of
VkSwapchainCreateInfoKHR.
The VkSwapchainLatencyCreateInfoNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkSwapchainLatencyCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 latencyModeEnable;
} VkSwapchainLatencyCreateInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
latencyModeEnableisVK_TRUEif the created swapchain will utilize low latency mode,VK_FALSEotherwise.
The VkLatencySurfaceCapabilitiesNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkLatencySurfaceCapabilitiesNV {
VkStructureType sType;
const void* pNext;
uint32_t presentModeCount;
VkPresentModeKHR* pPresentModes;
} VkLatencySurfaceCapabilitiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentModeCountis the number of presentation modes provided. -
pPresentModesis list of presentation modes optimized for use with low latency mode withpresentModeCountentries.
If pPresentModes is NULL, then the number of present modes that are
optimized for use with low latency mode returned in presentModeCount.
Otherwise, presentModeCount must be set by the application 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 presentModeCount is less than the number of optimized
present modes, at most presentModeCount values will be written to
pPresentModes.
35.14. Present Barrier
The VK_NV_present_barrier extension allows applications to
synchronize corresponding presentation requests across multiple swapchains
using the present barrier.
A swapchain is said to be using the present barrier if the swapchain is
created by adding a VkSwapchainPresentBarrierCreateInfoNV structure to
the pNext chain of the VkSwapchainCreateInfoKHR structure, and
setting
VkSwapchainPresentBarrierCreateInfoNV::presentBarrierEnable to
true.
A set of corresponding presentation requests is defined as exactly one queued presentation request associated with each swapchain using the present barrier, whether or not that queued request has executed. A given presentation request is added, when created by calling vkQueuePresentKHR and specifying a swapchain using the present barrier, either to the oldest existing set of corresponding requests for which there is no existing member associated with the request’s swapchain, or to a new set of corresponding requests if no such set exists.
A set of corresponding requests is said to be full when it contains one request from each swapchain using the present barrier. Queued presentation of an image to a swapchain using the present barrier is deferred by the implementation until the set of corresponding requests is full, and the visibility operations associated with all requests in that set, as described by vkQueuePresentKHR, have completed.
Additionally, the set of swapchains using the present barrier can be in the same process, or different processes running under the same operating system. And if the required synchronization hardware is connected and correctly configured, this extension also supports applications to synchronize corresponding presentation requests using the present barrier across distributed systems. However, the configuration mechanism of the required hardware is outside the scope of the Vulkan specification and this extension.
The VkSwapchainPresentBarrierCreateInfoNV structure is defined as:
// Provided by VK_NV_present_barrier
typedef struct VkSwapchainPresentBarrierCreateInfoNV {
VkStructureType sType;
void* pNext;
VkBool32 presentBarrierEnable;
} VkSwapchainPresentBarrierCreateInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentBarrierEnableis a boolean value indicating a request for using the present barrier.
If the pNext chain of VkSwapchainCreateInfoKHR does not include
this structure, the default value for presentBarrierEnable is
VK_FALSE, meaning the swapchain does not request to use the present
barrier.
Additionally, when recreating a swapchain that was using the present
barrier, and the pNext chain of VkSwapchainCreateInfoKHR does
not include this structure, it means the swapchain will stop using the
present barrier.
35.14.1. Present Metering
Present Metering evenly paces out the next numFramesPerBatch
vkQueuePresentKHR presents.
This gives smoother pacing between presents in applications with frame
generation integrations.
The VkSetPresentConfigNV structure is defined as:
// Provided by VK_NV_present_metering
typedef struct VkSetPresentConfigNV {
VkStructureType sType;
const void* pNext;
uint32_t numFramesPerBatch;
uint32_t presentConfigFeedback;
} VkSetPresentConfigNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
numFramesPerBatchis the number of frames to batch -
presentConfigFeedbackwill return the success or error status
The metering configuration applies to all swapchains in the array in
VkPresentInfoKHR.
The configuration specified by VkSetPresentConfigNV applies to the
next numFramesPerBatch calls to vkQueuePresentKHR and needs to
be updated every numFramesPerBatch presents.
36. 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 dependent 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.
36.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 by the implementation at any time until the deferred operation enters the complete state. The application must obey the following rules 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.
When a deferral is requested for a command, the implementation may perform memory management operations on the allocator supplied to vkCreateDeferredOperationKHR for the deferred operation object, as described in the Memory Allocation chapter. Such allocations must occur on the thread which requests deferral.
If an allocator was supplied for the deferred command at the time of the deferral request, then the implementation may perform memory management operations on this allocator during the execution of vkDeferredOperationJoinKHR. These operations may occur concurrently and may be performed by any joined thread. The application must ensure that the supplied allocator is able to operate correctly under these conditions.
36.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.
37. Private Data
The private data extension provides a way for users to associate arbitrary application-defined data with Vulkan objects. This association is accomplished by storing 64-bit unsigned integers of application-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 a VkPrivateDataSlotCreateInfo -
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 a VkStructureType value identifying 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 application-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 application-defined data to associate the object with. This data will be stored atprivateDataSlot.
To retrieve application-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 application-defined 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 |
38. Acceleration Structures
38.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.
38.1.1. Geometry
Geometries refer to a triangle, sphere, linear swept sphere (LSS), or axis-aligned bounding box.
A triangle is a fundamental geometric primitive defined by three vertices in 3D space, forming a flat, planar surface.
An axis-aligned bounding box (AABB) is a rectangular box defined by two points (minimum and maximum corners) that encloses a 3D object or scene. Its faces are aligned with the coordinate axes, making intersection tests efficient for spatial partitioning and acceleration structures.
A sphere primitive is defined by a position and a radius.
The linear swept sphere (LSS) primitive is comprised of two sphere endcaps and a truncated cone midsection. The midsection is constructed so that it tangentially intersects with the endcaps. Two points, P0 and P1, and two radii, r0 and r1, fully describe the primitive.
The following figure shows an example of the LSS primitive composed of two sphere endcaps connected by a midsection. The solid non-dotted outline indicates the intersectable portion of the primitive.
Endcaps on LSS primitives are optional and are controlled by
VkAccelerationStructureGeometryLinearSweptSpheresDataNV::endCapsMode.
The following figure shows an example of the LSS primitive without the
endcaps with only the midsection present.
A LSS geometry can be defined in multiple ways. If only the vertex and radius data are specified in VkAccelerationStructureGeometryLinearSweptSpheresDataNV without specifying the index data, LSS primitives are drawn in pairs of vertices. Each primitive i is defined by entries (i × 2, i × 2 + 1) in the vertex and radius buffers. For example, if a vertex buffer contains vertices A, B, C, D, E, F and G, (assuming each character represents a position vector) with corresponding radii as rA, rB, rC, rD, rE, rF and rG respectively, the LSS primitives drawn will be as shown below with G skipped because it does not have a corresponding vertex pair.
LSS primitives can be chained together by specifying an index buffer and indexing mode in the VkAccelerationStructureGeometryLinearSweptSpheresDataNV structure.
If the VkRayTracingLssIndexingModeNV::indexingMode is set to
VK_RAY_TRACING_LSS_INDEXING_MODE_LIST_NV, then the consecutive pair of
indices in the index buffer select the vertices that define the LSS chain.
For example, assuming the same vertex buffer as before, if the index buffer
contains indices [6, 5, 5, 4, 4, 3, 2, 1], the LSS primitives will be
chained as shown:
Note that due to the lack of a [3, 2] pair, there is a break in the chain and D is not connected to C.
If the VkRayTracingLssIndexingModeNV::indexingMode is set to
VK_RAY_TRACING_LSS_INDEXING_MODE_SUCCESSIVE_NV, then each LSS
primitive is defined by two successive positions and radii, (k, k
1), where k is a single index in the index buffer.
For example, if the index buffer contains indices [0, 1, 2, 4], the
LSS primitives will be chained as shown below.
Note that due to the absence of index 3 in the index buffer, there is a
break in the chain and D is not connected to E.
38.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.
38.1.3. Bottom Level Acceleration Structures
Opaque acceleration structure for an array of geometries.
38.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.
If the original acceleration structure was built using opacity micromaps and
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT
was set in flags, the application must provide a micromap matching
the original micromap in structure with only opacity values updated.
The application is prohibited from changing anything other than the specific
opacity values assigned to the triangles.
More precisely, the application must not use an update operation to do any of the following:
-
Remove micromaps or VkOpacityMicromapSpecialIndexEXT values from a geometry which previously had them, or vice versa.
-
Change between use of VkOpacityMicromapSpecialIndexEXT values and explicit micro-map triangles.
-
Change the subdivision level or format of the micromap triangle associated with any acceleration-structure triangle.
If the original acceleration structure was built using opacity micromaps and
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_EXT
was set in flags, the application must provide a micromap to the
update operation.
If VkMicromapBuildSizesInfoEXT::discardable is VK_FALSE, a
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT
or
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_EXT
operation transfers the reference in the acceleration structure to the new
micromap.
If the original acceleration structure was built using opacity micromaps and neither opacity micromap update flag is set the application must provide the original micromap to the update operation.
If the original acceleration structure was built using displacement
micromaps and
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_BIT_NV
was set in flags, the application must provide a displacement
micromap to the update operation.
If the original acceleration structure was built using displacement micromaps and the displacement micromap update flag is not set the application must provide the original micromap to the update operation.
38.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 reference is 0.
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.
An inactive LSS or sphere is one where any of the radius or position component is NaN.
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.
The active/inactive state of primitives must not be changed with
acceleration structure updates.
For chained LSS, using the
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_CHAINED_NV mode, entire
chains must be either active or inactive.
If any chain contains both active and inactive primitives, the behavior is
undefined.
38.1.6. Degenerate Primitives and Instances
Degenerate primitives and instances behave differently to inactive primitives and instances, and are defined as:
-
triangles that have one or more vertices whose respective (X), (Y), (Z) components are identical, or have three vertices that have at least two of the (X), (Y), or (Z) components identical, therefore forming a line or point. Degenerate triangles do not generate any intersections.
-
AABBs whose
minX=maxX,minY=maxY, andminZ=maxZ. Degenerate AABBs may invoke the intersection shader. -
LSS primitives where both the radii are set to
0. -
sphere primitives whose radius is set to
0. -
instances that reference bottom level acceleration structures that contain no active primitives. When building an acceleration structure, implementations should treat degenerate instances as though they are a point at the instance origin, specified by VkAccelerationStructureInstanceKHR::
transform.
Unlike inactive primitives and instances, degenerate primitives and instances may transition from the degenerate to the non-degenerate state, or vice versa, when performing an acceleration structure update.
If an acceleration structure is built without
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in
VkAccelerationStructureInfoNV::flags
or
VkAccelerationStructureBuildGeometryInfoKHR::flags
, degenerate primitives may be discarded.
Primitives that are defined with the same index value for more than one
vertex can always be discarded.
38.1.7. 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 |
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR).
Accesses to each
VkAccelerationStructureBuildGeometryInfoKHR::srcAccelerationStructure
and
VkAccelerationStructureBuildGeometryInfoKHR::dstAccelerationStructure
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.
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 a VkStructureType value identifying 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 thedstAccelerationStructureacceleration 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 each 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, VK_NV_cooperative_vector
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, VK_NV_cooperative_vector
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 a VkStructureType value identifying 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 structure. -
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 a VkStructureType value identifying 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. -
vertexStrideis the stride in bytes between each vertex. -
maxVertexis the number of vertices invertexDataminus one. -
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 a VkStructureType value identifying 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 VkAccelerationStructureTrianglesOpacityMicromapEXT structure is
defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkAccelerationStructureTrianglesOpacityMicromapEXT {
VkStructureType sType;
void* pNext;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexBuffer;
VkDeviceSize indexStride;
uint32_t baseTriangle;
uint32_t usageCountsCount;
const VkMicromapUsageEXT* pUsageCounts;
const VkMicromapUsageEXT* const* ppUsageCounts;
VkMicromapEXT micromap;
} VkAccelerationStructureTrianglesOpacityMicromapEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
indexTypeis the type of triangle indices used when indexing this micromap -
indexBufferis the address containing the triangle indices -
indexStrideis the byte stride between triangle indices -
baseTriangleis the base value added to the non-negative triangle indices -
usageCountsCountspecifies the number of usage counts structures that will be used to determine the size of this micromap. -
pUsageCountsis a pointer to an array of VkMicromapUsageEXT structures. -
ppUsageCountsis a pointer to an array of pointers to VkMicromapUsageEXT structures. -
micromapis the handle to the micromap object to include in this geometry
If VkAccelerationStructureTrianglesOpacityMicromapEXT is included in
the pNext chain of a
VkAccelerationStructureGeometryTrianglesDataKHR structure, that
geometry will reference that micromap.
For each triangle in the geometry, the acceleration structure build fetches
an index from indexBuffer using indexType and indexStride
if present.
If indexBuffer is NULL then the index used is the index of the
triangle in the geometry.
If that value is the unsigned cast of one of the values from VkOpacityMicromapSpecialIndexEXT then that triangle behaves as described for that special value in Ray Opacity Micromap.
Otherwise that triangle uses the opacity micromap information from
micromap at that index plus baseTriangle.
Only one of pUsageCounts or ppUsageCounts can be a valid
pointer, the other must be NULL.
The elements of the non-NULL array describe the total count used to build
this geometry.
For a given format and subdivisionLevel the number of triangles
in this geometry matching those values after indirection and special index
handling must be equal to the sum of matching count provided.
If micromap is VK_NULL_HANDLE, then every value read from
indexBuffer must be one of the values in
VkOpacityMicromapSpecialIndexEXT.
The VkOpacityMicromapSpecialIndexEXT enumeration is defined as:
// Provided by VK_EXT_opacity_micromap
typedef enum VkOpacityMicromapSpecialIndexEXT {
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_TRANSPARENT_EXT = -1,
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_OPAQUE_EXT = -2,
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_TRANSPARENT_EXT = -3,
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_OPAQUE_EXT = -4,
// Provided by VK_EXT_opacity_micromap with VK_NV_cluster_acceleration_structure
VK_OPACITY_MICROMAP_SPECIAL_INDEX_CLUSTER_GEOMETRY_DISABLE_OPACITY_MICROMAP_NV = -5,
} VkOpacityMicromapSpecialIndexEXT;
-
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_TRANSPARENT_EXTspecifies that the entire triangle is fully transparent. -
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_OPAQUE_EXTspecifies that the entire triangle is fully opaque. -
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_TRANSPARENT_EXTspecifies that the entire triangle is unknown-transparent. -
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_OPAQUE_EXTspecifies that the entire triangle is unknown-opaque. -
VK_OPACITY_MICROMAP_SPECIAL_INDEX_CLUSTER_GEOMETRY_DISABLE_OPACITY_MICROMAP_NVspecifies that Opacity Micromap will be disabled for this triangle and opacity value will be picked from VkClusterAccelerationStructureBuildTriangleClusterInfoNV::baseGeometryIndexAndGeometryFlagsinstead. Note that this special index is only valid for Cluster Geometry.
The VkAccelerationStructureTrianglesDisplacementMicromapNV structure
is defined as:
// Provided by VK_NV_displacement_micromap
typedef struct VkAccelerationStructureTrianglesDisplacementMicromapNV {
VkStructureType sType;
void* pNext;
VkFormat displacementBiasAndScaleFormat;
VkFormat displacementVectorFormat;
VkDeviceOrHostAddressConstKHR displacementBiasAndScaleBuffer;
VkDeviceSize displacementBiasAndScaleStride;
VkDeviceOrHostAddressConstKHR displacementVectorBuffer;
VkDeviceSize displacementVectorStride;
VkDeviceOrHostAddressConstKHR displacedMicromapPrimitiveFlags;
VkDeviceSize displacedMicromapPrimitiveFlagsStride;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexBuffer;
VkDeviceSize indexStride;
uint32_t baseTriangle;
uint32_t usageCountsCount;
const VkMicromapUsageEXT* pUsageCounts;
const VkMicromapUsageEXT* const* ppUsageCounts;
VkMicromapEXT micromap;
} VkAccelerationStructureTrianglesDisplacementMicromapNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
displacementBiasAndScaleFormatis the format of displacement bias and scale used in this displacement micromap reference. -
displacementVectorFormatis the format of displacement vector used in this displacement micromap reference. -
displacementBiasAndScaleBufferis the address containing the bias and scale. -
displacementBiasAndScaleStrideis the byte stride between bias and scale values. -
displacementVectorBufferis the address containing the displacement vector values. -
displacementVectorStrideis the byte stride between displacement vector values. -
displacedMicromapPrimitiveFlagsis the address containing the primitive flags. -
displacedMicromapPrimitiveFlagsStrideis the byte stride between primitive flag values. -
indexTypeis the type of triangle indices used when indexing this micromap. -
indexBufferis the address containing the triangle indices. -
indexStrideis the byte stride between triangle indices. -
baseTriangleis the base value added to the non-negative triangle indices. -
usageCountsCountspecifies the number of usage counts structures that will be used to determine the size of this micromap. -
pUsageCountsis a pointer to an array of VkMicromapUsageEXT structures. -
ppUsageCountsis a pointer to an array of pointers to VkMicromapUsageEXT structures. -
micromapis the handle to the micromap object to include in this geometry.
If VkAccelerationStructureTrianglesDisplacementMicromapNV is included
in the pNext chain of a
VkAccelerationStructureGeometryTrianglesDataKHR structure, that
geometry will reference that micromap.
For each triangle in the geometry, the acceleration structure build fetches
an index from indexBuffer using indexType and indexStride.
That triangle uses the displacement micromap information from micromap
at that index plus baseTriangle.
Only one of pUsageCounts or ppUsageCounts can be a valid
pointer, the other must be NULL.
The elements of the non-NULL array describe the total count used to build
this geometry.
For a given format and subdivisionLevel the number of triangles
in this geometry matching those values after indirection must be equal to
the sum of matching count provided.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 application-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 device address containing a bottom level cluster acceleration structure built using vkCmdBuildClusterAccelerationStructureIndirectNV
-
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 structure 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,
// Provided by VK_EXT_opacity_micromap
VK_GEOMETRY_INSTANCE_FORCE_OPACITY_MICROMAP_2_STATE_BIT_EXT = 0x00000010,
// Provided by VK_EXT_opacity_micromap
VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_BIT_EXT = 0x00000020,
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,
// Provided by VK_EXT_opacity_micromap
// VK_GEOMETRY_INSTANCE_FORCE_OPACITY_MICROMAP_2_STATE_EXT is a deprecated alias
VK_GEOMETRY_INSTANCE_FORCE_OPACITY_MICROMAP_2_STATE_EXT = VK_GEOMETRY_INSTANCE_FORCE_OPACITY_MICROMAP_2_STATE_BIT_EXT,
// Provided by VK_EXT_opacity_micromap
// VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_EXT is a deprecated alias
VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_EXT = VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_BIT_EXT,
} 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_KHRspecifies 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 application-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 structure 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 application-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 structure 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_SPHERES_NV,primitiveCountis the number of spheres to be built, where each sphere is treated as 1 vertex.-
If the geometry uses indices,
primitiveCountindices are consumed from VkAccelerationStructureGeometrySpheresDataNV::indexData, starting at an offset ofprimitiveOffset. The value offirstVertexis added to the index values before fetching vertices and radii. -
If the geometry does not use indices,
primitiveCountvertices and radii are consumed from VkAccelerationStructureGeometrySpheresDataNV::vertexData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometrySpheresDataNV::vertexStride×firstVertexand VkAccelerationStructureGeometrySpheresDataNV::radiusData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometrySpheresDataNV::radiusStride×firstVertexrespectively.
-
-
For geometries of type
VK_GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV,primitiveCountis the number of LSS primitives to be built, where each LSS primitive is treated as 2 vertices.-
If the geometry uses indices,
primitiveCount× 2 indices are consumed from VkAccelerationStructureGeometryLinearSweptSpheresDataNV::indexData, starting at an offset ofprimitiveOffset. The value offirstVertexis added to the index values before fetching vertices and radii. -
If the geometry does not use indices,
primitiveCount× 2 vertices and radii are consumed from VkAccelerationStructureGeometryLinearSweptSpheresDataNV::vertexData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometryLinearSweptSpheresDataNV::vertexStride×firstVertexand VkAccelerationStructureGeometryLinearSweptSpheresDataNV::radiusData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometryLinearSweptSpheresDataNV::radiusStride×firstVertexrespectively.
-
-
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.
If VkAccelerationStructureGeometryLinearSweptSpheresDataNV is included
in the pNext chain of a VkAccelerationStructureGeometryKHR
structure, then that structures defines the linear swept sphere’s (LSS)
geometry data.
The VkAccelerationStructureGeometryLinearSweptSpheresDataNV structure
is defined as:
// Provided by VK_NV_ray_tracing_linear_swept_spheres
typedef struct VkAccelerationStructureGeometryLinearSweptSpheresDataNV {
VkStructureType sType;
const void* pNext;
VkFormat vertexFormat;
VkDeviceOrHostAddressConstKHR vertexData;
VkDeviceSize vertexStride;
VkFormat radiusFormat;
VkDeviceOrHostAddressConstKHR radiusData;
VkDeviceSize radiusStride;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexData;
VkDeviceSize indexStride;
VkRayTracingLssIndexingModeNV indexingMode;
VkRayTracingLssPrimitiveEndCapsModeNV endCapsMode;
} VkAccelerationStructureGeometryLinearSweptSpheresDataNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexFormatis the VkFormat of each LSS vertex element. -
vertexDatais a device or host address to memory containing vertex data for this geometry. -
vertexStrideis the stride in bytes between each vertex element. -
radiusFormatis the VkFormat of each LSS radius. -
radiusDatais a device or host address to memory containing LSS radius data value. -
radiusStrideis the stride in bytes between each radius value. -
indexTypeis the VkIndexType of each index element. -
indexDataisNULLor a device or host address to memory containing index data for vertex and radius buffers for this geometry. -
indexStrideis the stride in bytes between each index element. -
indexingModeis a VkRayTracingLssIndexingModeNV value specifying the mode of indexing. -
endCapsModeis a VkRayTracingLssPrimitiveEndCapsModeNV value specifying the endcaps mode for LSS primitives.
If an index buffer is not specified in indexData, LSS primitives are
rendered individually using subsequent pairs of vertices similar to
VK_PRIMITIVE_TOPOLOGY_LINE_LIST.
Chaining LSS primitives can be achieved by specifying an index buffer in
VkAccelerationStructureGeometryLinearSweptSpheresDataNV::indexData
and setting
VkAccelerationStructureGeometryLinearSweptSpheresDataNV::indexingMode
to one of VkRayTracingLssIndexingModeNV values:
// Provided by VK_NV_ray_tracing_linear_swept_spheres
typedef enum VkRayTracingLssIndexingModeNV {
VK_RAY_TRACING_LSS_INDEXING_MODE_LIST_NV = 0,
VK_RAY_TRACING_LSS_INDEXING_MODE_SUCCESSIVE_NV = 1,
} VkRayTracingLssIndexingModeNV;
-
VK_RAY_TRACING_LSS_INDEXING_MODE_LIST_NVspecifies that a list of indices is provided where each consecutive pair of indices define a LSS primitive. -
VK_RAY_TRACING_LSS_INDEXING_MODE_SUCCESSIVE_NVspecifies a successive implicit indexing format, in which each LSS primitive is defined by two successive positions and radii, (k, k + 1), where k is a single index provided in the index buffer. In this indexing scheme, there is a 1:1 mapping between the index buffer and primitive index within the geometry.
The default behavior with endcaps in a LSS chain is that both endcaps will
be enabled for all beginning and end points.
To change the LSS chain’s endcaps mode use
VkAccelerationStructureGeometryLinearSweptSpheresDataNV::endCapsMode.
The possible values for endCapsMode are:
// Provided by VK_NV_ray_tracing_linear_swept_spheres
typedef enum VkRayTracingLssPrimitiveEndCapsModeNV {
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_NONE_NV = 0,
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_CHAINED_NV = 1,
} VkRayTracingLssPrimitiveEndCapsModeNV;
-
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_NONE_NVdisables all endcaps and the chain boundaries have no influence. -
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_CHAINED_NVspecifies that whenVK_RAY_TRACING_LSS_INDEXING_MODE_SUCCESSIVE_NVis used as indexing mode for the LSS primitive, the first primitive in each chain will have both endcaps enabled, and every following primitive in the chain only has endcaps at the trailing position enabled.
In addition to LSS primitives, simple sphere geometry is also supported. Spheres do not have an endcap mode. If an index buffer is present, each entry represents a single position and radius describing one sphere primitive. If no index buffer is provided, the vertex position and radius values are sequentially read from the corresponding buffers.
If VkAccelerationStructureGeometrySpheresDataNV is included in the
pNext chain of a VkAccelerationStructureGeometryKHR structure,
then that structures defines the sphere’s geometry data.
The VkAccelerationStructureGeometrySpheresDataNV structure is defined
as:
// Provided by VK_NV_ray_tracing_linear_swept_spheres
typedef struct VkAccelerationStructureGeometrySpheresDataNV {
VkStructureType sType;
const void* pNext;
VkFormat vertexFormat;
VkDeviceOrHostAddressConstKHR vertexData;
VkDeviceSize vertexStride;
VkFormat radiusFormat;
VkDeviceOrHostAddressConstKHR radiusData;
VkDeviceSize radiusStride;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexData;
VkDeviceSize indexStride;
} VkAccelerationStructureGeometrySpheresDataNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexFormatis the VkFormat of each sphere’s vertex element. -
vertexDatais a device or host address to memory containing vertex data in form of pairs of centers of spheres that define all sphere geometry. -
vertexStrideis the stride in bytes between each vertex element. -
radiusFormatis the VkFormat of each sphere’s radius. -
radiusDatais a device or host address to memory containing sphere’s radius data value. -
radiusStrideis the stride in bytes between each radius value. -
indexTypeis the VkIndexType of each index element. -
indexDataisNULLor a device or host address to memory containing index data for vertex and radius buffers for this geometry. -
indexStrideis the stride in bytes between each index element.
38.1.8. 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_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or 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_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or 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_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or 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 a VkStructureType value identifying 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,
// Provided by VK_KHR_acceleration_structure
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR = 2,
// Provided by VK_KHR_acceleration_structure
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 vkCmdWriteAccelerationStructuresPropertiesNV , 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_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or 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_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage, and an 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 a VkStructureType value identifying 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_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or 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_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
38.2. Cluster Level Acceleration Structures
Acceleration structure build times in ray tracing applications with extensive geometry can be reduced by introducing alternative acceleration structure types that facilitate bottom-level acceleration structure construction using pre-generated primitive clusters, improving geometry reuse. This can be achieved by incorporating additional acceleration structure types:
Cluster Level Acceleration Structure (CLAS) is an intermediate acceleration structure constructed from triangles, which serves as a building block for Cluster Level Bottom Level Acceleration Structure. A CLAS shares similarities with a traditional bottom level acceleration structure but has several key distinctions. A CLAS can only contain a limited number of triangles and vertices. CLAS objects cannot be directly referenced in a top level acceleration structure, instead, they must be part of a Cluster Level Bottom Level Acceleration Structure. The geometry indices within a CLAS are local to it, potentially non-consecutive, and customizable per primitive. Each CLAS can also have a user-defined 32-bit ClusterID, which is accessible in the hit shaders. The vertex positions within a CLAS can be quantized by zeroing specific floating-point mantissa bits to optimize storage.
Cluster Template Acceleration Structure is a partially constructed CLAS designed for efficient instantiation into multiple CLAS objects. During a cluster template build, some pre-computation is performed independent of vertex positions, allowing reuse across multiple CLAS objects with different vertex data. A cluster template itself does not require vertex positions but it retains non-positional properties similar to a CLAS, which are then inherited during instantiation. A cluster template must be instantiated into a CLAS object to be usable.
Cluster Level Bottom Level Acceleration Structure is a new alternative to the existing bottom level acceleration structures, which is constructed using references to already built CLAS objects and is the only cluster acceleration structure that can be referenced in a top level acceleration structure.
These cluster acceleration structures can be built or moved by a single versatile multi-indirect function vkCmdBuildClusterAccelerationStructureIndirectNV. To determine the memory requirements for executing this function, call:
// Provided by VK_NV_cluster_acceleration_structure
void vkGetClusterAccelerationStructureBuildSizesNV(
VkDevice device,
const VkClusterAccelerationStructureInputInfoNV* pInfo,
VkAccelerationStructureBuildSizesInfoKHR* pSizeInfo);
-
deviceis the logical device that owns the acceleration structure. -
pInfois a pointer to a VkClusterAccelerationStructureInputInfoNV structure containing parameters required for the memory requirements query. -
pSizeInfois a pointer to a VkAccelerationStructureBuildSizesInfoKHR structure which returns the size required for an acceleration structure and scratch buffer, given the build parameters.
If VkClusterAccelerationStructureInputInfoNV::opMode is
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV,
acceleration structure and scratch memory sizes are returned for all
VkClusterAccelerationStructureInputInfoNV::maxAccelerationStructureCount
acceleration structures.
If VkClusterAccelerationStructureInputInfoNV::opMode is
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV,
scratch memory size for all
VkClusterAccelerationStructureInputInfoNV::maxAccelerationStructureCount
acceleration structures and the acceleration structure memory size for a
single acceleration structure is returned.
If VkClusterAccelerationStructureInputInfoNV::opMode is
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, only
scratch memory size is returned for the requested acceleration structures.
The VkClusterAccelerationStructureInputInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureInputInfoNV {
VkStructureType sType;
void* pNext;
uint32_t maxAccelerationStructureCount;
VkBuildAccelerationStructureFlagsKHR flags;
VkClusterAccelerationStructureOpTypeNV opType;
VkClusterAccelerationStructureOpModeNV opMode;
VkClusterAccelerationStructureOpInputNV opInput;
} VkClusterAccelerationStructureInputInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxAccelerationStructureCountis the maximum number of acceleration structures that will be provided to the multi indirect operation. -
flagsis a bitmask of VkBuildAccelerationStructureFlagsKHR specifying flags for the multi indirect operation. -
opTypeis a VkClusterAccelerationStructureOpTypeNV value specifying the type of operation to perform. -
opModeis a VkClusterAccelerationStructureOpModeNV value specifying the mode of operation. -
opInputis a VkClusterAccelerationStructureOpInputNV value specifying the descriptions of the operation.
Values which can be set in VkClusterAccelerationStructureOpTypeNV
are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureOpTypeNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_MOVE_OBJECTS_NV = 0,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_CLUSTERS_BOTTOM_LEVEL_NV = 1,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_NV = 2,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_TEMPLATE_NV = 3,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_INSTANTIATE_TRIANGLE_CLUSTER_NV = 4,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_GET_CLUSTER_TEMPLATE_INDICES_NV = 5,
} VkClusterAccelerationStructureOpTypeNV;
-
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_MOVE_OBJECTS_NVspecifies that a cluster acceleration structure, cluster acceleration structure template or a bottom level acceleration structure built from cluster acceleration structures will be moved. If a cluster acceleration structure is moved, the bottom level cluster acceleration structures containing it will have to be re-built. If used withVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, it returns the size of existing cluster acceleration structures. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_CLUSTERS_BOTTOM_LEVEL_NVspecifies that bottom level cluster acceleration structures will be built. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_NVspecifies that cluster acceleration structures will be built. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_TEMPLATE_NVspecifies that a template for cluster acceleration structure will be built. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_INSTANTIATE_TRIANGLE_CLUSTER_NVspecifies that a template for a cluster acceleration structure will be instantiated, resulting in a built cluster acceleration structure. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_GET_CLUSTER_TEMPLATE_INDICES_NVspecifies that the vertex indices of the cluster template acceleration structure will be fetched.
Values which can be set in VkClusterAccelerationStructureOpModeNV
are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureOpModeNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV = 0,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV = 1,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV = 2,
} VkClusterAccelerationStructureOpModeNV;
-
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NVspecifies that the build or move operation will implicitly distribute built or compacted cluster acceleration structures starting at the address provided in VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData. If a move operation is being performed, the acceleration structures will be tightly compacted. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NVspecifies that the build or move operation will explicitly write built or compacted cluster acceleration structures in the array of addresses provided in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NVspecifies that computed cluster acceleration structure sizes will be written to VkClusterAccelerationStructureCommandsInfoNV::dstSizesArray.
The VkClusterAccelerationStructureOpInputNV union is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef union VkClusterAccelerationStructureOpInputNV {
VkClusterAccelerationStructureClustersBottomLevelInputNV* pClustersBottomLevel;
VkClusterAccelerationStructureTriangleClusterInputNV* pTriangleClusters;
VkClusterAccelerationStructureMoveObjectsInputNV* pMoveObjects;
} VkClusterAccelerationStructureOpInputNV;
-
pClustersBottomLevelis a VkClusterAccelerationStructureClustersBottomLevelInputNV structure specifying an upper threshold on parameters to build multiple bottom level acceleration structures from multiple cluster level acceleration structures. -
pTriangleClustersis a VkClusterAccelerationStructureTriangleClusterInputNV structure specifying an upper threshold on parameters to build a regular or templated cluster acceleration structure. -
pMoveObjectsis a VkClusterAccelerationStructureMoveObjectsInputNV structure specifying an upper threshold on the number of bytes moved and the type of acceleration structure being moved.
The VkClusterAccelerationStructureClustersBottomLevelInputNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureClustersBottomLevelInputNV {
VkStructureType sType;
void* pNext;
uint32_t maxTotalClusterCount;
uint32_t maxClusterCountPerAccelerationStructure;
} VkClusterAccelerationStructureClustersBottomLevelInputNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxTotalClusterCountis the total number of clusters acceleration structures that will be built or moved across all input arguments. -
maxClusterCountPerAccelerationStructureis the maximum number of clusters acceleration structures that will be built or moved per input argument.
The VkClusterAccelerationStructureTriangleClusterInputNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureTriangleClusterInputNV {
VkStructureType sType;
void* pNext;
VkFormat vertexFormat;
uint32_t maxGeometryIndexValue;
uint32_t maxClusterUniqueGeometryCount;
uint32_t maxClusterTriangleCount;
uint32_t maxClusterVertexCount;
uint32_t maxTotalTriangleCount;
uint32_t maxTotalVertexCount;
uint32_t minPositionTruncateBitCount;
} VkClusterAccelerationStructureTriangleClusterInputNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexFormatis the VkFormat of each vertex element. -
maxGeometryIndexValueis the maximum geometry index value for any constructed geometry. -
maxClusterUniqueGeometryCountis the maximum number of unique values of the geometry index for each cluster or cluster template. -
maxClusterTriangleCountis the maximum number of triangles in a cluster or cluster template. -
maxClusterVertexCountis the maximum number of unique vertices in the cluster’s index buffer. -
maxTotalTriangleCountis the sum of all triangles across all clusters or cluster templates. -
maxTotalVertexCountis the maximum number of vertices across all clusters or cluster templates. -
minPositionTruncateBitCountis the least value specified in cluster build in VkClusterAccelerationStructureBuildTriangleClusterInfoNV::positionTruncateBitCountor cluster template build in VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV::positionTruncateBitCount.
The VkClusterAccelerationStructureMoveObjectsInputNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureMoveObjectsInputNV {
VkStructureType sType;
void* pNext;
VkClusterAccelerationStructureTypeNV type;
VkBool32 noMoveOverlap;
VkDeviceSize maxMovedBytes;
} VkClusterAccelerationStructureMoveObjectsInputNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis a VkClusterAccelerationStructureTypeNV value identifying the type of cluster acceleration structure. -
noMoveOverlapspecifies if the source and destination cluster acceleration structures overlap in memory for the move operation. If set toVK_TRUE, the source cluster acceleration structure remains valid after the move and move operation acts like a copy. -
maxMovedBytesis the maximum number of bytes that may be moved in this operation.
Values which can be set in VkClusterAccelerationStructureTypeNV are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureTypeNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_CLUSTERS_BOTTOM_LEVEL_NV = 0,
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_TRIANGLE_CLUSTER_NV = 1,
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_TRIANGLE_CLUSTER_TEMPLATE_NV = 2,
} VkClusterAccelerationStructureTypeNV;
-
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_CLUSTERS_BOTTOM_LEVEL_NVspecifies a bottom level cluster acceleration structure. -
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_TRIANGLE_CLUSTER_NVspecifies a cluster acceleration structure. -
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_TRIANGLE_CLUSTER_TEMPLATE_NVspecifies a template cluster acceleration structure.
To build or move a cluster acceleration structure or a cluster acceleration structure template call:
// Provided by VK_NV_cluster_acceleration_structure
void vkCmdBuildClusterAccelerationStructureIndirectNV(
VkCommandBuffer commandBuffer,
const VkClusterAccelerationStructureCommandsInfoNV* pCommandInfos);
-
commandBufferis the command buffer into which the command is recorded. -
pCommandInfosis a pointer to a VkClusterAccelerationStructureCommandsInfoNV structure containing parameters required for building or moving the cluster acceleration structure.
Similar to vkCmdBuildAccelerationStructuresKHR, this command may
initiate multiple acceleration structures builds and there is no ordering or
synchronization implied between any of the individual acceleration structure
builds.
Accesses to the acceleration structure scratch memory as identified by the
VkClusterAccelerationStructureCommandsInfoNV::scratchData 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 |
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR).
Accesses to each
VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData,
VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray
and VkClusterAccelerationStructureCommandsInfoNV::dstSizesArray
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 memory with input data as identified by any used values of
VkClusterAccelerationStructureCommandsInfoNV::srcInfosArray,
VkClusterAccelerationStructureCommandsInfoNV::srcInfosCount and
VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags
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 VkClusterAccelerationStructureCommandsInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureCommandsInfoNV {
VkStructureType sType;
void* pNext;
VkClusterAccelerationStructureInputInfoNV input;
VkDeviceAddress dstImplicitData;
VkDeviceAddress scratchData;
VkStridedDeviceAddressRegionKHR dstAddressesArray;
VkStridedDeviceAddressRegionKHR dstSizesArray;
VkStridedDeviceAddressRegionKHR srcInfosArray;
VkDeviceAddress srcInfosCount;
VkClusterAccelerationStructureAddressResolutionFlagsNV addressResolutionFlags;
} VkClusterAccelerationStructureCommandsInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
inputis VkClusterAccelerationStructureInputInfoNV structure describing the build or move parameters for the cluster acceleration structure. -
dstImplicitDatais the device address for memory where the implicit build of cluster acceleration structure will be saved. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NVorVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, this value is ignored. -
scratchDatais the device address of scratch memory that will be used during cluster acceleration structure move or build. -
dstAddressesArrayis a VkStridedDeviceAddressRegionKHR where the individual addresses and stride of moved or built cluster acceleration structures will be saved or read from depending on VkClusterAccelerationStructureInputInfoNV::opMode. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NVand the address indstAddressesArrayis not0, then the addresses are saved. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, then the addresses are read from. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, then this value is ignored and may be0. -
dstSizesArrayisNULLor a VkStridedDeviceAddressRegionKHR containing sizes of moved or built cluster acceleration structures. Similar todstAddressesArray, if VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV, then the sizes are saved. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, then the sizes are read from. -
srcInfosArrayis a VkStridedDeviceAddressRegionKHR where input data for the build or move operation is read from. If the stride is0, the structures are assumed to be packed tightly. Its format is dependent on VkClusterAccelerationStructureInputInfoNV::opTypeas per the table below.
|
Format of |
|
|
|
VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV |
|
|
|
VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV |
|
|
|
-
srcInfosCountis the device address of memory containing the count of number of build or move operations to perform. The actual value is the minimum of this value and the value specified ininput::maxAccelerationStructureCount. If this value is0, the count is determined byinput::maxAccelerationStructureCountalone. -
addressResolutionFlagsis a bitmask of VkClusterAccelerationStructureAddressResolutionFlagBitsNV values specifying how an implementation will interpret the device addresses in this structure.
Bits which can be set in
VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags,
specifying how the device address in
VkClusterAccelerationStructureCommandsInfoNV are interpreted, are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureAddressResolutionFlagBitsNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_NONE_NV = 0,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_IMPLICIT_DATA_BIT_NV = 0x00000001,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SCRATCH_DATA_BIT_NV = 0x00000002,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NV = 0x00000004,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_SIZES_ARRAY_BIT_NV = 0x00000008,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_ARRAY_BIT_NV = 0x00000010,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_COUNT_BIT_NV = 0x00000020,
} VkClusterAccelerationStructureAddressResolutionFlagBitsNV;
-
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_NONE_NVspecifies that no address resolution flags are provided. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_IMPLICIT_DATA_BIT_NVspecifies another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SCRATCH_DATA_BIT_NVspecifies another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::scratchData. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NVspecifies another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_SIZES_ARRAY_BIT_NVspecifies another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::dstSizesArray. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_ARRAY_BIT_NVspecifies another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::srcInfosArray. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_COUNT_BIT_NVspecifies another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::srcInfosCount.
// Provided by VK_NV_cluster_acceleration_structure
typedef VkFlags VkClusterAccelerationStructureAddressResolutionFlagsNV;
VkClusterAccelerationStructureAddressResolutionFlagsNV is a bitmask
type for setting a mask of zero or more
VkClusterAccelerationStructureAddressResolutionFlagBitsNV.
The VkClusterAccelerationStructureMoveObjectsInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureMoveObjectsInfoNV {
VkDeviceAddress srcAccelerationStructure;
} VkClusterAccelerationStructureMoveObjectsInfoNV;
-
srcAccelerationStructureis the device address of the source cluster acceleration structure that will be moved.
The VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV {
uint32_t clusterReferencesCount;
uint32_t clusterReferencesStride;
VkDeviceAddress clusterReferences;
} VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV;
-
clusterReferencesCountis the number of clusters this bottom level acceleration structure will be built from. -
clusterReferencesStrideis the stride inclusterReferences. -
clusterReferencesis the device memory containing the address of the clusters.
Bits which can be set in
VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV::geometryFlags,
specifying geometry flags for cluster acceleration structure, are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureGeometryFlagBitsNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_CULL_DISABLE_BIT_NV = 0x00000001,
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_NO_DUPLICATE_ANYHIT_INVOCATION_BIT_NV = 0x00000002,
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_OPAQUE_BIT_NV = 0x00000004,
} VkClusterAccelerationStructureGeometryFlagBitsNV;
-
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_CULL_DISABLE_BIT_NVdisables face culling for this geometry. -
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_NO_DUPLICATE_ANYHIT_INVOCATION_BIT_NVspecifies 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. -
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_OPAQUE_BIT_NVspecifies that this geometry does not invoke the any-hit shaders even if present in a hit group.
// Provided by VK_NV_cluster_acceleration_structure
typedef VkFlags VkClusterAccelerationStructureGeometryFlagsNV;
VkClusterAccelerationStructureGeometryFlagsNV is a bitmask type for
setting a mask of zero or more
VkClusterAccelerationStructureGeometryFlagBitsNV.
The VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV {
uint32_t geometryIndex:24;
uint32_t reserved:5;
uint32_t geometryFlags:3;
} VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV;
-
geometryIndexspecifies the geometry index for all triangles in the cluster acceleration structure. -
reservedis reserved for future use. -
geometryFlagsis a bitmask of VkClusterAccelerationStructureGeometryFlagBitsNV values describing geometry flags for the cluster acceleration structure.
The C language specification does not define the ordering of bit-fields, but in practice, this structure produces the correct layout with existing compilers. The intended bit pattern is the following:
-
geometryIndex,reservedandmaskoccupy the same memory as if a singleuint32_twas specified in their place-
geometryIndexoccupies the 24 least significant bits of that memory -
geometryFlagsoccupies the 3 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.
Bits which can be set in
VkClusterAccelerationStructureBuildTriangleClusterInfoNV::clusterFlags,
specifying flags for clusters in an acceleration structure, are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureClusterFlagBitsNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_CLUSTER_ALLOW_DISABLE_OPACITY_MICROMAPS_NV = 0x00000001,
} VkClusterAccelerationStructureClusterFlagBitsNV;
-
VK_CLUSTER_ACCELERATION_STRUCTURE_CLUSTER_ALLOW_DISABLE_OPACITY_MICROMAPS_NVspecifies that the specified cluster acceleration structure may be referenced in an instance withVK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_BIT_EXTset.
// Provided by VK_NV_cluster_acceleration_structure
typedef VkFlags VkClusterAccelerationStructureClusterFlagsNV;
VkClusterAccelerationStructureClusterFlagsNV is a bitmask type for
setting a mask of zero or more
VkClusterAccelerationStructureClusterFlagBitsNV.
The VkClusterAccelerationStructureBuildTriangleClusterInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureBuildTriangleClusterInfoNV {
uint32_t clusterID;
VkClusterAccelerationStructureClusterFlagsNV clusterFlags;
uint32_t triangleCount:9;
uint32_t vertexCount:9;
uint32_t positionTruncateBitCount:6;
uint32_t indexType:4;
uint32_t opacityMicromapIndexType:4;
VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV baseGeometryIndexAndGeometryFlags;
uint16_t indexBufferStride;
uint16_t vertexBufferStride;
uint16_t geometryIndexAndFlagsBufferStride;
uint16_t opacityMicromapIndexBufferStride;
VkDeviceAddress indexBuffer;
VkDeviceAddress vertexBuffer;
VkDeviceAddress geometryIndexAndFlagsBuffer;
VkDeviceAddress opacityMicromapArray;
VkDeviceAddress opacityMicromapIndexBuffer;
} VkClusterAccelerationStructureBuildTriangleClusterInfoNV;
-
clusterIDis a user specified identifier assigned to this cluster. -
clusterFlagsis a bitmask of VkClusterAccelerationStructureClusterFlagBitsNV values describing flags how the cluster should be built. -
triangleCountis the number of triangles in this cluster. -
vertexCountis the number of unique vertices in this cluster. -
positionTruncateBitCountis the number of bits starting at the lowest bit (i.e. the LSBs of the mantissa), of each vertex position that will be truncated to zero to improve floating-point compression. -
indexTypeis a single VkClusterAccelerationStructureIndexFormatFlagBitsNV value specifying the index type inindexBuffer. -
opacityMicromapIndexTypeis a single VkClusterAccelerationStructureIndexFormatFlagBitsNV value specifying the index type inopacityMicromapIndexBuffer. -
baseGeometryIndexAndGeometryFlagsis a VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV value specifying the base geometry index and flags for all triangles in the cluster. -
indexBufferStrideis the stride in bytes inindexBufferwith0meaning the values are tightly-packed. -
vertexBufferStrideis the stride in bytes invertexBufferwith0meaning the values are tightly-packed. -
geometryIndexAndFlagsBufferStrideis the stride in bytes ingeometryIndexAndFlagsBufferwith0meaning the values are tightly-packed. -
opacityMicromapIndexBufferStrideis the stride in bytes inopacityMicromapIndexBufferwith0meaning the values are tightly-packed. -
indexBuffercontains the indices of vertices in the cluster and is of typeindexType. -
vertexBufferspecifies the vertex data of the triangles in the cluster with format specified in VkClusterAccelerationStructureTriangleClusterInputNV::vertexFormat. -
geometryIndexAndFlagsBufferis eitherNULLor an address containing strided VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV values specifying the geometry index and flag for every triangle in the cluster. -
opacityMicromapArrayis eitherNULLor specifies the address of a valid opacity micromap array to reference from the cluster acceleration structure. If it isNULL, then opacity micromaps will be disabled for this cluster acceleration structure. -
opacityMicromapIndexBufferis eitherNULLor specifies the address of a strided array with size equal to the number of triangles or indices into the opacity micromap array.
The C language specification does not define the ordering of bit-fields, but in practice, this structure produces the correct layout with existing compilers. The intended bit pattern is the following:
-
triangleCount,vertexCount,positionTruncateBitCount,indexTypeandopacityMicromapIndexTypeoccupy the same memory as if a singleuint32_twas specified in their place-
triangleCountoccupies the 9 least significant bits of that memory -
vertexCountoccupies the next 9 least significant bits of that memory -
positionTruncateBitCountoccupies the next 6 least significant bits of that memory -
indexTypeoccupies the next 4 least significant bits of that memory -
opacityMicromapIndexTypeoccupies the 4 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.
Bits that can be set in
VkClusterAccelerationStructureBuildTriangleClusterInfoNV::indexType,
VkClusterAccelerationStructureBuildTriangleClusterInfoNV::opacityMicromapIndexType,
VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV::indexType
and
VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV::opacityMicromapIndexType
specifying the index type is one of:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureIndexFormatFlagBitsNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_8BIT_NV = 0x00000001,
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_16BIT_NV = 0x00000002,
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_32BIT_NV = 0x00000004,
} VkClusterAccelerationStructureIndexFormatFlagBitsNV;
-
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_8BIT_NVspecifies that 8-bit indices will be used. -
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_16BIT_NVspecifies that 16-bit indices will be used. -
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_32BIT_NVspecifies that 32-bit indices will be used.
// Provided by VK_NV_cluster_acceleration_structure
typedef VkFlags VkClusterAccelerationStructureIndexFormatFlagsNV;
VkClusterAccelerationStructureIndexFormatFlagsNV is a bitmask type for
setting a single VkClusterAccelerationStructureIndexFormatFlagBitsNV.
The VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV {
uint32_t clusterID;
VkClusterAccelerationStructureClusterFlagsNV clusterFlags;
uint32_t triangleCount:9;
uint32_t vertexCount:9;
uint32_t positionTruncateBitCount:6;
uint32_t indexType:4;
uint32_t opacityMicromapIndexType:4;
VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV baseGeometryIndexAndGeometryFlags;
uint16_t indexBufferStride;
uint16_t vertexBufferStride;
uint16_t geometryIndexAndFlagsBufferStride;
uint16_t opacityMicromapIndexBufferStride;
VkDeviceAddress indexBuffer;
VkDeviceAddress vertexBuffer;
VkDeviceAddress geometryIndexAndFlagsBuffer;
VkDeviceAddress opacityMicromapArray;
VkDeviceAddress opacityMicromapIndexBuffer;
VkDeviceAddress instantiationBoundingBoxLimit;
} VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV;
-
clusterIDis a user specified identifier assigned to this cluster template. -
clusterFlagsis a bitmask of VkClusterAccelerationStructureClusterFlagBitsNV values describing flags how the cluster template should be built. -
triangleCountis the number of triangles in this cluster. -
vertexCountis the number of unique vertices in this cluster. -
positionTruncateBitCountis the number of bits starting at the lowest bit (i.e. the LSBs of the mantissa), of each vertex position that will be truncated to zero to improve floating-point compression. -
indexTypeis a single VkClusterAccelerationStructureIndexFormatFlagBitsNV value specifying the index type inindexBuffer. -
opacityMicromapIndexTypeis a single VkClusterAccelerationStructureIndexFormatFlagBitsNV value specifying the index type inopacityMicromapIndexBuffer. -
baseGeometryIndexAndGeometryFlagsis a VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV value specifying the base geometry index and flags for all triangles in the cluster template. -
indexBufferStrideis the stride in bytes inindexBuffer. -
vertexBufferStrideis the stride in bytes invertexBuffer. -
geometryIndexAndFlagsBufferStrideis the stride in bytes ingeometryIndexAndFlagsBuffer. -
opacityMicromapIndexBufferStrideis the stride in bytes inopacityMicromapIndexBuffer. -
indexBuffercontains the indices of vertices in the cluster and is of typeindexType. -
vertexBufferis eitherNULLor specifies the vertex data of the triangles in the cluster template with format specified in VkClusterAccelerationStructureTriangleClusterInputNV::vertexFormat. -
geometryIndexAndFlagsBufferis eitherNULLor an address containing strided VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV values specifying the geometry index and flag for every triangle in the cluster. -
opacityMicromapArrayis eitherNULLor specifies the address of a valid opacity micromap array to reference from the cluster acceleration structure. If it isNULL, then opacity micromaps will be disabled for this cluster acceleration structure. -
opacityMicromapIndexBufferis eitherNULLor specifies the address of a strided array with size equal to the number of triangles or indices into the opacity micromap array. -
instantiationBoundingBoxLimitis eitherNULLor specifies the address of a bounding box within which all instantiated clusters must lie. The bounding box is specified by six 32-bit floating-point values in the order MinX, MinY, MinZ, MaxX, MaxY, MaxZ.
The C language specification does not define the ordering of bit-fields, but in practice, this structure produces the correct layout with existing compilers. The intended bit pattern is the following:
-
triangleCount,vertexCount,positionTruncateBitCount,indexTypeandopacityMicromapIndexTypeoccupy the same memory as if a singleuint32_twas specified in their place-
triangleCountoccupies the 9 least significant bits of that memory -
vertexCountoccupies the next 9 least significant bits of that memory -
positionTruncateBitCountoccupies the next 6 least significant bits of that memory -
indexTypeoccupies the next 4 least significant bits of that memory -
opacityMicromapIndexTypeoccupies the 4 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.
Cluster templates cannot be directly used to build bottom level acceleration structures, instead, they must be instantiated into CLAS objects.
The VkClusterAccelerationStructureInstantiateClusterInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureInstantiateClusterInfoNV {
uint32_t clusterIdOffset;
uint32_t geometryIndexOffset:24;
uint32_t reserved:8;
VkDeviceAddress clusterTemplateAddress;
VkStridedDeviceAddressNV vertexBuffer;
} VkClusterAccelerationStructureInstantiateClusterInfoNV;
-
clusterIdOffsetis an unsigned offset applied to theclusterIDvalue stored in the cluster template. -
geometryIndexOffsetis a signed offset applied to the geometry index of each triangle. -
reservedis reserved for future use. -
clusterTemplateAddressis the address of a previously built cluster template. -
vertexBufferis eitherNULLor a VkStridedDeviceAddressNV structure containing the vertex data for the indexed triangles stored in the cluster template.
The VkClusterAccelerationStructureGetTemplateIndicesInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureGetTemplateIndicesInfoNV {
VkDeviceAddress clusterTemplateAddress;
} VkClusterAccelerationStructureGetTemplateIndicesInfoNV;
-
clusterTemplateAddressis the device address of the cluster template acceleration structure whose index data is being fetched.
The VkStridedDeviceAddressNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkStridedDeviceAddressNV {
VkDeviceAddress startAddress;
VkDeviceSize strideInBytes;
} VkStridedDeviceAddressNV;
-
startAddressis the device address (as returned by the vkGetBufferDeviceAddress command) at which the region starts, or zero if the region is unused. -
strideInBytesis the byte stride between consecutive elements. Only the bottom 32 bits are used. The field is 64 bits to ensure consistent alignment across all containing structures.
38.3. Partitioned Top Level Acceleration Structures
Partitioned Top Level Acceleration Structures (PTLAS) allow efficient reuse of previously constructed sections of the top level acceleration structure by eliminating a full rebuild when only a few instances are modified. This reduces build times and supports handling a higher number of instances, making it more suitable for large and complex scenes.
PTLAS organizes instances into partitions, enabling a two-stage build process: first, it constructs an acceleration structure for each partition by grouping the instances within it, and second, it combines these partition structures into a single acceleration structure, similar to the current top-level acceleration structure.
To maintain compatibility, PTLAS behaves identically to the current top-level acceleration structure from the perspective of ray tracing shaders and pipelines.
PTLAS includes a unique global partition that operates independently of other partitions. Instances can be assigned to this global partition just like they would to regular partitions. The global partition is well-suited for frequently updated instances, such as animated characters. During the build process, instances in the global partition are treated as if they belong to individual partitions, without increasing the maximum partition count. However, instances in the global partition may still impact build performance. Once these instances become stable, they should be moved to a spatially optimized, non-global partition to lower build costs and minimize trace performance issues.
To handle large worlds requiring more precision than 32-bit floating-point
numbers offer, PTLAS offers efficient partition translation.
Typically, applications maintain precision by placing the world center near
the camera.
Partition translation allows an additional translation of instances during
construction without changing their stored transforms.
This method stores instance transforms relative to partitions, applying a
translation to achieve accurate world positions.
Higher precision is maintained using smaller floating-point numbers until
the structure is built.
World space coordinates can also be updated efficiently without rebuilding
the entire PTLAS.
Partition translation requires extra memory for untranslated instance
transforms and must be explicitly enabled with
VkPartitionedAccelerationStructureFlagsNV::enablePartitionTranslation
flag.
To determine the memory requirements for a PTAS, call:
// Provided by VK_NV_partitioned_acceleration_structure
void vkGetPartitionedAccelerationStructuresBuildSizesNV(
VkDevice device,
const VkPartitionedAccelerationStructureInstancesInputNV* pInfo,
VkAccelerationStructureBuildSizesInfoKHR* pSizeInfo);
-
deviceis the logical device that owns the acceleration structure. -
pInfois a pointer to a VkPartitionedAccelerationStructureInstancesInputNV structure containing parameters required for the memory requirements query. -
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 VkPartitionedAccelerationStructureInstancesInputNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureInstancesInputNV {
VkStructureType sType;
void* pNext;
VkBuildAccelerationStructureFlagsKHR flags;
uint32_t instanceCount;
uint32_t maxInstancePerPartitionCount;
uint32_t partitionCount;
uint32_t maxInstanceInGlobalPartitionCount;
} VkPartitionedAccelerationStructureInstancesInputNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkBuildAccelerationStructureFlagsKHR specifying flags for the PTLAS build operation. -
instanceCountis the number of instances in this PTLAS. -
maxInstancePerPartitionCountis the maximum number of instances per partition in the PTLAS. -
partitionCountis the number of partitions in the PTLAS. -
maxInstanceInGlobalPartitionCountis maximum number of instances in the global partition.
If the pNext chain includes a
VkPartitionedAccelerationStructureFlagsNV structure, then that
structure specifies additional flags for the PTLAS.
The VkPartitionedAccelerationStructureFlagsNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureFlagsNV {
VkStructureType sType;
void* pNext;
VkBool32 enablePartitionTranslation;
} VkPartitionedAccelerationStructureFlagsNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
enablePartitionTranslationspecifies if a partition translation may be applied with VkPartitionedAccelerationStructureWritePartitionTranslationDataNV.
To build a partitioned top level acceleration structure, call:
// Provided by VK_NV_partitioned_acceleration_structure
void vkCmdBuildPartitionedAccelerationStructuresNV(
VkCommandBuffer commandBuffer,
const VkBuildPartitionedAccelerationStructureInfoNV* pBuildInfo);
-
commandBufferis the command buffer into which the command is recorded. -
pBuildInfois a pointer to a VkBuildPartitionedAccelerationStructureInfoNV structure containing parameters required for building a PTLAS.
Accesses to the acceleration structure scratch memory as identified by the
VkBuildPartitionedAccelerationStructureInfoNV::scratchData 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 |
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR).
Accesses to each
VkBuildPartitionedAccelerationStructureInfoNV::srcAccelerationStructureData
and
VkBuildPartitionedAccelerationStructureInfoNV::dstAccelerationStructureData
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.
Accesses to memory with input data as identified by any used values of
VkBuildPartitionedAccelerationStructureInfoNV::srcInfos and
VkBuildPartitionedAccelerationStructureInfoNV::srcInfosCount
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 VkBuildPartitionedAccelerationStructureInfoNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkBuildPartitionedAccelerationStructureInfoNV {
VkStructureType sType;
void* pNext;
VkPartitionedAccelerationStructureInstancesInputNV input;
VkDeviceAddress srcAccelerationStructureData;
VkDeviceAddress dstAccelerationStructureData;
VkDeviceAddress scratchData;
VkDeviceAddress srcInfos;
VkDeviceAddress srcInfosCount;
} VkBuildPartitionedAccelerationStructureInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
inputis a VkPartitionedAccelerationStructureInstancesInputNV structure describing the instance and partition count information in the PTLAS. -
srcAccelerationStructureDataisNULLor an address of a previously built PTLAS. If non-NULL, the PTLAS stored at this address is used as a basis to create new PTLAS. -
dstAccelerationStructureDatais the address to store the built PTLAS. -
scratchDatais the device address of scratch memory that will be used during PTLAS build. -
srcInfosis the device address of an array of VkBuildPartitionedAccelerationStructureIndirectCommandNV structures describing the type of operation to perform. -
srcInfosCountis a device address containing the size ofsrcInfosarray.
Members srcAccelerationStructureData and
dstAccelerationStructureData may be the same or different.
If they are the same, the update happens in-place.
Otherwise, the destination acceleration structure is updated and the source
is not modified.
The VkBuildPartitionedAccelerationStructureIndirectCommandNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkBuildPartitionedAccelerationStructureIndirectCommandNV {
VkPartitionedAccelerationStructureOpTypeNV opType;
uint32_t argCount;
VkStridedDeviceAddressNV argData;
} VkBuildPartitionedAccelerationStructureIndirectCommandNV;
-
opTypeis a VkPartitionedAccelerationStructureOpTypeNV describing the type of operation. -
argCountthe number of structures inargDataarray. -
argDatais an array of VkStridedDeviceAddressNV structures containing the write or update data for instances and partitions in the PTLAS. The structure is dependent onopTypeas shown in the table below.
|
Format of |
|
|
|
|
|
VkPartitionedAccelerationStructureWritePartitionTranslationDataNV |
Values which can be set in VkPartitionedAccelerationStructureOpTypeNV are:
// Provided by VK_NV_partitioned_acceleration_structure
typedef enum VkPartitionedAccelerationStructureOpTypeNV {
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_WRITE_INSTANCE_NV = 0,
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_UPDATE_INSTANCE_NV = 1,
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_WRITE_PARTITION_TRANSLATION_NV = 2,
} VkPartitionedAccelerationStructureOpTypeNV;
-
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_WRITE_INSTANCE_NVis used to assign a transformed bottom level acceleration structure to an instance and partition. This is similar to VkAccelerationStructureInstanceKHR that defines the properties and transformations for a single instance in non-partitioned TLAS. Any partition that contains at least one of the affected instances will have their internal acceleration structure rebuilt. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_UPDATE_INSTANCE_NVspecifies that an instance will be updated with a new bottom level acceleration structure. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_WRITE_PARTITION_TRANSLATION_NVspecifies that a partition will be assigned a translation vector.
The VkPartitionedAccelerationStructureWriteInstanceDataNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureWriteInstanceDataNV {
VkTransformMatrixKHR transform;
float explicitAABB[6];
uint32_t instanceID;
uint32_t instanceMask;
uint32_t instanceContributionToHitGroupIndex;
VkPartitionedAccelerationStructureInstanceFlagsNV instanceFlags;
uint32_t instanceIndex;
uint32_t partitionIndex;
VkDeviceAddress accelerationStructure;
} VkPartitionedAccelerationStructureWriteInstanceDataNV;
-
transformis a VkTransformMatrixKHR structure describing the transformation to be applied to the instance in PTLAS. -
explicitAABBspecifies an axis aligned bounding box representing the maximum extent of any vertex within the used acceleration structure after applying the instance-to-world transformation. The partition translation is not applied to the bounding box. -
instanceIDis a user specified constant assigned to an instance in the PTLAS. -
instanceMaskis a 8-bit mask assigned to the instance that may be used to include or reject group of instances. -
instanceContributionToHitGroupIndexis a 24-bit per application specified instance value added in the indexing into the shader binding table to fetch the hit group to use. -
instanceFlagsis a bitmask of VkPartitionedAccelerationStructureInstanceFlagsNV specifying flags an instance in the PTLAS. -
instanceIndexis the index of the instance within the PTLAS. -
partitionIndexis the index of the partition to which this instance belongs. Global partitions are referred to byVK_PARTITIONED_ACCELERATION_STRUCTURE_PARTITION_INDEX_GLOBAL_NV. -
accelerationStructureis the device address of the bottom level acceleration structure or a clustered bottom level acceleration structure that is being instanced. This instance is disabled if the device address is0.
The VkPartitionedAccelerationStructureUpdateInstanceDataNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureUpdateInstanceDataNV {
uint32_t instanceIndex;
uint32_t instanceContributionToHitGroupIndex;
VkDeviceAddress accelerationStructure;
} VkPartitionedAccelerationStructureUpdateInstanceDataNV;
-
instanceIndexis the index of the instance being updated. -
instanceContributionToHitGroupIndexis a 24-bit per instance value added in the indexing into the shader binding table to fetch the hit group to use. -
accelerationStructureis the device address of the bottom level acceleration structure or a clustered bottom level acceleration structure whose instance is being updated. The instance is disabled if the device address is0.
If the instance was originally disabled by specifying a 0 in
VkPartitionedAccelerationStructureWriteInstanceDataNV::accelerationStructure,
it can not be updated to a new acceleration structure as the instance may
have been permanently disabled by the implementation.
To avoid a refit, the new acceleration structure must be within the
bounding box specified by
VkPartitionedAccelerationStructureWriteInstanceDataNV::explicitAABB
when the instance was first created.
Bits which can be set in
VkPartitionedAccelerationStructureWriteInstanceDataNV::instanceFlags,
specifying flags for instances, are:
// Provided by VK_NV_partitioned_acceleration_structure
typedef enum VkPartitionedAccelerationStructureInstanceFlagBitsNV {
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_TRIANGLE_FACING_CULL_DISABLE_BIT_NV = 0x00000001,
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_TRIANGLE_FLIP_FACING_BIT_NV = 0x00000002,
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_FORCE_OPAQUE_BIT_NV = 0x00000004,
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_FORCE_NO_OPAQUE_BIT_NV = 0x00000008,
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_ENABLE_EXPLICIT_BOUNDING_BOX_NV = 0x00000010,
} VkPartitionedAccelerationStructureInstanceFlagBitsNV;
-
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_TRIANGLE_FACING_CULL_DISABLE_BIT_NVdisables face culling for this instance. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_TRIANGLE_FLIP_FACING_BIT_NVspecifies that the facing determination for geometry in this instance is inverted. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_FORCE_OPAQUE_BIT_NVcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere specified on all geometries referenced by this instance. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_FORCE_NO_OPAQUE_BIT_NVcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere not specified on all geometries referenced by this instance. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_ENABLE_EXPLICIT_BOUNDING_BOX_NVenables use of an explicit bounding box for this instance.
// Provided by VK_NV_partitioned_acceleration_structure
typedef VkFlags VkPartitionedAccelerationStructureInstanceFlagsNV;
VkPartitionedAccelerationStructureInstanceFlagsNV is a bitmask type
for setting a mask of zero or more
VkPartitionedAccelerationStructureInstanceFlagBitsNV.
The VkPartitionedAccelerationStructureWritePartitionTranslationDataNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureWritePartitionTranslationDataNV {
uint32_t partitionIndex;
float partitionTranslation[3];
} VkPartitionedAccelerationStructureWritePartitionTranslationDataNV;
-
partitionIndexis the index of partition to write. Global partition is referred to byVK_PARTITIONED_ACCELERATION_STRUCTURE_PARTITION_INDEX_GLOBAL_NV. -
partitionTranslationsets the translation vector for this partition. When tracing this partition, the contained instances will behave as if the partition translation was added to the translation component of the instance transform. This translation vector is also added to the instances in the partition that had their bounding box specified.
38.4. 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 interchangeable. 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 an application-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.
39. Micromap
39.1. Micromaps
Acceleration structures store and organize geometry for ray tracing, but in some cases it is beneficial to include some information within the geometry, particularly for triangles. A micromap organizes this data around a map of values corresponding to subdivided microtriangles which can be added to a triangle geometry when building a bottom level acceleration structure.
An opacity micromap is a type of micromap which stores information to control intersection opacity as described in Ray Opacity Micromap.
A displacement micromap is a type of micromap which stores information to displace sub-triangle vertices as described in Displacement Micromap.
A micromap is considered to be constructed if a micromap build command or copy command has been executed with the given acceleration structure as the destination.
39.1.1. Building Micromaps
To build micromaps call:
// Provided by VK_EXT_opacity_micromap
void vkCmdBuildMicromapsEXT(
VkCommandBuffer commandBuffer,
uint32_t infoCount,
const VkMicromapBuildInfoEXT* pInfos);
-
commandBufferis the command buffer into which the command will be recorded. -
infoCountis the number of micromaps to build. It specifies the number of thepInfosstructures that must be provided. -
pInfosis a pointer to an array ofinfoCountVkMicromapBuildInfoEXT structures defining the data used to build each micromap.
The vkCmdBuildMicromapsEXT command provides the ability to initiate
multiple micromaps builds, however there is no ordering or synchronization
implied between any of the individual micromap builds.
|
Note
|
This means that there cannot be any memory aliasing between any micromap memories or scratch memories being used by any of the builds. |
Accesses to the micromap scratch buffers as identified by the
VkMicromapBuildInfoEXT::scratchData buffer device addresses
must be synchronized with the
VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
pipeline stage and an
access type of
(VK_ACCESS_2_MICROMAP_READ_BIT_EXT |
VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT).
Accesses to VkMicromapBuildInfoEXT::dstMicromap must be
synchronized with the
VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
pipeline stage and an
access type of
VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT.
Accesses to other input buffers as identified by any used values of
VkMicromapBuildInfoEXT::data or
VkMicromapBuildInfoEXT::triangleArray must be
synchronized with the
VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
pipeline stage and an
access type of
VK_ACCESS_SHADER_READ_BIT.
Formats which can be set in VkMicromapUsageEXT::format and
VkMicromapTriangleEXT::format for micromap builds, are:
// Provided by VK_EXT_opacity_micromap
typedef enum VkOpacityMicromapFormatEXT {
VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT = 1,
VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT = 2,
} VkOpacityMicromapFormatEXT;
-
VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXTspecifies that the given micromap format has one bit per subtriangle encoding either fully opaque or fully transparent. -
VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXTspecifies that the given micromap format has two bits per subtriangle encoding four modes which can be interpreted as described in ray traversal.
|
Note
|
For compactness, these values are stored as 16-bit in some structures. |
Formats which can be set in VkMicromapUsageEXT::format and
VkMicromapTriangleEXT::format for micromap builds, are:
// Provided by VK_NV_displacement_micromap
typedef enum VkDisplacementMicromapFormatNV {
VK_DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV = 1,
VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV = 2,
VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV = 3,
} VkDisplacementMicromapFormatNV;
-
VK_DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NVspecifies that the given micromap format encodes 64 micro-triangles worth of displacements in 64 bytes as described in Displacement Micromap Encoding. -
VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NVspecifies that the given micromap format encodes 256 micro-triangles worth of displacements in 128 bytes as described in Displacement Micromap Encoding. -
VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NVspecifies that the given micromap format encodes 1024 micro-triangles worth of displacements in 128 bytes as described in Displacement Micromap Encoding.
|
Note
|
For compactness, these values are stored as 16-bit in some structures. |
The VkMicromapBuildInfoEXT structure is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapBuildInfoEXT {
VkStructureType sType;
const void* pNext;
VkMicromapTypeEXT type;
VkBuildMicromapFlagsEXT flags;
VkBuildMicromapModeEXT mode;
VkMicromapEXT dstMicromap;
uint32_t usageCountsCount;
const VkMicromapUsageEXT* pUsageCounts;
const VkMicromapUsageEXT* const* ppUsageCounts;
VkDeviceOrHostAddressConstKHR data;
VkDeviceOrHostAddressKHR scratchData;
VkDeviceOrHostAddressConstKHR triangleArray;
VkDeviceSize triangleArrayStride;
} VkMicromapBuildInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis a VkMicromapTypeEXT value specifying the type of micromap being built. -
flagsis a bitmask of VkBuildMicromapFlagBitsEXT specifying additional parameters of the micromap. -
modeis a VkBuildMicromapModeEXT value specifying the type of operation to perform. -
dstMicromapis a pointer to the target micromap for the build. -
usageCountsCountspecifies the number of usage counts structures that will be used to determine the size of this micromap. -
pUsageCountsis a pointer to an array of VkMicromapUsageEXT structures. -
ppUsageCountsis a pointer to an array of pointers to VkMicromapUsageEXT structures. -
datais the device or host address to memory which contains the data for the micromap. -
scratchDatais the device or host address to memory that will be used as scratch memory for the build. -
triangleArrayis the device or host address to memory containing the VkMicromapTriangleEXT data -
triangleArrayStrideis the stride in bytes between each element oftriangleArray
Only one of pUsageCounts or ppUsageCounts can be a valid
pointer, the other must be NULL.
The elements of the non-NULL array describe the total counts used to build
each micromap.
Each element contains a count which is the number of micromap
triangles of that format and subdivisionLevel contained in the
micromap.
Multiple elements with the same format and subdivisionLevel are
allowed and the total count for that format and subdivisionLevel
is the sum of the count for each element.
Each micromap triangle refers to one element in triangleArray which
contains the format and subdivisionLevel for that particular
triangle as well as a dataOffset in bytes which is the location
relative to data where that triangle’s micromap data begins.
The data at triangleArray is laid out as a 4 byte unsigned integer for
the dataOffset followed by a 2 byte unsigned integer for the
subdivision level then a 2 byte unsigned integer for the format.
In practice, compilers compile VkMicromapTriangleEXT to match this
pattern.
For opacity micromaps, the data at data is packed as either one bit
per element for VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT or two bits per
element for VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT and is packed from
LSB to MSB in each byte.
The data at each index in those bytes is interpreted as discussed in
Ray Opacity Micromap.
For displacement micromaps, the data at data is interpreted as
discussed in Displacement Micromap
Encoding.
The VkBuildMicromapModeEXT enumeration is defined as:
// Provided by VK_EXT_opacity_micromap
typedef enum VkBuildMicromapModeEXT {
VK_BUILD_MICROMAP_MODE_BUILD_EXT = 0,
} VkBuildMicromapModeEXT;
-
VK_BUILD_MICROMAP_MODE_BUILD_EXTspecifies that the destination micromap will be built using the specified data.
The VkMicromapUsageEXT structure is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapUsageEXT {
uint32_t count;
uint32_t subdivisionLevel;
uint32_t format;
} VkMicromapUsageEXT;
-
countis the number of triangles in the usage format defined by thesubdivisionLevelandformatbelow in the micromap -
subdivisionLevelis the subdivision level of this usage format -
formatis the format of this usage format
The format is interpreted based on the type of the micromap
using it.
The VkMicromapTriangleEXT structure is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapTriangleEXT {
uint32_t dataOffset;
uint16_t subdivisionLevel;
uint16_t format;
} VkMicromapTriangleEXT;
-
dataOffsetis the offset in bytes of the start of the data for this triangle. This is a byte aligned value. -
subdivisionLevelis the subdivision level of this triangle -
formatis the format of this triangle
The format is interpreted based on the type of the micromap
using it.
39.1.2. Copying Micromaps
An additional command exists for copying micromaps without updating their contents. Before copying, an application must query the size of the resulting micromap.
To query micromap size parameters call:
// Provided by VK_EXT_opacity_micromap
void vkCmdWriteMicromapsPropertiesEXT(
VkCommandBuffer commandBuffer,
uint32_t micromapCount,
const VkMicromapEXT* pMicromaps,
VkQueryType queryType,
VkQueryPool queryPool,
uint32_t firstQuery);
-
commandBufferis the command buffer into which the command will be recorded. -
micromapCountis the count of micromaps for which to query the property. -
pMicromapsis a pointer to an array of existing previously built micromaps. -
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 themicromapCountnumber of results.
Accesses to any of the micromaps listed in pMicromaps must be
synchronized with the
VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
pipeline stage and an
access type of
VK_ACCESS_2_MICROMAP_READ_BIT_EXT.
-
If
queryTypeisVK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then the value written out is the number of bytes required by a serialized micromap. -
If
queryTypeisVK_QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT, then the value written out is the number of bytes required by a compacted micromap.
To copy a micromap call:
// Provided by VK_EXT_opacity_micromap
void vkCmdCopyMicromapEXT(
VkCommandBuffer commandBuffer,
const VkCopyMicromapInfoEXT* pInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pInfois a pointer to a VkCopyMicromapInfoEXT structure defining the copy operation.
This command copies the pInfo->src micromap to the pInfo->dst
micromap in the manner specified by pInfo->mode.
Accesses to pInfo->src and pInfo->dst must be
synchronized with the
VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
pipeline stage and an
access type of
VK_ACCESS_2_MICROMAP_READ_BIT_EXT or
VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT as appropriate.
The VkCopyMicromapInfoEXT structure is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkCopyMicromapInfoEXT {
VkStructureType sType;
const void* pNext;
VkMicromapEXT src;
VkMicromapEXT dst;
VkCopyMicromapModeEXT mode;
} VkCopyMicromapInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcis the source micromap for the copy. -
dstis the target micromap for the copy. -
modeis a VkCopyMicromapModeEXT 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_EXT_opacity_micromap
typedef enum VkCopyMicromapModeEXT {
VK_COPY_MICROMAP_MODE_CLONE_EXT = 0,
VK_COPY_MICROMAP_MODE_SERIALIZE_EXT = 1,
VK_COPY_MICROMAP_MODE_DESERIALIZE_EXT = 2,
VK_COPY_MICROMAP_MODE_COMPACT_EXT = 3,
} VkCopyMicromapModeEXT;
-
VK_COPY_MICROMAP_MODE_CLONE_EXTcreates a direct copy of the micromap specified insrcinto the one specified bydst. Thedstmicromap must have been created with the same parameters assrc. -
VK_COPY_MICROMAP_MODE_SERIALIZE_EXTserializes the micromap to a semi-opaque format which can be reloaded on a compatible implementation. -
VK_COPY_MICROMAP_MODE_DESERIALIZE_EXTdeserializes the semi-opaque serialization format in the buffer to the micromap. -
VK_COPY_MICROMAP_MODE_COMPACT_EXTcreates a more compact version of a micromapsrcintodst. The micromapdstmust have been created with a size at least as large as that returned by vkCmdWriteMicromapsPropertiesEXT after the build of the micromap specified bysrc.
To copy a micromap to device memory call:
// Provided by VK_EXT_opacity_micromap
void vkCmdCopyMicromapToMemoryEXT(
VkCommandBuffer commandBuffer,
const VkCopyMicromapToMemoryInfoEXT* pInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pInfois an a pointer to a VkCopyMicromapToMemoryInfoEXT structure defining the copy operation.
Accesses to pInfo->src must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
pipeline stage and an
access type of
VK_ACCESS_2_MICROMAP_READ_BIT_EXT.
Accesses to the buffer indicated by pInfo->dst.deviceAddress must be
synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
pipeline stage and an access type of VK_ACCESS_TRANSFER_WRITE_BIT.
This command produces the same results as vkCopyMicromapToMemoryEXT, 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 vkCmdCopyMemoryToMicromapEXT or vkCopyMemoryToMicromapEXT.
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 vkGetDeviceMicromapCompatibilityEXT The serialized data is written to the buffer (or read from the buffer) according to the host endianness.
// Provided by VK_EXT_opacity_micromap
typedef struct VkCopyMicromapToMemoryInfoEXT {
VkStructureType sType;
const void* pNext;
VkMicromapEXT src;
VkDeviceOrHostAddressKHR dst;
VkCopyMicromapModeEXT mode;
} VkCopyMicromapToMemoryInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcis the source micromap for the copy -
dstis the device or host address to memory which is the target for the copy -
modeis a VkCopyMicromapModeEXT value specifying additional operations to perform during the copy.
To copy device memory to a micromap call:
// Provided by VK_EXT_opacity_micromap
void vkCmdCopyMemoryToMicromapEXT(
VkCommandBuffer commandBuffer,
const VkCopyMemoryToMicromapInfoEXT* pInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
pInfois a pointer to a VkCopyMemoryToMicromapInfoEXT structure defining the copy operation.
Accesses to pInfo->dst must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
pipeline stage and an
access type of
VK_ACCESS_2_MICROMAP_READ_BIT_EXT.
Accesses to the buffer indicated by pInfo->src.deviceAddress must be
synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
pipeline stage and an access type of VK_ACCESS_TRANSFER_READ_BIT.
This command can accept micromaps produced by either vkCmdCopyMicromapToMemoryEXT or vkCopyMicromapToMemoryEXT.
The VkCopyMemoryToMicromapInfoEXT structure is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkCopyMemoryToMicromapInfoEXT {
VkStructureType sType;
const void* pNext;
VkDeviceOrHostAddressConstKHR src;
VkMicromapEXT dst;
VkCopyMicromapModeEXT mode;
} VkCopyMemoryToMicromapInfoEXT;
-
sTypeis a VkStructureType value identifying 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 micromap for the copy. -
modeis a VkCopyMicromapModeEXT value specifying additional operations to perform during the copy.
To check if a serialized micromap is compatible with the current device call:
// Provided by VK_EXT_opacity_micromap
void vkGetDeviceMicromapCompatibilityEXT(
VkDevice device,
const VkMicromapVersionInfoEXT* pVersionInfo,
VkAccelerationStructureCompatibilityKHR* pCompatibility);
-
deviceis the device to check the version against. -
pVersionInfois a pointer to a VkMicromapVersionInfoEXT structure specifying version information to check against the device. -
pCompatibilityis a pointer to a VkAccelerationStructureCompatibilityKHR value in which compatibility information is returned.
The VkMicromapVersionInfoEXT structure is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapVersionInfoEXT {
VkStructureType sType;
const void* pNext;
const uint8_t* pVersionData;
} VkMicromapVersionInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pVersionDatais a pointer to the version header of a micromap as defined in vkCmdCopyMicromapToMemoryEXT
|
Note
|
|
39.2. Host Micromap Operations
Implementations are also required to provide host implementations of the
micromap operations if the micromapHostCommands feature is enabled:
-
vkBuildMicromapsEXT corresponding to vkCmdBuildMicromapsEXT
-
vkCopyMicromapEXT corresponding to vkCmdCopyMicromapEXT
-
vkCopyMicromapToMemoryEXT corresponding to vkCmdCopyMicromapToMemoryEXT
-
vkCopyMemoryToMicromapEXT corresponding to vkCmdCopyMemoryToMicromapEXT
-
vkWriteMicromapsPropertiesEXT corresponding to vkCmdWriteMicromapsPropertiesEXT
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 micromaps used by the host commands must be bound to host-visible memory, and all input data for micromap builds must be referenced using host addresses instead of device addresses. Applications are not required to map micromap memory when using the host commands.
|
Note
|
The vkBuildMicromapsEXT and vkCmdBuildMicromapsEXT may use different algorithms, and thus are not required to produce identical structures. Apart from these details, the host and device operations are interchangeable. |
|
Note
|
For efficient execution, micromaps 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 micromaps on the host, call:
// Provided by VK_EXT_opacity_micromap
VkResult vkBuildMicromapsEXT(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
uint32_t infoCount,
const VkMicromapBuildInfoEXT* pInfos);
-
deviceis theVkDevicefor which the micromaps are being built. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
infoCountis the number of micromaps to build. It specifies the number of thepInfosthat must be provided. -
pInfosis a pointer to an array ofinfoCountVkMicromapBuildInfoEXT structures defining the geometry used to build each micromap.
This command fulfills the same task as vkCmdBuildMicromapsEXT but is executed by the host.
The vkBuildMicromapsEXT command provides the ability to initiate
multiple micromaps builds, however there is no ordering or synchronization
implied between any of the individual micromap builds.
|
Note
|
This means that there cannot be any memory aliasing between any micromap memories or scratch memories being used by any of the builds. |
To copy or compact a micromap on the host, call:
// Provided by VK_EXT_opacity_micromap
VkResult vkCopyMicromapEXT(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
const VkCopyMicromapInfoEXT* pInfo);
-
deviceis the device which owns the micromaps. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
pInfois a pointer to a VkCopyMicromapInfoEXT structure defining the copy operation.
This command fulfills the same task as vkCmdCopyMicromapEXT but is executed by the host.
To copy host accessible memory to a micromap, call:
// Provided by VK_EXT_opacity_micromap
VkResult vkCopyMemoryToMicromapEXT(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
const VkCopyMemoryToMicromapInfoEXT* pInfo);
-
deviceis the device which ownspInfo->dst. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
pInfois a pointer to a VkCopyMemoryToMicromapInfoEXT structure defining the copy operation.
This command fulfills the same task as vkCmdCopyMemoryToMicromapEXT but is executed by the host.
This command can accept micromaps produced by either vkCmdCopyMicromapToMemoryEXT or vkCopyMicromapToMemoryEXT.
To copy a micromap to host accessible memory, call:
// Provided by VK_EXT_opacity_micromap
VkResult vkCopyMicromapToMemoryEXT(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
const VkCopyMicromapToMemoryInfoEXT* pInfo);
-
deviceis the device which ownspInfo->src. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
pInfois a pointer to a VkCopyMicromapToMemoryInfoEXT structure defining the copy operation.
This command fulfills the same task as vkCmdCopyMicromapToMemoryEXT but is executed by the host.
This command produces the same results as vkCmdCopyMicromapToMemoryEXT, 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 vkCmdCopyMemoryToMicromapEXT or vkCopyMemoryToMicromapEXT.
To query micromap size parameters on the host, call:
// Provided by VK_EXT_opacity_micromap
VkResult vkWriteMicromapsPropertiesEXT(
VkDevice device,
uint32_t micromapCount,
const VkMicromapEXT* pMicromaps,
VkQueryType queryType,
size_t dataSize,
void* pData,
size_t stride);
-
deviceis the device which owns the micromaps inpMicromaps. -
micromapCountis the count of micromaps for which to query the property. -
pMicromapsis a pointer to an array of existing previously built micromaps. -
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 an application-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 vkCmdWriteMicromapsPropertiesEXT but is executed by the host.
39.2.1. Displacement Micromap
A displacement micromap in an acceleration structure includes information in the VkAccelerationStructureTrianglesDisplacementMicromapNV to define a base triangle and displacement directions then uses displacement information encoded in the micromap to apply to those values to generate the final position.
Displacement Base Triangle
If displacementBiasAndScaleBuffer is provided the bias and scale are
fetched from that buffer.
If displacementBiasAndScaleBuffer is zero the bias and scale are
assumed to be 0.0 and 1.0, respectively.
Given an input position from the geometry, the base position and displacement vector used by the displacement are computed by:
basePosition = inputPosition + displacementVector × bias
baseDisplacementVector = displacementVector × scale
The parameters of each micro-vertex are derived from a combination of the base triangle parameters extracted from the bottom-level acceleration structure, the barycentrics of that micro-vertex, and the displacement value fetched from the displacement micromap corresponding to that micro-vertex.
microVertexBasePosition = lerp(basePositions, microVertexBarycentrics)
microVertexDisplacementVector = lerp(displacementVectors, microVertexBarycentrics)
microVertexDisplacedPosition = microVertexBasePosition + microVertexDisplacementVector × micromapDisplacementValue
Displacement Micromap Encoding
Displacement amounts are stored in displacement blocks, each covering a triangular region of microvertices. Depending on the subdivision level and encoding format, one or more displacement blocks combine to store all displacement values for a given displacement micromap.
Displacement blocks are organized along a space filling curve within a displacement micromap if more than one block is required, then micro-vertices are organized along the same space filling curve within a displacement micromap.
The space-filling curve is purely hierarchical with recursive splitting, similar to that for opacity micromaps but operating on vertices instead of triangles. To maintain that the hierarchical ordering is contiguous while keeping continuous winding, some triangles are flipped and wound differently.
The VK_DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV format is
an uncompressed, packed format which covers 64 microtriangles (subdivision
level 3) in a block.
The block contains 45 displacement values encoded as 11 bit unorm values and
stored tightly packed in the vertex order described above, occupying 495
bits.
This is followed by 15 unused bits then 2 reserved bits which must be 0.
If this block is used to store displacement for a subdivision level below 3
the later unused values are ignored.
| Section | Field | Entries | Bits per entry | Starting bit offset |
|---|---|---|---|---|
Displacement amounts |
Vertex 0 - 44 |
45 |
11 |
0 |
Unused |
1 |
15 |
495 |
|
Reserved |
Must be 0 |
1 |
2 |
510 |
The VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV and
VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV formats
store displacements in a compressed form to save space.
Both formats use the same compression algorithm, differing in the number of
bits used in the different fields.
The compression algorithm works by starting with fully specified anchor vertices, then for each level, predicting the value for the displacement and encoding the correction for that value, using fewer bits for each level of subdivision.
When adding a vertex in the recursive subdivision process between two adjacent displacement values, the predicted value is given by the rounded average of the two adjacent values as integers:
prediction = (A + B + 1) / 2
The decoded value after applying the correction is given by:
decoded = prediction + ( SignExtend(correction) << shift )
where correction is given by the corrections field for a given level and micro vertex and shift is given by the shifts field indexed from the level then by 4 values, selected from interior or the 3 edges in vertex order in that order.
The bit encoding for
VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV
| Section | Field | Entries | Bits per entry | Starting bit offset |
|---|---|---|---|---|
Anchors |
Vertex 0 - 2 |
3 |
11 |
0 |
Corrections |
Level 1 |
3 |
11 |
33 |
Level 2 |
9 |
11 |
66 |
|
Level 3 |
30 |
10 |
165 |
|
Level 4 |
108 |
5 |
465 |
|
Unused |
1 |
1 |
1005 |
|
Shifts |
Level 4 |
4 |
3 |
1006 |
Level 3 |
4 |
1 |
1018 |
|
Reserved |
Must be 0 |
1 |
2 |
1022 |
The bit encoding for
VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV
| Section | Field | Entries | Bits per entry | Starting bit offset |
|---|---|---|---|---|
Anchors |
Vertex 0 - 2 |
3 |
11 |
0 |
Corrections |
Level 1 |
3 |
11 |
33 |
Level 2 |
9 |
8 |
66 |
|
Level 3 |
30 |
4 |
138 |
|
Level 4 |
108 |
2 |
258 |
|
Level 5 |
408 |
1 |
474 |
|
Unused |
1 |
88 |
882 |
|
Shifts |
Level 5 |
4 |
4 |
970 |
Level 4 |
4 |
4 |
986 |
|
Level 3 |
4 |
3 |
1002 |
|
Level 2 |
4 |
2 |
1014 |
|
Reserved |
Must be 0 |
1 |
2 |
1022 |
40. 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
a pipeline trace ray instruction
.
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.
40.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.
In case multiple instances are intersected by a ray, the ray transformation into the space of the instance is invariant under the order in which these instances are encountered in the top-level acceleration structure.
|
Note
|
Applying multiple forward and reverse transforms to a ray to transition from one instance to another could result in accumulated errors. Thus an implementation should behave as if the ray is transformed from the origin for each instance independently. |
Next, rays are tested against geometries in a 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 a pipeline trace
ray instruction, these values are available as a vector of 2 32-bit
floating-point values in the HitAttributeKHR storage class.
For linear swept sphere intersection candidate, the ray t value along
with a single u parameter suffice to identify the hit.
The u value specifies the position of the hit along the LSS
midsection, within the range [0, 1].
If the u value is exactly 0 or 1, then the intersection occurred
on the respective endcap 0, or endcap 1.
For pure sphere primitives, u is always set to 0.
LSS primitives may be self-enclosing if one of the endcap spheres is
completely enclosed within the other, and both endcaps are enabled.
In these instances, only the outer of the two endcaps is intersection
tested, and u will be returned as 0 or 1 accordingly.
For rays that originate inside a LSS or sphere primitive, or enter through
an absent endcap, no intersections will be reported.
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.
40.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.
|
Note
|
Because of the complexity of a definition of watertightness the language above does not list a must requirement but it is expected and tested that implementations will perform watertight intersection tests. |
For LSS primitives, connected LSS might overlap not only at the shared vertex endcap but also along their midsections. This applies even if an LSS disables the shared endcap. As such, there is no clear equivalent edge or vertex that could deterministically map a hit to just one of the LSS. So, unlike the ray-triangle intersection, the ray-LSS intersection provides no single-hit guarantee for LSS, including those that share a vertex causing the LSS to overlap. However, as with triangles, LSS intersection still returns the closest hit.
40.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.
40.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 pipeline
trace ray instructions will all behave as if SkipTrianglesKHR was
included in their 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 pipeline trace
ray instructions will all behave as if SkipAABBsKHR was included in
their Ray Flags operand.
40.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.
40.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 a pipeline trace
ray instruction, 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.
For LSS or sphere intersections, the HitKindKHR built-in is set to
HitKindLssPrimitiveNV or HitKindSpherePrimitiveNV respectively.
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.
40.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 initially determined as opaque if
VK_GEOMETRY_OPAQUE_BIT_KHR was included in the
VkGeometryNV::flags
or
VkAccelerationStructureGeometryKHR::flags
when the geometry it intersected with was built, otherwise it is considered
non-opaque.
If the geometry includes an opacity micromap, the opacity of the intersection at this point is instead derived as described in Ray Opacity Micromap.
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.
40.2.5. Ray Opacity Micromap
A VK_GEOMETRY_TYPE_TRIANGLES_KHR geometry in the acceleration
structure may have an opacity micromap associated with it to give
finer-grained opacity information.
If the intersection candidate is with a geometry with an associated opacity
micromap and VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_BIT_EXT is
not set in its instance then the micromap is used to determine geometry
opacity instead of the VK_GEOMETRY_OPAQUE_BIT_KHR flag in the
geometry.
The opacity information in the micromap object is accessed using the candidate intersection u and v coordinates. The integer u and v are computed from ⌊u⌋ + ⌊v⌋, clamping ⌊u⌋ as needed to keep the sum less than or equal to 1 << subdivisionlevel. These values are mapped into a linear index with a space filling curve which is defined recursively by traversing into the sub-triangle nearest vertex 0, then the middle triangle with ordering flipped, then nearest vertex 1 then nearest vertex 2.
|
Note
|
This encoding is spatially coherent, purely hierarchical, and allows a bit-parallel conversion between barycentric address and index values. See the appendix for reference code implementing this mapping. |
The result of the opacity micromap lookup and operations is to treat the
intersection as opaque, non-opaque, or ignored.
The interpretation of the values depends on
VK_GEOMETRY_INSTANCE_FORCE_OPACITY_MICROMAP_2_STATE_BIT_EXT in the
instance of the candidate intersection or
ForceOpacityMicromap2StateEXT ray flags on the ray.
If either is set, the opacity micromap information is interpreted in 2 state
override mode.
If the result of the micromap lookup is to treat the intersection candidate
as ignored, no further processing of that candidate is done.
If the associated opacity micromap has format
VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT, each element of the micromap
is represented by a single bit at the index derived above.
If the associated opacity micromap has format
VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT, each element is represented by
a two bit value at the index derived above.
| 4 State value | 2 State value | Special index value | 2 State override | Result |
|---|---|---|---|---|
0 |
0 |
|
Y |
Ignored |
0 |
0 |
|
N |
Ignored |
1 |
1 |
|
Y |
Opaque |
1 |
1 |
|
N |
Opaque |
2 |
|
Y |
Ignored |
|
2 |
|
N |
Non-opaque |
|
3 |
|
Y |
Opaque |
|
3 |
|
N |
Non-opaque |
40.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.
40.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 application-provided AABB. To avoid propagating false intersections the application should verify the intersection candidate before reporting any hits and only report intersections within the bounds of the desired geometry. Reporting an intersection outside the AABB either through the implementation giving a conservative bound or reporting a t out of range is legal but may result in unpredictable closest hit results.
If the ray was traced with a pipeline trace
ray instruction, 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 from the intersection with 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 a pipeline trace
ray instruction, 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.
40.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 a pipeline trace
ray instruction, 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.
40.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.
40.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 pipeline trace ray
instructions which can invoke a closest hit shader, 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 the
pipeline trace ray instruction 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 a pipeline trace ray
instruction where no hit result was identified, the miss
shader identified by the Miss Index parameter of the instruction is
invoked.
Control returns to the shader that executed the pipeline trace ray
instruction 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.
41. 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, a pipeline
trace ray instruction 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.
41.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 following table lists all shader call instructions and which stages each one can directly call.
| Instruction | Intersection | Any-Hit | Closest Hit | Miss | Callable |
|---|---|---|---|---|---|
|
X |
X |
X |
X |
|
|
X |
X |
X |
X |
|
|
X |
||||
|
X |
||||
|
X |
X |
|||
|
X |
X |
|||
|
X |
X |
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 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,
OpReorderThreadWithHintNV, OpReorderThreadWithHitObjectNV,
OpReportIntersectionKHR, and OpExecuteCallableKHR instructions are
invocation repack instructions.
The invocations that are executing before a shader call 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 shader call instruction are ordered by program-order and do not require explicit synchronization.
41.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 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.
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 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 a VkDeviceAddress of the ray generation shader binding table record used by this command. -
raygenShaderRecordSizeis a VkDeviceSize number of bytes corresponding to the ray generation shader binding table record at base addressraygenShaderRecordAddress. -
missShaderBindingTableAddressis a VkDeviceAddress of the first record in the miss shader binding table used by this command. -
missShaderBindingTableSizeis a VkDeviceSize number of bytes corresponding to the total size of the miss shader binding table atmissShaderBindingTableAddressthat may be accessed by this command. -
missShaderBindingTableStrideis a VkDeviceSize number of bytes between records of the miss shader binding table. -
hitShaderBindingTableAddressis a VkDeviceAddress of the first record in the hit shader binding table used by this command. -
hitShaderBindingTableSizeis a VkDeviceSize number of bytes corresponding to the total size of the hit shader binding table athitShaderBindingTableAddressthat may be accessed by this command. -
hitShaderBindingTableStrideis a VkDeviceSize number of bytes between records of the hit shader binding table. -
callableShaderBindingTableAddressis a VkDeviceAddress of the first record in the callable shader binding table used by this command. -
callableShaderBindingTableSizeis a VkDeviceSize number of bytes corresponding to the total size of the callable shader binding table atcallableShaderBindingTableAddressthat may be accessed by this command. -
callableShaderBindingTableStrideis a VkDeviceSize number 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.
41.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 |
41.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 pipeline trace ray
instructions.
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
pipeline trace ray instructions.
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
41.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. |
41.5. Ray Tracing Capture Replay
In a similar way to
bufferDeviceAddressCaptureReplay,
the rayTracingPipelineShaderGroupHandleCaptureReplay feature allows the
querying of opaque data which can be used in a future replay.
During the capture phase, capture/replay tools are expected to query opaque data for shader group handle replay using vkGetRayTracingCaptureReplayShaderGroupHandlesKHR.
Providing the opaque data during replay, using
VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle
at pipeline creation time, causes the implementation to generate identical
shader group handles to those in the capture phase, allowing capture/replay
tools to reuse previously recorded shader binding table buffer contents or
to obtain the same handles by calling
vkGetRayTracingCaptureReplayShaderGroupHandlesKHR again.
41.6. Ray Tracing Validation
Ray tracing validation can help root cause application issues and improve performance. Unlike existing validation layers, ray tracing validation performs checks at an implementation level, which helps identify potential problems that may not be caught by the layer.
By enabling the ray tracing validation feature, warnings and errors can be delivered straight from a ray tracing implementation to the application through a messenger callback registered with the implementation, where they can be processed through existing application-side debugging or logging systems.
42. Memory Decompression
To decompress data between one or more memory regions call:
// Provided by VK_NV_memory_decompression
void vkCmdDecompressMemoryNV(
VkCommandBuffer commandBuffer,
uint32_t decompressRegionCount,
const VkDecompressMemoryRegionNV* pDecompressMemoryRegions);
-
commandBufferis the command buffer into which the command will be recorded. -
decompressRegionCountis the number of memory regions to decompress. -
pDecompressMemoryRegionsis a pointer to an array ofdecompressRegionCountVkDecompressMemoryRegionNV structures specifying decompression parameters.
Each region specified in pDecompressMemoryRegions is decompressed from
the source to destination region based on the specified decompression
method.
The VkDecompressMemoryRegionNV structure is defined as:
// Provided by VK_NV_memory_decompression
typedef struct VkDecompressMemoryRegionNV {
VkDeviceAddress srcAddress;
VkDeviceAddress dstAddress;
VkDeviceSize compressedSize;
VkDeviceSize decompressedSize;
VkMemoryDecompressionMethodFlagsNV decompressionMethod;
} VkDecompressMemoryRegionNV;
-
srcAddressis the address where compressed data is stored. -
dstAddressis the destination address where decompressed data will be written. -
compressedSizeis the size of compressed data in bytes. -
decompressedSizeis the size of decompressed data in bytes. -
decompressionMethodis a bitmask ofVkMemoryDecompressionMethodFlagBitsNVwith a single bit set specifying the method used to decompress data.
To decompress data between one or more memory regions by specifying decompression parameters indirectly in a buffer, call:
// Provided by VK_NV_memory_decompression
void vkCmdDecompressMemoryIndirectCountNV(
VkCommandBuffer commandBuffer,
VkDeviceAddress indirectCommandsAddress,
VkDeviceAddress indirectCommandsCountAddress,
uint32_t stride);
-
commandBufferis the command buffer into which the command will be recorded. -
indirectCommandsAddressis the device address containing decompression parameters laid out as an array of VkDecompressMemoryRegionNV structures. -
indirectCommandsCountAddressis the device address containing the decompression count. -
strideis the byte stride between successive sets of decompression parameters located starting fromindirectCommandsAddress.
Each region specified in indirectCommandsAddress is decompressed from
the source to destination region based on the specified decompression
method.
Bits which can be set in
VkDecompressMemoryRegionNV::decompressionMethod specifying the
decompression method to select, or returned in
VkPhysicalDeviceMemoryDecompressionPropertiesNV::decompressionMethods
specifying the available decompression methods are:
// Provided by VK_NV_memory_decompression
// Flag bits for VkMemoryDecompressionMethodFlagBitsNV
typedef VkFlags64 VkMemoryDecompressionMethodFlagBitsNV;
static const VkMemoryDecompressionMethodFlagBitsNV VK_MEMORY_DECOMPRESSION_METHOD_GDEFLATE_1_0_BIT_NV = 0x00000001ULL;
-
VK_MEMORY_DECOMPRESSION_METHOD_GDEFLATE_1_0_BIT_NVspecifies that the GDeflate 1.0 algorithm is used to decompress data.
// Provided by VK_NV_memory_decompression
typedef VkFlags64 VkMemoryDecompressionMethodFlagsNV;
VkMemoryDecompressionMethodFlagsNV is a bitmask type for specifying a
mask of one or more VkMemoryDecompressionMethodFlagBitsNV:
43. Video Coding
Vulkan implementations may expose one or more queue families supporting video coding operations. These operations are performed by recording them into a command buffer within a video coding scope, and submitting them to queues with compatible video coding capabilities.
The Vulkan video functionalities are designed to be made available through a set of APIs built on top of each other, consisting of:
-
A core API providing common video coding functionalities,
-
APIs providing codec-independent video decode and video encode related functionalities, respectively,
-
Additional codec-specific APIs built on top of those.
This chapter details the fundamental components and operations of these.
43.1. Video Picture Resources
In the context of video coding, multidimensional arrays of image data that can be used as the source or target of video coding operations are referred to as video picture resources. They may store additional metadata that includes implementation-private information used during the execution of video coding operations, as discussed later.
Video picture resources are backed by VkImage objects. Individual subregions of VkImageView objects created from such resources can be used as decode output pictures, encode input pictures, reconstructed pictures, and/or reference pictures.
The parameters of a video picture resource are specified using a
VkVideoPictureResourceInfoKHR structure.
The VkVideoPictureResourceInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoPictureResourceInfoKHR {
VkStructureType sType;
const void* pNext;
VkOffset2D codedOffset;
VkExtent2D codedExtent;
uint32_t baseArrayLayer;
VkImageView imageViewBinding;
} VkVideoPictureResourceInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
codedOffsetis the offset in texels of the image subregion to use. -
codedExtentis the size in pixels of the coded image data. -
baseArrayLayeris the array layer of the image view specified inimageViewBindingto use as the video picture resource. -
imageViewBindingis an image view representing the video picture resource.
The image subresource referred to by such a structure is defined as the
image array layer index specified in baseArrayLayer relative to the
image subresource range the image view specified in imageViewBinding
was created with.
The meaning of the codedOffset and codedExtent depends on the
command and context the video picture resource is used in, as well as on the
used video profile and corresponding codec-specific
semantics, as described later.
A video picture resource is uniquely defined by the image subresource
referred to by an instance of this structure, together with the
codedOffset and codedExtent members that identify the image
subregion within the image subresource referenced corresponding to the video
picture resource according to the particular codec-specific semantics.
Accesses to image data within a video picture resource happen at the
granularity indicated by
VkVideoCapabilitiesKHR::pictureAccessGranularity, as returned by
vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile.
As a result, given an effective image subregion corresponding to a video
picture resource, the actual image subregion accessed may be larger than
that as it may include additional padding texels due to the picture access
granularity.
Any writes performed by video coding operations to such padding texels will
result in undefined texel values.
Two video picture resources match if they refer to the same image
subresource and they specify identical codedOffset and
codedExtent values.
43.2. Decoded Picture Buffer
An integral part of video coding pipelines is the reconstruction of pictures from a compressed video bitstream. A reconstructed picture is a video picture resource resulting from this process.
Such reconstructed pictures can be used as reference pictures in subsequent video coding operations to provide predictions of the values of samples of subsequently decoded or encoded pictures. The correct use of such reconstructed pictures as reference pictures is driven by the video compression standard, the implementation, and the application-specific use cases.
The list of reference pictures used to provide such predictions within a single video coding operation is referred to as the list of active reference pictures.
The decoded picture buffer (DPB) is an indexed data structure that
maintains the set of reference pictures available to be used in video coding
operations.
Individual indexed entries of the DPB are referred to as the
decoded picture buffer (DPB) slots.
The range of valid DPB slot indices is between zero and
N-1, where N is the capacity of the DPB.
Each DPB slot can refer to a reference picture containing a video frame
or can refer to up to two reference pictures containing the top and/or
bottom fields that, when both present, together represent a full video
frame
.
In Vulkan, the state and the backing store of the DPB is separated as follows:
-
The state of individual DPB slots is maintained by video session objects.
-
The backing store of DPB slots is provided by subregions of VkImage objects used as video picture resources.
In addition, the implementation may also maintain opaque metadata associated with DPB slots, including:
Such metadata may be stored by the implementation as part of the DPB slot state maintained by the video session, or as part of the video picture resource backing the DPB slot.
Any metadata stored in the video picture resources backing DPB slots are independent of the video session used to store it, hence such video picture resources can be shared with other video sessions. Correspondingly, any metadata that is dependent on the video session will always be stored as part of the DPB slot state maintained by that video session.
The responsibility of managing the DPB is split between the application and the implementation as follows:
-
The application maintains the association between DPB slot indices and corresponding video picture resources.
-
The implementation maintains global and per-slot opaque reference picture metadata.
In addition, the application is also responsible for managing the mapping between the codec-specific picture IDs and DPB slots, and any other codec-specific states unless otherwise specified.
43.2.1. DPB Slot States
At a given time, each DPB slot is either in active or inactive state. Initially, all DPB slots managed by a video session are in inactive state.
A DPB slot can be activated by using it as the target of picture reconstruction in a video coding operation with the reconstructed picture requested to be set up as a reference picture, according to the codec-specific semantics, changing its state to active and associating it with a picture reference to the reconstructed pictures.
Some video coding standards allow multiple picture references to be associated with a single DPB slot. In this case the state of the individual picture references can be independently updated.
|
Note
|
As an example, H.264 decoding allows associating a separate top field and bottom field picture with the same DPB slot. |
As part of reference picture setup, the implementation may also generate reference picture metadata. Such reference picture metadata is specific to each picture reference associated with the DPB slot.
If such a video coding operation completes successfully, the activated DPB slot will have a valid picture reference and the reconstructed picture is associated with the DPB slot. This is true even if the DPB slot is used as the target of a picture reconstruction that only sets up a top field or bottom field reference picture and thus does not yet refer to a complete frame. However, if any data provided as input to such a video coding operation is not compliant with the video compression standard used, that video coding operation may complete unsuccessfully, in which case the activated DPB slot will have an invalid picture reference. This is true even if the DPB slot previously had a valid picture reference to a top field or bottom field reference picture, but the reconstruction of the other field corresponding to the DPB slot failed.
The application can use queries to get feedback about the outcome of video coding operations and use the resulting VkQueryResultStatusKHR value to determine whether the video coding operation completed successfully (result status is positive) or unsuccessfully (result status is negative).
Using a reference picture associated with a DPB slot that has an invalid picture reference as an active reference picture in subsequent video coding operations is legal, however, the contents of the outputs of such operations are undefined, and any DPB slots activated by such video coding operations will also have an invalid picture reference. This is true even if such video coding operations may otherwise complete successfully.
A DPB slot can also be deactivated by the application, changing its state to inactive and invalidating any picture references and reference picture metadata associated with the DPB slot.
If an already active DPB slot is used as the target of picture reconstruction in a video coding operation, but the decoded picture is not requested to be set up as a reference picture, according to the codec-specific semantics, no reference picture setup happens and the corresponding picture reference and reference picture metadata is invalidated within the DPB slot. If the DPB slot no longer has any associated picture references after such an operation, the DPB slot is implicitly deactivated.
If an already active DPB slot is used as the target of picture reconstruction when decoding a field picture that is not marked as reference, then the behavior is as follows:
-
If the DPB slot is currently associated with a frame, then the DPB slot is deactivated.
-
If the DPB slot is not currently associated with a top field picture and the decoded picture is a top field picture, or if the DPB slot is not currently associated with a bottom field picture and the decoded picture is a bottom field picture, then the other field picture association of the DPB slot, if any, is not disturbed.
-
If the DPB slot is currently associated with a top field picture and the decoded picture is a top field picture, or if the DPB slot is currently associated with a bottom field picture and the decoded picture is a bottom field picture, then that picture association is invalidated, without disturbing the other field picture association, if any. If the DPB slot no longer has any associated picture references after such an operation, the DPB slot is implicitly deactivated.
A DPB slot can be activated with a new frame even if it is already active. In this case all previous associations of the DPB slots with reference pictures are replaced with an association with the reconstructed picture used to activate it.
If an already active DPB slot is activated with a reconstructed field picture, then the behavior is as follows:
-
If the DPB slot is currently associated with a frame, then that association is replaced with an association with the reconstructed field picture used to activate it.
-
If the DPB slot is not currently associated with a top field picture and the DPB slot is activated with a top field picture, or if the DPB slot is not currently associated with a bottom field picture and the DPB slot is activated with a bottom field picture, then the DPB slot is associated with the reconstructed field picture used to activate it, without disturbing the other field picture association, if any.
-
If the DPB slot is currently associated with a top field picture and the DPB slot is activated with a new top field picture, or if the DPB slot is currently associated with a bottom field picture and the DPB slot is activated with a new bottom field picture, then that association is replaced with an association with the reconstructed field picture used to activate it, without disturbing the other field picture association, if any.
43.3. Video Profiles
The VkVideoProfileInfoKHR structure is defined as follows:
// Provided by VK_KHR_video_queue
typedef struct VkVideoProfileInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoCodecOperationFlagBitsKHR videoCodecOperation;
VkVideoChromaSubsamplingFlagsKHR chromaSubsampling;
VkVideoComponentBitDepthFlagsKHR lumaBitDepth;
VkVideoComponentBitDepthFlagsKHR chromaBitDepth;
} VkVideoProfileInfoKHR;
-
sTypeis a VkStructureType value identifying 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.
Video profiles are provided as input to video capability queries such as vkGetPhysicalDeviceVideoCapabilitiesKHR or vkGetPhysicalDeviceVideoFormatPropertiesKHR, as well as when creating resources to be used by video coding operations such as images, buffers, query pools, and video sessions.
The full description of a video profile is specified by an instance of this
structure, and the codec-specific and auxiliary structures provided in its
pNext chain.
When this structure is specified as an input parameter to
vkGetPhysicalDeviceVideoCapabilitiesKHR, or through the
pProfiles member of a VkVideoProfileListInfoKHR structure in the
pNext chain of the input parameter of a query command such as
vkGetPhysicalDeviceVideoFormatPropertiesKHR or
vkGetPhysicalDeviceImageFormatProperties2, the following error codes
indicate specific causes of the failure of the query operation:
-
VK_ERROR_VIDEO_PICTURE_LAYOUT_NOT_SUPPORTED_KHRspecifies that the requested video picture layout (e.g. through thepictureLayoutmember of a VkVideoDecodeH264ProfileInfoKHR structure included in thepNextchain ofVkVideoProfileInfoKHR) is not supported. -
VK_ERROR_VIDEO_PROFILE_OPERATION_NOT_SUPPORTED_KHRspecifies that a video profile operation specified byvideoCodecOperationis not supported. -
VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHRspecifies that video format parameters specified bychromaSubsampling,lumaBitDepth, orchromaBitDepthare not supported. -
VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHRspecifies that the codec-specific parameters corresponding to the video codec operation are not supported.
Possible values of VkVideoProfileInfoKHR::videoCodecOperation,
specifying the type of video coding operation and video compression standard
used by a video profile, are:
// Provided by VK_KHR_video_queue
typedef enum VkVideoCodecOperationFlagBitsKHR {
VK_VIDEO_CODEC_OPERATION_NONE_KHR = 0,
// Provided by VK_KHR_video_encode_h264
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR = 0x00010000,
// Provided by VK_KHR_video_encode_h265
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR = 0x00020000,
// Provided by VK_KHR_video_decode_h264
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR = 0x00000001,
// Provided by VK_KHR_video_decode_h265
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR = 0x00000002,
// Provided by VK_KHR_video_decode_av1
VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHR = 0x00000004,
// Provided by VK_KHR_video_encode_av1
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR = 0x00040000,
// Provided by VK_KHR_video_decode_vp9
VK_VIDEO_CODEC_OPERATION_DECODE_VP9_BIT_KHR = 0x00000008,
} VkVideoCodecOperationFlagBitsKHR;
-
VK_VIDEO_CODEC_OPERATION_NONE_KHRspecifies that no video codec operations are supported. -
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHRspecifies support for H.264 decode operations. -
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHRspecifies support for H.265 decode operations. -
VK_VIDEO_CODEC_OPERATION_DECODE_VP9_BIT_KHRspecifies support for VP9 decode operations. -
VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHRspecifies support for AV1 decode operations. -
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHRspecifies support for H.264 encode operations. -
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHRspecifies support for H.265 encode operations. -
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHRspecifies support for AV1 encode operations.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoCodecOperationFlagsKHR;
VkVideoCodecOperationFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoCodecOperationFlagBitsKHR.
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_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_KHRspecifies that the format is monochrome. -
VK_VIDEO_CHROMA_SUBSAMPLING_420_BIT_KHRspecified that the format is 4:2:0 chroma subsampled, i.e. the two chroma components are sampled horizontally and vertically at half the sample rate of the luma component. -
VK_VIDEO_CHROMA_SUBSAMPLING_422_BIT_KHR- the format is 4:2:2 chroma subsampled, i.e. the two chroma components are sampled horizontally at half the sample rate of luma component. -
VK_VIDEO_CHROMA_SUBSAMPLING_444_BIT_KHR- the format is 4:4:4 chroma sampled, i.e. all three components of the Y′CBCR format are sampled at the same rate, thus there is no chroma subsampling.
Chroma subsampling is described in more detail in the Chroma Reconstruction section.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoChromaSubsamplingFlagsKHR;
VkVideoChromaSubsamplingFlagsKHR is a bitmask type for setting a mask
of zero or more VkVideoChromaSubsamplingFlagBitsKHR.
Possible values for the video format component bit depth are:
// 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_KHRspecifies a component bit depth of 8 bits. -
VK_VIDEO_COMPONENT_BIT_DEPTH_10_BIT_KHRspecifies a component bit depth of 10 bits. -
VK_VIDEO_COMPONENT_BIT_DEPTH_12_BIT_KHRspecifies a component bit depth of 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.
Additional information about the video decode use case can be provided by
adding a VkVideoDecodeUsageInfoKHR structure to the pNext chain
of VkVideoProfileInfoKHR.
The VkVideoDecodeUsageInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_queue
typedef struct VkVideoDecodeUsageInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoDecodeUsageFlagsKHR videoUsageHints;
} VkVideoDecodeUsageInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoUsageHintsis a bitmask of VkVideoDecodeUsageFlagBitsKHR specifying hints about the intended use of the video decode profile.
The following bits can be specified in
VkVideoDecodeUsageInfoKHR::videoUsageHints as a hint about the
video decode use case:
// Provided by VK_KHR_video_decode_queue
typedef enum VkVideoDecodeUsageFlagBitsKHR {
VK_VIDEO_DECODE_USAGE_DEFAULT_KHR = 0,
VK_VIDEO_DECODE_USAGE_TRANSCODING_BIT_KHR = 0x00000001,
VK_VIDEO_DECODE_USAGE_OFFLINE_BIT_KHR = 0x00000002,
VK_VIDEO_DECODE_USAGE_STREAMING_BIT_KHR = 0x00000004,
} VkVideoDecodeUsageFlagBitsKHR;
-
VK_VIDEO_DECODE_USAGE_TRANSCODING_BIT_KHRspecifies that video decoding is intended to be used in conjunction with video encoding to transcode a video bitstream with the same and/or different codecs. -
VK_VIDEO_DECODE_USAGE_OFFLINE_BIT_KHRspecifies that video decoding is intended to be used to consume a local video bitstream. -
VK_VIDEO_DECODE_USAGE_STREAMING_BIT_KHRspecifies that video decoding is intended to be used to consume a video bitstream received as a continuous flow over network.
|
Note
|
There are no restrictions on the combination of bits that can be specified by the application. However, applications should use reasonable combinations in order for the implementation to be able to select the most appropriate mode of operation for the particular use case. |
// Provided by VK_KHR_video_decode_queue
typedef VkFlags VkVideoDecodeUsageFlagsKHR;
VkVideoDecodeUsageFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoDecodeUsageFlagBitsKHR.
Additional information about the video encode use case can be provided by
adding a VkVideoEncodeUsageInfoKHR structure to the pNext chain
of VkVideoProfileInfoKHR.
The VkVideoEncodeUsageInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeUsageInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeUsageFlagsKHR videoUsageHints;
VkVideoEncodeContentFlagsKHR videoContentHints;
VkVideoEncodeTuningModeKHR tuningMode;
} VkVideoEncodeUsageInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoUsageHintsis a bitmask of VkVideoEncodeUsageFlagBitsKHR specifying hints about the intended use of the video encode profile. -
videoContentHintsis a bitmask of VkVideoEncodeContentFlagBitsKHR specifying hints about the content to be encoded using the video encode profile. -
tuningModeis a VkVideoEncodeTuningModeKHR value specifying the tuning mode to use when encoding with the video profile.
The following bits can be specified in
VkVideoEncodeUsageInfoKHR::videoUsageHints as a hint about the
video encode use case:
// Provided by VK_KHR_video_encode_queue
typedef enum VkVideoEncodeUsageFlagBitsKHR {
VK_VIDEO_ENCODE_USAGE_DEFAULT_KHR = 0,
VK_VIDEO_ENCODE_USAGE_TRANSCODING_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_USAGE_STREAMING_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_USAGE_RECORDING_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_USAGE_CONFERENCING_BIT_KHR = 0x00000008,
} VkVideoEncodeUsageFlagBitsKHR;
-
VK_VIDEO_ENCODE_USAGE_TRANSCODING_BIT_KHRspecifies that video encoding is intended to be used in conjunction with video decoding to transcode a video bitstream with the same and/or different codecs. -
VK_VIDEO_ENCODE_USAGE_STREAMING_BIT_KHRspecifies that video encoding is intended to be used to produce a video bitstream that is expected to be sent as a continuous flow over network. -
VK_VIDEO_ENCODE_USAGE_RECORDING_BIT_KHRspecifies that video encoding is intended to be used for real-time recording for offline consumption. -
VK_VIDEO_ENCODE_USAGE_CONFERENCING_BIT_KHRspecifies that video encoding is intended to be used in a video conferencing scenario.
|
Note
|
There are no restrictions on the combination of bits that can be specified by the application. However, applications should use reasonable combinations in order for the implementation to be able to select the most appropriate mode of operation for the particular use case. |
// Provided by VK_KHR_video_encode_queue
typedef VkFlags VkVideoEncodeUsageFlagsKHR;
VkVideoEncodeUsageFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoEncodeUsageFlagBitsKHR.
The following bits can be specified in
VkVideoEncodeUsageInfoKHR::videoContentHints as a hint about the
encoded video content:
// Provided by VK_KHR_video_encode_queue
typedef enum VkVideoEncodeContentFlagBitsKHR {
VK_VIDEO_ENCODE_CONTENT_DEFAULT_KHR = 0,
VK_VIDEO_ENCODE_CONTENT_CAMERA_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_CONTENT_DESKTOP_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_CONTENT_RENDERED_BIT_KHR = 0x00000004,
} VkVideoEncodeContentFlagBitsKHR;
-
VK_VIDEO_ENCODE_CONTENT_CAMERA_BIT_KHRspecifies that video encoding is intended to be used to encode camera content. -
VK_VIDEO_ENCODE_CONTENT_DESKTOP_BIT_KHRspecifies that video encoding is intended to be used to encode desktop content. -
VK_VIDEO_ENCODE_CONTENT_RENDERED_BIT_KHRspecified that video encoding is intended to be used to encode rendered (e.g. game) content.
|
Note
|
There are no restrictions on the combination of bits that can be specified by the application. However, applications should use reasonable combinations in order for the implementation to be able to select the most appropriate mode of operation for the particular content type. |
// Provided by VK_KHR_video_encode_queue
typedef VkFlags VkVideoEncodeContentFlagsKHR;
VkVideoEncodeContentFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoEncodeContentFlagBitsKHR.
Possible video encode tuning mode values are as follows:
// Provided by VK_KHR_video_encode_queue
typedef enum VkVideoEncodeTuningModeKHR {
VK_VIDEO_ENCODE_TUNING_MODE_DEFAULT_KHR = 0,
VK_VIDEO_ENCODE_TUNING_MODE_HIGH_QUALITY_KHR = 1,
VK_VIDEO_ENCODE_TUNING_MODE_LOW_LATENCY_KHR = 2,
VK_VIDEO_ENCODE_TUNING_MODE_ULTRA_LOW_LATENCY_KHR = 3,
VK_VIDEO_ENCODE_TUNING_MODE_LOSSLESS_KHR = 4,
} VkVideoEncodeTuningModeKHR;
-
VK_VIDEO_ENCODE_TUNING_MODE_DEFAULT_KHRspecifies the default tuning mode. -
VK_VIDEO_ENCODE_TUNING_MODE_HIGH_QUALITY_KHRspecifies that video encoding is tuned for high quality. When using this tuning mode, the implementation may compromise the latency of video encoding operations to improve quality. -
VK_VIDEO_ENCODE_TUNING_MODE_LOW_LATENCY_KHRspecifies that video encoding is tuned for low latency. When using this tuning mode, the implementation may compromise quality to increase the performance and lower the latency of video encode operations. -
VK_VIDEO_ENCODE_TUNING_MODE_ULTRA_LOW_LATENCY_KHRspecifies that video encoding is tuned for ultra-low latency. When using this tuning mode, the implementation may compromise quality to maximize the performance and minimize the latency of video encoding operations. -
VK_VIDEO_ENCODE_TUNING_MODE_LOSSLESS_KHRspecifies that video encoding is tuned for lossless encoding. When using this tuning mode, video encode operations produce lossless output.
The VkVideoProfileListInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoProfileListInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t profileCount;
const VkVideoProfileInfoKHR* pProfiles;
} VkVideoProfileListInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
profileCountis the number of elements in thepProfilesarray. -
pProfilesis a pointer to an array of VkVideoProfileInfoKHR structures.
|
Note
|
Video transcoding is an example of a use case that necessitates the specification of multiple profiles in various contexts. |
When the application provides a video decode profile and one or more video encode profiles in the profile list, the implementation ensures that any capabilitities returned or resources created are suitable for the video transcoding use cases without the need for manual data transformations.
43.4. Video Capabilities
43.4.1. Video Coding Capabilities
To query video coding capabilities for a specific video profile, call:
// Provided by VK_KHR_video_queue
VkResult vkGetPhysicalDeviceVideoCapabilitiesKHR(
VkPhysicalDevice physicalDevice,
const VkVideoProfileInfoKHR* pVideoProfile,
VkVideoCapabilitiesKHR* pCapabilities);
-
physicalDeviceis the physical device from which to query the video decode or encode capabilities. -
pVideoProfileis a pointer to a VkVideoProfileInfoKHR structure. -
pCapabilitiesis a pointer to a VkVideoCapabilitiesKHR structure in which the capabilities are returned.
If the video profile described by pVideoProfile is
supported by the implementation, then this command returns VK_SUCCESS
and pCapabilities is filled with the capabilities supported with the
specified video profile.
Otherwise, one of the video-profile-specific
error codes are returned.
The VkVideoCapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoCapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkVideoCapabilityFlagsKHR flags;
VkDeviceSize minBitstreamBufferOffsetAlignment;
VkDeviceSize minBitstreamBufferSizeAlignment;
VkExtent2D pictureAccessGranularity;
VkExtent2D minCodedExtent;
VkExtent2D maxCodedExtent;
uint32_t maxDpbSlots;
uint32_t maxActiveReferencePictures;
VkExtensionProperties stdHeaderVersion;
} VkVideoCapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoCapabilityFlagBitsKHR specifying capability flags. -
minBitstreamBufferOffsetAlignmentis the minimum alignment for bitstream buffer offsets. -
minBitstreamBufferSizeAlignmentis the minimum alignment for bitstream buffer range sizes. -
pictureAccessGranularityis the granularity at which image access to video picture resources happen. -
minCodedExtentis the minimum width and height of the coded frames. -
maxCodedExtentis the maximum width and height of the coded frames. -
maxDpbSlotsis the maximum number of DPB slots supported by a single video session. -
maxActiveReferencePicturesis the maximum number of active reference pictures a single video coding operation can use. -
stdHeaderVersionis a VkExtensionProperties structure reporting the Video Std header name and version supported for the video profile.
|
Note
|
It is common for video compression standards to allow using all reference
pictures associated with active DPB slots as active reference pictures,
hence for video decode profiles the values returned in |
Bits which can be set in VkVideoCapabilitiesKHR::flags are:
// 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_KHRspecifies that video sessions support producing and consuming protected content. -
VK_VIDEO_CAPABILITY_SEPARATE_REFERENCE_IMAGES_BIT_KHRindicates that the video picture resources associated with the DPB slots of a video session can be backed by separateVkImageobjects. If this capability flag is not present, then all DPB slots of a video session must be associated with video picture resources backed by the sameVkImageobject (e.g. using different layers of the same image).
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoCapabilityFlagsKHR;
VkVideoCapabilityFlagsKHR is a bitmask type for setting a mask of zero
or more VkVideoCapabilityFlagBitsKHR.
43.4.2. Video Format Capabilities
To enumerate the supported video formats and corresponding capabilities for a specific 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 from which to query the video format properties. -
pVideoFormatInfois a pointer to a VkPhysicalDeviceVideoFormatInfoKHR structure specifying the usage and video profiles for which supported image formats and capabilities are 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 image formats and capabilities 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 application 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.
Video format properties are always queried with respect to a specific set of
video profiles.
These are specified by chaining the VkVideoProfileListInfoKHR
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 video transcoding, 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 video profiles specified via
VkVideoProfileListInfoKHR::pProfiles are not supported, then
this command 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 this command returns
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
This command also returns VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR if
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage does not include
the appropriate flags as dictated by the decode capability flags returned in
VkVideoDecodeCapabilitiesKHR::flags for any of the profiles
specified in the VkVideoProfileListInfoKHR structure provided in the
pNext chain of pVideoFormatInfo.
If the decode capability flags include
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR but not
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR, then in
order to query video format properties for decode DPB and output usage,
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage must include
both VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR and
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR.
Otherwise, the call will fail with
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
If the decode capability flags include
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR but not
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR, then in
order to query video format properties for decode DPB usage,
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage must include
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, but not
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR.
Otherwise, the call will fail with
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
Similarly, to query video format properties for decode output usage,
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage must include
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, but not
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR.
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 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. |
Multiple VkVideoFormatPropertiesKHR entries may be returned with the
same format member with different componentMapping,
imageType, or imageTiling values, as described later.
If VkPhysicalDeviceVideoFormatInfoKHR::imageUsage includes
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR or
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR, multiple
VkVideoFormatPropertiesKHR entries may be returned with the same
format, componentMapping, imageType, and imageTiling
member values, but different quantizationMapTexelSize returned in the
VkVideoFormatQuantizationMapPropertiesKHR structure, if one is
included in the VkVideoFormatPropertiesKHR::pNext chain, when
the queried quantization map type supports
multiple distinct quantization map
texel sizes.
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 VkVideoProfileListInfoKHR structure to the
pNext chain of VkPhysicalDeviceImageFormatInfo2.
The following applies to all VkVideoFormatPropertiesKHR entries
returned by vkGetPhysicalDeviceVideoFormatPropertiesKHR:
-
vkGetPhysicalDeviceFormatProperties2 must succeed when called with
VkVideoFormatPropertiesKHR::format -
If
VkVideoFormatPropertiesKHR::imageTilingisVK_IMAGE_TILING_OPTIMAL, then theoptimalTilingFeaturesreturned by vkGetPhysicalDeviceFormatProperties2 must include all format features required by the image usage flags reported inVkVideoFormatPropertiesKHR::imageUsageFlagsfor the format, as indicated in the Format Feature Dependent Usage Flags section. -
If
VkVideoFormatPropertiesKHR::imageTilingisVK_IMAGE_TILING_LINEAR, then thelinearTilingFeaturesreturned by vkGetPhysicalDeviceFormatProperties2 must include all format features required by the image usage flags reported inVkVideoFormatPropertiesKHR::imageUsageFlagsfor the format, as indicated in the Format Feature Dependent Usage Flags section. -
vkGetPhysicalDeviceImageFormatProperties2 must succeed when called with a VkPhysicalDeviceImageFormatInfo2 structure containing the following information:
-
The
pNextchain including the same VkVideoProfileListInfoKHR structure used to callvkGetPhysicalDeviceVideoFormatPropertiesKHR. -
formatset to the value ofVkVideoFormatPropertiesKHR::format. -
typeset to the value ofVkVideoFormatPropertiesKHR::imageType. -
tilingset to the value ofVkVideoFormatPropertiesKHR::imageTiling. -
usageset to the value ofVkVideoFormatPropertiesKHR::imageUsageFlags. -
flagsset to the value ofVkVideoFormatPropertiesKHR::imageCreateFlags.
-
The componentMapping member of VkVideoFormatPropertiesKHR
defines the ordering of the Y′CBCR color channels from the perspective of
the video codec operations specified in VkVideoProfileListInfoKHR.
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 structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkPhysicalDeviceVideoFormatInfoKHR {
VkStructureType sType;
const void* pNext;
VkImageUsageFlags imageUsage;
} VkPhysicalDeviceVideoFormatInfoKHR;
-
sTypeis a VkStructureType value identifying 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 VkVideoFormatPropertiesKHR structure 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 a VkStructureType value identifying 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.
The list of supported video format properties for a set of image usage
flags with respect to a video profile is defined as the
list of VkVideoFormatPropertiesKHR structures and any structures
included in its pNext chain, obtained by calling
vkGetPhysicalDeviceVideoFormatPropertiesKHR with
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage equal to the
VkImageUsageFlags in question and the
VkPhysicalDeviceVideoFormatInfoKHR::pNext chain including a
VkVideoProfileListInfoKHR structure with its pProfiles member
containing a single array element specifying the VkVideoProfileInfoKHR
structure chain describing the video profile in question.
43.5. Video Sessions
Video sessions are objects that represent and maintain the state needed to perform video decode or encode operations using a specific video profile.
In case of video encode profiles this includes the current rate control configuration and the currently set video encode quality level.
Video sessions are represented by VkVideoSessionKHR handles:
// Provided by VK_KHR_video_queue
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkVideoSessionKHR)
43.5.1. 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 video session. -
pCreateInfois a pointer to a VkVideoSessionCreateInfoKHR structure containing parameters to be used to create the video session. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pVideoSessionis a pointer to a VkVideoSessionKHR handle in which the resulting video session object is returned.
The resulting video session object is said to be created with the video
codec operation specified in
pCreateInfo->pVideoProfile->videoCodecOperation.
The name and version of the codec-specific Video Std header to be used with
the video session is specified by the VkExtensionProperties structure
pointed to by pCreateInfo->pStdHeaderVersion.
If a non-existent or unsupported Video Std header version is specified in
pCreateInfo->pStdHeaderVersion->specVersion, then this command returns
VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHR.
Video session objects are created in uninitialized state.
In order to transition the video session into initial state, the
application must issue a vkCmdControlVideoCodingKHR command with
VkVideoCodingControlInfoKHR::flags including
VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR.
Video session objects also maintain the
state of the DPB.
The number of DPB slots usable with the created video session is specified
in pCreateInfo->maxDpbSlots, and each slot is initially in the
inactive state.
Each DPB slot maintained by the created video session can refer to a reference picture representing a video frame.
In addition, if the videoCodecOperation member of the
VkVideoProfileInfoKHR structure pointed to by
pCreateInfo->pVideoProfile is
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR and the
pictureLayout member of the VkVideoDecodeH264ProfileInfoKHR
structure provided in the VkVideoProfileInfoKHR::pNext chain is
not VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_PROGRESSIVE_KHR, then the
created video session supports interlaced frames and each DPB
slot maintained by the created video session can instead refer to
separate top field and bottom field reference pictures
that together can represent a full video frame.
In this case, it is up to the application, driven by the video content,
whether it associates any individual DPB slot with separate top and/or
bottom field pictures or a single picture representing a full frame.
The created video session can be used to perform video coding operations
using video frames up to the maximum size specified in
pCreateInfo->maxCodedExtent.
The minimum frame size allowed is implicitly derived from
VkVideoCapabilitiesKHR::minCodedExtent, as returned by
vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile
specified by pCreateInfo->pVideoProfile.
Accordingly, the created video session is said to be created with a
minCodedExtent equal to that.
In case of video session objects created with a video encode operation,
implementations may return the
VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error if any of the
specified Video Std parameters do not adhere to the syntactic or semantic
requirements of the used video compression standard, or if values derived
from parameters according to the rules defined by the used video compression
standard do not adhere to the capabilities of the video compression standard
or the implementation.
|
Note
|
Applications should not rely on the
|
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 VkVideoProfileInfoKHR* pVideoProfile;
VkFormat pictureFormat;
VkExtent2D maxCodedExtent;
VkFormat referencePictureFormat;
uint32_t maxDpbSlots;
uint32_t maxActiveReferencePictures;
const VkExtensionProperties* pStdHeaderVersion;
} VkVideoSessionCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queueFamilyIndexis the index of the queue family the created video session will be used with. -
flagsis a bitmask of VkVideoSessionCreateFlagBitsKHR specifying creation flags. -
pVideoProfileis a pointer to a VkVideoProfileInfoKHR structure specifying the video profile the created video session will be used with. -
pictureFormatis the image format the created video session will be used with. IfpVideoProfile->videoCodecOperationspecifies a decode operation, thenpictureFormatis the image format of decode output pictures usable with the created video session. IfpVideoProfile->videoCodecOperationspecifies an encode operation, thenpictureFormatis the image format of encode input pictures usable with the created video session. -
maxCodedExtentis the maximum width and height of the coded frames the created video session will be used with. -
referencePictureFormatis the image format of reference pictures stored in the DPB the created video session will be used with. -
maxDpbSlotsis the maximum number of DPB Slots that can be used with the created video session. -
maxActiveReferencePicturesis the maximum number of active reference pictures that can be used in a single video coding operation using the created video session. -
pStdHeaderVersionis a pointer to a VkExtensionProperties structure requesting the Video Std header version to use for thevideoCodecOperationspecified inpVideoProfile.
Bits which can be set in VkVideoSessionCreateInfoKHR::flags
are:
// Provided by VK_KHR_video_queue
typedef enum VkVideoSessionCreateFlagBitsKHR {
VK_VIDEO_SESSION_CREATE_PROTECTED_CONTENT_BIT_KHR = 0x00000001,
// Provided by VK_KHR_video_encode_queue
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR = 0x00000002,
// Provided by VK_KHR_video_maintenance1
VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR = 0x00000004,
// Provided by VK_KHR_video_encode_quantization_map
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR = 0x00000008,
// Provided by VK_KHR_video_encode_quantization_map
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_EMPHASIS_MAP_BIT_KHR = 0x00000010,
// Provided by VK_KHR_video_decode_queue with VK_KHR_video_maintenance2
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHR = 0x00000020,
} VkVideoSessionCreateFlagBitsKHR;
-
VK_VIDEO_SESSION_CREATE_PROTECTED_CONTENT_BIT_KHRspecifies that the video session uses protected video content. -
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHRspecifies that the implementation is allowed to override video session parameters and other codec-specific encoding parameters to optimize video encode operations based on the use case information specified in the video profile and the used video encode quality level.NoteNot specifying
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHRdoes not guarantee that the implementation will not do any codec-specific parameter overrides, as certain overrides are necessary for the correct operation of the video encoder implementation due to limitations to the available encoding tools on that implementation. This flag, however, enables the implementation to apply further optimizing overrides. -
VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHRspecifies that queries within video coding scopes using the created video session are executed inline with video coding operations. -
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHRspecifies that the video session can be used to encode pictures with quantization delta maps. -
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_EMPHASIS_MAP_BIT_KHRspecifies that the video session can be used to encode pictures with emphasis maps. -
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHRspecifies that the application can specify video session parameters inline with video decode operations instead of sourcing them from the bound video session parameters object.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoSessionCreateFlagsKHR;
VkVideoSessionCreateFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoSessionCreateFlagBitsKHR.
43.5.2. Destroying a Video Session
To destroy a video session, call:
// Provided by VK_KHR_video_queue
void vkDestroyVideoSessionKHR(
VkDevice device,
VkVideoSessionKHR videoSession,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the video session. -
videoSessionis the video session to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
43.5.3. Video Session Memory Association
After creating a video session object, and before the object can be used to record video coding operations into command buffers using it, the application must allocate and bind device memory to the video session. Device memory is allocated separately (see Device Memory) and then associated with the video session.
Video sessions may have multiple memory bindings identified by unique unsigned integer values. Appropriate device memory must be bound to each such memory binding before using the video session to record command buffer commands with it.
To determine the memory requirements for a video session object, call:
// Provided by VK_KHR_video_queue
VkResult vkGetVideoSessionMemoryRequirementsKHR(
VkDevice device,
VkVideoSessionKHR videoSession,
uint32_t* pMemoryRequirementsCount,
VkVideoSessionMemoryRequirementsKHR* pMemoryRequirements);
-
deviceis the logical device that owns the video session. -
videoSessionis the video session to query. -
pMemoryRequirementsCountis a pointer to an integer related to the number of memory binding requirements available or queried, as described below. -
pMemoryRequirementsisNULLor a pointer to an array of VkVideoSessionMemoryRequirementsKHR structures in which the memory binding requirements of the video session are returned.
If pMemoryRequirements is NULL, then the number of memory bindings
required for the video session is returned in
pMemoryRequirementsCount.
Otherwise, pMemoryRequirementsCount must point to a variable set by
the application to the number of elements in the pMemoryRequirements
array, and on return the variable is overwritten with the number of memory
binding requirements actually written to pMemoryRequirements.
If pMemoryRequirementsCount is less than the number of memory bindings
required for the video session, then at most pMemoryRequirementsCount
elements will be written to pMemoryRequirements, and
VK_INCOMPLETE will be returned, instead of VK_SUCCESS, to
indicate that not all required memory binding requirements were returned.
The VkVideoSessionMemoryRequirementsKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoSessionMemoryRequirementsKHR {
VkStructureType sType;
void* pNext;
uint32_t memoryBindIndex;
VkMemoryRequirements memoryRequirements;
} VkVideoSessionMemoryRequirementsKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryBindIndexis the index of the memory binding. -
memoryRequirementsis a VkMemoryRequirements structure in which the requested memory binding requirements for the binding index specified bymemoryBindIndexare returned.
To attach memory to a video session object, call:
// Provided by VK_KHR_video_queue
VkResult vkBindVideoSessionMemoryKHR(
VkDevice device,
VkVideoSessionKHR videoSession,
uint32_t bindSessionMemoryInfoCount,
const VkBindVideoSessionMemoryInfoKHR* pBindSessionMemoryInfos);
-
deviceis the logical device that owns the video session. -
videoSessionis the video session to be bound with device memory. -
bindSessionMemoryInfoCountis the number of elements inpBindSessionMemoryInfos. -
pBindSessionMemoryInfosis a pointer to an array ofbindSessionMemoryInfoCountVkBindVideoSessionMemoryInfoKHR structures specifying memory regions to be bound to specific memory bindings of the video session.
The valid usage statements below refer to the VkMemoryRequirements
structure corresponding to a specific element of
pBindSessionMemoryInfos, which is defined as follows:
-
If the
memoryBindIndexmember of the element ofpBindSessionMemoryInfosin question matches thememoryBindIndexmember of one of the elements returned inpMemoryRequirementswhen vkGetVideoSessionMemoryRequirementsKHR is called with the samevideoSessionand withpMemoryRequirementsCountequal tobindSessionMemoryInfoCount, then thememoryRequirementsmember of that element ofpMemoryRequirementsis the VkMemoryRequirements structure corresponding to the element ofpBindSessionMemoryInfosin question. -
Otherwise the element of
pBindSessionMemoryInfosin question is said to not have a corresponding VkMemoryRequirements structure.
The VkBindVideoSessionMemoryInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkBindVideoSessionMemoryInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t memoryBindIndex;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
VkDeviceSize memorySize;
} VkBindVideoSessionMemoryInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryBindIndexis the memory binding index to bind memory to. -
memoryis the allocated device memory to be bound to the video session’s memory binding 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.
43.6. Video Profile Compatibility
Resources and query pools used with a particular video session must be compatible with the video profile the video session was created with.
A VkBuffer is compatible with a video profile if it was created with
the VkBufferCreateInfo::pNext chain including a
VkVideoProfileListInfoKHR structure with its pProfiles member
containing an element matching the VkVideoProfileInfoKHR structure
chain describing the video profile, and
VkBufferCreateInfo::usage including at least one bit specific to
video coding usage.
-
VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR -
VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR -
VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR -
VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR
A VkBuffer is also compatible with a video profile if it was created
with VkBufferCreateInfo::flags including
VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR.
A VkImage is compatible with a video profile if it was created with
the VkImageCreateInfo::pNext chain including a
VkVideoProfileListInfoKHR structure with its pProfiles member
containing an element matching the VkVideoProfileInfoKHR structure
chain describing the video profile, and VkImageCreateInfo::usage
including at least one bit specific to video coding usage.
-
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR -
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_DST_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR
A VkImage is also compatible with a video profile if all of the following conditions are true for the VkImageCreateInfo structure the image was created with:
-
VkImageCreateInfo::
flagsincludedVK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. -
The list of VkVideoFormatPropertiesKHR structures, obtained by calling vkGetPhysicalDeviceVideoFormatPropertiesKHR with VkPhysicalDeviceVideoFormatInfoKHR::
imageUsageequal to the VkImageCreateInfo::usagethe image was created with and the VkPhysicalDeviceVideoFormatInfoKHR::pNextchain including a VkVideoProfileListInfoKHR structure with itspProfilesmember containing a single array element specifying the VkVideoProfileInfoKHR structure chain describing the video profile in question, contains an element for which all of the following conditions are true with respect to the VkImageCreateInfo structure the image was created with:-
VkImageCreateInfo::
formatequals VkVideoFormatPropertiesKHR::format. -
VkImageCreateInfo::
flagsonly containsVK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHRand/or bits also set in VkVideoFormatPropertiesKHR::imageCreateFlags.NoteSpecifying
VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHRwhen creating decode output pictures or encode input pictures is always supported when the videoMaintenance1 feature is enabled, regardless of the supported VkImageCreateFlags reported in VkVideoFormatPropertiesKHR::imageCreateFlags. Accordingly, implementations should not reportVK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHRin VkVideoFormatPropertiesKHR::imageCreateFlagsfor any video format. -
VkImageCreateInfo::
imageTypeequals VkVideoFormatPropertiesKHR::imageType. -
VkImageCreateInfo::
tilingequals VkVideoFormatPropertiesKHR::imageTiling. -
VkImageCreateInfo::
usageonly contains bits also set in VkVideoFormatPropertiesKHR::imageUsageFlags, or VkImageCreateInfo::flagsincludesVK_IMAGE_CREATE_EXTENDED_USAGE_BIT.
-
|
Note
|
While some of these rules allow creating buffer or image resources that may
be compatible with any video profile, applications should still prefer to
include the specific video profiles the buffer or image resource is expected
to be used with (through a VkVideoProfileListInfoKHR structure
included in the |
A VkImageView is compatible with a video profile if the VkImage it was created from is also compatible with that video profile.
A VkQueryPool is compatible with a video profile if it was created
with the VkQueryPoolCreateInfo::pNext chain including a
VkVideoProfileInfoKHR structure chain describing the same video
profile, and VkQueryPoolCreateInfo::queryType having one of the
following values:
-
VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR -
VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR
43.7. Video Session Parameters
Video session parameters objects can store preprocessed codec-specific parameters used with a compatible video session, and enable reducing the number of parameters needed to be provided and processed by the implementation while recording video coding operations into command buffers.
Parameters stored in such objects are immutable to facilitate the concurrent use of the stored parameters in multiple threads. At the same time, new parameters can be added to existing objects using the vkUpdateVideoSessionParametersKHR command.
In order to support concurrent use of the stored immutable parameters while
also allowing the video session parameters object to be extended with new
parameters, each video session parameters object maintains an update
sequence counter that is set to 0 at object creation time and must be
incremented by each subsequent update operation.
Certain video sequences that adhere to particular video compression standards permit updating previously supplied parameters. If a parameter update is necessary, the application has the following options:
-
Cache the set of parameters on the application side and create a new video session parameters object adding all the parameters with appropriate changes, as necessary; or
-
Create a new video session parameters object providing only the updated parameters and the previously used object as the template, which ensures that parameters not specified at creation time will be copied unmodified from the template object.
The actual types of parameters that can be stored and the capacity for individual parameter types, and the methods of initializing, updating, and referring to individual parameters are specific to the video codec operation the video session parameters object was created with.
-
For
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHRthese are defined in the H.264 Decode Parameter Sets section. -
For
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHRthese are defined in the H.265 Decode Parameter Sets section. -
For
VK_VIDEO_CODEC_OPERATION_DECODE_VP9_BIT_KHRthere are no defined parameter sets and therefore do not use video session parameters objects. -
For
VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHRthese are defined in the AV1 Decode Parameter Sets section. -
For
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHRthese are defined in the H.264 Encode Parameter Sets section. -
For
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHRthese are defined in the H.265 Encode Parameter Sets section. -
For
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHRthese are defined in the AV1 Encode Parameter Sets section.
Video session parameters objects created with an encode operation are further specialized based on the video encode quality level the video session parameters are used with, as implementations may apply different sets of parameter overrides depending on the used quality level. This enables implementations to store the potentially optimized set of parameters in these objects, further limiting the necessary processing required while recording video encode operations into command buffers.
Video session parameters are represented by
VkVideoSessionParametersKHR handles:
// Provided by VK_KHR_video_queue
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkVideoSessionParametersKHR)
43.7.1. Creating Video Session Parameters
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 creates the video session parameters object. -
pCreateInfois a pointer to VkVideoSessionParametersCreateInfoKHR structure containing parameters to be used to create the video session parameters object. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pVideoSessionParametersis a pointer to a VkVideoSessionParametersKHR handle in which the resulting video session parameters object is returned.
The resulting video session parameters object is said to be created with the
video codec operation pCreateInfo->videoSession was created with.
Video session parameters objects created with an encode operation are always
created with respect to a video encode quality
level.
By default, the created video session parameters objects are created with
quality level zero, unless otherwise specified by including a
VkVideoEncodeQualityLevelInfoKHR structure in the
pCreateInfo->pNext chain, in which case the video session parameters
object is created with the quality level specified in
VkVideoEncodeQualityLevelInfoKHR::qualityLevel.
If pCreateInfo->videoSessionParametersTemplate is not
VK_NULL_HANDLE, then it will be used as a template for constructing
the new video session parameters object.
This happens by first adding any parameters according to the additional
creation parameters provided in the pCreateInfo->pNext chain, followed
by adding any parameters from the template object that have a key that does
not match the key of any of the already added parameters.
For video session parameters objects created with an encode operation, the
template object specified in
pCreateInfo->videoSessionParametersTemplate must have been created
with the same video encode quality level as the
newly created object.
|
Note
|
This means that codec-specific parameters stored in video session parameters objects can only be reused across different video encode quality levels by re-specifying them, as previously created video session parameters against other quality levels cannot be used as template because the original codec-specific parameters (before the implementation may have applied parameter overrides) may no longer be available in them for the purposes of constructing the derived object. |
Video session parameters objects are only compatible with
quantization maps if they are created with
pCreateInfo->flags including
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR.
Video session parameters objects created with
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR
against a video session object that was created with
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR or
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_EMPHASIS_MAP_BIT_KHR are created
with a specific compatible quantization
map texel size specified in the quantizationMapTexelSize member of
the VkVideoEncodeQuantizationMapSessionParametersCreateInfoKHR
structure included in the pNext chain of pCreateInfo.
|
Note
|
This means that the quantization map texel size that such a video session parameters object is compatible with is fixed for the lifetime of the object. Applications have to create separate video session parameters objects to use different quantization map texel sizes with a single video session object. This is necessary because the used quantization map texel size may affect the parameter overrides the implementation has to perform and thus the final values of the used codec-specific parameters. |
For video session parameters objects created with
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR,
the template object specified in
pCreateInfo->videoSessionParametersTemplate must also have been
created with
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR
and the same compatible quantization
map texel size specified in
VkVideoEncodeQuantizationMapSessionParametersCreateInfoKHR::quantizationMapTexelSize.
|
Note
|
This means that codec-specific parameters stored in video session parameters objects can only be reused with different quantization map texel sizes by re-specifying them, as previously created video session parameters against other quantization map texel sizes cannot be used as template because the original codec-specific parameters (before the implementation may have applied parameter overrides) may no longer be available in them for the purposes of constructing the derived object. |
For video session parameters objects created without
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR,
the template object specified in
pCreateInfo->videoSessionParametersTemplate must also have been
created without
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR.
If pCreateInfo->videoSession was created with the video codec
operation VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR, then the
created video session parameters object will initially contain the following
sets of parameter entries:
-
StdVideoH264SequenceParameterSetstructures representing H.264 SPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH264SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH264SequenceParameterSetentries specified inpParametersAddInfo->pStdSPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH264SequenceParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the sameseq_parameter_set_id.
-
-
StdVideoH264PictureParameterSetstructures representing H.264 PPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH264SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH264PictureParameterSetentries specified inpParametersAddInfo->pStdPPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH264PictureParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the sameseq_parameter_set_idandpic_parameter_set_id.
-
If pCreateInfo->videoSession was created with the video codec
operation VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, then the
created video session parameters object will initially contain the following
sets of parameter entries:
-
StdVideoH265VideoParameterSetstructures representing H.265 VPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH265VideoParameterSetentries specified inpParametersAddInfo->pStdVPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265VideoParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the samevps_video_parameter_set_id.
-
-
StdVideoH265SequenceParameterSetstructures representing H.265 SPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH265SequenceParameterSetentries specified inpParametersAddInfo->pStdSPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265SequenceParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the samesps_video_parameter_set_idandsps_seq_parameter_set_id.
-
-
StdVideoH265PictureParameterSetstructures representing H.265 PPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH265PictureParameterSetentries specified inpParametersAddInfo->pStdPPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265PictureParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the samesps_video_parameter_set_id,pps_seq_parameter_set_id, andpps_pic_parameter_set_id.
-
If pCreateInfo->videoSession was created with the video codec
operation VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHR, then the
created video session parameters object will contain a single
AV1 sequence header represented by a
StdVideoAV1SequenceHeader structure specified through the
pStdSequenceHeader member of the
VkVideoDecodeAV1SessionParametersCreateInfoKHR structure provided in
the pCreateInfo->pNext chain.
As such video session parameters objects can only contain a single
AV1 sequence header, it is not possible to
use a previously created object as a template or subsequently update the
created video session parameters object.
If pCreateInfo->videoSession was created with the video codec
operation VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the
created video session parameters object will initially contain the following
sets of parameter entries:
-
StdVideoH264SequenceParameterSetstructures representing H.264 SPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH264SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH264SequenceParameterSetentries specified inpParametersAddInfo->pStdSPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH264SequenceParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the sameseq_parameter_set_id.
-
-
StdVideoH264PictureParameterSetstructures representing H.264 PPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH264SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH264PictureParameterSetentries specified inpParametersAddInfo->pStdPPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH264PictureParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the sameseq_parameter_set_idandpic_parameter_set_id.
-
If pCreateInfo->videoSession was created with the video codec
operation VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the
created video session parameters object will initially contain the following
sets of parameter entries:
-
StdVideoH265VideoParameterSetstructures representing H.265 VPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH265VideoParameterSetentries specified inpParametersAddInfo->pStdVPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265VideoParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the samevps_video_parameter_set_id.
-
-
StdVideoH265SequenceParameterSetstructures representing H.265 SPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH265SequenceParameterSetentries specified inpParametersAddInfo->pStdSPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265SequenceParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the samesps_video_parameter_set_idandsps_seq_parameter_set_id.
-
-
StdVideoH265PictureParameterSetstructures representing H.265 PPS entries, as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure provided in thepCreateInfo->pNextchain is notNULL, then the set ofStdVideoH265PictureParameterSetentries specified inpParametersAddInfo->pStdPPSsare added first; -
If
pCreateInfo->videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265PictureParameterSetentry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the samesps_video_parameter_set_id,pps_seq_parameter_set_id, andpps_pic_parameter_set_id.
-
If pCreateInfo->videoSession was created with the video codec
operation VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR, then the
created video session parameters object will contain a single
AV1 sequence header specified through the
members of the VkVideoEncodeAV1SessionParametersCreateInfoKHR
structure provided in the pCreateInfo->pNext chain.
As such video session parameters objects can only contain a single
AV1 sequence header, it is not possible to
use a previously created object as a template or subsequently update the
created video session parameters object.
In case of video session parameters objects created with a video encode
operation, implementations may return the
VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error if any of the
specified Video Std parameters do not adhere to the syntactic or semantic
requirements of the used video compression standard, or if values derived
from parameters according to the rules defined by the used video compression
standard do not adhere to the capabilities of the video compression standard
or the implementation.
|
Note
|
Applications should not rely on the
|
The VkVideoSessionParametersCreateInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoSessionParametersCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoSessionParametersCreateFlagsKHR flags;
VkVideoSessionParametersKHR videoSessionParametersTemplate;
VkVideoSessionKHR videoSession;
} VkVideoSessionParametersCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoSessionParametersCreateFlagBitsKHR specifying create flags. -
videoSessionParametersTemplateisVK_NULL_HANDLEor a valid handle to a VkVideoSessionParametersKHR object used as a template for constructing the new video session parameters object. -
videoSessionis the video session object against which the video session parameters object is going to be created.
Limiting values are defined below that are referenced by the relevant valid usage statements of this structure.
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR, then letStdVideoH264SequenceParameterSet spsAddList[]be the list of H.264 SPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH264SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH264SequenceParameterSetentries specified inpParametersAddInfo->pStdSPSsare added tospsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH264SequenceParameterSetentry stored in it withseq_parameter_set_idnot matching any of the entries already inspsAddListis added tospsAddList.
-
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR, then letStdVideoH264PictureParameterSet ppsAddList[]be the list of H.264 PPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH264SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH264PictureParameterSetentries specified inpParametersAddInfo->pStdPPSsare added toppsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH264PictureParameterSetentry stored in it withseq_parameter_set_idorpic_parameter_set_idnot matching any of the entries already inppsAddListis added toppsAddList.
-
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, then letStdVideoH265VideoParameterSet vpsAddList[]be the list of H.265 VPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH265VideoParameterSetentries specified inpParametersAddInfo->pStdVPSsare added tovpsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265VideoParameterSetentry stored in it withvps_video_parameter_set_idnot matching any of the entries already invpsAddListis added tovpsAddList.
-
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, then letStdVideoH265SequenceParameterSet spsAddList[]be the list of H.265 SPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH265SequenceParameterSetentries specified inpParametersAddInfo->pStdSPSsare added tospsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265SequenceParameterSetentry stored in it withsps_video_parameter_set_idorsps_seq_parameter_set_idnot matching any of the entries already inspsAddListis added tospsAddList.
-
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, then letStdVideoH265PictureParameterSet ppsAddList[]be the list of H.265 PPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH265PictureParameterSetentries specified inpParametersAddInfo->pStdPPSsare added toppsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265PictureParameterSetentry stored in it withsps_video_parameter_set_id,pps_seq_parameter_set_id, orpps_pic_parameter_set_idnot matching any of the entries already inppsAddListis added toppsAddList.
-
-
If
videoSessionwas created with an encode operation, then letuint32_t qualityLevelbe the video encode quality level of the created video session parameters object, defined as follows:-
If the
pNextchain of this structure includes a VkVideoEncodeQualityLevelInfoKHR structure, thenqualityLevelis equal to VkVideoEncodeQualityLevelInfoKHR::qualityLevel. -
Otherwise
qualityLevelis0
-
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then letStdVideoH264SequenceParameterSet spsAddList[]be the list of H.264 SPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH264SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH264SequenceParameterSetentries specified inpParametersAddInfo->pStdSPSsare added tospsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH264SequenceParameterSetentry stored in it withseq_parameter_set_idnot matching any of the entries already inspsAddListis added tospsAddList.
-
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then letStdVideoH264PictureParameterSet ppsAddList[]be the list of H.264 PPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH264SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH264PictureParameterSetentries specified inpParametersAddInfo->pStdPPSsare added toppsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH264PictureParameterSetentry stored in it withseq_parameter_set_idorpic_parameter_set_idnot matching any of the entries already inppsAddListis added toppsAddList.
-
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then letStdVideoH265VideoParameterSet vpsAddList[]be the list of H.265 VPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH265VideoParameterSetentries specified inpParametersAddInfo->pStdVPSsare added tovpsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265VideoParameterSetentry stored in it withvps_video_parameter_set_idnot matching any of the entries already invpsAddListis added tovpsAddList.
-
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then letStdVideoH265SequenceParameterSet spsAddList[]be the list of H.265 SPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH265SequenceParameterSetentries specified inpParametersAddInfo->pStdSPSsare added tospsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265SequenceParameterSetentry stored in it withsps_video_parameter_set_idorsps_seq_parameter_set_idnot matching any of the entries already inspsAddListis added tospsAddList.
-
-
If
videoSessionwas created with the codec operationVK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then letStdVideoH265PictureParameterSet ppsAddList[]be the list of H.265 PPS entries to add to the created video session parameters object, defined as follows:-
If the
pParametersAddInfomember of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure provided in thepNextchain is notNULL, then the set ofStdVideoH265PictureParameterSetentries specified inpParametersAddInfo->pStdPPSsare added toppsAddList; -
If
videoSessionParametersTemplateis notVK_NULL_HANDLE, then eachStdVideoH265PictureParameterSetentry stored in it withsps_video_parameter_set_id,pps_seq_parameter_set_id, orpps_pic_parameter_set_idnot matching any of the entries already inppsAddListis added toppsAddList.
-
Bits which can be set in
VkVideoSessionParametersCreateInfoKHR::flags are:
// Provided by VK_KHR_video_encode_quantization_map
typedef enum VkVideoSessionParametersCreateFlagBitsKHR {
// Provided by VK_KHR_video_encode_quantization_map
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR = 0x00000001,
} VkVideoSessionParametersCreateFlagBitsKHR;
-
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHRspecifies that the created video session parameters object can be used with quantization maps.
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoSessionParametersCreateFlagsKHR;
VkVideoSessionParametersCreateFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoSessionParametersCreateFlagBitsKHR.
The VkVideoEncodeQuantizationMapSessionParametersCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_video_encode_quantization_map
typedef struct VkVideoEncodeQuantizationMapSessionParametersCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkExtent2D quantizationMapTexelSize;
} VkVideoEncodeQuantizationMapSessionParametersCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
quantizationMapTexelSizespecifies the quantization map texel size a video session parameters object created withVK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHRis compatible with.
43.7.2. 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 logical device that destroys the video session parameters object. -
videoSessionParametersis the video session parameters object to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
43.7.3. Updating Video Session Parameters
To update video session parameters object with new parameters, call:
// Provided by VK_KHR_video_queue
VkResult vkUpdateVideoSessionParametersKHR(
VkDevice device,
VkVideoSessionParametersKHR videoSessionParameters,
const VkVideoSessionParametersUpdateInfoKHR* pUpdateInfo);
-
deviceis the logical device that updates the video session parameters. -
videoSessionParametersis the video session parameters object to update. -
pUpdateInfois a pointer to a VkVideoSessionParametersUpdateInfoKHR structure specifying the parameter update information.
After a successful call to this command, the
update sequence counter of
videoSessionParameters is changed to the value specified in
pUpdateInfo->updateSequenceCount.
|
Note
|
As each update issued to a video session parameters object needs to specify the next available update sequence count value, concurrent updates of the same video session parameters object are inherently disallowed. However, recording video coding operations to command buffers referring to parameters previously added to the video session parameters object is allowed, even if there is a concurrent update in progress adding some new entries to the object. |
If videoSessionParameters was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR and the
pUpdateInfo->pNext chain includes a
VkVideoDecodeH264SessionParametersAddInfoKHR structure, then this
command adds the following parameter entries to
videoSessionParameters:
-
The H.264 SPS entries specified in VkVideoDecodeH264SessionParametersAddInfoKHR::
pStdSPSs. -
The H.264 PPS entries specified in VkVideoDecodeH264SessionParametersAddInfoKHR::
pStdPPSs.
If videoSessionParameters was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR and the
pUpdateInfo->pNext chain includes a
VkVideoDecodeH265SessionParametersAddInfoKHR structure, then this
command adds the following parameter entries to
videoSessionParameters:
-
The H.265 VPS entries specified in VkVideoDecodeH265SessionParametersAddInfoKHR::
pStdVPSs. -
The H.265 SPS entries specified in VkVideoDecodeH265SessionParametersAddInfoKHR::
pStdSPSs. -
The H.265 PPS entries specified in VkVideoDecodeH265SessionParametersAddInfoKHR::
pStdPPSs.
If videoSessionParameters was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and the
pUpdateInfo->pNext chain includes a
VkVideoEncodeH264SessionParametersAddInfoKHR structure, then this
command adds the following parameter entries to
videoSessionParameters:
-
The H.264 SPS entries specified in VkVideoEncodeH264SessionParametersAddInfoKHR::
pStdSPSs. -
The H.264 PPS entries specified in VkVideoEncodeH264SessionParametersAddInfoKHR::
pStdPPSs.
If videoSessionParameters was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the
pUpdateInfo->pNext chain includes a
VkVideoEncodeH265SessionParametersAddInfoKHR structure, then this
command adds the following parameter entries to
videoSessionParameters:
-
The H.265 VPS entries specified in VkVideoEncodeH265SessionParametersAddInfoKHR::
pStdVPSs. -
The H.265 SPS entries specified in VkVideoEncodeH265SessionParametersAddInfoKHR::
pStdSPSs. -
The H.265 PPS entries specified in VkVideoEncodeH265SessionParametersAddInfoKHR::
pStdPPSs.
In case of video session parameters objects created with a video encode
operation, implementations may return the
VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error if any of the
specified Video Std parameters do not adhere to the syntactic or semantic
requirements of the used video compression standard, or if values derived
from parameters according to the rules defined by the used video compression
standard do not adhere to the capabilities of the video compression standard
or the implementation.
|
Note
|
Applications should not rely on the
|
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
updateSequenceCountis the new update sequence count to set for the video session parameters object.
43.8. Video Coding Scope
Applications can record video coding commands for a video session only within a video coding scope.
To begin a video coding scope, call:
// Provided by VK_KHR_video_queue
void vkCmdBeginVideoCodingKHR(
VkCommandBuffer commandBuffer,
const VkVideoBeginCodingInfoKHR* pBeginInfo);
-
commandBufferis the command buffer in which to record the command. -
pBeginInfois a pointer to a VkVideoBeginCodingInfoKHR structure specifying the parameters of the video coding scope, including the video session and video session parameters object to use.
After beginning a video coding scope, the video session object specified in
pBeginInfo->videoSession is bound to the command buffer, and the
command buffer is ready to record video coding operations.
Similarly, if pBeginInfo->videoSessionParameters is not
VK_NULL_HANDLE, it is also bound to the command buffer, and video
coding operations can refer to the codec-specific parameters stored in it.
This command also establishes the set of bound reference picture resources that can be used as reconstructed pictures or reference pictures within the video coding scope. Each element of this set consists of a video picture resource and the DPB slot index associated with it, if there is one.
The set of bound reference picture resources is immutable within a video coding scope, however, the DPB slot index associated with any of the bound reference picture resources can change during the video coding scope in response to video coding operations.
The VkVideoReferenceSlotInfoKHR structures provided as the elements of
pBeginInfo->pReferenceSlots are interpreted by this command as
follows:
-
If
slotIndexis non-negative andpPictureResourceis notNULL, then the video picture resource defined by the VkVideoPictureResourceInfoKHR structure pointed to bypPictureResourceis added to the set of bound reference picture resources and is associated with the DPB slot index specified inslotIndex. -
If
slotIndexis non-negative andpPictureResourceisNULL, then the DPB slot with indexslotIndexis deactivated by this command. -
If
slotIndexis negative andpPictureResourceis notNULL, then the video picture resource defined by the VkVideoPictureResourceInfoKHR structure pointed to bypPictureResourceis added to the set of bound reference picture resources without an associated DPB slot. Such a picture resource can be subsequently used as a reconstructed picture to associate it with a DPB slot. -
If
slotIndexis negative andpPictureResourceisNULL, then the element is ignored.
|
Note
|
It is possible for multiple bound reference picture resources to be associated with the same DPB slot index, or for a single bound reference picture to refer to multiple separate reference pictures. For example, in case of an H.264 decode profile with interlaced frame support a single DPB slot can refer to two separate pictures for the top and bottom fields. Depending on the picture layout used by the H.264 decode profile, the following special cases may arise:
|
All non-negative slotIndex values specified in the elements of
pBeginInfo->pReferenceSlots must identify DPB slots of the video
session that are in the active state at the time this
command is executed on the device.
|
Note
|
The application does not have to specify an entry in
|
In case of a video encode session, the application is also responsible for
providing information about the current rate
control state configured for the video session by including an instance of
the VkVideoEncodeRateControlInfoKHR structure in the pNext chain
of pBeginInfo.
If no VkVideoEncodeRateControlInfoKHR is included, then the presence
of an empty VkVideoEncodeRateControlInfoKHR structure is implied which
indicates that the current rate control mode
is VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR.
The specified state must match the
effective rate control state configured for the video session at the time
the recorded command is executed on the device.
|
Note
|
Including an instance of the VkVideoEncodeRateControlInfoKHR structure
in the |
The VkVideoBeginCodingInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoBeginCodingInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoBeginCodingFlagsKHR flags;
VkVideoSessionKHR videoSession;
VkVideoSessionParametersKHR videoSessionParameters;
uint32_t referenceSlotCount;
const VkVideoReferenceSlotInfoKHR* pReferenceSlots;
} VkVideoBeginCodingInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
videoSessionis the video session object to be bound for the processing of the video commands. -
videoSessionParametersisVK_NULL_HANDLEor a handle of a VkVideoSessionParametersKHR object to be used for the processing of the video commands. IfVK_NULL_HANDLE, then no video session parameters object is bound for the duration of the video coding scope. -
referenceSlotCountis the number of elements in thepReferenceSlotsarray. -
pReferenceSlotsis a pointer to an array of VkVideoReferenceSlotInfoKHR structures specifying the information used to determine the set of bound reference picture resources for the video coding scope and their initial association with DPB slot indices.
Limiting values are defined below that are referenced by the relevant valid usage statements of this structure.
-
Let
VkOffset2D codedOffsetGranularitybe the minimum alignment requirement for the coded offset of video picture resources. Unless otherwise defined, the value of thexandymembers ofcodedOffsetGranularityare0.-
If
videoSessionwas created with an H.264 decode profile with a VkVideoDecodeH264ProfileInfoKHR::pictureLayoutofVK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHR, thencodedOffsetGranularityis equal to VkVideoDecodeH264CapabilitiesKHR::fieldOffsetGranularity, as returned by vkGetPhysicalDeviceVideoCapabilitiesKHR for that video profile.
-
// 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 VkVideoReferenceSlotInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoReferenceSlotInfoKHR {
VkStructureType sType;
const void* pNext;
int32_t slotIndex;
const VkVideoPictureResourceInfoKHR* pPictureResource;
} VkVideoReferenceSlotInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
slotIndexis the index of the DPB slot or a negative integer value. -
pPictureResourceisNULLor a pointer to a VkVideoPictureResourceInfoKHR structure describing the video picture resource associated with the DPB slot index specified byslotIndex.
To end a video coding scope, call:
// Provided by VK_KHR_video_queue
void vkCmdEndVideoCodingKHR(
VkCommandBuffer commandBuffer,
const VkVideoEndCodingInfoKHR* pEndCodingInfo);
-
commandBufferis the command buffer in which to record the command. -
pEndCodingInfois a pointer to a VkVideoEndCodingInfoKHR structure specifying the parameters for ending the video coding scope.
After ending a video coding scope, the video session object, the optional video session parameters object, and all reference picture resources previously bound by the corresponding vkCmdBeginVideoCodingKHR command are unbound.
The VkVideoEndCodingInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoEndCodingInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEndCodingFlagsKHR flags;
} VkVideoEndCodingInfoKHR;
-
sTypeis a VkStructureType value identifying 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.
43.9. Video Coding Control
To apply dynamic controls to the bound video session object, call:
// Provided by VK_KHR_video_queue
void vkCmdControlVideoCodingKHR(
VkCommandBuffer commandBuffer,
const VkVideoCodingControlInfoKHR* pCodingControlInfo);
-
commandBufferis the command buffer in which to record the command. -
pCodingControlInfois a pointer to a VkVideoCodingControlInfoKHR structure specifying the control parameters.
The control parameters provided in this call are applied to the video session at the time the command executes on the device and are in effect until a subsequent call to this command with the same video session bound changes the corresponding control parameters.
A newly created video session must be reset before performing video coding
operations using it by including VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR
in pCodingControlInfo->flags.
The reset operation also returns all DPB slots of the video session to the
inactive state.
Correspondingly, any DPB slot index associated with the
bound reference picture resources is
removed.
For encode sessions, the reset operation returns rate control configuration to implementation default settings and sets the video encode quality level to zero.
After video coding operations are performed using a video session, the reset operation can be used to return the video session to the same initial state as after the reset of a newly created video session. This can be used, for example, when different video sequences are needed to be processed with the same video session object.
If pCodingControlInfo->flags includes
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, then the command
replaces the rate control configuration maintained
by the video session with the configuration specified in the
VkVideoEncodeRateControlInfoKHR structure included in the
pCodingControlInfo->pNext chain.
If pCodingControlInfo->flags includes
VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR, then the command
changes the current video encode quality level to
the value specified in the qualityLevel member of the
VkVideoEncodeQualityLevelInfoKHR structure included in the
pCodingControlInfo->pNext chain.
The VkVideoCodingControlInfoKHR structure is defined as:
// Provided by VK_KHR_video_queue
typedef struct VkVideoCodingControlInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoCodingControlFlagsKHR flags;
} VkVideoCodingControlInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoCodingControlFlagsKHR specifying control flags.
Bits which can be set in VkVideoCodingControlInfoKHR::flags,
specifying the video coding control parameters to be modified, are:
// Provided by VK_KHR_video_queue
typedef enum VkVideoCodingControlFlagBitsKHR {
VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR = 0x00000001,
// Provided by VK_KHR_video_encode_queue
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR = 0x00000002,
// Provided by VK_KHR_video_encode_queue
VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR = 0x00000004,
} VkVideoCodingControlFlagBitsKHR;
-
VK_VIDEO_CODING_CONTROL_RESET_BIT_KHRspecifies a request for the bound video session to be reset before other coding control parameters are applied. -
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHRspecifies that the coding control parameters include video encode rate control parameters (see VkVideoEncodeRateControlInfoKHR). -
VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHRspecifies that the coding control parameters include video encode quality level parameters (see VkVideoEncodeQualityLevelInfoKHR).
// Provided by VK_KHR_video_queue
typedef VkFlags VkVideoCodingControlFlagsKHR;
VkVideoCodingControlFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoCodingControlFlagBitsKHR.
43.10. Inline Queries
If a video session was created with
VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, beginning queries
using commands such as vkCmdBeginQuery within a video coding scope is
not allowed.
Instead, queries are executed inline by including an instance of the
VkVideoInlineQueryInfoKHR structure in the pNext chain of the
parameters of one of the video coding commands, with its queryPool
member set to a valid VkQueryPool handle.
The VkVideoInlineQueryInfoKHR structure is defined as:
// Provided by VK_KHR_video_maintenance1
typedef struct VkVideoInlineQueryInfoKHR {
VkStructureType sType;
const void* pNext;
VkQueryPool queryPool;
uint32_t firstQuery;
uint32_t queryCount;
} VkVideoInlineQueryInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queryPoolisVK_NULL_HANDLEor a valid handle to a VkQueryPool object that will manage the results of the queries. -
firstQueryis the query index within the query pool that will contain the query results for the first video coding operation. The query results of subsequent video coding operations will be contained by subsequent query indices. -
queryCountis the number of queries to execute.NoteIn practice, if
queryPoolis notVK_NULL_HANDLE, thenqueryCountwill always have to match the number of video coding operations issued by the video coding command this structure is specified to, meaning that using inline queries in a video coding command will always execute a query for each issued video coding operation.
This structure can be included in the pNext chain of the input
parameter structure of video coding commands.
-
In the
pNextchain of thepDecodeInfoparameter of the vkCmdDecodeVideoKHR command to execute a query for each video decode operation issued by the command. -
In the
pNextchain of thepEncodeInfoparameter of the vkCmdEncodeVideoKHR command to execute a query for each video encode operation issued by the command.
43.11. Video Decode Operations
Video decode operations consume compressed video data from a video bitstream buffer and zero or more reference pictures, and produce a decode output picture and an optional reconstructed picture.
|
Note
|
Such decode output pictures can be shared with the Decoded Picture Buffer, and can also be used as the input of video encode operations, with graphics or compute operations, or with Window System Integration APIs, depending on the capabilities of the implementation. |
Video decode operations may access the following resources in the
VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR stage:
-
The source video bitstream buffer range and the image subregions corresponding to the list of active reference pictures with access
VK_ACCESS_2_VIDEO_DECODE_READ_BIT_KHR. -
The image subregions corresponding to the target decode output picture and reconstructed picture with access
VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR.
The image subresource of each video picture resource accessed by the video decode operation is specified using a corresponding VkVideoPictureResourceInfoKHR structure. Each such image subresource must be in the appropriate image layout as follows:
-
If the image subresource is used in the video decode operation only as decode output picture, then it must be in the
VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHRlayout , unless theunifiedImageLayoutsVideofeature is enabled, in which case it may be in theVK_IMAGE_LAYOUT_GENERALlayout . -
If the image subresource is used in the video decode operation both as decode output picture and reconstructed picture, then it must be in the
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHRlayout , unless theunifiedImageLayoutsVideofeature is enabled, in which case it may be in theVK_IMAGE_LAYOUT_GENERALlayout . -
If the image subresource is used in the video decode operation only as reconstructed picture, then it must be in the
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHRlayout , unless theunifiedImageLayoutsVideofeature is enabled, in which case it may be in theVK_IMAGE_LAYOUT_GENERALlayout . -
If the image subresource is used in the video decode operation as a reference picture, then it must be in the
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHRlayout , unless theunifiedImageLayoutsVideofeature is enabled, in which case it may be in theVK_IMAGE_LAYOUT_GENERALlayout .
A video decode operation may complete unsuccessfully. In this case the decode output picture will have undefined contents. Similarly, if reference picture setup is requested, the reconstructed picture will also have undefined contents, and the activated DPB slot will have an invalid picture reference.
43.11.1. Codec-Specific Semantics
The following aspects of video decode operations are codec-specific:
-
The interpretation of the contents of the source video bitstream buffer range.
-
The construction and interpretation of the list of active reference pictures and the interpretation of the picture data referred to by the corresponding image subregions.
-
The construction and interpretation of information related to the decode output picture and the generation of picture data to the corresponding image subregion.
-
The decision on reference picture setup.
-
The construction and interpretation of information related to the optional reconstructed picture and the generation of picture data to the corresponding image subregion.
These codec-specific behaviors are defined for each video codec operation separately.
-
If the used video codec operation is
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR, then the codec-specific aspects of the video decoding process are performed as defined in the H.264 Decode Operations section. -
If the used video codec operation is
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, then the codec-specific aspects of the video decoding process are performed as defined in the H.265 Decode Operations section. -
If the used video codec operation is
VK_VIDEO_CODEC_OPERATION_DECODE_VP9_BIT_KHR, then the codec-specific aspects of the video decoding process are performed as defined in the VP9 Decode Operations section. -
If the used video codec operation is
VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHR, then the codec-specific aspects of the video decoding process are performed as defined in the AV1 Decode Operations section.
43.11.2. Video Decode Operation Steps
Each video decode operation performs the following steps in the
VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR stage:
-
Reads the encoded video data from the source video bitstream buffer range.
-
Performs picture reconstruction of the encoded video data according to the codec-specific semantics, applying any prediction data read from the active reference pictures in the process;
-
Writes the decoded picture data to the decode output picture, and optionally to the reconstructed picture, if one is specified and is different from the decode output picture, according to the codec-specific semantics;
-
If reference picture setup is requested, the DPB slot index specified in the reconstructed picture information is activated with the reconstructed picture.
When reconstructed picture information is provided, the specified DPB slot index is associated with the corresponding bound reference picture resource, indifferent of whether reference picture setup is requested.
43.11.3. Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR with
pVideoProfile->videoCodecOperation specifying a decode operation, 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoDecodeCapabilityFlagBitsKHR describing the supported video decoding capabilities.
Bits which may be set in VkVideoDecodeCapabilitiesKHR::flags,
indicating the decoding capabilities supported, are:
// Provided by VK_KHR_video_decode_queue
typedef enum VkVideoDecodeCapabilityFlagBitsKHR {
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_KHRspecifies support for using the same video picture resource as the reconstructed picture and decode output picture in a video decode operation. -
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHRspecifies support for using distinct video picture resources as the reconstructed picture and decode output picture in a video decode operation.NoteSome video profiles allow using distinct video picture resources as the reconstructed picture and decode output picture in specific video decode operations even when the video decode profile does not support
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR. Even if the implementation only reports coincide, the decode output picture for film grain enabled frames must be a different video picture resource from the reconstructed picture because film grain is applied outside of the coding loop.
Implementations are only required to support one of
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR and
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR.
Accordingly, applications should handle both cases to maximize portability.
|
Note
|
If both |
// Provided by VK_KHR_video_decode_queue
typedef VkFlags VkVideoDecodeCapabilityFlagsKHR;
VkVideoDecodeCapabilityFlagsKHR is a bitmask type for setting a mask
of zero or more VkVideoDecodeCapabilityFlagBitsKHR.
43.11.4. Video Decode Commands
To launch video decode operations, call:
// Provided by VK_KHR_video_decode_queue
void vkCmdDecodeVideoKHR(
VkCommandBuffer commandBuffer,
const VkVideoDecodeInfoKHR* pDecodeInfo);
-
commandBufferis the command buffer in which to record the command. -
pDecodeInfois a pointer to a VkVideoDecodeInfoKHR structure specifying the parameters of the video decode operations.
Each call issues one or more video decode operations.
The implicit parameter opCount corresponds to the number of video
decode operations issued by the command.
After calling this command, the
active query index of each
active query is incremented by opCount.
Currently each call to this command results in the issue of a single video decode operation.
If the bound video session was created with
VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR and the pNext
chain of pDecodeInfo includes a VkVideoInlineQueryInfoKHR
structure with its queryPool member specifying a valid
VkQueryPool handle, then this command will execute a query for each
video decode operation issued by it.
- Active Reference Picture Information
-
The list of active reference pictures used by a video decode operation is a list of image subregions used as the source of reference picture data and related parameters, and is derived from the VkVideoReferenceSlotInfoKHR structures provided as the elements of the
pDecodeInfo->pReferenceSlotsarray. For each element ofpDecodeInfo->pReferenceSlots, one or more elements are added to the active reference picture list, as defined by the codec-specific semantics. Each element of this list contains the following information:-
The image subregion within the image subresource referred to by the video picture resource used as the reference picture.
-
The DPB slot index the reference picture is associated with.
-
The codec-specific reference information related to the reference picture.
-
- Reconstructed Picture Information
-
Information related to the optional reconstructed picture used by a video decode operation is derived from the VkVideoReferenceSlotInfoKHR structure pointed to by
pDecodeInfo->pSetupReferenceSlot, if notNULL, as defined by the codec-specific semantics, and consists of the following:-
The image subregion within the image subresource referred to by the video picture resource used as the reconstructed picture.
-
The DPB slot index to use for picture reconstruction.
-
The codec-specific reference information related to the reconstructed picture.
-
Specifying a valid VkVideoReferenceSlotInfoKHR structure in
pDecodeInfo->pSetupReferenceSlot is always required, unless the video
session was created with
VkVideoSessionCreateInfoKHR::maxDpbSlots equal to zero.
However, the DPB slot identified by
pDecodeInfo->pSetupReferenceSlot->slotIndex is only
activated with the reconstructed
picture specified in
pDecodeInfo->pSetupReferenceSlot->pPictureResource if reference
picture setup is requested according to the
codec-specific semantics.
If reconstructed picture information is specified, and
pDecodeInfo->pSetupReferenceSlot->pPictureResource refers to a
video picture resource different than that of
the decode output picture, but reference picture
setup is not requested, the contents of the video
picture resource corresponding to the reconstructed picture will be
undefined after the video decode operation.
|
Note
|
Some implementations may always output the reconstructed picture or use it as temporary storage during the video decode operation even when the reconstructed picture is not marked for future reference. |
- Decode Output Picture Information
-
Information related to the decode output picture used by a video decode operation is derived from
pDecodeInfo->dstPictureResourceand any codec-specific parameters provided in thepDecodeInfo->pNextchain, as defined by the codec-specific semantics, and consists of the following:-
The image subregion within the image subresource referred to by the video picture resource used as the decode output picture.
-
The codec-specific picture information related to the decode output picture.
-
Several limiting values are defined below that are referenced by the relevant valid usage statements of this command.
-
Let
uint32_t activeReferencePictureCountbe the size of the list of active reference pictures used by the video decode operation. Unless otherwise defined,activeReferencePictureCountis set to the value ofpDecodeInfo->referenceSlotCount.-
If the bound video session was created with an H.264 decode profile, then let
activeReferencePictureCountbe the value ofpDecodeInfo->referenceSlotCountplus the number of elements of thepDecodeInfo->pReferenceSlotsarray that have a VkVideoDecodeH264DpbSlotInfoKHR structure included in theirpNextchain with bothpStdReferenceInfo->flags.top_field_flagandpStdReferenceInfo->flags.bottom_field_flagset.NoteThis means that the elements of
pDecodeInfo->pReferenceSlotsthat include both a top and bottom field reference are counted as two separate active reference pictures, as described in the active reference picture list construction rules for H.264 decode operations.
-
-
Let
VkOffset2D codedOffsetGranularitybe the minimum alignment requirement for the coded offset of video picture resources. Unless otherwise defined, the value of thexandymembers ofcodedOffsetGranularityare0.-
If the bound video session was created with an H.264 decode profile with a VkVideoDecodeH264ProfileInfoKHR::
pictureLayoutofVK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHR, thencodedOffsetGranularityis equal to VkVideoDecodeH264CapabilitiesKHR::fieldOffsetGranularity, as returned by vkGetPhysicalDeviceVideoCapabilitiesKHR for that video profile.
-
-
Let
uint32_t dpbFrameUseCount[]be an array of sizemaxDpbSlots, wheremaxDpbSlotsis the VkVideoSessionCreateInfoKHR::maxDpbSlotsthe bound video session was created with, with each element indicating the number of times a frame associated with the corresponding DPB slot index is referred to by the video coding operation. Let the initial value of each element of the array be0.-
If
pDecodeInfo->pSetupReferenceSlotis notNULL, thendpbFrameUseCount[i]is incremented by one, whereiequalspDecodeInfo->pSetupReferenceSlot->slotIndex. If the bound video session object was created with an H.264 decode profile, thendpbFrameUseCount[i]is decremented by one if eitherpStdReferenceInfo->flags.top_field_flagorpStdReferenceInfo->flags.bottom_field_flagis set in the VkVideoDecodeH264DpbSlotInfoKHR structure in thepDecodeInfo->pSetupReferenceSlot->pNextchain. -
For each element of
pDecodeInfo->pReferenceSlots,dpbFrameUseCount[i]is incremented by one, whereiequals theslotIndexmember of the corresponding element. If the bound video session object was created with an H.264 decode profile, thendpbFrameUseCount[i]is decremented by one if eitherpStdReferenceInfo->flags.top_field_flagorpStdReferenceInfo->flags.bottom_field_flagis set in the VkVideoDecodeH264DpbSlotInfoKHR structure in thepNextchain of the corresponding element ofpDecodeInfo->pReferenceSlots.
-
-
Let
uint32_t dpbTopFieldUseCount[]anduint32_t dpbBottomFieldUseCount[]be arrays of sizemaxDpbSlots, wheremaxDpbSlotsis the VkVideoSessionCreateInfoKHR::maxDpbSlotsthe bound video session was created with, with each element indicating the number of times the top field or the bottom field, respectively, associated with the corresponding DPB slot index is referred to by the video coding operation. Let the initial value of each element of the arrays be0.-
If the bound video session object was created with an H.264 decode profile and
pDecodeInfo->pSetupReferenceSlotis notNULL, then perform the following:-
If
pStdReferenceInfo->flags.top_field_flagis set in the VkVideoDecodeH264DpbSlotInfoKHR structure in thepDecodeInfo->pSetupReferenceSlot->pNextchain, thendpbTopFieldUseCount[i]is incremented by one, whereiequalspDecodeInfo->pSetupReferenceSlot->slotIndex. -
If
pStdReferenceInfo->flags.bottom_field_flagis set in the VkVideoDecodeH264DpbSlotInfoKHR structure in thepDecodeInfo->pSetupReferenceSlot->pNextchain, thendpbBottomFieldUseCount[i]is incremented by one, whereiequalspDecodeInfo->pSetupReferenceSlot->slotIndex.
-
-
If the bound video session object was created with an H.264 decode profile, then perform the following for each element of
pDecodeInfo->pReferenceSlots:-
If
pStdReferenceInfo->flags.top_field_flagis set in the VkVideoDecodeH264DpbSlotInfoKHR structure in thepNextchain of the element, thendpbTopFieldUseCount[i]is incremented by one, whereiequals theslotIndexmember of the element. -
If
pStdReferenceInfo->flags.bottom_field_flagis set in the VkVideoDecodeH264DpbSlotInfoKHR structure in thepNextchain of the element, thendpbBottomFieldUseCount[i]is incremented by one, whereiequals theslotIndexmember of the element.
-
-
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;
VkVideoPictureResourceInfoKHR dstPictureResource;
const VkVideoReferenceSlotInfoKHR* pSetupReferenceSlot;
uint32_t referenceSlotCount;
const VkVideoReferenceSlotInfoKHR* pReferenceSlots;
} VkVideoDecodeInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
srcBufferis the source video bitstream buffer to read the encoded bitstream from. -
srcBufferOffsetis the starting offset in bytes from the start ofsrcBufferto read the encoded bitstream from. -
srcBufferRangeis the size in bytes of the encoded bitstream to decode fromsrcBuffer, starting fromsrcBufferOffset. -
dstPictureResourceis the video picture resource to use as the decode output picture. -
pSetupReferenceSlotisNULLor a pointer to a VkVideoReferenceSlotInfoKHR structure specifying the reconstructed picture information. -
referenceSlotCountis the number of elements in thepReferenceSlotsarray. -
pReferenceSlotsisNULLor a pointer to an array of VkVideoReferenceSlotInfoKHR structures describing the DPB slots and corresponding reference picture resources to use in this video decode operation (the set of active reference pictures).
// Provided by VK_KHR_video_decode_queue
typedef VkFlags VkVideoDecodeFlagsKHR;
VkVideoDecodeFlagsKHR is a bitmask type for setting a mask, but is
currently reserved for future use.
43.12. H.264 Decode Operations
Video decode operations using an H.264 decode profile can be used to decode elementary video stream sequences compliant to the ITU-T H.264 Specification.
|
Note
|
Refer to the Preamble for information on how the Khronos Intellectual Property Rights Policy relates to normative references to external materials not created by Khronos. |
This process is performed according to the video decode operation steps with the codec-specific semantics defined in section 8 of the ITU-T H.264 Specification as follows:
-
Syntax elements, derived values, and other parameters are applied from the following structures:
-
The
StdVideoH264SequenceParameterSetstructure corresponding to the active SPS specifying the H.264 sequence parameter set. -
The
StdVideoH264PictureParameterSetstructure corresponding to the active PPS specifying the H.264 picture parameter set. -
The
StdVideoDecodeH264PictureInfostructure specifying the H.264 picture information. -
The
StdVideoDecodeH264ReferenceInfostructures specifying the H.264 reference information corresponding to the optional reconstructed picture and any active reference pictures.
-
-
The contents of the provided video bitstream buffer range are interpreted as defined in the H.264 Decode Bitstream Data Access section.
-
Picture data in the video picture resources corresponding to the used active reference pictures, decode output picture, and optional reconstructed picture is accessed as defined in the H.264 Decode Picture Data Access section.
-
The decision on reference picture setup is made according to the parameters specified in the H.264 picture information.
If the parameters and the bitstream adhere to the syntactic and semantic requirements defined in the corresponding sections of the ITU-T H.264 Specification, as described above, and the DPB slots associated with the active reference pictures all refer to valid picture references, then the video decode operation will complete successfully. Otherwise, the video decode operation may complete unsuccessfully.
43.12.1. H.264 Decode Bitstream Data Access
If the target decode output picture is a frame, then the video bitstream buffer range should contain a VCL NAL unit comprised of the slice headers and data of a picture representing an entire frame, as defined in sections 7.3.3 and 7.3.4, and this data is interpreted as defined in sections 7.4.3 and 7.4.4 of the ITU-T H.264 Specification, respectively.
If the target decode output picture is a field, then the video bitstream buffer range should contain a VCL NAL unit comprised of the slice headers and data of a picture representing a field, as defined in sections 7.3.3 and 7.3.4, and this data is interpreted as defined in sections 7.4.3 and 7.4.4 of the ITU-T H.264 Specification, respectively.
The offsets provided in
VkVideoDecodeH264PictureInfoKHR::pSliceOffsets should specify
the starting offsets corresponding to each slice header within the video
bitstream buffer range.
43.12.2. H.264 Decode Picture Data Access
The effective imageOffset and imageExtent corresponding to a
decode output picture,
reference picture, or
reconstructed picture used in video decode
operations with an H.264 decode profile are defined
as follows:
-
imageOffsetis (codedOffset.x,codedOffset.y) andimageExtentis (codedExtent.width,codedExtent.height), if the picture represents a frame. -
imageOffsetis (codedOffset.x,codedOffset.y) andimageExtentis (codedExtent.width,codedExtent.height), if the picture represents a field and the picture layout of the used H.264 decode profile isVK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_KHR. -
imageOffsetis (codedOffset.x,codedOffset.y) andimageExtentis (codedExtent.width,codedExtent.height/ 2), if the picture represents a field and the picture layout of the used H.264 decode profile isVK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHR.
Where codedOffset and codedExtent are the members of the
VkVideoPictureResourceInfoKHR structure corresponding to the picture.
However, accesses to image data within a video picture resource happen at
the granularity indicated by
VkVideoCapabilitiesKHR::pictureAccessGranularity, as returned by
vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile.
This means that the complete image subregion accessed by video coding
operations using an H.264 decode profile for the
video picture resource is defined as the set of texels within the coordinate
range:
-
([
startX,endX), [startY,endY))
Where:
-
startXequalsimageOffset.xrounded down to the nearest integer multiple ofpictureAccessGranularity.width; -
endXequalsimageOffset.x+imageExtent.widthrounded up to the nearest integer multiple ofpictureAccessGranularity.widthand clamped to the width of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure; -
startY equals
imageOffset.yrounded down to the nearest integer multiple ofpictureAccessGranularity.height; -
endY equals
imageOffset.y+imageExtent.heightrounded up to the nearest integer multiple ofpictureAccessGranularity.heightand clamped to the height of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure.
In case of video decode operations using an H.264
decode profile, any access to a picture at the coordinates
(x,y), as defined by the ITU-T H.264
Specification, is an access to the image subresource
referred to by the corresponding
VkVideoPictureResourceInfoKHR structure at the texel coordinates
specified below:
-
(
x,y), if the accessed picture represents a frame. -
(
x,y× 2), if the accessed picture represents a top field and the picture layout of the used H.264 decode profile isVK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_KHR. -
(
x,y× 2 + 1), if the accessed picture represents a bottom field and the picture layout of the used H.264 decode profile isVK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_KHR. -
(
x,y), if the accessed picture represents a top field and the picture layout of the used H.264 decode profile isVK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHR. -
(
codedOffset.x+x,codedOffset.y+y), if the accessed picture represents a bottom field and the picture layout of the used H.264 decode profile isVK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHR.
Where codedOffset is the member of the corresponding
VkVideoPictureResourceInfoKHR structure.
43.12.3. H.264 Decode Profile
A video profile supporting H.264 video decode operations is specified by
setting VkVideoProfileInfoKHR::videoCodecOperation to
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR and adding a
VkVideoDecodeH264ProfileInfoKHR structure to the
VkVideoProfileInfoKHR::pNext chain.
The VkVideoDecodeH264ProfileInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_h264
typedef struct VkVideoDecodeH264ProfileInfoKHR {
VkStructureType sType;
const void* pNext;
StdVideoH264ProfileIdc stdProfileIdc;
VkVideoDecodeH264PictureLayoutFlagBitsKHR pictureLayout;
} VkVideoDecodeH264ProfileInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileIdcis aStdVideoH264ProfileIdcvalue specifying the H.264 codec profile IDC, where enum constantSTD_VIDEO_H264_PROFILE_IDC_BASELINEidentifies the Constrained Baseline profile as defined in A.2.1.1 of the ITU-T H.264 Specification, and all other values correspond to profiles defined in section A.2 of the ITU-T H.264 Specification. -
pictureLayoutis a VkVideoDecodeH264PictureLayoutFlagBitsKHR value specifying the picture layout used by the H.264 video sequence to be decoded.
The H.264 video decode picture layout flags are defined as follows:
// Provided by VK_KHR_video_decode_h264
typedef enum VkVideoDecodeH264PictureLayoutFlagBitsKHR {
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_PROGRESSIVE_KHR = 0,
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_KHR = 0x00000001,
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHR = 0x00000002,
} VkVideoDecodeH264PictureLayoutFlagBitsKHR;
-
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_PROGRESSIVE_KHRspecifies support for progressive content. This flag has the value0. -
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_KHRspecifies support for or use of a picture layout for interlaced content where all lines belonging to the top field are decoded to the even-numbered lines within the picture resource, and all lines belonging to the bottom field are decoded to the odd-numbered lines within the picture resource. -
VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHRspecifies support for or use of a picture layout for interlaced content where all lines belonging to a field are grouped together in a single image subregion, and the two fields comprising the frame can be stored in separate image subregions of the same image subresource or in separate image subresources.
// Provided by VK_KHR_video_decode_h264
typedef VkFlags VkVideoDecodeH264PictureLayoutFlagsKHR;
VkVideoDecodeH264PictureLayoutFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoDecodeH264PictureLayoutFlagBitsKHR.
43.12.4. H.264 Decode Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for an H.264 decode profile, the
VkVideoCapabilitiesKHR::pNext chain must include a
VkVideoDecodeH264CapabilitiesKHR structure that will be filled with
the profile-specific capabilities.
The VkVideoDecodeH264CapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_decode_h264
typedef struct VkVideoDecodeH264CapabilitiesKHR {
VkStructureType sType;
void* pNext;
StdVideoH264LevelIdc maxLevelIdc;
VkOffset2D fieldOffsetGranularity;
} VkVideoDecodeH264CapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxLevelIdcis aStdVideoH264LevelIdcvalue indicating the maximum H.264 level supported by the profile, where enum constantSTD_VIDEO_H264_LEVEL_IDC_<major>_<minor>identifies H.264 level<major>.<minor>as defined in section A.3 of the ITU-T H.264 Specification. -
fieldOffsetGranularityis the minimum alignment for VkVideoPictureResourceInfoKHR::codedOffsetspecified for a video picture resource when using the picture layoutVK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHR.
43.12.5. H.264 Decode Parameter Sets
Video session parameters objects created with
the video codec operation VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR
can contain the following types of parameters:
- H.264 Sequence Parameter Sets (SPS)
-
Represented by
StdVideoH264SequenceParameterSetstructures and interpreted as follows:-
reserved1andreserved2are used only for padding purposes and are otherwise ignored; -
seq_parameter_set_idis used as the key of the SPS entry; -
level_idcis one of the enum constantsSTD_VIDEO_H264_LEVEL_IDC_<major>_<minor>identifying the H.264 level<major>.<minor>as defined in section A.3 of the ITU-T H.264 Specification; -
if
flags.seq_scaling_matrix_present_flagis set, then theStdVideoH264ScalingListsstructure pointed to bypScalingListsis interpreted as follows:-
scaling_list_present_maskis a bitmask where bit index i corresponds toseq_scaling_list_present_flag[i]as defined in section 7.4.2.1 of the ITU-T H.264 Specification; -
use_default_scaling_matrix_maskis a bitmask where bit index i corresponds toUseDefaultScalingMatrix4x4Flag[i], when i < 6, or corresponds toUseDefaultScalingMatrix8x8Flag[i-6], otherwise, as defined in section 7.3.2.1 of the ITU-T H.264 Specification; -
ScalingList4x4andScalingList8x8correspond to the identically named syntax elements defined in section 7.3.2.1 of the ITU-T H.264 Specification;
-
-
if
flags.vui_parameters_present_flagis set, thenpSequenceParameterSetVuiis a pointer to aStdVideoH264SequenceParameterSetVuistructure that is interpreted as follows:-
reserved1is used only for padding purposes and is otherwise ignored; -
flags.color_description_present_flagis interpreted as the value ofcolour_description_present_flag, as defined in section E.2.1 of the ITU-T H.264 Specification;NoteThe name of
colour_description_present_flagwas misspelled in the Video Std header. -
if
flags.nal_hrd_parameters_present_flagorflags.vcl_hrd_parameters_present_flagis set, then theStdVideoH264HrdParametersstructure pointed to bypHrdParametersis interpreted as follows:-
reserved1is used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoH264HrdParametersare interpreted as defined in section E.2.2 of the ITU-T H.264 Specification;
-
-
all other members of
StdVideoH264SequenceParameterSetVuiare interpreted as defined in section E.2.1 of the ITU-T H.264 Specification;
-
-
all other members of
StdVideoH264SequenceParameterSetare interpreted as defined in section 7.4.2.1 of the ITU-T H.264 Specification.
-
- H.264 Picture Parameter Sets (PPS)
-
Represented by
StdVideoH264PictureParameterSetstructures and interpreted as follows:-
the pair constructed from
seq_parameter_set_idandpic_parameter_set_idis used as the key of the PPS entry; -
if
flags.pic_scaling_matrix_present_flagis set, then theStdVideoH264ScalingListsstructure pointed to bypScalingListsis interpreted as follows:-
scaling_list_present_maskis a bitmask where bit index i corresponds topic_scaling_list_present_flag[i]as defined in section 7.4.2.2 of the ITU-T H.264 Specification; -
use_default_scaling_matrix_maskis a bitmask where bit index i corresponds toUseDefaultScalingMatrix4x4Flag[i], when i < 6, or corresponds toUseDefaultScalingMatrix8x8Flag[i-6], otherwise, as defined in section 7.3.2.2 of the ITU-T H.264 Specification; -
ScalingList4x4andScalingList8x8correspond to the identically named syntax elements defined in section 7.3.2.2 of the ITU-T H.264 Specification;
-
-
all other members of
StdVideoH264PictureParameterSetare interpreted as defined in section 7.4.2.2 of the ITU-T H.264 Specification.
-
When a video session parameters object is
created with the codec operation
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR, the
VkVideoSessionParametersCreateInfoKHR::pNext chain must include
a VkVideoDecodeH264SessionParametersCreateInfoKHR structure specifying
the capacity and initial contents of the object.
The VkVideoDecodeH264SessionParametersCreateInfoKHR structure is
defined as:
// Provided by VK_KHR_video_decode_h264
typedef struct VkVideoDecodeH264SessionParametersCreateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t maxStdSPSCount;
uint32_t maxStdPPSCount;
const VkVideoDecodeH264SessionParametersAddInfoKHR* pParametersAddInfo;
} VkVideoDecodeH264SessionParametersCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxStdSPSCountis the maximum number of H.264 SPS entries the createdVkVideoSessionParametersKHRcan contain. -
maxStdPPSCountis the maximum number of H.264 PPS entries the createdVkVideoSessionParametersKHRcan contain. -
pParametersAddInfoisNULLor a pointer to a VkVideoDecodeH264SessionParametersAddInfoKHR structure specifying H.264 parameters to add upon object creation.
The VkVideoDecodeH264SessionParametersAddInfoKHR structure is defined
as:
// Provided by VK_KHR_video_decode_h264
typedef struct VkVideoDecodeH264SessionParametersAddInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t stdSPSCount;
const StdVideoH264SequenceParameterSet* pStdSPSs;
uint32_t stdPPSCount;
const StdVideoH264PictureParameterSet* pStdPPSs;
} VkVideoDecodeH264SessionParametersAddInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdSPSCountis the number of elements in thepStdSPSsarray. -
pStdSPSsis a pointer to an array ofStdVideoH264SequenceParameterSetstructures describing the H.264 SPS entries to add. -
stdPPSCountis the number of elements in thepStdPPSsarray. -
pStdPPSsis a pointer to an array ofStdVideoH264PictureParameterSetstructures describing the H.264 PPS entries to add.
This structure can be specified in the following places:
-
In the
pParametersAddInfomember of the VkVideoDecodeH264SessionParametersCreateInfoKHR structure specified in thepNextchain of VkVideoSessionParametersCreateInfoKHR used to create a video session parameters object. In this case, if the video codec operation the video session parameters object is created with isVK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR, then it defines the set of initial parameters to add to the created object (see Creating Video Session Parameters). -
In the
pNextchain of VkVideoSessionParametersUpdateInfoKHR. In this case, if the video codec operation the video session parameters object to be updated was created with isVK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR, then it defines the set of parameters to add to it (see Updating Video Session Parameters).
Inline Parameter Sets
In case of video sessions created with the video codec
operation VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR and with
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHR, the
application can also specify the active parameter sets inline by
including an instance of the
VkVideoDecodeH264InlineSessionParametersInfoKHR structure in the
pNext chain of VkVideoDecodeInfoKHR.
The VkVideoDecodeH264InlineSessionParametersInfoKHR structure is
defined as:
// Provided by VK_KHR_video_decode_h264 with VK_KHR_video_maintenance2
typedef struct VkVideoDecodeH264InlineSessionParametersInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoH264SequenceParameterSet* pStdSPS;
const StdVideoH264PictureParameterSet* pStdPPS;
} VkVideoDecodeH264InlineSessionParametersInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdSPSisNULLor a pointer to an instance of theStdVideoH264SequenceParameterSetstructure describing the active H.264 SPS. -
pStdPPSisNULLor a pointer to an instance of theStdVideoH264PictureParameterSetstructure describing the active H.264 PPS.
If pStdSPS or pStdPPS is not NULL, the issued video decode
operations will use the parameter sets specified by them, respectively,
instead of the corresponding parameter sets being sourced from the bound
video session parameters object.
43.12.6. H.264 Decoding Parameters
The VkVideoDecodeH264PictureInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_h264
typedef struct VkVideoDecodeH264PictureInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeH264PictureInfo* pStdPictureInfo;
uint32_t sliceCount;
const uint32_t* pSliceOffsets;
} VkVideoDecodeH264PictureInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdPictureInfois a pointer to aStdVideoDecodeH264PictureInfostructure specifying H.264 picture information. -
sliceCountis the number of elements inpSliceOffsets. -
pSliceOffsetsis a pointer to an array ofsliceCountoffsets specifying the start offset of the slices of the picture within the video bitstream buffer range specified in VkVideoDecodeInfoKHR.
This structure is specified in the pNext chain of the
VkVideoDecodeInfoKHR structure passed to vkCmdDecodeVideoKHR to
specify the codec-specific picture information for an H.264
decode operation.
- Decode Output Picture Information
-
When this structure is specified in the
pNextchain of the VkVideoDecodeInfoKHR structure passed to vkCmdDecodeVideoKHR, the information related to the decode output picture is defined as follows:-
If
pStdPictureInfo->flags.field_pic_flagis not set, then the picture represents a frame. -
If
pStdPictureInfo->flags.field_pic_flagis set, then the picture represents a field. Specifically:-
If
pStdPictureInfo->flags.bottom_field_flagis not set, then the picture represents the top field of the frame. -
If
pStdPictureInfo->flags.bottom_field_flagis set, then the picture represents the bottom field of the frame.
-
-
The image subregion used is determined according to the H.264 Decode Picture Data Access section.
-
The decode output picture is associated with the H.264 picture information provided in
pStdPictureInfo.
-
- Std Picture Information
-
The members of the
StdVideoDecodeH264PictureInfostructure pointed to bypStdPictureInfoare interpreted as follows:-
reserved1andreserved2are used only for padding purposes and are otherwise ignored; -
flags.is_intraas defined in section 3.73 of the ITU-T H.264 Specification; -
flags.is_referenceas defined in section 3.136 of the ITU-T H.264 Specification; -
flags.complementary_field_pairas defined in section 3.35 of the ITU-T H.264 Specification; -
seq_parameter_set_idandpic_parameter_set_idare used to identify the active parameter sets, as described below; -
all other members are interpreted as defined in section 7.4.3 of the ITU-T H.264 Specification.
-
Reference picture setup is controlled by the value of
StdVideoDecodeH264PictureInfo::flags.is_reference.
If it is set and a reconstructed
picture is specified, then the latter is used as the target of picture
reconstruction to activate the DPB slot
specified in pDecodeInfo->pSetupReferenceSlot->slotIndex.
If StdVideoDecodeH264PictureInfo::flags.is_reference is not set,
but a reconstructed picture is
specified, then the corresponding picture reference associated with the
DPB slot is invalidated, as described in the
DPB Slot States section.
- Active Parameter Sets
-
The members of the
StdVideoDecodeH264PictureInfostructure pointed to bypStdPictureInfoare used to select the active parameter sets to use from the specified inline parameter sets or from the bound video session parameters object, as follows:-
The active SPS is the SPS identified by the key specified in
StdVideoDecodeH264PictureInfo::seq_parameter_set_id. -
The active PPS is the PPS identified by the key specified by the pair constructed from
StdVideoDecodeH264PictureInfo::seq_parameter_set_idandStdVideoDecodeH264PictureInfo::pic_parameter_set_id.
-
If the bound video session was created with
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHR and any of
the active parameter sets are specified
inline, then the corresponding inline
parameter set is used.
Otherwise, the parameter set in question is sourced from the bound video
session parameters object.
The VkVideoDecodeH264DpbSlotInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_h264
typedef struct VkVideoDecodeH264DpbSlotInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeH264ReferenceInfo* pStdReferenceInfo;
} VkVideoDecodeH264DpbSlotInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdReferenceInfois a pointer to aStdVideoDecodeH264ReferenceInfostructure specifying H.264 reference information.
This structure is specified in the pNext chain of
VkVideoDecodeInfoKHR::pSetupReferenceSlot, if not NULL, and
the pNext chain of the elements of
VkVideoDecodeInfoKHR::pReferenceSlots to specify the
codec-specific reference picture information for an H.264
decode operation.
- Active Reference Picture Information
-
When this structure is specified in the
pNextchain of the elements of VkVideoDecodeInfoKHR::pReferenceSlots, one or two elements are added to the list of active reference pictures used by the video decode operation for each element of VkVideoDecodeInfoKHR::pReferenceSlotsas follows:-
If neither
pStdReferenceInfo->flags.top_field_flagnorpStdReferenceInfo->flags.bottom_field_flagis set, then the picture is added as a frame reference to the list of active reference pictures. -
If
pStdReferenceInfo->flags.top_field_flagis set, then the picture is added as a top field reference to the list of active reference pictures. -
If
pStdReferenceInfo->flags.bottom_field_flagis set, then the picture is added as a bottom field reference to the list of active reference pictures. -
For each added reference picture, the corresponding image subregion used is determined according to the H.264 Decode Picture Data Access section.
-
Each added reference picture is associated with the DPB slot index specified in the
slotIndexmember of the corresponding element of VkVideoDecodeInfoKHR::pReferenceSlots. -
Each added reference picture is associated with the H.264 reference information provided in
pStdReferenceInfo.
-
|
Note
|
When both the top and bottom field of an interlaced frame currently
associated with a DPB slot is intended to be used as an active reference
picture and both fields are stored in the same image subregion (which is the
case when using
|
- Reconstructed Picture Information
-
When this structure is specified in the
pNextchain of VkVideoDecodeInfoKHR::pSetupReferenceSlot, the information related to the reconstructed picture is defined as follows:-
If neither
pStdReferenceInfo->flags.top_field_flagnorpStdReferenceInfo->flags.bottom_field_flagis set, then the picture represents a frame. -
If
pStdReferenceInfo->flags.top_field_flagis set, then the picture represents a field, specifically, the top field of the frame. -
If
pStdReferenceInfo->flags.bottom_field_flagis set, then the picture represents a field, specifically, the bottom field of the frame. -
The image subregion used is determined according to the H.264 Decode Picture Data Access section.
-
If reference picture setup is requested, then the reconstructed picture is used to activate the DPB slot with the index specified in VkVideoDecodeInfoKHR::
pSetupReferenceSlot->slotIndex. -
The reconstructed picture is associated with the H.264 reference information provided in
pStdReferenceInfo.
-
- Std Reference Information
-
The members of the
StdVideoDecodeH264ReferenceInfostructure pointed to bypStdReferenceInfoare interpreted as follows:-
flags.top_field_flagis used to indicate whether the reference is used as top field reference; -
flags.bottom_field_flagis used to indicate whether the reference is used as bottom field reference; -
flags.used_for_long_term_referenceis used to indicate whether the picture is marked as “used for long-term reference” as defined in section 8.2.5.1 of the ITU-T H.264 Specification; -
flags.is_non_existingis used to indicate whether the picture is marked as “non-existing” as defined in section 8.2.5.2 of the ITU-T H.264 Specification; -
all other members are interpreted as defined in section 8.2 of the ITU-T H.264 Specification.
-
43.12.7. H.264 Decode Requirements
This section describes the required H.264 decoding capabilities for
physical devices that have at least one queue family that supports the video
codec operation VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR, as
returned by vkGetPhysicalDeviceQueueFamilyProperties2 in
VkQueueFamilyVideoPropertiesKHR::videoCodecOperations.
| Video Std Header Name | Version |
|---|---|
|
1.0.0 |
| Video Capability | Requirement | Requirement Type1 |
|---|---|---|
|
- |
min |
|
4096 |
max |
|
4096 |
max |
|
(64,64) |
max |
|
- |
max |
|
- |
min |
|
0 |
min |
|
0 |
min |
|
|
min |
|
|
min |
|
(0,0) except for profiles using |
implementation-dependent |
- 1
-
The Requirement Type column specifies the requirement is either the minimum value all implementations must support, the maximum value all implementations must support, or the exact value all implementations must support. For bitmasks a minimum value is the least bits all implementations must set, but they may have additional bits set beyond this minimum.
43.13. H.265 Decode Operations
Video decode operations using an H.265 decode profile can be used to decode elementary video stream sequences compliant to the ITU-T H.265 Specification.
|
Note
|
Refer to the Preamble for information on how the Khronos Intellectual Property Rights Policy relates to normative references to external materials not created by Khronos. |
This process is performed according to the video decode operation steps with the codec-specific semantics defined in section 8 of ITU-T H.265 Specification:
-
Syntax elements, derived values, and other parameters are applied from the following structures:
-
The
StdVideoH265VideoParameterSetstructure corresponding to the active VPS specifying the H.265 video parameter set. -
The
StdVideoH265SequenceParameterSetstructure corresponding to the active SPS specifying the H.265 sequence parameter set. -
The
StdVideoH265PictureParameterSetstructure corresponding to the active PPS specifying the H.265 picture parameter set. -
The
StdVideoDecodeH265PictureInfostructure specifying the H.265 picture information. -
The
StdVideoDecodeH265ReferenceInfostructures specifying the H.265 reference information corresponding to the optional reconstructed picture and any active reference pictures.
-
-
The contents of the provided video bitstream buffer range are interpreted as defined in the H.265 Decode Bitstream Data Access section.
-
Picture data in the video picture resources corresponding to the used active reference pictures, decode output picture, and optional reconstructed picture is accessed as defined in the H.265 Decode Picture Data Access section.
-
The decision on reference picture setup is made according to the parameters specified in the H.265 picture information.
If the parameters and the bitstream adhere to the syntactic and semantic requirements defined in the corresponding sections of the ITU-T H.265 Specification, as described above, and the DPB slots associated with the active reference pictures all refer to valid picture references, then the video decode operation will complete successfully. Otherwise, the video decode operation may complete unsuccessfully.
43.13.1. H.265 Decode Bitstream Data Access
The video bitstream buffer range should contain a VCL NAL unit comprised of the slice segment headers and data of a picture representing a frame, as defined in sections 7.3.6 and 7.3.8, and this data is interpreted as defined in sections 7.4.7 and 7.4.9 of the ITU-T H.265 Specification, respectively.
The offsets provided in
VkVideoDecodeH265PictureInfoKHR::pSliceSegmentOffsets should
specify the starting offsets corresponding to each slice segment header
within the video bitstream buffer range.
43.13.2. H.265 Decode Picture Data Access
Accesses to image data within a video picture resource happen at the
granularity indicated by
VkVideoCapabilitiesKHR::pictureAccessGranularity, as returned by
vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile.
Accordingly, the complete image subregion of a
decode output picture,
reference picture, or
reconstructed picture accessed by video coding
operations using an H.265 decode profile is defined
as the set of texels within the coordinate range:
-
([0,
endX), [0,endY))
Where:
-
endXequalscodedExtent.widthrounded up to the nearest integer multiple ofpictureAccessGranularity.widthand clamped to the width of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure; -
endY equals
codedExtent.heightrounded up to the nearest integer multiple ofpictureAccessGranularity.heightand clamped to the height of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure;
Where codedExtent is the member of the
VkVideoPictureResourceInfoKHR structure corresponding to the picture.
In case of video decode operations using an H.265
decode profile, any access to a picture at the coordinates
(x,y), as defined by the ITU-T H.265
Specification, is an access to the image subresource
referred to by the corresponding
VkVideoPictureResourceInfoKHR structure at the texel coordinates
(x,y).
43.13.3. H.265 Decode Profile
A video profile supporting H.265 video decode operations is specified by
setting VkVideoProfileInfoKHR::videoCodecOperation to
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR and adding a
VkVideoDecodeH265ProfileInfoKHR structure to the
VkVideoProfileInfoKHR::pNext chain.
The VkVideoDecodeH265ProfileInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_h265
typedef struct VkVideoDecodeH265ProfileInfoKHR {
VkStructureType sType;
const void* pNext;
StdVideoH265ProfileIdc stdProfileIdc;
} VkVideoDecodeH265ProfileInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileIdcis aStdVideoH265ProfileIdcvalue specifying the H.265 codec profile IDC, as defined in section A.3 of the ITU-T H.265 Specification.
43.13.4. H.265 Decode Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for an H.265 decode profile, the
VkVideoCapabilitiesKHR::pNext chain must include a
VkVideoDecodeH265CapabilitiesKHR structure that will be filled with
the profile-specific capabilities.
The VkVideoDecodeH265CapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_decode_h265
typedef struct VkVideoDecodeH265CapabilitiesKHR {
VkStructureType sType;
void* pNext;
StdVideoH265LevelIdc maxLevelIdc;
} VkVideoDecodeH265CapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxLevelIdcis aStdVideoH265LevelIdcvalue indicating the maximum H.265 level supported by the profile, where enum constantSTD_VIDEO_H265_LEVEL_IDC_<major>_<minor>identifies H.265 level<major>.<minor>as defined in section A.4 of the ITU-T H.265 Specification.
43.13.5. H.265 Decode Parameter Sets
Video session parameters objects created with
the video codec operation VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR
can contain the following types of parameters:
- H.265 Video Parameter Sets (VPS)
-
Represented by
StdVideoH265VideoParameterSetstructures and interpreted as follows:-
reserved1,reserved2, andreserved3are used only for padding purposes and are otherwise ignored; -
vps_video_parameter_set_idis used as the key of the VPS entry; -
the
max_latency_increase_plus1,max_dec_pic_buffering_minus1, andmax_num_reorder_picsmembers of theStdVideoH265DecPicBufMgrstructure pointed to bypDecPicBufMgrcorrespond tovps_max_latency_increase_plus1,vps_max_dec_pic_buffering_minus1, andvps_max_num_reorder_pics, respectively, as defined in section 7.4.3.1 of the ITU-T H.265 Specification; -
the
StdVideoH265HrdParametersstructure pointed to bypHrdParametersis interpreted as follows:-
reservedis used only for padding purposes and is otherwise ignored; -
flags.fixed_pic_rate_general_flagis a bitmask where bit index i corresponds tofixed_pic_rate_general_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
flags.fixed_pic_rate_within_cvs_flagis a bitmask where bit index i corresponds tofixed_pic_rate_within_cvs_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
flags.low_delay_hrd_flagis a bitmask where bit index i corresponds tolow_delay_hrd_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
if
flags.nal_hrd_parameters_present_flagis set, thenpSubLayerHrdParametersNalis a pointer to an array ofvps_max_sub_layers_minus1+ 1 number ofStdVideoH265SubLayerHrdParametersstructures wherevps_max_sub_layers_minus1is the corresponding member of the encompassingStdVideoH265VideoParameterSetstructure and each element is interpreted as follows:-
cbr_flagis a bitmask where bit index i corresponds tocbr_flag[i]as defined in section E.3.3 of the ITU-T H.265 Specification; -
all other members of the
StdVideoH265SubLayerHrdParametersstructure are interpreted as defined in section E.3.3 of the ITU-T H.265 Specification;
-
-
if
flags.vcl_hrd_parameters_present_flagis set, thenpSubLayerHrdParametersVclis a pointer to an array ofvps_max_sub_layers_minus1+ 1 number ofStdVideoH265SubLayerHrdParametersstructures wherevps_max_sub_layers_minus1is the corresponding member of the encompassingStdVideoH265VideoParameterSetstructure and each element is interpreted as follows:-
cbr_flagis a bitmask where bit index i corresponds tocbr_flag[i]as defined in section E.3.3 of the ITU-T H.265 Specification; -
all other members of the
StdVideoH265SubLayerHrdParametersstructure are interpreted as defined in section E.3.3 of the ITU-T H.265 Specification;
-
-
all other members of
StdVideoH265HrdParametersare interpreted as defined in section E.3.2 of the ITU-T H.265 Specification;
-
-
the
StdVideoH265ProfileTierLevelstructure pointed to bypProfileTierLevelare interpreted as follows:-
general_level_idcis one of the enum constantsSTD_VIDEO_H265_LEVEL_IDC_<major>_<minor>identifying the H.265 level<major>.<minor>as defined in section A.4 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265ProfileTierLevelare interpreted as defined in section 7.4.4 of the ITU-T H.265 Specification;
-
-
all other members of
StdVideoH265VideoParameterSetare interpreted as defined in section 7.4.3.1 of the ITU-T H.265 Specification.
-
- H.265 Sequence Parameter Sets (SPS)
-
Represented by
StdVideoH265SequenceParameterSetstructures and interpreted as follows:-
reserved1andreserved2are used only for padding purposes and are otherwise ignored; -
the pair constructed from
sps_video_parameter_set_idandsps_seq_parameter_set_idis used as the key of the SPS entry; -
the
StdVideoH265ProfileTierLevelstructure pointed to bypProfileTierLevelare interpreted as follows:-
general_level_idcis one of the enum constantsSTD_VIDEO_H265_LEVEL_IDC_<major>_<minor>identifying the H.265 level<major>.<minor>as defined in section A.4 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265ProfileTierLevelare interpreted as defined in section 7.4.4 of the ITU-T H.265 Specification;
-
-
the
max_latency_increase_plus1,max_dec_pic_buffering_minus1, andmax_num_reorder_picsmembers of theStdVideoH265DecPicBufMgrstructure pointed to bypDecPicBufMgrcorrespond tosps_max_latency_increase_plus1,sps_max_dec_pic_buffering_minus1, andsps_max_num_reorder_pics, respectively, as defined in section 7.4.3.2 of the ITU-T H.265 Specification; -
if
flags.sps_scaling_list_data_present_flagis set, then theStdVideoH265ScalingListsstructure pointed to bypScalingListsis interpreted as follows:-
ScalingList4x4,ScalingList8x8,ScalingList16x16, andScalingList32x32correspond toScalingList[0],ScalingList[1],ScalingList[2], andScalingList[3], respectively, as defined in section 7.3.4 of the ITU-T H.265 Specification; -
ScalingListDCCoef16x16andScalingListDCCoef32x32correspond toscaling_list_dc_coef_minus8[0]andscaling_list_dc_coef_minus8[1], respectively, as defined in section 7.3.4 of the ITU-T H.265 Specification;
-
-
pShortTermRefPicSetis a pointer to an array ofnum_short_term_ref_pic_setsnumber ofStdVideoH265ShortTermRefPicSetstructures where each element is interpreted as follows:-
reserved1,reserved2, andreserved3are used only for padding purposes and are otherwise ignored; -
used_by_curr_pic_flagis a bitmask where bit index i corresponds toused_by_curr_pic_flag[i]as defined in section 7.4.8 of the ITU-T H.265 Specification; -
use_delta_flagis a bitmask where bit index i corresponds touse_delta_flag[i]as defined in section 7.4.8 of the ITU-T H.265 Specification; -
used_by_curr_pic_s0_flagis a bitmask where bit index i corresponds toused_by_curr_pic_s0_flag[i]as defined in section 7.4.8 of the ITU-T H.265 Specification; -
used_by_curr_pic_s1_flagis a bitmask where bit index i corresponds toused_by_curr_pic_s1_flag[i]as defined in section 7.4.8 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265ShortTermRefPicSetare interpreted as defined in section 7.4.8 of the ITU-T H.265 Specification;
-
-
if
flags.long_term_ref_pics_present_flagis set then theStdVideoH265LongTermRefPicsSpsstructure pointed to bypLongTermRefPicsSpsis interpreted as follows:-
used_by_curr_pic_lt_sps_flagis a bitmask where bit index i corresponds toused_by_curr_pic_lt_sps_flag[i]as defined in section 7.4.3.2 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265LongTermRefPicsSpsare interpreted as defined in section 7.4.3.2 of the ITU-T H.265 Specification;
-
-
if
flags.vui_parameters_present_flagis set, then theStdVideoH265SequenceParameterSetVuistructure pointed to bypSequenceParameterSetVuiis interpreted as follows:-
reserved1,reserved2, andreserved3are used only for padding purposes and are otherwise ignored; -
the
StdVideoH265HrdParametersstructure pointed to bypHrdParametersis interpreted as follows:-
flags.fixed_pic_rate_general_flagis a bitmask where bit index i corresponds tofixed_pic_rate_general_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
flags.fixed_pic_rate_within_cvs_flagis a bitmask where bit index i corresponds tofixed_pic_rate_within_cvs_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
flags.low_delay_hrd_flagis a bitmask where bit index i corresponds tolow_delay_hrd_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
if
flags.nal_hrd_parameters_present_flagis set, thenpSubLayerHrdParametersNalis a pointer to an array ofsps_max_sub_layers_minus1+ 1 number ofStdVideoH265SubLayerHrdParametersstructures wheresps_max_sub_layers_minus1is the corresponding member of the encompassingStdVideoH265SequenceParameterSetstructure and each element is interpreted as follows:-
cbr_flagis a bitmask where bit index i corresponds tocbr_flag[i]as defined in section E.3.3 of the ITU-T H.265 Specification; -
all other members of the
StdVideoH265SubLayerHrdParametersstructure are interpreted as defined in section E.3.3 of the ITU-T H.265 Specification;
-
-
if
flags.vcl_hrd_parameters_present_flagis set, thenpSubLayerHrdParametersVclis a pointer to an array ofsps_max_sub_layers_minus1+ 1 number ofStdVideoH265SubLayerHrdParametersstructures wheresps_max_sub_layers_minus1is the corresponding member of the encompassingStdVideoH265SequenceParameterSetstructure and each element is interpreted as follows:-
cbr_flagis a bitmask where bit index i corresponds tocbr_flag[i]as defined in section E.3.3 of the ITU-T H.265 Specification; -
all other members of the
StdVideoH265SubLayerHrdParametersstructure are interpreted as defined in section E.3.3 of the ITU-T H.265 Specification;
-
-
all other members of
StdVideoH265HrdParametersare interpreted as defined in section E.3.2 of the ITU-T H.265 Specification;
-
-
all other members of
pSequenceParameterSetVuiare interpreted as defined in section E.3.1 of the ITU-T H.265 Specification;
-
-
if
flags.sps_palette_predictor_initializer_present_flagis set, then thePredictorPaletteEntriesmember of theStdVideoH265PredictorPaletteEntriesstructure pointed to bypPredictorPaletteEntriesis interpreted as defined in section 7.4.9.13 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265SequenceParameterSetare interpreted as defined in section 7.4.3.1 of the ITU-T H.265 Specification.
-
- H.265 Picture Parameter Sets (PPS)
-
Represented by
StdVideoH265PictureParameterSetstructures and interpreted as follows:-
reserved1,reserved2, andreserved3are used only for padding purposes and are otherwise ignored; -
the triplet constructed from
sps_video_parameter_set_id,pps_seq_parameter_set_id, andpps_pic_parameter_set_idis used as the key of the PPS entry; -
if
flags.pps_scaling_list_data_present_flagis set, then theStdVideoH265ScalingListsstructure pointed to bypScalingListsis interpreted as follows:-
ScalingList4x4,ScalingList8x8,ScalingList16x16, andScalingList32x32correspond toScalingList[0],ScalingList[1],ScalingList[2], andScalingList[3], respectively, as defined in section 7.3.4 of the ITU-T H.265 Specification; -
ScalingListDCCoef16x16andScalingListDCCoef32x32correspond toscaling_list_dc_coef_minus8[0]andscaling_list_dc_coef_minus8[1], respectively, as defined in section 7.3.4 of the ITU-T H.265 Specification;
-
-
if
flags.pps_palette_predictor_initializer_present_flagis set, then thePredictorPaletteEntriesmember of theStdVideoH265PredictorPaletteEntriesstructure pointed to bypPredictorPaletteEntriesis interpreted as defined in section 7.4.9.13 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265PictureParameterSetare interpreted as defined in section 7.4.3.3 of the ITU-T H.265 Specification.
-
When a video session parameters object is
created with the codec operation
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, the
VkVideoSessionParametersCreateInfoKHR::pNext chain must include
a VkVideoDecodeH265SessionParametersCreateInfoKHR structure specifying
the capacity and initial contents of the object.
The VkVideoDecodeH265SessionParametersCreateInfoKHR structure is
defined as:
// Provided by VK_KHR_video_decode_h265
typedef struct VkVideoDecodeH265SessionParametersCreateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t maxStdVPSCount;
uint32_t maxStdSPSCount;
uint32_t maxStdPPSCount;
const VkVideoDecodeH265SessionParametersAddInfoKHR* pParametersAddInfo;
} VkVideoDecodeH265SessionParametersCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxStdVPSCountis the maximum number of H.265 VPS entries the createdVkVideoSessionParametersKHRcan contain. -
maxStdSPSCountis the maximum number of H.265 SPS entries the createdVkVideoSessionParametersKHRcan contain. -
maxStdPPSCountis the maximum number of H.265 PPS entries the createdVkVideoSessionParametersKHRcan contain. -
pParametersAddInfoisNULLor a pointer to a VkVideoDecodeH265SessionParametersAddInfoKHR structure specifying H.265 parameters to add upon object creation.
The VkVideoDecodeH265SessionParametersAddInfoKHR structure is defined
as:
// Provided by VK_KHR_video_decode_h265
typedef struct VkVideoDecodeH265SessionParametersAddInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t stdVPSCount;
const StdVideoH265VideoParameterSet* pStdVPSs;
uint32_t stdSPSCount;
const StdVideoH265SequenceParameterSet* pStdSPSs;
uint32_t stdPPSCount;
const StdVideoH265PictureParameterSet* pStdPPSs;
} VkVideoDecodeH265SessionParametersAddInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdVPSCountis the number of elements in thepStdVPSsarray. -
pStdVPSsis a pointer to an array ofStdVideoH265VideoParameterSetstructures describing the H.265 VPS entries to add. -
stdSPSCountis the number of elements in thepStdSPSsarray. -
pStdSPSsis a pointer to an array ofStdVideoH265SequenceParameterSetstructures describing the H.265 SPS entries to add. -
stdPPSCountis the number of elements in thepStdPPSsarray. -
pStdPPSsis a pointer to an array ofStdVideoH265PictureParameterSetstructures describing the H.265 PPS entries to add.
This structure can be specified in the following places:
-
In the
pParametersAddInfomember of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure specified in thepNextchain of VkVideoSessionParametersCreateInfoKHR used to create a video session parameters object. In this case, if the video codec operation the video session parameters object is created with isVK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, then it defines the set of initial parameters to add to the created object (see Creating Video Session Parameters). -
In the
pNextchain of VkVideoSessionParametersUpdateInfoKHR. In this case, if the video codec operation the video session parameters object to be updated was created with isVK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, then it defines the set of parameters to add to it (see Updating Video Session Parameters).
Inline Parameter Sets
In case of video sessions created with the video codec
operation VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR and with
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHR, the
application can also specify the active parameter sets inline by
including an instance of the
VkVideoDecodeH265InlineSessionParametersInfoKHR structure in the
pNext chain of VkVideoDecodeInfoKHR.
The VkVideoDecodeH265InlineSessionParametersInfoKHR structure is
defined as:
// Provided by VK_KHR_video_decode_h265 with VK_KHR_video_maintenance2
typedef struct VkVideoDecodeH265InlineSessionParametersInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoH265VideoParameterSet* pStdVPS;
const StdVideoH265SequenceParameterSet* pStdSPS;
const StdVideoH265PictureParameterSet* pStdPPS;
} VkVideoDecodeH265InlineSessionParametersInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdVPSisNULLor a pointer to an instance of theStdVideoH265VideoParameterSetstructure describing the active H.265 VPS. -
pStdSPSisNULLor a pointer to an instance of theStdVideoH265SequenceParameterSetstructure describing the active H.265 SPS. -
pStdPPSisNULLor a pointer to an instance of theStdVideoH265PictureParameterSetstructure describing the active H.265 PPS.
If pStdVPS, pStdSPS, or pStdPPS is not NULL, the issued
video decode operations will use the parameter sets specified by them,
respectively, instead of the corresponding active parameter sets being
sourced from the bound video session parameters object.
43.13.6. H.265 Decoding Parameters
The VkVideoDecodeH265PictureInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_h265
typedef struct VkVideoDecodeH265PictureInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeH265PictureInfo* pStdPictureInfo;
uint32_t sliceSegmentCount;
const uint32_t* pSliceSegmentOffsets;
} VkVideoDecodeH265PictureInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdPictureInfois a pointer to aStdVideoDecodeH265PictureInfostructure specifying H.265 picture information. -
sliceSegmentCountis the number of elements inpSliceSegmentOffsets. -
pSliceSegmentOffsetsis a pointer to an array ofsliceSegmentCountoffsets specifying the start offset of the slice segments of the picture within the video bitstream buffer range specified in VkVideoDecodeInfoKHR.
This structure is specified in the pNext chain of the
VkVideoDecodeInfoKHR structure passed to vkCmdDecodeVideoKHR to
specify the codec-specific picture information for an H.265
decode operation.
- Decode Output Picture Information
-
When this structure is specified in the
pNextchain of the VkVideoDecodeInfoKHR structure passed to vkCmdDecodeVideoKHR, the information related to the decode output picture is defined as follows:-
The image subregion used is determined according to the H.265 Decode Picture Data Access section.
-
The decode output picture is associated with the H.265 picture information provided in
pStdPictureInfo.
-
- Std Picture Information
-
The members of the
StdVideoDecodeH265PictureInfostructure pointed to bypStdPictureInfoare interpreted as follows:-
reservedis used only for padding purposes and is otherwise ignored; -
flags.IrapPicFlagas defined in section 3.73 of the ITU-T H.265 Specification; -
flags.IdrPicFlagas defined in section 3.67 of the ITU-T H.265 Specification; -
flags.IsReferenceas defined in section 3.132 of the ITU-T H.265 Specification; -
sps_video_parameter_set_id,pps_seq_parameter_set_id, andpps_pic_parameter_set_idare used to identify the active parameter sets, as described below; -
PicOrderCntValas defined in section 8.3.1 of the ITU-T H.265 Specification; -
NumBitsForSTRefPicSetInSliceis the number of bits used inst_ref_pic_setwhenshort_term_ref_pic_set_sps_flagis0, or0otherwise, as defined in sections 7.4.7 and 7.4.8 of the ITU-T H.265 Specification; -
NumDeltaPocsOfRefRpsIdxis the value ofNumDeltaPocs[RefRpsIdx]whenshort_term_ref_pic_set_sps_flagis1, or0otherwise, as defined in sections 7.4.7 and 7.4.8 of the ITU-T H.265 Specification; -
RefPicSetStCurrBefore,RefPicSetStCurrAfter, andRefPicSetLtCurrare interpreted as defined in section 8.3.2 of the ITU-T H.265 Specification where each element of these arrays either identifies an active reference picture using its DPB slot index or contains the valueSTD_VIDEO_H265_NO_REFERENCE_PICTUREto indicate “no reference picture”; -
all other members are interpreted as defined in section 8.3.2 of the ITU-T H.265 Specification.
-
Reference picture setup is controlled by the value of
StdVideoDecodeH265PictureInfo::flags.IsReference.
If it is set and a reconstructed
picture is specified, then the latter is used as the target of picture
reconstruction to activate the corresponding
DPB slot.
If StdVideoDecodeH265PictureInfo::flags.IsReference is not set,
but a reconstructed picture is
specified, then the corresponding picture reference associated with the
DPB slot is invalidated, as described in the
DPB Slot States section.
- Active Parameter Sets
-
The members of the
StdVideoDecodeH265PictureInfostructure pointed to bypStdPictureInfoare used to select the active parameter sets to use from the specified inline parameter sets or from the bound video session parameters object, as follows:-
The active VPS is the VPS identified by the key specified in
StdVideoDecodeH265PictureInfo::sps_video_parameter_set_id. -
The active SPS is the SPS identified by the key specified by the pair constructed from
StdVideoDecodeH265PictureInfo::sps_video_parameter_set_idandStdVideoDecodeH265PictureInfo::pps_seq_parameter_set_id. -
The active PPS is the PPS identified by the key specified by the triplet constructed from
StdVideoDecodeH265PictureInfo::sps_video_parameter_set_id,StdVideoDecodeH265PictureInfo::pps_seq_parameter_set_id, andStdVideoDecodeH265PictureInfo::pps_pic_parameter_set_id.
-
If the bound video session was created with
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHR and any of
the active parameter sets are specified
inline, then the corresponding inline
parameter set is used.
Otherwise, the parameter set in question is sourced from the bound video
session parameters object.
The VkVideoDecodeH265DpbSlotInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_h265
typedef struct VkVideoDecodeH265DpbSlotInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeH265ReferenceInfo* pStdReferenceInfo;
} VkVideoDecodeH265DpbSlotInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdReferenceInfois a pointer to aStdVideoDecodeH265ReferenceInfostructure specifying reference picture information described in section 8.3 of the ITU-T H.265 Specification.
This structure is specified in the pNext chain of
VkVideoDecodeInfoKHR::pSetupReferenceSlot, if not NULL, and
the pNext chain of the elements of
VkVideoDecodeInfoKHR::pReferenceSlots to specify the
codec-specific reference picture information for an H.265
decode operation.
- Active Reference Picture Information
-
When this structure is specified in the
pNextchain of the elements of VkVideoDecodeInfoKHR::pReferenceSlots, one element is added to the list of active reference pictures used by the video decode operation for each element of VkVideoDecodeInfoKHR::pReferenceSlotsas follows:-
The image subregion used is determined according to the H.265 Decode Picture Data Access section.
-
The reference picture is associated with the DPB slot index specified in the
slotIndexmember of the corresponding element of VkVideoDecodeInfoKHR::pReferenceSlots. -
The reference picture is associated with the H.265 reference information provided in
pStdReferenceInfo.
-
- Reconstructed Picture Information
-
When this structure is specified in the
pNextchain of VkVideoDecodeInfoKHR::pSetupReferenceSlot, the information related to the reconstructed picture is defined as follows:-
The image subregion used is determined according to the H.265 Decode Picture Data Access section.
-
If reference picture setup is requested, then the reconstructed picture is used to activate the DPB slot with the index specified in VkVideoDecodeInfoKHR::
pSetupReferenceSlot->slotIndex. -
The reconstructed picture is associated with the H.265 reference information provided in
pStdReferenceInfo.
-
- Std Reference Information
-
The members of the
StdVideoDecodeH265ReferenceInfostructure pointed to bypStdReferenceInfoare interpreted as follows:-
flags.used_for_long_term_referenceis used to indicate whether the picture is marked as “used for long-term reference” as defined in section 8.3.2 of the ITU-T H.265 Specification; -
flags.unused_for_referenceis used to indicate whether the picture is marked as “unused for reference” as defined in section 8.3.2 of the ITU-T H.265 Specification; -
all other members are interpreted as defined in section 8.3 of the ITU-T H.265 Specification.
-
43.13.7. H.265 Decode Requirements
This section describes the required H.265 decoding capabilities for
physical devices that have at least one queue family that supports the video
codec operation VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, as
returned by vkGetPhysicalDeviceQueueFamilyProperties2 in
VkQueueFamilyVideoPropertiesKHR::videoCodecOperations.
| Video Std Header Name | Version |
|---|---|
|
1.0.0 |
| Video Capability | Requirement | Requirement Type1 |
|---|---|---|
|
- |
min |
|
4096 |
max |
|
4096 |
max |
|
(64,64) |
max |
|
- |
max |
|
- |
min |
|
0 |
min |
|
0 |
min |
|
|
min |
|
|
min |
- 1
-
The Requirement Type column specifies the requirement is either the minimum value all implementations must support, the maximum value all implementations must support, or the exact value all implementations must support. For bitmasks a minimum value is the least bits all implementations must set, but they may have additional bits set beyond this minimum.
43.14. VP9 Decode Operations
Video decode operations using an VP9 decode profile can be used to decode elementary video stream sequences compliant with the VP9 Specification.
|
Note
|
Refer to the Preamble for information on how the Khronos Intellectual Property Rights Policy relates to normative references to external materials not created by Khronos. |
This process is performed according to the video decode operation steps with the codec-specific semantics defined in section 8 of the VP9 Specification:
-
Syntax elements, derived values, and other parameters are applied from the
StdVideoDecodeVP9PictureInfostructure specifying the VP9 picture information. -
The contents of the provided video bitstream buffer range are interpreted as defined in the VP9 Decode Bitstream Data Access section.
-
Picture data in the video picture resources corresponding to the used active reference pictures, decode output picture, and optional reconstructed picture is accessed as defined in the VP9 Decode Picture Data Access section.
-
The decision on reference picture setup is made according to the parameters specified in the VP9 picture information.
If the parameters and the bitstream adhere to the syntactic and semantic requirements defined in the corresponding sections of the VP9 Specification, as described above, and the DPB slots associated with the active reference pictures all refer to valid picture references, then the video decode operation will complete successfully. Otherwise, the video decode operation may complete unsuccessfully.
43.14.1. VP9 Decode Bitstream Data Access
The video bitstream buffer range should contain the bitstream that represents an entire frame, as defined in section 6.1, and this data is interpreted as defined in section 7.1 of the VP9 Specification, respectively.
The offset specified in
VkVideoDecodeVP9PictureInfoKHR::uncompressedHeaderOffset should
specify the starting offset of the uncompressed header of the frame, as
defined in section 6.2 of the VP9 Specification.
The offset specified in
VkVideoDecodeVP9PictureInfoKHR::compressedHeaderOffset should
specify the starting offset of the compressed header of the frame, as
defined in section 6.3 of the VP9 Specification.
The offset specified in
VkVideoDecodeVP9PictureInfoKHR::tilesOffset should specify the
starting offset of the frame tile data, as defined in section 6.4 of the
VP9 Specification.
43.14.2. VP9 Decode Picture Data Access
Accesses to image data within a video picture resource happen at the
granularity indicated by
VkVideoCapabilitiesKHR::pictureAccessGranularity, as returned by
vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile.
Accordingly, the complete image subregion of a
decode output picture,
reference picture, or
reconstructed picture accessed by video coding
operations using an VP9 decode profile is defined as
the set of texels within the coordinate range:
-
([0,
endX), [0,endY))
Where:
-
endXequalscodedExtent.widthrounded up to the nearest integer multiple ofpictureAccessGranularity.widthand clamped to the width of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure; -
endY equals
codedExtent.heightrounded up to the nearest integer multiple ofpictureAccessGranularity.heightand clamped to the height of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure;
Where codedExtent is the member of the
VkVideoPictureResourceInfoKHR structure corresponding to the picture.
In case of video decode operations using an VP9 decode
profile, any access to a picture at the coordinates
(x,y), as defined by the VP9 Specification,
is an access to the image subresource
referred to by the corresponding
VkVideoPictureResourceInfoKHR structure at the texel coordinates
(x,y).
43.14.3. VP9 Reference Names and Semantics
Individual reference frames used in the decoding process have different
semantics, as defined in section 7.4.12 of the VP9
Specification.
The VP9 semantics associated with a reference picture are indicated by the
corresponding enumeration constant defined in the Video Std enumeration type
StdVideoVP9ReferenceName:
-
STD_VIDEO_VP9_REFERENCE_NAME_INTRA_FRAMEidentifies the reference used for intra coding (INTRA_FRAME), as defined in sections 2 and 8.5.1 of the VP9 Specification. -
All other enumeration constants refer to backward or forward references used for inter coding, as defined in sections 2 and 8.5.2 of the VP9 Specification:
-
STD_VIDEO_VP9_REFERENCE_NAME_LAST_FRAMEidentifies theLAST_FRAMEreference -
STD_VIDEO_VP9_REFERENCE_NAME_GOLDEN_FRAMEidentifies theGOLDEN_FRAMEreference -
STD_VIDEO_VP9_REFERENCE_NAME_ALTREF_FRAMEidentifies theALTREF_FRAMEreference
-
These enumeration constants are not directly used in any APIs but are used to indirectly index into certain Video Std and Vulkan API parameter arrays.
43.14.4. VP9 Decode Profile
A video profile supporting VP9 video decode operations is specified by
setting VkVideoProfileInfoKHR::videoCodecOperation to
VK_VIDEO_CODEC_OPERATION_DECODE_VP9_BIT_KHR and adding a
VkVideoDecodeVP9ProfileInfoKHR structure to the
VkVideoProfileInfoKHR::pNext chain.
The VkVideoDecodeVP9ProfileInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_vp9
typedef struct VkVideoDecodeVP9ProfileInfoKHR {
VkStructureType sType;
const void* pNext;
StdVideoVP9Profile stdProfile;
} VkVideoDecodeVP9ProfileInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileis aStdVideoVP9Profilevalue specifying the VP9 codec profile, as defined in section 7.2 of the VP9 Specification.
43.14.5. VP9 Decode Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for an VP9 decode profile, the
VkVideoCapabilitiesKHR::pNext chain must include a
VkVideoDecodeVP9CapabilitiesKHR structure that will be filled with the
profile-specific capabilities.
The VkVideoDecodeVP9CapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_decode_vp9
typedef struct VkVideoDecodeVP9CapabilitiesKHR {
VkStructureType sType;
void* pNext;
StdVideoVP9Level maxLevel;
} VkVideoDecodeVP9CapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxLevelis aStdVideoVP9Levelvalue specifying the maximum VP9 level supported by the profile, as defined in section A.1 of the VP9 Specification.
43.14.6. VP9 Decoding Parameters
The VkVideoDecodeVP9PictureInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_vp9
typedef struct VkVideoDecodeVP9PictureInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeVP9PictureInfo* pStdPictureInfo;
int32_t referenceNameSlotIndices[VK_MAX_VIDEO_VP9_REFERENCES_PER_FRAME_KHR];
uint32_t uncompressedHeaderOffset;
uint32_t compressedHeaderOffset;
uint32_t tilesOffset;
} VkVideoDecodeVP9PictureInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdPictureInfois a pointer to aStdVideoDecodeVP9PictureInfostructure specifying VP9 picture information. -
referenceNameSlotIndicesis an array of three (VK_MAX_VIDEO_VP9_REFERENCES_PER_FRAME_KHR, which is equal to the Video Std definitionSTD_VIDEO_VP9_REFS_PER_FRAME) signed integer values specifying the index of the DPB slot or a negative integer value for each VP9 reference name used for inter coding. In particular, the DPB slot index for the VP9 reference nameframeis specified inreferenceNameSlotIndices[frame-STD_VIDEO_VP9_REFERENCE_NAME_LAST_FRAME]. -
uncompressedHeaderOffsetis the byte offset of the uncompressed frame header, as defined in section 6.2 of the VP9 Specification. -
compressedHeaderOffsetis the byte offset of the compressed frame header, as defined in section 6.3 of the VP9 Specification. -
tilesOffsetis the byte offset of the frame tile data, as defined in section 6.4 of the VP9 Specification.
This structure is specified in the pNext chain of the
VkVideoDecodeInfoKHR structure passed to vkCmdDecodeVideoKHR to
specify the codec-specific picture information for an VP9
decode operation.
- Decode Output Picture Information
-
When this structure is specified in the
pNextchain of the VkVideoDecodeInfoKHR structure passed to vkCmdDecodeVideoKHR, the information related to the decode output picture is defined as follows:-
The image subregion used is determined according to the VP9 Decode Picture Data Access section.
-
The decode output picture is associated with the VP9 picture information provided in
pStdPictureInfo.
-
- Std Picture Information
-
The members of the
StdVideoDecodeVP9PictureInfostructure pointed to bypStdPictureInfoare interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
ref_frame_sign_bias_maskis a bitmask where bit index i corresponds toref_frame_sign_bias[i]as defined in section 7.2 of the VP9 Specification; -
the
StdVideoVP9ColorConfigstructure pointed to bypColorConfigis interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
all other members of
StdVideoVP9ColorConfigare interpreted as defined in sections 6.2, 6.2.2, and 7.2.2 of the VP9 Specification;
-
-
the
StdVideoVP9LoopFilterstructure pointed to bypLoopFilteris interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
update_ref_deltais a bitmask where bit index i is interpreted as the value ofupdate_ref_deltacorresponding to element i ofloop_filter_ref_deltasas defined in section 7.2.8 of the VP9 Specification; -
update_mode_deltais a bitmask where bit index i is interpreted as the value ofupdate_mode_deltacorresponding to element i ofloop_filter_mode_deltasas defined in section 7.2.8 of the VP9 Specification; -
all other members of
StdVideoVP9LoopFilterare interpreted as defined in section 7.2.8 of the VP9 Specification;NoteIf the syntax elements corresponding to
loop_filter_ref_deltasandloop_filter_mode_deltasare not present, the application should specify the previous values, as defined in section 7.2.8 of the VP9 Specification.
-
-
if
flags.segmentation_enabledis set, then theStdVideoVP9Segmentationstructure pointed to bypSegmentationis interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
the elements of
FeatureEnabledare bitmasks where bit index j of element i corresponds toFeatureEnabled[i][j]as defined in section 6.2.11 of the VP9 Specification; -
FeatureDatais interpreted as defined in section 6.2.11 of the VP9 Specification; -
all other members of
StdVideoVP9Segmentationare interpreted as defined in section 7.2.10 of the VP9 Specification;
-
-
all other members are interpreted as defined in section 7.2 of the VP9 Specification.
-
Reference picture setup is controlled by the value of
StdVideoDecodeVP9PictureInfo::refresh_frame_flags.
If it is not zero and a reconstructed
picture is specified, then the latter is used as the target of picture
reconstruction to activate the DPB slot
specified in pDecodeInfo->pSetupReferenceSlot->slotIndex.
If StdVideoDecodeVP9PictureInfo::refresh_frame_flags is zero, but
a reconstructed picture is specified,
then the corresponding picture reference associated with the DPB
slot is invalidated, as described in the DPB Slot
States section.
|
Note
|
VP9 decode operations do not need any std reference information to be
specified for the active reference pictures and the optional reconstructed
picture.
Accordingly, no DPB slot info structure exists in the API that would need to
be chained to the corresponding VkVideoReferenceSlotInfoKHR structures
and no |
43.14.7. VP9 Decode Requirements
This section describes the required VP9 decoding capabilities for physical
devices that have at least one queue family that supports the video codec
operation VK_VIDEO_CODEC_OPERATION_DECODE_VP9_BIT_KHR, as returned by
vkGetPhysicalDeviceQueueFamilyProperties2 in
VkQueueFamilyVideoPropertiesKHR::videoCodecOperations.
| Video Std Header Name | Version |
|---|---|
|
1.0.0 |
| Video Capability | Requirement | Requirement Type1 |
|---|---|---|
|
- |
min |
|
4096 |
max |
|
4096 |
max |
|
(64,64) |
max |
|
- |
max |
|
- |
min |
|
0 |
min |
|
0 |
min |
|
|
min |
|
|
min |
- 1
-
The Requirement Type column specifies the requirement is either the minimum value all implementations must support, the maximum value all implementations must support, or the exact value all implementations must support. For bitmasks a minimum value is the least bits all implementations must set, but they may have additional bits set beyond this minimum.
43.15. AV1 Decode Operations
Video decode operations using an AV1 decode profile can be used to decode elementary video stream sequences compliant with the AV1 Specification.
|
Note
|
Refer to the Preamble for information on how the Khronos Intellectual Property Rights Policy relates to normative references to external materials not created by Khronos. |
This process is performed according to the video decode operation steps with the codec-specific semantics defined in section 7 of the AV1 Specification:
-
Syntax elements, derived values, and other parameters are applied from the following structures:
-
The
StdVideoAV1SequenceHeaderstructure stored in the bound video session parameters object specifying the active sequence header. -
The
StdVideoDecodeAV1PictureInfostructure specifying the AV1 picture information. -
The
StdVideoDecodeAV1ReferenceInfostructures specifying the AV1 reference information corresponding to the optional reconstructed picture and any active reference pictures.
-
-
The contents of the provided video bitstream buffer range are interpreted as defined in the AV1 Decode Bitstream Data Access section.
-
Picture data in the video picture resources corresponding to the used active reference pictures, decode output picture, and optional reconstructed picture is accessed as defined in the AV1 Decode Picture Data Access section.
-
The decision on reference picture setup is made according to the parameters specified in the AV1 picture information.
If the parameters and the bitstream adhere to the syntactic and semantic requirements defined in the corresponding sections of the AV1 Specification, as described above, and the DPB slots associated with the active reference pictures all refer to valid picture references, then the video decode operation will complete successfully. Otherwise, the video decode operation may complete unsuccessfully.
43.15.1. AV1 Decode Bitstream Data Access
The video bitstream buffer range should contain one or more frame OBUs, comprised of a frame header OBU and tile group OBU, that together represent an entire frame, as defined in sections 5.10, 5.9, and 5.11, and this data is interpreted as defined in sections 6.9, 6.8, and 6.10 of the AV1 Specification, respectively.
The offset specified in
VkVideoDecodeAV1PictureInfoKHR::frameHeaderOffset should
specify the starting offset of the frame header OBU of the frame.
|
Note
|
When the tiles of the frame are encoded into multiple tile groups, each
frame OBU has a separate frame header OBU but their content is expected to
match per the requirements of the AV1 Specification.
Accordingly, the offset specified in |
The offsets and sizes provided in
VkVideoDecodeAV1PictureInfoKHR::pTileOffsets and
VkVideoDecodeAV1PictureInfoKHR::pTileSizes, respectively,
should specify the starting offsets and sizes corresponding to each tile
within the video bitstream buffer range.
43.15.2. AV1 Decode Picture Data Access
Accesses to image data within a video picture resource happen at the
granularity indicated by
VkVideoCapabilitiesKHR::pictureAccessGranularity, as returned by
vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile.
Accordingly, the complete image subregion of a
decode output picture,
reference picture, or
reconstructed picture accessed by video coding
operations using an AV1 decode profile is defined as
the set of texels within the coordinate range:
-
([0,
endX), [0,endY))
Where:
-
endXequalscodedExtent.widthrounded up to the nearest integer multiple ofpictureAccessGranularity.widthand clamped to the width of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure; -
endY equals
codedExtent.heightrounded up to the nearest integer multiple ofpictureAccessGranularity.heightand clamped to the height of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure;
Where codedExtent is the member of the
VkVideoPictureResourceInfoKHR structure corresponding to the picture.
In case of video decode operations using an AV1 decode
profile, any access to a picture at the coordinates
(x,y), as defined by the AV1
Specification, is an access to the image subresource
referred to by the corresponding
VkVideoPictureResourceInfoKHR structure at the texel coordinates
(x,y).
43.15.3. AV1 Reference Names and Semantics
Individual reference frames used in the decoding process have different
semantics, as defined in section 6.10.24 of the AV1
Specification.
The AV1 semantics associated with a reference picture are indicated by the
corresponding enumeration constant defined in the Video Std enumeration type
StdVideoAV1ReferenceName:
-
STD_VIDEO_AV1_REFERENCE_NAME_INTRA_FRAMEidentifies the reference used for intra coding (INTRA_FRAME), as defined in sections 2 and 7.11.2 of the AV1 Specification. -
All other enumeration constants refer to backward or forward references used for inter coding, as defined in sections 2 and 7.11.3 of the AV1 Specification:
-
STD_VIDEO_AV1_REFERENCE_NAME_LAST_FRAMEidentifies theLAST_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_LAST2_FRAMEidentifies theLAST2_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_LAST3_FRAMEidentifies theLAST3_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_GOLDEN_FRAMEidentifies theGOLDEN_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_BWDREF_FRAMEidentifies theBWDREF_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_ALTREF2_FRAMEidentifies theALTREF2_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_ALTREF_FRAMEidentifies theALTREF_FRAMEreference
-
These enumeration constants are not directly used in any APIs but are used to indirectly index into certain Video Std and Vulkan API parameter arrays.
43.15.4. AV1 Decode Profile
A video profile supporting AV1 video decode operations is specified by
setting VkVideoProfileInfoKHR::videoCodecOperation to
VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHR and adding a
VkVideoDecodeAV1ProfileInfoKHR structure to the
VkVideoProfileInfoKHR::pNext chain.
The VkVideoDecodeAV1ProfileInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_av1
typedef struct VkVideoDecodeAV1ProfileInfoKHR {
VkStructureType sType;
const void* pNext;
StdVideoAV1Profile stdProfile;
VkBool32 filmGrainSupport;
} VkVideoDecodeAV1ProfileInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileis aStdVideoAV1Profilevalue specifying the AV1 codec profile, as defined in section A.2 of the AV1 Specification. -
filmGrainSupportspecifies whether AV1 film grain, as defined in section 7.8.3 of the AV1 Specification, can be used with the video profile. When this member isVK_TRUE, video session objects created against the video profile will be able to decode pictures that have film grain enabled.
|
Note
|
Enabling |
43.15.5. AV1 Decode Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for an AV1 decode profile, the
VkVideoCapabilitiesKHR::pNext chain must include a
VkVideoDecodeAV1CapabilitiesKHR structure that will be filled with the
profile-specific capabilities.
The VkVideoDecodeAV1CapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_decode_av1
typedef struct VkVideoDecodeAV1CapabilitiesKHR {
VkStructureType sType;
void* pNext;
StdVideoAV1Level maxLevel;
} VkVideoDecodeAV1CapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxLevelis aStdVideoAV1Levelvalue specifying the maximum AV1 level supported by the profile, as defined in section A.3 of the AV1 Specification.
43.15.6. AV1 Decode Parameter Sets
Video session parameters objects created with
the video codec operation VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHR
contain a single instance of the following parameter set:
- AV1 Sequence Header
-
Represented by
StdVideoAV1SequenceHeaderstructures and interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
the
StdVideoAV1ColorConfigstructure pointed to bypColorConfigis interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
all other members of
StdVideoAV1ColorConfigare interpreted as defined in section 6.4.2 of the AV1 Specification;
-
-
if
flags.timing_info_present_flagis set, then theStdVideoAV1TimingInfostructure pointed to bypTimingInfois interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoAV1TimingInfoare interpreted as defined in section 6.4.3 of the AV1 Specification;
-
-
all other members of
StdVideoAV1SequenceHeaderare interpreted as defined in section 6.4 of the AV1 Specification.
-
When a video session parameters object is
created with the codec operation
VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHR, the
VkVideoSessionParametersCreateInfoKHR::pNext chain must include
a VkVideoDecodeAV1SessionParametersCreateInfoKHR structure specifying
the contents of the object.
The VkVideoDecodeAV1SessionParametersCreateInfoKHR structure is
defined as:
// Provided by VK_KHR_video_decode_av1
typedef struct VkVideoDecodeAV1SessionParametersCreateInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoAV1SequenceHeader* pStdSequenceHeader;
} VkVideoDecodeAV1SessionParametersCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdSequenceHeaderis a pointer to aStdVideoAV1SequenceHeaderstructure describing the AV1 sequence header entry to store in the created object.
|
Note
|
As AV1 video session parameters objects will only ever contain a single AV1 sequence header, this has to be specified at object creation time and such video session parameters objects cannot be updated using the vkUpdateVideoSessionParametersKHR command. When a new AV1 sequence header is decoded from the input video bitstream the application needs to create a new video session parameters object to store it. |
Inline Parameter Sets
In case of video sessions created with the video codec
operation VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHR and with
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHR, the
application can also specify the active sequence header inline by including an instance of the
VkVideoDecodeAV1InlineSessionParametersInfoKHR structure in the
pNext chain of VkVideoDecodeInfoKHR.
The VkVideoDecodeAV1InlineSessionParametersInfoKHR structure is
defined as:
// Provided by VK_KHR_video_decode_av1 with VK_KHR_video_maintenance2
typedef struct VkVideoDecodeAV1InlineSessionParametersInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoAV1SequenceHeader* pStdSequenceHeader;
} VkVideoDecodeAV1InlineSessionParametersInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdSequenceHeaderisNULLor a pointer to an instance of theStdVideoAV1SequenceHeaderstructure describing the active AV1 sequence header.
If pStdSequenceHeader is not NULL, the issued video decode
operations will use the specified sequence header parameters instead of the
active sequence header being sourced from the bound video session parameters
object.
43.15.7. AV1 Decoding Parameters
The VkVideoDecodeAV1PictureInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_av1
typedef struct VkVideoDecodeAV1PictureInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeAV1PictureInfo* pStdPictureInfo;
int32_t referenceNameSlotIndices[VK_MAX_VIDEO_AV1_REFERENCES_PER_FRAME_KHR];
uint32_t frameHeaderOffset;
uint32_t tileCount;
const uint32_t* pTileOffsets;
const uint32_t* pTileSizes;
} VkVideoDecodeAV1PictureInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdPictureInfois a pointer to aStdVideoDecodeAV1PictureInfostructure specifying AV1 picture information. -
referenceNameSlotIndicesis an array of seven (VK_MAX_VIDEO_AV1_REFERENCES_PER_FRAME_KHR, which is equal to the Video Std definitionSTD_VIDEO_AV1_REFS_PER_FRAME) signed integer values specifying the index of the DPB slot or a negative integer value for each AV1 reference name used for inter coding. In particular, the DPB slot index for the AV1 reference nameframeis specified inreferenceNameSlotIndices[frame-STD_VIDEO_AV1_REFERENCE_NAME_LAST_FRAME]. -
frameHeaderOffsetis the byte offset of the AV1 frame header OBU, as defined in section 5.9 of the AV1 Specification, within the video bitstream buffer range specified in VkVideoDecodeInfoKHR. -
tileCountis the number of elements inpTileOffsetsandpTileSizes. -
pTileOffsetsis a pointer to an array oftileCountintegers specifying the byte offset of the tiles of the picture within the video bitstream buffer range specified in VkVideoDecodeInfoKHR. -
pTileSizesis a pointer to an array oftileCountintegers specifying the byte size of the tiles of the picture within the video bitstream buffer range specified in VkVideoDecodeInfoKHR.
This structure is specified in the pNext chain of the
VkVideoDecodeInfoKHR structure passed to vkCmdDecodeVideoKHR to
specify the codec-specific picture information for an AV1
decode operation.
- Decode Output Picture Information
-
When this structure is specified in the
pNextchain of the VkVideoDecodeInfoKHR structure passed to vkCmdDecodeVideoKHR, the information related to the decode output picture is defined as follows:-
The image subregion used is determined according to the AV1 Decode Picture Data Access section.
-
The decode output picture is associated with the AV1 picture information provided in
pStdPictureInfo.
-
- Std Picture Information
-
The members of the
StdVideoDecodeAV1PictureInfostructure pointed to bypStdPictureInfoare interpreted as follows:-
flags.reserved,reserved1, andreserved2are used only for padding purposes and are otherwise ignored; -
flags.apply_grainindicates that film grain is enabled for the decoded picture, as defined in section 6.8.20 of the AV1 Specification; -
OrderHint,OrderHints, andexpectedFrameIdare interpreted as defined in section 6.8.2 of the AV1 Specification; -
the
StdVideoAV1TileInfostructure pointed to bypTileInfois interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
pMiColStartsis a pointer to an array ofTileColsnumber of unsigned integers that corresponds toMiColStartsdefined in section 6.8.14 of the AV1 Specification; -
pMiRowStartsis a pointer to an array ofTileRowsnumber of unsigned integers that corresponds toMiRowStartsdefined in section 6.8.14 of the AV1 Specification; -
pWidthInSbsMinus1is a pointer to an array ofTileColsnumber of unsigned integers that corresponds towidth_in_sbs_minus_1defined in section 6.8.14 of the AV1 Specification; -
pHeightInSbsMinus1is a pointer to an array ofTileRowsnumber of unsigned integers that corresponds toheight_in_sbs_minus_1defined in section 6.8.14 of the AV1 Specification; -
all other members of
StdVideoAV1TileInfoare interpreted as defined in section 6.8.14 of the AV1 Specification;
-
-
the
StdVideoAV1Quantizationstructure pointed to bypQuantizationis interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoAV1Quantizationare interpreted as defined in section 6.8.11 of the AV1 Specification;
-
-
if
flags.segmentation_enabledis set, then theStdVideoAV1Segmentationstructure pointed to bypSegmentationis interpreted as follows:-
the elements of
FeatureEnabledare bitmasks where bit index j of element i corresponds toFeatureEnabled[i][j]as defined in section 5.9.14 of the AV1 Specification; -
FeatureDatais interpreted as defined in section 5.9.14 of the AV1 Specification;
-
-
the
StdVideoAV1LoopFilterstructure pointed to bypLoopFilteris interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
update_ref_deltais a bitmask where bit index i is interpreted as the value ofupdate_ref_deltacorresponding to element i ofloop_filter_ref_deltasas defined in section 6.8.10 of the AV1 Specification; -
update_mode_deltais a bitmask where bit index i is interpreted as the value ofupdate_mode_deltacorresponding to element i ofloop_filter_mode_deltasas defined in section 6.8.10 of the AV1 Specification; -
all other members of
StdVideoAV1LoopFilterare interpreted as defined in section 6.8.10 of the AV1 Specification;NoteIf the syntax elements corresponding to
loop_filter_ref_deltasandloop_filter_mode_deltasare not present or otherwise defined according to section 5.9.11 of the AV1 Specification, the application should specify the previous values, as defined in section 6.8.10 of the AV1 Specification.
-
-
if
flags.enable_cdefis set in the active sequence header, then the members of theStdVideoAV1CDEFstructure pointed to bypCDEFare interpreted as follows:-
cdef_y_sec_strengthandcdef_uv_sec_strengthare the bitstream values of the corresponding syntax elements defined in section 5.9.19 of the AV1 Specification; -
all other members of
StdVideoAV1CDEFare interpreted as defined in section 6.10.14 of the AV1 Specification;
-
-
the
StdVideoAV1LoopRestorationstructure pointed to bypLoopRestorationis interpreted as follows:-
LoopRestorationSize[plane] is interpreted as log2(size) - 5, wheresizeis the value ofLoopRestorationSize[plane] as defined in section 6.10.15 of the AV1 Specification. -
all other members of
StdVideoAV1LoopRestorationare defined as in section 6.10.15 of the AV1 Specification;
-
-
the members of the
StdVideoAV1GlobalMotionstructure provided inglobal_motionare interpreted as defined in section 7.10 of the AV1 Specification; -
if
flags.film_grain_params_presentis set in the active sequence header, then theStdVideoAV1FilmGrainstructure pointed to bypFilmGrainis interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoAV1FilmGrainare interpreted as defined in section 6.8.20 of the AV1 Specification;
-
-
all other members are interpreted as defined in section 6.8 of the AV1 Specification.
-
When film grain is enabled for the decoded frame,
the flags.update_grain and film_grain_params_ref_idx values
specified in StdVideoAV1FilmGrain are ignored by AV1 decode operations
and the load_grain_params function, as defined in section 6.8.20 of the
AV1 Specification, is not executed.
Instead, the application is responsible for specifying the effective film
grain parameters for the frame in StdVideoAV1FilmGrain.
When film grain is enabled for the decoded frame,
the application is required to specify a different decode output picture
resource in VkVideoDecodeInfoKHR::dstPictureResource compared to
the reconstructed picture specified in
VkVideoDecodeInfoKHR::pSetupReferenceSlot->pPictureResource even
if the implementation does not report support for
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR in
VkVideoDecodeCapabilitiesKHR::flags for the video decode
profile.
Reference picture setup is controlled by the value of
StdVideoDecodeAV1PictureInfo::refresh_frame_flags.
If it is not zero and a reconstructed
picture is specified, then the latter is used as the target of picture
reconstruction to activate the DPB slot
specified in pDecodeInfo->pSetupReferenceSlot->slotIndex.
If StdVideoDecodeAV1PictureInfo::refresh_frame_flags is zero, but
a reconstructed picture is specified,
then the corresponding picture reference associated with the DPB
slot is invalidated, as described in the DPB Slot
States section.
- Active Parameter Sets
-
The active sequence header is the AV1 sequence header stored in the bound video session parameters object , unless the bound video session was created with
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHRand the active sequence header is specified inline. .
The VkVideoDecodeAV1DpbSlotInfoKHR structure is defined as:
// Provided by VK_KHR_video_decode_av1
typedef struct VkVideoDecodeAV1DpbSlotInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoDecodeAV1ReferenceInfo* pStdReferenceInfo;
} VkVideoDecodeAV1DpbSlotInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdReferenceInfois a pointer to aStdVideoDecodeAV1ReferenceInfostructure specifying AV1 reference information.
This structure is specified in the pNext chain of
VkVideoDecodeInfoKHR::pSetupReferenceSlot, if not NULL, and
the pNext chain of the elements of
VkVideoDecodeInfoKHR::pReferenceSlots to specify the
codec-specific reference picture information for an AV1 decode
operation.
- Active Reference Picture Information
-
When this structure is specified in the
pNextchain of the elements of VkVideoDecodeInfoKHR::pReferenceSlots, one element is added to the list of active reference pictures used by the video decode operation for each element of VkVideoDecodeInfoKHR::pReferenceSlotsas follows:-
The image subregion used is determined according to the AV1 Decode Picture Data Access section.
-
The reference picture is associated with the DPB slot index specified in the
slotIndexmember of the corresponding element of VkVideoDecodeInfoKHR::pReferenceSlots. -
The reference picture is associated with the AV1 reference information provided in
pStdReferenceInfo.
-
- Reconstructed Picture Information
-
When this structure is specified in the
pNextchain of VkVideoDecodeInfoKHR::pSetupReferenceSlot, the information related to the reconstructed picture is defined as follows:-
The image subregion used is determined according to the AV1 Decode Picture Data Access section.
-
If reference picture setup is requested, then the reconstructed picture is used to activate the DPB slot with the index specified in VkVideoDecodeInfoKHR::
pSetupReferenceSlot->slotIndex. -
The reconstructed picture is associated with the AV1 reference information provided in
pStdReferenceInfo.
-
- Std Reference Information
-
The members of the
StdVideoDecodeAV1ReferenceInfostructure pointed to bypStdReferenceInfoare interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
flags.disable_frame_end_update_cdfis interpreted as defined in section 6.8.2 of the AV1 Specification; -
flags.segmentation_enabledis interpreted as defined in section 6.8.13 of the AV1 Specification; -
frame_typeis interpreted as defined in section 6.8.2 of the AV1 Specification;NoteThe
frame_typemember is defined with the typeuint8_t, but it takes the same values defined in theStdVideoAV1FrameTypeenumeration type asStdVideoDecodeAV1PictureInfo::frame_type. -
RefFrameSignBiasis a bitmask where bit index i corresponds toRefFrameSignBias[i]as defined in section 6.8.2 of the AV1 Specification; -
OrderHintis interpreted as defined in section 6.8.2 of the AV1 Specification; -
SavedOrderHintsis interpreted as defined in section 7.20 of the AV1 Specification.NoteWhen the AV1 reference information is provided for the reconstructed picture, certain parameters (e.g.
frame_type) are specified both in the AV1 picture information and in the AV1 reference information. This is necessary because unlike the AV1 picture information, which is only used for the purposes of the video decode operation in question, the AV1 reference information specified for the reconstructed picture may be associated with the activated DPB slot, meaning that some implementations may maintain it as part of the reference picture metadata corresponding to the video picture resource associated with the DPB slot. When the AV1 reference information is provided for an active reference picture, the specified parameters correspond to the parameters specified when the DPB slot was activated (set up) with the reference picture, as usual, in order to communicate these parameters for implementations that do not maintain any subset of these parameters as part of the DPB slot’s reference picture metadata.
-
43.15.8. AV1 Decode Requirements
This section describes the required AV1 decoding capabilities for physical
devices that have at least one queue family that supports the video codec
operation VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHR, as returned by
vkGetPhysicalDeviceQueueFamilyProperties2 in
VkQueueFamilyVideoPropertiesKHR::videoCodecOperations.
| Video Std Header Name | Version |
|---|---|
|
1.0.0 |
| Video Capability | Requirement | Requirement Type1 |
|---|---|---|
|
- |
min |
|
4096 |
max |
|
4096 |
max |
|
(64,64) |
max |
|
- |
max |
|
- |
min |
|
0 |
min |
|
0 |
min |
|
|
min |
|
|
min |
- 1
-
The Requirement Type column specifies the requirement is either the minimum value all implementations must support, the maximum value all implementations must support, or the exact value all implementations must support. For bitmasks a minimum value is the least bits all implementations must set, but they may have additional bits set beyond this minimum.
43.16. Video Encode Operations
Video encode operations consume an encode input picture and zero or more reference pictures, and produce compressed video data to a video bitstream buffer and an optional reconstructed picture.
|
Note
|
Such encode input pictures can be used as the output of video decode operations, with graphics or compute operations, or with Window System Integration APIs, depending on the capabilities of the implementation. |
Video encode operations may access the following resources in the
VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR stage:
-
The image subregions corresponding to the source encode input picture and active reference pictures with access
VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR. -
The destination video bitstream buffer range and the optional reconstructed picture with access
VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR. -
The image subregion corresponding to a quantization map used in the video encode operation with access
VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR.
The image subresource of each video picture resource accessed by the video encode operation is specified using a corresponding VkVideoPictureResourceInfoKHR structure. Each such image subresource must be in the appropriate image layout as follows:
-
If the image subresource is used in the video encode operation as an encode input picture, then it must be in the
VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHRlayout , unless theunifiedImageLayoutsVideofeature is enabled, in which case it may be in theVK_IMAGE_LAYOUT_GENERALlayout . -
If the image subresource is used in the video encode operation as a reconstructed picture or reference picture, then it must be in the
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHRlayout , unless theunifiedImageLayoutsVideofeature is enabled, in which case it may be in theVK_IMAGE_LAYOUT_GENERALlayout . -
If the image subresource is used in the video encode operation as a quantization map, then it must be in the
VK_IMAGE_LAYOUT_VIDEO_ENCODE_QUANTIZATION_MAP_KHRlayout , unless theunifiedImageLayoutsVideofeature is enabled, in which case it may be in theVK_IMAGE_LAYOUT_GENERALlayout .
A video encode operation may complete unsuccessfully. In this case the target video bitstream buffer will have undefined contents. Similarly, if reference picture setup is requested, the reconstructed-picture will also have undefined contents, and the activated DPB slot will have an invalid picture reference.
If a video encode operation completes successfully and the codec-specific parameters provided by the application adhere to the syntactic and semantic requirements defined in the corresponding video compression standard, then the target video bitstream buffer will contain compressed video data after the execution of the video encode operation according to the respective codec-specific semantics.
43.16.1. Codec-Specific Semantics
The following aspects of video encode operations are codec-specific:
-
The compressed video data written to the target video bitstream buffer range.
-
The construction and interpretation of the list of active reference pictures and the interpretation of the picture data referred to by the corresponding image subregions.
-
The construction and interpretation of information related to the encode input picture and the interpretation of the picture data referred to by the corresponding image subregion.
-
The decision on reference picture setup.
-
The construction and interpretation of information related to the optional reconstructed picture and the generation of picture data to the corresponding image subregion.
-
Certain aspects of rate control.
These codec-specific behaviors are defined for each video codec operation separately.
-
If the used video codec operation is
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the codec-specific aspects of the video encoding process are performed as defined in the H.264 Encode Operations section. -
If the used video codec operation is
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the codec-specific aspects of the video encoding process are performed as defined in the H.265 Encode Operations section. -
If the used video codec operation is
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR, then the codec-specific aspects of the video encoding process are performed as defined in the AV1 Encode Operations section.
Video Encode Parameter Overrides
Implementations supporting video encode operations for any particular video codec operation often support only a subset of the available encoding tools defined by the corresponding video compression standards. Accordingly, certain implementation-dependent limitations may apply to codec-specific parameters provided through the structures defined in the Video Std headers corresponding to the used video codec operation.
Exposing all of these restrictions on particular codec-specific parameter values or combinations thereof in the form of application-queryable capabilities is impractical, hence this specification allows implementations to override the value of any of the codec-specific parameters, unless otherwise specified, as long as all of the following conditions are met:
-
If the application-provided codec-specific parameters adhere to the syntactic and semantic requirements and rules defined by the used video compression standard, and thus would be usable to produce a video bitstream compliant with that standard, then the codec-specific parameters resulting from the process of implementation overrides must also adhere to the same requirements and rules, and any video bitstream produced using the overridden parameters must also be compliant.
-
The overridden codec-specific parameter values must not have an impact on the codec-independent behaviors defined for video encode operations.
-
The implementation must not override any codec-specific parameters specified to a command that may cause application-provided codec-specific parameters specified to subsequent commands to no longer adhere to the semantic requirements and rules defined by the used video compression standard, unless the implementation also overrides those parameters to adhere to any such requirements and rules.
-
The overridden codec-specific parameter values must not have an impact on the codec-specific picture data access semantics.
-
The overridden codec-specific parameter values may change the contents of the codec-specific bitstream elements produced by video encode operations or otherwise retrieved by the application (e.g. using the vkGetEncodedVideoSessionParametersKHR command) but must still adhere to the codec-specific semantics defined for that video codec operation, including, but not limited to, the number, type, and order of the encoded codec-specific bitstream elements.
Besides codec-specific parameter overrides performed for implementation-dependent reasons, applications can enable the implementation to apply additional optimizing overrides that may improve the efficiency or performance of video encoding operations. However, implementations must meet the conditions listed above even in case of such optimizing overrides.
|
Note
|
Unless the application opts in for optimizing overrides, implementations are not expected to override any of the codec-specific parameters, except when such overrides are necessary for the correct operation of video encoder implementation due to limitations to the available encoding tools on that implementation. |
43.16.2. Video Encode Operation Steps
Each video encode operation performs the following steps in the
VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR stage:
-
Reads the input picture data from the encode input picture;
-
Determine derived encoding quality parameters according to the codec-specific semantics and the current rate control state;
-
Compresses the input picture data according to the codec-specific semantics, applying any prediction data read from the active reference pictures and rate control restrictions in the process;
-
Writes the encoded bitstream data to the destination video bitstream buffer range;
-
Performs picture reconstruction of the encoded video data according to the codec-specific semantics, applying any prediction data read from the active reference pictures in the process, if a reconstructed picture is specified and reference picture setup is requested;
-
If reference picture setup is requested, the DPB slot index specified in the reconstructed picture information is activated with the reconstructed picture;
-
Writes the reconstructed picture data to the reconstructed picture, if one is specified, according to the codec-specific semantics.
When reconstructed picture information is provided, the specified DPB slot index is associated with the corresponding bound reference picture resource, indifferent of whether reference picture setup is requested.
43.16.3. Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR with
pVideoProfile->videoCodecOperation specifying an encode operation, 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;
uint32_t maxRateControlLayers;
uint64_t maxBitrate;
uint32_t maxQualityLevels;
VkExtent2D encodeInputPictureGranularity;
VkVideoEncodeFeedbackFlagsKHR supportedEncodeFeedbackFlags;
} VkVideoEncodeCapabilitiesKHR;
-
sTypeis a VkStructureType value identifying 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 indicating supported rate control modes. -
maxRateControlLayersindicates the maximum number of rate control layers supported. -
maxBitrateindicates the maximum supported bitrate. -
maxQualityLevelsindicates the number of discrete video encode quality levels supported. Implementations must support at least one quality level. -
encodeInputPictureGranularityindicates the granularity at which encode input picture data is encoded and may indicate a texel granularity up to the size of the largest supported codec-specific coding block. This capability does not impose any valid usage constraints on the application, however, depending on the contents of the encode input picture, it may have effects on the encoded bitstream, as described in more detail below. -
supportedEncodeFeedbackFlagsis a bitmask of VkVideoEncodeFeedbackFlagBitsKHR values specifying the supported flags for video encode feedback queries.
Implementations must include support for at least
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR and
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR in
supportedEncodeFeedbackFlags.
encodeInputPictureGranularity provides information about the way
encode input picture data is used as input to video
encode operations.
In particular, some implementations may not be able to limit the set of
texels used to encode the output video bitstream to the image subregion
specified in the VkVideoPictureResourceInfoKHR structure corresponding
to the encode input picture (i.e. to the resolution of the image data to
encode specified in its codedExtent member).
|
Note
|
For example, the application requests the coded extent to be 1920x1080, but
the implementation is only able to source the encode input picture data at
the granularity of the codec-specific coding block size which is 16x16
pixels (or as otherwise indicated in |
If codedExtent rounded up to the next integer multiple of
encodeInputPictureGranularity is greater than the extent of the image
subresource specified for the encode input picture,
then the texel values corresponding to texel coordinates outside of the
bounds of the image subresource may be undefined.
However, implementations should use well-defined default values for such
texels in order to maximize the encoding efficiency for the last coding
block row/column, and/or to ensure consistent encoding results across
repeated encoding of the same input content.
Nonetheless, the values used for such texels must not have an effect on
whether the video encode operation produces a compliant bitstream, and must
not have any other effects on the encoded picture data beyond what may
otherwise result from using these texel values as input to any compression
algorithm, as defined in the used video compression standard.
|
Note
|
While not required, it is generally a good practice for applications to make
sure that the image subresource used for the encode input picture has an
extent that is an integer multiple of the codec-specific coding block size
(or at least |
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_PRECEDING_EXTERNALLY_ENCODED_BYTES_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_CAPABILITY_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_DETECTION_BIT_KHR = 0x00000002,
// Provided by VK_KHR_video_encode_quantization_map
VK_VIDEO_ENCODE_CAPABILITY_QUANTIZATION_DELTA_MAP_BIT_KHR = 0x00000004,
// Provided by VK_KHR_video_encode_quantization_map
VK_VIDEO_ENCODE_CAPABILITY_EMPHASIS_MAP_BIT_KHR = 0x00000008,
} VkVideoEncodeCapabilityFlagBitsKHR;
-
VK_VIDEO_ENCODE_CAPABILITY_PRECEDING_EXTERNALLY_ENCODED_BYTES_BIT_KHRspecifies that the implementation supports the use of VkVideoEncodeInfoKHR::precedingExternallyEncodedBytes. -
VK_VIDEO_ENCODE_CAPABILITY_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_DETECTION_BIT_KHRspecifies that the implementation is able to detect and report when the destination video bitstream buffer range provided by the application is not sufficiently large to fit the encoded bitstream data produced by a video encode operation by reporting theVK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHRquery result status code.NoteSome implementations may not be able to reliably detect insufficient bitstream buffer range conditions in all situations. Such implementations will not report support for the
VK_VIDEO_ENCODE_CAPABILITY_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_DETECTION_BIT_KHRencode capability flag for the video profile, but may still report theVK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHRquery result status code in certain cases. Applications should always check for the specific query result status codeVK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHReven when this encode capability flag is not supported by the implementation for the video profile in question. However, applications must not assume that a different negative query result status code indicating an unsuccessful completion of a video encode operation is not the result of an insufficient bitstream buffer condition unless this encode capability flag is supported.
-
VK_VIDEO_ENCODE_CAPABILITY_QUANTIZATION_DELTA_MAP_BIT_KHRspecifies support for using quantization delta maps. -
VK_VIDEO_ENCODE_CAPABILITY_EMPHASIS_MAP_BIT_KHRspecifies support for using emphasis maps.
// Provided by VK_KHR_video_encode_queue
typedef VkFlags VkVideoEncodeCapabilityFlagsKHR;
VkVideoEncodeCapabilityFlagsKHR is a bitmask type for setting a mask
of zero or more VkVideoEncodeCapabilityFlagBitsKHR.
43.16.4. Video Encode Quality Levels
Implementations can support more than one video encode quality levels for a video encode profile, which control the number and type of implementation-specific encoding tools and algorithms utilized in the encoding process.
|
Note
|
Generally, using higher video encode quality levels may produce higher quality video streams at the cost of additional processing time. However, as the final quality of an encoded picture depends on the contents of the encode input picture, the contents of the active reference pictures, the codec-specific encode parameters, and the particular implementation-specific tools used corresponding to the individual video encode quality levels, there are no guarantees that using a higher video encode quality level will always produce a higher quality encoded picture for any given set of inputs. |
To query properties for a specific video encode quality level supported by a video encode profile, call:
// Provided by VK_KHR_video_encode_queue
VkResult vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR* pQualityLevelInfo,
VkVideoEncodeQualityLevelPropertiesKHR* pQualityLevelProperties);
-
physicalDeviceis the physical device to query the video encode quality level properties for. -
pQualityLevelInfois a pointer to a VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR structure specifying the video encode profile and quality level to query properties for. -
pQualityLevelPropertiesis a pointer to a VkVideoEncodeQualityLevelPropertiesKHR structure in which the properties are returned.
The VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR structure is
defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR {
VkStructureType sType;
const void* pNext;
const VkVideoProfileInfoKHR* pVideoProfile;
uint32_t qualityLevel;
} VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pVideoProfileis a pointer to a VkVideoProfileInfoKHR structure specifying the video profile to query the video encode quality level properties for. -
qualityLevelis the video encode quality level to query properties for.
The VkVideoEncodeQualityLevelPropertiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeQualityLevelPropertiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeRateControlModeFlagBitsKHR preferredRateControlMode;
uint32_t preferredRateControlLayerCount;
} VkVideoEncodeQualityLevelPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
preferredRateControlModeis a VkVideoEncodeRateControlModeFlagBitsKHR value indicating the preferred rate control mode to use with the video encode quality level. -
preferredRateControlLayerCountindicates the preferred number of rate control layers to use with the video encode quality level.
The VkVideoEncodeQualityLevelInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeQualityLevelInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t qualityLevel;
} VkVideoEncodeQualityLevelInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
qualityLevelis the used video encode quality level.
This structure can be specified in the following places:
-
In the
pNextchain of VkVideoSessionParametersCreateInfoKHR to specify the video encode quality level to use for a video session parameters object created for a video encode session. If no instance of this structure is included in thepNextchain of VkVideoSessionParametersCreateInfoKHR, then the video session parameters object is created with a video encode quality level of zero. -
In the
pNextchain of VkVideoCodingControlInfoKHR to change the video encode quality level state of the bound video session.
43.16.5. Retrieving Encoded Session Parameters
Any codec-specific parameters stored in video session parameters objects may need to be separately encoded and included in the final video bitstream data, depending on the used video compression standard. In such cases the application must call the vkGetEncodedVideoSessionParametersKHR command to retrieve the encoded parameter data from the used video session parameters object in order to be able to produce a compliant video bitstream.
|
Note
|
This is needed because implementations may have changed some of the codec-specific parameters stored in the video session parameters object, as defined in the Video Encode Parameter Overrides section. In addition, the vkGetEncodedVideoSessionParametersKHR command enables the application to retrieve the encoded parameter data without having to encode these codec-specific parameters manually. |
Encoded parameter data can be retrieved from a video session parameters object created with a video encode operation using the command:
// Provided by VK_KHR_video_encode_queue
VkResult vkGetEncodedVideoSessionParametersKHR(
VkDevice device,
const VkVideoEncodeSessionParametersGetInfoKHR* pVideoSessionParametersInfo,
VkVideoEncodeSessionParametersFeedbackInfoKHR* pFeedbackInfo,
size_t* pDataSize,
void* pData);
-
deviceis the logical device that owns the video session parameters object. -
pVideoSessionParametersInfois a pointer to a VkVideoEncodeSessionParametersGetInfoKHR structure specifying the parameters of the encoded parameter data to retrieve. -
pFeedbackInfois eitherNULLor a pointer to a VkVideoEncodeSessionParametersFeedbackInfoKHR structure in which feedback about the requested parameter data is returned. -
pDataSizeis a pointer to asize_tvalue related to the amount of encode parameter data returned, as described below. -
pDatais eitherNULLor a pointer to a buffer to write the encoded parameter data to.
If pData is NULL, then the size of the encoded parameter data, in
bytes, that can be retrieved is returned in pDataSize.
Otherwise, pDataSize must point to a variable set by the application
to the size of the buffer, in bytes, pointed to by pData, and on
return the variable is overwritten with the number of bytes actually written
to pData.
If pDataSize is less than the size of the encoded parameter data that
can be retrieved, then no data will be written to pData, zero will be
written to pDataSize, and VK_INCOMPLETE will be returned instead
of VK_SUCCESS, to indicate that no encoded parameter data was
returned.
If pFeedbackInfo is not NULL then the members of the
VkVideoEncodeSessionParametersFeedbackInfoKHR structure and any
additional structures included in its pNext chain that are applicable
to the video session parameters object specified in
pVideoSessionParametersInfo->videoSessionParameters will be filled
with feedback about the requested parameter data on all successful calls to
this command.
|
Note
|
This includes the cases when |
|
Note
|
This query does not behave consistently with the behavior described in Opaque Binary Data Results, for historical reasons. If the amount of data available is larger than the passed |
The VkVideoEncodeSessionParametersGetInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeSessionParametersGetInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoSessionParametersKHR videoSessionParameters;
} VkVideoEncodeSessionParametersGetInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoSessionParametersis the VkVideoSessionParametersKHR object to retrieve encoded parameter data from.
Depending on the used video encode operation, additional codec-specific
structures may need to be included in the pNext chain of this
structure to identify the specific video session parameters to retrieve
encoded parameter data for, as described in the corresponding sections.
The VkVideoEncodeSessionParametersFeedbackInfoKHR structure is defined
as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeSessionParametersFeedbackInfoKHR {
VkStructureType sType;
void* pNext;
VkBool32 hasOverrides;
} VkVideoEncodeSessionParametersFeedbackInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
hasOverridesindicates whether any of the requested parameter data were overridden by the implementation.
Depending on the used video encode operation, additional codec-specific
structures can be included in the pNext chain of this structure to
capture codec-specific feedback information about the requested parameter
data, as described in the corresponding sections.
43.16.6. Video Encode Commands
To launch video encode operations, call:
// Provided by VK_KHR_video_encode_queue
void vkCmdEncodeVideoKHR(
VkCommandBuffer commandBuffer,
const VkVideoEncodeInfoKHR* pEncodeInfo);
-
commandBufferis the command buffer in which to record the command. -
pEncodeInfois a pointer to a VkVideoEncodeInfoKHR structure specifying the parameters of the video encode operations.
Each call issues one or more video encode operations.
The implicit parameter opCount corresponds to the number of video
encode operations issued by the command.
After calling this command, the
active query index of each
active query is incremented by opCount.
Currently each call to this command results in the issue of a single video encode operation.
If the bound video session was created with
VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR and the pNext
chain of pEncodeInfo includes a VkVideoInlineQueryInfoKHR
structure with its queryPool member specifying a valid
VkQueryPool handle, then this command will execute a query for each
video encode operation issued by it.
- Active Reference Picture Information
-
The list of active reference pictures used by a video encode operation is a list of image subregions used as the source of reference picture data and related parameters, and is derived from the VkVideoReferenceSlotInfoKHR structures provided as the elements of the
pEncodeInfo->pReferenceSlotsarray. For each element ofpEncodeInfo->pReferenceSlots, one or more elements are added to the active reference picture list, as defined by the codec-specific semantics. Each element of this list contains the following information:-
The image subregion within the image subresource referred to by the video picture resource used as the reference picture.
-
The DPB slot index the reference picture is associated with.
-
The codec-specific reference information related to the reference picture.
-
- Reconstructed Picture Information
-
Information related to the optional reconstructed picture used by a video encode operation is derived from the VkVideoReferenceSlotInfoKHR structure pointed to by
pEncodeInfo->pSetupReferenceSlot, if notNULL, as defined by the codec-specific semantics, and consists of the following:-
The image subregion within the image subresource referred to by the video picture resource used as the reconstructed picture.
-
The DPB slot index to use for picture reconstruction.
-
The codec-specific reference information related to the reconstructed picture.
-
Specifying a valid VkVideoReferenceSlotInfoKHR structure in
pEncodeInfo->pSetupReferenceSlot is always required, unless the video
session was created with
VkVideoSessionCreateInfoKHR::maxDpbSlots equal to zero.
However, the DPB slot identified by
pEncodeInfo->pSetupReferenceSlot->slotIndex is only
activated with the reconstructed
picture specified in
pEncodeInfo->pSetupReferenceSlot->pPictureResource if reference
picture setup is requested according to the
codec-specific semantics.
If reconstructed picture information is specified, but reference picture setup is not requested, according to the codec-specific semantics, the contents of the video picture resource corresponding to the reconstructed picture will be undefined after the video encode operation.
|
Note
|
Some implementations may always output the reconstructed picture or use it as temporary storage during the video encode operation even when the reconstructed picture is not marked for future reference. |
- Encode Input Picture Information
-
Information related to the encode input picture used by a video encode operation is derived from
pEncodeInfo->srcPictureResourceand any codec-specific parameters provided in thepEncodeInfo->pNextchain, as defined by the codec-specific semantics, and consists of the following:-
The image subregion within the image subresource referred to by the video picture resource used as the encode input picture.
-
The codec-specific picture information related to the encoded picture.
-
Several limiting values are defined below that are referenced by the relevant valid usage statements of this command.
-
Let
uint32_t activeReferencePictureCountbe the size of the list of active reference pictures used by the video encode operation. Unless otherwise defined,activeReferencePictureCountis set to the value ofpEncodeInfo->referenceSlotCount. -
Let
VkOffset2D codedOffsetGranularitybe the minimum alignment requirement for the coded offset of video picture resources. Unless otherwise defined, the value of thexandymembers ofcodedOffsetGranularityare0. -
Let
uint32_t dpbFrameUseCount[]be an array of sizemaxDpbSlots, wheremaxDpbSlotsis the VkVideoSessionCreateInfoKHR::maxDpbSlotsthe bound video session was created with, with each element indicating the number of times a frame associated with the corresponding DPB slot index is referred to by the video coding operation. Let the initial value of each element of the array be0.-
If
pEncodeInfo->pSetupReferenceSlotis notNULL, thendpbFrameUseCount[i]is incremented by one, whereiequalspEncodeInfo->pSetupReferenceSlot->slotIndex. -
For each element of
pEncodeInfo->pReferenceSlots,dpbFrameUseCount[i]is incremented by one, whereiequals theslotIndexmember of the corresponding element.
-
-
If there is a bound video session parameters object created with
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR, then letVkExtent2D quantizationMapTexelSizebe the quantization map texel size the bound video session parameters object was created with. -
Let
VkExtent2D maxCodingBlockSizebe the maximum codec-specific coding block size that may be used by the video encode operation.-
If the bound video session object was created with an H.264 encode profile, then let
maxCodingBlockSizebe equal to the size of an H.264 macroblock, i.e.{16,16}. -
If the bound video session object was created with an H.265 encode profile, then let
maxCodingBlockSizebe equal to the maximum H.265 coding block size that may be used by the video encode operation derived as the maximum of the CTB sizes corresponding to the VkVideoEncodeH265CtbSizeFlagBitsKHR bits set in VkVideoEncodeH265CapabilitiesKHR::ctbSizes, as returned by vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the bound video session was created with. -
If the bound video session object was created with an AV1 encode profile, then let
maxCodingBlockSizebe equal to the maximum AV1 superblock size that may be used by the video encode operation derived as the maximum of the superblock sizes corresponding to the VkVideoEncodeAV1SuperblockSizeFlagBitsKHR bits set in VkVideoEncodeAV1CapabilitiesKHR::superblockSizes, as returned by vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the bound video session was created with. -
Otherwise,
maxCodingBlockSizeis undefined.
-
-
If
maxCodingBlockSizeis defined, then letVkExtent2D minCodingBlockExtentbe the coded extent of the encode input picture expressed in terms of codec-specific coding blocks, assuming the maximum size of such coding blocks, as defined bymaxCodingBlockSize, calculated from the value of thecodedExtentmember ofpEncodeInfo->srcPictureResourceas follows:-
minCodingBlockExtent.width= (codedExtent.width
maxCodingBlockSize.width- 1) /maxCodingBlockSize.width -
minCodingBlockExtent.height= (codedExtent.height
maxCodingBlockSize.height- 1) /maxCodingBlockSize.height
-
-
If the bound video session object was created with an H.264 encode profile, then:
-
Let
StdVideoH264PictureType h264PictureTypebe the picture type of the encoded picture set to the value ofpStdPictureInfo->primary_pic_typespecified in the VkVideoEncodeH264PictureInfoKHR structure included in thepEncodeInfo->pNextchain. -
Let
StdVideoH264PictureType h264L0PictureTypes[]andStdVideoH264PictureType h264L1PictureTypes[]be the picture types of the reference pictures in the L0 and L1 reference lists, respectively. IfpStdPictureInfo->pRefListsspecified in the VkVideoEncodeH264PictureInfoKHR structure included in thepEncodeInfo->pNextchain is notNULL, then for each reference index specified in the elements of thepStdPictureInfo->pRefLists->RefPicList0andpStdPictureInfo->pRefLists->RefPicList1arrays, if the reference index is notSTD_VIDEO_H264_NO_REFERENCE_PICTURE,pStdReferenceInfo->primary_pic_typeis added toh264L0PictureTypesorh264L1PictureTypes, respectively, wherepStdReferenceInfois the member of the VkVideoEncodeH264DpbSlotInfoKHR structure included in thepNextchain of the element ofpEncodeInfo->pReferenceSlotsfor whichslotIndexequals the reference index in question.
-
-
If the bound video session was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHRand with the intra refresh modeVK_VIDEO_ENCODE_INTRA_REFRESH_MODE_PER_PICTURE_PARTITION_BIT_KHR,pEncodeInfo->flagsincludesVK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHR, and thepNextchain ofpEncodeInfoincludes a VkVideoEncodeIntraRefreshInfoKHR structure, then letuint32_t intraRefreshH264SliceIndexbe the intra refresh index specified in VkVideoEncodeIntraRefreshInfoKHR::intraRefreshIndex. OtherwiseintraRefreshH264SliceIndexis not defined. -
If the bound video session object was created with an H.265 encode profile, then:
-
Let
StdVideoH265PictureType h265PictureTypebe the picture type of the encoded picture set to the value ofpStdPictureInfo->pic_typespecified in the VkVideoEncodeH265PictureInfoKHR structure included in thepEncodeInfo->pNextchain. -
Let
StdVideoH265PictureType h265L0PictureTypes[]andStdVideoH265PictureType h265L1PictureTypes[]be the picture types of the reference pictures in the L0 and L1 reference lists, respectively. IfpStdPictureInfo->pRefListsspecified in the VkVideoEncodeH265PictureInfoKHR structure included in thepEncodeInfo->pNextchain is notNULL, then for each reference index specified in the elements of thepStdPictureInfo->pRefLists->RefPicList0andpStdPictureInfo->pRefLists->RefPicList1arrays, if the reference index is notSTD_VIDEO_H265_NO_REFERENCE_PICTURE,pStdReferenceInfo->pic_typeis added toh265L0PictureTypesorh265L1PictureTypes, respectively, wherepStdReferenceInfois the member of the VkVideoEncodeH265DpbSlotInfoKHR structure included in thepNextchain of the element ofpEncodeInfo->pReferenceSlotsfor whichslotIndexequals the reference index in question.
-
-
If the bound video session was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHRand with the intra refresh modeVK_VIDEO_ENCODE_INTRA_REFRESH_MODE_PER_PICTURE_PARTITION_BIT_KHR,pEncodeInfo->flagsincludesVK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHR, and thepNextchain ofpEncodeInfoincludes a VkVideoEncodeIntraRefreshInfoKHR structure, then letuint32_t intraRefreshH265SliceSegmentIndexbe the intra refresh index specified in VkVideoEncodeIntraRefreshInfoKHR::intraRefreshIndex. OtherwiseintraRefreshH265SliceSegmentIndexis not defined. -
If the bound video session object was created with an AV1 encode profile, then:
-
If the
primaryReferenceCdfOnlymember of the VkVideoEncodeAV1PictureInfoKHR structure included in thepEncodeInfo->pNextchain is set toVK_TRUE, then letint32_t cdfOnlyReferenceIndexbe the value of VkVideoEncodeAV1PictureInfoKHR::pStdPictureInfo->primary_ref_frame. -
Otherwise let
int32_t cdfOnlyReferenceIndexbe-1.
-
The VkVideoEncodeInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeFlagsKHR flags;
VkBuffer dstBuffer;
VkDeviceSize dstBufferOffset;
VkDeviceSize dstBufferRange;
VkVideoPictureResourceInfoKHR srcPictureResource;
const VkVideoReferenceSlotInfoKHR* pSetupReferenceSlot;
uint32_t referenceSlotCount;
const VkVideoReferenceSlotInfoKHR* pReferenceSlots;
uint32_t precedingExternallyEncodedBytes;
} VkVideoEncodeInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextis a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeFlagBitsKHR indicating video encode command flags. -
dstBufferis the destination video bitstream buffer to write the encoded bitstream to. -
dstBufferOffsetis the starting offset in bytes from the start ofdstBufferto write the encoded bitstream to. -
dstBufferRangeis the maximum bitstream size in bytes that can be written todstBuffer, starting fromdstBufferOffset. -
srcPictureResourceis the video picture resource to use as the encode input picture. -
pSetupReferenceSlotisNULLor a pointer to a VkVideoReferenceSlotInfoKHR structure specifying the reconstructed picture information. -
referenceSlotCountis the number of elements in thepReferenceSlotsarray. -
pReferenceSlotsisNULLor a pointer to an array of VkVideoReferenceSlotInfoKHR structures describing the DPB slots and corresponding reference picture resources to use in this video encode operation (the set of active reference pictures). -
precedingExternallyEncodedBytesis the number of bytes externally encoded by the application to the video bitstream and is used to update the internal state of the implementation’s rate control algorithm to account for the bitrate budget consumed by these externally encoded bytes.
Bits which can be set in VkVideoEncodeInfoKHR::flags,
specifying video encode flags, are:
// Provided by VK_KHR_video_encode_quantization_map
typedef enum VkVideoEncodeFlagBitsKHR {
// Provided by VK_KHR_video_encode_intra_refresh
VK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHR = 0x00000004,
// Provided by VK_KHR_video_encode_quantization_map
VK_VIDEO_ENCODE_WITH_QUANTIZATION_DELTA_MAP_BIT_KHR = 0x00000001,
// Provided by VK_KHR_video_encode_quantization_map
VK_VIDEO_ENCODE_WITH_EMPHASIS_MAP_BIT_KHR = 0x00000002,
} VkVideoEncodeFlagBitsKHR;
-
VK_VIDEO_ENCODE_WITH_QUANTIZATION_DELTA_MAP_BIT_KHRspecifies the use of a quantization delta map in the issued video encode operations. -
VK_VIDEO_ENCODE_WITH_EMPHASIS_MAP_BIT_KHRspecifies the use of an emphasis map in the issued video encode operations. -
VK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHRenables intra refresh for the encoded picture.
// Provided by VK_KHR_video_encode_queue
typedef VkFlags VkVideoEncodeFlagsKHR;
VkVideoEncodeFlagsKHR is a bitmask type for setting a mask of zero or more VkVideoEncodeFlagBitsKHR.
43.17. Video Encode Intra Refresh
Encoding a picture with intra refresh enables encoding a subset of the coding blocks produced for an encode input picture with intra prediction.
|
Note
|
This enables the application to perform a decoder refresh through a series of pictures instead of a single picture. In conjunction with restricting reference picture prediction, this enables avoiding error propagation across refresh cycles without introducing sudden spikes in the bitrate. This is achieved by amortizing the bitstream consumption of the refresh across a series of subsequent pictures. |
An intra refresh cycle is a series of encode operations using intra refresh that contain at least one encode operation for any subregion of the coded extent that encoded the subregion with intra prediction.
The intra refresh cycle duration is the number of encode operations in an intra refresh cycle.
For the purposes of performing an intra refresh cycle, the coded extent is divided into a set of intra refresh regions. The number of intra refresh regions for a given intra refresh cycle equals the intra refresh cycle duration.
Implementations may partition the coded extent into intra refresh regions in an implementation-specific manner, unless otherwise specified. The following is true for the resulting set of intra refresh regions:
-
Each intra refresh region encompasses entire coding blocks.
-
Any intra refresh region may be non-rectangular.
-
Some intra refresh regions may be empty.
-
The union of intra refresh regions of a given partitioning covers the entire coded extent.
NoteWhile intra refresh regions are generally disjoint, there may be overlap between distinct intra refresh regions of a given partitioning in order to accommodate for any filtering that may need to be applied across coding blocks of neighboring intra refresh regions.
An intra refresh cycle is performed by encoding subsequent pictures with intra refresh, each encoding subsequent intra refresh regions using intra prediction. This inherently defines an ordering of encode operations within an intra refresh cycle. Therefore each encode operation in an intra refresh cycle has an intra refresh index that provides the following information:
-
The intra refresh index of an encode operation using intra refresh is the ordinal index of the intra refresh region being encoded using intra prediction.
-
The intra refresh index of an encode operation using intra refresh inherently tells the number of intra refresh regions already refreshed by previous encode operations of the intra refresh cycle.
|
Note
|
For AV1 encoding, applications should consider setting the
|
An intra refresh region of a picture encoded using intra refresh is considered clean once the encode operation within the intra refresh cycle that encoded that intra refresh region using intra prediction is complete. Otherwise, the intra refresh region is considered dirty.
The number of dirty intra refresh regions of a picture encoded using intra refresh is always one less than the difference between the intra refresh cycle duration and the intra refresh index used to encode that picture.
|
Note
|
As the intra refresh cycle progresses, each subsequent picture encoded with intra refresh will have fewer dirty intra refresh regions. Consequently, the final encode operation of the intra refresh cycle will produce an encoded picture with no more dirty intra refresh regions. |
43.17.1. Intra Refresh Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR with
pVideoProfile->videoCodecOperation specifying an encode operation, the
VkVideoEncodeIntraRefreshCapabilitiesKHR structure can be included in
the pNext chain of the VkVideoCapabilitiesKHR structure to
retrieve capabilities specific to video encode intra refresh.
The VkVideoEncodeIntraRefreshCapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_intra_refresh
typedef struct VkVideoEncodeIntraRefreshCapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeIntraRefreshModeFlagsKHR intraRefreshModes;
uint32_t maxIntraRefreshCycleDuration;
uint32_t maxIntraRefreshActiveReferencePictures;
VkBool32 partitionIndependentIntraRefreshRegions;
VkBool32 nonRectangularIntraRefreshRegions;
} VkVideoEncodeIntraRefreshCapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
intraRefreshModesis a bitmask of VkVideoEncodeIntraRefreshModeFlagBitsKHR values indicating the set of supported intra refresh modes. -
maxIntraRefreshCycleDurationspecifies the maximum supported intra refresh cycle duration. -
maxIntraRefreshActiveReferencePicturesis the maximum number of active reference pictures when encoding pictures with intra refresh enabled. This capability indicates additional restrictions beyond the maximum number of active reference pictures supported by the video profile, as reported in VkVideoCapabilitiesKHR::maxActiveReferencePicturesand the maximum requested at video session creation time in VkVideoSessionCreateInfoKHR::maxActiveReferencePictures. -
partitionIndependentIntraRefreshRegionsspecifies whether the implementation supports intra refresh regions that are independent of the picture partitioning used during encoding. If it isVK_TRUE, then pictures can be encoded with multiple picture partitions, independent of the used intra refresh mode. Otherwise, pictures cannot be encoded with multiple picture partitions with any intra refresh mode other thanVK_VIDEO_ENCODE_INTRA_REFRESH_MODE_PER_PICTURE_PARTITION_BIT_KHR.NoteThis capability is only indicative for AV1 encode profiles and does not impose any restrictions on the application as implementations may change the application requested picture partitioning according to implementation-specific restrictions.
-
nonRectangularIntraRefreshRegionsspecifies whether the implementation supports non-rectangular intra refresh regions.NoteIf this capability is not supported, then using per picture partition intra refresh may impose additional restrictions on the number of picture partitions a picture can be encoded with.
43.17.2. Intra Refresh Modes
The intra refresh modes are defined with the following enums:
// Provided by VK_KHR_video_encode_intra_refresh
typedef enum VkVideoEncodeIntraRefreshModeFlagBitsKHR {
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_NONE_KHR = 0,
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_PER_PICTURE_PARTITION_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_BLOCK_BASED_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_BLOCK_ROW_BASED_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_BLOCK_COLUMN_BASED_BIT_KHR = 0x00000008,
} VkVideoEncodeIntraRefreshModeFlagBitsKHR;
-
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_NONE_KHRspecifies that intra refresh must not be used. -
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_PER_PICTURE_PARTITION_BIT_KHRspecifies the use of per picture partition intra refresh. In this mode each intra refresh region i corresponds to the encoded picture partition i. -
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_BLOCK_BASED_BIT_KHRspecifies the use of any block-based intra refresh. In this mode each intra refresh region encompasses a set of coding blocks, independent of encoded picture partitions but without any additional guarantees on the granularity at which the picture is split into intra refresh regions. When using this mode, the set of coding blocks comprising the intra refresh regions and the direction of intra refresh are implementation-defined. -
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_BLOCK_ROW_BASED_BIT_KHRspecifies the use of block-row-based intra refresh. This mode is a block-based intra refresh mode where each intra refresh region encompasses a set of coding block rows. -
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_BLOCK_COLUMN_BASED_BIT_KHRspecifies the use of block-column-based intra refresh. This mode is a block-based intra refresh mode where each intra refresh region encompasses a set of coding block columns.
Implementations reporting support for
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_BLOCK_ROW_BASED_BIT_KHR and/or
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_BLOCK_COLUMN_BASED_BIT_KHR in
VkVideoEncodeIntraRefreshCapabilitiesKHR::intraRefreshModes are
also required to report support for
VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_BLOCK_BASED_BIT_KHR.
|
Note
|
Both block-row-based and block-column-based intra refresh are just specific
types of block-based intra refresh that provide additional guarantees about
the granularity at which the picture is split into intra refresh regions,
therefore implementations supporting either block-row-based or
block-column-based intra refresh inherently support block-based intra
refresh.
Applications can use
|
// Provided by VK_KHR_video_encode_intra_refresh
typedef VkFlags VkVideoEncodeIntraRefreshModeFlagsKHR;
VkVideoEncodeIntraRefreshModeFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoEncodeIntraRefreshModeFlagBitsKHR.
The used intra refresh mode is selected at video
session creation time by including an instance of the
VkVideoEncodeSessionIntraRefreshCreateInfoKHR structure in the
pNext chain of the VkVideoSessionCreateInfoKHR structure and
specifying one of the supported intra refresh modes, as returned in
VkVideoEncodeIntraRefreshCapabilitiesKHR::intraRefreshModes, in
its intraRefreshMode member.
The VkVideoEncodeSessionIntraRefreshCreateInfoKHR structure is defined
as:
// Provided by VK_KHR_video_encode_intra_refresh
typedef struct VkVideoEncodeSessionIntraRefreshCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeIntraRefreshModeFlagBitsKHR intraRefreshMode;
} VkVideoEncodeSessionIntraRefreshCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
intraRefreshModeis a VkVideoEncodeIntraRefreshModeFlagBitsKHR specifying the used intra refresh mode.
43.17.3. Encoding Pictures with Intra Refresh
If the video encode operation is issued with the
VK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHR flag, the picture will be
encoded with intra refresh, resulting in the intra refresh region identified by the specified
intra refresh index to be encoded with intra
prediction.
Intra refresh parameters are specified to video encode operations by
including an instance of the VkVideoEncodeIntraRefreshInfoKHR
structure in the pNext chain of the VkVideoEncodeInfoKHR
structure specified to the video encode command.
The VkVideoEncodeIntraRefreshInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_intra_refresh
typedef struct VkVideoEncodeIntraRefreshInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t intraRefreshCycleDuration;
uint32_t intraRefreshIndex;
} VkVideoEncodeIntraRefreshInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
intraRefreshCycleDurationis the used intra refresh cycle duration. -
intraRefreshIndexis the intra refresh index of the encoded picture.
43.17.4. Referencing Pictures Encoded with Intra Refresh
When using pictures encoded with intra refresh as an active reference picture in a video encode operation, applications may want to limit the set of intra refresh regions of the reference picture that are used to predict samples of the encoded picture to exclude dirty intra refresh regions of the reference picture in question.
|
Note
|
This enables the application to avoid error propagation from previous refresh cycles by only using already refreshed (clean) intra refresh regions for sample prediction. |
In order to limit the set of intra refresh
regions of an active reference picture used
for sample prediction, the application must specify an instance of the
VkVideoReferenceIntraRefreshInfoKHR structure in the pNext chain
of the VkVideoReferenceSlotInfoKHR structure specifying the active
reference picture in question.
The VkVideoReferenceIntraRefreshInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_intra_refresh
typedef struct VkVideoReferenceIntraRefreshInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t dirtyIntraRefreshRegions;
} VkVideoReferenceIntraRefreshInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dirtyIntraRefreshRegionsis the number of dirty intra refresh regions in the reference picture.
In order to use active reference pictures with a non-zero number of dirty intra refresh regions and therefore limit sample prediction to clean intra refresh regions, the currently encoded picture must be encoded with intra refresh enabled.
When limiting sample prediction to clean intra refresh regions of a reference picture with a non-zero number of dirty intra refresh regions, the number of dirty intra refresh regions must equal the used intra refresh cycle duration minus the intra refresh index of the encoded picture.
|
Note
|
This has the practical effect that pictures can only reference the previous picture within the intra refresh cycle or pictures outside of the intra refresh cycle. |
Given an active reference picture with
dirtyIntraRefreshRegions number of
dirty intra refresh regions and an
intra refresh cycle duration of
intraRefreshCycleDuration, the samples within intra refresh region
index i of the encoded picture are allowed to be predicted by samples
within intra refresh region index j of the active reference picture in
question if and only if any of the following conditions are true:
-
The picture is encoded with
VK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHRand i is greater than theintraRefreshIndexof the encoded picture. -
The picture is encoded with
VK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHR, i is less than theintraRefreshIndexof the encoded picture, and j is less than the difference ofintraRefreshCycleDurationanddirtyIntraRefreshRegions.
|
Note
|
Even if a particular intra refresh region is allowed to be used for sample prediction, as defined above, implementations may not always support sample prediction from the given intra refresh region. Some implementations may only support sample prediction from a single set of intra refresh regions across the entire set of active reference pictures. For example, when encoding a picture with two active reference pictures, one with no dirty intra refresh regions, and one with some dirty intra refresh regions, sample prediction may not happen from those intra refresh regions of the first active reference picture which are marked dirty in the second active reference picture. Other implementations may have the additional restriction that the set of intra refresh regions to use for sample prediction across the entire set of active reference pictures is implied from the intra refresh index of the currently encoded picture, further restricting the set of intra refresh regions that such implementations can use for sample prediction. For example, when encoding a picture with intra refresh using an active reference picture that has no dirty intra refresh regions, sample prediction may not happen from intra refresh regions of the active reference picture which have an index greater than or equal to the currently encoded picture’s intra refresh index, even though those intra refresh regions were not marked as dirty. None of these implementation limitations will have an effect on application behavior from the perspective of correctness, but they may negatively impact the encoding efficiency. |
43.18. Video Encode Rate Control
The size of the encoded bitstream data produced by video encode operations is a function of the following set of constraints:
-
The capabilities of the compression algorithms defined and employed by the used video compression standard;
-
Restrictions imposed by the selected video profile according to the rules defined by the used video compression standard;
-
Further restrictions imposed by the capabilities supported by the implementation for the selected video profile;
-
The image data in the encode input picture and the set of active reference pictures (as these affect the effectiveness of the compression algorithms employed by the video encode operations);
-
The set of codec-specific and codec-independent encoding parameters provided by the application.
These also inherently define the set of decoder capabilities required for reconstructing and processing the picture data in the encoded bitstream.
Video coding uses bitrate as the quantitative metric associated with encoded bitstream data size which expresses the rate at which video bitstream data can be transferred or processed, measured in number of bits per second. This bitrate is both a function of the encoded bitstream data size of the encoded pictures as well as the frame rate used by the video sequence.
Rate control algorithms are used by video encode operations to enable adjusting encoding parameters to achieve a target bitrate, or otherwise directly or indirectly control the bitrate of the generated video bitstream data. These algorithms are usually not defined by the used video compression standard, although some video compression standards do provide non-normative guidelines for implementations.
Accordingly, this specification does not mandate implementations to produce identical encoded bitstream data outputs in response to video encode operations, however, it does define a set of codec-independent and codec-specific parameters that enable the application to control the behavior of the rate control algorithms supported by the implementation. Some of these parameters guarantee certain implementation behavior while others provide guidance for implementations to apply various rate control heuristics.
|
Note
|
Applications need to make sure that they configure rate control parameters appropriately and that they follow the promises made to the implementation through parameters providing guidance for the implementation’s rate control algorithms and heuristics in order to be able to get the desired rate control behavior and to be able to hit the set bitrate targets. In addition, the behavior of rate control may also differ across implementations even if the capabilities of the used video profile match between those implementations. This may happen due to implementations applying different rate control algorithms or heuristics internally, and thus even the same set of guidance parameter values may have different effects on the rate control behavior across implementations. |
43.18.1. Rate Control Modes
After a video session is reset to the initial state, the default behavior and parameters of video encode rate control are entirely implementation-dependent and the application cannot affect the bitrate or quality parameters of the encoded bitstream data produced by video encode operations unless the application changes the rate control configuration of the video session, as described in the Video Coding Control section.
For each supported video profile, the implementation may expose a set of rate control modes that are available for use by the application when encoding bitstreams targeting that video profile. These modes allow using different rate control algorithms that fall into one of the following two categories:
-
Per-operation rate control
-
Stream-level rate control
In case of per-operation rate control, the bitrate of the generated video bitstream data is indirectly controlled by quality, size, or other encoding parameters specified by the application for each individual video encode operation.
In case of stream-level rate control, the application can directly specify target bitrates besides other encoding parameters to control the behavior of the rate control algorithm used by the implementation across multiple video encode operations.
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_DEFAULT_KHR = 0,
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR = 0x00000004,
} VkVideoEncodeRateControlModeFlagBitsKHR;
-
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHRspecifies the use of implementation-specific rate control. -
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHRspecifies that rate control is disabled and the application will specify per-operation rate control parameters controlling the encoding quality. In this mode implementations will encode pictures independently of the output bitrate of prior video encode operations.-
When using an H.264 encode profile, implementations will use the QP value specified in VkVideoEncodeH264NaluSliceInfoKHR::
constantQpto control the quality of the encoded picture. -
When using an H.265 encode profile, implementations will use the QP value specified in VkVideoEncodeH265NaluSliceSegmentInfoKHR::
constantQpto control the quality of the encoded picture. -
When using an AV1 encode profile, implementations will use the quantizer index value specified in VkVideoEncodeAV1PictureInfoKHR::
constantQIndexto control the quality of the encoded picture.
-
-
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHRspecifies the use of constant bitrate (CBR) rate control mode. In this mode the implementation will attempt to produce the encoded bitstream at a constant bitrate while conforming to the constraints of other rate control parameters. -
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHRspecifies the use of variable bitrate (VBR) rate control mode. In this mode the implementation will produce the encoded bitstream at a variable bitrate according to the constraints of other rate control parameters.
// Provided by VK_KHR_video_encode_queue
typedef VkFlags VkVideoEncodeRateControlModeFlagsKHR;
VkVideoEncodeRateControlModeFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoEncodeRateControlModeFlagBitsKHR.
43.18.2. Leaky Bucket Model
Video encoding implementations use the leaky bucket model for stream-level rate control. The leaky bucket is a concept referring to the interface between the video encoder and the consumer (for example, a network connection), where the video encoder produces encoded bitstream data corresponding to the encoded pictures and adds them in the leaky bucket while its content are drained by the consumer.
Analogously, a similar leaky bucket is considered to exist at the input interface of a video decoder, into which encoded bitstream data is continuously added and is subsequently consumed by the video decoder. It is desirable to avoid overflowing or underflowing this leaky bucked because:
-
In case of an underflow, the video decoder will be unable to consume encoded bitstream data in order to decode pictures (and optionally display them).
-
In case of an overflow, the leaky bucket will be unable to accommodate more encoded bitstream data and such data may need to be thrown away, leading to the loss of the corresponding encoded pictures.
These requirements can be satisfied by imposing various constraints on the encoder-side leaky bucket to avoid its overflow or underflow, depending on the used rate control algorithm and codec parameters. However, enumerating these constraints is outside the scope of this specification.
The term virtual buffer is often used as an alternative to refer to the leaky bucket.
This virtual buffer model is defined by the following parameters:
-
The bitrate (
R) at which the encoded bitstream is expected to be processed. -
The size (
B) of the virtual buffer. -
The initial occupancy (
F) of the virtual buffer.
In this model the virtual buffer is used to smooth out fluctuations in the bitrate of the encoded bitstream over time without experiencing buffer overflow or underflow, as long as the bitrate of the encoded stream does not diverge from the target bitrate for extended periods of time.
This buffering may inherently impose a processing delay, as the goal of the model is to enable decoders maintain a consistent processing rate of an encoded bitstream with varying data rate.
The initial or start-up delay (D) is computed as:
-
D=F/R
|
Note
|
Applications need to configure the virtual buffer with sufficient size to avoid or minimize buffer overflows and underflows while also keeping it small enough to meet their latency goals. |
43.18.3. Rate Control Layers
Some video compression standards and video profiles allow associating encoded pictures with specific video coding layers. The name, identification, and semantics associated with such video coding layers are defined by the corresponding video compression standards.
Analogously, stream-level rate control can be configured to use one or more rate control layers:
-
When a single rate control layer is configured, it is applied to all encoded pictures, regardless of the picture’s video coding layer. In this case the distribution of the available bitrate budget across video coding layers is implementation-dependent.
-
When multiple rate control layers are configured, each rate control layer is applied to the corresponding video coding layer, i.e. only across encoded pictures pertaining to the corresponding video coding layer.
Individual rate control layers are identified using layer indices between
zero and N-1, where N is the number of active rate control layers.
Rate control layers are only applicable when using stream-level rate control modes.
43.18.4. Rate Control State
Rate control state is maintained by the implementation in the
video session objects and its parameters are specified
using an instance of the VkVideoEncodeRateControlInfoKHR structure.
The complete rate control state of a video session is defined by the
following set of parameters:
-
The values of the members of the VkVideoEncodeRateControlInfoKHR structure used to configure the rate control state.
-
The values of the members of any VkVideoEncodeRateControlLayerInfoKHR structures specified in VkVideoEncodeRateControlInfoKHR::
pLayersused to configure the state of individual rate control layers. -
If the video session was created with an H.264 encode profile:
-
The values of the members of the VkVideoEncodeH264RateControlInfoKHR structure, if one is specified in the
pNextchain of the VkVideoEncodeRateControlInfoKHR used to configure the rate control state. -
The values of the members of any VkVideoEncodeH264RateControlLayerInfoKHR structures included in the
pNextchain of a VkVideoEncodeRateControlLayerInfoKHR structure used to configure the state of a rate control layer.
-
-
If the video session was created with an H.265 encode profile:
-
The values of the members of the VkVideoEncodeH265RateControlInfoKHR structure, if one is specified in the
pNextchain of the VkVideoEncodeRateControlInfoKHR used to configure the rate control state. -
The values of the members of any VkVideoEncodeH265RateControlLayerInfoKHR structures included in the
pNextchain of a VkVideoEncodeRateControlLayerInfoKHR structure used to configure the state of a rate control layer.
-
-
If the video session was created with an AV1 encode profile:
-
The values of the members of the VkVideoEncodeAV1RateControlInfoKHR structure, if one is specified in the
pNextchain of the VkVideoEncodeRateControlInfoKHR used to configure the rate control state. -
The values of the members of any VkVideoEncodeAV1RateControlLayerInfoKHR structures included in the
pNextchain of a VkVideoEncodeRateControlLayerInfoKHR structure used to configure the state of a rate control layer.
-
Two rate control states match if all the parameters listed above match between them.
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;
uint32_t layerCount;
const VkVideoEncodeRateControlLayerInfoKHR* pLayers;
uint32_t virtualBufferSizeInMs;
uint32_t initialVirtualBufferSizeInMs;
} VkVideoEncodeRateControlInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
rateControlModeis a VkVideoEncodeRateControlModeFlagBitsKHR value specifying the rate control mode. -
layerCountspecifies the number of rate control layers to use. -
pLayersis a pointer to an array oflayerCountVkVideoEncodeRateControlLayerInfoKHR structures, each specifying the rate control configuration of the corresponding rate control layer. -
virtualBufferSizeInMsis the size in milliseconds of the virtual buffer used by the implementation’s rate control algorithm for the leaky bucket model, with respect to the average bitrate of the stream calculated by summing the values of theaverageBitratemembers of the elements of thepLayersarray. -
initialVirtualBufferSizeInMsis the initial occupancy in milliseconds of the virtual buffer used by the implementation’s rate control algorithm for the leaky bucket model.
If layerCount is zero then the values of virtualBufferSizeInMs
and initialVirtualBufferSizeInMs are ignored.
This structure can be specified in the following places:
-
In the
pNextchain of VkVideoBeginCodingInfoKHR to specify the current rate control state expected to be configured when beginning a video coding scope. -
In the
pNextchain of VkVideoCodingControlInfoKHR to change the rate control configuration of the bound video session.
Including this structure in the pNext chain of
VkVideoCodingControlInfoKHR and including
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR in
VkVideoCodingControlInfoKHR::flags enables updating the rate
control configuration of the bound video session.
This replaces the entire rate control configuration of the bound video
session and may reset the state of all enabled rate control layers to an
initial state according to the codec-specific rate control semantics defined
in the corresponding sections listed below.
When layerCount is greater than one, multiple
rate control layers are configured, and each
rate control layer is applied to the corresponding video coding layer
identified by the index of the corresponding element of pLayer.
-
If the video session was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then this index specifies the H.264 temporal layer ID of the video coding layer the rate control layer is applied to. -
If the video session was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then this index specifies the H.265 temporal ID of the video coding layer the rate control layer is applied to. -
If the video session was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR, then this index specifies the AV1 temporal ID of the temporal layer the rate control layer is applied to.
Additional structures providing codec-specific rate control parameters can
be included in the pNext chain of VkVideoCodingControlInfoKHR
depending on the video profile the bound video session
was created.
For further details see:
The new rate control configuration takes effect when the corresponding vkCmdControlVideoCodingKHR is executed on the device, and only impacts video encode 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.
Rate Control Layer State
The configuration of individual rate control layers is specified using an
instance of the VkVideoEncodeRateControlLayerInfoKHR structure.
The VkVideoEncodeRateControlLayerInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_queue
typedef struct VkVideoEncodeRateControlLayerInfoKHR {
VkStructureType sType;
const void* pNext;
uint64_t averageBitrate;
uint64_t maxBitrate;
uint32_t frameRateNumerator;
uint32_t frameRateDenominator;
} VkVideoEncodeRateControlLayerInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextis a pointer to a structure extending this structure. -
averageBitrateis the average bitrate to be targeted by the implementation’s rate control algorithm. -
maxBitrateis the peak bitrate to be targeted by the implementation’s rate control algorithm. -
frameRateNumeratoris the numerator of the frame rate assumed by the implementation’s rate control algorithm. -
frameRateDenominatoris the denominator of the frame rate assumed by the implementation’s rate control algorithm.
|
Note
|
The ability of the implementation’s rate control algorithm to be able to match the requested average and/or peak bitrates may be limited by the set of other codec-independent and codec-specific rate control parameters specified by the application, the input content, as well as the application conforming to the rate control guidance provided to the implementation, as described earlier. |
Additional structures providing codec-specific rate control parameters can
be included in the pNext chain of
VkVideoEncodeRateControlLayerInfoKHR depending on the
video profile the bound video session was created with.
For further details see:
43.19. Video Encode Quantization Maps
Quantization maps are VkImage objects that are used in video encode operations to control the relative quantization parameter values across the encoded picture. Each texel in the quantization map controls the relative quantization parameter values used to encode the corresponding rectangular block of texels in the encode input picture.
The size of the rectangular block of texels each quantization map texel covers is referred to as the quantization map texel size.
The extent of the image subresource used as a quantization map when encoding
a picture with a coded extent of (width,height) thus has
to be at least (⌈width / texelSize.width⌉,
⌈height / texelSize.height⌉), where texelSize
is the used quantization map texel size.
In particular, the quantization map texel at location
(x,y) contains relative quantization parameter values used
when encoding the texelSize sized rectangular block of the
encode input picture starting at the texel location
(x × texelSize.width, y ×
texelSize.height).
The quantization map texel size does not always match the size of the
codec-specific coding blocks used during encoding.
Furthermore, some video compression standards allow the size of the
codec-specific coding blocks to vary across the encoded picture.
In order to accommodate for such mismatches between the granularity at which
quantization parameters are stored in quantization maps and the granularity
at which they are applied to codec-specific coding blocks during encoding,
the following mapping rules are applied to define the quantization map texel
value corresponding to a given codec-specific coding block with a size
(width,height) at the texel location
(x,y) in the encode input
picture:
-
If the size of the codec-specific coding block matches the used quantization map texel size, then the fetched quantization map value corresponding to the codec-specific coding block is the texel value at the texel location (
x/texelSize.width,y/texelSize.height). -
If the size of the codec-specific coding block is smaller than the used quantization map texel size, then the fetched quantization map value corresponding to the codec-specific coding block is the texel value at the texel location (⌊
x/texelSize.width⌋, ⌊y/texelSize.height⌋). -
If the size of the codec-specific coding block is larger than the used quantization map texel size, then the fetched quantization map value corresponding to the codec-specific coding block may be any value determined as the linear interpolation of the quantization map texel values in the subregion starting at texel location (
x/texelSize.width,y/texelSize.height) with a size (⌈width/texelSize.width⌉, ⌈height/texelSize.height⌉).
The actual control parameters stored in the quantization map depend on its type. This specification supports the following types of quantization maps:
43.19.1. Quantization Delta Maps
Quantization delta maps contain values that directly affect the codec-specific quantization parameter values used to encode the corresponding block of the encode input picture.
Quantization delta maps can be used in conjunction with any
rate control mode, including
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR.
Due to their codec-specific nature, they are described in more detail in the corresponding codec-specific section for video encode operations that support them. In particular:
-
The behavior of quantization delta maps used with an H.264 encode profile is described in the H.264 Encode Quantization and H.264 QP Delta Maps sections.
-
The behavior of quantization delta maps used with an H.265 encode profile is described in the H.265 Encode Quantization and H.265 QP Delta Maps sections.
-
The behavior of quantization delta maps used with an AV1 encode profile is described in the AV1 Encode Quantization and AV1 Quantizer Index Delta Maps sections.
This specification does not support quantization delta maps for any other video encode operation.
43.19.2. Emphasis Maps
Emphasis maps contain values that indirectly affect the codec-specific quantization parameter values used to encode the corresponding block of the encode input picture.
The texels of emphasis maps contain values that provide input to the encoder implementation about the relative importance (emphasis) of regions of the encoded pictures in order to enable the implementation’s rate control algorithm to allocate more bitrate budget for regions of the encoded picture with higher emphasis values than to those with lower emphasis values.
Emphasis maps can only be used when the current
rate control mode configured for the video
session is not VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR or
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR.
As these emphasis values only control the otherwise implementation-specific behavior of the used rate control algorithm, this specification does not impose additional restrictions on implementations beyond the ones outlined in the corresponding codec-specific sections describing quantization behavior:
-
The behavior of emphasis maps used with an H.264 encode profile is described in the H.264 Encode Quantization section.
-
The behavior of emphasis maps used with an H.265 encode profile is described in the H.265 Encode Quantization section.
-
The behavior of emphasis maps used with an AV1 encode profile is described in the AV1 Encode Quantization section.
This specification does not support emphasis maps for any other video encode operation.
Emphasis maps always have single channel unsigned normalized integer formats
and implementations are required to support the VK_FORMAT_R8_UNORM
format for emphasis maps, as reported in
VkVideoFormatPropertiesKHR::format, when the video encode
profile supports VK_VIDEO_ENCODE_CAPABILITY_EMPHASIS_MAP_BIT_KHR.
43.19.3. Quantization Map Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR with
pVideoProfile->videoCodecOperation specifying an encode operation, the
VkVideoEncodeQuantizationMapCapabilitiesKHR structure can be included
in the pNext chain of the VkVideoCapabilitiesKHR structure to
retrieve capabilities specific to video encode quantization maps.
The VkVideoEncodeQuantizationMapCapabilitiesKHR structure is defined
as:
// Provided by VK_KHR_video_encode_quantization_map
typedef struct VkVideoEncodeQuantizationMapCapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkExtent2D maxQuantizationMapExtent;
} VkVideoEncodeQuantizationMapCapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxQuantizationMapExtentindicates the maximum supported width and height of quantization maps.
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities of an H.264 encode profile, the
VkVideoEncodeH264QuantizationMapCapabilitiesKHR structure can be
included in the pNext chain of the VkVideoCapabilitiesKHR
structure to retrieve additional video encode quantization map capabilities
specific to H.264 encode profiles.
The VkVideoEncodeH264QuantizationMapCapabilitiesKHR structure is
defined as:
// Provided by VK_KHR_video_encode_h264 with VK_KHR_video_encode_quantization_map
typedef struct VkVideoEncodeH264QuantizationMapCapabilitiesKHR {
VkStructureType sType;
void* pNext;
int32_t minQpDelta;
int32_t maxQpDelta;
} VkVideoEncodeH264QuantizationMapCapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minQpDeltaindicates the minimum QP delta value supported for H.264 QP delta maps. -
maxQpDeltaindicates the maximum QP delta value supported for H.264 QP delta maps.
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities of an H.265 encode profile, the
VkVideoEncodeH265QuantizationMapCapabilitiesKHR structure can be
included in the pNext chain of the VkVideoCapabilitiesKHR
structure to retrieve additional video encode quantization map capabilities
specific to H.265 encode profiles.
The VkVideoEncodeH265QuantizationMapCapabilitiesKHR structure is
defined as:
// Provided by VK_KHR_video_encode_h265 with VK_KHR_video_encode_quantization_map
typedef struct VkVideoEncodeH265QuantizationMapCapabilitiesKHR {
VkStructureType sType;
void* pNext;
int32_t minQpDelta;
int32_t maxQpDelta;
} VkVideoEncodeH265QuantizationMapCapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minQpDeltaindicates the minimum QP delta value supported for H.265 QP delta maps. -
maxQpDeltaindicates the maximum QP delta value supported for H.265 QP delta maps.
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities of an AV1 encode profile, the
VkVideoEncodeAV1QuantizationMapCapabilitiesKHR structure can be
included in the pNext chain of the VkVideoCapabilitiesKHR
structure to retrieve additional video encode quantization map capabilities
specific to AV1 encode profiles.
The VkVideoEncodeAV1QuantizationMapCapabilitiesKHR structure is
defined as:
// Provided by VK_KHR_video_encode_av1 with VK_KHR_video_encode_quantization_map
typedef struct VkVideoEncodeAV1QuantizationMapCapabilitiesKHR {
VkStructureType sType;
void* pNext;
int32_t minQIndexDelta;
int32_t maxQIndexDelta;
} VkVideoEncodeAV1QuantizationMapCapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minQIndexDeltaindicates the minimum quantizer index delta value supported for AV1 quantizer index delta maps. -
maxQIndexDeltaindicates the maximum quantizer index delta value supported for AV1 quantizer index delta maps.
43.19.4. Quantization Map Format Properties
When calling vkGetPhysicalDeviceVideoFormatPropertiesKHR, the
VkVideoFormatQuantizationMapPropertiesKHR structure can be included
in the pNext chain of the VkVideoFormatPropertiesKHR structure
to retrieve video format properties specific to video encode quantization
maps.
The VkVideoFormatQuantizationMapPropertiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_quantization_map
typedef struct VkVideoFormatQuantizationMapPropertiesKHR {
VkStructureType sType;
void* pNext;
VkExtent2D quantizationMapTexelSize;
} VkVideoFormatQuantizationMapPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
quantizationMapTexelSizeindicates the quantization map texel size of the video format, i.e. the number of pixels corresponding to each quantization map texel.
The values returned in this structure are only defined if the allowed image
usage flags returned in
VkVideoFormatPropertiesKHR::imageUsageFlags for this video
format include
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR or
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR.
Implementations may support multiple quantization map texel sizes for a
particular video format which is indicated by
vkGetPhysicalDeviceVideoFormatPropertiesKHR returning multiple entries
with different quantizationMapTexelSize values.
When calling vkGetPhysicalDeviceVideoFormatPropertiesKHR, the
VkVideoFormatH265QuantizationMapPropertiesKHR structure can be
included in the pNext chain of the VkVideoFormatPropertiesKHR
structure to retrieve video format properties specific to video encode
quantization maps used with an H.265 encode profile.
The VkVideoFormatH265QuantizationMapPropertiesKHR structure is defined
as:
// Provided by VK_KHR_video_encode_h265 with VK_KHR_video_encode_quantization_map
typedef struct VkVideoFormatH265QuantizationMapPropertiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeH265CtbSizeFlagsKHR compatibleCtbSizes;
} VkVideoFormatH265QuantizationMapPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
compatibleCtbSizesis a bitmask of VkVideoEncodeH265CtbSizeFlagBitsKHR indicating the CTB sizes that quantization maps using this video format are compatible with.NoteThe value of
compatibleCtbSizesdoes not limit the use of the specific quantization map format, but does limit the implementation in being able to encode pictures with CTB sizes not included incompatibleCtbSizesbut otherwise supported by the used video profile, as indicated by VkVideoEncodeH265CapabilitiesKHR::ctbSizes. In particular, using smaller quantization map texel sizes may prevent implementations from encoding with larger CTB sizes which may have a negative impact on the efficiency of the encoder.
The values returned in this structure are only defined if the allowed image
usage flags returned in
VkVideoFormatPropertiesKHR::imageUsageFlags for this video
format include
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR or
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR.
When calling vkGetPhysicalDeviceVideoFormatPropertiesKHR, the
VkVideoFormatAV1QuantizationMapPropertiesKHR structure can be
included in the pNext chain of the VkVideoFormatPropertiesKHR
structure to retrieve video format properties specific to video encode
quantization maps used with an AV1 encode profile.
The VkVideoFormatAV1QuantizationMapPropertiesKHR structure is defined
as:
// Provided by VK_KHR_video_encode_av1 with VK_KHR_video_encode_quantization_map
typedef struct VkVideoFormatAV1QuantizationMapPropertiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeAV1SuperblockSizeFlagsKHR compatibleSuperblockSizes;
} VkVideoFormatAV1QuantizationMapPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
compatibleSuperblockSizesis a bitmask of VkVideoEncodeAV1SuperblockSizeFlagBitsKHR indicating the AV1 superblock sizes that quantization maps using this video format are compatible with.NoteThe value of
compatibleSuperblockSizesdoes not limit the use of the specific quantization map format, but does limit the implementation in being able to encode pictures with superblock sizes not included incompatibleSuperblockSizesbut otherwise supported by the used video profile, as indicated by VkVideoEncodeAV1CapabilitiesKHR::superblockSizes. In particular, using smaller quantization map texel sizes may prevent implementations from encoding with larger superblock sizes which may have a negative impact on the efficiency of the encoder.
The values returned in this structure are only defined if the allowed image
usage flags returned in
VkVideoFormatPropertiesKHR::imageUsageFlags for this video
format include
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR or
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR.
43.19.5. Encoding with Quantization Maps
The VkVideoEncodeQuantizationMapInfoKHR structure can be included in
the pNext chain of the VkVideoEncodeInfoKHR structure passed to
the vkCmdEncodeVideoKHR command to specify the quantization map used
by the issued video encode operations.
The VkVideoEncodeQuantizationMapInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_quantization_map
typedef struct VkVideoEncodeQuantizationMapInfoKHR {
VkStructureType sType;
const void* pNext;
VkImageView quantizationMap;
VkExtent2D quantizationMapExtent;
} VkVideoEncodeQuantizationMapInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
quantizationMapspecifies the image view to use as the quantization map. -
quantizationMapExtentspecifies the extent of the image subregion ofquantizationMapto use as the quantization map starting at offset (0,0).
43.20. H.264 Encode Operations
Video encode operations using an H.264 encode profile can be used to encode elementary video stream sequences compliant to the ITU-T H.264 Specification.
|
Note
|
Refer to the Preamble for information on how the Khronos Intellectual Property Rights Policy relates to normative references to external materials not created by Khronos. |
This process is performed according to the video encode operation steps with the codec-specific semantics defined in section 8 of the ITU-T H.264 Specification as follows:
-
Syntax elements, derived values, and other parameters are applied from the following structures:
-
The
StdVideoH264SequenceParameterSetstructure corresponding to the active SPS specifying the H.264 sequence parameter set. -
The
StdVideoH264PictureParameterSetstructure corresponding to the active PPS specifying the H.264 picture parameter set. -
The
StdVideoEncodeH264PictureInfostructure specifying the H.264 picture information. -
The
StdVideoEncodeH264SliceHeaderstructures specifying the H.264 slice header parameters for each encoded H.264 slice. -
The
StdVideoEncodeH264ReferenceInfostructures specifying the H.264 reference information corresponding to the optional reconstructed picture and any active reference pictures.
-
-
The encoded bitstream data is written to the destination video bitstream buffer range as defined in the H.264 Encode Bitstream Data Access section.
-
Picture data in the video picture resources corresponding to the used encode input picture, active reference pictures, and optional reconstructed picture is accessed as defined in the H.264 Encode Picture Data Access section.
-
The decision on reference picture setup is made according to the parameters specified in the H.264 picture information.
If the parameters adhere to the syntactic and semantic requirements defined in the corresponding sections of the ITU-T H.264 Specification, as described above, and the DPB slots associated with the active reference pictures all refer to valid picture references, then the video encode operation will complete successfully. Otherwise, the video encode operation may complete unsuccessfully.
43.20.1. H.264 Encode Parameter Overrides
Implementations may override, unless otherwise specified, any of the H.264 encode parameters specified in the following Video Std structures:
-
StdVideoH264SequenceParameterSet -
StdVideoH264PictureParameterSet -
StdVideoEncodeH264PictureInfo -
StdVideoEncodeH264SliceHeader -
StdVideoEncodeH264ReferenceInfo
All such H.264 encode parameter overrides must fulfill the conditions defined in the Video Encode Parameter Overrides section.
In addition, implementations must not override any of the following H.264 encode parameters:
-
StdVideoEncodeH264PictureInfo::primary_pic_type -
StdVideoEncodeH264SliceHeader::slice_type
If the videoMaintenance2 feature is
enabled, implementations must not override any of the following H.264
encode parameters:
-
the following parameters specified in
StdVideoH264SequenceParameterSet:-
flags.vui_parameters_present_flag -
profile_idc -
level_idc -
chroma_format_idc
-
-
the following parameters specified in the
StdVideoH264SequenceParameterSetVuistructure pointed to byStdVideoH264SequenceParameterSet::pSequenceParameterSetVui:-
flags.aspect_ratio_info_present_flag -
flags.overscan_info_present_flag -
flags.overscan_appropriate_flag -
flags.video_signal_type_present_flag -
flags.video_full_range_flag -
flags.color_description_present_flag -
flags.chroma_loc_info_present_flag -
flags.timing_info_present_flag -
flags.fixed_frame_rate_flag -
aspect_ratio_idc -
sar_width -
sar_height -
video_format -
colour_primaries -
transfer_characteristics -
matrix_coefficients -
num_units_in_tick -
time_scale -
chroma_sample_loc_type_top_field -
chroma_sample_loc_type_bottom_field
-
In case of H.264 encode parameters stored in video session parameters objects, applications need to use the vkGetEncodedVideoSessionParametersKHR command to determine whether any implementation overrides happened. If the query indicates that implementation overrides were applied, then the application needs to retrieve and use the encoded H.264 parameter sets in the bitstream in order to be able to produce a compliant H.264 video bitstream using the H.264 encode parameters stored in the video session parameters object.
In case of any H.264 encode parameters stored in the encoded bitstream
produced by video encode operations, if the implementation supports the
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR
video encode feedback query flag, the
application can use such queries to retrieve feedback about whether any
implementation overrides have been applied to those H.264 encode parameters.
43.20.2. H.264 Encode Bitstream Data Access
Each video encode operation writes one or more VCL NAL units comprising of
slice headers and data of the encoded picture, in the format defined in
sections 7.3.3 and 7.3.4, according to the semantics defined in sections
7.4.3 and 7.4.4 of the ITU-T H.264 Specification,
respectively.
The number of VCL NAL units written is specified by
VkVideoEncodeH264PictureInfoKHR::naluSliceEntryCount.
In addition, if
VkVideoEncodeH264PictureInfoKHR::generatePrefixNalu is
VK_TRUE for the video encode operation, then an additional prefix NAL
unit is written before each VCL NAL unit corresponding to individual slices
in the format defined in section 7.3.2.12, according to the semantics
defined in section 7.4.2.12 of the ITU-T H.264 Specification,
respectively.
43.20.3. H.264 Encode Picture Data Access
Accesses to image data within a video picture resource happen at the
granularity indicated by
VkVideoCapabilitiesKHR::pictureAccessGranularity, as returned by
vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile.
Accordingly, the complete image subregion of a encode
input picture, reference picture, or
reconstructed picture accessed by video coding
operations using an H.264 encode profile is defined
as the set of texels within the coordinate range:
-
([0,
endX), [0,endY))
Where:
-
endXequalscodedExtent.widthrounded up to the nearest integer multiple ofpictureAccessGranularity.widthand clamped to the width of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure; -
endY equals
codedExtent.heightrounded up to the nearest integer multiple ofpictureAccessGranularity.heightand clamped to the height of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure;
Where codedExtent is the member of the
VkVideoPictureResourceInfoKHR structure corresponding to the picture.
In case of video encode operations using an H.264
encode profile, any access to a picture at the coordinates
(x,y), as defined by the ITU-T H.264
Specification, is an access to the image subresource
referred to by the corresponding
VkVideoPictureResourceInfoKHR structure at the texel coordinates
(x,y).
Implementations may choose not to access some or all texels within particular reference pictures available to a video encode operation (e.g. due to video encode parameter overrides restricting the effective set of used reference pictures, or if the encoding algorithm chooses not to use certain subregions of the reference picture data for sample prediction).
43.20.4. H.264 Frame, Picture, and Slice
H.264 pictures are partitioned into slices, as defined in section 6.3 of the ITU-T H.264 Specification.
For the purposes of this specification, the H.264 slices comprising a picture are referred to as the picture partitions of the picture.
Video encode operations using an H.264 encode
profile can encode slices of different types, as defined in section 7.4.3
of the ITU-T H.264 Specification, by specifying the
corresponding enumeration constant value in
StdVideoEncodeH264SliceHeader::slice_type in the
H.264 slice header parameters from the
Video Std enumeration type StdVideoH264SliceType:
-
STD_VIDEO_H264_SLICE_TYPE_Pindicates that the slice is a P slice as defined in section 3.109 of the ITU-T H.264 Specification. -
STD_VIDEO_H264_SLICE_TYPE_Bindicates that the slice is a B slice as defined in section 3.9 of the ITU-T H.264 Specification. -
STD_VIDEO_H264_SLICE_TYPE_Iindicates that the slice is an I slice as defined in section 3.66 of the ITU-T H.264 Specification.
Pictures constructed from such slices can be of different types, as defined
in section 7.4.2.4 of the ITU-T H.264 Specification.
Video encode operations using an H.264 encode
profile can encode pictures of a specific type by specifying the
corresponding enumeration constant value in
StdVideoEncodeH264PictureInfo::primary_pic_type in the
H.264 picture information from the Video Std
enumeration type StdVideoH264PictureType:
-
STD_VIDEO_H264_PICTURE_TYPE_Pindicates that the picture is a P picture. A frame consisting of a P picture is also referred to as a P frame. -
STD_VIDEO_H264_PICTURE_TYPE_Bindicates that the picture is a B picture. A frame consisting of a B picture is also referred to as a B frame. -
STD_VIDEO_H264_PICTURE_TYPE_Iindicates that the picture is an I picture. A frame consisting of an I picture is also referred to as an I frame. -
STD_VIDEO_H264_PICTURE_TYPE_IDRindicates that the picture is a special type of I picture called an IDR picture as defined in section 3.69 of the ITU-T H.264 Specification. A frame consisting of an IDR picture is also referred to as an IDR frame.
43.20.5. H.264 Coding Blocks
H.264 encode supports a single type of coding block called a macroblock, as defined in section 3.84 of the ITU-T H.264 Specification.
43.20.6. H.264 Encode Profile
A video profile supporting H.264 video encode operations is specified by
setting VkVideoProfileInfoKHR::videoCodecOperation to
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and adding a
VkVideoEncodeH264ProfileInfoKHR structure to the
VkVideoProfileInfoKHR::pNext chain.
The VkVideoEncodeH264ProfileInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264ProfileInfoKHR {
VkStructureType sType;
const void* pNext;
StdVideoH264ProfileIdc stdProfileIdc;
} VkVideoEncodeH264ProfileInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileIdcis aStdVideoH264ProfileIdcvalue specifying the H.264 codec profile IDC, where enum constantSTD_VIDEO_H264_PROFILE_IDC_BASELINEidentifies the Constrained Baseline profile as defined in A.2.1.1 of the ITU-T H.264 Specification, and all other values correspond to profiles defined in section A.2 of the ITU-T H.264 Specification.
43.20.7. H.264 Encode Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for an H.264 encode profile, the
VkVideoCapabilitiesKHR::pNext chain must include a
VkVideoEncodeH264CapabilitiesKHR structure that will be filled with
the profile-specific capabilities.
The VkVideoEncodeH264CapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264CapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeH264CapabilityFlagsKHR flags;
StdVideoH264LevelIdc maxLevelIdc;
uint32_t maxSliceCount;
uint32_t maxPPictureL0ReferenceCount;
uint32_t maxBPictureL0ReferenceCount;
uint32_t maxL1ReferenceCount;
uint32_t maxTemporalLayerCount;
VkBool32 expectDyadicTemporalLayerPattern;
int32_t minQp;
int32_t maxQp;
VkBool32 prefersGopRemainingFrames;
VkBool32 requiresGopRemainingFrames;
VkVideoEncodeH264StdFlagsKHR stdSyntaxFlags;
} VkVideoEncodeH264CapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeH264CapabilityFlagBitsKHR indicating supported H.264 encoding capabilities. -
maxLevelIdcis aStdVideoH264LevelIdcvalue indicating the maximum H.264 level supported by the profile, where enum constantSTD_VIDEO_H264_LEVEL_IDC_<major>_<minor>identifies H.264 level<major>.<minor>as defined in section A.3 of the ITU-T H.264 Specification. -
maxSliceCountindicates the maximum number of slices that can be encoded for a single picture. Further restrictions may apply to the number of slices that can be encoded for a single picture depending on other capabilities and codec-specific rules. -
maxPPictureL0ReferenceCountindicates the maximum number of reference pictures the implementation supports in the reference list L0 for P pictures.NoteAs implementations may override the reference lists,
maxPPictureL0ReferenceCountdoes not limit the number of elements that the application can specify in the L0 reference list for P pictures. However, ifmaxPPictureL0ReferenceCountis zero, then the use of P pictures is not allowed. -
maxBPictureL0ReferenceCountindicates the maximum number of reference pictures the implementation supports in the reference list L0 for B pictures. -
maxL1ReferenceCountindicates the maximum number of reference pictures the implementation supports in the reference list L1 if encoding of B pictures is supported.NoteAs implementations may override the reference lists,
maxBPictureL0ReferenceCountandmaxL1ReferenceCountdoes not limit the number of elements that the application can specify in the L0 and L1 reference lists for B pictures. However, ifmaxBPictureL0ReferenceCountandmaxL1ReferenceCountare both zero, then the use of B pictures is not allowed. -
maxTemporalLayerCountindicates the maximum number of H.264 temporal layers supported by the implementation. -
expectDyadicTemporalLayerPatternindicates that the implementation’s rate control algorithms expect the application to use a dyadic temporal layer pattern when encoding multiple temporal layers. -
minQpindicates the minimum QP value supported. -
maxQpindicates the maximum QP value supported. -
prefersGopRemainingFramesindicates that the implementation’s rate control algorithm prefers the application to specify the number of frames of each type remaining in the current group of pictures when beginning a video coding scope. -
requiresGopRemainingFramesindicates that the implementation’s rate control algorithm requires the application to specify the number of frames of each type remaining in the current group of pictures when beginning a video coding scope. -
stdSyntaxFlagsis a bitmask of VkVideoEncodeH264StdFlagBitsKHR indicating capabilities related to H.264 syntax elements.
Bits which may be set in
VkVideoEncodeH264CapabilitiesKHR::flags, indicating the H.264
encoding capabilities supported, are:
// Provided by VK_KHR_video_encode_h264
typedef enum VkVideoEncodeH264CapabilityFlagBitsKHR {
VK_VIDEO_ENCODE_H264_CAPABILITY_HRD_COMPLIANCE_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_H264_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_H264_CAPABILITY_ROW_UNALIGNED_SLICE_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_KHR = 0x00000008,
VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHR = 0x00000010,
VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHR = 0x00000020,
VK_VIDEO_ENCODE_H264_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR = 0x00000040,
VK_VIDEO_ENCODE_H264_CAPABILITY_PER_SLICE_CONSTANT_QP_BIT_KHR = 0x00000080,
VK_VIDEO_ENCODE_H264_CAPABILITY_GENERATE_PREFIX_NALU_BIT_KHR = 0x00000100,
// Provided by VK_KHR_video_encode_h264 with VK_KHR_video_encode_intra_refresh
VK_VIDEO_ENCODE_H264_CAPABILITY_B_PICTURE_INTRA_REFRESH_BIT_KHR = 0x00000400,
// Provided by VK_KHR_video_encode_h264 with VK_KHR_video_encode_quantization_map
VK_VIDEO_ENCODE_H264_CAPABILITY_MB_QP_DIFF_WRAPAROUND_BIT_KHR = 0x00000200,
} VkVideoEncodeH264CapabilityFlagBitsKHR;
-
VK_VIDEO_ENCODE_H264_CAPABILITY_HRD_COMPLIANCE_BIT_KHRspecifies whether the implementation may be able to generate HRD compliant bitstreams if any of thenal_hrd_parameters_present_flagorvcl_hrd_parameters_present_flagmembers ofStdVideoH264SpsVuiFlagsare set to1in the active SPS. -
VK_VIDEO_ENCODE_H264_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHRspecifies that ifStdVideoH264PpsFlags::weighted_pred_flagis set to1orStdVideoH264PictureParameterSet::weighted_bipred_idcis set toSTD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICITin the active PPS when encoding a P picture or B picture, respectively, then the implementation is able to internally decide syntax forpred_weight_table, as defined in section 7.4.3.2 of the ITU-T H.264 Specification, and the application is not required to provide a weight table in the H.264 slice header parameters. -
VK_VIDEO_ENCODE_H264_CAPABILITY_ROW_UNALIGNED_SLICE_BIT_KHRspecifies 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). When a picture is encoded with intra refresh, encoding non-rectangular slices also requires: support for the VkVideoEncodeIntraRefreshCapabilitiesKHR::nonRectangularIntraRefreshRegionscapability. -
VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_KHRspecifies that when a frame is encoded with multiple slices, the implementation allows encoding each slice with a differentStdVideoEncodeH264SliceHeader::slice_typespecified in the H.264 slice header parameters. If not supported, all slices of the frame must be encoded with the sameslice_typewhich corresponds to the picture type of the frame. There is one exception to this rule: if the picture is encoded with the intra refresh modeVK_VIDEO_ENCODE_INTRA_REFRESH_MODE_PER_PICTURE_PARTITION_BIT_KHR, then the currently refreshed slice must specify theslice_typeSTD_VIDEO_H264_SLICE_TYPE_Iand can differ from theslice_typeof the other slices regardless of whetherVK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_KHRis supported. -
VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHRspecifies support for using a B frame as L0 reference, as specified inStdVideoEncodeH264ReferenceListsInfo::RefPicList0in the H.264 picture information. -
VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHRspecifies support for using a B frame as L1 reference, as specified inStdVideoEncodeH264ReferenceListsInfo::RefPicList1in the H.264 picture information. -
VK_VIDEO_ENCODE_H264_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHRspecifies support for specifying different QP values in the members of VkVideoEncodeH264QpKHR. -
VK_VIDEO_ENCODE_H264_CAPABILITY_PER_SLICE_CONSTANT_QP_BIT_KHRspecifies support for specifying different constant QP values for each slice. -
VK_VIDEO_ENCODE_H264_CAPABILITY_GENERATE_PREFIX_NALU_BIT_KHRspecifies support for generating prefix NAL units by setting VkVideoEncodeH264PictureInfoKHR::generatePrefixNalutoVK_TRUE. -
VK_VIDEO_ENCODE_H264_CAPABILITY_MB_QP_DIFF_WRAPAROUND_BIT_KHRindicates support for wraparound during the calculation of the QP values of subsequently encoded macroblocks, as defined in equation 7-37 of the ITU-T H.264 Specification. If not supported, equation 7-37 of the ITU-T H.264 Specification is effectively reduced to the following:QPY = QPY,PREV +
mb_qp_deltaNoteThe effect of this is that the maximum QP difference across subsequent macroblocks is limited to the [-(26 + QpBdOffsetY / 2), 25 + QpBdOffsetY / 2] range.
-
VK_VIDEO_ENCODE_H264_CAPABILITY_B_PICTURE_INTRA_REFRESH_BIT_KHRindicates support for encoding B pictures with intra refresh enabled.
// Provided by VK_KHR_video_encode_h264
typedef VkFlags VkVideoEncodeH264CapabilityFlagsKHR;
VkVideoEncodeH264CapabilityFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoEncodeH264CapabilityFlagBitsKHR.
Bits which may be set in
VkVideoEncodeH264CapabilitiesKHR::stdSyntaxFlags, indicating the
capabilities related to the H.264 syntax elements, are:
// Provided by VK_KHR_video_encode_h264
typedef enum VkVideoEncodeH264StdFlagBitsKHR {
VK_VIDEO_ENCODE_H264_STD_SEPARATE_COLOR_PLANE_FLAG_SET_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_H264_STD_QPPRIME_Y_ZERO_TRANSFORM_BYPASS_FLAG_SET_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_H264_STD_SCALING_MATRIX_PRESENT_FLAG_SET_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_H264_STD_CHROMA_QP_INDEX_OFFSET_BIT_KHR = 0x00000008,
VK_VIDEO_ENCODE_H264_STD_SECOND_CHROMA_QP_INDEX_OFFSET_BIT_KHR = 0x00000010,
VK_VIDEO_ENCODE_H264_STD_PIC_INIT_QP_MINUS26_BIT_KHR = 0x00000020,
VK_VIDEO_ENCODE_H264_STD_WEIGHTED_PRED_FLAG_SET_BIT_KHR = 0x00000040,
VK_VIDEO_ENCODE_H264_STD_WEIGHTED_BIPRED_IDC_EXPLICIT_BIT_KHR = 0x00000080,
VK_VIDEO_ENCODE_H264_STD_WEIGHTED_BIPRED_IDC_IMPLICIT_BIT_KHR = 0x00000100,
VK_VIDEO_ENCODE_H264_STD_TRANSFORM_8X8_MODE_FLAG_SET_BIT_KHR = 0x00000200,
VK_VIDEO_ENCODE_H264_STD_DIRECT_SPATIAL_MV_PRED_FLAG_UNSET_BIT_KHR = 0x00000400,
VK_VIDEO_ENCODE_H264_STD_ENTROPY_CODING_MODE_FLAG_UNSET_BIT_KHR = 0x00000800,
VK_VIDEO_ENCODE_H264_STD_ENTROPY_CODING_MODE_FLAG_SET_BIT_KHR = 0x00001000,
VK_VIDEO_ENCODE_H264_STD_DIRECT_8X8_INFERENCE_FLAG_UNSET_BIT_KHR = 0x00002000,
VK_VIDEO_ENCODE_H264_STD_CONSTRAINED_INTRA_PRED_FLAG_SET_BIT_KHR = 0x00004000,
VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_DISABLED_BIT_KHR = 0x00008000,
VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_ENABLED_BIT_KHR = 0x00010000,
VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_PARTIAL_BIT_KHR = 0x00020000,
VK_VIDEO_ENCODE_H264_STD_SLICE_QP_DELTA_BIT_KHR = 0x00080000,
VK_VIDEO_ENCODE_H264_STD_DIFFERENT_SLICE_QP_DELTA_BIT_KHR = 0x00100000,
} VkVideoEncodeH264StdFlagBitsKHR;
-
VK_VIDEO_ENCODE_H264_STD_SEPARATE_COLOR_PLANE_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264SpsFlags::separate_colour_plane_flagin the SPS when that value is1. -
VK_VIDEO_ENCODE_H264_STD_QPPRIME_Y_ZERO_TRANSFORM_BYPASS_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264SpsFlags::qpprime_y_zero_transform_bypass_flagin the SPS when that value is1. -
VK_VIDEO_ENCODE_H264_STD_SCALING_MATRIX_PRESENT_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided values forStdVideoH264SpsFlags::seq_scaling_matrix_present_flagin the SPS andStdVideoH264PpsFlags::pic_scaling_matrix_present_flagin the PPS when any of those values are1. -
VK_VIDEO_ENCODE_H264_STD_CHROMA_QP_INDEX_OFFSET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264PictureParameterSet::chroma_qp_index_offsetin the PPS when that value is non-zero. -
VK_VIDEO_ENCODE_H264_STD_SECOND_CHROMA_QP_INDEX_OFFSET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264PictureParameterSet::second_chroma_qp_index_offsetin the PPS when that value is non-zero. -
VK_VIDEO_ENCODE_H264_STD_PIC_INIT_QP_MINUS26_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264PictureParameterSet::pic_init_qp_minus26in the PPS when that value is non-zero. -
VK_VIDEO_ENCODE_H264_STD_WEIGHTED_PRED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264PpsFlags::weighted_pred_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H264_STD_WEIGHTED_BIPRED_IDC_EXPLICIT_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264PictureParameterSet::weighted_bipred_idcin the PPS when that value isSTD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT. -
VK_VIDEO_ENCODE_H264_STD_WEIGHTED_BIPRED_IDC_IMPLICIT_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264PictureParameterSet::weighted_bipred_idcin the PPS when that value isSTD_VIDEO_H264_WEIGHTED_BIPRED_IDC_IMPLICIT. -
VK_VIDEO_ENCODE_H264_STD_TRANSFORM_8X8_MODE_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264PpsFlags::transform_8x8_mode_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H264_STD_DIRECT_SPATIAL_MV_PRED_FLAG_UNSET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeH264SliceHeaderFlags::direct_spatial_mv_pred_flagin the H.264 slice header parameters when that value is0. -
VK_VIDEO_ENCODE_H264_STD_ENTROPY_CODING_MODE_FLAG_UNSET_BIT_KHRspecifies whether the implementation supports CAVLC entropy coding, as defined in section 9.2 of the ITU-T H.264 Specification, and thus supports using the application-provided value forStdVideoH264PpsFlags::entropy_coding_mode_flagin the PPS when that value is0. -
VK_VIDEO_ENCODE_H264_STD_ENTROPY_CODING_MODE_FLAG_SET_BIT_KHRspecifies whether the implementation supports CABAC entropy coding, as defined in section 9.3 of the ITU-T H.264 Specification, and thus supports using the application-provided value forStdVideoH264PpsFlags::entropy_coding_mode_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H264_STD_DIRECT_8X8_INFERENCE_FLAG_UNSET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264SpsFlags::direct_8x8_inference_flagin the SPS when that value is0. -
VK_VIDEO_ENCODE_H264_STD_CONSTRAINED_INTRA_PRED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH264PpsFlags::constrained_intra_pred_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_DISABLED_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeH264SliceHeader::disable_deblocking_filter_idcin the H.264 slice header parameters when that value isSTD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_DISABLED. -
VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_ENABLED_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeH264SliceHeader::disable_deblocking_filter_idcin the H.264 slice header parameters when that value isSTD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_ENABLED. -
VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_PARTIAL_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeH264SliceHeader::disable_deblocking_filter_idcin the H.264 slice header parameters when that value isSTD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_PARTIAL. -
VK_VIDEO_ENCODE_H264_STD_SLICE_QP_DELTA_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeH264SliceHeader::slice_qp_deltain the H.264 slice header parameters when that value is identical across the slices of the encoded frame. -
VK_VIDEO_ENCODE_H264_STD_DIFFERENT_SLICE_QP_DELTA_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeH264SliceHeader::slice_qp_deltain the H.264 slice header parameters when that value is different across the slices of the encoded frame.
These capability flags provide information to the application about specific H.264 syntax element values that the implementation supports without having to override them and do not otherwise restrict the values that the application can specify for any of the mentioned H.264 syntax elements.
// Provided by VK_KHR_video_encode_h264
typedef VkFlags VkVideoEncodeH264StdFlagsKHR;
VkVideoEncodeH264StdFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoEncodeH264StdFlagBitsKHR.
43.20.8. H.264 Encode Quality Level Properties
When calling vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR
with pVideoProfile->videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the
VkVideoEncodeH264QualityLevelPropertiesKHR structure must be included
in the pNext chain of the VkVideoEncodeQualityLevelPropertiesKHR
structure to retrieve additional video encode quality level properties
specific to H.264 encoding.
The VkVideoEncodeH264QualityLevelPropertiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264QualityLevelPropertiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeH264RateControlFlagsKHR preferredRateControlFlags;
uint32_t preferredGopFrameCount;
uint32_t preferredIdrPeriod;
uint32_t preferredConsecutiveBFrameCount;
uint32_t preferredTemporalLayerCount;
VkVideoEncodeH264QpKHR preferredConstantQp;
uint32_t preferredMaxL0ReferenceCount;
uint32_t preferredMaxL1ReferenceCount;
VkBool32 preferredStdEntropyCodingModeFlag;
} VkVideoEncodeH264QualityLevelPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
preferredRateControlFlagsis a bitmask of VkVideoEncodeH264RateControlFlagBitsKHR values indicating the preferred flags to use for VkVideoEncodeH264RateControlInfoKHR::flags. -
preferredGopFrameCountindicates the preferred value to use for VkVideoEncodeH264RateControlInfoKHR::gopFrameCount. -
preferredIdrPeriodindicates the preferred value to use for VkVideoEncodeH264RateControlInfoKHR::idrPeriod. -
preferredConsecutiveBFrameCountindicates the preferred value to use for VkVideoEncodeH264RateControlInfoKHR::consecutiveBFrameCount. -
preferredTemporalLayerCountindicates the preferred value to use for VkVideoEncodeH264RateControlInfoKHR::temporalLayerCount. -
preferredConstantQpindicates the preferred values to use for VkVideoEncodeH264NaluSliceInfoKHR::constantQpfor each picture type when using rate control modeVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. -
preferredMaxL0ReferenceCountindicates the preferred maximum number of reference pictures to use in the reference list L0. -
preferredMaxL1ReferenceCountindicates the preferred maximum number of reference pictures to use in the reference list L1. -
preferredStdEntropyCodingModeFlagindicates the preferred value to use forentropy_coding_mode_flaginStdVideoH264PpsFlags.
43.20.9. H.264 Encode Session
Additional parameters can be specified when creating a video session with an
H.264 encode profile by including an instance of the
VkVideoEncodeH264SessionCreateInfoKHR structure in the pNext
chain of VkVideoSessionCreateInfoKHR.
The VkVideoEncodeH264SessionCreateInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264SessionCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 useMaxLevelIdc;
StdVideoH264LevelIdc maxLevelIdc;
} VkVideoEncodeH264SessionCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
useMaxLevelIdcindicates whether the value ofmaxLevelIdcshould be used by the implementation. When it isVK_FALSE, the implementation ignores the value ofmaxLevelIdcand uses the value of VkVideoEncodeH264CapabilitiesKHR::maxLevelIdc, as reported by vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile. -
maxLevelIdcis aStdVideoH264LevelIdcvalue specifying the upper bound on the H.264 level for the video bitstreams produced by the created video session, where enum constantSTD_VIDEO_H264_LEVEL_IDC_<major>_<minor>identifies H.264 level<major>.<minor>as defined in section A.3 of the ITU-T H.264 Specification.
43.20.10. H.264 Encode Parameter Sets
Video session parameters objects created with
the video codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR
can contain the following types of parameters:
- H.264 Sequence Parameter Sets (SPS)
-
Represented by
StdVideoH264SequenceParameterSetstructures and interpreted as follows:-
reserved1andreserved2are used only for padding purposes and are otherwise ignored; -
seq_parameter_set_idis used as the key of the SPS entry; -
level_idcis one of the enum constantsSTD_VIDEO_H264_LEVEL_IDC_<major>_<minor>identifying the H.264 level<major>.<minor>as defined in section A.3 of the ITU-T H.264 Specification; -
if
flags.seq_scaling_matrix_present_flagis set, then theStdVideoH264ScalingListsstructure pointed to bypScalingListsis interpreted as follows:-
scaling_list_present_maskis a bitmask where bit index i corresponds toseq_scaling_list_present_flag[i]as defined in section 7.4.2.1 of the ITU-T H.264 Specification; -
use_default_scaling_matrix_maskis a bitmask where bit index i corresponds toUseDefaultScalingMatrix4x4Flag[i], when i < 6, or corresponds toUseDefaultScalingMatrix8x8Flag[i-6], otherwise, as defined in section 7.3.2.1 of the ITU-T H.264 Specification; -
ScalingList4x4andScalingList8x8correspond to the identically named syntax elements defined in section 7.3.2.1 of the ITU-T H.264 Specification;
-
-
if
flags.vui_parameters_present_flagis set, thenpSequenceParameterSetVuiis a pointer to aStdVideoH264SequenceParameterSetVuistructure that is interpreted as follows:-
reserved1is used only for padding purposes and is otherwise ignored; -
flags.color_description_present_flagis interpreted as the value ofcolour_description_present_flag, as defined in section E.2.1 of the ITU-T H.264 Specification;NoteThe name of
colour_description_present_flagwas misspelled in the Video Std header. -
if
flags.nal_hrd_parameters_present_flagorflags.vcl_hrd_parameters_present_flagis set, then theStdVideoH264HrdParametersstructure pointed to bypHrdParametersis interpreted as follows:-
reserved1is used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoH264HrdParametersare interpreted as defined in section E.2.2 of the ITU-T H.264 Specification;
-
-
all other members of
StdVideoH264SequenceParameterSetVuiare interpreted as defined in section E.2.1 of the ITU-T H.264 Specification;
-
-
all other members of
StdVideoH264SequenceParameterSetare interpreted as defined in section 7.4.2.1 of the ITU-T H.264 Specification.
-
- H.264 Picture Parameter Sets (PPS)
-
Represented by
StdVideoH264PictureParameterSetstructures and interpreted as follows:-
the pair constructed from
seq_parameter_set_idandpic_parameter_set_idis used as the key of the PPS entry; -
if
flags.pic_scaling_matrix_present_flagis set, then theStdVideoH264ScalingListsstructure pointed to bypScalingListsis interpreted as follows:-
scaling_list_present_maskis a bitmask where bit index i corresponds topic_scaling_list_present_flag[i]as defined in section 7.4.2.2 of the ITU-T H.264 Specification; -
use_default_scaling_matrix_maskis a bitmask where bit index i corresponds toUseDefaultScalingMatrix4x4Flag[i], when i < 6, or corresponds toUseDefaultScalingMatrix8x8Flag[i-6], otherwise, as defined in section 7.3.2.2 of the ITU-T H.264 Specification; -
ScalingList4x4andScalingList8x8correspond to the identically named syntax elements defined in section 7.3.2.2 of the ITU-T H.264 Specification;
-
-
all other members of
StdVideoH264PictureParameterSetare interpreted as defined in section 7.4.2.2 of the ITU-T H.264 Specification.
-
Implementations may override any of these parameters according to the semantics defined in the Video Encode Parameter Overrides section before storing the resulting H.264 parameter sets into the video session parameters object. Applications need to use the vkGetEncodedVideoSessionParametersKHR command to determine whether any implementation overrides happened and to retrieve the encoded H.264 parameter sets in order to be able to produce a compliant H.264 video bitstream.
Such H.264 parameter set overrides may also have cascading effects on the
implementation overrides applied to the encoded bitstream produced by video
encode operations.
If the implementation supports the
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR
video encode feedback query flag, then the
application can use such queries to retrieve feedback about whether any
implementation overrides have been applied to the encoded bitstream.
When a video session parameters object is
created with the codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the
VkVideoSessionParametersCreateInfoKHR::pNext chain must include
a VkVideoEncodeH264SessionParametersCreateInfoKHR structure specifying
the capacity and initial contents of the object.
The VkVideoEncodeH264SessionParametersCreateInfoKHR structure is
defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264SessionParametersCreateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t maxStdSPSCount;
uint32_t maxStdPPSCount;
const VkVideoEncodeH264SessionParametersAddInfoKHR* pParametersAddInfo;
} VkVideoEncodeH264SessionParametersCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxStdSPSCountis the maximum number of H.264 SPS entries the createdVkVideoSessionParametersKHRcan contain. -
maxStdPPSCountis the maximum number of H.264 PPS entries the createdVkVideoSessionParametersKHRcan contain. -
pParametersAddInfoisNULLor a pointer to a VkVideoEncodeH264SessionParametersAddInfoKHR structure specifying H.264 parameters to add upon object creation.
The VkVideoEncodeH264SessionParametersAddInfoKHR structure is defined
as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264SessionParametersAddInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t stdSPSCount;
const StdVideoH264SequenceParameterSet* pStdSPSs;
uint32_t stdPPSCount;
const StdVideoH264PictureParameterSet* pStdPPSs;
} VkVideoEncodeH264SessionParametersAddInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdSPSCountis the number of elements in thepStdSPSsarray. -
pStdSPSsis a pointer to an array ofStdVideoH264SequenceParameterSetstructures describing the H.264 SPS entries to add. -
stdPPSCountis the number of elements in thepStdPPSsarray. -
pStdPPSsis a pointer to an array ofStdVideoH264PictureParameterSetstructures describing the H.264 PPS entries to add.
This structure can be specified in the following places:
-
In the
pParametersAddInfomember of the VkVideoEncodeH264SessionParametersCreateInfoKHR structure specified in thepNextchain of VkVideoSessionParametersCreateInfoKHR used to create a video session parameters object. In this case, if the video codec operation the video session parameters object is created with isVK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then it defines the set of initial parameters to add to the created object (see Creating Video Session Parameters). -
In the
pNextchain of VkVideoSessionParametersUpdateInfoKHR. In this case, if the video codec operation the video session parameters object to be updated was created with isVK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then it defines the set of parameters to add to it (see Updating Video Session Parameters).
The VkVideoEncodeH264SessionParametersGetInfoKHR structure is defined
as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264SessionParametersGetInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 writeStdSPS;
VkBool32 writeStdPPS;
uint32_t stdSPSId;
uint32_t stdPPSId;
} VkVideoEncodeH264SessionParametersGetInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
writeStdSPSindicates whether the encoded H.264 sequence parameter set identified bystdSPSIdis requested to be retrieved. -
writeStdPPSindicates whether the encoded H.264 picture parameter set identified by the pair constructed fromstdSPSIdandstdPPSIdis requested to be retrieved. -
stdSPSIdspecifies the H.264 sequence parameter set ID used to identify the retrieved H.264 sequence and/or picture parameter set(s). -
stdPPSIdspecifies the H.264 picture parameter set ID used to identify the retrieved H.264 picture parameter set whenwriteStdPPSisVK_TRUE.
When this structure is specified in the pNext chain of the
VkVideoEncodeSessionParametersGetInfoKHR structure passed to
vkGetEncodedVideoSessionParametersKHR, the command will write encoded
parameter data to the output buffer in the following order:
-
The H.264 sequence parameter set identified by
stdSPSId, ifwriteStdSPSisVK_TRUE. -
The H.264 picture parameter set identified by the pair constructed from
stdSPSIdandstdPPSId, ifwriteStdPPSisVK_TRUE.
The VkVideoEncodeH264SessionParametersFeedbackInfoKHR structure is
defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264SessionParametersFeedbackInfoKHR {
VkStructureType sType;
void* pNext;
VkBool32 hasStdSPSOverrides;
VkBool32 hasStdPPSOverrides;
} VkVideoEncodeH264SessionParametersFeedbackInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
hasStdSPSOverridesindicates whether any of the parameters of the requested H.264 sequence parameter set, if one was requested via VkVideoEncodeH264SessionParametersGetInfoKHR::writeStdSPS, were overridden by the implementation. -
hasStdPPSOverridesindicates whether any of the parameters of the requested H.264 picture parameter set, if one was requested via VkVideoEncodeH264SessionParametersGetInfoKHR::writeStdPPS, were overridden by the implementation.
43.20.11. H.264 Encoding Parameters
The VkVideoEncodeH264PictureInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264PictureInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t naluSliceEntryCount;
const VkVideoEncodeH264NaluSliceInfoKHR* pNaluSliceEntries;
const StdVideoEncodeH264PictureInfo* pStdPictureInfo;
VkBool32 generatePrefixNalu;
} VkVideoEncodeH264PictureInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
naluSliceEntryCountis the number of elements inpNaluSliceEntries. -
pNaluSliceEntriesis a pointer to an array ofnaluSliceEntryCountVkVideoEncodeH264NaluSliceInfoKHR structures specifying the parameters of the individual H.264 slices to encode for the input picture. -
pStdPictureInfois a pointer to aStdVideoEncodeH264PictureInfostructure specifying H.264 picture information. -
generatePrefixNalucontrols whether prefix NALUs are generated before slice NALUs into the target bitstream, as defined in sections 7.3.2.12 and 7.4.2.12 of the ITU-T H.264 Specification.
This structure is specified in the pNext chain of the
VkVideoEncodeInfoKHR structure passed to vkCmdEncodeVideoKHR to
specify the codec-specific picture information for an H.264
encode operation.
- Encode Input Picture Information
-
When this structure is specified in the
pNextchain of the VkVideoEncodeInfoKHR structure passed to vkCmdEncodeVideoKHR, the information related to the encode input picture is defined as follows:-
The image subregion used is determined according to the H.264 Encode Picture Data Access section.
-
The encode input picture is associated with the H.264 picture information provided in
pStdPictureInfo.
-
- Std Picture Information
-
The members of the
StdVideoEncodeH264PictureInfostructure pointed to bypStdPictureInfoare interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
flags.IdrPicFlagas defined in section 7.4.1 of the ITU-T H.264 Specification; -
flags.is_referenceas defined in section 3.136 of the ITU-T H.264 Specification; -
seq_parameter_set_idandpic_parameter_set_idare used to identify the active parameter sets, as described below; -
primary_pic_typeas defined in section 7.4.2 of the ITU-T H.264 Specification; -
PicOrderCntas defined in section 8.2 of the ITU-T H.264 Specification; -
temporal_idas defined in section G.7.4.1.1 of the ITU-T H.264 Specification; -
if
pRefListsis notNULL, then it is a pointer to aStdVideoEncodeH264ReferenceListsInfostructure that is interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
ref_pic_list_modification_flag_l0andref_pic_list_modification_flag_l1as defined in section 7.4.3.1 of the ITU-T H.264 Specification; -
num_ref_idx_l0_active_minus1andnum_ref_idx_l1_active_minus1as defined in section 7.4.3 of the ITU-T H.264 Specification; -
RefPicList0andRefPicList1as defined in section 8.2.4 of the ITU-T H.264 Specification where each element of these arrays either identifies an active reference picture using its DPB slot index or contains the valueSTD_VIDEO_H264_NO_REFERENCE_PICTUREto indicate “no reference picture”; -
if
refList0ModOpCountis not zero, thenpRefList0ModOperationsis a pointer to an array ofrefList0ModOpCountnumber ofStdVideoEncodeH264RefListModEntrystructures specifying the modification parameters for the reference list L0 as defined in section 7.4.3.1 of the ITU-T H.264 Specification; -
if
refList1ModOpCountis not zero, thenpRefList1ModOperationsis a pointer to an array ofrefList1ModOpCountnumber ofStdVideoEncodeH264RefListModEntrystructures specifying the modification parameters for the reference list L1 as defined in section 7.4.3.1 of the ITU-T H.264 Specification; -
if
refPicMarkingOpCountis not zero, thenrefPicMarkingOperationsis a pointer to an array ofrefPicMarkingOpCountnumber ofStdVideoEncodeH264RefPicMarkingEntrystructures specifying the reference picture marking parameters as defined in section 7.4.3.3 of the ITU-T H.264 Specification;
-
-
all other members are interpreted as defined in section 7.4.3 of the ITU-T H.264 Specification.
-
Reference picture setup is controlled by the value of
StdVideoEncodeH264PictureInfo::flags.is_reference.
If it is set and a reconstructed
picture is specified, then the latter is used as the target of picture
reconstruction to activate the DPB slot
specified in pEncodeInfo->pSetupReferenceSlot->slotIndex.
If StdVideoEncodeH264PictureInfo::flags.is_reference is not set,
but a reconstructed picture is
specified, then the corresponding picture reference associated with the
DPB slot is invalidated, as described in the
DPB Slot States section.
- Active Parameter Sets
-
The members of the
StdVideoEncodeH264PictureInfostructure pointed to bypStdPictureInfoare used to select the active parameter sets to use from the bound video session parameters object, as follows:-
The active SPS is the SPS identified by the key specified in
StdVideoEncodeH264PictureInfo::seq_parameter_set_id. -
The active PPS is the PPS identified by the key specified by the pair constructed from
StdVideoEncodeH264PictureInfo::seq_parameter_set_idandStdVideoEncodeH264PictureInfo::pic_parameter_set_id.
-
H.264 encoding uses explicit weighted sample prediction for a slice, as
defined in section 8.4.2.3 of the ITU-T H.264 Specification,
if any of the following conditions are true for the active
PPS and the pStdSliceHeader member of the
corresponding element of pNaluSliceEntries:
-
pStdSliceHeader->slice_typeisSTD_VIDEO_H264_SLICE_TYPE_Pandweighted_pred_flagis enabled in the active PPS. -
pStdSliceHeader->slice_typeisSTD_VIDEO_H264_SLICE_TYPE_Bandweighted_bipred_idcin the active PPS equalsSTD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT.
The VkVideoEncodeH264NaluSliceInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264NaluSliceInfoKHR {
VkStructureType sType;
const void* pNext;
int32_t constantQp;
const StdVideoEncodeH264SliceHeader* pStdSliceHeader;
} VkVideoEncodeH264NaluSliceInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
constantQpis the QP to use for the slice if the current rate control mode configured for the video session isVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. -
pStdSliceHeaderis a pointer to aStdVideoEncodeH264SliceHeaderstructure specifying H.264 slice header parameters for the slice.
- Std Slice Header Parameters
-
The members of the
StdVideoEncodeH264SliceHeaderstructure pointed to bypStdSliceHeaderare interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
if
pWeightTableis notNULL, then it is a pointer to aStdVideoEncodeH264WeightTablethat is interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoEncodeH264WeightTableare interpreted as defined in section 7.4.3.2 of the ITU-T H.264 Specification;
-
-
all other members are interpreted as defined in section 7.4.3 of the ITU-T H.264 Specification.
-
The VkVideoEncodeH264DpbSlotInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264DpbSlotInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoEncodeH264ReferenceInfo* pStdReferenceInfo;
} VkVideoEncodeH264DpbSlotInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdReferenceInfois a pointer to aStdVideoEncodeH264ReferenceInfostructure specifying H.264 reference information.
This structure is specified in the pNext chain of
VkVideoEncodeInfoKHR::pSetupReferenceSlot, if not NULL, and
the pNext chain of the elements of
VkVideoEncodeInfoKHR::pReferenceSlots to specify the
codec-specific reference picture information for an H.264
encode operation.
- Active Reference Picture Information
-
When this structure is specified in the
pNextchain of the elements of VkVideoEncodeInfoKHR::pReferenceSlots, one element is added to the list of active reference pictures used by the video encode operation for each element of VkVideoEncodeInfoKHR::pReferenceSlotsas follows:-
The image subregion used is determined according to the H.264 Encode Picture Data Access section.
-
The reference picture is associated with the DPB slot index specified in the
slotIndexmember of the corresponding element of VkVideoEncodeInfoKHR::pReferenceSlots. -
The reference picture is associated with the H.264 reference information provided in
pStdReferenceInfo.
-
- Reconstructed Picture Information
-
When this structure is specified in the
pNextchain of VkVideoEncodeInfoKHR::pSetupReferenceSlot, the information related to the reconstructed picture is defined as follows:-
The image subregion used is determined according to the H.264 Encode Picture Data Access section.
-
If reference picture setup is requested, then the reconstructed picture is used to activate the DPB slot with the index specified in VkVideoEncodeInfoKHR::
pSetupReferenceSlot->slotIndex. -
The reconstructed picture is associated with the H.264 reference information provided in
pStdReferenceInfo.
-
- Std Reference Information
-
The members of the
StdVideoEncodeH264ReferenceInfostructure pointed to bypStdReferenceInfoare interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
flags.used_for_long_term_referenceis used to indicate whether the picture is marked as “used for long-term reference” as defined in section 8.2.5.1 of the ITU-T H.264 Specification; -
primary_pic_typeas defined in section 7.4.2 of the ITU-T H.264 Specification; -
long_term_pic_numandlong_term_frame_idxas defined in section 7.4.3 of the ITU-T H.264 Specification; -
temporal_idas defined in section G.7.4.1.1 of the ITU-T H.264 Specification; -
all other members are interpreted as defined in section 8.2 of the ITU-T H.264 Specification.
-
43.20.12. H.264 Encode Rate Control
Group of Pictures
In case of H.264 encoding it is common practice to follow a regular pattern of different picture types in display order when encoding subsequent frames. This pattern is referred to as the group of pictures (GOP).
A regular GOP is defined by the following parameters:
-
The number of frames in the GOP;
-
The number of consecutive B frames between I and/or P frames in display order.
GOPs are further classified as open and closed GOPs.
Frame types in an open GOP follow each other in display order according to the following algorithm:
-
The first frame is always an I frame.
-
This is followed by a number of consecutive B frames, as defined above.
-
If the number of frames in the GOP is not reached yet, then the next frame is a P frame and the algorithm continues from step 2.
In case of a closed GOP, an IDR frame is used at a certain period.
It is also typical for H.264 encoding to use specific reference picture usage patterns across the frames of the GOP. The two most common reference patterns used are as follows:
- Flat Reference Pattern
-
-
Each P frame uses the last non-B frame, in display order, as reference.
-
Each B frame uses the last non-B frame, in display order, as its forward reference, and uses the next non-B frame, in display order, as its backward reference.
-
- Dyadic Reference Pattern
-
-
Each P frame uses the last non-B frame, in display order, as reference.
-
The following algorithm is applied to the sequence of consecutive B frames between I and/or P frames in display order:
-
The B frame in the middle of this sequence uses the frame preceding the sequence as its forward reference, and uses the frame following the sequence as its backward reference.
-
The algorithm is executed recursively for the following frame sequences:
-
The B frames of the original sequence preceding the frame in the middle, if any.
-
The B frames of the original sequence following the frame in the middle, if any.
-
-
-
The application can provide guidance to the implementation’s rate control algorithm about the structure of the GOP used by the application. Any such guidance about the GOP and its structure does not mandate that specific GOP structure to be used by the application, as the picture type of individual encoded pictures is still application-controlled, however, any deviation from the provided guidance may result in undesired rate control behavior including, but not limited, to the implementation not being able to conform to the expected average or target bitrates, or other rate control parameters specified by the application.
When an H.264 encode session is used to encode multiple temporal layers, it is also common practice to follow a regular pattern for the H.264 temporal ID for the encoded pictures in display order when encoding subsequent frames. This pattern is referred to as the temporal GOP. The most common temporal layer pattern used is as follows:
- Dyadic Temporal Layer Pattern
-
-
The number of frames in the temporal GOP is 2n-1, where n is the number of temporal layers.
-
The ith frame in the temporal GOP uses temporal ID t, if and only if the index of the least significant bit set in i equals n-t-1, except for the first frame, which is the only frame in the temporal GOP using temporal ID zero.
-
The ith frame in the temporal GOP uses the rth frame as reference, where r is calculated from i by clearing the least significant bit set in it, except for the first frame in the temporal GOP, which uses the first frame of the previous temporal GOP, if any, as reference.
-
|
Note
|
Multi-layer rate control and multi-layer coding are typically used for streaming cases where low latency is expected, hence B pictures with backward prediction are usually not used. |
The VkVideoEncodeH264RateControlInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264RateControlInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeH264RateControlFlagsKHR flags;
uint32_t gopFrameCount;
uint32_t idrPeriod;
uint32_t consecutiveBFrameCount;
uint32_t temporalLayerCount;
} VkVideoEncodeH264RateControlInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeH264RateControlFlagBitsKHR specifying H.264 rate control flags. -
gopFrameCountis the number of frames within a group of pictures (GOP) intended to be used by the application. If it is 0, the rate control algorithm may assume an implementation-dependent GOP length. If it isUINT32_MAX, the GOP length is treated as infinite. -
idrPeriodis the interval, in terms of number of frames, between two IDR frames (see IDR period). If it is 0, the rate control algorithm may assume an implementation-dependent IDR period. If it isUINT32_MAX, the IDR period is treated as infinite. -
consecutiveBFrameCountis the number of consecutive B frames between I and/or P frames within the GOP. -
temporalLayerCountspecifies the number of H.264 temporal layers that the application intends to use.
When an instance of this structure is included in the pNext chain of
the VkVideoCodingControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command, and
VkVideoCodingControlInfoKHR::flags includes
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, the parameters in
this structure are used as guidance for the implementation’s rate control
algorithm (see Video Coding Control).
If flags includes
VK_VIDEO_ENCODE_H264_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR, then
the rate control state is reset to an initial state to meet HRD compliance
requirements.
Otherwise the new rate control state may be applied without a reset
depending on the implementation and the specified rate control parameters.
|
Note
|
It would be possible to infer the picture type to be used when encoding a
frame, on the basis of the values provided for |
Bits which can be set in
VkVideoEncodeH264RateControlInfoKHR::flags, specifying H.264
rate control flags, are:
// Provided by VK_KHR_video_encode_h264
typedef enum VkVideoEncodeH264RateControlFlagBitsKHR {
VK_VIDEO_ENCODE_H264_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_H264_RATE_CONTROL_REGULAR_GOP_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR = 0x00000008,
VK_VIDEO_ENCODE_H264_RATE_CONTROL_TEMPORAL_LAYER_PATTERN_DYADIC_BIT_KHR = 0x00000010,
} VkVideoEncodeH264RateControlFlagBitsKHR;
-
VK_VIDEO_ENCODE_H264_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHRspecifies that rate control should attempt to produce an HRD compliant bitstream, as defined in annex C of the ITU-T H.264 Specification. -
VK_VIDEO_ENCODE_H264_RATE_CONTROL_REGULAR_GOP_BIT_KHRspecifies that the application intends to use a regular GOP structure according to the parameters specified in thegopFrameCount,idrPeriod, andconsecutiveBFrameCountmembers of the VkVideoEncodeH264RateControlInfoKHR structure. -
VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHRspecifies that the application intends to follow a flat reference pattern in the GOP. -
VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHRspecifies that the application intends to follow a dyadic reference pattern in the GOP. -
VK_VIDEO_ENCODE_H264_RATE_CONTROL_TEMPORAL_LAYER_PATTERN_DYADIC_BIT_KHRspecifies that the application intends to follow a dyadic temporal layer pattern.
// Provided by VK_KHR_video_encode_h264
typedef VkFlags VkVideoEncodeH264RateControlFlagsKHR;
VkVideoEncodeH264RateControlFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoEncodeH264RateControlFlagBitsKHR.
Rate Control Layers
The VkVideoEncodeH264RateControlLayerInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264RateControlLayerInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 useMinQp;
VkVideoEncodeH264QpKHR minQp;
VkBool32 useMaxQp;
VkVideoEncodeH264QpKHR maxQp;
VkBool32 useMaxFrameSize;
VkVideoEncodeH264FrameSizeKHR maxFrameSize;
} VkVideoEncodeH264RateControlLayerInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
useMinQpindicates whether the QP values determined by rate control will be clamped to the lower bounds on the QP values specified inminQp. -
minQpspecifies the lower bounds on the QP values, for each picture type, that the implementation’s rate control algorithm will use whenuseMinQpisVK_TRUE. -
useMaxQpindicates whether the QP values determined by rate control will be clamped to the upper bounds on the QP values specified inmaxQp. -
maxQpspecifies the upper bounds on the QP values, for each picture type, that the implementation’s rate control algorithm will use whenuseMaxQpisVK_TRUE. -
useMaxFrameSizeindicates whether the implementation’s rate control algorithm should use the values specified inmaxFrameSizeas the upper bounds on the encoded frame size for each picture type. -
maxFrameSizespecifies the upper bounds on the encoded frame size, for each picture type, whenuseMaxFrameSizeisVK_TRUE.
When used, the values in minQp and maxQp guarantee that the
effective QP values used by the implementation will respect those lower and
upper bounds, respectively.
However, limiting the range of QP values that the implementation is able to
use will also limit the capabilities of the implementation’s rate control
algorithm to comply to other constraints.
In particular, the implementation may not be able to comply to the
following:
-
The average and/or peak bitrate values to be used for the encoded bitstream specified in the
averageBitrateandmaxBitratemembers of the VkVideoEncodeRateControlLayerInfoKHR structure. -
The upper bounds on the encoded frame size, for each picture type, specified in the
maxFrameSizemember ofVkVideoEncodeH264RateControlLayerInfoKHR.
|
Note
|
In general, applications need to configure rate control parameters appropriately in order to be able to get the desired rate control behavior, as described in the Video Encode Rate Control section. |
When an instance of this structure is included in the pNext chain of a
VkVideoEncodeRateControlLayerInfoKHR structure specified in one of the
elements of the pLayers array member of the
VkVideoEncodeRateControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command,
VkVideoCodingControlInfoKHR::flags includes
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, and the bound
video session was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, it specifies the
H.264-specific rate control parameters of the rate control layer
corresponding to that element of pLayers.
The VkVideoEncodeH264QpKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264QpKHR {
int32_t qpI;
int32_t qpP;
int32_t qpB;
} VkVideoEncodeH264QpKHR;
-
qpIis the QP to be used for I pictures. -
qpPis the QP to be used for P pictures. -
qpBis the QP to be used for B pictures.
The VkVideoEncodeH264FrameSizeKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264FrameSizeKHR {
uint32_t frameISize;
uint32_t framePSize;
uint32_t frameBSize;
} VkVideoEncodeH264FrameSizeKHR;
-
frameISizeis the size in bytes to be used for I pictures. -
framePSizeis the size in bytes to be used for P pictures. -
frameBSizeis the size in bytes to be used for B pictures.
GOP Remaining Frames
Besides session level rate control configuration, the application can specify the number of frames per frame type remaining in the group of pictures (GOP).
The VkVideoEncodeH264GopRemainingFrameInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h264
typedef struct VkVideoEncodeH264GopRemainingFrameInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 useGopRemainingFrames;
uint32_t gopRemainingI;
uint32_t gopRemainingP;
uint32_t gopRemainingB;
} VkVideoEncodeH264GopRemainingFrameInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
useGopRemainingFramesindicates whether the implementation’s rate control algorithm should use the values specified ingopRemainingI,gopRemainingP, andgopRemainingB. IfuseGopRemainingFramesisVK_FALSE, then the values ofgopRemainingI,gopRemainingP, andgopRemainingBare ignored. -
gopRemainingIspecifies the number of I frames the implementation’s rate control algorithm should assume to be remaining in the GOP prior to executing the video encode operation. -
gopRemainingPspecifies the number of P frames the implementation’s rate control algorithm should assume to be remaining in the GOP prior to executing the video encode operation. -
gopRemainingBspecifies the number of B frames the implementation’s rate control algorithm should assume to be remaining in the GOP prior to executing the video encode operation.
Setting useGopRemainingFrames to VK_TRUE and including this
structure in the pNext chain of VkVideoBeginCodingInfoKHR is
only mandatory if the
VkVideoEncodeH264CapabilitiesKHR::requiresGopRemainingFrames
reported for the used video profile is VK_TRUE.
However, implementations may use these remaining frame counts, when
specified, even when it is not required.
In particular, when the application does not use a
regular GOP structure, these values may provide
additional guidance for the implementation’s rate control algorithm.
The VkVideoEncodeH264CapabilitiesKHR::prefersGopRemainingFrames
capability is also used to indicate that the implementation’s rate control
algorithm may operate more accurately if the application specifies the
remaining frame counts using this structure.
As with other rate control guidance values, if the effective order and number of frames encoded by the application are not in line with the remaining frame counts specified in this structure at any given point, then the behavior of the implementation’s rate control algorithm may deviate from the one expected by the application.
H.264 QP Delta Maps
Quantization delta maps used with an H.264 encode profile are referred to as QP delta maps and their texels contain integer values representing QP delta values that are applied in the process of determining the quantization parameters of the encoded picture.
Accordingly, H.264 QP delta maps always have single channel integer formats,
as reported in VkVideoFormatPropertiesKHR::format.
When the rate control mode is
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, the QP delta
values are added to the per slice constant QP values that, in effect, enable
the application to explicitly control the used QP values at the granularity
of the used quantization map texel
size.
For all other rate control modes, the QP delta values can be used to offset the QP values that the rate control algorithm would otherwise produce.
H.264 Encode Quantization
Performing H.264 encode operations involves the process of assigning QP values to individual H.264 macroblocks. This process depends on the used rate control mode, as well as other encode and rate control parameters, as described below:
-
If the configured rate control mode is
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR, then the QP value is initialized by the implementation-specific default rate control algorithm.-
If the video encode operation is issued with a quantization delta map, the QP delta value corresponding to the macroblock, as fetched from the quantization map, is added to the previously determined QP value. If the fetched QP delta value falls outside the supported QP delta value range reported in the
minQpDeltaandmaxQpDeltamembers of VkVideoEncodeH264QuantizationMapCapabilitiesKHR, then the QP value used for the macroblock becomes undefined.
-
-
If the configured rate control mode is
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then the QP value is initialized from the constant QP value specified for the H.264 slice the macroblock is part of.-
If the video encode operation is issued with a quantization delta map, the QP delta value corresponding to the macroblock, as fetched from the quantization map, is added to the previously determined QP value. If the fetched QP delta value falls outside the supported QP delta value range reported in the
minQpDeltaandmaxQpDeltamembers of VkVideoEncodeH264QuantizationMapCapabilitiesKHR, then the QP value used for the macroblock becomes undefined.
-
-
If the configured rate control mode is not
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHRorVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then the QP value is initialized by the corresponding rate control algorithm.-
If the video encode operation is issued with a quantization delta map, the QP delta value corresponding to the macroblock, as fetched from the quantization map, is added to the previously determined QP value. If the fetched QP delta value falls outside the supported QP delta value range reported in the
minQpDeltaandmaxQpDeltamembers of VkVideoEncodeH264QuantizationMapCapabilitiesKHR, then the QP value used for the macroblock becomes undefined. -
If the video encode operation is issued with an emphasis map, the rate control will adjust the QP value based on the emphasis value corresponding to the macroblock, as fetched from the quantization map, according to the following equation:
QPnew = f(QPprev,e)
Where QPnew is the resulting QP value, QPprev is the previously determined QP value, e is the emphasis value corresponding to the macroblock, and f is an implementation-defined function for which the following implication is true:
e1 < e2 ⇒ f(QP,e1) ≥ f(QP,e2)
NoteThis means that lower emphasis values will result in higher QP values, whereas higher emphasis values will result in lower QP values, but the function is not strictly decreasing with respect to the input emphasis value for a given input QP value.
-
If clamping to minimum QP values is enabled in the applied rate control layer, then the QP value is clamped to the corresponding minimum QP value.
-
If clamping to maximum QP values is enabled in the applied rate control layer, then the QP value is clamped to the corresponding maximum QP value.
-
-
If
VK_VIDEO_ENCODE_H264_CAPABILITY_MB_QP_DIFF_WRAPAROUND_BIT_KHRis not supported, then the determined QP value is clamped in such a way that themb_qp_deltavalue of the encoded macroblock complies to the modified version of equation 7-37 of the ITU-T H.264 Specification.NoteThe effect of this is that the maximum QP difference across subsequent macroblocks is limited to the [-(26 + QpBdOffsetY / 2), 25 + QpBdOffsetY / 2] range and only has an observable change in behavior when the video encode operation is issued with a QP delta map.
-
In all cases, the final QP value is clamped to the QP value range supported by the video profile, as reported in the
minQpandmaxQpmembers of VkVideoEncodeH264CapabilitiesKHR.
43.20.13. H.264 Encode Requirements
This section described the required H.264 encoding capabilities for
physical devices that have at least one queue family that supports the video
codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, as
returned by vkGetPhysicalDeviceQueueFamilyProperties2 in
VkQueueFamilyVideoPropertiesKHR::videoCodecOperations.
| Video Std Header Name | Version |
|---|---|
|
1.0.0 |
| Video Capability | Requirement | Requirement Type1 |
|---|---|---|
|
- |
min |
|
4096 |
max |
|
4096 |
max |
|
(64,64) |
max |
|
- |
max |
|
- |
min |
|
0 |
min |
|
0 |
min |
|
- |
min |
|
|
min |
|
64000 |
min |
|
1 |
min |
|
(64,64) |
max |
|
|
min |
|
- |
min |
|
|
min |
|
1 |
min |
|
0 |
min |
|
0 |
min |
|
0 |
min |
|
1 |
min |
|
- |
implementation-dependent |
|
- |
max |
|
- |
min |
|
- |
implementation-dependent |
|
- |
implementation-dependent |
|
- |
min |
|
- 2 |
min |
|
- 3 |
max |
|
- 3 |
min |
|
0 |
min |
|
2 5 |
min |
|
1 5 |
min |
|
- |
implementation-dependent |
|
- |
implementation-dependent |
- 1
-
The Requirement Type column specifies the requirement is either the minimum value all implementations must support, the maximum value all implementations must support, or the exact value all implementations must support. For bitmasks a minimum value is the least bits all implementations must set, but they may have additional bits set beyond this minimum.
- 2
-
If VkVideoCapabilitiesKHR::
flagsincludesVK_VIDEO_ENCODE_CAPABILITY_QUANTIZATION_DELTA_MAP_BIT_KHRorVK_VIDEO_ENCODE_CAPABILITY_EMPHASIS_MAP_BIT_KHR, then thewidthandheightmembers ofmaxQuantizationMapExtentmust be greater than zero. - 3
-
If VkVideoCapabilitiesKHR::
flagsincludesVK_VIDEO_ENCODE_CAPABILITY_QUANTIZATION_DELTA_MAP_BIT_KHR, thenmaxQpDeltamust be greater thanminQpDelta. - 4
-
If the
videoMaintenance2feature is supported. - 5
-
If VkVideoEncodeIntraRefreshCapabilitiesKHR::
intraRefreshModesis not zero.
43.21. H.265 Encode Operations
Video encode operations using an H.265 encode profile can be used to encode elementary video stream sequences compliant to the ITU-T H.265 Specification.
|
Note
|
Refer to the Preamble for information on how the Khronos Intellectual Property Rights Policy relates to normative references to external materials not created by Khronos. |
This process is performed according to the video encode operation steps with the codec-specific semantics defined in section 8 of the ITU-T H.265 Specification as follows:
-
Syntax elements, derived values, and other parameters are applied from the following structures:
-
The
StdVideoH265VideoParameterSetstructure corresponding to the active VPS specifying the H.265 video parameter set. -
The
StdVideoH265SequenceParameterSetstructure corresponding to the active SPS specifying the H.265 sequence parameter set. -
The
StdVideoH265PictureParameterSetstructure corresponding to the active PPS specifying the H.265 picture parameter set. -
The
StdVideoEncodeH265PictureInfostructure specifying the H.265 picture information. -
The
StdVideoEncodeH265SliceSegmentHeaderstructures specifying the H.265 slice segment header parameters for each encoded H.265 slice segment. -
The
StdVideoEncodeH265ReferenceInfostructures specifying the H.265 reference information corresponding to the optional reconstructed picture and any active reference pictures.
-
-
The encoded bitstream data is written to the destination video bitstream buffer range as defined in the H.265 Encode Bitstream Data Access section.
-
Picture data in the video picture resources corresponding to the used encode input picture, active reference pictures, and optional reconstructed picture is accessed as defined in the H.265 Encode Picture Data Access section.
-
The decision on reference picture setup is made according to the parameters specified in the H.265 picture information.
If the parameters adhere to the syntactic and semantic requirements defined in the corresponding sections of the ITU-T H.265 Specification, as described above, and the DPB slots associated with the active reference pictures all refer to valid picture references, then the video encode operation will complete successfully. Otherwise, the video encode operation may complete unsuccessfully.
43.21.1. H.265 Encode Parameter Overrides
Implementations may override, unless otherwise specified, any of the H.265 encode parameters specified in the following Video Std structures:
-
StdVideoH265VideoParameterSet -
StdVideoH265SequenceParameterSet -
StdVideoH265PictureParameterSet -
StdVideoEncodeH265PictureInfo -
StdVideoEncodeH265SliceSegmentHeader -
StdVideoEncodeH265ReferenceInfo
All such H.265 encode parameter overrides must fulfill the conditions defined in the Video Encode Parameter Overrides section.
In addition, implementations must not override any of the following H.265 encode parameters:
-
StdVideoEncodeH265PictureInfo::pic_type -
StdVideoEncodeH265SliceSegmentHeader::slice_type
If the videoMaintenance2 feature is
enabled, implementations must not override any of the following H.265
encode parameters:
-
the following parameters specified in the
StdVideoH265ProfileTierLevelstructure pointed to byStdVideoH265VideoParameterSet::pProfileTierLevelandStdVideoH265SequenceParameterSet::pProfileTierLevel:-
flags.general_tier_flag -
flags.general_progressive_source_flag, if set to1 -
flags.general_interlaced_source_flag, if set to0 -
flags.general_frame_only_constraint_flag -
general_profile_idc -
general_level_idc
-
-
the following parameters specified in
StdVideoH265SequenceParameterSet:-
chroma_format_idc
-
-
the following parameters specified in the
StdVideoH265SequenceParameterSetVuistructure pointed to byStdVideoH265SequenceParameterSet::pSequenceParameterSetVui:-
flags.aspect_ratio_info_present_flag -
flags.overscan_info_present_flag -
flags.overscan_appropriate_flag -
flags.video_signal_type_present_flag -
flags.video_full_range_flag -
flags.colour_description_present_flag -
flags.chroma_loc_info_present_flag -
flags.neutral_chroma_indication_flag -
flags.field_seq_flag -
flags.frame_field_info_present_flag -
flags.default_display_window_flag -
flags.vui_timing_info_present_flag -
flags.vui_poc_proportional_to_timing_flag -
aspect_ratio_idc -
sar_width -
sar_height -
video_format -
colour_primaries -
transfer_characteristics -
matrix_coeffs -
chroma_sample_loc_type_top_field -
chroma_sample_loc_type_bottom_field -
def_disp_win_left_offset -
def_disp_win_right_offset -
def_disp_win_top_offset -
def_disp_win_bottom_offset -
vui_num_units_in_tick -
vui_time_scale -
vui_num_ticks_poc_diff_one_minus1
-
In case of a video session parameters object
created with
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR,
the following H.265 SPS and PPS
parameters may be overridden by the implementation according to the
quantization map texel size the video
session parameters object was created with:
-
StdVideoH265SequenceParameterSet::log2_min_luma_coding_block_size_minus3 -
StdVideoH265SequenceParameterSet::log2_diff_max_min_luma_coding_block_size -
StdVideoH265SequenceParameterSet::log2_min_pcm_luma_coding_block_size_minus3 -
StdVideoH265SequenceParameterSet::log2_diff_max_min_pcm_luma_coding_block_size -
StdVideoH265PictureParameterSet::diff_cu_qp_delta_depth
This may be necessary in order to limit the set of H.265 coding unit and coding tree unit sizes used during picture encoding to those that are supported by the implementation when using the specific quantization map texel size.
In case of H.265 encode parameters stored in video session parameters objects, applications need to use the vkGetEncodedVideoSessionParametersKHR command to determine whether any implementation overrides happened. If the query indicates that implementation overrides were applied, then the application needs to retrieve and use the encoded H.265 parameter sets in the bitstream in order to be able to produce a compliant H.265 video bitstream using the H.265 encode parameters stored in the video session parameters object.
In case of any H.265 encode parameters stored in the encoded bitstream
produced by video encode operations, if the implementation supports the
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR
video encode feedback query flag, the
application can use such queries to retrieve feedback about whether any
implementation overrides have been applied to those H.265 encode parameters.
43.21.2. H.265 Encode Bitstream Data Access
Each video encode operation writes one or more VCL NAL units comprising of
slice segment headers and data of the encoded picture, in the format defined
in sections 7.3.6 and 7.3.8, according to the semantics defined in sections
7.4.7 and 7.4.9 of the ITU-T H.265 Specification,
respectively.
The number of VCL NAL units written is specified by
VkVideoEncodeH265PictureInfoKHR::naluSliceSegmentEntryCount.
43.21.3. H.265 Encode Picture Data Access
Accesses to image data within a video picture resource happen at the
granularity indicated by
VkVideoCapabilitiesKHR::pictureAccessGranularity, as returned by
vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile.
Accordingly, the complete image subregion of a encode
input picture, reference picture, or
reconstructed picture accessed by video coding
operations using an H.265 encode profile is defined
as the set of texels within the coordinate range:
-
([0,
endX), [0,endY))
Where:
-
endXequalscodedExtent.widthrounded up to the nearest integer multiple ofpictureAccessGranularity.widthand clamped to the width of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure; -
endY equals
codedExtent.heightrounded up to the nearest integer multiple ofpictureAccessGranularity.heightand clamped to the height of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure;
Where codedExtent is the member of the
VkVideoPictureResourceInfoKHR structure corresponding to the picture.
In case of video encode operations using an H.265
encode profile, any access to a picture at the coordinates
(x,y), as defined by the ITU-T H.265
Specification, is an access to the image subresource
referred to by the corresponding
VkVideoPictureResourceInfoKHR structure at the texel coordinates
(x,y).
Implementations may choose not to access some or all texels within particular reference pictures available to a video encode operation (e.g. due to video encode parameter overrides restricting the effective set of used reference pictures, or if the encoding algorithm chooses not to use certain subregions of the reference picture data for sample prediction).
43.21.4. H.265 Frame, Picture, Slice Segments, and Tiles
H.265 pictures consist of one or more slices, slice segments, and tiles, as defined in section 6.3.1 of the ITU-T H.265 Specification.
For the purposes of this specification, the H.265 slice segments comprising a picture are referred to as the picture partitions of the picture.
Video encode operations using an H.265 encode
profile can encode slice segments of different types, as defined in
section 7.4.7.1 of the ITU-T H.265 Specification, by
specifying the corresponding enumeration constant value in
StdVideoEncodeH265SliceSegmentHeader::slice_type in the
H.265 slice segment header
parameters from the Video Std enumeration type StdVideoH265SliceType:
-
STD_VIDEO_H265_SLICE_TYPE_Bindicates that the slice segment is part of a B slice as defined in section 3.12 of the ITU-T H.265 Specification. -
STD_VIDEO_H265_SLICE_TYPE_Pindicates that the slice segment is part of a P slice as defined in section 3.111 of the ITU-T H.265 Specification. -
STD_VIDEO_H265_SLICE_TYPE_Iindicates that the slice segment is part of an I slice as defined in section 3.74 of the ITU-T H.265 Specification.
Pictures constructed from such slice segments can be of different types, as
defined in section 7.4.3.5 of the ITU-T H.265 Specification.
Video encode operations using an H.265 encode
profile can encode pictures of a specific type by specifying the
corresponding enumeration constant value in
StdVideoEncodeH265PictureInfo::pic_type in the
H.265 picture information from the Video Std
enumeration type StdVideoH265PictureType:
-
STD_VIDEO_H265_PICTURE_TYPE_Pindicates that the picture is a P picture. A frame consisting of a P picture is also referred to as a P frame. -
STD_VIDEO_H265_PICTURE_TYPE_Bindicates that the picture is a B picture. A frame consisting of a B picture is also referred to as a B frame. -
STD_VIDEO_H265_PICTURE_TYPE_Iindicates that the picture is an I picture. A frame consisting of an I picture is also referred to as an I frame. -
STD_VIDEO_H265_PICTURE_TYPE_IDRindicates that the picture is a special type of I picture called an IDR picture as defined in section 3.67 of the ITU-T H.265 Specification. A frame consisting of an IDR picture is also referred to as an IDR frame.
43.21.5. H.265 Coding Blocks
H.265 encode supports two types of coding blocks:
-
Coding tree unit, as defined in section 3.35 of the ITU-T H.265 Specification.
-
Coding unit, as defined in section 3.36 of the ITU-T H.265 Specification.
43.21.6. H.265 Encode Profile
A video profile supporting H.265 video encode operations is specified by
setting VkVideoProfileInfoKHR::videoCodecOperation to
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and adding a
VkVideoEncodeH265ProfileInfoKHR structure to the
VkVideoProfileInfoKHR::pNext chain.
The VkVideoEncodeH265ProfileInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265ProfileInfoKHR {
VkStructureType sType;
const void* pNext;
StdVideoH265ProfileIdc stdProfileIdc;
} VkVideoEncodeH265ProfileInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileIdcis aStdVideoH265ProfileIdcvalue specifying the H.265 codec profile IDC, as defined in section A.3 of the ITU-T H.265 Specification.
43.21.7. H.265 Encode Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for an H.265 encode profile, the
VkVideoCapabilitiesKHR::pNext chain must include a
VkVideoEncodeH265CapabilitiesKHR structure that will be filled with
the profile-specific capabilities.
The VkVideoEncodeH265CapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265CapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeH265CapabilityFlagsKHR flags;
StdVideoH265LevelIdc maxLevelIdc;
uint32_t maxSliceSegmentCount;
VkExtent2D maxTiles;
VkVideoEncodeH265CtbSizeFlagsKHR ctbSizes;
VkVideoEncodeH265TransformBlockSizeFlagsKHR transformBlockSizes;
uint32_t maxPPictureL0ReferenceCount;
uint32_t maxBPictureL0ReferenceCount;
uint32_t maxL1ReferenceCount;
uint32_t maxSubLayerCount;
VkBool32 expectDyadicTemporalSubLayerPattern;
int32_t minQp;
int32_t maxQp;
VkBool32 prefersGopRemainingFrames;
VkBool32 requiresGopRemainingFrames;
VkVideoEncodeH265StdFlagsKHR stdSyntaxFlags;
} VkVideoEncodeH265CapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeH265CapabilityFlagBitsKHR indicating supported H.265 encoding capabilities. -
maxLevelIdcis aStdVideoH265LevelIdcvalue indicating the maximum H.265 level supported by the profile, where enum constantSTD_VIDEO_H265_LEVEL_IDC_<major>_<minor>identifies H.265 level<major>.<minor>as defined in section A.4 of the ITU-T H.265 Specification. -
maxSliceSegmentCountindicates the maximum number of slice segments that can be encoded for a single picture. Further restrictions may apply to the number of slice segments that can be encoded for a single picture depending on other capabilities and codec-specific rules. -
maxTilesindicates the maximum number of H.265 tile columns and rows, as defined in sections 3.175 and 3.176 of the ITU-T H.265 Specification that can be encoded for a single picture. Further restrictions may apply to the number of H.265 tiles that can be encoded for a single picture depending on other capabilities and codec-specific rules. -
ctbSizesis a bitmask of VkVideoEncodeH265CtbSizeFlagBitsKHR describing the supported CTB sizes. -
transformBlockSizesis a bitmask of VkVideoEncodeH265TransformBlockSizeFlagBitsKHR describing the supported transform block sizes. -
maxPPictureL0ReferenceCountindicates the maximum number of reference pictures the implementation supports in the reference list L0 for P pictures.NoteAs implementations may override the reference lists,
maxPPictureL0ReferenceCountdoes not limit the number of elements that the application can specify in the L0 reference list for P pictures. However, ifmaxPPictureL0ReferenceCountis zero, then the use of P pictures is not allowed. In case of H.265 encoding, pictures can be encoded using only forward prediction even if P pictures are not supported, as the ITU-T H.265 Specification supports generalized P & B frames (also known as low delay B frames) whereas B frames can refer to past frames through both the L0 and L1 reference lists. -
maxBPictureL0ReferenceCountindicates the maximum number of reference pictures the implementation supports in the reference list L0 for B pictures. -
maxL1ReferenceCountindicates the maximum number of reference pictures the implementation supports in the reference list L1 if encoding of B pictures is supported.NoteAs implementations may override the reference lists,
maxBPictureL0ReferenceCountandmaxL1ReferenceCountdoes not limit the number of elements that the application can specify in the L0 and L1 reference lists for B pictures. However, ifmaxBPictureL0ReferenceCountandmaxL1ReferenceCountare both zero, then the use of B pictures is not allowed. -
maxSubLayerCountindicates the maximum number of H.265 sub-layers supported by the implementation. -
expectDyadicTemporalSubLayerPatternindicates that the implementation’s rate control algorithms expect the application to use a dyadic temporal sub-layer pattern when encoding multiple temporal sub-layers. -
minQpindicates the minimum QP value supported. -
maxQpindicates the maximum QP value supported. -
prefersGopRemainingFramesindicates that the implementation’s rate control algorithm prefers the application to specify the number of frames of each type remaining in the current group of pictures when beginning a video coding scope. -
requiresGopRemainingFramesindicates that the implementation’s rate control algorithm requires the application to specify the number of frames of each type remaining in the current group of pictures when beginning a video coding scope. -
stdSyntaxFlagsis a bitmask of VkVideoEncodeH265StdFlagBitsKHR indicating capabilities related to H.265 syntax elements.
Bits which may be set in
VkVideoEncodeH265CapabilitiesKHR::flags, indicating the H.265
encoding capabilities supported, are:
// Provided by VK_KHR_video_encode_h265
typedef enum VkVideoEncodeH265CapabilityFlagBitsKHR {
VK_VIDEO_ENCODE_H265_CAPABILITY_HRD_COMPLIANCE_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_H265_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_H265_CAPABILITY_ROW_UNALIGNED_SLICE_SEGMENT_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_SLICE_SEGMENT_TYPE_BIT_KHR = 0x00000008,
VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHR = 0x00000010,
VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHR = 0x00000020,
VK_VIDEO_ENCODE_H265_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR = 0x00000040,
VK_VIDEO_ENCODE_H265_CAPABILITY_PER_SLICE_SEGMENT_CONSTANT_QP_BIT_KHR = 0x00000080,
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILES_PER_SLICE_SEGMENT_BIT_KHR = 0x00000100,
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_SEGMENTS_PER_TILE_BIT_KHR = 0x00000200,
// Provided by VK_KHR_video_encode_h265 with VK_KHR_video_encode_intra_refresh
VK_VIDEO_ENCODE_H265_CAPABILITY_B_PICTURE_INTRA_REFRESH_BIT_KHR = 0x00000800,
// Provided by VK_KHR_video_encode_h265 with VK_KHR_video_encode_quantization_map
VK_VIDEO_ENCODE_H265_CAPABILITY_CU_QP_DIFF_WRAPAROUND_BIT_KHR = 0x00000400,
} VkVideoEncodeH265CapabilityFlagBitsKHR;
-
VK_VIDEO_ENCODE_H265_CAPABILITY_HRD_COMPLIANCE_BIT_KHRspecifies whether the implementation may be able to generate HRD compliant bitstreams if any of thenal_hrd_parameters_present_flag,vcl_hrd_parameters_present_flag, orsub_pic_hrd_params_present_flagmembers ofStdVideoH265HrdFlagsare set to1in the HRD parameters of the active VPS or active SPS, or ifStdVideoH265SpsVuiFlags::vui_hrd_parameters_present_flagis set to1in the active SPS. -
VK_VIDEO_ENCODE_H265_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHRspecifies that if theweighted_pred_flagor theweighted_bipred_flagmember ofStdVideoH265PpsFlagsis set to1in the active PPS when encoding a P picture or B picture, respectively, then the implementation is able to internally decide syntax forpred_weight_table, as defined in section 7.4.7.3 of the ITU-T H.265 Specification, and the application is not required to provide a weight table in the H.265 slice segment header parameters. -
VK_VIDEO_ENCODE_H265_CAPABILITY_ROW_UNALIGNED_SLICE_SEGMENT_BIT_KHRspecifies 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 indicates 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). When a picture is encoded with intra refresh, encoding non-rectangular slice segments also requires: support for the VkVideoEncodeIntraRefreshCapabilitiesKHR::nonRectangularIntraRefreshRegionscapability. -
VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_SLICE_SEGMENT_TYPE_BIT_KHRspecifies that when a frame is encoded with multiple slice segments, the implementation allows encoding each slice segment with a differentStdVideoEncodeH265SliceSegmentHeader::slice_typespecified in the H.265 slice segment header parameters. If not supported, all slice segments of the frame must be encoded with the sameslice_typewhich corresponds to the picture type of the frame. There is one exception to this rule: if the picture is encoded with the intra refresh modeVK_VIDEO_ENCODE_INTRA_REFRESH_MODE_PER_PICTURE_PARTITION_BIT_KHR, then the currently refreshed slice segment must specify theslice_typeSTD_VIDEO_H265_SLICE_TYPE_Iand can differ from theslice_typeof the other slice segments regardless of whetherVK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_SLICE_SEGMENT_TYPE_BIT_KHRis supported. -
VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHRspecifies support for using a B frame as L0 reference, as specified inStdVideoEncodeH265ReferenceListsInfo::RefPicList0in the H.265 picture information. -
VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHRspecifies support for using a B frame as L1 reference, as specified inStdVideoEncodeH265ReferenceListsInfo::RefPicList1in the H.265 picture information. -
VK_VIDEO_ENCODE_H265_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHRspecifies support for specifying different QP values in the members of VkVideoEncodeH265QpKHR. -
VK_VIDEO_ENCODE_H265_CAPABILITY_PER_SLICE_SEGMENT_CONSTANT_QP_BIT_KHRspecifies support for specifying different constant QP values for each slice segment. -
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILES_PER_SLICE_SEGMENT_BIT_KHRspecifies whether encoding multiple tiles per slice segment, as defined in section 6.3.1 of the ITU-T H.265 Specification, is supported. If this capability flag is not present, then the implementation is only able to encode a single tile for each slice segment. -
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_SEGMENTS_PER_TILE_BIT_KHRspecifies whether encoding multiple slice segments per tile, as defined in section 6.3.1 of the ITU-T H.265 Specification, is supported. If this capability flag is not present, then the implementation is only able to encode a single slice segment for each tile. -
VK_VIDEO_ENCODE_H265_CAPABILITY_CU_QP_DIFF_WRAPAROUND_BIT_KHRindicates support for wraparound during the calculation of the QP values of subsequently encoded coding units, as defined in section 7.4.9.14 of the ITU-T H.265 Specification. If not supported, equation 8-283 of the ITU-T H.265 Specification is effectively reduced to the following:QpY = qPY_PRED +
CuQpDeltaValNoteThe effect of this is that the maximum QP difference across subsequent coding units is limited to the [-(26 + QpBdOffsetY / 2), 25 + QpBdOffsetY / 2] range.
-
VK_VIDEO_ENCODE_H265_CAPABILITY_B_PICTURE_INTRA_REFRESH_BIT_KHRindicates support for encoding B pictures with intra refresh enabled.
// Provided by VK_KHR_video_encode_h265
typedef VkFlags VkVideoEncodeH265CapabilityFlagsKHR;
VkVideoEncodeH265CapabilityFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoEncodeH265CapabilityFlagBitsKHR.
Bits which may be set in
VkVideoEncodeH265CapabilitiesKHR::stdSyntaxFlags, indicating the
capabilities related to the H.265 syntax elements, are:
// Provided by VK_KHR_video_encode_h265
typedef enum VkVideoEncodeH265StdFlagBitsKHR {
VK_VIDEO_ENCODE_H265_STD_SEPARATE_COLOR_PLANE_FLAG_SET_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_H265_STD_SAMPLE_ADAPTIVE_OFFSET_ENABLED_FLAG_SET_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_H265_STD_SCALING_LIST_DATA_PRESENT_FLAG_SET_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_H265_STD_PCM_ENABLED_FLAG_SET_BIT_KHR = 0x00000008,
VK_VIDEO_ENCODE_H265_STD_SPS_TEMPORAL_MVP_ENABLED_FLAG_SET_BIT_KHR = 0x00000010,
VK_VIDEO_ENCODE_H265_STD_INIT_QP_MINUS26_BIT_KHR = 0x00000020,
VK_VIDEO_ENCODE_H265_STD_WEIGHTED_PRED_FLAG_SET_BIT_KHR = 0x00000040,
VK_VIDEO_ENCODE_H265_STD_WEIGHTED_BIPRED_FLAG_SET_BIT_KHR = 0x00000080,
VK_VIDEO_ENCODE_H265_STD_LOG2_PARALLEL_MERGE_LEVEL_MINUS2_BIT_KHR = 0x00000100,
VK_VIDEO_ENCODE_H265_STD_SIGN_DATA_HIDING_ENABLED_FLAG_SET_BIT_KHR = 0x00000200,
VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_SET_BIT_KHR = 0x00000400,
VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_UNSET_BIT_KHR = 0x00000800,
VK_VIDEO_ENCODE_H265_STD_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT_FLAG_SET_BIT_KHR = 0x00001000,
VK_VIDEO_ENCODE_H265_STD_TRANSQUANT_BYPASS_ENABLED_FLAG_SET_BIT_KHR = 0x00002000,
VK_VIDEO_ENCODE_H265_STD_CONSTRAINED_INTRA_PRED_FLAG_SET_BIT_KHR = 0x00004000,
VK_VIDEO_ENCODE_H265_STD_ENTROPY_CODING_SYNC_ENABLED_FLAG_SET_BIT_KHR = 0x00008000,
VK_VIDEO_ENCODE_H265_STD_DEBLOCKING_FILTER_OVERRIDE_ENABLED_FLAG_SET_BIT_KHR = 0x00010000,
VK_VIDEO_ENCODE_H265_STD_DEPENDENT_SLICE_SEGMENTS_ENABLED_FLAG_SET_BIT_KHR = 0x00020000,
VK_VIDEO_ENCODE_H265_STD_DEPENDENT_SLICE_SEGMENT_FLAG_SET_BIT_KHR = 0x00040000,
VK_VIDEO_ENCODE_H265_STD_SLICE_QP_DELTA_BIT_KHR = 0x00080000,
VK_VIDEO_ENCODE_H265_STD_DIFFERENT_SLICE_QP_DELTA_BIT_KHR = 0x00100000,
} VkVideoEncodeH265StdFlagBitsKHR;
-
VK_VIDEO_ENCODE_H265_STD_SEPARATE_COLOR_PLANE_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265SpsFlags::separate_colour_plane_flagin the SPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_SAMPLE_ADAPTIVE_OFFSET_ENABLED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265SpsFlags::sample_adaptive_offset_enabled_flagin the SPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_SCALING_LIST_DATA_PRESENT_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value for thescaling_list_enabled_flagandsps_scaling_list_data_present_flagmembers ofStdVideoH265SpsFlagsin the SPS, and the application-provided value forStdVideoH265PpsFlags::pps_scaling_list_data_present_flagin the PPS when those values are1. -
VK_VIDEO_ENCODE_H265_STD_PCM_ENABLED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265SpsFlags::pcm_enable_flagin the SPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_SPS_TEMPORAL_MVP_ENABLED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265SpsFlags::sps_temporal_mvp_enabled_flagin the SPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_INIT_QP_MINUS26_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PictureParameterSet::init_qp_minus26in the PPS when that value is non-zero. -
VK_VIDEO_ENCODE_H265_STD_WEIGHTED_PRED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::weighted_pred_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_WEIGHTED_BIPRED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::weighted_bipred_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_LOG2_PARALLEL_MERGE_LEVEL_MINUS2_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PictureParameterSet::log2_parallel_merge_level_minus2in the PPS when that value is non-zero. -
VK_VIDEO_ENCODE_H265_STD_SIGN_DATA_HIDING_ENABLED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::sign_data_hiding_enabled_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::transform_skip_enabled_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_UNSET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::transform_skip_enabled_flagin the PPS when that value is0. -
VK_VIDEO_ENCODE_H265_STD_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::pps_slice_chroma_qp_offsets_present_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_TRANSQUANT_BYPASS_ENABLED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::transquant_bypass_enabled_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_CONSTRAINED_INTRA_PRED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::constrained_intra_pred_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_ENTROPY_CODING_SYNC_ENABLED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::entropy_coding_sync_enabled_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_DEBLOCKING_FILTER_OVERRIDE_ENABLED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::deblocking_filter_override_enabled_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_DEPENDENT_SLICE_SEGMENTS_ENABLED_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoH265PpsFlags::dependent_slice_segments_enabled_flagin the PPS when that value is1. -
VK_VIDEO_ENCODE_H265_STD_DEPENDENT_SLICE_SEGMENT_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeH265SliceSegmentHeader::dependent_slice_segment_flagin the H.265 slice segment header parameters when that value is1. -
VK_VIDEO_ENCODE_H265_STD_SLICE_QP_DELTA_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeH265SliceSegmentHeader::slice_qp_deltain the H.265 slice segment header parameters when that value is identical across the slice segments of the encoded frame. -
VK_VIDEO_ENCODE_H265_STD_DIFFERENT_SLICE_QP_DELTA_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeH265SliceSegmentHeader::slice_qp_deltain the H.265 slice segment header parameters when that value is different across the slice segments of the encoded frame.
These capability flags provide information to the application about specific H.265 syntax element values that the implementation supports without having to override them and do not otherwise restrict the values that the application can specify for any of the mentioned H.265 syntax elements.
// Provided by VK_KHR_video_encode_h265
typedef VkFlags VkVideoEncodeH265StdFlagsKHR;
VkVideoEncodeH265StdFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoEncodeH265StdFlagBitsKHR.
Bits which may be set in
VkVideoEncodeH265CapabilitiesKHR::ctbSizes, indicating the CTB
sizes supported by the implementation, are:
// Provided by VK_KHR_video_encode_h265
typedef enum VkVideoEncodeH265CtbSizeFlagBitsKHR {
VK_VIDEO_ENCODE_H265_CTB_SIZE_16_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_H265_CTB_SIZE_32_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_H265_CTB_SIZE_64_BIT_KHR = 0x00000004,
} VkVideoEncodeH265CtbSizeFlagBitsKHR;
-
VK_VIDEO_ENCODE_H265_CTB_SIZE_16_BIT_KHRspecifies that a CTB size of 16x16 is supported. -
VK_VIDEO_ENCODE_H265_CTB_SIZE_32_BIT_KHRspecifies that a CTB size of 32x32 is supported. -
VK_VIDEO_ENCODE_H265_CTB_SIZE_64_BIT_KHRspecifies that a CTB size of 64x64 is supported.
// Provided by VK_KHR_video_encode_h265
typedef VkFlags VkVideoEncodeH265CtbSizeFlagsKHR;
VkVideoEncodeH265CtbSizeFlagsKHR is a bitmask type for setting a mask
of zero or more VkVideoEncodeH265CtbSizeFlagBitsKHR.
Implementations must support at least one of
VkVideoEncodeH265CtbSizeFlagBitsKHR.
Bits which may be set in
VkVideoEncodeH265CapabilitiesKHR::transformBlockSizes,
indicating the transform block sizes supported by the implementation, are:
// Provided by VK_KHR_video_encode_h265
typedef enum VkVideoEncodeH265TransformBlockSizeFlagBitsKHR {
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_4_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_8_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_16_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_32_BIT_KHR = 0x00000008,
} VkVideoEncodeH265TransformBlockSizeFlagBitsKHR;
-
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_4_BIT_KHRspecifies that a transform block size of 4x4 is supported. -
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_8_BIT_KHRspecifies that a transform block size of 8x8 is supported. -
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_16_BIT_KHRspecifies that a transform block size of 16x16 is supported. -
VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_32_BIT_KHRspecifies that a transform block size of 32x32 is supported.
// Provided by VK_KHR_video_encode_h265
typedef VkFlags VkVideoEncodeH265TransformBlockSizeFlagsKHR;
VkVideoEncodeH265TransformBlockSizeFlagsKHR is a bitmask type for
setting a mask of zero or more
VkVideoEncodeH265TransformBlockSizeFlagBitsKHR.
Implementations must support at least one of
VkVideoEncodeH265TransformBlockSizeFlagBitsKHR.
43.21.8. H.265 Encode Quality Level Properties
When calling vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR
with pVideoProfile->videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the
VkVideoEncodeH265QualityLevelPropertiesKHR structure must be included
in the pNext chain of the VkVideoEncodeQualityLevelPropertiesKHR
structure to retrieve additional video encode quality level properties
specific to H.265 encoding.
The VkVideoEncodeH265QualityLevelPropertiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265QualityLevelPropertiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeH265RateControlFlagsKHR preferredRateControlFlags;
uint32_t preferredGopFrameCount;
uint32_t preferredIdrPeriod;
uint32_t preferredConsecutiveBFrameCount;
uint32_t preferredSubLayerCount;
VkVideoEncodeH265QpKHR preferredConstantQp;
uint32_t preferredMaxL0ReferenceCount;
uint32_t preferredMaxL1ReferenceCount;
} VkVideoEncodeH265QualityLevelPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
preferredRateControlFlagsis a bitmask of VkVideoEncodeH265RateControlFlagBitsKHR values indicating the preferred flags to use for VkVideoEncodeH265RateControlInfoKHR::flags. -
preferredGopFrameCountindicates the preferred value to use for VkVideoEncodeH265RateControlInfoKHR::gopFrameCount. -
preferredIdrPeriodindicates the preferred value to use for VkVideoEncodeH265RateControlInfoKHR::idrPeriod. -
preferredConsecutiveBFrameCountindicates the preferred value to use for VkVideoEncodeH265RateControlInfoKHR::consecutiveBFrameCount. -
preferredSubLayerCountindicates the preferred value to use for VkVideoEncodeH265RateControlInfoKHR::subLayerCount. -
preferredConstantQpindicates the preferred values to use for VkVideoEncodeH265NaluSliceSegmentInfoKHR::constantQpfor each picture type when using rate control modeVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. -
preferredMaxL0ReferenceCountindicates the preferred maximum number of reference pictures to use in the reference list L0. -
preferredMaxL1ReferenceCountindicates the preferred maximum number of reference pictures to use in the reference list L1.
43.21.9. H.265 Encode Session
Additional parameters can be specified when creating a video session with an
H.265 encode profile by including an instance of the
VkVideoEncodeH265SessionCreateInfoKHR structure in the pNext
chain of VkVideoSessionCreateInfoKHR.
The VkVideoEncodeH265SessionCreateInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265SessionCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 useMaxLevelIdc;
StdVideoH265LevelIdc maxLevelIdc;
} VkVideoEncodeH265SessionCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
useMaxLevelIdcindicates whether the value ofmaxLevelIdcshould be used by the implementation. When it isVK_FALSE, the implementation ignores the value ofmaxLevelIdcand uses the value of VkVideoEncodeH265CapabilitiesKHR::maxLevelIdc, as reported by vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile. -
maxLevelIdcis aStdVideoH265LevelIdcvalue specifying the upper bound on the H.265 level for the video bitstreams produced by the created video session, where enum constantSTD_VIDEO_H265_LEVEL_IDC_<major>_<minor>identifies H.265 level<major>.<minor>as defined in section A.4 of the ITU-T H.265 Specification.
43.21.10. H.265 Encode Parameter Sets
Video session parameters objects created with
the video codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR
can contain the following types of parameters:
- H.265 Video Parameter Sets (VPS)
-
Represented by
StdVideoH265VideoParameterSetstructures and interpreted as follows:-
reserved1,reserved2, andreserved3are used only for padding purposes and are otherwise ignored; -
vps_video_parameter_set_idis used as the key of the VPS entry; -
the
max_latency_increase_plus1,max_dec_pic_buffering_minus1, andmax_num_reorder_picsmembers of theStdVideoH265DecPicBufMgrstructure pointed to bypDecPicBufMgrcorrespond tovps_max_latency_increase_plus1,vps_max_dec_pic_buffering_minus1, andvps_max_num_reorder_pics, respectively, as defined in section 7.4.3.1 of the ITU-T H.265 Specification; -
the
StdVideoH265HrdParametersstructure pointed to bypHrdParametersis interpreted as follows:-
reservedis used only for padding purposes and is otherwise ignored; -
flags.fixed_pic_rate_general_flagis a bitmask where bit index i corresponds tofixed_pic_rate_general_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
flags.fixed_pic_rate_within_cvs_flagis a bitmask where bit index i corresponds tofixed_pic_rate_within_cvs_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
flags.low_delay_hrd_flagis a bitmask where bit index i corresponds tolow_delay_hrd_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
if
flags.nal_hrd_parameters_present_flagis set, thenpSubLayerHrdParametersNalis a pointer to an array ofvps_max_sub_layers_minus1+ 1 number ofStdVideoH265SubLayerHrdParametersstructures wherevps_max_sub_layers_minus1is the corresponding member of the encompassingStdVideoH265VideoParameterSetstructure and each element is interpreted as follows:-
cbr_flagis a bitmask where bit index i corresponds tocbr_flag[i]as defined in section E.3.3 of the ITU-T H.265 Specification; -
all other members of the
StdVideoH265SubLayerHrdParametersstructure are interpreted as defined in section E.3.3 of the ITU-T H.265 Specification;
-
-
if
flags.vcl_hrd_parameters_present_flagis set, thenpSubLayerHrdParametersVclis a pointer to an array ofvps_max_sub_layers_minus1+ 1 number ofStdVideoH265SubLayerHrdParametersstructures wherevps_max_sub_layers_minus1is the corresponding member of the encompassingStdVideoH265VideoParameterSetstructure and each element is interpreted as follows:-
cbr_flagis a bitmask where bit index i corresponds tocbr_flag[i]as defined in section E.3.3 of the ITU-T H.265 Specification; -
all other members of the
StdVideoH265SubLayerHrdParametersstructure are interpreted as defined in section E.3.3 of the ITU-T H.265 Specification;
-
-
all other members of
StdVideoH265HrdParametersare interpreted as defined in section E.3.2 of the ITU-T H.265 Specification;
-
-
the
StdVideoH265ProfileTierLevelstructure pointed to bypProfileTierLevelare interpreted as follows:-
general_level_idcis one of the enum constantsSTD_VIDEO_H265_LEVEL_IDC_<major>_<minor>identifying the H.265 level<major>.<minor>as defined in section A.4 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265ProfileTierLevelare interpreted as defined in section 7.4.4 of the ITU-T H.265 Specification;
-
-
all other members of
StdVideoH265VideoParameterSetare interpreted as defined in section 7.4.3.1 of the ITU-T H.265 Specification.
-
- H.265 Sequence Parameter Sets (SPS)
-
Represented by
StdVideoH265SequenceParameterSetstructures and interpreted as follows:-
reserved1andreserved2are used only for padding purposes and are otherwise ignored; -
the pair constructed from
sps_video_parameter_set_idandsps_seq_parameter_set_idis used as the key of the SPS entry; -
the
StdVideoH265ProfileTierLevelstructure pointed to bypProfileTierLevelare interpreted as follows:-
general_level_idcis one of the enum constantsSTD_VIDEO_H265_LEVEL_IDC_<major>_<minor>identifying the H.265 level<major>.<minor>as defined in section A.4 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265ProfileTierLevelare interpreted as defined in section 7.4.4 of the ITU-T H.265 Specification;
-
-
the
max_latency_increase_plus1,max_dec_pic_buffering_minus1, andmax_num_reorder_picsmembers of theStdVideoH265DecPicBufMgrstructure pointed to bypDecPicBufMgrcorrespond tosps_max_latency_increase_plus1,sps_max_dec_pic_buffering_minus1, andsps_max_num_reorder_pics, respectively, as defined in section 7.4.3.2 of the ITU-T H.265 Specification; -
if
flags.sps_scaling_list_data_present_flagis set, then theStdVideoH265ScalingListsstructure pointed to bypScalingListsis interpreted as follows:-
ScalingList4x4,ScalingList8x8,ScalingList16x16, andScalingList32x32correspond toScalingList[0],ScalingList[1],ScalingList[2], andScalingList[3], respectively, as defined in section 7.3.4 of the ITU-T H.265 Specification; -
ScalingListDCCoef16x16andScalingListDCCoef32x32correspond toscaling_list_dc_coef_minus8[0]andscaling_list_dc_coef_minus8[1], respectively, as defined in section 7.3.4 of the ITU-T H.265 Specification;
-
-
pShortTermRefPicSetis a pointer to an array ofnum_short_term_ref_pic_setsnumber ofStdVideoH265ShortTermRefPicSetstructures where each element is interpreted as follows:-
reserved1,reserved2, andreserved3are used only for padding purposes and are otherwise ignored; -
used_by_curr_pic_flagis a bitmask where bit index i corresponds toused_by_curr_pic_flag[i]as defined in section 7.4.8 of the ITU-T H.265 Specification; -
use_delta_flagis a bitmask where bit index i corresponds touse_delta_flag[i]as defined in section 7.4.8 of the ITU-T H.265 Specification; -
used_by_curr_pic_s0_flagis a bitmask where bit index i corresponds toused_by_curr_pic_s0_flag[i]as defined in section 7.4.8 of the ITU-T H.265 Specification; -
used_by_curr_pic_s1_flagis a bitmask where bit index i corresponds toused_by_curr_pic_s1_flag[i]as defined in section 7.4.8 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265ShortTermRefPicSetare interpreted as defined in section 7.4.8 of the ITU-T H.265 Specification;
-
-
if
flags.long_term_ref_pics_present_flagis set then theStdVideoH265LongTermRefPicsSpsstructure pointed to bypLongTermRefPicsSpsis interpreted as follows:-
used_by_curr_pic_lt_sps_flagis a bitmask where bit index i corresponds toused_by_curr_pic_lt_sps_flag[i]as defined in section 7.4.3.2 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265LongTermRefPicsSpsare interpreted as defined in section 7.4.3.2 of the ITU-T H.265 Specification;
-
-
if
flags.vui_parameters_present_flagis set, then theStdVideoH265SequenceParameterSetVuistructure pointed to bypSequenceParameterSetVuiis interpreted as follows:-
reserved1,reserved2, andreserved3are used only for padding purposes and are otherwise ignored; -
the
StdVideoH265HrdParametersstructure pointed to bypHrdParametersis interpreted as follows:-
flags.fixed_pic_rate_general_flagis a bitmask where bit index i corresponds tofixed_pic_rate_general_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
flags.fixed_pic_rate_within_cvs_flagis a bitmask where bit index i corresponds tofixed_pic_rate_within_cvs_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
flags.low_delay_hrd_flagis a bitmask where bit index i corresponds tolow_delay_hrd_flag[i]as defined in section E.3.2 of the ITU-T H.265 Specification; -
if
flags.nal_hrd_parameters_present_flagis set, thenpSubLayerHrdParametersNalis a pointer to an array ofsps_max_sub_layers_minus1+ 1 number ofStdVideoH265SubLayerHrdParametersstructures wheresps_max_sub_layers_minus1is the corresponding member of the encompassingStdVideoH265SequenceParameterSetstructure and each element is interpreted as follows:-
cbr_flagis a bitmask where bit index i corresponds tocbr_flag[i]as defined in section E.3.3 of the ITU-T H.265 Specification; -
all other members of the
StdVideoH265SubLayerHrdParametersstructure are interpreted as defined in section E.3.3 of the ITU-T H.265 Specification;
-
-
if
flags.vcl_hrd_parameters_present_flagis set, thenpSubLayerHrdParametersVclis a pointer to an array ofsps_max_sub_layers_minus1+ 1 number ofStdVideoH265SubLayerHrdParametersstructures wheresps_max_sub_layers_minus1is the corresponding member of the encompassingStdVideoH265SequenceParameterSetstructure and each element is interpreted as follows:-
cbr_flagis a bitmask where bit index i corresponds tocbr_flag[i]as defined in section E.3.3 of the ITU-T H.265 Specification; -
all other members of the
StdVideoH265SubLayerHrdParametersstructure are interpreted as defined in section E.3.3 of the ITU-T H.265 Specification;
-
-
all other members of
StdVideoH265HrdParametersare interpreted as defined in section E.3.2 of the ITU-T H.265 Specification;
-
-
all other members of
pSequenceParameterSetVuiare interpreted as defined in section E.3.1 of the ITU-T H.265 Specification;
-
-
if
flags.sps_palette_predictor_initializer_present_flagis set, then thePredictorPaletteEntriesmember of theStdVideoH265PredictorPaletteEntriesstructure pointed to bypPredictorPaletteEntriesis interpreted as defined in section 7.4.9.13 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265SequenceParameterSetare interpreted as defined in section 7.4.3.1 of the ITU-T H.265 Specification.
-
- H.265 Picture Parameter Sets (PPS)
-
Represented by
StdVideoH265PictureParameterSetstructures and interpreted as follows:-
reserved1,reserved2, andreserved3are used only for padding purposes and are otherwise ignored; -
the triplet constructed from
sps_video_parameter_set_id,pps_seq_parameter_set_id, andpps_pic_parameter_set_idis used as the key of the PPS entry; -
if
flags.pps_scaling_list_data_present_flagis set, then theStdVideoH265ScalingListsstructure pointed to bypScalingListsis interpreted as follows:-
ScalingList4x4,ScalingList8x8,ScalingList16x16, andScalingList32x32correspond toScalingList[0],ScalingList[1],ScalingList[2], andScalingList[3], respectively, as defined in section 7.3.4 of the ITU-T H.265 Specification; -
ScalingListDCCoef16x16andScalingListDCCoef32x32correspond toscaling_list_dc_coef_minus8[0]andscaling_list_dc_coef_minus8[1], respectively, as defined in section 7.3.4 of the ITU-T H.265 Specification;
-
-
if
flags.pps_palette_predictor_initializer_present_flagis set, then thePredictorPaletteEntriesmember of theStdVideoH265PredictorPaletteEntriesstructure pointed to bypPredictorPaletteEntriesis interpreted as defined in section 7.4.9.13 of the ITU-T H.265 Specification; -
all other members of
StdVideoH265PictureParameterSetare interpreted as defined in section 7.4.3.3 of the ITU-T H.265 Specification.
-
Implementations may override any of these parameters according to the semantics defined in the Video Encode Parameter Overrides section before storing the resulting H.265 parameter sets into the video session parameters object. Applications need to use the vkGetEncodedVideoSessionParametersKHR command to determine whether any implementation overrides happened and to retrieve the encoded H.265 parameter sets in order to be able to produce a compliant H.265 video bitstream.
Such H.265 parameter set overrides may also have cascading effects on the
implementation overrides applied to the encoded bitstream produced by video
encode operations.
If the implementation supports the
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR
video encode feedback query flag, then the
application can use such queries to retrieve feedback about whether any
implementation overrides have been applied to the encoded bitstream.
When a video session parameters object is
created with the codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the
VkVideoSessionParametersCreateInfoKHR::pNext chain must include
a VkVideoEncodeH265SessionParametersCreateInfoKHR structure specifying
the capacity and initial contents of the object.
The VkVideoEncodeH265SessionParametersCreateInfoKHR structure is
defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265SessionParametersCreateInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t maxStdVPSCount;
uint32_t maxStdSPSCount;
uint32_t maxStdPPSCount;
const VkVideoEncodeH265SessionParametersAddInfoKHR* pParametersAddInfo;
} VkVideoEncodeH265SessionParametersCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxStdVPSCountis the maximum number of H.265 VPS entries the createdVkVideoSessionParametersKHRcan contain. -
maxStdSPSCountis the maximum number of H.265 SPS entries the createdVkVideoSessionParametersKHRcan contain. -
maxStdPPSCountis the maximum number of H.265 PPS entries the createdVkVideoSessionParametersKHRcan contain. -
pParametersAddInfoisNULLor a pointer to a VkVideoEncodeH265SessionParametersAddInfoKHR structure specifying H.265 parameters to add upon object creation.
The VkVideoEncodeH265SessionParametersAddInfoKHR structure is defined
as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265SessionParametersAddInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t stdVPSCount;
const StdVideoH265VideoParameterSet* pStdVPSs;
uint32_t stdSPSCount;
const StdVideoH265SequenceParameterSet* pStdSPSs;
uint32_t stdPPSCount;
const StdVideoH265PictureParameterSet* pStdPPSs;
} VkVideoEncodeH265SessionParametersAddInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdVPSCountis the number of elements in thepStdVPSsarray. -
pStdVPSsis a pointer to an array ofStdVideoH265VideoParameterSetstructures describing the H.265 VPS entries to add. -
stdSPSCountis the number of elements in thepStdSPSsarray. -
pStdSPSsis a pointer to an array ofStdVideoH265SequenceParameterSetstructures describing the H.265 SPS entries to add. -
stdPPSCountis the number of elements in thepStdPPSsarray. -
pStdPPSsis a pointer to an array ofStdVideoH265PictureParameterSetstructures describing the H.265 PPS entries to add.
This structure can be specified in the following places:
-
In the
pParametersAddInfomember of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure specified in thepNextchain of VkVideoSessionParametersCreateInfoKHR used to create a video session parameters object. In this case, if the video codec operation the video session parameters object is created with isVK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then it defines the set of initial parameters to add to the created object (see Creating Video Session Parameters). -
In the
pNextchain of VkVideoSessionParametersUpdateInfoKHR. In this case, if the video codec operation the video session parameters object to be updated was created with isVK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then it defines the set of parameters to add to it (see Updating Video Session Parameters).
The VkVideoEncodeH265SessionParametersGetInfoKHR structure is defined
as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265SessionParametersGetInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 writeStdVPS;
VkBool32 writeStdSPS;
VkBool32 writeStdPPS;
uint32_t stdVPSId;
uint32_t stdSPSId;
uint32_t stdPPSId;
} VkVideoEncodeH265SessionParametersGetInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
writeStdVPSindicates whether the encoded H.265 video parameter set identified bystdVPSIdis requested to be retrieved. -
writeStdSPSindicates whether the encoded H.265 sequence parameter set identified by the pair constructed fromstdVPSIdandstdSPSIdis requested to be retrieved. -
writeStdPPSindicates whether the encoded H.265 picture parameter set identified by the triplet constructed fromstdVPSId,stdSPSId, andstdPPSIdis requested to be retrieved. -
stdVPSIdspecifies the H.265 video parameter set ID used to identify the retrieved H.265 video, sequence, and/or picture parameter set(s). -
stdSPSIdspecifies the H.265 sequence parameter set ID used to identify the retrieved H.265 sequence and/or picture parameter set(s) whenwriteStdSPSand/orwriteStdPPSisVK_TRUE. -
stdPPSIdspecifies the H.265 picture parameter set ID used to identify the retrieved H.265 picture parameter set whenwriteStdPPSisVK_TRUE.
When this structure is specified in the pNext chain of the
VkVideoEncodeSessionParametersGetInfoKHR structure passed to
vkGetEncodedVideoSessionParametersKHR, the command will write encoded
parameter data to the output buffer in the following order:
-
The H.265 video parameter set identified by
stdVPSId, ifwriteStdVPSisVK_TRUE. -
The H.265 sequence parameter set identified by the pair constructed from
stdVPSIdandstdSPSId, ifwriteStdSPSisVK_TRUE. -
The H.265 picture parameter set identified by the triplet constructed from
stdVPSId,stdSPSId, andstdPPSId, ifwriteStdPPSisVK_TRUE.
The VkVideoEncodeH265SessionParametersFeedbackInfoKHR structure is
defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265SessionParametersFeedbackInfoKHR {
VkStructureType sType;
void* pNext;
VkBool32 hasStdVPSOverrides;
VkBool32 hasStdSPSOverrides;
VkBool32 hasStdPPSOverrides;
} VkVideoEncodeH265SessionParametersFeedbackInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
hasStdVPSOverridesindicates whether any of the parameters of the requested H.265 video parameter set, if one was requested via VkVideoEncodeH265SessionParametersGetInfoKHR::writeStdVPS, were overridden by the implementation. -
hasStdSPSOverridesindicates whether any of the parameters of the requested H.265 sequence parameter set, if one was requested via VkVideoEncodeH265SessionParametersGetInfoKHR::writeStdSPS, were overridden by the implementation. -
hasStdPPSOverridesindicates whether any of the parameters of the requested H.265 picture parameter set, if one was requested via VkVideoEncodeH265SessionParametersGetInfoKHR::writeStdPPS, were overridden by the implementation.
43.21.11. H.265 Encoding Parameters
The VkVideoEncodeH265PictureInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265PictureInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t naluSliceSegmentEntryCount;
const VkVideoEncodeH265NaluSliceSegmentInfoKHR* pNaluSliceSegmentEntries;
const StdVideoEncodeH265PictureInfo* pStdPictureInfo;
} VkVideoEncodeH265PictureInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
naluSliceSegmentEntryCountis the number of elements inpNaluSliceSegmentEntries. -
pNaluSliceSegmentEntriesis a pointer to an array ofnaluSliceSegmentEntryCountVkVideoEncodeH265NaluSliceSegmentInfoKHR structures specifying the parameters of the individual H.265 slice segments to encode for the input picture. -
pStdPictureInfois a pointer to aStdVideoEncodeH265PictureInfostructure specifying H.265 picture information.
This structure is specified in the pNext chain of the
VkVideoEncodeInfoKHR structure passed to vkCmdEncodeVideoKHR to
specify the codec-specific picture information for an H.265
encode operation.
- Encode Input Picture Information
-
When this structure is specified in the
pNextchain of the VkVideoEncodeInfoKHR structure passed to vkCmdEncodeVideoKHR, the information related to the encode input picture is defined as follows:-
The image subregion used is determined according to the H.265 Encode Picture Data Access section.
-
The encode input picture is associated with the H.265 picture information provided in
pStdPictureInfo.
-
- Std Picture Information
-
The members of the
StdVideoEncodeH265PictureInfostructure pointed to bypStdPictureInfoare interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
flags.is_referenceas defined in section 3.132 of the ITU-T H.265 Specification; -
flags.IrapPicFlagas defined in section 3.73 of the ITU-T H.265 Specification; -
flags.used_for_long_term_referenceis used to indicate whether the picture is marked as “used for long-term reference” as defined in section 8.3.2 of the ITU-T H.265 Specification; -
flags.discardable_flagandcross_layer_bla_flagas defined in section F.7.4.7.1 of the ITU-T H.265 Specification; -
pic_typeas defined in section 7.4.3.5 of the ITU-T H.265 Specification; -
sps_video_parameter_set_id,pps_seq_parameter_set_id, andpps_pic_parameter_set_idare used to identify the active parameter sets, as described below; -
PicOrderCntValas defined in section 8.3.1 of the ITU-T H.265 Specification; -
TemporalIdas defined in section 7.4.2.2 of the ITU-T H.265 Specification; -
if
pRefListsis notNULL, then it is a pointer to aStdVideoEncodeH265ReferenceListsInfostructure that is interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
ref_pic_list_modification_flag_l0andref_pic_list_modification_flag_l1as defined in section 7.4.7.2 of the ITU-T H.265 Specification; -
num_ref_idx_l0_active_minus1andnum_ref_idx_l1_active_minus1as defined in section 7.4.7.1 of the ITU-T H.265 Specification; -
RefPicList0andRefPicList1as defined in section 8.3.4 of the ITU-T H.265 Specification where each element of these arrays either identifies an active reference picture using its DPB slot index or contains the valueSTD_VIDEO_H265_NO_REFERENCE_PICTUREto indicate “no reference picture”; -
list_entry_l0andlist_entry_l1as defined in section 7.4.7.2 of the ITU-T H.265 Specification;
-
-
if
flags.short_term_ref_pic_set_sps_flagis set, then theStdVideoH265ShortTermRefPicSetstructure pointed to bypShortTermRefPicSetis interpreted as defined for the elements of thepShortTermRefPicSetarray specified in H.265 sequence parameter sets. -
if
flags.long_term_ref_pics_present_flagis set in the active SPS, then theStdVideoEncodeH265LongTermRefPicsstructure pointed to bypLongTermRefPicsis interpreted as follows:-
used_by_curr_pic_lt_flagis a bitmask where bit index i corresponds toused_by_curr_pic_lt_flag[i]as defined in section 7.4.7.1 of the ITU-T H.265 Specification; -
all other members of
StdVideoEncodeH265LongTermRefPicsare interpreted as defined in section 7.4.7.1 of the ITU-T H.265 Specification;
-
-
all other members are interpreted as defined in section 7.4.7.1 of the ITU-T H.265 Specification.
-
Reference picture setup is controlled by the value of
StdVideoEncodeH265PictureInfo::flags.is_reference.
If it is set and a reconstructed
picture is specified, then the latter is used as the target of picture
reconstruction to activate the DPB slot
specified in pEncodeInfo->pSetupReferenceSlot->slotIndex.
If StdVideoEncodeH265PictureInfo::flags.is_reference is not set,
but a reconstructed picture is
specified, then the corresponding picture reference associated with the
DPB slot is invalidated, as described in the
DPB Slot States section.
- Active Parameter Sets
-
The members of the
StdVideoEncodeH265PictureInfostructure pointed to bypStdPictureInfoare used to select the active parameter sets to use from the bound video session parameters object, as follows:-
The active VPS is the VPS identified by the key specified in
StdVideoEncodeH265PictureInfo::sps_video_parameter_set_id. -
The active SPS is the SPS identified by the key specified by the pair constructed from
StdVideoEncodeH265PictureInfo::sps_video_parameter_set_idandStdVideoEncodeH265PictureInfo::pps_seq_parameter_set_id. -
The active PPS is the PPS identified by the key specified by the triplet constructed from
StdVideoEncodeH265PictureInfo::sps_video_parameter_set_id,StdVideoEncodeH265PictureInfo::pps_seq_parameter_set_id, andStdVideoEncodeH265PictureInfo::pps_pic_parameter_set_id.
-
H.265 encoding uses explicit weighted sample prediction for a slice
segment, as defined in section 8.5.3.3.4 of the ITU-T H.265
Specification, if any of the following conditions are true for the active
PPS and the pStdSliceSegmentHeader member of the
corresponding element of pNaluSliceSegmentEntries:
-
pStdSliceSegmentHeader->slice_typeisSTD_VIDEO_H265_SLICE_TYPE_Pandweighted_pred_flagis enabled in the active PPS. -
pStdSliceSegmentHeader->slice_typeisSTD_VIDEO_H265_SLICE_TYPE_Bandweighted_bipred_flagis enabled in the active PPS.
The number of H.265 tiles, as defined in section 3.174 of the ITU-T H.265 Specification, is derived from the
num_tile_columns_minus1 and num_tile_rows_minus1 members of the
active PPS as follows:
-
(
num_tile_columns_minus1+ 1) × (num_tile_rows_minus1+ 1)
The VkVideoEncodeH265NaluSliceSegmentInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265NaluSliceSegmentInfoKHR {
VkStructureType sType;
const void* pNext;
int32_t constantQp;
const StdVideoEncodeH265SliceSegmentHeader* pStdSliceSegmentHeader;
} VkVideoEncodeH265NaluSliceSegmentInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
constantQpis the QP to use for the slice segment if the current rate control mode configured for the video session isVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. -
pStdSliceSegmentHeaderis a pointer to aStdVideoEncodeH265SliceSegmentHeaderstructure specifying H.265 slice segment header parameters for the slice segment.
- Std Slice Segment Header Parameters
-
The members of the
StdVideoEncodeH265SliceSegmentHeaderstructure pointed to bypStdSliceSegmentHeaderare interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
if
pWeightTableis notNULL, then it is a pointer to aStdVideoEncodeH265WeightTablethat is interpreted as follows:-
flags.luma_weight_l0_flag,flags.chroma_weight_l0_flag,flags.luma_weight_l1_flag, andflags.chroma_weight_l1_flagare bitmasks where bit index i corresponds toluma_weight_l0_flag[i],chroma_weight_l0_flag[i],luma_weight_l1_flag[i], andchroma_weight_l1_flag[i], respectively, as defined in section 7.4.7.3 of the ITU-T H.265 Specification; -
all other members of
StdVideoEncodeH265WeightTableare interpreted as defined in section 7.4.7.3 of the ITU-T H.265 Specification;
-
-
all other members are interpreted as defined in section 7.4.7.1 of the ITU-T H.265 Specification.
-
The VkVideoEncodeH265DpbSlotInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265DpbSlotInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoEncodeH265ReferenceInfo* pStdReferenceInfo;
} VkVideoEncodeH265DpbSlotInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdReferenceInfois a pointer to aStdVideoEncodeH265ReferenceInfostructure specifying H.265 reference information.
This structure is specified in the pNext chain of
VkVideoEncodeInfoKHR::pSetupReferenceSlot, if not NULL, and
the pNext chain of the elements of
VkVideoEncodeInfoKHR::pReferenceSlots to specify the
codec-specific reference picture information for an H.265
encode operation.
- Active Reference Picture Information
-
When this structure is specified in the
pNextchain of the elements of VkVideoEncodeInfoKHR::pReferenceSlots, one element is added to the list of active reference pictures used by the video encode operation for each element of VkVideoEncodeInfoKHR::pReferenceSlotsas follows:-
The image subregion used is determined according to the H.265 Encode Picture Data Access section.
-
The reference picture is associated with the DPB slot index specified in the
slotIndexmember of the corresponding element of VkVideoEncodeInfoKHR::pReferenceSlots. -
The reference picture is associated with the H.265 reference information provided in
pStdReferenceInfo.
-
- Reconstructed Picture Information
-
When this structure is specified in the
pNextchain of VkVideoEncodeInfoKHR::pSetupReferenceSlot, the information related to the reconstructed picture is defined as follows:-
The image subregion used is determined according to the H.265 Encode Picture Data Access section.
-
If reference picture setup is requested, then the reconstructed picture is used to activate the DPB slot with the index specified in VkVideoEncodeInfoKHR::
pSetupReferenceSlot->slotIndex. -
The reconstructed picture is associated with the H.265 reference information provided in
pStdReferenceInfo.
-
- Std Reference Information
-
The members of the
StdVideoEncodeH265ReferenceInfostructure pointed to bypStdReferenceInfoare interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
flags.used_for_long_term_referenceis used to indicate whether the picture is marked as “used for long-term reference” as defined in section 8.3.2 of the ITU-T H.265 Specification; -
flags.unused_for_referenceis used to indicate whether the picture is marked as “unused for reference” as defined in section 8.3.2 of the ITU-T H.265 Specification; -
pic_typeas defined in section 7.4.3.5 of the ITU-T H.265 Specification; -
PicOrderCntValas defined in section 8.3.1 of the ITU-T H.265 Specification; -
TemporalIdas defined in section 7.4.2.2 of the ITU-T H.265 Specification.
-
43.21.12. H.265 Encode Rate Control
Group of Pictures
In case of H.265 encoding it is common practice to follow a regular pattern of different picture types in display order when encoding subsequent frames. This pattern is referred to as the group of pictures (GOP).
A regular GOP is defined by the following parameters:
-
The number of frames in the GOP;
-
The number of consecutive B frames between I and/or P frames in display order.
GOPs are further classified as open and closed GOPs.
Frame types in an open GOP follow each other in display order according to the following algorithm:
-
The first frame is always an I frame.
-
This is followed by a number of consecutive B frames, as defined above.
-
If the number of frames in the GOP is not reached yet, then the next frame is a P frame and the algorithm continues from step 2.
In case of a closed GOP, an IDR frame is used at a certain period.
It is also typical for H.265 encoding to use specific reference picture usage patterns across the frames of the GOP. The two most common reference patterns used are as follows:
- Flat Reference Pattern
-
-
Each P frame uses the last non-B frame, in display order, as reference.
-
Each B frame uses the last non-B frame, in display order, as its forward reference, and uses the next non-B frame, in display order, as its backward reference.
-
- Dyadic Reference Pattern
-
-
Each P frame uses the last non-B frame, in display order, as reference.
-
The following algorithm is applied to the sequence of consecutive B frames between I and/or P frames in display order:
-
The B frame in the middle of this sequence uses the frame preceding the sequence as its forward reference, and uses the frame following the sequence as its backward reference.
-
The algorithm is executed recursively for the following frame sequences:
-
The B frames of the original sequence preceding the frame in the middle, if any.
-
The B frames of the original sequence following the frame in the middle, if any.
-
-
-
The application can provide guidance to the implementation’s rate control algorithm about the structure of the GOP used by the application. Any such guidance about the GOP and its structure does not mandate that specific GOP structure to be used by the application, as the picture type of individual encoded pictures is still application-controlled, however, any deviation from the provided guidance may result in undesired rate control behavior including, but not limited, to the implementation not being able to conform to the expected average or target bitrates, or other rate control parameters specified by the application.
When an H.265 encode session is used to encode multiple temporal sub-layers, it is also common practice to follow a regular pattern for the H.265 temporal ID for the encoded pictures in display order when encoding subsequent frames. This pattern is referred to as the temporal GOP. The most common temporal layer pattern used is as follows:
- Dyadic Temporal Sub-Layer Pattern
-
-
The number of frames in the temporal GOP is 2n-1, where n is the number of temporal sub-layers.
-
The ith frame in the temporal GOP uses temporal ID t, if and only if the index of the least significant bit set in i equals n-t-1, except for the first frame, which is the only frame in the temporal GOP using temporal ID zero.
-
The ith frame in the temporal GOP uses the rth frame as reference, where r is calculated from i by clearing the least significant bit set in it, except for the first frame in the temporal GOP, which uses the first frame of the previous temporal GOP, if any, as reference.
-
|
Note
|
Multi-layer rate control and multi-layer coding are typically used for streaming cases where low latency is expected, hence B pictures with backward prediction are usually not used. |
The VkVideoEncodeH265RateControlInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265RateControlInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeH265RateControlFlagsKHR flags;
uint32_t gopFrameCount;
uint32_t idrPeriod;
uint32_t consecutiveBFrameCount;
uint32_t subLayerCount;
} VkVideoEncodeH265RateControlInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeH265RateControlFlagBitsKHR specifying H.265 rate control flags. -
gopFrameCountis the number of frames within a group of pictures (GOP) intended to be used by the application. If it is 0, the rate control algorithm may assume an implementation-dependent GOP length. If it isUINT32_MAX, the GOP length is treated as infinite. -
idrPeriodis the interval, in terms of number of frames, between two IDR frames (see IDR period). If it is 0, the rate control algorithm may assume an implementation-dependent IDR period. If it isUINT32_MAX, the IDR period is treated as infinite. -
consecutiveBFrameCountis the number of consecutive B frames between I and/or P frames within the GOP. -
subLayerCountspecifies the number of H.265 sub-layers that the application intends to use.
When an instance of this structure is included in the pNext chain of
the VkVideoCodingControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command, and
VkVideoCodingControlInfoKHR::flags includes
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, the parameters in
this structure are used as guidance for the implementation’s rate control
algorithm (see Video Coding Control).
If flags includes
VK_VIDEO_ENCODE_H265_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR, then
the rate control state is reset to an initial state to meet HRD compliance
requirements.
Otherwise the new rate control state may be applied without a reset
depending on the implementation and the specified rate control parameters.
|
Note
|
It would be possible to infer the picture type to be used when encoding a
frame, on the basis of the values provided for |
Bits which can be set in
VkVideoEncodeH265RateControlInfoKHR::flags, specifying H.265
rate control flags, are:
// Provided by VK_KHR_video_encode_h265
typedef enum VkVideoEncodeH265RateControlFlagBitsKHR {
VK_VIDEO_ENCODE_H265_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_H265_RATE_CONTROL_REGULAR_GOP_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR = 0x00000008,
VK_VIDEO_ENCODE_H265_RATE_CONTROL_TEMPORAL_SUB_LAYER_PATTERN_DYADIC_BIT_KHR = 0x00000010,
} VkVideoEncodeH265RateControlFlagBitsKHR;
-
VK_VIDEO_ENCODE_H265_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHRspecifies that rate control should attempt to produce an HRD compliant bitstream, as defined in annex C of the ITU-T H.265 Specification. -
VK_VIDEO_ENCODE_H265_RATE_CONTROL_REGULAR_GOP_BIT_KHRspecifies that the application intends to use a regular GOP structure according to the parameters specified in thegopFrameCount,idrPeriod, andconsecutiveBFrameCountmembers of the VkVideoEncodeH265RateControlInfoKHR structure. -
VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHRspecifies that the application intends to follow a flat reference pattern in the GOP. -
VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHRspecifies that the application intends to follow a dyadic reference pattern in the GOP. -
VK_VIDEO_ENCODE_H265_RATE_CONTROL_TEMPORAL_SUB_LAYER_PATTERN_DYADIC_BIT_KHRspecifies that the application intends to follow a dyadic temporal sub-layer pattern.
// Provided by VK_KHR_video_encode_h265
typedef VkFlags VkVideoEncodeH265RateControlFlagsKHR;
VkVideoEncodeH265RateControlFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoEncodeH265RateControlFlagBitsKHR.
Rate Control Layers
The VkVideoEncodeH265RateControlLayerInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265RateControlLayerInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 useMinQp;
VkVideoEncodeH265QpKHR minQp;
VkBool32 useMaxQp;
VkVideoEncodeH265QpKHR maxQp;
VkBool32 useMaxFrameSize;
VkVideoEncodeH265FrameSizeKHR maxFrameSize;
} VkVideoEncodeH265RateControlLayerInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
useMinQpindicates whether the QP values determined by rate control will be clamped to the lower bounds on the QP values specified inminQp. -
minQpspecifies the lower bounds on the QP values, for each picture type, that the implementation’s rate control algorithm will use whenuseMinQpisVK_TRUE. -
useMaxQpindicates whether the QP values determined by rate control will be clamped to the upper bounds on the QP values specified inmaxQp. -
maxQpspecifies the upper bounds on the QP values, for each picture type, that the implementation’s rate control algorithm will use whenuseMaxQpisVK_TRUE. -
useMaxFrameSizeindicates whether the implementation’s rate control algorithm should use the values specified inmaxFrameSizeas the upper bounds on the encoded frame size for each picture type. -
maxFrameSizespecifies the upper bounds on the encoded frame size, for each picture type, whenuseMaxFrameSizeisVK_TRUE.
When used, the values in minQp and maxQp guarantee that the
effective QP values used by the implementation will respect those lower and
upper bounds, respectively.
However, limiting the range of QP values that the implementation is able to
use will also limit the capabilities of the implementation’s rate control
algorithm to comply to other constraints.
In particular, the implementation may not be able to comply to the
following:
-
The average and/or peak bitrate values to be used for the encoded bitstream specified in the
averageBitrateandmaxBitratemembers of the VkVideoEncodeRateControlLayerInfoKHR structure. -
The upper bounds on the encoded frame size, for each picture type, specified in the
maxFrameSizemember ofVkVideoEncodeH265RateControlLayerInfoKHR.
|
Note
|
In general, applications need to configure rate control parameters appropriately in order to be able to get the desired rate control behavior, as described in the Video Encode Rate Control section. |
When an instance of this structure is included in the pNext chain of a
VkVideoEncodeRateControlLayerInfoKHR structure specified in one of the
elements of the pLayers array member of the
VkVideoEncodeRateControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command,
VkVideoCodingControlInfoKHR::flags includes
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, and the bound
video session was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, it specifies the
H.265-specific rate control parameters of the rate control layer
corresponding to that element of pLayers.
The VkVideoEncodeH265QpKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265QpKHR {
int32_t qpI;
int32_t qpP;
int32_t qpB;
} VkVideoEncodeH265QpKHR;
-
qpIis the QP to be used for I pictures. -
qpPis the QP to be used for P pictures. -
qpBis the QP to be used for B pictures.
The VkVideoEncodeH265FrameSizeKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265FrameSizeKHR {
uint32_t frameISize;
uint32_t framePSize;
uint32_t frameBSize;
} VkVideoEncodeH265FrameSizeKHR;
GOP Remaining Frames
Besides session level rate control configuration, the application can specify the number of frames per frame type remaining in the group of pictures (GOP).
The VkVideoEncodeH265GopRemainingFrameInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_h265
typedef struct VkVideoEncodeH265GopRemainingFrameInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 useGopRemainingFrames;
uint32_t gopRemainingI;
uint32_t gopRemainingP;
uint32_t gopRemainingB;
} VkVideoEncodeH265GopRemainingFrameInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
useGopRemainingFramesindicates whether the implementation’s rate control algorithm should use the values specified ingopRemainingI,gopRemainingP, andgopRemainingB. IfuseGopRemainingFramesisVK_FALSE, then the values ofgopRemainingI,gopRemainingP, andgopRemainingBare ignored. -
gopRemainingIspecifies the number of I frames the implementation’s rate control algorithm should assume to be remaining in the GOP prior to executing the video encode operation. -
gopRemainingPspecifies the number of P frames the implementation’s rate control algorithm should assume to be remaining in the GOP prior to executing the video encode operation. -
gopRemainingBspecifies the number of B frames the implementation’s rate control algorithm should assume to be remaining in the GOP prior to executing the video encode operation.
Setting useGopRemainingFrames to VK_TRUE and including this
structure in the pNext chain of VkVideoBeginCodingInfoKHR is
only mandatory if the
VkVideoEncodeH265CapabilitiesKHR::requiresGopRemainingFrames
reported for the used video profile is VK_TRUE.
However, implementations may use these remaining frame counts, when
specified, even when it is not required.
In particular, when the application does not use a
regular GOP structure, these values may provide
additional guidance for the implementation’s rate control algorithm.
The VkVideoEncodeH265CapabilitiesKHR::prefersGopRemainingFrames
capability is also used to indicate that the implementation’s rate control
algorithm may operate more accurately if the application specifies the
remaining frame counts using this structure.
As with other rate control guidance values, if the effective order and number of frames encoded by the application are not in line with the remaining frame counts specified in this structure at any given point, then the behavior of the implementation’s rate control algorithm may deviate from the one expected by the application.
H.265 QP Delta Maps
Quantization delta maps used with an H.265 encode profile are referred to as QP delta maps and their texels contain integer values representing QP delta values that are applied in the process of determining the quantization parameters of the encoded picture.
Accordingly, H.265 QP delta maps always have single channel integer formats,
as reported in VkVideoFormatPropertiesKHR::format.
When the rate control mode is
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, the QP delta
values are added to the per slice segment constant QP values that, in
effect, enable the application to explicitly control the used QP values at
the granularity of the used
quantization map texel size.
For all other rate control modes, the QP delta values can be used to offset the QP values that the rate control algorithm would otherwise produce.
H.265 Encode Quantization
Performing H.265 encode operations involves the process of assigning QP values to individual H.265 coding units. This process depends on the used rate control mode, as well as other encode and rate control parameters, as described below:
-
If the configured rate control mode is
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR, then the QP value is initialized by the implementation-specific default rate control algorithm.-
If the video encode operation is issued with a quantization delta map, the QP delta value corresponding to the coding unit, as fetched from the quantization map, is added to the previously determined QP value. If the fetched QP delta value falls outside the supported QP delta value range reported in the
minQpDeltaandmaxQpDeltamembers of VkVideoEncodeH265QuantizationMapCapabilitiesKHR, then the QP value used for the coding unit becomes undefined.
-
-
If the configured rate control mode is
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then the QP value is initialized from the constant QP value specified for the H.265 slice segment the coding unit is part of.-
If the video encode operation is issued with a quantization delta map, the QP delta value corresponding to the coding unit, as fetched from the quantization map, is added to the previously determined QP value. If the fetched QP delta value falls outside the supported QP delta value range reported in the
minQpDeltaandmaxQpDeltamembers of VkVideoEncodeH265QuantizationMapCapabilitiesKHR, then the QP value used for the coding unit becomes undefined.
-
-
If the configured rate control mode is not
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHRorVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then the QP value is initialized by the corresponding rate control algorithm.-
If the video encode operation is issued with a quantization delta map, the QP delta value corresponding to the coding unit, as fetched from the quantization map, is added to the previously determined QP value. If the fetched QP delta value falls outside the supported QP delta value range reported in the
minQpDeltaandmaxQpDeltamembers of VkVideoEncodeH265QuantizationMapCapabilitiesKHR, then the QP value used for the coding unit becomes undefined. -
If the video encode operation is issued with an emphasis map, the rate control will adjust the QP value based on the emphasis value corresponding to the coding unit, as fetched from the quantization map, according to the following equation:
QPnew = f(QPprev,e)
Where QPnew is the resulting QP value, QPprev is the previously determined QP value, e is the emphasis value corresponding to the coding unit, and f is an implementation-defined function for which the following implication is true:
e1 < e2 ⇒ f(QP,e1) ≥ f(QP,e2)
NoteThis means that lower emphasis values will result in higher QP values, whereas higher emphasis values will result in lower QP values, but the function is not strictly decreasing with respect to the input emphasis value for a given input QP value.
-
If clamping to minimum QP values is enabled in the applied rate control layer, then the QP value is clamped to the corresponding minimum QP value.
-
If clamping to maximum QP values is enabled in the applied rate control layer, then the QP value is clamped to the corresponding maximum QP value.
-
-
If
VK_VIDEO_ENCODE_H265_CAPABILITY_CU_QP_DIFF_WRAPAROUND_BIT_KHRis not supported, then the determined QP value is clamped in such a way that theCuQpDeltaValvalue of the encoded coding unit complies to the modified version of equation 8-283 of the ITU-T H.265 Specification.NoteThe effect of this is that the maximum QP difference across subsequent coding units is limited to the [-(26 + QpBdOffsetY / 2), 25 + QpBdOffsetY / 2] range and only has an observable change in behavior when the video encode operation is issued with a QP delta map.
-
In all cases, the final QP value is clamped to the QP value range supported by the video profile, as reported in the
minQpandmaxQpmembers of VkVideoEncodeH265CapabilitiesKHR.
43.21.13. H.265 Encode Requirements
This section described the required H.265 encoding capabilities for
physical devices that have at least one queue family that supports the video
codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, as
returned by vkGetPhysicalDeviceQueueFamilyProperties2 in
VkQueueFamilyVideoPropertiesKHR::videoCodecOperations.
| Video Std Header Name | Version |
|---|---|
|
1.0.0 |
| Video Capability | Requirement | Requirement Type1 |
|---|---|---|
|
- |
min |
|
4096 |
max |
|
4096 |
max |
|
(64,64) |
max |
|
- |
max |
|
- |
min |
|
0 |
min |
|
0 |
min |
|
- |
min |
|
|
min |
|
128000 |
min |
|
1 |
min |
|
(64,64) |
max |
|
|
min |
|
- |
min |
|
|
min |
|
1 |
min |
|
(1,1) |
min |
|
at least one bit set |
implementation-dependent |
|
at least one bit set |
implementation-dependent |
|
0 |
min |
|
0 |
min |
|
0 |
min |
|
1 |
min |
|
- |
implementation-dependent |
|
- |
max |
|
- |
min |
|
- |
implementation-dependent |
|
- |
implementation-dependent |
|
- |
min |
|
- 2 |
min |
|
- 3 |
max |
|
- 3 |
min |
|
0 |
min |
|
2 5 |
min |
|
1 5 |
min |
|
- |
implementation-dependent |
|
- |
implementation-dependent |
- 1
-
The Requirement Type column specifies the requirement is either the minimum value all implementations must support, the maximum value all implementations must support, or the exact value all implementations must support. For bitmasks a minimum value is the least bits all implementations must set, but they may have additional bits set beyond this minimum.
- 2
-
If VkVideoCapabilitiesKHR::
flagsincludesVK_VIDEO_ENCODE_CAPABILITY_QUANTIZATION_DELTA_MAP_BIT_KHRorVK_VIDEO_ENCODE_CAPABILITY_EMPHASIS_MAP_BIT_KHR, then thewidthandheightmembers ofmaxQuantizationMapExtentmust be greater than zero. - 3
-
If VkVideoCapabilitiesKHR::
flagsincludesVK_VIDEO_ENCODE_CAPABILITY_QUANTIZATION_DELTA_MAP_BIT_KHR, thenmaxQpDeltamust be greater thanminQpDelta. - 4
-
If the
videoMaintenance2feature is supported. - 5
-
If VkVideoEncodeIntraRefreshCapabilitiesKHR::
intraRefreshModesis not zero.
43.22. AV1 Encode Operations
Video encode operations using an AV1 encode profile can be used to encode elementary video stream sequences compliant with the AV1 Specification.
|
Note
|
Refer to the Preamble for information on how the Khronos Intellectual Property Rights Policy relates to normative references to external materials not created by Khronos. |
This process is performed according to the video encode operation steps with the codec-specific semantics defined in section 7 of the AV1 Specification:
-
Syntax elements, derived values, and other parameters are applied from the following structures:
-
The
StdVideoAV1SequenceHeaderstructure, the optionalStdVideoEncodeAV1DecoderModelInfostructure, and the optional array ofStdVideoEncodeAV1OperatingPointInfostructures stored in the bound video session parameters object specifying the active sequence header. -
The
StdVideoEncodeAV1PictureInfostructure specifying the AV1 picture information. -
The
StdVideoEncodeAV1ReferenceInfostructures specifying the AV1 reference information corresponding to the optional reconstructed picture and any active reference pictures. -
The encoded bitstream data is written to the destination video bitstream buffer range as defined in the AV1 Encode Bitstream Data Access section.
-
Picture data in the video picture resources corresponding to the used encode input picture, active reference pictures, and optional reconstructed picture is accessed as defined in the AV1 Encode Picture Data Access section.
-
-
The decision on reference picture setup is made according to the parameters specified in the AV1 picture information.
If the parameters adhere to the syntactic and semantic requirements defined in the corresponding sections of the AV1 Specification, as described above, and the DPB slots associated with the active reference pictures all refer to valid picture references, then the video encode operation will complete successfully. Otherwise, the video encode operation may complete unsuccessfully.
43.22.1. AV1 Encode Parameter Overrides
Implementations may override, unless otherwise specified, any of the AV1 encode parameters specified in the following Video Std structures:
-
StdVideoAV1SequenceHeader -
StdVideoEncodeAV1DecoderModelInfo -
StdVideoEncodeAV1OperatingPointInfo -
StdVideoEncodeAV1PictureInfo -
StdVideoEncodeAV1ReferenceInfo
All such AV1 encode parameter overrides must fulfill the conditions defined in the Video Encode Parameter Overrides section.
In addition, implementations must not override any of the following AV1 encode parameters:
-
the following parameters specified in
StdVideoAV1SequenceHeader:-
flags.still_picture -
flags.enable_order_hint -
flags.frame_id_numbers_present_flag -
flags.film_grain_params_present -
flags.timing_info_present_flag -
flags.initial_display_delay_present_flag -
delta_frame_id_length_minus_2 -
additional_frame_id_length_minus_1 -
order_hint_bits_minus_1
-
-
the following parameters specified in the
StdVideoAV1ColorConfigstructure pointed to byStdVideoAV1SequenceHeader::pColorConfig:-
flags.mono_chrome -
flags.color_range -
BitDepth -
subsampling_x -
subsampling_y -
color_primaries -
transfer_characteristics -
matrix_coefficients -
chroma_sample_position
-
-
the following parameters specified in the
StdVideoAV1TimingInfostructure pointed to byStdVideoAV1SequenceHeader::pTimingInfo:-
flags.equal_picture_interval -
num_units_in_display_tick -
time_scale -
num_ticks_per_picture_minus_1
-
-
the parameters specified in
StdVideoEncodeAV1DecoderModelInfo -
the parameters specified in
StdVideoEncodeAV1OperatingPointInfo -
the following parameters specified in
StdVideoEncodeAV1PictureInfo:-
flags.show_frame -
flags.showable_frame -
frame_type -
frame_presentation_time -
current_frame_id -
order_hint -
refresh_frame_flags -
render_width_minus_1 -
render_height_minus_1 -
ref_order_hint -
ref_frame_idx -
delta_frame_id_minus_1
-
-
the following parameters specified in the
StdVideoEncodeAV1ExtensionHeaderstructure pointed to byStdVideoEncodeAV1PictureInfo::pExtensionHeaderwhen VkVideoEncodeAV1PictureInfoKHR::generateObuExtensionHeaderis set toVK_TRUE:-
temporal_id -
spatial_id
-
If VkVideoEncodeAV1PictureInfoKHR::primaryReferenceCdfOnly is
set to VK_TRUE for a video encode operation, the implementation will
not override StdVideoEncodeAV1PictureInfo::primary_ref_frame.
|
Note
|
Implementations supporting the
|
If VkVideoEncodeAV1CapabilitiesKHR::codedPictureAlignment is not
equal to {8,8} for the used video profile, implementations will override
the coded picture’s resolution and parameters related to the width and
height in the following manner:
-
Let
wandhbe thecodedExtent.widthandcodedExtent.heightof the VkVideoPictureResourceInfoKHR structure corresponding to the encode input picture, rounded up to the nearest integer multiple of 8. -
Let
aWandaHbewandhrounded up to the nearest integer multiple ofcodedPictureAlignment.widthandcodedPictureAlignment.heightrespectively. -
If
wequalsaW, no override will occur. Otherwise the coded width will beaW. -
If
hequalsaH, no override will occur. Otherwise the coded height will beaH.
|
Note
|
The AV1 specification codes all resolutions to an 8x8 alignment, but supports unaligned resolutions through implicit cropping. Thus, if the original coded extent, aligned to 8x8, meets the implementation required alignment, no override needs to occur. Otherwise, the implementation cannot code the requested coded extent, so the final resolution in the bitstream is overridden to be aligned to the implementation required alignment. For example, consider an implementation that is only able to output
bitstreams that are 16x16 aligned (as indicated by
VkVideoEncodeAV1CapabilitiesKHR:: |
In case of a video session parameters object
created with
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR,
the following AV1 sequence header parameters
may be overridden by the implementation according to the
quantization map texel size the video
session parameters object was created with:
-
StdVideoAV1SequenceHeader::flags.use_128x128_superblock
This may be necessary to change the AV1 superblock size used during encoding to be compatible with the used quantization map texel size.
In case of AV1 encode parameters stored in video session parameters objects, applications need to use the vkGetEncodedVideoSessionParametersKHR command to determine whether any implementation overrides happened. If the query indicates that implementation overrides were applied, then the application needs to retrieve and use the encoded AV1 sequence header in the bitstream in order to be able to produce a compliant AV1 video bitstream using the AV1 encode parameters stored in the video session parameters object.
In case of any AV1 encode parameters stored in the encoded bitstream
produced by video encode operations, if the implementation supports the
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR
video encode feedback query flag, the
application can use such queries to retrieve feedback about whether any
implementation overrides have been applied to those AV1 encode parameters.
43.22.2. AV1 Encode Bitstream Data Access
Each video encode operation writes either:
-
A single OBU with
obu_typeequal toOBU_FRAMEcomprising of the frame header and tile data of the encoded picture, or -
An OBU with
obu_typeequal toOBU_FRAME_HEADERencapsulating the frame header of the encoded picture, followed by one or more OBUs withobu_typeequal toOBU_TILE_GROUPcomprising of the tile data of the encoded picture.
In addition, if
VkVideoEncodeAV1PictureInfoKHR::generateObuExtensionHeader is
set to VK_TRUE for the video encode operation, then OBU extension
headers are included in the generated bitstream as defined in sections
5.3.1, 5.3.2, and 5.3.3 of the AV1 Specification.
43.22.3. AV1 Encode Picture Data Access
Accesses to image data within a video picture resource happen at the
granularity indicated by
VkVideoCapabilitiesKHR::pictureAccessGranularity, as returned by
vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile.
Accordingly, the complete image subregion of a encode
input picture, reference picture, or
reconstructed picture accessed by video coding
operations using an AV1 encode profile is defined as
the set of texels within the coordinate range:
-
([0,
endX),[0,endY))
Where:
-
endXequalscodedExtent.widthrounded up to the nearest integer multiple ofpictureAccessGranularity.widthand clamped to the width of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure; -
endY equals
codedExtent.heightrounded up to the nearest integer multiple ofpictureAccessGranularity.heightand clamped to the height of the image subresource referred to by the corresponding VkVideoPictureResourceInfoKHR structure;
Where codedExtent is the member of the
VkVideoPictureResourceInfoKHR structure corresponding to the picture.
In case of video encode operations using an AV1 encode
profile, any access to a picture at the coordinates
(x,y), as defined by the AV1
Specification, is an access to the image subresource
referred to by the corresponding
VkVideoPictureResourceInfoKHR structure at the texel coordinates
(x,y).
Implementations may choose not to access some or all texels within particular reference pictures available to a video encode operation (e.g. due to video encode parameter overrides restricting the effective set of used reference pictures, or if the encoding algorithm chooses not to use certain subregions of the reference picture data for sample prediction).
43.22.4. AV1 Reference Names and Semantics
Individual reference frames used in the encoding process have different
semantics, as defined in section 6.10.24 of the AV1
Specification.
The AV1 semantics associated with a reference picture is indicated by the
corresponding enumeration constant defined in the Video Std enumeration type
StdVideoAV1ReferenceName:
-
STD_VIDEO_AV1_REFERENCE_NAME_INTRA_FRAMEidentifies the reference used for intra coding (INTRA_FRAME), as defined in sections 2 and 7.11.2 of the AV1 Specification. -
All other enumeration constants refer to backward or forward references used for inter coding, as defined in sections 2 and 7.11.3 of the AV1 Specification:
-
STD_VIDEO_AV1_REFERENCE_NAME_LAST_FRAMEidentifies theLAST_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_LAST2_FRAMEidentifies theLAST2_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_LAST3_FRAMEidentifies theLAST3_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_GOLDEN_FRAMEidentifies theGOLDEN_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_BWDREF_FRAMEidentifies theBWDREF_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_ALTREF2_FRAMEidentifies theALTREF2_FRAMEreference -
STD_VIDEO_AV1_REFERENCE_NAME_ALTREF_FRAMEidentifies theALTREF_FRAMEreference
-
These enumeration constants are not directly used in any APIs but are used to indirectly index into certain Video Std and Vulkan API parameter arrays.
43.22.5. AV1 Prediction Modes
AV1 encoding supports multiple types of prediction modes, as described in section 6.10.24 of the AV1 Specification.
Possible AV1 encode prediction modes are as follows:
// Provided by VK_KHR_video_encode_av1
typedef enum VkVideoEncodeAV1PredictionModeKHR {
VK_VIDEO_ENCODE_AV1_PREDICTION_MODE_INTRA_ONLY_KHR = 0,
VK_VIDEO_ENCODE_AV1_PREDICTION_MODE_SINGLE_REFERENCE_KHR = 1,
VK_VIDEO_ENCODE_AV1_PREDICTION_MODE_UNIDIRECTIONAL_COMPOUND_KHR = 2,
VK_VIDEO_ENCODE_AV1_PREDICTION_MODE_BIDIRECTIONAL_COMPOUND_KHR = 3,
} VkVideoEncodeAV1PredictionModeKHR;
-
VK_VIDEO_ENCODE_AV1_PREDICTION_MODE_INTRA_ONLY_KHRspecifies the use of intra-only prediction mode, used when encoding AV1 frames of typeSTD_VIDEO_AV1_FRAME_TYPE_KEYorSTD_VIDEO_AV1_FRAME_TYPE_INTRA_ONLY. -
VK_VIDEO_ENCODE_AV1_PREDICTION_MODE_SINGLE_REFERENCE_KHRspecifies the use of single reference prediction mode, used when encoding AV1 frames of typeSTD_VIDEO_AV1_FRAME_TYPE_INTERorSTD_VIDEO_AV1_FRAME_TYPE_SWITCHwithreference_select, as defined in section 6.8.23 of the AV1 Specification, equal to 0. When using this prediction mode, the application must specify a reference picture for at least one AV1 reference name in VkVideoEncodeAV1PictureInfoKHR::referenceNameSlotIndicesthat is supported by the implementation, as reported in VkVideoEncodeAV1CapabilitiesKHR::singleReferenceNameMask. -
VK_VIDEO_ENCODE_AV1_PREDICTION_MODE_UNIDIRECTIONAL_COMPOUND_KHRspecifies the use of unidirectional compound prediction mode, used when encoding AV1 frames of typeSTD_VIDEO_AV1_FRAME_TYPE_INTERorSTD_VIDEO_AV1_FRAME_TYPE_SWITCHwithreference_select, as defined in section 6.8.23 of the AV1 Specification, equal to 1, and both reference names used for prediction are from the same reference frame group, as defined in section 6.10.24 of the AV1 Specification. When using this prediction mode, the application must specify a reference picture for at least two AV1 reference names in VkVideoEncodeAV1PictureInfoKHR::referenceNameSlotIndicesthat is supported by the implementation, as reported in VkVideoEncodeAV1CapabilitiesKHR::unidirectionalCompoundReferenceNameMask, where those two reference names are one of the allowed pairs of reference names, as defined in section 5.11.25 of the AV1 Specification, listed below:-
LAST_FRAMEandLAST2_FRAME, -
LAST_FRAMEandLAST3_FRAME, -
LAST_FRAMEandGOLDEN_FRAME, or -
BWDREF_FRAMEandALTREF_FRAME.
-
-
VK_VIDEO_ENCODE_AV1_PREDICTION_MODE_BIDIRECTIONAL_COMPOUND_KHRspecifies the use of bidirectional compound prediction mode, used when encoding AV1 frames of typeSTD_VIDEO_AV1_FRAME_TYPE_INTERorSTD_VIDEO_AV1_FRAME_TYPE_SWITCHwithreference_select, as defined in section 6.8.23 of the AV1 Specification, equal to 1, and the two reference names used for prediction are from different reference frame groups, as defined in section 6.10.24 of the AV1 Specification. When using this prediction mode, the application must specify a reference picture for at least one AV1 reference name from each reference frame group in VkVideoEncodeAV1PictureInfoKHR::referenceNameSlotIndicesthat is supported by the implementation, as reported in VkVideoEncodeAV1CapabilitiesKHR::bidirectionalCompoundReferenceNameMask.
The effective prediction mode used to encode individual AV1 mode info blocks may use simpler prediction modes than the one set by the application for the frame, as allowed by the AV1 Specification, in particular:
-
Frames encoded with single reference prediction mode may contain mode info blocks encoded with intra-only prediction mode.
-
Frames encoded with unidirectional compound prediction mode may contain mode info blocks encoded with intra-only or single reference prediction mode.
-
Frames encoded with bidirectional compound prediction mode may contain mode info blocks encoded with intra-only, single reference, or unidirectional compound prediction mode.
43.22.6. AV1 Frame and Tile
AV1 frames are partitioned into tiles, as defined in section 2 of the AV1 Specification.
For the purposes of this specification, the AV1 tiles comprising a frame are referred to as the picture partitions of the frame.
43.22.7. AV1 Coding Blocks
AV1 encode supports two types of coding blocks, as defined in section 2 of the AV1 Specification:
-
Superblock.
-
Mode info block.
43.22.8. AV1 Encode Profile
A video profile supporting AV1 video encode operations is specified by
setting VkVideoProfileInfoKHR::videoCodecOperation to
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR and adding a
VkVideoEncodeAV1ProfileInfoKHR structure to the
VkVideoProfileInfoKHR::pNext chain.
The VkVideoEncodeAV1ProfileInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1ProfileInfoKHR {
VkStructureType sType;
const void* pNext;
StdVideoAV1Profile stdProfile;
} VkVideoEncodeAV1ProfileInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stdProfileis aStdVideoAV1Profilevalue specifying the AV1 codec profile, as defined in section A.2 of the AV1 Specification.
43.22.9. AV1 Encode Capabilities
When calling vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for an AV1 encode profile, the
VkVideoCapabilitiesKHR::pNext chain must include a
VkVideoEncodeAV1CapabilitiesKHR structure that will be filled with the
profile-specific capabilities.
The VkVideoEncodeAV1CapabilitiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1CapabilitiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeAV1CapabilityFlagsKHR flags;
StdVideoAV1Level maxLevel;
VkExtent2D codedPictureAlignment;
VkExtent2D maxTiles;
VkExtent2D minTileSize;
VkExtent2D maxTileSize;
VkVideoEncodeAV1SuperblockSizeFlagsKHR superblockSizes;
uint32_t maxSingleReferenceCount;
uint32_t singleReferenceNameMask;
uint32_t maxUnidirectionalCompoundReferenceCount;
uint32_t maxUnidirectionalCompoundGroup1ReferenceCount;
uint32_t unidirectionalCompoundReferenceNameMask;
uint32_t maxBidirectionalCompoundReferenceCount;
uint32_t maxBidirectionalCompoundGroup1ReferenceCount;
uint32_t maxBidirectionalCompoundGroup2ReferenceCount;
uint32_t bidirectionalCompoundReferenceNameMask;
uint32_t maxTemporalLayerCount;
uint32_t maxSpatialLayerCount;
uint32_t maxOperatingPoints;
uint32_t minQIndex;
uint32_t maxQIndex;
VkBool32 prefersGopRemainingFrames;
VkBool32 requiresGopRemainingFrames;
VkVideoEncodeAV1StdFlagsKHR stdSyntaxFlags;
} VkVideoEncodeAV1CapabilitiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeAV1CapabilityFlagBitsKHR indicating supported AV1 encoding capabilities. -
maxLevelis aStdVideoAV1Levelvalue indicating the maximum AV1 level supported by the profile, as defined in section A.3 of the AV1 Specification. -
codedPictureAlignmentindicates the alignment at which the implementation will code pictures. This capability does not impose any valid usage constraints on the application. However, depending on thecodedExtentof the encode input picture resource, this capability may result in a change of the resolution of the encoded picture, as described in more detail below. -
maxTilesindicates the maximum number of AV1 tile columns and rows the implementation supports. -
minTileSizeindicates the minimum extent of individual AV1 tiles the implementation supports. -
maxTileSizeindicates the maximum extent of individual AV1 tiles the implementation supports. -
superblockSizesis a bitmask of VkVideoEncodeAV1SuperblockSizeFlagBitsKHR values indicating the supported AV1 superblock sizes. -
maxSingleReferenceCountindicates the maximum number of reference pictures the implementation supports when using single reference prediction mode. -
singleReferenceNameMaskis a bitmask of supported AV1 reference names when using single reference prediction mode. -
maxUnidirectionalCompoundReferenceCountindicates the maximum number of reference pictures the implementation supports when using unidirectional compound prediction mode. -
maxUnidirectionalCompoundGroup1ReferenceCountindicates the maximum number of reference pictures the implementation supports when using unidirectional compound prediction mode from reference frame group 1, as defined in section 6.10.24 of the AV1 Specification. -
unidirectionalCompoundReferenceNameMaskis a bitmask of supported AV1 reference names when using unidirectional compound prediction mode. -
maxBidirectionalCompoundReferenceCountindicates the maximum number of reference pictures the implementation supports when using bidirectional compound prediction mode. -
maxBidirectionalCompoundGroup1ReferenceCountindicates the maximum number of reference pictures the implementation supports when using bidirectional compound prediction mode from reference frame group 1, as defined in section 6.10.24 of the AV1 Specification. -
maxBidirectionalCompoundGroup2ReferenceCountindicates the maximum number of reference pictures the implementation supports when using bidirectional compound prediction mode from reference frame group 2, as defined in section 6.10.24 of the AV1 Specification. -
bidirectionalCompoundReferenceNameMaskis a bitmask of supported AV1 reference names when using bidirectional compound prediction mode. -
maxTemporalLayerCountindicates the maximum number of AV1 temporal layers supported by the implementation. -
maxSpatialLayerCountindicates the maximum number of AV1 spatial layers supported by the implementation. -
maxOperatingPointsindicates the maximum number of AV1 operating points supported by the implementation. -
minQIndexindicates the minimum quantizer index value supported. -
maxQIndexindicates the maximum quantizer index value supported. -
prefersGopRemainingFramesindicates that the implementation’s rate control algorithm prefers the application to specify the number of frames in each AV1 rate control group remaining in the current group of pictures when beginning a video coding scope. -
requiresGopRemainingFramesindicates that the implementation’s rate control algorithm requires the application to specify the number of frames in each AV1 rate control group remaining in the current group of pictures when beginning a video coding scope. -
stdSyntaxFlagsis a bitmask of VkVideoEncodeAV1StdFlagBitsKHR indicating capabilities related to AV1 syntax elements.
singleReferenceNameMask,
unidirectionalCompoundReferenceNameMask, and
bidirectionalCompoundReferenceNameMask are encoded such that when bit
index i is set, it indicates support for the
AV1 reference name
STD_VIDEO_AV1_REFERENCE_NAME_LAST_FRAME + i.
|
Note
|
These masks indicate which elements of the |
codedPictureAlignment provides information about implementation
limitations to encode arbitrary resolutions.
In particular, some implementations may not be able to generate bitstreams
aligned to the requirements of the AV1 Specification (8x8).
In such cases, the implementation may override the width and height of the bitstream, in order to produce a
bitstream compliant to the AV1 Specification.
If such an override occurs, the encoded resolution of the coded picture is
enlargened, with the texel values used for the texel coordinates outside of
the bounds of the codedExtent of the encode input picture resource
being first governed by the rules regarding the
encode input picture granularity.
Any texel values outside of the region described by the encode input picture
granularity are implementation-defined.
Implementations should use well-defined values to minimize impact on the
produced encoded content.
|
Note
|
This capability does not impose additional application requirements. However, these overrides change the effective resolution of the bitstream and add padding pixels. Applications sensitive to such overrides can use this capability and the corresponding override behavior to compute the cropping needed to reproduce the original input of the encoding and transmit it in a side channel (i.e. by using cropping fields available in a container). Additionally, applications can explicitly consider this alignment in their coded extent, to avoid implementation-defined texel values being included in the encoded content. |
Bits which may be set in
VkVideoEncodeAV1CapabilitiesKHR::flags, indicating the AV1
encoding capabilities supported, are:
// Provided by VK_KHR_video_encode_av1
typedef enum VkVideoEncodeAV1CapabilityFlagBitsKHR {
VK_VIDEO_ENCODE_AV1_CAPABILITY_PER_RATE_CONTROL_GROUP_MIN_MAX_Q_INDEX_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_AV1_CAPABILITY_GENERATE_OBU_EXTENSION_HEADER_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_AV1_CAPABILITY_PRIMARY_REFERENCE_CDF_ONLY_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_AV1_CAPABILITY_FRAME_SIZE_OVERRIDE_BIT_KHR = 0x00000008,
VK_VIDEO_ENCODE_AV1_CAPABILITY_MOTION_VECTOR_SCALING_BIT_KHR = 0x00000010,
// Provided by VK_KHR_video_encode_av1 with VK_KHR_video_encode_intra_refresh
VK_VIDEO_ENCODE_AV1_CAPABILITY_COMPOUND_PREDICTION_INTRA_REFRESH_BIT_KHR = 0x00000020,
} VkVideoEncodeAV1CapabilityFlagBitsKHR;
-
VK_VIDEO_ENCODE_AV1_CAPABILITY_PER_RATE_CONTROL_GROUP_MIN_MAX_Q_INDEX_BIT_KHRspecifies support for specifying different quantizer index values in the members of VkVideoEncodeAV1QIndexKHR. -
VK_VIDEO_ENCODE_AV1_CAPABILITY_GENERATE_OBU_EXTENSION_HEADER_BIT_KHRspecifies support for generating OBU extension headers, as defined in section 5.3.3 of the AV1 Specification. -
VK_VIDEO_ENCODE_AV1_CAPABILITY_PRIMARY_REFERENCE_CDF_ONLY_BIT_KHRspecifies support for using the primary reference frame indicated by the value ofStdVideoEncodeAV1PictureInfo::primary_ref_framein the AV1 picture information only for CDF data reference, as defined in section 6.8.2 of the AV1 Specification. -
VK_VIDEO_ENCODE_AV1_CAPABILITY_FRAME_SIZE_OVERRIDE_BIT_KHRspecifies support for encoding a picture with a frame size different from the maximum frame size defined in the active AV1 sequence header. If this capability is not supported, thenframe_size_override_flagmust not be set in the AV1 picture information of the encoded frame and the coded extent of the encode input picture must match the maximum coded extent allowed by the active AV1 sequence header, i.e. (max_frame_width_minus_1+ 1,max_frame_height_minus_1+ 1). -
VK_VIDEO_ENCODE_AV1_CAPABILITY_MOTION_VECTOR_SCALING_BIT_KHRspecifies support for motion vector scaling, as defined in section 7.11.3.3 of the AV1 Specification. If this capability is not supported, then the coded extent of all active reference pictures must match the coded extent of the encode input picture. This capability may only be supported by a video profile whenVK_VIDEO_ENCODE_AV1_CAPABILITY_FRAME_SIZE_OVERRIDE_BIT_KHRis also supported. -
VK_VIDEO_ENCODE_AV1_CAPABILITY_COMPOUND_PREDICTION_INTRA_REFRESH_BIT_KHRindicates support for encoding frames using unidirectional or bidirectional compound prediction mode with intra refresh enabled.
// Provided by VK_KHR_video_encode_av1
typedef VkFlags VkVideoEncodeAV1CapabilityFlagsKHR;
VkVideoEncodeAV1CapabilityFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoEncodeAV1CapabilityFlagBitsKHR.
Bits which may be set in
VkVideoEncodeAV1CapabilitiesKHR::stdSyntaxFlags, indicating the
capabilities related to the AV1 syntax elements, are:
// Provided by VK_KHR_video_encode_av1
typedef enum VkVideoEncodeAV1StdFlagBitsKHR {
VK_VIDEO_ENCODE_AV1_STD_UNIFORM_TILE_SPACING_FLAG_SET_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_AV1_STD_SKIP_MODE_PRESENT_UNSET_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_AV1_STD_PRIMARY_REF_FRAME_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_AV1_STD_DELTA_Q_BIT_KHR = 0x00000008,
} VkVideoEncodeAV1StdFlagBitsKHR;
-
VK_VIDEO_ENCODE_AV1_STD_UNIFORM_TILE_SPACING_FLAG_SET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoAV1TileInfoFlags::uniform_tile_spacing_flagin the AV1 tile parameters when that value is1, indifferent of the coded extent of the encode input picture and the number of tile columns and rows requested in theTileColsandTileRowsmembers ofStdVideoAV1TileInfo. -
VK_VIDEO_ENCODE_AV1_STD_SKIP_MODE_PRESENT_UNSET_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeAV1PictureInfoFlags::skip_mode_presentwhen that value is0. -
VK_VIDEO_ENCODE_AV1_STD_PRIMARY_REF_FRAME_BIT_KHRspecifies whether the implementation supports using the application-provided value forStdVideoEncodeAV1PictureInfo::primary_ref_frame. -
VK_VIDEO_ENCODE_AV1_STD_DELTA_Q_BIT_KHRspecifies whether the implementation supports using the application-provided values for theDeltaQYDc,DeltaQUDc,DeltaQUAc,DeltaQVDc, andDeltaQVAcmembers ofStdVideoAV1Quantization.
These capability flags provide information to the application about specific AV1 syntax element values that the implementation supports without having to override them and do not otherwise restrict the values that the application can specify for any of the mentioned AV1 syntax elements.
// Provided by VK_KHR_video_encode_av1
typedef VkFlags VkVideoEncodeAV1StdFlagsKHR;
VkVideoEncodeAV1StdFlagsKHR is a bitmask type for setting a mask of
zero or more VkVideoEncodeAV1StdFlagBitsKHR.
Bits which may be set in
VkVideoEncodeAV1CapabilitiesKHR::superblockSizes, indicating the
superblock sizes supported by the implementation, are:
// Provided by VK_KHR_video_encode_av1
typedef enum VkVideoEncodeAV1SuperblockSizeFlagBitsKHR {
VK_VIDEO_ENCODE_AV1_SUPERBLOCK_SIZE_64_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_AV1_SUPERBLOCK_SIZE_128_BIT_KHR = 0x00000002,
} VkVideoEncodeAV1SuperblockSizeFlagBitsKHR;
-
VK_VIDEO_ENCODE_AV1_SUPERBLOCK_SIZE_64_BIT_KHRspecifies that a superblock size of 64x64 is supported. -
VK_VIDEO_ENCODE_AV1_SUPERBLOCK_SIZE_128_BIT_KHRspecifies that a superblock size of 128x128 is supported.
// Provided by VK_KHR_video_encode_av1
typedef VkFlags VkVideoEncodeAV1SuperblockSizeFlagsKHR;
VkVideoEncodeAV1SuperblockSizeFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoEncodeAV1SuperblockSizeFlagBitsKHR.
Implementations must support at least one of
VkVideoEncodeAV1SuperblockSizeFlagBitsKHR.
43.22.10. AV1 Encode Quality Level Properties
When calling vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR
with pVideoProfile->videoCodecOperation specified as
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR, the
VkVideoEncodeAV1QualityLevelPropertiesKHR structure must be included
in the pNext chain of the VkVideoEncodeQualityLevelPropertiesKHR
structure to retrieve additional video encode quality level properties
specific to AV1 encoding.
The VkVideoEncodeAV1QualityLevelPropertiesKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1QualityLevelPropertiesKHR {
VkStructureType sType;
void* pNext;
VkVideoEncodeAV1RateControlFlagsKHR preferredRateControlFlags;
uint32_t preferredGopFrameCount;
uint32_t preferredKeyFramePeriod;
uint32_t preferredConsecutiveBipredictiveFrameCount;
uint32_t preferredTemporalLayerCount;
VkVideoEncodeAV1QIndexKHR preferredConstantQIndex;
uint32_t preferredMaxSingleReferenceCount;
uint32_t preferredSingleReferenceNameMask;
uint32_t preferredMaxUnidirectionalCompoundReferenceCount;
uint32_t preferredMaxUnidirectionalCompoundGroup1ReferenceCount;
uint32_t preferredUnidirectionalCompoundReferenceNameMask;
uint32_t preferredMaxBidirectionalCompoundReferenceCount;
uint32_t preferredMaxBidirectionalCompoundGroup1ReferenceCount;
uint32_t preferredMaxBidirectionalCompoundGroup2ReferenceCount;
uint32_t preferredBidirectionalCompoundReferenceNameMask;
} VkVideoEncodeAV1QualityLevelPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
preferredRateControlFlagsis a bitmask of VkVideoEncodeAV1RateControlFlagBitsKHR values indicating the preferred flags to use for VkVideoEncodeAV1RateControlInfoKHR::flags. -
preferredGopFrameCountindicates the preferred value to use for VkVideoEncodeAV1RateControlInfoKHR::gopFrameCount. -
preferredKeyFramePeriodindicates the preferred value to use for VkVideoEncodeAV1RateControlInfoKHR::keyFramePeriod. -
preferredConsecutiveBipredictiveFrameCountindicates the preferred value to use for VkVideoEncodeAV1RateControlInfoKHR::consecutiveBipredictiveFrameCount. -
preferredTemporalLayerCountindicates the preferred value to use for VkVideoEncodeAV1RateControlInfoKHR::temporalLayerCount. -
preferredConstantQIndexindicates the preferred value to use for VkVideoEncodeAV1PictureInfoKHR::constantQIndexwhen using rate control modeVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. -
preferredMaxSingleReferenceCountindicates the preferred maximum number of reference pictures to use with single reference prediction mode. -
preferredSingleReferenceNameMaskis a bitmask of preferred AV1 reference names when using single reference prediction mode. -
preferredMaxUnidirectionalCompoundReferenceCountindicates the preferred maximum number of reference pictures to use with unidirectional compound prediction mode. -
preferredMaxUnidirectionalCompoundGroup1ReferenceCountindicates the preferred maximum number of reference pictures to use with unidirectional compound prediction mode from reference frame group 1, as defined in section 6.10.24 of the AV1 Specification. -
preferredUnidirectionalCompoundReferenceNameMaskis a bitmask of preferred AV1 reference names when using unidirectional compound prediction mode. -
preferredMaxBidirectionalCompoundReferenceCountindicates the preferred maximum number of reference pictures to use with bidirectional compound prediction mode. -
preferredMaxBidirectionalCompoundGroup1ReferenceCountindicates the preferred maximum number of reference pictures to use with bidirectional compound prediction mode from reference frame group 1, as defined in section 6.10.24 of the AV1 Specification. -
preferredMaxBidirectionalCompoundGroup2ReferenceCountindicates the preferred maximum number of reference pictures to use with bidirectional compound prediction mode from reference frame group 2, as defined in section 6.10.24 of the AV1 Specification. -
preferredBidirectionalCompoundReferenceNameMaskis a bitmask of preferred AV1 reference names when using bidirectional compound prediction mode.
preferredSingleReferenceNameMask,
preferredUnidirectionalCompoundReferenceNameMask, and
preferredBidirectionalCompoundReferenceNameMask are encoded such that
when bit index i is set, it indicates preference for using the
AV1 reference name
STD_VIDEO_AV1_REFERENCE_NAME_LAST_FRAME + i.
43.22.11. AV1 Encode Session
Additional parameters can be specified when creating a video session with an
AV1 encode profile by including an instance of the
VkVideoEncodeAV1SessionCreateInfoKHR structure in the pNext
chain of VkVideoSessionCreateInfoKHR.
The VkVideoEncodeAV1SessionCreateInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1SessionCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 useMaxLevel;
StdVideoAV1Level maxLevel;
} VkVideoEncodeAV1SessionCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
useMaxLevelindicates whether the value ofmaxLevelshould be used by the implementation. When it is set toVK_FALSE, the implementation ignores the value ofmaxLeveland uses the value of VkVideoEncodeAV1CapabilitiesKHR::maxLevel, as reported by vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile. -
maxLevelis aStdVideoAV1Levelvalue specifying the upper bound on the AV1 level for the video bitstreams produced by the created video session.
43.22.12. AV1 Encode Parameter Sets
Video session parameters objects created with
the video codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR
contain a single instance of the following parameter set:
- AV1 Sequence Header
-
Represented by
StdVideoAV1SequenceHeaderstructures and interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
the
StdVideoAV1ColorConfigstructure pointed to bypColorConfigis interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
all other members of
StdVideoAV1ColorConfigare interpreted as defined in section 6.4.2 of the AV1 Specification;
-
-
if
flags.timing_info_present_flagis set, then theStdVideoAV1TimingInfostructure pointed to bypTimingInfois interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoAV1TimingInfoare interpreted as defined in section 6.4.3 of the AV1 Specification;
-
-
all other members of
StdVideoAV1SequenceHeaderare interpreted as defined in section 6.4 of the AV1 Specification.
-
When StdVideoAV1SequenceHeader::flags.timing_info_present_flag is
set, the AV1 sequence header can be amended with AV1 decoder model
information, represented by a StdVideoEncodeAV1DecoderModelInfo
structure and interpreted as follows:
-
reserved1is used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoEncodeAV1DecoderModelInfoare interpreted as defined in section 6.4.4 of the AV1 Specification.
When
StdVideoAV1SequenceHeader::flags.reduced_still_picture_header is
not set, the AV1 sequence header can be amended with AV1 operating point
information, represented by an array of
StdVideoEncodeAV1OperatingPointInfo structures and interpreted as
follows:
-
flags.reservedis used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoEncodeAV1OperatingPointInfoare interpreted as the corresponding element of the respective arrays defined in section 6.4 of the AV1 Specification.
Implementations may override any of these parameters according to the semantics defined in the Video Encode Parameter Overrides section before storing the resulting AV1 sequence header into the video session parameters object. Applications need to use the vkGetEncodedVideoSessionParametersKHR command to determine whether any implementation overrides happened and to retrieve the encoded AV1 sequence header in order to be able to produce a compliant AV1 video bitstream.
The encoded AV1 sequence header retrieved using the
vkGetEncodedVideoSessionParametersKHR command is encoded as a single
OBU with obu_type equal to OBU_SEQUENCE_HEADER, as defined in
section 5.3 of the AV1 Specification.
Such AV1 sequence header overrides may also have cascading effects on the
implementation overrides applied to the encoded bitstream produced by video
encode operations.
If the implementation supports the
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR
video encode feedback query flag, then the
application can use such queries to retrieve feedback about whether any
implementation overrides have been applied to the encoded bitstream.
When a video session parameters object is
created with the codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR, the
VkVideoSessionParametersCreateInfoKHR::pNext chain must include
a VkVideoEncodeAV1SessionParametersCreateInfoKHR structure specifying
the contents of the object.
The VkVideoEncodeAV1SessionParametersCreateInfoKHR structure is
defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1SessionParametersCreateInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoAV1SequenceHeader* pStdSequenceHeader;
const StdVideoEncodeAV1DecoderModelInfo* pStdDecoderModelInfo;
uint32_t stdOperatingPointCount;
const StdVideoEncodeAV1OperatingPointInfo* pStdOperatingPoints;
} VkVideoEncodeAV1SessionParametersCreateInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdSequenceHeaderis a pointer to aStdVideoAV1SequenceHeaderstructure describing parameters of the AV1 sequence header entry to store in the created object. -
pStdDecoderModelInfoisNULLor a pointer to aStdVideoEncodeAV1DecoderModelInfostructure specifying the AV1 decoder model information to store in the created object. -
stdOperatingPointCountis the number of elements in thepStdOperatingPointsarray. -
pStdOperatingPointsisNULLor a pointer to an array ofstdOperatingPointCountnumber ofStdVideoEncodeAV1OperatingPointInfostructures specifying the AV1 operating point information to store in the created object. Each element i specifies the parameter values corresponding to element i of the syntax elements defined in section 6.4 of the AV1 Specification.
43.22.13. AV1 Encoding Parameters
The VkVideoEncodeAV1PictureInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1PictureInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeAV1PredictionModeKHR predictionMode;
VkVideoEncodeAV1RateControlGroupKHR rateControlGroup;
uint32_t constantQIndex;
const StdVideoEncodeAV1PictureInfo* pStdPictureInfo;
int32_t referenceNameSlotIndices[VK_MAX_VIDEO_AV1_REFERENCES_PER_FRAME_KHR];
VkBool32 primaryReferenceCdfOnly;
VkBool32 generateObuExtensionHeader;
} VkVideoEncodeAV1PictureInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
predictionModespecifies the AV1 prediction mode to use for the encoded frame. -
rateControlGroupspecifies the AV1 rate control group to use for the encoded frame when the current rate control mode is notVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. Otherwise it is ignored. -
constantQIndexis the quantizer index to use for the encoded frame if the current rate control mode configured for the video session isVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. -
pStdPictureInfois a pointer to aStdVideoEncodeAV1PictureInfostructure specifying AV1 picture information. -
referenceNameSlotIndicesis an array of seven (VK_MAX_VIDEO_AV1_REFERENCES_PER_FRAME_KHR, which is equal to the Video Std definitionSTD_VIDEO_AV1_REFS_PER_FRAME) signed integer values specifying the index of the DPB slot or a negative integer value for each AV1 reference name used for inter coding. In particular, the DPB slot index for the AV1 reference nameframeis specified inreferenceNameSlotIndices[frame-STD_VIDEO_AV1_REFERENCE_NAME_LAST_FRAME]. -
primaryReferenceCdfOnlycontrols whether the primary reference frame indicated by the value ofpStdPictureInfo->primary_ref_frameis used only for CDF data reference, as defined in sections 6.8.2 of the AV1 Specification. If set toVK_TRUE, then the primary reference frame’s picture data will not be used for sample prediction. -
generateObuExtensionHeadercontrols whether OBU extension headers are generated into the target bitstream, as defined in sections 5.3.1, 5.3.2, and 5.3.3 of the AV1 Specification.
This structure is specified in the pNext chain of the
VkVideoEncodeInfoKHR structure passed to vkCmdEncodeVideoKHR to
specify the codec-specific picture information for an AV1
encode operation.
- Encode Input Picture Information
-
When this structure is specified in the
pNextchain of the VkVideoEncodeInfoKHR structure passed to vkCmdEncodeVideoKHR, the information related to the encode input picture is defined as follows:-
The image subregion used is determined according to the AV1 Encode Picture Data Access section.
-
The encode input picture is associated with the AV1 picture information provided in
pStdPictureInfo.
-
- Std Picture Information
-
The members of the
StdVideoEncodeAV1PictureInfostructure pointed to bypStdPictureInfoare interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
pSegmentationmust beNULLNoteAV1 segmentation is currently not supported in video encode operations. Accordingly, the application needs to set
flags.segmentation_enabledto0andpSegmentationtoNULL. -
pTileInfoisNULLor a pointer to aStdVideoAV1TileInfostructure specifying AV1 tile parameters; -
the
StdVideoAV1Quantizationstructure pointed to bypQuantizationis interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
all other members of
StdVideoAV1Quantizationare interpreted as defined in section 6.8.11 of the AV1 Specification;
-
-
the
StdVideoAV1LoopFilterstructure pointed to bypLoopFilteris interpreted as follows:-
flags.reservedis used only for padding purposes and is otherwise ignored; -
update_ref_deltais a bitmask where bit index i is interpreted as the value ofupdate_ref_deltacorresponding to element i ofloop_filter_ref_deltasas defined in section 6.8.10 of the AV1 Specification; -
update_mode_deltais a bitmask where bit index i is interpreted as the value ofupdate_mode_deltacorresponding to element i ofloop_filter_mode_deltasas defined in section 6.8.10 of the AV1 Specification; -
all other members of
StdVideoAV1LoopFilterare interpreted as defined in section 6.8.10 of the AV1 Specification;
-
-
if
flags.enable_cdefis set in the active sequence header, then the members of theStdVideoAV1CDEFstructure pointed to bypCDEFare interpreted as follows:-
cdef_y_sec_strengthandcdef_uv_sec_strengthare the bitstream values of the corresponding syntax elements defined in section 5.9.19 of the AV1 Specification; -
all other members of
StdVideoAV1CDEFare interpreted as defined in section 6.10.14 of the AV1 Specification;
-
-
if
flags.UsesLris set in the active sequence header, then theStdVideoAV1LoopRestorationstructure pointed to bypLoopRestorationis interpreted as follows:-
LoopRestorationSize[plane] is interpreted as log2(size) - 5, wheresizeis the value ofLoopRestorationSize[plane] as defined in section 6.10.15 of the AV1 Specification; -
all other members of
StdVideoAV1LoopRestorationare defined as in section 6.10.15 of the AV1 Specification;
-
-
the members of the
StdVideoAV1GlobalMotionstructure provided inglobal_motionare interpreted as defined in section 7.10 of the AV1 Specification; -
pExtensionHeaderisNULLor a pointer to aStdVideoEncodeAV1ExtensionHeaderstructure whosetemporal_idandspatial_idmembers specify the temporal and spatial layer ID of the reference frame, respectively (these IDs are encoded into the OBU extension header if VkVideoEncodeAV1PictureInfoKHR::generateObuExtensionHeaderis set toVK_TRUEfor the encode operation); -
if
flags.buffer_removal_time_present_flagis set, thenpBufferRemovalTimesis a pointer to an array of N number of unsigned integer values specifying the elements of thebuffer_removal_timearray, as defined in section 6.8.2 of the AV1 Specification, where N is the number of operating points specified for the active sequence header through VkVideoEncodeAV1SessionParametersCreateInfoKHR::stdOperatingPointCount; -
all other members are interpreted as defined in section 6.8 of the AV1 Specification.
-
Reference picture setup is controlled by the value of
StdVideoEncodeAV1PictureInfo::refresh_frame_flags.
If it is not zero and a reconstructed
picture is specified, then the latter is used as the target of picture
reconstruction to activate the DPB slot
specified in pEncodeInfo->pSetupReferenceSlot->slotIndex.
If StdVideoEncodeAV1PictureInfo::refresh_frame_flags is zero, but
a reconstructed picture is specified,
then the corresponding picture reference associated with the DPB
slot is invalidated, as described in the DPB Slot
States section.
- Std Tile Parameters
-
Specifying AV1 tile parameters is optional. If
StdVideoEncodeAV1PictureInfo::pTileInfoisNULL, then the implementation determines the values of AV1 tile parameters defined in section 6.8.14 of the AV1 Specification in an implementation-dependent manner. IfStdVideoEncodeAV1PictureInfo::pTileInfois notNULL, then the members of theStdVideoAV1TileInfostructure pointed to byStdVideoEncodeAV1PictureInfo::pTileInfoare interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
TileColsandTileRowsspecify the number of tile columns and tile rows as defined in section 6.8.14 of the AV1 Specification; -
tile_size_bytes_minus_1is ignored, as its value, as defined in section 6.8.14 of the AV1 Specification, is determined as the result of the encoding process; -
pMiColStartsandpMiRowStartsare ignored, as the elements of theMiColStartsandMiRowStartsarrays defined in section 6.8.14 of the AV1 Specification are determined by the implementation based on the tile widths and heights determined by the implementation or specified through thepWidthInSbsMinus1andpHeightInSbsMinus1arrays, respectively; -
pWidthInSbsMinus1isNULLor a pointer to an array ofTileColsnumber of unsigned integers that corresponds towidth_in_sbs_minus_1defined in section 6.8.14 of the AV1 Specification; -
pHeightInSbsMinus1isNULLor is a pointer to an array ofTileRowsnumber of unsigned integers that corresponds toheight_in_sbs_minus_1defined in section 6.8.14 of the AV1 Specification; -
all other members of
StdVideoAV1TileInfoare interpreted as defined in section 6.8.14 of the AV1 Specification.
-
If flags.uniform_tile_spacing_flag is set, then pWidthInSbsMinus1
and pHeightInSbsMinus1 are ignored.
If flags.uniform_tile_spacing_flag is not set and
pWidthInSbsMinus1 is NULL, then the width of individual tile columns
is determined in an implementation-dependent manner.
If flags.uniform_tile_spacing_flag is not set and
pHeightInSbsMinus1 is NULL, then the height of individual tile rows
is determined in an implementation-dependent manner.
|
Note
|
In general, implementations are expected to respect the application-specified AV1 tile parameters. However, as implementations may have restrictions on the combination of tile column and row counts, and tile widths and heights with respect to the extent of the encoded frame beyond the restrictions specified in the AV1 Specification and this specification (through video profile capabilities), certain parameter combinations may require the implementation to override them in order to conform to such implementation-specific limitations. |
- Active Parameter Sets
-
The active sequence header is the AV1 sequence header stored in the bound video session parameters object.
The VkVideoEncodeAV1DpbSlotInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1DpbSlotInfoKHR {
VkStructureType sType;
const void* pNext;
const StdVideoEncodeAV1ReferenceInfo* pStdReferenceInfo;
} VkVideoEncodeAV1DpbSlotInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pStdReferenceInfois a pointer to aStdVideoEncodeAV1ReferenceInfostructure specifying AV1 reference information.
This structure is specified in the pNext chain of
VkVideoEncodeInfoKHR::pSetupReferenceSlot, if not NULL, and
the pNext chain of the elements of
VkVideoEncodeInfoKHR::pReferenceSlots to specify the
codec-specific reference picture information for an AV1 encode
operation.
- Active Reference Picture Information
-
When this structure is specified in the
pNextchain of the elements of VkVideoEncodeInfoKHR::pReferenceSlots, one element is added to the list of active reference pictures used by the video encode operation for each element of VkVideoEncodeInfoKHR::pReferenceSlotsas follows:-
The image subregion used is determined according to the AV1 Encode Picture Data Access section.
-
The reference picture is associated with the DPB slot index specified in the
slotIndexmember of the corresponding element of VkVideoEncodeInfoKHR::pReferenceSlots. -
The reference picture is associated with the AV1 reference information provided in
pStdReferenceInfo.
-
- Reconstructed Picture Information
-
When this structure is specified in the
pNextchain of VkVideoEncodeInfoKHR::pSetupReferenceSlot, the information related to the reconstructed picture is defined as follows:-
The image subregion used is determined according to the AV1 Encode Picture Data Access section.
-
If reference picture setup is requested, then the reconstructed picture is used to activate the DPB slot with the index specified in VkVideoEncodeInfoKHR::
pSetupReferenceSlot->slotIndex. -
The reconstructed picture is associated with the AV1 reference information provided in
pStdReferenceInfo.
-
- Std Reference Information
-
The members of the
StdVideoEncodeAV1ReferenceInfostructure pointed to bypStdReferenceInfoare interpreted as follows:-
flags.reservedandreserved1are used only for padding purposes and are otherwise ignored; -
flags.disable_frame_end_update_cdfis interpreted as defined in section 6.8.2 of the AV1 Specification; -
flags.segmentation_enabledis interpreted as defined in section 6.8.13 of the AV1 Specification; -
RefFrameIdis interpreted as the element of theRefFrameIdarray defined in section 6.8.2 of the AV1 Specification corresponding to the reference frame; -
frame_typeis interpreted as defined in section 6.8.2 of the AV1 Specification; -
OrderHintis interpreted as defined in section 6.8.2 of the AV1 Specification; -
pExtensionHeaderisNULLor a pointer to aStdVideoEncodeAV1ExtensionHeaderstructure whosetemporal_idandspatial_idmembers specify the temporal and spatial layer ID of the reference frame, respectively.
-
43.22.14. AV1 Encode Rate Control
Group of Pictures
In case of AV1 encoding it is common practice to follow a regular pattern of frame types and prediction directions in display order when encoding subsequent frames. This pattern is referred to as the group of pictures (GOP).
The AV1 Specification, unlike some other video compression
standards, does not restrict the direction in display order of the
referenced frames based on the used frame type or
AV1 prediction mode.
Accordingly, this specification introduces the concept of rate control
groups for which the application can specify separate rate control
configuration parameters.
When encoding a frame, the application specifies the rate control group the
encoded frame belongs to through a VkVideoEncodeAV1RateControlGroupKHR
value in VkVideoEncodeAV1PictureInfoKHR::rateControlGroup.
This value is then used by the implementation’s rate control algorithm to
determine which rate control configuration parameters apply to it.
Possible AV1 encode rate control groups are as follows:
// Provided by VK_KHR_video_encode_av1
typedef enum VkVideoEncodeAV1RateControlGroupKHR {
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_INTRA_KHR = 0,
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_PREDICTIVE_KHR = 1,
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHR = 2,
} VkVideoEncodeAV1RateControlGroupKHR;
-
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_INTRA_KHRshould be specified when encoding AV1 frames that use intra-only prediction (e.g. when encoding AV1 frames of typeSTD_VIDEO_AV1_FRAME_TYPE_KEYorSTD_VIDEO_AV1_FRAME_TYPE_INTRA_ONLY). -
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_PREDICTIVE_KHRshould be specified when encoding AV1 frames that only have forward references in display order. -
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHRshould be specified when encoding AV1 frames that have backward references in display order.
|
Note
|
While the application can specify any rate control group for any frame, indifferent of the frame type, prediction mode, or prediction direction, specifying a rate control group that does not reflect the prediction direction used by the encoded frame may result in unexpected behavior of the implementation’s rate control algorithm. |
A regular GOP is defined by the following parameters:
-
The number of frames in the GOP;
-
The number of consecutive frames encoded with
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHRbetween frames encoded with other rate control groups in display order.
GOPs are further classified as open and closed GOPs.
Frame types in an open GOP follow each other in display order according to the following algorithm:
-
The first frame is always a frame encoded with
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_INTRA_KHR. -
This is followed by a number of consecutive frames encoded with
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHR. -
If the number of frames in the GOP is not reached yet, then the next frame is a frame encoded with
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_PREDICTIVE_KHRand the algorithm continues from step 2.
In case of a closed GOP, a frame with the AV1 frame type
STD_VIDEO_AV1_FRAME_TYPE_KEY is used at a certain period.
It is also typical for AV1 encoding to use specific reference picture usage patterns across the frames of the GOP. The two most common reference patterns used are as follows:
- Flat Reference Pattern
-
-
Each frame encoded with
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_PREDICTIVE_KHRrefers to the last frame that was not encoded usingVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHR, in display order, as its forward reference. -
Each frame encoded with
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHRrefers to the last frame that was not encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHR, in display order, as its forward reference, and refers to the next frame that was not encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHR, in display order, as its backward reference.
-
- Dyadic Reference Pattern
-
-
Each frame encoded with
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_PREDICTIVE_KHRrefers to the last frame that was not encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHR, in display order, as its forward reference. -
The following algorithm is applied to the sequence of consecutive frames encoded with
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHRbetween frames using other rate control groups in display order:-
The frame in the middle of this sequence uses the frame preceding the sequence as its forward reference, and uses the frame following the sequence as its backward reference.
-
The algorithm is executed recursively for the following frame sequences:
-
The frames of the original sequence preceding the frame in the middle, if any.
-
The frames of the original sequence following the frame in the middle, if any.
-
-
-
The application can provide guidance to the implementation’s rate control algorithm about the structure of the GOP used by the application. Any such guidance about the GOP and its structure does not mandate that specific GOP structure to be used by the application, as the frame type and the selected rate control group is still application-controlled, however, any deviation from the provided guidance may result in undesired rate control behavior including, but not limited, to the implementation not being able to conform to the expected average or target bitrates, or other rate control parameters specified by the application.
When an AV1 encode session is used to encode multiple temporal layers, it is also common practice to follow a regular pattern for the AV1 temporal ID for the encoded frames in display order when encoding subsequent frames. This pattern is referred to as the temporal GOP. The most common temporal layer pattern used is as follows:
- Dyadic Temporal Layer Pattern
-
-
The number of frames in the temporal GOP is 2n-1, where n is the number of temporal layers.
-
The ith frame in the temporal GOP uses temporal ID t, if and only if the index of the least significant bit set in i equals n-t-1, except for the first frame, which is the only frame in the temporal GOP using temporal ID zero.
-
The ith frame in the temporal GOP uses the rth frame as reference, where r is calculated from i by clearing the least significant bit set in it, except for the first frame in the temporal GOP, which uses the first frame of the previous temporal GOP, if any, as reference.
-
|
Note
|
Multi-layer rate control and multi-layer coding are typically used for streaming cases where low latency is expected, hence frames usually do not use backward references in display order. |
The VkVideoEncodeAV1RateControlInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1RateControlInfoKHR {
VkStructureType sType;
const void* pNext;
VkVideoEncodeAV1RateControlFlagsKHR flags;
uint32_t gopFrameCount;
uint32_t keyFramePeriod;
uint32_t consecutiveBipredictiveFrameCount;
uint32_t temporalLayerCount;
} VkVideoEncodeAV1RateControlInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkVideoEncodeAV1RateControlFlagBitsKHR specifying AV1 rate control flags. -
gopFrameCountis the number of frames within a group of pictures (GOP) intended to be used by the application. If it is set to 0, the rate control algorithm may assume an implementation-dependent GOP length. If it is set toUINT32_MAX, the GOP length is treated as infinite. -
keyFramePeriodis the interval, in terms of number of frames, between two frames with the AV1 frame typeSTD_VIDEO_AV1_FRAME_TYPE_KEY(see key frame period). If it is set to 0, the rate control algorithm may assume an implementation-dependent key frame period. If it is set toUINT32_MAX, the key frame period is treated as infinite. -
consecutiveBipredictiveFrameCountis the number of consecutive frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHRbetween frames encoded with other rate control groups within the GOP. -
temporalLayerCountspecifies the number of AV1 temporal layers that the application intends to use.
When an instance of this structure is included in the pNext chain of
the VkVideoCodingControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command, and
VkVideoCodingControlInfoKHR::flags includes
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, the parameters in
this structure are used as guidance for the implementation’s rate control
algorithm (see Video Coding Control).
Bits which can be set in
VkVideoEncodeAV1RateControlInfoKHR::flags, specifying AV1 rate
control flags, are:
// Provided by VK_KHR_video_encode_av1
typedef enum VkVideoEncodeAV1RateControlFlagBitsKHR {
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_REGULAR_GOP_BIT_KHR = 0x00000001,
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_TEMPORAL_LAYER_PATTERN_DYADIC_BIT_KHR = 0x00000002,
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR = 0x00000004,
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR = 0x00000008,
} VkVideoEncodeAV1RateControlFlagBitsKHR;
-
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_REGULAR_GOP_BIT_KHRspecifies that the application intends to use a regular GOP structure according to the parameters specified in thegopFrameCountandkeyFramePeriodmembers of the VkVideoEncodeAV1RateControlInfoKHR structure. -
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_TEMPORAL_LAYER_PATTERN_DYADIC_BIT_KHRspecifies that the application intends to follow a dyadic temporal layer pattern. -
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHRspecifies that the application intends to follow a flat reference pattern in the GOP. -
VK_VIDEO_ENCODE_AV1_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHRspecifies that the application intends to follow a dyadic reference pattern in the GOP.
// Provided by VK_KHR_video_encode_av1
typedef VkFlags VkVideoEncodeAV1RateControlFlagsKHR;
VkVideoEncodeAV1RateControlFlagsKHR is a bitmask type for setting a
mask of zero or more VkVideoEncodeAV1RateControlFlagBitsKHR.
Rate Control Layers
The VkVideoEncodeAV1RateControlLayerInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1RateControlLayerInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 useMinQIndex;
VkVideoEncodeAV1QIndexKHR minQIndex;
VkBool32 useMaxQIndex;
VkVideoEncodeAV1QIndexKHR maxQIndex;
VkBool32 useMaxFrameSize;
VkVideoEncodeAV1FrameSizeKHR maxFrameSize;
} VkVideoEncodeAV1RateControlLayerInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
useMinQIndexindicates whether the quantizer index values determined by rate control will be clamped to the lower bounds on the quantizer index values specified inminQIndex. -
minQIndexspecifies the lower bounds on the quantizer index values, for each rate control group, that the implementation’s rate control algorithm will use whenuseMinQIndexis set toVK_TRUE. -
useMaxQIndexindicates whether the quantizer index values determined by rate control will be clamped to the upper bounds on the quantizer index values specified inmaxQIndex. -
maxQIndexspecifies the upper bounds on the quantizer index values, for each rate control group, that the implementation’s rate control algorithm will use whenuseMaxQIndexis set toVK_TRUE. -
useMaxFrameSizeindicates whether the implementation’s rate control algorithm should use the values specified inmaxFrameSizeas the upper bounds on the encoded frame size for each rate control group. -
maxFrameSizespecifies the upper bounds on the encoded frame size, for each rate control group, whenuseMaxFrameSizeis set toVK_TRUE.
When used, the values in minQIndex and maxQIndex guarantee that
the effective quantizer index values used by the implementation will respect
those lower and upper bounds, respectively.
However, limiting the range of quantizer index values that the
implementation is able to use will also limit the capabilities of the
implementation’s rate control algorithm to comply to other constraints.
In particular, the implementation may not be able to comply to the
following:
-
The average and/or peak bitrate values to be used for the encoded bitstream specified in the
averageBitrateandmaxBitratemembers of the VkVideoEncodeRateControlLayerInfoKHR structure. -
The upper bounds on the encoded frame size, for each rate control group, specified in the
maxFrameSizemember ofVkVideoEncodeAV1RateControlLayerInfoKHR.
|
Note
|
In general, applications need to configure rate control parameters appropriately in order to be able to get the desired rate control behavior, as described in the Video Encode Rate Control section. |
When an instance of this structure is included in the pNext chain of a
VkVideoEncodeRateControlLayerInfoKHR structure specified in one of the
elements of the pLayers array member of the
VkVideoEncodeRateControlInfoKHR structure passed to the
vkCmdControlVideoCodingKHR command,
VkVideoCodingControlInfoKHR::flags includes
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, and the bound
video session was created with the video codec operation
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR, it specifies the
AV1-specific rate control parameters of the rate control layer corresponding
to that element of pLayers.
The VkVideoEncodeAV1QIndexKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1QIndexKHR {
uint32_t intraQIndex;
uint32_t predictiveQIndex;
uint32_t bipredictiveQIndex;
} VkVideoEncodeAV1QIndexKHR;
-
intraQIndexis the quantizer index to be used for frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_INTRA_KHR. -
predictiveQIndexis the quantizer index to be used for frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_PREDICTIVE_KHR. -
bipredictiveQIndexis the quantizer index to be used for frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHR.
The VkVideoEncodeAV1FrameSizeKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1FrameSizeKHR {
uint32_t intraFrameSize;
uint32_t predictiveFrameSize;
uint32_t bipredictiveFrameSize;
} VkVideoEncodeAV1FrameSizeKHR;
-
intraFrameSizeis the size in bytes to be used for frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_INTRA_KHR. -
predictiveFrameSizeis the size in bytes to be used for frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_PREDICTIVE_KHR. -
bipredictiveFrameSizeis the size in bytes to be used for frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHR.
GOP Remaining Frames
Besides session level rate control configuration, the application can specify the number of frames per frame type remaining in the group of pictures (GOP).
The VkVideoEncodeAV1GopRemainingFrameInfoKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkVideoEncodeAV1GopRemainingFrameInfoKHR {
VkStructureType sType;
const void* pNext;
VkBool32 useGopRemainingFrames;
uint32_t gopRemainingIntra;
uint32_t gopRemainingPredictive;
uint32_t gopRemainingBipredictive;
} VkVideoEncodeAV1GopRemainingFrameInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
useGopRemainingFramesindicates whether the implementation’s rate control algorithm should use the values specified ingopRemainingIntra,gopRemainingPredictive, andgopRemainingBipredictive. IfuseGopRemainingFramesisVK_FALSE, then the values ofgopRemainingIntra,gopRemainingPredictive, andgopRemainingBipredictiveare ignored. -
gopRemainingIntraspecifies the number of frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_INTRA_KHRthe implementation’s rate control algorithm should assume to be remaining in the GOP prior to executing the next video encode operation. -
gopRemainingPredictivespecifies the number of frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_PREDICTIVE_KHRthe implementation’s rate control algorithm should assume to be remaining in the GOP prior to executing the next video encode operation. -
gopRemainingBipredictivespecifies the number of frames encoded withVK_VIDEO_ENCODE_AV1_RATE_CONTROL_GROUP_BIPREDICTIVE_KHRthe implementation’s rate control algorithm should assume to be remaining in the GOP prior to executing the next video encode operation.
Setting useGopRemainingFrames to VK_TRUE and including this
structure in the pNext chain of VkVideoBeginCodingInfoKHR is
only mandatory if the
VkVideoEncodeAV1CapabilitiesKHR::requiresGopRemainingFrames
reported for the used video profile is VK_TRUE.
However, implementations may use these remaining frame counts, when
specified, even when it is not required.
In particular, when the application does not use a
regular GOP structure, these values may provide
additional guidance for the implementation’s rate control algorithm.
The VkVideoEncodeAV1CapabilitiesKHR::prefersGopRemainingFrames
capability is also used to indicate that the implementation’s rate control
algorithm may operate more accurately if the application specifies the
remaining frame counts using this structure.
As with other rate control guidance values, if the effective order and number of frames encoded by the application are not in line with the remaining frame counts specified in this structure at any given point, then the behavior of the implementation’s rate control algorithm may deviate from the one expected by the application.
AV1 Quantizer Index Delta Maps
Quantization delta maps used with an AV1 encode profile are referred to as quantizer index delta maps and their texels contain integer values representing quantizer index delta values that are applied in the process of determining the quantizer indices of the encoded picture.
Accordingly, AV1 quantizer index delta maps always have single channel
integer formats, as reported in
VkVideoFormatPropertiesKHR::format.
When the rate control mode is
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, the quantizer
index delta values are added to the constant quantizer index value that, in
effect, enable the application to explicitly control the used quantizer
index values at the granularity of the used
quantization map texel size.
For all other rate control modes, the quantizer index delta values can be used to offset the quantizer index values that the rate control algorithm would otherwise produce.
AV1 Encode Quantization
Performing AV1 encode operations involves the process of assigning quantizer index values to individual AV1 mode info blocks. This process depends on the used rate control mode, as well as other encode and rate control parameters, as described below:
-
If the configured rate control mode is
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR, then the quantizer index value is initialized by the implementation-specific default rate control algorithm.-
If the video encode operation is issued with a quantization delta map, the quantizer index delta value corresponding to the mode info block, as fetched from the quantization map, is added to the previously determined quantizer index value. If the fetched quantizer index delta value falls outside the supported quantizer index delta value range reported in the
minQIndexDeltaandmaxQIndexDeltamembers of VkVideoEncodeAV1QuantizationMapCapabilitiesKHR, then the quantizer index value used for the mode info block becomes undefined.
-
-
If the configured rate control mode is
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then the quantizer index value is initialized from the constant quantizer index value specified for the encoded frame.-
If the video encode operation is issued with a quantization delta map, the quantizer index delta value corresponding to the mode info block, as fetched from the quantization map, is added to the previously determined quantizer index value. If the fetched quantizer index delta value falls outside the supported quantizer index delta value range reported in the
minQIndexDeltaandmaxQIndexDeltamembers of VkVideoEncodeAV1QuantizationMapCapabilitiesKHR, then the quantizer index value used for the mode info block becomes undefined.
-
-
If the configured rate control mode is not
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHRorVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then the quantizer index value is initialized by the corresponding rate control algorithm.-
If the video encode operation is issued with a quantization delta map, the quantizer index delta value corresponding to the mode info block, as fetched from the quantization map, is added to the previously determined quantizer index value. If the fetched quantizer index delta value falls outside the supported quantizer index delta value range reported in the
minQIndexDeltaandmaxQIndexDeltamembers of VkVideoEncodeAV1QuantizationMapCapabilitiesKHR, then the quantizer index value used for the mode info block becomes undefined. -
If the video encode operation is issued with an emphasis map, the rate control will adjust the quantizer index value based on the emphasis value corresponding to the mode info block, as fetched from the quantization map, according to the following equation:
QIndexnew = f(QIndexprev,e)
Where QIndexnew is the resulting quantizer index value, QIndexprev is the previously determined quantizer index value, e is the emphasis value corresponding to the macroblock, and f is an implementation-defined function for which the following implication is true:
e1 < e2 ⇒ f(QIndex,e1) ≥ f(QIndex,e2)
NoteThis means that lower emphasis values will result in higher quantizer index values, whereas higher emphasis values will result in lower quantizer index values, but the function is not strictly decreasing with respect to the input emphasis value for a given input quantizer index value.
-
If clamping to minimum quantizer index values is enabled in the applied rate control layer, then the quantizer index value is clamped to the corresponding minimum quantizer index value.
-
If clamping to maximum quantizer index values is enabled in the applied rate control layer, then the quantizer index value is clamped to the corresponding maximum quantizer index value.
-
-
In all cases, the final quantizer index value is clamped to the minimum and maximum quantizer index values supported by the video profile.
43.22.15. AV1 Encode Requirements
This section described the required AV1 encoding capabilities for physical
devices that have at least one queue family that supports the video codec
operation VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR, as returned by
vkGetPhysicalDeviceQueueFamilyProperties2 in
VkQueueFamilyVideoPropertiesKHR::videoCodecOperations.
| Video Std Header Name | Version |
|---|---|
|
1.0.0 |
| Video Capability | Requirement | Requirement Type1 |
|---|---|---|
|
- |
min |
|
4096 |
max |
|
4096 |
max |
|
(64,64) |
max |
|
- |
max |
|
- |
min |
|
0 |
min |
|
0 |
min |
|
- |
min |
|
|
min |
|
5529600 |
min |
|
1 |
min |
|
(64,64) |
max |
|
|
min |
|
- |
min |
|
(8,8) |
min |
|
1 |
min |
|
- |
max |
|
- |
min |
|
|
min |
|
at least one bit set |
implementation-dependent |
|
0 |
min |
|
- 2 |
min |
|
0 3 |
min |
|
0 3,4 |
min |
|
- 2 |
min |
|
0 3 |
min |
|
0 3,5 |
min |
|
0 3,5 |
min |
|
- 2 |
min |
|
1 |
min |
|
1 |
min |
|
0 |
min |
|
- |
max |
|
- |
min |
|
- |
implementation-dependent |
|
- |
implementation-dependent |
|
- |
min |
|
- 6 |
min |
|
- 7 |
max |
|
- 7 |
min |
|
0 |
min |
|
2 9 |
min |
|
1 9 |
min |
|
- |
implementation-dependent |
|
- |
implementation-dependent |
- 1
-
The Requirement Type column specifies the requirement is either the minimum value all implementations must support, the maximum value all implementations must support, or the exact value all implementations must support. For bitmasks a minimum value is the least bits all implementations must set, but they may have additional bits set beyond this minimum.
- 2
-
These masks must only have bits set in the least significant
VK_MAX_VIDEO_AV1_REFERENCES_PER_FRAME_KHRbits (bit index i indicates support for the AV1 reference nameSTD_VIDEO_AV1_REFERENCE_NAME_LAST_FRAME+ i when using the corresponding AV1 prediction mode), and must have at least as many bits set in any*ReferenceNameMaskcapability as the value of the correspondingmax*ReferenceCountcapability. - 3
-
If greater than zero, it must be at least
2. - 4
-
maxUnidirectionalCompoundGroup1ReferenceCountmust be less than or equal tomaxUnidirectionalCompoundReferenceCount - 5
-
The sum of
maxBidirectionalCompoundGroup1ReferenceCountandmaxBidirectionalCompoundGroup2ReferenceCountmust be greater than or equal tomaxBidirectionalCompoundReferenceCount - 6
-
If VkVideoCapabilitiesKHR::
flagsincludesVK_VIDEO_ENCODE_CAPABILITY_QUANTIZATION_DELTA_MAP_BIT_KHRorVK_VIDEO_ENCODE_CAPABILITY_EMPHASIS_MAP_BIT_KHR, then thewidthandheightmembers ofmaxQuantizationMapExtentmust be greater than zero. - 7
-
If VkVideoCapabilitiesKHR::
flagsincludesVK_VIDEO_ENCODE_CAPABILITY_QUANTIZATION_DELTA_MAP_BIT_KHR, thenmaxQIndexDeltamust be greater thanminQIndexDelta. - 8
-
If the
videoMaintenance2feature is supported. - 9
-
If VkVideoEncodeIntraRefreshCapabilitiesKHR::
intraRefreshModesis not zero.
44. Optical Flow
44.1. Optical Flow Queues
VK_NV_optical_flow adds an optical flow queue type bit
VK_QUEUE_OPTICAL_FLOW_BIT_NV to VkQueueFlagBits.
Optical flow operations are supported by queues with an advertised queue
capability of VK_QUEUE_OPTICAL_FLOW_BIT_NV.
As in the case of other queue types, an application must use
vkGetPhysicalDeviceQueueFamilyProperties to query whether the physical
device has support for the Optical Flow Queue.
When the implementation reports the VK_QUEUE_OPTICAL_FLOW_BIT_NV bit
for a queue family, it advertises general support for Vulkan queue
operations described in Devices and Queues.
44.2. Optical Flow Image Formats
To enumerate the supported image formats for a specific optical flow usage, call:
// Provided by VK_NV_optical_flow
VkResult vkGetPhysicalDeviceOpticalFlowImageFormatsNV(
VkPhysicalDevice physicalDevice,
const VkOpticalFlowImageFormatInfoNV* pOpticalFlowImageFormatInfo,
uint32_t* pFormatCount,
VkOpticalFlowImageFormatPropertiesNV* pImageFormatProperties);
-
physicalDeviceis the physical device being queried. -
pOpticalFlowImageFormatInfois a pointer to a VkOpticalFlowImageFormatInfoNV structure specifying the optical flow usage for which information is returned. -
pFormatCountis a pointer to an integer related to the number of optical flow properties available or queried, as described below. -
pImageFormatPropertiesis a pointer to an array of VkOpticalFlowImageFormatPropertiesNV structures in which supported formats and image parameters are returned.
If pImageFormatProperties is NULL, then the number of optical flow
properties supported for the given physicalDevice is returned in
pFormatCount.
Otherwise, pFormatCount must point to a variable set by the
application to the number of elements in the pImageFormatProperties
array, and on return the variable is overwritten with the number of values
actually written to pImageFormatProperties.
If the value of pFormatCount is less than the number of optical flow
properties supported, at most pFormatCount values will be written to
pImageFormatProperties, and VK_INCOMPLETE will be returned
instead of VK_SUCCESS, to indicate that not all the available values
were returned.
Before creating an image to be used as an optical flow frame, obtain the
supported image creation parameters by querying with
vkGetPhysicalDeviceFormatProperties2 and
vkGetPhysicalDeviceImageFormatProperties2 using one of the reported
formats and adding VkOpticalFlowImageFormatInfoNV to the pNext
chain of VkPhysicalDeviceImageFormatInfo2.
When querying the parameters with
vkGetPhysicalDeviceImageFormatProperties2 for images used for optical
flow operations, the VkOpticalFlowImageFormatInfoNV::usage field
must contain one or more of the bits defined in
VkOpticalFlowUsageFlagBitsNV.
|
Note
|
|
The VkOpticalFlowImageFormatInfoNV structure is defined as:
// Provided by VK_NV_optical_flow
typedef struct VkOpticalFlowImageFormatInfoNV {
VkStructureType sType;
const void* pNext;
VkOpticalFlowUsageFlagsNV usage;
} VkOpticalFlowImageFormatInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
usageis a bitmask of VkOpticalFlowUsageFlagBitsNV describing the intended optical flow usage of the image.
Bits which can be set in VkOpticalFlowImageFormatInfoNV::usage,
controlling optical flow usage, are:
// Provided by VK_NV_optical_flow
typedef enum VkOpticalFlowUsageFlagBitsNV {
VK_OPTICAL_FLOW_USAGE_UNKNOWN_NV = 0,
VK_OPTICAL_FLOW_USAGE_INPUT_BIT_NV = 0x00000001,
VK_OPTICAL_FLOW_USAGE_OUTPUT_BIT_NV = 0x00000002,
VK_OPTICAL_FLOW_USAGE_HINT_BIT_NV = 0x00000004,
VK_OPTICAL_FLOW_USAGE_COST_BIT_NV = 0x00000008,
VK_OPTICAL_FLOW_USAGE_GLOBAL_FLOW_BIT_NV = 0x00000010,
} VkOpticalFlowUsageFlagBitsNV;
-
VK_OPTICAL_FLOW_USAGE_INPUT_BIT_NVspecifies that the image can be used as input or reference frame for an optical flow operation. -
VK_OPTICAL_FLOW_USAGE_OUTPUT_BIT_NVspecifies that the image can be used as output flow vector map for an optical flow operation. -
VK_OPTICAL_FLOW_USAGE_HINT_BIT_NVspecifies that the image can be used as hint flow vector map for an optical flow operation. -
VK_OPTICAL_FLOW_USAGE_COST_BIT_NVspecifies that the image can be used as output cost map for an optical flow operation. -
VK_OPTICAL_FLOW_USAGE_GLOBAL_FLOW_BIT_NVspecifies that the image can be used as global flow vector for an optical flow operation.
// Provided by VK_NV_optical_flow
typedef VkFlags VkOpticalFlowUsageFlagsNV;
VkOpticalFlowUsageFlagsNV is a bitmask type for setting a mask of zero
or more VkOpticalFlowUsageFlagBitsNV.
The VkOpticalFlowImageFormatPropertiesNV structure is defined as:
// Provided by VK_NV_optical_flow
typedef struct VkOpticalFlowImageFormatPropertiesNV {
VkStructureType sType;
const void* pNext;
VkFormat format;
} VkOpticalFlowImageFormatPropertiesNV;
-
sTypeis a VkStructureType value identifying 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 optical flow image usages.
44.3. Optical Flow Session
44.3.1. Optical Flow Session Object
Optical flow session objects are abstracted and represented by VkOpticalFlowSessionNV handles:
// Provided by VK_NV_optical_flow
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkOpticalFlowSessionNV)
Creating an Optical Flow Session
To create an optical flow session object, call:
// Provided by VK_NV_optical_flow
VkResult vkCreateOpticalFlowSessionNV(
VkDevice device,
const VkOpticalFlowSessionCreateInfoNV* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkOpticalFlowSessionNV* pSession);
-
deviceis the logical device that creates the optical flow session object. -
pCreateInfois a pointer to a VkOpticalFlowSessionCreateInfoNV structure containing parameters specifying the creation of the optical flow session. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pSessionis a pointer to a VkOpticalFlowSessionNV handle specifying the optical flow session object which will be created by this function when it returnsVK_SUCCESS
The VkOpticalFlowSessionCreateInfoNV structure is defined as:
// Provided by VK_NV_optical_flow
typedef struct VkOpticalFlowSessionCreateInfoNV {
VkStructureType sType;
void* pNext;
uint32_t width;
uint32_t height;
VkFormat imageFormat;
VkFormat flowVectorFormat;
VkFormat costFormat;
VkOpticalFlowGridSizeFlagsNV outputGridSize;
VkOpticalFlowGridSizeFlagsNV hintGridSize;
VkOpticalFlowPerformanceLevelNV performanceLevel;
VkOpticalFlowSessionCreateFlagsNV flags;
} VkOpticalFlowSessionCreateInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
widthis the width in pixels of the input or reference frame to be bound to this optical flow session. -
heightis the height in pixels of the input or reference frame to be bound to this optical flow session. -
imageFormatis the VkFormat of the input and reference frame to be bound to this optical flow session. -
flowVectorFormatis the VkFormat of the flow vector maps (output or hint) to be bound to this optical flow session. -
costFormatis the VkFormat of the cost maps to be bound to this optical flow session. -
outputGridSizeis exactly one bit of VkOpticalFlowGridSizeFlagsNV specifying the grid size of the output flow and cost maps to be bound to this optical flow session. The size of the output flow and cost maps is determined byVkOpticalFlowSessionCreateInfoNV::widthandVkOpticalFlowSessionCreateInfoNV::heightdivided byVkOpticalFlowSessionCreateInfoNV::outputGridSize. -
hintGridSizeis one exactly bit of VkOpticalFlowGridSizeFlagsNV specifying the grid size of the hint flow vector maps to be bound to this optical flow session. The size of the hint maps is determined byVkOpticalFlowSessionCreateInfoNV::widthandVkOpticalFlowSessionCreateInfoNV::heightdivided byVkOpticalFlowSessionCreateInfoNV::hintGridSize. -
performanceLevelis the VkOpticalFlowPerformanceLevelNV used for this optical flow session. -
flagsare the VkOpticalFlowSessionCreateFlagsNV used for this optical flow session.
The VkOpticalFlowSessionCreatePrivateDataInfoNV structure is for NV internal use only and is defined as:
// Provided by VK_NV_optical_flow
typedef struct VkOpticalFlowSessionCreatePrivateDataInfoNV {
VkStructureType sType;
void* pNext;
uint32_t id;
uint32_t size;
const void* pPrivateData;
} VkOpticalFlowSessionCreatePrivateDataInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
idis an identifier for data which is passed at a memory location specified inVkOpticalFlowSessionCreatePrivateDataInfoNV::pPrivateData. -
sizeis the size of data in bytes which is passed at a memory location specified inVkOpticalFlowSessionCreatePrivateDataInfoNV::pPrivateData. -
pPrivateDatais a pointer to NV internal data.
Optical flow vectors are generated block-wise, one vector for each block of NxN pixels (referred to as grid).
Bits which can be set in
VkOpticalFlowSessionCreateInfoNV::outputGridSize and
VkOpticalFlowSessionCreateInfoNV::hintGridSize, or which are
returned in
VkPhysicalDeviceOpticalFlowPropertiesNV::supportedOutputGridSizes
and
VkPhysicalDeviceOpticalFlowPropertiesNV::supportedHintGridSizes
controlling optical flow grid sizes, are:
// Provided by VK_NV_optical_flow
typedef enum VkOpticalFlowGridSizeFlagBitsNV {
VK_OPTICAL_FLOW_GRID_SIZE_UNKNOWN_NV = 0,
VK_OPTICAL_FLOW_GRID_SIZE_1X1_BIT_NV = 0x00000001,
VK_OPTICAL_FLOW_GRID_SIZE_2X2_BIT_NV = 0x00000002,
VK_OPTICAL_FLOW_GRID_SIZE_4X4_BIT_NV = 0x00000004,
VK_OPTICAL_FLOW_GRID_SIZE_8X8_BIT_NV = 0x00000008,
} VkOpticalFlowGridSizeFlagBitsNV;
-
VK_OPTICAL_FLOW_GRID_SIZE_1X1_BIT_NVspecifies that grid is 1x1 pixel. -
VK_OPTICAL_FLOW_GRID_SIZE_2X2_BIT_NVspecifies that grid is 2x2 pixel. -
VK_OPTICAL_FLOW_GRID_SIZE_4X4_BIT_NVspecifies that grid is 4x4 pixel. -
VK_OPTICAL_FLOW_GRID_SIZE_8X8_BIT_NVspecifies that grid is 8x8 pixel.
// Provided by VK_NV_optical_flow
typedef VkFlags VkOpticalFlowGridSizeFlagsNV;
VkOpticalFlowGridSizeFlagsNV is a bitmask type for setting a mask of
zero or more VkOpticalFlowGridSizeFlagBitsNV.
Optical flow exposes performance levels which the application can choose based on the desired performance and quality requirement.
The optical flow performance level types are defined with the following:
// Provided by VK_NV_optical_flow
typedef enum VkOpticalFlowPerformanceLevelNV {
VK_OPTICAL_FLOW_PERFORMANCE_LEVEL_UNKNOWN_NV = 0,
VK_OPTICAL_FLOW_PERFORMANCE_LEVEL_SLOW_NV = 1,
VK_OPTICAL_FLOW_PERFORMANCE_LEVEL_MEDIUM_NV = 2,
VK_OPTICAL_FLOW_PERFORMANCE_LEVEL_FAST_NV = 3,
} VkOpticalFlowPerformanceLevelNV;
-
VK_OPTICAL_FLOW_PERFORMANCE_LEVEL_SLOW_NVis a level with slower performance but higher quality. -
VK_OPTICAL_FLOW_PERFORMANCE_LEVEL_MEDIUM_NVis a level with medium performance and medium quality. -
VK_OPTICAL_FLOW_PERFORMANCE_LEVEL_FAST_NVis a preset with higher performance but lower quality.
Bits which can be set in
VkOpticalFlowSessionCreateInfoNV::flags, controlling optical
flow session operations, are:
// Provided by VK_NV_optical_flow
typedef enum VkOpticalFlowSessionCreateFlagBitsNV {
VK_OPTICAL_FLOW_SESSION_CREATE_ENABLE_HINT_BIT_NV = 0x00000001,
VK_OPTICAL_FLOW_SESSION_CREATE_ENABLE_COST_BIT_NV = 0x00000002,
VK_OPTICAL_FLOW_SESSION_CREATE_ENABLE_GLOBAL_FLOW_BIT_NV = 0x00000004,
VK_OPTICAL_FLOW_SESSION_CREATE_ALLOW_REGIONS_BIT_NV = 0x00000008,
VK_OPTICAL_FLOW_SESSION_CREATE_BOTH_DIRECTIONS_BIT_NV = 0x00000010,
} VkOpticalFlowSessionCreateFlagBitsNV;
-
VK_OPTICAL_FLOW_SESSION_CREATE_ENABLE_HINT_BIT_NVspecifies that a VkImageView with external flow vectors will be used as hints in performing the motion search and must be bound toVK_OPTICAL_FLOW_SESSION_BINDING_POINT_HINT_NV. -
VK_OPTICAL_FLOW_SESSION_CREATE_ENABLE_COST_BIT_NVspecifies that the cost for the forward flow is generated in a VkImageView which must be bound toVK_OPTICAL_FLOW_SESSION_BINDING_POINT_COST_NV. Additionally, ifVK_OPTICAL_FLOW_SESSION_CREATE_BOTH_DIRECTIONS_BIT_NVis also set, the cost for backward flow is generated in a VkImageView which must be bound toVK_OPTICAL_FLOW_SESSION_BINDING_POINT_BACKWARD_COST_NV. The cost is the confidence level of the flow vector for each grid in the frame. The Cost implies how (in)accurate the flow vector is. Higher cost value implies the flow vector to be less accurate and vice-versa. -
VK_OPTICAL_FLOW_SESSION_CREATE_ENABLE_GLOBAL_FLOW_BIT_NVspecifies that a global flow vector is estimated from forward flow in a single pixel VkImageView which must be bound toVK_OPTICAL_FLOW_SESSION_BINDING_POINT_GLOBAL_FLOW_NV. -
VK_OPTICAL_FLOW_SESSION_CREATE_ALLOW_REGIONS_BIT_NVspecifies that regions of interest can be specified in VkOpticalFlowExecuteInfoNV. -
VK_OPTICAL_FLOW_SESSION_CREATE_BOTH_DIRECTIONS_BIT_NVspecifies that backward flow is generated in addition to forward flow which is always generated.
VkOpticalFlowSessionCreateFlagsNV is a bitmask type for setting a mask
of zero or more VkOpticalFlowSessionCreateFlagBitsNV.
// Provided by VK_NV_optical_flow
typedef VkFlags VkOpticalFlowSessionCreateFlagsNV;
Destroying an Optical Flow Session
To destroy an optical flow session object, call:
// Provided by VK_NV_optical_flow
void vkDestroyOpticalFlowSessionNV(
VkDevice device,
VkOpticalFlowSessionNV session,
const VkAllocationCallbacks* pAllocator);
-
deviceis the device that was used for the creation of the optical flow session. -
sessionis the optical flow session to be destroyed. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
44.3.2. Binding Vulkan Image Views to an Optical Flow Session
To bind a Vulkan image to an optical flow session object, call:
// Provided by VK_NV_optical_flow
VkResult vkBindOpticalFlowSessionImageNV(
VkDevice device,
VkOpticalFlowSessionNV session,
VkOpticalFlowSessionBindingPointNV bindingPoint,
VkImageView view,
VkImageLayout layout);
-
deviceis the device which owns the optical flow session objectsession. -
sessionis the optical flow session object to which the image view is to be bound. -
bindingPointspecifies the binding point VkOpticalFlowSessionBindingPointNV to which the image view is bound. -
viewis a VkImageView to be bound. -
layoutmust specify the layout that the image subresources accessible fromviewwill be in at the time the optical flow vectors are calculated with vkCmdOpticalFlowExecuteNV on aVkDevice.
The optical flow session binding points are defined with the following:
// Provided by VK_NV_optical_flow
typedef enum VkOpticalFlowSessionBindingPointNV {
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_UNKNOWN_NV = 0,
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_INPUT_NV = 1,
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_REFERENCE_NV = 2,
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_HINT_NV = 3,
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_FLOW_VECTOR_NV = 4,
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_BACKWARD_FLOW_VECTOR_NV = 5,
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_COST_NV = 6,
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_BACKWARD_COST_NV = 7,
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_GLOBAL_FLOW_NV = 8,
} VkOpticalFlowSessionBindingPointNV;
-
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_INPUT_NVspecifies the binding point for the input frame. -
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_REFERENCE_NVspecifies the binding point for the input reference frame. -
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_HINT_NVspecifies the binding point for the optional external hint flow vectors. -
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_FLOW_VECTOR_NVspecifies the binding point for output flow vectors of default forward flow calculation. -
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_BACKWARD_FLOW_VECTOR_NVspecifies the binding point for the optional output flow vector map of optional backward flow calculation. -
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_COST_NVspecifies the binding point for the optional output cost map of default forward flow calculation. -
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_BACKWARD_COST_NVspecifies the binding point for the optional output cost map of optional backward flow calculation. -
VK_OPTICAL_FLOW_SESSION_BINDING_POINT_GLOBAL_FLOW_NVspecifies the binding point for the optional global flow value of default forward flow calculation.
44.3.3. Optical Flow Execution
Default direction of flow estimation is forward which calculates the optical flow from input frame to reference frame. Optionally backward flow estimation can be additionally calculated. An output flow vector (Vx, Vy) means that current pixel (x, y) of input frame can be found at location (x+Vx, y+Vy) in reference frame. A backward flow vector (Vx, Vy) means that current pixel (x, y) of reference frame can be found at location (x+Vx, y+Vy) in input frame.
To calculate optical flow vectors from two input frames, call:
// Provided by VK_NV_optical_flow
void vkCmdOpticalFlowExecuteNV(
VkCommandBuffer commandBuffer,
VkOpticalFlowSessionNV session,
const VkOpticalFlowExecuteInfoNV* pExecuteInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
sessionis the optical flow session object on which this command is operating. -
pExecuteInfoInfo is a pointer to a VkOpticalFlowExecuteInfoNV.
The VkOpticalFlowExecuteInfoNV structure is defined as:
// Provided by VK_NV_optical_flow
typedef struct VkOpticalFlowExecuteInfoNV {
VkStructureType sType;
void* pNext;
VkOpticalFlowExecuteFlagsNV flags;
uint32_t regionCount;
const VkRect2D* pRegions;
} VkOpticalFlowExecuteInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsare the VkOpticalFlowExecuteFlagsNV used for this command. -
regionCountis the number of regions of interest specified inpRegions. -
pRegionsis a pointer toregionCountVkRect2Dregions of interest.
Bits which can be set in VkOpticalFlowExecuteInfoNV::flags,
controlling optical flow execution, are:
// Provided by VK_NV_optical_flow
typedef enum VkOpticalFlowExecuteFlagBitsNV {
VK_OPTICAL_FLOW_EXECUTE_DISABLE_TEMPORAL_HINTS_BIT_NV = 0x00000001,
} VkOpticalFlowExecuteFlagBitsNV;
-
VK_OPTICAL_FLOW_EXECUTE_DISABLE_TEMPORAL_HINTS_BIT_NVspecifies that temporal hints from previously generated flow vectors are not used. If temporal hints are enabled, optical flow vectors from previous vkCmdOpticalFlowExecuteNV call are automatically used as hints for the current vkCmdOpticalFlowExecuteNV call, to take advantage of temporal correlation in a video sequence. Temporal hints should be disabled if there is a-priori knowledge of no temporal correlation (e.g. a scene change, independent successive frame pairs).
VkOpticalFlowExecuteFlagsNV is a bitmask type for setting a mask of
zero or more VkOpticalFlowExecuteFlagBitsNV.
// Provided by VK_NV_optical_flow
typedef VkFlags VkOpticalFlowExecuteFlagsNV;
45. Execution Graphs
Execution graphs provide a way for applications to dispatch multiple operations dynamically from a single initial command on the host. To achieve this, a new execution graph pipeline is provided, that links together multiple shaders or pipelines which each describe one or more operations that can be dispatched within the execution graph. Each linked pipeline or shader describes an execution node within the graph, which can be dispatched dynamically from another shader within the same graph. This allows applications to describe much richer execution topologies at a finer granularity than would typically be possible with API commands alone.
45.1. Pipeline Creation
To create execution graph pipelines, call:
// Provided by VK_AMDX_shader_enqueue
VkResult vkCreateExecutionGraphPipelinesAMDX(
VkDevice device,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkExecutionGraphPipelineCreateInfoAMDX* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
deviceis the logical device that creates the execution graph 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. The implementation must not access this object outside of the duration of this command. -
createInfoCountis the length of thepCreateInfosandpPipelinesarrays. -
pCreateInfosis a pointer to an array of VkExecutionGraphPipelineCreateInfoAMDX 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 execution graph pipeline objects are returned.
Pipelines are created and returned as described for Multiple Pipeline Creation.
The VkExecutionGraphPipelineCreateInfoAMDX structure is defined as:
// Provided by VK_AMDX_shader_enqueue
typedef struct VkExecutionGraphPipelineCreateInfoAMDX {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags flags;
uint32_t stageCount;
const VkPipelineShaderStageCreateInfo* pStages;
const VkPipelineLibraryCreateInfoKHR* pLibraryInfo;
VkPipelineLayout layout;
VkPipeline basePipelineHandle;
int32_t basePipelineIndex;
} VkExecutionGraphPipelineCreateInfoAMDX;
-
sTypeis a VkStructureType value identifying 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 execution graph pipeline. -
pLibraryInfois a pointer to a VkPipelineLibraryCreateInfoKHR structure defining pipeline libraries to include. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. The implementation must not access this object outside of the duration of the command this structure is passed to. -
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.
Each shader stage provided when creating an execution graph pipeline
(including those in libraries) is associated with a name and an index,
determined by the inclusion or omission of a
VkPipelineShaderStageNodeCreateInfoAMDX structure in its pNext
chain.
For any graphics pipeline libraries, only the name and index of the vertex
or mesh shader stage is linked directly to the graph as a node - other
shader stages in the pipeline will be executed after those shader stages as
normal.
Task shaders cannot be included in a graphics pipeline used for a draw node.
In addition to the shader name and index, an internal "node index" is also generated for each node, which can be queried with vkGetExecutionGraphPipelineNodeIndexAMDX, and is used exclusively for initial dispatch of an execution graph.
VK_SHADER_INDEX_UNUSED_AMDX is a special shader index used to indicate
that the created node does not override the index.
In this case, the shader index is determined through other means.
It is defined as:
#define VK_SHADER_INDEX_UNUSED_AMDX (~0U)
The VkPipelineShaderStageNodeCreateInfoAMDX structure is defined as:
// Provided by VK_AMDX_shader_enqueue
typedef struct VkPipelineShaderStageNodeCreateInfoAMDX {
VkStructureType sType;
const void* pNext;
const char* pName;
uint32_t index;
} VkPipelineShaderStageNodeCreateInfoAMDX;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pNameis the shader name to use when creating a node in an execution graph. IfpNameisNULL, the name of the entry point specified in SPIR-V is used as the shader name. -
indexis the shader index to use when creating a node in an execution graph. IfindexisVK_SHADER_INDEX_UNUSED_AMDXthen the original index is used, either as specified by theShaderIndexAMDXexecution mode, or0if that too is not specified.
When included in the pNext chain of a
VkPipelineShaderStageCreateInfo structure, this structure specifies
the shader name and shader index of a node when creating an execution graph
pipeline.
If this structure is omitted, the shader name is set to the name of the
entry point in SPIR-V and the shader index is set to 0.
When dispatching a node from another shader, the name is fixed at pipeline creation, but the index can be set dynamically. By associating multiple shaders with the same name but different indexes, applications can dynamically select different nodes to execute. Applications must ensure each node has a unique name and index.
|
Note
|
Shaders with the same name must be of the same type - e.g. a compute and graphics shader, or even two compute shaders where one is coalescing and the other is not, cannot share the same name. |
To query the internal node index for a particular node in an execution graph, call:
// Provided by VK_AMDX_shader_enqueue
VkResult vkGetExecutionGraphPipelineNodeIndexAMDX(
VkDevice device,
VkPipeline executionGraph,
const VkPipelineShaderStageNodeCreateInfoAMDX* pNodeInfo,
uint32_t* pNodeIndex);
-
deviceis the logical device thatexecutionGraphwas created on. -
executionGraphis the execution graph pipeline to query the internal node index for. -
pNodeInfois a pointer to a VkPipelineShaderStageNodeCreateInfoAMDX structure identifying the name and index of the node to query. -
pNodeIndexis the returned internal node index of the identified node.
Once this function returns, the contents of pNodeIndex contain the
internal node index of the identified node.
45.2. Initializing Scratch Memory
Implementations may need scratch memory to manage dispatch queues or similar when executing a pipeline graph, and this is explicitly managed by the application.
To query the scratch space required to dispatch an execution graph, call:
// Provided by VK_AMDX_shader_enqueue
VkResult vkGetExecutionGraphPipelineScratchSizeAMDX(
VkDevice device,
VkPipeline executionGraph,
VkExecutionGraphPipelineScratchSizeAMDX* pSizeInfo);
-
deviceis the logical device thatexecutionGraphwas created on. -
executionGraphis the execution graph pipeline to query the scratch space for. -
pSizeInfois a pointer to a VkExecutionGraphPipelineScratchSizeAMDX structure that will contain the required scratch size.
After this function returns, information about the scratch space required
will be returned in pSizeInfo.
The VkExecutionGraphPipelineScratchSizeAMDX structure is defined as:
// Provided by VK_AMDX_shader_enqueue
typedef struct VkExecutionGraphPipelineScratchSizeAMDX {
VkStructureType sType;
void* pNext;
VkDeviceSize minSize;
VkDeviceSize maxSize;
VkDeviceSize sizeGranularity;
} VkExecutionGraphPipelineScratchSizeAMDX;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minSizeindicates the minimum scratch space required for dispatching the queried execution graph. -
maxSizeindicates the maximum scratch space that can be used for dispatching the queried execution graph. -
sizeGranularityindicates the granularity at which the scratch space can be increased fromminSize.
Applications can use any amount of scratch memory greater than
minSize for dispatching a graph, however only the values equal to
minSize + an integer multiple of sizeGranularity will be used.
Greater values may result in higher performance, up to maxSize which
indicates the most memory that an implementation can use effectively.
To initialize scratch memory for a particular execution graph, call:
// Provided by VK_AMDX_shader_enqueue
void vkCmdInitializeGraphScratchMemoryAMDX(
VkCommandBuffer commandBuffer,
VkPipeline executionGraph,
VkDeviceAddress scratch,
VkDeviceSize scratchSize);
-
commandBufferis the command buffer into which the command will be recorded. -
executionGraphis the execution graph pipeline to initialize the scratch memory for. -
scratchis the address of scratch memory to be initialized. -
scratchSizeis a range in bytes of scratch memory to be initialized.
This command must be called before using scratch to dispatch the
bound execution graph pipeline.
Execution of this command may modify any memory locations in the range
[scratch,scratch + scratchSize).
Accesses to this memory range are performed in the
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the
VK_ACCESS_2_SHADER_STORAGE_READ_BIT and
VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT access flags.
If any portion of scratch is modified by any command other than
vkCmdDispatchGraphAMDX, vkCmdDispatchGraphIndirectAMDX,
vkCmdDispatchGraphIndirectCountAMDX, or
vkCmdInitializeGraphScratchMemoryAMDX with the same execution graph,
it must be reinitialized for the execution graph again before dispatching
against it.
45.3. Dispatching a Graph
Initial dispatch of an execution graph is done from the host in the same way as any other command, and can be used in a similar way to compute dispatch commands, with indirect variants available.
To record an execution graph dispatch, call:
// Provided by VK_AMDX_shader_enqueue
void vkCmdDispatchGraphAMDX(
VkCommandBuffer commandBuffer,
VkDeviceAddress scratch,
VkDeviceSize scratchSize,
const VkDispatchGraphCountInfoAMDX* pCountInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
scratchis the address of scratch memory to be used. -
scratchSizeis a range in bytes of scratch memory to be used. -
pCountInfois a host pointer to a VkDispatchGraphCountInfoAMDX structure defining the nodes which will be initially executed.
When this command is executed, the nodes specified in pCountInfo are
executed.
Nodes executed as part of this command are not implicitly synchronized in
any way against each other once they are dispatched.
There are no rasterization order guarantees between separately dispatched
graphics nodes, though individual primitives within a single dispatch do
adhere to rasterization order.
Draw calls executed before or after the execution graph also execute
relative to each graphics node with respect to rasterization order.
For this command, all device/host pointers in substructures are treated as host pointers and read only during host execution of this command. Once this command returns, no reference to the original pointers is retained.
Execution of this command may modify any memory locations in the range
[scratch,scratch + scratchSize).
Accesses to this memory range are performed in the
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the
VK_ACCESS_2_SHADER_STORAGE_READ_BIT and
VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT access flags.
This command captures command buffer state for mesh nodes similarly to draw commands.
To record an execution graph dispatch with node and payload parameters read on device, call:
// Provided by VK_AMDX_shader_enqueue
void vkCmdDispatchGraphIndirectAMDX(
VkCommandBuffer commandBuffer,
VkDeviceAddress scratch,
VkDeviceSize scratchSize,
const VkDispatchGraphCountInfoAMDX* pCountInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
scratchis the address of scratch memory to be used. -
scratchSizeis a range in bytes of scratch memory to be used. -
pCountInfois a host pointer to a VkDispatchGraphCountInfoAMDX structure defining the nodes which will be initially executed.
When this command is executed, the nodes specified in pCountInfo are
executed.
Nodes executed as part of this command are not implicitly synchronized in
any way against each other once they are dispatched.
There are no rasterization order guarantees between separately dispatched
graphics nodes, though individual primitives within a single dispatch do
adhere to rasterization order.
Draw calls executed before or after the execution graph also execute
relative to each graphics node with respect to rasterization order.
For this command, all device/host pointers in substructures are treated as
device pointers and read during device execution of this command.
The allocation and contents of these pointers only needs to be valid during
device execution.
All of these addresses will be read in the
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the
VK_ACCESS_2_SHADER_STORAGE_READ_BIT access flag.
Execution of this command may modify any memory locations in the range
[scratch,scratch + scratchSize).
Accesses to this memory range are performed in the
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the
VK_ACCESS_2_SHADER_STORAGE_READ_BIT and
VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT access flags.
This command captures command buffer state for mesh nodes similarly to draw commands.
To record an execution graph dispatch with all parameters read on device, call:
// Provided by VK_AMDX_shader_enqueue
void vkCmdDispatchGraphIndirectCountAMDX(
VkCommandBuffer commandBuffer,
VkDeviceAddress scratch,
VkDeviceSize scratchSize,
VkDeviceAddress countInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
scratchis the address of scratch memory to be used. -
scratchSizeis a range in bytes of scratch memory to be used. -
countInfois a device address of a VkDispatchGraphCountInfoAMDX structure defining the nodes which will be initially executed.
When this command is executed, the nodes specified in countInfo are
executed.
Nodes executed as part of this command are not implicitly synchronized in
any way against each other once they are dispatched.
For this command, all pointers in substructures are treated as device
pointers and read during device execution of this command.
The allocation and contents of these pointers only needs to be valid during
device execution.
All of these addresses will be read in the
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the
VK_ACCESS_2_SHADER_STORAGE_READ_BIT access flag.
Execution of this command may modify any memory locations in the range
[scratch,scratch + scratchSize).
Accesses to this memory range are performed in the
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT pipeline stage with the
VK_ACCESS_2_SHADER_STORAGE_READ_BIT and
VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT access flags.
The VkDeviceOrHostAddressConstAMDX union is defined as:
// Provided by VK_AMDX_shader_enqueue
typedef union VkDeviceOrHostAddressConstAMDX {
VkDeviceAddress deviceAddress;
const void* hostAddress;
} VkDeviceOrHostAddressConstAMDX;
-
deviceAddressis a buffer device address as returned by the vkGetBufferDeviceAddressKHR command. -
hostAddressis a const host memory address.
The VkDispatchGraphCountInfoAMDX structure is defined as:
// Provided by VK_AMDX_shader_enqueue
typedef struct VkDispatchGraphCountInfoAMDX {
uint32_t count;
VkDeviceOrHostAddressConstAMDX infos;
uint64_t stride;
} VkDispatchGraphCountInfoAMDX;
-
countis the number of dispatches to perform. -
infosis the device or host address of a flat array of VkDispatchGraphInfoAMDX structures -
strideis the byte stride between successive VkDispatchGraphInfoAMDX structures ininfos
Whether infos is consumed as a device or host pointer is defined by
the command this structure is used in.
The VkDispatchGraphInfoAMDX structure is defined as:
// Provided by VK_AMDX_shader_enqueue
typedef struct VkDispatchGraphInfoAMDX {
uint32_t nodeIndex;
uint32_t payloadCount;
VkDeviceOrHostAddressConstAMDX payloads;
uint64_t payloadStride;
} VkDispatchGraphInfoAMDX;
-
nodeIndexis the index of a node in an execution graph to be dispatched. -
payloadCountis the number of payloads to dispatch for the specified node. -
payloadsis a device or host address pointer to a flat array of payloads with size equal to the product ofpayloadCountandpayloadStride -
payloadStrideis the byte stride between successive payloads inpayloads
Whether payloads is consumed as a device or host pointer is defined by
the command this structure is used in.
45.4. Shader Enqueue
Compute shaders in an execution graph can use the
OpInitializeNodePayloadsAMDX to initialize nodes for dispatch.
Any node payload initialized in this way will be enqueued for dispatch once
the shader is done writing to the payload.
As compilers may be conservative when making this determination, shaders
can further call OpFinalizeNodePayloadsAMDX to guarantee that the
payload is no longer being written.
The Node Name operand of the PayloadNodeNameAMDX decoration
on a payload identifies the shader name of the node to be enqueued, and the
Shader Index operand of OpInitializeNodePayloadsAMDX
identifies the shader index.
A node identified in this way is dispatched as described in the following
sections.
45.4.1. Compute Nodes
Compute shaders added as nodes to an execution graph are executed
differently based on the presence or absence of the
StaticNumWorkgroupsAMDX or CoalescingAMDX execution modes.
Dispatching a compute shader node that does not declare either the
StaticNumWorkgroupsAMDX or CoalescingAMDX execution mode will
execute a number of workgroups in each dimension specified by the first 12
bytes of the payload, interpreted as a VkDispatchIndirectCommand.
The same payload will be broadcast to each workgroup in the same dispatch.
Additional values in the payload are have no effect on execution.
Dispatching a compute shader node with the StaticNumWorkgroupsAMDX
execution mode will execute workgroups in each dimension according to the
x, y, and z size operands to the
StaticNumWorkgroupsAMDX execution mode.
The same payload will be broadcast to each workgroup in the same dispatch.
Any values in the payload have no effect on execution.
Dispatching a compute shader node with the CoalescingAMDX execution
mode will enqueue a single invocation for execution.
Implementations may combine multiple such dispatches into the same
workgroup, up to the size of the workgroup.
The number of invocations coalesced into a given workgroup in this way can
be queried via the CoalescedInputCountAMDX built-in.
Any values in the payload have no effect on execution.
45.4.2. Mesh Nodes
Graphics pipelines added as nodes to an execution graph are executed in a manner similar to a vkCmdDrawMeshTasksIndirectEXT, using the same payloads as compute shaders, but capturing some state from the command buffer.
When an execution graph dispatch is recorded into a command buffer, it captures the following dynamic state for use with draw nodes:
-
VK_DYNAMIC_STATE_VIEWPORT -
VK_DYNAMIC_STATE_SCISSOR -
VK_DYNAMIC_STATE_LINE_WIDTH -
VK_DYNAMIC_STATE_DEPTH_BIAS -
VK_DYNAMIC_STATE_BLEND_CONSTANTS -
VK_DYNAMIC_STATE_DEPTH_BOUNDS -
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT -
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT -
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR
Other state is not captured, and graphics pipelines must not be created with other dynamic states when used as a library in an execution graph pipeline.
46. External Compute Queues
External compute queues are used to join compatible external APIs to a
VkDevice, allowing workloads submitted through these external APIs to
be executed simultaneously to workloads submitted through Vulkan.
External compute queues are represented by VkExternalComputeQueueNV
handles:
// Provided by VK_NV_external_compute_queue
VK_DEFINE_HANDLE(VkExternalComputeQueueNV)
To create an external compute queue for use by compatible external APIs call:
// Provided by VK_NV_external_compute_queue
VkResult vkCreateExternalComputeQueueNV(
VkDevice device,
const VkExternalComputeQueueCreateInfoNV* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkExternalComputeQueueNV* pExternalQueue);
-
deviceis the VkDevice that the external queue will be a part of. -
pCreateInfois a pointer to a VkExternalComputeQueueCreateInfoNV structure specifying configuration info for creating the external queue. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pExternalQueueis a pointer to a VkExternalComputeQueueNV object that will be filled with the handle for the created external queue.
To destroy a previously created external compute queue call:
// Provided by VK_NV_external_compute_queue
void vkDestroyExternalComputeQueueNV(
VkDevice device,
VkExternalComputeQueueNV externalQueue,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the external queue. -
externalQueueis the VkExternalComputeQueueNV to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
To query the implementation-specific data that must be passed to compatible external APIs during their initialization process call:
// Provided by VK_NV_external_compute_queue
void vkGetExternalComputeQueueDataNV(
VkExternalComputeQueueNV externalQueue,
VkExternalComputeQueueDataParamsNV* params,
void* pData);
-
externalQueueis the VkExternalComputeQueueNV to query the data for. -
paramsis a pointer to a VkExternalComputeQueueDataParamsNV structure specifying parameters required for retrieval of the implementation-specific data. -
pDatais a pointer to application-allocated memory in which the requested data will be returned.
The VkExternalComputeQueueDeviceCreateInfoNV structure is defined as:
// Provided by VK_NV_external_compute_queue
typedef struct VkExternalComputeQueueDeviceCreateInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t reservedExternalQueues;
} VkExternalComputeQueueDeviceCreateInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
reservedExternalQueuesis the maximum number of external queues an application can create at once. This must be less than or equal to themaxExternalQueuesvalue reported by VkPhysicalDeviceExternalComputeQueuePropertiesNV
The VkExternalComputeQueueCreateInfoNV structure is defined as:
// Provided by VK_NV_external_compute_queue
typedef struct VkExternalComputeQueueCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkQueue preferredQueue;
} VkExternalComputeQueueCreateInfoNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
preferredQueueis aVkQueuesupporting graphics commands.
When creating a VkExternalComputeQueueNV, the preferredQueue
field is a strong scheduling hint as to which VkQueue Vulkan graphics
workloads will be submitted to with the expectation that execution will
overlap with execution of work submitted by the external API.
The VkExternalComputeQueueDataParamsNV structure is defined as:
// Provided by VK_NV_external_compute_queue
typedef struct VkExternalComputeQueueDataParamsNV {
VkStructureType sType;
const void* pNext;
uint32_t deviceIndex;
} VkExternalComputeQueueDataParamsNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceIndexis the index of the device within a device group that the data is being queried for. This is ignored if device groups are not utilized.
The VkPhysicalDeviceExternalComputeQueuePropertiesNV structure is
defined as:
// Provided by VK_NV_external_compute_queue
typedef struct VkPhysicalDeviceExternalComputeQueuePropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t externalDataSize;
uint32_t maxExternalQueues;
} VkPhysicalDeviceExternalComputeQueuePropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalDataSizeis the minimum size of the memory allocation that applications can pass to vkGetExternalComputeQueueDataNV. -
maxExternalQueuesis the maximum number of external queues that an application can create.
47. Data graphs
Data graph pipelines encapsulate computational graphs that operate on whole resources (e.g. tensors). The graph operations that form these computational graphs are executed by graph processing engines.
47.1. Pipeline Creation
To create data graph pipelines, call:
// Provided by VK_ARM_data_graph
VkResult vkCreateDataGraphPipelinesARM(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
VkPipelineCache pipelineCache,
uint32_t createInfoCount,
const VkDataGraphPipelineCreateInfoARM* pCreateInfos,
const VkAllocationCallbacks* pAllocator,
VkPipeline* pPipelines);
-
deviceis the logical device that creates the data graph 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 VkDataGraphPipelineCreateInfoARM 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 data graph pipelines objects are returned.
The implementation will create a pipeline in each element of
pPipelines from the corresponding element of pCreateInfos.
If the creation of any pipeline fails, that pipeline will be set to
VK_NULL_HANDLE.
The VkDataGraphPipelineCreateInfoARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineCreateInfoARM {
VkStructureType sType;
const void* pNext;
VkPipelineCreateFlags2KHR flags;
VkPipelineLayout layout;
uint32_t resourceInfoCount;
const VkDataGraphPipelineResourceInfoARM* pResourceInfos;
} VkDataGraphPipelineCreateInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkPipelineCreateFlagBits2KHR specifying how the pipeline will be generated. -
layoutis the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. -
resourceInfoCountis the length of thepResourceInfosarray. -
pResourceInfosis a pointer to an array of VkDataGraphPipelineResourceInfoARM structures.
Applications can create a data graph pipeline entirely from data present in
a pipeline cache.
This is done by including a VkDataGraphPipelineIdentifierCreateInfoARM
structure in the pNext chain.
If the required data is not found in the pipeline cache, creating the data
graph pipeline 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 to create a data graph pipeline, implementations
may fail pipeline creation with VK_PIPELINE_COMPILE_REQUIRED for any
reason.
The VkDataGraphPipelineShaderModuleCreateInfoARM structure is defined
as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineShaderModuleCreateInfoARM {
VkStructureType sType;
const void* pNext;
VkShaderModule module;
const char* pName;
const VkSpecializationInfo* pSpecializationInfo;
uint32_t constantCount;
const VkDataGraphPipelineConstantARM* pConstants;
} VkDataGraphPipelineShaderModuleCreateInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
moduleis optionally a VkShaderModule object containing the description of the graph. -
pNameis a pointer to a null-terminated UTF-8 string specifying the graph entry point name for this pipeline. -
pSpecializationInfois a pointer to a VkSpecializationInfo structure as described in Specialization Constants, orNULL. -
constantCountis the length of thepConstantsarray. -
pConstantsis a pointer to an array of VkDataGraphPipelineConstantARM structures.
If module is not VK_NULL_HANDLE, the pipeline’s graph is defined
by module.
If module is VK_NULL_HANDLE, the pipeline’s graph is defined by
the chained VkShaderModuleCreateInfo.
The VkDataGraphPipelineIdentifierCreateInfoARM structure is defined
as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineIdentifierCreateInfoARM {
VkStructureType sType;
const void* pNext;
uint32_t identifierSize;
const uint8_t* pIdentifier;
} VkDataGraphPipelineIdentifierCreateInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
identifierSizeis the size in bytes of the identifier data accessible viapIdentifier. -
pIdentiferis a pointer toidentifierSizebytes of data that describe the pipeline being created.
The VkDataGraphPipelineCompilerControlCreateInfoARM structure is
defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineCompilerControlCreateInfoARM {
VkStructureType sType;
const void* pNext;
const char* pVendorOptions;
} VkDataGraphPipelineCompilerControlCreateInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pVendorOptionsis a null-terminated UTF-8 string specifying implementation-specific options that affect the creation of a data graph pipeline.
The VkDataGraphPipelineConstantARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineConstantARM {
VkStructureType sType;
const void* pNext;
uint32_t id;
const void* pConstantData;
} VkDataGraphPipelineConstantARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextis a pointer to a structure extending this structure. -
idis the unique identifier of the graph constant this structure describes. -
pConstantDatais a pointer to the data for this graph constant.
The size and layout of the data pointed to by pConstantData is
specified by a specific structure in the pNext chain for each type of
graph constant.
For graph constants of tensor type, the layout of the data is specified by a VkTensorDescriptionARM structure. The data must be laid out according to the following members of this structure:
-
VkTensorDescriptionARM::
tiling -
VkTensorDescriptionARM::
format -
VkTensorDescriptionARM::
dimensionCount -
VkTensorDescriptionARM::
pDimensions -
VkTensorDescriptionARM::
pStrides
The presence of a
VkDataGraphPipelineConstantTensorSemiStructuredSparsityInfoARM
structure in the pNext chain has no impact on the expected layout of
the data pointed to by pConstantData.
The VkDataGraphPipelineConstantTensorSemiStructuredSparsityInfoARM
structure is defined as:
// Provided by VK_ARM_data_graph with VK_ARM_tensors
typedef struct VkDataGraphPipelineConstantTensorSemiStructuredSparsityInfoARM {
VkStructureType sType;
const void* pNext;
uint32_t dimension;
uint32_t zeroCount;
uint32_t groupSize;
} VkDataGraphPipelineConstantTensorSemiStructuredSparsityInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dimensionis the dimension of the tensor along which its data is sparse. -
zeroCountis the number of tensor elements that must be zero in every group ofgroupSizeelements. -
groupSizeis the number of tensor elements in a group.
|
Note
|
This extension does not provide applications with a way of knowing which
combinations of |
The VkDataGraphPipelineResourceInfoARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineResourceInfoARM {
VkStructureType sType;
const void* pNext;
uint32_t descriptorSet;
uint32_t binding;
uint32_t arrayElement;
} VkDataGraphPipelineResourceInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
descriptorSetis the descriptor set number of the resource being described. -
bindingis the binding number of the resource being described. -
arrayElementis the element in the resource array ifdescriptorSetandbindingidentifies an array of resources or0otherwise.
47.2. Sessions
Graph pipelines execute within data graph pipeline sessions that provide a context for their execution as well as binding points for the memory they need (e.g. transient storage).
Graph pipeline sessions are represented by
VkDataGraphPipelineSessionARM handles:
// Provided by VK_ARM_data_graph
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDataGraphPipelineSessionARM)
To create a data graph pipeline session, call
// Provided by VK_ARM_data_graph
VkResult vkCreateDataGraphPipelineSessionARM(
VkDevice device,
const VkDataGraphPipelineSessionCreateInfoARM* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDataGraphPipelineSessionARM* pSession);
-
deviceis the logical device that creates the data graph pipeline session. -
pCreateInfois a pointer to a VkDataGraphPipelineSessionCreateInfoARM structure. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pSessionis a pointer to a VkDataGraphPipelineSessionARM handle in which the resulting data graph pipeline session object is returned.
The VkDataGraphPipelineSessionCreateInfoARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineSessionCreateInfoARM {
VkStructureType sType;
const void* pNext;
VkDataGraphPipelineSessionCreateFlagsARM flags;
VkPipeline dataGraphPipeline;
} VkDataGraphPipelineSessionCreateInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkDataGraphPipelineSessionCreateFlagBitsARM describing additional parameters of the session. -
dataGraphPipelineis the VkPipeline handle of the data graph pipeline for which a session is being created.
Bits which can be set in
VkDataGraphPipelineSessionCreateInfoARM::flags, specifying
additional parameters of a data graph pipeline session, are:
// Provided by VK_ARM_data_graph
// Flag bits for VkDataGraphPipelineSessionCreateFlagBitsARM
typedef VkFlags64 VkDataGraphPipelineSessionCreateFlagBitsARM;
static const VkDataGraphPipelineSessionCreateFlagBitsARM VK_DATA_GRAPH_PIPELINE_SESSION_CREATE_PROTECTED_BIT_ARM = 0x00000001ULL;
-
VK_DATA_GRAPH_PIPELINE_SESSION_CREATE_PROTECTED_BIT_ARMspecifies that the data graph pipeline session is backed by protected memory.
// Provided by VK_ARM_data_graph
typedef VkFlags64 VkDataGraphPipelineSessionCreateFlagsARM;
VkDataGraphPipelineSessionCreateFlagsARM is a bitmask type for setting
a mask of zero or more VkDataGraphPipelineSessionCreateFlagBitsARM.
To determine the bind point requirements for a data graph pipeline session, call:
// Provided by VK_ARM_data_graph
VkResult vkGetDataGraphPipelineSessionBindPointRequirementsARM(
VkDevice device,
const VkDataGraphPipelineSessionBindPointRequirementsInfoARM* pInfo,
uint32_t* pBindPointRequirementCount,
VkDataGraphPipelineSessionBindPointRequirementARM* pBindPointRequirements);
-
deviceis the logical device that owns the data graph pipeline session. -
pInfois a pointer to a VkDataGraphPipelineSessionBindPointRequirementsInfoARM structure containing parameters for the bind point requirements query. -
pBindPointRequirementCountis a pointer to an integer related to the number of bind point available or queried, as described below. -
pBindPointRequirementsis eitherNULLor a pointer to an array of VkDataGraphPipelineSessionBindPointRequirementARM structures.
If pBindPointRequirements is NULL, then the number of bind points
associated with the data graph pipeline session is returned in
pBindPointRequirementCount.
Otherwise, pBindPointRequirementCount must point to a variable set by
the user to the number of elements in the pBindPointRequirements
array, and on return the variable is overwritten with the number of
structures actually written to pBindPointRequirements.
If pBindPointRequirementCount is less than the number of bind points
associated with the data graph pipeline session, at most
pBindPointRequirementCount structures will be written, and
VK_INCOMPLETE will be returned instead of VK_SUCCESS, to
indicate that not all the required bind points were returned.
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineSessionBindPointRequirementsInfoARM {
VkStructureType sType;
const void* pNext;
VkDataGraphPipelineSessionARM session;
} VkDataGraphPipelineSessionBindPointRequirementsInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sessionis a VkDataGraphPipelineSessionARM specifying the data graph pipeline session whose bind point requirements are being queried.
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineSessionBindPointRequirementARM {
VkStructureType sType;
const void* pNext;
VkDataGraphPipelineSessionBindPointARM bindPoint;
VkDataGraphPipelineSessionBindPointTypeARM bindPointType;
uint32_t numObjects;
} VkDataGraphPipelineSessionBindPointRequirementARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bindPointis a VkDataGraphPipelineSessionBindPointARM specifying the data graph pipeline session bind point being required. -
bindPointTypeis a VkDataGraphPipelineSessionBindPointTypeARM specifying the type of object required forbindPoint. -
numObjectsis the number of objects required forbindPoint.
Implementations must always return 1 for numObjects if
bindPoint is one of the following bind points:
-
VK_DATA_GRAPH_PIPELINE_SESSION_BIND_POINT_TRANSIENT_ARM
Possible values of VkDataGraphPipelineSessionBindPointARM, specifying
the bind point of a data graph pipeline session, are:
// Provided by VK_ARM_data_graph
typedef enum VkDataGraphPipelineSessionBindPointARM {
VK_DATA_GRAPH_PIPELINE_SESSION_BIND_POINT_TRANSIENT_ARM = 0,
} VkDataGraphPipelineSessionBindPointARM;
-
VK_DATA_GRAPH_PIPELINE_SESSION_BIND_POINT_TRANSIENT_ARMcorresponds to the transient data produced and consumed during one dispatch of a data graph pipeline in a data graph pipeline session. This transient data is never reused by subsequent dispatches and can safely be clobbered once a vkCmdDispatchDataGraphARM command completes execution.
Possible values of VkDataGraphPipelineSessionBindPointTypeARM,
specifying the type of a bind point of a data graph pipeline session, are:
// Provided by VK_ARM_data_graph
typedef enum VkDataGraphPipelineSessionBindPointTypeARM {
VK_DATA_GRAPH_PIPELINE_SESSION_BIND_POINT_TYPE_MEMORY_ARM = 0,
} VkDataGraphPipelineSessionBindPointTypeARM;
-
VK_DATA_GRAPH_PIPELINE_SESSION_BIND_POINT_TYPE_MEMORY_ARMcorresponds to a memory allocation.
To determine the memory requirements for a data graph pipeline session, call:
// Provided by VK_ARM_data_graph
void vkGetDataGraphPipelineSessionMemoryRequirementsARM(
VkDevice device,
const VkDataGraphPipelineSessionMemoryRequirementsInfoARM* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
deviceis the logical device that owns the data graph pipeline session. -
pInfois a pointer to a VkDataGraphPipelineSessionMemoryRequirementsInfoARM structure containing parameters for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the data graph pipeline session object are returned.
The VkDataGraphPipelineSessionMemoryRequirementsInfoARM structure is
defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineSessionMemoryRequirementsInfoARM {
VkStructureType sType;
const void* pNext;
VkDataGraphPipelineSessionARM session;
VkDataGraphPipelineSessionBindPointARM bindPoint;
uint32_t objectIndex;
} VkDataGraphPipelineSessionMemoryRequirementsInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sessionis the data graph pipeline session to query. -
bindPointis the bind point of a data graph pipeline session for which memory requirements are being queried. -
objectIndexis the index of the object whose memory requirements are being queried.
To attach memory to a data graph pipeline session object, call:
// Provided by VK_ARM_data_graph
VkResult vkBindDataGraphPipelineSessionMemoryARM(
VkDevice device,
uint32_t bindInfoCount,
const VkBindDataGraphPipelineSessionMemoryInfoARM* pBindInfos);
-
deviceis the logical device that owns the data graph pipeline session and memory. -
bindInfoCountis the length of thepBindInfosarray. -
pBindInfosis a pointer to an array of VkBindDataGraphPipelineSessionMemoryInfoARM structures describing graph pipeline sessions and memory to bind.
The VkBindDataGraphPipelineSessionMemoryInfoARM structure is defined
as:
// Provided by VK_ARM_data_graph
typedef struct VkBindDataGraphPipelineSessionMemoryInfoARM {
VkStructureType sType;
const void* pNext;
VkDataGraphPipelineSessionARM session;
VkDataGraphPipelineSessionBindPointARM bindPoint;
uint32_t objectIndex;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
} VkBindDataGraphPipelineSessionMemoryInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sessionis the data graph pipeline session to be attached to memory. -
bindPointis the data graph pipeline session bind point to whichmemoryis to be attached. -
objectIndexis the index of the object forbindPointat whichmemoryis to be attached. -
memoryis a VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the resion ofmemorywhich is to be bound to the data graph pipeline session.
To destroy a data graph pipeline session, call:
// Provided by VK_ARM_data_graph
void vkDestroyDataGraphPipelineSessionARM(
VkDevice device,
VkDataGraphPipelineSessionARM session,
const VkAllocationCallbacks* pAllocator);
-
deviceis the logical device that destroys the data graph pipeline session. -
sessionis the handle of the data graph pipeline session to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
47.3. Dispatch
To record a data graph pipeline dispatch, call:
// Provided by VK_ARM_data_graph
void vkCmdDispatchDataGraphARM(
VkCommandBuffer commandBuffer,
VkDataGraphPipelineSessionARM session,
const VkDataGraphPipelineDispatchInfoARM* pInfo);
-
commandBufferis the command buffer into which the command will be recorded. -
sessionis the VkDataGraphPipelineSessionARM that data graph pipeline being dispatched will use. -
pInfoisNULLor a pointer to a VkDataGraphPipelineDispatchInfoARM structure.
The VkDataGraphPipelineDispatchInfoARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineDispatchInfoARM {
VkStructureType sType;
void* pNext;
VkDataGraphPipelineDispatchFlagsARM flags;
} VkDataGraphPipelineDispatchInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkDataGraphPipelineDispatchFlagBitsARM describing additional parameters of the dispatch.
Bits which can be set in
VkDataGraphPipelineDispatchInfoARM::flags, specifying additional
parameters of a data graph pipeline dispatch, are:
// Provided by VK_ARM_data_graph
// Flag bits for VkDataGraphPipelineDispatchFlagBitsARM
typedef VkFlags64 VkDataGraphPipelineDispatchFlagBitsARM;
// Provided by VK_ARM_data_graph
typedef VkFlags64 VkDataGraphPipelineDispatchFlagsARM;
VkDataGraphPipelineDispatchFlagsARM is a bitmask type for setting a
mask of zero or more VkDataGraphPipelineDispatchFlagBitsARM.
47.4. Properties
To query the properties of a data graph pipeline that can be obtained, call:
// Provided by VK_ARM_data_graph
VkResult vkGetDataGraphPipelineAvailablePropertiesARM(
VkDevice device,
const VkDataGraphPipelineInfoARM* pPipelineInfo,
uint32_t* pPropertiesCount,
VkDataGraphPipelinePropertyARM* pProperties);
-
deviceis the logical device that created the data graph pipeline. -
pPipelineInfois a VkDataGraphPipelineInfoARM that describes the VkPipeline being queried. -
pPropertiesCountis a pointer to an integer related to the number of properties available or queried, as described below. -
pPropertiesis eitherNULLor a pointer to an array of VkDataGraphPipelinePropertyARM enums.
If pProperties is NULL, then the number of properties associated
with the data graph pipeline is returned in pPropertiesCount.
Otherwise, pPropertiesCount 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 enums actually written to
pProperties.
If pPropertiesCount is less than the number of properties associated
with the data graph pipeline, at most pPropertiesCount structures will
be written, and VK_INCOMPLETE will be returned instead of
VK_SUCCESS, to indicate that not all the available properties were
returned.
To query properties of a data graph pipeline, call:
// Provided by VK_ARM_data_graph
VkResult vkGetDataGraphPipelinePropertiesARM(
VkDevice device,
const VkDataGraphPipelineInfoARM* pPipelineInfo,
uint32_t propertiesCount,
VkDataGraphPipelinePropertyQueryResultARM* pProperties);
-
deviceis the logical device that created the data graph pipeline. -
pPipelineInfois a VkDataGraphPipelineInfoARM that describes the VkPipeline being queried. -
propertiesCountis the length of thepPropertiesarray. -
pPropertiesis a pointer to an array of VkDataGraphPipelinePropertyQueryResultARM structures.
The VkDataGraphPipelineInfoARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelineInfoARM {
VkStructureType sType;
const void* pNext;
VkPipeline dataGraphPipeline;
} VkDataGraphPipelineInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dataGraphPipelineis a VkPipeline handle.
The VkDataGraphPipelinePropertyQueryResultARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphPipelinePropertyQueryResultARM {
VkStructureType sType;
const void* pNext;
VkDataGraphPipelinePropertyARM property;
VkBool32 isText;
size_t dataSize;
void* pData;
} VkDataGraphPipelinePropertyQueryResultARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
propertyis a VkDataGraphPipelinePropertyARM specifying the property of the data graph pipeline being queried. -
isTextspecifies whether the returned data is text or opaque data. IfisTextisVK_TRUEthen the data returned inpDatais text and guaranteed to be a null-terminated UTF-8 string. -
dataSizeis an integer related to the size, in bytes, of the data, as described below. -
pDatais eitherNULLor a pointer to a block of memory into which the implementation will return the property data.
If pData is NULL, then the size, in bytes, of the property 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 NUL character.
If dataSize is less than the size, in bytes, of the property data, at
most dataSize bytes of data will be written to pData, and
VK_INCOMPLETE will be returned by
vkGetDataGraphPipelinePropertiesARM instead of VK_SUCCESS, to
indicate that not all the available property data 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
NUL character.
Possible values of
VkDataGraphPipelinePropertyQueryResultARM::property, specifying
the property of the data graph pipeline being queried, are:
// Provided by VK_ARM_data_graph
typedef enum VkDataGraphPipelinePropertyARM {
VK_DATA_GRAPH_PIPELINE_PROPERTY_CREATION_LOG_ARM = 0,
VK_DATA_GRAPH_PIPELINE_PROPERTY_IDENTIFIER_ARM = 1,
} VkDataGraphPipelinePropertyARM;
-
VK_DATA_GRAPH_PIPELINE_PROPERTY_CREATION_LOG_ARMcorresponds to a human-readable log produced during the creation of a data graph pipeline. It may contain information about errors encountered during the creation or other information generally useful for debugging. This property can be queried for any data graph pipeline. -
VK_DATA_GRAPH_PIPELINE_PROPERTY_IDENTIFIER_ARMcorresponds to an opaque identifier for the data graph pipeline. It can be used to create a graph pipeline from a pipeline cache without the need to provide any creation data beyond the identifier, using a VkDataGraphPipelineIdentifierCreateInfoARM structure.
47.5. Processing Engines
Data graph pipelines execute on one or more data graph processing engines.
Each queue family of a VkPhysicalDevice that supports
VK_QUEUE_DATA_GRAPH_BIT_ARM may provide access to processing engines.
Processing engines may be foreign.
Foreign processing engines require the use of external memory and semaphores
to exchange data and synchronize with data graph pipelines that target them.
Each processing engine may support a selection of graph
operations.
There exists a default processing engine that enables implementations to
support some operations without tying support to specific processing
engines.
This allows implementations to avoid being specific about the processing
engines that they use internally or to remove the necessity for applications
to choose the specific processing engine used to execute a given set of
operations.
To query the properties of a data graph processing engine for a specific queue family of a physical device, call:
// Provided by VK_ARM_data_graph
void vkGetPhysicalDeviceQueueFamilyDataGraphProcessingEnginePropertiesARM(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceQueueFamilyDataGraphProcessingEngineInfoARM* pQueueFamilyDataGraphProcessingEngineInfo,
VkQueueFamilyDataGraphProcessingEnginePropertiesARM* pQueueFamilyDataGraphProcessingEngineProperties);
-
physicalDeviceis the physical device to query. -
pQueueFamilyDataGraphProcessingEngineInfois a pointer to a VkPhysicalDeviceQueueFamilyDataGraphProcessingEngineInfoARM structure that specifies the data graph processing engine and queue family to query. -
pQueueFamilyDataGraphProcessingEnginePropertiesis a pointer to a VkQueueFamilyDataGraphProcessingEnginePropertiesARM structure in which the queries properties are returned.
The VkPhysicalDeviceQueueFamilyDataGraphProcessingEngineInfoARM
structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkPhysicalDeviceQueueFamilyDataGraphProcessingEngineInfoARM {
VkStructureType sType;
const void* pNext;
uint32_t queueFamilyIndex;
VkPhysicalDeviceDataGraphProcessingEngineTypeARM engineType;
} VkPhysicalDeviceQueueFamilyDataGraphProcessingEngineInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queueFamilyIndexspecifies the queue family being queried. -
engineTypeis a VkPhysicalDeviceDataGraphProcessingEngineTypeARM specifying the engine type whose properties are being queried.
The VkQueueFamilyDataGraphProcessingEnginePropertiesARM structure is
defined as:
// Provided by VK_ARM_data_graph
typedef struct VkQueueFamilyDataGraphProcessingEnginePropertiesARM {
VkStructureType sType;
const void* pNext;
VkExternalSemaphoreHandleTypeFlags foreignSemaphoreHandleTypes;
VkExternalMemoryHandleTypeFlags foreignMemoryHandleTypes;
} VkQueueFamilyDataGraphProcessingEnginePropertiesARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
foreignSemaphoreHandleTypesis a VkExternalSemaphoreHandleTypeFlags that describes the external semaphore handle types supported by a foreign data graph processing engine. -
foreignMemoryHandleTypesis a VkExternalMemoryHandleTypeFlags that describes the external memory handle types supported by a foreign data graph processing engine.
The VkPhysicalDeviceDataGraphProcessingEngineARM structure is defined
as:
// Provided by VK_ARM_data_graph
typedef struct VkPhysicalDeviceDataGraphProcessingEngineARM {
VkPhysicalDeviceDataGraphProcessingEngineTypeARM type;
VkBool32 isForeign;
} VkPhysicalDeviceDataGraphProcessingEngineARM;
-
typeis a VkPhysicalDeviceDataGraphProcessingEngineTypeARM that specifies the type of the processing engine. -
isForeignspecifies whether the processing engine is foreign.
The defined data graph processing engines are:
// Provided by VK_ARM_data_graph
typedef enum VkPhysicalDeviceDataGraphProcessingEngineTypeARM {
VK_PHYSICAL_DEVICE_DATA_GRAPH_PROCESSING_ENGINE_TYPE_DEFAULT_ARM = 0,
} VkPhysicalDeviceDataGraphProcessingEngineTypeARM;
-
VK_PHYSICAL_DEVICE_DATA_GRAPH_PROCESSING_ENGINE_TYPE_DEFAULT_ARMcorresponds to the default data graph processing engine.
The VkDataGraphProcessingEngineCreateInfoARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkDataGraphProcessingEngineCreateInfoARM {
VkStructureType sType;
const void* pNext;
uint32_t processingEngineCount;
VkPhysicalDeviceDataGraphProcessingEngineARM* pProcessingEngines;
} VkDataGraphProcessingEngineCreateInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
processingEngineCountis the number of elements inpProcessingEngines. -
pProcessingEnginesis a pointer to an array ofprocessingEngineCountVkPhysicalDeviceDataGraphProcessingEngineARM structures.
47.6. Operations
Data graph processing engines execute data graph operations. Operations may be of a fixed-function nature, configurable or not, or may , for example, be provided as part of a SPIR-V extended instruction set.
To query the data graph processing engines and operations they support for a specific queue family of a physical device, call:
// Provided by VK_ARM_data_graph
VkResult vkGetPhysicalDeviceQueueFamilyDataGraphPropertiesARM(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
uint32_t* pQueueFamilyDataGraphPropertyCount,
VkQueueFamilyDataGraphPropertiesARM* pQueueFamilyDataGraphProperties);
-
physicalDeviceis the physical device to query. -
queueFamilyIndexis the index of the queue family being queried. -
pQueueFamilyDataGraphPropertyCountis a pointer to an integer related to the number of properties available or queried. -
pQueueFamilyDataGraphPropertiesis eitherNULLor a pointer to an array of VkQueueFamilyDataGraphPropertiesARM structures.
If pQueueFamilyDataGraphProperties is NULL, then the number of
properties available is returned in
pQueueFamilyDataGraphPropertyCount.
Otherwise, pQueueFamilyDataGraphPropertyCount must point to a
variable set by the application to the number of elements in the
pQueueFamilyDataGraphProperties array, and on return the variable is
overwritten with the number of structures actually written to
pQueueFamilyDataGraphProperties.
If pQueueFamilyDataGraphPropertyCount is less than the number of
properties available, at most pQueueFamilyDataGraphPropertyCount
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 VkQueueFamilyDataGraphPropertiesARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkQueueFamilyDataGraphPropertiesARM {
VkStructureType sType;
const void* pNext;
VkPhysicalDeviceDataGraphProcessingEngineARM engine;
VkPhysicalDeviceDataGraphOperationSupportARM operation;
} VkQueueFamilyDataGraphPropertiesARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
engineis a VkPhysicalDeviceDataGraphProcessingEngineARM structure describing a data graph processing engine. -
operationis a VkPhysicalDeviceDataGraphOperationSupportARM structure describing one or more operations supported by a data graph processing engine.
The VkPhysicalDeviceDataGraphOperationSupportARM structure is defined
as:
// Provided by VK_ARM_data_graph
typedef struct VkPhysicalDeviceDataGraphOperationSupportARM {
VkPhysicalDeviceDataGraphOperationTypeARM operationType;
char name[VK_MAX_PHYSICAL_DEVICE_DATA_GRAPH_OPERATION_SET_NAME_SIZE_ARM];
uint32_t version;
} VkPhysicalDeviceDataGraphOperationSupportARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
operationTypeis a VkPhysicalDeviceDataGraphOperationTypeARM enum specifying the type of the operation whose support is being described. -
nameis a pointer to a null-terminated UTF-8 string specifying the name of the operation whose support is being described. -
versionis an integer specifying the version of the operation whose support is being described.
The defined data graph operations are:
// Provided by VK_ARM_data_graph
typedef enum VkPhysicalDeviceDataGraphOperationTypeARM {
VK_PHYSICAL_DEVICE_DATA_GRAPH_OPERATION_TYPE_SPIRV_EXTENDED_INSTRUCTION_SET_ARM = 0,
} VkPhysicalDeviceDataGraphOperationTypeARM;
-
VK_PHYSICAL_DEVICE_DATA_GRAPH_OPERATION_TYPE_SPIRV_EXTENDED_INSTRUCTION_SET_ARMcorresponds to operations provided by a SPIR-V extended instruction set.
48. 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.
48.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 dispatch from a VkDevice object or a child object of a VkDevice, or take any of them as a parameter, are considered device-level functionality. Types defined by a device extension are also considered device-level functionality.
Commands that dispatch from VkPhysicalDevice, or accept a VkPhysicalDevice object as a parameter, are considered either instance-level or device-level functionality depending if the functionality is specified by an instance extension or device extension respectively.
Additionally, commands that enumerate physical device properties 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,
|
48.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.
48.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) >> 29U)
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) >> 22U) & 0x7FU)
VK_VERSION_MAJOR extracts the API major version number from a packed
version number:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.0. See Deprecated Functionality for more information. |
// Provided by VK_VERSION_1_0
#define VK_VERSION_MAJOR(version) ((uint32_t)(version) >> 22U)
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) >> 12U) & 0x3FFU)
VK_VERSION_MINOR extracts the API minor version number from a packed
version number:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.0. See Deprecated Functionality for more information. |
// Provided by VK_VERSION_1_0
#define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12U) & 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.0. See Deprecated Functionality for more information. |
// Provided by VK_VERSION_1_0
#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)) << 29U) | (((uint32_t)(major)) << 22U) | (((uint32_t)(minor)) << 12U) | ((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.
|
Warning
|
This functionality is deprecated by Vulkan Version 1.0. See Deprecated Functionality for more information. |
// Provided by VK_VERSION_1_0
#define VK_MAKE_VERSION(major, minor, patch) \
((((uint32_t)(major)) << 22U) | (((uint32_t)(minor)) << 12U) | ((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
VK_API_VERSION_1_4 returns the API version number for Vulkan 1.4.0.
// Provided by VK_VERSION_1_4
// Vulkan 1.4 version number
#define VK_API_VERSION_1_4 VK_MAKE_API_VERSION(0, 1, 4, 0)// Patch version should always be set to 0
48.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.
48.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
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If pPropertyCount is less than the number of 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.
48.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
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If pPropertyCount is less than the number of 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.
48.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. |
48.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
application to the number of elements in the pProperties array, and on
return the variable is overwritten with the number of structures actually
written to pProperties.
If pPropertyCount is less than the number of 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.
48.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.
If the VK_KHR_ray_tracing_pipeline extension is advertised as
supported by this query, the VK_KHR_pipeline_library extension
must also be supported.
Implementations claiming support for the Roadmap 2022
profile must advertise the VK_KHR_global_priority extension in
pProperties.
Implementations claiming support for the Roadmap 2024
profile must advertise the following extensions 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.
Accessing Device-Level Functionality From a VkPhysicalDevice
Some device extensions also add support for physical-device-level functionality. Physical-device-level functionality can be used, if the required extension is supported as advertised by vkEnumerateDeviceExtensionProperties for a given VkPhysicalDevice.
Accessing Device-Level Functionality From a VkDevice
For commands that are dispatched from a VkDevice, or from a child object of a VkDevice, device extensions must be enabled in vkCreateDevice.
48.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 |
48.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.
48.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 realize 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.
48.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 favor of.
|
Note
|
Structure and enumerated types defined in extensions that were promoted to core in a later version of Vulkan are defined in terms of the equivalent Vulkan core interfaces in that version and its successors. This affects the Vulkan Specification, the Vulkan header files, and the corresponding XML Registry. |
When extension functionality is promoted, minor changes may be introduced, limited to the following:
-
Naming
-
Non-intrusive parameter 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 endeavors 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 they are no longer intended to be used by applications under certain conditions. 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 related 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 command definitions, due to the fact that the C99 ABI has no way to alias command definitions without resorting to macros. Calling either command will produce identical behavior within the bounds of the specification, and should still invoke the same path in the implementation. Debug tools may use separate commands 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.
49. Features
Features advertise additional functionality which can be enabled in the API. If a feature is supported by a physical device, it must be enabled when creating a VkDevice in order to use its associated functionality with that VkDevice. If a feature is unsupported, that functionality cannot be used with that VkDevice.
|
Note
|
Features are reported via 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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.1. See Deprecated Functionality for more information. |
// 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 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.
Each structure in pFeatures and its pNext chain contains
VkBool32 members corresponding to fine-grained features.
Each such member is returned with a VK_TRUE value indicating that
feature is supported on this physical device, or a VK_FALSE value
indicating it is unsupported.
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 a VkStructureType value identifying 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 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:
-
robustBufferAccessenables Robust Buffer Access guarantees for shader buffer accesses. -
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. SeemaxDrawIndexedIndexValue. -
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 beVK_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 beVK_FALSE, and thelogicOpmember is ignored. -
multiDrawIndirectspecifies whether multiple draw indirect is supported. If this feature is not enabled, thedrawCountparameter to the vkCmdDrawIndirect and vkCmdDrawIndexedIndirect commands must be 0 or 1. ThemaxDrawIndirectCountmember of theVkPhysicalDeviceLimitsstructure must also be 1 if this feature is not supported. SeemaxDrawIndirectCount. -
drawIndirectFirstInstancespecifies whether indirect drawing calls support thefirstInstanceparameter. If this feature is not enabled, thefirstInstancemember of allVkDrawIndirectCommandandVkDrawIndexedIndirectCommandstructures that are provided to the vkCmdDrawIndirect and vkCmdDrawIndexedIndirect commands must be 0. -
depthClampspecifies whether depth clamping is supported. If this feature is not enabled, thedepthClampEnablemember of the VkPipelineRasterizationStateCreateInfo structure must beVK_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 0.0 unless theVK_DYNAMIC_STATE_DEPTH_BIASdynamic state is enabled, in which case thedepthBiasClampparameter to vkCmdSetDepthBias must be 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 beVK_FALSEunless theVK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLEdynamic state is enabled, in which case thedepthBoundsTestEnableparameter to vkCmdSetDepthBoundsTestEnable must beVK_FALSE. WhendepthBoundsTestEnableisVK_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 1.0 unless theVK_DYNAMIC_STATE_LINE_WIDTHdynamic state is enabled, in which case thelineWidthparameter to vkCmdSetLineWidth must be 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 beVK_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 1. -
The
firstViewportandviewportCountparameters to the vkCmdSetViewport command must be 0 and 1, respectively. -
The
firstScissorandscissorCountparameters to the vkCmdSetScissor command must be 0 and 1, respectively. -
The
exclusiveScissorCountmember of the VkPipelineViewportExclusiveScissorStateCreateInfoNV structure must be 0 or 1. -
The
firstExclusiveScissorandexclusiveScissorCountparameters to the vkCmdSetExclusiveScissorNV command must be 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_BLOCKTo 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_BLOCKTo 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_BLOCKTo 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 to vkCreateQueryPool. If this feature is enabled, queries of this type can enableVK_QUERY_CONTROL_PRECISE_BITin theflagsparameter to vkCmdBeginQuery. 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_UINTNoteshaderStorageImageExtendedFormatsfeature 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 and storage texel buffers require a format qualifier to be specified when reading.shaderStorageImageReadWithoutFormatapplies only to formats listed in the storage without format list. -
shaderStorageImageWriteWithoutFormatspecifies whether storage images and storage texel buffers 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 integer expressions that are dynamically uniform within either the subgroup or the invocation group 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 integer expressions that are dynamically uniform within either the subgroup or the invocation group 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 integer expressions that are dynamically uniform within either the subgroup or the invocation group 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 integer expressions that are dynamically uniform within either the subgroup or the invocation group 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 the vkBindBufferMemory and vkBindImageMemory commands. 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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVulkan11Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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 and payload 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 this feature 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 integer expressions that are dynamically uniform within either the subgroup or the invocation group 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 integer expressions that are dynamically uniform within either the subgroup or the invocation group 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 integer expressions that are dynamically uniform within either the subgroup or the invocation group 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 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 mesh, vertex or tessellation evaluation shaders. If this feature is not enabled, theViewportIndexbuilt-in decoration must not be used on outputs in mesh, vertex or tessellation evaluation shaders. -
shaderOutputLayerindicates whether the implementation supports theShaderLayerSPIR-V capability enabling variables decorated with theLayerbuilt-in to be exported from mesh, vertex or tessellation evaluation shaders. If this feature is not enabled, theLayerbuilt-in decoration must not be used on outputs in mesh, 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVulkan12Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
robustImageAccessenables Robust Image Access guarantees for shader image accesses. -
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 , mesh, or task 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_BLOCKTo 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVulkan13Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceVulkan14Features structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceVulkan14Features {
VkStructureType sType;
void* pNext;
VkBool32 globalPriorityQuery;
VkBool32 shaderSubgroupRotate;
VkBool32 shaderSubgroupRotateClustered;
VkBool32 shaderFloatControls2;
VkBool32 shaderExpectAssume;
VkBool32 rectangularLines;
VkBool32 bresenhamLines;
VkBool32 smoothLines;
VkBool32 stippledRectangularLines;
VkBool32 stippledBresenhamLines;
VkBool32 stippledSmoothLines;
VkBool32 vertexAttributeInstanceRateDivisor;
VkBool32 vertexAttributeInstanceRateZeroDivisor;
VkBool32 indexTypeUint8;
VkBool32 dynamicRenderingLocalRead;
VkBool32 maintenance5;
VkBool32 maintenance6;
VkBool32 pipelineProtectedAccess;
VkBool32 pipelineRobustness;
VkBool32 hostImageCopy;
VkBool32 pushDescriptor;
} VkPhysicalDeviceVulkan14Features;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
globalPriorityQueryindicates whether the implementation supports the ability to query global queue priorities. -
shaderSubgroupRotatespecifies whether shader modules can declare theGroupNonUniformRotateKHRcapability. -
shaderSubgroupRotateClusteredspecifies whether shader modules can use theClusterSizeoperand toOpGroupNonUniformRotateKHR. -
shaderFloatControls2specifies whether shader modules can declare theFloatControls2capability. -
shaderExpectAssumespecifies whether shader modules can declare theExpectAssumeKHRcapability. -
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_RECTANGULARlines. -
stippledBresenhamLinesindicates whether the implementation supports stippled line rasterization withVK_LINE_RASTERIZATION_MODE_BRESENHAMlines. -
stippledSmoothLinesindicates whether the implementation supports stippled line rasterization withVK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTHlines. -
vertexAttributeInstanceRateDivisorspecifies whether vertex attribute fetching may be repeated in the case of instanced rendering. -
vertexAttributeInstanceRateZeroDivisorspecifies whether a zero value for VkVertexInputBindingDivisorDescriptionEXT::divisoris supported. -
indexTypeUint8indicates thatVK_INDEX_TYPE_UINT8can be used with vkCmdBindIndexBuffer2 and vkCmdBindIndexBuffer. -
dynamicRenderingLocalReadspecifies that the implementation supports local reads inside dynamic render pass instances using the vkCmdBeginRendering command. -
maintenance5indicates that the implementation supports the following:-
The ability to expose support for the optional format
VK_FORMAT_A1B5G5R5_UNORM_PACK16. -
The ability to expose support for the optional format
VK_FORMAT_A8_UNORM. -
A property to indicate that multisample coverage operations are performed after sample counting in EarlyFragmentTests mode.
-
Creating a
VkBufferViewwith a subset of the associatedVkBufferusage using VkBufferUsageFlags2CreateInfo. -
A new function vkCmdBindIndexBuffer2, allowing a range of memory to be bound as an index buffer.
-
vkGetDeviceProcAddr will return
NULLfor function pointers of core functions for versions higher than the version requested by the application. -
vkCmdBindVertexBuffers2 supports using
VK_WHOLE_SIZEin thepSizesparameter. -
If
PointSizeis not written, a default value of1.0is used for the size of points. -
VkShaderModuleCreateInfo can be added as a chained structure to pipeline creation via VkPipelineShaderStageCreateInfo, rather than having to create a shader module.
-
A function vkGetRenderingAreaGranularity to query the optimal render area for a dynamic rendering instance.
-
A property to indicate that depth/stencil texturing operations with
VK_COMPONENT_SWIZZLE_ONEhave defined behavior. -
vkGetDeviceImageSubresourceLayout allows an application to perform a vkGetImageSubresourceLayout query without having to create an image.
-
VK_REMAINING_ARRAY_LAYERSas thelayerCountmember of VkImageSubresourceLayers. -
A property to indicate whether
PointSizecontrols the final rasterization of polygons if polygon mode isVK_POLYGON_MODE_POINT. -
Two properties to indicate the non-strict line rasterization algorithm used.
-
Two new flags words VkPipelineCreateFlagBits2 and VkBufferUsageFlagBits2.
-
Physical-device-level functions can now be called with any value in the valid range for a type beyond the defined enumerants, such that applications can avoid checking individual features, extensions, or versions before querying supported properties of a particular enumerant.
-
Copies between images of any type are allowed, with 1D images treated as 2D images with a height of
1.
-
-
maintenance6indicates that the implementation supports the following:-
VK_NULL_HANDLE can be used when binding an index buffer
-
VkBindMemoryStatus can be included in the
pNextchain of the VkBindBufferMemoryInfo and VkBindImageMemoryInfo structures, enabling applications to retrieve VkResult values for individual memory binding operations. -
VkPhysicalDeviceMaintenance6Properties::
blockTexelViewCompatibleMultipleLayersproperty to indicate that the implementation supports creating image views withVK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BITwhere thelayerCountmember ofsubresourceRangeis greater than1. -
VkPhysicalDeviceMaintenance6Properties::
maxCombinedImageSamplerDescriptorCountproperty which indicates the maximum descriptor size required for any format that requires a sampler Y′CBCR conversion supported by the implementation. -
A VkPhysicalDeviceMaintenance6Properties::
fragmentShadingRateClampCombinerInputsproperty which indicates whether the implementation clamps the inputs to fragment shading rate combiner operations.
-
-
pipelineProtectedAccessindicates whether the implementation supports specifying protected access on individual pipelines. -
pipelineRobustnessindicates that robustness can be requested on a per-pipeline-stage granularity. -
hostImageCopyindicates that the implementation supports copying from host memory to images using the vkCopyMemoryToImage command, copying from images to host memory using the vkCopyImageToMemory command, and copying between images using the vkCopyImageToImage command. -
pushDescriptorindicates that the implementation supports push descriptors.
If the VkPhysicalDeviceVulkan14Features 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVulkan14Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVariablePointersFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMultiviewFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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 and payload memory. -
shaderSharedFloat32AtomicAddindicates whether shaders can perform 32-bit floating-point add atomic operations on shared and payload memory. -
shaderSharedFloat64Atomicsindicates whether shaders can perform 64-bit floating-point load, store and exchange atomic operations on shared and payload memory. -
shaderSharedFloat64AtomicAddindicates whether shaders can perform 64-bit floating-point add atomic operations on shared and payload 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderAtomicFloatFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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 and payload memory. -
shaderSharedFloat16AtomicAddindicates whether shaders can perform 16-bit floating-point add atomic operations on shared and payload memory. -
shaderSharedFloat16AtomicMinMaxindicates whether shaders can perform 16-bit floating-point min and max atomic operations on shared and payload memory. -
shaderSharedFloat32AtomicMinMaxindicates whether shaders can perform 32-bit floating-point min and max atomic operations on shared and payload memory. -
shaderSharedFloat64AtomicMinMaxindicates whether shaders can perform 64-bit floating-point min and max atomic operations on shared and payload 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderAtomicFloat2FeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderAtomicInt64Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderAtomicInt64FeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevice8BitStorageFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevice16BitStorageFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderFloat16Int8Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderSubgroupClockindicates whether shaders can performSubgroupscoped clock reads. -
shaderDeviceClockindicates whether shaders can performDevicescoped clock reads.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderClockFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceSamplerYcbcrConversionFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceProtectedMemoryFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceConditionalRenderingFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderDrawParametersFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
taskShaderspecifies whether task shaders are supported. If this feature is not enabled, theVK_SHADER_STAGE_TASK_BIT_NVandVK_PIPELINE_STAGE_TASK_SHADER_BIT_NVenum values must not be used. -
meshShaderspecifies whether mesh shaders are supported. If this feature is not enabled, theVK_SHADER_STAGE_MESH_BIT_NVandVK_PIPELINE_STAGE_MESH_SHADER_BIT_NVenum values must not be used.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMeshShaderFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceMeshShaderFeaturesEXT structure is defined as:
// Provided by VK_EXT_mesh_shader
typedef struct VkPhysicalDeviceMeshShaderFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 taskShader;
VkBool32 meshShader;
VkBool32 multiviewMeshShader;
VkBool32 primitiveFragmentShadingRateMeshShader;
VkBool32 meshShaderQueries;
} VkPhysicalDeviceMeshShaderFeaturesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
taskShaderspecifies whether task shaders are supported. If this feature is not enabled, theVK_SHADER_STAGE_TASK_BIT_EXTandVK_PIPELINE_STAGE_TASK_SHADER_BIT_EXTenum values must not be used. -
meshShaderspecifies whether mesh shaders are supported. If this feature is not enabled, theVK_SHADER_STAGE_MESH_BIT_EXTandVK_PIPELINE_STAGE_MESH_SHADER_BIT_EXTenum values must not be used. -
multiviewMeshShaderspecifies whether the implementation supportsmultiviewrendering within a render pass, with mesh shaders. If this feature is not enabled, then a pipeline compiled against a subpass with a non-zero view mask must not include a mesh shader. -
primitiveFragmentShadingRateMeshShaderindicates that the implementation supports the primitive fragment shading rate in mesh shaders. -
meshShaderQueriesindicates that the implementation supports creating query pools using theVK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXTquery type and statistic queries containing theVK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXTandVK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXTflags
If the VkPhysicalDeviceMeshShaderFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMeshShaderFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The corresponding features of the VkPhysicalDeviceMeshShaderFeaturesNV
structure must match those in VkPhysicalDeviceMeshShaderFeaturesEXT.
The VkPhysicalDeviceMemoryDecompressionFeaturesNV structure is defined
as:
// Provided by VK_NV_memory_decompression
typedef struct VkPhysicalDeviceMemoryDecompressionFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 memoryDecompression;
} VkPhysicalDeviceMemoryDecompressionFeaturesNV;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryDecompressionindicates whether memory decompression is supported.
If the VkPhysicalDeviceMemoryDecompressionFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMemoryDecompressionFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
shaderInputAttachmentArrayDynamicIndexingindicates whether arrays of input attachments can be indexed by integer expressions that are dynamically uniform within either the subgroup or the invocation group 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 integer expressions that are dynamically uniform within either the subgroup or the invocation group 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 integer expressions that are dynamically uniform within either the subgroup or the invocation group 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDescriptorIndexingFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceCopyMemoryIndirectFeaturesNV structure is defined
as:
// Provided by VK_NV_copy_memory_indirect
typedef struct VkPhysicalDeviceCopyMemoryIndirectFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 indirectCopy;
} VkPhysicalDeviceCopyMemoryIndirectFeaturesNV;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
indirectCopyindicates whether indirect copies are supported.
If the VkPhysicalDeviceCopyMemoryIndirectFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCopyMemoryIndirectFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceVertexAttributeDivisorFeatures structure is
defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceVertexAttributeDivisorFeatures {
VkStructureType sType;
void* pNext;
VkBool32 vertexAttributeInstanceRateDivisor;
VkBool32 vertexAttributeInstanceRateZeroDivisor;
} VkPhysicalDeviceVertexAttributeDivisorFeatures;
or the equivalent
// Provided by VK_KHR_vertex_attribute_divisor
typedef VkPhysicalDeviceVertexAttributeDivisorFeatures VkPhysicalDeviceVertexAttributeDivisorFeaturesKHR;
or the equivalent
// Provided by VK_EXT_vertex_attribute_divisor
typedef VkPhysicalDeviceVertexAttributeDivisorFeatures VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
vertexAttributeInstanceRateDivisorspecifies whether vertex attribute fetching may be repeated in the case of instanced rendering. -
vertexAttributeInstanceRateZeroDivisorspecifies whether a zero value for VkVertexInputBindingDivisorDescriptionEXT::divisoris supported.
If the VkPhysicalDeviceVertexAttributeDivisorFeatures 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVertexAttributeDivisorFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
decodeModeSharedExponentindicates whether the implementation supports decoding ASTC compressed formats toVK_FORMAT_E5B9G9R9_UFLOAT_PACK32internal precision.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceASTCDecodeFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceTransformFeedbackFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
vulkanMemoryModelindicates 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVulkanMemoryModelFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceInlineUniformBlockFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRepresentativeFragmentTestFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
exclusiveScissorindicates that the implementation supports the exclusive scissor test.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceExclusiveScissorFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCornerSampledImageFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceComputeShaderDerivativesFeaturesKHR structure is
defined as:
// Provided by VK_KHR_compute_shader_derivatives
typedef struct VkPhysicalDeviceComputeShaderDerivativesFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 computeDerivativeGroupQuads;
VkBool32 computeDerivativeGroupLinear;
} VkPhysicalDeviceComputeShaderDerivativesFeaturesKHR;
or the equivalent
// Provided by VK_NV_compute_shader_derivatives
typedef VkPhysicalDeviceComputeShaderDerivativesFeaturesKHR VkPhysicalDeviceComputeShaderDerivativesFeaturesNV;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
computeDerivativeGroupQuadsindicates that the implementation supports theComputeDerivativeGroupQuadsKHRSPIR-V capability. -
computeDerivativeGroupLinearindicates that the implementation supports theComputeDerivativeGroupLinearKHRSPIR-V capability.
See Quad shader scope for more information.
If the VkPhysicalDeviceComputeShaderDerivativesFeaturesKHR. 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceComputeShaderDerivativesFeaturesKHR., it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageFootprintspecifies whether the implementation supports theImageFootprintNVSPIR-V capability.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderImageFootprintFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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 an application-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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShadingRateImageFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFragmentDensityMapFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFragmentDensityMap2FeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceFragmentDensityMapOffsetFeaturesEXT structure is
defined as:
// Provided by VK_EXT_fragment_density_map_offset
typedef struct VkPhysicalDeviceFragmentDensityMapOffsetFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 fragmentDensityMapOffset;
} VkPhysicalDeviceFragmentDensityMapOffsetFeaturesEXT;
or the equivalent
// Provided by VK_QCOM_fragment_density_map_offset
typedef VkPhysicalDeviceFragmentDensityMapOffsetFeaturesEXT VkPhysicalDeviceFragmentDensityMapOffsetFeaturesQCOM;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityMapOffsetspecifies whether the implementation supports fragment density map offsets
If the VkPhysicalDeviceFragmentDensityMapOffsetFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFragmentDensityMapOffsetFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceFragmentDensityMapLayeredFeaturesVALVE structure
is defined as:
// Provided by VK_VALVE_fragment_density_map_layered
typedef struct VkPhysicalDeviceFragmentDensityMapLayeredFeaturesVALVE {
VkStructureType sType;
void* pNext;
VkBool32 fragmentDensityMapLayered;
} VkPhysicalDeviceFragmentDensityMapLayeredFeaturesVALVE;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityMapLayeredspecifies whether the implementation supports layered fragment density maps.
If the VkPhysicalDeviceFragmentDensityMapLayeredFeaturesVALVE 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFragmentDensityMapLayeredFeaturesVALVE, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
invocationMaskindicates that the implementation supports the use of an invocation mask image to optimize the ray dispatch.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceInvocationMaskFeaturesHUAWEI, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceScalarBlockLayoutFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceUniformBufferStandardLayoutFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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::depthClampEnableisVK_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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDepthClipEnableFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMemoryPriorityFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceBufferDeviceAddressFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceBufferDeviceAddressFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
|
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dedicatedAllocationImageAliasingindicates that the implementation supports aliasing of compatible image objects on a dedicated allocation.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDedicatedAllocationImageAliasingFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImagelessFramebufferFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFragmentShaderInterlockFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCooperativeMatrixFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceCooperativeMatrixFeaturesKHR structure is defined
as:
// Provided by VK_KHR_cooperative_matrix
typedef struct VkPhysicalDeviceCooperativeMatrixFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 cooperativeMatrix;
VkBool32 cooperativeMatrixRobustBufferAccess;
} VkPhysicalDeviceCooperativeMatrixFeaturesKHR;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cooperativeMatrixindicates that the implementation supports theCooperativeMatrixKHRSPIR-V capability. -
cooperativeMatrixRobustBufferAccessindicates that the implementation supports robust buffer access for SPIR-VOpCooperativeMatrixLoadKHRandOpCooperativeMatrixStoreKHRinstructions.
If the VkPhysicalDeviceCooperativeMatrixFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCooperativeMatrixFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceCooperativeMatrix2FeaturesNV structure is defined
as:
// Provided by VK_NV_cooperative_matrix2
typedef struct VkPhysicalDeviceCooperativeMatrix2FeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 cooperativeMatrixWorkgroupScope;
VkBool32 cooperativeMatrixFlexibleDimensions;
VkBool32 cooperativeMatrixReductions;
VkBool32 cooperativeMatrixConversions;
VkBool32 cooperativeMatrixPerElementOperations;
VkBool32 cooperativeMatrixTensorAddressing;
VkBool32 cooperativeMatrixBlockLoads;
} VkPhysicalDeviceCooperativeMatrix2FeaturesNV;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cooperativeMatrixWorkgroupScopeindicates that the implementation supports workgroup scope cooperative matrices. -
cooperativeMatrixFlexibleDimensionsindicates that the implementation supports cooperative matrix sizes that are a multiple of the granularity advertised in VkCooperativeMatrixFlexibleDimensionsPropertiesNV. -
cooperativeMatrixReductionsindicates that the implementation supports theCooperativeMatrixReductionsNVSPIR-V capability. This allows performing (row, column, 2x2, or all element) reductions on matrices. -
cooperativeMatrixConversionsindicates that the implementation supports theCooperativeMatrixConversionsNVSPIR-V capability. This allows converting accumulator matrices to A or B matrices. -
cooperativeMatrixPerElementOperationsindicates that the implementation supports theCooperativeMatrixPerElementOperationsNVSPIR-V capability. This allows performing element-wise operations on matrix elements using a callback function. -
cooperativeMatrixTensorAddressingindicates that the implementation supports theTensorAddressingNVandCooperativeMatrixTensorAddressingNVSPIR-V capabilities. This allows using tensor layout and tensor view types for matrix loads and stores. -
cooperativeMatrixBlockLoadsindicates that the implementation supports theCooperativeMatrixBlockLoadsNVSPIR-V capability. This allows setting block size for loads and using a callback function to decode block elements.
If the VkPhysicalDeviceCooperativeMatrix2FeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCooperativeMatrix2FeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceCooperativeVectorFeaturesNV structure is defined
as:
// Provided by VK_NV_cooperative_vector
typedef struct VkPhysicalDeviceCooperativeVectorFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 cooperativeVector;
VkBool32 cooperativeVectorTraining;
} VkPhysicalDeviceCooperativeVectorFeaturesNV;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cooperativeVectorindicates that the implementation supports theCooperativeVectorNVSPIR-V capability. -
cooperativeVectorTrainingindicates that the implementation supports theCooperativeVectorTrainingNVSPIR-V capability.
If the VkPhysicalDeviceCooperativeVectorFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCooperativeVectorFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceYcbcrImageArraysFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceHostQueryResetFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderIntegerFunctions2indicates that the implementation supports theIntegerFunctions2INTELSPIR-V capability.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderIntegerFunctions2FeaturesINTELfeatures., it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCoverageReductionModeFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceTimelineSemaphoreFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX structure is
defined as:
// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX {
VkStructureType sType;
void* pNext;
VkBool32 screenBufferImport;
} VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX;
The members of the
VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX structure
describe the following features:
-
screenBufferImportindicates whether QNX Screen buffer import functionality is supported. IfscreenBufferImportisVK_TRUE, VkDeviceMemory supports importing_screen_bufferfrom applications. In this case, the application is responsible for the resource management of the_screen_buffer.
Features |
Functionality |
|
|
Always supported1 |
vkGetScreenBufferPropertiesQNX, VkScreenBufferPropertiesQNX, VkScreenBufferFormatPropertiesQNX, VkExternalFormatQNX |
- 1
-
Functionality in this row is always available.
The Functionality supported for QNX
Screen buffer features table summarizes the functionality enabled by the
VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX structure.
Each entry in the body of the table summarizes the functionality that can
be used when the given features are supported and enabled.
This summarizes Valid Usage statements that are added elsewhere in this
specification.
If the VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceIndexTypeUint8Features structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceIndexTypeUint8Features {
VkStructureType sType;
void* pNext;
VkBool32 indexTypeUint8;
} VkPhysicalDeviceIndexTypeUint8Features;
or the equivalent
// Provided by VK_KHR_index_type_uint8
typedef VkPhysicalDeviceIndexTypeUint8Features VkPhysicalDeviceIndexTypeUint8FeaturesKHR;
or the equivalent
// Provided by VK_EXT_index_type_uint8
typedef VkPhysicalDeviceIndexTypeUint8Features VkPhysicalDeviceIndexTypeUint8FeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
indexTypeUint8indicates thatVK_INDEX_TYPE_UINT8can be used with vkCmdBindIndexBuffer2 and vkCmdBindIndexBuffer.
If the VkPhysicalDeviceIndexTypeUint8Features 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceIndexTypeUint8Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePrimitiveTopologyListRestartFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderSMBuiltinsindicates whether the implementation supports the SPIR-VShaderSMBuiltinsNVcapability.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderSMBuiltinsFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineExecutableInfoindicates that the implementation supports reporting properties and statistics about the pipeline executables associated with a compiled pipeline.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePipelineExecutablePropertiesFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceTexelBufferAlignmentFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceAttachmentFeedbackLoopDynamicStateFeaturesEXT
structure is defined as:
// Provided by VK_EXT_attachment_feedback_loop_dynamic_state
typedef struct VkPhysicalDeviceAttachmentFeedbackLoopDynamicStateFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 attachmentFeedbackLoopDynamicState;
} VkPhysicalDeviceAttachmentFeedbackLoopDynamicStateFeaturesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentFeedbackLoopDynamicStatespecifies whether dynamic feedback loops are supported.
If the VkPhysicalDeviceAttachmentFeedbackLoopDynamicStateFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceAttachmentFeedbackLoopDynamicStateFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceLegacyVertexAttributesFeaturesEXT structure is
defined as:
// Provided by VK_EXT_legacy_vertex_attributes
typedef struct VkPhysicalDeviceLegacyVertexAttributesFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 legacyVertexAttributes;
} VkPhysicalDeviceLegacyVertexAttributesFeaturesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
legacyVertexAttributesspecifies whether compatibility features for vertex attributes are supported when using dynamic vertex input state.
If the VkPhysicalDeviceLegacyVertexAttributesFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceLegacyVertexAttributesFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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_BLOCKTo 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceTextureCompressionASTCHDRFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceLineRasterizationFeatures structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceLineRasterizationFeatures {
VkStructureType sType;
void* pNext;
VkBool32 rectangularLines;
VkBool32 bresenhamLines;
VkBool32 smoothLines;
VkBool32 stippledRectangularLines;
VkBool32 stippledBresenhamLines;
VkBool32 stippledSmoothLines;
} VkPhysicalDeviceLineRasterizationFeatures;
or the equivalent
// Provided by VK_KHR_line_rasterization
typedef VkPhysicalDeviceLineRasterizationFeatures VkPhysicalDeviceLineRasterizationFeaturesKHR;
or the equivalent
// Provided by VK_EXT_line_rasterization
typedef VkPhysicalDeviceLineRasterizationFeatures VkPhysicalDeviceLineRasterizationFeaturesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying 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_RECTANGULARlines. -
stippledBresenhamLinesindicates whether the implementation supports stippled line rasterization withVK_LINE_RASTERIZATION_MODE_BRESENHAMlines. -
stippledSmoothLinesindicates whether the implementation supports stippled line rasterization withVK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTHlines.
If the VkPhysicalDeviceLineRasterizationFeatures 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceLineRasterizationFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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 , mesh, or task 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceSubgroupSizeControlFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
|
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCoherentMemoryFeaturesAMD, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceAccelerationStructureFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRayTracingPipelineFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rayQueryindicates whether the implementation supports ray query (OpRayQueryProceedKHR) functionality.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRayQueryFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRayTracingMaintenance1FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceVideoEncodeQuantizationMapFeaturesKHR structure is
defined as:
// Provided by VK_KHR_video_encode_quantization_map
typedef struct VkPhysicalDeviceVideoEncodeQuantizationMapFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 videoEncodeQuantizationMap;
} VkPhysicalDeviceVideoEncodeQuantizationMapFeaturesKHR;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoEncodeQuantizationMapindicates that the implementation supports video encode quantization maps.NoteSupport for
videoEncodeQuantizationMapdoes not indicate that all video encode profiles support quantization maps. Support for quantization maps for any specific video encode profile is subject to video-profile-specific capabilities.
If the VkPhysicalDeviceVideoEncodeQuantizationMapFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVideoEncodeQuantizationMapFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceVideoEncodeIntraRefreshFeaturesKHR structure is
defined as:
// Provided by VK_KHR_video_encode_intra_refresh
typedef struct VkPhysicalDeviceVideoEncodeIntraRefreshFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 videoEncodeIntraRefresh;
} VkPhysicalDeviceVideoEncodeIntraRefreshFeaturesKHR;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoEncodeIntraRefreshspecifies that the implementation supports video encode intra refresh.NoteSupport for
videoEncodeIntraRefreshdoes not indicate that all video encode profiles support intra refresh. Support for intra refresh for any specific video encode profile is subject to video-profile-specific capabilities.
If the VkPhysicalDeviceVideoEncodeIntraRefreshFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVideoEncodeIntraRefreshFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceVideoMaintenance1FeaturesKHR structure is defined
as:
// Provided by VK_KHR_video_maintenance1
typedef struct VkPhysicalDeviceVideoMaintenance1FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 videoMaintenance1;
} VkPhysicalDeviceVideoMaintenance1FeaturesKHR;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoMaintenance1indicates that the implementation supports the following:-
The new buffer creation flag
VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. -
The new image creation flag
VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. -
The new video session creation flag
VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR.
-
If the VkPhysicalDeviceVideoMaintenance1FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVideoMaintenance1FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceVideoMaintenance2FeaturesKHR structure is defined
as:
// Provided by VK_KHR_video_maintenance2
typedef struct VkPhysicalDeviceVideoMaintenance2FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 videoMaintenance2;
} VkPhysicalDeviceVideoMaintenance2FeaturesKHR;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoMaintenance2specifies that the implementation supports the following:-
Support for issuing video coding control commands against video decode sessions without a bound video session parameters object.
-
The new video session creation flag
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHRfor video decode sessions. -
Required support for the rate control mode
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHRfor the following video encode profiles: -
Additional guarantees on Video Std parameters used with video encode profiles that the implementations support without the need to override them.
-
If the VkPhysicalDeviceVideoMaintenance2FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVideoMaintenance2FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceVideoEncodeAV1FeaturesKHR structure is defined as:
// Provided by VK_KHR_video_encode_av1
typedef struct VkPhysicalDeviceVideoEncodeAV1FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 videoEncodeAV1;
} VkPhysicalDeviceVideoEncodeAV1FeaturesKHR;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoEncodeAV1indicates that the implementation supports AV1 encode operations.
If the VkPhysicalDeviceVideoEncodeAV1FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVideoEncodeAV1FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceVideoDecodeVP9FeaturesKHR structure is defined as:
// Provided by VK_KHR_video_decode_vp9
typedef struct VkPhysicalDeviceVideoDecodeVP9FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 videoDecodeVP9;
} VkPhysicalDeviceVideoDecodeVP9FeaturesKHR;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
videoDecodeVP9specifies that the implementation supports VP9 decode operations.
If the VkPhysicalDeviceVideoDecodeVP9FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVideoDecodeVP9FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceExtendedDynamicStateFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceExtendedDynamicState2FeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceExtendedDynamicState3FeaturesEXT structure is
defined as:
// Provided by VK_EXT_extended_dynamic_state3
typedef struct VkPhysicalDeviceExtendedDynamicState3FeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 extendedDynamicState3TessellationDomainOrigin;
VkBool32 extendedDynamicState3DepthClampEnable;
VkBool32 extendedDynamicState3PolygonMode;
VkBool32 extendedDynamicState3RasterizationSamples;
VkBool32 extendedDynamicState3SampleMask;
VkBool32 extendedDynamicState3AlphaToCoverageEnable;
VkBool32 extendedDynamicState3AlphaToOneEnable;
VkBool32 extendedDynamicState3LogicOpEnable;
VkBool32 extendedDynamicState3ColorBlendEnable;
VkBool32 extendedDynamicState3ColorBlendEquation;
VkBool32 extendedDynamicState3ColorWriteMask;
VkBool32 extendedDynamicState3RasterizationStream;
VkBool32 extendedDynamicState3ConservativeRasterizationMode;
VkBool32 extendedDynamicState3ExtraPrimitiveOverestimationSize;
VkBool32 extendedDynamicState3DepthClipEnable;
VkBool32 extendedDynamicState3SampleLocationsEnable;
VkBool32 extendedDynamicState3ColorBlendAdvanced;
VkBool32 extendedDynamicState3ProvokingVertexMode;
VkBool32 extendedDynamicState3LineRasterizationMode;
VkBool32 extendedDynamicState3LineStippleEnable;
VkBool32 extendedDynamicState3DepthClipNegativeOneToOne;
VkBool32 extendedDynamicState3ViewportWScalingEnable;
VkBool32 extendedDynamicState3ViewportSwizzle;
VkBool32 extendedDynamicState3CoverageToColorEnable;
VkBool32 extendedDynamicState3CoverageToColorLocation;
VkBool32 extendedDynamicState3CoverageModulationMode;
VkBool32 extendedDynamicState3CoverageModulationTableEnable;
VkBool32 extendedDynamicState3CoverageModulationTable;
VkBool32 extendedDynamicState3CoverageReductionMode;
VkBool32 extendedDynamicState3RepresentativeFragmentTestEnable;
VkBool32 extendedDynamicState3ShadingRateImageEnable;
} VkPhysicalDeviceExtendedDynamicState3FeaturesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
extendedDynamicState3TessellationDomainOriginindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT
-
-
extendedDynamicState3DepthClampEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT
-
-
extendedDynamicState3PolygonModeindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_POLYGON_MODE_EXT
-
-
extendedDynamicState3RasterizationSamplesindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT
-
-
extendedDynamicState3SampleMaskindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_SAMPLE_MASK_EXT
-
-
extendedDynamicState3AlphaToCoverageEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT
-
-
extendedDynamicState3AlphaToOneEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT
-
-
extendedDynamicState3LogicOpEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT
-
-
extendedDynamicState3ColorBlendEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT
-
-
extendedDynamicState3ColorBlendEquationindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT
-
-
extendedDynamicState3ColorWriteMaskindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT
-
-
extendedDynamicState3RasterizationStreamindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT
-
-
extendedDynamicState3ConservativeRasterizationModeindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT
-
-
extendedDynamicState3ExtraPrimitiveOverestimationSizeindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT
-
-
extendedDynamicState3DepthClipEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT
-
-
extendedDynamicState3SampleLocationsEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT
-
-
extendedDynamicState3ColorBlendAdvancedindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT
-
-
extendedDynamicState3ProvokingVertexModeindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT
-
-
extendedDynamicState3LineRasterizationModeindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT
-
-
extendedDynamicState3LineStippleEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT
-
-
extendedDynamicState3DepthClipNegativeOneToOneindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT
-
-
extendedDynamicState3ViewportWScalingEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV
-
-
extendedDynamicState3ViewportSwizzleindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV
-
-
extendedDynamicState3CoverageToColorEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV
-
-
extendedDynamicState3CoverageToColorLocationindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV
-
-
extendedDynamicState3CoverageModulationModeindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV
-
-
extendedDynamicState3CoverageModulationTableEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV
-
-
extendedDynamicState3CoverageModulationTableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV
-
-
extendedDynamicState3CoverageReductionModeindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV
-
-
extendedDynamicState3RepresentativeFragmentTestEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV
-
-
extendedDynamicState3ShadingRateImageEnableindicates that the implementation supports the following dynamic state:-
VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV
-
If the VkPhysicalDeviceExtendedDynamicState3FeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceExtendedDynamicState3FeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDeviceGeneratedCommandsComputeFeaturesNV structure
is defined as:
// Provided by VK_NV_device_generated_commands_compute
typedef struct VkPhysicalDeviceDeviceGeneratedCommandsComputeFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 deviceGeneratedCompute;
VkBool32 deviceGeneratedComputePipelines;
VkBool32 deviceGeneratedComputeCaptureReplay;
} VkPhysicalDeviceDeviceGeneratedCommandsComputeFeaturesNV;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceGeneratedComputeindicates whether the implementation supports functionality to generate dispatch commands and push constants for the compute pipeline on the device. See Device-Generated Commands. -
deviceGeneratedComputePipelinesindicates whether the implementation supports functionality to generate commands to bind compute pipelines on the device. See Device-Generated Commands. -
deviceGeneratedComputeCaptureReplayindicates whether the implementation supports functionality to capture compute pipeline address and reuse later for replay in Device-Generated Commands.
If the VkPhysicalDeviceDeviceGeneratedCommandsComputeFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDeviceGeneratedCommandsComputeFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT structure is
defined as:
// Provided by VK_EXT_device_generated_commands
typedef struct VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 deviceGeneratedCommands;
VkBool32 dynamicGeneratedPipelineLayout;
} VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceGeneratedCommandsindicates whether the implementation supports functionality to generate commands on the device. -
dynamicGeneratedPipelineLayoutindicates the implementation allows thepipelineLayoutmember of VkIndirectCommandsLayoutCreateInfoEXT to be VK_NULL_HANDLE and VkPipelineLayoutCreateInfo can be chained off those structures'pNextinstead.
If the VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDeviceGeneratedCommandsFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
diagnosticsConfigindicates whether the implementation supports the ability to configure diagnostic tools.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDiagnosticsConfigFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceClusterAccelerationStructureFeaturesNV structure
is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkPhysicalDeviceClusterAccelerationStructureFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 clusterAccelerationStructure;
} VkPhysicalDeviceClusterAccelerationStructureFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
clusterAccelerationStructureindicates whether the implementation supports the ability to generate and trace cluster acceleration structures.
If the VkPhysicalDeviceClusterAccelerationStructureFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceClusterAccelerationStructureFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePartitionedAccelerationStructureFeaturesNV
structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPhysicalDevicePartitionedAccelerationStructureFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 partitionedAccelerationStructure;
} VkPhysicalDevicePartitionedAccelerationStructureFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
partitionedAccelerationStructureindicates whether the implementation supports the ability to generate top level partitioned acceleration structures.
If the VkPhysicalDevicePartitionedAccelerationStructureFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePartitionedAccelerationStructureFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceMemoryReportindicates whether the implementation supports the ability to register device memory report callbacks.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDeviceMemoryReportFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceGlobalPriorityQueryFeatures structure is defined
as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceGlobalPriorityQueryFeatures {
VkStructureType sType;
void* pNext;
VkBool32 globalPriorityQuery;
} VkPhysicalDeviceGlobalPriorityQueryFeatures;
or the equivalent
// Provided by VK_KHR_global_priority
typedef VkPhysicalDeviceGlobalPriorityQueryFeatures VkPhysicalDeviceGlobalPriorityQueryFeaturesKHR;
or the equivalent
// Provided by VK_EXT_global_priority_query
typedef VkPhysicalDeviceGlobalPriorityQueryFeatures VkPhysicalDeviceGlobalPriorityQueryFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceGlobalPriorityQueryFeatures 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceGlobalPriorityQueryFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePipelineCreationCacheControlFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePrivateDataFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderSubgroupUniformControlFlowspecifies whether the implementation supports the shader execution modeSubgroupUniformControlFlowKHR
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderSubgroupUniformControlFlowFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRobustness2FeaturesKHR structure is defined as:
// Provided by VK_KHR_robustness2
typedef struct VkPhysicalDeviceRobustness2FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 robustBufferAccess2;
VkBool32 robustImageAccess2;
VkBool32 nullDescriptor;
} VkPhysicalDeviceRobustness2FeaturesKHR;
or the equivalent
// Provided by VK_EXT_robustness2
typedef VkPhysicalDeviceRobustness2FeaturesKHR VkPhysicalDeviceRobustness2FeaturesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
robustBufferAccess2enables Robust Buffer Access 2 guarantees for shader buffer accesses. -
robustImageAccess2enables Robust Image Access 2 guarantees for shader image accesses. -
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 VkPhysicalDeviceRobustness2FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRobustness2FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
robustImageAccessenables Robust Image Access guarantees for shader image accesses.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImageRobustnessFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderTerminateInvocationFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCustomBorderColorFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceBorderColorSwizzleFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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 if thetessellationShaderfeature is supported. -
tessellationPointModeindicates whether this implementation supports point output from the Tessellation stage of a graphics pipeline. This member is only meaningful if thetessellationShaderfeature is 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePortabilitySubsetFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePerformanceQueryFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevice4444FormatsFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
|
Note
|
Although the formats defined by the |
The VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT structure is
defined as:
// Provided by VK_EXT_mutable_descriptor_type
typedef struct VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 mutableDescriptorType;
} VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT;
or the equivalent
// Provided by VK_VALVE_mutable_descriptor_type
typedef VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
mutableDescriptorTypeindicates that the implementation must support using the VkDescriptorType ofVK_DESCRIPTOR_TYPE_MUTABLE_EXTwith 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 VkMutableDescriptorTypeListEXT for
VK_DESCRIPTOR_TYPE_MUTABLE_EXThave the corresponding non-uniform indexing features enabled in VkPhysicalDeviceDescriptorIndexingFeatures. -
VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BITwithdescriptorTypeofVK_DESCRIPTOR_TYPE_MUTABLE_EXTrelaxes 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 VkMutableDescriptorTypeListEXT for
VK_DESCRIPTOR_TYPE_MUTABLE_EXThave the corresponding dynamic indexing features enabled. -
VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXTmust be supported. -
VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXTmust be supported.
-
If the VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 describes the following feature:
-
sTypeis a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDepthClipControlFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDepthClampControlFeaturesEXT structure is defined
as:
// Provided by VK_EXT_depth_clamp_control
typedef struct VkPhysicalDeviceDepthClampControlFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 depthClampControl;
} VkPhysicalDeviceDepthClampControlFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
depthClampControlindicates that the implementation supports setting VkPipelineViewportDepthClampControlCreateInfoEXT::depthClampModetoVK_DEPTH_CLAMP_MODE_USER_DEFINED_RANGE_EXT.
If the VkPhysicalDeviceDepthClampControlFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDepthClampControlFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceWorkgroupMemoryExplicitLayoutFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceSynchronization2Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexInputDynamicStateindicates that the implementation supports the following dynamic states:-
VK_DYNAMIC_STATE_VERTEX_INPUT_EXT
-
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVertexInputDynamicStateFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePrimitivesGeneratedQueryFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFragmentShadingRateFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceLegacyDitheringFeaturesEXT structure is defined
as:
// Provided by VK_EXT_legacy_dithering
typedef struct VkPhysicalDeviceLegacyDitheringFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 legacyDithering;
} VkPhysicalDeviceLegacyDitheringFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
legacyDitheringindicates whether the implementation supports Legacy Dithering.
If the VkPhysicalDeviceLegacyDitheringFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceLegacyDitheringFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFragmentShadingRateEnumsFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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_DISCARD_RECTANGLE_ENABLE_EXT,VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceInheritedViewportScissorFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePipelineProtectedAccessFeatures structure is
defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDevicePipelineProtectedAccessFeatures {
VkStructureType sType;
void* pNext;
VkBool32 pipelineProtectedAccess;
} VkPhysicalDevicePipelineProtectedAccessFeatures;
or the equivalent
// Provided by VK_EXT_pipeline_protected_access
typedef VkPhysicalDevicePipelineProtectedAccessFeatures VkPhysicalDevicePipelineProtectedAccessFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDevicePipelineProtectedAccessFeatures 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePipelineProtectedAccessFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceYcbcr2Plane444FormatsFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
|
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
colorWriteEnableindicates that the implementation supports the dynamic stateVK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceColorWriteEnableFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelinePropertiesIdentifierindicates that the implementation supports querying a unique pipeline identifier.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePipelinePropertiesFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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 theVK_EXT_transform_feedbackextension 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceProvokingVertexFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
When VkPhysicalDeviceProvokingVertexFeaturesEXT is in the pNext
chain of VkDeviceCreateInfo but the transformFeedback feature is not enabled, the value of
transformFeedbackPreservesProvokingVertex is ignored.
The VkPhysicalDeviceDescriptorBufferFeaturesEXT structure is defined
as:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkPhysicalDeviceDescriptorBufferFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 descriptorBuffer;
VkBool32 descriptorBufferCaptureReplay;
VkBool32 descriptorBufferImageLayoutIgnored;
VkBool32 descriptorBufferPushDescriptors;
} VkPhysicalDeviceDescriptorBufferFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
descriptorBufferindicates that the implementation supports putting shader-accessible descriptors directly in memory. -
descriptorBufferCaptureReplayindicates that the implementation supports capture and replay when using descriptor buffers. If this isVK_TRUE, all resources created withVK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT,VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT,VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT,VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, orVK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTmust be created before resources of the same types without those flags. -
descriptorBufferImageLayoutIgnoredindicates that the implementation will ignoreimageLayoutinVkDescriptorImageInfowhen calling vkGetDescriptorEXT. -
descriptorBufferPushDescriptorsindicates that the implementation supports using push descriptors with descriptor buffers.
If the VkPhysicalDeviceDescriptorBufferFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDescriptorBufferFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDescriptorBufferTensorFeaturesARM structure is
defined as:
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
typedef struct VkPhysicalDeviceDescriptorBufferTensorFeaturesARM {
VkStructureType sType;
void* pNext;
VkBool32 descriptorBufferTensorDescriptors;
} VkPhysicalDeviceDescriptorBufferTensorFeaturesARM;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
descriptorBufferTensorDescriptorsindicates that the implementation supports putthing shader-accessible tensor descriptors directly in memory.
If the VkPhysicalDeviceDescriptorBufferTensorFeaturesARM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDescriptorBufferTensorFeaturesARM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMultiDrawFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRayTracingMotionBlurFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRayTracingLinearSweptSpheresFeaturesNV structure
is defined as:
// Provided by VK_NV_ray_tracing_linear_swept_spheres
typedef struct VkPhysicalDeviceRayTracingLinearSweptSpheresFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 spheres;
VkBool32 linearSweptSpheres;
} VkPhysicalDeviceRayTracingLinearSweptSpheresFeaturesNV;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
spheresindicates whether the implementation supports sphere primitives in ray tracing. -
linearSweptSpheresindicates whether the implementation supports linear swept sphere primitives in ray tracing.
If the VkPhysicalDeviceRayTracingLinearSweptSpheresFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRayTracingLinearSweptSpheresFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceOpacityMicromapFeaturesEXT structure is defined
as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkPhysicalDeviceOpacityMicromapFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 micromap;
VkBool32 micromapCaptureReplay;
VkBool32 micromapHostCommands;
} VkPhysicalDeviceOpacityMicromapFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
micromapindicates whether the implementation supports the micromap array feature. -
micromapCaptureReplayindicates whether the implementation supports capture and replay of addresses for micromap arrays. -
micromapHostCommandsindicates whether the implementation supports host side micromap array commands.
If the VkPhysicalDeviceOpacityMicromapFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceOpacityMicromapFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDisplacementMicromapFeaturesNV structure is
defined as:
// Provided by VK_NV_displacement_micromap
typedef struct VkPhysicalDeviceDisplacementMicromapFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 displacementMicromap;
} VkPhysicalDeviceDisplacementMicromapFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
displacementMicromapindicates whether the implementation supports the displacement micromap feature.
If the VkPhysicalDeviceDisplacementMicromapFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDisplacementMicromapFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRayTracingValidationFeaturesNV structure is
defined as:
// Provided by VK_NV_ray_tracing_validation
typedef struct VkPhysicalDeviceRayTracingValidationFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 rayTracingValidation;
} VkPhysicalDeviceRayTracingValidationFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rayTracingValidationindicates whether the implementation supports the ray tracing validation feature.
If the VkPhysicalDeviceRayTracingValidationFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRayTracingValidationFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceZeroInitializeDeviceMemoryFeaturesEXT structure is
defined as:
// Provided by VK_EXT_zero_initialize_device_memory
typedef struct VkPhysicalDeviceZeroInitializeDeviceMemoryFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 zeroInitializeDeviceMemory;
} VkPhysicalDeviceZeroInitializeDeviceMemoryFeaturesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
zeroInitializeDeviceMemoryindicates that the implementation supports zeroing memory allocations using a user-specified flag.
If the VkPhysicalDeviceZeroInitializeDeviceMemoryFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceZeroInitializeDeviceMemoryFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
subpassShadingspecifies whether subpass shading is supported.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceSubpassShadingFeaturesHUAWEI, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceExternalMemoryRDMAFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentIdindicates that the implementation supports specifying present ID values in theVkPresentIdKHRextension to theVkPresentInfoKHRstruct.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePresentIdFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePresentId2FeaturesKHR structure is defined as:
// Provided by VK_KHR_present_id2
typedef struct VkPhysicalDevicePresentId2FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 presentId2;
} VkPhysicalDevicePresentId2FeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentId2indicates that the implementation supports specifying present ID values in theVkPresentId2KHRextension to theVkPresentInfoKHRstruct.
If the VkPhysicalDevicePresentId2FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePresentId2FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentWaitindicates that the implementation supportsvkWaitForPresentKHR.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePresentWaitFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePresentWait2FeaturesKHR structure is defined as:
// Provided by VK_KHR_present_wait2
typedef struct VkPhysicalDevicePresentWait2FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 presentWait2;
} VkPhysicalDevicePresentWait2FeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentWait2indicates that the implementation supportsvkWaitForPresent2KHR.
If the VkPhysicalDevicePresentWait2FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePresentWait2FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceUnifiedImageLayoutsFeaturesKHR structure is
defined as:
// Provided by VK_KHR_unified_image_layouts
typedef struct VkPhysicalDeviceUnifiedImageLayoutsFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 unifiedImageLayouts;
VkBool32 unifiedImageLayoutsVideo;
} VkPhysicalDeviceUnifiedImageLayoutsFeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
unifiedImageLayoutsspecifies whether usage ofVK_IMAGE_LAYOUT_GENERAL, where valid, incurs no loss in efficiency. Additionally, it indicates whether it can be used in place ofVK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT. -
unifiedImageLayoutsVideospecifies whetherVK_IMAGE_LAYOUT_GENERALcan be used in place of any of the following image layouts with no loss in efficiency.-
VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR -
VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR -
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_QUANTIZATION_MAP_KHR
-
If the VkPhysicalDeviceUnifiedImageLayoutsFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceUnifiedImageLayoutsFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceHostImageCopyFeatures structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceHostImageCopyFeatures {
VkStructureType sType;
void* pNext;
VkBool32 hostImageCopy;
} VkPhysicalDeviceHostImageCopyFeatures;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkPhysicalDeviceHostImageCopyFeatures VkPhysicalDeviceHostImageCopyFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
hostImageCopyindicates that the implementation supports copying from host memory to images using the vkCopyMemoryToImage command, copying from images to host memory using the vkCopyImageToMemory command, and copying between images using the vkCopyImageToImage command.
If the VkPhysicalDeviceHostImageCopyFeatures 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceHostImageCopyFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePresentBarrierFeaturesNV structure is defined as:
// Provided by VK_NV_present_barrier
typedef struct VkPhysicalDevicePresentBarrierFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 presentBarrier;
} VkPhysicalDevicePresentBarrierFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentBarrierindicates that the implementation supports the present barrier feature.
If the VkPhysicalDevicePresentBarrierFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePresentBarrierFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderIntegerDotProductFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMaintenance4Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceMaintenance5Features structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceMaintenance5Features {
VkStructureType sType;
void* pNext;
VkBool32 maintenance5;
} VkPhysicalDeviceMaintenance5Features;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkPhysicalDeviceMaintenance5Features VkPhysicalDeviceMaintenance5FeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
maintenance5indicates that the implementation supports the following:-
The ability to expose support for the optional format
VK_FORMAT_A1B5G5R5_UNORM_PACK16. -
The ability to expose support for the optional format
VK_FORMAT_A8_UNORM. -
A property to indicate that multisample coverage operations are performed after sample counting in EarlyFragmentTests mode.
-
Creating a
VkBufferViewwith a subset of the associatedVkBufferusage using VkBufferUsageFlags2CreateInfo. -
A new function vkCmdBindIndexBuffer2, allowing a range of memory to be bound as an index buffer.
-
vkGetDeviceProcAddr will return
NULLfor function pointers of core functions for versions higher than the version requested by the application. -
vkCmdBindVertexBuffers2 supports using
VK_WHOLE_SIZEin thepSizesparameter. -
If
PointSizeis not written, a default value of1.0is used for the size of points. -
VkShaderModuleCreateInfo can be added as a chained structure to pipeline creation via VkPipelineShaderStageCreateInfo, rather than having to create a shader module.
-
A function vkGetRenderingAreaGranularity to query the optimal render area for a dynamic rendering instance.
-
A property to indicate that depth/stencil texturing operations with
VK_COMPONENT_SWIZZLE_ONEhave defined behavior. -
vkGetDeviceImageSubresourceLayout allows an application to perform a vkGetImageSubresourceLayout query without having to create an image.
-
VK_REMAINING_ARRAY_LAYERSas thelayerCountmember of VkImageSubresourceLayers. -
A property to indicate whether
PointSizecontrols the final rasterization of polygons if polygon mode isVK_POLYGON_MODE_POINT. -
Two properties to indicate the non-strict line rasterization algorithm used.
-
Two new flags words VkPipelineCreateFlagBits2 and VkBufferUsageFlagBits2.
-
Physical-device-level functions can now be called with any value in the valid range for a type beyond the defined enumerants, such that applications can avoid checking individual features, extensions, or versions before querying supported properties of a particular enumerant.
-
Copies between images of any type are allowed, with 1D images treated as 2D images with a height of
1.
-
If the VkPhysicalDeviceMaintenance5Features 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMaintenance5Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceMaintenance6Features structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceMaintenance6Features {
VkStructureType sType;
void* pNext;
VkBool32 maintenance6;
} VkPhysicalDeviceMaintenance6Features;
or the equivalent
// Provided by VK_KHR_maintenance6
typedef VkPhysicalDeviceMaintenance6Features VkPhysicalDeviceMaintenance6FeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
maintenance6indicates that the implementation supports the following:-
VK_NULL_HANDLE can be used when binding an index buffer
-
VkBindMemoryStatus can be included in the
pNextchain of the VkBindBufferMemoryInfo and VkBindImageMemoryInfo structures, enabling applications to retrieve VkResult values for individual memory binding operations. -
VkPhysicalDeviceMaintenance6Properties::
blockTexelViewCompatibleMultipleLayersproperty to indicate that the implementation supports creating image views withVK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BITwhere thelayerCountmember ofsubresourceRangeis greater than1. -
VkPhysicalDeviceMaintenance6Properties::
maxCombinedImageSamplerDescriptorCountproperty which indicates the maximum descriptor size required for any format that requires a sampler Y′CBCR conversion supported by the implementation. -
A VkPhysicalDeviceMaintenance6Properties::
fragmentShadingRateClampCombinerInputsproperty which indicates whether the implementation clamps the inputs to fragment shading rate combiner operations.
-
If the VkPhysicalDeviceMaintenance6Features 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMaintenance6Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceMaintenance7FeaturesKHR structure is defined as:
// Provided by VK_KHR_maintenance7
typedef struct VkPhysicalDeviceMaintenance7FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 maintenance7;
} VkPhysicalDeviceMaintenance7FeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maintenance7indicates that the implementation supports the following:-
The
VK_RENDERING_CONTENTS_INLINE_BIT_KHRandVK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHRflags can be used to record commands in render pass instances both inline and in secondary command buffers executed with vkCmdExecuteCommands for dynamic rendering and legacy render passes respectively. -
Querying information regarding the underlying devices in environments where the Vulkan implementation is provided through layered implementations. This is done by chaining VkPhysicalDeviceLayeredApiPropertiesListKHR to VkPhysicalDeviceProperties2.
-
New limits which indicate the maximum total count of dynamic uniform buffers and dynamic storage buffers that can be included in a pipeline layout.
-
32-bit timestamp queries must wrap on overflow
-
A property that indicates whether a fragment shading rate attachment can have a size that is too small to cover a specified render area.
-
A property that indicates support for writing to one aspect of a depth/stencil attachment without performing a read-modify-write operation on the other aspect
-
If the VkPhysicalDeviceMaintenance7FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMaintenance7FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceMaintenance8FeaturesKHR structure is defined as:
// Provided by VK_KHR_maintenance8
typedef struct VkPhysicalDeviceMaintenance8FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 maintenance8;
} VkPhysicalDeviceMaintenance8FeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maintenance8indicates that the implementation supports the following:-
Allow copies between depth/stencil and “matching” color attachments
-
Allow
dstCacheinvkMergePipelineCachesto be implicitly synchronized. -
Require src/dst sync scopes to work when doing queue family ownership transfers
-
Support
Offset(as an alternative toConstOffset) image operand in texture sampling and fetch operations -
Use the SPIR-V definition of OpSRem and OpSMod, making these operations produce well-defined results for negative operands
-
Loosen layer restrictions when blitting from 3D images to other image types
-
Add space for an additional 64 access flags for use with VkMemoryBarrier2, VkBufferMemoryBarrier2, and VkImageMemoryBarrier2
-
If the VkPhysicalDeviceMaintenance8FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMaintenance8FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceMaintenance9FeaturesKHR structure is defined as:
// Provided by VK_KHR_maintenance9
typedef struct VkPhysicalDeviceMaintenance9FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 maintenance9;
} VkPhysicalDeviceMaintenance9FeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maintenance9indicates that the implementation supports the following:-
The restriction that certain bitfield SPIR-V instructions only operate on 32-bit integers is relaxed.
-
The value returned when a vertex shader reads an unbound vertex attribute is defined by way of the
defaultVertexAttributeValueproperty. -
A new VkQueryPoolCreateFlagBits::
VK_QUERY_POOL_CREATE_RESET_BIT_KHRflag can be used to initialize all queries in query pool to the reset state on creation. -
vkCmdSetEvent2 may not provide a dependency other than the event src stage mask.
-
The effects of image memory barriers and image layout transitions on 3D images created with
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BITare limited to only those slices specified inVkImageSubresourceRange -
A device can be created with no queues. This can be used for compiling pipelines or shaders for the purpose of filling pipeline caches.
-
Queue family ownership transfers are no longer required when transitioning resources created with
VK_SHARING_MODE_EXCLUSIVEbetween queue families that supportVK_QUEUE_GRAPHICS_BITand those that support onlyVK_QUEUE_TRANSFER_BIT. -
image2DViewOf3DSparseenables 2D views of 3D sparse images.
-
If the VkPhysicalDeviceMaintenance9FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMaintenance9FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDynamicRenderingFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT structure is defined
as:
// Provided by VK_EXT_rgba10x6_formats
typedef struct VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 formatRgba10x6WithoutYCbCrSampler;
} VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePipelineRobustnessFeatures structure is defined
as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDevicePipelineRobustnessFeatures {
VkStructureType sType;
void* pNext;
VkBool32 pipelineRobustness;
} VkPhysicalDevicePipelineRobustnessFeatures;
or the equivalent
// Provided by VK_EXT_pipeline_robustness
typedef VkPhysicalDevicePipelineRobustnessFeatures VkPhysicalDevicePipelineRobustnessFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
|
Note
|
Enabling the |
If the VkPhysicalDevicePipelineRobustnessFeatures 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePipelineRobustnessFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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, Texel Gathering 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImageViewMinLodFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesEXT
structure is defined as:
// Provided by VK_EXT_rasterization_order_attachment_access
typedef struct VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 rasterizationOrderColorAttachmentAccess;
VkBool32 rasterizationOrderDepthAttachmentAccess;
VkBool32 rasterizationOrderStencilAttachmentAccess;
} VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesEXT;
or the equivalent
// Provided by VK_ARM_rasterization_order_attachment_access
typedef VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesEXT VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesARM;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying 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 VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRasterizationOrderAttachmentAccessFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
subpassMergeFeedbackindicates whether the implementation supports feedback of subpass merging.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceSubpassMergeFeedbackFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceLinearColorAttachmentFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceAttachmentFeedbackLoopLayoutFeaturesEXT structure
is defined as:
// Provided by VK_EXT_attachment_feedback_loop_layout
typedef struct VkPhysicalDeviceAttachmentFeedbackLoopLayoutFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 attachmentFeedbackLoopLayout;
} VkPhysicalDeviceAttachmentFeedbackLoopLayoutFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
attachmentFeedbackLoopLayoutindicates whether the implementation supports usingVK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXTimage layout for images created withVK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT.
The VkPhysicalDeviceNestedCommandBufferFeaturesEXT structure is
defined as:
// Provided by VK_EXT_nested_command_buffer
typedef struct VkPhysicalDeviceNestedCommandBufferFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 nestedCommandBuffer;
VkBool32 nestedCommandBufferRendering;
VkBool32 nestedCommandBufferSimultaneousUse;
} VkPhysicalDeviceNestedCommandBufferFeaturesEXT;
This structure describes the following features:
-
nestedCommandBufferindicates the implementation supports nested command buffers, which allows Secondary Command Buffers to execute other Secondary Command Buffers. -
nestedCommandBufferRenderingindicates that it is valid to call vkCmdExecuteCommands inside a Secondary Command Buffer recorded withVK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT. -
nestedCommandBufferSimultaneousUseindicates that the implementation supports nested command buffers with command buffers that are recorded withVK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.
If the VkPhysicalDeviceNestedCommandBufferFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceNestedCommandBufferFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceGraphicsPipelineLibraryFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePipelineBinaryFeaturesKHR structure is defined as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPhysicalDevicePipelineBinaryFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 pipelineBinaries;
} VkPhysicalDevicePipelineBinaryFeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBinariesindicates that the implementation supports Pipeline Binaries.
If the VkPhysicalDevicePipelineBinaryFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePipelineBinaryFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
multisampledRenderToSingleSampledindicates that the implementation supports multisampled rendering to single-sampled render pass attachments.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMultisampledRenderToSingleSampledFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 a VkStructureType value identifying 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImage2DViewOf3DFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceImageSlicedViewOf3DFeaturesEXT structure is
defined as:
// Provided by VK_EXT_image_sliced_view_of_3d
typedef struct VkPhysicalDeviceImageSlicedViewOf3DFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 imageSlicedViewOf3D;
} VkPhysicalDeviceImageSlicedViewOf3DFeaturesEXT;
The members of the VkPhysicalDeviceImageSlicedViewOf3DFeaturesEXT
structure describe the following features:
-
imageSlicedViewOf3Dindicates that the implementation supports using a sliced view of a 3D image in a descriptor of typeVK_DESCRIPTOR_TYPE_STORAGE_IMAGEby using a VkImageViewSlicedCreateInfoEXT structure when creating the view.
If the VkPhysicalDeviceImageSlicedViewOf3DFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImageSlicedViewOf3DFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageCompressionControlindicates that the implementation supports providing controls for image compression at image creation time.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImageCompressionControlFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageCompressionControlSwapchainindicates that the implementation supports controlling image controls per swapchain and querying image compression properties per surface.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImageCompressionControlSwapchainFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRayTracingPositionFetchFeaturesKHR structure is
defined as:
// Provided by VK_KHR_ray_tracing_position_fetch
typedef struct VkPhysicalDeviceRayTracingPositionFetchFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 rayTracingPositionFetch;
} VkPhysicalDeviceRayTracingPositionFetchFeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rayTracingPositionFetchindicates that the implementation supports fetching the object space vertex positions of a hit triangle.
If the VkPhysicalDeviceRayTracingPositionFetchFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRayTracingPositionFetchFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderFloatControls2Features structure is defined
as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceShaderFloatControls2Features {
VkStructureType sType;
void* pNext;
VkBool32 shaderFloatControls2;
} VkPhysicalDeviceShaderFloatControls2Features;
or the equivalent
// Provided by VK_KHR_shader_float_controls2
typedef VkPhysicalDeviceShaderFloatControls2Features VkPhysicalDeviceShaderFloatControls2FeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceShaderFloatControls2Features 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderFloatControls2Features, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderEarlyAndLateFragmentTestsindicates whether the implementation supports theEarlyAndLateFragmentTestsAMDExecutionMode.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderEarlyAndLateFragmentTestsFeaturesAMD, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceAntiLagFeaturesAMD structure is defined as:
// Provided by VK_AMD_anti_lag
typedef struct VkPhysicalDeviceAntiLagFeaturesAMD {
VkStructureType sType;
void* pNext;
VkBool32 antiLag;
} VkPhysicalDeviceAntiLagFeaturesAMD;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
antiLagindicates whether the implementation supports AMD Radeon™ Anti-Lag functionality. TheantiLagfeature only supports a single GPU and must not be enabled if VkDeviceGroupDeviceCreateInfo::physicalDeviceCountis greater than 1.
If the VkPhysicalDeviceAntiLagFeaturesAMD 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceAntiLagFeaturesAMD, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nonSeamlessCubeMapindicates that the implementation supportsVK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT.
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceNonSeamlessCubeMapFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
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 feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderModuleIdentifierFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceTilePropertiesFeaturesQCOM structure is defined
as:
// Provided by VK_QCOM_tile_properties
typedef struct VkPhysicalDeviceTilePropertiesFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 tileProperties;
} VkPhysicalDeviceTilePropertiesFeaturesQCOM;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tilePropertiesindicates that the implementation supports queries for returning tile properties.
If the VkPhysicalDeviceTilePropertiesFeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceTilePropertiesFeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceImageProcessingFeaturesQCOM structure is defined
as:
// Provided by VK_QCOM_image_processing
typedef struct VkPhysicalDeviceImageProcessingFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 textureSampleWeighted;
VkBool32 textureBoxFilter;
VkBool32 textureBlockMatch;
} VkPhysicalDeviceImageProcessingFeaturesQCOM;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
textureSampleWeightedindicates that the implementation supports shader modules that declare theTextureSampleWeightedQCOMcapability. -
textureBoxFilterindicates that the implementation supports shader modules that declare theTextureBoxFilterQCOMcapability. -
textureBlockMatchindicates that the implementation supports shader modules that declare theTextureBlockMatchQCOMcapability.
If the VkPhysicalDeviceImageProcessingFeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImageProcessingFeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceImageProcessing2FeaturesQCOM structure is defined
as:
// Provided by VK_QCOM_image_processing2
typedef struct VkPhysicalDeviceImageProcessing2FeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 textureBlockMatch2;
} VkPhysicalDeviceImageProcessing2FeaturesQCOM;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
textureBlockMatch2indicates that the implementation supports shader modules that declare theTextureBlockMatch2QCOMcapability.
If the VkPhysicalDeviceImageProcessing2FeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImageProcessing2FeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDepthClampZeroOneFeaturesKHR structure is defined
as:
// Provided by VK_KHR_depth_clamp_zero_one
typedef struct VkPhysicalDeviceDepthClampZeroOneFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 depthClampZeroOne;
} VkPhysicalDeviceDepthClampZeroOneFeaturesKHR;
or the equivalent
// Provided by VK_EXT_depth_clamp_zero_one
typedef VkPhysicalDeviceDepthClampZeroOneFeaturesKHR VkPhysicalDeviceDepthClampZeroOneFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
depthClampZeroOneindicates that the implementation supports clamping the depth to a range of0to1.
If the VkPhysicalDeviceDepthClampZeroOneFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDepthClampZeroOneFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderTileImageFeaturesEXT structure is defined
as:
// Provided by VK_EXT_shader_tile_image
typedef struct VkPhysicalDeviceShaderTileImageFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 shaderTileImageColorReadAccess;
VkBool32 shaderTileImageDepthReadAccess;
VkBool32 shaderTileImageStencilReadAccess;
} VkPhysicalDeviceShaderTileImageFeaturesEXT;
The members of the VkPhysicalDeviceShaderTileImageFeaturesEXT
structure describe the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderTileImageColorReadAccessindicates that the implementation supports theTileImageColorReadAccessEXTSPIR-V capability. -
shaderTileImageDepthReadAccessindicates that the implementation supports theTileImageDepthReadAccessEXTSPIR-V capability. -
shaderTileImageStencilReadAccessindicates that the implementation supports theTileImageStencilReadAccessEXTSPIR-V capability.
If the VkPhysicalDeviceShaderTileImageFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderTileImageFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDepthBiasControlFeaturesEXT structure is defined
as:
// Provided by VK_EXT_depth_bias_control
typedef struct VkPhysicalDeviceDepthBiasControlFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 depthBiasControl;
VkBool32 leastRepresentableValueForceUnormRepresentation;
VkBool32 floatRepresentation;
VkBool32 depthBiasExact;
} VkPhysicalDeviceDepthBiasControlFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
depthBiasControlindicates whether the implementation supports thevkCmdSetDepthBias2EXTcommand and theVkDepthBiasRepresentationInfoEXTstructure. -
leastRepresentableValueForceUnormRepresentationindicates whether the implementation supports using theVK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXTdepth bias representation. -
floatRepresentationindicates whether the implementation supports using theVK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXTdepth bias representation. -
depthBiasExactindicates whether the implementation supports forcing depth bias to not be scaled to ensure a minimum resolvable difference usingVkDepthBiasRepresentationInfoEXT::depthBiasExact.
The VkPhysicalDeviceAddressBindingReportFeaturesEXT structure is
defined as:
// Provided by VK_EXT_device_address_binding_report
typedef struct VkPhysicalDeviceAddressBindingReportFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 reportAddressBinding;
} VkPhysicalDeviceAddressBindingReportFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
reportAddressBindingindicates whether this implementation supports reporting the binding of GPU virtual address ranges to Vulkan objects.
If the VkPhysicalDeviceAddressBindingReportFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceAddressBindingReportFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceOpticalFlowFeaturesNV structure is defined as:
// Provided by VK_NV_optical_flow
typedef struct VkPhysicalDeviceOpticalFlowFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 opticalFlow;
} VkPhysicalDeviceOpticalFlowFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
opticalFlowindicates whether the implementation supports optical flow.
If the VkPhysicalDeviceOpticalFlowFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceOpticalFlowFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceFaultFeaturesEXT structure is defined as:
// Provided by VK_EXT_device_fault
typedef struct VkPhysicalDeviceFaultFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 deviceFault;
VkBool32 deviceFaultVendorBinary;
} VkPhysicalDeviceFaultFeaturesEXT;
The members of the VkPhysicalDeviceFaultFeaturesEXT structure describe
the following features:
-
deviceFaultindicates that the implementation supports the reporting of device fault information. -
deviceFaultVendorBinaryindicates that the implementation supports the generation of vendor-specific binary crash dumps. These may provide additional information when imported into vendor-specific external tools.
If the VkPhysicalDeviceFaultFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFaultFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePipelineLibraryGroupHandlesFeaturesEXT structure
is defined as:
// Provided by VK_EXT_pipeline_library_group_handles
typedef struct VkPhysicalDevicePipelineLibraryGroupHandlesFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 pipelineLibraryGroupHandles;
} VkPhysicalDevicePipelineLibraryGroupHandlesFeaturesEXT;
This structure describes the following features:
If the VkPhysicalDevicePipelineLibraryGroupHandlesFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePipelineLibraryGroupHandlesFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderObjectFeaturesEXT structure is defined as:
// Provided by VK_EXT_shader_object
typedef struct VkPhysicalDeviceShaderObjectFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 shaderObject;
} VkPhysicalDeviceShaderObjectFeaturesEXT;
This structure describes the following feature:
-
shaderObjectindicates whether the implementation supports shader objects.
If the VkPhysicalDeviceShaderObjectFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderObjectFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceTensorFeaturesARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkPhysicalDeviceTensorFeaturesARM {
VkStructureType sType;
void* pNext;
VkBool32 tensorNonPacked;
VkBool32 shaderTensorAccess;
VkBool32 shaderStorageTensorArrayDynamicIndexing;
VkBool32 shaderStorageTensorArrayNonUniformIndexing;
VkBool32 descriptorBindingStorageTensorUpdateAfterBind;
VkBool32 tensors;
} VkPhysicalDeviceTensorFeaturesARM;
The members of the VkPhysicalDeviceTensorFeaturesARM structure
describe the following features:
-
tensorNonPackedindicates whether the implementation supports the creation of tensors that are not packed tensors. -
shaderTensorAccessindicates whether shader modules can declare theTensorsARMcapability. -
shaderStorageBufferArrayDynamicIndexingindicates whether arrays of storage tensors 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_TENSOR_ARMmust be indexed only by constant integral expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageTensorArrayDynamicIndexingARMcapability. -
shaderStorageTensorArrayNonUniformIndexingindicates whether arrays of storage tensors 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_TENSOR_ARMmust not be indexed by non-uniform integer expressions when aggregated into arrays in shader code. This also indicates whether shader modules can declare theStorageTensorArrayNonUniformIndexingARMcapability. -
descriptorBindingStorageTensorUpdateAfterBindindicates whether the implementation supports updating storage tensor 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_TENSOR_ARM. -
tensorsindicates whether the implementation supports tensor resources.
If the VkPhysicalDeviceTensorFeaturesARM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceTensorFeaturesARM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderCoreBuiltinsFeaturesARM structure is defined
as:
// Provided by VK_ARM_shader_core_builtins
typedef struct VkPhysicalDeviceShaderCoreBuiltinsFeaturesARM {
VkStructureType sType;
void* pNext;
VkBool32 shaderCoreBuiltins;
} VkPhysicalDeviceShaderCoreBuiltinsFeaturesARM;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderCoreBuiltinsindicates whether the implementation supports the SPIR-VCoreBuiltinsARMcapability.
If the VkPhysicalDeviceShaderCoreBuiltinsFeaturesARM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderCoreBuiltinsFeaturesARM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceFrameBoundaryFeaturesEXT structure is defined as:
// Provided by VK_EXT_frame_boundary
typedef struct VkPhysicalDeviceFrameBoundaryFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 frameBoundary;
} VkPhysicalDeviceFrameBoundaryFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
frameBoundaryindicates whether the implementation supports frame boundary information.
If the VkPhysicalDeviceFrameBoundaryFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFrameBoundaryFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceSwapchainMaintenance1FeaturesKHR structure is
defined as:
// Provided by VK_KHR_swapchain_maintenance1
typedef struct VkPhysicalDeviceSwapchainMaintenance1FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 swapchainMaintenance1;
} VkPhysicalDeviceSwapchainMaintenance1FeaturesKHR;
or the equivalent
// Provided by VK_EXT_swapchain_maintenance1
typedef VkPhysicalDeviceSwapchainMaintenance1FeaturesKHR VkPhysicalDeviceSwapchainMaintenance1FeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainMaintenance1indicates that the implementation supports the following:-
VkSwapchainPresentFenceInfoKHR, specifying a fence that is signaled when the resources associated with a present operation can be safely destroyed.
-
VkSwapchainPresentModesCreateInfoKHR and VkSwapchainPresentModeInfoKHR, allowing the swapchain to switch present modes without a need for recreation.
-
VkSwapchainPresentScalingCreateInfoKHR, specifying the scaling behavior of the swapchain in presence of window resizing.
-
The
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHRflag, allowing the implementation to defer the allocation of swapchain image memory until first acquisition. -
vkReleaseSwapchainImagesKHR, allowing acquired swapchain images to be released without presenting them.
-
If the VkPhysicalDeviceSwapchainMaintenance1FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceSwapchainMaintenance1FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePresentModeFifoLatestReadyFeaturesKHR structure is
defined as:
// Provided by VK_KHR_present_mode_fifo_latest_ready
typedef struct VkPhysicalDevicePresentModeFifoLatestReadyFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 presentModeFifoLatestReady;
} VkPhysicalDevicePresentModeFifoLatestReadyFeaturesKHR;
or the equivalent
// Provided by VK_EXT_present_mode_fifo_latest_ready
typedef VkPhysicalDevicePresentModeFifoLatestReadyFeaturesKHR VkPhysicalDevicePresentModeFifoLatestReadyFeaturesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentModeFifoLatestReadyspecifies whether the implementation supports theVK_PRESENT_MODE_FIFO_LATEST_READY_KHRpresent mode.
If the VkPhysicalDevicePresentModeFifoLatestReadyFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePresentModeFifoLatestReadyFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDynamicRenderingUnusedAttachmentsFeaturesEXT
structure is defined as:
// Provided by VK_EXT_dynamic_rendering_unused_attachments
typedef struct VkPhysicalDeviceDynamicRenderingUnusedAttachmentsFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 dynamicRenderingUnusedAttachments;
} VkPhysicalDeviceDynamicRenderingUnusedAttachmentsFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dynamicRenderingUnusedAttachmentsindicates that the implementation supports binding graphics pipelines within a render pass instance where any pipeline VkPipelineRenderingCreateInfo::pColorAttachmentFormatselement with a format other thanVK_FORMAT_UNDEFINEDis allowed with a corresponding VkRenderingInfo::pColorAttachmentselement with animageViewequal to VK_NULL_HANDLE, or any pipeline VkPipelineRenderingCreateInfo::pColorAttachmentFormatselement with aVK_FORMAT_UNDEFINEDformat is allowed with a corresponding VkRenderingInfo::pColorAttachmentselement with a non-VK_NULL_HANDLEimageView. Also a VkPipelineRenderingCreateInfo::depthAttachmentFormatother thanVK_FORMAT_UNDEFINEDis allowed with a VK_NULL_HANDLE VkRenderingInfo::pDepthAttachment, or a VkPipelineRenderingCreateInfo::depthAttachmentFormatofVK_FORMAT_UNDEFINEDis allowed with a non-VK_NULL_HANDLE VkRenderingInfo::pDepthAttachment. Also a VkPipelineRenderingCreateInfo::stencilAttachmentFormatother thanVK_FORMAT_UNDEFINEDis allowed with a VK_NULL_HANDLE VkRenderingInfo::pStencilAttachment, or a VkPipelineRenderingCreateInfo::stencilAttachmentFormatofVK_FORMAT_UNDEFINEDis allowed with a non-VK_NULL_HANDLE VkRenderingInfo::pStencilAttachment. Any writes to a VkRenderingInfo::pColorAttachments, VkRenderingInfo::pDepthAttachment, or VkRenderingInfo::pStencilAttachmentwith VK_NULL_HANDLE are discarded.
If the VkPhysicalDeviceDynamicRenderingUnusedAttachmentsFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDynamicRenderingUnusedAttachmentsFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRayTracingInvocationReorderFeaturesNV structure is
defined as:
// Provided by VK_NV_ray_tracing_invocation_reorder
typedef struct VkPhysicalDeviceRayTracingInvocationReorderFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 rayTracingInvocationReorder;
} VkPhysicalDeviceRayTracingInvocationReorderFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rayTracingInvocationReorderindicates that the implementation supportsSPV_NV_shader_invocation_reorder.
If the VkPhysicalDeviceRayTracingInvocationReorderFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRayTracingInvocationReorderFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceExtendedSparseAddressSpaceFeaturesNV structure is
defined as:
// Provided by VK_NV_extended_sparse_address_space
typedef struct VkPhysicalDeviceExtendedSparseAddressSpaceFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 extendedSparseAddressSpace;
} VkPhysicalDeviceExtendedSparseAddressSpaceFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
extendedSparseAddressSpaceindicates that the implementation supports allowing certain usages of sparse memory resources to exceedVkPhysicalDeviceLimits::sparseAddressSpaceSize. See VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV.
If the VkPhysicalDeviceExtendedSparseAddressSpaceFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceExtendedSparseAddressSpaceFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceMultiviewPerViewViewportsFeaturesQCOM structure is
defined as:
// Provided by VK_QCOM_multiview_per_view_viewports
typedef struct VkPhysicalDeviceMultiviewPerViewViewportsFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 multiviewPerViewViewports;
} VkPhysicalDeviceMultiviewPerViewViewportsFeaturesQCOM;
This structure describes the following features:
If the VkPhysicalDeviceMultiviewPerViewViewportsFeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMultiviewPerViewViewportsFeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceMultiviewPerViewRenderAreasFeaturesQCOM structure
is defined as:
// Provided by VK_QCOM_multiview_per_view_render_areas
typedef struct VkPhysicalDeviceMultiviewPerViewRenderAreasFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 multiviewPerViewRenderAreas;
} VkPhysicalDeviceMultiviewPerViewRenderAreasFeaturesQCOM;
This structure describes the following features:
If the VkPhysicalDeviceMultiviewPerViewRenderAreasFeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMultiviewPerViewRenderAreasFeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceClusterCullingShaderFeaturesHUAWEI structure is
defined as:
// Provided by VK_HUAWEI_cluster_culling_shader
typedef struct VkPhysicalDeviceClusterCullingShaderFeaturesHUAWEI {
VkStructureType sType;
void* pNext;
VkBool32 clustercullingShader;
VkBool32 multiviewClusterCullingShader;
} VkPhysicalDeviceClusterCullingShaderFeaturesHUAWEI;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
clustercullingShaderspecifies whether cluster culling shader is supported. -
multiviewClusterCullingShaderspecifies whether multiview is supported.
If the VkPhysicalDeviceClusterCullingShaderFeaturesHUAWEI 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceClusterCullingShaderFeaturesHUAWEI, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
To query whether a Cluster Culling Shader supports the per-cluster shading
rate feature, include a
VkPhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI structure in the
pNext chain of the
VkPhysicalDeviceClusterCullingShaderFeaturesHUAWEI structure.
This structure is defined as:
// Provided by VK_HUAWEI_cluster_culling_shader
typedef struct VkPhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI {
VkStructureType sType;
void* pNext;
VkBool32 clusterShadingRate;
} VkPhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
clusterShadingRatespecifies whether per-cluster shading rates is supported.
The VkPhysicalDeviceHdrVividFeaturesHUAWEI structure is defined as:
// Provided by VK_HUAWEI_hdr_vivid
typedef struct VkPhysicalDeviceHdrVividFeaturesHUAWEI {
VkStructureType sType;
void* pNext;
VkBool32 hdrVivid;
} VkPhysicalDeviceHdrVividFeaturesHUAWEI;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceHdrVividFeaturesHUAWEI 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceHdrVividFeaturesHUAWEI, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderEnqueueFeaturesAMDX structure is defined as:
// Provided by VK_AMDX_shader_enqueue
typedef struct VkPhysicalDeviceShaderEnqueueFeaturesAMDX {
VkStructureType sType;
void* pNext;
VkBool32 shaderEnqueue;
VkBool32 shaderMeshEnqueue;
} VkPhysicalDeviceShaderEnqueueFeaturesAMDX;
This structure describes the following feature:
-
shaderEnqueueindicates whether the implementation supports execution graphs. -
shaderMeshEnqueueindicates whether the implementation supports mesh nodes in execution graphs.
If the VkPhysicalDeviceShaderEnqueueFeaturesAMDX 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderEnqueueFeaturesAMDX, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceCubicClampFeaturesQCOM structure is defined as:
// Provided by VK_QCOM_filter_cubic_clamp
typedef struct VkPhysicalDeviceCubicClampFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 cubicRangeClamp;
} VkPhysicalDeviceCubicClampFeaturesQCOM;
This structure describes the following features:
-
cubicRangeClampindicates that the implementation supports cubic filtering in combination with a texel range clamp.
If the VkPhysicalDeviceCubicClampFeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCubicClampFeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceYcbcrDegammaFeaturesQCOM structure is defined as:
// Provided by VK_QCOM_ycbcr_degamma
typedef struct VkPhysicalDeviceYcbcrDegammaFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 ycbcrDegamma;
} VkPhysicalDeviceYcbcrDegammaFeaturesQCOM;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
ycbcrDegammaindicates whether the implementation supports Y′CBCR degamma.
If the VkPhysicalDeviceYcbcrDegammaFeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceYcbcrDegammaFeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceCubicWeightsFeaturesQCOM structure is defined as:
// Provided by VK_QCOM_filter_cubic_weights
typedef struct VkPhysicalDeviceCubicWeightsFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 selectableCubicWeights;
} VkPhysicalDeviceCubicWeightsFeaturesQCOM;
This structure describes the following feature:
If the VkPhysicalDeviceCubicWeightsFeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCubicWeightsFeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDescriptorPoolOverallocationFeaturesNV structure
is defined as:
// Provided by VK_NV_descriptor_pool_overallocation
typedef struct VkPhysicalDeviceDescriptorPoolOverallocationFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 descriptorPoolOverallocation;
} VkPhysicalDeviceDescriptorPoolOverallocationFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
descriptorPoolOverallocationindicates that the implementation allows the application to opt into descriptor pool overallocation by creating the descriptor pool withVK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_SETS_BIT_NVand/orVK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_POOLS_BIT_NVflags.
If the VkPhysicalDeviceDescriptorPoolOverallocationFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDescriptorPoolOverallocationFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePerStageDescriptorSetFeaturesNV structure is
defined as:
// Provided by VK_NV_per_stage_descriptor_set
typedef struct VkPhysicalDevicePerStageDescriptorSetFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 perStageDescriptorSet;
VkBool32 dynamicPipelineLayout;
} VkPhysicalDevicePerStageDescriptorSetFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
perStageDescriptorSetindicates that the implementation allows theVK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NVdescriptor set layout creation flag to be used so the bindings are specified per-stage rather than across all stages. -
dynamicPipelineLayoutindicates the implementation allows thelayoutmember of VkBindDescriptorSetsInfo, VkPushConstantsInfo, VkPushDescriptorSetInfo, VkPushDescriptorSetWithTemplateInfo, VkSetDescriptorBufferOffsetsInfoEXT and VkBindDescriptorBufferEmbeddedSamplersInfoEXT to be VK_NULL_HANDLE and VkPipelineLayoutCreateInfo can be chained off those structures'pNextinstead.
If the VkPhysicalDevicePerStageDescriptorSetFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePerStageDescriptorSetFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceCudaKernelLaunchFeaturesNV structure is defined
as:
// Provided by VK_NV_cuda_kernel_launch
typedef struct VkPhysicalDeviceCudaKernelLaunchFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 cudaKernelLaunchFeatures;
} VkPhysicalDeviceCudaKernelLaunchFeaturesNV;
This structure describes the following features:
If the VkPhysicalDeviceCudaKernelLaunchFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCudaKernelLaunchFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderMaximalReconvergenceFeaturesKHR structure is
defined as:
// Provided by VK_KHR_shader_maximal_reconvergence
typedef struct VkPhysicalDeviceShaderMaximalReconvergenceFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 shaderMaximalReconvergence;
} VkPhysicalDeviceShaderMaximalReconvergenceFeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderMaximalReconvergencespecifies whether the implementation supports the shader execution modeMaximallyReconvergesKHR
If the VkPhysicalDevicePrivateDataFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePrivateDataFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceExternalFormatResolveFeaturesANDROID structure is
defined as:
// Provided by VK_ANDROID_external_format_resolve
typedef struct VkPhysicalDeviceExternalFormatResolveFeaturesANDROID {
VkStructureType sType;
void* pNext;
VkBool32 externalFormatResolve;
} VkPhysicalDeviceExternalFormatResolveFeaturesANDROID;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalFormatResolvespecifies whether external format resolves are supported.
If the VkPhysicalDeviceExternalFormatResolveFeaturesANDROID 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceExternalFormatResolveFeaturesANDROID, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceTileShadingFeaturesQCOM structure is defined as:
// Provided by VK_QCOM_tile_shading
typedef struct VkPhysicalDeviceTileShadingFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 tileShading;
VkBool32 tileShadingFragmentStage;
VkBool32 tileShadingColorAttachments;
VkBool32 tileShadingDepthAttachments;
VkBool32 tileShadingStencilAttachments;
VkBool32 tileShadingInputAttachments;
VkBool32 tileShadingSampledAttachments;
VkBool32 tileShadingPerTileDraw;
VkBool32 tileShadingPerTileDispatch;
VkBool32 tileShadingDispatchTile;
VkBool32 tileShadingApron;
VkBool32 tileShadingAnisotropicApron;
VkBool32 tileShadingAtomicOps;
VkBool32 tileShadingImageProcessing;
} VkPhysicalDeviceTileShadingFeaturesQCOM;
This structure describes the following features:
-
tileShadingindicates that the implementation supports tile shading render pass instances. -
tileShadingFragmentStageindicates that the implementation supports tile shading in the fragment stage. -
tileShadingColorAttachmentsindicates that the implementation supports access to color attachments in a tile shader. -
tileShadingDepthAttachmentsindicates that the implementation supports access to depth aspect of depth stencil attachments. -
tileShadingStencilAttachmentsindicates that the implementation supports access to stencil aspect of depth stencil attachments. -
tileShadingInputAttachmentsindicates that the implementation supports access to input attachments. -
tileShadingSampledAttachmentsindicates that the implementation supports access to sampling of tile attachments. -
tileShadingPerTileDrawindicates that the implementation supports the recording of vkCmdDraw* commands when per-tile execution model is enabled. -
tileShadingPerTileDispatchindicates that the implementation supports the recording ofvkCmdDispatch* commands within those regions of a command buffer where the per-tile execution model is enabled. -
tileShadingDispatchTileindicates that the implementation supports the recording of vkCmdDispatchTileQCOM commands. -
tileShadingApronindicates that the implementation supports VkRenderPassTileShadingCreateInfoQCOM::apronSizevalue other than (0,0). See Tiling Aprons for more information. -
tileShadingAnisotropicApronindicates that the implementation supports VkRenderPassTileShadingCreateInfoQCOM::apronSizeset to a value whereapronSize::widthdiffers fromapronSize::height. -
tileShadingAtomicOpsindicates that the implementation supports atomic operations on tile attachment variables. -
tileShadingImageProcessingindicates that the implementation supports image processing operations with tile attachments.
If the VkPhysicalDeviceTileShadingFeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceTileShadingFeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceSchedulingControlsFeaturesARM structure is defined
as:
// Provided by VK_ARM_scheduling_controls
typedef struct VkPhysicalDeviceSchedulingControlsFeaturesARM {
VkStructureType sType;
void* pNext;
VkBool32 schedulingControls;
} VkPhysicalDeviceSchedulingControlsFeaturesARM;
This structure describes the following features:
If the VkPhysicalDeviceSchedulingControlsFeaturesARM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceSchedulingControlsFeaturesARM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRelaxedLineRasterizationFeaturesIMG structure is
defined as:
// Provided by VK_IMG_relaxed_line_rasterization
typedef struct VkPhysicalDeviceRelaxedLineRasterizationFeaturesIMG {
VkStructureType sType;
void* pNext;
VkBool32 relaxedLineRasterization;
} VkPhysicalDeviceRelaxedLineRasterizationFeaturesIMG;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
relaxedLineRasterizationindicates that the implementation supports relaxed line rasterization control.
If the VkPhysicalDeviceRelaxedLineRasterizationFeaturesIMG 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRelaxedLineRasterizationFeaturesIMG, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRenderPassStripedFeaturesARM structure is defined
as:
// Provided by VK_ARM_render_pass_striped
typedef struct VkPhysicalDeviceRenderPassStripedFeaturesARM {
VkStructureType sType;
void* pNext;
VkBool32 renderPassStriped;
} VkPhysicalDeviceRenderPassStripedFeaturesARM;
The members of the VkPhysicalDeviceRenderPassStripedFeaturesARM
structure describe the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
renderPassStripedindicates that striped rendering is supported by the implementation.
If the VkPhysicalDeviceRenderPassStripedFeaturesARM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRenderPassStripedFeaturesARM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderSubgroupRotateFeatures structure is defined
as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceShaderSubgroupRotateFeatures {
VkStructureType sType;
void* pNext;
VkBool32 shaderSubgroupRotate;
VkBool32 shaderSubgroupRotateClustered;
} VkPhysicalDeviceShaderSubgroupRotateFeatures;
or the equivalent
// Provided by VK_KHR_shader_subgroup_rotate
typedef VkPhysicalDeviceShaderSubgroupRotateFeatures VkPhysicalDeviceShaderSubgroupRotateFeaturesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceShaderSubgroupRotateFeatures 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderSubgroupRotateFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderExpectAssumeFeatures structure is defined
as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceShaderExpectAssumeFeatures {
VkStructureType sType;
void* pNext;
VkBool32 shaderExpectAssume;
} VkPhysicalDeviceShaderExpectAssumeFeatures;
or the equivalent
// Provided by VK_KHR_shader_expect_assume
typedef VkPhysicalDeviceShaderExpectAssumeFeatures VkPhysicalDeviceShaderExpectAssumeFeaturesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceShaderExpectAssumeFeatures 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderExpectAssumeFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDynamicRenderingLocalReadFeatures structure is
defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceDynamicRenderingLocalReadFeatures {
VkStructureType sType;
void* pNext;
VkBool32 dynamicRenderingLocalRead;
} VkPhysicalDeviceDynamicRenderingLocalReadFeatures;
or the equivalent
// Provided by VK_KHR_dynamic_rendering_local_read
typedef VkPhysicalDeviceDynamicRenderingLocalReadFeatures VkPhysicalDeviceDynamicRenderingLocalReadFeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
dynamicRenderingLocalReadspecifies that the implementation supports local reads inside dynamic render pass instances using the vkCmdBeginRendering command.
If the VkPhysicalDeviceDynamicRenderingLocalReadFeatures 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDynamicRenderingLocalReadFeatures, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderQuadControlFeaturesKHR structure is defined
as:
// Provided by VK_KHR_shader_quad_control
typedef struct VkPhysicalDeviceShaderQuadControlFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 shaderQuadControl;
} VkPhysicalDeviceShaderQuadControlFeaturesKHR;
This structure describes the following features:
If the VkPhysicalDeviceShaderQuadControlFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderQuadControlFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderBfloat16FeaturesKHR structure is defined as:
// Provided by VK_KHR_shader_bfloat16
typedef struct VkPhysicalDeviceShaderBfloat16FeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 shaderBFloat16Type;
VkBool32 shaderBFloat16DotProduct;
VkBool32 shaderBFloat16CooperativeMatrix;
} VkPhysicalDeviceShaderBfloat16FeaturesKHR;
This structure describes the following features:
-
shaderBFloat16Typeindicates whether the implementation supports shaders with theBFloat16TypeKHRcapability. -
shaderBFloat16DotProductindicates whether the implementation supports shaders with theBFloat16DotProductKHRcapability. -
shaderBFloat16CooperativeMatrixindicates whether the implementation supports shaders with theBFloat16CooperativeMatrixKHRcapability.
If the VkPhysicalDeviceShaderBfloat16FeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderBfloat16FeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceMapMemoryPlacedFeaturesEXT structure is defined
as:
// Provided by VK_EXT_map_memory_placed
typedef struct VkPhysicalDeviceMapMemoryPlacedFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 memoryMapPlaced;
VkBool32 memoryMapRangePlaced;
VkBool32 memoryUnmapReserve;
} VkPhysicalDeviceMapMemoryPlacedFeaturesEXT;
This structure describes the following features:
-
memoryMapPlacedindicates that the implementation supports placing memory maps at application-specified virtual addresses. -
memoryMapRangePlacedindicates that the implementation supports placing memory maps of a subrange of a memory object at application-specified virtual addresses. -
memoryUnmapReserveindicates that the implementation supports leaving the memory range reserved when unmapping a memory object.
If the VkPhysicalDeviceMapMemoryPlacedFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceMapMemoryPlacedFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderAtomicFloat16VectorFeaturesNV structure is defined as:
// Provided by VK_NV_shader_atomic_float16_vector
typedef struct VkPhysicalDeviceShaderAtomicFloat16VectorFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 shaderFloat16VectorAtomics;
} VkPhysicalDeviceShaderAtomicFloat16VectorFeaturesNV;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDeviceShaderAtomicFloat16VectorFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderAtomicFloat16VectorFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePipelineOpacityMicromapFeaturesARM structure is defined as:
// Provided by VK_ARM_pipeline_opacity_micromap
typedef struct VkPhysicalDevicePipelineOpacityMicromapFeaturesARM {
VkStructureType sType;
void* pNext;
VkBool32 pipelineOpacityMicromap;
} VkPhysicalDevicePipelineOpacityMicromapFeaturesARM;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDevicePipelineOpacityMicromapFeaturesARM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePipelineOpacityMicromapFeaturesARM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceRawAccessChainsFeaturesNV structure is defined as:
// Provided by VK_NV_raw_access_chains
typedef struct VkPhysicalDeviceRawAccessChainsFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 shaderRawAccessChains;
} VkPhysicalDeviceRawAccessChainsFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderRawAccessChainsspecifies whether shader modules can declare theRawAccessChainsNVcapability.
If the VkPhysicalDeviceRawAccessChainsFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceRawAccessChainsFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceCommandBufferInheritanceFeaturesNV structure is
defined as:
// Provided by VK_NV_command_buffer_inheritance
typedef struct VkPhysicalDeviceCommandBufferInheritanceFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 commandBufferInheritance;
} VkPhysicalDeviceCommandBufferInheritanceFeaturesNV;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
commandBufferInheritanceindicates that command buffers executed in a queue inherit graphics and compute state from the previously executed command buffer in that queue.
If the VkPhysicalDeviceCommandBufferInheritanceFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceCommandBufferInheritanceFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceImageAlignmentControlFeaturesMESA structure is
defined as:
// Provided by VK_MESA_image_alignment_control
typedef struct VkPhysicalDeviceImageAlignmentControlFeaturesMESA {
VkStructureType sType;
void* pNext;
VkBool32 imageAlignmentControl;
} VkPhysicalDeviceImageAlignmentControlFeaturesMESA;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageAlignmentControlspecifies that VkImageAlignmentControlCreateInfoMESA can be chained in VkImageCreateInfo
If the VkPhysicalDeviceImageAlignmentControlFeaturesMESA 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceImageAlignmentControlFeaturesMESA, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderReplicatedCompositesFeaturesEXT structure is
defined as:
// Provided by VK_EXT_shader_replicated_composites
typedef struct VkPhysicalDeviceShaderReplicatedCompositesFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 shaderReplicatedComposites;
} VkPhysicalDeviceShaderReplicatedCompositesFeaturesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderReplicatedCompositesspecifies whether shader modules can declare theReplicatedCompositesEXTcapability.
If the VkPhysicalDeviceShaderReplicatedCompositesFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderReplicatedCompositesFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderRelaxedExtendedInstructionFeaturesKHR
structure is defined as:
// Provided by VK_KHR_shader_relaxed_extended_instruction
typedef struct VkPhysicalDeviceShaderRelaxedExtendedInstructionFeaturesKHR {
VkStructureType sType;
void* pNext;
VkBool32 shaderRelaxedExtendedInstruction;
} VkPhysicalDeviceShaderRelaxedExtendedInstructionFeaturesKHR;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderRelaxedExtendedInstructionspecifies whether the implementation supports SPIR-V modules that use theSPV_KHR_relaxed_extended_instructionextension.
If the VkPhysicalDeviceShaderRelaxedExtendedInstructionFeaturesKHR 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderRelaxedExtendedInstructionFeaturesKHR, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceVertexAttributeRobustnessFeaturesEXT structure is
defined as:
// Provided by VK_EXT_vertex_attribute_robustness
typedef struct VkPhysicalDeviceVertexAttributeRobustnessFeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 vertexAttributeRobustness;
} VkPhysicalDeviceVertexAttributeRobustnessFeaturesEXT;
This structure describes the following feature:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexAttributeRobustnessindicates that vertex shaders can read vertex attribute locations that have no vertex attribute description and the value returned is (0,0,0,0) or (0,0,0,1).
If the VkPhysicalDeviceVertexAttributeRobustnessFeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceVertexAttributeRobustnessFeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceTileMemoryHeapFeaturesQCOM structure is defined
as:
// Provided by VK_QCOM_tile_memory_heap
typedef struct VkPhysicalDeviceTileMemoryHeapFeaturesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 tileMemoryHeap;
} VkPhysicalDeviceTileMemoryHeapFeaturesQCOM;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tileMemoryHeapindicates whether the implementation supports tile memory heap functionality.
If the VkPhysicalDeviceTileMemoryHeapFeaturesQCOM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceTileMemoryHeapFeaturesQCOM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDevicePresentMeteringFeaturesNV structure is defined as:
// Provided by VK_NV_present_metering
typedef struct VkPhysicalDevicePresentMeteringFeaturesNV {
VkStructureType sType;
void* pNext;
VkBool32 presentMetering;
} VkPhysicalDevicePresentMeteringFeaturesNV;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
presentMeteringindicates whether the implementation supports present metering capability.
If the VkPhysicalDevicePresentMeteringFeaturesNV 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDevicePresentMeteringFeaturesNV, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceFormatPackFeaturesARM structure is defined as:
// Provided by VK_ARM_format_pack
typedef struct VkPhysicalDeviceFormatPackFeaturesARM {
VkStructureType sType;
void* pNext;
VkBool32 formatPack;
} VkPhysicalDeviceFormatPackFeaturesARM;
This structure describes the following feature:
-
formatPackindicates that the implementation must support using a VkFormat ofVK_FORMAT_R10X6_UINT_PACK16_ARM,VK_FORMAT_R10X6G10X6_UINT_2PACK16_ARM,VK_FORMAT_R10X6G10X6B10X6A10X6_UINT_4PACK16_ARM,VK_FORMAT_R12X4_UINT_PACK16_ARM,VK_FORMAT_R12X4G12X4_UINT_2PACK16_ARM,VK_FORMAT_R12X4G12X4B12X4A12X4_UINT_4PACK16_ARM,VK_FORMAT_R14X2_UINT_PACK16_ARM,VK_FORMAT_R14X2G14X2_UINT_2PACK16_ARM, andVK_FORMAT_R14X2G14X2B14X2A14X2_UINT_4PACK16_ARM, with at least the following VkFormatFeatureFlagBits:-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT -
VK_FORMAT_FEATURE_TRANSFER_SRC_BIT -
VK_FORMAT_FEATURE_TRANSFER_DST_BIT
-
If the VkPhysicalDeviceFormatPackFeaturesARM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceFormatPackFeaturesARM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceDataGraphFeaturesARM structure is defined as:
// Provided by VK_ARM_data_graph
typedef struct VkPhysicalDeviceDataGraphFeaturesARM {
VkStructureType sType;
void* pNext;
VkBool32 dataGraph;
VkBool32 dataGraphUpdateAfterBind;
VkBool32 dataGraphSpecializationConstants;
VkBool32 dataGraphDescriptorBuffer;
VkBool32 dataGraphShaderModule;
} VkPhysicalDeviceDataGraphFeaturesARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dataGraphspecifies whether data graph pipelines can be used. -
dataGraphUpdateAfterBindspecifies whether data graph pipelines can be created with a VkPipelineLayout that uses one or more VkDescriptorSetLayout objects created with theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
dataGraphSpecializationConstantsspecifies whether data graph pipelines can be created from shader modules that use specialization constants. -
dataGraphDescriptorBufferspecifies whether data graph pipelines can use descriptor buffers. -
dataGraphShaderModulespecifies whether data graph pipelines can be created from a shader module.
If the VkPhysicalDeviceDataGraphFeaturesARM 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceDataGraphFeaturesARM, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceShaderFloat8FeaturesEXT structure is defined as:
// Provided by VK_EXT_shader_float8
typedef struct VkPhysicalDeviceShaderFloat8FeaturesEXT {
VkStructureType sType;
void* pNext;
VkBool32 shaderFloat8;
VkBool32 shaderFloat8CooperativeMatrix;
} VkPhysicalDeviceShaderFloat8FeaturesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderFloat8indicates whether the implementation supports shaders with theFloat8EXTcapability. -
shaderFloat8indicates whether the implementation supports shaders with theFloat8CooperativeMatrixEXTcapability.
If the VkPhysicalDeviceShaderFloat8FeaturesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceShaderFloat8FeaturesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
49.1. Feature Requirements
All Vulkan graphics implementations must support the following features:
-
If Vulkan 1.0 is supported,
robustBufferAccessmust be supported ifVK_KHR_portability_subsetis not advertised -
If Vulkan 1.1 is supported, the following features must be supported:
-
storageBuffer16BitAccessifuniformAndStorageBuffer16BitAccessis supported -
shaderDrawParametersifVK_KHR_shader_draw_parametersis supported
-
-
If Vulkan 1.2 is supported, the following features must be supported:
-
samplerMirrorClampToEdgeifVK_KHR_sampler_mirror_clamp_to_edgeis supported -
drawIndirectCountifVK_KHR_draw_indirect_countis supported -
storageBuffer8BitAccessifuniformAndStorageBuffer8BitAccessis supported -
shaderInt64ifshaderSharedInt64AtomicsorshaderBufferInt64Atomicsare supported -
descriptorIndexingifVK_EXT_descriptor_indexingis supported -
shaderSampledImageArrayDynamicIndexingifdescriptorIndexingis supported -
shaderStorageBufferArrayDynamicIndexingifdescriptorIndexingis supported -
shaderUniformTexelBufferArrayDynamicIndexingifdescriptorIndexingis supported -
shaderStorageTexelBufferArrayDynamicIndexingifdescriptorIndexingis supported -
shaderSampledImageArrayNonUniformIndexingifdescriptorIndexingis supported -
shaderStorageBufferArrayNonUniformIndexingifdescriptorIndexingis supported -
shaderUniformTexelBufferArrayNonUniformIndexingifdescriptorIndexingis supported -
descriptorBindingSampledImageUpdateAfterBindifdescriptorIndexingis supported -
descriptorBindingStorageImageUpdateAfterBindifdescriptorIndexingis supported -
descriptorBindingStorageBufferUpdateAfterBindifdescriptorIndexingis supported -
descriptorBindingUniformTexelBufferUpdateAfterBindifdescriptorIndexingis supported -
descriptorBindingStorageTexelBufferUpdateAfterBindifdescriptorIndexingis supported -
descriptorBindingUpdateUnusedWhilePendingifdescriptorIndexingis supported -
descriptorBindingPartiallyBoundifdescriptorIndexingis supported -
runtimeDescriptorArrayifdescriptorIndexingis supported -
shaderOutputViewportIndexifVK_EXT_shader_viewport_index_layeris supported -
shaderOutputLayerifVK_EXT_shader_viewport_index_layeris supported -
samplerFilterMinmaxifVK_EXT_sampler_filter_minmaxis supported
-
If Vulkan 1.3 is supported, the following features must be supported:
-
If Vulkan 1.4 is supported, the following features must be supported:
-
pipelineProtectedAccessifprotectedMemoryis supported
-
If
VK_KHR_dynamic_renderingis supported,dynamicRenderingmust be supported -
If
VK_KHR_multiviewis supported,multiviewmust be supported -
If
VK_KHR_shader_float16_int8is supported, at least one ofshaderFloat16orshaderInt8must be supported -
If
VK_KHR_16bit_storageis supported,storageBuffer16BitAccessmust be supported -
If
VK_KHR_imageless_framebufferis supported,imagelessFramebuffermust be supported -
If
VK_KHR_performance_queryis supported,performanceCounterQueryPoolsmust be supported -
If
VK_KHR_variable_pointersis supported,variablePointersStorageBuffermust be supported -
If
VK_KHR_shader_bfloat16is supported, the following features must be supported:-
at least one of
shaderBFloat16CooperativeMatrixorshaderBFloat16DotProduct
-
If
VK_KHR_sampler_ycbcr_conversionis supported,samplerYcbcrConversionmust be supported -
If
VK_KHR_shader_subgroup_extended_typesis supported,shaderSubgroupExtendedTypesmust be supported -
If
VK_KHR_8bit_storageis supported,storageBuffer8BitAccessmust be supported -
If
VK_KHR_shader_atomic_int64is supported,shaderBufferInt64Atomicsmust be supported -
If
VK_KHR_shader_clockis supported,shaderSubgroupClockmust be supported -
If
VK_KHR_global_priorityis supported,globalPriorityQuerymust be supported -
If
VK_KHR_timeline_semaphoreis supported,timelineSemaphoremust be supported -
If
VK_KHR_vulkan_memory_modelis supported,vulkanMemoryModelmust be supported -
If
VK_KHR_shader_terminate_invocationis supported,shaderTerminateInvocationmust be supported -
If
VK_KHR_fragment_shading_rateis supported,pipelineFragmentShadingRatemust be supported -
If
VK_KHR_dynamic_rendering_local_readis supported,dynamicRenderingLocalReadmust be supported -
If
VK_KHR_shader_quad_controlis supported,shaderQuadControlmust be supported -
If
VK_KHR_separate_depth_stencil_layoutsis supported,separateDepthStencilLayoutsmust be supported -
If
VK_KHR_present_waitis supported,presentWaitmust be supported -
If
VK_KHR_uniform_buffer_standard_layoutis supported,uniformBufferStandardLayoutmust be supported -
If
VK_KHR_buffer_device_addressis supported,bufferDeviceAddressmust be supported -
If
VK_KHR_pipeline_executable_propertiesis supported,pipelineExecutableInfomust be supported -
If
VK_KHR_shader_integer_dot_productis supported,shaderIntegerDotProductmust be supported -
If
VK_KHR_present_idis supported,presentIdmust be supported -
If
VK_KHR_synchronization2is supported,synchronization2must be supported -
If
VK_KHR_fragment_shader_barycentricis supported,fragmentShaderBarycentricmust be supported -
If
VK_KHR_shader_subgroup_uniform_control_flowis supported,shaderSubgroupUniformControlFlowmust be supported -
If
VK_KHR_zero_initialize_workgroup_memoryis supported,shaderZeroInitializeWorkgroupMemorymust be supported -
If
VK_KHR_workgroup_memory_explicit_layoutis supported,workgroupMemoryExplicitLayoutmust be supported -
If
VK_KHR_ray_tracing_maintenance1is supported,rayTracingMaintenance1must be supported -
If
VK_KHR_maintenance4is supported,maintenance4must be supported -
If
VK_KHR_shader_subgroup_rotateis supported,shaderSubgroupRotatemust be supported -
If
VK_KHR_shader_maximal_reconvergenceis supported,shaderMaximalReconvergencemust be supported -
If
VK_KHR_maintenance5is supported,maintenance5must be supported -
If
VK_KHR_present_id2is supported,presentId2must be supported -
If
VK_KHR_present_wait2is supported,presentWait2must be supported -
If
VK_KHR_ray_tracing_position_fetchis supported,rayTracingPositionFetchmust be supported -
If
VK_KHR_pipeline_binaryis supported,pipelineBinariesmust be supported -
If
VK_KHR_swapchain_maintenance1is supported,swapchainMaintenance1must be supported -
If
VK_KHR_cooperative_matrixis supported,cooperativeMatrixmust be supported -
If
VK_KHR_compute_shader_derivativesis supported,computeDerivativeGroupLinearmust be supported -
If
VK_KHR_video_encode_av1is supported,videoEncodeAV1must be supported -
If
VK_KHR_video_decode_vp9is supported,videoDecodeVP9must be supported -
If
VK_KHR_video_maintenance1is supported,videoMaintenance1must be supported -
If
VK_KHR_vertex_attribute_divisoris supported,vertexAttributeInstanceRateDivisormust be supported -
If
VK_KHR_unified_image_layoutsis supported,unifiedImageLayoutsmust be supported -
If
VK_KHR_shader_float_controls2is supported,shaderFloatControls2must be supported -
If
VK_KHR_index_type_uint8is supported,indexTypeUint8must be supported -
If
VK_KHR_line_rasterizationis supported, at least one ofrectangularLines,bresenhamLines,smoothLines,stippledRectangularLines,stippledBresenhamLines, orstippledSmoothLinesmust be supported -
If
VK_KHR_shader_expect_assumeis supported,shaderExpectAssumemust be supported -
If
VK_KHR_maintenance6is supported,maintenance6must be supported -
If
VK_KHR_video_encode_intra_refreshis supported,videoEncodeIntraRefreshmust be supported -
If
VK_KHR_video_encode_quantization_mapis supported,videoEncodeQuantizationMapmust be supported -
If
VK_KHR_shader_relaxed_extended_instructionis supported,shaderRelaxedExtendedInstructionmust be supported -
If
VK_KHR_maintenance7is supported,maintenance7must be supported -
If
VK_KHR_maintenance8is supported,maintenance8must be supported -
If
VK_KHR_maintenance9is supported,maintenance9must be supported -
If
VK_KHR_video_maintenance2is supported,videoMaintenance2must be supported -
If
VK_KHR_depth_clamp_zero_oneis supported,depthClampZeroOnemust be supported -
If
VK_KHR_robustness2is supported, at least one ofrobustBufferAccess2,robustImageAccess2, ornullDescriptormust be supported -
If
VK_KHR_present_mode_fifo_latest_readyis supported,presentModeFifoLatestReadymust be supported -
If
VK_EXT_transform_feedbackis supported,transformFeedbackmust be supported -
If
VK_NV_corner_sampled_imageis supported,cornerSampledImagemust be supported -
If
VK_EXT_texture_compression_astc_hdris supported,textureCompressionASTC_HDRmust be supported -
If
VK_EXT_pipeline_robustnessis supported,pipelineRobustnessmust be supported -
If
VK_EXT_conditional_renderingis supported,conditionalRenderingmust be supported -
If
VK_EXT_depth_clip_enableis supported,depthClipEnablemust be supported -
If
VK_IMG_relaxed_line_rasterizationis supported,relaxedLineRasterizationmust be supported -
If
VK_AMDX_shader_enqueueis supported, the following features must be supported:-
shaderMeshEnqueueifVK_EXT_mesh_shaderis supported
-
If
VK_EXT_inline_uniform_blockis supported, the following features must be supported:-
descriptorBindingInlineUniformBlockUpdateAfterBindifVK_EXT_descriptor_indexingis supported, or if Vulkan 1.2 anddescriptorIndexingare supported
-
If
VK_NV_shader_sm_builtinsis supported,shaderSMBuiltinsmust be supported -
If
VK_EXT_descriptor_indexingis supported, the following features must be supported: -
If
VK_NV_shading_rate_imageis supported,shadingRateImagemust be supported -
If
VK_NV_representative_fragment_testis supported,representativeFragmentTestmust be supported -
If
VK_EXT_vertex_attribute_divisoris supported,vertexAttributeInstanceRateDivisormust be supported -
If
VK_NV_compute_shader_derivativesis supported, at least one ofcomputeDerivativeGroupQuadsorcomputeDerivativeGroupLinearmust be supported -
If
VK_NV_mesh_shaderis supported,VkPhysicalDeviceMeshShaderFeaturesNV::meshShadermust be supported -
If
VK_NV_shader_image_footprintis supported,imageFootprintmust be supported -
If
VK_NV_scissor_exclusiveis supported,exclusiveScissormust be supported -
If
VK_INTEL_shader_integer_functions2is supported,shaderIntegerFunctions2must be supported -
If
VK_EXT_fragment_density_mapis supported,fragmentDensityMapmust be supported -
If
VK_EXT_scalar_block_layoutis supported,scalarBlockLayoutmust be supported -
If
VK_EXT_subgroup_size_controlis supported, the following features must be supported: -
If
VK_AMD_device_coherent_memoryis supported,deviceCoherentMemorymust be supported -
If
VK_EXT_shader_image_atomic_int64is supported, the following features must be supported: -
If
VK_EXT_memory_priorityis supported,memoryPrioritymust be supported -
If
VK_NV_dedicated_allocation_image_aliasingis supported,dedicatedAllocationImageAliasingmust be supported -
If
VK_EXT_buffer_device_addressis supported,VkPhysicalDeviceBufferDeviceAddressFeaturesEXT::bufferDeviceAddressmust be supported -
If
VK_NV_cooperative_matrixis supported,VkPhysicalDeviceCooperativeMatrixFeaturesNV::cooperativeMatrixmust be supported -
If
VK_NV_coverage_reduction_modeis supported,coverageReductionModemust be supported -
If
VK_EXT_fragment_shader_interlockis supported, at least one offragmentShaderSampleInterlock,fragmentShaderPixelInterlock, orfragmentShaderShadingRateInterlockmust be supported -
If
VK_EXT_ycbcr_image_arraysis supported,ycbcrImageArraysmust be supported -
If
VK_EXT_provoking_vertexis supported,provokingVertexLastmust be supported -
If
VK_EXT_line_rasterizationis supported, at least one ofrectangularLines,bresenhamLines,smoothLines,stippledRectangularLines,stippledBresenhamLines, orstippledSmoothLinesmust be supported -
If
VK_EXT_shader_atomic_floatis supported, the following features must be supported:-
at least one of
shaderBufferFloat32Atomics,shaderBufferFloat32AtomicAdd,shaderBufferFloat64Atomics,shaderBufferFloat64AtomicAdd,shaderSharedFloat32Atomics,shaderSharedFloat32AtomicAdd,shaderSharedFloat64Atomics,shaderSharedFloat64AtomicAdd,shaderImageFloat32Atomics, orshaderImageFloat32AtomicAdd -
shaderImageFloat32AtomicsifsparseImageFloat32Atomicsis supported -
shaderImageFloat32AtomicAddifsparseImageFloat32AtomicAddis supported
-
-
If
VK_EXT_host_query_resetis supported,hostQueryResetmust be supported -
If
VK_EXT_index_type_uint8is supported,indexTypeUint8must be supported -
If
VK_EXT_extended_dynamic_stateis supported,extendedDynamicStatemust be supported -
If
VK_EXT_host_image_copyis supported,hostImageCopymust be supported -
If
VK_EXT_map_memory_placedis supported,memoryMapPlacedmust be supported -
If
VK_EXT_shader_atomic_float2is supported, the following features must be supported:-
at least one of
shaderBufferFloat16Atomics,shaderBufferFloat16AtomicAdd,shaderBufferFloat16AtomicMinMax,shaderBufferFloat32AtomicMinMax,shaderBufferFloat64AtomicMinMax,shaderSharedFloat16Atomics,shaderSharedFloat16AtomicAdd,shaderSharedFloat16AtomicMinMax,shaderSharedFloat32AtomicMinMax,shaderSharedFloat64AtomicMinMax, orshaderImageFloat32AtomicMinMax -
shaderImageFloat32AtomicMinMaxifsparseImageFloat32AtomicMinMaxis supported
-
-
If
VK_EXT_swapchain_maintenance1is supported,swapchainMaintenance1must be supported -
If
VK_EXT_shader_demote_to_helper_invocationis supported,shaderDemoteToHelperInvocationmust be supported -
If
VK_NV_device_generated_commandsis supported,VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::deviceGeneratedCommandsmust be supported -
If
VK_NV_inherited_viewport_scissoris supported,inheritedViewportScissor2Dmust be supported -
If
VK_EXT_texel_buffer_alignmentis supported,texelBufferAlignmentmust be supported -
If
VK_EXT_depth_bias_controlis supported,depthBiasControlmust be supported -
If
VK_EXT_device_memory_reportis supported,deviceMemoryReportmust be supported -
If
VK_EXT_robustness2is supported, at least one ofrobustBufferAccess2,robustImageAccess2, ornullDescriptormust be supported -
If
VK_EXT_custom_border_coloris supported,customBorderColorsmust be supported -
If
VK_NV_present_barrieris supported,presentBarriermust be supported -
If
VK_EXT_private_datais supported,privateDatamust be supported -
If
VK_EXT_pipeline_creation_cache_controlis supported,pipelineCreationCacheControlmust be supported -
If
VK_NV_device_diagnostics_configis supported,diagnosticsConfigmust be supported -
If
VK_NV_cuda_kernel_launchis supported,cudaKernelLaunchFeaturesmust be supported -
If
VK_QCOM_tile_shadingis supported, the following features must be supported: -
If
VK_EXT_descriptor_bufferis supported,descriptorBuffermust be supported -
If
VK_EXT_graphics_pipeline_libraryis supported,graphicsPipelineLibrarymust be supported -
If
VK_AMD_shader_early_and_late_fragment_testsis supported,shaderEarlyAndLateFragmentTestsmust be supported -
If
VK_NV_fragment_shading_rate_enumsis supported,fragmentShadingRateEnumsmust be supported -
If
VK_NV_ray_tracing_motion_bluris supported,rayTracingMotionBlurmust be supported -
If
VK_EXT_ycbcr_2plane_444_formatsis supported,ycbcr2plane444Formatsmust be supported -
If
VK_EXT_fragment_density_map2is supported,fragmentDensityMapDeferredmust be supported -
If
VK_EXT_image_robustnessis supported,robustImageAccessmust be supported -
If
VK_EXT_image_compression_controlis supported,imageCompressionControlmust be supported -
If
VK_EXT_attachment_feedback_loop_layoutis supported,attachmentFeedbackLoopLayoutmust be supported -
If
VK_EXT_4444_formatsis supported,formatA4R4G4B4must be supported -
If
VK_EXT_device_faultis supported,deviceFaultmust be supported -
If
VK_EXT_rgba10x6_formatsis supported,formatRgba10x6WithoutYCbCrSamplermust be supported -
If
VK_VALVE_mutable_descriptor_typeis supported,mutableDescriptorTypemust be supported -
If
VK_EXT_vertex_input_dynamic_stateis supported,vertexInputDynamicStatemust be supported -
If
VK_EXT_device_address_binding_reportis supported,reportAddressBindingmust be supported -
If
VK_EXT_depth_clip_controlis supported,depthClipControlmust be supported -
If
VK_EXT_primitive_topology_list_restartis supported,primitiveTopologyListRestartmust be supported -
If
VK_EXT_present_mode_fifo_latest_readyis supported,presentModeFifoLatestReadymust be supported -
If
VK_HUAWEI_subpass_shadingis supported,subpassShadingmust be supported -
If
VK_HUAWEI_invocation_maskis supported,invocationMaskmust be supported -
If
VK_NV_external_memory_rdmais supported,externalMemoryRDMAmust be supported -
If
VK_EXT_pipeline_propertiesis supported,pipelinePropertiesIdentifiermust be supported -
If
VK_EXT_frame_boundaryis supported,frameBoundarymust be supported -
If
VK_EXT_multisampled_render_to_single_sampledis supported,multisampledRenderToSingleSampledmust be supported -
If
VK_EXT_extended_dynamic_state2is supported,extendedDynamicState2must be supported -
If
VK_EXT_color_write_enableis supported,colorWriteEnablemust be supported -
If
VK_EXT_primitives_generated_queryis supported,primitivesGeneratedQuerymust be supported -
If
VK_EXT_global_priority_queryis supported,globalPriorityQuerymust be supported -
If
VK_EXT_image_view_min_lodis supported,minLodmust be supported -
If
VK_EXT_multi_drawis supported,multiDrawmust be supported -
If
VK_EXT_image_2d_view_of_3dis supported,image2DViewOf3Dmust be supported -
If
VK_EXT_shader_tile_imageis supported,shaderTileImageColorReadAccessmust be supported -
If
VK_EXT_opacity_micromapis supported,micromapmust be supported -
If
VK_NV_displacement_micromapis supported,displacementMicromapmust be supported -
If
VK_HUAWEI_cluster_culling_shaderis supported,clustercullingShadermust be supported -
If
VK_EXT_border_color_swizzleis supported,borderColorSwizzlemust be supported -
If
VK_EXT_pageable_device_local_memoryis supported,pageableDeviceLocalMemorymust be supported -
If
VK_ARM_scheduling_controlsis supported,schedulingControlsmust be supported -
If
VK_EXT_image_sliced_view_of_3dis supported,imageSlicedViewOf3Dmust be supported -
If
VK_VALVE_descriptor_set_host_mappingis supported,descriptorSetHostMappingmust be supported -
If
VK_EXT_depth_clamp_zero_oneis supported,depthClampZeroOnemust be supported -
If
VK_EXT_non_seamless_cube_mapis supported,nonSeamlessCubeMapmust be supported -
If
VK_ARM_render_pass_stripedis supported,renderPassStripedmust be supported -
If
VK_QCOM_fragment_density_map_offsetis supported,fragmentDensityMapOffsetmust be supported -
If
VK_NV_copy_memory_indirectis supported,indirectCopymust be supported -
If
VK_NV_memory_decompressionis supported,memoryDecompressionmust be supported -
If
VK_NV_device_generated_commands_computeis supported,deviceGeneratedComputemust be supported -
If
VK_NV_ray_tracing_linear_swept_spheresis supported, at least one ofspheresorlinearSweptSpheresmust be supported -
If
VK_NV_linear_color_attachmentis supported,linearColorAttachmentmust be supported -
If
VK_EXT_image_compression_control_swapchainis supported,imageCompressionControlSwapchainmust be supported -
If
VK_QCOM_image_processingis supported, the following features must be supported: -
If
VK_EXT_nested_command_bufferis supported,nestedCommandBuffermust be supported -
If
VK_EXT_extended_dynamic_state3is supported, the following features must be supported:-
tessellationShaderifextendedDynamicState3TessellationDomainOriginis supported -
depthClampifextendedDynamicState3DepthClampEnableis supported -
fillModeNonSolidifextendedDynamicState3PolygonModeis supported -
alphaToOneifextendedDynamicState3AlphaToOneEnableis supported -
logicOpifextendedDynamicState3LogicOpEnableis supported -
geometryStreamsifVK_EXT_transform_feedbackandextendedDynamicState3RasterizationStreamare supported
-
-
If
VK_EXT_subpass_merge_feedbackis supported,subpassMergeFeedbackmust be supported -
If
VK_ARM_tensorsis supported,tensorsmust be supported -
If
VK_EXT_shader_module_identifieris supported,shaderModuleIdentifiermust be supported -
If
VK_NV_optical_flowis supported,opticalFlowmust be supported -
If
VK_EXT_legacy_ditheringis supported,legacyDitheringmust be supported -
If
VK_EXT_pipeline_protected_accessis supported,pipelineProtectedAccessmust be supported -
If
VK_ANDROID_external_format_resolveis supported,externalFormatResolvemust be supported -
If
VK_AMD_anti_lagis supported,antiLagmust be supported -
If
VK_EXT_shader_objectis supported,shaderObjectmust be supported -
If
VK_QCOM_tile_propertiesis supported,tilePropertiesmust be supported -
If
VK_SEC_amigo_profilingis supported,amigoProfilingmust be supported -
If
VK_QCOM_multiview_per_view_viewportsis supported,multiviewPerViewViewportsmust be supported -
If
VK_NV_ray_tracing_invocation_reorderis supported,rayTracingInvocationReordermust be supported -
If
VK_NV_cooperative_vectoris supported,cooperativeVectormust be supported -
If
VK_NV_extended_sparse_address_spaceis supported,extendedSparseAddressSpacemust be supported -
If
VK_EXT_mutable_descriptor_typeis supported,mutableDescriptorTypemust be supported -
If
VK_EXT_legacy_vertex_attributesis supported,legacyVertexAttributesmust be supported -
If
VK_ARM_shader_core_builtinsis supported,shaderCoreBuiltinsmust be supported -
If
VK_EXT_pipeline_library_group_handlesis supported,pipelineLibraryGroupHandlesmust be supported -
If
VK_EXT_dynamic_rendering_unused_attachmentsis supported,dynamicRenderingUnusedAttachmentsmust be supported -
If
VK_ARM_data_graphis supported,dataGraphmust be supported -
If
VK_QCOM_multiview_per_view_render_areasis supported,multiviewPerViewRenderAreasmust be supported -
If
VK_NV_per_stage_descriptor_setis supported,perStageDescriptorSetmust be supported -
If
VK_QCOM_image_processing2is supported,textureBlockMatch2must be supported -
If
VK_QCOM_filter_cubic_weightsis supported,selectableCubicWeightsmust be supported -
If
VK_QCOM_ycbcr_degammais supported,ycbcrDegammamust be supported -
If
VK_QCOM_filter_cubic_clampis supported,cubicRangeClampmust be supported -
If
VK_EXT_attachment_feedback_loop_dynamic_stateis supported,attachmentFeedbackLoopDynamicStatemust be supported -
If
VK_QNX_external_memory_screen_bufferis supported,screenBufferImportmust be supported -
If
VK_NV_descriptor_pool_overallocationis supported,descriptorPoolOverallocationmust be supported -
If
VK_QCOM_tile_memory_heapis supported,tileMemoryHeapmust be supported -
If
VK_NV_raw_access_chainsis supported,shaderRawAccessChainsmust be supported -
If
VK_NV_command_buffer_inheritanceis supported,commandBufferInheritancemust be supported -
If
VK_NV_shader_atomic_float16_vectoris supported,shaderFloat16VectorAtomicsmust be supported -
If
VK_EXT_shader_replicated_compositesis supported,shaderReplicatedCompositesmust be supported -
If
VK_EXT_shader_float8is supported,shaderFloat8must be supported -
If
VK_NV_ray_tracing_validationis supported,rayTracingValidationmust be supported -
If
VK_NV_cluster_acceleration_structureis supported,clusterAccelerationStructuremust be supported -
If
VK_NV_partitioned_acceleration_structureis supported,partitionedAccelerationStructuremust be supported -
If
VK_EXT_device_generated_commandsis supported,deviceGeneratedCommandsmust be supported -
If
VK_MESA_image_alignment_controlis supported,imageAlignmentControlmust be supported -
If
VK_EXT_depth_clamp_controlis supported,depthClampControlmust be supported -
If
VK_HUAWEI_hdr_vividis supported,hdrVividmust be supported -
If
VK_NV_cooperative_matrix2is supported, at least one ofcooperativeMatrixWorkgroupScope,cooperativeMatrixFlexibleDimensions,cooperativeMatrixReductions,cooperativeMatrixConversions,cooperativeMatrixPerElementOperations,cooperativeMatrixTensorAddressing, orcooperativeMatrixBlockLoadsmust be supported -
If
VK_ARM_pipeline_opacity_micromapis supported,pipelineOpacityMicromapmust be supported -
If
VK_EXT_vertex_attribute_robustnessis supported,vertexAttributeRobustnessmust be supported -
If
VK_ARM_format_packis supported,formatPackmust be supported -
If
VK_VALVE_fragment_density_map_layeredis supported,fragmentDensityMapLayeredmust be supported -
If
VK_NV_present_meteringis supported,presentMeteringmust be supported -
If
VK_EXT_fragment_density_map_offsetis supported,fragmentDensityMapOffsetmust be supported -
If
VK_EXT_zero_initialize_device_memoryis supported,zeroInitializeDeviceMemorymust be supported -
If
VK_SEC_pipeline_cache_incremental_modeis supported,pipelineCacheIncrementalModemust be supported -
If
VK_KHR_acceleration_structureis supported, the following features must be supported:-
descriptorIndexingif Vulkan 1.2 is supported
-
If
VK_KHR_ray_tracing_pipelineis supported, the following features must be supported: -
If
VK_KHR_ray_queryis supported,rayQuerymust be supported -
If
VK_EXT_mesh_shaderis supported, the following features must be supported: -
VK_KHR_fragment_shading_rateif theprimitiveFragmentShadingRateMeshShaderfeature is supported. -
VK_EXT_transform_feedback, if theextendedDynamicState3RasterizationStreamfeature is supported. -
VK_EXT_conservative_rasterizationextension, if theextendedDynamicState3ConservativeRasterizationModefeature is supported. -
VK_EXT_conservative_rasterizationextension, if theextendedDynamicState3ExtraPrimitiveOverestimationSizefeature is supported. -
VK_EXT_sample_locationsextension, if theextendedDynamicState3SampleLocationsEnablefeature is supported. -
VK_EXT_blend_operation_advancedextension, if theextendedDynamicState3ColorBlendAdvancedfeature is supported. -
VK_EXT_provoking_vertex, if theextendedDynamicState3ProvokingVertexModefeature is supported. -
Vulkan 1.4 or the VK_KHR_line_rasterization extension or the VK_EXT_line_rasterization extension, if the
extendedDynamicState3LineRasterizationModefeature is supported. -
VK_KHR_line_rasterizationorVK_EXT_line_rasterizationextension, if theextendedDynamicState3LineStippleEnablefeature is supported. -
VK_EXT_depth_clip_control, if theextendedDynamicState3DepthClipNegativeOneToOnefeature is supported. -
VK_NV_clip_space_w_scalingextension, if theextendedDynamicState3ViewportWScalingEnablefeature is supported. -
VK_NV_viewport_swizzleextension, if theextendedDynamicState3ViewportSwizzlefeature is supported. -
VK_NV_fragment_coverage_to_colorextension, if theextendedDynamicState3CoverageToColorEnablefeature is supported. -
VK_NV_fragment_coverage_to_colorextension, if theextendedDynamicState3CoverageToColorLocationfeature is supported. -
VK_NV_framebuffer_mixed_samplesextension, if theextendedDynamicState3CoverageModulationModefeature is supported. -
VK_NV_framebuffer_mixed_samplesextension, if theextendedDynamicState3CoverageModulationTableEnablefeature is supported. -
VK_NV_framebuffer_mixed_samplesextension, if theextendedDynamicState3CoverageModulationTablefeature is supported. -
VK_NV_coverage_reduction_mode, if theextendedDynamicState3CoverageReductionModefeature is supported. -
VK_NV_representative_fragment_test, if theextendedDynamicState3RepresentativeFragmentTestEnablefeature is supported. -
VK_NV_shading_rate_image, if theextendedDynamicState3ShadingRateImageEnablefeature is supported. -
If Vulkan 1.4 is supported, at least one queue family is reported by vkGetPhysicalDeviceQueueFamilyProperties that includes the
VK_QUEUE_GRAPHICS_BITflag, and no additional queue families are reported that support theVK_QUEUE_TRANSFER_BITflag, thehostImageCopyfeature must be supported.
All other features defined in the Specification are optional.
49.2. Profile Features
49.2.1. Roadmap 2022
Implementations that claim support for the Roadmap 2022 profile must support the following features:
49.2.2. Roadmap 2024
Implementations that claim support for the Roadmap 2024 profile must support the following features:
50. 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, linear or optimal tensor 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. If theextendedSparseAddressSpacefeature is enabled, then the difference betweenextendedSparseAddressSpaceSizeandsparseAddressSpaceSizecan also be used, byVkImagecreated with theusagemember of VkImageCreateInfo only containing bits inextendedSparseImageUsageFlagsandVkBuffercreated with theusagemember of VkBufferCreateInfo only containing bits inextendedSparseBufferUsageFlags. -
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. -
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. If thetexelBufferAlignmentfeature is enabled, this limit is equivalent to the maximum of theuniformTexelBufferOffsetAlignmentBytesandstorageTexelBufferOffsetAlignmentBytesmembers of VkPhysicalDeviceTexelBufferAlignmentProperties, but smaller alignment is optionally allowed bystorageTexelBufferOffsetSingleTexelAlignmentanduniformTexelBufferOffsetSingleTexelAlignment. If thetexelBufferAlignmentfeature is 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 theOffsetorConstOffsetimage operand of any of theOpImageSample*orOpImageFetch*image instructions. -
maxTexelOffsetis the maximum offset value for theOffsetorConstOffsetimage 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 isVK_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 all 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. This value is also the optimal host memory offset alignment in bytes for vkCopyMemoryToImage and vkCopyImageToMemory. 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. This value is also the optimal host memory row pitch alignment in bytes for vkCopyMemoryToImage and vkCopyImageToMemory. 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 VkPhysicalDevicePushDescriptorProperties structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDevicePushDescriptorProperties {
VkStructureType sType;
void* pNext;
uint32_t maxPushDescriptors;
} VkPhysicalDevicePushDescriptorProperties;
or the equivalent
// Provided by VK_KHR_push_descriptor
typedef VkPhysicalDevicePushDescriptorProperties VkPhysicalDevicePushDescriptorPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
If the VkPhysicalDevicePushDescriptorProperties 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
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;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxDiscardRectanglesis the maximum number of active discard rectangles that can be specified.
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 a VkStructureType value identifying 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 VkPhysicalDeviceLegacyVertexAttributesPropertiesEXT structure is
defined as:
// Provided by VK_EXT_legacy_vertex_attributes
typedef struct VkPhysicalDeviceLegacyVertexAttributesPropertiesEXT {
VkStructureType sType;
void* pNext;
VkBool32 nativeUnalignedPerformance;
} VkPhysicalDeviceLegacyVertexAttributesPropertiesEXT;
This structure describes the following features:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nativeUnalignedPerformancespecifies whether unaligned vertex fetches do not incur significant performance penalties as compared to aligned fetches.
If the VkPhysicalDeviceLegacyVertexAttributesPropertiesEXT 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.
If the application wishes to use a VkDevice with any features
described by VkPhysicalDeviceLegacyVertexAttributesPropertiesEXT, it must add an instance of the structure,
with the desired feature members set to VK_TRUE, to the pNext
chain of VkDeviceCreateInfo when creating the VkDevice.
The VkPhysicalDeviceExternalMemoryHostPropertiesEXT structure is
defined as:
// Provided by VK_EXT_external_memory_host
typedef struct VkPhysicalDeviceExternalMemoryHostPropertiesEXT {
VkStructureType sType;
void* pNext;
VkDeviceSize minImportedHostPointerAlignment;
} VkPhysicalDeviceExternalMemoryHostPropertiesEXT;
-
sTypeis a VkStructureType value identifying 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;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
perViewPositionAllComponentsisVK_TRUEif the implementation supports per-view position values that differ in components other than the X component.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 the shaderSubgroupUniformControlFlow feature is enabled,
subgroupSize must be greater than or equal to 4.
If the shaderQuadControl feature is
supported, supportedOperations must include VK_SUBGROUP_FEATURE_QUAD_BIT.
If VK_KHR_shader_subgroup_rotate is supported, and the implementation
advertises support with a VkExtensionProperties::specVersion
greater than or equal to 2, and the shaderSubgroupRotate feature is supported,
VK_SUBGROUP_FEATURE_ROTATE_BIT must be returned in
VkPhysicalDeviceVulkan11Properties::subgroupSupportedOperations
and
VkPhysicalDeviceSubgroupProperties::supportedOperations.
If VK_KHR_shader_subgroup_rotate is supported, and the implementation
advertises support with a VkExtensionProperties::specVersion
greater than or equal to 2, and the
shaderSubgroupRotateClustered feature is supported,
VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT must be returned in
VkPhysicalDeviceVulkan11Properties::subgroupSupportedOperations
and
VkPhysicalDeviceSubgroupProperties::supportedOperations.
If Vulkan 1.4 is supported, VK_SUBGROUP_FEATURE_ROTATE_BIT and
VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT must be returned in
VkPhysicalDeviceSubgroupProperties::supportedOperations and
VkPhysicalDeviceVulkan11Properties::subgroupSupportedOperations
|
Note
|
|
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_VERSION_1_4
VK_SUBGROUP_FEATURE_ROTATE_BIT = 0x00000200,
// Provided by VK_VERSION_1_4
VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT = 0x00000400,
// Provided by VK_NV_shader_subgroup_partitioned
VK_SUBGROUP_FEATURE_PARTITIONED_BIT_NV = 0x00000100,
// Provided by VK_KHR_shader_subgroup_rotate
VK_SUBGROUP_FEATURE_ROTATE_BIT_KHR = VK_SUBGROUP_FEATURE_ROTATE_BIT,
// Provided by VK_KHR_shader_subgroup_rotate
VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT_KHR = VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT,
} 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. -
VK_SUBGROUP_FEATURE_ROTATE_BITspecifies the device will accept SPIR-V shader modules containing theGroupNonUniformRotateKHRcapability. -
VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BITspecifies the device will accept SPIR-V shader modules that use theClusterSizeoperand toOpGroupNonUniformRotateKHR.
// 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxVertexAttribDivisoris the maximum value of the number of instances that will repeat the value of vertex attribute data when instanced rendering is enabled.
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 VkPhysicalDeviceVertexAttributeDivisorProperties structure is
defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceVertexAttributeDivisorProperties {
VkStructureType sType;
void* pNext;
uint32_t maxVertexAttribDivisor;
VkBool32 supportsNonZeroFirstInstance;
} VkPhysicalDeviceVertexAttributeDivisorProperties;
or the equivalent
// Provided by VK_KHR_vertex_attribute_divisor
typedef VkPhysicalDeviceVertexAttributeDivisorProperties VkPhysicalDeviceVertexAttributeDivisorPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
maxVertexAttribDivisoris the maximum value of the number of instances that will repeat the value of vertex attribute data when instanced rendering is enabled. -
supportsNonZeroFirstInstancespecifies whether a non-zero value for thefirstInstanceparameter of drawing commands is supported when VkVertexInputBindingDivisorDescription::divisoris not1.
If the VkPhysicalDeviceVertexAttributeDivisorProperties 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 VkMemoryAllocateInfo::allocationSizeis larger the errorVK_ERROR_OUT_OF_DEVICE_MEMORYmay be returned.
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 a VkStructureType value identifying 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 VkPhysicalDeviceMaintenance5Properties structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceMaintenance5Properties {
VkStructureType sType;
void* pNext;
VkBool32 earlyFragmentMultisampleCoverageAfterSampleCounting;
VkBool32 earlyFragmentSampleMaskTestBeforeSampleCounting;
VkBool32 depthStencilSwizzleOneSupport;
VkBool32 polygonModePointSize;
VkBool32 nonStrictSinglePixelWideLinesUseParallelogram;
VkBool32 nonStrictWideLinesUseParallelogram;
} VkPhysicalDeviceMaintenance5Properties;
or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkPhysicalDeviceMaintenance5Properties VkPhysicalDeviceMaintenance5PropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
earlyFragmentMultisampleCoverageAfterSampleCountingis a boolean value indicating whether the fragment shading and multisample coverage operations are performed after sample counting for fragment shaders withEarlyFragmentTestsexecution mode. -
earlyFragmentSampleMaskTestBeforeSampleCountingis a boolean value indicating whether the sample mask test operation is performed before sample counting for fragment shaders using theEarlyFragmentTestsexecution mode. -
depthStencilSwizzleOneSupportis a boolean indicating that depth/stencil texturing operations withVK_COMPONENT_SWIZZLE_ONEhave defined behavior. -
polygonModePointSizeis a boolean value indicating whether the point size of the final rasterization of polygons withVK_POLYGON_MODE_POINTis controlled byPointSize. -
nonStrictSinglePixelWideLinesUseParallelogramis a boolean value indicating whether non-strict lines with a width of 1.0 are rasterized as parallelograms or using Bresenham’s algorithm. -
nonStrictWideLinesUseParallelogramis a boolean value indicating whether non-strict lines with a width greater than 1.0 are rasterized as parallelograms or using Bresenham’s algorithm.
If the VkPhysicalDeviceMaintenance5Properties 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 VkPhysicalDeviceMaintenance6Properties structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceMaintenance6Properties {
VkStructureType sType;
void* pNext;
VkBool32 blockTexelViewCompatibleMultipleLayers;
uint32_t maxCombinedImageSamplerDescriptorCount;
VkBool32 fragmentShadingRateClampCombinerInputs;
} VkPhysicalDeviceMaintenance6Properties;
or the equivalent
// Provided by VK_KHR_maintenance6
typedef VkPhysicalDeviceMaintenance6Properties VkPhysicalDeviceMaintenance6PropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
blockTexelViewCompatibleMultipleLayersis a boolean value indicating that an implementation supports creating image views withVK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BITwhere thelayerCountmember ofsubresourceRangeis greater than1. -
maxCombinedImageSamplerDescriptorCountis the maximum number of combined image sampler descriptors that the implementation uses to access any of the formats that require a sampler Y′CBCR conversion supported by the implementation. -
fragmentShadingRateClampCombinerInputsis a boolean value indicating that an implementation clamps the inputs to combiner operations.
If the VkPhysicalDeviceMaintenance6Properties 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 VkPhysicalDeviceMaintenance7PropertiesKHR structure is defined as:
// Provided by VK_KHR_maintenance7
typedef struct VkPhysicalDeviceMaintenance7PropertiesKHR {
VkStructureType sType;
void* pNext;
VkBool32 robustFragmentShadingRateAttachmentAccess;
VkBool32 separateDepthStencilAttachmentAccess;
uint32_t maxDescriptorSetTotalUniformBuffersDynamic;
uint32_t maxDescriptorSetTotalStorageBuffersDynamic;
uint32_t maxDescriptorSetTotalBuffersDynamic;
uint32_t maxDescriptorSetUpdateAfterBindTotalUniformBuffersDynamic;
uint32_t maxDescriptorSetUpdateAfterBindTotalStorageBuffersDynamic;
uint32_t maxDescriptorSetUpdateAfterBindTotalBuffersDynamic;
} VkPhysicalDeviceMaintenance7PropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
robustFragmentShadingRateAttachmentAccessindicates whether the scaled size of a fragment shading rate attachment can be less than the size of the render area. IfrobustFragmentShadingRateAttachmentAccessisVK_FALSE, the size of the attachment multiplied by the texel size must be greater than or equal to the size of the render area. If it isVK_TRUEand the fragment shading rate attachment was created with VkImageSubresourceRange::baseMipLevelequal to 0, the scaled size can be smaller than the render area, and shading rates for missing texels are defined by texel replacement for invalid texels. -
separateDepthStencilAttachmentAccessindicates support for writing to one aspect of a depth/stencil attachment without performing read-modify-write operations on the other aspect. If this property isVK_TRUE, writes to one aspect must not result in read-modify-write operations on the other aspect. IfVK_FALSE, writes to one aspect may result in writes to the other aspect as defined by render pass load operations, render pass store operations and render pass resolve operations. -
maxDescriptorSetTotalUniformBuffersDynamicis the maximum total count 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. -
maxDescriptorSetTotalStorageBuffersDynamicis the maximum total count 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. -
maxDescriptorSetTotalBuffersDynamicis the maximum total count of dynamic uniform buffers and storage buffers that can be included in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMICorVK_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. -
maxDescriptorSetUpdateAfterBindTotalUniformBuffersDynamicis similar tomaxDescriptorSetTotalUniformBuffersDynamicbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindTotalStorageBuffersDynamicis similar tomaxDescriptorSetTotalStorageBuffersDynamicbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxDescriptorSetUpdateAfterBindTotalBuffersDynamicis similar tomaxDescriptorSetTotalBuffersDynamicbut 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.
If the VkPhysicalDeviceMaintenance7PropertiesKHR 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 VkPhysicalDeviceLayeredApiPropertiesListKHR structure is defined
as:
// Provided by VK_KHR_maintenance7
typedef struct VkPhysicalDeviceLayeredApiPropertiesListKHR {
VkStructureType sType;
void* pNext;
uint32_t layeredApiCount;
VkPhysicalDeviceLayeredApiPropertiesKHR* pLayeredApis;
} VkPhysicalDeviceLayeredApiPropertiesListKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
layeredApiCountis an integer related to the number of layered implementations underneath the Vulkan physical device, as described below. -
pLayeredApisis a pointer to an array of VkPhysicalDeviceLayeredApiPropertiesKHR in which information regarding the layered implementations underneath the Vulkan physical device are returned.
If pLayeredApis is NULL, then the number of layered implementations
that are underneath the top-most Vulkan physical device (i.e. the one
returned by vkGetPhysicalDeviceProperties2) is returned in
layeredApiCount.
Otherwise, layeredApiCount must be set by the application to the
number of elements in the pLayeredApis array, and on return the
variable is overwritten with the number of values actually written to
pLayeredApis.
If the value of layeredApiCount is less than the number of layered
implementations underneath the Vulkan physical device, at most
layeredApiCount values will be written to pLayeredApis.
An implementation that is not a layer will return 0 in
layeredApiCount.
In the presence of multiple layered implementations, each element of
pLayeredApis corresponds to an API implementation that is implemented
on top of the API at the previous index.
If there are layered implementations underneath a non-Vulkan implementation,
they may not be visible in this query as the corresponding APIs may lack
such a query.
If the VkPhysicalDeviceLayeredApiPropertiesListKHR 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 VkPhysicalDeviceLayeredApiPropertiesKHR structure is defined as:
// Provided by VK_KHR_maintenance7
typedef struct VkPhysicalDeviceLayeredApiPropertiesKHR {
VkStructureType sType;
void* pNext;
uint32_t vendorID;
uint32_t deviceID;
VkPhysicalDeviceLayeredApiKHR layeredAPI;
char deviceName[VK_MAX_PHYSICAL_DEVICE_NAME_SIZE];
} VkPhysicalDeviceLayeredApiPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vendorIDis a unique identifier for the vendor of the layered implementation. -
deviceIDis a unique identifier for the layered implementation among devices available from the vendor. -
layeredAPIis a VkPhysicalDeviceLayeredApiKHR specifying the API implemented by the layered implementation. -
deviceNameis an array ofVK_MAX_PHYSICAL_DEVICE_NAME_SIZEcharcontaining a null-terminated UTF-8 string which is the name of the device.
If layeredAPI is VK_PHYSICAL_DEVICE_LAYERED_API_VULKAN_KHR,
additional Vulkan-specific information can be queried by including the
VkPhysicalDeviceLayeredApiVulkanPropertiesKHR structure in the
pNext chain.
Otherwise if such a structure is included in the pNext chain, it is
ignored.
The list of possible API implementations of a layered implementation
underneath the Vulkan physical device, as returned in
VkPhysicalDeviceLayeredApiPropertiesKHR::layeredAPI, are:
// Provided by VK_KHR_maintenance7
typedef enum VkPhysicalDeviceLayeredApiKHR {
VK_PHYSICAL_DEVICE_LAYERED_API_VULKAN_KHR = 0,
VK_PHYSICAL_DEVICE_LAYERED_API_D3D12_KHR = 1,
VK_PHYSICAL_DEVICE_LAYERED_API_METAL_KHR = 2,
VK_PHYSICAL_DEVICE_LAYERED_API_OPENGL_KHR = 3,
VK_PHYSICAL_DEVICE_LAYERED_API_OPENGLES_KHR = 4,
} VkPhysicalDeviceLayeredApiKHR;
-
VK_PHYSICAL_DEVICE_LAYERED_API_VULKAN_KHR- the device implements the Vulkan API. -
VK_PHYSICAL_DEVICE_LAYERED_API_D3D12_KHR- the device implements the D3D12 API. -
VK_PHYSICAL_DEVICE_LAYERED_API_METAL_KHR- the device implements the Metal API. -
VK_PHYSICAL_DEVICE_LAYERED_API_OPENGL_KHR- the device implements the OpenGL API. -
VK_PHYSICAL_DEVICE_LAYERED_API_OPENGLES_KHR- the device implements the OpenGL ES API.
The VkPhysicalDeviceLayeredApiVulkanPropertiesKHR structure is defined
as:
// Provided by VK_KHR_maintenance7
typedef struct VkPhysicalDeviceLayeredApiVulkanPropertiesKHR {
VkStructureType sType;
void* pNext;
VkPhysicalDeviceProperties2 properties;
} VkPhysicalDeviceLayeredApiVulkanPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
propertiesis a VkPhysicalDeviceProperties2 in which properties of the underlying layered Vulkan implementation are returned.
The implementation must zero-fill the contents of
properties.properties.limits and
properties.properties.sparseProperties.
The VkPhysicalDeviceMaintenance9PropertiesKHR structure is defined as:
// Provided by VK_KHR_maintenance9
typedef struct VkPhysicalDeviceMaintenance9PropertiesKHR {
VkStructureType sType;
void* pNext;
VkBool32 image2DViewOf3DSparse;
VkDefaultVertexAttributeValueKHR defaultVertexAttributeValue;
} VkPhysicalDeviceMaintenance9PropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
If the
image2DViewOf3Dfeature is enabled,image2DViewOf3DSparseindicates whether the implementation supports binding a slice of a sparse 3D image to a 2D image view. -
defaultVertexAttributeValueis a VkDefaultVertexAttributeValueKHR that indicates what value the implementation will return when the vertex shader reads unbound vertex attributes. Unbound attributes are those that have no corresponding VkVertexInputAttributeDescription::locationdefined in the bound graphics pipeline or no corresponding VkVertexInputAttributeDescription2EXT::locationset by the most recent call to vkCmdSetVertexInputEXT when the state is dynamic .
If the VkPhysicalDeviceMaintenance9PropertiesKHR 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 possible values returned by the implementation when the vertex shader reads an unbound vertex attribute are:
// Provided by VK_KHR_maintenance9
typedef enum VkDefaultVertexAttributeValueKHR {
VK_DEFAULT_VERTEX_ATTRIBUTE_VALUE_ZERO_ZERO_ZERO_ZERO_KHR = 0,
VK_DEFAULT_VERTEX_ATTRIBUTE_VALUE_ZERO_ZERO_ZERO_ONE_KHR = 1,
} VkDefaultVertexAttributeValueKHR;
-
VK_DEFAULT_VERTEX_ATTRIBUTE_VALUE_ZERO_ZERO_ZERO_ZERO_KHR- the value read for an unbound vertex attribute is (0,0,0,0). -
VK_DEFAULT_VERTEX_ATTRIBUTE_VALUE_ZERO_ZERO_ZERO_ONE_KHR- the value read for an unbound vertex attribute is (0,0,0,1).
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 a VkStructureType value identifying 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 multiview 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 VkPhysicalDeviceMeshShaderPropertiesEXT structure is defined as:
// Provided by VK_EXT_mesh_shader
typedef struct VkPhysicalDeviceMeshShaderPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t maxTaskWorkGroupTotalCount;
uint32_t maxTaskWorkGroupCount[3];
uint32_t maxTaskWorkGroupInvocations;
uint32_t maxTaskWorkGroupSize[3];
uint32_t maxTaskPayloadSize;
uint32_t maxTaskSharedMemorySize;
uint32_t maxTaskPayloadAndSharedMemorySize;
uint32_t maxMeshWorkGroupTotalCount;
uint32_t maxMeshWorkGroupCount[3];
uint32_t maxMeshWorkGroupInvocations;
uint32_t maxMeshWorkGroupSize[3];
uint32_t maxMeshSharedMemorySize;
uint32_t maxMeshPayloadAndSharedMemorySize;
uint32_t maxMeshOutputMemorySize;
uint32_t maxMeshPayloadAndOutputMemorySize;
uint32_t maxMeshOutputComponents;
uint32_t maxMeshOutputVertices;
uint32_t maxMeshOutputPrimitives;
uint32_t maxMeshOutputLayers;
uint32_t maxMeshMultiviewViewCount;
uint32_t meshOutputPerVertexGranularity;
uint32_t meshOutputPerPrimitiveGranularity;
uint32_t maxPreferredTaskWorkGroupInvocations;
uint32_t maxPreferredMeshWorkGroupInvocations;
VkBool32 prefersLocalInvocationVertexOutput;
VkBool32 prefersLocalInvocationPrimitiveOutput;
VkBool32 prefersCompactVertexOutput;
VkBool32 prefersCompactPrimitiveOutput;
} VkPhysicalDeviceMeshShaderPropertiesEXT;
The members of the VkPhysicalDeviceMeshShaderPropertiesEXT structure
describe the following implementation-dependent limits:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxTaskWorkGroupTotalCountis the maximum number of total local workgroups that can be launched by a single mesh tasks drawing command. See Programmable Mesh Shading. -
maxTaskWorkGroupCount[3] is the maximum number of local workgroups that can be launched by a single mesh tasks drawing 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 drawing commands must be less than or equal to the corresponding limit. The product of these dimensions must be less than or equal tomaxTaskWorkGroupTotalCount. -
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, 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. -
maxTaskPayloadSizeis the maximum total storage size, in bytes, available for variables declared with theTaskPayloadWorkgroupEXTstorage class in shader modules in the task shader stage. -
maxTaskSharedMemorySizeis the maximum total storage size, in bytes, available for variables declared with theWorkgroupstorage class in shader modules in the task shader stage. -
maxTaskPayloadAndSharedMemorySizeis the maximum total storage size, in bytes, available for variables that are declared with theTaskPayloadWorkgroupEXTorWorkgroupstorage class, in shader modules in the task shader stage. -
maxMeshWorkGroupTotalCountis the maximum number of local output tasks a single task shader workgroup can emit. -
maxMeshWorkGroupCount[3] is the maximum number of local output tasks a single task shader workgroup can emit, per dimension. These three values represent the maximum number of local output tasks for the X, Y, and Z dimensions, respectively. The workgroup count parameters to theOpEmitMeshTasksEXTmust be less than or equal to the corresponding limit. The product of these dimensions must be less than or equal tomaxMeshWorkGroupTotalCount. -
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, 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. -
maxMeshSharedMemorySizeis the maximum total storage size, in bytes, available for variables declared with theWorkgroupstorage class in shader modules in the mesh shader stage. -
maxMeshPayloadAndSharedMemorySizeis the maximum total storage size, in bytes, available for variables that are declared with theTaskPayloadWorkgroupEXTorWorkgroupstorage class in shader modules in the mesh shader stage. -
maxMeshOutputMemorySizeis the maximum total storage size, in bytes, available for output variables in shader modules in the mesh shader stage, according to the formula in Mesh Shader Output. -
maxMeshPayloadAndOutputMemorySizeis the maximum total storage size, in bytes, available for variables that are declared with theTaskPayloadWorkgroupEXTstorage class, or output variables in shader modules in the mesh shader stage, according to the formula in Mesh Shader Output. -
maxMeshOutputComponentsis the maximum number of components of output variables which can be output from the mesh shader stage. -
maxMeshOutputVerticesis the maximum number of vertices which can be emitted by a single mesh shader workgroup. -
maxMeshOutputPrimitivesis the maximum number of primitives which can be emitted by a single mesh shader workgroup. -
maxMeshOutputLayersis one greater than the maximum layer index that can be output from the mesh shader stage. -
maxMeshMultiviewViewCountis one greater than the maximum view index that can be used by any mesh shader. -
meshOutputPerVertexGranularityis the granularity of vertex allocation. The number of output vertices allocated for the mesh shader stage is padded to a multiple of this number. The value can be used to calculate the required storage size for output variables in shader modules in the mesh shader stage, which must be less than or equal tomaxMeshOutputMemorySize. -
meshOutputPerPrimitiveGranularityis the granularity of primitive allocation. The number of output primitives allocated for the mesh shader stage is padded to a multiple of this number. The value can be used to calculate the required storage size for output variables in shader modules in the mesh shader stage, which must be less than or equal tomaxMeshOutputMemorySize. -
maxPreferredTaskWorkGroupInvocationsis the maximum number of task shader invocations in a single workgroup that is preferred by the implementation for optimal performance. The value is guaranteed to be a multiple of a supported subgroup size for the task shader stage. -
maxPreferredMeshWorkGroupInvocationsis the maximum number of mesh shader invocations in a single workgroup that is preferred by the implementation for optimal performance. The value is guaranteed to be a multiple of a supported subgroup size for the mesh shader stage. -
prefersLocalInvocationVertexOutputspecifies whether writes to the vertex output array in a mesh shader yield best performance when the array index matchesLocalInvocationIndex. -
prefersLocalInvocationPrimitiveOutputspecifies whether writes to the primitive output array in a mesh shader yield best performance when the array index matchesLocalInvocationIndex. -
prefersCompactVertexOutputspecifies whether output vertices should be compacted after custom culling in the mesh shader for best performance, otherwise keeping the vertices at their original location may be better. -
prefersCompactPrimitiveOutputspecifies whether output primitives should be compacted after custom culling in the mesh shader for best performance, otherwise the use ofCullPrimitiveEXTmay be better.
If the VkPhysicalDeviceMeshShaderPropertiesEXT structure is included
in the pNext chain of VkPhysicalDeviceProperties2, it is filled
with the implementation-dependent limits.
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 a VkStructureType value identifying 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 non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of uniform buffers may execute multiple times in order to access all the descriptors. -
shaderSampledImageArrayNonUniformIndexingNativeis a boolean value indicating whether sampler and image descriptors natively support non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of samplers or images may execute multiple times in order to access all the descriptors. -
shaderStorageBufferArrayNonUniformIndexingNativeis a boolean value indicating whether storage buffer descriptors natively support non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of storage buffers may execute multiple times in order to access all the descriptors. -
shaderStorageImageArrayNonUniformIndexingNativeis a boolean value indicating whether storage image descriptors natively support non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of storage images may execute multiple times in order to access all the descriptors. -
shaderInputAttachmentArrayNonUniformIndexingNativeis a boolean value indicating whether input attachment descriptors natively support non-uniform indexing. If this isVK_FALSE, then a single dynamic instance of an instruction that non-uniformly indexes an array of input attachments may execute multiple times in order to access all the descriptors. -
robustBufferAccessUpdateAfterBindis a boolean value indicating whetherrobustBufferAccesscan be enabled on 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. Similarly, if this property isVK_FALSE, robustness must not be enabled through the VkPipelineRobustnessCreateInfo mechanism. -
quadDivergentImplicitLodis a boolean value indicating whether implicit LOD calculations for image operations have well-defined results when the image and/or sampler objects used for the instruction are not uniform within a quad. See Derivative Image Operations. -
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
maxInlineUniformBlockSizeis the maximum size in bytes of an inline uniform block binding. -
maxPerStageDescriptorInlineUniformBlocksis 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 VkPhysicalDeviceFragmentDensityMapOffsetPropertiesEXT structure is
defined as:
// Provided by VK_EXT_fragment_density_map_offset
typedef struct VkPhysicalDeviceFragmentDensityMapOffsetPropertiesEXT {
VkStructureType sType;
void* pNext;
VkExtent2D fragmentDensityOffsetGranularity;
} VkPhysicalDeviceFragmentDensityMapOffsetPropertiesEXT;
or the equivalent
// Provided by VK_QCOM_fragment_density_map_offset
typedef VkPhysicalDeviceFragmentDensityMapOffsetPropertiesEXT VkPhysicalDeviceFragmentDensityMapOffsetPropertiesQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
fragmentDensityOffsetGranularityis the granularity for fragment density offsets.
If the VkPhysicalDeviceFragmentDensityMapOffsetPropertiesEXT 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 VkPhysicalDeviceFragmentDensityMapLayeredPropertiesVALVE structure
is defined as:
// Provided by VK_VALVE_fragment_density_map_layered
typedef struct VkPhysicalDeviceFragmentDensityMapLayeredPropertiesVALVE {
VkStructureType sType;
void* pNext;
uint32_t maxFragmentDensityMapLayers;
} VkPhysicalDeviceFragmentDensityMapLayeredPropertiesVALVE;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxFragmentDensityMapLayersis the maximum number of layers to use with a layered fragment density map.
If the VkPhysicalDeviceFragmentDensityMapLayeredPropertiesVALVE 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 VkPhysicalDeviceTileMemoryHeapPropertiesQCOM structure is defined
as:
// Provided by VK_QCOM_tile_memory_heap
typedef struct VkPhysicalDeviceTileMemoryHeapPropertiesQCOM {
VkStructureType sType;
void* pNext;
VkBool32 queueSubmitBoundary;
VkBool32 tileBufferTransfers;
} VkPhysicalDeviceTileMemoryHeapPropertiesQCOM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
queueSubmitBoundaryis a boolean describing if tile memory becomes undefined at a queue submit boundary instead of the default command buffer submission batch boundary. -
tileBufferTransfersis a boolean describing if buffers bound to tile memory support transfer operations.
If the VkPhysicalDeviceTileMemoryHeapPropertiesQCOM 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 VkPhysicalDeviceMemoryDecompressionPropertiesNV structure is
defined as:
// Provided by VK_NV_memory_decompression
typedef struct VkPhysicalDeviceMemoryDecompressionPropertiesNV {
VkStructureType sType;
void* pNext;
VkMemoryDecompressionMethodFlagsNV decompressionMethods;
uint64_t maxDecompressionIndirectCount;
} VkPhysicalDeviceMemoryDecompressionPropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
decompressionMethodsis a bitmask of VkMemoryDecompressionMethodFlagBitsNV specifying memory decompression methods supported by the implementation. -
maxDecompressionIndirectCountspecifies the maximum supported count value in thecountBufferof vkCmdDecompressMemoryIndirectCountNV
If the VkPhysicalDeviceMemoryDecompressionPropertiesNV 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 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 a VkStructureType value identifying 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 be1. -
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 VkPhysicalDeviceCopyMemoryIndirectPropertiesNV structure is
defined as:
// Provided by VK_NV_copy_memory_indirect
typedef struct VkPhysicalDeviceCopyMemoryIndirectPropertiesNV {
VkStructureType sType;
void* pNext;
VkQueueFlags supportedQueues;
} VkPhysicalDeviceCopyMemoryIndirectPropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
supportedQueuesis a bitmask of VkQueueFlagBits indicating the queues on which indirect copy commands are supported.
If the indirectCopy feature is supported,
supportedQueues must return at least one supported queue.
If the VkPhysicalDeviceCopyMemoryIndirectPropertiesNV 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 entry in a shader binding table. 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 a VkStructureType value identifying 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 VkPhysicalDeviceCooperativeMatrixPropertiesKHR structure is
defined as:
// Provided by VK_KHR_cooperative_matrix
typedef struct VkPhysicalDeviceCooperativeMatrixPropertiesKHR {
VkStructureType sType;
void* pNext;
VkShaderStageFlags cooperativeMatrixSupportedStages;
} VkPhysicalDeviceCooperativeMatrixPropertiesKHR;
-
sTypeis a VkStructureType value identifying 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.
cooperativeMatrixSupportedStages must not have any bits other than
VK_SHADER_STAGE_COMPUTE_BIT set.
If the VkPhysicalDeviceCooperativeMatrixPropertiesKHR 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 VkPhysicalDeviceCooperativeMatrix2PropertiesNV structure is
defined as:
// Provided by VK_NV_cooperative_matrix2
typedef struct VkPhysicalDeviceCooperativeMatrix2PropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t cooperativeMatrixWorkgroupScopeMaxWorkgroupSize;
uint32_t cooperativeMatrixFlexibleDimensionsMaxDimension;
uint32_t cooperativeMatrixWorkgroupScopeReservedSharedMemory;
} VkPhysicalDeviceCooperativeMatrix2PropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cooperativeMatrixWorkgroupScopeMaxWorkgroupSizeis the maximum number of invocations in a workgroup when the module usesOpTypeCooperativeMatrixKHRwithScopeequal toWorkgroup. -
cooperativeMatrixFlexibleDimensionsMaxDimensionis the maximum supported dimension for cooperative matrix types when thecooperativeMatrixFlexibleDimensionsfeature is enabled. -
cooperativeMatrixWorkgroupScopeReservedSharedMemoryis the number of bytes of shared memory reserved for the implementation when the module usesOpTypeCooperativeMatrixKHRwithScopeequal toWorkgroup.
If the VkPhysicalDeviceCooperativeMatrix2PropertiesNV 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 VkPhysicalDeviceCooperativeVectorPropertiesNV structure is defined
as:
// Provided by VK_NV_cooperative_vector
typedef struct VkPhysicalDeviceCooperativeVectorPropertiesNV {
VkStructureType sType;
void* pNext;
VkShaderStageFlags cooperativeVectorSupportedStages;
VkBool32 cooperativeVectorTrainingFloat16Accumulation;
VkBool32 cooperativeVectorTrainingFloat32Accumulation;
uint32_t maxCooperativeVectorComponents;
} VkPhysicalDeviceCooperativeVectorPropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
cooperativeVectorSupportedStagesis a bitfield of VkShaderStageFlagBits describing the shader stages that cooperative vector instructions are supported in.cooperativeVectorSupportedStageswill have theVK_SHADER_STAGE_COMPUTE_BITbit set if any of the physical device’s queues supportVK_QUEUE_COMPUTE_BIT. -
cooperativeVectorTrainingFloat16AccumulationisVK_TRUEif the implementation supports cooperative vector training functions accumulating 16-bit floating-point results. -
cooperativeVectorTrainingFloat32AccumulationisVK_TRUEif the implementation supports cooperative vector training functions accumulating 32-bit floating-point results. -
maxCooperativeVectorComponentsindicates the maximum number of components that can be in a cooperative vector.
If the VkPhysicalDeviceCooperativeVectorPropertiesNV 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;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderWarpsPerSMis the maximum number of simultaneously executing warps on an SM.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 VkPhysicalDeviceLineRasterizationProperties structure is defined
as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceLineRasterizationProperties {
VkStructureType sType;
void* pNext;
uint32_t lineSubPixelPrecisionBits;
} VkPhysicalDeviceLineRasterizationProperties;
or the equivalent
// Provided by VK_KHR_line_rasterization
typedef VkPhysicalDeviceLineRasterizationProperties VkPhysicalDeviceLineRasterizationPropertiesKHR;
or the equivalent
// Provided by VK_EXT_line_rasterization
typedef VkPhysicalDeviceLineRasterizationProperties VkPhysicalDeviceLineRasterizationPropertiesEXT;
-
sTypeis a VkStructureType value identifying 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 VkPhysicalDeviceLineRasterizationProperties 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 VkPhysicalDeviceRobustness2PropertiesKHR structure is defined as:
// Provided by VK_KHR_robustness2
typedef struct VkPhysicalDeviceRobustness2PropertiesKHR {
VkStructureType sType;
void* pNext;
VkDeviceSize robustStorageBufferAccessSizeAlignment;
VkDeviceSize robustUniformBufferAccessSizeAlignment;
} VkPhysicalDeviceRobustness2PropertiesKHR;
or the equivalent
// Provided by VK_EXT_robustness2
typedef VkPhysicalDeviceRobustness2PropertiesKHR VkPhysicalDeviceRobustness2PropertiesEXT;
-
sTypeis a VkStructureType value identifying 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 VkPhysicalDeviceRobustness2PropertiesKHR 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 a VkStructureType value identifying 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 in VkIndirectCommandsLayoutTokenNV. -
maxIndirectCommandsStreamStrideis the maximum stream stride in VkIndirectCommandsLayoutCreateInfoNV. -
minSequencesCountBufferOffsetAlignmentis the minimum alignment for memory addresses which can be used in VkGeneratedCommandsInfoNV. -
minSequencesIndexBufferOffsetAlignmentis the minimum alignment for memory addresses which can be used in VkGeneratedCommandsInfoNV. -
minIndirectCommandsBufferOffsetAlignmentis the minimum alignment for memory addresses used in VkIndirectCommandsStreamNV, and as preprocess buffer in VkGeneratedCommandsInfoNV.
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 VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT structure is
defined as:
// Provided by VK_EXT_device_generated_commands
typedef struct VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t maxIndirectPipelineCount;
uint32_t maxIndirectShaderObjectCount;
uint32_t maxIndirectSequenceCount;
uint32_t maxIndirectCommandsTokenCount;
uint32_t maxIndirectCommandsTokenOffset;
uint32_t maxIndirectCommandsIndirectStride;
VkIndirectCommandsInputModeFlagsEXT supportedIndirectCommandsInputModes;
VkShaderStageFlags supportedIndirectCommandsShaderStages;
VkShaderStageFlags supportedIndirectCommandsShaderStagesPipelineBinding;
VkShaderStageFlags supportedIndirectCommandsShaderStagesShaderBinding;
VkBool32 deviceGeneratedCommandsTransformFeedback;
VkBool32 deviceGeneratedCommandsMultiDrawIndirectCount;
} VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxIndirectPipelineCountis the maximum number of pipelines passed to vkCreateIndirectExecutionSetEXT. -
maxIndirectShaderObjectCountis the maximum number of shader objects passed to vkCreateIndirectExecutionSetEXT. If this value is zero, binding shader objects indirectly is not supported. -
maxIndirectSequenceCountis the maximum number of sequences in VkGeneratedCommandsInfoEXT and in VkGeneratedCommandsMemoryRequirementsInfoEXT. -
maxIndirectCommandsTokenCountis the maximum number of tokens in VkIndirectCommandsLayoutCreateInfoEXT. -
maxIndirectCommandsTokenOffsetis the maximum offset in VkIndirectCommandsLayoutTokenEXT. -
maxIndirectCommandsIndirectStrideis the maximum stream stride in VkIndirectCommandsLayoutCreateInfoEXT. -
supportedIndirectCommandsInputModesindicates the supported input modes. -
supportedIndirectCommandsShaderStagesindicates the stages which can be used to generate indirect commands. Implementations are required to support, at minimum:VK_SHADER_STAGE_VERTEX_BIT,VK_SHADER_STAGE_FRAGMENT_BIT,VK_SHADER_STAGE_COMPUTE_BIT. -
supportedIndirectCommandsShaderStagesPipelineBindingindicates the stages which can be used within indirect execution sets for indirectly binding shader stages using pipelines. -
supportedIndirectCommandsShaderStagesShaderBindingindicates the stages which can be used within indirect execution sets for indirectly binding shader stages using shader objects. -
deviceGeneratedCommandsTransformFeedbackindicates whether the implementation supports interactions withVK_EXT_transform_feedbackfor pipelines not created withVK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT. -
deviceGeneratedCommandsMultiDrawIndirectCountindicates whether the implementation supports COUNT variants of multi-draw indirect tokens.
If the VkPhysicalDeviceDeviceGeneratedCommandsPropertiesEXT 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 a VkStructureType value identifying 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 VkPhysicalDevicePartitionedAccelerationStructurePropertiesNV
structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPhysicalDevicePartitionedAccelerationStructurePropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t maxPartitionCount;
} VkPhysicalDevicePartitionedAccelerationStructurePropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxPartitionCountindicates the maximum number of partitions allowed in a partitioned acceleration structure.
If the VkPhysicalDevicePartitionedAccelerationStructurePropertiesNV 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 VkPhysicalDeviceClusterAccelerationStructurePropertiesNV structure
is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkPhysicalDeviceClusterAccelerationStructurePropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t maxVerticesPerCluster;
uint32_t maxTrianglesPerCluster;
uint32_t clusterScratchByteAlignment;
uint32_t clusterByteAlignment;
uint32_t clusterTemplateByteAlignment;
uint32_t clusterBottomLevelByteAlignment;
uint32_t clusterTemplateBoundsByteAlignment;
uint32_t maxClusterGeometryIndex;
} VkPhysicalDeviceClusterAccelerationStructurePropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxVerticesPerClusterindicates the maximum number of unique vertices that can be specified in the index buffer for a cluster. -
maxTrianglesPerClusterindicates the maximum number of triangles in a cluster. -
clusterScratchByteAlignmentindicates the alignment required for scratch memory used in building or moving cluster acceleration structures. -
clusterByteAlignmentindicates the alignment of buffers when building cluster acceleration structures. -
clusterTemplateByteAlignmentindicates the alignment of buffers when building cluster templates. -
clusterBottomLevelByteAlignmentindicates the alignment of buffers when building bottom level acceleration structures. -
clusterTemplateBoundsByteAlignmentindicates the alignment of VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV::pname::instantiationBoundingBoxLimit. -
maxClusterGeometryIndexindicates the maximum geometry index possible for a triangle in an cluster acceleration structures.
If the VkPhysicalDeviceClusterAccelerationStructurePropertiesNV 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 a VkStructureType value identifying 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 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 VkPhysicalDeviceDescriptorBufferPropertiesEXT structure is defined
as:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkPhysicalDeviceDescriptorBufferPropertiesEXT {
VkStructureType sType;
void* pNext;
VkBool32 combinedImageSamplerDescriptorSingleArray;
VkBool32 bufferlessPushDescriptors;
VkBool32 allowSamplerImageViewPostSubmitCreation;
VkDeviceSize descriptorBufferOffsetAlignment;
uint32_t maxDescriptorBufferBindings;
uint32_t maxResourceDescriptorBufferBindings;
uint32_t maxSamplerDescriptorBufferBindings;
uint32_t maxEmbeddedImmutableSamplerBindings;
uint32_t maxEmbeddedImmutableSamplers;
size_t bufferCaptureReplayDescriptorDataSize;
size_t imageCaptureReplayDescriptorDataSize;
size_t imageViewCaptureReplayDescriptorDataSize;
size_t samplerCaptureReplayDescriptorDataSize;
size_t accelerationStructureCaptureReplayDescriptorDataSize;
size_t samplerDescriptorSize;
size_t combinedImageSamplerDescriptorSize;
size_t sampledImageDescriptorSize;
size_t storageImageDescriptorSize;
size_t uniformTexelBufferDescriptorSize;
size_t robustUniformTexelBufferDescriptorSize;
size_t storageTexelBufferDescriptorSize;
size_t robustStorageTexelBufferDescriptorSize;
size_t uniformBufferDescriptorSize;
size_t robustUniformBufferDescriptorSize;
size_t storageBufferDescriptorSize;
size_t robustStorageBufferDescriptorSize;
size_t inputAttachmentDescriptorSize;
size_t accelerationStructureDescriptorSize;
VkDeviceSize maxSamplerDescriptorBufferRange;
VkDeviceSize maxResourceDescriptorBufferRange;
VkDeviceSize samplerDescriptorBufferAddressSpaceSize;
VkDeviceSize resourceDescriptorBufferAddressSpaceSize;
VkDeviceSize descriptorBufferAddressSpaceSize;
} VkPhysicalDeviceDescriptorBufferPropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
combinedImageSamplerDescriptorSingleArrayindicates that the implementation does not require an array ofVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERdescriptors to be written into a descriptor buffer as an array of image descriptors, immediately followed by an array of sampler descriptors. -
bufferlessPushDescriptorsindicates that the implementation does not require a buffer created withVK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXTto be bound when using push descriptors. -
allowSamplerImageViewPostSubmitCreationindicates that the implementation does not restrict when the VkSampler or VkImageView objects used to retrieve descriptor data can be created in relation to command buffer submission. If this value isVK_FALSE, then the application must create any VkSampler or VkImageView objects whose descriptor data is accessed during the execution of a command buffer, before the vkQueueSubmit , or vkQueueSubmit2, call that submits that command buffer. -
descriptorBufferOffsetAlignmentindicates the required alignment in bytes when setting offsets into the descriptor buffer. -
maxDescriptorBufferBindingsindicates the maximum number of descriptor buffer bindings. -
maxResourceDescriptorBufferBindingsindicates the maximum number of descriptor buffer bindings withVK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXTthat can be used. -
maxSamplerDescriptorBufferBindingsindicates the maximum number of descriptor buffer bindings withVK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXTthat can be used. -
maxEmbeddedImmutableSamplerBindingsindicates the maximum number of embedded immutable sampler sets that can be bound. -
maxEmbeddedImmutableSamplersindicates the maximum number of unique immutable samplers in descriptor set layouts created withVK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT, and pipeline layouts created from them, which can simultaneously exist on a device. -
bufferCaptureReplayDescriptorDataSizeindicates the maximum size in bytes of the opaque data used for capture and replay with buffers. -
imageCaptureReplayDescriptorDataSizeindicates the maximum size in bytes of the opaque data used for capture and replay with images. -
imageViewCaptureReplayDescriptorDataSizeindicates the maximum size in bytes of the opaque data used for capture and replay with image views. -
samplerCaptureReplayDescriptorDataSizeindicates the maximum size in bytes of the opaque data used for capture and replay with samplers. -
accelerationStructureCaptureReplayDescriptorDataSizeindicates the maximum size in bytes of the opaque data used for capture and replay with acceleration structures. -
samplerDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_SAMPLERdescriptor. -
combinedImageSamplerDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERdescriptor. -
sampledImageDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_SAMPLED_IMAGEdescriptor. -
storageImageDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_STORAGE_IMAGEdescriptor. -
uniformTexelBufferDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERdescriptor if therobustBufferAccessfeature is not enabled. -
robustUniformTexelBufferDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFERdescriptor if therobustBufferAccessfeature is enabled. -
storageTexelBufferDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERdescriptor if therobustBufferAccessfeature is not enabled. -
robustStorageTexelBufferDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFERdescriptor if therobustBufferAccessfeature is enabled. -
uniformBufferDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERdescriptor. -
robustUniformBufferDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERdescriptor if therobustBufferAccessfeature is enabled. -
storageBufferDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_STORAGE_BUFFERdescriptor. -
robustStorageBufferDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_STORAGE_BUFFERdescriptor if therobustBufferAccessfeature is enabled. -
inputAttachmentDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENTdescriptor. -
accelerationStructureDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHRorVK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NVdescriptor. -
maxSamplerDescriptorBufferRangeindicates the maximum range in bytes from the address of a sampler descriptor buffer binding that is accessible to a shader. -
maxResourceDescriptorBufferRangeindicates the maximum range in bytes from the address of a resource descriptor buffer binding that is accessible to a shader. -
samplerDescriptorBufferAddressSpaceSizeindicates the total size in bytes of the address space available for descriptor buffers created withVK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT. -
resourceDescriptorBufferAddressSpaceSizeindicates the total size in bytes of the address space available for descriptor buffers created withVK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT. -
descriptorBufferAddressSpaceSizeindicates the total size in bytes of the address space available for descriptor buffers created with bothVK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXTandVK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT.
A descriptor binding with type VK_DESCRIPTOR_TYPE_MUTABLE_VALVE has a
descriptor size which is implied by the descriptor types included in the
VkMutableDescriptorTypeCreateInfoVALVE::pDescriptorTypes list.
The descriptor size is equal to the maximum size of any descriptor type
included in the pDescriptorTypes list.
As there is no way to request robust and non-robust descriptors separately,
or specify robust/non-robust descriptors in the set layout, if the
robustBufferAccess feature is enabled
then robust descriptors are always used.
If the VkPhysicalDeviceDescriptorBufferPropertiesEXT 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 VkPhysicalDeviceDescriptorBufferDensityMapPropertiesEXT structure
is defined as:
// Provided by VK_EXT_descriptor_buffer
typedef struct VkPhysicalDeviceDescriptorBufferDensityMapPropertiesEXT {
VkStructureType sType;
void* pNext;
size_t combinedImageSamplerDensityMapDescriptorSize;
} VkPhysicalDeviceDescriptorBufferDensityMapPropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
combinedImageSamplerDensityMapDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLERdescriptor when creating the descriptor withVK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXTset.
If the VkPhysicalDeviceDescriptorBufferDensityMapPropertiesEXT 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 VkPhysicalDeviceDescriptorBufferTensorPropertiesARM structure is
defined as:
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
typedef struct VkPhysicalDeviceDescriptorBufferTensorPropertiesARM {
VkStructureType sType;
void* pNext;
size_t tensorCaptureReplayDescriptorDataSize;
size_t tensorViewCaptureReplayDescriptorDataSize;
size_t tensorDescriptorSize;
} VkPhysicalDeviceDescriptorBufferTensorPropertiesARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensorCaptureReplayDescriptorDataSizeindicates the maximum size in bytes of the opaque data used for capture and replay with tensors. -
tensorViewCaptureReplayDescriptorDataSizeindicates the maximum size in bytes of the opaque data used for capture and replay with tensor views. -
tensorDescriptorSizeindicates the size in bytes of aVK_DESCRIPTOR_TYPE_TENSOR_ARMdescriptor.
If the VkPhysicalDeviceDescriptorBufferTensorPropertiesARM 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 VkPhysicalDeviceHostImageCopyProperties structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDeviceHostImageCopyProperties {
VkStructureType sType;
void* pNext;
uint32_t copySrcLayoutCount;
VkImageLayout* pCopySrcLayouts;
uint32_t copyDstLayoutCount;
VkImageLayout* pCopyDstLayouts;
uint8_t optimalTilingLayoutUUID[VK_UUID_SIZE];
VkBool32 identicalMemoryTypeRequirements;
} VkPhysicalDeviceHostImageCopyProperties;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkPhysicalDeviceHostImageCopyProperties VkPhysicalDeviceHostImageCopyPropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
copySrcLayoutCountis an integer related to the number of image layouts for host copies from images available or queried, as described below. -
pCopySrcLayoutsis a pointer to an array of VkImageLayout in which supported image layouts for use with host copy operations from images are returned. -
copyDstLayoutCountis an integer related to the number of image layouts for host copies to images available or queried, as described below. -
pCopyDstLayoutsis a pointer to an array of VkImageLayout in which supported image layouts for use with host copy operations to images are returned. -
optimalTilingLayoutUUIDis an array ofVK_UUID_SIZEuint8_tvalues representing a universally unique identifier for the implementation’s swizzling layout of images created withVK_IMAGE_TILING_OPTIMAL. -
identicalMemoryTypeRequirementsindicates that specifying theVK_IMAGE_USAGE_HOST_TRANSFER_BITflag in VkImageCreateInfo::usagedoes not affect the memory type requirements of the image.
If the VkPhysicalDeviceHostImageCopyProperties 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 pCopyDstLayouts is NULL, then the number of image layouts that
are supported in VkCopyMemoryToImageInfo::dstImageLayout and
VkCopyImageToImageInfo::dstImageLayout is returned in
copyDstLayoutCount.
Otherwise, copyDstLayoutCount must be set by the application to the
number of elements in the pCopyDstLayouts array, and on return the
variable is overwritten with the number of values actually written to
pCopyDstLayouts.
If the value of copyDstLayoutCount is less than the number of image
layouts that are supported, at most copyDstLayoutCount values will be
written to pCopyDstLayouts.
The implementation must include the VK_IMAGE_LAYOUT_GENERAL image
layout in pCopyDstLayouts.
If the unifiedImageLayouts feature
is enabled, the implementation must include all the image layouts that are
interchangeable with VK_IMAGE_LAYOUT_GENERAL in pCopyDstLayouts.
If pCopySrcLayouts is NULL, then the number of image layouts that
are supported in VkCopyImageToMemoryInfo::srcImageLayout and
VkCopyImageToImageInfo::srcImageLayout is returned in
copySrcLayoutCount.
Otherwise, copySrcLayoutCount must be set by the application to the
number of elements in the pCopySrcLayouts array, and on return the
variable is overwritten with the number of values actually written to
pCopySrcLayouts.
If the value of copySrcLayoutCount is less than the number of image
layouts that are supported, at most copySrcLayoutCount values will be
written to pCopySrcLayouts.
The implementation must include the VK_IMAGE_LAYOUT_GENERAL image
layout in pCopySrcLayouts.
If the unifiedImageLayouts feature
is enabled, the implementation must include all the image layouts that are
interchangeable with VK_IMAGE_LAYOUT_GENERAL in pCopySrcLayouts.
The optimalTilingLayoutUUID value can be used to ensure compatible
data layouts when using the VK_HOST_IMAGE_COPY_MEMCPY_BIT flag in
vkCopyMemoryToImage and vkCopyImageToMemory.
The VkPhysicalDeviceSubpassShadingPropertiesHUAWEI structure is
defined as:
// Provided by VK_HUAWEI_subpass_shading
typedef struct VkPhysicalDeviceSubpassShadingPropertiesHUAWEI {
VkStructureType sType;
void* pNext;
uint32_t maxSubpassShadingWorkgroupSizeAspectRatio;
} VkPhysicalDeviceSubpassShadingPropertiesHUAWEI;
-
sTypeis a VkStructureType value identifying 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 VkPhysicalDeviceNestedCommandBufferPropertiesEXT structure is
defined as:
// Provided by VK_EXT_nested_command_buffer
typedef struct VkPhysicalDeviceNestedCommandBufferPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t maxCommandBufferNestingLevel;
} VkPhysicalDeviceNestedCommandBufferPropertiesEXT;
The members of the VkPhysicalDeviceNestedCommandBufferPropertiesEXT
structure describe the following features:
-
maxCommandBufferNestingLevelindicates the maximum nesting level of calls to vkCmdExecuteCommands from Secondary Command Buffers. AmaxCommandBufferNestingLevelofUINT32_MAXmeans there is no limit to the nesting level.
If the VkPhysicalDeviceNestedCommandBufferPropertiesEXT 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;
-
When the provoking vertex mode is
VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, and the primitive order is odd in a triangle strip, the ordering of vertices is defined in last vertex table.triStripVertexOrderIndependentOfProvokingVertexequal toVK_TRUEindicates that the implementation ignores this and uses the vertex order defined byVK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXTinstead.
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 VkPhysicalDevicePipelineRobustnessProperties structure is defined
as:
// Provided by VK_VERSION_1_4
typedef struct VkPhysicalDevicePipelineRobustnessProperties {
VkStructureType sType;
void* pNext;
VkPipelineRobustnessBufferBehavior defaultRobustnessStorageBuffers;
VkPipelineRobustnessBufferBehavior defaultRobustnessUniformBuffers;
VkPipelineRobustnessBufferBehavior defaultRobustnessVertexInputs;
VkPipelineRobustnessImageBehavior defaultRobustnessImages;
} VkPhysicalDevicePipelineRobustnessProperties;
or the equivalent
// Provided by VK_EXT_pipeline_robustness
typedef VkPhysicalDevicePipelineRobustnessProperties VkPhysicalDevicePipelineRobustnessPropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure.
-
defaultRobustnessStorageBuffersdescribes the behavior of out of bounds accesses made to storage buffers when no robustness features are enabled -
defaultRobustnessUniformBuffersdescribes the behavior of out of bounds accesses made to uniform buffers when no robustness features are enabled -
defaultRobustnessVertexInputsdescribes the behavior of out of bounds accesses made to vertex input attributes when no robustness features are enabled -
defaultRobustnessImagesdescribes the behavior 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 VkPhysicalDevicePipelineRobustnessProperties 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 VkPhysicalDeviceExtendedDynamicState3PropertiesEXT structure is
defined as:
// Provided by VK_EXT_extended_dynamic_state3
typedef struct VkPhysicalDeviceExtendedDynamicState3PropertiesEXT {
VkStructureType sType;
void* pNext;
VkBool32 dynamicPrimitiveTopologyUnrestricted;
} VkPhysicalDeviceExtendedDynamicState3PropertiesEXT;
-
dynamicPrimitiveTopologyUnrestrictedindicates that the implementation allowsvkCmdSetPrimitiveTopologyto use a different primitive topology class to the one specified in the active graphics pipeline.
If the VkPhysicalDeviceExtendedDynamicState3PropertiesEXT 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 VkPhysicalDeviceOpticalFlowPropertiesNV structure is defined as:
// Provided by VK_NV_optical_flow
typedef struct VkPhysicalDeviceOpticalFlowPropertiesNV {
VkStructureType sType;
void* pNext;
VkOpticalFlowGridSizeFlagsNV supportedOutputGridSizes;
VkOpticalFlowGridSizeFlagsNV supportedHintGridSizes;
VkBool32 hintSupported;
VkBool32 costSupported;
VkBool32 bidirectionalFlowSupported;
VkBool32 globalFlowSupported;
uint32_t minWidth;
uint32_t minHeight;
uint32_t maxWidth;
uint32_t maxHeight;
uint32_t maxNumRegionsOfInterest;
} VkPhysicalDeviceOpticalFlowPropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
supportedOutputGridSizesare the supported VkOpticalFlowGridSizeFlagsNV which can be specified inVkOpticalFlowSessionCreateInfoNV::outputGridSize. -
supportedHintGridSizesare the supported VkOpticalFlowGridSizeFlagsNV which can be specified inVkOpticalFlowSessionCreateInfoNV::hintGridSize. -
hintSupportedis a boolean describing whether using hint flow vector map is supported in an optical flow session. -
costSupportedis a boolean describing whether cost map generation is supported in an optical flow session. -
bidirectionalFlowSupportedis a boolean describing whether bi-directional flow generation is supported in an optical flow session. -
globalFlowSupportedis a boolean describing whether global flow vector map generation is supported in an optical flow session. -
minWidthis the minimum width in pixels for images used in an optical flow session. -
minHeightis the minimum height in pixels for images used in an optical flow session. -
maxWidthis the maximum width in pixels for images used in an optical flow session. -
maxHeightis the maximum height in pixels for images used in an optical flow session. -
maxNumRegionsOfInterestis the maximum number of regions of interest which can be used in an optical flow session. If thismaxNumRegionsOfInterestis 0, regions of interest are not supported in an optical flow session.
If the VkPhysicalDeviceOpticalFlowPropertiesNV 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 VkPhysicalDeviceOpacityMicromapPropertiesEXT structure is defined
as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkPhysicalDeviceOpacityMicromapPropertiesEXT {
VkStructureType sType;
void* pNext;
uint32_t maxOpacity2StateSubdivisionLevel;
uint32_t maxOpacity4StateSubdivisionLevel;
} VkPhysicalDeviceOpacityMicromapPropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxOpacity2StateSubdivisionLevelis the maximum allowedsubdivisionLevelwhenformatisVK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT -
maxOpacity4StateSubdivisionLevelis the maximum allowedsubdivisionLevelwhenformatisVK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT
If the VkPhysicalDeviceOpacityMicromapPropertiesEXT 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 VkPhysicalDeviceDisplacementMicromapPropertiesNV structure is
defined as:
// Provided by VK_NV_displacement_micromap
typedef struct VkPhysicalDeviceDisplacementMicromapPropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t maxDisplacementMicromapSubdivisionLevel;
} VkPhysicalDeviceDisplacementMicromapPropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxDisplacementMicromapSubdivisionLevelis the maximum allowedsubdivisionLevelfor displacement micromaps.
If the VkPhysicalDeviceDisplacementMicromapPropertiesNV 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 VkPhysicalDeviceShaderCoreBuiltinsPropertiesARM structure is
defined as:
// Provided by VK_ARM_shader_core_builtins
typedef struct VkPhysicalDeviceShaderCoreBuiltinsPropertiesARM {
VkStructureType sType;
void* pNext;
uint64_t shaderCoreMask;
uint32_t shaderCoreCount;
uint32_t shaderWarpsPerCore;
} VkPhysicalDeviceShaderCoreBuiltinsPropertiesARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderCoreMaskis a bitfield where each bit set represents the presence of a shader core whose ID is the bit position. The highest ID for any shader core on the device is the position of the most significant bit set. -
shaderCoreCountis the number of shader cores on the device. -
shaderWarpsPerCoreis the maximum number of simultaneously executing warps on a shader core.
If the VkPhysicalDeviceShaderCoreBuiltinsPropertiesARM 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
rayTracingInvocationReorderReorderingHint field of
VkPhysicalDeviceRayTracingInvocationReorderPropertiesNV are:
// Provided by VK_NV_ray_tracing_invocation_reorder
typedef enum VkRayTracingInvocationReorderModeNV {
VK_RAY_TRACING_INVOCATION_REORDER_MODE_NONE_NV = 0,
VK_RAY_TRACING_INVOCATION_REORDER_MODE_REORDER_NV = 1,
} VkRayTracingInvocationReorderModeNV;
-
VK_RAY_TRACING_INVOCATION_REORDER_MODE_NONE_NVspecifies that the implementation is likely to not reorder at reorder calls. -
VK_RAY_TRACING_INVOCATION_REORDER_MODE_REORDER_NVspecifies that the implementation is likely to reorder at reorder calls.
The VkPhysicalDeviceRayTracingInvocationReorderPropertiesNV structure
is defined as:
// Provided by VK_NV_ray_tracing_invocation_reorder
typedef struct VkPhysicalDeviceRayTracingInvocationReorderPropertiesNV {
VkStructureType sType;
void* pNext;
VkRayTracingInvocationReorderModeNV rayTracingInvocationReorderReorderingHint;
} VkPhysicalDeviceRayTracingInvocationReorderPropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
rayTracingInvocationReorderReorderingHintis a hint indicating if the implementation will actually reorder at the reorder calls.
|
Note
|
Because the extension changes how hits are managed there is a compatibility reason to expose the extension even when an implementation does not have sorting active. |
If the VkPhysicalDeviceRayTracingInvocationReorderPropertiesNV 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 VkPhysicalDeviceClusterCullingShaderPropertiesHUAWEI structure is
defined as:
// Provided by VK_HUAWEI_cluster_culling_shader
typedef struct VkPhysicalDeviceClusterCullingShaderPropertiesHUAWEI {
VkStructureType sType;
void* pNext;
uint32_t maxWorkGroupCount[3];
uint32_t maxWorkGroupSize[3];
uint32_t maxOutputClusterCount;
VkDeviceSize indirectBufferOffsetAlignment;
} VkPhysicalDeviceClusterCullingShaderPropertiesHUAWEI;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxWorkGroupCount[3] is the maximum number of local workgroups that can be launched by a single command. These three value represent the maximum local workgroup count in the X, Y and Z dimensions, respectively. In the current implementation, the values of Y and Z are both implicitly set as one. groupCountX of DrawCluster command must be less than or equal to maxWorkGroupCount[0]. -
maxWorkGroupSize[3] is the maximum size of a local workgroup. These three value represent the maximum local workgroup size in the X, Y and Z dimensions, respectively. The x, y and z sizes, as specified by theLocalSizeorLocalSizeIdexecution mode or by the object decorated by the WorkgroupSize decoration in shader modules, must be less than or equal to the corresponding limit. In the current implementation, the maximum workgroup size of the X dimension is 32, the others are 1. -
maxOutputClusterCountis the maximum number of output cluster a single cluster culling shader workgroup can emit. -
indirectBufferOffsetAlignmentindicates the alignment for cluster drawing command buffer stride. vkCmdDrawClusterIndirectHUAWEI::offsetmust be a multiple of this value.
If the VkPhysicalDeviceClusterCullingShaderPropertiesHUAWEI 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 VkPhysicalDeviceShaderCorePropertiesARM structure is defined as:
// Provided by VK_ARM_shader_core_properties
typedef struct VkPhysicalDeviceShaderCorePropertiesARM {
VkStructureType sType;
void* pNext;
uint32_t pixelRate;
uint32_t texelRate;
uint32_t fmaRate;
} VkPhysicalDeviceShaderCorePropertiesARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pixelRateis an unsigned integer value indicating the maximum number of pixels output per clock per shader core. -
texelRateis an unsigned integer value indicating the maximum number of texels per clock per shader core. -
fmaRateis an unsigned integer value indicating the maximum number of single-precision fused multiply-add operations per clock per shader core.
If a throughput rate cannot be determined on the physical device, the value
0 will be returned for that rate.
If the VkPhysicalDeviceShaderCorePropertiesARM 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 VkPhysicalDeviceShaderObjectPropertiesEXT structure is defined as:
// Provided by VK_EXT_shader_object
typedef struct VkPhysicalDeviceShaderObjectPropertiesEXT {
VkStructureType sType;
void* pNext;
uint8_t shaderBinaryUUID[VK_UUID_SIZE];
uint32_t shaderBinaryVersion;
} VkPhysicalDeviceShaderObjectPropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
shaderBinaryUUIDis an array ofVK_UUID_SIZEuint8_tvalues representing a universally unique identifier for one or more implementations whose shader binaries are guaranteed to be compatible with each other. -
shaderBinaryVersionis an unsigned integer incremented to represent backwards compatible differences between implementations with the sameshaderBinaryUUID.
The purpose and usage of the values of this structure are described in greater detail in Binary Shader Compatibility.
If the VkPhysicalDeviceShaderObjectPropertiesEXT 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 VkPhysicalDeviceShaderEnqueuePropertiesAMDX structure is defined
as:
// Provided by VK_AMDX_shader_enqueue
typedef struct VkPhysicalDeviceShaderEnqueuePropertiesAMDX {
VkStructureType sType;
void* pNext;
uint32_t maxExecutionGraphDepth;
uint32_t maxExecutionGraphShaderOutputNodes;
uint32_t maxExecutionGraphShaderPayloadSize;
uint32_t maxExecutionGraphShaderPayloadCount;
uint32_t executionGraphDispatchAddressAlignment;
uint32_t maxExecutionGraphWorkgroupCount[3];
uint32_t maxExecutionGraphWorkgroups;
} VkPhysicalDeviceShaderEnqueuePropertiesAMDX;
The members of the VkPhysicalDeviceShaderEnqueuePropertiesAMDX
structure describe the following limits:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxExecutionGraphDepthdefines the maximum node chain depth in the graph. The dispatched node is at depth 1 and the node enqueued by it is at depth 2, and so on. If a node enqueues itself, each recursive enqueue increases the depth by 1 as well. -
maxExecutionGraphShaderOutputNodesspecifies the maximum number of unique nodes that can be dispatched from a single shader, and must be at least 256. -
maxExecutionGraphShaderPayloadSizespecifies the maximum total size of payload declarations in a shader. For any payload declarations that share resources, indicated byNodeSharesPayloadLimitsWithAMDXdecorations, the maximum size of each set of shared payload declarations is taken. The sum of each shared set’s maximum size and the size of each unshared payload is counted against this limit. -
maxExecutionGraphShaderPayloadCountspecifies the maximum number of output payloads that can be initialized in a single workgroup. -
executionGraphDispatchAddressAlignmentspecifies the alignment of non-scratch VkDeviceAddress arguments consumed by graph dispatch commands. -
maxExecutionGraphWorkgroupCount[3] is the maximum number of local workgroups that a shader can be dispatched with in X, Y, and Z dimensions, respectively. -
maxExecutionGraphWorkgroupsis the total number of local workgroups that a shader can be dispatched with.
If the VkPhysicalDeviceShaderEnqueuePropertiesAMDX 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 VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV structure
is defined as:
// Provided by VK_NV_extended_sparse_address_space
typedef struct VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV {
VkStructureType sType;
void* pNext;
VkDeviceSize extendedSparseAddressSpaceSize;
VkImageUsageFlags extendedSparseImageUsageFlags;
VkBufferUsageFlags extendedSparseBufferUsageFlags;
} VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
extendedSparseAddressSpaceSizeis the total amount of address space available, in bytes, for sparse memory resources of all usages if theextendedSparseAddressSpacefeature is enabled. This must be greater than or equal toVkPhysicalDeviceLimits::sparseAddressSpaceSize, and the difference in space must only be used with usages allowed below. This is an upper bound on the sum of the sizes of all sparse resources, regardless of whether any memory is bound to them. -
extendedSparseImageUsageFlagsis a bitmask of VkImageUsageFlagBits of usages which may allow an implementation to use the fullextendedSparseAddressSpaceSizespace. -
extendedSparseBufferUsageFlagsis a bitmask of VkBufferUsageFlagBits of usages which may allow an implementation to use the fullextendedSparseAddressSpaceSizespace.
If the VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV 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 VkPhysicalDeviceCudaKernelLaunchPropertiesNV structure is defined
as:
// Provided by VK_NV_cuda_kernel_launch
typedef struct VkPhysicalDeviceCudaKernelLaunchPropertiesNV {
VkStructureType sType;
void* pNext;
uint32_t computeCapabilityMinor;
uint32_t computeCapabilityMajor;
} VkPhysicalDeviceCudaKernelLaunchPropertiesNV;
The members of the VkPhysicalDeviceCudaKernelLaunchPropertiesNV
structure describe the following features:
If the VkPhysicalDeviceCudaKernelLaunchPropertiesNV 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 VkPhysicalDeviceExternalFormatResolvePropertiesANDROID structure
is defined as:
// Provided by VK_ANDROID_external_format_resolve
typedef struct VkPhysicalDeviceExternalFormatResolvePropertiesANDROID {
VkStructureType sType;
void* pNext;
VkBool32 nullColorAttachmentWithExternalFormatResolve;
VkChromaLocation externalFormatResolveChromaOffsetX;
VkChromaLocation externalFormatResolveChromaOffsetY;
} VkPhysicalDeviceExternalFormatResolvePropertiesANDROID;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
nullColorAttachmentWithExternalFormatResolveindicates that there must be no color attachment image when performing external format resolves if it isVK_TRUE. -
externalFormatResolveChromaOffsetXindicates the VkChromaLocation that an implementation uses in the X axis for accesses to an external format image as a resolve attachment. This must be consistent between external format resolves and load operations from external format resolve attachments to color attachments whennullColorAttachmentWithExternalFormatResolveisVK_TRUE. -
externalFormatResolveChromaOffsetYindicates the VkChromaLocation that an implementation uses in the Y axis for accesses to an external format image as a resolve attachment. This must be consistent between external format resolves and load operations from external format resolve attachments to color attachments whennullColorAttachmentWithExternalFormatResolveisVK_TRUE.
If the VkPhysicalDeviceExternalFormatResolvePropertiesANDROID 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 VkPhysicalDevicePipelineBinaryPropertiesKHR structure is defined
as:
// Provided by VK_KHR_pipeline_binary
typedef struct VkPhysicalDevicePipelineBinaryPropertiesKHR {
VkStructureType sType;
void* pNext;
VkBool32 pipelineBinaryInternalCache;
VkBool32 pipelineBinaryInternalCacheControl;
VkBool32 pipelineBinaryPrefersInternalCache;
VkBool32 pipelineBinaryPrecompiledInternalCache;
VkBool32 pipelineBinaryCompressedData;
} VkPhysicalDevicePipelineBinaryPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pipelineBinaryInternalCachespecifies that the implementation maintains a pipeline cache internal to the implementation. If this isVK_TRUE, applications can create pipeline binaries with only a pipeline create info, and in this case, an implementation may be able to create a pipeline binary directly without application needing to capture the binary itself. -
pipelineBinaryInternalCacheControlspecifies whether the driver’s internal cache can be disabled. If this property isVK_TRUEVkDevicePipelineBinaryInternalCacheControlKHR::disableInternalCachecan be used to disable the driver’s internal cache, allowing an application to take full control of both memory and disk usage. -
pipelineBinaryPrefersInternalCachespecifies that the implementation prefers to maintain an internal cache, and applications should not store pipeline binaries in their own on-disk caches to avoid increased on-disk storage requirements. Applications are encouraged to only store pipeline keys instead, and aim to create pipeline binaries from key alone on subsequent runs of the application. -
pipelineBinaryPrecompiledInternalCachespecifies that the implementation may have pipeline binaries in its internal cache, which is populated without the application ever having generated that pipeline itself. Applications can attempt to create binaries without extracting pipeline binary data from the pipeline prior for a set of pipeline keys, including from previous runs of the application. -
pipelineBinaryCompressedDataspecifies that the binary data is already compressed and so applications should not attempt to compress it.
|
Note
|
These properties tend to be platform specific and may change depending on
external configuration which is outside the scope of this specification.
These properties are intended to guide applications when implementations
have dedicated caching solutions available.
In particular, if the |
If the VkPhysicalDevicePipelineBinaryPropertiesKHR 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 VkPhysicalDeviceRenderPassStripedPropertiesARM structure is
defined as:
// Provided by VK_ARM_render_pass_striped
typedef struct VkPhysicalDeviceRenderPassStripedPropertiesARM {
VkStructureType sType;
void* pNext;
VkExtent2D renderPassStripeGranularity;
uint32_t maxRenderPassStripes;
} VkPhysicalDeviceRenderPassStripedPropertiesARM;
The members of the VkPhysicalDeviceRenderPassStripedPropertiesARM
structure describe the following limits:
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
renderPassStripeGranularityindicates the minimum supported granularity of striped render pass regions. -
maxRenderPassStripesindicates the maximum number of stripes supported in striped rendering.
If the VkPhysicalDeviceRenderPassStripedPropertiesARM 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 VkPhysicalDeviceComputeShaderDerivativesPropertiesKHR structure is
defined as:
// Provided by VK_KHR_compute_shader_derivatives
typedef struct VkPhysicalDeviceComputeShaderDerivativesPropertiesKHR {
VkStructureType sType;
void* pNext;
VkBool32 meshAndTaskShaderDerivatives;
} VkPhysicalDeviceComputeShaderDerivativesPropertiesKHR;
The members of the
VkPhysicalDeviceComputeShaderDerivativesPropertiesKHR structure
describe the following:
If the VkPhysicalDeviceComputeShaderDerivativesPropertiesKHR 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 VkPhysicalDeviceMapMemoryPlacedPropertiesEXT structure is defined
as:
// Provided by VK_EXT_map_memory_placed
typedef struct VkPhysicalDeviceMapMemoryPlacedPropertiesEXT {
VkStructureType sType;
void* pNext;
VkDeviceSize minPlacedMemoryMapAlignment;
} VkPhysicalDeviceMapMemoryPlacedPropertiesEXT;
The members of the VkPhysicalDeviceMapMemoryPlacedPropertiesEXT
structure describe the following:
If the VkPhysicalDeviceMapMemoryPlacedPropertiesEXT 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 VkPhysicalDeviceImageAlignmentControlPropertiesMESA structure is
defined as:
// Provided by VK_MESA_image_alignment_control
typedef struct VkPhysicalDeviceImageAlignmentControlPropertiesMESA {
VkStructureType sType;
void* pNext;
uint32_t supportedImageAlignmentMask;
} VkPhysicalDeviceImageAlignmentControlPropertiesMESA;
The members of the VkPhysicalDeviceImageAlignmentControlPropertiesMESA
structure describe the following:
-
supportedImageAlignmentMaskis a bitwise-or of all potentially supported image alignments for a given physical device when usingVK_IMAGE_TILING_OPTIMAL. If a given alignment is supported, the application can request an image to have that alignment. A given set of image creation parameters may support a subset of these alignments. To determine if a particular alignment is supported for a given set of image creation parameters, check VkMemoryRequirements::alignmentafter chaining in VkImageAlignmentControlCreateInfoMESA.
If the VkPhysicalDeviceImageAlignmentControlPropertiesMESA 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 VkPhysicalDeviceTileShadingPropertiesQCOM structure is defined as:
// Provided by VK_QCOM_tile_shading
typedef struct VkPhysicalDeviceTileShadingPropertiesQCOM {
VkStructureType sType;
void* pNext;
uint32_t maxApronSize;
VkBool32 preferNonCoherent;
VkExtent2D tileGranularity;
VkExtent2D maxTileShadingRate;
} VkPhysicalDeviceTileShadingPropertiesQCOM;
-
sTypeis a VkStructureType value identifying this structure -
pNextisNULLor a pointer to a structure extending this structure. -
maxApronSizeis the maximum value supported which can be specified for VkRenderPassTileShadingCreateInfoQCOM::apronSizeorwidthandheight. -
preferNonCoherentindicates that the implementation prefers tile attachments declared in shaders with theNonCoherentTileAttachmentReadQCOMdecoration. Use of the decoration may offer performance or power advantages. -
tileGranularityprovides a guarantee on the granularity of each tile. Each tile will have dimensions that are a multiple of this granularity in width and height. -
maxTileShadingRateis the maximum value ofTileShadingRateQCOMand must be a power of 2.
If the VkPhysicalDeviceTileShadingPropertiesQCOM 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 VkPhysicalDeviceTensorPropertiesARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkPhysicalDeviceTensorPropertiesARM {
VkStructureType sType;
void* pNext;
uint32_t maxTensorDimensionCount;
uint64_t maxTensorElements;
uint64_t maxPerDimensionTensorElements;
int64_t maxTensorStride;
uint64_t maxTensorSize;
uint32_t maxTensorShaderAccessArrayLength;
uint32_t maxTensorShaderAccessSize;
uint32_t maxDescriptorSetStorageTensors;
uint32_t maxPerStageDescriptorSetStorageTensors;
uint32_t maxDescriptorSetUpdateAfterBindStorageTensors;
uint32_t maxPerStageDescriptorUpdateAfterBindStorageTensors;
VkBool32 shaderStorageTensorArrayNonUniformIndexingNative;
VkShaderStageFlags shaderTensorSupportedStages;
} VkPhysicalDeviceTensorPropertiesARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxTensorDimensionCountis the maximum number of dimensions that can be specified in thedimensionCountmember of VkTensorDescriptionARM. -
maxTensorElementsis the maximum number of data elements in a created tensor as specified in the VkTensorDescriptionARM of VkTensorCreateInfoARM. The number of data elements in a tensor is computed as the product ofpDimensions[i] for all 0 ≤ i ≤ dimensionCount-1. -
maxPerDimensionTensorElementsis the maximum number of data elements alongside any dimension of a tensor. -
maxTensorStrideis the maximum value for a tensor stride that can be used in VkTensorDescriptionARM::pStrides. -
maxTensorShaderAccessArrayLengthis the maximum number of elements in an array returned byOpTensoReadARMor consumed byOpTensorWriteARM. -
maxTensorShaderAccessSizeis the maximum size in bytes of the data that can be read from a tensor withOpTensorReadARMor written to a tensor withOpTensorWriteARM. -
maxDescriptorSetStorageTensorsis the maximum number of tensors that can be included in descriptor bindings in a pipeline layout across all pipeline shader stages and descriptor set numbers. Descriptors with a type ofVK_DESCRIPTOR_TYPE_TENSOR_ARMcount against this limit. -
maxPerStageDescriptorSetStorageTensorsis the maximum number of tensors that can be accessible to a single shader stage in a pipeline layout. Descriptors with a type ofVK_DESCRIPTOR_TYPE_TENSOR_ARMcount against this limit. A descriptor is accessible to a pipeline shader stage when thestageFlagsmember of the VkDescriptorSetLayoutBinding structure has the bit for that shader stage set. -
maxDescriptorSetUpdateAfterBindStorageTensorsis similar tomaxDescriptorSetStorageTensorsbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
maxPerStageDescriptorUpdateAfterBindStorageTensorsis similar tomaxPerStageDescriptorSetStorageTensorsbut counts descriptors from descriptor sets created with or without theVK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BITbit set. -
shaderStorageTensorArrayNonUniformIndexingNativeis a boolean value indicating whether storage tensor 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. -
shaderTensorSupportedStagesis a bitfield of VkShaderStageFlagBits describing the shader stages that can access tensor resources.shaderTensorSupportedStageswill have theVK_SHADER_STAGE_COMPUTE_BITbit set if any of the physical device’s queues supportVK_QUEUE_COMPUTE_BIT.
If the VkPhysicalDeviceTensorPropertiesARM structure is included in the pNext chain of the
VkPhysicalDeviceProperties2 structure passed to
vkGetPhysicalDeviceProperties2, it is filled in with each
corresponding implementation-dependent property.
50.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 × |
|
|
|
|
|
|
|
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
||
|
||
|
||
|
|
|
|
||
|
|
|
|
||
|
|
|
|
||
|
||
|
|
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Vulkan 1.4, VK_KHR_vertex_attribute_divisor, VK_EXT_vertex_attribute_divisor |
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
3 × |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
3 × |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesNV:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
3 × |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
3 × |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
3 × |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
3 × |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
|
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
||
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
||
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
||
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
||
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Vulkan 1.4, VK_KHR_line_rasterization, VK_EXT_line_rasterization |
|
|
|
|
||
|
||
2 × |
|
|
2 × |
|
|
|
|
|
|
||
|
||
|
||
2 × |
|
|
|
|
|
|
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
||
|
||
|
||
|
||
|
|
|
|
|
|
|
||
|
||
|
- |
|
|
|
|
2 × |
|
|
2 × |
|
|
2 × |
|
|
|
||
|
|
|
|
|
|
|
|
|
3 × |
|
|
3 × |
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3 × |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
- |
|
|
- |
|
|
|
|
|
||
2 × |
|
|
2 × |
|
| Limit | Unsupported Limit | Supported Limit | Limit Type1 |
|---|---|---|---|
|
- |
4096 (Vulkan Core) |
min |
|
- |
4096 (Vulkan Core) |
min |
|
- |
256 (Vulkan Core) |
min |
|
- |
4096 (Vulkan Core) |
min |
|
- |
256 (Vulkan Core) |
min |
|
- |
65536 |
min |
|
- |
16384 (Vulkan Core) |
min |
|
- |
227 |
min |
|
- |
128 (Vulkan Core) |
min |
|
- |
4096 |
min |
|
- |
4000 |
min |
|
- |
131072 (Vulkan Core) |
max |
|
0 |
231 |
min |
|
- |
4 (Vulkan Core) |
min |
|
- |
16 |
min |
|
- |
12 (Vulkan Core) |
min |
|
- |
4 (Vulkan Core) |
min |
|
- |
16 (Vulkan Core) |
min |
|
- |
4 (Vulkan Core) |
min |
|
- |
4 |
min |
|
- |
128 2 (Vulkan Core) |
min |
|
- |
96 8 (Vulkan Core) |
min, n × PerStage |
|
- |
72 8 (Vulkan Core) |
min, n × PerStage |
|
- |
8 |
min |
|
- |
24 8 (Vulkan Core) |
min, n × PerStage |
|
- |
4 |
min |
|
- |
|
min |
|
- |
|
min |
|
- |
|
min |
|
- |
96 8 (Vulkan Core) |
min, n × PerStage |
|
- |
24 8 (Vulkan Core) |
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 (Vulkan Core) |
min |
|
- |
16384 |
min |
|
- |
(65535,65535,65535) |
min |
|
- |
128 (Vulkan Core) |
min |
|
- |
(128,128,64) (Vulkan Core) |
min |
|
- |
1/4 (Vulkan Core) |
min |
|
- |
|
bitfield |
|
- |
|
bitfield |
|
- |
- (Vulkan Core) |
Boolean |
|
- |
- (Vulkan Core) |
Boolean |
|
- |
|
Boolean |
|
- |
|
Boolean |
|
- |
- (Vulkan Core) |
min |
|
- |
4 |
min |
|
- |
4 (Vulkan Core) |
min |
|
- |
4 (Vulkan Core) |
min |
|
224-1 |
232-1 |
min |
|
1 |
216-1 |
min |
|
- |
2 (Vulkan Core) |
min |
|
1 |
16 |
min |
|
1 |
16 |
min |
|
- |
(4096,4096) (Vulkan Core) |
min |
|
- |
(-8192,8191) (Vulkan Core) |
(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 (Vulkan Core) |
min |
|
- |
4096 (Vulkan Core) |
min |
|
- |
256 |
min |
|
- |
( |
min |
|
- |
( |
min |
|
- |
( |
min |
|
- |
( |
min |
|
- |
( |
min |
|
- |
4 (Vulkan Core) |
min |
|
- |
( |
min |
|
- |
|
min |
|
- |
( |
min |
|
- |
( |
min |
|
|
( |
min |
|
- |
1 |
min |
|
- |
- (Vulkan Core) |
Boolean |
|
- |
- |
duration |
|
0 |
8 |
min |
|
0 |
8 |
min |
|
0 |
8 |
min |
|
- |
2 |
min |
|
(1.0,1.0) |
(1.0,64.0 - ULP) 6 (Vulkan Core) |
(max,min) |
|
(1.0,1.0) |
(1.0,8.0 - ULP) 7 |
(max,min) |
|
0.0 |
1.0 6 (Vulkan Core) |
max, fixed point increment |
|
0.0 |
1.0 7 (Vulkan Core) |
max, fixed point increment |
|
- |
- |
implementation-dependent |
|
- |
- (Vulkan Core) |
Boolean |
|
- |
- |
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 |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
65536 |
max |
|
- |
- |
implementation-dependent |
|
- |
- |
implementation-dependent |
|
- |
- |
implementation-dependent |
|
- |
1 |
min |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
1024 |
min |
|
- |
230 |
min |
|
- |
230 |
min |
|
- |
0.0 |
min |
|
- |
0.0 |
min |
|
- |
0.0 |
min |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
0 |
500000 |
min |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
0 9 |
500000 9 |
min |
|
0 9 |
12 9 |
min |
|
0 9 |
500000 9 |
min |
|
0 9 |
500000 9 |
min |
|
0 9 |
500000 9 |
min |
|
0 9 |
4 9 (Vulkan Core) |
min |
|
0 9 |
500000 9 |
min |
|
0 9 |
500000 9 |
min |
|
0 9 |
72 8 9 |
min, n × PerStage |
|
0 9 |
8 9 |
min |
|
0 9 |
500000 9 |
min |
|
0 9 |
4 9 |
min |
|
0 9 |
|
min |
|
0 9 |
|
min |
|
0 9 |
|
min |
|
0 9 |
500000 9 |
min |
|
0 9 |
500000 9 |
min |
|
0 9 |
4 9 |
min |
|
- |
256 |
min |
|
- |
4 |
min |
|
- |
4 |
min |
|
- |
4 |
min |
|
- |
4 |
min |
|
- |
256 |
min |
|
- |
216-1 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
216-1 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
32 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
(32,1,1) |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
16384 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
216-1 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
32 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
(32,1,1) |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
16384 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
256 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
256 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
1 |
min |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
- |
implementation-dependent |
VkPhysicalDeviceMeshShaderPropertiesNV:: |
- |
- |
implementation-dependent |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
2^22 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
(65535,65535,65535) |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
128 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
(128,128,128) |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
16384 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
32768 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
32768 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
2^22 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
(65535,65535,65535) |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
128 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
(128,128,128) |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
28672 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
28672 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
32768 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
48128 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
128 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
256 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
256 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
8 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
1 |
min |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
0 |
32 |
max |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
0 |
32 |
max |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
- |
implementation-dependent |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
- |
implementation-dependent |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
- |
implementation-dependent |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
- |
implementation-dependent |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
- |
implementation-dependent |
VkPhysicalDeviceMeshShaderPropertiesEXT:: |
- |
- |
implementation-dependent |
|
- |
1 |
min |
|
- |
1 |
min |
|
- |
227 |
min |
|
- |
512 |
min |
|
- |
512 |
min |
|
- |
512 |
min |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
(1,1) |
min |
|
- |
(1,1) |
min |
|
- |
- |
implementation-dependent |
|
|
|
implementation-dependent |
|
|
|
implementation-dependent |
|
2 |
2 |
min |
|
1 |
1 |
min |
|
- |
(1024,1024) |
max |
|
- |
(2) |
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 |
|
- |
256 |
min |
|
- |
256 |
min |
|
- |
256 |
max |
|
- |
128 |
max |
|
- |
32 |
max |
|
- |
256 |
max |
|
- |
32 |
max |
|
- |
224-1 |
min |
|
- |
16 |
min |
|
- |
500000 9 |
min |
|
- |
256 |
max |
|
- |
64 |
max |
|
- |
230 |
min |
|
- |
32 |
max |
|
- |
32 |
min |
|
- |
224-1 |
min |
|
- |
231-1 |
min |
|
- |
4 |
min |
|
- |
212 |
min |
|
- |
212 |
min |
|
- |
2048 |
min |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
220 |
min |
|
- |
16 |
min |
|
- |
2047 |
min |
|
- |
212 |
min |
|
- |
false |
implementation-dependent |
|
- |
false |
implementation-dependent |
|
0 |
212 |
implementation-dependent |
|
- |
2048 |
min |
|
- |
|
min |
|
- |
( |
min |
|
- |
0 |
min |
|
- |
0 |
min |
|
- |
32 |
min |
|
- |
4 |
max |
|
- |
256 |
max |
|
(0,0) |
(32,32) |
max |
|
(0,0) |
(8,8) |
min |
|
0 |
1 |
min |
|
|
|
implementation-dependent |
|
|
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
(2,2) |
min |
|
- |
2 |
min |
|
- |
16 |
min |
|
- |
|
min |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
min |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
256 |
max |
|
- |
3 |
min |
|
- |
1 |
min |
|
- |
1 |
min |
|
- |
1 |
min |
|
- |
2032 |
min |
|
- |
64 |
max |
|
- |
64 |
max |
|
- |
64 |
max |
|
- |
64 |
max |
|
- |
64 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
256 |
max |
|
- |
211 × |
min |
|
- |
(220 - 215) × |
min |
|
- |
227 |
min |
|
- |
227 |
min |
|
- |
227 |
min |
|
- |
256 |
max |
|
0 |
1 |
min |
|
- |
1024 |
min |
|
- |
1 |
min |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
|
implementation-dependent |
|
- |
1024 |
min |
|
- |
(64,64) |
min |
|
- |
(64,64) |
min |
|
- |
(64,64) |
min |
|
- |
- |
implementation-dependent |
|
- |
3 |
min |
|
- |
3 |
min |
|
1 |
216-1 |
min |
|
- |
(65536,1,1) |
min |
|
- |
(32,1,1) |
min |
|
- |
1024 |
min |
|
- |
- |
implementation-dependent |
|
- |
32 |
min |
|
- |
256 |
min |
|
- |
32768 |
min |
|
- |
256 |
min |
|
- |
4 |
max |
|
- |
1024 |
min |
|
- |
(65535,65535,65535) |
min |
|
- |
224-1 |
min |
|
0 |
|
min |
|
- |
(64,64) |
max |
|
- |
32 |
min |
|
- |
65536 |
max |
|
- |
1 |
min |
|
|
- |
implementation-dependent |
|
- |
subgroupSize × 2 |
min |
|
- |
256 |
min |
|
- |
|
max |
|
- |
128 |
min |
|
- |
1 |
min |
|
- |
- |
implementation-dependent |
|
- |
(16,16) |
min |
|
- |
(8,8) |
min |
|
- |
4 |
min |
|
- |
65536 |
min |
|
- |
65536 |
min |
|
- |
65536 |
min |
|
- |
16 |
min |
|
- |
16 |
min |
|
0 |
500000 |
min |
|
0 |
500000 |
min |
|
- |
|
bitfield |
- 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. - 12
-
maxResourceDescriptorSizeis defined as the maximum value ofstorageImageDescriptorSize,sampledImageDescriptorSize,robustUniformTexelBufferDescriptorSize,robustStorageTexelBufferDescriptorSize,robustUniformBufferDescriptorSize,robustStorageBufferDescriptorSize,inputAttachmentDescriptorSize, andaccelerationStructureDescriptorSize.
50.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 a VkStructureType value identifying 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
sampleLocationSampleCounts the
width and height members of
VkMultisamplePropertiesEXT::maxSampleLocationGridSize must be
greater than or equal to the corresponding members of
maxSampleLocationGridSize,
respectively, otherwise both members must be 0.
50.3. Profile Limits
50.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 |
50.3.2. Roadmap 2024
Implementations that claim support for the Roadmap 2024 profile must satisfy the following additional limit requirements:
| Limit | Supported Limit | Limit Type1 |
|---|---|---|
|
|
Boolean |
|
|
Boolean |
|
|
Boolean |
|
8 |
min |
|
7 |
min |
51. 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.
51.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_VERSION_1_4
VK_FORMAT_A1B5G5R5_UNORM_PACK16 = 1000470000,
// Provided by VK_VERSION_1_4
VK_FORMAT_A8_UNORM = 1000470001,
// 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_ARM_tensors
VK_FORMAT_R8_BOOL_ARM = 1000460000,
// Provided by VK_NV_optical_flow
VK_FORMAT_R16G16_SFIXED5_NV = 1000464000,
// Provided by VK_ARM_format_pack
VK_FORMAT_R10X6_UINT_PACK16_ARM = 1000609000,
// Provided by VK_ARM_format_pack
VK_FORMAT_R10X6G10X6_UINT_2PACK16_ARM = 1000609001,
// Provided by VK_ARM_format_pack
VK_FORMAT_R10X6G10X6B10X6A10X6_UINT_4PACK16_ARM = 1000609002,
// Provided by VK_ARM_format_pack
VK_FORMAT_R12X4_UINT_PACK16_ARM = 1000609003,
// Provided by VK_ARM_format_pack
VK_FORMAT_R12X4G12X4_UINT_2PACK16_ARM = 1000609004,
// Provided by VK_ARM_format_pack
VK_FORMAT_R12X4G12X4B12X4A12X4_UINT_4PACK16_ARM = 1000609005,
// Provided by VK_ARM_format_pack
VK_FORMAT_R14X2_UINT_PACK16_ARM = 1000609006,
// Provided by VK_ARM_format_pack
VK_FORMAT_R14X2G14X2_UINT_2PACK16_ARM = 1000609007,
// Provided by VK_ARM_format_pack
VK_FORMAT_R14X2G14X2B14X2A14X2_UINT_4PACK16_ARM = 1000609008,
// Provided by VK_ARM_format_pack
VK_FORMAT_R14X2_UNORM_PACK16_ARM = 1000609009,
// Provided by VK_ARM_format_pack
VK_FORMAT_R14X2G14X2_UNORM_2PACK16_ARM = 1000609010,
// Provided by VK_ARM_format_pack
VK_FORMAT_R14X2G14X2B14X2A14X2_UNORM_4PACK16_ARM = 1000609011,
// Provided by VK_ARM_format_pack
VK_FORMAT_G14X2_B14X2R14X2_2PLANE_420_UNORM_3PACK16_ARM = 1000609012,
// Provided by VK_ARM_format_pack
VK_FORMAT_G14X2_B14X2R14X2_2PLANE_422_UNORM_3PACK16_ARM = 1000609013,
// 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,
// Provided by VK_NV_optical_flow
// VK_FORMAT_R16G16_S10_5_NV is a deprecated alias
VK_FORMAT_R16G16_S10_5_NV = VK_FORMAT_R16G16_SFIXED5_NV,
// Provided by VK_KHR_maintenance5
VK_FORMAT_A1B5G5R5_UNORM_PACK16_KHR = VK_FORMAT_A1B5G5R5_UNORM_PACK16,
// Provided by VK_KHR_maintenance5
VK_FORMAT_A8_UNORM_KHR = VK_FORMAT_A8_UNORM,
} 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_A1B5G5R5_UNORM_PACK16specifies a four-component, 16-bit packed unsigned normalized format that has a 1-bit A component in bit 15, a 5-bit B component in bits 10..14, a 5-bit G component in bits 5..9, and a 5-bit R component in bits 0..4. -
VK_FORMAT_A8_UNORMspecifies a one-component, 8-bit unsigned normalized format that has a single 8-bit A component. -
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. -
VK_FORMAT_R16G16_SFIXED5_NVspecifies a two-component, 16-bit signed fixed-point format with linear encoding. The components are signed two’s-complement integers where the most significant bit specifies the sign bit, the next 10 bits specify the integer value, and the last 5 bits represent the fractional value. The signed 16-bit values can be converted to floats in the range [-1024,1023.96875] by dividing the value by 32 (25). -
VK_FORMAT_R10X6_UINT_PACK16_ARMspecifies a one-component, 16-bit unsigned integer 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_UINT_2PACK16_ARMspecifies a two-component, 32-bit unsigned integer 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_UINT_4PACK16_ARMspecifies a four-component, 64-bit unsigned integer 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_R12X4_UINT_PACK16_ARMspecifies a one-component, 16-bit unsigned integer 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_UINT_2PACK16_ARMspecifies a two-component, 32-bit unsigned integer 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_UINT_4PACK16_ARMspecifies a four-component, 64-bit unsigned integer 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_R14X2_UINT_PACK16_ARMspecifies a one-component, 16-bit unsigned integer format that has a single 14-bit R component in the top 14 bits of a 16-bit word, with the bottom 2 bits unused. -
VK_FORMAT_R14X2G14X2_UINT_2PACK16_ARMspecifies a two-component, 32-bit unsigned integer format that has a 14-bit R component in the top 14 bits of the word in bytes 0..1, and a 14-bit G component in the top 14 bits of the word in bytes 2..3, with the bottom 2 bits of each word unused. -
VK_FORMAT_R14X2G14X2B14X2A14X2_UINT_4PACK16_ARMspecifies a four-component, 64-bit unsigned integer format that has a 14-bit R component in the top 14 bits of the word in bytes 0..1, a 14-bit G component in the top 14 bits of the word in bytes 2..3, a 14-bit B component in the top 14 bits of the word in bytes 4..5, and a 14-bit A component in the top 14 bits of the word in bytes 6..7, with the bottom 2 bits of each word unused. -
VK_FORMAT_R14X2_UNORM_PACK16_ARMspecifies a one-component, 16-bit unsigned normalized format that has a single 14-bit R component in the top 14 bits of a 16-bit word, with the bottom 2 bits unused. -
VK_FORMAT_R14X2G14X2_UNORM_2PACK16_ARMspecifies a two-component, 32-bit unsigned normalized format that has a 14-bit R component in the top 14 bits of the word in bytes 0..1, and a 14-bit G component in the top 14 bits of the word in bytes 2..3, with the bottom 2 bits of each word unused. -
VK_FORMAT_R14X2G14X2B14X2A14X2_UNORM_4PACK16_ARMspecifies a four-component, 64-bit unsigned normalized format that has a 14-bit R component in the top 14 bits of the word in bytes 0..1, a 14-bit G component in the top 14 bits of the word in bytes 2..3, a 14-bit B component in the top 14 bits of the word in bytes 4..5, and a 14-bit A component in the top 14 bits of the word in bytes 6..7, with the bottom 2 bits of each word unused. -
VK_FORMAT_G14X2_B14X2R14X2_2PLANE_420_UNORM_3PACK16_ARMspecifies an unsigned normalized multi-planar format that has a 14-bit G component in the top 14 bits of each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 14-bit B component in the top 14 bits of the word in bytes 0..1, and a 14-bit R component in the top 14 bits of the word in bytes 2..3, with the bottom 2 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_G14X2_B14X2R14X2_2PLANE_422_UNORM_3PACK16_ARMspecifies an unsigned normalized multi-planar format that has a 14-bit G component in the top 14 bits of each 16-bit word of plane 0, and a two-component, 32-bit BR plane 1 consisting of a 14-bit B component in the top 14 bits of the word in bytes 0..1, and a 14-bit R component in the top 14 bits of the word in bytes 2..3, with the bottom 2 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_R8_BOOL_ARMspecifies a one-component 8-bit boolean format that has a single 8-bit R component. See 8-bit booleans.
51.1.1. Compatible Formats of Planes of Multi-Planar Formats
Individual planes of multi-planar formats are size-compatible with single-plane color formats if they occupy the same number of bits per texel block, and are compatible with those formats if they have the same block extent.
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. These planes are also size-compatible with any format that is size-compatible with the listed single-plane format.
| 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 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h/2 |
|
|||
0 |
|
w |
h |
1 |
|
w/2 |
h |
51.1.2. Compatible Formats for Depth-Stencil to/from Color Copies
If the maintenance8 feature is enabled,
individual aspects of depth-stencil formats are size-compatible with certain
single-component color formats when performing bit-wise copy operations.
The following is a complete list of all per-aspect format compatibility
relations by size:
-
32-bit depth (
VK_FORMAT_D32_SFLOAT,VK_FORMAT_D32_SFLOAT_S8_UINT)-
VK_FORMAT_R32_SFLOAT,VK_FORMAT_R32_SINT,VK_FORMAT_R32_UINT
-
-
24-bit depth (
VK_FORMAT_X8_D24_UNORM_PACK32,VK_FORMAT_D24_UNORM_S8_UINT)-
VK_FORMAT_R32_SFLOAT,VK_FORMAT_R32_SINT,VK_FORMAT_R32_UINT
-
-
16-bit depth (
VK_FORMAT_D16_UNORM,VK_FORMAT_D16_UNORM_S8_UINT)-
VK_FORMAT_R16_SFLOAT,VK_FORMAT_R16_UNORM,VK_FORMAT_R16_SNORM,VK_FORMAT_R16_UINT,VK_FORMAT_R16_SINT
-
-
8-bit stencil (
VK_FORMAT_S8_UINT,VK_FORMAT_D16_UNORM_S8_UINT,VK_FORMAT_D24_UNORM_S8_UINT,VK_FORMAT_D32_SFLOAT_S8_UINT)-
VK_FORMAT_R8_UINT,VK_FORMAT_R8_SINT,VK_FORMAT_R8_UNORM,VK_FORMAT_R8_SNORM
-
51.1.3. Multi-Planar Format Image Aspect
When using VkImageAspectFlagBits to select a plane of a multi-planar format, the following are the valid options:
-
Two planes
-
VK_IMAGE_ASPECT_PLANE_0_BIT -
VK_IMAGE_ASPECT_PLANE_1_BIT
-
-
Three planes
-
VK_IMAGE_ASPECT_PLANE_0_BIT -
VK_IMAGE_ASPECT_PLANE_1_BIT -
VK_IMAGE_ASPECT_PLANE_2_BIT
-
51.1.4. 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_A1B5G5R5_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 -
VK_FORMAT_R10X6_UINT_PACK16_ARM -
VK_FORMAT_R10X6G10X6_UINT_2PACK16_ARM -
VK_FORMAT_R10X6G10X6B10X6A10X6_UINT_4PACK16_ARM -
VK_FORMAT_R12X4_UINT_PACK16_ARM -
VK_FORMAT_R12X4G12X4_UINT_2PACK16_ARM -
VK_FORMAT_R12X4G12X4B12X4A12X4_UINT_4PACK16_ARM -
VK_FORMAT_R14X2_UINT_PACK16_ARM -
VK_FORMAT_R14X2G14X2_UINT_2PACK16_ARM -
VK_FORMAT_R14X2G14X2B14X2A14X2_UINT_4PACK16_ARM -
VK_FORMAT_R14X2_UNORM_PACK16_ARM -
VK_FORMAT_R14X2G14X2_UNORM_2PACK16_ARM -
VK_FORMAT_R14X2G14X2B14X2A14X2_UNORM_4PACK16_ARM -
VK_FORMAT_G14X2_B14X2R14X2_2PLANE_420_UNORM_3PACK16_ARM -
VK_FORMAT_G14X2_B14X2R14X2_2PLANE_422_UNORM_3PACK16_ARM
-
-
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
-
51.1.5. 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 | Type-Declaration instructions | Numeric type | Description |
|---|---|---|---|
|
OpTypeFloat |
floating-point |
The components are unsigned normalized values in the range [0,1] |
|
OpTypeFloat |
floating-point |
The components are signed normalized values in the range [-1,1] |
|
OpTypeFloat |
floating-point |
The components are unsigned integer values that get converted to floating-point in the range [0,2n-1] |
|
OpTypeFloat |
floating-point |
The components are signed integer values that get converted to floating-point in the range [-2n-1,2n-1-1] |
|
OpTypeInt |
unsigned integer |
The components are unsigned integer values in the range [0,2n-1] |
|
OpTypeInt |
signed integer |
The components are signed integer values in the range [-2n-1,2n-1-1] |
|
OpTypeFloat |
floating-point |
The components are unsigned floating-point numbers (used by packed, shared exponent, and some compressed formats) |
|
OpTypeFloat |
floating-point |
The components are signed floating-point numbers |
|
OpTypeFloat |
floating-point |
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 |
|
OpTypeInt |
scaled signed integer |
The components are signed fractional integer values that get converted to floating-point in the range [-1024,1023.96875] |
|
OpTypeBool |
boolean |
The components are booleans |
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 texels 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. |
51.1.6. 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 |
|
||||||||||||
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 |
|
|||||||||||||||
A |
B |
G |
R |
||||||||||||
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 |
|
|||||||||||||||
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 |
|
|||||||||||||||
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 |
51.1.7. 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).
51.1.8. Format Compatibility Classes
Uncompressed color formats are compatible with each other if they occupy
the same number of bits per texel block
as long as neither or both are alpha formats (e.g.,
VK_FORMAT_A8_UNORM)
.
Compressed color formats are compatible with each other if the only
difference between them is the numeric format of
the uncompressed texels.
Each depth/stencil format is only compatible with itself.
In the following table, all the formats in the
same row are compatible.
Each format has a defined texel block extent specifying how many texels
each texel block represents in each dimension.
| Class, Texel Block Size, Texel Block Extent, # Texels/Block | Formats |
|---|---|
8-bit |
|
16-bit |
|
8-bit alpha |
|
24-bit |
|
32-bit |
|
32-bit (continued) |
|
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 |
|
64-bit R14G14B14A14 |
|
14-bit 2-plane 420 |
|
14-bit 2-plane 422 |
|
Size Compatibility
Color formats with the same texel block size are considered
size-compatible as long as neither or both are alpha formats (e.g.,
VK_FORMAT_A8_UNORM).
If two size-compatible formats have different block extents (i.e. for
compressed formats), then an image with size A × B × C in
one format with a block extent of a × b × c can be
represented as an image with size X × Y × Z in the other
format with block extent x × y × z at the ratio between
the block extents for each format, where
-
⌈A/a⌉ = ⌈X/x⌉
-
⌈B/b⌉ = ⌈Y/y⌉
-
⌈C/c⌉ = ⌈Z/z⌉
|
Note
|
For example, a 7x3 image in the |
Images created with the
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag can have
size-compatible views created from them to enable access via different
size-compatible formats.
Image views created in this way will be sized to match the expectations of
the block extents noted above.
Copy operations are able to copy between size-compatible formats in different resources to enable manipulation of data in different formats. The extent used in these copy operations always matches the source image, and is resized to the expectations of the block extents noted above for the destination image.
Copy operations between color formats and a depth-stencil are size-compatible as defined by the list of compatible depth-stencil and color formats.
51.2. Format Properties
To query supported format features which are properties of the physical device, call:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.1. See Deprecated Functionality for more information. |
// 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 block-compressed,
requires sampler Y′CBCR
conversion,
or is a depth/stencil 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,
// Provided by VK_KHR_video_decode_queue
VK_FORMAT_FEATURE_VIDEO_DECODE_OUTPUT_BIT_KHR = 0x02000000,
// Provided by VK_KHR_video_decode_queue
VK_FORMAT_FEATURE_VIDEO_DECODE_DPB_BIT_KHR = 0x04000000,
// 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,
// Provided by VK_KHR_video_encode_queue
VK_FORMAT_FEATURE_VIDEO_ENCODE_INPUT_BIT_KHR = 0x08000000,
// Provided by VK_KHR_video_encode_queue
VK_FORMAT_FEATURE_VIDEO_ENCODE_DPB_BIT_KHR = 0x10000000,
// 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. -
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. If the applicationapiVersionis Vulkan 1.0 andVK_KHR_maintenance1is not supported,VK_FORMAT_FEATURE_TRANSFER_SRC_BITis implied to be set when the format feature flag is not 0. -
VK_FORMAT_FEATURE_TRANSFER_DST_BITspecifies that an image can be used as a destination image for copy commands and clear commands. If the applicationapiVersionis Vulkan 1.0 andVK_KHR_maintenance1is not supported,VK_FORMAT_FEATURE_TRANSFER_DST_BITis implied to be set when the format feature flag is not 0. -
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 a numeric format other thanUINT, 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 a decode output picture in video decode operations. -
VK_FORMAT_FEATURE_VIDEO_DECODE_DPB_BIT_KHRspecifies that an image view with this format can be used as an output reconstructed picture or an input reference picture in video decode operations. -
VK_FORMAT_FEATURE_VIDEO_ENCODE_INPUT_BIT_KHRspecifies that an image view with this format can be used as an encode input picture in video encode operations. -
VK_FORMAT_FEATURE_VIDEO_ENCODE_DPB_BIT_KHRspecifies that an image view with this format can be used as an output reconstructed picture or an input reference picture in video encode operations.NoteSpecific 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.
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.
|
Note
|
|
// 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 format).
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::formatProperties.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_EXT_image_drm_format_modifier with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
typedef struct VkDrmFormatModifierPropertiesList2EXT {
VkStructureType sType;
void* pNext;
uint32_t drmFormatModifierCount;
VkDrmFormatModifierProperties2EXT* pDrmFormatModifierProperties;
} VkDrmFormatModifierPropertiesList2EXT;
-
sTypeis a VkStructureType value identifying 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_EXT_image_drm_format_modifier with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
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_STORAGE_IMAGE_BIT = 0x00000002ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_IMAGE_ATOMIC_BIT = 0x00000004ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_UNIFORM_TEXEL_BUFFER_BIT = 0x00000008ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_BIT = 0x00000010ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_ATOMIC_BIT = 0x00000020ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VERTEX_BUFFER_BIT = 0x00000040ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BIT = 0x00000080ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BLEND_BIT = 0x00000100ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000200ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BLIT_SRC_BIT = 0x00000400ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BLIT_DST_BIT = 0x00000800ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_LINEAR_BIT = 0x00001000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TRANSFER_SRC_BIT = 0x00004000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TRANSFER_DST_BIT = 0x00008000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_MINMAX_BIT = 0x00010000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_MIDPOINT_CHROMA_SAMPLES_BIT = 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_SEPARATE_RECONSTRUCTION_FILTER_BIT = 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_FORCEABLE_BIT = 0x00200000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_DISJOINT_BIT = 0x00400000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COSITED_CHROMA_SAMPLES_BIT = 0x00800000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT = 0x80000000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT = 0x100000000ULL;
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT = 0x200000000ULL;
// Provided by VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_CUBIC_BIT = 0x00002000ULL;
// Provided by VK_VERSION_1_4
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT = 0x400000000000ULL;
// Provided by VK_KHR_video_decode_queue with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_DECODE_OUTPUT_BIT_KHR = 0x02000000ULL;
// Provided by VK_KHR_video_decode_queue with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_DECODE_DPB_BIT_KHR = 0x04000000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR = 0x20000000ULL;
// Provided by VK_EXT_fragment_density_map with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x01000000ULL;
// Provided by VK_KHR_fragment_shading_rate with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x40000000ULL;
// Provided by VK_EXT_host_image_copy
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT_EXT = 0x400000000000ULL;
// Provided by VK_KHR_video_encode_queue with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_ENCODE_INPUT_BIT_KHR = 0x08000000ULL;
// Provided by VK_KHR_video_encode_queue with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_ENCODE_DPB_BIT_KHR = 0x10000000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT_KHR = 0x00000001ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_IMAGE_BIT_KHR = 0x00000002ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_IMAGE_ATOMIC_BIT_KHR = 0x00000004ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_ATOMIC_BIT_KHR = 0x00000020ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VERTEX_BUFFER_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BIT_KHR = 0x00000080ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BLEND_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_DEPTH_STENCIL_ATTACHMENT_BIT_KHR = 0x00000200ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BLIT_SRC_BIT_KHR = 0x00000400ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BLIT_DST_BIT_KHR = 0x00000800ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_LINEAR_BIT_KHR = 0x00001000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TRANSFER_SRC_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TRANSFER_DST_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_MIDPOINT_CHROMA_SAMPLES_BIT_KHR = 0x00020000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR = 0x00040000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR = 0x00080000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR = 0x00100000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR = 0x00200000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_DISJOINT_BIT_KHR = 0x00400000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_COSITED_CHROMA_SAMPLES_BIT_KHR = 0x00800000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHR = 0x80000000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHR = 0x100000000ULL;
// Provided by VK_KHR_format_feature_flags2
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT_KHR = 0x200000000ULL;
// Provided by VK_KHR_format_feature_flags2 with VK_VERSION_1_2 or VK_EXT_sampler_filter_minmax
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_MINMAX_BIT_KHR = 0x00010000ULL;
// Provided by VK_KHR_format_feature_flags2 with VK_EXT_filter_cubic or VK_IMG_filter_cubic
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT = 0x00002000ULL;
// Provided by VK_NV_ray_tracing_linear_swept_spheres
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_ACCELERATION_STRUCTURE_RADIUS_BUFFER_BIT_NV = 0x8000000000000ULL;
// Provided by VK_NV_linear_color_attachment with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV = 0x4000000000ULL;
// Provided by VK_QCOM_image_processing with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_WEIGHT_IMAGE_BIT_QCOM = 0x400000000ULL;
// Provided by VK_QCOM_image_processing with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_WEIGHT_SAMPLED_IMAGE_BIT_QCOM = 0x800000000ULL;
// Provided by VK_QCOM_image_processing with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM = 0x1000000000ULL;
// Provided by VK_QCOM_image_processing with VK_KHR_format_feature_flags2 or VK_VERSION_1_3
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_BOX_FILTER_SAMPLED_BIT_QCOM = 0x2000000000ULL;
// Provided by VK_ARM_tensors
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TENSOR_SHADER_BIT_ARM = 0x8000000000ULL;
// Provided by VK_ARM_tensors
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TENSOR_IMAGE_ALIASING_BIT_ARM = 0x80000000000ULL;
// Provided by VK_NV_optical_flow
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_OPTICAL_FLOW_IMAGE_BIT_NV = 0x10000000000ULL;
// Provided by VK_NV_optical_flow
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_OPTICAL_FLOW_VECTOR_BIT_NV = 0x20000000000ULL;
// Provided by VK_NV_optical_flow
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_OPTICAL_FLOW_COST_BIT_NV = 0x40000000000ULL;
// Provided by VK_ARM_data_graph
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_TENSOR_DATA_GRAPH_BIT_ARM = 0x1000000000000ULL;
// Provided by VK_KHR_video_encode_quantization_map
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR = 0x2000000000000ULL;
// Provided by VK_KHR_video_encode_quantization_map
static const VkFormatFeatureFlagBits2 VK_FORMAT_FEATURE_2_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR = 0x4000000000000ULL;
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. -
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 a numeric format other thanUINT, 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 a decode output picture in video decode operations. -
VK_FORMAT_FEATURE_2_VIDEO_DECODE_DPB_BIT_KHRspecifies that an image view with this format can be used as an output reconstructed picture or an input reference picture in video decode operations. -
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_INPUT_BIT_KHRspecifies that an image view with this format can be used as an encode input picture in video encode operations. -
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_DPB_BIT_KHRspecifies that an image view with this format can be used as an output reconstructed picture or an input reference picture in video encode operations.NoteSpecific 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.
-
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BITspecifies that image views or buffer views created with this format can be used as storage images or storage texel buffers respectively for read operations without specifying a format. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITspecifies that image views or buffer views created with this format can be used as storage images or storage texel buffers respectively 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. -
VK_FORMAT_FEATURE_2_WEIGHT_IMAGE_BIT_QCOMspecifies that image views created with this format can be used as the weight image input to weight image sampling operations. -
VK_FORMAT_FEATURE_2_WEIGHT_SAMPLED_IMAGE_BIT_QCOMspecifies that image views created with this format can be sampled in weight image sampling operations. -
VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOMspecifies that image views created with this format can be used in block matching operations. -
VK_FORMAT_FEATURE_2_BOX_FILTER_SAMPLED_BIT_QCOMspecifies that image views created with this format can be sampled in box filter sampling operations. -
VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BITspecifies that an image can be created withVK_IMAGE_USAGE_HOST_TRANSFER_BIT. -
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHRspecifies that an image view with this format can be used as a quantization delta map in video encode operations. -
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHRspecifies that an image view with this format can be used as an emphasis map in video encode operations.NoteVideo encode quantization maps have additional restrictions specific to the video profile they are used with that can be enumerated using the vkGetPhysicalDeviceVideoFormatPropertiesKHR command.
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. -
VK_FORMAT_FEATURE_2_ACCELERATION_STRUCTURE_RADIUS_BUFFER_BIT_NVspecifies that the format can be used as the radius format when creating an acceleration structure (VkAccelerationStructureGeometryLinearSweptSpheresDataNV::radiusFormatorVkAccelerationStructureGeometrySpheresDataNV::radiusFormat). This format can also be used as the radius format in host memory when doing host acceleration structure builds. -
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BITspecifies that buffer views created with this format can be used as storage texel buffers for read operations without specifying a format. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITspecifies that buffer views created with this format can be used as storage texel buffers for write operations without specifying a format. -
VK_FORMAT_FEATURE_2_OPTICAL_FLOW_IMAGE_BIT_NVspecifies that an image view with this format can be used as an input or reference to optical flow operations -
VK_FORMAT_FEATURE_2_OPTICAL_FLOW_VECTOR_BIT_NVspecifies that an image view with this format can be used as a flow vector map (either as hint, output or global flow) for optical flow operations -
VK_FORMAT_FEATURE_2_OPTICAL_FLOW_COST_BIT_NVspecifies that an image view with this format can be used as an output cost map for optical flow operations
The VkTensorFormatPropertiesARM structure describes properties of a VkFormat when that format is used to describe tensor elements. These properties, like those of VkFormatProperties2, are independent of any particular tensor.
The VkTensorFormatPropertiesARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkTensorFormatPropertiesARM {
VkStructureType sType;
const void* pNext;
VkFormatFeatureFlags2 optimalTilingTensorFeatures;
VkFormatFeatureFlags2 linearTilingTensorFeatures;
} VkTensorFormatPropertiesARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
linearTilingTensorFeaturesis a bitmask of VkFormatFeatureFlagBits2 specifying features supported by tensors created with atilingparameter ofVK_TENSOR_TILING_LINEAR_ARM. -
optimalTilingTensorFeaturesis a bitmask of VkFormatFeatureFlagBits2 specifying features supported by tensors created with atilingparameter ofVK_TENSOR_TILING_OPTIMAL_ARM.
The following bits may be set in linearTilingTensorFeatures and
optimalTilingTensorFeatures, specifying that the features are
supported by tensors or tensor views created with the queried
vkGetPhysicalDeviceFormatProperties2::format:
-
VK_FORMAT_FEATURE_2_TRANSFER_SRC_BITspecifies that a tensor can be used as a source tensor for copy commands. -
VK_FORMAT_FEATURE_2_TRANSFER_DST_BITspecifies that a tensor can be used as a destination tensor for copy commands. -
VK_FORMAT_FEATURE_2_TENSOR_SHADER_BIT_ARMspecifies that a tensor view can be used as a storage tensor with compute pipelines. -
VK_FORMAT_FEATURE_2_TENSOR_IMAGE_ALIASING_BIT_ARMspecifies that a tensor can be aliased to an image or that an image can be aliased to a tensor. -
VK_FORMAT_FEATURE_2_TENSOR_DATA_GRAPH_BIT_ARMspecifies that a tensor view can be used as a storage tensor with data graph pipelines.
// 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 a VkStructureType value identifying 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.
51.2.1. Potential Format Features
Some valid usage conditions depend on the format features supported by a 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 -
VkScreenBufferFormatPropertiesQNX::
formatFeaturesof a valid external format if VkFormat isVK_FORMAT_UNDEFINED
51.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 |
§ |
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 features marked with § must be supported for
|
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
Format |
|||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||
|
✓ |
✓ |
✓ |
† |
✓ |
✓ |
✓ |
✓ |
✓ |
||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
||||||||||||
|
✓ |
||||||||||||
|
✓ |
||||||||||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
|||||
Format features marked with † must be supported for
|
|||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
|
↓ |
||||||||||||
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 |
||||||||||
|
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_2_ACCELERATION_STRUCTURE_RADIUS_BUFFER_BIT_NV must
be supported in bufferFeatures for the following formats if either of
the spheres or linearSweptSpheres feature is supported:
-
VK_FORMAT_R32_SFLOAT -
VK_FORMAT_R16_SFLOAT
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
If the hostImageCopy feature is supported
and VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT is supported in
optimalTilingFeatures or linearTilingFeatures for a color
format, VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT must also be
supported in optimalTilingFeatures or linearTilingFeatures
respectively.
51.3.1. Formats Without Shader Storage Format
The device-level features for using a storage image or a storage texel
buffer 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 -
VK_FORMAT_A8_UNORM
|
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.
An implementation that does not support either of
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT or
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT for a format
must not report support for VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT or
VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT for that format if it is
not listed in the SPIR-V and Vulkan Image Format
Compatibility table.
|
Note
|
Some older implementations do not follow this restriction.
They report support for formats as storage images even though they do not
support access without the Drivers which pass Vulkan conformance test suite version 1.3.9.0, or any subsequent version will conform to the requirement above. |
51.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.
51.3.3. Format Feature Dependent Usage Flags
Certain resource usage flags depend on support for the corresponding format feature flag for the format in question. The following tables list the VkBufferUsageFlagBits, VkImageUsageFlagBits and VkTensorUsageFlagBitsARM that have such dependencies, and the format feature flags they depend on. Additional restrictions, including, but not limited to, further required format feature flags specific to the particular use of the resource may apply, as described in the respective sections of this specification.
| Buffer usage flag | Required format feature flag |
|---|---|
|
|
|
|
|
|
| Image usage flag | Required format feature flag |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Tensor usage flag | Required format feature flag |
|---|---|
|
|
|
|
|
|
|
|
|
|
51.3.4. Tensor Format Support
For tensors, implementations must support at least the following set of features on the listed tensor formats.
The following tables show which tensor feature bits must be supported for each format.
✓ |
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 |
|
|
|
|
|
|
|
↓ |
||
|
↓ |
||
|
↓ |
||
Format |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
52. Additional Capabilities
This chapter describes additional capabilities beyond the minimum capabilities described in the Limits and Formats chapters, including:
52.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:
|
Warning
|
This functionality is deprecated by Vulkan Version 1.1. See Deprecated Functionality for more information. |
// 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.
If the hostImageCopy feature is supported,
and:
-
usageincludesVK_IMAGE_USAGE_SAMPLED_BIT, and -
flagsdoes not include any ofVK_IMAGE_CREATE_SPARSE_BINDING_BIT,VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, orVK_IMAGE_CREATE_SPARSE_ALIASED_BIT
Then the result of calls to vkGetPhysicalDeviceImageFormatProperties
with identical parameters except for the inclusion of
VK_IMAGE_USAGE_HOST_TRANSFER_BIT in usage must be identical.
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
VkVideoProfileListInfoKHR structure with a profileCount member
greater than 0, then this command returns format capabilities specific to
image types used in conjunction with the specified video
profiles.
In this case, this command will return one of the
video-profile-specific error codes if any of
the profiles specified via VkVideoProfileListInfoKHR::pProfiles
are not supported.
Furthermore, if VkPhysicalDeviceImageFormatInfo2::usage includes
any image usage flag not supported by the specified video profiles, then
this command returns VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
If the hostImageCopy feature is supported,
and:
-
pImageFormatInfo->usageincludesVK_IMAGE_USAGE_SAMPLED_BIT -
pImageFormatInfo->flagsdoes not include either ofVK_IMAGE_CREATE_SPARSE_BINDING_BIT,VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, orVK_IMAGE_CREATE_SPARSE_ALIASED_BIT -
The
pNextchain ofpImageFormatInfodoes not include a VkPhysicalDeviceExternalImageFormatInfo structure with non-zerohandleType -
pImageFormatInfo->tilingis notVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
Then the result of calls to vkGetPhysicalDeviceImageFormatProperties2
with identical parameters except for the inclusion of
VK_IMAGE_USAGE_HOST_TRANSFER_BIT in pImageFormatInfo->usage
must be identical.
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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. An application-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 a VkStructureType value identifying 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_QNX_external_memory_screen_buffer
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX = 0x00004000,
// Provided by VK_EXT_external_memory_metal
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLBUFFER_BIT_EXT = 0x00010000,
// Provided by VK_EXT_external_memory_metal
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT = 0x00020000,
// Provided by VK_EXT_external_memory_metal
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLHEAP_BIT_EXT = 0x00040000,
// 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 an AHardwareBuffer object 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. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNXspecifies a_screen_bufferobject defined by the QNX SDP. See QNX Screen Buffer for more details of this handle type. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLBUFFER_BIT_EXTis a handle to aMTLResourceholding aMTLBuffer. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXTis a handle to aMTLResourceholding aMTLTexture. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLHEAP_BIT_EXTis a handle to aMTLResourceholding aMTLHeap.
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 |
|
No restriction |
No restriction |
|
No restriction |
Must match |
|
No restriction |
Must match |
|
No restriction |
Must match |
|
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 a VkStructureType value identifying 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 tensors, images or buffers created with the specified parameters and handle type must use the mechanisms defined by VkMemoryDedicatedRequirements and VkMemoryDedicatedAllocateInfo or VkMemoryDedicatedAllocateInfoTensorARM to create (or import) a dedicated allocation for the tensor, 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 -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNXfor images only -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT
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 buffers with
external handle type
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX.
Implementations must not report
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for
tensors,
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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifieris the image’s Linux DRM format modifier, corresponding to VkImageDrmFormatModifierExplicitCreateInfoEXT::drmFormatModifieror to VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers. -
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 a VkStructureType value identifying 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
|
Instead of querying all the potential formats that the application might use
in the descriptor layout, the application can use the
VkPhysicalDeviceMaintenance6Properties::maxCombinedImageSamplerDescriptorCount
property to determine the maximum descriptor size that will accommodate any
and all formats that require a
sampler Y′CBCR conversion supported by the implementation.
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 a VkStructureType value identifying 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 query if using VK_IMAGE_USAGE_HOST_TRANSFER_BIT has a negative
impact on device performance when accessing an image, add
VK_IMAGE_USAGE_HOST_TRANSFER_BIT to
VkPhysicalDeviceImageFormatInfo2::usage, and add a
VkHostImageCopyDevicePerformanceQuery structure to the pNext
chain of a VkImageFormatProperties2 structure passed to
vkGetPhysicalDeviceImageFormatProperties2.
This structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkHostImageCopyDevicePerformanceQuery {
VkStructureType sType;
void* pNext;
VkBool32 optimalDeviceAccess;
VkBool32 identicalMemoryLayout;
} VkHostImageCopyDevicePerformanceQuery;
or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkHostImageCopyDevicePerformanceQuery VkHostImageCopyDevicePerformanceQueryEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
optimalDeviceAccessreturnsVK_TRUEif use of host image copy has no adverse effect on device access performance, compared to an image that is created with exact same creation parameters, and bound to the same VkDeviceMemory, except thatVK_IMAGE_USAGE_HOST_TRANSFER_BITis replaced withVK_IMAGE_USAGE_TRANSFER_SRC_BITandVK_IMAGE_USAGE_TRANSFER_DST_BIT. -
identicalMemoryLayoutreturnsVK_TRUEif use of host image copy has no impact on memory layout compared to an image that is created with exact same creation parameters, and bound to the same VkDeviceMemory, except thatVK_IMAGE_USAGE_HOST_TRANSFER_BITis replaced withVK_IMAGE_USAGE_TRANSFER_SRC_BITandVK_IMAGE_USAGE_TRANSFER_DST_BIT.
The implementation may return VK_FALSE in optimalDeviceAccess
if identicalMemoryLayout is VK_FALSE.
If identicalMemoryLayout is VK_TRUE, optimalDeviceAccess
must be VK_TRUE.
The implementation may return VK_TRUE in optimalDeviceAccess
while identicalMemoryLayout is VK_FALSE.
In this situation, any device performance impact should not be measurable.
If VkPhysicalDeviceImageFormatInfo2::format is a
block-compressed format and vkGetPhysicalDeviceImageFormatProperties2
returns VK_SUCCESS, the implementation must return VK_TRUE in
optimalDeviceAccess.
|
Note
|
Applications can make use of |
|
Note
|
Layout not being identical yet still considered optimal for device access could happen if the implementation has different memory layout patterns, some of which are easier to access on the host. |
|
Note
|
The most practical reason for |
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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. An application-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. An application-specified value is ignored.
52.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 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 component, a superset ofVkPhysicalDeviceLimits::framebufferDepthSampleCounts -
If
usageincludesVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, andformatincludes a stencil component, a superset ofVkPhysicalDeviceLimits::framebufferStencilSampleCounts -
If
usageincludesVK_IMAGE_USAGE_SAMPLED_BIT, andformatincludes a color component, a superset ofVkPhysicalDeviceLimits::sampledImageColorSampleCounts -
If
usageincludesVK_IMAGE_USAGE_SAMPLED_BIT, andformatincludes a depth component, 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.
52.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
52.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 a VkStructureType value identifying 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.
Only usage flags representable in VkBufferUsageFlagBits are returned
in this structure’s usage.
If the pNext chain includes a VkBufferUsageFlags2CreateInfo
structure, all usage flags of the buffer are returned in
VkBufferUsageFlags2CreateInfo::usage.
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 a VkStructureType value identifying 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.
52.3. Additional Tensor Capabilities
To query the external handle types supported by tensors, call:
// Provided by VK_ARM_tensors
void vkGetPhysicalDeviceExternalTensorPropertiesARM(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalTensorInfoARM* pExternalTensorInfo,
VkExternalTensorPropertiesARM* pExternalTensorProperties);
-
physicalDeviceis the physical device from which to query the tensor capabilities. -
pExternalTensorInfois a pointer to a VkPhysicalDeviceExternalTensorInfoARM structure describing the parameters that would be consumed by vkCreateTensorARM. -
pExternalTensorPropertiesis a pointer to a VkExternalTensorPropertiesARM structure in which the capabilities are returned.
The VkPhysicalDeviceExternalTensorInfoARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkPhysicalDeviceExternalTensorInfoARM {
VkStructureType sType;
const void* pNext;
VkTensorCreateFlagsARM flags;
const VkTensorDescriptionARM* pDescription;
VkExternalMemoryHandleTypeFlagBits handleType;
} VkPhysicalDeviceExternalTensorInfoARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkTensorCreateFlagBitsARM describing additional parameters of the tensor, corresponding to VkTensorCreateInfoARM::flags. -
pDescriptionis a VkTensorDescriptionARM structure describing the tensor, corresponding to VkTensorCreateInfoARM::pDescription. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the external memory handle type for which capabilities will be returned.
The VkExternalTensorPropertiesARM structure is defined as:
// Provided by VK_ARM_tensors
typedef struct VkExternalTensorPropertiesARM {
VkStructureType sType;
const void* pNext;
VkExternalMemoryProperties externalMemoryProperties;
} VkExternalTensorPropertiesARM;
-
sTypeis a VkStructureType value identifying 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 tensor creation parameters.
52.4. 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 a VkStructureType value identifying 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 a VkStructureType value identifying 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
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.
52.5. 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 a VkStructureType value identifying 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 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.
52.6. Timestamp Calibration Capabilities
To query the set of time domains for which a physical device supports timestamp calibration, call:
// Provided by VK_KHR_calibrated_timestamps
VkResult vkGetPhysicalDeviceCalibrateableTimeDomainsKHR(
VkPhysicalDevice physicalDevice,
uint32_t* pTimeDomainCount,
VkTimeDomainKHR* pTimeDomains);
or the equivalent command
// Provided by VK_EXT_calibrated_timestamps
VkResult vkGetPhysicalDeviceCalibrateableTimeDomainsEXT(
VkPhysicalDevice physicalDevice,
uint32_t* pTimeDomainCount,
VkTimeDomainKHR* 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 VkTimeDomainKHR 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
application 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.
53. 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,
// Provided by VK_KHR_video_queue
VK_OBJECT_TYPE_VIDEO_SESSION_KHR = 1000023000,
// Provided by VK_KHR_video_queue
VK_OBJECT_TYPE_VIDEO_SESSION_PARAMETERS_KHR = 1000023001,
// 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,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_cuda_kernel_launch
VK_OBJECT_TYPE_CUDA_MODULE_NV = 1000307000,
#endif
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_cuda_kernel_launch
VK_OBJECT_TYPE_CUDA_FUNCTION_NV = 1000307001,
#endif
// Provided by VK_FUCHSIA_buffer_collection
VK_OBJECT_TYPE_BUFFER_COLLECTION_FUCHSIA = 1000366000,
// Provided by VK_EXT_opacity_micromap
VK_OBJECT_TYPE_MICROMAP_EXT = 1000396000,
// Provided by VK_ARM_tensors
VK_OBJECT_TYPE_TENSOR_ARM = 1000460000,
// Provided by VK_ARM_tensors
VK_OBJECT_TYPE_TENSOR_VIEW_ARM = 1000460001,
// Provided by VK_NV_optical_flow
VK_OBJECT_TYPE_OPTICAL_FLOW_SESSION_NV = 1000464000,
// Provided by VK_EXT_shader_object
VK_OBJECT_TYPE_SHADER_EXT = 1000482000,
// Provided by VK_KHR_pipeline_binary
VK_OBJECT_TYPE_PIPELINE_BINARY_KHR = 1000483000,
// Provided by VK_ARM_data_graph
VK_OBJECT_TYPE_DATA_GRAPH_PIPELINE_SESSION_ARM = 1000507000,
// Provided by VK_NV_external_compute_queue
VK_OBJECT_TYPE_EXTERNAL_COMPUTE_QUEUE_NV = 1000556000,
// Provided by VK_EXT_device_generated_commands
VK_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_EXT = 1000572000,
// Provided by VK_EXT_device_generated_commands
VK_OBJECT_TYPE_INDIRECT_EXECUTION_SET_EXT = 1000572001,
// 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.
53.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.
53.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
application-defined information with Vulkan objects.
These commands are device-level commands but they may reference
instance-level objects (such as VkInstance) and physical device-level
objects (such as VkPhysicalDevice) with a few restrictions:
* The data for the corresponding object may still be available after the
VkDevice used in the corresponding API call to set it is
destroyed, but access to this data is not guaranteed and should be
avoided.
* Subsequent calls to change the data of the same object across multiple
VkDevice objects, may result in the data being changed to the
most recent version for all VkDevice objects and not just the
VkDevice used in the most recent API call.
Object Naming
An object can be given an application-defined name by calling:
// Provided by VK_EXT_debug_utils
VkResult vkSetDebugUtilsObjectNameEXT(
VkDevice device,
const VkDebugUtilsObjectNameInfoEXT* pNameInfo);
-
deviceis the device that is associated with the named object passed in viaobjectHandle. -
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 a VkStructureType value identifying 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 a VkStructureType value identifying 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.
53.1.2. Queue Labels
All Vulkan work is 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 a VkStructureType value identifying 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 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.
53.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. -
pLabelInfois a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label to insert.
53.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 a VkStructureType value identifying 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 application 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,
// Provided by VK_EXT_device_address_binding_report
VK_DEBUG_UTILS_MESSAGE_TYPE_DEVICE_ADDRESS_BINDING_BIT_EXT = 0x00000008,
} 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. -
VK_DEBUG_UTILS_MESSAGE_TYPE_DEVICE_ADDRESS_BINDING_BIT_EXTspecifies that the implementation has modified the set of GPU-visible virtual addresses associated with a Vulkan object.
// 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 a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis0and is reserved for future use. -
pMessageIdNameisNULLor a null-terminated UTF-8 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 will be the VUID. -
messageIdNumberis the ID number of the triggering message. If the message corresponds to a validation layer message, then this number is an internal hash of the VUID. -
pMessageisNULLifmessageTypesis equal toVK_DEBUG_UTILS_MESSAGE_TYPE_DEVICE_ADDRESS_BINDING_BIT_EXT, or a null-terminated UTF-8 string detailing the trigger conditions. If the message corresponds to a validation layer message, then this will contain the main message with the specification text and link. -
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.
The definition of VkDeviceAddressBindingCallbackDataEXT is:
// Provided by VK_EXT_device_address_binding_report
typedef struct VkDeviceAddressBindingCallbackDataEXT {
VkStructureType sType;
void* pNext;
VkDeviceAddressBindingFlagsEXT flags;
VkDeviceAddress baseAddress;
VkDeviceSize size;
VkDeviceAddressBindingTypeEXT bindingType;
} VkDeviceAddressBindingCallbackDataEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkDeviceAddressBindingFlagBitsEXT specifying additional information about the binding event that caused the callback to be called. -
baseAddressis a GPU-accessible virtual address identifying the start of a region of the virtual address space associated with a Vulkan object, as identified by thepObjectsmember of VkDebugUtilsMessengerCallbackDataEXT. -
sizeis the size in bytes of a region of GPU-accessible virtual address space. -
bindingTypeis a VkDeviceAddressBindingTypeEXT specifying the type of binding event that caused the callback to be called.
If the reportAddressBinding feature
is enabled and the implementation binds or unbinds a region of virtual
address space associated with a Vulkan object, the implementation must
submit a debug message with the following properties:
-
messageSeverityequal toVK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT -
messageTypesequal toVK_DEBUG_UTILS_MESSAGE_TYPE_DEVICE_ADDRESS_BINDING_BIT_EXT -
VkDebugUtilsMessengerCallbackDataEXT::pObjectsmust identify the associated Vulkan object -
VkDeviceAddressBindingCallbackDataEXTmust be included in thepNextchain ofVkDebugUtilsMessengerCallbackDataEXT
These debug messages must be emitted both for GPU virtual address space
regions that are explicitly bound to a Vulkan object via the
vkBind*Memory/vkBind*Memory2 functions, and for those that are
implicitly generated via memory allocation or importing external memory.
An implementation may report binding events associated with a Vulkan object
via VkDebugUtilsMessengerEXT prior to the object becoming visible to
an application via other Vulkan commands.
For example, object creation functions may report binding events that occur
during an objects creation.
In such cases, VkDeviceAddressBindingCallbackDataEXT::flags
must include VK_DEVICE_ADDRESS_BINDING_INTERNAL_OBJECT_BIT_EXT.
Object handles reported in this manner are not valid object handles, and must not be used as an input parameter to any Vulkan command.
Any valid object handle returned by an object creation function must match the handle specified via any previously reported binding events associated with the object’s creation.
Bits which can be set in
VkDeviceAddressBindingCallbackDataEXT::flags specifying
additional information about a binding event are:
// Provided by VK_EXT_device_address_binding_report
typedef enum VkDeviceAddressBindingFlagBitsEXT {
VK_DEVICE_ADDRESS_BINDING_INTERNAL_OBJECT_BIT_EXT = 0x00000001,
} VkDeviceAddressBindingFlagBitsEXT;
-
VK_DEVICE_ADDRESS_BINDING_INTERNAL_OBJECT_BIT_EXTspecifies that VkDeviceAddressBindingCallbackDataEXT describes a Vulkan object that has not been made visible to the application via a Vulkan command.
// Provided by VK_EXT_device_address_binding_report
typedef VkFlags VkDeviceAddressBindingFlagsEXT;
VkDeviceAddressBindingFlagsEXT is a bitmask type for setting a mask of zero or more VkDeviceAddressBindingFlagBitsEXT.
The VkDeviceAddressBindingTypeEXT enum is defined as:
// Provided by VK_EXT_device_address_binding_report
typedef enum VkDeviceAddressBindingTypeEXT {
VK_DEVICE_ADDRESS_BINDING_TYPE_BIND_EXT = 0,
VK_DEVICE_ADDRESS_BINDING_TYPE_UNBIND_EXT = 1,
} VkDeviceAddressBindingTypeEXT;
-
VK_DEVICE_ADDRESS_BINDING_TYPE_BIND_EXTspecifies that a new GPU-accessible virtual address range has been bound. -
VK_DEVICE_ADDRESS_BINDING_TYPE_UNBIND_EXTspecifies that a GPU-accessible virtual address range has been unbound.
To intentionally submit a debug message, 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.
53.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.
53.2.1. Object Annotation
The commands in this section allow application developers to associate application-defined information with Vulkan objects at will.
An object can be given an application-defined 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 a VkStructureType value identifying 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 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 a VkStructureType value identifying 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.
53.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 a VkStructureType value identifying 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 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.
53.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 a VkStructureType value identifying 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 application 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 UTF-8 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 UTF-8 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_EXT_debug_report with VK_NVX_binary_import
VK_DEBUG_REPORT_OBJECT_TYPE_CU_MODULE_NVX_EXT = 1000029000,
// Provided by VK_EXT_debug_report with VK_NVX_binary_import
VK_DEBUG_REPORT_OBJECT_TYPE_CU_FUNCTION_NVX_EXT = 1000029001,
// Provided by VK_KHR_acceleration_structure with VK_EXT_debug_report
VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR_EXT = 1000150000,
// Provided by VK_EXT_debug_report with VK_NV_ray_tracing
VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV_EXT = 1000165000,
// Provided by VK_EXT_debug_report with VK_NV_cuda_kernel_launch
VK_DEBUG_REPORT_OBJECT_TYPE_CUDA_MODULE_NV_EXT = 1000307000,
// Provided by VK_EXT_debug_report with VK_NV_cuda_kernel_launch
VK_DEBUG_REPORT_OBJECT_TYPE_CUDA_FUNCTION_NV_EXT = 1000307001,
// Provided by VK_EXT_debug_report with VK_FUCHSIA_buffer_collection
VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_COLLECTION_FUCHSIA_EXT = 1000366000,
// VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT is a deprecated alias
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 is a deprecated alias
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 with VK_EXT_debug_report
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 UTF-8 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.
53.4. Device Loss Debugging
53.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_NV_device_diagnostic_checkpoints with VK_VERSION_1_3 or VK_KHR_synchronization2
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
application 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_NV_device_diagnostic_checkpoints with VK_VERSION_1_3 or VK_KHR_synchronization2
typedef struct VkCheckpointData2NV {
VkStructureType sType;
void* pNext;
VkPipelineStageFlags2 stage;
void* pCheckpointMarker;
} VkCheckpointData2NV;
-
sTypeis a VkStructureType value identifying 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
application 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 a VkStructureType value identifying 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.
53.4.2. Device Fault Diagnosis
To retrieve diagnostic information about faults that may have caused device loss, call:
// Provided by VK_EXT_device_fault
VkResult vkGetDeviceFaultInfoEXT(
VkDevice device,
VkDeviceFaultCountsEXT* pFaultCounts,
VkDeviceFaultInfoEXT* pFaultInfo);
-
deviceis the logical device from which to query the diagnostic fault information. -
pFaultCountsis a pointer to a VkDeviceFaultCountsEXT structure in which counts for structures describing additional fault information are returned. -
pFaultInfoisNULLor a pointer to a VkDeviceFaultInfoEXT structure in which fault information is returned.
If pFaultInfo is NULL, then the counts of corresponding additional
fault information structures available are returned in the
addressInfoCount and vendorInfoCount members of
pFaultCounts.
Additionally, the size of any vendor-specific binary crash dump is returned
in the vendorBinarySize member of pFaultCounts.
If pFaultInfo is not NULL, pFaultCounts must point to a
VkDeviceFaultCountsEXT structure with each structure count or size
member (addressInfoCount, vendorInfoCount,
vendorBinarySize) set by the application to the number of elements in
the corresponding output array member of pFaultInfo
(pAddressInfos and pVendorInfos), or to the size of the output
buffer in bytes (pVendorBinaryData).
On return, each structure count member is overwritten with the number of
structures actually written to the corresponding output array member of
pFaultInfo.
Similarly, vendorBinarySize is overwritten with the number of bytes
actually written to the pVendorBinaryData member of pFaultInfo.
If the vendor-specific crash dumps
feature is not enabled, then implementations must set
pFaultCounts->vendorBinarySize to zero and must not modify
pFaultInfo->pVendorBinaryData.
If any pFaultCounts structure count member is less than the number of
corresponding fault properties available, at most structure count
(addressInfoCount, vendorInfoCount) elements will be written to
the associated pFaultInfo output array.
Similarly, if vendorBinarySize is less than the size in bytes of the
available crash dump data, at most vendorBinarySize elements will be
written to pVendorBinaryData.
If pFaultInfo is NULL, then subsequent calls to
vkGetDeviceFaultInfoEXT for the same device must return
identical values in the addressInfoCount, vendorInfoCount and
vendorBinarySize members of pFaultCounts.
If pFaultInfo is not NULL, then subsequent calls to
vkGetDeviceFaultInfoEXT for the same device must return
identical values in the output members of pFaultInfo
(pAddressInfos, pVendorInfos, pVendorBinaryData), up to
the limits described by the structure count and buffer size members of
pFaultCounts (addressInfoCount, vendorInfoCount,
vendorBinarySize).
If the sizes of the output members of pFaultInfo increase for a
subsequent call to vkGetDeviceFaultInfoEXT, then supplementary
information may be returned in the additional available space.
If any pFaultCounts structure count member is smaller than the number
of corresponding fault properties available, or if
pFaultCounts->vendorBinarySize is smaller than the size in bytes of
the generated binary crash dump data, VK_INCOMPLETE will be returned
instead of VK_SUCCESS, to indicate that not all the available
properties were returned.
If pFaultCounts->vendorBinarySize is less than what is necessary to
store the binary crash dump header, nothing
will be written to pFaultInfo->pVendorBinaryData and zero will be
written to pFaultCounts->vendorBinarySize.
The VkDeviceFaultCountsEXT structure is defined as:
// Provided by VK_EXT_device_fault
typedef struct VkDeviceFaultCountsEXT {
VkStructureType sType;
void* pNext;
uint32_t addressInfoCount;
uint32_t vendorInfoCount;
VkDeviceSize vendorBinarySize;
} VkDeviceFaultCountsEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
addressInfoCountis the number of VkDeviceFaultAddressInfoEXT structures describing either memory accesses which may have caused a page fault, or the addresses of active instructions at the time of the fault. -
vendorInfoCountis the number of VkDeviceFaultVendorInfoEXT structures describing vendor-specific fault information. -
vendorBinarySizeis the size in bytes of a vendor-specific binary crash dump, which may provide additional information when imported into external tools.
The VkDeviceFaultInfoEXT structure is defined as:
// Provided by VK_EXT_device_fault
typedef struct VkDeviceFaultInfoEXT {
VkStructureType sType;
void* pNext;
char description[VK_MAX_DESCRIPTION_SIZE];
VkDeviceFaultAddressInfoEXT* pAddressInfos;
VkDeviceFaultVendorInfoEXT* pVendorInfos;
void* pVendorBinaryData;
} VkDeviceFaultInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description of the fault. -
pAddressInfosisNULLor a pointer to an array of VkDeviceFaultAddressInfoEXT structures describing either memory accesses which may have caused a page fault, or describing active instruction pointers at the time of the fault. If notNULL, each element ofpAddressInfosdescribes the a bounded region of GPU virtual address space containing either the GPU virtual address accessed, or the value of an active instruction pointer. -
pVendorInfosisNULLor a pointer to an array of VkDeviceFaultVendorInfoEXT structures describing vendor-specific fault information. -
pVendorBinaryDataisNULLor a pointer tovendorBinarySizenumber of bytes of data, which will be populated with a vendor-specific binary crash dump, as described in Vendor Binary Crash Dumps.
An implementation should populate as many members of VkDeviceFaultInfoEXT as possible, given the information available at the time of the fault and the constraints of the implementation itself.
Due to hardware limitations, pAddressInfos describes ranges of GPU
virtual address space, rather than precise addresses.
The precise memory address accessed or the precise value of the instruction
pointer must lie within the region described.
|
Note
|
Each element of
Comparison of the GPU virtual addresses described by |
The VkDeviceFaultAddressInfoEXT structure is defined as:
// Provided by VK_EXT_device_fault
typedef struct VkDeviceFaultAddressInfoEXT {
VkDeviceFaultAddressTypeEXT addressType;
VkDeviceAddress reportedAddress;
VkDeviceSize addressPrecision;
} VkDeviceFaultAddressInfoEXT;
-
addressTypeis either the type of memory operation that triggered a page fault, or the type of association between an instruction pointer and a fault. -
reportedAddressis the GPU virtual address recorded by the device. -
addressPrecisionis a power of two value that specifies how precisely the device can report the address.
The combination of reportedAddress and addressPrecision allow
the possible range of addresses to be calculated, such that:
lower_address = (pInfo->reportedAddress & ~(pInfo->addressPrecision-1))
upper_address = (pInfo->reportedAddress | (pInfo->addressPrecision-1))
|
Note
|
It is valid for the |
Possible values of VkDeviceFaultAddressInfoEXT::addressType are:
// Provided by VK_EXT_device_fault
typedef enum VkDeviceFaultAddressTypeEXT {
VK_DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT = 0,
VK_DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT = 1,
VK_DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT = 2,
VK_DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT = 3,
VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_UNKNOWN_EXT = 4,
VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT = 5,
VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT = 6,
} VkDeviceFaultAddressTypeEXT;
-
VK_DEVICE_FAULT_ADDRESS_TYPE_NONE_EXTspecifies that VkDeviceFaultAddressInfoEXT does not describe a page fault, or an instruction address. -
VK_DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXTspecifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid read operation. -
VK_DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXTspecifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid write operation. -
VK_DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXTdescribes a page fault triggered by an attempt to execute non-executable memory. -
VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_UNKNOWN_EXTspecifies an instruction pointer value at the time the fault occurred. This may or may not be related to a fault. -
VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXTspecifies an instruction pointer value associated with an invalid instruction fault. -
VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXTspecifies an instruction pointer value associated with a fault.
|
Note
|
The instruction pointer values recorded may not identify the specific instruction(s) that triggered the fault. The relationship between the instruction pointer reported and triggering instruction will be vendor-specific. |
The VkDeviceFaultVendorInfoEXT structure is defined as:
// Provided by VK_EXT_device_fault
typedef struct VkDeviceFaultVendorInfoEXT {
char description[VK_MAX_DESCRIPTION_SIZE];
uint64_t vendorFaultCode;
uint64_t vendorFaultData;
} VkDeviceFaultVendorInfoEXT;
-
descriptionis an array ofVK_MAX_DESCRIPTION_SIZEcharcontaining a null-terminated UTF-8 string which is a human readable description of the fault. -
vendorFaultCodeis the vendor-specific fault code for this fault. -
vendorFaultDatais the vendor-specific fault data associated with this fault.
Vendor Binary Crash Dumps
Applications can store the vendor-specific binary crash dump data retrieved by calling vkGetDeviceFaultInfoEXT for later analysis using external tools.
However, the format of this data may depend on the vendor ID, device ID,
driver version, and other details of the device.
To enable external applications to identify the original device from which a
crash dump was generated, the initial bytes written to
VkDeviceFaultInfoEXT::pVendorBinaryData must begin with a valid
crash dump header.
Version one of the crash dump header is defined as:
// Provided by VK_EXT_device_fault
typedef struct VkDeviceFaultVendorBinaryHeaderVersionOneEXT {
uint32_t headerSize;
VkDeviceFaultVendorBinaryHeaderVersionEXT headerVersion;
uint32_t vendorID;
uint32_t deviceID;
uint32_t driverVersion;
uint8_t pipelineCacheUUID[VK_UUID_SIZE];
uint32_t applicationNameOffset;
uint32_t applicationVersion;
uint32_t engineNameOffset;
uint32_t engineVersion;
uint32_t apiVersion;
} VkDeviceFaultVendorBinaryHeaderVersionOneEXT;
-
headerSizeis the length in bytes of the crash dump header. -
headerVersionis a VkDeviceFaultVendorBinaryHeaderVersionEXT enum value specifying the version of the header. A consumer of the crash dump should use the header version to interpret the remainder of the header.headerVersionmust be written as exactly 4 bytes. -
vendorIDis theVkPhysicalDeviceProperties::vendorIDof the implementation. -
deviceIDis theVkPhysicalDeviceProperties::deviceIDof the implementation. -
driverVersionis theVkPhysicalDeviceProperties::driverVersionof the implementation. -
pipelineCacheUUIDis an array ofVK_UUID_SIZEuint8_tvalues matching theVkPhysicalDeviceProperties::pipelineCacheUUIDproperty of the implementation. -
applicationNameOffsetis zero, or an offset from the base address of the crash dump header to a null-terminated UTF-8 string containing the name of the application. IfapplicationNameOffsetis non-zero, this string must match the application name specified via VkApplicationInfo::pApplicationNameduring instance creation. -
applicationVersionmust be zero or the value specified by VkApplicationInfo::applicationVersionduring instance creation. -
engineNameOffsetis zero, or an offset from the base address of the crash dump header to a null-terminated UTF-8 string containing the name of the engine (if any) used to create the application. IfengineNameOffsetis non-zero, this string must match the engine name specified via VkApplicationInfo::pEngineNameduring instance creation. -
engineVersionmust be zero or the value specified by VkApplicationInfo::engineVersionduring instance creation. -
apiVersionmust be zero or the value specified by VkApplicationInfo::apiVersionduring instance creation.
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 56 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 crash dump header
are:
// Provided by VK_EXT_device_fault
typedef enum VkDeviceFaultVendorBinaryHeaderVersionEXT {
VK_DEVICE_FAULT_VENDOR_BINARY_HEADER_VERSION_ONE_EXT = 1,
} VkDeviceFaultVendorBinaryHeaderVersionEXT;
-
VK_DEVICE_FAULT_VENDOR_BINARY_HEADER_VERSION_ONE_EXTspecifies version one of the binary crash dump header.
53.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 application
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 a VkStructureType value identifying 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,
// Provided by VK_EXT_tooling_info
VK_TOOL_PURPOSE_VALIDATION_BIT_EXT = VK_TOOL_PURPOSE_VALIDATION_BIT,
// Provided by VK_EXT_tooling_info
VK_TOOL_PURPOSE_PROFILING_BIT_EXT = VK_TOOL_PURPOSE_PROFILING_BIT,
// Provided by VK_EXT_tooling_info
VK_TOOL_PURPOSE_TRACING_BIT_EXT = VK_TOOL_PURPOSE_TRACING_BIT,
// Provided by VK_EXT_tooling_info
VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT_EXT = VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT,
// Provided by VK_EXT_tooling_info
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.
53.6. Frame Boundary
The VkFrameBoundaryEXT structure is defined as:
// Provided by VK_EXT_frame_boundary
typedef struct VkFrameBoundaryEXT {
VkStructureType sType;
const void* pNext;
VkFrameBoundaryFlagsEXT flags;
uint64_t frameID;
uint32_t imageCount;
const VkImage* pImages;
uint32_t bufferCount;
const VkBuffer* pBuffers;
uint64_t tagName;
size_t tagSize;
const void* pTag;
} VkFrameBoundaryEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkFrameBoundaryFlagBitsEXT that can flag the last submission of a frame identifier. -
frameIDis the frame identifier. -
imageCountis the number of images that store frame results. -
pImagesis a pointer to an array of VkImage objects with imageCount entries. -
bufferCountis the number of buffers the store the frame results. -
pBuffersis a pointer to an array of VkBuffer objects with bufferCount entries. -
tagNameis a numerical identifier for tag data. -
tagSizeis the number of bytes of tag data. -
pTagis a pointer to an array oftagSizebytes containing tag data.
The application can associate frame boundary information to a queue
submission call by adding a VkFrameBoundaryEXT structure to the
pNext chain of queue submission,
VkPresentInfoKHR,
or VkBindSparseInfo.
|
Note
|
The frame identifier is used to associate one or more queue submissions to a frame. It is meant to be unique within a frame lifetime, i.e. it is possible (though not recommended) to reuse frame identifiers, as long as any two frames that may have overlapping queue submissions (as in the example above) use different frame identifiers. Since the concept of frame is application-dependent, there is no way to validate the use of frame identifier. It is good practice to use a monotonically increasing counter as the frame identifier and not reuse identifiers between frames. |
The pImages and pBuffers arrays contain a list of images and
buffers which store the "end result" of the frame.
As the concept of frame is application-dependent, not all frames may
produce their results in images or buffers, yet this is a sufficiently
common case to be handled by VkFrameBoundaryEXT.
Note that no extra information, such as image layout is being provided,
since the images are meant to be used by tools which would already be
tracking this required information.
Having the possibility of passing a list of end-result images makes
VkFrameBoundaryEXT as expressive as vkQueuePresentKHR, which is
often the default frame boundary delimiter.
The application can also associate arbitrary extra information via tag data
using tagName, tagSize and pTag.
This extra information is typically tool-specific.
The bit which can be set in VkFrameBoundaryEXT::flags is:
// Provided by VK_EXT_frame_boundary
typedef enum VkFrameBoundaryFlagBitsEXT {
VK_FRAME_BOUNDARY_FRAME_END_BIT_EXT = 0x00000001,
} VkFrameBoundaryFlagBitsEXT;
-
VK_FRAME_BOUNDARY_FRAME_END_BIT_EXTspecifies that this queue submission is the last one for this frame, i.e. once this queue submission has terminated, then the work for this frame is completed.
Note that in the presence of timeline semaphores, the last queue submission might not be the last one to be submitted, as timeline semaphores allow for wait-before-signal submissions. In the context of frame boundary, the queue submission that should be done flagged as the last one is the one that is meant to be executed last, even if it may not be the last one to be submitted.
// Provided by VK_EXT_frame_boundary
typedef VkFlags VkFrameBoundaryFlagsEXT;
VkFrameBoundaryFlagsEXT is a bitmask type for setting a mask of zero or more VkFrameBoundaryFlagBitsEXT.
The VkFrameBoundaryTensorsARM structure is defined as:
// Provided by VK_EXT_frame_boundary with VK_ARM_tensors
typedef struct VkFrameBoundaryTensorsARM {
VkStructureType sType;
const void* pNext;
uint32_t tensorCount;
const VkTensorARM* pTensors;
} VkFrameBoundaryTensorsARM;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
tensorCountis the number of tensors that store frame results. -
pTensorsis a pointer to an array of VkTensorARM objects with tensorCount entries.
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.4 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 operations on all floating-point values:
-
Positive and negative infinities and positive and negative zeros are generated as dictated by IEEE 754 for the specified encoding, but subject to the precisions allowed by each operation for a given encoding, as specified in Precision of Individual Operations.
-
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.
-
The set of operations
OpPhi,OpSelect,OpFunctionCall,OpReturnValue,OpVectorExtractDynamic,OpVectorInsertDynamic,OpVectorShuffle,OpCompositeConstruct,OpCompositeExtract,OpCompositeInsert,OpTranspose,OpCopyObject,OpCopyLogical,OpCopyMemory,OpGroupNonUniformBroadcast,OpGroupNonUniformBroadcastFirst,OpGroupNonUniformShuffle,OpGroupNonUniformShuffleXor,OpGroupNonUniformShuffleUp,OpGroupNonUniformShuffleDown,OpGroupNonUniformQuadBroadcast,OpGroupNonUniformQuadSwap,OpSubgroupReadInvocationKHR,OpSubgroupFirstInvocationKHR,OpGroupNonUniformRotateKHR,OpCooperativeMatrixLoadKHR,OpCooperativeMatrixStoreKHR,OpCooperativeMatrixLoadNV,OpCooperativeMatrixStoreNV,OpCooperativeMatrixLoadTensorNV,OpCooperativeMatrixStoreTensorNV,OpAtomicLoad,OpAtomicStore,OpAtomicExchange,OpStore, andOpLoadare referred to as bit-preserving operations. -
The floating-point environment used for an instruction can be determined as follows:
-
If the SPIR-V specifies it explicitly using the
FPFastMathdecoration orFPFastMathDefaultExecutionModethen that is used. -
If the environment is not specified in the SPIR-V then it is determined as follows:
-
If the operation is not decorated
NoContractionthen the flagsAllowContract,AllowReassoc,AllowRecip, andAllowTransformare assumed. -
If any of the following conditions are true then the flags
NSZ,NotInf, andNotNaNare assumed:-
The entry point does not use the
ExecutionModeSignedZeroInfNanPreservewith a bit-width corresponding to one of the operands or to the result type. -
The operation is not a bit-preserving operation and is not one of
OpFConvert,OpFNegate,OpFAdd,OpFSub,OpFMul,OpFDiv,OpIsNan,OpIsInf,OpVectorTimesScalar,OpMatrixTimesScalar,OpVectorTimesMatrix,OpMatrixTimesVector,OpMatrixTimesMatrix,OpOuterProduct,OpDot,OpFOrdEqual,OpFUnordEqual,OpFOrdNotEqual,OpFUnordNotEqual,OpFOrdLessThan,OpFUnordLessThan,OpFOrdGreaterThan,OpFUnordGreaterThan,OpFOrdLessThanEqual,OpFUnordLessThanEqual,OpFOrdGreaterThanEqual,OpFUnordGreaterThanEqual,OpGroupNonUniformAllEqual,OpSubgroupAllEqualKHR,OpGroupNonUniformFMin,OpGroupNonUniformFMax,OpAtomicCompareExchange,OpAtomicCompareExchangeWeak,OpDPdx,OpDPdy,OpFwidth,OpDPdxFine,OpDPdyFine,OpFwidthFine,OpDPdxCoarse,OpDPdyCoarse, orOpFwidthCoarse. -
The operation is an
OpLoadfrom theInputStorageClassin the fragment shader stage.
-
-
-
-
All bit-preserving operations and the following instructions must not flush denormalized values:
OpConstant,OpConstantComposite,OpSpecConstant,OpSpecConstantComposite, andOpBitcast. -
Denormalized values are supported.
-
By default any denormalized floating-point 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.
-
Denormalized floating-point values whose type use the
Float8E4M3EXTorFloat8E5M2EXTFP Encoding must be preserved during conversions to IEEE 754 binary 16 floating-point values. -
If the entry point is declared with the
DenormFlushToZeroExecutionModethen for the affected instructions 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
DenormFlushToZeroExecutionMode:OpSpecConstantOp(with opcodeOpFConvert),OpFConvert,OpFNegate,OpFAdd,OpFSub,OpFMul,OpFDiv,OpFRem,OpFMod,OpVectorTimesScalar,OpMatrixTimesScalar,OpVectorTimesMatrix,OpMatrixTimesVector,OpMatrixTimesMatrix,OpOuterProduct,OpDot,OpGroupNonUniformFMin,OpGroupNonUniformFMax,OpAtomicFAddEXT,OpAtomicFMinEXT,OpAtomicFMaxEXT,OpDPdx,OpDPdy,OpFwidth,OpDPdxFine,OpDPdyFineOpFwidthFine,OpDPdxCoarse,OpDPdyCoarse,OpFwidthCoarse; 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,Length,Distance,Cross,Normalize,FaceForward,Reflect,Refract,NMin,NMax, andNClamp. -
The following core SPIR-V instructions must respect the
DenormPreserveExecutionModefor floating-point values with an IEEE 754 encoding: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,OpSubgroupAllEqualKHR,OpGroupNonUniformAllEqual,OpGroupNonUniformFMin,OpGroupNonUniformFMax,OpAtomicCompareExchange,OpAtomicCompareExchangeWeak,OpAtomicFAddEXT,OpAtomicFMinEXT,OpAtomicFMaxEXT,OpDPdx,OpDPdy,OpFwidth,OpDPdxFine,OpDPdyFineOpFwidthFine,OpDPdxCoarse,OpDPdyCoarse,OpFwidthCoarse; and the following extended instructions for GLSL:FAbs,FSign,Radians,Degrees,FMin,FMax,FClamp,FMix,Fma,PackHalf2x16,PackDouble2x32,UnpackHalf2x16,UnpackDouble2x32,NMin,NMax, andNClamp.
-
The precision of double-precision instructions is at least that of single precision.
The precision of individual operations is defined in Precision of Individual Operations. Subject to the constraints below, however, implementations may reorder or combine operations, resulting in expressions exhibiting different precisions than might be expected from the constituent operations.
Evaluation of Expressions
Implementations may rearrange floating-point operations using any of the
mathematical properties governing the expressions in precise arithmetic,
even where the floating- point operations do not share these properties.
This includes, but is not limited to, associativity and distributivity, and
may involve a different number of rounding steps than would occur if the
operations were not rearranged.
In shaders that use the SignedZeroInfNanPreserve Execution Mode the
values must be preserved if they are generated after any rearrangement but
the Execution Mode does not change which rearrangements are valid.
This rearrangement can be prevented for particular operations by using the
NoContraction decoration.
|
Note
|
For example, in the absence of the If the |
Precision of Individual Operations
The precision of individual operations is defined either in terms of rounding (correctly rounded), as an error bound in ULP, or as inherited from a formula as follows:
Operations that are described as returning the “correct result” will return the infinitely precise result which, due to the nature of the operation, will not need rounding.
Operations described as “correctly rounded” will return the infinitely
precise result, x, rounded so as to be representable in
floating-point.
If the entry point is declared with the RoundingModeRTE or the
RoundingModeRTZ Execution Mode then this is done according to
IEEE 754 “roundTiesToEven” or “roundTowardZero” rounding
directions, respectively.
These execution modes do not affect operations on floating-point values with
the following encodings:
-
BFloat16KHR -
Float8E4M3EXT -
Float8E5M2EXT
Otherwise, they are rounded with implementation-defined rounding mode.
Operations described as “correctly rounded with implementation-defined rounding mode” will return the infinitely precise result, x, rounded so as to be representable in floating-point. 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. Which value is chosen is implementation-defined.
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, finite 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 non-equal, 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.
The precision of all instructions on float values with the BFloat16KHR
encoding is required to be
correctly rounded with
implementation defined rounding mode.
For IEEE754 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 |
|---|---|---|
|
Correct result. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Inherited from . |
|
|
Inherited from . |
|
|
Inherited from . |
|
|
Correctly rounded. |
|
|
Inherited from . |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
2.5 ULP for |y| = 0 or |y| in the range [2-126, 2126]. |
2.5 ULP for |y| = 0 or |y| in the range [2-14, 214]. |
|
Inherited from x - y × trunc(x/y). |
|
|
Inherited from x - y × floor(x/y). |
|
|
Correctly rounded with implementation defined rounding mode. |
|
conversions between types |
Correctly rounded. |
|
|
Correct result. |
|
|
Return value correct result, value in memory correctly rounded. |
|
|
Correct result. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
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 , where is a correctly rounded approximation to . |
|
|
Inherited from , where is a correctly rounded approximation to . |
|
|
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 . |
|
|
Correct result. |
|
|
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. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correctly rounded. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Inherited from . |
|
|
Correctly rounded. |
|
|
Inherited from , where . |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correct result. |
|
|
Correctly rounded with implementation defined rounding mode. |
|
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.
If the maintenance8 feature is not enabled
and if
either operand to OpSRem and OpSMod instructions is negative the
result is undefined.
|
Note
|
While the |
OpCooperativeMatrixMulAddNV performs its operations in an
implementation-dependent order and internal precision.
OpCooperativeMatrixMulAddKHR performs its operations in an
implementation-dependent order and internal precision.
OpCooperativeVectorMatrixMulNV and
OpCooperativeVectorMatrixMulAddNV perform their operations in an
implementation-dependent order and internal precision.
When inputType is VK_COMPONENT_TYPE_FLOAT16_KHR and
inputInterpretation is a lower-precision floating-point type (e.g.
VK_COMPONENT_TYPE_FLOAT_E4M3_NV or
VK_COMPONENT_TYPE_FLOAT_E5M2_NV), the input vector should be
converted to the lower-precision type before performing the matrix-vector
multiply, but may keep the full 16 bits of precision.
Buffer Indexing Calculations
Pipelines and shaders may be compiled to use 32-bit integer arithmetic to
compute byte offsets (e.g. based on OpAccessChain instructions) within
a
physical storage buffer or
buffer, limiting the accessible range to 4GB.
For physical storage buffers, the base address is a 64-bit value and the
implicit base plus offset calculation uses 64-bit addition.
|
Note
|
Note that |
The offset calculations that have the 4GB limit include:
-
OpAccessChainandOpPtrAccessChain- the total offset summed over all indices multiplied by strides, including spanning multiple access chain instructions that lead to a given memory access. -
OpCooperativeMatrixLoadKHRandOpCooperativeMatrixStoreKHRinstructions computing an offset based on element, row, and stride parameters. -
OpCooperativeMatrixLoadKHRandOpCooperativeMatrixStoreKHRinstructions computing an offset based on element, row, and stride parameters. -
OpCooperativeMatrixLoadTensorNVandOpCooperativeMatrixStoreTensorNVinstructions computing an offset based on tensor layout state.
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-Declaration instructions | Bit Width | Signedness |
|---|---|---|---|
|
Any |
Any |
Any |
|
|
32 |
N/A |
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|
32 |
1 |
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
0 |
||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|
64 |
1 |
|
0 |
The SPIR-V Type is defined by an instruction in SPIR-V, declared with the Type-Declaration Instruction, Bit Width, and Signedness from above.
Compatibility Between SPIR-V Image Dimensions and Vulkan ImageView Types
SPIR-V Image Dim values are compatible with VkImageView
viewType values as defined below:
| SPIR-V Image Dim | Compatible Vulkan ImageView viewTypes |
|---|---|
1D |
|
2D |
|
3D |
|
Cube |
|
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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Ray Query Precision and Operation
The values returned by
OpRayQueryGetIntersectionTriangleVertexPositionsKHR are transformed by
the geometry transform, which is performed at standard
floating-point precision, but without a
specifically defined order of floating-point operations to perform the
matrix multiplication.
Compatibility Between SPIR-V Tensor Element Types And Vulkan Formats
SPIR-V Tensor Element Type values are compatible with
VkFormat values as defined below:
| SPIR-V Tensor Element Type | Compatible Vulkan Formats |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Appendix B: Memory Model
|
Note
|
This memory model describes synchronizations provided by all implementations; however, some of the synchronizations defined require extra features to be supported by the implementation. See VkPhysicalDeviceVulkanMemoryModelFeatures. |
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://registry.khronos.org/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 shader call 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 shader call 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 shader call 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.
|
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
, or NonPrivateElementARM
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. 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 operations, 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,
or a tensor write instruction that includes MakeElementAvailableARM,
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,
or a tensor read instruction that includes MakeElementVisibleARM
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 location 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 signaled 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 instruction
(OpCooperativeMatrixLoadKHR
, OpCooperativeMatrixLoadNV
, OpCooperativeMatrixLoadTensorNV
), some implementation-dependent invocation(s) within the instance of the
matrix’s scope perform a non-atomic load from each memory location that is
defined to be accessed by the instruction.
For each memory location accessed by a dynamic instance of a cooperative
matrix store instruction (OpCooperativeMatrixStoreKHR
, OpCooperativeMatrixStoreNV
, OpCooperativeMatrixStoreTensorNV
), a single implementation-dependent invocation within the instance of the
matrix’s scope performs a non-atomic store to that memory location.
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.
Vulkan Version 1.4
Vulkan Version 1.4 promoted a number of key extensions into the core API:
All differences in behavior between these extensions and the corresponding Vulkan 1.4 functionality are summarized below.
- Differences Relative to
VK_KHR_dynamic_rendering_local_read -
If the VK_KHR_dynamic_rendering_local_read extension is not supported, Vulkan 1.4 implementations must support local read only for storage resources and single sampled color attachments.
Support for reading depth/stencil attachments and multi-sampled attachments are respectively gated behind the new boolean
dynamicRenderingLocalReadDepthStencilAttachmentsanddynamicRenderingLocalReadMultisampledAttachmentsproperties.-
If
dynamicRenderingLocalReadDepthStencilAttachmentsisVK_FALSE, implementations do not support depth/stencil attachment access within dynamic rendering. -
If
dynamicRenderingLocalReadMultisampledAttachmentsisVK_FALSE, implementations do not support multisampled attachment access within dynamic rendering. -
If both properties are
VK_TRUE, the full functionality of the extension is supported.
-
- Differences Relative to
VK_EXT_host_image_copy -
If the VK_EXT_host_image_copy extension is not supported, support for it is optional in Vulkan 1.4.
-
An implementation that has a
VK_QUEUE_GRAPHICS_BITqueue must support either:-
the
hostImageCopyfeature; or -
an additional queue that supports
VK_QUEUE_TRANSFER_BIT.
-
-
- Differences Relative to
VK_KHR_push_descriptor -
VK_KHR_push_descriptor did not include a feature bit, so a new feature bit has been added to VkPhysicalDeviceVulkan14Features to gate its functionality:
pushDescriptor. Enabling this new feature has the same effect as enabling the extension. - Differences Relative to
VK_EXT_pipeline_protected_access -
VK_EXT_pipeline_protected_access is only useful when the
protectedMemoryfeature is supported. As theprotectedMemoryfeature is optional in core Vulkan, thepipelineProtectedAccessfeature is only required when theprotectedMemoryfeature is supported. - Differences Relative to
VK_KHR_line_rasterization -
The
bresenhamLinesfeature is required, rather than just any one of the line style features. - Differences Relative to
VK_KHR_shader_subgroup_rotate -
The
shaderSubgroupRotateClusteredfeature is required in addition toshaderSubgroupRotate. - Additional Vulkan 1.4 Feature Support
-
In addition to the promoted extensions described above, Vulkan 1.4 added required support for:
-
All queues supporting
VK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BITmust also advertiseVK_QUEUE_TRANSFER_BIT. -
Clustered subgroup operations must be advertised in Vulkan 1.4 via setting both
VK_SUBGROUP_FEATURE_CLUSTERED_BITandVK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT(as an interaction with the promoted VK_KHR_shader_subgroup_rotate functionality) insupportedOperations. -
The following features that were optional in earlier versions:
-
- Updated Vulkan 1.4 Limit Support
-
Vulkan 1.4 also requires support for the following updated limits:
-
maxImageDimension1Dis increased from 4096 to 8192 -
maxImageDimension2Dis increased from 4096 to 8192 -
maxImageDimension3Dis increased from 256 to 512 -
maxImageDimensionCubeis increased from 4096 to 8192 -
maxImageArrayLayersis increased from 256 to 2048 -
maxUniformBufferRangeis increased from 16384 to 65536 -
maxPushConstantsSizeis increased from 128 to 256 -
bufferImageGranularityis decreased from 131072 to 4096 -
maxBoundDescriptorSetsis increased from 4 to 7 -
maxPerStageDescriptorUniformBuffersis increased from 12 to 15 -
maxPerStageResourcesis increased from 128 to 200 -
maxDescriptorSetUniformBuffersis increased from 72 to 90 -
maxDescriptorSetStorageBuffersis increased from 24 to 96 -
maxDescriptorSetStorageImagesis increased from 24 to 144 -
maxFragmentCombinedOutputResourcesis increased from 4 to 16 -
maxComputeWorkGroupInvocationsis increased from 128 to 256 -
maxComputeWorkGroupSizeis increased from (128,128,64) to (256,256,64) -
shaderSignedZeroInfNanPreserveFloat16is changed from unspecified toVK_TRUE -
shaderSignedZeroInfNanPreserveFloat32is changed from unspecified toVK_TRUE -
subTexelPrecisionBitsis increased from 4 to 8 -
mipmapPrecisionBitsis increased from 4 to 6 -
maxSamplerLodBiasis increased from 2 to 14 -
maxViewportDimensionsis increased from (4096,4096) to (7680,7680) -
viewportBoundsRangeis increased from (-8192,8191) to (-15360,15359) -
maxFramebufferWidthis increased from 4096 to 7680 -
maxFramebufferHeightis increased from 4096 to 7680 -
maxColorAttachmentsis increased from 7 to 8 -
timestampComputeAndGraphicsis changed from unspecified toVK_TRUE -
pointSizeRangeis increased from (1.0,64.0 - ULP) to (1.0,256.0 -pointSizeGranularity) -
pointSizeGranularityis decreased from 1.0 to 0.125 -
lineWidthGranularityis decreased from 1.0 to 0.5 -
maxPushDescriptorsis increased from 16 to 32 -
standardSampleLocationsis changed from unspecified toVK_TRUE
-
New Structures
-
Extending VkBindBufferMemoryInfo, VkBindImageMemoryInfo:
-
Extending VkBufferViewCreateInfo, VkBufferCreateInfo, VkPhysicalDeviceExternalBufferInfo, VkDescriptorBufferBindingInfoEXT:
-
Extending VkComputePipelineCreateInfo, VkGraphicsPipelineCreateInfo, VkRayTracingPipelineCreateInfoNV, VkRayTracingPipelineCreateInfoKHR:
-
Extending VkDeviceQueueCreateInfo:
-
Extending VkGraphicsPipelineCreateInfo, VkCommandBufferInheritanceInfo:
-
Extending VkGraphicsPipelineCreateInfo, VkComputePipelineCreateInfo, VkPipelineShaderStageCreateInfo, VkRayTracingPipelineCreateInfoKHR:
-
Extending VkImageFormatProperties2:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineRasterizationStateCreateInfo:
-
Extending VkPipelineVertexInputStateCreateInfo:
-
Extending VkQueueFamilyProperties2:
-
Extending VkSubresourceLayout2:
New Enum Constants
-
VK_MAX_GLOBAL_PRIORITY_SIZE -
Extending VkAttachmentLoadOp:
-
VK_ATTACHMENT_LOAD_OP_NONE
-
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT
-
-
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT
-
-
Extending VkDescriptorUpdateTemplateType:
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_LINE_STIPPLE
-
-
Extending VkFormat:
-
VK_FORMAT_A1B5G5R5_UNORM_PACK16 -
VK_FORMAT_A8_UNORM
-
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_HOST_TRANSFER_BIT
-
-
Extending VkIndexType:
-
VK_INDEX_TYPE_UINT8
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT -
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT
-
-
Extending VkResult:
-
VK_ERROR_NOT_PERMITTED
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BIND_DESCRIPTOR_SETS_INFO -
VK_STRUCTURE_TYPE_BIND_MEMORY_STATUS -
VK_STRUCTURE_TYPE_BUFFER_USAGE_FLAGS_2_CREATE_INFO -
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO -
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO -
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO -
VK_STRUCTURE_TYPE_DEVICE_IMAGE_SUBRESOURCE_INFO -
VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO -
VK_STRUCTURE_TYPE_HOST_IMAGE_COPY_DEVICE_PERFORMANCE_QUERY -
VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO -
VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2 -
VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY -
VK_STRUCTURE_TYPE_MEMORY_MAP_INFO -
VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY -
VK_STRUCTURE_TYPE_MEMORY_UNMAP_INFO -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_LOCAL_READ_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GLOBAL_PRIORITY_QUERY_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_PROTECTED_ACCESS_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_ROBUSTNESS_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_EXPECT_ASSUME_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT_CONTROLS_2_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_ROTATE_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_4_FEATURES -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_4_PROPERTIES -
VK_STRUCTURE_TYPE_PIPELINE_CREATE_FLAGS_2_CREATE_INFO -
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO -
VK_STRUCTURE_TYPE_PIPELINE_ROBUSTNESS_CREATE_INFO -
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO -
VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO -
VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_INFO -
VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_WITH_TEMPLATE_INFO -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_GLOBAL_PRIORITY_PROPERTIES -
VK_STRUCTURE_TYPE_RENDERING_AREA_INFO -
VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_LOCATION_INFO -
VK_STRUCTURE_TYPE_RENDERING_INPUT_ATTACHMENT_INDEX_INFO -
VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE -
VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2
-
-
Extending VkSubgroupFeatureFlagBits:
-
VK_SUBGROUP_FEATURE_ROTATE_BIT -
VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT
-
Vulkan 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_formatsextension 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 commands defined by
VK_EXT_extended_dynamic_stateare 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 commands defined by
VK_EXT_extended_dynamic_state2for 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. The
texelBufferAlignmentfeature is enabled if using a Vulkan 1.3 instance. - Differences Relative to
VK_EXT_texture_compression_astc_hdr -
If the
VK_EXT_texture_compression_astc_hdrextension is not supported, support for all formats defined by it are optional in Vulkan 1.3. ThetextureCompressionASTC_HDRmember 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_formatsextension 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, VkExecutionGraphPipelineCreateInfoAMDX, VkDataGraphPipelineCreateInfoARM:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineShaderStageCreateInfo, VkShaderCreateInfoEXT:
-
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 VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_CUBIC_BIT
-
-
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
-
Vulkan 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_storageextension is not supported, support for the SPIR-VstorageBuffer8BitAccesscapability in shader modules is optional. Support for this feature is defined by VkPhysicalDeviceVulkan12Features::storageBuffer8BitAccesswhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_KHR_draw_indirect_count -
If the
VK_KHR_draw_indirect_countextension is not supported, support for the commands vkCmdDrawIndirectCount and vkCmdDrawIndexedIndirectCount is optional. Support for this feature is defined by VkPhysicalDeviceVulkan12Features::drawIndirectCountwhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_KHR_sampler_mirror_clamp_to_edge -
If the
VK_KHR_sampler_mirror_clamp_to_edgeextension is not supported, support for the VkSamplerAddressModeVK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGEis optional. Support for this feature is defined by VkPhysicalDeviceVulkan12Features::samplerMirrorClampToEdgewhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_EXT_descriptor_indexing -
If the
VK_EXT_descriptor_indexingextension is not supported, support for thedescriptorIndexingfeature is optional. Support for this feature is defined by VkPhysicalDeviceVulkan12Features::descriptorIndexingwhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_EXT_scalar_block_layout -
If the
VK_EXT_scalar_block_layoutextension is not supported, support for thescalarBlockLayoutfeature is optional. Support for this feature is defined by VkPhysicalDeviceVulkan12Features::scalarBlockLayoutwhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_EXT_shader_viewport_index_layer -
The
ShaderViewportIndexLayerEXTSPIR-V capability was replaced with theShaderViewportIndexandShaderLayercapabilities. Declaring both is equivalent to declaringShaderViewportIndexLayerEXT. If theVK_EXT_shader_viewport_index_layerextension is not supported, support for theShaderViewportIndexLayerEXTSPIR-V capability is optional. Support for this feature is defined by VkPhysicalDeviceVulkan12Features::shaderOutputViewportIndexand VkPhysicalDeviceVulkan12Features::shaderOutputLayerwhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_KHR_buffer_device_address -
If the
VK_KHR_buffer_device_addressextension is not supported, support for thebufferDeviceAddressfeature is optional. Support for this feature is defined by VkPhysicalDeviceVulkan12Features::bufferDeviceAddresswhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_KHR_shader_atomic_int64 -
If the
VK_KHR_shader_atomic_int64extension is not supported, support for theshaderBufferInt64Atomicsfeature is optional. Support for this feature is defined by VkPhysicalDeviceVulkan12Features::shaderBufferInt64Atomicswhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_KHR_shader_float16_int8 -
If the
VK_KHR_shader_float16_int8extension is not supported, support for theshaderFloat16andshaderInt8features is optional. Support for these features are defined by VkPhysicalDeviceVulkan12Features::shaderFloat16and VkPhysicalDeviceVulkan12Features::shaderInt8when queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_KHR_vulkan_memory_model -
If the
VK_KHR_vulkan_memory_modelextension is not supported, support for thevulkanMemoryModelfeature is optional. Support for this feature is defined by VkPhysicalDeviceVulkan12Features::vulkanMemoryModelwhen 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
-
Vulkan 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_storageextension is not supported, support for thestorageBuffer16BitAccessfeature is optional. Support for this feature is defined by VkPhysicalDevice16BitStorageFeatures::storageBuffer16BitAccessor VkPhysicalDeviceVulkan11Features::storageBuffer16BitAccesswhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_KHR_sampler_ycbcr_conversion -
If the
VK_KHR_sampler_ycbcr_conversionextension is not supported, support for thesamplerYcbcrConversionfeature is optional. Support for this feature is defined by VkPhysicalDeviceSamplerYcbcrConversionFeatures::samplerYcbcrConversionor VkPhysicalDeviceVulkan11Features::samplerYcbcrConversionwhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_KHR_shader_draw_parameters -
If the
VK_KHR_shader_draw_parametersextension is not supported, support for theSPV_KHR_shader_draw_parametersSPIR-V extension is optional. Support for this feature is defined by VkPhysicalDeviceShaderDrawParametersFeatures::shaderDrawParametersor VkPhysicalDeviceVulkan11Features::shaderDrawParameterswhen queried via vkGetPhysicalDeviceFeatures2. - Differences Relative to
VK_KHR_variable_pointers -
If the
VK_KHR_variable_pointersextension is not supported, support for thevariablePointersStorageBufferfeature is optional. Support for this feature is defined by VkPhysicalDeviceVariablePointersFeatures::variablePointersStorageBufferor VkPhysicalDeviceVulkan11Features::variablePointersStorageBufferwhen queried via vkGetPhysicalDeviceFeatures2. - Additional Vulkan 1.1 Feature Support
-
In addition to the promoted extensions described above, Vulkan 1.1 added support for:
-
SPIR-V version 1.1
-
SPIR-V version 1.2
-
SPIR-V version 1.3
-
The group operations and subgroup scope.
-
The protected memory feature.
-
A new command to enumerate the instance version: vkEnumerateInstanceVersion.
-
The VkPhysicalDeviceShaderDrawParametersFeatures feature query structure (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
-
Vulkan Version 1.0
Vulkan Version 1.0 was the initial release of the Vulkan API.
New Structures
-
Extending VkBindDescriptorSetsInfo, VkPushConstantsInfo, VkPushDescriptorSetInfo, VkPushDescriptorSetWithTemplateInfo, VkSetDescriptorBufferOffsetsInfoEXT, VkBindDescriptorBufferEmbeddedSamplersInfoEXT, VkIndirectCommandsLayoutCreateInfoEXT:
-
Extending VkPipelineShaderStageCreateInfo, VkDataGraphPipelineShaderModuleCreateInfoARM:
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. The online Registry of extensions is available at URL
Authors creating extensions and layers must follow the mandatory procedures described in the Vulkan Documentation and Extensions document when creating extensions and layers.
The version of the Vulkan specification published on the Vulkan Documentation site and in the Registry includes all registered and published extensions. It is also possible to build the specification with an arbitrary set of extensions included, and the specification you are viewing may not include all extensions.
In the remainder of this appendix, 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.
Extension Dependencies
Extensions which have dependencies on specific core versions or on other extensions will list such dependencies.
For core versions, the specified version must be supported at runtime. All extensions implicitly require support for Vulkan 1.0.
For a device extension, use of any device-level functionality defined by that extension requires that any extensions that extension depends on be enabled.
For any extension, use of any instance-level functionality defined by that extension requires only that any extensions that extension depends on be supported at runtime.
Extension Interactions
Some extensions define APIs which are only supported when other extensions or core versions are supported at runtime. Such interactions are noted as “API Interactions”.
List of Current Extensions
VK_KHR_acceleration_structure
- Name String
-
VK_KHR_acceleration_structure - Extension Type
-
Device extension
- Registered Extension Number
-
151
- Revision
-
13
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_2
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_EXT_debug_report
-
Interacts with VK_KHR_format_feature_flags2
-
- Contact
-
-
Daniel Koch [GitHub]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 VkCopyAccelerationStructureModeKHR:
-
VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR -
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR
-
-
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_EXT_debug_report is supported:
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR_EXT
-
If VK_KHR_format_feature_flags2 or Vulkan Version 1.3 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jesse Hall [GitHub]critsec
-
Other Extension Metadata
- Last Modified Date
-
2016-01-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Faith 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_calibrated_timestamps
- Name String
-
VK_KHR_calibrated_timestamps - Extension Type
-
Device extension
- Registered Extension Number
-
544
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Rakos [GitHub]aqnuep
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-07-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Alan Harrison, AMD
-
Derrick Owens, AMD
-
Daniel Rakos, RasterGrid
-
Faith 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_KHR_CALIBRATED_TIMESTAMPS_EXTENSION_NAME -
VK_KHR_CALIBRATED_TIMESTAMPS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_KHR
-
VK_KHR_compute_shader_derivatives
- Name String
-
VK_KHR_compute_shader_derivatives - Extension Type
-
Device extension
- Registered Extension Number
-
512
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Jean-Noe Morissette [GitHub]MagicPoncho
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-06-26
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_compute_shader_derivatives -
This extension provides API support for
GL_KHR_compute_shader_derivatives
-
- Contributors
-
-
Jean-Noe Morissette, Epic Games
-
Daniel Koch, NVIDIA
-
Pat Brown, NVIDIA
-
Stu Smith, AMD
-
Jan-Harald Fredriksen, Arm
-
Tobias Hector, AMD
-
Ralph Potter, Samsung
-
Pan Gao, Huawei
-
Samuel (Sheng-Wen) Huang, MediaTek
-
Graeme Leese, Broadcom
-
Hans-Kristian Arntzen, Valve
-
Matthew Netsch, Qualcomm
-
Description
This extension adds Vulkan support for the
SPV_KHR_compute_shader_derivatives
SPIR-V extension.
The SPIR-V extension provides two new execution modes, both of which allow
execution models with defined workgroups to use built-ins that evaluate
derivatives explicitly or implicitly.
Derivatives will be computed via differencing over a 2x2 group of shader
invocations.
The DerivativeGroupQuadsKHR 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 DerivativeGroupLinearKHR execution mode assembles shader
invocations into 2x2 groups, where each group has local invocation index
values of the form 4m+{0,1,2,3}.
The new execution modes are supported in compute shaders and optionally (see meshAndTaskShaderDerivatives) in mesh and task shaders.
New Enum Constants
-
VK_KHR_COMPUTE_SHADER_DERIVATIVES_EXTENSION_NAME -
VK_KHR_COMPUTE_SHADER_DERIVATIVES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_PROPERTIES_KHR
-
VK_KHR_cooperative_matrix
- Name String
-
VK_KHR_cooperative_matrix - Extension Type
-
Device extension
- Registered Extension Number
-
507
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Kevin Petit [GitHub]kpet
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-05-03
- Interactions and External Dependencies
-
-
This extension provides API support for
GLSL_KHR_cooperative_matrix
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Markus Tavenrath, NVIDIA
-
Daniel Koch, NVIDIA
-
Kevin Petit, Arm Ltd.
-
Boris Zanin, AMD
-
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_KHR_cooperative_matrix
SPIR-V extension and can be used with the
GLSL_KHR_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_KHR_COOPERATIVE_MATRIX_EXTENSION_NAME -
VK_KHR_COOPERATIVE_MATRIX_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_PROPERTIES_KHR
-
VK_KHR_deferred_host_operations
- Name String
-
VK_KHR_deferred_host_operations - Extension Type
-
Device extension
- Registered Extension Number
-
269
- Revision
-
4
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Josh Barczak [GitHub]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_depth_clamp_zero_one
- Name String
-
VK_KHR_depth_clamp_zero_one - Extension Type
-
Device extension
- Registered Extension Number
-
605
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Graeme Leese [GitHub]gnl21
-
Description
This extension is based on the VK_EXT_depth_clamp_zero_one
extension.
This extension gives defined behavior to fragment depth values which end up
outside the conventional [0, 1] range.
It can be used to ensure portability in edge cases of features like
depthBias.
The particular behavior is chosen to match OpenGL to aid porting or
emulation.
New Enum Constants
-
VK_KHR_DEPTH_CLAMP_ZERO_ONE_EXTENSION_NAME -
VK_KHR_DEPTH_CLAMP_ZERO_ONE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLAMP_ZERO_ONE_FEATURES_KHR
-
VK_KHR_display
- Name String
-
VK_KHR_display - Extension Type
-
Instance extension
- Registered Extension Number
-
3
- Revision
-
23
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]cubanismo
-
Norbert Nopper [GitHub]FslNopper
-
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.
RESOLVED: 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?
RESOLVED: 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?
RESOLVED: 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?
RESOLVED: 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).
RESOLVED: 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?
RESOLVED: 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?
RESOLVED: 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?
RESOLVED: Require specifying a plane explicitly.
9) Should displays have an associated window system display, such as an
HDC or Display*?
RESOLVED: 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?
RESOLVED: 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.
RESOLVED: Do not make displays or modes dispatchable. They will dispatch based on their associated physical device.
12) Should hardware cursor capabilities be exposed?
RESOLVED: Defer. This could be a separate extension on top of the base WSI specs.
13) How many display objects should be enumerated for "tiled" display devices? There are ongoing design discussions among lower-level display API authors regarding how to expose displays 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.
-
Reused 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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 swapchains 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jesse Hall [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jesse Hall [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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?
RESOLVED: Yes. 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. Unlike file descriptor opaque handles, win32 opaque handle ownership can not be transferred back to a driver by an import operation.
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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. 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. Unlike file descriptor opaque handles, win32 opaque handle ownership can not be transferred back to a driver by an import operation.
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- 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 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 the shaderSampleRateInterpolationFunctions feature 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_dynamic_rendering
-
Interacts with VK_KHR_format_feature_flags2
-
- SPIR-V Dependencies
- Contact
-
-
Tobias Hector [GitHub]tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-09-30
- Interactions and External Dependencies
-
-
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:
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
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 or Vulkan Version 1.3 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering 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
-
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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 queries for device display properties and
capabilities that can be easily extended by other extensions, without
introducing any further queries.
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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 queries for device surface capabilities that can
be easily extended by other extensions, without introducing any further
queries.
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_incremental_present
- Name String
-
VK_KHR_incremental_present - Extension Type
-
Device extension
- Registered Extension Number
-
85
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Ian Elliott [GitHub]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 structure 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 transformed. 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.
VK_KHR_maintenance7
- Name String
-
VK_KHR_maintenance7 - Extension Type
-
Device extension
- Registered Extension Number
-
563
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Mike Blumenkrantz [GitHub]zmike
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-01-30
- Interactions and External Dependencies
- Contributors
-
-
Mike Blumenkrantz, Valve
-
Hans-Kristian Arntzen, Valve
-
Pan Gao, Huawei
-
Tobias Hector, AMD
-
Jon Leech, Khronos
-
Daniel Story, Nintendo
-
Shahbaz Youssefi, Google
-
Yiwei Zhang, Google
-
Matthew Netsch, Qualcomm
-
Description
VK_KHR_maintenance7 adds a collection of minor features, none of which would warrant an entire extension of their own.
The proposed new features are as follows:
-
Add a property query to determine if a framebuffer writes to depth or stencil aspect does not trigger a write access in the sibling aspect. For example, this allows sampling stencil aspect as a texture while rendering to the sibling depth attachment and vice-versa given appropriate image layouts.
-
Add a way to query information regarding the underlying devices in environments where the Vulkan implementation is provided through layered implementations. For example, running on Mesa/Venus, driver ID is returned as
VK_DRIVER_ID_MESA_VENUS, but it can be necessary to know what the real driver under the hood is. The new VkPhysicalDeviceLayeredApiPropertiesKHR structure can be used to gather information regarding layers underneath the top-level physical device. -
Promote
VK_RENDERING_CONTENTS_INLINE_BIT_EXTandVK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXTto KHR -
Add a limit to report the maximum total count of dynamic uniform buffers and dynamic storage buffers that can be included in a pipeline layout.
-
Require that for an unsigned integer query, the 32-bit result value must be equal to the 32 least significant bits of the equivalent 64-bit result value.
-
Add query for robust access support when using fragment shading rate attachments
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceLayeredApiPropertiesKHR:
-
Extending VkPhysicalDeviceProperties2:
New Enum Constants
-
VK_KHR_MAINTENANCE_7_EXTENSION_NAME -
VK_KHR_MAINTENANCE_7_SPEC_VERSION -
Extending VkRenderingFlagBits:
-
VK_RENDERING_CONTENTS_INLINE_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_API_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_API_PROPERTIES_LIST_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_API_VULKAN_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_7_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_7_PROPERTIES_KHR
-
-
Extending VkSubpassContents:
-
VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR
-
VK_KHR_maintenance8
- Name String
-
VK_KHR_maintenance8 - Extension Type
-
Device extension
- Registered Extension Number
-
575
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Mike Blumenkrantz [GitHub]zmike
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-01-07
- Interactions and External Dependencies
- Contributors
-
-
Jon Leech, Khronos
-
Mike Blumenkrantz, Valve
-
Spencer Fricke, LunarG
-
Jan-Harald Fredriksen, ARM
-
Piers Daniell, NVIDIA
-
Matthew Netsch, Qualcomm
-
Ricardo Garcia, Igalia
-
Lionel Landwerlin, Intel
-
Rick Hammerstone, Qualcomm
-
Daniel Story, Nintendo
-
Hans-Kristian Arntzen, Valve
-
Caterina Shablia, Collabora
-
Georg Lehmann, Valve
-
Shahbaz Youssefi, Google
-
Tobias Hector, AMD
-
Description
VK_KHR_maintenance8 adds a collection of minor features, none of which would warrant an entire extension of their own.
The new features are as follows:
-
Allow copies between depth/stencil and “matching” color attachments
-
Allow
dstCacheinvkMergePipelineCachesto be implicitly synchronized. -
Require src/dst sync scopes to work when doing queue family ownership transfers
-
Support
Offset(as an alternative toConstOffset) image operand in texture sampling and fetch operations -
Use the SPIR-V definition of
OpSRemandOpSMod, making these operations produce well-defined results for negative operands -
Loosen layer restrictions when blitting from 3D images to other image types
-
Add space for an additional 64 access flags for use with VkMemoryBarrier2, VkBufferMemoryBarrier2, and VkImageMemoryBarrier2
New Enum Constants
-
VK_KHR_MAINTENANCE_8_EXTENSION_NAME -
VK_KHR_MAINTENANCE_8_SPEC_VERSION -
Extending VkDependencyFlagBits:
-
VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR
-
-
Extending VkPipelineCacheCreateFlagBits:
-
VK_PIPELINE_CACHE_CREATE_INTERNALLY_SYNCHRONIZED_MERGE_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MEMORY_BARRIER_ACCESS_FLAGS_3_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_8_FEATURES_KHR
-
VK_KHR_maintenance9
- Name String
-
VK_KHR_maintenance9 - Extension Type
-
Device extension
- Registered Extension Number
-
585
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Mike Blumenkrantz [GitHub]zmike
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-05-29
- Interactions and External Dependencies
- Contributors
-
-
Mike Blumenkrantz, Valve
-
Shahbaz Youssefi, Google
-
Hans-Kristian Arntzen, Valve
-
Piers Daniell, NVIDIA
-
Daniel Story, Nintendo
-
Jeff Bolz, NVIDIA
-
Description
VK_KHR_maintenance9 adds a collection of minor features, none of which would warrant an entire extension of their own.
The new features are as follows:
-
Support VkDevice with no queues. These can be used as effectively an offline compiler to prepopulate pipeline caches, without expensive queue creation or internal memory allocations.
-
Allow
vkCmdSetEvent2to not provide a dependency, providingvkCmdSetEvent-style usage using enums fromVK_KHR_synchronization2 -
Add a VkQueryPoolCreateFlagBits::
VK_QUERY_POOL_CREATE_RESET_BIT_KHRflag to create a query pool with all queries initialized to the reset state. -
Allow any integer bit width for specific bit-wise operations.
-
Add a property to enable sparse support with
VK_EXT_image_2d_view_of_3d. -
Add a property to indicate the implementation will return (0,0,0,0) or (0,0,0,1) to vertex shaders that read unassigned attributes.
-
The effects of image memory barriers and image layout transitions on 3D images created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT are scoped to the slices specified by the user-provided VkImageSubresourceRange.
-
Queue family ownership transfers are no longer required for buffers and linear images, and a new physical device queue family property is exposed to indicate whether queue family ownership transfers are required for optimal images.
New Enum Constants
-
VK_KHR_MAINTENANCE_9_EXTENSION_NAME -
VK_KHR_MAINTENANCE_9_SPEC_VERSION -
Extending VkDependencyFlagBits:
-
VK_DEPENDENCY_ASYMMETRIC_EVENT_BIT_KHR
-
-
Extending VkQueryPoolCreateFlagBits:
-
VK_QUERY_POOL_CREATE_RESET_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_9_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_9_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_OWNERSHIP_TRANSFER_PROPERTIES_KHR
-
VK_KHR_performance_query
- Name String
-
VK_KHR_performance_query - Extension Type
-
Device extension
- Registered Extension Number
-
117
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Alon Or-bach [GitHub]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 = {
.sType = VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR,
.pNext = NULL,
// Specify the queue family that this performance query is performed on
.queueFamilyIndex = queueFamilyIndex,
// The number of counters to enable
.counterIndexCount = enabledCounterCount,
// The array of indices of counters to enable
.pCounterIndices = enabledCounters
};
// Get the number of passes our counters will require.
uint32_t numPasses;
vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(
physicalDevice,
&performanceQueryCreateInfo,
&numPasses);
VkQueryPoolCreateInfo queryPoolCreateInfo = {
.sType = VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
.pNext = &performanceQueryCreateInfo,
.flags = 0,
// Using our new query type here
.queryType = VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR,
.queryCount = 1,
.pipelineStatistics = 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 = {
.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
.pNext = NULL,
.flags = 0,
.pInheritanceInfo = NULL
};
VkAcquireProfilingLockInfoKHR lockInfo = {
.sType = VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR,
.pNext = NULL,
.flags = 0,
.timeout = 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) * enabledCounterCount,
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_binary
- Name String
-
VK_KHR_pipeline_binary - Extension Type
-
Device extension
- Registered Extension Number
-
484
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Stu Smith [GitHub]stu-s
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-07-01
- Contributors
-
-
Stu Smith, AMD
-
Tobias Hector, AMD
-
Alan Harrison, AMD
-
Maciej Jesionowski, AMD
-
Younggwan Kim, Arm
-
Jan-Harald Fredriksen, Arm
-
Ting Wei, Arm
-
Chris Glover, Google
-
Shahbaz Youssefi, Google
-
Jakub Kuderski, Google
-
Piotr Byszewski, Mobica
-
Piers Daniell, NVIDIA
-
Ralph Potter, Samsung
-
Matthew Netsch, Qualcomm
-
Hans-Kristian Arntzen, Valve
-
Samuel Pitoiset, Valve
-
Tatsuyuki Ishi, Valve
-
Description
This extension provides a method to obtain binary data associated with individual pipelines such that applications can manage caching themselves instead of using VkPipelineCache objects.
New Structures
-
Extending VkDeviceCreateInfo:
-
Extending VkGraphicsPipelineCreateInfo, VkComputePipelineCreateInfo, VkRayTracingPipelineCreateInfoKHR:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
New Enum Constants
-
VK_KHR_PIPELINE_BINARY_EXTENSION_NAME -
VK_KHR_PIPELINE_BINARY_SPEC_VERSION -
VK_MAX_PIPELINE_BINARY_KEY_SIZE_KHR -
Extending VkObjectType:
-
VK_OBJECT_TYPE_PIPELINE_BINARY_KHR
-
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR
-
-
Extending VkResult:
-
VK_ERROR_NOT_ENOUGH_SPACE_KHR -
VK_PIPELINE_BINARY_MISSING_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_PIPELINE_BINARY_INTERNAL_CACHE_CONTROL_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_BINARY_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_BINARY_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PIPELINE_BINARY_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_PIPELINE_BINARY_DATA_INFO_KHR -
VK_STRUCTURE_TYPE_PIPELINE_BINARY_HANDLES_INFO_KHR -
VK_STRUCTURE_TYPE_PIPELINE_BINARY_INFO_KHR -
VK_STRUCTURE_TYPE_PIPELINE_BINARY_KEY_KHR -
VK_STRUCTURE_TYPE_PIPELINE_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_RELEASE_CAPTURED_PIPELINE_DATA_INFO_KHR
-
VK_KHR_pipeline_executable_properties
- Name String
-
VK_KHR_pipeline_executable_properties - Extension Type
-
Device extension
- Registered Extension Number
-
270
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Faith Ekstrand [GitHub]gfxstrand
-
Other Extension Metadata
- Last Modified Date
-
2019-05-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
- Contributors
-
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Christoph Kubisch [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Charles Giessen [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Keith Packard [GitHub]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_id2
- Name String
-
VK_KHR_present_id2 - Extension Type
-
Device extension
- Registered Extension Number
-
480
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Stone
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-01-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Hans-Kristian Arntzen, Valve
-
James Jones, NVIDIA
-
Daniel Stone, Collabora
-
Derek Foreman, Collabora
-
contributors to `VK_KHR_present_id`
-
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_2_EXTENSION_NAME -
VK_KHR_PRESENT_ID_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_ID_2_FEATURES_KHR -
VK_STRUCTURE_TYPE_PRESENT_ID_2_KHR -
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_PRESENT_ID_2_KHR
-
-
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_PRESENT_ID_2_BIT_KHR
-
VK_KHR_present_mode_fifo_latest_ready
- Name String
-
VK_KHR_present_mode_fifo_latest_ready - Extension Type
-
Device extension
- Registered Extension Number
-
622
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Lionel Duc [GitHub]nvlduc
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-03-18
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Lionel Duc, NVIDIA
-
Lina Versace, Google
-
Description
This extension is based on VK_EXT_present_mode_fifo_latest_ready
and provides equivalent functionality.
This extension adds a new present mode,
VK_PRESENT_MODE_FIFO_LATEST_READY_KHR.
This tear-free present mode behaves much like
VK_PRESENT_MODE_FIFO_KHR, except that each vertical blanking period
dequeues consecutive present requests until the latest ready is found to
update the current image.
While this seems similar in concept to VK_PRESENT_MODE_MAILBOX_KHR,
the fundamental difference is that the processing of the present requests is
done during vblank.
From the application perspective, this means for example, that in a
flip-based model, a single vblank may cause multiple swapchain images to be
released at once, while VK_PRESENT_MODE_MAILBOX_KHR may continuously
be releasing images as new requests become ready.
This additional present mode is useful when using a time-based present API.
New Enum Constants
-
VK_KHR_PRESENT_MODE_FIFO_LATEST_READY_EXTENSION_NAME -
VK_KHR_PRESENT_MODE_FIFO_LATEST_READY_SPEC_VERSION -
Extending VkPresentModeKHR:
-
VK_PRESENT_MODE_FIFO_LATEST_READY_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_MODE_FIFO_LATEST_READY_FEATURES_KHR
-
VK_KHR_present_wait
- Name String
-
VK_KHR_present_wait - Extension Type
-
Device extension
- Registered Extension Number
-
249
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Keith Packard [GitHub]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_present_wait2
- Name String
-
VK_KHR_present_wait2 - Extension Type
-
Device extension
- Registered Extension Number
-
481
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Stone
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-05-30
- IP Status
-
No known IP claims.
- Contributors
-
-
Hans-Kristian Arntzen, Valve
-
James Jones, NVIDIA
-
Daniel Stone, Collabora
-
Derek Foreman, Collabora
-
contributors to `VK_KHR_present_wait`
-
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_2_EXTENSION_NAME -
VK_KHR_PRESENT_WAIT_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_WAIT_2_FEATURES_KHR -
VK_STRUCTURE_TYPE_PRESENT_WAIT_2_INFO_KHR -
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_PRESENT_WAIT_2_KHR
-
-
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_PRESENT_WAIT_2_BIT_KHR
-
Issues
1) When does the wait finish?
RESOLVED. The wait request will complete when the timeout expires, or after the corresponding presentation request has either taken effect within the presentation engine or has been replaced without presentation. Additionally, a wait may complete immediately if the swapchain becomes out of date.
In circumstances outside the application’s control, this wait may be particularly long. For example, a user session may have the display locked and switched off for multiple days. During this time, the latest image presented through the WSI will never be presented to the user (because nothing is being presented), or replaced (because nothing newer has been queued by the application). Each operating system may have a separate mechanism to inform the application of states such as these, however it is out of scope of the Vulkan WSI.
There is no requirement for any precise timing relationship between the presentation of the image to the user and the end of the wait.
This extension is not intended for time-to-light estimation, which is better solved by a separate extension dedicated to present-timing feedback for audio/visual/input synchronization.
2) Should this use fences or other existing synchronization mechanism?
RESOLVED. VkFence is a legacy primitive. Building a new API around a legacy primitive is undesirable.
Other existing synchronization mechanisms may lack a platform-provided framework for sharing synchronization objects between display and render drivers.
For these reasons, 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_id2, should be created to provide a
shared structure for presentation identifiers.
4) What happens when presentations complete out of order with respect to 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 specification.
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.
OPTION D: The order of completion between outstanding
vkWaitForPresent2KHR calls is always undefined.
However, a VK_SUCCESS return value in
VkPresentWait2InfoKHR::presentId implies that future calls to
vkWaitForPresent2KHR where
VkPresentWait2InfoKHR::presentId is less than or equal to N will
complete immediately.
RESOLVED. OPTION D: This option ensures implementations do not need to create complex internal queues to generate signals in the right order.
5) Should this extension deviate from VK_KHR_present_wait and
require the presentation engine to provide the presentId values?
RESOLVED.
No.
This extension is intended to be a bugfix of VK_KHR_present_wait,
and existing low-latency apis require an application provided id.
At least on some platforms, a mapping mechanism would be required to
translate between presentation engine and application ids.
This exceeds the intended scope of this extension.
When needed in the future, we can introduce an independent presentation engine driven id and a mechanism for mapping presentation engine ids to application provided ids.
VK_KHR_ray_query
- Name String
-
VK_KHR_ray_query - Extension Type
-
Device extension
- Registered Extension Number
-
349
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2020-11-12
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_EXT_device_generated_commands
-
Interacts with VK_KHR_ray_tracing_pipeline
-
Interacts with VK_KHR_synchronization2
-
- SPIR-V Dependencies
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2022-02-21
- Interactions and External Dependencies
-
-
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 or Vulkan Version 1.3 and VK_KHR_ray_tracing_pipeline is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR
-
If VK_EXT_device_generated_commands is supported:
-
Extending VkIndirectCommandsTokenTypeEXT:
-
VK_INDIRECT_COMMANDS_TOKEN_TYPE_TRACE_RAYS2_EXT
-
If VK_KHR_synchronization2 or Vulkan Version 1.3 is supported:
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
-
VK_KHR_ray_tracing_pipeline
- Name String
-
VK_KHR_ray_tracing_pipeline - Extension Type
-
Device extension
- Registered Extension Number
-
348
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_KHR_ray_query
-
- SPIR-V Dependencies
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2020-11-12
- Interactions and External Dependencies
-
-
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 VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_BUILT_IN_PRIMITIVES_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 → VkPhysicalDeviceRayTracingPipelinePropertiesKHR (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 the VK_KHR_pipeline_library extension were a
required 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 queryable 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_ray_tracing_position_fetch
- Name String
-
VK_KHR_ray_tracing_position_fetch - Extension Type
-
Device extension
- Registered Extension Number
-
482
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Eric Werness
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-02-17
- Interactions and External Dependencies
-
-
This extension provides API support for
GLSL_EXT_ray_tracing_position_fetch -
Interacts with
VK_KHR_ray_tracing_pipeline -
Interacts with
VK_KHR_ray_query
-
- Contributors
-
-
Eric Werness, NVIDIA
-
Stu Smith, AMD
-
Yuriy O’Donnell, Epic Games
-
Ralph Potter, Samsung
-
Joshua Barczak, Intel
-
Lionel Landwerlin, Intel
-
Andrew Garrard, Imagination Technologies
-
Alex Bourd, Qualcomm
-
Yunpeng Zhu, Huawei Technologies
-
Marius Bjorge, Arm
-
Daniel Koch, NVIDIA
-
Description
VK_KHR_ray_tracing_position_fetch adds the ability to fetch the vertex
positions in the shader from a hit triangle as stored in the acceleration
structure.
An application adds
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_BIT_KHR to the
acceleration structure at build time.
Then, if the hit is a triangle geometry, the shader (any-hit or closest hit
for ray pipelines or using ray query) can fetch the three, three-component
vertex positions in object space, of the triangle which was hit.
New Enum Constants
-
VK_KHR_RAY_TRACING_POSITION_FETCH_EXTENSION_NAME -
VK_KHR_RAY_TRACING_POSITION_FETCH_SPEC_VERSION -
Extending VkBuildAccelerationStructureFlagBitsKHR:
-
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_BIT_KHR -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_POSITION_FETCH_FEATURES_KHR
-
VK_KHR_robustness2
- Name String
-
VK_KHR_robustness2 - Extension Type
-
Device extension
- Registered Extension Number
-
613
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2025-01-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Liam Middlebrook, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension is based on the VK_EXT_robustness2 extension.
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_KHR_ROBUSTNESS_2_EXTENSION_NAME -
VK_KHR_ROBUSTNESS_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_PROPERTIES_KHR
-
Issues
-
Why do VkPhysicalDeviceRobustness2PropertiesKHR::
robustUniformBufferAccessSizeAlignmentand VkPhysicalDeviceRobustness2PropertiesKHR::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_KHR_shader_bfloat16
- Name String
-
VK_KHR_shader_bfloat16 - Extension Type
-
Device extension
- Registered Extension Number
-
142
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_KHR_cooperative_matrix
-
- SPIR-V Dependencies
- Contact
-
-
Tobias Hector [GitHub]tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-04-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Tobias Hector, AMD
-
Stu Smith, AMD
-
Jeff Bolz, Nvidia
-
Kévin Petit, Arm
-
David Neto, Google
-
Graeme Leese, Broadcom
-
Ruihao Zhang, Qualcomm
-
Mark Sheppard, Imagination
-
Ben Ashbaugh, Intel
-
Dmitry Sidorov, Intel
-
Victor Mustya, Intel
-
Description
This extension enables support for bfloat16 (“brain float”) operations in
shaders as defined in SPV_KHR_bfloat16.
New Enum Constants
-
VK_KHR_SHADER_BFLOAT16_EXTENSION_NAME -
VK_KHR_SHADER_BFLOAT16_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_BFLOAT16_FEATURES_KHR
-
If VK_KHR_cooperative_matrix is supported:
-
Extending VkComponentTypeKHR:
-
VK_COMPONENT_TYPE_BFLOAT16_KHR
-
VK_KHR_shader_clock
- Name String
-
VK_KHR_shader_clock - Extension Type
-
Device extension
- Registered Extension Number
-
182
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Aaron Hagan [GitHub]ahagan
-
Other Extension Metadata
- Last Modified Date
-
2019-4-25
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_ARB_shader_clockandGL_EXT_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_maximal_reconvergence
- Name String
-
VK_KHR_shader_maximal_reconvergence - Extension Type
-
Device extension
- Registered Extension Number
-
435
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Alan Baker [GitHub]alan-baker
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-11-12
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires SPIR-V 1.3.
-
This extension requires
SPV_KHR_maximal_reconvergence
-
- Contributors
-
-
Alan Baker, Google
-
Description
This extension allows the use of the SPV_KHR_maximal_reconvergence SPIR-V
extension in shader modules.
SPV_KHR_maximal_reconvergence provides stronger guarantees that diverged
subgroups will reconverge.
These guarantees should match shader author intuition about divergence and
reconvergence of invocations based on the structure of the code in the HLL.
Developers should utilize this extension if they require stronger guarantees about reconvergence than either the core spec or SPV_KHR_subgroup_uniform_control_flow. This extension will define the rules that govern how invocations diverge and reconverge in a way that should match developer intuition. It allows robust programs to be written relying on subgroup operations and other tangled instructions.
New Enum Constants
-
VK_KHR_SHADER_MAXIMAL_RECONVERGENCE_EXTENSION_NAME -
VK_KHR_SHADER_MAXIMAL_RECONVERGENCE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_MAXIMAL_RECONVERGENCE_FEATURES_KHR
-
VK_KHR_shader_quad_control
- Name String
-
VK_KHR_shader_quad_control - Extension Type
-
Device extension
- Registered Extension Number
-
236
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Tobias Hector [GitHub]tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-11-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Tobias Hector, AMD
-
Bill Licea-Kane, Qualcomm
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, Arm
-
Nicolai Hähnle, AMD
-
Jeff Bolz, NVidia
-
Alan Baker, Google
-
Hans-Kristian Arntzen, Valve
-
Description
This extension adds new quad any/all operations, requires that derivatives are well-defined in quad-uniform control flow, and adds the ability to require helper invocations participate in group operations.
New Enum Constants
-
VK_KHR_SHADER_QUAD_CONTROL_EXTENSION_NAME -
VK_KHR_SHADER_QUAD_CONTROL_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_QUAD_CONTROL_FEATURES_KHR
-
VK_KHR_shader_relaxed_extended_instruction
- Name String
-
VK_KHR_shader_relaxed_extended_instruction - Extension Type
-
Device extension
- Registered Extension Number
-
559
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Nathan Gauër [GitHub]Keenuts
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-01-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Alan Baker, Google LLC
-
Nathan Gauër, Google LLC
-
Description
This extension allows the use of the SPV_KHR_relaxed_extended_instruction
extension in SPIR-V shader modules.
It adds a new SPIR-V instruction, which allows some usage of forward
references in non-semantic instruction sets.
This extensions interacts with the SPV_KHR_non_semantic_info extension,
hence with VK_KHR_shader_non_semantic_info.
New Enum Constants
-
VK_KHR_SHADER_RELAXED_EXTENDED_INSTRUCTION_EXTENSION_NAME -
VK_KHR_SHADER_RELAXED_EXTENDED_INSTRUCTION_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_RELAXED_EXTENDED_INSTRUCTION_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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Alan Baker [GitHub]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 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Alon Or-bach [GitHub]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 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
James Jones [GitHub]cubanismo
-
Ian Elliott [GitHub]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
-
Faith 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 structure 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_maintenance1
- Name String
-
VK_KHR_surface_maintenance1 - Extension Type
-
Instance extension
- Registered Extension Number
-
487
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-03-31
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Lionel Landwerlin, Intel
-
Shahbaz Youssefi, Google
-
Chris Forbes, Google
-
Ian Elliott, Google
-
Hans-Kristian Arntzen, Valve
-
Daniel Stone, Collabora
-
Description
This extension is based off the VK_EXT_surface_maintenance1
extension.
VK_KHR_surface_maintenance1 adds a collection of window system
integration features that were intentionally left out or overlooked in the
original VK_KHR_surface extension.
The new features are as follows:
-
Allow querying number of min/max images from a surface for a particular presentation mode.
-
Allow querying a surface’s scaled presentation capabilities.
-
Allow querying a surface for the set of presentation modes which can be easily switched between without requiring swapchain recreation.
New Enum Constants
-
VK_KHR_SURFACE_MAINTENANCE_1_EXTENSION_NAME -
VK_KHR_SURFACE_MAINTENANCE_1_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_COMPATIBILITY_KHR -
VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_KHR -
VK_STRUCTURE_TYPE_SURFACE_PRESENT_SCALING_CAPABILITIES_KHR
-
VK_KHR_surface_protected_capabilities
- Name String
-
VK_KHR_surface_protected_capabilities - Extension Type
-
Instance extension
- Registered Extension Number
-
240
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Sandeep Shinde [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_1
-
- Contact
-
-
James Jones [GitHub]cubanismo
-
Ian Elliott [GitHub]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
-
Faith 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 Vulkan Version 1.1 is supported:
-
Extending VkBindImageMemoryInfo:
-
Extending VkImageCreateInfo:
-
Extending VkPresentInfoKHR:
-
Extending VkSwapchainCreateInfoKHR:
New Enums
If Vulkan Version 1.1 is supported:
New Bitmasks
If Vulkan 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 Vulkan 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 application 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 application 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 application 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 (Faith Ekstrand)
-
Merged the VkRotationFlagBitsKHR and VkMirrorFlagBitsKHR enums into a single VkSurfaceTransformFlagBitsKHR enum.
-
-
Revision 36, 2015-06-26 (Faith 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 (Faith 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_maintenance1
- Name String
-
VK_KHR_swapchain_maintenance1 - Extension Type
-
Device extension
- Registered Extension Number
-
488
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-03-31
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Shahbaz Youssefi, Google
-
Chris Forbes, Google
-
Ian Elliott, Google
-
Yiwei Zhang, Google
-
Charlie Lao, Google
-
Chad Versace, Google
-
Ralph Potter, Samsung
-
Igor Nazarov, Samsung
-
Hyunchang Kim, Samsung
-
Suenghwan Lee, Samsung
-
Munseong Kang, Samsung
-
Joonyong Park, Samsung
-
Hans-Kristian Arntzen, Valve
-
Lisa Wu, Arm
-
Daniel Stone, Collabora
-
Pan Gao, Huawei
-
Description
This extension is based off the VK_EXT_swapchain_maintenance1
extension.
VK_KHR_swapchain_maintenance1 adds a collection of window system
integration features that were intentionally left out or overlooked in the
original VK_KHR_swapchain extension.
The new features are as follows:
-
Specify a fence that will be signaled when the resources associated with a present operation can be safely destroyed.
-
Allow changing the present mode a swapchain is using at per-present granularity.
-
Allow applications to define the behavior when presenting a swapchain image to a surface with different dimensions than the image. Using this feature may allow implementations to avoid returning
VK_ERROR_OUT_OF_DATE_KHRin this situation. -
Allow applications to defer swapchain memory allocation for improved startup time and memory footprint.
-
Allow applications to release previously acquired images without presenting them.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPresentInfoKHR:
-
Extending VkSwapchainCreateInfoKHR:
New Enum Constants
-
VK_KHR_SWAPCHAIN_MAINTENANCE_1_EXTENSION_NAME -
VK_KHR_SWAPCHAIN_MAINTENANCE_1_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SWAPCHAIN_MAINTENANCE_1_FEATURES_KHR -
VK_STRUCTURE_TYPE_RELEASE_SWAPCHAIN_IMAGES_INFO_KHR -
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_FENCE_INFO_KHR -
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODES_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODE_INFO_KHR -
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_SCALING_CREATE_INFO_KHR
-
-
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR
-
VK_KHR_swapchain_mutable_format
- Name String
-
VK_KHR_swapchain_mutable_format - Extension Type
-
Device extension
- Registered Extension Number
-
201
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Rakos [GitHub]drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2018-03-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Faith 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_unified_image_layouts
- Name String
-
VK_KHR_unified_image_layouts - Extension Type
-
Device extension
- Registered Extension Number
-
528
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_EXT_attachment_feedback_loop_layout
-
Interacts with VK_KHR_dynamic_rendering
-
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-10-15
- Interactions and External Dependencies
-
-
This extension interacts with
VK_EXT_attachment_feedback_loop_layout -
This extension interacts with
VK_KHR_video_decode_queue -
This extension interacts with
VK_KHR_video_encode_queue -
This extension interacts with
VK_KHR_video_encode_quantization_map
-
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Tobias Hector, AMD
-
Jan-Harald Fredriksen, ARM
-
Ting Wei, ARM
-
Faith Ekstrand, Collabora
-
Lina Versace, Google
-
Shahbaz Youssefi, Google
-
James Fitzpatrick, Imagination
-
Daniel Story, Nintendo
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Piers Daniell, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Matthew Netsch, Qualcomm
-
Patrick Boyle, Qualcomm
-
Daniel Rakos, RasterGrid
-
Ralph Potter, Samsung
-
Hans-Kristian Arntzen, VALVE
-
Samuel Pitoiset, VALVE
-
Description
This extension significantly simplifies synchronization in Vulkan by
removing the need for image layout transitions in most cases.
In particular, it guarantees that using the VK_IMAGE_LAYOUT_GENERAL layout
everywhere possible is just as efficient as using the other layouts.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
If VK_EXT_attachment_feedback_loop_layout and Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
New Enum Constants
-
VK_KHR_UNIFIED_IMAGE_LAYOUTS_EXTENSION_NAME -
VK_KHR_UNIFIED_IMAGE_LAYOUTS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_UNIFIED_IMAGE_LAYOUTS_FEATURES_KHR
-
If VK_EXT_attachment_feedback_loop_layout and Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ATTACHMENT_FEEDBACK_LOOP_INFO_EXT
-
VK_KHR_video_decode_av1
- Name String
-
VK_KHR_video_decode_av1 - Extension Type
-
Device extension
- Registered Extension Number
-
513
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Rakos [GitHub]aqnuep
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-01-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Benjamin Cheng, AMD
-
Ho Hin Lau, AMD
-
Lynne Iribarren, Independent
-
David Airlie, Red Hat, Inc.
-
Ping Liu, Intel
-
Srinath Kumarapuram, NVIDIA
-
Vassili Nikolaev, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Charlie Turner, Igalia
-
Daniel Almeida, Collabora
-
Nicolas Dufresne, Collabora
-
Daniel Rakos, RasterGrid
-
Description
This extension builds upon the VK_KHR_video_decode_queue extension
by adding support for decoding elementary video stream sequences compliant
with the AV1 video compression standard.
New Structures
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoDecodeInfoKHR:
-
Extending VkVideoProfileInfoKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoReferenceSlotInfoKHR:
-
Extending VkVideoSessionParametersCreateInfoKHR:
New Enum Constants
-
VK_KHR_VIDEO_DECODE_AV1_EXTENSION_NAME -
VK_KHR_VIDEO_DECODE_AV1_SPEC_VERSION -
VK_MAX_VIDEO_AV1_REFERENCES_PER_FRAME_KHR -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_DPB_SLOT_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_PICTURE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_PROFILE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_SESSION_PARAMETERS_CREATE_INFO_KHR
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_DECODE_AV1_BIT_KHR
-
VK_KHR_video_decode_h264
- Name String
-
VK_KHR_video_decode_h264 - Extension Type
-
Device extension
- Registered Extension Number
-
41
- Revision
-
9
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-12-05
- 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
-
Daniel Rakos, RasterGrid
-
Description
This extension builds upon the VK_KHR_video_decode_queue extension
by adding support for decoding elementary video stream sequences compliant
with the H.264/AVC video compression standard.
|
Note
|
This extension was promoted to |
New Structures
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoDecodeInfoKHR:
-
Extending VkVideoProfileInfoKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoReferenceSlotInfoKHR:
-
Extending VkVideoSessionParametersCreateInfoKHR:
-
Extending VkVideoSessionParametersUpdateInfoKHR:
New Enum Constants
-
VK_KHR_VIDEO_DECODE_H264_EXTENSION_NAME -
VK_KHR_VIDEO_DECODE_H264_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_DPB_SLOT_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PICTURE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PROFILE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_ADD_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_SESSION_PARAMETERS_CREATE_INFO_KHR
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR
-
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
-
-
Revision 6, 2022-08-09 (Daniel Rakos)
-
Rename
VkVideoDecodeH264ProfileEXTtoVkVideoDecodeH264ProfileInfoEXT -
Rename
VkVideoDecodeH264MvcEXTtoVkVideoDecodeH264MvcInfoEXT
-
-
Revision 7, 2022-09-18 (Daniel Rakos)
-
Change type of
VkVideoDecodeH264ProfileInfoEXT::pictureLayouttoVkVideoDecodeH264PictureLayoutFlagBitsEXT -
Remove MVC support and related
VkVideoDecodeH264MvcInfoEXTstructure -
Rename
spsStdCount,pSpsStd,ppsStdCount, andpPpsStdtostdSPSCount,pStdSPSs,stdPPSCount, andpStdPPSs, respectively, inVkVideoDecodeH264SessionParametersAddInfoEXT -
Rename
maxSpsStdCountandmaxPpsStdCounttomaxStdSPSCountandmaxStdPPSCount, respectively, inVkVideoDecodeH264SessionParametersCreateInfoEXT -
Rename
slicesCountandpSlicesDataOffsetstosliceCountandpSliceOffsets, respectively, inVkVideoDecodeH264PictureInfoEXT
-
-
Revision 8, 2022-09-29 (Daniel Rakos)
-
Change extension from
EXTtoKHR -
Extension is no longer provisional
-
-
Revision 9, 2023-12-05 (Daniel Rakos)
-
Condition reference picture setup based on the value of
StdVideoDecodeH264PictureInfo::flags.is_reference
-
VK_KHR_video_decode_h265
- Name String
-
VK_KHR_video_decode_h265 - Extension Type
-
Device extension
- Registered Extension Number
-
188
- Revision
-
8
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-12-05
- 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
-
Daniel Rakos, RasterGrid
-
Description
This extension builds upon the VK_KHR_video_decode_queue extension
by adding support for decoding elementary video stream sequences compliant
with the H.265/HEVC video compression standard.
|
Note
|
This extension was promoted to |
New Structures
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoDecodeInfoKHR:
-
Extending VkVideoProfileInfoKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoReferenceSlotInfoKHR:
-
Extending VkVideoSessionParametersCreateInfoKHR:
-
Extending VkVideoSessionParametersUpdateInfoKHR:
New Enum Constants
-
VK_KHR_VIDEO_DECODE_H265_EXTENSION_NAME -
VK_KHR_VIDEO_DECODE_H265_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_DPB_SLOT_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PICTURE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PROFILE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_ADD_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_SESSION_PARAMETERS_CREATE_INFO_KHR
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR
-
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
-
-
Revision 4, 2022-08-09 (Daniel Rakos)
-
Rename
VkVideoDecodeH265ProfileEXTtoVkVideoDecodeH265ProfileInfoEXT
-
-
Revision 5, 2022-09-18 (Daniel Rakos)
-
Rename
vpsStdCount,pVpsStd,spsStdCount,pSpsStd,ppsStdCount, andpPpsStdtostdVPSCount,pStdVPSs,stdSPSCount,pStdSPSs,stdPPSCount, andpStdPPSs, respectively, inVkVideoDecodeH265SessionParametersAddInfoEXT -
Rename
maxVpsStdCount,maxSpsStdCount, andmaxPpsStdCounttomaxStdVPSCount,maxStdSPSCountandmaxStdPPSCount, respectively, inVkVideoDecodeH265SessionParametersCreateInfoEXT -
Rename
slicesCountandpSlicesDataOffsetstosliceCountandpSliceOffsets, respectively, inVkVideoDecodeH265PictureInfoEXT
-
-
Revision 6, 2022-11-14 (Daniel Rakos)
-
Rename
slicetosliceSegmentin the APIs for better clarity
-
-
Revision 7, 2022-11-14 (Daniel Rakos)
-
Change extension from
EXTtoKHR -
Extension is no longer provisional
-
-
Revision 8, 2023-12-05 (Daniel Rakos)
-
Condition reference picture setup based on the value of
StdVideoDecodeH265PictureInfo::flags.IsReference
-
VK_KHR_video_decode_queue
- Name String
-
VK_KHR_video_decode_queue - Extension Type
-
Device extension
- Registered Extension Number
-
25
- Revision
-
8
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_format_feature_flags2
-
- Contact
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-12-05
- 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
-
Daniel Rakos, RasterGrid
-
Description
This extension builds upon the VK_KHR_video_queue extension by
adding common APIs specific to video decoding and thus enabling
implementations to expose queue families supporting video decode operations.
More specifically, it adds video decode specific capabilities and a new command buffer command that allows recording video decode operations against a video session.
This extension is to be used in conjunction with other codec specific video decode extensions that enable decoding video sequences of specific video compression standards.
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 -
VK_STRUCTURE_TYPE_VIDEO_DECODE_USAGE_INFO_KHR
-
If VK_KHR_format_feature_flags2 or Vulkan Version 1.3 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}
-
-
Revision 5, 2022-07-18 (Daniel Rakos)
-
Remove
VkVideoDecodeFlagBitsKHRas it contains no defined flags for now
-
-
Revision 6, 2022-08-12 (Daniel Rakos)
-
Add VkVideoDecodeUsageInfoKHR structure and related flags
-
-
Revision 7, 2022-09-29 (Daniel Rakos)
-
Extension is no longer provisional
-
-
Revision 8, 2023-12-05 (Daniel Rakos)
-
Require the specification of a reconstructed picture in all cases, except when the video session was created with no DPB slots to match shipping implementations
-
Make DPB slot activation behavior codec-specific to continue allowing application control over reference picture setup now that a reconstructed picture is always mandatory
-
VK_KHR_video_decode_vp9
- Name String
-
VK_KHR_video_decode_vp9 - Extension Type
-
Device extension
- Registered Extension Number
-
515
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Ahmed Abdelkhalek [GitHub]aabdelkh
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-04-11
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Benjamin Cheng, AMD
-
Lynne Iribarren, Independent
-
David Airlie, Red Hat, Inc.
-
Ping Liu, Intel
-
Srinath Kumarapuram, NVIDIA
-
Vassili Nikolaev, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Konda Raju, NVIDIA
-
Daniel Almeida, Collabora
-
Nicolas Dufresne, Collabora
-
Daniel Rakos, RasterGrid
-
Description
This extension builds upon the VK_KHR_video_decode_queue extension
by adding support for decoding elementary video stream sequences compliant
with the VP9 video compression standard.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoDecodeInfoKHR:
-
Extending VkVideoProfileInfoKHR, VkQueryPoolCreateInfo:
New Enum Constants
-
VK_KHR_VIDEO_DECODE_VP9_EXTENSION_NAME -
VK_KHR_VIDEO_DECODE_VP9_SPEC_VERSION -
VK_MAX_VIDEO_VP9_REFERENCES_PER_FRAME_KHR -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_DECODE_VP9_FEATURES_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_VP9_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_VP9_PICTURE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_DECODE_VP9_PROFILE_INFO_KHR
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_DECODE_VP9_BIT_KHR
-
VK_KHR_video_encode_av1
- Name String
-
VK_KHR_video_encode_av1 - Extension Type
-
Device extension
- Registered Extension Number
-
514
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Rakos [GitHub]aqnuep
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-09-23
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Benjamin Cheng, AMD
-
Ho Hin Lau, AMD
-
Lynne Iribarren, Independent
-
David Airlie, Red Hat, Inc.
-
Ping Liu, Intel
-
Srinath Kumarapuram, NVIDIA
-
Vassili Nikolaev, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Konda Raju, NVIDIA
-
Charlie Turner, Igalia
-
Daniel Almeida, Collabora
-
Nicolas Dufresne, Collabora
-
Daniel Rakos, RasterGrid
-
Description
This extension builds upon the VK_KHR_video_encode_queue extension
by adding support for encoding elementary video stream sequences compliant
with the AV1 video compression standard.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkVideoBeginCodingInfoKHR:
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoCodingControlInfoKHR, VkVideoBeginCodingInfoKHR:
-
Extending VkVideoEncodeInfoKHR:
-
Extending VkVideoEncodeQualityLevelPropertiesKHR:
-
Extending VkVideoEncodeRateControlLayerInfoKHR:
-
Extending VkVideoProfileInfoKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoReferenceSlotInfoKHR:
-
Extending VkVideoSessionCreateInfoKHR:
-
Extending VkVideoSessionParametersCreateInfoKHR:
New Enum Constants
-
VK_KHR_VIDEO_ENCODE_AV1_EXTENSION_NAME -
VK_KHR_VIDEO_ENCODE_AV1_SPEC_VERSION -
VK_MAX_VIDEO_AV1_REFERENCES_PER_FRAME_KHR -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_AV1_FEATURES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_DPB_SLOT_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_GOP_REMAINING_FRAME_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_PICTURE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_PROFILE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_QUALITY_LEVEL_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_RATE_CONTROL_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_RATE_CONTROL_LAYER_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_SESSION_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_SESSION_PARAMETERS_CREATE_INFO_KHR
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR
-
VK_KHR_video_encode_h264
- Name String
-
VK_KHR_video_encode_h264 - Extension Type
-
Device extension
- Registered Extension Number
-
39
- Revision
-
14
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Ahmed Abdelkhalek [GitHub]aabdelkh
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-12-05
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
George Hao, AMD
-
Jake Beju, AMD
-
Peter Fang, AMD
-
Ping Liu, Intel
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Ravi Chaudhary, NVIDIA
-
Yang Liu, AMD
-
Daniel Rakos, RasterGrid
-
Aidan Fabius, Core Avionics & Industrial Inc.
-
Lynne Iribarren, Independent
-
Description
This extension builds upon the VK_KHR_video_encode_queue extension
by adding support for encoding elementary video stream sequences compliant
with the H.264/AVC video compression standard.
|
Note
|
This extension was promoted to |
New Structures
-
Extending VkVideoBeginCodingInfoKHR:
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoCodingControlInfoKHR, VkVideoBeginCodingInfoKHR:
-
Extending VkVideoEncodeInfoKHR:
-
Extending VkVideoEncodeQualityLevelPropertiesKHR:
-
Extending VkVideoEncodeRateControlLayerInfoKHR:
-
Extending VkVideoEncodeSessionParametersGetInfoKHR:
-
Extending VkVideoProfileInfoKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoReferenceSlotInfoKHR:
-
Extending VkVideoSessionCreateInfoKHR:
-
Extending VkVideoSessionParametersCreateInfoKHR:
-
Extending VkVideoSessionParametersUpdateInfoKHR:
New Enum Constants
-
VK_KHR_VIDEO_ENCODE_H264_EXTENSION_NAME -
VK_KHR_VIDEO_ENCODE_H264_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_DPB_SLOT_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_GOP_REMAINING_FRAME_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_NALU_SLICE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PICTURE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PROFILE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_QUALITY_LEVEL_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_LAYER_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_ADD_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_FEEDBACK_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_GET_INFO_KHR
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR
-
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.
-
-
Revision 8, 2022-07-18 (Daniel Rakos)
-
Replace
VkVideoEncodeH264RateControlStructureFlagBitsEXTbit enum withVkVideoEncodeH264RateControlStructureEXTenum -
Rename
VkVideoEncodeH264ProfileEXTtoVkVideoEncodeH264ProfileInfoEXT -
Rename
VkVideoEncodeH264ReferenceListsEXTtoVkVideoEncodeH264ReferenceListsInfoEXT -
Rename
VkVideoEncodeH264EmitPictureParametersEXTtoVkVideoEncodeH264EmitPictureParametersInfoEXT -
Rename
VkVideoEncodeH264NaluSliceEXTtoVkVideoEncodeH264NaluSliceInfoEXT
-
-
Revision 9, 2022-09-18 (Daniel Rakos)
-
Rename
spsStdCount,pSpsStd,ppsStdCount, andpPpsStdtostdSPSCount,pStdSPSs,stdPPSCount, andpStdPPSs, respectively, inVkVideoEncodeH264SessionParametersAddInfoEXT -
Rename
maxSpsStdCountandmaxPpsStdCounttomaxStdSPSCountandmaxStdPPSCount, respectively, inVkVideoEncodeH264SessionParametersCreateInfoEXT
-
-
Revision 10, 2023-03-06 (Daniel Rakos)
-
Removed
VkVideoEncodeH264EmitPictureParametersInfoEXT -
Changed member types in
VkVideoEncodeH264CapabilitiesEXTandVkVideoEncodeH264ReferenceListsInfoEXTfromuint8_ttouint32_t -
Changed the type of
VkVideoEncodeH264RateControlInfoEXT::temporalLayerCountandVkVideoEncodeH264RateControlLayerInfoEXT::temporalLayerIdfromuint8_ttouint32_t -
Removed
VkVideoEncodeH264InputModeFlagsEXTandVkVideoEncodeH264OutputModeFlagsEXTas we only support frame-in-frame-out mode for now -
Rename
pCurrentPictureInfoinVkVideoEncodeH264VclFrameInfoEXTtopStdPictureInfo -
Rename
pSliceHeaderStdinVkVideoEncodeH264NaluSliceInfoEXTtopStdSliceHeader -
Rename
pReferenceFinalListsinVkVideoEncodeH264VclFrameInfoEXTandVkVideoEncodeH264NaluSliceInfoEXTtopStdReferenceFinalLists -
Removed the
slotIndexmember ofVkVideoEncodeH264DpbSlotInfoEXTand changed it to be chained toVkVideoReferenceSlotInfoKHR -
Replaced
VkVideoEncodeH264ReferenceListsInfoEXTwith the new Video Std header structureStdVideoEncodeH264ReferenceListsthat also includes data previously part of the now removedStdVideoEncodeH264RefMemMgmtCtrlOperationsstructure -
Added new capability flag
VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_REFERENCE_FINAL_LISTS_BIT_EXT
-
-
Revision 11, 2023-05-22 (Daniel Rakos)
-
Renamed
VkVideoEncodeH264VclFrameInfoEXTtoVkVideoEncodeH264PictureInfoEXT -
Added
VkVideoEncodeH264PictureInfoEXT::generatePrefixNaluandVK_VIDEO_ENCODE_H264_CAPABILITY_GENERATE_PREFIX_NALU_BIT_EXTto enable the generation of H.264 prefix NALUs when supported by the implementation -
Removed
VkVideoEncodeH264RateControlLayerInfoEXT::temporalLayerId -
Added
expectDyadicTemporalLayerPatterncapability -
Added the
VkVideoEncodeH264SessionParametersGetInfoEXTstructure to identify the H.264 parameter sets to retrieve encoded parameter data for, and theVkVideoEncodeH264SessionParametersFeedbackInfoEXTstructure to retrieve H.264 parameter set override information when using the newvkGetEncodedVideoSessionParametersKHRcommand -
Added
VkVideoEncodeH264NaluSliceInfoEXT::constantQpto specify per-slice constant QP when rate control mode isVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR -
Added
VkVideoEncodeH264QualityLevelPropertiesEXTfor retrieving H.264 specific quality level recommendations -
Replaced
VkVideoEncodeH264RateControlStructureEXTenum with the flags typeVkVideoEncodeH264RateControlFlagsEXTand bits defined inVkVideoEncodeH264RateControlFlagBitsEXTand added HRD compliance flag -
Removed
useInitialRcQpandinitialRcQpmembers ofVkVideoEncodeH264RateControlLayerInfoEXT -
Added
prefersGopRemainingFramesandrequiresGopRemainingFrames, and the newVkVideoEncodeH264GopRemainingFrameInfoEXTstructure to allow specifying remaining frames of each type in the rate control GOP -
Added
maxTemporalLayers,maxQp, andminQpcapabilities -
Added
maxLevelIdccapability and newVkVideoEncodeH264SessionCreateInfoEXTstructure to specify upper bounds on the H.264 level of the produced video bitstream -
Moved capability flags specific to codec syntax restrictions from
VkVideoEncodeH264CapabilityFlagsEXTto the newVkVideoEncodeH264StdFlagsEXTwhich is now included as a separatestdSyntaxFlagsmember inVkVideoEncodeH264CapabilitiesEXT -
Removed codec syntax override values from
VkVideoEncodeH264CapabilitiesEXT -
Removed
VkVideoEncodeH264NaluSliceInfoEXT::mbCountandVK_VIDEO_ENCODE_H264_CAPABILITY_SLICE_MB_COUNT_BIT_EXT -
Replaced
VK_VIDEO_ENCODE_H264_CAPABILITY_MULTIPLE_SLICES_PER_FRAME_BIT_EXTwith the newmaxSliceCountcapability -
Removed capability flag
VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_REFERENCE_FINAL_LISTS_BIT_EXTand removedpStdReferenceFinalListsmembers from theVkVideoEncodeH264PictureInfoEXTandVkVideoEncodeH264NaluSliceInfoEXTstructures as reference lists info is now included inpStdPictureInfo -
Added capability flag
VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_EXT
-
-
Revision 12, 2023-07-19 (Daniel Rakos)
-
Added video std capability flags
VK_VIDEO_ENCODE_H264_STD_SLICE_QP_DELTA_BIT_EXTandVK_VIDEO_ENCODE_H264_STD_DIFFERENT_SLICE_QP_DELTA_BIT_EXT -
Fixed optionality of the array members of
VkVideoEncodeH264SessionParametersAddInfoEXT -
Fixed optionality of
VkVideoEncodeH264RateControlInfoEXT::flags
-
-
Revision 13, 2023-09-04 (Daniel Rakos)
-
Change extension from
EXTtoKHR -
Extension is no longer provisional
-
-
Revision 14, 2023-12-05 (Daniel Rakos)
-
Condition reference picture setup based on the value of
StdVideoEncodeH264PictureInfo::flags.is_reference
-
VK_KHR_video_encode_h265
- Name String
-
VK_KHR_video_encode_h265 - Extension Type
-
Device extension
- Registered Extension Number
-
40
- Revision
-
14
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Ahmed Abdelkhalek [GitHub]aabdelkh
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-12-05
- 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
-
Ravi Chaudhary, NVIDIA
-
Daniel Rakos, RasterGrid
-
Aidan Fabius, Core Avionics & Industrial Inc.
-
Lynne Iribarren, Independent
-
Description
This extension builds upon the VK_KHR_video_encode_queue extension
by adding support for encoding elementary video stream sequences compliant
with the H.265/HEVC video compression standard.
|
Note
|
This extension was promoted to |
New Structures
-
Extending VkVideoBeginCodingInfoKHR:
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoCodingControlInfoKHR, VkVideoBeginCodingInfoKHR:
-
Extending VkVideoEncodeInfoKHR:
-
Extending VkVideoEncodeQualityLevelPropertiesKHR:
-
Extending VkVideoEncodeRateControlLayerInfoKHR:
-
Extending VkVideoEncodeSessionParametersGetInfoKHR:
-
Extending VkVideoProfileInfoKHR, VkQueryPoolCreateInfo:
-
Extending VkVideoReferenceSlotInfoKHR:
-
Extending VkVideoSessionCreateInfoKHR:
-
Extending VkVideoSessionParametersCreateInfoKHR:
-
Extending VkVideoSessionParametersUpdateInfoKHR:
New Enum Constants
-
VK_KHR_VIDEO_ENCODE_H265_EXTENSION_NAME -
VK_KHR_VIDEO_ENCODE_H265_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_DPB_SLOT_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_GOP_REMAINING_FRAME_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_NALU_SLICE_SEGMENT_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PICTURE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PROFILE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_QUALITY_LEVEL_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_LAYER_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_ADD_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_FEEDBACK_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_GET_INFO_KHR
-
-
Extending VkVideoCodecOperationFlagBitsKHR:
-
VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR
-
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.
-
-
Revision 8, 2022-07-18 (Daniel Rakos)
-
Replace
VkVideoEncodeH265RateControlStructureFlagBitsEXTbit enum withVkVideoEncodeH265RateControlStructureEXTenum -
Rename
VkVideoEncodeH265ProfileEXTtoVkVideoEncodeH265ProfileInfoEXT -
Rename
VkVideoEncodeH265ReferenceListsEXTtoVkVideoEncodeH265ReferenceListsInfoEXT -
Rename
VkVideoEncodeH265EmitPictureParametersEXTtoVkVideoEncodeH265EmitPictureParametersInfoEXT -
Rename
VkVideoEncodeH265NaluSliceSegmentEXTtoVkVideoEncodeH265NaluSliceSegmentInfoEXT
-
-
Revision 9, 2022-09-18 (Daniel Rakos)
-
Rename
vpsStdCount,pVpsStd,spsStdCount,pSpsStd,ppsStdCount, andpPpsStdtostdVPSCount,pStdVPSs,stdSPSCount,pStdSPSs,stdPPSCount, andpStdPPSs, respectively, inVkVideoEncodeH265SessionParametersAddInfoEXT -
Rename
maxVpsStdCount,maxSpsStdCount, andmaxPpsStdCounttomaxStdVPSCount,maxStdSPSCountandmaxStdPPSCount, respectively, inVkVideoEncodeH265SessionParametersCreateInfoEXT
-
-
Revision 10, 2023-03-06 (Daniel Rakos)
-
Removed
VkVideoEncodeH265EmitPictureParametersInfoEXT -
Changed member types in
VkVideoEncodeH265CapabilitiesEXTandVkVideoEncodeH265ReferenceListsInfoEXTfromuint8_ttouint32_t -
Changed the type of
VkVideoEncodeH265RateControlInfoEXT::subLayerCountandVkVideoEncodeH265RateControlLayerInfoEXT::temporalIdfromuint8_ttouint32_t -
Removed
VkVideoEncodeH265InputModeFlagsEXTandVkVideoEncodeH265OutputModeFlagsEXTas we only support frame-in-frame-out mode for now -
Rename
pCurrentPictureInfoinVkVideoEncodeH265VclFrameInfoEXTtopStdPictureInfo -
Rename
pSliceSegmentHeaderStdinVkVideoEncodeH265NaluSliceSegmentInfoEXTtopStdSliceSegmentHeader -
Rename
pReferenceFinalListsinVkVideoEncodeH265VclFrameInfoEXTandVkVideoEncodeH265NaluSliceSegmentInfoEXTtopStdReferenceFinalLists -
Removed the
slotIndexmember ofVkVideoEncodeH265DpbSlotInfoEXTand changed it to be chained toVkVideoReferenceSlotInfoKHR -
Replaced
VkVideoEncodeH265ReferenceListsInfoEXTwith the new Video Std header structureStdVideoEncodeH265ReferenceLists -
Added new capability flag
VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_REFERENCE_FINAL_LISTS_BIT_EXT
-
-
Revision 11, 2023-05-26 (Daniel Rakos)
-
Renamed
VkVideoEncodeH265VclFrameInfoEXTtoVkVideoEncodeH265PictureInfoEXT -
Removed
VkVideoEncodeH265RateControlLayerInfoEXT::temporalId -
Added
expectDyadicTemporalSubLayerPatterncapability -
Added the
VkVideoEncodeH265SessionParametersGetInfoEXTstructure to identify the H.265 parameter sets to retrieve encoded parameter data for, and theVkVideoEncodeH265SessionParametersFeedbackInfoEXTstructure to retrieve H.265 parameter set override information when using the newvkGetEncodedVideoSessionParametersKHRcommand -
Added
VkVideoEncodeH265NaluSliceSegmentInfoEXT::constantQpto specify per-slice segment constant QP when rate control mode isVK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR -
Added
VkVideoEncodeH265QualityLevelPropertiesEXTfor retrieving H.265 specific quality level recommendations -
Replaced
VkVideoEncodeH265RateControlStructureEXTenum with the flags typeVkVideoEncodeH265RateControlFlagsEXTand bits defined inVkVideoEncodeH265RateControlFlagBitsEXTand added HRD compliance flag -
Removed
useInitialRcQpandinitialRcQpmembers ofVkVideoEncodeH265RateControlLayerInfoEXT -
Added
prefersGopRemainingFramesandrequiresGopRemainingFrames, and the newVkVideoEncodeH265GopRemainingFrameInfoEXTstructure to allow specifying remaining frames of each type in the rate control GOP -
Renamed
maxSubLayersCountcapability tomaxSubLayerCount -
Added
maxQp, andminQpcapabilities -
Added
maxLevelIdccapability and newVkVideoEncodeH265SessionCreateInfoEXTstructure to specify upper bounds on the H.265 level of the produced video bitstream -
Moved capability flags specific to codec syntax restrictions from
VkVideoEncodeH265CapabilityFlagsEXTto the newVkVideoEncodeH265StdFlagsEXTwhich is now included as a separatestdSyntaxFlagsmember inVkVideoEncodeH265CapabilitiesEXT -
Added
stdprefix to codec syntax capabilities inVkVideoEncodeH265CapabilitiesEXT -
Removed
VkVideoEncodeH265NaluSliceSegmentInfoEXT::ctbCountandVK_VIDEO_ENCODE_H265_CAPABILITY_SLICE_SEGMENT_CTB_COUNT_BIT_EXT -
Replaced
VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_SEGMENTS_PER_FRAME_BIT_EXTwith the newmaxSliceSegmentCountcapability -
Added
maxTilescapability -
Removed codec syntax min/max capabilities from
VkVideoEncodeH265CapabilitiesEXT -
Removed capability flag
VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_REFERENCE_FINAL_LISTS_BIT_EXTand removedpStdReferenceFinalListsmembers from theVkVideoEncodeH265PictureInfoEXTandVkVideoEncodeH265NaluSliceSegmentInfoEXTstructures as reference lists info is now included inpStdPictureInfo -
Added capability flag
VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_EXT
-
-
Revision 12, 2023-07-19 (Daniel Rakos)
-
Added video std capability flags
VK_VIDEO_ENCODE_H265_STD_SLICE_QP_DELTA_BIT_EXTandVK_VIDEO_ENCODE_H265_STD_DIFFERENT_SLICE_QP_DELTA_BIT_EXT -
Fixed optionality of the array members of
VkVideoEncodeH265SessionParametersAddInfoEXT -
Fixed optionality of
VkVideoEncodeH265RateControlInfoEXT::flags
-
-
Revision 13, 2023-09-04 (Daniel Rakos)
-
Change extension from
EXTtoKHR -
Extension is no longer provisional
-
-
Revision 14, 2023-12-05 (Daniel Rakos)
-
Condition reference picture setup based on the value of
StdVideoEncodeH265PictureInfo::flags.is_reference
-
VK_KHR_video_encode_intra_refresh
- Name String
-
VK_KHR_video_encode_intra_refresh - Extension Type
-
Device extension
- Registered Extension Number
-
553
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_KHR_video_encode_av1
-
Interacts with VK_KHR_video_encode_h264
-
Interacts with VK_KHR_video_encode_h265
-
- Contact
-
-
Ahmed Abdelkhalek [GitHub]aabdelkh
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-03-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Benjamin Cheng, AMD
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Ping Liu, Intel
-
Daniel Rakos, RasterGrid
-
Lynne Iribarren, Independent
-
Description
This extension builds upon the VK_KHR_video_encode_queue extension
by enabling the application to perform intra refresh in video encode
operations.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoEncodeInfoKHR:
-
Extending VkVideoReferenceSlotInfoKHR:
-
Extending VkVideoSessionCreateInfoKHR:
New Enum Constants
-
VK_KHR_VIDEO_ENCODE_INTRA_REFRESH_EXTENSION_NAME -
VK_KHR_VIDEO_ENCODE_INTRA_REFRESH_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_INTRA_REFRESH_FEATURES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_INTRA_REFRESH_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_INTRA_REFRESH_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_INTRA_REFRESH_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_REFERENCE_INTRA_REFRESH_INFO_KHR
-
-
Extending VkVideoEncodeFlagBitsKHR:
-
VK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHR
-
If VK_KHR_video_encode_av1 is supported:
-
Extending VkVideoEncodeAV1CapabilityFlagBitsKHR:
-
VK_VIDEO_ENCODE_AV1_CAPABILITY_COMPOUND_PREDICTION_INTRA_REFRESH_BIT_KHR
-
If VK_KHR_video_encode_h264 is supported:
-
Extending VkVideoEncodeH264CapabilityFlagBitsKHR:
-
VK_VIDEO_ENCODE_H264_CAPABILITY_B_PICTURE_INTRA_REFRESH_BIT_KHR
-
If VK_KHR_video_encode_h265 is supported:
-
Extending VkVideoEncodeH265CapabilityFlagBitsKHR:
-
VK_VIDEO_ENCODE_H265_CAPABILITY_B_PICTURE_INTRA_REFRESH_BIT_KHR
-
VK_KHR_video_encode_quantization_map
- Name String
-
VK_KHR_video_encode_quantization_map - Extension Type
-
Device extension
- Registered Extension Number
-
554
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_KHR_video_encode_av1
-
Interacts with VK_KHR_video_encode_h264
-
Interacts with VK_KHR_video_encode_h265
-
- Contact
-
-
Ahmed Abdelkhalek [GitHub]aabdelkh
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-09-23
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Benjamin Cheng, AMD
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Ping Liu, Intel
-
Daniel Rakos, RasterGrid
-
Lynne Iribarren, Independent
-
Description
This extension builds upon the VK_KHR_video_encode_queue extension
by enabling fine grained control of codec-specific quantization parameters
in video encode operations.
More specifically, it adds support for quantization maps:
-
Quantization delta maps to directly control the relative value of quantization parameter values on a per-block basis for all rate control modes (including when rate control is disabled).
-
Emphasis maps to indirectly control the relative quantization parameter values on a per-block basis when rate control is not disabled and the rate control mode is not configured to the implementation-defined default mode.
This extension is to be used in conjunction with other codec specific video encode extensions that specify the codec specific quantization parameters these maps control.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoEncodeInfoKHR:
-
Extending VkVideoFormatPropertiesKHR:
-
Extending VkVideoSessionParametersCreateInfoKHR:
If VK_KHR_video_encode_av1 is supported:
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoFormatPropertiesKHR:
If VK_KHR_video_encode_h264 is supported:
If VK_KHR_video_encode_h265 is supported:
New Enum Constants
-
VK_KHR_VIDEO_ENCODE_QUANTIZATION_MAP_EXTENSION_NAME -
VK_KHR_VIDEO_ENCODE_QUANTIZATION_MAP_SPEC_VERSION -
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR -
VK_FORMAT_FEATURE_2_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_VIDEO_ENCODE_QUANTIZATION_MAP_KHR
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_QUANTIZATION_MAP_FEATURES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUANTIZATION_MAP_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUANTIZATION_MAP_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUANTIZATION_MAP_SESSION_PARAMETERS_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_FORMAT_QUANTIZATION_MAP_PROPERTIES_KHR
-
-
Extending VkVideoEncodeCapabilityFlagBitsKHR:
-
VK_VIDEO_ENCODE_CAPABILITY_EMPHASIS_MAP_BIT_KHR -
VK_VIDEO_ENCODE_CAPABILITY_QUANTIZATION_DELTA_MAP_BIT_KHR
-
-
Extending VkVideoEncodeFlagBitsKHR:
-
VK_VIDEO_ENCODE_WITH_EMPHASIS_MAP_BIT_KHR -
VK_VIDEO_ENCODE_WITH_QUANTIZATION_DELTA_MAP_BIT_KHR
-
-
Extending VkVideoSessionCreateFlagBitsKHR:
-
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_EMPHASIS_MAP_BIT_KHR -
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR
-
-
Extending VkVideoSessionParametersCreateFlagBitsKHR:
-
VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR
-
If VK_KHR_video_encode_av1 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_ENCODE_AV1_QUANTIZATION_MAP_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_FORMAT_AV1_QUANTIZATION_MAP_PROPERTIES_KHR
-
If VK_KHR_video_encode_h264 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_QUANTIZATION_MAP_CAPABILITIES_KHR
-
-
Extending VkVideoEncodeH264CapabilityFlagBitsKHR:
-
VK_VIDEO_ENCODE_H264_CAPABILITY_MB_QP_DIFF_WRAPAROUND_BIT_KHR
-
If VK_KHR_video_encode_h265 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_QUANTIZATION_MAP_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_FORMAT_H265_QUANTIZATION_MAP_PROPERTIES_KHR
-
-
Extending VkVideoEncodeH265CapabilityFlagBitsKHR:
-
VK_VIDEO_ENCODE_H265_CAPABILITY_CU_QP_DIFF_WRAPAROUND_BIT_KHR
-
VK_KHR_video_encode_queue
- Name String
-
VK_KHR_video_encode_queue - Extension Type
-
Device extension
- Registered Extension Number
-
300
- Revision
-
12
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_format_feature_flags2
-
- Contact
-
-
Ahmed Abdelkhalek [GitHub]aabdelkh
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-12-05
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Damien Kessler, NVIDIA
-
George Hao, AMD
-
Jake Beju, AMD
-
Peter Fang, AMD
-
Piers Daniell, NVIDIA
-
Srinath Kumarapuram, NVIDIA
-
Thomas J. Meier, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Ravi Chaudhary, NVIDIA
-
Yang Liu, AMD
-
Daniel Rakos, RasterGrid
-
Ping Liu, Intel
-
Aidan Fabius, Core Avionics & Industrial Inc.
-
Lynne Iribarren, Independent
-
Description
This extension builds upon the VK_KHR_video_queue extension by
adding common APIs specific to video encoding and thus enabling
implementations to expose queue families supporting video encode operations.
More specifically, it adds video encode specific capabilities and a new command buffer command that allows recording video encode operations against a video session.
This extension is to be used in conjunction with other codec specific video encode extensions that enable encoding video sequences of specific video compression standards.
New Structures
-
Extending VkQueryPoolCreateInfo:
-
Extending VkVideoCapabilitiesKHR:
-
Extending VkVideoCodingControlInfoKHR, VkVideoBeginCodingInfoKHR:
-
Extending VkVideoCodingControlInfoKHR, VkVideoSessionParametersCreateInfoKHR:
-
Extending VkVideoProfileInfoKHR, VkQueryPoolCreateInfo:
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 VkQueryResultStatusKHR:
-
VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR
-
-
Extending VkQueueFlagBits:
-
VK_QUEUE_VIDEO_ENCODE_BIT_KHR
-
-
Extending VkResult:
-
VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR -
VK_STRUCTURE_TYPE_QUERY_POOL_VIDEO_ENCODE_FEEDBACK_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_CAPABILITIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_LAYER_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_FEEDBACK_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_GET_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_ENCODE_USAGE_INFO_KHR
-
-
Extending VkVideoCodingControlFlagBitsKHR:
-
VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR -
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR
-
-
Extending VkVideoSessionCreateFlagBitsKHR:
-
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR
-
If VK_KHR_format_feature_flags2 or Vulkan Version 1.3 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
-
-
Revision 6, 2022-07-18 (Daniel Rakos)
-
Remove
VkVideoEncodeRateControlFlagBitsKHRandVkVideoEncodeFlagBitsKHRas they contain no defined flags for now -
Add
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHRandVK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_LAYER_BIT_KHRto indicate rate control and rate control layer change requests, respectively, in video coding control operations
-
-
Revision 7, 2022-08-12 (Daniel Rakos)
-
Add VkVideoEncodeUsageInfoKHR structure and related flags
-
-
Revision 8, 2023-03-06 (Daniel Rakos)
-
Replace
VK_QUERY_TYPE_VIDEO_ENCODE_BITSTREAM_BUFFER_RANGE_KHRqueries with more genericVK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHRqueries that can be extended in the future with more feedback values -
Rename
dstBitstreamBuffer,dstBitstreamBufferOffset, anddstBitstreamBufferMaxRangeinVkVideoEncodeInfoKHRtodstBuffer,dstBufferOffset, anddstBufferRange, respectively, for consistency with the naming convention in the video decode extensions -
Change the type of
rateControlLayerCountandqualityLevelCountinVkVideoEncodeCapabilitiesKHRfromuint8_ttouint32_tand rename them tomaxRateControlLayersandmaxQualityLevels, respectively -
Change the type of
averageBitrateandmaxBitrateinVkVideoEncodeRateControlLayerInfoKHR`fromuint32_ttouint64_t -
Fixed the definition of rate control flag bits and added the new
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHRconstant to indicate implementation-specific automatic rate control -
Change the type of
VkVideoEncodeRateControlInfoKHR::layerCountfromuint8_ttouint32_t -
Rename
pLayerConfigstopLayersinVkVideoEncodeRateControlInfoKHR
-
-
Revision 9, 2023-03-28 (Daniel Rakos)
-
Removed
VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_LAYER_BIT_KHRand the ability to change the state of individual rate control layers -
Added new
VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHRflag to video encode feedback queries -
Added new video session create flag
VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHRto opt-in to video session and encoding parameter optimizations -
Added the
vkGetEncodedVideoSessionParametersKHRcommand to enable retrieving encoded video session parameter data -
Moved
virtualBufferSizeInMsandinitialVirtualBufferSizeInMsfromVkVideoEncodeRateControlLayerInfoKHRtoVkVideoEncodeRateControlInfoKHR -
Added
maxBitratecapability -
Renamed
inputImageDataFillAlignmentcapability toencodeInputPictureGranularityto better reflect its purpose -
Added new
vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHRcommand and related structures to enable querying recommended settings for video encode quality levels -
Added
VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHRflag andVkVideoEncodeQualityLevelInfoKHRstructure to allow controlling video encode quality level and removedqualityLevelfrom the encode operation parameters
-
-
Revision 10, 2023-07-19 (Daniel Rakos)
-
Added
VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHRquery result status code and the related capability flagVK_VIDEO_ENCODE_CAPABILITY_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_DETECTION_BIT_KHR
-
-
Revision 11, 2023-09-04 (Daniel Rakos)
-
Extension is no longer provisional
-
-
Revision 12, 2023-12-05 (Daniel Rakos)
-
Require the specification of a reconstructed picture in all cases, except when the video session was created with no DPB slots to match shipping implementations
-
Make DPB slot activation behavior codec-specific to continue allowing application control over reference picture setup now that a reconstructed picture is always mandatory
-
VK_KHR_video_maintenance1
- Name String
-
VK_KHR_video_maintenance1 - Extension Type
-
Device extension
- Registered Extension Number
-
516
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Rakos [GitHub]aqnuep
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-07-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Aidan Fabius, Core Avionics & Industrial Inc.
-
Ping Liu, Intel
-
Lynne Iribarren, Independent
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Daniel Rakos, RasterGrid
-
Description
VK_KHR_video_maintenance1 adds a collection of minor video coding
features, none of which would warrant an entire extension of their own.
The new features are as follows:
-
Allow creating buffers that can be used in video coding operations, independent of the used video profile, using the new buffer creation flag
VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. -
Allow creating images that can be used as decode output or encode input pictures, independent of the used video profile, using the new image creation flag
VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. -
Allow specifying queries used by video coding operations as part of the video coding command parameters, instead of using begin/end query when the video session is created using the new video session creation flag
VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR.
New Enum Constants
-
VK_KHR_VIDEO_MAINTENANCE_1_EXTENSION_NAME -
VK_KHR_VIDEO_MAINTENANCE_1_SPEC_VERSION -
Extending VkBufferCreateFlagBits:
-
VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_MAINTENANCE_1_FEATURES_KHR -
VK_STRUCTURE_TYPE_VIDEO_INLINE_QUERY_INFO_KHR
-
-
Extending VkVideoSessionCreateFlagBitsKHR:
-
VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR
-
VK_KHR_video_maintenance2
- Name String
-
VK_KHR_video_maintenance2 - Extension Type
-
Device extension
- Registered Extension Number
-
587
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_KHR_video_decode_av1
-
Interacts with VK_KHR_video_decode_h264
-
Interacts with VK_KHR_video_decode_h265
-
Interacts with VK_KHR_video_decode_queue
-
- Contact
-
-
Daniel Rakos [GitHub]aqnuep
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-10-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Ahmed Abdelkhalek, AMD
-
Benjamin Cheng, AMD
-
Aidan Fabius, Core Avionics & Industrial Inc.
-
Ping Liu, Intel
-
Lynne Iribarren, Independent
-
Srinath Kumarapuram, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Daniel Rakos, RasterGrid
-
Description
VK_KHR_video_maintenance2 adds a collection of minor video coding
features, none of which would warrant an entire extension of their own.
The new features are as follows:
-
Allow video coding control commands (such as video session reset) to be issued without the need for a bound video session parameters object for video decode operations that would otherwise require the use of video session parameters objects.
-
Allow applications to specify codec-specific parameter sets inline for each decode operation instead of having to construct video session parameters objects.
-
Require support for
VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHRin all applicable video encode profiles. -
Provide additional guarantees on Video Std parameters that the encoder implementation will not override.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
If VK_KHR_video_decode_av1 is supported:
If VK_KHR_video_decode_h264 is supported:
If VK_KHR_video_decode_h265 is supported:
New Enum Constants
-
VK_KHR_VIDEO_MAINTENANCE_2_EXTENSION_NAME -
VK_KHR_VIDEO_MAINTENANCE_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_MAINTENANCE_2_FEATURES_KHR
-
If VK_KHR_video_decode_av1 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_DECODE_AV1_INLINE_SESSION_PARAMETERS_INFO_KHR
-
If VK_KHR_video_decode_h264 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_INLINE_SESSION_PARAMETERS_INFO_KHR
-
If VK_KHR_video_decode_h265 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_INLINE_SESSION_PARAMETERS_INFO_KHR
-
If VK_KHR_video_decode_queue is supported:
-
Extending VkVideoSessionCreateFlagBitsKHR:
-
VK_VIDEO_SESSION_CREATE_INLINE_SESSION_PARAMETERS_BIT_KHR
-
VK_KHR_video_queue
- Name String
-
VK_KHR_video_queue - Extension Type
-
Device extension
- Registered Extension Number
-
24
- Revision
-
8
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Tony Zlatinski [GitHub]tzlatinski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-09-29
- 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
-
Description
This extension provides common APIs to enable exposing queue families with support for video codec operations by introducing the following new object types and related functionalities:
-
Video session objects that represent and maintain the state needed to perform video codec operations.
-
Video session parameters objects that act as a container for codec specific parameters.
In addition, it also introduces query commands that allow applications to determine video coding related capabilities, and command buffer commands that enable recording video coding operations against a video session.
This extension is to be used in conjunction with other extensions that enable specific video coding operations.
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_BIND_VIDEO_SESSION_MEMORY_INFO_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_FORMAT_INFO_KHR -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_QUERY_RESULT_STATUS_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_VIDEO_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_VIDEO_BEGIN_CODING_INFO_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_PICTURE_RESOURCE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_PROFILE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_PROFILE_LIST_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_SESSION_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_VIDEO_SESSION_MEMORY_REQUIREMENTS_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
-
-
Revision 5, 2022-08-11 (Daniel Rakos)
-
Add
VkVideoSessionParametersCreateFlagsKHR -
Remove
VkVideoCodingQualityPresetFlagsKHR -
Rename
VkQueueFamilyQueryResultStatusProperties2KHRtoVkQueueFamilyQueryResultStatusPropertiesKHR -
Rename
VkVideoQueueFamilyProperties2KHRtoVkQueueFamilyVideoPropertiesKHR -
Rename
VkVideoProfileKHRtoVkVideoProfileInfoKHR -
Rename
VkVideoProfilesKHRtoVkVideoProfileListInfoKHR -
Rename
VkVideoGetMemoryPropertiesKHRtoVkVideoSessionMemoryRequirementsKHR -
Rename
VkVideoBindMemoryKHRtoVkBindVideoSessionMemoryInfoKHR -
Fix
pNextconstness ofVkPhysicalDeviceVideoFormatInfoKHRandVkVideoSessionMemoryRequirementsKHR -
Fix incorrectly named value enums in bit enum types
VkVideoCodecOperationFlagBitsKHRandVkVideoChromaSubsamplingFlagBitsKHR -
Remove unnecessary default values from
VkVideoSessionCreateFlagBitsKHRandVkVideoCodingControlFlagBitsKHR -
Eliminate nested pointer in
VkVideoSessionMemoryRequirementsKHR -
Rename
VkVideoPictureResourceKHRtoVkVideoPictureResourceInfoKHR -
Rename
VkVideoReferenceSlotKHRtoVkVideoReferenceSlotInfoKHR
-
-
Revision 6, 2022-09-18 (Daniel Rakos)
-
Rename the
maxReferencePicturesSlotsCountandmaxReferencePicturesActiveCountfields ofVkVideoCapabilitiesKHRandVkVideoSessionCreateInfoKHRtomaxDpbSlotsandmaxActiveReferencePictures, respectively, to clarify their meaning -
Rename
capabilityFlagstoflagsinVkVideoCapabilitiesKHR -
Rename
videoPictureExtentGranularitytopictureAccessGranularityinVkVideoCapabilitiesKHR -
Rename
minExtentandmaxExtenttominCodedExtentandmaxCodedExtent, respectively, inVkVideoCapabilitiesKHR -
Rename
referencePicturesFormattoreferencePictureFormatinVkVideoSessionCreateInfoKHR
-
-
Revision 7, 2022-09-26 (Daniel Rakos)
-
Change type of
VkVideoReferenceSlotInfoKHR::slotIndexfromint8_ttoint32_t
-
-
Revision 8, 2022-09-29 (Daniel Rakos)
-
Extension is no longer provisional
-
VK_KHR_wayland_surface
- Name String
-
VK_KHR_wayland_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
7
- Revision
-
6
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jesse Hall [GitHub]critsec
-
Ian Elliott [GitHub]ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Faith 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 (Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Carsten Rohde [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jesse Hall [GitHub]critsec
-
Ian Elliott [GitHub]ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2017-04-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Caio Marcelo de Oliveira Filho [GitHub]cmarcelo
-
Other Extension Metadata
- Last Modified Date
-
2020-06-01
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_EXT_shared_memory_block
-
- Contributors
-
-
Caio Marcelo de Oliveira Filho, Intel
-
Jeff Bolz, NVIDIA
-
Graeme Leese, Broadcom
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jesse Hall [GitHub]critsec
-
Ian Elliott [GitHub]ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jesse Hall [GitHub]critsec
-
Ian Elliott [GitHub]ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- 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.
VK_EXT_acquire_xlib_display
- Name String
-
VK_EXT_acquire_xlib_display - Extension Type
-
Instance extension
- Registered Extension Number
-
90
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jan-Harald Fredriksen [GitHub]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 =
{
.sType = VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT,
.pNext = NULL,
.decodeMode = VK_FORMAT_R8G8B8A8_UNORM
};
VkImageViewCreateInfo createInfo =
{
.sType = VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO,
.pNext = &decodeMode,
// flags, image, viewType set to application-desired values
.format = VK_FORMAT_ASTC_8x8_UNORM_BLOCK,
// components, subresourceRange set to application-desired values
};
VkImageView imageView;
VkResult result = vkCreateImageView(
device,
&createInfo,
NULL,
&imageView);
VK_EXT_attachment_feedback_loop_dynamic_state
- Name String
-
VK_EXT_attachment_feedback_loop_dynamic_state - Extension Type
-
Device extension
- Registered Extension Number
-
525
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Uses
- Contact
-
-
Mike Blumenkrantz [GitHub]zmike
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-04-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Mike Blumenkrantz, Valve
-
Daniel Story, Nintendo
-
Stu Smith, AMD
-
Samuel Pitoiset, Valve
-
Ricardo Garcia, Igalia
-
Description
This extension adds support for setting attachment feedback loops dynamically on command buffers.
New Enum Constants
-
VK_EXT_ATTACHMENT_FEEDBACK_LOOP_DYNAMIC_STATE_EXTENSION_NAME -
VK_EXT_ATTACHMENT_FEEDBACK_LOOP_DYNAMIC_STATE_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ATTACHMENT_FEEDBACK_LOOP_DYNAMIC_STATE_FEATURES_EXT
-
VK_EXT_attachment_feedback_loop_layout
- Name String
-
VK_EXT_attachment_feedback_loop_layout - Extension Type
-
Device extension
- Registered Extension Number
-
340
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Uses
- Contact
-
-
Joshua Ashton [GitHub]Joshua-Ashton
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-04-04
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Ashton, Valve
-
Faith Ekstrand, Collabora
-
Bas Nieuwenhuizen, Google
-
Samuel Iglesias Gonsálvez, Igalia
-
Ralph Potter, Samsung
-
Jan-Harald Fredriksen, Arm
-
Ricardo Garcia, Igalia
-
Description
This extension adds a new image layout,
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT, which allows
applications to have an image layout in which they are able to both render
to and sample/fetch from the same subresource of an image in a given render
pass.
New Enum Constants
-
VK_EXT_ATTACHMENT_FEEDBACK_LOOP_LAYOUT_EXTENSION_NAME -
VK_EXT_ATTACHMENT_FEEDBACK_LOOP_LAYOUT_SPEC_VERSION -
Extending VkDependencyFlagBits:
-
VK_DEPENDENCY_FEEDBACK_LOOP_BIT_EXT
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT -
VK_PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ATTACHMENT_FEEDBACK_LOOP_LAYOUT_FEATURES_EXT
-
VK_EXT_blend_operation_advanced
- Name String
-
VK_EXT_blend_operation_advanced - Extension Type
-
Device extension
- Registered Extension Number
-
149
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jeff Bolz [GitHub]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
-
VK_EXT_border_color_swizzle
- Name String
-
VK_EXT_border_color_swizzle - Extension Type
-
Device extension
- Registered Extension Number
-
412
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Uses
- Contact
-
-
Piers Daniell [GitHub]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_color_write_enable
- Name String
-
VK_EXT_color_write_enable - Extension Type
-
Device extension
- Registered Extension Number
-
382
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Sharif Elcott [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Vikram Kushwaha [GitHub]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.
VK_EXT_conservative_rasterization
- Name String
-
VK_EXT_conservative_rasterization - Extension Type
-
Device extension
- Registered Extension Number
-
102
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Piers Daniell [GitHub]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
-
VK_EXT_custom_border_color
- Name String
-
VK_EXT_custom_border_color - Extension Type
-
Device extension
- Registered Extension Number
-
288
- Revision
-
12
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Uses
- Contact
-
-
Liam Middlebrook [GitHub]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
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Special Use
- Contact
-
-
Mark Young [GitHub]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 chain of the VkInstanceCreateInfo structure passed
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 = {
.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT,
.pNext = NULL,
.flags = 0,
.messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT |
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,
.messageType= VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
.pfnUserCallback = myOutputDebugString,
.pUserData = NULL
};
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 = {
.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT,
.pNext = NULL,
.flags = 0,
.messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,
.messageType = VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
.pfnUserCallback = mystdOutLogger,
.pUserData = NULL
};
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 =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT,
.pNext = NULL,
.objectType = VK_OBJECT_TYPE_IMAGE,
.objectHandle = (uint64_t)image,
.pObjectName = "Brick Diffuse Texture",
};
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 =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT,
.pNext = NULL,
.pLabelName = "Brick House",
.color = { 1.0f, 0.0f, 0.0f, 1.0f },
};
// Start an annotated group of calls under the 'Brick House' name
pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &houseLabel);
{
// A mutable structure for each part being rendered
VkDebugUtilsLabelEXT housePartLabel =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT,
.pNext = NULL,
.pLabelName = NULL,
.color = { 0.0f, 0.0f, 0.0f, 0.0f },
};
// 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 =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT,
.pNext = NULL,
.pLabelName = "Main Render Work",
.color = { 0.0f, 1.0f, 0.0f, 1.0f },
};
// 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_bias_control
- Name String
-
VK_EXT_depth_bias_control - Extension Type
-
Device extension
- Registered Extension Number
-
284
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Joshua Ashton [GitHub]Joshua-Ashton
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-02-15
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Ashton, VALVE
-
Hans-Kristian Arntzen, VALVE
-
Mike Blumenkrantz, VALVE
-
Georg Lehmann, VALVE
-
Piers Daniell, NVIDIA
-
Lionel Landwerlin, INTEL
-
Tobias Hector, AMD
-
Ricardo Garcia, IGALIA
-
Jan-Harald Fredriksen, ARM
-
Shahbaz Youssefi, GOOGLE
-
Tom Olson, ARM
-
Description
This extension adds a new structure, VkDepthBiasRepresentationInfoEXT,
that can be added to a pNext chain of
VkPipelineRasterizationStateCreateInfo and allows setting the scaling
and representation of depth bias for a pipeline.
This state can also be set dynamically by using the new structure mentioned
above in combination with the new vkCmdSetDepthBias2EXT command.
New Enum Constants
-
VK_EXT_DEPTH_BIAS_CONTROL_EXTENSION_NAME -
VK_EXT_DEPTH_BIAS_CONTROL_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEPTH_BIAS_INFO_EXT -
VK_STRUCTURE_TYPE_DEPTH_BIAS_REPRESENTATION_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_BIAS_CONTROL_FEATURES_EXT
-
VK_EXT_depth_clamp_control
- Name String
-
VK_EXT_depth_clamp_control - Extension Type
-
Device extension
- Registered Extension Number
-
583
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jules Blok [GitHub]jules
-
- Extension Proposal
Description
This extension allows the application to control the viewport depth clamp
range separately from the viewport minDepth and maxDepth.
This gives the ability for the application to restrict depth values to an
application-defined range rather than
the viewport depth range or the range defined in the
VK_EXT_depth_clamp_zero_one extension.
It can be used to set a smaller or larger clamping range than the viewport depth range without affecting the depth mapping of the viewport transform. Another possible use of this extension is to restrict depth values beyond the viewport depth range to a clamping range other than the [0, 1] range defined in the VK_EXT_depth_clamp_zero_one extension.
New Enum Constants
-
VK_EXT_DEPTH_CLAMP_CONTROL_EXTENSION_NAME -
VK_EXT_DEPTH_CLAMP_CONTROL_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_DEPTH_CLAMP_RANGE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLAMP_CONTROL_FEATURES_EXT -
VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_DEPTH_CLAMP_CONTROL_CREATE_INFO_EXT
-
Issues
1) Should the depth clamp range be a per-viewport parameter?
RESOLVED: No. Because the depth clamp range was previously defined to be equal to the viewport depth range, conformant runtimes are already handling the depth clamp range as a per-viewport parameter. However because of complexities from interactions with multiple viewports a per-viewport clamp range is left to a future extensions if a use case arises.
2) Should this pipeline state be dynamic?
RESOLVED: Yes. Since the viewport depth range can already be a dynamic state conformant runtimes are already able to handle the depth clamp range as a dynamic state.
3) Can the depth clamp range be ignored when depth clamping is disabled?
RESOLVED: Yes. This extension overrides the clamping range used only when depth clamping is enabled. The alternative would be highly unintuitive. As a consequence the VK_EXT_depth_clip_enable extension is required if depth clipping is desired in combination with this extension.
VK_EXT_depth_clip_control
- Name String
-
VK_EXT_depth_clip_control - Extension Type
-
Device extension
- Registered Extension Number
-
356
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Shahbaz Youssefi [GitHub]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 structure to chain to
VkPipelineViewportStateCreateInfo::pNext instead.
VK_EXT_depth_clip_enable
- Name String
-
VK_EXT_depth_clip_enable - Extension Type
-
Device extension
- Registered Extension Number
-
103
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Piers Daniell [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Piers Daniell [GitHub]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: This situation can also arise without this extension (when fragment shaders replace depth values, for example), and this extension does not change the behavior, which is defined in the Depth Test section of the Fragment Operations chapter.
VK_EXT_descriptor_buffer
- Name String
-
VK_EXT_descriptor_buffer - Extension Type
-
Device extension
- Registered Extension Number
-
317
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_KHR_acceleration_structure
-
Interacts with VK_NV_ray_tracing
-
- Contact
-
-
Tobias Hector [GitHub]tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-06-07
- IP Status
-
No known IP claims.
- Contributors
-
-
Tobias Hector, AMD
-
Stu Smith, AMD
-
Maciej Jesionowski, AMD
-
Boris Zanin, AMD
-
Hans-Kristian Arntzen, Valve
-
Connor Abbott, Valve
-
Baldur Karlsson, Valve
-
Mike Blumenkrantz, Valve
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, Arm
-
Rodrigo Locatti, NVIDIA
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
Jeff Leger, QUALCOMM
-
Lionel Landwerlin, Intel
-
Slawomir Grajewski, Intel
-
Description
This extension introduces new commands to put shader-accessible descriptors directly in memory, making the management of descriptor data more explicit.
New Structures
-
Extending VkBufferCreateInfo, VkImageCreateInfo, VkImageViewCreateInfo, VkSamplerCreateInfo, VkAccelerationStructureCreateInfoKHR, VkAccelerationStructureCreateInfoNV, VkTensorCreateInfoARM, VkTensorViewCreateInfoARM:
-
Extending VkDescriptorBufferBindingInfoEXT:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
If VK_KHR_acceleration_structure or VK_NV_ray_tracing is supported:
New Enum Constants
-
VK_EXT_DESCRIPTOR_BUFFER_EXTENSION_NAME -
VK_EXT_DESCRIPTOR_BUFFER_SPEC_VERSION -
Extending VkAccelerationStructureCreateFlagBitsKHR:
-
VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT
-
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT
-
-
Extending VkBufferCreateFlagBits:
-
VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT -
VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT -
VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT
-
-
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT -
VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT
-
-
Extending VkImageViewCreateFlagBits:
-
VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT
-
-
Extending VkSamplerCreateFlagBits:
-
VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BUFFER_CAPTURE_DESCRIPTOR_DATA_INFO_EXT -
VK_STRUCTURE_TYPE_DESCRIPTOR_ADDRESS_INFO_EXT -
VK_STRUCTURE_TYPE_DESCRIPTOR_BUFFER_BINDING_INFO_EXT -
VK_STRUCTURE_TYPE_DESCRIPTOR_BUFFER_BINDING_PUSH_DESCRIPTOR_BUFFER_HANDLE_EXT -
VK_STRUCTURE_TYPE_DESCRIPTOR_GET_INFO_EXT -
VK_STRUCTURE_TYPE_IMAGE_CAPTURE_DESCRIPTOR_DATA_INFO_EXT -
VK_STRUCTURE_TYPE_IMAGE_VIEW_CAPTURE_DESCRIPTOR_DATA_INFO_EXT -
VK_STRUCTURE_TYPE_OPAQUE_CAPTURE_DESCRIPTOR_DATA_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_DENSITY_MAP_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_SAMPLER_CAPTURE_DESCRIPTOR_DATA_INFO_EXT
-
If VK_KHR_acceleration_structure or VK_NV_ray_tracing is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CAPTURE_DESCRIPTOR_DATA_INFO_EXT
-
VK_EXT_device_address_binding_report
- Name String
-
VK_EXT_device_address_binding_report - Extension Type
-
Device extension
- Registered Extension Number
-
355
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Uses
- Contact
-
-
Ralph Potter [GitLab]r_potter
-
Other Extension Metadata
- Last Modified Date
-
2020-11-23
- Interactions and External Dependencies
-
-
This extension requires
VK_EXT_debug_utils
-
- Contributors
-
-
Ralph Potter, Samsung
-
Spencer Fricke, Samsung
-
Jan-Harald Fredriksen, ARM
-
Andrew Ellem, Google
-
Alex Walters, IMG
-
Jeff Bolz, NVIDIA
-
Description
This extension enables applications to track the binding of regions of the GPU virtual address space, and to associate those regions with Vulkan objects. This extension is primarily intended to aid in crash postmortem, where applications may wish to map a faulting GPU address to a Vulkan object.
For example, a page fault triggered by accessing an address located within a region of the GPU virtual address space that was previously reported as bound and then unbound may indicate a use-after-free error. Similarly, faults generated by accessing virtual addresses outside the limits of a bound region of GPU virtual address space may indicate indexing beyond the bounds of a resource.
New Enum Constants
-
VK_EXT_DEVICE_ADDRESS_BINDING_REPORT_EXTENSION_NAME -
VK_EXT_DEVICE_ADDRESS_BINDING_REPORT_SPEC_VERSION -
Extending VkDebugUtilsMessageTypeFlagBitsEXT:
-
VK_DEBUG_UTILS_MESSAGE_TYPE_DEVICE_ADDRESS_BINDING_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_ADDRESS_BINDING_CALLBACK_DATA_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ADDRESS_BINDING_REPORT_FEATURES_EXT
-
Issues
1.) Should this extend VK_EXT_debug_utils or VK_EXT_device_memory_report?
RESOLVED: Extend VK_EXT_debug_utils. VK_EXT_device_memory_report focuses on memory allocations and would not normally trigger callbacks in all of the situations where VK_EXT_device_address_binding_report is expected to.
2.) Should this extension cover all Vulkan object types, or only resources such as buffers and images?
RESOLVED: The extension covers all Vulkan objects, and is not restricted to objects backed by VkDeviceMemory objects.
3.) Should reallocation be identified explicitly, or as an unbind/bind pair?
RESOLVED: Reallocation should be represented as an unbind/bind pair.
4.) Can multiple Vulkan objects share an overlapping virtual address range?
RESOLVED: Yes. This can be expected to occur due to resources aliasing.
5.) Can a single Vulkan object be associated with multiple virtual address ranges concurrently?
RESOLVED: Yes. These should be reported via multiple calls to the reporting callback.
6.) Should the virtual address ranges associated with internal allocations such as memory pools be reported?
RESOLVED: Virtual address ranges associated with internal allocations should only be reported when they become associated with a specific Vulkan object. In the case of internal pool allocations, a bind event should be reported when resources from the pool are assigned to a Vulkan object, and an unbind event should be reported when those resources are returned to the pool. Implementations should not report the binding or unbinding of virtual address ranges for which there are no related API objects visible to the application developer.
7.) Can an implementation report binding a virtual address range at VkImage or VkImageView creation, rather than in response to vkBindImageMemory?
RESOLVED: Yes. Virtual address range binding should be reported at the appropriate point at which it occurs within the implementation. This extension does not mandate when that should occur, and applications should anticipate receiving callback events at any point after registering callbacks.
8.) Can reporting of binding/unbinding be deferred until a resource is referenced by an executing command buffer?
RESOLVED: Changes to the virtual address ranges associated with a Vulkan object should be reported as close as possible to where they occur within the implementation. If virtual address binding is deferred, then the callback should also be deferred to match.
9.) Do bind/unbind callbacks have to form matched pairs? Can a large region be bound, and then subregions unbound, resulting in fragmentation?
RESOLVED: Splitting of virtual address regions, and unmatched bind/unbind callbacks may occur. Developers should anticipate that sparse memory may exhibit this behavior.
10.) The specification mandates that a callback must be triggered whenever a GPU virtual address range associated with any Vulkan object is bound or unbound. Do we need queries or properties indicating which Vulkan objects will report binding modifications?
RESOLVED: No. This extension is not intended to mandate how and when implementations bind virtual ranges to objects. Adding queries or properties would constrain implementations, which might otherwise vary how virtual address bindings occur based on usage.
11.) Should vkAllocateMemory and vkFreeMemory trigger reporting callbacks?
RESOLVED: If an implementation binds a GPU virtual address range when vkAllocateMemory is called, then the callbacks must be triggered associating the virtual address range with the VkDeviceMemory object. If the device memory is subsequently bound to a buffer or image via vkBind*Memory, the callbacks should be triggered a second time, reporting the association between virtual address range and the buffer/image.
VK_EXT_device_fault
- Name String
-
VK_EXT_device_fault - Extension Type
-
Device extension
- Registered Extension Number
-
342
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Ralph Potter [GitLab]r_potter
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-03-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Ralph Potter, Samsung
-
Stuart Smith, AMD
-
Jan-Harald Fredriksen, ARM
-
Mark Bellamy, ARM
-
Andrew Ellem, Google
-
Alex Walters, IMG
-
Jeff Bolz, NVIDIA
-
Baldur Karlsson, Valve
-
Description
Device loss can be triggered by a variety of issues, including invalid API usage, implementation errors, or hardware failures.
This extension introduces a new command: vkGetDeviceFaultInfoEXT,
which may be called subsequent to a VK_ERROR_DEVICE_LOST error code
having been returned by the implementation.
This command allows developers to query for additional information on GPU
faults which may have caused device loss, and to generate binary crash
dumps, which may be loaded into external tools for further diagnosis.
New Enum Constants
-
VK_EXT_DEVICE_FAULT_EXTENSION_NAME -
VK_EXT_DEVICE_FAULT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_FAULT_COUNTS_EXT -
VK_STRUCTURE_TYPE_DEVICE_FAULT_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FAULT_FEATURES_EXT
-
VK_EXT_device_generated_commands
- Name String
-
VK_EXT_device_generated_commands - Extension Type
-
Device extension
- Registered Extension Number
-
573
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_EXT_shader_object
-
- Contact
-
-
Mike Blumenkrantz [GitHub]zmike
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-02-23
- 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 requires
VK_KHR_maintenance5for the ability to use VkPipelineCreateFlags2KHR. -
This extension interacts with
VK_NV_mesh_shader. If the latter extension is not supported, remove the command tokens to initiate NV mesh tasks drawing in this extension. -
This extension interacts with
VK_EXT_mesh_shader. If the latter extension is not supported, remove the command tokens to initiate EXT mesh tasks drawing in this extension. -
This extension interacts with
VK_KHR_ray_tracing_pipeline. If the latter extension is not supported, remove the command tokens to initiate ray tracing in this extension. -
This extension interacts with
VK_EXT_shader_object. If the latter extension is not supported, remove references to shader objects in this extension.
-
- Contributors
-
-
Mike Blumenkrantz, VALVE
-
Hans-Kristian Arntzen, VALVE
-
Jan-Harald Fredriksen, ARM
-
Spencer Fricke, LunarG
-
Ricardo Garcia, Igalia
-
Tobias Hector, AMD
-
Baldur Karlsson, VALVE
-
Christoph Kubisch, NVIDIA
-
Lionel Landwerlin, INTEL
-
Jon Leech, Khronos
-
Ting Wei, ARM
-
Ken Shanyi Zhang, AMD
-
Faith Ekstrand, Collabora
-
Vikram Kushwaha, NVIDIA
-
Connor Abbott, VALVE
-
Samuel Pitoiset, VALVE
-
Description
This extension allows the device to generate a number of commands for
command buffers.
It provides a subset of functionality from both
VK_NV_device_generated_commands and
VK_NV_device_generated_commands_compute as well as some new features.
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.
To render objects which have been processed on the device, Vulkan has
several ways to perform indirect rendering, from the most basic
vkCmdDrawIndirect with one indirect draw to vkCmdDrawIndirectCount which
supports multiple indirect draws batched together, with a way to determine
number of draws at device execution time.
However, if rendering state needs to change between the indirect draws, then unextended Vulkan forces the application to speculatively record a prohibitive number of redundant indirect commands covering all possible state combinations - which could end up processing nothing after culling - or 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 and shader object 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 vkGetBufferDeviceAddress -
create a
VkIndirectExecutionSetEXTfor the ability to change shaders on the device. -
create a VkIndirectCommandsLayoutEXT, which lists the VkIndirectCommandsTokenTypeEXT 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 based on the layout.
-
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 vkGetGeneratedCommandsMemoryRequirementsEXT. -
optionally preprocess the generated content using vkCmdPreprocessGeneratedCommandsEXT, for example on an asynchronous compute queue, or for the purpose of reusing the data in multiple executions.
-
call vkCmdExecuteGeneratedCommandsEXT 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 number of vertex buffer bindings
-
a different index buffer, with an optional dynamic offset and index type
-
a number of different push constants
-
updates to bound shader stages
For each dispatch in a sequence, the following can be specified:
-
a number of different push constants
-
updates to bound shader stages
For each trace rays in a sequence, the following can be specified:
-
a number of different push constants
-
updates to bound shader stages
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 VkGeneratedCommandsInfoEXT, VkGeneratedCommandsMemoryRequirementsInfoEXT:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
If VK_EXT_shader_object is supported:
New Enum Constants
-
VK_EXT_DEVICE_GENERATED_COMMANDS_EXTENSION_NAME -
VK_EXT_DEVICE_GENERATED_COMMANDS_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_COMMAND_PREPROCESS_READ_BIT_EXT -
VK_ACCESS_COMMAND_PREPROCESS_WRITE_BIT_EXT
-
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_PREPROCESS_BUFFER_BIT_EXT
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_EXT -
VK_OBJECT_TYPE_INDIRECT_EXECUTION_SET_EXT
-
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_COMMAND_PREPROCESS_BIT_EXT
-
-
Extending VkShaderCreateFlagBitsEXT:
-
VK_SHADER_CREATE_INDIRECT_BINDABLE_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_INFO_EXT -
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_MEMORY_REQUIREMENTS_INFO_EXT -
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_PIPELINE_INFO_EXT -
VK_STRUCTURE_TYPE_GENERATED_COMMANDS_SHADER_INFO_EXT -
VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_INDIRECT_COMMANDS_LAYOUT_TOKEN_EXT -
VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_PIPELINE_INFO_EXT -
VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_SHADER_INFO_EXT -
VK_STRUCTURE_TYPE_INDIRECT_EXECUTION_SET_SHADER_LAYOUT_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_WRITE_INDIRECT_EXECUTION_SET_PIPELINE_EXT -
VK_STRUCTURE_TYPE_WRITE_INDIRECT_EXECUTION_SET_SHADER_EXT
-
VK_EXT_device_memory_report
- Name String
-
VK_EXT_device_memory_report - Extension Type
-
Device extension
- Registered Extension Number
-
285
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Yiwei Zhang [GitHub]zzyiwei
-
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 application 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 a
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.
VK_EXT_direct_mode_display
- Name String
-
VK_EXT_direct_mode_display - Extension Type
-
Instance extension
- Registered Extension Number
-
89
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Nicolas Caramelli [GitHub]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
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2023-01-18
- 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.
Version 2 of this extension introduces new dynamic states
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT and
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT, and the corresponding
functions vkCmdSetDiscardRectangleEnableEXT and
vkCmdSetDiscardRectangleModeEXT.
Applications that use these dynamic states must ensure the implementation
advertises at least specVersion 2 of this extension.
New Enum Constants
-
VK_EXT_DISCARD_RECTANGLES_EXTENSION_NAME -
VK_EXT_DISCARD_RECTANGLES_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT -
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
James Jones [GitHub]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_dynamic_rendering_unused_attachments
- Name String
-
VK_EXT_dynamic_rendering_unused_attachments - Extension Type
-
Device extension
- Registered Extension Number
-
500
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-05-22
- IP Status
-
No known IP claims.
- Contributors
-
-
Daniel Story, Nintendo
-
Hans-Kristian Arntzen, Valve
-
Jan-Harald Fredriksen, Arm
-
James Fitzpatrick, Imagination Technologies
-
Pan Gao, Huawei Technologies
-
Ricardo Garcia, Igalia
-
Stu Smith, AMD
-
Description
This extension lifts some restrictions in the
VK_KHR_dynamic_rendering extension to allow render pass instances
and bound pipelines within those render pass instances to have an unused
attachment specified in one but not the other.
It also allows pipelines to use different formats in a render pass as long
the attachment is NULL.
New Enum Constants
-
VK_EXT_DYNAMIC_RENDERING_UNUSED_ATTACHMENTS_EXTENSION_NAME -
VK_EXT_DYNAMIC_RENDERING_UNUSED_ATTACHMENTS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_UNUSED_ATTACHMENTS_FEATURES_EXT
-
VK_EXT_extended_dynamic_state3
- Name String
-
VK_EXT_extended_dynamic_state3 - Extension Type
-
Device extension
- Registered Extension Number
-
456
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_1
-
Interacts with VK_EXT_blend_operation_advanced
-
Interacts with VK_EXT_conservative_rasterization
-
Interacts with VK_EXT_depth_clip_control
-
Interacts with VK_EXT_depth_clip_enable
-
Interacts with VK_EXT_line_rasterization
-
Interacts with VK_EXT_provoking_vertex
-
Interacts with VK_EXT_sample_locations
-
Interacts with VK_EXT_transform_feedback
-
Interacts with VK_KHR_maintenance2
-
Interacts with VK_NV_clip_space_w_scaling
-
Interacts with VK_NV_coverage_reduction_mode
-
Interacts with VK_NV_fragment_coverage_to_color
-
Interacts with VK_NV_framebuffer_mixed_samples
-
Interacts with VK_NV_representative_fragment_test
-
Interacts with VK_NV_shading_rate_image
-
Interacts with VK_NV_viewport_swizzle
-
Interacts with VkPhysicalDeviceExtendedDynamicState3FeaturesEXT::extendedDynamicState3AlphaToOneEnable
-
Interacts with VkPhysicalDeviceExtendedDynamicState3FeaturesEXT::extendedDynamicState3DepthClampEnable
-
Interacts with VkPhysicalDeviceExtendedDynamicState3FeaturesEXT::extendedDynamicState3LogicOpEnable
-
Interacts with VkPhysicalDeviceExtendedDynamicState3FeaturesEXT::extendedDynamicState3PolygonMode
-
Interacts with VkPhysicalDeviceExtendedDynamicState3FeaturesEXT::extendedDynamicState3RasterizationStream
-
Interacts with VkPhysicalDeviceExtendedDynamicState3FeaturesEXT::extendedDynamicState3TessellationDomainOrigin
-
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-09-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Daniel Story, Nintendo
-
Jamie Madill, Google
-
Jan-Harald Fredriksen, Arm
-
Faith Ekstrand, Collabora
-
Mike Blumenkrantz, Valve
-
Ricardo Garcia, Igalia
-
Samuel Pitoiset, Valve
-
Shahbaz Youssefi, Google
-
Stu Smith, AMD
-
Tapani Pälli, Intel
-
Description
This extension adds almost all of the remaining pipeline state as dynamic state to help applications further reduce the number of monolithic pipelines they need to create and bind.
New Commands
If VK_EXT_blend_operation_advanced is supported:
If VK_EXT_conservative_rasterization is supported:
If VK_EXT_depth_clip_control is supported:
If VK_EXT_depth_clip_enable is supported:
If VK_EXT_line_rasterization is supported:
If VK_EXT_provoking_vertex is supported:
If VK_EXT_sample_locations is supported:
If VK_EXT_transform_feedback is supported:
If VK_KHR_maintenance2 or Vulkan Version 1.1 is supported:
If VK_NV_clip_space_w_scaling is supported:
If VK_NV_coverage_reduction_mode is supported:
If VK_NV_fragment_coverage_to_color is supported:
If VK_NV_framebuffer_mixed_samples is supported:
If VK_NV_representative_fragment_test is supported:
If VK_NV_shading_rate_image is supported:
If VK_NV_viewport_swizzle is supported:
New Enum Constants
-
VK_EXT_EXTENDED_DYNAMIC_STATE_3_EXTENSION_NAME -
VK_EXT_EXTENDED_DYNAMIC_STATE_3_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT -
VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT -
VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT -
VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT -
VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT -
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT -
VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT -
VK_DYNAMIC_STATE_POLYGON_MODE_EXT -
VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT -
VK_DYNAMIC_STATE_SAMPLE_MASK_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_3_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_3_PROPERTIES_EXT
-
If VK_EXT_blend_operation_advanced is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT
-
If VK_EXT_conservative_rasterization is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT -
VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT
-
If VK_EXT_depth_clip_control is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT
-
If VK_EXT_depth_clip_enable is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT
-
If VK_EXT_line_rasterization is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT -
VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT
-
If VK_EXT_provoking_vertex is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT
-
If VK_EXT_sample_locations is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT
-
If VK_EXT_transform_feedback is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT
-
If VK_KHR_maintenance2 or Vulkan Version 1.1 is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT
-
If VK_NV_clip_space_w_scaling is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV
-
If VK_NV_coverage_reduction_mode is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV
-
If VK_NV_fragment_coverage_to_color is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV -
VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV
-
If VK_NV_framebuffer_mixed_samples is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV -
VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV
-
If VK_NV_representative_fragment_test is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV
-
If VK_NV_shading_rate_image is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV
-
If VK_NV_viewport_swizzle is supported:
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV
-
Issues
1) What about the VkPipelineMultisampleStateCreateInfo state
sampleShadingEnable and minSampleShading?
- UNRESOLVED
-
-
sampleShadingEnableandminSampleShadingare required when compiling the fragment shader, and it is not meaningful to set them dynamically since they always need to match the fragment shader state, so this hardware state may as well just come from the pipeline with the fragment shader.
-
VK_EXT_external_memory_acquire_unmodified
- Name String
-
VK_EXT_external_memory_acquire_unmodified - Extension Type
-
Device extension
- Registered Extension Number
-
454
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Lina Versace [GitHub]linyaa-kiwi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-03-09
- Contributors
-
-
Lina Versace, Google
-
Chia-I Wu, Google
-
James Jones, NVIDIA
-
Yiwei Zhang, Google
-
Description
A memory barrier may have a performance penalty when acquiring ownership of a subresource range from an external queue family. This extension provides API that may reduce the performance penalty if ownership of the subresource range was previously released to the external queue family and if the resource’s memory has remained unmodified between the release and acquire operations.
New Enum Constants
-
VK_EXT_EXTERNAL_MEMORY_ACQUIRE_UNMODIFIED_EXTENSION_NAME -
VK_EXT_EXTERNAL_MEMORY_ACQUIRE_UNMODIFIED_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_ACQUIRE_UNMODIFIED_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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Lina Versace [GitHub]linyaa-kiwi
-
Other Extension Metadata
- Last Modified Date
-
2017-10-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Lina Versace, Google
-
James Jones, NVIDIA
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Rakos [GitHub]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
-
Faith 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_external_memory_metal
- Name String
-
VK_EXT_external_memory_metal - Extension Type
-
Device extension
- Registered Extension Number
-
603
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Aitor Camacho Larrondo [GitHub]aitor-lunarg
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-07-18
- IP Status
-
No known IP claims.
- Contributors
-
-
Aitor Camacho Larrondo, LunarG Inc.
-
Description
An application may wish to reference device memory in multiple Vulkan device instances, in multiple processes, and/or in Metal API. This extension enables an application to export and import Metal handles from Vulkan memory objects such that the underlying resources can be referenced outside the scope of the Vulkan device instance that created them.
New Enum Constants
-
VK_EXT_EXTERNAL_MEMORY_METAL_EXTENSION_NAME -
VK_EXT_EXTERNAL_MEMORY_METAL_SPEC_VERSION -
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLBUFFER_BIT_EXT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLHEAP_BIT_EXT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_METAL_HANDLE_INFO_EXT -
VK_STRUCTURE_TYPE_MEMORY_GET_METAL_HANDLE_INFO_EXT -
VK_STRUCTURE_TYPE_MEMORY_METAL_HANDLE_PROPERTIES_EXT
-
VK_EXT_filter_cubic
- Name String
-
VK_EXT_filter_cubic - Extension Type
-
Device extension
- Registered Extension Number
-
171
- Revision
-
3
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
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-Harald Fredriksen, 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
-
VK_EXT_fragment_density_map
- Name String
-
VK_EXT_fragment_density_map - Extension Type
-
Device extension
- Registered Extension Number
-
219
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_dynamic_rendering
-
Interacts with VK_KHR_format_feature_flags2
-
- SPIR-V Dependencies
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2021-09-30
- Interactions and External Dependencies
-
-
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 Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkRenderPassCreateInfo, VkRenderPassCreateInfo2:
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
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 or Vulkan Version 1.3 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_FRAGMENT_DENSITY_MAP_BIT_EXT
-
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering 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
-
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Matthew Netsch [GitHub]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_2_EXTENSION_NAME -
VK_EXT_FRAGMENT_DENSITY_MAP_2_SPEC_VERSION -
Extending VkImageViewCreateFlagBits:
-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_2_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_2_PROPERTIES_EXT
-
VK_EXT_fragment_density_map_offset
- Name String
-
VK_EXT_fragment_density_map_offset - Extension Type
-
Device extension
- Registered Extension Number
-
620
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Connor Abbott [GitHub]cwabbott0
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-02-14
- Contributors
-
-
Connor Abbott, Valve Corporation
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Jonathan Tinkham, Qualcomm Technologies, Inc.
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Manan Katwala, Qualcomm Technologies, Inc.
-
Mike Blumenkrantz, Valve Corporation
-
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 Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkSubpassEndInfo, VkRenderingEndInfoEXT:
New Enum Constants
-
VK_EXT_FRAGMENT_DENSITY_MAP_OFFSET_EXTENSION_NAME -
VK_EXT_FRAGMENT_DENSITY_MAP_OFFSET_SPEC_VERSION -
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_OFFSET_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_RENDERING_END_INFO_EXT -
VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_OFFSET_END_INFO_EXT
-
VK_EXT_fragment_shader_interlock
- Name String
-
VK_EXT_fragment_shader_interlock - Extension Type
-
Device extension
- Registered Extension Number
-
252
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-05-02
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_ARB_fragment_shader_interlock
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, Arm
-
Faith 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_frame_boundary
- Name String
-
VK_EXT_frame_boundary - Extension Type
-
Device extension
- Registered Extension Number
-
376
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
James Fitzpatrick [GitHub]jamesfitzpatrick
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-06-14
- Contributors
-
-
James Fitzpatrick, Imagination Technologies
-
Hugues Evrard, Google
-
Melih Yasin Yalcin, Google
-
Andrew Garrard, Imagination Technologies
-
Jan-Harald Fredriksen, Arm
-
Vassili Nikolaev, NVIDIA
-
Ting Wei, Huawei
-
Description
VK_EXT_frame_boundary is a device extension that helps tools (such as debuggers) to group queue submissions per frames in non-trivial scenarios, typically when vkQueuePresentKHR is not a relevant frame boundary delimiter.
New Enum Constants
-
VK_EXT_FRAME_BOUNDARY_EXTENSION_NAME -
VK_EXT_FRAME_BOUNDARY_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FRAME_BOUNDARY_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAME_BOUNDARY_FEATURES_EXT
-
VK_EXT_full_screen_exclusive
- Name String
-
VK_EXT_full_screen_exclusive - Extension Type
-
Device extension
- Registered Extension Number
-
256
- Revision
-
4
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_1
-
Interacts with VK_KHR_device_group
-
Interacts with VK_KHR_win32_surface
-
- Contact
-
-
James Jones [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Tobias Hector [GitHub]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
-
3
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Courtney Goeltzenleuchter [GitHub]courtney-g
-
Other Extension Metadata
- Last Modified Date
-
2024-03-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, Google
-
Sebastian Wick, Red Hat Inc.
-
Tobias Hector, AMD
-
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.
SMPTE 2086 metadata defines the color volume of the display on which the content was optimized for viewing and includes the color primaries, white point, and luminance range. When such content is reproduced on another display, this metadata can be used by the presentation engine to improve processing of images. For instance, values in the image can first be clamped to the color volume described in the metadata, and then what remains can be remapped to the color volume of the presentation engine.
CTA 861.3 metadata additionally includes the maximum intended luminance for the content and the maximum average light level across frames.
This extension does not define exactly how this metadata is used, however, it simply provides a mechanism to provide it to the presentation engine. Presentation engines may process the image based on the metadata before displaying it, resulting in the image being modified outside of Vulkan. For example, the clamping of colors in the image to the color volume may change those values in the image itself.
The metadata does not override or otherwise influence the color space and color encoding.
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 for the currently specified metadata?
No, Vulkan does not provide queries for state that the application can track on its own.
2) Should we specify default metadata if not specified by the application?
No, the metadata is optional and the absence of the metadata is well-defined.
Version History
-
Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)
-
Initial version
-
-
Revision 2, 2018-12-19 (Courtney Goeltzenleuchter)
-
Correct implicit validity for VkHdrMetadataEXT structure
-
-
Revision 3, 2024-03-26 (Tobias Hector & Sebastian Wick)
-
Clarifications and removal of erroneous "reference monitor" term
-
VK_EXT_headless_surface
- Name String
-
VK_EXT_headless_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
257
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Lisa Wu [GitHub]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 customizable 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 customizable 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Mike Blumenkrantz [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jan-Harald Fredriksen [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jan-Harald Fredriksen [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_format_feature_flags2
-
- Contact
-
-
Lina Versace [GitHub]linyaa-kiwi
-
Other Extension Metadata
- Last Modified Date
-
2021-09-30
- IP Status
-
No known IP claims.
- Contributors
-
-
Antoine Labour, Google
-
Bas Nieuwenhuizen, Google
-
Lina Versace, Google
-
James Jones, NVIDIA
-
Faith 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 color space.
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 expressible 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 framebuffer’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 or Vulkan Version 1.3 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 or Vulkan Version 1.3 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 (Lina Versace)
-
First stable revision
-
-
Revision 2, 2021-09-30 (Jon Leech)
-
Add interaction with
VK_KHR_format_feature_flags2tovk.xml
-
VK_EXT_image_sliced_view_of_3d
- Name String
-
VK_EXT_image_sliced_view_of_3d - Extension Type
-
Device extension
- Registered Extension Number
-
419
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Mike Blumenkrantz [GitHub]zmike
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-01-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Mike Blumenkrantz, Valve
-
Hans-Kristian Arntzen, Valve
-
Ricardo Garcia, Igalia
-
Shahbaz Youssefi, Google
-
Piers Daniell, NVIDIA
-
Description
This extension allows creating 3D views of 3D images such that the views contain a subset of the slices in the image, using a Z offset and range, for the purpose of using the views as storage image descriptors. This matches functionality in D3D12 and is primarily intended to support D3D12 emulation.
New Enum Constants
-
VK_EXT_IMAGE_SLICED_VIEW_OF_3D_EXTENSION_NAME -
VK_EXT_IMAGE_SLICED_VIEW_OF_3D_SPEC_VERSION -
VK_REMAINING_3D_SLICES_EXT -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_VIEW_SLICED_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_SLICED_VIEW_OF_3D_FEATURES_EXT
-
VK_EXT_image_view_min_lod
- Name String
-
VK_EXT_image_view_min_lod - Extension Type
-
Device extension
- Registered Extension Number
-
392
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Joshua Ashton [GitHub]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
-
Faith Ekstrand, Intel
-
Tom Olson, ARM
-
Description
This extension allows applications to clamp the minimum LOD value during
Image Level(s) Selection,
Texel Gathering 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_layer_settings
- Name String
-
VK_EXT_layer_settings - Extension Type
-
Instance extension
- Registered Extension Number
-
497
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Christophe Riccio [GitHub]christophe
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-09-23
- IP Status
-
No known IP claims.
- Contributors
-
-
Christophe Riccio, LunarG
-
Mark Lobodzinski, LunarG
-
Charles Giessen, LunarG
-
Spencer Fricke, LunarG
-
Juan Ramos, LunarG
-
Daniel Rakos, RasterGrid
-
Shahbaz Youssefi, Google
-
Lina Versace, Google
-
Bill Hollings, The Brenwill Workshop
-
Jon Leech, Khronos
-
Tom Olson, Arm
-
Description
This extension provides a mechanism for configuring programmatically through the Vulkan API the behavior of layers.
This extension provides the VkLayerSettingsCreateInfoEXT structure
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 VkLayerSettingEXT structure values that configure specific features of layers.
|
Note
|
The |
New Enum Constants
-
VK_EXT_LAYER_SETTINGS_EXTENSION_NAME -
VK_EXT_LAYER_SETTINGS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT
-
Example
One example usage of VK_EXT_layer_settings is as implemented by the Vulkan
Profiles layer.
It allows the profiles layer tests used by the profiles layer C.I. to programmatically configure the layer for each test without affecting the C.I. environment, allowing to run multiple tests concurrently.
const char* profile_file_data = JSON_TEST_FILES_PATH "VP_KHR_roadmap_2022.json";
const char* profile_name_data = "VP_KHR_roadmap_2022";
VkBool32 emulate_portability_data = VK_TRUE;
const char* simulate_capabilities[] = {
"SIMULATE_API_VERSION_BIT",
"SIMULATE_FEATURES_BIT",
"SIMULATE_PROPERTIES_BIT",
"SIMULATE_EXTENSIONS_BIT",
"SIMULATE_FORMATS_BIT",
"SIMULATE_QUEUE_FAMILY_PROPERTIES_BIT"
};
const char* debug_reports[] = {
"DEBUG_REPORT_ERROR_BIT",
"DEBUG_REPORT_WARNING_BIT",
"DEBUG_REPORT_NOTIFICATION_BIT",
"DEBUG_REPORT_DEBUG_BIT"
};
const VkLayerSettingEXT settings[] = {
{kLayerName, kLayerSettingsProfileFile, VK_LAYER_SETTING_TYPE_STRING_EXT, 1, &profile_file_data},
{kLayerName, kLayerSettingsProfileName, VK_LAYER_SETTING_TYPE_STRING_EXT, 1, &profile_name_data},
{kLayerName, kLayerSettingsEmulatePortability, VK_LAYER_SETTING_TYPE_BOOL32_EXT, 1, &emulate_portability_data},
{kLayerName, kLayerSettingsSimulateCapabilities, VK_LAYER_SETTING_TYPE_STRING_EXT,
static_cast<uint32_t>(std::size(simulate_capabilities)), simulate_capabilities},
{kLayerName, kLayerSettingsDebugReports, VK_LAYER_SETTING_TYPE_STRING_EXT,
static_cast<uint32_t>(std::size(debug_reports)), debug_reports}
};
const VkLayerSettingsCreateInfoEXT layer_settings_create_info{
VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT, nullptr,
static_cast<uint32_t>(std::size(settings)), settings};
VkInstanceCreateInfo inst_create_info = {};
...
inst_create_info.pNext = &layer_settings_create_info;
vkCreateInstance(&inst_create_info, nullptr, &_instances);
VK_EXT_legacy_dithering
- Name String
-
VK_EXT_legacy_dithering - Extension Type
-
Device extension
- Registered Extension Number
-
466
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_VERSION_1_4
-
Interacts with VK_KHR_dynamic_rendering
-
Interacts with VK_KHR_maintenance5
-
- Special Use
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-02-22
- Contributors
-
-
Shahbaz Youssefi, Google
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, Arm
-
Description
This extension exposes a hardware feature used by some vendors to implement OpenGL’s dithering. The purpose of this extension is to support layering OpenGL over Vulkan, by allowing the layer to take advantage of the same hardware feature and provide equivalent dithering to OpenGL applications.
New Enum Constants
-
VK_EXT_LEGACY_DITHERING_EXTENSION_NAME -
VK_EXT_LEGACY_DITHERING_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_DITHERING_FEATURES_EXT
-
-
Extending VkSubpassDescriptionFlagBits:
-
VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT
-
If VK_KHR_dynamic_rendering or Vulkan Version 1.3 and VK_KHR_maintenance5 or Vulkan Version 1.4 is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_ENABLE_LEGACY_DITHERING_BIT_EXT
-
-
Extending VkRenderingFlagBits:
-
VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT
-
Version History
-
Revision 1, 2022-03-31 (Shahbaz Youssefi)
-
Internal revisions
-
-
Revision 2, 2024-02-22 (Shahbaz Youssefi)
-
Added pipeline create flag to support dynamic rendering
-
Issues
1) In OpenGL, the dither state can change dynamically. Should this extension add a pipeline state for dither?
RESOLVED: No. Changing dither state is rarely, if ever, done during rendering. Every surveyed Android application either entirely disables dither, explicitly enables it, or uses the default state (which is enabled). Additionally, on some hardware dither can only be specified in a render pass granularity, so a change in dither state would necessarily need to cause a render pass break. This extension considers dynamic changes in OpenGL dither state a theoretical situation, and expects the layer to break the render pass in such a situation without any practical downsides.
VK_EXT_legacy_vertex_attributes
- Name String
-
VK_EXT_legacy_vertex_attributes - Extension Type
-
Device extension
- Registered Extension Number
-
496
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Mike Blumenkrantz [GitHub]zmike
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-02-23
- IP Status
-
No known IP claims.
- Contributors
-
-
Mike Blumenkrantz, Valve
-
Piers Daniell, NVIDIA
-
Spencer Fricke, LunarG
-
Alyssa Rosenzweig, Valve
-
Description
This extension adds support for legacy features of (non-64-bit) vertex attributes as found in OpenGL:
-
Vertex attributes loaded from arbitrary buffer alignments
-
Vertex attributes using arbitrary strides
-
Vertex attributes where the component data type of the binding does not match the component numeric type of the shader input
These features are only usable with dynamic vertex input. Unaligned loads of vertex attributes may incur performance penalties, indicated with a property.
New Enum Constants
-
VK_EXT_LEGACY_VERTEX_ATTRIBUTES_EXTENSION_NAME -
VK_EXT_LEGACY_VERTEX_ATTRIBUTES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_VERTEX_ATTRIBUTES_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_VERTEX_ATTRIBUTES_PROPERTIES_EXT
-
VK_EXT_map_memory_placed
- Name String
-
VK_EXT_map_memory_placed - Extension Type
-
Device extension
- Registered Extension Number
-
273
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Faith Ekstrand [GitHub]gfxstrand
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-03-21
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Depends on apitext:VK_KHR_map_memory2
-
Interacts with apitext:VK_EXT_external_memory_host
-
- Contributors
-
-
Faith Ekstrand, Collabora
-
Tobias Hector, AMD
-
James Jones, NVIDIA
-
Georg Lehmann, Valve
-
Derek Lesho, Codeweavers
-
Description
This extension allows an application to request that vkMapMemory2KHR attempt to place the memory map at a particular virtual address.
New Enum Constants
-
VK_EXT_MAP_MEMORY_PLACED_EXTENSION_NAME -
VK_EXT_MAP_MEMORY_PLACED_SPEC_VERSION -
Extending VkMemoryMapFlagBits:
-
VK_MEMORY_MAP_PLACED_BIT_EXT
-
-
Extending VkMemoryUnmapFlagBits:
-
VK_MEMORY_UNMAP_RESERVE_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MEMORY_MAP_PLACED_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_PROPERTIES_EXT
-
VK_EXT_memory_budget
- Name String
-
VK_EXT_memory_budget - Extension Type
-
Device extension
- Registered Extension Number
-
238
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jeff Bolz [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jeff Bolz [GitHub]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_mesh_shader
- Name String
-
VK_EXT_mesh_shader - Extension Type
-
Device extension
- Registered Extension Number
-
329
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_2
-
Interacts with VK_EXT_device_generated_commands
-
Interacts with VK_KHR_draw_indirect_count
-
Interacts with VK_KHR_fragment_shading_rate
-
Interacts with VK_NV_device_generated_commands
-
Interacts with VkPhysicalDeviceMeshShaderFeaturesEXT::primitiveFragmentShadingRateMeshShader
-
- SPIR-V Dependencies
- Contact
-
-
Christoph Kubisch [GitHub]pixeljetstream
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-01-20
- Interactions and External Dependencies
-
-
This extension provides API support for
GLSL_EXT_mesh_shader -
Interacts with Vulkan 1.1
-
Interacts with
VK_KHR_multiview -
Interacts with
VK_KHR_fragment_shading_rate
-
- Contributors
-
-
Christoph Kubisch, NVIDIA
-
Pat Brown, NVIDIA
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Piers Daniell, NVIDIA
-
Pierre Boudier, NVIDIA
-
Patrick Mours, NVIDIA
-
David Zhao Akeley, NVIDIA
-
Kedarnath Thangudu, NVIDIA
-
Timur Kristóf, Valve
-
Hans-Kristian Arntzen, Valve
-
Philip Rebohle, Valve
-
Mike Blumenkrantz, Valve
-
Slawomir Grajewski, Intel
-
Michal Pietrasiuk, Intel
-
Mariusz Merecki, Intel
-
Tom Olson, ARM
-
Jan-Harald Fredriksen, ARM
-
Sandeep Kakarlapudi, ARM
-
Ruihao Zhang, QUALCOMM
-
Ricardo Garcia, Igalia, S.L.
-
Tobias Hector, AMD
-
Stu Smith, AMD
-
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.
This extension also adds support for the following SPIR-V extension in Vulkan:
New Commands
If VK_KHR_draw_indirect_count or Vulkan Version 1.2 is supported:
New Enum Constants
-
VK_EXT_MESH_SHADER_EXTENSION_NAME -
VK_EXT_MESH_SHADER_SPEC_VERSION -
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT -
VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT
-
-
Extending VkQueryPipelineStatisticFlagBits:
-
VK_QUERY_PIPELINE_STATISTIC_MESH_SHADER_INVOCATIONS_BIT_EXT -
VK_QUERY_PIPELINE_STATISTIC_TASK_SHADER_INVOCATIONS_BIT_EXT
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT
-
-
Extending VkShaderStageFlagBits:
-
VK_SHADER_STAGE_MESH_BIT_EXT -
VK_SHADER_STAGE_TASK_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_PROPERTIES_EXT
-
If VK_EXT_device_generated_commands is supported:
-
Extending VkIndirectCommandsTokenTypeEXT:
-
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_EXT -
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_EXT
-
If VK_NV_device_generated_commands is supported:
-
Extending VkIndirectCommandsTokenTypeNV:
-
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV
-
New or Modified Built-In Variables
-
(modified)
Position -
(modified)
PointSize -
(modified)
ClipDistance -
(modified)
CullDistance -
(modified)
PrimitiveId -
(modified)
Layer -
(modified)
ViewportIndex -
(modified)
NumWorkgroups -
(modified)
WorkgroupSize -
(modified)
WorkgroupId -
(modified)
LocalInvocationId -
(modified)
GlobalInvocationId -
(modified)
LocalInvocationIndex -
(modified)
NumSubgroups -
(modified)
SubgroupId -
(modified)
DrawIndex -
(modified)
PrimitiveShadingRateKHR -
(modified)
ViewIndex
VK_EXT_metal_objects
- Name String
-
VK_EXT_metal_objects - Extension Type
-
Device extension
- Registered Extension Number
-
312
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Bill Hollings [GitHub]billhollings
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-04-04
- 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 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.
-
Incorporated 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.
-
-
Revision 2, 2024-04-04 (Bill Hollings)
-
Add an
__unsafe_unretainedownership qualifier to all Metal object declarations, to support Automatic Reference Counting (ARC) on Apple devices.
-
VK_EXT_metal_surface
- Name String
-
VK_EXT_metal_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
218
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Dzmitry Malyshau [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Mike Blumenkrantz [GitHub]zmike
-
Other Extension Metadata
- Last Modified Date
-
2021-05-19
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1.
-
Interacts with
VK_KHR_shader_draw_parameters.
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Mike Blumenkrantz, VALVE
-
Piers Daniell, NVIDIA
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Shahbaz Youssefi [GitHub]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_mutable_descriptor_type
- Name String
-
VK_EXT_mutable_descriptor_type - Extension Type
-
Device extension
- Registered Extension Number
-
495
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Joshua Ashton [GitHub]Joshua-Ashton
-
Hans-Kristian Arntzen [GitHub]HansKristian-Work
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-08-22
- 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_EXT_MUTABLE_DESCRIPTOR_TYPE_EXTENSION_NAME -
VK_EXT_MUTABLE_DESCRIPTOR_TYPE_SPEC_VERSION -
Extending VkDescriptorPoolCreateFlagBits:
-
VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT
-
-
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT
-
-
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_MUTABLE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MUTABLE_DESCRIPTOR_TYPE_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MUTABLE_DESCRIPTOR_TYPE_FEATURES_EXT
-
Version History
-
Revision 1, 2022-08-22 (Jon Leech)
-
Initial version, promoted from VK_VALVE_mutable_descriptor_type.
-
VK_EXT_nested_command_buffer
- Name String
-
VK_EXT_nested_command_buffer - Extension Type
-
Device extension
- Registered Extension Number
-
452
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2023-09-18
- Contributors
-
-
Daniel Story, Nintendo
-
Peter Kohaut, NVIDIA
-
Shahbaz Youssefi, Google
-
Slawomir Grajewski, Intel
-
Stu Smith, AMD
-
Description
With core Vulkan it is not legal to call vkCmdExecuteCommands when recording a secondary command buffer. This extension relaxes that restriction, allowing secondary command buffers to execute other secondary command buffers.
New Enum Constants
-
VK_EXT_NESTED_COMMAND_BUFFER_EXTENSION_NAME -
VK_EXT_NESTED_COMMAND_BUFFER_SPEC_VERSION -
Extending VkRenderingFlagBits:
-
VK_RENDERING_CONTENTS_INLINE_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_NESTED_COMMAND_BUFFER_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_NESTED_COMMAND_BUFFER_PROPERTIES_EXT
-
-
Extending VkSubpassContents:
-
VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT
-
Issues
1) The Command Buffer Levels property for the Vulkan commands comes from the
cmdbufferlevel attribute in vk.xml for the command, and it is currently
not possible to modify this attribute based on whether an extension is
enabled.
For this extension we want the cmdbufferlevel attribute for
vkCmdExecuteCommands to be primary,secondary when this extension is
enabled and primary otherwise.
RESOLVED: The cmdbufferlevel attribute for vkCmdExecuteCommands
has been changed to primary,secondary and a new VUID added to prohibit
recording this command in a secondary command buffer unless this extension
is enabled.
VK_EXT_non_seamless_cube_map
- Name String
-
VK_EXT_non_seamless_cube_map - Extension Type
-
Device extension
- Registered Extension Number
-
423
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Uses
- Contact
-
-
Georg Lehmann [GitHub]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_opacity_micromap
- Name String
-
VK_EXT_opacity_micromap - Extension Type
-
Device extension
- Registered Extension Number
-
397
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Christoph Kubisch [GitHub]pixeljetstream
-
Eric Werness
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-08-24
- Interactions and External Dependencies
-
-
This extension provides API support for
GLSL_EXT_opacity_micromap
-
- Contributors
-
-
Christoph Kubisch, NVIDIA
-
Eric Werness, NVIDIA
-
Josh Barczak, Intel
-
Stu Smith, AMD
-
Description
When adding transparency to a ray traced scene, an application can choose between further tessellating the geometry or using an any-hit shader to allow the ray through specific parts of the geometry. These options have the downside of either significantly increasing memory consumption or adding runtime overhead to run shader code in the middle of traversal, respectively.
This extension adds the ability to add an opacity micromap to geometry when building an acceleration structure. The opacity micromap compactly encodes opacity information which can be read by the implementation to mark parts of triangles as opaque or transparent. The format is externally visible to allow the application to compress its internal geometry and surface representations into the compressed format ahead of time. The compressed format subdivides each triangle into a set of subtriangles, each of which can be assigned either two or four opacity values. These opacity values can control if a ray hitting that subtriangle is treated as an opaque hit, complete miss, or possible hit, depending on the controls described in Ray Opacity Micromap.
This extension provides:
-
a VkMicromapEXT structure to store the micromap,
-
functions similar to acceleration structure build functions to build the opacity micromap array, and
-
a structure to extend VkAccelerationStructureGeometryTrianglesDataKHR to attach a micromap to the geometry of the acceleration structure.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
New Enum Constants
-
VK_EXT_OPACITY_MICROMAP_EXTENSION_NAME -
VK_EXT_OPACITY_MICROMAP_SPEC_VERSION -
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_MICROMAP_READ_BIT_EXT -
VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT -
VK_BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT
-
-
Extending VkBuildAccelerationStructureFlagBitsKHR:
-
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_EXT -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXT -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_EXT -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT
-
-
Extending VkGeometryInstanceFlagBitsKHR:
-
VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_BIT_EXT -
VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_EXT -
VK_GEOMETRY_INSTANCE_FORCE_OPACITY_MICROMAP_2_STATE_BIT_EXT -
VK_GEOMETRY_INSTANCE_FORCE_OPACITY_MICROMAP_2_STATE_EXT
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_MICROMAP_EXT
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT -
VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_OPACITY_MICROMAP_EXT -
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_MICROMAP_INFO_EXT -
VK_STRUCTURE_TYPE_COPY_MICROMAP_INFO_EXT -
VK_STRUCTURE_TYPE_COPY_MICROMAP_TO_MEMORY_INFO_EXT -
VK_STRUCTURE_TYPE_MICROMAP_BUILD_INFO_EXT -
VK_STRUCTURE_TYPE_MICROMAP_BUILD_SIZES_INFO_EXT -
VK_STRUCTURE_TYPE_MICROMAP_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_MICROMAP_VERSION_INFO_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPACITY_MICROMAP_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPACITY_MICROMAP_PROPERTIES_EXT
-
Reference Code
uint32_t BarycentricsToSpaceFillingCurveIndex(float u, float v, uint32_t level)
{
u = clamp(u, 0.0f, 1.0f);
v = clamp(v, 0.0f, 1.0f);
uint32_t iu, iv, iw;
// Quantize barycentric coordinates
float fu = u * (1u << level);
float fv = v * (1u << level);
iu = (uint32_t)fu;
iv = (uint32_t)fv;
float uf = fu - float(iu);
float vf = fv - float(iv);
if (iu >= (1u << level)) iu = (1u << level) - 1u;
if (iv >= (1u << level)) iv = (1u << level) - 1u;
uint32_t iuv = iu + iv;
if (iuv >= (1u << level))
iu -= iuv - (1u << level) + 1u;
iw = ~(iu + iv);
if (uf + vf >= 1.0f && iuv < (1u << level) - 1u) --iw;
uint32_t b0 = ~(iu ^ iw);
b0 &= ((1u << level) - 1u);
uint32_t t = (iu ^ iv) & b0;
uint32_t f = t;
f ^= f >> 1u;
f ^= f >> 2u;
f ^= f >> 4u;
f ^= f >> 8u;
uint32_t b1 = ((f ^ iu) & ~b0) | t;
// Interleave bits
b0 = (b0 | (b0 << 8u)) & 0x00ff00ffu;
b0 = (b0 | (b0 << 4u)) & 0x0f0f0f0fu;
b0 = (b0 | (b0 << 2u)) & 0x33333333u;
b0 = (b0 | (b0 << 1u)) & 0x55555555u;
b1 = (b1 | (b1 << 8u)) & 0x00ff00ffu;
b1 = (b1 | (b1 << 4u)) & 0x0f0f0f0fu;
b1 = (b1 | (b1 << 2u)) & 0x33333333u;
b1 = (b1 | (b1 << 1u)) & 0x55555555u;
return b0 | (b1 << 1u);
}
Issues
(1) Is the build actually similar to an acceleration structure build?
-
Resolved: The build should be much lighter-weight than an acceleration structure build, but the infrastructure is similar enough that it makes sense to keep the concepts compatible.
(2) Why does VkMicromapUsageEXT not have type/pNext?
-
Resolved: There can be a very large number of these structures, so doubling the size of these can be significant memory consumption. Also, an application may be loading these directly from a file which is more compatible with it being a flat structure. The including structures are extensible and are probably a more suitable place to add extensibility.
(3) Why is there a SPIR-V extension?
-
Resolved: There is a ray flag. To be consistent with how the existing ray tracing extensions work that ray flag needs its own extension.
(4) Should there be indirect micromap build?
-
Resolved: Not for now. There is more in-depth usage metadata required and it seems less likely that something like a GPU culling system would need to change the counts for a micromap.
(5) Should micromaps have a micromap device address?
-
Resolved: There is no need right now (can just use the handle) but that is a bit different from acceleration structures, though the two are not completely parallel in their usage.
(6) Why are the alignment requirements defined as a mix of hardcoded values and caps?
-
Resolved: This is most parallel with the definition of
VK_KHR_acceleration_structureand maintaining commonality makes it easier for applications to share memory.
VK_EXT_pageable_device_local_memory
- Name String
-
VK_EXT_pageable_device_local_memory - Extension Type
-
Device extension
- Registered Extension Number
-
413
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Piers Daniell [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Matthaeus G. Chajdas [GitHub]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
-
VK_EXT_physical_device_drm
- Name String
-
VK_EXT_physical_device_drm - Extension Type
-
Device extension
- Registered Extension Number
-
354
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Simon Ser [GitHub]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_library_group_handles
- Name String
-
VK_EXT_pipeline_library_group_handles - Extension Type
-
Device extension
- Registered Extension Number
-
499
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Hans-Kristian Arntzen [GitHub]HansKristian-Work
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-01-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Hans-Kristian Arntzen, Valve
-
Stuart Smith, AMD
-
Ricardo Garcia, Igalia
-
Lionel Landwerlin, Intel
-
Eric Werness, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
When using pipeline libraries in ray tracing pipelines, a library might get linked into different pipelines in an incremental way. An application can have a strategy where a ray tracing pipeline is comprised of N pipeline libraries and is later augmented by creating a new pipeline with N + 1 libraries. Without this extension, all group handles must be re-queried as the group handle is tied to the pipeline, not the library. This is problematic for applications which aim to decouple construction of record buffers and the linkage of ray tracing pipelines.
To aid in this, this extension enables support for querying group handles
directly from pipeline libraries.
Group handles obtained from a library must remain bitwise identical in any
VkPipeline that links to the library.
With this feature, the extension also improves compatibility with DXR 1.1 AddToStateObject(), which guarantees that group handles returned remain bitwise identical between parent and child pipelines. In addition, querying group handles from COLLECTION objects is also supported with that API.
New Enum Constants
-
VK_EXT_PIPELINE_LIBRARY_GROUP_HANDLES_EXTENSION_NAME -
VK_EXT_PIPELINE_LIBRARY_GROUP_HANDLES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_LIBRARY_GROUP_HANDLES_FEATURES_EXT
-
VK_EXT_pipeline_properties
- Name String
-
VK_EXT_pipeline_properties - Extension Type
-
Device extension
- Registered Extension Number
-
373
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Mukund Keshava [GitHub]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 command?
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 identifier to be supported.
VK_EXT_post_depth_coverage
- Name String
-
VK_EXT_post_depth_coverage - Extension Type
-
Device extension
- Registered Extension Number
-
156
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-07-17
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Shahbaz Youssefi [GitHub]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
-
VK_EXT_primitives_generated_query
- Name String
-
VK_EXT_primitives_generated_query - Extension Type
-
Device extension
- Registered Extension Number
-
383
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-01-24
- Contributors
-
-
Shahbaz Youssefi, Google
-
Piers Daniell, NVIDIA
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Jesse Hall [GitHub]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
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Lina Versace [GitHub]linyaa-kiwi
-
Other Extension Metadata
- Last Modified Date
-
2017-11-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Lina Versace, Google
-
James Jones, NVIDIA
-
Faith 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.
VK_EXT_rasterization_order_attachment_access
- Name String
-
VK_EXT_rasterization_order_attachment_access - Extension Type
-
Device extension
- Registered Extension Number
-
464
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jan-Harald Fredriksen [GitHub]janharaldfredriksen-arm
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-07-04
- IP Status
-
No known IP claims.
- Contributors
-
-
Tobias Hector, AMD
-
Jan-Harald Fredriksen, Arm
-
Description
This extension extends the mechanism of input attachments to allow access to framebuffer attachments that are used both as input and as color or depth/stencil attachments from one fragment to the next, in rasterization order, without explicit synchronization.
New Enum Constants
-
VK_EXT_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_EXTENSION_NAME -
VK_EXT_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_SPEC_VERSION -
Extending VkPipelineColorBlendStateCreateFlagBits:
-
VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT
-
-
Extending VkPipelineDepthStencilStateCreateFlagBits:
-
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT -
VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_FEATURES_EXT
-
-
Extending VkSubpassDescriptionFlagBits:
-
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT -
VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT
-
VK_EXT_rgba10x6_formats
- Name String
-
VK_EXT_rgba10x6_formats - Extension Type
-
Device extension
- Registered Extension Number
-
345
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Jan-Harald Fredriksen [GitHub]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_sample_locations
- Name String
-
VK_EXT_sample_locations - Extension Type
-
Device extension
- Registered Extension Number
-
144
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Rakos [GitHub]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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VkPhysicalDeviceShaderAtomicFloatFeaturesEXT::sparseImageFloat32AtomicAdd
-
Interacts with VkPhysicalDeviceShaderAtomicFloatFeaturesEXT::sparseImageFloat32Atomics
-
- SPIR-V Dependencies
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha-nv
-
Other Extension Metadata
- Last Modified Date
-
2020-07-15
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VkPhysicalDeviceShaderAtomicFloat2FeaturesEXT::sparseImageFloat32AtomicMinMax
-
- SPIR-V Dependencies
- Contact
-
-
Faith Ekstrand [GitHub]gfxstrand
-
Other Extension Metadata
- Last Modified Date
-
2020-08-14
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension provides API support for
GLSL_EXT_shader_atomic_float2
-
- Contributors
-
-
Faith 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_float8
- Name String
-
VK_EXT_shader_float8 - Extension Type
-
Device extension
- Registered Extension Number
-
568
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- API Interactions
-
-
Interacts with VK_KHR_cooperative_matrix
-
- SPIR-V Dependencies
- Contact
-
-
Kevin Petit [GitHub]kpet
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-04-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Kévin Petit, Arm Ltd.
-
Stu Smith, AMD
-
Jeff Bolz, NVIDIA
-
Craig Graham, Samsung
-
Description
This extension enables support for 8-bit floating-point data types as defined in SPV_EXT_float8.
New Enum Constants
-
VK_EXT_SHADER_FLOAT8_EXTENSION_NAME -
VK_EXT_SHADER_FLOAT8_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT8_FEATURES_EXT
-
If VK_KHR_cooperative_matrix is supported:
-
Extending VkComponentTypeKHR:
-
VK_COMPONENT_TYPE_FLOAT8_E4M3_EXT -
VK_COMPONENT_TYPE_FLOAT8_E5M2_EXT
-
Issues
1) Resolve interactions with the changes VK_KHR_shader_float16 makes to rules for denorm flushing (always allowed by default for all FP formats). How to describe the requirement to preserve subnormals?
+ RESOLVED: Subnormals are always preserved when converting FP8 values to IEEE 754 binary 16. In all other cases, subnormals may be flushed to zero.
+
VK_EXT_shader_image_atomic_int64
- Name String
-
VK_EXT_shader_image_atomic_int64 - Extension Type
-
Device extension
- Registered Extension Number
-
235
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Tobias Hector [GitHub]tobski
-
Other Extension Metadata
- Last Modified Date
-
2020-07-14
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Hans-Kristian Arntzen [GitHub]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
-
Faith 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_object
- Name String
-
VK_EXT_shader_object - Extension Type
-
Device extension
- Registered Extension Number
-
483
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_1
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_EXT_blend_operation_advanced
-
Interacts with VK_EXT_conservative_rasterization
-
Interacts with VK_EXT_depth_clamp_control
-
Interacts with VK_EXT_depth_clip_control
-
Interacts with VK_EXT_depth_clip_enable
-
Interacts with VK_EXT_fragment_density_map
-
Interacts with VK_EXT_line_rasterization
-
Interacts with VK_EXT_mesh_shader
-
Interacts with VK_EXT_provoking_vertex
-
Interacts with VK_EXT_sample_locations
-
Interacts with VK_EXT_subgroup_size_control
-
Interacts with VK_EXT_transform_feedback
-
Interacts with VK_KHR_device_group
-
Interacts with VK_KHR_fragment_shading_rate
-
Interacts with VK_NV_clip_space_w_scaling
-
Interacts with VK_NV_coverage_reduction_mode
-
Interacts with VK_NV_fragment_coverage_to_color
-
Interacts with VK_NV_framebuffer_mixed_samples
-
Interacts with VK_NV_mesh_shader
-
Interacts with VK_NV_representative_fragment_test
-
Interacts with VK_NV_shading_rate_image
-
Interacts with VK_NV_viewport_swizzle
-
- Contact
-
-
Daniel Story [GitHub]daniel-story
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-03-30
- Interactions and External Dependencies
-
-
Interacts with
VK_EXT_extended_dynamic_state -
Interacts with
VK_EXT_extended_dynamic_state2 -
Interacts with
VK_EXT_extended_dynamic_state3 -
Interacts with
VK_EXT_vertex_input_dynamic_state
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Piers Daniell, NVIDIA
-
Sandy Jamieson, Nintendo
-
Žiga Markuš, LunarG
-
Tobias Hector, AMD
-
Alex Walters, Imagination
-
Shahbaz Youssefi, Google
-
Ralph Potter, Samsung
-
Jan-Harald Fredriksen, ARM
-
Connor Abott, Valve
-
Arseny Kapoulkine, Roblox
-
Patrick Doane, Activision
-
Jeff Leger, Qualcomm
-
Stu Smith, AMD
-
Chris Glover, Google
-
Ricardo Garcia, Igalia
-
Faith Ekstrand, Collabora
-
Timur Kristóf, Valve
-
Caterina Shablia, Collabora
-
Daniel Koch, NVIDIA
-
Alyssa Rosenzweig, Collabora
-
Mike Blumenkrantz, Valve
-
Samuel Pitoiset, Valve
-
Qun Lin, AMD
-
Spencer Fricke, LunarG
-
Soroush Faghihi Kashani, Imagination
-
Description
This extension introduces a new VkShaderEXT object type which represents a single compiled shader stage. Shader objects provide a more flexible alternative to VkPipeline objects, which may be helpful in certain use cases.
New Commands
If VK_EXT_blend_operation_advanced is supported:
If VK_EXT_conservative_rasterization is supported:
If VK_EXT_depth_clamp_control is supported:
If VK_EXT_depth_clip_control is supported:
If VK_EXT_depth_clip_enable is supported:
If VK_EXT_line_rasterization is supported:
If VK_EXT_provoking_vertex is supported:
If VK_EXT_sample_locations is supported:
If VK_EXT_transform_feedback is supported:
If VK_NV_clip_space_w_scaling is supported:
If VK_NV_coverage_reduction_mode is supported:
If VK_NV_fragment_coverage_to_color is supported:
If VK_NV_framebuffer_mixed_samples is supported:
If VK_NV_representative_fragment_test is supported:
If VK_NV_shading_rate_image is supported:
If VK_NV_viewport_swizzle is supported:
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineShaderStageCreateInfo, VkShaderCreateInfoEXT:
New Enum Constants
-
VK_EXT_SHADER_OBJECT_EXTENSION_NAME -
VK_EXT_SHADER_OBJECT_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_SHADER_EXT
-
-
Extending VkResult:
-
VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT -
VK_INCOMPATIBLE_SHADER_BINARY_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_OBJECT_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_OBJECT_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_SHADER_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_VERTEX_INPUT_ATTRIBUTE_DESCRIPTION_2_EXT -
VK_STRUCTURE_TYPE_VERTEX_INPUT_BINDING_DESCRIPTION_2_EXT
-
If VK_EXT_fragment_density_map is supported:
-
Extending VkShaderCreateFlagBitsEXT:
-
VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT
-
If VK_EXT_mesh_shader or VK_NV_mesh_shader is supported:
-
Extending VkShaderCreateFlagBitsEXT:
-
VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT
-
If VK_EXT_subgroup_size_control or Vulkan Version 1.3 is supported:
-
Extending VkShaderCreateFlagBitsEXT:
-
VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT -
VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT
-
If VK_KHR_device_group or Vulkan Version 1.1 is supported:
-
Extending VkShaderCreateFlagBitsEXT:
-
VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT
-
If VK_KHR_fragment_shading_rate is supported:
-
Extending VkShaderCreateFlagBitsEXT:
-
VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT
-
Examples
Example 1
Create linked pair of vertex and fragment shaders.
// Logical device created with the shaderObject feature enabled
VkDevice device;
// SPIR-V shader code for a vertex shader, along with its size in bytes
void* pVertexSpirv;
size_t vertexSpirvSize;
// SPIR-V shader code for a fragment shader, along with its size in bytes
void* pFragmentSpirv;
size_t fragmentSpirvSize;
// Descriptor set layout compatible with the shaders
VkDescriptorSetLayout descriptorSetLayout;
VkShaderCreateInfoEXT shaderCreateInfos[2] =
{
{
.sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT,
.pNext = NULL,
.flags = VK_SHADER_CREATE_LINK_STAGE_BIT_EXT,
.stage = VK_SHADER_STAGE_VERTEX_BIT,
.nextStage = VK_SHADER_STAGE_FRAGMENT_BIT,
.codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT,
.codeSize = vertexSpirvSize,
.pCode = pVertexSpirv,
.pName = "main",
.setLayoutCount = 1,
.pSetLayouts = &descriptorSetLayout;
.pushConstantRangeCount = 0,
.pPushConstantRanges = NULL,
.pSpecializationInfo = NULL
},
{
.sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT,
.pNext = NULL,
.flags = VK_SHADER_CREATE_LINK_STAGE_BIT_EXT,
.stage = VK_SHADER_STAGE_FRAGMENT_BIT,
.nextStage = 0,
.codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT,
.codeSize = fragmentSpirvSize,
.pCode = pFragmentSpirv,
.pName = "main",
.setLayoutCount = 1,
.pSetLayouts = &descriptorSetLayout;
.pushConstantRangeCount = 0,
.pPushConstantRanges = NULL,
.pSpecializationInfo = NULL
}
};
VkResult result;
VkShaderEXT shaders[2];
result = vkCreateShadersEXT(device, 2, &shaderCreateInfos, NULL, shaders);
if (result != VK_SUCCESS)
{
// Handle error
}
Later, during command buffer recording, bind the linked shaders and draw.
// Command buffer in the recording state
VkCommandBuffer commandBuffer;
// Vertex and fragment shader objects created above
VkShaderEXT shaders[2];
// Assume vertex buffers, descriptor sets, etc. have been bound, and existing
// state setting commands have been called to set all required state
const VkShaderStageFlagBits stages[2] =
{
VK_SHADER_STAGE_VERTEX_BIT,
VK_SHADER_STAGE_FRAGMENT_BIT
};
// Bind linked shaders
vkCmdBindShadersEXT(commandBuffer, 2, stages, shaders);
// Equivalent to the previous line. Linked shaders can be bound one at a time,
// in any order:
// vkCmdBindShadersEXT(commandBuffer, 1, &stages[1], &shaders[1]);
// vkCmdBindShadersEXT(commandBuffer, 1, &stages[0], &shaders[0]);
// The above is sufficient to draw if the device was created with the
// tessellationShader and geometryShader features disabled. Otherwise, since
// those stages should not execute, vkCmdBindShadersEXT() must be called at
// least once with each of their stages in pStages before drawing:
const VkShaderStageFlagBits unusedStages[3] =
{
VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT,
VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT,
VK_SHADER_STAGE_GEOMETRY_BIT
};
// NULL pShaders is equivalent to an array of stageCount VK_NULL_HANDLE values,
// meaning no shaders are bound to those stages, and that any previously bound
// shaders are unbound
vkCmdBindShadersEXT(commandBuffer, 3, unusedStages, NULL);
// Graphics shader objects may only be used to draw inside dynamic render pass
// instances begun with vkCmdBeginRendering(), assume one has already been begun
// Draw a triangle
vkCmdDraw(commandBuffer, 3, 1, 0, 0);
Example 2
Create unlinked vertex, geometry, and fragment shaders.
// Logical device created with the shaderObject feature enabled
VkDevice device;
// SPIR-V shader code for vertex shaders, along with their sizes in bytes
void* pVertexSpirv[2];
size_t vertexSpirvSize[2];
// SPIR-V shader code for a geometry shader, along with its size in bytes
void pGeometrySpirv;
size_t geometrySpirvSize;
// SPIR-V shader code for fragment shaders, along with their sizes in bytes
void* pFragmentSpirv[2];
size_t fragmentSpirvSize[2];
// Descriptor set layout compatible with the shaders
VkDescriptorSetLayout descriptorSetLayout;
VkShaderCreateInfoEXT shaderCreateInfos[5] =
{
// Stage order does not matter
{
.sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT,
.pNext = NULL,
.flags = 0,
.stage = VK_SHADER_STAGE_GEOMETRY_BIT,
.nextStage = VK_SHADER_STAGE_FRAGMENT_BIT,
.codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT,
.codeSize = pGeometrySpirv,
.pCode = geometrySpirvSize,
.pName = "main",
.setLayoutCount = 1,
.pSetLayouts = &descriptorSetLayout;
.pushConstantRangeCount = 0,
.pPushConstantRanges = NULL,
.pSpecializationInfo = NULL
},
{
.sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT,
.pNext = NULL,
.flags = 0,
.stage = VK_SHADER_STAGE_VERTEX_BIT,
.nextStage = VK_SHADER_STAGE_GEOMETRY_BIT,
.codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT,
.codeSize = vertexSpirvSize[0],
.pCode = pVertexSpirv[0],
.pName = "main",
.setLayoutCount = 1,
.pSetLayouts = &descriptorSetLayout;
.pushConstantRangeCount = 0,
.pPushConstantRanges = NULL,
.pSpecializationInfo = NULL
},
{
.sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT,
.pNext = NULL,
.flags = 0,
.stage = VK_SHADER_STAGE_FRAGMENT_BIT,
.nextStage = 0,
.codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT,
.codeSize = fragmentSpirvSize[0],
.pCode = pFragmentSpirv[0],
.pName = "main",
.setLayoutCount = 1,
.pSetLayouts = &descriptorSetLayout;
.pushConstantRangeCount = 0,
.pPushConstantRanges = NULL,
.pSpecializationInfo = NULL
},
{
.sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT,
.pNext = NULL,
.flags = 0,
.stage = VK_SHADER_STAGE_FRAGMENT_BIT,
.nextStage = 0,
.codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT,
.codeSize = fragmentSpirvSize[1],
.pCode = pFragmentSpirv[1],
.pName = "main",
.setLayoutCount = 1,
.pSetLayouts = &descriptorSetLayout;
.pushConstantRangeCount = 0,
.pPushConstantRanges = NULL,
.pSpecializationInfo = NULL
},
{
.sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT,
.pNext = NULL,
.flags = 0,
.stage = VK_SHADER_STAGE_VERTEX_BIT,
// Suppose we want this vertex shader to be able to be followed by
// either a geometry shader or fragment shader:
.nextStage = VK_SHADER_STAGE_GEOMETRY_BIT | VK_SHADER_STAGE_FRAGMENT_BIT,
.codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT,
.codeSize = vertexSpirvSize[1],
.pCode = pVertexSpirv[1],
.pName = "main",
.setLayoutCount = 1,
.pSetLayouts = &descriptorSetLayout;
.pushConstantRangeCount = 0,
.pPushConstantRanges = NULL,
.pSpecializationInfo = NULL
}
};
VkResult result;
VkShaderEXT shaders[5];
result = vkCreateShadersEXT(device, 5, &shaderCreateInfos, NULL, shaders);
if (result != VK_SUCCESS)
{
// Handle error
}
Later, during command buffer recording, bind the linked shaders in different combinations and draw.
// Command buffer in the recording state
VkCommandBuffer commandBuffer;
// Vertex, geometry, and fragment shader objects created above
VkShaderEXT shaders[5];
// Assume vertex buffers, descriptor sets, etc. have been bound, and existing
// state setting commands have been called to set all required state
const VkShaderStageFlagBits stages[3] =
{
// Any order is allowed
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_STAGE_VERTEX_BIT,
VK_SHADER_STAGE_GEOMETRY_BIT,
};
VkShaderEXT bindShaders[3] =
{
shaders[2], // FS
shaders[1], // VS
shaders[0] // GS
};
// Bind unlinked shaders
vkCmdBindShadersEXT(commandBuffer, 3, stages, bindShaders);
// Assume the tessellationShader feature is disabled, so vkCmdBindShadersEXT()
// need not have been called with either tessellation stage
// Graphics shader objects may only be used to draw inside dynamic render pass
// instances begun with vkCmdBeginRendering(), assume one has already been begun
// Draw a triangle
vkCmdDraw(commandBuffer, 3, 1, 0, 0);
// Bind a different unlinked fragment shader
const VkShaderStageFlagBits fragmentStage = VK_SHADER_STAGE_FRAGMENT_BIT;
vkCmdBindShadersEXT(commandBuffer, 1, &fragmentStage, &shaders[3]);
// Draw another triangle
vkCmdDraw(commandBuffer, 3, 1, 0, 0);
// Bind a different unlinked vertex shader
const VkShaderStageFlagBits vertexStage = VK_SHADER_STAGE_VERTEX_BIT;
vkCmdBindShadersEXT(commandBuffer, 1, &vertexStage, &shaders[4]);
// Draw another triangle
vkCmdDraw(commandBuffer, 3, 1, 0, 0);
VK_EXT_shader_replicated_composites
- Name String
-
VK_EXT_shader_replicated_composites - Extension Type
-
Device extension
- Registered Extension Number
-
565
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Kevin Petit [GitHub]kpet
-
- Extension Proposal
- Last Modified Date
-
2024-02-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Kévin Petit, Arm Ltd.
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
This extension adds support for creating composites from a single value in SPIR-V modules, as defined by SPV_EXT_replicated_composites.
New Enum Constants
-
VK_EXT_SHADER_REPLICATED_COMPOSITES_EXTENSION_NAME -
VK_EXT_SHADER_REPLICATED_COMPOSITES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_REPLICATED_COMPOSITES_FEATURES_EXT
-
VK_EXT_shader_stencil_export
- Name String
-
VK_EXT_shader_stencil_export - Extension Type
-
Device extension
- Registered Extension Number
-
141
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Dominik Witczak [GitHub]dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2017-07-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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.
VK_EXT_shader_tile_image
- Name String
-
VK_EXT_shader_tile_image - Extension Type
-
Device extension
- Registered Extension Number
-
396
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Jan-Harald Fredriksen [GitHub]janharaldfredriksen-arm
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-03-23
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_EXT_shader_tile_image
-
- Contributors
-
-
Sandeep Kakarlapudi, Arm
-
Jan-Harald Fredriksen, Arm
-
James Fitzpatrick, Imagination
-
Andrew Garrard, Imagination
-
Jeff Leger, Qualcomm
-
Huilong Wang, Huawei
-
Graeme Leese, Broadcom
-
Hans-Kristian Arntzen, Valve
-
Tobias Hector, AMD
-
Jeff Bolz, NVIDIA
-
Shahbaz Youssefi, Google
-
Description
This extension allows fragment shader invocations to read color, depth and stencil values at their pixel location in rasterization order. The functionality is only available when using dynamic render passes introduced by VK_KHR_dynamic_rendering. Example use cases are programmable blending and deferred shading.
See fragment shader tile image reads for more information.
New Enum Constants
-
VK_EXT_SHADER_TILE_IMAGE_EXTENSION_NAME -
VK_EXT_SHADER_TILE_IMAGE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TILE_IMAGE_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TILE_IMAGE_PROPERTIES_EXT
-
Examples
Color read example.
layout( location = 0 /* aliased to color attachment 0 */ ) tileImageEXT highp attachmentEXT color0;
layout( location = 1 /* aliased to color attachment 1 */ ) tileImageEXT highp attachmentEXT color1;
layout( location = 0 ) out vec4 fragColor;
void main()
{
vec4 value = colorAttachmentReadEXT(color0) + colorAttachmentReadEXT(color1);
fragColor = value;
}
Depth & Stencil read example.
void main()
{
// read sample 0: works for non-MSAA or MSAA targets
highp float last_depth = depthAttachmentReadEXT();
lowp uint last_stencil = stencilAttachmentReadEXT();
//..
}
VK_EXT_subpass_merge_feedback
- Name String
-
VK_EXT_subpass_merge_feedback - Extension Type
-
Device extension
- Registered Extension Number
-
459
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Ting Wei [GitHub]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
-
VK_EXT_swapchain_colorspace
- Name String
-
VK_EXT_swapchain_colorspace - Extension Type
-
Instance extension
- Registered Extension Number
-
105
- Revision
-
5
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Courtney Goeltzenleuchter [GitHub]courtney-g
-
Other Extension Metadata
- Last Modified Date
-
2019-04-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, Google
-
Description
This extension expands VkColorSpaceKHR to add support for most
standard color spaces beyond VK_COLOR_SPACE_SRGB_NONLINEAR_KHR.
This extension also adds support for VK_COLOR_SPACE_PASS_THROUGH_EXT
which allows applications to use color spaces not explicitly enumerated in
VkColorSpaceKHR.
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 color spaces. 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 color space?
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 color space transfer function usage.
-
Refer to normative definitions in the Data Format Specification.
-
Clarify DCI-P3 and Display P3 usage.
-
-
Revision 5, 2024-03-16 (Zehui Lin)
-
Fix interchanged concepts of EOTF and OETF.
-
Clarify that the presentation engine can accept the color spaces.
-
VK_EXT_transform_feedback
- Name String
-
VK_EXT_transform_feedback - Extension Type
-
Device extension
- Registered Extension Number
-
29
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Special Uses
- Contact
-
-
Piers Daniell [GitHub]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
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Cort Stratton [GitHub]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 structure 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_vertex_input_dynamic_state
- Name String
-
VK_EXT_vertex_input_dynamic_state - Extension Type
-
Device extension
- Registered Extension Number
-
353
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Piers Daniell [GitHub]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 structure 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Piers Daniell [GitHub]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_EXT_zero_initialize_device_memory
- Name String
-
VK_EXT_zero_initialize_device_memory - Extension Type
-
Device extension
- Registered Extension Number
-
621
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Contact
-
-
Mike Blumenkrantz [GitHub]zmike
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-04-09
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1.
-
Interacts with
VK_KHR_get_physical_device_properties2.
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Hans-Kristian Arntzen, VALVE
-
Mike Blumenkrantz, VALVE
-
Tobias Hector, AMD
-
Faith Ekstrand, Collabora
-
Ricardo Garcia, Igalia
-
Jan-Harald Fredriksen, ARM
-
Spencer Fricke, LunarG
-
Description
By default, Vulkan provides no guarantees that device memory allocated through vkAllocateMemory is cleared to zero. This means that applications wanting resources to be zero-initialized must execute a command such as vkCmdFillBuffer or vkCmdClearColorImage on the device to ensure a deterministic result. This can be wasteful if the underlying platform either:
-
Already performs that zero clear anyway, due to e.g. security concerns.
-
Can be performed more efficiently in implementation, by e.g. clearing pages to zero in the background after device memory is freed.
This extension also has uses in API layering and porting efforts, where zero memory behavior may be more strict than Vulkan. Different OS platforms also have wildly different behaviors here, which leads to implementations needing to apply workarounds to paper over these issues in the wild. If an extension exists to make allocation behavior explicit, we hopefully achieve a more robust ecosystem for Vulkan.
New Enum Constants
-
VK_EXT_ZERO_INITIALIZE_DEVICE_MEMORY_EXTENSION_NAME -
VK_EXT_ZERO_INITIALIZE_DEVICE_MEMORY_SPEC_VERSION -
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT
-
-
Extending VkMemoryAllocateFlagBits:
-
VK_MEMORY_ALLOCATE_ZERO_INITIALIZE_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_DEVICE_MEMORY_FEATURES_EXT
-
VK_AMD_anti_lag
- Name String
-
VK_AMD_anti_lag - Extension Type
-
Device extension
- Registered Extension Number
-
477
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Stu Smith
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-06-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Tobias Hector, AMD
-
Stuart Smith, AMD
-
Arkadiusz Sarwa, AMD
-
Description
This extension automatically paces the CPU to make sure it does not get too far ahead of the GPU, reducing the latency between inputs received and updates on the screen. Additionally, Anti-Lag+ offers applications the ability to inform the driver when input processing begins, in order to align the timing of display updates, enabling even lower latency between receiving input and displaying on the screen.
New Enum Constants
-
VK_AMD_ANTI_LAG_EXTENSION_NAME -
VK_AMD_ANTI_LAG_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ANTI_LAG_DATA_AMD -
VK_STRUCTURE_TYPE_ANTI_LAG_PRESENTATION_INFO_AMD -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ANTI_LAG_FEATURES_AMD
-
VK_AMD_buffer_marker
- Name String
-
VK_AMD_buffer_marker - Extension Type
-
Device extension
- Registered Extension Number
-
180
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_synchronization2
-
- Special Use
- Contact
-
-
Daniel Rakos [GitHub]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.
New Commands
If Vulkan Version 1.3 or VK_KHR_synchronization2 is supported:
VK_AMD_device_coherent_memory
- Name String
-
VK_AMD_device_coherent_memory - Extension Type
-
Device extension
- Registered Extension Number
-
230
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Tobias Hector [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Matthaeus G. Chajdas [GitHub]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 color space. 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Dominik Witczak [GitHub]dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2016-05-30
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Martin Dinkov [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_dynamic_rendering
-
- Contact
-
-
Matthaeus G. Chajdas [GitHub]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 Structures
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
New Enum Constants
-
VK_AMD_MIXED_ATTACHMENT_SAMPLES_EXTENSION_NAME -
VK_AMD_MIXED_ATTACHMENT_SAMPLES_SPEC_VERSION
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_AMD
-
VK_AMD_pipeline_compiler_control
- Name String
-
VK_AMD_pipeline_compiler_control - Extension Type
-
Device extension
- Registered Extension Number
-
184
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Matthaeus G. Chajdas [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Daniel Rakos [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Dominik Witczak [GitHub]dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2016-09-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Martin Dinkov [GitHub]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;
VK_AMD_shader_core_properties2
- Name String
-
VK_AMD_shader_core_properties2 - Extension Type
-
Device extension
- Registered Extension Number
-
228
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Matthaeus G. Chajdas [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Tobias Hector [GitHub]tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-09-14
- Interactions and External Dependencies
-
-
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 the VK_EXT_shader_stencil_export extension 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Qun Lin [GitHub]linqun
-
Other Extension Metadata
- Last Modified Date
-
2016-05-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
-
VK_AMD_shader_fragment_mask
- Name String
-
VK_AMD_shader_fragment_mask - Extension Type
-
Device extension
- Registered Extension Number
-
138
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Aaron Hagan [GitHub]AaronHaganAMD
-
Other Extension Metadata
- Last Modified Date
-
2017-08-16
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Dominik Witczak [GitHub]dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2017-08-21
- Interactions and External Dependencies
-
-
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
-
VK_AMD_shader_info
- Name String
-
VK_AMD_shader_info - Extension Type
-
Device extension
- Registered Extension Number
-
43
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Special Use
- Contact
-
-
Jaakko Konttinen [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Qun Lin [GitHub]linqun
-
Other Extension Metadata
- Last Modified Date
-
2016-05-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
-
VK_AMD_texture_gather_bias_lod
- Name String
-
VK_AMD_texture_gather_bias_lod - Extension Type
-
Device extension
- Registered Extension Number
-
42
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Rex Xu [GitHub]amdrexu
-
Other Extension Metadata
- Last Modified Date
-
2017-03-21
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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_format_resolve
- Name String
-
VK_ANDROID_external_format_resolve - Extension Type
-
Device extension
- Registered Extension Number
-
469
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_dynamic_rendering
-
- Special Use
- Contact
-
-
Chris Forbes [GitHub]chrisforbes
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-05-03
- IP Status
-
No known IP claims.
- Contributors
-
-
Tobias Hector, AMD
-
Chris Forbes, Google
-
Jan-Harald Fredriksen, Arm
-
Shahbaz Youssefi, Google
-
Matthew Netsch, Qualcomm
-
Tony Zlatsinki, Nvidia
-
Daniel Koch, Nvidia
-
Jeff Leger, Qualcomm
-
Alex Walters, Imagination
-
Andrew Garrard, Imagination
-
Ralph Potter, Samsung
-
Ian Elliott, Google
-
Description
This extension enables rendering to Android Hardware Buffers with external formats which cannot be directly represented as renderable in Vulkan, including Y′CBCR formats.
New Structures
-
Extending VkAndroidHardwareBufferPropertiesANDROID:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
New Enum Constants
-
VK_ANDROID_EXTERNAL_FORMAT_RESOLVE_EXTENSION_NAME -
VK_ANDROID_EXTERNAL_FORMAT_RESOLVE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_RESOLVE_PROPERTIES_ANDROID -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FORMAT_RESOLVE_FEATURES_ANDROID -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FORMAT_RESOLVE_PROPERTIES_ANDROID
-
If VK_KHR_dynamic_rendering or Vulkan Version 1.3 is supported:
-
Extending VkResolveModeFlagBits:
-
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID -
VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_BIT_ANDROID
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_format_feature_flags2
-
- Contact
-
-
Jesse Hall [GitHub]critsec
-
Other Extension Metadata
- Last Modified Date
-
2021-09-30
- IP Status
-
No known IP claims.
- Contributors
-
-
Ray Smith, ARM
-
Lina 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 Structures
-
Extending VkAndroidHardwareBufferPropertiesANDROID:
-
Extending VkImageCreateInfo, VkSamplerYcbcrConversionCreateInfo, VkAttachmentDescription2, VkGraphicsPipelineCreateInfo, VkCommandBufferInheritanceInfo:
-
Extending VkImageFormatProperties2:
-
Extending VkMemoryAllocateInfo:
If VK_KHR_format_feature_flags2 or Vulkan Version 1.3 is supported:
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 or Vulkan Version 1.3 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_data_graph
- Name String
-
VK_ARM_data_graph - Extension Type
-
Device extension
- Registered Extension Number
-
508
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_ARM_tensors
-
- SPIR-V Dependencies
- Contact
-
-
Kevin Petit [GitHub]kpet
-
Other Extension Metadata
- Last Modified Date
-
2025-06-18
- Interactions and External Dependencies
-
-
This extension requires
SPV_ARM_graph -
This extension interacts with
VK_EXT_mutable_descriptor_type -
This extension interacts with
VK_EXT_pipeline_protected_access -
This extension interacts with
VK_ARM_tensors -
This extension interacts with
VK_EXT_descriptor_buffer -
This extension interacts with
VK_KHR_maintenance6
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Kévin Petit, Arm Ltd.
-
Emma Ben Yossef, Arm Ltd.
-
Stefano Bucciarelli, Arm Ltd.
-
Marco Cattani, Arm Ltd.
-
Aaron DeBattista, Arm Ltd.
-
Jan-Harald Fredriksen, Arm Ltd.
-
Einar Hov, Arm Ltd.
-
Robert Hughes, Arm Ltd.
-
Oualid Khelifi, Arm Ltd.
-
Derek Lamberti, Arm Ltd.
-
Chetan Mistry, Arm Ltd.
-
Georgios Teneketzis, Arm Ltd.
-
Description
This extension adds support for a new type of pipeline, data graph pipelines, that provide an encapsulation construct for computational graphs operating on full resources (e.g. ML/AI graphs, image processing pipelines, etc). This extension only supports tensor resources and does not define any operations that can be used within those graphs. These operations will be defined by separate extensions.
New Structures
-
Extending VkDataGraphPipelineCreateInfoARM:
-
Extending VkDataGraphPipelineCreateInfoARM, VkDescriptorPoolCreateInfo, VkCommandPoolCreateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
If VK_ARM_tensors is supported:
New Enum Constants
-
VK_ARM_DATA_GRAPH_EXTENSION_NAME -
VK_ARM_DATA_GRAPH_SPEC_VERSION -
VK_MAX_PHYSICAL_DEVICE_DATA_GRAPH_OPERATION_SET_NAME_SIZE_ARM -
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_DATA_GRAPH_READ_BIT_ARM -
VK_ACCESS_2_DATA_GRAPH_WRITE_BIT_ARM
-
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_DATA_GRAPH_FOREIGN_DESCRIPTOR_BIT_ARM
-
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_TENSOR_DATA_GRAPH_BIT_ARM
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_DATA_GRAPH_PIPELINE_SESSION_ARM
-
-
Extending VkPipelineBindPoint:
-
VK_PIPELINE_BIND_POINT_DATA_GRAPH_ARM
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_DATA_GRAPH_BIT_ARM
-
-
Extending VkQueueFlagBits:
-
VK_QUEUE_DATA_GRAPH_BIT_ARM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BIND_DATA_GRAPH_PIPELINE_SESSION_MEMORY_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_COMPILER_CONTROL_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_CONSTANT_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_DISPATCH_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_IDENTIFIER_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_PROPERTY_QUERY_RESULT_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_RESOURCE_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SESSION_BIND_POINT_REQUIREMENTS_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SESSION_BIND_POINT_REQUIREMENT_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SESSION_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SESSION_MEMORY_REQUIREMENTS_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_SHADER_MODULE_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_DATA_GRAPH_PROCESSING_ENGINE_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DATA_GRAPH_FEATURES_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_QUEUE_FAMILY_DATA_GRAPH_PROCESSING_ENGINE_INFO_ARM -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_DATA_GRAPH_PROCESSING_ENGINE_PROPERTIES_ARM -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_DATA_GRAPH_PROPERTIES_ARM
-
-
Extending VkTensorUsageFlagBitsARM:
-
VK_TENSOR_USAGE_DATA_GRAPH_BIT_ARM
-
If VK_ARM_tensors is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DATA_GRAPH_PIPELINE_CONSTANT_TENSOR_SEMI_STRUCTURED_SPARSITY_INFO_ARM
-
Issues
1) Should graph pipeline resource info structures be integrated into pipeline layouts? Would a new graph pipeline layout be a better fit?
RESOLVED: Graph pipeline resource info are passed separately at pipeline creation time.
2) Do we need a new shader stage for graph pipelines for use in creating descriptor set layouts?
RESOLVED: Currently using VK_SHADER_STAGE_ALL.
3) Should this extension provide applications with a way of knowing which combinations of sparsity information implementations can take advantage of when processing graph constants?
RESOLVED: No. Describing the exact combinations is in some cases complex and it is always valid for implementations to ignore the sparsity information and treat the data as dense. Specific implementations can provide guidance to application writers if they so desire and applications are encouraged to always provide sparsity information that they have.
VK_ARM_format_pack
- Name String
-
VK_ARM_format_pack - Extension Type
-
Device extension
- Registered Extension Number
-
610
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Jan-Harald Fredriksen [GitHub]janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2025-03-24
- Interactions and External Dependencies
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Lisa Wu, Arm
-
Oivind Boge, Arm
-
Description
This extension adds support for additional 1-, 2- and 4-component formats with 10, 12, or 14 bits of components in 16-bit containers.
New Enum Constants
-
VK_ARM_FORMAT_PACK_EXTENSION_NAME -
VK_ARM_FORMAT_PACK_SPEC_VERSION -
Extending VkFormat:
-
VK_FORMAT_G14X2_B14X2R14X2_2PLANE_420_UNORM_3PACK16_ARM -
VK_FORMAT_G14X2_B14X2R14X2_2PLANE_422_UNORM_3PACK16_ARM -
VK_FORMAT_R10X6G10X6B10X6A10X6_UINT_4PACK16_ARM -
VK_FORMAT_R10X6G10X6_UINT_2PACK16_ARM -
VK_FORMAT_R10X6_UINT_PACK16_ARM -
VK_FORMAT_R12X4G12X4B12X4A12X4_UINT_4PACK16_ARM -
VK_FORMAT_R12X4G12X4_UINT_2PACK16_ARM -
VK_FORMAT_R12X4_UINT_PACK16_ARM -
VK_FORMAT_R14X2G14X2B14X2A14X2_UINT_4PACK16_ARM -
VK_FORMAT_R14X2G14X2B14X2A14X2_UNORM_4PACK16_ARM -
VK_FORMAT_R14X2G14X2_UINT_2PACK16_ARM -
VK_FORMAT_R14X2G14X2_UNORM_2PACK16_ARM -
VK_FORMAT_R14X2_UINT_PACK16_ARM -
VK_FORMAT_R14X2_UNORM_PACK16_ARM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FORMAT_PACK_FEATURES_ARM
-
Issues
What do we call this extension?
RESOLVED
Many existing extension have the format in the name, but in this case we want to expose multiple formats.
We will describe this set of formats as a "pack".
Compatibility classes
- RESOLVED
-
Should these additional formats be in the same compatibility class as any other formats? For single-plane formats, we put formats with the same number of bits (but different types) in the same class. Each multi-plane or subsampled format gets its own compatibility class. This is consistent with how existing formats are handled.
Format feature requirements
- RESOLVED
-
The format feature queries could be used to determine what is supported on any given implementation, but it may be useful to establish a baseline requirement in the specification. For that purpose, we require a set of format features - sufficient to enable texture operations - to be supported for the added unsigned integer single-plane formats. Other formats and format features are optional.
VK_ARM_pipeline_opacity_micromap
- Name String
-
VK_ARM_pipeline_opacity_micromap - Extension Type
-
Device extension
- Registered Extension Number
-
597
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Mathieu Robart [GitHub]mathieurobart-arm
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-01-07
- IP Status
-
No known IP claims.
- Contributors
-
-
Mathieu Robart, Arm
-
Marius Bjorge, Arm
-
Yaozhong Zhang, Arm
-
Jan-Harald Fredriksen, Arm
-
Description
The Opacity Micromap extension VK_EXT_opacity_micromap supports the new
pipeline creation flag
VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT, indicating that
the ray tracing pipeline may be used with acceleration structures
referencing micromaps.
This allows for possible optimizations, knowing beforehand that opacity
micromaps may be used with the pipeline.
An equivalent flag does not exist for pipelines supporting Ray Query with opacity micromaps, such as graphics and compute. Consequently, it is currently not possible to optimize such pipelines for no-opacity, e.g. when opacity micromaps are supported by an application but not used by the pipeline. This may lead to performance degradation.
This extension adds a new flag,
VK_PIPELINE_CREATE_2_DISALLOW_OPACITY_MICROMAP_BIT_ARM, indicating that a
pipeline will NOT be used with an acceleration structure referencing an
opacity micromap, therefore allowing possible pipeline optimizations.
New Enum Constants
-
VK_ARM_PIPELINE_OPACITY_MICROMAP_EXTENSION_NAME -
VK_ARM_PIPELINE_OPACITY_MICROMAP_SPEC_VERSION -
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_DISALLOW_OPACITY_MICROMAP_BIT_ARM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_OPACITY_MICROMAP_FEATURES_ARM
-
VK_ARM_render_pass_striped
- Name String
-
VK_ARM_render_pass_striped - Extension Type
-
Device extension
- Registered Extension Number
-
425
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Jan-Harald Fredriksen [GitHub]janharaldfredriksen-arm
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-11-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Lisa Wu, Arm
-
Torbjorn Nilsson, Arm
-
Ying-Chieh Chen, Mediatek
-
Jim Chiu, Mediatek
-
Description
This extension adds the ability to split a render pass instance into stripes, and to get a notification when rendering has completed for each stripe.
New Structures
-
Extending VkCommandBufferSubmitInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkRenderingInfo, VkRenderPassBeginInfo:
New Enum Constants
-
VK_ARM_RENDER_PASS_STRIPED_EXTENSION_NAME -
VK_ARM_RENDER_PASS_STRIPED_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RENDER_PASS_STRIPED_FEATURES_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RENDER_PASS_STRIPED_PROPERTIES_ARM -
VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_BEGIN_INFO_ARM -
VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_INFO_ARM -
VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_SUBMIT_INFO_ARM
-
VK_ARM_scheduling_controls
- Name String
-
VK_ARM_scheduling_controls - Extension Type
-
Device extension
- Registered Extension Number
-
418
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Kevin Petit [GitHub]kpet
-
Other Extension Metadata
- Last Modified Date
-
2023-08-23
- Interactions and External Dependencies
-
None
- IP Status
-
No known IP claims.
- Contributors
-
-
Kévin Petit, Arm Ltd.
-
Jan-Harald Fredriksen, Arm Ltd.
-
Mikel Garai, Arm Ltd.
-
Description
This extension exposes a collection of controls to modify the scheduling behavior of Arm Mali devices.
New Enum Constants
-
VK_ARM_SCHEDULING_CONTROLS_EXTENSION_NAME -
VK_ARM_SCHEDULING_CONTROLS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_QUEUE_SHADER_CORE_CONTROL_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_FEATURES_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_PROPERTIES_ARM
-
VK_ARM_shader_core_builtins
- Name String
-
VK_ARM_shader_core_builtins - Extension Type
-
Device extension
- Registered Extension Number
-
498
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Kevin Petit [GitHub]kpet
-
Other Extension Metadata
- Last Modified Date
-
2022-10-05
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_ARM_shader_core_builtins
-
- Contributors
-
-
Kevin Petit, Arm Ltd.
-
Jan-Harald Fredriksen, Arm Ltd.
-
Description
This extension provides the ability to determine device-specific properties on Arm GPUs. It exposes properties for the number of shader cores, the maximum number of warps that can run on a shader core, and shader builtins to enable invocations to identify which core and warp a shader invocation is executing on.
This extension enables support for the SPIR-V CoreBuiltinsARM
capability.
These properties and built-ins can be used for debugging or performance
optimization purposes.
A typical optimization example would be to use CoreIDARM to select a
per-shader-core instance of a data structure in algorithms that use atomics
so as to reduce contention.
New Enum Constants
-
VK_ARM_SHADER_CORE_BUILTINS_EXTENSION_NAME -
VK_ARM_SHADER_CORE_BUILTINS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_BUILTINS_FEATURES_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_BUILTINS_PROPERTIES_ARM
-
VK_ARM_shader_core_properties
- Name String
-
VK_ARM_shader_core_properties - Extension Type
-
Device extension
- Registered Extension Number
-
416
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Jan-Harald Fredriksen [GitHub]janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2023-02-07
- IP Status
-
No known IP claims.
- Contributors
-
-
Jan-Harald Fredriksen, Arm Ltd.
-
Description
This extension provides the ability to determine device-specific performance properties of Arm GPUs.
It exposes properties for the number of texel, pixel, and fused multiply-add
operations per clock per shader core.
This can be used in combination with the
VK_ARM_shader_core_builtins extension that provides the ability to
query the number of shader cores on the physical device.
New Enum Constants
-
VK_ARM_SHADER_CORE_PROPERTIES_EXTENSION_NAME -
VK_ARM_SHADER_CORE_PROPERTIES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_ARM
-
VK_ARM_tensors
- Name String
-
VK_ARM_tensors - Extension Type
-
Device extension
- Registered Extension Number
-
461
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_EXT_descriptor_buffer
-
Interacts with VK_EXT_frame_boundary
-
- SPIR-V Dependencies
- Contact
-
-
Kevin Petit [GitHub]kpet
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-06-03
- Interactions and External Dependencies
-
-
This extension requires
SPV_ARM_tensors -
This extension provides API support for
GL_ARM_tensors -
This extension interacts with
VK_EXT_mutable_descriptor_type -
This extension interacts with
VK_EXT_descriptor_buffer -
This extension interacts with
VK_EXT_frame_boundary -
This extension interacts with
VK_EXT_robustness2
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Kévin Petit, Arm Ltd.
-
Einar Hov, Arm Ltd.
-
Dominic Symes, Arm Ltd.
-
Jan-Harald Fredriksen, Arm Ltd.
-
Marco Cattani, Arm Ltd.
-
Lisa Wu, Arm Ltd.
-
Robert Hughes, Arm Ltd.
-
David Garbett, Arm Ltd.
-
Oualid Khelifi, Arm Ltd.
-
New Structures
-
Extending VkDataGraphPipelineResourceInfoARM, VkDataGraphPipelineConstantARM:
-
Extending VkDependencyInfo:
-
Extending VkFormatProperties2:
-
Extending VkMemoryAllocateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkTensorCreateInfoARM:
-
Extending VkWriteDescriptorSet:
If VK_EXT_descriptor_buffer is supported:
If VK_EXT_frame_boundary is supported:
New Enum Constants
-
VK_ARM_TENSORS_EXTENSION_NAME -
VK_ARM_TENSORS_SPEC_VERSION -
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_TENSOR_ARM
-
-
Extending VkFormat:
-
VK_FORMAT_R8_BOOL_ARM
-
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_TENSOR_IMAGE_ALIASING_BIT_ARM -
VK_FORMAT_FEATURE_2_TENSOR_SHADER_BIT_ARM
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_TENSOR_ALIASING_ARM
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_TENSOR_ALIASING_BIT_ARM
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_TENSOR_ARM -
VK_OBJECT_TYPE_TENSOR_VIEW_ARM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BIND_TENSOR_MEMORY_INFO_ARM -
VK_STRUCTURE_TYPE_COPY_TENSOR_INFO_ARM -
VK_STRUCTURE_TYPE_DEVICE_TENSOR_MEMORY_REQUIREMENTS_ARM -
VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_TENSOR_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_EXTERNAL_TENSOR_PROPERTIES_ARM -
VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_TENSOR_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_TENSOR_INFO_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TENSOR_FEATURES_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TENSOR_PROPERTIES_ARM -
VK_STRUCTURE_TYPE_TENSOR_COPY_ARM -
VK_STRUCTURE_TYPE_TENSOR_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_TENSOR_DEPENDENCY_INFO_ARM -
VK_STRUCTURE_TYPE_TENSOR_DESCRIPTION_ARM -
VK_STRUCTURE_TYPE_TENSOR_FORMAT_PROPERTIES_ARM -
VK_STRUCTURE_TYPE_TENSOR_MEMORY_BARRIER_ARM -
VK_STRUCTURE_TYPE_TENSOR_MEMORY_REQUIREMENTS_INFO_ARM -
VK_STRUCTURE_TYPE_TENSOR_VIEW_CREATE_INFO_ARM -
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_TENSOR_ARM
-
If VK_EXT_descriptor_buffer is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DESCRIPTOR_GET_TENSOR_INFO_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_TENSOR_FEATURES_ARM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_TENSOR_PROPERTIES_ARM -
VK_STRUCTURE_TYPE_TENSOR_CAPTURE_DESCRIPTOR_DATA_INFO_ARM -
VK_STRUCTURE_TYPE_TENSOR_VIEW_CAPTURE_DESCRIPTOR_DATA_INFO_ARM
-
-
Extending VkTensorCreateFlagBitsARM:
-
VK_TENSOR_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_ARM
-
-
Extending VkTensorViewCreateFlagBitsARM:
-
VK_TENSOR_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_ARM
-
If VK_EXT_frame_boundary is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FRAME_BOUNDARY_TENSORS_ARM
-
Issues
1) Should tensor strides be passed in elements or in bytes?
RESOLVED: Strides are passed in bytes but are required to be a multiple of the tensor element size. Passing strides in bytes makes it possible to relax this requirement in the future without an interface change. It also makes it easier to describe memory alignment requirements.
2) Should there be commands to copy data between tensors and buffers/images?
RESOLVED: Adding these commands would result in a rather large API surface and not insignificant implementation and validation cost. The same outcome can be achieved with memory aliasing and tensor to tensor copy operations.
3) Should this extension define transpose and/or other data reorganization operations?
RESOLVED: These operations are useful to expose but this extension is only meant to add base support for tensors. Additional operations should be layered on top and defined in other extensions.
4) Why are tensor strides described using signed integers?
RESOLVED: Negative strides make it possible to describe different linear data layouts. While this extension does not allow negative strides, it uses signed integers for strides to make it possible to relax this limitation in future extensions.
VK_FUCHSIA_buffer_collection
- Name String
-
VK_FUCHSIA_buffer_collection - Extension Type
-
Device extension
- Registered Extension Number
-
367
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_EXT_debug_report
-
- Contact
-
-
John Rosasco [GitHub]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 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
-
If VK_EXT_debug_report is supported:
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_COLLECTION_FUCHSIA_EXT
-
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.
VK_FUCHSIA_external_memory
- Name String
-
VK_FUCHSIA_external_memory - Extension Type
-
Device extension
- Registered Extension Number
-
365
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
John Rosasco [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
John Rosasco [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Craig Stout [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Jean-Francois Roy [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Jean-Francois Roy [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Hai Nguyen [GitHub]chaoticbob
-
Other Extension Metadata
- Last Modified Date
-
2018-07-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Hai Nguyen, Google
-
Neil Henning, AMD
-
VK_GOOGLE_display_timing
- Name String
-
VK_GOOGLE_display_timing - Extension Type
-
Device extension
- Registered Extension Number
-
93
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Ian Elliott [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Hai Nguyen [GitHub]chaoticbob
-
Other Extension Metadata
- Last Modified Date
-
2018-07-09
- IP Status
-
No known IP claims.
- 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.
VK_GOOGLE_surfaceless_query
- Name String
-
VK_GOOGLE_surfaceless_query - Extension Type
-
Instance extension
- Registered Extension Number
-
434
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-08-03
- 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, color spaces and present modes to be queried without
providing a surface.
Identically, vkGetPhysicalDeviceSurfaceFormats2KHR,
vkGetPhysicalDeviceSurfacePresentModes2EXT, and
vkGetPhysicalDeviceSurfaceCapabilities2KHR 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.
VK_GOOGLE_user_type
- Name String
-
VK_GOOGLE_user_type - Extension Type
-
Device extension
- Registered Extension Number
-
290
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Kaye Mason [GitHub]chaleur
-
Other Extension Metadata
- Last Modified Date
-
2019-07-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Kaye Mason, Google
-
Hai Nguyen, Google
-
VK_HUAWEI_cluster_culling_shader
- Name String
-
VK_HUAWEI_cluster_culling_shader - Extension Type
-
Device extension
- Registered Extension Number
-
405
- Revision
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Yuchang Wang [GitHub]richard_Wang2
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-08-16
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_HUAWEI_cluster_culling_shader.
-
- Contributors
-
-
Yuchang Wang, Huawei
-
Juntao Li, Huawei
-
Pan Gao, Huawei
-
Jie Cao, Huawei
-
Yunjin Zhang, Huawei
-
Shujie Zhou, Huawei
-
Chaojun Wang, Huawei
-
Jiajun Hu, Huawei
-
Cong Zhang, Huawei
-
Description
Cluster Culling Shaders (CCS) are similar to the existing compute shaders. Their main purpose is to provide an execution environment in order to perform coarse-level geometry culling and LOD selection more efficiently on the GPU.
The traditional 2-pass GPU culling solution using a compute shader sometimes needs a pipeline barrier between compute and graphics pipeline to optimize performance. An additional compaction process may also be required. This extension addresses these shortcomings, allowing compute shaders to directly emit visible clusters to the following graphics pipeline.
A set of new built-in output variables are used to express a visible cluster, including per-cluster shading rate. In addition, a new built-in function is used to emit these variables from CCS to the IA stage. The IA stage can use these variables to fetch vertices of a visible cluster and drive vertex shaders to shading these vertices.
Note that CCS do not work with geometry or tessellation shaders, but both IA and vertex shaders are preserved. Vertex shaders are still used for vertex position shading, instead of directly outputting transformed vertices from the compute shader. This makes CCS more suitable for mobile GPUs.
New Structures
-
Extending VkPhysicalDeviceClusterCullingShaderFeaturesHUAWEI:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
New Enum Constants
-
VK_HUAWEI_CLUSTER_CULLING_SHADER_EXTENSION_NAME -
VK_HUAWEI_CLUSTER_CULLING_SHADER_SPEC_VERSION -
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI
-
-
Extending VkQueryPipelineStatisticFlagBits:
-
VK_QUERY_PIPELINE_STATISTIC_CLUSTER_CULLING_SHADER_INVOCATIONS_BIT_HUAWEI
-
-
Extending VkShaderStageFlagBits:
-
VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_FEATURES_HUAWEI -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_PROPERTIES_HUAWEI -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_VRS_FEATURES_HUAWEI
-
Sample Code
Example of cluster culling in a GLSL shader
#extension GL_HUAWEI_cluster_culling_shader: enable
#define GPU_WARP_SIZE 32
#define GPU_GROUP_SIZE GPU_WARP_SIZE
#define GPU_CLUSTER_PER_INVOCATION 1
#define GPU_CLUSTER_PER_WORKGROUP (GPU_GROUP_SIZE * GPU_CLUSTER_PER_INVOCATION)
// Number of threads per workgroup
// - 1D only
// - warpsize = 32
layout(local_size_x=GPU_GROUP_SIZE, local_size_y=1, local_size_z=1) in;
#define GPU_DRAW_BUFFER_BINDING 0
#define GPU_INSTANCE_DESCRIPTOR_BINDING 1
struct BoundingSphere
{
vec3 center;
float radius;
};
struct InstanceData
{
mat4 mvp_matrix; // mvp matrix.
vec4 frustum_planes[6]; // six frustum planes
mat4 model_matrix_transpose_inverse; // inverse transpose of model matrix.
vec3 view_origin; // view original
};
struct InstanceDescriptor
{
uint begin;
uint end;
uint cluster_count;
uint debug;
BoundingSphere sphere;
InstanceData instance_data;
};
struct DrawElementsCommand{
uint indexcount;
uint instanceCount;
uint firstIndex;
int vertexoffset;
uint firstInstance;
uint cluster_id;
};
// indexed mode
out gl_PerClusterHUAWEI{
uint gl_IndexCountHUAWEI;
uint gl_InstanceCountHUAWEI;
uint gl_FirstIndexHUAWEI;
int gl_VertexOffsetHUAWEI;
uint gl_FirstInstanceHUAWEI;
uint gl_ClusterIDHUAWEI;
uint gl_ClusterShadingRateHUAWEI;
};
layout(binding = GPU_DRAW_BUFFER_BINDING, std430) buffer draw_indirect_ssbo
{
DrawElementsCommand draw_commands[];
};
layout(binding = GPU_INSTANCE_DESCRIPTOR_BINDING, std430) buffer instance_descriptor_ssbo
{
InstanceDescriptor instance_descriptors[];
};
float Distance(uint instance_id)
{
vec3 v = normalize(instance_descriptor[instance_id].sphere.center -
instance_descriptor[instance_id].instance_data.view_origin);
float dist = sqrt(dot(v,v));
return dist;
}
bool isSphereOutsideFrustum( vec3 sphere_center, float sphere_radius )
{
bool isInside = false;
for(int i = 0; i < 6; i++)
{
isInside = isInside ||
(dot(instance_descriptors[instance_id].instance_data.frustum_planes[i].xyz,
sphere_center) + instance_descriptors[instance_id].instance_data.frustum_planes[i].w <
sphere_radius);
}
return isInside;
}
void main()
{
// get instance description
instance_id = gl_GlobalInvocationID.x;
InstanceDescriptor inst_desc = instance_descriptors[instance_id];
//instance based culling
bool render = !isSphereOutsideFrustum(inst_desc.sphere.center, inst_desc.sphere.radius);
if (render)
{
// calculate distance
float distance = Distance(instance_id);
// update shading rate built-in variable
if(distance > 0.7)
gl_ClusterShadingRateHUAWEI =
gl_ShadingRateFlag4VerticalPixelsEXT | gl_ShadingRateFlag4HorizontalPixelsEXT;
else if(distance > 0.3)
gl_ClusterShadingRateHUAWEI =
gl_ShadingRateFlag2VerticalPixelsEXT | gl_ShadingRateFlag2HorizontalPixelsEXT;
else
gl_ClusterShadingRateHUAWEI = 0;
// this is a visible cluster, update built-in output variable.
// in case of indexed mode:
gl_IndexCountHUAWEI = draw_commands[cluster_id].indexcount;
gl_InstanceCountHUAWEI = draw_commands[cluster_id].instanceCount;
gl_FirstIndexHUAWEI = draw_commands[cluster_id].firstIndex;
gl_VertexOffsetHUAWEI = draw_commands[cluster_id].vertexoffset;
gl_FirstInstanceHUAWEI = draw_commands[cluster_id].firstInstance;
gl_ClusterIDHUAWEI = draw_commands[cluster_id].cluster_id;
// emit built-in output variables as a drawing command to subsequent
// rendering pipeline.
dispatchClusterHUAWEI();
}
}
Example of graphics pipeline creation with cluster culling shader
// create a cluster culling shader stage info structure.
VkPipelineShaderStageCreateInfo ccsStageInfo{};
ccsStageInfo.sType = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO;
ccsStageInfo.stage = VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI;
ccsStageInfo.module = clustercullingshaderModule;
ccsStageInfo.pName = "main";
// pipeline shader stage creation
VkPipelineShaderStageCreateInfo shaderStages[] = { ccsStageInfo, vertexShaderStageInfo, fragmentShaderStageInfo };
// create graphics pipeline
VkGraphicsPipelineCreateInfo pipelineInfo{};
pipelineInfo.sType = VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO;
pipelineInfo.stageCount = 3;
pipelineInfo.pStage = shaderStages;
pipelineInfo.pVertexInputState = &vertexInputInfo;
// ...
VkPipeline graphicsPipeline;
VkCreateGraphicsPipelines(device, VK_NULL_HANDLE, 1, &pipelineInfo, nullptr, &graphicsPipeline);
Example of launching the execution of cluster culling shader
vkCmdBindPipeline(commandBuffer, VK_PIPELINE_BIND_POINT_GRAPHICS, graphicsPipeline);
vkCmdDrawClusterHUAWEI(commandBuffer, groupCountX, 1, 1);
vkCmdEndRenderPass(commandBuffer);
VK_HUAWEI_hdr_vivid
- Name String
-
VK_HUAWEI_hdr_vivid - Extension Type
-
Device extension
- Registered Extension Number
-
591
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Zehui Lin [GitHub]bactlink
-
Other Extension Metadata
- Last Modified Date
-
2024-10-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Juntao Li, Huawei
-
Pan Gao, Huawei
-
Xiufeng Zhang, Huawei
-
Zehui Lin, Huawei
-
Description
This extension allows applications to assign HDR Vivid (T/UWA 005.1-2022) metadata to swapchains.
HDR Vivid is an HDR standard released by UWA (UHD World Association). It defines tone mapping from the metadata to better preserve the creator’s intentions and achieve better consistency across devices with different display capabilities.
New Enum Constants
-
VK_HUAWEI_HDR_VIVID_EXTENSION_NAME -
VK_HUAWEI_HDR_VIVID_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_HDR_VIVID_DYNAMIC_METADATA_HUAWEI -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HDR_VIVID_FEATURES_HUAWEI
-
VK_HUAWEI_invocation_mask
- Name String
-
VK_HUAWEI_invocation_mask - Extension Type
-
Device extension
- Registered Extension Number
-
371
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Pan Gao [GitHub]PanGao-h
-
- 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
-
Juntao Li, Huawei
-
Liang Chen, Huawei
-
Shaozhuang Shi, Huawei
-
Hailong Chu, 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
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Pan Gao [GitHub]PanGao-h
-
Other Extension Metadata
- Last Modified Date
-
2021-06-01
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_HUAWEI_subpass_shading.
-
- Contributors
-
-
Hueilong Wang
-
Juntao Li, Huawei
-
Renmiao Lu, Huawei
-
Pan Gao, Huawei
-
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_SHADER_BIT_HUAWEI -
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_SHADER_BIT_HUAWEI, VK_ACCESS_INPUT_ATTACHMENT_READ_BIT
};
VkMemoryBarrier2KHR subpassShadingToFragment = {
VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR, NULL,
VK_PIPELINE_STAGE_2_SUBPASS_SHADER_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 3, 2023-06-19 (Pan Gao)
-
Rename
VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEItoVK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEIto better aligned with naming of other pipeline stages
-
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Tobias Hector [GitHub]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 =
{
.sType = VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO,
// 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_relaxed_line_rasterization
- Name String
-
VK_IMG_relaxed_line_rasterization - Extension Type
-
Device extension
- Registered Extension Number
-
111
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
James Fitzpatrick [GitHub]jamesfitzpatrick
-
Other Extension Metadata
- Last Modified Date
-
2023-10-22
- IP Status
-
No known IP claims.
- Contributors
-
-
James Fitzpatrick, Imagination
-
Andrew Garrard, Imagination
-
Alex Walters, Imagination
-
Description
OpenGL specifies that implementations should rasterize lines using the diamond exit rule (a slightly modified version of Bresenham’s algorithm). To implement OpenGL some implementations have a device-level compatibility mode to rasterize lines according to the OpenGL specification.
This extension allows OpenGL emulation layers to enable the OpenGL compatible line rasterization mode of such implementations.
New Enum Constants
-
VK_IMG_RELAXED_LINE_RASTERIZATION_EXTENSION_NAME -
VK_IMG_RELAXED_LINE_RASTERIZATION_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RELAXED_LINE_RASTERIZATION_FEATURES_IMG
-
VK_INTEL_performance_query
- Name String
-
VK_INTEL_performance_query - Extension Type
-
Device extension
- Registered Extension Number
-
211
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Special Use
- Contact
-
-
Lionel Landwerlin [GitHub]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 an 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.
VK_INTEL_shader_integer_functions2
- Name String
-
VK_INTEL_shader_integer_functions2 - Extension Type
-
Device extension
- Registered Extension Number
-
210
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Ian Romanick [GitHub]ianromanick
-
Other Extension Metadata
- Last Modified Date
-
2019-04-30
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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_LUNARG_direct_driver_loading
- Name String
-
VK_LUNARG_direct_driver_loading - Extension Type
-
Instance extension
- Registered Extension Number
-
460
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Charles Giessen [GitHub]charles-lunarg
-
- Extension Proposal
Description
This extension provides a mechanism for applications to add drivers to the implementation. This allows drivers to be included with an application without requiring installation and is capable of being used in any execution environment, such as a process running with elevated privileges.
New Enum Constants
-
VK_LUNARG_DIRECT_DRIVER_LOADING_EXTENSION_NAME -
VK_LUNARG_DIRECT_DRIVER_LOADING_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_INFO_LUNARG -
VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_LIST_LUNARG
-
VK_MESA_image_alignment_control
- Name String
-
VK_MESA_image_alignment_control - Extension Type
-
Device extension
- Registered Extension Number
-
576
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Hans-Kristian Arntzen [GitHub]HansKristian-Work
-
Other Extension Metadata
- Last Modified Date
-
2024-05-03
- IP Status
-
No known IP claims.
- Contributors
-
-
Hans-Kristian Arntzen, Valve
-
Description
This extension allows applications to request a narrower alignment for
images than an implementation would otherwise require.
Some implementations internally support multiple image layouts in
VK_IMAGE_TILING_OPTIMAL, each with different alignment requirements
and performance trade-offs.
In some API layering use cases such as D3D12, it is beneficial to be able to
control the alignment, since certain alignments for placed resources are
guaranteed to be supported, and emulating that expectation requires
unnecessary padding of allocations.
VkImageAlignmentControlCreateInfoMESA can be chained to VkImageCreateInfo, requesting that the alignment is no more than the provided alignment. If the requested alignment is not supported for a given VkImageCreateInfo, a larger alignment may be returned.
While something similar could be achieved with
VK_EXT_image_drm_format_modifier in theory, this is not the
intended way to use that extension.
Format modifiers are generally used for externally shareable images, and
would not be platform portable.
It is also a cumbersome API to use just to lower the alignment.
New Enum Constants
-
VK_MESA_IMAGE_ALIGNMENT_CONTROL_EXTENSION_NAME -
VK_MESA_IMAGE_ALIGNMENT_CONTROL_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_ALIGNMENT_CONTROL_CREATE_INFO_MESA -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ALIGNMENT_CONTROL_FEATURES_MESA -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ALIGNMENT_CONTROL_PROPERTIES_MESA
-
VK_MSFT_layered_driver
- Name String
-
VK_MSFT_layered_driver - Extension Type
-
Device extension
- Registered Extension Number
-
531
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Jesse Natalie [GitHub]jenatali
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-06-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Natalie, Microsoft
-
Description
This extension adds new physical device properties to allow applications and the Vulkan ICD loader to understand when a physical device is implemented as a layered driver on top of another underlying API.
New Enum Constants
-
VK_MSFT_LAYERED_DRIVER_EXTENSION_NAME -
VK_MSFT_LAYERED_DRIVER_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_DRIVER_PROPERTIES_MSFT
-
VK_NN_vi_surface
- Name String
-
VK_NN_vi_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
63
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Mathias Heyer [GitLab]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::window 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Jeff Juliano [GitHub]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 structure 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Eric Werness [GitHub]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 structure 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_cluster_acceleration_structure
- Name String
-
VK_NV_cluster_acceleration_structure - Extension Type
-
Device extension
- Registered Extension Number
-
570
- Revision
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_EXT_opacity_micromap
-
Interacts with VK_KHR_ray_tracing_pipeline
-
- SPIR-V Dependencies
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-09-09
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Eric Werness, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Jan Schmid, NVIDIA
-
Pyarelal Knowles, NVIDIA
-
Description
Acceleration structure build times can become a bottleneck in ray tracing applications dealing with extensive dynamic geometry. This extension addresses the problem by enabling applications to construct bottom-level acceleration structures (BLAS) from pre-generated acceleration structures based on clusters of triangles (CLAS), leading to significant improvements in build times.
It provides a host-side query function to fetch the requirements and a versatile multi-indirect call for managing cluster geometry. This call enables applications to generate cluster geometry, construct Cluster BLAS from CLAS lists, and move or copy CLAS and BLAS. By sourcing inputs from device memory and processing multiple elements simultaneously, the call reduces the host-side costs associated with traditional acceleration structure functions.
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_cluster_acceleration_structure
New Structures
If VK_KHR_ray_tracing_pipeline is supported:
New Enum Constants
-
VK_NV_CLUSTER_ACCELERATION_STRUCTURE_EXTENSION_NAME -
VK_NV_CLUSTER_ACCELERATION_STRUCTURE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_CLUSTERS_BOTTOM_LEVEL_INPUT_NV -
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_COMMANDS_INFO_NV -
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_INPUT_INFO_NV -
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_MOVE_OBJECTS_INPUT_NV -
VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_TRIANGLE_CLUSTER_INPUT_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_ACCELERATION_STRUCTURE_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_ACCELERATION_STRUCTURE_PROPERTIES_NV -
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CLUSTER_ACCELERATION_STRUCTURE_CREATE_INFO_NV
-
If VK_EXT_opacity_micromap is supported:
-
Extending VkOpacityMicromapSpecialIndexEXT:
-
VK_OPACITY_MICROMAP_SPECIAL_INDEX_CLUSTER_GEOMETRY_DISABLE_OPACITY_MICROMAP_NV
-
VK_NV_command_buffer_inheritance
- Name String
-
VK_NV_command_buffer_inheritance - Extension Type
-
Device extension
- Registered Extension Number
-
560
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Lujin Wang [GitHub]lujinwangnv
-
Other Extension Metadata
- Last Modified Date
-
2024-02-15
- IP Status
-
No known IP claims.
- Contributors
-
-
Piers Daniell, NVIDIA
-
Daniel Story, Nintendo
-
Description
This extension allows applications to take advantage of the graphics and compute state that remains valid in the queue between executions of submitted command buffers. This works across both primary and secondary command buffers.
The state inherited includes the previously bound pipeline state, previously bound shader objects, previously bound vertex and index buffers, previously bound descriptor sets and push constants, and all previously set dynamic state.
This extension relaxes the requirement that all that state needs to be bound and set after begin command buffer and before the next draw or dispatch.
By not having to set state that has been inherited applications can save both CPU and GPU cycles by not having to set state redundantly, and also have improved flexibility when reusing secondary command buffers.
New Enum Constants
-
VK_NV_COMMAND_BUFFER_INHERITANCE_EXTENSION_NAME -
VK_NV_COMMAND_BUFFER_INHERITANCE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMMAND_BUFFER_INHERITANCE_FEATURES_NV
-
Issues
1) How can the validation layer know when state is valid at draw or dispatch time if it is inherited at execution time?
RESOLVED: Validation of invalid state at draw and dispatch time cannot be done while recording those commands. Instead the validation layer will need to keep track of any unset state when draw and dispatch commands are recorded, but not report an error at that time. It should also keep track of what state is valid at the end of each recorded command buffer. When secondary command buffer execution is recorded the validation layer can update its unset state tracking for that command buffer, and also for draw and dispatch commands recorded after execution of the secondary as they will inherit state from the executed secondary. This can be done recursively so every recorded primary command buffer has a final tally of any unset state used at draw and dispatch time. Finally when the primary is submitted to the queue the validation layer will know the previous primaries submitted to the queue and will know if there is any unset state used and can report the error then.
VK_NV_cooperative_matrix
- Name String
-
VK_NV_cooperative_matrix - Extension Type
-
Device extension
- Registered Extension Number
-
250
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-02-05
- Interactions and External Dependencies
-
-
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 VkComponentTypeKHR:
-
VK_COMPONENT_TYPE_FLOAT16_NV -
VK_COMPONENT_TYPE_FLOAT32_NV -
VK_COMPONENT_TYPE_FLOAT64_NV -
VK_COMPONENT_TYPE_SINT16_NV -
VK_COMPONENT_TYPE_SINT32_NV -
VK_COMPONENT_TYPE_SINT64_NV -
VK_COMPONENT_TYPE_SINT8_NV -
VK_COMPONENT_TYPE_UINT16_NV -
VK_COMPONENT_TYPE_UINT32_NV -
VK_COMPONENT_TYPE_UINT64_NV -
VK_COMPONENT_TYPE_UINT8_NV
-
-
Extending VkScopeKHR:
-
VK_SCOPE_DEVICE_NV -
VK_SCOPE_QUEUE_FAMILY_NV -
VK_SCOPE_SUBGROUP_NV -
VK_SCOPE_WORKGROUP_NV
-
-
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_cooperative_matrix2
- Name String
-
VK_NV_cooperative_matrix2 - Extension Type
-
Device extension
- Registered Extension Number
-
594
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-08-01
- Interactions and External Dependencies
-
-
This extension provides API support for
GLSL_NV_cooperative_matrix2
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Karthik Vaidyanathan, NVIDIA
-
Description
This extension adds several new features building on the cooperative matrix types added in VK_KHR_cooperative_matrix. The goal is to add and accelerate features beyond just simple GEMM kernels, including adding support for type/use conversions, reductions, per-element operations, and tensor addressing, and also to improve usability and out-of-the-box performance by adding support for more flexible matrix sizes, and workgroup scope matrices with compiler-managed staging through shared memory.
The new functionality is defined by the
SPV_NV_tensor_addressing and
SPV_NV_cooperative_matrix2
SPIR-V extensions and can be used with the
GLSL_NV_cooperative_matrix2
GLSL extension.
This extension includes support for enumerating the matrix types and dimensions that are supported by the implementation, and which specific features are supported.
New Enum Constants
-
VK_NV_COOPERATIVE_MATRIX_2_EXTENSION_NAME -
VK_NV_COOPERATIVE_MATRIX_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COOPERATIVE_MATRIX_FLEXIBLE_DIMENSIONS_PROPERTIES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_2_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_MATRIX_2_PROPERTIES_NV
-
VK_NV_cooperative_vector
- Name String
-
VK_NV_cooperative_vector - Extension Type
-
Device extension
- Registered Extension Number
-
492
- Revision
-
4
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-05-23
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_cooperative_vector -
This extension provides API support for
GL_NV_cooperative_vector
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension adds support for using cooperative vector types in SPIR-V. Unlike cooperative matrix types, a variable with a cooperative vector type is logically stored in the invocation it belongs to, but they can cooperate behind the scenes when performing matrix-vector multiplies. Cooperative vectors do not require a fully occupied subgroup or uniform control flow like cooperative matrices, although these do increase the likelihood of being on the fast path. And unlike normal vector types, they have arbitrary length and support a relatively limited set of operations. These types are intended to help accelerate the evaluation of small neural networks, where each invocation is performing its own independent evaluation of the network.
Cooperative vector types are defined by the
SPV_NV_cooperative_vector
SPIR-V extension and can be used with the
GL_NV_cooperative_vector
GLSL extension.
This extension includes support for enumerating the combinations of types that are supported by the implementation, and for converting matrix data to and from an optimized opaque layout.
New Enum Constants
-
VK_NV_COOPERATIVE_VECTOR_EXTENSION_NAME -
VK_NV_COOPERATIVE_VECTOR_SPEC_VERSION -
Extending VkComponentTypeKHR:
-
VK_COMPONENT_TYPE_FLOAT_E4M3_NV -
VK_COMPONENT_TYPE_FLOAT_E5M2_NV -
VK_COMPONENT_TYPE_SINT8_PACKED_NV -
VK_COMPONENT_TYPE_UINT8_PACKED_NV
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_CONVERT_COOPERATIVE_VECTOR_MATRIX_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CONVERT_COOPERATIVE_VECTOR_MATRIX_INFO_NV -
VK_STRUCTURE_TYPE_COOPERATIVE_VECTOR_PROPERTIES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_VECTOR_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COOPERATIVE_VECTOR_PROPERTIES_NV
-
VK_NV_copy_memory_indirect
- Name String
-
VK_NV_copy_memory_indirect - Extension Type
-
Device extension
- Registered Extension Number
-
427
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha-nv
-
Other Extension Metadata
- Last Modified Date
-
2022-10-14
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Jeff Bolz, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
This extension adds support for performing copies between memory and image regions using indirect parameters that are read by the device from a buffer during execution. This functionality may be useful for performing copies where the copy parameters are not known during the command buffer creation time.
New Enum Constants
-
VK_NV_COPY_MEMORY_INDIRECT_EXTENSION_NAME -
VK_NV_COPY_MEMORY_INDIRECT_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COPY_MEMORY_INDIRECT_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COPY_MEMORY_INDIRECT_PROPERTIES_NV
-
VK_NV_corner_sampled_image
- Name String
-
VK_NV_corner_sampled_image - Extension Type
-
Device extension
- Registered Extension Number
-
51
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Daniel Koch [GitHub]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 Mip Level Sizing.
-
The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. See Image Mip Level 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 LOD 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: Probably, but later.
VK_NV_coverage_reduction_mode
- Name String
-
VK_NV_coverage_reduction_mode - Extension Type
-
Device extension
- Registered Extension Number
-
251
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Kedarnath Thangudu [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Nuno Subtil [GitHub]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_descriptor_pool_overallocation
- Name String
-
VK_NV_descriptor_pool_overallocation - Extension Type
-
Device extension
- Registered Extension Number
-
547
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Description
There are scenarios where the application does not know ahead of time how many descriptor sets it may need to allocate from a descriptor pool, or how many descriptors of any of the descriptor types it may need to allocate from the descriptor pool.
This extension gives applications the ability to request the implementation allow more sets or descriptors to be allocated than initially specified at descriptor pool creation time, subject to available resources.
The VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_SETS_BIT_NV flag
lets the application allocate more than
VkDescriptorPoolCreateInfo::maxSets descriptor sets, and the
VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_POOLS_BIT_NV lets the
application allocate more descriptors than initially specified by
VkDescriptorPoolSize::descriptorCount for any descriptor types.
New Enum Constants
-
VK_NV_DESCRIPTOR_POOL_OVERALLOCATION_EXTENSION_NAME -
VK_NV_DESCRIPTOR_POOL_OVERALLOCATION_SPEC_VERSION -
Extending VkDescriptorPoolCreateFlagBits:
-
VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_POOLS_BIT_NV -
VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_SETS_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_POOL_OVERALLOCATION_FEATURES_NV
-
VK_NV_device_diagnostic_checkpoints
- Name String
-
VK_NV_device_diagnostic_checkpoints - Extension Type
-
Device extension
- Registered Extension Number
-
207
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_synchronization2
-
- Contact
-
-
Nuno Subtil [GitHub]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 Commands
If Vulkan Version 1.3 or VK_KHR_synchronization2 is supported:
New Structures
If Vulkan Version 1.3 or VK_KHR_synchronization2 is supported:
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
-
If Vulkan Version 1.3 or VK_KHR_synchronization2 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CHECKPOINT_DATA_2_NV -
VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_2_NV
-
VK_NV_device_diagnostics_config
- Name String
-
VK_NV_device_diagnostics_config - Extension Type
-
Device extension
- Registered Extension Number
-
301
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Kedarnath Thangudu [GitHub]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
-
VK_NV_device_generated_commands
- Name String
-
VK_NV_device_generated_commands - Extension Type
-
Device extension
- Registered Extension Number
-
278
- Revision
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Christoph Kubisch [GitHub]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 reusing 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 desirable. 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 reusing already “generated” indirectCommands?
Expose a preprocessBuffer to reuse implementation-dependencyFlags data.
Set isPreprocessed to VK_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.
VK_NV_device_generated_commands_compute
- Name String
-
VK_NV_device_generated_commands_compute - Extension Type
-
Device extension
- Registered Extension Number
-
429
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha-nv
-
Other Extension Metadata
- Last Modified Date
-
2023-07-21
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Jeff Bolz, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Piers Daniell, NVIDIA
-
Daniel Koch, NVIDIA
-
Hans-Kristian Arntzen, Valve
-
Mike Blumenkrantz, VALVE
-
Description
This extension allows the device to generate commands for binding compute pipelines, setting push constants and launching compute dispatches.
New Enum Constants
-
VK_NV_DEVICE_GENERATED_COMMANDS_COMPUTE_EXTENSION_NAME -
VK_NV_DEVICE_GENERATED_COMMANDS_COMPUTE_SPEC_VERSION -
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_INDIRECT_BINDABLE_BIT_NV
-
-
Extending VkIndirectCommandsTokenTypeNV:
-
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NV -
VK_INDIRECT_COMMANDS_TOKEN_TYPE_PIPELINE_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_INDIRECT_BUFFER_INFO_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_GENERATED_COMMANDS_COMPUTE_FEATURES_NV -
VK_STRUCTURE_TYPE_PIPELINE_INDIRECT_DEVICE_ADDRESS_INFO_NV
-
VK_NV_display_stereo
- Name String
-
VK_NV_display_stereo - Extension Type
-
Instance extension
- Registered Extension Number
-
552
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Russell Chou [GitHub]russellcnv
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-11-20
- Contributors
-
-
Russell Chou, NVIDIA
-
Jeff Juliano, NVIDIA
-
James Jones, NVIDIA
-
Description
This extension allows the application to choose which type of 3D stereo hardware it wants to use so the driver can configure it properly. This configuration is useful for swapchains created from display surfaces because some environments do not have an intermediate windowing system available for easy configuration. This extension will override any stereo type configuration in the windowing system.
For HDMI 3D, only some display modes support stereo rendering, and a new structure is needed to expose that information to the application.
New Enum Constants
-
VK_NV_DISPLAY_STEREO_EXTENSION_NAME -
VK_NV_DISPLAY_STEREO_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_MODE_STEREO_PROPERTIES_NV -
VK_STRUCTURE_TYPE_DISPLAY_SURFACE_STEREO_CREATE_INFO_NV
-
VK_NV_extended_sparse_address_space
- Name String
-
VK_NV_extended_sparse_address_space - Extension Type
-
Device extension
- Registered Extension Number
-
493
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Russell Chou [GitHub]russellcnv
-
Other Extension Metadata
- Last Modified Date
-
2023-10-03
- Contributors
-
-
Russell Chou, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Eric Werness, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
Implementations may be able to support an extended address space for sparse memory resources, but only for a certain set of usages.
This extension adds a query for the extended limit, and the supported usages
that are allowed for that limit.
This limit is an increase to
VkPhysicalDeviceLimits::sparseAddressSpaceSize when the
VkImage or VkBuffer uses only usages that are supported.
New Enum Constants
-
VK_NV_EXTENDED_SPARSE_ADDRESS_SPACE_EXTENSION_NAME -
VK_NV_EXTENDED_SPARSE_ADDRESS_SPACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_SPARSE_ADDRESS_SPACE_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_SPARSE_ADDRESS_SPACE_PROPERTIES_NV
-
VK_NV_external_compute_queue
- Name String
-
VK_NV_external_compute_queue - Extension Type
-
Device extension
- Registered Extension Number
-
557
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Chris Lentini [GitHub]clentini
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-03-24
- Contributors
-
-
Chris Lentini, NVIDIA
-
Eric Werness, NVIDIA
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Liam Middlebrook, NVIDIA
-
Lionel Duc, NVIDIA
-
Description
This extension gives applications the ability to join compatible external
compute APIs to a VkDevice.
In this way, the extension allows an application to achieve simultaneous
execution between work submitted from these compatible external APIs and
work that has been submitted through the Vulkan API.
At device creation time, an application must supply a VkExternalComputeQueueDeviceCreateInfoNV. This communicates to the implementation the maximum number of external queues that the application can create at once. This information may be used by the implementation to aid in decisions made during device creation.
After device creation, the function vkCreateExternalComputeQueueNV is
used by an application to create a new VkExternalComputeQueueNV
object.
The VkExternalComputeQueueNV object holds information and reserves
resources necessary for a compatible external API to be able to join a
VkDevice.
This information can be queried through the
vkGetExternalComputeQueueDataNV function, returning an opaque blob of
data which can be passed to compatible external APIs.
The application must finally call vkDestroyExternalComputeQueueNV
when it is done in order to release the reserved resources.
This extension introduces a new properties structure, VkPhysicalDeviceExternalComputeQueuePropertiesNV, which can be queried through vkGetPhysicalDeviceProperties2. The structure provides information on functional limits to the extension as well as a way of querying the size of the application allocated memory which must be passed to the vkGetExternalComputeQueueDataNV function.
When creating a VkExternalComputeQueueNV through
vkCreateExternalComputeQueueNV, the
VkExternalComputeQueueCreateInfoNV structure requires an application
to supply a VkQueue to aid in external compute queue creation.
The supplied VkQueue is a strong scheduling hint about which queue it
expects to submit graphics workloads to and with which it expects
simultaneous execution of compute workloads submitted through the external
API.
New Enum Constants
-
VK_NV_EXTERNAL_COMPUTE_QUEUE_EXTENSION_NAME -
VK_NV_EXTERNAL_COMPUTE_QUEUE_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_EXTERNAL_COMPUTE_QUEUE_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXTERNAL_COMPUTE_QUEUE_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_EXTERNAL_COMPUTE_QUEUE_DATA_PARAMS_NV -
VK_STRUCTURE_TYPE_EXTERNAL_COMPUTE_QUEUE_DEVICE_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_COMPUTE_QUEUE_PROPERTIES_NV
-
|
Note
|
While the external queue is now a part of a |
|
Note
|
In general, synchronization and resource sharing between the external API and Vulkan must still be accomplished via existing cross-API interop mechanisms. |
VK_NV_external_memory_rdma
- Name String
-
VK_NV_external_memory_rdma - Extension Type
-
Device extension
- Registered Extension Number
-
372
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Carsten Rohde [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Jeff Bolz [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Jeff Bolz [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Pat Brown [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_dynamic_rendering
-
- Contact
-
-
Jeff Bolz [GitHub]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 Structures
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
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
-
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ATTACHMENT_SAMPLE_COUNT_INFO_NV
-
VK_NV_geometry_shader_passthrough
- Name String
-
VK_NV_geometry_shader_passthrough - Extension Type
-
Device extension
- Registered Extension Number
-
96
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-02-15
- Interactions and External Dependencies
-
-
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.
Behavior 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 passthrough 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 variables 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
David Zhao Akeley [GitHub]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 reusable 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_format_feature_flags2
-
- Contact
-
-
sourav parmar [GitHub]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 or Vulkan Version 1.3 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV
-
VK_NV_low_latency
- Name String
-
VK_NV_low_latency - Extension Type
-
Device extension
- Registered Extension Number
-
311
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Charles Hansen [GitHub]cshansen
-
Description
This extension adds the VkQueryLowLatencySupportNV structure, a structure used to query support for NVIDIA Reflex.
New Structures
-
Extending VkSemaphoreCreateInfo:
New Enum Constants
-
VK_NV_LOW_LATENCY_EXTENSION_NAME -
VK_NV_LOW_LATENCY_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_QUERY_LOW_LATENCY_SUPPORT_NV
-
VK_NV_low_latency2
- Name String
-
VK_NV_low_latency2 - Extension Type
-
Device extension
- Registered Extension Number
-
506
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Charles Hansen [GitHub]cshansen
-
Other Extension Metadata
- Last Modified Date
-
2023-09-25
- Contributors
-
-
Charles Hansen, NVIDIA
-
Liam Middlebrook, NVIDIA
-
Lionel Duc, NVIDIA
-
James Jones, NVIDIA
-
Eric Sullivan, NVIDIA
-
New Enum Constants
-
VK_NV_LOW_LATENCY_2_EXTENSION_NAME -
VK_NV_LOW_LATENCY_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_GET_LATENCY_MARKER_INFO_NV -
VK_STRUCTURE_TYPE_LATENCY_SLEEP_INFO_NV -
VK_STRUCTURE_TYPE_LATENCY_SLEEP_MODE_INFO_NV -
VK_STRUCTURE_TYPE_LATENCY_SUBMISSION_PRESENT_ID_NV -
VK_STRUCTURE_TYPE_LATENCY_SURFACE_CAPABILITIES_NV -
VK_STRUCTURE_TYPE_LATENCY_TIMINGS_FRAME_REPORT_NV -
VK_STRUCTURE_TYPE_OUT_OF_BAND_QUEUE_TYPE_INFO_NV -
VK_STRUCTURE_TYPE_SET_LATENCY_MARKER_INFO_NV -
VK_STRUCTURE_TYPE_SWAPCHAIN_LATENCY_CREATE_INFO_NV
-
Description
This extension gives applications timing suggestions on when to start the
recording of new frames to reduce the latency between input sampling and
frame presentation.
Applications can accomplish this through the extension by calling
vkSetLatencySleepModeNV to allow the driver to pace a given swapchain,
then calling vkLatencySleepNV before input sampling to delay the start
of the CPU side work.
Additional methods and structures are provided to give insight into the
latency pipeline of an application through the latency markers.
VK_NV_low_latency provides legacy support for applications that
make use of the NVIDIA Reflex SDK whereas new implementations should use the
VK_NV_low_latency2 extension.
Issues
1) How does Low Latency 2 work with applications that utilize device groups?
Low Latency 2 does not support device groups.
Version History
-
Revision 2, 2023-11-15 (Charles Hansen)
-
Update vkGetLatencyTimingsNV. This is a breaking API change which brings behavior in line with other array querying commands. More background can be found in https://github.com/KhronosGroup/Vulkan-Docs/issues/2269
-
-
Revision 1, 2023-09-25 (Charles Hansen)
-
Internal revisions
-
VK_NV_memory_decompression
- Name String
-
VK_NV_memory_decompression - Extension Type
-
Device extension
- Registered Extension Number
-
428
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha-nv
-
Other Extension Metadata
- Last Modified Date
-
2022-01-31
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Jeff Bolz, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Piers Daniell, NVIDIA
-
New Enum Constants
-
VK_NV_MEMORY_DECOMPRESSION_EXTENSION_NAME -
VK_NV_MEMORY_DECOMPRESSION_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_DECOMPRESSION_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_DECOMPRESSION_PROPERTIES_NV
-
VK_NV_mesh_shader
- Name String
-
VK_NV_mesh_shader - Extension Type
-
Device extension
- Registered Extension Number
-
203
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_2
-
Interacts with VK_EXT_device_generated_commands
-
Interacts with VK_KHR_draw_indirect_count
-
- SPIR-V Dependencies
- Contact
-
-
Christoph Kubisch [GitHub]pixeljetstream
-
Other Extension Metadata
- Last Modified Date
-
2018-07-19
- Interactions and External Dependencies
-
-
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 Commands
If VK_KHR_draw_indirect_count or Vulkan Version 1.2 is supported:
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
-
If VK_EXT_device_generated_commands is supported:
-
Extending VkIndirectCommandsTokenTypeEXT:
-
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_COUNT_NV_EXT -
VK_INDIRECT_COMMANDS_TOKEN_TYPE_DRAW_MESH_TASKS_NV_EXT
-
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_optical_flow
- Name String
-
VK_NV_optical_flow - Extension Type
-
Device extension
- Registered Extension Number
-
465
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Carsten Rohde [GitHub]crohde
-
Other Extension Metadata
- Last Modified Date
-
2022-09-26
- Contributors
-
-
Carsten Rohde, NVIDIA
-
Vipul Parashar, NVIDIA
-
Jeff Bolz, NVIDIA
-
Eric Werness, NVIDIA
-
Description
Optical flow are fundamental algorithms in computer vision (CV) area. This extension allows applications to estimate 2D displacement of pixels between two frames.
|
Note
|
This extension is designed to be used with upcoming NVIDIA Optical Flow SDK Version 5 which will be available on NVIDIA Developer webpage. |
New Enum Constants
-
VK_NV_OPTICAL_FLOW_EXTENSION_NAME -
VK_NV_OPTICAL_FLOW_SPEC_VERSION -
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV -
VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV
-
-
Extending VkFormat:
-
VK_FORMAT_R16G16_S10_5_NV -
VK_FORMAT_R16G16_SFIXED5_NV
-
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_OPTICAL_FLOW_COST_BIT_NV -
VK_FORMAT_FEATURE_2_OPTICAL_FLOW_IMAGE_BIT_NV -
VK_FORMAT_FEATURE_2_OPTICAL_FLOW_VECTOR_BIT_NV
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_OPTICAL_FLOW_SESSION_NV
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV
-
-
Extending VkQueueFlagBits:
-
VK_QUEUE_OPTICAL_FLOW_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_OPTICAL_FLOW_EXECUTE_INFO_NV -
VK_STRUCTURE_TYPE_OPTICAL_FLOW_IMAGE_FORMAT_INFO_NV -
VK_STRUCTURE_TYPE_OPTICAL_FLOW_IMAGE_FORMAT_PROPERTIES_NV -
VK_STRUCTURE_TYPE_OPTICAL_FLOW_SESSION_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_OPTICAL_FLOW_SESSION_CREATE_PRIVATE_DATA_INFO_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPTICAL_FLOW_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPTICAL_FLOW_PROPERTIES_NV
-
Examples
// Example querying available input formats
VkOpticalFlowImageFormatInfoNV ofFormatInfo = { VK_STRUCTURE_TYPE_OPTICAL_FLOW_IMAGE_FORMAT_INFO_NV };
ofFormatInfo.usage = VK_OPTICAL_FLOW_USAGE_INPUT_BIT_NV;
uint32_t count = 0;
vkGetPhysicalDeviceOpticalFlowImageFormatsNV(physicalDevice, &ofFormatInfo, &count, NULL);
VkOpticalFlowImageFormatPropertiesNV* fmt = new VkOpticalFlowImageFormatPropertiesNV[count];
memset(fmt, 0, count * sizeof(VkOpticalFlowImageFormatPropertiesNV));
for (uint32_t i = 0; i < count; i++) {
fmt[i].sType = VK_STRUCTURE_TYPE_OPTICAL_FLOW_IMAGE_FORMAT_PROPERTIES_NV;
}
vkGetPhysicalDeviceOpticalFlowImageFormatsNV(physicalDevice, &ofFormatInfo, &count, fmt);
// Pick one of the available formats
VkFormat inputFormat = fmt[0].format;
// Check feature support for optimal tiling
VkFormatProperties3 formatProperties3 = { VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3 };
VkFormatProperties2 formatProperties2 = { VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_2, &formatProperties3 };
vkGetPhysicalDeviceFormatProperties2(physicalDevice, inputFormat, &formatProperties2);
if (!(formatProperties3.optimalTilingFeatures & VK_FORMAT_FEATURE_2_OPTICAL_FLOW_IMAGE_BIT_NV)) {
return false;
}
// Check support for image creation parameters
VkPhysicalDeviceImageFormatInfo2 imageFormatInfo2 = { VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2, &ofFormatInfo };
imageFormatInfo2.format = inputFormat;
imageFormatInfo2.type = VK_IMAGE_TYPE_2D;
imageFormatInfo2.tiling = VK_IMAGE_TILING_OPTIMAL;
imageFormatInfo2.usage = VK_IMAGE_USAGE_SAMPLED_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT;
VkImageFormatProperties2 imageFormatProperties2 = { VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2 };
if (vkGetPhysicalDeviceImageFormatProperties2(physicalDevice, &imageFormatInfo2, &imageFormatProperties2) != VK_SUCCESS) {
return false;
}
VkImageCreateInfo imageCreateInfo = { VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, &ofFormatInfo };
imageCreateInfo.imageType = VK_IMAGE_TYPE_2D;
imageCreateInfo.format = inputFormat;
imageCreateInfo.extent = { width, height, (uint32_t)1};
imageCreateInfo.mipLevels = 1;
imageCreateInfo.arrayLayers = 1;
imageCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;
imageCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT;
imageCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;
vkCreateImage(device, &imageCreateInfo, NULL, &input);
"allocate memory, bind image, create view"
"do the same for reference and output"
// Create optical flow session
VkOpticalFlowSessionCreateInfoNV sessionCreateInfo = { VK_STRUCTURE_TYPE_OPTICAL_FLOW_SESSION_CREATE_INFO_NV };
sessionCreateInfo.width = width;
sessionCreateInfo.height = height;
sessionCreateInfo.imageFormat = inputFormat;
sessionCreateInfo.flowVectorFormat = outputFormat;
sessionCreateInfo.outputGridSize = VK_OPTICAL_FLOW_GRID_SIZE_4X4_BIT_NV;
sessionCreateInfo.performanceLevel = VK_OPTICAL_FLOW_PERFORMANCE_LEVEL_SLOW_NV;
VkOpticalFlowSessionNV session;
vkCreateOpticalFlowSessionNV(device, &sessionCreateInfo, NULL, &session);
"allocate command buffer"
"transfer images to VK_PIPELINE_STAGE_2_OPTICAL_FLOW_BIT_NV"
"transfer input images to VK_ACCESS_2_OPTICAL_FLOW_READ_BIT_NV and output image to VK_ACCESS_2_OPTICAL_FLOW_WRITE_BIT_NV"
vkBindOpticalFlowSessionImageNV(device, session, VK_OPTICAL_FLOW_SESSION_BINDING_POINT_INPUT_NV, inputView, VK_IMAGE_LAYOUT_GENERAL);
vkBindOpticalFlowSessionImageNV(device, session, VK_OPTICAL_FLOW_SESSION_BINDING_POINT_REFERENCE_NV, refView, VK_IMAGE_LAYOUT_GENERAL);
vkBindOpticalFlowSessionImageNV(device, session, VK_OPTICAL_FLOW_SESSION_BINDING_POINT_FLOW_VECTOR_NV, outputView, VK_IMAGE_LAYOUT_GENERAL);
VkOpticalFlowExecuteInfoNV opticalFlowExecuteInfo = { VK_STRUCTURE_TYPE_OPTICAL_FLOW_EXECUTE_INFO_NV };
vkCmdOpticalFlowExecuteNV(cmd, session, &opticalFlowExecuteInfo);
"submit command buffer"
VK_NV_partitioned_acceleration_structure
- Name String
-
VK_NV_partitioned_acceleration_structure - Extension Type
-
Device extension
- Registered Extension Number
-
571
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-01-09
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Eric Werness, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Jan Schmid, NVIDIA
-
Pyarelal Knowles, NVIDIA
-
Description
With an increase in scene complexity and expansive game worlds, the number of instances has surged in ray tracing over the last few years. The current Top Level Acceleration Structure (TLAS) API necessitates a full rebuild of the entire data structure even when only a few instances are modified.
This extension introduces Partitioned Top Level Acceleration Structures (PTLAS) as an alternative to the existing TLAS. PTLAS enables the efficient reuse of previously constructed parts of the acceleration structure, resulting in much faster build times and supporting a higher number of instances.
New Structures
New Enum Constants
-
VK_NV_PARTITIONED_ACCELERATION_STRUCTURE_EXTENSION_NAME -
VK_NV_PARTITIONED_ACCELERATION_STRUCTURE_SPEC_VERSION -
VK_PARTITIONED_ACCELERATION_STRUCTURE_PARTITION_INDEX_GLOBAL_NV -
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_PARTITIONED_ACCELERATION_STRUCTURE_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BUILD_PARTITIONED_ACCELERATION_STRUCTURE_INFO_NV -
VK_STRUCTURE_TYPE_PARTITIONED_ACCELERATION_STRUCTURE_FLAGS_NV -
VK_STRUCTURE_TYPE_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCES_INPUT_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PARTITIONED_ACCELERATION_STRUCTURE_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PARTITIONED_ACCELERATION_STRUCTURE_PROPERTIES_NV -
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_PARTITIONED_ACCELERATION_STRUCTURE_NV
-
VK_NV_per_stage_descriptor_set
- Name String
-
VK_NV_per_stage_descriptor_set - Extension Type
-
Device extension
- Registered Extension Number
-
517
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2023-10-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Daniel Story, Nintendo
-
Description
This extension introduces a new descriptor set layout creation flag that allows bindings in a descriptor set to be scoped to each shader stage. This means that shaders bound at the same time may use completely different descriptor set layouts without any restrictions on compatibility, and that the descriptor limits that would otherwise apply to the union of all stages together instead apply to each stage individually. It also means that descriptors shared by multiple stages must be bound to each stage or set of stages that use a unique descriptor set layout using their specific per stage descriptor set layout(s).
This extension also allows each of the new descriptor binding functions from
VK_KHR_maintenance6 to have their VkPipelineLayout member be
optionally set to VK_NULL_HANDLE, in which case the pipeline layout
information is taken from a VkPipelineLayoutCreateInfo structure in
the pNext chain.
This enables descriptors to be directly bound using descriptor set layouts
without applications needing to create and manage VkPipelineLayout
objects at command recording time.
New Enum Constants
-
VK_NV_PER_STAGE_DESCRIPTOR_SET_EXTENSION_NAME -
VK_NV_PER_STAGE_DESCRIPTOR_SET_SPEC_VERSION -
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PER_STAGE_DESCRIPTOR_SET_FEATURES_NV
-
VK_NV_present_barrier
- Name String
-
VK_NV_present_barrier - Extension Type
-
Device extension
- Registered Extension Number
-
293
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Liya Li [GitHub]liyli
-
Other Extension Metadata
- Last Modified Date
-
2022-05-16
- Contributors
-
-
Liya Li, Nvidia
-
Martin Schwarzer, Nvidia
-
Andy Wolf, Nvidia
-
Ian Williams, Nvidia
-
Ben Morris, Nvidia
-
James Jones, Nvidia
-
Jeff Juliano, Nvidia
-
Description
This extension adds support for synchronizing corresponding presentation requests across multiple swapchains using the present barrier.
New Enum Constants
-
VK_NV_PRESENT_BARRIER_EXTENSION_NAME -
VK_NV_PRESENT_BARRIER_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_BARRIER_FEATURES_NV -
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_PRESENT_BARRIER_NV -
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_BARRIER_CREATE_INFO_NV
-
Issues
1) Is there a query interface to check if a swapchain is using the present barrier?
RESOLVED. There is no such query interface. When creating a swapchain, an application can specify to use the present barrier, and if the swapchain is created successfully, this swapchain will be using the present barrier.
2) Do we need an extra interface to set up the present barrier across distributed systems?
RESOLVED. If the required hardware is presented in the system, and all settings for the physical synchronization with other systems are set up, an implementation manages the configuration automatically when creating a swapchain, without any extra calls from the application.
VK_NV_raw_access_chains
- Name String
-
VK_NV_raw_access_chains - Extension Type
-
Device extension
- Registered Extension Number
-
556
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Rodrigo Locatti [GitHub]rlocatti
-
Other Extension Metadata
- Last Modified Date
-
2023-12-04
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_raw_access_chains
-
- Contributors
-
-
Hans-Kristian Arntzen, Valve
-
Rodrigo Locatti, NVIDIA
-
Description
This extension allows the use of the SPV_NV_raw_access_chains extension in
SPIR-V shader modules.
This enables SPIR-V producers to efficiently implement interfaces similar to
Direct3D structured buffers and byte address buffers, allowing shaders
compiled from an HLSL source to generate more efficient code.
VK_NV_ray_tracing_invocation_reorder
- Name String
-
VK_NV_ray_tracing_invocation_reorder - Extension Type
-
Device extension
- Registered Extension Number
-
491
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Eric Werness [GitHub]ewerness-nv
-
Other Extension Metadata
- Last Modified Date
-
2022-11-02
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_NV_shader_invocation_reorder
-
- Contributors
-
-
Eric Werness, NVIDIA
-
Ashwin Lele, NVIDIA
-
Description
The ray tracing pipeline API provides some ability to reorder for locality, but it is useful to have more control over how the reordering happens and what information is included in the reordering. The shader API provides a hit object to contain result information from the hit which can be used as part of the explicit sorting plus options that contain an integer for hint bits to use to add more locality.
New Enum Constants
-
VK_NV_RAY_TRACING_INVOCATION_REORDER_EXTENSION_NAME -
VK_NV_RAY_TRACING_INVOCATION_REORDER_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_INVOCATION_REORDER_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_INVOCATION_REORDER_PROPERTIES_NV
-
HLSL Mapping
HLSL does not provide this functionality natively yet.
However, it is possible to use this functionality via SPIR-V Intrinsics.
The codes for shader invocation reorder are obtained from this page:
#define ShaderInvocationReorderNV 5383
#define HitObjectAttributeNV 5385
#define OpHitObjectRecordHitMotionNV 5249
#define OpHitObjectRecordHitWithIndexMotionNV 5250
#define OpHitObjectRecordMissMotionNV 5251
#define OpHitObjectGetWorldToObjectNV 5252
#define OpHitObjectGetObjectToWorldNV 5253
#define OpHitObjectGetObjectRayDirectionNV 5254
#define OpHitObjectGetObjectRayOriginNV 5255
#define OpHitObjectTraceRayMotionNV 5256
#define OpHitObjectGetShaderRecordBufferHandleNV 5257
#define OpHitObjectGetShaderBindingTableRecordIndexNV 5258
#define OpHitObjectRecordEmptyNV 5259
#define OpHitObjectTraceRayNV 5260
#define OpHitObjectRecordHitNV 5261
#define OpHitObjectRecordHitWithIndexNV 5262
#define OpHitObjectRecordMissNV 5263
#define OpHitObjectExecuteShaderNV 5264
#define OpHitObjectGetCurrentTimeNV 5265
#define OpHitObjectGetAttributesNV 5266
#define OpHitObjectGetHitKindNV 5267
#define OpHitObjectGetPrimitiveIndexNV 5268
#define OpHitObjectGetGeometryIndexNV 5269
#define OpHitObjectGetInstanceIdNV 5270
#define OpHitObjectGetInstanceCustomIndexNV 5271
#define OpHitObjectGetWorldRayDirectionNV 5272
#define OpHitObjectGetWorldRayOriginNV 5273
#define OpHitObjectGetRayTMaxNV 5274
#define OpHitObjectGetRayTMinNV 5275
#define OpHitObjectIsEmptyNV 5276
#define OpHitObjectIsHitNV 5277
#define OpHitObjectIsMissNV 5278
#define OpReorderThreadWithHitObjectNV 5279
#define OpReorderThreadWithHintNV 5280
#define OpTypeHitObjectNV 5281
The capability and extension need to be added:
[[vk::ext_capability(ShaderInvocationReorderNV)]]
[[vk::ext_extension("SPV_NV_shader_invocation_reorder")]]
The creation of the HitObject type can be done like this:
[[vk::ext_type_def(HitObjectAttributeNV, OpTypeHitObjectNV)]]
void createHitObjectNV();
#define HitObjectNV vk::ext_type<HitObjectAttributeNV>
The payload:
-
must be global
-
needs the
RayPayloadKHRattribute as an extra storage class
struct [raypayload] HitPayload
{
float hitT : write(closesthit, miss) : read(caller);
int instanceIndex : write(closesthit) : read(caller);
float3 pos : write(closesthit) : read(caller);
float3 nrm : write(closesthit) : read(caller);
};
#define RayPayloadKHR 5338
[[vk::ext_storage_class(RayPayloadKHR)]] static HitPayload payload;
Here is the declaration of a few invocation reordering functions:
[[vk::ext_instruction(OpHitObjectRecordEmptyNV)]]
void hitObjectRecordEmptyNV([[vk::ext_reference]] HitObjectNV hitObject);
[[vk::ext_instruction(OpHitObjectTraceRayNV)]]
void hitObjectTraceRayNV(
[[vk::ext_reference]] HitObjectNV hitObject,
RaytracingAccelerationStructure as,
uint RayFlags,
uint CullMask,
uint SBTOffset,
uint SBTStride,
uint MissIndex,
float3 RayOrigin,
float RayTmin,
float3 RayDirection,
float RayTMax,
[[vk::ext_reference]] [[vk::ext_storage_class(RayPayloadKHR)]] HitPayload payload
);
[[vk::ext_instruction(OpReorderThreadWithHintNV)]]
void reorderThreadWithHintNV(int Hint, int Bits);
[[vk::ext_instruction(OpReorderThreadWithHitObjectNV)]]
void reorderThreadWithHitObjectNV([[vk::ext_reference]] HitObjectNV hitObject);
[[vk::ext_instruction(OpHitObjectExecuteShaderNV)]]
void hitObjectExecuteShaderNV([[vk::ext_reference]] HitObjectNV hitObject, [[vk::ext_reference]] [[vk::ext_storage_class(RayPayloadKHR)]] HitPayload payload);
[[vk::ext_instruction(OpHitObjectIsHitNV)]]
bool hitObjectIsHitNV([[vk::ext_reference]] HitObjectNV hitObject);
Using the function in the code, can be done like this
if (USE_SER == 1)
{
createHitObjectNV();
HitObjectNV hObj; // hitObjectNV hObj;
hitObjectRecordEmptyNV(hObj); //Initialize to an empty hit object
hitObjectTraceRayNV(hObj, topLevelAS, rayFlags, 0xFF, 0, 0, 0, r.Origin, 0.0, r.Direction, INFINITE, payload);
reorderThreadWithHitObjectNV(hObj);
hitObjectExecuteShaderNV(hObj, payload);
}
Note:
-
createHitObjectNV() needs to be call at least once. This can be also done in the main entry of the shader.
-
Function with a payload parameter, needs to have the payload struct defined before. There are no templated declaration of the function.
VK_NV_ray_tracing_linear_swept_spheres
- Name String
-
VK_NV_ray_tracing_linear_swept_spheres - Extension Type
-
Device extension
- Registered Extension Number
-
430
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-01-03
- Interactions and External Dependencies
-
-
This extension requires
SPV_NV_linear_swept_spheres -
This extension provides API support for
GL_NV_linear_swept_spheres
-
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Eric Werness, NVIDIA
-
Daniel Koch, NVIDIA
-
Ashwin Lele, NVIDIA
-
Nathan Morrical, NVIDIA
-
Description
This extension adds two new primitives for ray tracing: a sphere primitive and a linear swept sphere (LSS) primitive. The purpose of the LSS primitive is to enable rendering of high quality hair and fur using a compact primitive representation encoded in the acceleration structure. Sphere primitives are defined by a position and a radius and are a subset of LSS, but are useful in their own right, for example for particle systems.
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_NV_linear_swept_spheres
New Enum Constants
-
VK_NV_RAY_TRACING_LINEAR_SWEPT_SPHERES_EXTENSION_NAME -
VK_NV_RAY_TRACING_LINEAR_SWEPT_SPHERES_SPEC_VERSION -
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_ACCELERATION_STRUCTURE_RADIUS_BUFFER_BIT_NV
-
-
Extending VkGeometryTypeKHR:
-
VK_GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV -
VK_GEOMETRY_TYPE_SPHERES_NV
-
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_SPHERES_AND_LINEAR_SWEPT_SPHERES_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_LINEAR_SWEPT_SPHERES_DATA_NV -
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_SPHERES_DATA_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_LINEAR_SWEPT_SPHERES_FEATURES_NV
-
VK_NV_ray_tracing_motion_blur
- Name String
-
VK_NV_ray_tracing_motion_blur - Extension Type
-
Device extension
- Registered Extension Number
-
328
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Eric Werness
-
Other Extension Metadata
- Last Modified Date
-
2021-06-16
- Interactions and External Dependencies
-
-
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
-
VK_NV_ray_tracing_validation
- Name String
-
VK_NV_ray_tracing_validation - Extension Type
-
Device extension
- Registered Extension Number
-
569
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha-nv
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-03-04
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Eric Werness, NVIDIA
-
Piers Daniell, NVIDIA
-
Description
This extension adds support for performing ray tracing validation at an implementation level.
New Enum Constants
-
VK_NV_RAY_TRACING_VALIDATION_EXTENSION_NAME -
VK_NV_RAY_TRACING_VALIDATION_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_VALIDATION_FEATURES_NV
-
VK_NV_representative_fragment_test
- Name String
-
VK_NV_representative_fragment_test - Extension Type
-
Device extension
- Registered Extension Number
-
167
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Kedarnath Thangudu [GitHub]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 LOD computations work with the representative fragment test enabled?
RESOLVED: If a fragment shader uses derivative functions or texture lookups using automatic LOD 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.
VK_NV_sample_mask_override_coverage
- Name String
-
VK_NV_sample_mask_override_coverage - Extension Type
-
Device extension
- Registered Extension Number
-
95
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2016-12-08
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Pat Brown [GitHub]nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2023-01-18
- 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.
Version 2 of this extension introduces
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV and
vkCmdSetExclusiveScissorEnableNV.
Applications that use this dynamic state must ensure the implementation
advertises at least specVersion 2 of this extension.
New Enum Constants
-
VK_NV_SCISSOR_EXCLUSIVE_EXTENSION_NAME -
VK_NV_SCISSOR_EXCLUSIVE_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV -
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_atomic_float16_vector
- Name String
-
VK_NV_shader_atomic_float16_vector - Extension Type
-
Device extension
- Registered Extension Number
-
564
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2024-02-03
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_NV_shader_atomic_fp16_vector
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension allows a shader to perform atomic add, min, max, and exchange operations on 2- and 4-component vectors of float16. Buffer, workgroup, and image storage classes are all supported.
New Enum Constants
-
VK_NV_SHADER_ATOMIC_FLOAT16_VECTOR_EXTENSION_NAME -
VK_NV_SHADER_ATOMIC_FLOAT16_VECTOR_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT16_VECTOR_FEATURES_NV
-
VK_NV_shader_image_footprint
- Name String
-
VK_NV_shader_image_footprint - Extension Type
-
Device extension
- Registered Extension Number
-
205
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Pat Brown [GitHub]nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2018-09-13
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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 visibility), 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 LOD 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.
VK_NV_shader_sm_builtins
- Name String
-
VK_NV_shader_sm_builtins - Extension Type
-
Device extension
- Registered Extension Number
-
155
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2019-05-28
- Interactions and External Dependencies
-
-
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
-
VK_NV_shader_subgroup_partitioned
- Name String
-
VK_NV_shader_subgroup_partitioned - Extension Type
-
Device extension
- Registered Extension Number
-
199
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2018-03-17
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Pat Brown [GitHub]nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2019-07-18
- Interactions and External Dependencies
-
-
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 applications 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.
VK_NV_viewport_array2
- Name String
-
VK_NV_viewport_array2 - Extension Type
-
Device extension
- Registered Extension Number
-
97
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-02-15
- Interactions and External Dependencies
-
-
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.
Behavior is described in the GL_NV_viewport_array2 extension
specification.
|
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Piers Daniell [GitHub]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
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- API Interactions
-
-
Interacts with VK_EXT_debug_report
-
- Contact
-
-
Eric Werness [GitHub]ewerness-nv
-
Liam Middlebrook [GitHub]liam-middlebrook
-
Other Extension Metadata
- Last Modified Date
-
2024-11-04
- 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 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 -
VK_STRUCTURE_TYPE_CU_MODULE_TEXTURING_MODE_CREATE_INFO_NVX
-
If VK_EXT_debug_report is supported:
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_CU_FUNCTION_NVX_EXT -
VK_DEBUG_REPORT_OBJECT_TYPE_CU_MODULE_NVX_EXT
-
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 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 VkCuModuleTexturingModeCreateInfoNVX {
VkStructureType sType;
const void* pNext;
VkBool32 use64bitTexturing;
} VkCuModuleTexturingModeCreateInfoNVX;
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
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Eric Werness [GitHub]ewerness-nv
-
Other Extension Metadata
- Last Modified Date
-
2024-11-04
- Contributors
-
-
Eric Werness, NVIDIA
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Liam Middlebrook, 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
-
VK_NVX_multiview_per_view_attributes
- Name String
-
VK_NVX_multiview_per_view_attributes - Extension Type
-
Device extension
- Registered Extension Number
-
98
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_dynamic_rendering
-
- SPIR-V Dependencies
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-01-13
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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 the VK_NV_viewport_array2 extension is not also supported and
enabled, the per-view viewport mask must not be used.
New Structures
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
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
-
If Vulkan Version 1.3 or VK_KHR_dynamic_rendering is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_ATTRIBUTES_INFO_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_OHOS_surface
- Name String
-
VK_OHOS_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
588
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Weilan Chen [GitHub]wchen-h
-
Other Extension Metadata
- Last Modified Date
-
2025-05-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Weilan Chen, Huawei
-
Zehui Lin, Huawei
-
Pan Gao, Huawei
-
Zhao Zhang, Huawei
-
Yang Shi, Huawei
-
Description
The VK_OHOS_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
OHNativeWindow, the native surface type of Open Harmony OS.
Common consumer endpoints for OHNativeWindows are the system window
compositor, video encoders, and application-specific compositors.
New Enum Constants
-
VK_OHOS_SURFACE_EXTENSION_NAME -
VK_OHOS_SURFACE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_OH_SURFACE_CREATE_INFO_OHOS
-
VK_QCOM_filter_cubic_clamp
- Name String
-
VK_QCOM_filter_cubic_clamp - Extension Type
-
Device extension
- Registered Extension Number
-
522
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2023-08-02
- Contributors
-
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Description
This extension extends cubic filtering by adding the ability to enable an anti-ringing clamp. Cubic filtering samples from a 4x4 region of texels and computes a cubic weighted average of the region. In some cases, the resulting value is outside the range of any of the texels in the 4x4 region. This is sometimes referred to as “filter overshoot” or “filter ringing” and can occur when there is a sharp discontinuity in the 4x4 region being filtered. For some use cases this “ringing” can produces unacceptable artifacts.
The solution to the ringing problem is to clamp the post-cubic-filtered value to be within the max and min of texel values in the 4x4 region. While such “range clamping” can be performed in shader code, the additional texture fetches and clamping ALU operations can be costly.
Certain Adreno GPUs are able to perform the range clamp in the texture unit during cubic filtering at significant performance/power savings versus a shader-based clamping approach. This extension exposes such hardware functionality.
This extension extends VkSamplerReductionMode, adding
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_RANGECLAMP_QCOM which
enables the range clamp operation.
New Enum Constants
-
VK_QCOM_FILTER_CUBIC_CLAMP_EXTENSION_NAME -
VK_QCOM_FILTER_CUBIC_CLAMP_SPEC_VERSION -
Extending VkSamplerReductionMode:
-
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_RANGECLAMP_QCOM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUBIC_CLAMP_FEATURES_QCOM
-
VK_QCOM_filter_cubic_weights
- Name String
-
VK_QCOM_filter_cubic_weights - Extension Type
-
Device extension
- Registered Extension Number
-
520
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2023-06-23
- Contributors
-
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Description
This extension extends cubic filtering by adding the ability to select a set of weights. Without this extension, the weights used in cubic filtering are limited to those corresponding to a Catmull-Rom spline. This extension adds support for 3 additional spline weights.
This extension adds a new structure that can be added to the pNext
chain of VkSamplerCreateInfo that can be used to specify which set of
cubic weights are used in cubic filtering.
A similar structure can be added to the pNext chain of
VkBlitImageInfo2 to specify cubic weights used in a blit operation.
With this extension weights corresponding to the following additional splines can be selected for cubic filtered sampling and blits:
-
Zero Tangent Cardinal
-
B-Spline
-
Mitchell-Netravali
New Enum Constants
-
VK_QCOM_FILTER_CUBIC_WEIGHTS_EXTENSION_NAME -
VK_QCOM_FILTER_CUBIC_WEIGHTS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BLIT_IMAGE_CUBIC_WEIGHTS_INFO_QCOM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUBIC_WEIGHTS_FEATURES_QCOM -
VK_STRUCTURE_TYPE_SAMPLER_CUBIC_WEIGHTS_CREATE_INFO_QCOM
-
VK_QCOM_image_processing
- Name String
-
VK_QCOM_image_processing - Extension Type
-
Device extension
- Registered Extension Number
-
441
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_format_feature_flags2
-
- SPIR-V Dependencies
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-07-08
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_QCOM_image_processing
-
- Contributors
-
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Ruihao Zhang, Qualcomm Technologies, Inc.
-
Description
GPUs are commonly used to process images for various applications from 3D graphics to UI and from composition to compute applications. Simple scaling and filtering can be done with bilinear filtering, which comes for free during texture sampling. However, as screen sizes get larger and more use cases rely on GPU such as camera and video post-processing needs, there is increasing demand for GPU to support higher order filtering and other advanced image processing.
This extension introduces a new set of SPIR-V built-in functions for image processing. It exposes the following new imaging operations
-
The
OpImageSampleWeightedQCOMinstruction takes 3 operands: sampled image, weight image, and texture coordinates. The instruction computes a weighted average of an MxN region of texels in the sampled image, using a set of MxN weights in the weight image. -
The
OpImageBoxFilterQCOMinstruction takes 3 operands: sampled image, box size, and texture coordinates. Note that box size specifies a floating-point width and height in texels. The instruction computes a weighted average of all texels in the sampled image that are covered (either partially or fully) by a box with the specified size and centered at the specified texture coordinates. -
The
OpImageBlockMatchSADQCOMandOpImageBlockMatchSSDQCOMinstructions each takes 5 operands: target image, target coordinates, reference image, reference coordinates, and block size. Each instruction computes an error metric, that describes whether a block of texels in the target image matches a corresponding block of texels in the reference image. The error metric is computed per-component.OpImageBlockMatchSADQCOMcomputes "Sum Of Absolute Difference" andOpImageBlockMatchSSDQCOMcomputes "Sum of Squared Difference".
Each of the image processing instructions operate only on 2D images. The instructions do not-support sampling of mipmap, multi-plane, multi-layer, multi-sampled, or depth/stencil images. The instructions can be used in any shader stage.
Implementations of this extension should support these operations natively at the HW instruction level, offering potential performance gains as well as ease of development.
New Enum Constants
-
VK_QCOM_IMAGE_PROCESSING_EXTENSION_NAME -
VK_QCOM_IMAGE_PROCESSING_SPEC_VERSION -
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM -
VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM -
VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM
-
-
Extending VkSamplerCreateFlagBits:
-
VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_VIEW_SAMPLE_WEIGHT_CREATE_INFO_QCOM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_FEATURES_QCOM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_PROPERTIES_QCOM
-
If VK_KHR_format_feature_flags2 or Vulkan Version 1.3 is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM -
VK_FORMAT_FEATURE_2_BOX_FILTER_SAMPLED_BIT_QCOM -
VK_FORMAT_FEATURE_2_WEIGHT_IMAGE_BIT_QCOM -
VK_FORMAT_FEATURE_2_WEIGHT_SAMPLED_IMAGE_BIT_QCOM
-
VK_QCOM_image_processing2
- Name String
-
VK_QCOM_image_processing2 - Extension Type
-
Device extension
- Registered Extension Number
-
519
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2023-03-10
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_QCOM_image_processing2
-
- Contributors
-
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Description
This extension enables support for the SPIR-V TextureBlockMatch2QCOM
capability.
It builds on the functionality of QCOM_image_processing with the addition of
4 new image processing operations.
-
The
opImageBlockMatchWindowSADQCOM` SPIR-V instruction builds upon the functionality ofopImageBlockMatchSADQCOM` by repeatedly performing block match operations across a 2D window. The “2D windowExtent” and “compareMode” are specified by VkSamplerBlockMatchWindowCreateInfoQCOM in the sampler used to create the target image. LikeOpImageBlockMatchSADQCOM,opImageBlockMatchWindowSADQCOMcomputes an error metric, that describes whether a block of texels in the target image matches a corresponding block of texels in the reference image. UnlikeOpImageBlockMatchSADQCOM, this instruction computes an error metric at each (X,Y) location within the 2D window and returns either the minimum or maximum error. The instruction only supports single-component formats. Refer to the pseudocode below for details. -
The
opImageBlockMatchWindowSSDQCOMfollows the same pattern, computing the SSD error metric at each location within the 2D window. -
The
opImageBlockMatchGatherSADQCOMbuilds uponOpImageBlockMatchSADQCOM. This instruction computes an error metric, that describes whether a block of texels in the target image matches a corresponding block of texels in the reference image. The instruction computes the SAD error metric at 4 texel offsets and returns the error metric for each offset in the X,Y,Z,and W components. The instruction only supports single-component texture formats. Refer to the pseudocode below for details. -
The
opImageBlockMatchGatherSSDQCOMfollows the same pattern, computing the SSD error metric for 4 offsets.
Each of the above 4 image processing instructions are limited to single-component formats.
Below is the pseudocode for GLSL built-in function
textureWindowBlockMatchSADQCOM.
The pseudocode for textureWindowBlockMatchSSD is identical other than
replacing all instances of "SAD" with "SSD".
vec4 textureBlockMatchWindowSAD( sampler2D target,
uvec2 targetCoord,
samler2D reference,
uvec2 refCoord,
uvec2 blocksize) {
// compareMode (MIN or MAX) comes from the vkSampler associated with `target`
// uvec2 window comes from the vkSampler associated with `target`
minSAD = INF;
maxSAD = -INF;
uvec2 minCoord;
uvec2 maxCoord;
for (uint x=0, x < window.width; x++) {
for (uint y=0; y < window.height; y++) {
float SAD = textureBlockMatchSAD(target,
targetCoord + uvec2(x, y),
reference,
refCoord,
blocksize).x;
// Note: the below comparison operator will produce undefined results
// if SAD is a denorm value.
if (SAD < minSAD) {
minSAD = SAD;
minCoord = uvec2(x,y);
}
if (SAD > maxSAD) {
maxSAD = SAD;
maxCoord = uvec2(x,y);
}
}
}
if (compareMode=MIN) {
return vec4(minSAD, minCoord.x, minCoord.y, 0.0);
} else {
return vec4(maxSAD, maxCoord.x, maxCoord.y, 0.0);
}
}
Below is the pseudocode for textureBlockMatchGatherSADQCOM.
The pseudocode for textureBlockMatchGatherSSD follows an identical
pattern.
vec4 textureBlockMatchGatherSAD( sampler2D target,
uvec2 targetCoord,
samler2D reference,
uvec2 refCoord,
uvec2 blocksize) {
vec4 out;
for (uint x=0, x<4; x++) {
float SAD = textureBlockMatchSAD(target,
targetCoord + uvec2(x, 0),
reference,
refCoord,
blocksize).x;
out[x] = SAD;
}
return out;
}
New Enum Constants
-
VK_QCOM_IMAGE_PROCESSING_2_EXTENSION_NAME -
VK_QCOM_IMAGE_PROCESSING_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_2_FEATURES_QCOM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_PROCESSING_2_PROPERTIES_QCOM -
VK_STRUCTURE_TYPE_SAMPLER_BLOCK_MATCH_WINDOW_CREATE_INFO_QCOM
-
Issues
1) What is the precision of the min/max comparison checks?
RESOLVED: Intermediate computations for the new operations are performed
at 16-bit floating-point precision.
If the value of "float SAD" in the above code sample is a 16-bit denorm
value, then behavior of the MIN/MAX comparison is undefined.
VK_QCOM_multiview_per_view_render_areas
- Name String
-
VK_QCOM_multiview_per_view_render_areas - Extension Type
-
Device extension
- Registered Extension Number
-
511
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2023-01-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension interacts with
VK_KHR_dynamic_rendering -
This extension interacts with
VK_QCOM_render_pass_transform
-
- Contributors
-
-
Jeff Leger, Qualcomm
-
Jonathan Tinkham, Qualcomm
-
Jonathan Wicks, Qualcomm
-
Description
Certain use cases (e.g., side-by-side VR rendering) use multiview and render to distinct regions of the framebuffer for each view. On some implementations, there may be a performance benefit for providing per-view render areas to the implementation. Such per-view render areas can be used by the implementation to reduce the pixels that are affected by attachment load, store, and multisample resolve operations.
The extension enables a multiview render pass instance to define per-view render areas. For each view of a multiview render pass instance, only those pixels in the per-view render area are affected by load, store and resolve operations.
New Enum Constants
-
VK_QCOM_MULTIVIEW_PER_VIEW_RENDER_AREAS_EXTENSION_NAME -
VK_QCOM_MULTIVIEW_PER_VIEW_RENDER_AREAS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_RENDER_AREAS_RENDER_PASS_BEGIN_INFO_QCOM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PER_VIEW_RENDER_AREAS_FEATURES_QCOM
-
Issues
1) Do the per-view renderAreas interact with
vkGetRenderAreaGranularity ?
RESOLVED: There is no change.
The granularity returned by vkGetRenderAreaGranularity also applies to
the per-view renderAreas.
2) How does this extension interact with
VK_QCOM_render_pass_transform?
RESOLVED: When VK_QCOM_render_pass_transform is enabled, the
application provides render area in non-rotated coordinates which is rotated
by the implementation to the rotated coordinate system.
When this extension is used in combination with
VK_QCOM_render_pass_transform, then the renderArea provided
in VkRenderingInfo::renderArea,
VkRenderPassBeginInfo::renderArea, or
VkCommandBufferInheritanceRenderPassTransformInfoQCOM::renderArea
is rotated by the implementation.
The per-view render areas are not rotated.
3) How does this extension interact with
VK_QCOM_multiview_per_view_viewports
RESOLVED: There is no direct interaction. The per-view viewports and the per-view renderAreas are orthogonal features.
4) When a per-view renderArea is specified, must multiview rendering
for each view of a multiview render pass be contained within the per-view
renderArea?
RESOLVED: Yes, and the VK_QCOM_multiview_per_view_viewports may
help here since it provides per-view scissors.
5) When per-view render areas are specified, what purpose if any do
VkRenderPassBeginInfo::renderArea and
VkRenderingInfo::renderArea serve?
RESOLVED: The per-view renderArea effectively overrides the
per-renderpass renderArea.
The per-view renderArea defines the regions of the attachments that
are effected by load, store, and multisample resolve operations.
A valid implementation could ignore the per-renderpass renderArea.
However, as an aid to the implementation, the application must set the
per-renderpass renderArea to an area that is at least as large as the
union of all the per-view render areas.
Pixels that are within the per-renderpass renderArea but not within
any per-view render area must not be affected by load, store, or multisample
resolve operations.
VK_QCOM_multiview_per_view_viewports
- Name String
-
VK_QCOM_multiview_per_view_viewports - Extension Type
-
Device extension
- Registered Extension Number
-
489
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2022-11-22
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension interacts with
VK_KHR_dynamic_rendering -
This extension interacts with
VK_EXT_extended_dynamic_state
-
- Contributors
-
-
Jeff Leger, Qualcomm
-
Jonathan Tinkham, Qualcomm
-
Jonathan Wicks, Qualcomm
-
Description
Certain use cases for multiview have a need for specifying a separate
viewport and scissor for each view, without using shader-based viewport
indexing as introduced with VK_EXT_shader_viewport_index_layer.
This extension adds a new way to control ViewportIndex with multiview.
When the multiviewPerViewViewports feature is enabled and if the last
pre-rasterization shader entry point’s interface does not use the
ViewportIndex built-in decoration, then each view of a multiview render
pass instance will use a viewport and scissor index equal to the
ViewIndex.
New Enum Constants
-
VK_QCOM_MULTIVIEW_PER_VIEW_VIEWPORTS_EXTENSION_NAME -
VK_QCOM_MULTIVIEW_PER_VIEW_VIEWPORTS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_PER_VIEW_VIEWPORTS_FEATURES_QCOM
-
Issues
1) Is it possible to enable/disable the
multiviewPerViewViewports
feature for individual render pass instances?
RESOLVED: No, when the multiviewPerViewViewports feature is enabled during
vkCreateDevice, then all created render pass instances (including dynamic
render passes from VK_KHR_dynamic_rendering) and all created
VkPipelines will have the feature enabled.
This approach was chosen because it simplifies application code and there is
no known use case to enable/disable the feature for individual render passes
or pipelines.
2) When this extension is used, is the value of ViewportIndex
implicitly written by the last pre-rasterization shader stage and can the
value of ViewportIndex be read in the fragment shader?
RESOLVED: No, use of the extension does not add an implicit write to
ViewportIndex in any shader stage, and additionally, the value of
ViewportIndex in the fragment shader is undefined.
VK_QCOM_render_pass_shader_resolve
- Name String
-
VK_QCOM_render_pass_shader_resolve - Extension Type
-
Device extension
- Registered Extension Number
-
172
- Revision
-
4
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2020-03-25
- Contributors
-
-
Bill Licea-Kane, Qualcomm Technologies, Inc.
-
Description
Render pass 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
-
VK_QCOM_render_pass_transform
- Name String
-
VK_QCOM_render_pass_transform - Extension Type
-
Device extension
- Registered Extension Number
-
283
- Revision
-
5
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2025-06-30
- Interactions and External Dependencies
-
-
This extension interacts with
VK_KHR_swapchain -
This extension interacts with
VK_KHR_surface -
This extension interacts with
VK_EXT_fragment_density_map -
This extension interacts with
VK_KHR_fragment_shading_rate -
This extension interacts with
VK_QCOM_tile_properties
-
- Contributors
-
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Brandon Light, Qualcomm Technologies, Inc.
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Arpit Agarwal, Qualcomm Technologies, Inc.
-
Žiga Markuš, LunarG, 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) does not 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. -
If this extension is used with
VK_QCOM_tile_properties, then vkGetFramebufferTilePropertiesQCOM and vkGetDynamicRenderingTilePropertiesQCOM return tile properties in the rotated coordinate space.
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 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 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
-
-
Revision 3, 2022-07-11 (Arpit Agarwal)
-
Adds interactions with VK_QCOM_tile_properties
-
-
Revision 4, 2023-12-13 (Matthew Netsch)
-
Relax dependencies on VK_KHR_surface and VK_KHR_swapchain
-
-
Revision 5, 2025-06-30 (Matthew Netsch)
-
Fix pNext const on info structs
-
VK_QCOM_rotated_copy_commands
- Name String
-
VK_QCOM_rotated_copy_commands - Extension Type
-
Device extension
- Registered Extension Number
-
334
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2023-12-13
- Interactions and External Dependencies
-
-
This extension interacts with
VK_KHR_swapchain -
This extension interacts with
VK_KHR_surface
-
- Contributors
-
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Matthew Netsch, 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_QCOM_tile_memory_heap
- Name String
-
VK_QCOM_tile_memory_heap - Extension Type
-
Device extension
- Registered Extension Number
-
548
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_QCOM_tile_properties
-
- Contact
-
-
Patrick Boyle [GitHub]pboyleQCOM
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-05-05
- Interactions and External Dependencies
-
-
Interacts with
VK_QCOM_tile_properties -
Interacts with
VK_QCOM_tile_shading
-
- Contributors
-
-
Patrick Boyle, Qualcomm Technologies, Inc.
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Srihari Babu Alla, Qualcomm Technologies, Inc.
-
Kevin Matlage, Qualcomm Technologies, Inc.
-
Description
This extension adds a new memory heap which allows applications to allocate
and manage tile memory.
A tile memory heap is denoted by the new
VK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOM property.
Memory contents within this heap behave differently than other heaps and
only persist its memory contents within a command buffer submission batch
boundary.
This boundary may be extended to a queue submit boundary by querying
queueSubmitBoundary in the new
VkPhysicalDeviceTileMemoryHeapPropertiesQCOM structure.
Tile memory from this heap can be bound to VkImages or VkBuffers.
The following new usage flags VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM,
VK_BUFFER_USAGE_TILE_MEMORY_BIT_QCOM,
VK_BUFFER_USAGE_2_TILE_MEMORY_BIT_QCOM were added for this.
A new extended structure is added to get memory requirements for tile memory
VkTileMemoryRequirementsQCOM.
A new command is added to bind tile memory to a command buffer in order to access and persist tile memory contents while executing commands vkCmdBindTileMemoryQCOM.
This extension can be used in combination with VK_QCOM_tile_properties with the new structure VkTileMemorySizeInfoQCOM.
New Structures
-
Extending VkCommandBufferInheritanceInfo:
-
Extending VkMemoryRequirements2:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
If VK_QCOM_tile_properties is supported:
New Enum Constants
-
VK_QCOM_TILE_MEMORY_HEAP_EXTENSION_NAME -
VK_QCOM_TILE_MEMORY_HEAP_SPEC_VERSION -
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_TILE_MEMORY_BIT_QCOM
-
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_TILE_MEMORY_BIT_QCOM
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM
-
-
Extending VkMemoryHeapFlagBits:
-
VK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_MEMORY_HEAP_FEATURES_QCOM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_MEMORY_HEAP_PROPERTIES_QCOM -
VK_STRUCTURE_TYPE_TILE_MEMORY_BIND_INFO_QCOM -
VK_STRUCTURE_TYPE_TILE_MEMORY_REQUIREMENTS_QCOM
-
If VK_QCOM_tile_properties is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_TILE_MEMORY_SIZE_INFO_QCOM
-
VK_QCOM_tile_properties
- Name String
-
VK_QCOM_tile_properties - Extension Type
-
Device extension
- Registered Extension Number
-
485
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_KHR_dynamic_rendering
-
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-07-11
- Interactions and External Dependencies
-
-
This extension interacts with
VK_EXT_subpass_merge_feedback
-
- Contributors
-
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Jonathan Tinkham, Qualcomm Technologies, Inc.
-
Arpit Agarwal, Qualcomm Technologies, Inc.
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Description
This extension allows an application to query the tile properties. This extension supports both renderpasses and dynamic rendering.
New Enum Constants
-
VK_QCOM_TILE_PROPERTIES_EXTENSION_NAME -
VK_QCOM_TILE_PROPERTIES_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_PROPERTIES_FEATURES_QCOM -
VK_STRUCTURE_TYPE_TILE_PROPERTIES_QCOM
-
VK_QCOM_tile_shading
- Name String
-
VK_QCOM_tile_shading - Extension Type
-
Device extension
- Registered Extension Number
-
310
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2025-5-12
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension interacts with
VK_KHR_dynamic_rendering -
This extension interacts with
VK_EXT_transform_feedback -
This extension interacts with
VK_EXT_debug_marker -
This extension interacts with
VK_EXT_attachment_feedback_loop_layout -
This extension interacts with
VK_KHR_dynamic_rendering_local_read -
This extension interacts with
VK_QCOM_image_processing
-
- Contributors
-
-
Jeff Leger, Qualcomm
-
Matt Netsch, Qualcomm
-
Srihari Babu Alla, Qualcomm
-
Matthew Smith, Qualcomm
-
Kevin Matlage, Qualcomm
-
Alex Bourd, Qualcomm
-
Description
This extension exposes tile shading in Vulkan. Many mobile GPUs utilize Tile-Based Deferred Rendering (TBDR) to optimize for power and performance. Conversely, most desktop GPUs use immediate-mode rendering (IM). Adreno ™ GPUs uniquely have the ability to operate in either mode, and when this extension is not enabled, the Adreno driver will select the most optimal mode (TBDR or IM) based on the workload; this feature is called FlexRender ™. When this extension is in use, FlexRender is disabled and the GPU operates exclusively in TBDR wherever possible.
The TBDR mode divides the color and depth/stencil buffer attachments into a regular grid of smaller regions called "tiles". When a render pass instance is submitted for execution on an Adreno GPU, the rendering is split into two phases: a single "visibility pass" followed by multiple "rendering passes" where a separate render pass is issued for each tile in the framebuffer.
The "visibility pass" processes the geometry: identifies which tiles are covered by each primitive, eliminates occluded primitives and unneeded state changes, and performs other tile-specific optimizations. The primitive coverage information collected during the visibility pass is used in the subsequent "rendering pass" for each tile. During the rendering pass for each tile, any primitives that were determined not to cover the current tile are skipped.
This deferred rasterization additionally utilizes a specialized high-bandwidth on-die memory, "tile memory". Tile memory is dramatically more efficient than other device memory. The tile memory temporarily stores the color and other attachments for each tile during rasterization. After each tile is fully rasterized, the resulting tile is typically copied to device memory backing the attachment as specified by the render pass STORE_OP. The per-tile rendering passes occur independently for each tile, with multiple tiles potentially being processed in parallel.
This extension enables applications to leverage the power and performance of tile memory in new ways:
-
Adds a mechanism for recording dispatches or draws that are guaranteed to be executed per-tile.
-
Such draws bypass the above-mentioned visibility-based skipping and are guaranteed to be executed for every tile in the rendering pass.
-
Shaders can declare "tile attachments" variables, providing shader access to color, depth/stencil, and input attachment pixels.
-
Fragment and compute shaders can read these render pass attachments at any location within the tile. Compute shaders can also write to color attachments at any location within the tile.
-
Shaders can use new built-in variables that provide the location, size, and apron region of the tile.
-
A new tile dispatch command automatically scales workgroup sizes and counts to the tile size, given a desired shading rate.
-
Framebuffer-local dependencies are expanded to tile-sized regions, rather than a single pixel or sample.
-
A tile shading render pass can also enable tiling "aprons". This is a specialized rendering mode where the GPU renders overlapping tiles that enable specific use-cases.
New Enum Constants
-
VK_QCOM_TILE_SHADING_EXTENSION_NAME -
VK_QCOM_TILE_SHADING_SPEC_VERSION -
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_SHADER_TILE_ATTACHMENT_READ_BIT_QCOM -
VK_ACCESS_2_SHADER_TILE_ATTACHMENT_WRITE_BIT_QCOM
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPATCH_TILE_INFO_QCOM -
VK_STRUCTURE_TYPE_PER_TILE_BEGIN_INFO_QCOM -
VK_STRUCTURE_TYPE_PER_TILE_END_INFO_QCOM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_SHADING_FEATURES_QCOM -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TILE_SHADING_PROPERTIES_QCOM -
VK_STRUCTURE_TYPE_RENDER_PASS_TILE_SHADING_CREATE_INFO_QCOM
-
-
Extending VkSubpassDescriptionFlagBits:
-
VK_SUBPASS_DESCRIPTION_TILE_SHADING_APRON_BIT_QCOM
-
VK_QCOM_ycbcr_degamma
- Name String
-
VK_QCOM_ycbcr_degamma - Extension Type
-
Device extension
- Registered Extension Number
-
521
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2023-07-31
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
None
- Contributors
-
-
Jeff Leger, Qualcomm
-
Jonathan Wicks, Qualcomm
-
Description
This extension allows implementations to expose support for “sRGB EOTF” also known as “sRGB degamma”, used in combination with images using 8-bit Y′CBCR formats. In addition, the degamma can be selectively applied to the Y (luma) or CrCb (chroma).
VK_KHR_sampler_ycbcr_conversion adds support for Y′CBCR
conversion, but allows texture sampling in a non-linear space which can
cause artifacts.
This extension allows implementations to expose sRGB degamma for Y′CBCR
formats, which is performed during texture filtering, allowing texture
filtering to operate in a linear space.
New Enum Constants
-
VK_QCOM_YCBCR_DEGAMMA_EXTENSION_NAME -
VK_QCOM_YCBCR_DEGAMMA_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_DEGAMMA_FEATURES_QCOM -
VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_YCBCR_DEGAMMA_CREATE_INFO_QCOM
-
Issues
1) Which Y′CBCR formats support the degamma feature?
RESOLVED: For implementations that support the extension, each format that
contains 8-bit R, G, and B components and supports either
VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or
VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT must support degamma.
Since non-compressed Vulkan sRGB formats are already limited to 8-bit components, and since Adreno supports degamma for all 8bit Y′CBCR formats, this extension does not introduce a new VK_FORMAT_FEATURE* bit for the degamma feature.
2) On which Y′CBCR components is the degamma applied?
RESOLVED: While degamma is expected to be applied to only the Y (luma) component, the extension provides the ability to selectively enable degamma for both the Y (luma) and/or CbCr (chroma) components.
3) Should degamma be enabled for the sampler object or for the image view object?
RESOLVED: Both. This extension extends VkSamplerYcbcrConversionCreateInfo and the specification already requires that both sampler and view objects must be created with an identical VkSamplerYcbcrConversionCreateInfo in their pNext chains.
4) Why apply the “sRGB” transfer function directly to Y′CBCR data when it would be more correct to use the “ITU transfer function”, and do so only after the values have been converted into non-linear R’G’B'?
RESOLVED: Y′CBCR is frequently stored according to standards (e.g. BT.601
and BT.709) that specify that the conversion between linear and non-linear
should use the ITU Transfer function.
The ITU transfer function is mathematically different from the sRGB transfer
function and while sRGB and ITU define similar curves, the difference is
significant.
Performing the “sRGB degamma” prior to range expansion can introduce
artifacts if the content uses VK_SAMPLER_YCBCR_RANGE_ITU_NARROW
encoding.
Nevertheless, using sRGB can make sense for certain use cases where camera
YCbCr images are known to be encoded with sRGB (or a pure gamma 2.2)
transfer function and are known to use full-range encoding.
For those use cases, this extension leverages the GPU ability to enable sRGB degamma at little cost, and can improve quality because texture filtering is able to occur in linear space.
VK_QNX_external_memory_screen_buffer
- Name String
-
VK_QNX_external_memory_screen_buffer - Extension Type
-
Device extension
- Registered Extension Number
-
530
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Mike Gorchak [GitHub]mgorchak-blackberry
-
Aaron Ruby [GitHub]aruby-blackberry
-
Other Extension Metadata
- Last Modified Date
-
2023-05-17
- IP Status
-
No known IP claims.
- Contributors
-
-
Mike Gorchak, QNX / Blackberry Limited
-
Aaron Ruby, QNX / Blackberry Limited
-
Description
This extension enables an application to import QNX Screen
_screen_buffer objects created outside of the Vulkan device into Vulkan
memory objects, where they can be bound to images and buffers.
Some _screen_buffer 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.
_screen_buffer is strongly typed, so naming the handle type is
redundant.
The internal layout and therefore size of a _screen_buffer image may
depend on native usage flags that do not have corresponding Vulkan
counterparts.
New Structures
-
Extending VkImageCreateInfo, VkSamplerYcbcrConversionCreateInfo:
-
Extending VkMemoryAllocateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkScreenBufferPropertiesQNX:
New Enum Constants
-
VK_QNX_EXTERNAL_MEMORY_SCREEN_BUFFER_EXTENSION_NAME -
VK_QNX_EXTERNAL_MEMORY_SCREEN_BUFFER_SPEC_VERSION -
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_QNX -
VK_STRUCTURE_TYPE_IMPORT_SCREEN_BUFFER_INFO_QNX -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_SCREEN_BUFFER_FEATURES_QNX -
VK_STRUCTURE_TYPE_SCREEN_BUFFER_FORMAT_PROPERTIES_QNX -
VK_STRUCTURE_TYPE_SCREEN_BUFFER_PROPERTIES_QNX
-
VK_QNX_screen_surface
- Name String
-
VK_QNX_screen_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
379
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Mike Gorchak [GitHub]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_SEC_amigo_profiling
- Name String
-
VK_SEC_amigo_profiling - Extension Type
-
Device extension
- Registered Extension Number
-
486
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Ralph Potter [GitLab]r_potter
-
Other Extension Metadata
- Last Modified Date
-
2022-07-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Ralph Potter, Samsung
-
Sangrak Oh, Samsung
-
Jinku Kang, Samsung
-
Description
This extension is intended to communicate information from layered API implementations such as ANGLE to internal proprietary system schedulers. It has no behavioral implications beyond enabling more intelligent behavior from the system scheduler.
Application developers should avoid using this extension.
It is documented solely for the benefit of tools and layer developers, who
may need to manipulate pNext chains that include these structures.
|
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_SEC_AMIGO_PROFILING_EXTENSION_NAME -
VK_SEC_AMIGO_PROFILING_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_AMIGO_PROFILING_SUBMIT_INFO_SEC -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_AMIGO_PROFILING_FEATURES_SEC
-
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_SEC_amigo_profiling
typedef struct VkPhysicalDeviceAmigoProfilingFeaturesSEC {
VkStructureType sType;
void* pNext;
VkBool32 amigoProfiling;
} VkPhysicalDeviceAmigoProfilingFeaturesSEC;
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_SEC_amigo_profiling
typedef struct VkAmigoProfilingSubmitInfoSEC {
VkStructureType sType;
const void* pNext;
uint64_t firstDrawTimestamp;
uint64_t swapBufferTimestamp;
} VkAmigoProfilingSubmitInfoSEC;
VK_SEC_pipeline_cache_incremental_mode
- Name String
-
VK_SEC_pipeline_cache_incremental_mode - Extension Type
-
Device extension
- Registered Extension Number
-
638
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Contact
-
-
Chris Hambacher [GitHub]chambacher
-
Other Extension Metadata
- Last Modified Date
-
2025-06-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Chris Hambacher, Samsung
-
Mohan Maiya, Samsung
-
Brandon Schade, Samsung
-
Description
This extension allows layered implementations such as ANGLE to modify the default behavior of VkPipelineCache to return only the incremental data from the previous call to vkGetPipelineCacheData. Application developers should avoid using this extension.
|
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_SEC_PIPELINE_CACHE_INCREMENTAL_MODE_EXTENSION_NAME -
VK_SEC_PIPELINE_CACHE_INCREMENTAL_MODE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CACHE_INCREMENTAL_MODE_FEATURES_SEC
-
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_SEC_pipeline_cache_incremental_mode
typedef struct VkPhysicalDevicePipelineCacheIncrementalModeFeaturesSEC {
VkStructureType sType;
void* pNext;
VkBool32 pipelineCacheIncrementalMode;
} VkPhysicalDevicePipelineCacheIncrementalModeFeaturesSEC;
VK_VALVE_descriptor_set_host_mapping
- Name String
-
VK_VALVE_descriptor_set_host_mapping - Extension Type
-
Device extension
- Registered Extension Number
-
421
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Special Use
- Contact
-
-
Hans-Kristian Arntzen [GitHub]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_fragment_density_map_layered
- Name String
-
VK_VALVE_fragment_density_map_layered - Extension Type
-
Device extension
- Registered Extension Number
-
612
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Contact
-
-
Connor Abbott [GitHub]cwabbott0
-
Other Extension Metadata
- Last Modified Date
-
2025-06-06
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1.
-
Interacts with Vulkan 1.3.
-
Interacts with Vulkan 1.4.
-
Interacts with
VK_EXT_fragment_density_map.
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Connor Abbott, VALVE
-
Mike Blumenkrantz, VALVE
-
New Enum Constants
-
VK_VALVE_FRAGMENT_DENSITY_MAP_LAYERED_EXTENSION_NAME -
VK_VALVE_FRAGMENT_DENSITY_MAP_LAYERED_SPEC_VERSION -
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVE
-
-
Extending VkRenderingFlagBits:
-
VK_RENDERING_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVE
-
-
Extending VkRenderPassCreateFlagBits:
-
VK_RENDER_PASS_CREATE_PER_LAYER_FRAGMENT_DENSITY_BIT_VALVE
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_LAYERED_FEATURES_VALVE -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_LAYERED_PROPERTIES_VALVE -
VK_STRUCTURE_TYPE_PIPELINE_FRAGMENT_DENSITY_MAP_LAYERED_CREATE_INFO_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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
-
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 [GitHub]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 behavior 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 capabilities, 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_AMDX_shader_enqueue
- Name String
-
VK_AMDX_shader_enqueue - Extension Type
-
Device extension
- Registered Extension Number
-
135
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
-
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- API Interactions
-
-
Interacts with VK_VERSION_1_4
-
Interacts with VK_EXT_mesh_shader
-
Interacts with VK_KHR_maintenance5
-
- SPIR-V Dependencies
- Contact
-
-
Tobias Hector [GitHub]tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-07-17
- Provisional
-
This extension is provisional and should not be used in production applications. The functionality may change in ways that break backwards compatibility between revisions, and before final release.
- Contributors
-
-
Tobias Hector, AMD
-
Matthaeus Chajdas, AMD
-
Maciej Jesionowski, AMD
-
Robert Martin, AMD
-
Qun Lin, AMD
-
Rex Xu, AMD
-
Dominik Witczak, AMD
-
Karthik Srinivasan, AMD
-
Nicolai Haehnle, AMD
-
Stuart Smith, AMD
-
Description
This extension adds the ability for developers to enqueue mesh and compute shader workgroups from other compute shaders.
New Enum Constants
-
VK_AMDX_SHADER_ENQUEUE_EXTENSION_NAME -
VK_AMDX_SHADER_ENQUEUE_SPEC_VERSION -
VK_SHADER_INDEX_UNUSED_AMDX -
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_EXECUTION_GRAPH_SCRATCH_BIT_AMDX
-
-
Extending VkPipelineBindPoint:
-
VK_PIPELINE_BIND_POINT_EXECUTION_GRAPH_AMDX
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXECUTION_GRAPH_PIPELINE_CREATE_INFO_AMDX -
VK_STRUCTURE_TYPE_EXECUTION_GRAPH_PIPELINE_SCRATCH_SIZE_AMDX -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ENQUEUE_FEATURES_AMDX -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ENQUEUE_PROPERTIES_AMDX -
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_NODE_CREATE_INFO_AMDX
-
If VK_KHR_maintenance5 or Vulkan Version 1.4 is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_EXECUTION_GRAPH_SCRATCH_BIT_AMDX
-
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDX
-
VK_NV_cuda_kernel_launch
- Name String
-
VK_NV_cuda_kernel_launch - Extension Type
-
Device extension
- Registered Extension Number
-
308
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
-
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- API Interactions
-
-
Interacts with VK_EXT_debug_report
-
- Contact
-
-
Tristan Lorach [GitHub]tlorach
-
Description
Interoperability between APIs can sometimes create additional overhead depending on the platform used. This extension targets deployment of existing CUDA kernels via Vulkan, with a way to directly upload PTX kernels and dispatch the kernels from Vulkan’s command buffer without the need to use interoperability between the Vulkan and CUDA contexts. However, we do encourage actual development using the native CUDA runtime for the purpose of debugging and profiling.
The application will first have to create a CUDA module using vkCreateCudaModuleNV then create the CUDA function entry point with vkCreateCudaFunctionNV.
Then in order to dispatch this function, the application will create a command buffer where it will launch the kernel with vkCmdCudaLaunchKernelNV.
When done, the application will then destroy the function handle, as well as the CUDA module handle with vkDestroyCudaFunctionNV and vkDestroyCudaModuleNV.
To reduce the impact of compilation time, this extension offers the
capability to return a binary cache from the PTX that was provided.
For this, a first query for the required cache size is made with
vkGetCudaModuleCacheNV with a NULL pointer to a buffer and with a
valid pointer receiving the size; then another call of the same function
with a valid pointer to a buffer to retrieve the data.
The resulting cache could then be used later for further runs of this
application by sending this cache instead of the PTX code (using the same
vkCreateCudaModuleNV), thus significantly speeding up the
initialization of the CUDA module.
As with VkPipelineCache, the binary cache depends on the hardware architecture. The application must assume the cache might fail, and need to handle falling back to the original PTX code as necessary. Most often, the cache will succeed if the same GPU driver and architecture is used between the cache generation from PTX and the use of this cache. In the event of a new driver version, or if using a different GPU architecture, the cache is likely to become invalid.
New Enum Constants
-
VK_NV_CUDA_KERNEL_LAUNCH_EXTENSION_NAME -
VK_NV_CUDA_KERNEL_LAUNCH_SPEC_VERSION -
Extending VkObjectType:
-
VK_OBJECT_TYPE_CUDA_FUNCTION_NV -
VK_OBJECT_TYPE_CUDA_MODULE_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CUDA_FUNCTION_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_CUDA_LAUNCH_INFO_NV -
VK_STRUCTURE_TYPE_CUDA_MODULE_CREATE_INFO_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_PROPERTIES_NV
-
If VK_EXT_debug_report is supported:
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_CUDA_FUNCTION_NV_EXT -
VK_DEBUG_REPORT_OBJECT_TYPE_CUDA_MODULE_NV_EXT
-
VK_NV_present_metering
- Name String
-
VK_NV_present_metering - Extension Type
-
Device extension
- Registered Extension Number
-
614
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
-
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Contact
-
-
Charles Hansen [GitHub]chansen
-
Other Extension Metadata
- Last Modified Date
-
2025-01-08
- Provisional
-
*This extension is provisional and should not be used in production applications. The functionality defined by this extension may change in ways that break backwards compatibility between revisions, and before the final release of the non-provisional version of this extension.
- Contributors
-
-
Charles Hansen, NVIDIA
-
Lionel Duc, NVIDIA
-
New Enum Constants
-
VK_NV_PRESENT_METERING_EXTENSION_NAME -
VK_NV_PRESENT_METERING_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_METERING_FEATURES_NV -
VK_STRUCTURE_TYPE_SET_PRESENT_CONFIG_NV
-
List of Deprecated Extensions
-
VK_KHR_16bit_storage (promoted to core)
-
VK_KHR_8bit_storage (promoted to core)
-
VK_KHR_bind_memory2 (promoted to core)
-
VK_KHR_buffer_device_address (promoted to core)
-
VK_KHR_copy_commands2 (promoted to core)
-
VK_KHR_create_renderpass2 (promoted to core)
-
VK_KHR_dedicated_allocation (promoted to core)
-
VK_KHR_depth_stencil_resolve (promoted to core)
-
VK_KHR_descriptor_update_template (promoted to core)
-
VK_KHR_device_group (promoted to core)
-
VK_KHR_device_group_creation (promoted to core)
-
VK_KHR_draw_indirect_count (promoted to core)
-
VK_KHR_driver_properties (promoted to core)
-
VK_KHR_dynamic_rendering (promoted to core)
-
VK_KHR_dynamic_rendering_local_read (promoted to core)
-
VK_KHR_external_fence (promoted to core)
-
VK_KHR_external_fence_capabilities (promoted to core)
-
VK_KHR_external_memory (promoted to core)
-
VK_KHR_external_memory_capabilities (promoted to core)
-
VK_KHR_external_semaphore (promoted to core)
-
VK_KHR_external_semaphore_capabilities (promoted to core)
-
VK_KHR_format_feature_flags2 (promoted to core)
-
VK_KHR_get_memory_requirements2 (promoted to core)
-
VK_KHR_get_physical_device_properties2 (promoted to core)
-
VK_KHR_global_priority (promoted to core)
-
VK_KHR_image_format_list (promoted to core)
-
VK_KHR_imageless_framebuffer (promoted to core)
-
VK_KHR_index_type_uint8 (promoted to core)
-
VK_KHR_line_rasterization (promoted to core)
-
VK_KHR_load_store_op_none (promoted to core)
-
VK_KHR_maintenance1 (promoted to core)
-
VK_KHR_maintenance2 (promoted to core)
-
VK_KHR_maintenance3 (promoted to core)
-
VK_KHR_maintenance4 (promoted to core)
-
VK_KHR_maintenance5 (promoted to core)
-
VK_KHR_maintenance6 (promoted to core)
-
VK_KHR_map_memory2 (promoted to core)
-
VK_KHR_multiview (promoted to core)
-
VK_KHR_push_descriptor (promoted to core)
-
VK_KHR_relaxed_block_layout (promoted to core)
-
VK_KHR_sampler_mirror_clamp_to_edge (promoted to core)
-
VK_KHR_sampler_ycbcr_conversion (promoted to core)
-
VK_KHR_separate_depth_stencil_layouts (promoted to core)
-
VK_KHR_shader_atomic_int64 (promoted to core)
-
VK_KHR_shader_draw_parameters (promoted to core)
-
VK_KHR_shader_expect_assume (promoted to core)
-
VK_KHR_shader_float16_int8 (promoted to core)
-
VK_KHR_shader_float_controls (promoted to core)
-
VK_KHR_shader_float_controls2 (promoted to core)
-
VK_KHR_shader_integer_dot_product (promoted to core)
-
VK_KHR_shader_non_semantic_info (promoted to core)
-
VK_KHR_shader_subgroup_extended_types (promoted to core)
-
VK_KHR_shader_subgroup_rotate (promoted to core)
-
VK_KHR_shader_terminate_invocation (promoted to core)
-
VK_KHR_spirv_1_4 (promoted to core)
-
VK_KHR_storage_buffer_storage_class (promoted to core)
-
VK_KHR_synchronization2 (promoted to core)
-
VK_KHR_timeline_semaphore (promoted to core)
-
VK_KHR_uniform_buffer_standard_layout (promoted to core)
-
VK_KHR_variable_pointers (promoted to core)
-
VK_KHR_vertex_attribute_divisor (promoted to core)
-
VK_KHR_vulkan_memory_model (promoted to core)
-
VK_KHR_zero_initialize_workgroup_memory (promoted to core)
-
VK_EXT_4444_formats (promoted to core)
-
VK_EXT_descriptor_indexing (promoted to core)
-
VK_EXT_extended_dynamic_state (promoted to core)
-
VK_EXT_extended_dynamic_state2 (promoted to core)
-
VK_EXT_host_image_copy (promoted to core)
-
VK_EXT_host_query_reset (promoted to core)
-
VK_EXT_image_robustness (promoted to core)
-
VK_EXT_inline_uniform_block (promoted to core)
-
VK_EXT_pipeline_creation_cache_control (promoted to core)
-
VK_EXT_pipeline_creation_feedback (promoted to core)
-
VK_EXT_pipeline_protected_access (promoted to core)
-
VK_EXT_pipeline_robustness (promoted to core)
-
VK_EXT_private_data (promoted to core)
-
VK_EXT_sampler_filter_minmax (promoted to core)
-
VK_EXT_scalar_block_layout (promoted to core)
-
VK_EXT_separate_stencil_usage (promoted to core)
-
VK_EXT_shader_demote_to_helper_invocation (promoted to core)
-
VK_EXT_shader_viewport_index_layer (promoted to core)
-
VK_EXT_subgroup_size_control (promoted to core)
-
VK_EXT_texel_buffer_alignment (promoted to core)
-
VK_EXT_texture_compression_astc_hdr (promoted to core)
-
VK_EXT_tooling_info (promoted to core)
-
VK_EXT_ycbcr_2plane_444_formats (promoted to core)
VK_KHR_16bit_storage
- Name String
-
VK_KHR_16bit_storage - Extension Type
-
Device extension
- Registered Extension Number
-
84
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jan-Harald Fredriksen [GitHub]janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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.
Promotion to Vulkan 1.4
If Vulkan 1.4 is supported, support for the storageBuffer16BitAccess
capability is required.
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Alexander Galazin [GitHub]alegal-arm
-
Other Extension Metadata
- Last Modified Date
-
2018-02-05
- Interactions and External Dependencies
-
-
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
Vulkan APIs in this extension are 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.
External interactions defined by this extension, such as SPIR-V token names,
retain their original names.
The original Vulkan API names are still available as aliases of the core
functionality.
Promotion to Vulkan 1.4
If Vulkan 1.4 is supported, support for the storageBuffer8BitAccess
capability is required.
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Tobias Hector [GitHub]tobski
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- 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
-
VK_KHR_buffer_device_address
- Name String
-
VK_KHR_buffer_device_address - Extension Type
-
Device extension
- Registered Extension Number
-
258
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-24
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
-
Faith 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.
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
If Vulkan 1.3 is supported, support for the bufferDeviceAddress
capability is required.
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
-
VK_KHR_copy_commands2
- Name String
-
VK_KHR_copy_commands2 - Extension Type
-
Device extension
- Registered Extension Number
-
338
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2020-07-06
- 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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the KHR suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Tobias Hector [GitHub]tobias
-
Description
This extension provides a new command 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 reference in VkAttachmentReference2KHR::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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones [GitHub]cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Faith 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 =
{
.sType = VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS_KHR,
.pNext = NULL,
};
VkMemoryRequirements2 memoryRequirements =
{
.sType = VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2,
.pNext = &dedicatedRequirements,
};
const VkImageMemoryRequirementsInfo2 imageRequirementsInfo =
{
.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2,
.pNext = NULL,
.image = 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 =
{
.sType = VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_KHR,
.pNext = NULL,
.image = image,
.buffer = VK_NULL_HANDLE,
};
VkMemoryAllocateInfo memoryAllocateInfo =
{
.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO,
.pNext = &dedicatedInfo,
.allocationSize = memoryRequirements.size,
.memoryTypeIndex = FindMemoryTypeIndex(memoryRequirements.memoryTypeBits),
};
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 (Faith Ekstrand)
-
Rework the extension to be query-based
-
-
Revision 3, 2017-07-31 (Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jan-Harald Fredriksen [GitHub]janharald
-
Other Extension Metadata
- Last Modified Date
-
2018-04-09
- 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- API Interactions
-
-
Interacts with VK_EXT_debug_report
-
Interacts with VK_KHR_push_descriptor
-
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Markus Tavenrath [GitHub]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
-
- 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 initialization 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 an application-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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_KHR_bind_memory2
-
Interacts with VK_KHR_surface
-
Interacts with VK_KHR_swapchain
-
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-10-10
- IP Status
-
No known IP claims.
- 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_BIT_KHR -
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2016-10-19
- IP Status
-
No known IP claims.
- 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2017-08-25
- 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 on 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 commands vkCmdDrawIndirectCount and vkCmdDrawIndexedIndirectCount are optional. The original type, enum, and command names are still available as aliases of the core functionality.
VK_KHR_driver_properties
- Name String
-
VK_KHR_driver_properties - Extension Type
-
Device extension
- Registered Extension Number
-
197
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Daniel Rakos [GitHub]drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2018-04-11
- 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Tobias Hector [GitHub]tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-10-06
- 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:
New Enum Constants
-
VK_KHR_DYNAMIC_RENDERING_EXTENSION_NAME -
VK_KHR_DYNAMIC_RENDERING_SPEC_VERSION -
Extending VkAttachmentStoreOp:
-
VK_ATTACHMENT_STORE_OP_NONE_KHR
-
-
Extending VkRenderingFlagBits:
-
VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR -
VK_RENDERING_RESUMING_BIT_KHR -
VK_RENDERING_SUSPENDING_BIT_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
-
Promotion to Vulkan 1.3
Vulkan APIs in this extension are included in core Vulkan 1.3, with the KHR suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API names are still available as aliases of the core functionality.
VK_KHR_dynamic_rendering_local_read
- Name String
-
VK_KHR_dynamic_rendering_local_read - Extension Type
-
Device extension
- Registered Extension Number
-
233
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Tobias Hector [GitHub]tobski
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-11-03
- Contributors
-
-
Tobias Hector, AMD
-
Hans-Kristian Arntzen, Valve
-
Connor Abbott, Valve
-
Pan Gao, Huawei
-
Lionel Landwerlin, Intel
-
Shahbaz Youssefi, Google
-
Alyssa Rosenzweig, Valve
-
Jan-Harald Fredriksen, Arm
-
Mike Blumenkrantz, Valve
-
Graeme Leese, Broadcom
-
Piers Daniell, Nvidia
-
Stuart Smith, AMD
-
Daniel Story, Nintendo
-
James Fitzpatrick, Imagination
-
Piotr Byszewski, Mobica
-
Spencer Fricke, LunarG
-
Tom Olson, Arm
-
Michal Pietrasiuk, Intel
-
Matthew Netsch, Qualcomm
-
Marty Johnson, Khronos
-
Wyvern Wang, Huawei
-
Jeff Bolz, Nvidia
-
Samuel (Sheng-Wen) Huang, MediaTek
-
Description
This extension enables reads from attachments and resources written by previous fragment shaders within a dynamic render pass.
New Enum Constants
-
VK_KHR_DYNAMIC_RENDERING_LOCAL_READ_EXTENSION_NAME -
VK_KHR_DYNAMIC_RENDERING_LOCAL_READ_SPEC_VERSION -
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_LOCAL_READ_FEATURES_KHR -
VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_LOCATION_INFO_KHR -
VK_STRUCTURE_TYPE_RENDERING_INPUT_ATTACHMENT_INDEX_INFO_KHR
-
Promotion to Vulkan 1.4
Functionality in this extension is included in core Vulkan 1.4, with the KHR suffix omitted. However, Vulkan 1.4 implementations only have to support local read for storage resources and single sampled color attachments.
Support for reading depth/stencil attachments and multi-sampled attachments
are respectively gated behind the new boolean
dynamicRenderingLocalReadDepthStencilAttachments and
dynamicRenderingLocalReadMultisampledAttachments properties, as
described in the Version 1.4 appendix.
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jesse Hall [GitHub]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
-
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jesse Hall [GitHub]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_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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones [GitHub]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.
-
- Contributors
-
-
Faith Ekstrand, Intel
-
Ian Elliott, 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
-
Lina 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.
Reusing 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 objects 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones [GitHub]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.
-
- Contributors
-
-
Ian Elliott, 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones [GitHub]cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Faith Ekstrand, Intel
-
Jesse Hall, Google
-
Tobias Hector, Imagination Technologies
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Ray Smith, ARM
-
Lina 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
James Jones [GitHub]cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-20
- IP Status
-
No known IP claims.
- 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
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_2
-
Interacts with VK_EXT_filter_cubic
-
Interacts with VK_EXT_sampler_filter_minmax
-
Interacts with VK_IMG_filter_cubic
-
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Lionel Landwerlin [GitHub]llandwerlin
-
Other Extension Metadata
- Last Modified Date
-
2021-07-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Lionel Landwerlin, Intel
-
Faith 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 command, 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_KHRspecify that an implementation supports reading and writing, respectively, a given VkFormat through storage operations without specifying the format in the shader. -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT_KHRspecifies 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.
Prior to version 2 of this extension, implementations exposing the
shaderStorageImageReadWithoutFormat and
shaderStorageImageWriteWithoutFormat features may not report
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHR and
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHR in
VkFormatProperties3KHR::bufferFeatures.
Despite this, buffer reads/writes are supported as intended by the original
features.
New Structures
-
Extending VkFormatProperties2:
New Enum Constants
-
VK_KHR_FORMAT_FEATURE_FLAGS_2_EXTENSION_NAME -
VK_KHR_FORMAT_FEATURE_FLAGS_2_SPEC_VERSION -
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_BLIT_DST_BIT_KHR -
VK_FORMAT_FEATURE_2_BLIT_SRC_BIT_KHR -
VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BIT_KHR -
VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BLEND_BIT_KHR -
VK_FORMAT_FEATURE_2_COSITED_CHROMA_SAMPLES_BIT_KHR -
VK_FORMAT_FEATURE_2_DEPTH_STENCIL_ATTACHMENT_BIT_KHR -
VK_FORMAT_FEATURE_2_DISJOINT_BIT_KHR -
VK_FORMAT_FEATURE_2_MIDPOINT_CHROMA_SAMPLES_BIT_KHR -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT_KHR -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT_KHR -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_LINEAR_BIT_KHR -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR -
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR -
VK_FORMAT_FEATURE_2_STORAGE_IMAGE_ATOMIC_BIT_KHR -
VK_FORMAT_FEATURE_2_STORAGE_IMAGE_BIT_KHR -
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHR -
VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_ATOMIC_BIT_KHR -
VK_FORMAT_FEATURE_2_STORAGE_TEXEL_BUFFER_BIT_KHR -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHR -
VK_FORMAT_FEATURE_2_TRANSFER_DST_BIT_KHR -
VK_FORMAT_FEATURE_2_TRANSFER_SRC_BIT_KHR -
VK_FORMAT_FEATURE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR -
VK_FORMAT_FEATURE_2_VERTEX_BUFFER_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FORMAT_PROPERTIES_3_KHR
-
If VK_EXT_filter_cubic or VK_IMG_filter_cubic is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
-
If Vulkan Version 1.2 or VK_EXT_sampler_filter_minmax is supported:
-
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_FILTER_MINMAX_BIT_KHR
-
Promotion to Vulkan 1.3
Vulkan APIs in this extension are included in core Vulkan 1.3, with the KHR suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Faith Ekstrand [GitHub]gfxstrand
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Contributors
-
-
Faith Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Jesse Hall, Google
-
Description
This extension provides new queries for memory requirements of images and
buffers that can be easily extended by other extensions, without introducing
any additional commands.
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Ian Elliott, Google
-
Description
This extension provides new queries for device features, device properties,
and format properties that can be easily extended by other extensions,
without introducing any further queries.
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 =
{
.sType = VK_STRUCTURE_TYPE_HYPOTHETICAL_FEATURES_KHR,
.pNext = NULL,
};
VkPhysicalDeviceFeatures2KHR features =
{
.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR,
.pNext = &hypotheticalFeatures,
};
// 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 =
{
.sType = VK_STRUCTURE_TYPE_HYPOTHETICAL_FEATURES_KHR,
.pNext = NULL,
};
VkPhysicalDeviceFeatures2KHR enabledFeatures =
{
.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2_KHR,
.pNext = &enabledHypotheticalFeatures,
};
enabledFeatures.features.xyz = VK_TRUE;
enabledHypotheticalFeatures.abc = VK_TRUE;
VkDeviceCreateInfo deviceCreateInfo =
{
.sType = VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO,
.pNext = &enabledFeatures,
...
.pEnabledFeatures = NULL,
};
VkDevice device;
vkCreateDevice(physicalDevice, &deviceCreateInfo, NULL, &device);
VK_KHR_global_priority
- Name String
-
VK_KHR_global_priority - Extension Type
-
Device extension
- Registered Extension Number
-
189
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Tobias Hector [GitHub]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 favor 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 VkQueueGlobalPriority:
-
VK_QUEUE_GLOBAL_PRIORITY_HIGH_KHR -
VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR -
VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR -
VK_QUEUE_GLOBAL_PRIORITY_REALTIME_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
-
Promotion to Vulkan 1.4
Functionality in this extension is included in core Vulkan 1.4 with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
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_image_format_list
- Name String
-
VK_KHR_image_format_list - Extension Type
-
Device extension
- Registered Extension Number
-
148
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Faith Ekstrand [GitHub]gfxstrand
-
Other Extension Metadata
- Last Modified Date
-
2017-03-20
- IP Status
-
No known IP claims.
- Contributors
-
-
Faith 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Tobias Hector [GitHub]tobias
-
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_index_type_uint8
- Name String
-
VK_KHR_index_type_uint8 - Extension Type
-
Device extension
- Registered Extension Number
-
534
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2023-06-06
- 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_KHR_INDEX_TYPE_UINT8_EXTENSION_NAME -
VK_KHR_INDEX_TYPE_UINT8_SPEC_VERSION -
Extending VkIndexType:
-
VK_INDEX_TYPE_UINT8_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_KHR
-
VK_KHR_line_rasterization
- Name String
-
VK_KHR_line_rasterization - Extension Type
-
Device extension
- Registered Extension Number
-
535
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2023-06-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Allen Jensen, NVIDIA
-
Faith 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_KHR_LINE_RASTERIZATION_EXTENSION_NAME -
VK_KHR_LINE_RASTERIZATION_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_LINE_STIPPLE_KHR
-
-
Extending VkLineRasterizationMode:
-
VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR -
VK_LINE_RASTERIZATION_MODE_DEFAULT_KHR -
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR -
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_KHR
-
Promotion to Vulkan 1.4
Functionality in this extension is included in core Vulkan 1.4 with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
When Version 1.4 is supported, the
bresenhamLines feature must be supported.
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_KHR_load_store_op_none
- Name String
-
VK_KHR_load_store_op_none - Extension Type
-
Device extension
- Registered Extension Number
-
527
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-05-16
- Contributors
-
-
Shahbaz Youssefi, Google
-
Bill Licea-Kane, Qualcomm Technologies, Inc.
-
Tobias Hector, AMD
-
Description
This extension provides VK_ATTACHMENT_LOAD_OP_NONE_KHR and
VK_ATTACHMENT_STORE_OP_NONE_KHR, which are identically promoted from
the VK_EXT_load_store_op_none extension.
New Enum Constants
-
VK_KHR_LOAD_STORE_OP_NONE_EXTENSION_NAME -
VK_KHR_LOAD_STORE_OP_NONE_SPEC_VERSION -
Extending VkAttachmentLoadOp:
-
VK_ATTACHMENT_LOAD_OP_NONE_KHR
-
-
Extending VkAttachmentStoreOp:
-
VK_ATTACHMENT_STORE_OP_NONE_KHR
-
Promotion to Vulkan 1.4
Functionality in this extension is included in core Vulkan 1.4 with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.
|
Note
|
While |
VK_KHR_maintenance1
- Name String
-
VK_KHR_maintenance1 - Extension Type
-
Device extension
- Registered Extension Number
-
70
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2018-03-13
- Contributors
-
-
Dan Ginsburg, Valve
-
Daniel Koch, NVIDIA
-
Daniel Rakos, AMD
-
Jan-Harald Fredriksen, ARM
-
Faith 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
-
VK_KHR_maintenance2
- Name String
-
VK_KHR_maintenance2 - Extension Type
-
Device extension
- Registered Extension Number
-
118
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Michael Worcester [GitHub]michaelworcester
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- 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 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2021-10-25
- Interactions and External Dependencies
-
-
Requires SPIR-V 1.2 for
LocalSizeId
-
- Contributors
-
-
Lionel Duc, NVIDIA
-
Faith 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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the KHR suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API names are still available as aliases of the core functionality.
VK_KHR_maintenance5
- Name String
-
VK_KHR_maintenance5 - Extension Type
-
Device extension
- Registered Extension Number
-
471
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_2
-
Interacts with VK_VERSION_1_3
-
Interacts with VK_VERSION_1_4
-
Interacts with VK_ARM_pipeline_opacity_micromap
-
Interacts with VK_EXT_attachment_feedback_loop_layout
-
Interacts with VK_EXT_buffer_device_address
-
Interacts with VK_EXT_conditional_rendering
-
Interacts with VK_EXT_descriptor_buffer
-
Interacts with VK_EXT_fragment_density_map
-
Interacts with VK_EXT_graphics_pipeline_library
-
Interacts with VK_EXT_opacity_micromap
-
Interacts with VK_EXT_pipeline_creation_cache_control
-
Interacts with VK_EXT_pipeline_protected_access
-
Interacts with VK_EXT_transform_feedback
-
Interacts with VK_KHR_acceleration_structure
-
Interacts with VK_KHR_buffer_device_address
-
Interacts with VK_KHR_dynamic_rendering
-
Interacts with VK_KHR_fragment_shading_rate
-
Interacts with VK_KHR_pipeline_executable_properties
-
Interacts with VK_KHR_pipeline_library
-
Interacts with VK_KHR_ray_tracing_pipeline
-
Interacts with VK_KHR_video_decode_queue
-
Interacts with VK_KHR_video_encode_queue
-
Interacts with VK_NV_device_generated_commands
-
Interacts with VK_NV_displacement_micromap
-
Interacts with VK_NV_ray_tracing
-
Interacts with VK_NV_ray_tracing_motion_blur
-
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Stu Smith [GitHub]stu-s
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-05-02
- Interactions and External Dependencies
- Contributors
-
-
Stu Smith, AMD
-
Tobias Hector, AMD
-
Shahbaz Youssefi, Google
-
Slawomir Cygan, Intel
-
Lionel Landwerlin, Intel
-
James Fitzpatrick, Imagination Technologies
-
Andrew Garrard, Imagination Technologies
-
Ralph Potter, Samsung
-
Pan Gao, Huawei
-
Jan-Harald Fredriksen, ARM
-
Jon Leech, Khronos
-
Mike Blumenkrantz, Valve
-
Description
VK_KHR_maintenance5 adds a collection of minor features, none of which
would warrant an entire extension of their own.
The new features are as follows:
-
A new
VK_FORMAT_A1B5G5R5_UNORM_PACK16_KHRformat -
A new
VK_FORMAT_A8_UNORM_KHRformat -
A property to indicate that multisample coverage operations are performed after sample counting in EarlyFragmentTests mode
-
Relax VkBufferView creation requirements by allowing subsets of the associated VkBuffer usage using
VkBufferUsageFlags2CreateInfoKHR -
A new command vkCmdBindIndexBuffer2KHR, allowing a range of memory to be bound as an index buffer
-
vkGetDeviceProcAddr must return
NULLfor supported core functions beyond the version requested by the application. -
A property to indicate that the sample mask test is performed after sample counting in EarlyFragmentTests mode
-
vkCmdBindVertexBuffers2now supports usingVK_WHOLE_SIZEin thepSizesparameter. -
A default size of 1.0 is used if
PointSizeis not written -
Shader modules are deprecated - applications can now pass VkShaderModuleCreateInfo as a chained structure to pipeline creation via VkPipelineShaderStageCreateInfo
-
A function vkGetRenderingAreaGranularityKHR to query the optimal render area for a dynamic rendering instance.
-
A property to indicate that depth/stencil texturing operations with
VK_COMPONENT_SWIZZLE_ONEhave defined behavior -
Add vkGetImageSubresourceLayout2KHR and a new function vkGetDeviceImageSubresourceLayoutKHR to allow the application to query the image memory layout without having to create an image object and query it.
-
Allow
VK_REMAINING_ARRAY_LAYERSas thelayerCountmember of VkImageSubresourceLayers -
Adds stronger guarantees for propagation of
VK_ERROR_DEVICE_LOSTreturn values -
A property to indicate whether
PointSizecontrols the final rasterization of polygons if polygon mode isVK_POLYGON_MODE_POINT -
Two properties to indicate the non-strict line rasterization algorithm used
-
Two new flags words VkPipelineCreateFlagBits2KHR and VkBufferUsageFlagBits2KHR
-
Physical-device-level functions can now be called with any value in the valid range for a type beyond the defined enumerants, such that applications can avoid checking individual features, extensions, or versions before querying supported properties of a particular enumerant.
-
Clarification that copies between images of any type are allowed, treating 1D images as 2D images with a height of 1.
New Structures
-
Extending VkBufferViewCreateInfo, VkBufferCreateInfo, VkPhysicalDeviceExternalBufferInfo, VkDescriptorBufferBindingInfoEXT:
-
Extending VkComputePipelineCreateInfo, VkGraphicsPipelineCreateInfo, VkRayTracingPipelineCreateInfoNV, VkRayTracingPipelineCreateInfoKHR:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
New Enum Constants
-
VK_KHR_MAINTENANCE_5_EXTENSION_NAME -
VK_KHR_MAINTENANCE_5_SPEC_VERSION -
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT_KHR -
VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT_KHR -
VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT_KHR -
VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT_KHR -
VK_BUFFER_USAGE_2_TRANSFER_DST_BIT_KHR -
VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT_KHR -
VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT_KHR -
VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR -
VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT_KHR
-
-
Extending VkFormat:
-
VK_FORMAT_A1B5G5R5_UNORM_PACK16_KHR -
VK_FORMAT_A8_UNORM_KHR
-
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_ALLOW_DERIVATIVES_BIT_KHR -
VK_PIPELINE_CREATE_2_DERIVATIVE_BIT_KHR -
VK_PIPELINE_CREATE_2_DISABLE_OPTIMIZATION_BIT_KHR -
VK_PIPELINE_CREATE_2_DISPATCH_BASE_BIT_KHR -
VK_PIPELINE_CREATE_2_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BUFFER_USAGE_FLAGS_2_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_DEVICE_IMAGE_SUBRESOURCE_INFO_KHR -
VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_5_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PIPELINE_CREATE_FLAGS_2_CREATE_INFO_KHR -
VK_STRUCTURE_TYPE_RENDERING_AREA_INFO_KHR -
VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_KHR
-
If VK_KHR_dynamic_rendering or Vulkan Version 1.3 and VK_EXT_fragment_density_map is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT
-
If VK_KHR_dynamic_rendering or Vulkan Version 1.3 and VK_KHR_fragment_shading_rate is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
If VK_ARM_pipeline_opacity_micromap is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_DISALLOW_OPACITY_MICROMAP_BIT_ARM
-
If VK_EXT_attachment_feedback_loop_layout is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT -
VK_PIPELINE_CREATE_2_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT
-
If VK_EXT_conditional_rendering is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_CONDITIONAL_RENDERING_BIT_EXT
-
If VK_EXT_descriptor_buffer is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT -
VK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT -
VK_BUFFER_USAGE_2_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT
-
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_DESCRIPTOR_BUFFER_BIT_EXT
-
If VK_EXT_graphics_pipeline_library is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_LINK_TIME_OPTIMIZATION_BIT_EXT -
VK_PIPELINE_CREATE_2_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT
-
If VK_EXT_opacity_micromap is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT -
VK_BUFFER_USAGE_2_MICROMAP_STORAGE_BIT_EXT
-
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT
-
If VK_EXT_transform_feedback is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT -
VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT
-
If VK_KHR_acceleration_structure is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR -
VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR
-
If VK_KHR_pipeline_executable_properties is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR -
VK_PIPELINE_CREATE_2_CAPTURE_STATISTICS_BIT_KHR
-
If VK_KHR_pipeline_library is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_LIBRARY_BIT_KHR
-
If VK_KHR_ray_tracing_pipeline is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_SHADER_BINDING_TABLE_BIT_KHR
-
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR -
VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR -
VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR -
VK_PIPELINE_CREATE_2_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR -
VK_PIPELINE_CREATE_2_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR -
VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_AABBS_BIT_KHR -
VK_PIPELINE_CREATE_2_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
-
If VK_KHR_video_decode_queue is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_VIDEO_DECODE_DST_BIT_KHR -
VK_BUFFER_USAGE_2_VIDEO_DECODE_SRC_BIT_KHR
-
If VK_KHR_video_encode_queue is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_VIDEO_ENCODE_DST_BIT_KHR -
VK_BUFFER_USAGE_2_VIDEO_ENCODE_SRC_BIT_KHR
-
If VK_NV_device_generated_commands is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_NV
-
If VK_NV_displacement_micromap is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV
-
If VK_NV_ray_tracing is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_RAY_TRACING_BIT_NV
-
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_DEFER_COMPILE_BIT_NV
-
If VK_NV_ray_tracing_motion_blur is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_RAY_TRACING_ALLOW_MOTION_BIT_NV
-
If Vulkan Version 1.2 or VK_KHR_buffer_device_address or VK_EXT_buffer_device_address is supported:
-
Extending VkBufferUsageFlagBits2:
-
VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT_KHR
-
If Vulkan Version 1.3 or VK_EXT_pipeline_creation_cache_control is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_EARLY_RETURN_ON_FAILURE_BIT_KHR -
VK_PIPELINE_CREATE_2_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_KHR
-
If Vulkan Version 1.4 or VK_EXT_pipeline_protected_access is supported:
-
Extending VkPipelineCreateFlagBits2:
-
VK_PIPELINE_CREATE_2_NO_PROTECTED_ACCESS_BIT_EXT -
VK_PIPELINE_CREATE_2_PROTECTED_ACCESS_ONLY_BIT_EXT
-
VK_KHR_maintenance6
- Name String
-
VK_KHR_maintenance6 - Extension Type
-
Device extension
- Registered Extension Number
-
546
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_EXT_descriptor_buffer
-
Interacts with VK_KHR_push_descriptor
-
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Jon Leech [GitHub]oddhack
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-08-03
- Interactions and External Dependencies
-
-
Interacts with
VK_EXT_robustness2
-
- Contributors
-
-
Jon Leech, Khronos
-
Stu Smith, AMD
-
Mike Blumenkrantz, Valve
-
Ralph Potter, Samsung
-
James Fitzpatrick, Imagination Technologies
-
Piers Daniell, NVIDIA
-
Daniel Story, Nintendo
-
Description
VK_KHR_maintenance6 adds a collection of minor features, none of which would warrant an entire extension of their own.
The new features are as follows:
-
VkBindMemoryStatusKHR may be included in the
pNextchain of VkBindBufferMemoryInfo and VkBindImageMemoryInfo, allowing applications to identify individual resources for which memory binding failed during calls to vkBindBufferMemory2 and vkBindImageMemory2. -
A new property
fragmentShadingRateClampCombinerInputsto indicate if an implementation clamps the inputs to fragment shading rate combiner operations. -
VK_NULL_HANDLE is allowed to be used when binding an index buffer, instead of a valid VkBuffer handle. When the
nullDescriptorfeature is enabled, every index fetched results in a value of zero. -
A new property
maxCombinedImageSamplerDescriptorCountto indicate the maximum number of descriptors needed for any of the formats that require a sampler Y′CBCR conversion supported by the implementation. -
A new property
blockTexelViewCompatibleMultipleLayersindicating whetherVK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BITis allowed to be used withlayerCount> 1 -
pNextextensible *2 versions of all descriptor binding commands.
New Structures
-
Extending VkBindBufferMemoryInfo, VkBindImageMemoryInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
If VK_EXT_descriptor_buffer is supported:
If VK_KHR_push_descriptor is supported:
New Enum Constants
-
VK_KHR_MAINTENANCE_6_EXTENSION_NAME -
VK_KHR_MAINTENANCE_6_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BIND_DESCRIPTOR_SETS_INFO_KHR -
VK_STRUCTURE_TYPE_BIND_MEMORY_STATUS_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAINTENANCE_6_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PUSH_CONSTANTS_INFO_KHR
-
If VK_EXT_descriptor_buffer is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BIND_DESCRIPTOR_BUFFER_EMBEDDED_SAMPLERS_INFO_EXT -
VK_STRUCTURE_TYPE_SET_DESCRIPTOR_BUFFER_OFFSETS_INFO_EXT
-
If VK_KHR_push_descriptor is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_INFO_KHR -
VK_STRUCTURE_TYPE_PUSH_DESCRIPTOR_SET_WITH_TEMPLATE_INFO_KHR
-
VK_KHR_map_memory2
- Name String
-
VK_KHR_map_memory2 - Extension Type
-
Device extension
- Registered Extension Number
-
272
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Faith Ekstrand [GitHub]gfxstrand
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-03-14
- Interactions and External Dependencies
-
-
None
-
- Contributors
-
-
Faith Ekstrand, Collabora
-
Tobias Hector, AMD
-
Description
This extension provides extensible versions of the Vulkan memory map and unmap commands. The new commands are functionally identical to the core commands, except that their parameters are specified using extensible structures that can be used to pass extension-specific information.
New Enum Constants
-
VK_KHR_MAP_MEMORY_2_EXTENSION_NAME -
VK_KHR_MAP_MEMORY_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MEMORY_MAP_INFO_KHR -
VK_STRUCTURE_TYPE_MEMORY_UNMAP_INFO_KHR
-
VK_KHR_multiview
- Name String
-
VK_KHR_multiview - Extension Type
-
Device extension
- Registered Extension Number
-
54
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2016-10-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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_push_descriptor
- Name String
-
VK_KHR_push_descriptor - Extension Type
-
Device extension
- Registered Extension Number
-
81
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_1
-
Interacts with VK_KHR_descriptor_update_template
-
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Jeff Bolz [GitHub]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 Commands
If Vulkan Version 1.1 or VK_KHR_descriptor_update_template is supported:
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 Vulkan Version 1.1 or VK_KHR_descriptor_update_template is supported:
-
Extending VkDescriptorUpdateTemplateType:
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
-
VK_KHR_relaxed_block_layout
- Name String
-
VK_KHR_relaxed_block_layout - Extension Type
-
Device extension
- Registered Extension Number
-
145
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
John Kessenich [GitHub]johnkslang
-
Other Extension Metadata
- Last Modified Date
-
2017-03-26
- IP Status
-
No known IP claims.
- 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.
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Tobias Hector [GitHub]tobski
-
Other Extension Metadata
- Last Modified Date
-
2019-08-17
- 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 =
{
.sType = VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO,
// 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.
VK_KHR_sampler_ycbcr_conversion
- Name String
-
VK_KHR_sampler_ycbcr_conversion - Extension Type
-
Device extension
- Registered Extension Number
-
157
- Revision
-
14
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_EXT_debug_report
-
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Andrew Garrard [GitHub]fluppeteer
-
Other Extension Metadata
- Last Modified Date
-
2017-08-11
- IP Status
-
No known IP claims.
- 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.
Promotion to Vulkan 1.4
If Vulkan 1.4 is supported, support for the samplerYcbcrConversion
capability is required.
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 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 -
VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_KHR_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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-25
- 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Aaron Hagan [GitHub]ahagan
-
Other Extension Metadata
- Last Modified Date
-
2018-07-05
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension provides API support for
GL_ARB_shader_draw_parameters
-
- 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_expect_assume
- Name String
-
VK_KHR_shader_expect_assume - Extension Type
-
Device extension
- Registered Extension Number
-
545
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Kevin Petit [GitHub]kpet
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-12-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Kevin Petit, Arm
-
Tobias Hector, AMD
-
James Fitzpatrick, Imagination Technologies
-
Description
This extension allows the use of the SPV_KHR_expect_assume extension in
SPIR-V shader modules which enables SPIR-V producers to provide optimization
hints to the Vulkan implementation.
New Enum Constants
-
VK_KHR_SHADER_EXPECT_ASSUME_EXTENSION_NAME -
VK_KHR_SHADER_EXPECT_ASSUME_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_EXPECT_ASSUME_FEATURES_KHR
-
VK_KHR_shader_float16_int8
- Name String
-
VK_KHR_shader_float16_int8 - Extension Type
-
Device extension
- Registered Extension Number
-
83
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Alexander Galazin [GitHub]alegal-arm
-
Other Extension Metadata
- Last Modified Date
-
2018-03-07
- Interactions and External Dependencies
-
-
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.
Promotion to Vulkan 1.4
If Vulkan 1.4 is supported, support for the shaderInt8 capability is
required.
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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Alexander Galazin [GitHub]alegal-arm
-
Other Extension Metadata
- Last Modified Date
-
2018-09-11
- 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 standardize 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_float_controls2
- Name String
-
VK_KHR_shader_float_controls2 - Extension Type
-
Device extension
- Registered Extension Number
-
529
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Graeme Leese [GitHub]gnl21
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-05-16
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_float_controls2.
-
- Contributors
-
-
Graeme Leese, Broadcom
-
Description
This extension enables use of the more expressive fast floating-point math flags in the SPV_KHR_float_controls2 extension. These flags give finer- grained control over which optimizations compilers may apply, potentially speeding up execution while retaining correct results.
The extension also adds control over the fast-math modes to the GLSL extended instruction set, making these operations more consistent with SPIR-V and allowing their use in situations where floating-point conformance is important.
New Enum Constants
-
VK_KHR_SHADER_FLOAT_CONTROLS_2_EXTENSION_NAME -
VK_KHR_SHADER_FLOAT_CONTROLS_2_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_FLOAT_CONTROLS_2_FEATURES_KHR
-
VK_KHR_shader_integer_dot_product
- Name String
-
VK_KHR_shader_integer_dot_product - Extension Type
-
Device extension
- Registered Extension Number
-
281
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Kevin Petit [GitHub]kpet
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2021-06-16
- Interactions and External Dependencies
-
-
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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the KHR suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Baldur Karlsson [GitHub]baldurk
-
Other Extension Metadata
- Last Modified Date
-
2019-10-16
- 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Neil Henning [GitHub]sheredom
-
Other Extension Metadata
- Last Modified Date
-
2019-01-08
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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_subgroup_rotate
- Name String
-
VK_KHR_shader_subgroup_rotate - Extension Type
-
Device extension
- Registered Extension Number
-
417
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Kevin Petit [GitHub]kpet
-
- Extension Proposal
- Last Modified Date
-
2024-01-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Kévin Petit, Arm Ltd.
-
Tobias Hector, AMD
-
Jon Leech, Khronos
-
Matthew Netsch, Qualcomm
-
Jan-Harald Fredriksen, Arm Ltd.
-
Graeme Leese, Broadcom
-
Tom Olson, Arm Ltd.
-
Spencer Fricke, LunarG Inc.
-
This extension adds support for the subgroup rotate instruction defined in SPV_KHR_subgroup_rotate.
New Enum Constants
-
VK_KHR_SHADER_SUBGROUP_ROTATE_EXTENSION_NAME -
VK_KHR_SHADER_SUBGROUP_ROTATE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_SUBGROUP_ROTATE_FEATURES_KHR
-
-
Extending VkSubgroupFeatureFlagBits:
-
VK_SUBGROUP_FEATURE_ROTATE_BIT_KHR -
VK_SUBGROUP_FEATURE_ROTATE_CLUSTERED_BIT_KHR
-
VK_KHR_shader_terminate_invocation
- Name String
-
VK_KHR_shader_terminate_invocation - Extension Type
-
Device extension
- Registered Extension Number
-
216
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Jesse Hall [GitHub]critsec
-
Other Extension Metadata
- Last Modified Date
-
2020-08-11
- 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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the KHR suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jesse Hall [GitHub]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.
-
- 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Alexander Galazin [GitHub]alegal-arm
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- 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.
VK_KHR_synchronization2
- Name String
-
VK_KHR_synchronization2 - Extension Type
-
Device extension
- Registered Extension Number
-
315
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_EXT_blend_operation_advanced
-
Interacts with VK_EXT_conditional_rendering
-
Interacts with VK_EXT_device_generated_commands
-
Interacts with VK_EXT_fragment_density_map
-
Interacts with VK_EXT_mesh_shader
-
Interacts with VK_EXT_transform_feedback
-
Interacts with VK_KHR_acceleration_structure
-
Interacts with VK_KHR_fragment_shading_rate
-
Interacts with VK_KHR_ray_tracing_pipeline
-
Interacts with VK_NV_device_generated_commands
-
Interacts with VK_NV_mesh_shader
-
Interacts with VK_NV_ray_tracing
-
Interacts with VK_NV_shading_rate_image
-
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Tobias Hector [GitHub]tobski
-
Other Extension Metadata
- Last Modified Date
-
2020-12-03
- Interactions and External Dependencies
-
-
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.
-
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 Enum Constants
-
VK_KHR_SYNCHRONIZATION_2_EXTENSION_NAME -
VK_KHR_SYNCHRONIZATION_2_SPEC_VERSION -
Extending VkAccessFlagBits:
-
VK_ACCESS_NONE_KHR
-
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT_KHR -
VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT_KHR -
VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT_KHR -
VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT_KHR -
VK_ACCESS_2_HOST_READ_BIT_KHR -
VK_ACCESS_2_HOST_WRITE_BIT_KHR -
VK_ACCESS_2_INDEX_READ_BIT_KHR -
VK_ACCESS_2_INDIRECT_COMMAND_READ_BIT_KHR -
VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT_KHR -
VK_ACCESS_2_MEMORY_READ_BIT_KHR -
VK_ACCESS_2_MEMORY_WRITE_BIT_KHR -
VK_ACCESS_2_NONE_KHR -
VK_ACCESS_2_SHADER_READ_BIT_KHR -
VK_ACCESS_2_SHADER_SAMPLED_READ_BIT_KHR -
VK_ACCESS_2_SHADER_STORAGE_READ_BIT_KHR -
VK_ACCESS_2_SHADER_STORAGE_WRITE_BIT_KHR -
VK_ACCESS_2_SHADER_WRITE_BIT_KHR -
VK_ACCESS_2_TRANSFER_READ_BIT_KHR -
VK_ACCESS_2_TRANSFER_WRITE_BIT_KHR -
VK_ACCESS_2_UNIFORM_READ_BIT_KHR -
VK_ACCESS_2_VERTEX_ATTRIBUTE_READ_BIT_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 VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT_KHR -
VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT_KHR -
VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT_KHR -
VK_PIPELINE_STAGE_2_BLIT_BIT_KHR -
VK_PIPELINE_STAGE_2_BOTTOM_OF_PIPE_BIT_KHR -
VK_PIPELINE_STAGE_2_CLEAR_BIT_KHR -
VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT_KHR -
VK_PIPELINE_STAGE_2_COMPUTE_SHADER_BIT_KHR -
VK_PIPELINE_STAGE_2_COPY_BIT_KHR -
VK_PIPELINE_STAGE_2_DRAW_INDIRECT_BIT_KHR -
VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT_KHR -
VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT_KHR -
VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT_KHR -
VK_PIPELINE_STAGE_2_HOST_BIT_KHR -
VK_PIPELINE_STAGE_2_INDEX_INPUT_BIT_KHR -
VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT_KHR -
VK_PIPELINE_STAGE_2_NONE_KHR -
VK_PIPELINE_STAGE_2_PRE_RASTERIZATION_SHADERS_BIT_KHR -
VK_PIPELINE_STAGE_2_RESOLVE_BIT_KHR -
VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT_KHR -
VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT_KHR -
VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT_KHR -
VK_PIPELINE_STAGE_2_TRANSFER_BIT_KHR -
VK_PIPELINE_STAGE_2_VERTEX_ATTRIBUTE_INPUT_BIT_KHR -
VK_PIPELINE_STAGE_2_VERTEX_INPUT_BIT_KHR -
VK_PIPELINE_STAGE_2_VERTEX_SHADER_BIT_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
-
-
Extending VkSubmitFlagBits:
-
VK_SUBMIT_PROTECTED_BIT_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_device_generated_commands is supported:
-
Extending VkAccessFlagBits2:
-
VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_EXT -
VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_EXT
-
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_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_mesh_shader is supported:
-
Extending VkPipelineStageFlagBits2:
-
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT -
VK_PIPELINE_STAGE_2_TASK_SHADER_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_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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the KHR suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Faith Ekstrand [GitHub]gfxstrand
-
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
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Yuriy O’Donnell, Epic Games
-
Faith 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 application 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 synchronization 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 application 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 application 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.
VK_KHR_uniform_buffer_standard_layout
- Name String
-
VK_KHR_uniform_buffer_standard_layout - Extension Type
-
Device extension
- Registered Extension Number
-
254
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Graeme Leese [GitHub]gnl21
-
Other Extension Metadata
- Last Modified Date
-
2019-01-25
- Contributors
-
-
Graeme Leese, Broadcom
-
Jeff Bolz, NVIDIA
-
Tobias Hector, AMD
-
Faith Ekstrand, Intel
-
Neil Henning, AMD
-
Description
This extension enables tighter array and structure 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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.1
-
- Contact
-
-
Jesse Hall [GitHub]critsec
-
Other Extension Metadata
- Last Modified Date
-
2017-09-05
- IP Status
-
No known IP claims.
- Contributors
-
-
John Kessenich, Google
-
Neil Henning, Codeplay
-
David Neto, Google
-
Daniel Koch, Nvidia
-
Graeme Leese, Broadcom
-
Weifeng Zhang, Qualcomm
-
Stephen Clarke, Imagination Technologies
-
Faith 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.
Promotion to Vulkan 1.4
If Vulkan 1.4 is supported, support for the variablePointers and variablePointersStorageBuffer features is required.
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_vertex_attribute_divisor
- Name String
-
VK_KHR_vertex_attribute_divisor - Extension Type
-
Device extension
- Registered Extension Number
-
526
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-09-20
- IP Status
-
No known IP claims.
- Contributors
-
-
Shahbaz Youssefi, Google
-
Contributors to
VK_EXT_vertex_attribute_divisor
-
Description
This extension is based on the VK_EXT_vertex_attribute_divisor
extension.
The only difference is the new property supportsNonZeroFirstInstance,
which indicates support for non-zero values in firstInstance.
This allows the extension to be supported on implementations that have
traditionally only supported OpenGL ES.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineVertexInputStateCreateInfo:
New Enum Constants
-
VK_KHR_VERTEX_ATTRIBUTE_DIVISOR_EXTENSION_NAME -
VK_KHR_VERTEX_ATTRIBUTE_DIVISOR_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_KHR -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_KHR -
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_KHR
-
Promotion to Vulkan 1.4
Functionality in this extension is included in core Vulkan 1.4 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, 2023-09-20 (Shahbaz Youssefi)
-
First Version, based on
VK_EXT_vertex_attribute_divisor
-
VK_KHR_vulkan_memory_model
- Name String
-
VK_KHR_vulkan_memory_model - Extension Type
-
Device extension
- Registered Extension Number
-
212
- Revision
-
3
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2018-12-10
- IP Status
-
No known IP claims.
- 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 features
guarded by the VulkanMemoryModel, VulkanMemoryModelDeviceScope,
and VulkanMemoryModelAvailabilityVisibilityChains capabilities in
shader modules.
The Vulkan Memory Model 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.
Promotion to Vulkan 1.3
If Vulkan 1.3 is supported, support for the vulkanMemoryModel and
vulkanMemoryModelDeviceScope capabilities is required.
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
-
VK_KHR_zero_initialize_workgroup_memory
- Name String
-
VK_KHR_zero_initialize_workgroup_memory - Extension Type
-
Device extension
- Registered Extension Number
-
326
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Alan Baker [GitHub]alan-baker
-
Other Extension Metadata
- Last Modified Date
-
2020-11-18
- IP Status
-
No known IP claims.
- Contributors
-
-
Alan Baker, Google
-
Jeff Bolz, Nvidia
-
Faith 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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the KHR suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Joshua Ashton [GitHub]Joshua-Ashton
-
Other Extension Metadata
- Last Modified Date
-
2020-07-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Ashton, Valve
-
Faith 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
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Deprecated by VK_KHR_buffer_device_address extension
-
Which in turn was promoted to Vulkan 1.2
-
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-01-06
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension provides API support for
GLSL_EXT_buffer_referenceandGLSL_EXT_buffer_reference_uvec2
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Neil Henning, AMD
-
Tobias Hector, AMD
-
Faith 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.
VK_EXT_calibrated_timestamps
- Name String
-
VK_EXT_calibrated_timestamps - Extension Type
-
Device extension
- Registered Extension Number
-
185
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_calibrated_timestamps extension
-
- Contact
-
-
Daniel Rakos [GitHub]drakos-amd
-
- Extension Proposal
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
-
Faith Ekstrand, Intel
-
Keith Packard, Valve
-
Description
This extension provides an interface to query calibrated timestamps obtained quasi simultaneously from two time domains.
Promotion to VK_KHR_calibrated_timestamps
All functionality in this extension is included in
VK_KHR_calibrated_timestamps, with the suffix changed to KHR.
The original enum names are still available as aliases of the KHR
functionality.
New Enum Constants
-
VK_EXT_CALIBRATED_TIMESTAMPS_EXTENSION_NAME -
VK_EXT_CALIBRATED_TIMESTAMPS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT
-
-
Extending VkTimeDomainKHR:
-
VK_TIME_DOMAIN_CLOCK_MONOTONIC_EXT -
VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_EXT -
VK_TIME_DOMAIN_DEVICE_EXT -
VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_EXT
-
VK_EXT_debug_marker
- Name String
-
VK_EXT_debug_marker - Extension Type
-
Device extension
- Registered Extension Number
-
23
- Revision
-
4
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_EXT_debug_utils extension
-
- Special Use
- Contact
-
-
Baldur Karlsson [GitHub]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 =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT,
.pNext = NULL,
.objectType = VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT,
.object = (uint64_t)image,
.pObjectName = "Brick Diffuse Texture",
};
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 visualization 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 =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT,
.pNext = NULL,
.pMarkerName = "Brick House",
.color = { 1.0f, 0.0f, 0.0f, 1.0f },
};
// Start an annotated group of calls under the 'Brick House' name
pfnCmdDebugMarkerBeginEXT(commandBuffer, &houseMarker);
{
// A mutable structure for each part being rendered
VkDebugMarkerMarkerInfoEXT housePartMarker =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT,
.pNext = NULL,
.pMarkerName = NULL,
.color = { 0.0f, 0.0f, 0.0f, 0.0f },
};
// 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 visualization.
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)
-
Reorganize spec layout to closer match desired organization
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- API Interactions
-
-
Interacts with VK_VERSION_1_1
-
- Deprecation State
-
-
Deprecated by VK_EXT_debug_utils extension
-
- Special Use
- Contact
-
-
Courtney Goeltzenleuchter [GitHub]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 Vulkan 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 chain of the VkInstanceCreateInfo structure passed
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 = {
.sType = VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT,
.pNext = NULL,
.flags = VK_DEBUG_REPORT_ERROR_BIT_EXT |
VK_DEBUG_REPORT_WARNING_BIT_EXT,
.pfnCallback = myOutputDebugString,
.pUserData = NULL
};
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 = {
.sType = VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT,
.pNext = NULL,
.flags = VK_DEBUG_REPORT_WARNING_BIT_EXT,
.pfnCallback = mystdOutLogger,
.pUserData = NULL
};
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 application 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_depth_clamp_zero_one
- Name String
-
VK_EXT_depth_clamp_zero_one - Extension Type
-
Device extension
- Registered Extension Number
-
422
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_depth_clamp_zero_one extension
-
- Contact
-
-
Graeme Leese [GitHub]gnl21
-
Description
This extension gives defined behavior to fragment depth values which end up outside the conventional [0, 1] range. It can be used to ensure portability in edge cases of features like depthBias. The particular behavior is chosen to match OpenGL to aid porting or emulation.
Promotion to VK_KHR_depth_clamp_zero_one
All functionality in this extension is included in
VK_KHR_depth_clamp_zero_one, with the suffix change to KHR.
The original type, enum, and command names are still available as aliases of
the core functionality.
New Enum Constants
-
VK_EXT_DEPTH_CLAMP_ZERO_ONE_EXTENSION_NAME -
VK_EXT_DEPTH_CLAMP_ZERO_ONE_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLAMP_ZERO_ONE_FEATURES_EXT
-
VK_EXT_descriptor_indexing
- Name String
-
VK_EXT_descriptor_indexing - Extension Type
-
Device extension
- Registered Extension Number
-
162
- Revision
-
2
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-10-02
- Interactions and External Dependencies
-
-
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.
Promotion to Vulkan 1.2
Vulkan APIs in this extension are 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.
External interactions defined by this extension, such as SPIR-V token names,
retain their original names.
The original Vulkan API names are still available as aliases of the core
functionality.
Promotion to Vulkan 1.4
If Vulkan 1.4 is supported, support for the
shaderUniformTexelBufferArrayDynamicIndexing and
shaderStorageTexelBufferArrayDynamicIndexing capabilities is required.
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
-
VK_EXT_extended_dynamic_state
- Name String
-
VK_EXT_extended_dynamic_state - Extension Type
-
Device extension
- Registered Extension Number
-
268
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-12-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Dan Ginsburg, Valve Corporation
-
Graeme Leese, Broadcom
-
Hans-Kristian Arntzen, Valve Corporation
-
Jan-Harald Fredriksen, Arm Limited
-
Faith 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
All dynamic state enumerants and commands 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.
Issues
1) Why are the values of pStrides in vkCmdBindVertexBuffers2
limited to be between 0 and the maximum extent of the binding, when this
restriction is not present for the same static state?
Implementing these edge cases adds overhead to some implementations that would require significant cost when calling this function, and the intention is that this state should be more or less free to change.
VK_EXT_vertex_input_dynamic_state allows the stride to be changed freely when supported via vkCmdSetVertexInputEXT.
VK_EXT_extended_dynamic_state2
- Name String
-
VK_EXT_extended_dynamic_state2 - Extension Type
-
Device extension
- Registered Extension Number
-
378
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha-nv
-
Other Extension Metadata
- Last Modified Date
-
2021-04-12
- 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
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
commands in this extension are included in core Vulkan 1.3, with the EXT
suffix omitted.
The enumerants and commands 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to VK_KHR_global_priority extension
-
Which in turn was promoted to Vulkan 1.4
-
-
- Contact
-
-
Andres Rodriguez [GitHub]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 favor 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 VkQueueGlobalPriority:
-
VK_QUEUE_GLOBAL_PRIORITY_HIGH_EXT -
VK_QUEUE_GLOBAL_PRIORITY_LOW_EXT -
VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT -
VK_QUEUE_GLOBAL_PRIORITY_REALTIME_EXT
-
-
Extending VkResult:
-
VK_ERROR_NOT_PERMITTED_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_EXT
-
VK_EXT_global_priority_query
- Name String
-
VK_EXT_global_priority_query - Extension Type
-
Device extension
- Registered Extension Number
-
389
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_global_priority extension
-
Which in turn was promoted to Vulkan 1.4
-
-
- Contact
-
-
Yiwei Zhang [GitHub]zzyiwei
-
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_image_copy
- Name String
-
VK_EXT_host_image_copy - Extension Type
-
Device extension
- Registered Extension Number
-
271
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2023-04-26
- Contributors
-
-
Shahbaz Youssefi, Google
-
Faith Ekstrand, Collabora
-
Hans-Kristian Arntzen, Valve
-
Piers Daniell, NVIDIA
-
Jan-Harald Fredriksen, Arm
-
James Fitzpatrick, Imagination
-
Daniel Story, Nintendo
-
Description
This extension allows applications to copy data between host memory and images on the host processor, without staging the data through a GPU-accessible buffer. This removes the need to allocate and manage the buffer and its associated memory. On some architectures it may also eliminate an extra copy operation. This extension additionally allows applications to copy data between images on the host.
To support initializing a new image in preparation for a host copy, it is
now possible to transition a new image to VK_IMAGE_LAYOUT_GENERAL or
other host-copyable layouts via vkTransitionImageLayoutEXT.
Additionally, it is possible to perform copies that preserve the swizzling
layout of the image by using the VK_HOST_IMAGE_COPY_MEMCPY_BIT_EXT
flag.
In that case, the memory size needed for copies to or from a buffer can be
retrieved by chaining VkSubresourceHostMemcpySizeEXT to pLayout
in vkGetImageSubresourceLayout2EXT.
New Structures
-
Extending VkImageFormatProperties2:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkSubresourceLayout2:
New Enum Constants
-
VK_EXT_HOST_IMAGE_COPY_EXTENSION_NAME -
VK_EXT_HOST_IMAGE_COPY_SPEC_VERSION -
Extending VkFormatFeatureFlagBits2:
-
VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT_EXT
-
-
Extending VkHostImageCopyFlagBits:
-
VK_HOST_IMAGE_COPY_MEMCPY_BIT_EXT -
VK_HOST_IMAGE_COPY_MEMCPY_EXT
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO_EXT -
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO_EXT -
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO_EXT -
VK_STRUCTURE_TYPE_HOST_IMAGE_COPY_DEVICE_PERFORMANCE_QUERY_EXT -
VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO_EXT -
VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY_EXT -
VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES_EXT -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES_EXT -
VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE_EXT
-
Promotion to Vulkan 1.4
Functionality in this extension is included in core Vulkan 1.4, with the EXT suffix omitted. However, the feature is made optional in Vulkan 1.4. The original type, enum and command names are still available as aliases of the core functionality.
A Vulkan 1.4 implementation that has a VK_QUEUE_GRAPHICS_BIT queue
must support either:
-
the
hostImageCopyfeature; or -
an additional queue that supports
VK_QUEUE_TRANSFER_BIT.
Additionally, all queues supporting VK_QUEUE_GRAPHICS_BIT or
VK_QUEUE_COMPUTE_BIT must also advertise VK_QUEUE_TRANSFER_BIT.
Issues
1) When uploading data to an image, the data is usually loaded from disk.
Why not have the application load the data directly into a VkDeviceMemory
bound to a buffer (instead of host memory), and use
vkCmdCopyBufferToImage? The same could be done when downloading data
from an image.
RESOLVED: This may not always be possible. Complicated Vulkan applications such as game engines often have decoupled subsystems for streaming data and rendering. It may be unreasonable to require the streaming subsystem to coordinate with the rendering subsystem to allocate memory on its behalf, especially as Vulkan may not be the only API supported by the engine. In emulation layers, the image data is necessarily provided by the application in host memory, so an optimization as suggested is not possible. Most importantly, the device memory may not be mappable by an application, but still accessible to the driver.
2) Are optimalBufferCopyOffsetAlignment and
optimalBufferCopyRowPitchAlignment applicable to host memory as well with
the functions introduced by this extension? Or should there be new limits?
RESOLVED: No alignment requirements for the host memory pointer.
3) Should there be granularity requirements for image offsets and extents?
RESOLVED: No granularity requirements, i.e. a granularity of 1 pixel (for non-compressed formats) and 1 texel block (for compressed formats) is assumed.
4) How should the application deal with layout transitions before or after copying to or from images?
RESOLVED: An existing issue with linear images is that when emulating other APIs, it is impossible to know when to transition them as they are written to by the host and then used bindlessly. The copy operations in this extension are affected by the same limitation. A new command is thus introduced by this extension to address this problem by allowing the host to perform an image layout transition between a handful of layouts.
VK_EXT_host_query_reset
- Name String
-
VK_EXT_host_query_reset - Extension Type
-
Device extension
- Registered Extension Number
-
262
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Bas Nieuwenhuizen [GitHub]BNieuwenhuizen
-
Other Extension Metadata
- Last Modified Date
-
2019-03-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Bas Nieuwenhuizen, Google
-
Faith 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Graeme Leese [GitHub]gnl21
-
Other Extension Metadata
- Last Modified Date
-
2020-04-27
- 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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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_index_type_uint8
- Name String
-
VK_EXT_index_type_uint8 - Extension Type
-
Device extension
- Registered Extension Number
-
266
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_index_type_uint8 extension
-
Which in turn was promoted to Vulkan 1.4
-
-
- Contact
-
-
Piers Daniell [GitHub]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.
Promotion to VK_KHR_index_type_uint8
All functionality in this extension is included in
VK_KHR_index_type_uint8, with the suffix changed to KHR.
The original enum names are still available as aliases of the KHR
functionality.
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_inline_uniform_block
- Name String
-
VK_EXT_inline_uniform_block - Extension Type
-
Device extension
- Registered Extension Number
-
139
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_2
-
Interacts with VK_EXT_descriptor_indexing
-
Interacts with VkPhysicalDeviceVulkan12Features::descriptorIndexing
-
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Daniel Rakos [GitHub]aqnuep
-
Other Extension Metadata
- Last Modified Date
-
2018-08-01
- 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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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_line_rasterization
- Name String
-
VK_EXT_line_rasterization - Extension Type
-
Device extension
- Registered Extension Number
-
260
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_line_rasterization extension
-
Which in turn was promoted to Vulkan 1.4
-
-
- Special Use
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-05-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Allen Jensen, NVIDIA
-
Faith 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.
Promotion to VK_KHR_line_rasterization
All functionality in this extension is included in
VK_KHR_line_rasterization, with the suffix changed to KHR.
The original enum names are still available as aliases of the KHR
functionality.
New Enum Constants
-
VK_EXT_LINE_RASTERIZATION_EXTENSION_NAME -
VK_EXT_LINE_RASTERIZATION_SPEC_VERSION -
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_LINE_STIPPLE_EXT
-
-
Extending VkLineRasterizationMode:
-
VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT -
VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT -
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT -
VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_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
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to VK_KHR_load_store_op_none extension
-
Which in turn was promoted to Vulkan 1.4
-
-
- Contact
-
-
Shahbaz Youssefi [GitHub]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.
Promotion to VK_KHR_load_store_op_none
All functionality in this extension is included in
VK_KHR_load_store_op_none, with the suffix changed to KHR.
The original enum names are still available as aliases of the KHR
functionality.
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
-
|
Note
|
While |
VK_EXT_pipeline_creation_cache_control
- Name String
-
VK_EXT_pipeline_creation_cache_control - Extension Type
-
Device extension
- Registered Extension Number
-
298
- Revision
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Gregory Grebe [GitHub]grgrebe_amd
-
Other Extension Metadata
- Last Modified Date
-
2020-03-23
- 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.
In such a case, if the implementation fails to create a pipeline without
compilation, the implementation must return the result
VK_PIPELINE_COMPILE_REQUIRED_EXT and return VK_NULL_HANDLE for
the pipeline.
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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Special Use
- Contact
-
-
Jean-Francois Roy [GitHub]jfroy
-
Other Extension Metadata
- Last Modified Date
-
2019-03-12
- 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 VkPipelineCreationFeedbackFlagBits:
-
VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT_EXT -
VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT_EXT -
VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO_EXT
-
Promotion to Vulkan 1.3
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API names are still available as aliases of the core functionality.
VK_EXT_pipeline_protected_access
- Name String
-
VK_EXT_pipeline_protected_access - Extension Type
-
Device extension
- Registered Extension Number
-
467
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-07-28
- Contributors
-
-
Shahbaz Youssefi, Google
-
Jörg Wagner, Arm
-
Ralph Potter, Samsung
-
Daniel Koch, NVIDIA
-
Description
This extension allows protected memory access to be specified per pipeline as opposed to per device. Through the usage of this extension, any performance penalty paid due to access to protected memory will be limited to the specific pipelines that make such accesses.
New Enum Constants
-
VK_EXT_PIPELINE_PROTECTED_ACCESS_EXTENSION_NAME -
VK_EXT_PIPELINE_PROTECTED_ACCESS_SPEC_VERSION -
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT -
VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_PROTECTED_ACCESS_FEATURES_EXT
-
VK_EXT_pipeline_robustness
- Name String
-
VK_EXT_pipeline_robustness - Extension Type
-
Device extension
- Registered Extension Number
-
69
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.4
-
- 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.
-
Faith Ekstrand, Intel
-
Lionel Landwerlin, Intel
-
Shahbaz Youssefi, Google, Inc.
-
Description
This extension 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 VkPipelineRobustnessBufferBehavior:
-
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DEVICE_DEFAULT_EXT -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_DISABLED_EXT -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT -
VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT
-
-
Extending VkPipelineRobustnessImageBehavior:
-
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DEVICE_DEFAULT_EXT -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_DISABLED_EXT -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_2_EXT -
VK_PIPELINE_ROBUSTNESS_IMAGE_BEHAVIOR_ROBUST_IMAGE_ACCESS_EXT
-
-
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_present_mode_fifo_latest_ready
- Name String
-
VK_EXT_present_mode_fifo_latest_ready - Extension Type
-
Device extension
- Registered Extension Number
-
362
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_present_mode_fifo_latest_ready extension
-
- Contact
-
-
Lionel Duc [GitHub]nvlduc
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2024-05-28
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Lionel Duc, NVIDIA
-
Description
This device extension adds a new present mode,
VK_PRESENT_MODE_FIFO_LATEST_READY_EXT.
This tear-free present mode behaves much like
VK_PRESENT_MODE_FIFO_KHR, except that each vertical blanking period
dequeues consecutive present requests until the latest ready is found to
update the current image.
While this seems similar in concept to VK_PRESENT_MODE_MAILBOX_KHR,
the fundamental difference is that the processing of the present requests is
done during vblank.
From the application perspective, this means for example, that in a
flip-based model, a single vblank may cause multiple swapchain images to be
released at once, while VK_PRESENT_MODE_MAILBOX_KHR may continuously
be releasing images as new requests become ready.
This additional present mode is useful when using a time-based present API.
Promotion to VK_KHR_present_mode_fifo_latest_ready
All functionality in this extension is included in
VK_KHR_present_mode_fifo_latest_ready, with the suffix changed to
KHR.
The original type and enum names are still available as aliases of the KHR
names.
New Enum Constants
-
VK_EXT_PRESENT_MODE_FIFO_LATEST_READY_EXTENSION_NAME -
VK_EXT_PRESENT_MODE_FIFO_LATEST_READY_SPEC_VERSION -
Extending VkPresentModeKHR:
-
VK_PRESENT_MODE_FIFO_LATEST_READY_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_MODE_FIFO_LATEST_READY_FEATURES_EXT
-
VK_EXT_private_data
- Name String
-
VK_EXT_private_data - Extension Type
-
Device extension
- Registered Extension Number
-
296
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Matthew Rusch [GitHub]mattruschnv
-
Other Extension Metadata
- Last Modified Date
-
2020-03-25
- 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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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_robustness2
- Name String
-
VK_EXT_robustness2 - Extension Type
-
Device extension
- Registered Extension Number
-
287
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_robustness2 extension
-
- Contact
-
-
Liam Middlebrook [GitHub]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.
Promotion to VK_KHR_robustness2
All functionality in this extension is included in
VK_KHR_robustness2, 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_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_sampler_filter_minmax
- Name String
-
VK_EXT_sampler_filter_minmax - Extension Type
-
Device extension
- Registered Extension Number
-
131
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-05-19
- 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
-
VK_EXT_scalar_block_layout
- Name String
-
VK_EXT_scalar_block_layout - Extension Type
-
Device extension
- Registered Extension Number
-
222
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Tobias Hector [GitHub]tobski
-
Other Extension Metadata
- Last Modified Date
-
2018-11-14
- Contributors
-
-
Jeff Bolz
-
Jan-Harald Fredriksen
-
Graeme Leese
-
Faith 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
Vulkan APIs in this extension are 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.
External interactions defined by this extension, such as SPIR-V token names,
retain their original names.
The original Vulkan API names are still available as aliases of the core
functionality.
Promotion to Vulkan 1.4
If Vulkan 1.4 is supported, support for the scalarBlockLayout
capability is required.
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Daniel Rakos [GitHub]drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2018-11-08
- 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-01
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Deprecation State
-
-
Deprecated by Vulkan 1.2
-
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2016-11-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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 an invocation value, or broadcast of a bit array 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Deprecation State
-
-
Deprecated by Vulkan 1.1
-
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2016-11-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.2
-
- Contact
-
-
Daniel Koch [GitHub]dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-08-08
- Interactions and External Dependencies
-
-
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.
Behavior 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Neil Henning [GitHub]sheredom
-
Other Extension Metadata
- Last Modified Date
-
2019-03-05
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Faith 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 Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineShaderStageCreateInfo, VkShaderCreateInfoEXT:
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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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 (Faith Ekstrand)
-
Add the missing VkPhysicalDeviceSubgroupSizeControlFeaturesEXT for querying subgroup size control features.
-
VK_EXT_surface_maintenance1
- Name String
-
VK_EXT_surface_maintenance1 - Extension Type
-
Instance extension
- Registered Extension Number
-
275
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_surface_maintenance1 extension
-
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-12-16
- Interactions and External Dependencies
-
-
Promoted to
VK_KHR_surface_maintenance1
-
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Lionel Landwerlin, Intel
-
Shahbaz Youssefi, Google
-
Chris Forbes, Google
-
Ian Elliott, Google
-
Hans-Kristian Arntzen, Valve
-
Daniel Stone, Collabora
-
Description
VK_EXT_surface_maintenance1 adds a collection of window system
integration features that were intentionally left out or overlooked in the
original VK_KHR_surface extension.
The new features are as follows:
-
Allow querying number of min/max images from a surface for a particular presentation mode.
-
Allow querying a surface’s scaled presentation capabilities.
-
Allow querying a surface for the set of presentation modes which can be easily switched between without requiring swapchain recreation.
Promotion to VK_KHR_surface_maintenance1
All functionality in this extension is included in
VK_KHR_surface_maintenance1, with the suffix changed to KHR.
The original type, enum and command names are still available as aliases of
the KHR functionality.
New Enum Constants
-
VK_EXT_SURFACE_MAINTENANCE_1_EXTENSION_NAME -
VK_EXT_SURFACE_MAINTENANCE_1_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_COMPATIBILITY_EXT -
VK_STRUCTURE_TYPE_SURFACE_PRESENT_MODE_EXT -
VK_STRUCTURE_TYPE_SURFACE_PRESENT_SCALING_CAPABILITIES_EXT
-
VK_EXT_swapchain_maintenance1
- Name String
-
VK_EXT_swapchain_maintenance1 - Extension Type
-
Device extension
- Registered Extension Number
-
276
- Revision
-
1
- Ratification Status
-
Ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_swapchain_maintenance1 extension
-
- Contact
-
-
Shahbaz Youssefi [GitHub]syoussefi
-
- Extension Proposal
Other Extension Metadata
- Last Modified Date
-
2022-12-16
- Interactions and External Dependencies
-
-
Promoted to
VK_KHR_swapchain_maintenance1
-
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Shahbaz Youssefi, Google
-
Chris Forbes, Google
-
Ian Elliott, Google
-
Yiwei Zhang, Google
-
Charlie Lao, Google
-
Lina Versace, Google
-
Ralph Potter, Samsung
-
Igor Nazarov, Samsung
-
Hyunchang Kim, Samsung
-
Suenghwan Lee, Samsung
-
Munseong Kang, Samsung
-
Joonyong Park, Samsung
-
Hans-Kristian Arntzen, Valve
-
Lisa Wu, Arm
-
Daniel Stone, Collabora
-
Pan Gao, Huawei
-
Description
VK_EXT_swapchain_maintenance1 adds a collection of window system
integration features that were intentionally left out or overlooked in the
original VK_KHR_swapchain extension.
The new features are as follows:
-
Specify a fence that will be signaled when the resources associated with a present operation can be safely destroyed.
-
Allow changing the present mode a swapchain is using at per-present granularity.
-
Allow applications to define the behavior when presenting a swapchain image to a surface with different dimensions than the image. Using this feature may allow implementations to avoid returning
VK_ERROR_OUT_OF_DATE_KHRin this situation. -
Allow applications to defer swapchain memory allocation for improved startup time and memory footprint.
-
Allow applications to release previously acquired images without presenting them.
Promotion to VK_KHR_swapchain_maintenance1
All functionality in this extension is included in
VK_KHR_swapchain_maintenance1, with the suffix changed to KHR.
The original type, enum and command names are still available as aliases of
the KHR functionality.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPresentInfoKHR:
-
Extending VkSwapchainCreateInfoKHR:
New Enum Constants
-
VK_EXT_SWAPCHAIN_MAINTENANCE_1_EXTENSION_NAME -
VK_EXT_SWAPCHAIN_MAINTENANCE_1_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SWAPCHAIN_MAINTENANCE_1_FEATURES_EXT -
VK_STRUCTURE_TYPE_RELEASE_SWAPCHAIN_IMAGES_INFO_EXT -
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_FENCE_INFO_EXT -
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODES_CREATE_INFO_EXT -
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODE_INFO_EXT -
VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_SCALING_CREATE_INFO_EXT
-
-
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT
-
VK_EXT_texel_buffer_alignment
- Name String
-
VK_EXT_texel_buffer_alignment - Extension Type
-
Device extension
- Registered Extension Number
-
282
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Jeff Bolz [GitHub]jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-06
- 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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT
suffix omitted.
However, only the properties structure is promoted.
The feature structure is not promoted and texelBufferAlignment is
enabled if using a Vulkan 1.3 instance.
External interactions defined by this extension, such as SPIR-V token names,
retain their original names.
The original Vulkan API 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Jan-Harald Fredriksen [GitHub]janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2019-05-28
- 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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. However, the feature is made optional in Vulkan 1.3. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- API Interactions
-
-
Interacts with VK_EXT_debug_marker
-
Interacts with VK_EXT_debug_report
-
Interacts with VK_EXT_debug_utils
-
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Tobias Hector [GitHub]tobski
-
Other Extension Metadata
- Last Modified Date
-
2018-11-05
- 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
-
-
Extending VkToolPurposeFlagBits:
-
VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT_EXT -
VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT_EXT -
VK_TOOL_PURPOSE_PROFILING_BIT_EXT -
VK_TOOL_PURPOSE_TRACING_BIT_EXT -
VK_TOOL_PURPOSE_VALIDATION_BIT_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
Vulkan APIs in this extension are included in core Vulkan 1.3, with the EXT suffix omitted. External interactions defined by this extension, such as SPIR-V token names, retain their original names. The original Vulkan API 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);
}
}
VK_EXT_validation_features
- Name String
-
VK_EXT_validation_features - Extension Type
-
Instance extension
- Registered Extension Number
-
248
- Revision
-
6
- Ratification Status
-
Ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Deprecated by VK_EXT_layer_settings extension
-
- Special Use
- Contact
-
-
Karl Schultz [GitHub]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 structure 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.
Deprecation by VK_EXT_layer_settings
Functionality in this extension is subsumed into the
VK_EXT_layer_settings extension.
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
-
-
Revision 6, 2023-09-25 (Christophe Riccio)
-
Marked as deprecated by VK_EXT_layer_settings
-
VK_EXT_validation_flags
- Name String
-
VK_EXT_validation_flags - Extension Type
-
Instance extension
- Registered Extension Number
-
62
- Revision
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Deprecated by VK_EXT_layer_settings extension
-
- Special Use
- Contact
-
-
Tobin Ehlis [GitHub]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 structure 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_layer_settings
Functionality in this extension is subsumed into the
VK_EXT_layer_settings 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
-
VK_EXT_vertex_attribute_divisor
- Name String
-
VK_EXT_vertex_attribute_divisor - Extension Type
-
Device extension
- Registered Extension Number
-
191
- Revision
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_vertex_attribute_divisor extension
-
Which in turn was promoted to Vulkan 1.4
-
-
- Contact
-
-
Vikram Kushwaha [GitHub]vkushwaha
-
Other Extension Metadata
- Last Modified Date
-
2018-08-03
- IP Status
-
No known IP claims.
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Faith 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 =
{
.binding = 0,
.divisor = 4
};
const VkPipelineVertexInputDivisorStateCreateInfoEXT divisorInfo =
{
.sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT,
.pNext = NULL,
.vertexBindingDivisorCount = 1,
.pVertexBindingDivisors = &divisorDesc
}
const VkVertexInputBindingDescription binding =
{
.binding = 0,
.stride = sizeof(Vertex),
.inputRate = VK_VERTEX_INPUT_RATE_INSTANCE
};
const VkPipelineVertexInputStateCreateInfo viInfo =
{
.sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO,
.pNext = &divisorInfo,
...
};
//...
Version History
-
Revision 1, 2017-12-04 (Vikram Kushwaha)
-
First Version
-
-
Revision 2, 2018-07-16 (Faith 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_attribute_robustness
- Name String
-
VK_EXT_vertex_attribute_robustness - Extension Type
-
Device extension
- Registered Extension Number
-
609
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_maintenance9 extension
-
- Contact
-
-
Piers Daniell [GitHub]pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2024-11-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Daniel Story, Nintendo
-
Description
It can be detrimental to performance for applications to have to define fake vertex attribute locations and buffer bindings for vertex shaders that may reference attribute locations for which there is no vertex data.
This extension allows applications to not have to specify fake vertex attribute locations, and if the vertex shader reads those attributes it will read (0,0,0,0) or (0,0,0,1).
New Enum Constants
-
VK_EXT_VERTEX_ATTRIBUTE_ROBUSTNESS_EXTENSION_NAME -
VK_EXT_VERTEX_ATTRIBUTE_ROBUSTNESS_SPEC_VERSION -
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_ROBUSTNESS_FEATURES_EXT
-
VK_EXT_ycbcr_2plane_444_formats
- Name String
-
VK_EXT_ycbcr_2plane_444_formats - Extension Type
-
Device extension
- Registered Extension Number
-
331
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to Vulkan 1.3
-
- Contact
-
-
Tony Zlatinski [GitHub]tzlatinski
-
Other Extension Metadata
- Last Modified Date
-
2020-07-28
- 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
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Promoted to VK_KHR_draw_indirect_count extension
-
Which in turn was promoted to Vulkan 1.2
-
-
- Contact
-
-
Daniel Rakos [GitHub]drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2016-08-23
- 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.
VK_AMD_gpu_shader_half_float
- Name String
-
VK_AMD_gpu_shader_half_float - Extension Type
-
Device extension
- Registered Extension Number
-
37
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Deprecation State
-
-
Deprecated by VK_KHR_shader_float16_int8 extension
-
Which in turn was promoted to Vulkan 1.2
-
-
- Contact
-
-
Dominik Witczak [GitHub]dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2019-04-11
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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 is included in the
VK_KHR_shader_float16_int8 extension, when the
shaderFloat16 feature is enabled.
VK_AMD_gpu_shader_int16
- Name String
-
VK_AMD_gpu_shader_int16 - Extension Type
-
Device extension
- Registered Extension Number
-
133
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- SPIR-V Dependencies
- Deprecation State
-
-
Deprecated by VK_KHR_shader_float16_int8 extension
-
Which in turn was promoted to Vulkan 1.2
-
-
- Contact
-
-
Qun Lin [GitHub]linqun
-
Other Extension Metadata
- Last Modified Date
-
2019-04-11
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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 is included in the
VK_KHR_shader_float16_int8 extension, when the
shaderInt16 and shaderFloat16 features are enabled.
VK_AMD_negative_viewport_height
- Name String
-
VK_AMD_negative_viewport_height - Extension Type
-
Device extension
- Registered Extension Number
-
36
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Obsoleted by VK_KHR_maintenance1 extension
-
Which in turn was promoted to Vulkan 1.1
-
-
- Contact
-
-
Matthaeus G. Chajdas [GitHub]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 the
VK_KHR_maintenance1 extension 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.
VK_ARM_rasterization_order_attachment_access
- Name String
-
VK_ARM_rasterization_order_attachment_access - Extension Type
-
Device extension
- Registered Extension Number
-
343
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_EXT_rasterization_order_attachment_access extension
-
- Contact
-
-
Jan-Harald Fredriksen [GitHub]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
Render passes, and specifically subpass 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.
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_IMG_format_pvrtc
- Name String
-
VK_IMG_format_pvrtc - Extension Type
-
Device extension
- Registered Extension Number
-
55
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Deprecated without replacement
-
- 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).
|
Note
|
As also noted in the Khronos Data Format Specification, PVRTC1 images must have dimensions that are a power of two. |
Deprecation
Both PVRTC1 and PVRTC2 are slower than standard image formats on PowerVR GPUs, and support will be removed from future hardware.
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_MVK_ios_surface
- Name String
-
VK_MVK_ios_surface - Extension Type
-
Instance extension
- Registered Extension Number
-
123
- Revision
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Deprecated by VK_EXT_metal_surface extension
-
- Contact
-
-
Bill Hollings [GitHub]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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Deprecated by VK_EXT_metal_surface extension
-
- Contact
-
-
Bill Hollings [GitHub]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_compute_shader_derivatives
- Name String
-
VK_NV_compute_shader_derivatives - Extension Type
-
Device extension
- Registered Extension Number
-
202
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_compute_shader_derivatives extension
-
- Contact
-
-
Pat Brown [GitHub]nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2018-07-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
-
VK_NV_dedicated_allocation
- Name String
-
VK_NV_dedicated_allocation - Extension Type
-
Device extension
- Registered Extension Number
-
27
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Deprecated by VK_KHR_dedicated_allocation extension
-
Which in turn was promoted to Vulkan 1.1
-
-
- Contact
-
-
Jeff Bolz [GitHub]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 =
{
.sType = VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV,
.pNext = NULL,
.dedicatedAllocation = VK_TRUE,
};
VkImageCreateInfo imageCreateInfo =
{
.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO,
.pNext = &dedicatedImageInfo
// 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 =
{
.sType = VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV,
.pNext = NULL,
.image = image,
.buffer = VK_NULL_HANDLE,
};
VkMemoryAllocateInfo memoryAllocateInfo =
{
.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO,
.pNext = &dedicatedInfo,
.allocationSize = memoryRequirements.size,
.memoryTypeIndex = FindMemoryTypeIndex(memoryRequirements.memoryTypeBits),
};
VkDeviceMemory memory;
vkAllocateMemory(
device,
&memoryAllocateInfo,
NULL, // pAllocator
&memory);
// Bind the image to the memory
vkBindImageMemory(
device,
image,
memory,
0);
VK_NV_displacement_micromap
- Name String
-
VK_NV_displacement_micromap - Extension Type
-
Device extension
- Registered Extension Number
-
398
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
-
This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.
-
- Deprecation State
-
-
Deprecated by VK_NV_cluster_acceleration_structure extension
-
- Contact
-
-
Christoph Kubisch [GitHub]pixeljetstream
-
Eric Werness [GitHub]ewerness-nv
-
Other Extension Metadata
- Last Modified Date
-
2023-03-17
- Interactions and External Dependencies
-
TBD
- Contributors
-
-
Christoph Kubisch, NVIDIA
-
Eric Werness, NVIDIA
-
Description
Ray tracing can very efficiently render from geometry which has very fine detail, but when using only a basic triangle representation, memory consumption can be an issue. This extension adds the ability to add a displacement map to add more detail to triangles in an acceleration structure with an efficient in-memory format. The format is externally visible to allow the application to compress its internal geometry representations into the compressed format ahead of time. This format adds displacements along a defined vector to subtriangle vertices which are subdivided from the main triangles.
This extension provides:
-
a new VkMicromapTypeEXT format for the displacement micromap,
-
a structure to extend VkAccelerationStructureGeometryTrianglesDataKHR to attach a displacement micromap to the geometry of the acceleration structure,
-
enums extending VkBuildAccelerationStructureFlagBitsKHR to allow for updates.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
New Enum Constants
-
VK_NV_DISPLACEMENT_MICROMAP_EXTENSION_NAME -
VK_NV_DISPLACEMENT_MICROMAP_SPEC_VERSION -
Extending VkBuildAccelerationStructureFlagBitsKHR:
-
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_BIT_NV -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV
-
-
Extending VkMicromapTypeEXT:
-
VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_DISPLACEMENT_MICROMAP_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_FEATURES_NV -
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_PROPERTIES_NV
-
Issues
(1) What is the status of this extension?
-
Deprecated. The VK_NV_cluster_acceleration_structure extension is not a one-to-one replacement for this extension but enables similar performance improvements for high-tessellation geometry and is considered the preferred direction to improve high-tessellation geometry performance.
VK_NV_external_memory
- Name String
-
VK_NV_external_memory - Extension Type
-
Device extension
- Registered Extension Number
-
57
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Deprecated by VK_KHR_external_memory extension
-
Which in turn was promoted to Vulkan 1.1
-
-
- Contact
-
-
James Jones [GitHub]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 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
(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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Deprecated by VK_KHR_external_memory_capabilities extension
-
Which in turn was promoted to Vulkan 1.1
-
-
- Contact
-
-
James Jones [GitHub]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 structure 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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Deprecated by VK_KHR_external_memory_win32 extension
-
- Contact
-
-
James Jones [GitHub]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 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
(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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- SPIR-V Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_fragment_shader_barycentric extension
-
- Contact
-
-
Pat Brown [GitHub]nvpbrown
-
Other Extension Metadata
- Last Modified Date
-
2018-08-03
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
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
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
-
None
- Deprecation State
-
-
Deprecated without replacement
-
- Contact
-
-
Piers Daniell [GitHub]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_ray_tracing
- Name String
-
VK_NV_ray_tracing - Extension Type
-
Device extension
- Registered Extension Number
-
166
- Revision
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- API Interactions
-
-
Interacts with VK_VERSION_1_1
-
Interacts with VK_EXT_debug_report
-
Interacts with VK_KHR_get_memory_requirements2
-
- SPIR-V Dependencies
- Deprecation State
-
-
Deprecated by VK_KHR_ray_tracing_pipeline extension
-
- Contact
-
-
Eric Werness [GitHub]ewerness-nv
-
Other Extension Metadata
- Last Modified Date
-
2018-11-20
- Interactions and External Dependencies
-
-
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:
If VK_KHR_get_memory_requirements2 or Vulkan Version 1.1 is supported:
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 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
-
If VK_EXT_debug_report is supported:
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV_EXT
-
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_win32_keyed_mutex
- Name String
-
VK_NV_win32_keyed_mutex - Extension Type
-
Device extension
- Registered Extension Number
-
59
- Revision
-
2
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_KHR_win32_keyed_mutex extension
-
- Contact
-
-
Carsten Rohde [GitHub]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.
-
VK_QCOM_fragment_density_map_offset
- Name String
-
VK_QCOM_fragment_density_map_offset - Extension Type
-
Device extension
- Registered Extension Number
-
426
- Revision
-
3
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_EXT_fragment_density_map_offset extension
-
- Contact
-
-
Matthew Netsch [GitHub]mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2024-06-17
- Contributors
-
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Jonathan Tinkham, Qualcomm Technologies, Inc.
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Manan Katwala, Qualcomm Technologies, Inc.
-
Connor Abbott, Valve Corporation
-
Description
This extension allows an application to specify offsets to a fragment density map attachment, changing the location where the fragment density map is applied to the framebuffer. This is helpful for eye-tracking use cases where the fovea needs to be moved around the framebuffer to match the eye pose.
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
-
Version History
-
Revision 3, 2025-03-20 (Connor Abbott/Matthew Netsch)
-
Fix clamp equation and clarify the offsets are FDM relative (editorial only)
-
-
Revision 2, 2024-06-17 (Matthew Netsch)
-
Fix typo in spec regarding fragmentDensityMapOffset feature
-
-
Revision 1, 2021-09-03 (Matthew Netsch)
-
Initial version
-
VK_VALVE_mutable_descriptor_type
- Name String
-
VK_VALVE_mutable_descriptor_type - Extension Type
-
Device extension
- Registered Extension Number
-
352
- Revision
-
1
- Ratification Status
-
Not ratified
- Extension and Version Dependencies
- Deprecation State
-
-
Promoted to VK_EXT_mutable_descriptor_type extension
-
- Special Use
- Contact
-
-
Joshua Ashton [GitHub]Joshua-Ashton
-
Hans-Kristian Arntzen [GitHub]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
-
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 |
Roadmap 2024
The Roadmap 2024 milestone is intended to be supported by newer mid-to-high-end devices shipping in 2024 or shortly thereafter across mainstream smartphone, tablet, laptops, console and desktop devices.
Two of the core aims of this roadmap profile are to enable developers to rely on a number of important rasterization and shader features have been available for a long time, but until now have not enjoyed wide support.
Shader features required include smaller types (8/16-bit integers and 16-bit floats), reconvergence guarantees for subgroup ops (VK_KHR_shader_maximal_reconvergence and VK_KHR_shader_quad_control), and more consistent floating-point handling (VK_KHR_shader_float_controls2 and round-to-nearest-even for 32-/16-bit floats). Rasterization features include requiring support for multi-draw indirect, shader draw parameters, 8-bit indices, better line rasterization definitions, and local reads when using dynamic rendering. A few other features have been added opportunistically, in lieu of shipping a Vulkan 1.4 in the same time frame, such as push descriptors and the various minor improvements included in VK_KHR_maintenance5.
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 |
|---|---|---|---|---|
|
- |
4 |
7 |
min |
|
- |
4 |
8 |
min |
|
- |
FALSE |
TRUE |
Boolean |
| Limit Name | Unsupported Limit | Core Limit | Profile Limit | Limit Type1 |
|---|---|---|---|---|
|
- |
FALSE |
TRUE |
Boolean |
|
- |
FALSE |
TRUE |
Boolean |
Appendix G: Deprecation
Functionality in the specification such as commands and structures may be marked as deprecated, indicating that applications should avoid using it. A link to an explanatory section will be provided to explain how and why the functionality was deprecated, what functionality replaces it (if any), and what applications should do instead. Reasons for deprecating functionality may include:
-
Newer functionality fulfills the same role
-
Does not work as originally intended
-
Functionality cannot continue to work with newer features
|
Note
|
Deprecation is tagged in the xml registry, with both core versions and extensions able to express deprecation of any other interface. All deprecations will be listed in this section, however only functionality deprecated by a core version that is present will be emphasized with warnings. |
Deprecated functionality will remain available for backwards compatibility until a new major core version removes it, but applications targeting more recent versions of Vulkan should still avoid using deprecated functionality. Interactions with deprecated functionality will often be omitted when new extensions or features are developed, so deprecated functionality may not work with the latest features.
|
Note
|
Extensions can be deprecated in their entirety by a different mechanism, and are marked as deprecated in their appendix. See the Deprecation section of the Extensions chapter for more information. |
Deprecated Functionality
When functionality is deprecated, an explanation of its deprecation will be added to the below sections.
|
Note
|
This list is a work in progress - we intend to add other items to this section over time; things such as shader modules (deprecated by VK_KHR_maintenance5) and anything superseded by a new version of the same functionality (e.g. VK_KHR_synchronization2). |
Physical Device Queries: Deprecation via version 2
VK_KHR_get_physical_device_properties2 was incorporated into Vulkan 1.1, which introduced new versions of several physical device query functions. These provide the same functionality as the Vulkan 1.0 functionality but with greater extensibility.
When querying device features, vkGetPhysicalDeviceFeatures2 should be
used instead of vkGetPhysicalDeviceFeatures.
When enabling device features, VkPhysicalDeviceFeatures2 should be
provided in the pNext chain of VkDeviceCreateInfo instead of
using VkDeviceCreateInfo::pNext:pEnabledFeatures.
Version Macros: Deprecation via replacements including API variant
The version macros that do not take the API variant into account, such as VK_MAKE_VERSION or VK_VERSION_MAJOR, are deprecated by those that do, such as VK_MAKE_API_VERSION or VK_API_VERSION_MAJOR.
Instead of VK_API_VERSION, specific version defines (e.g. VK_API_VERSION_1_0) or the VK_MAKE_API_VERSION macro should be used instead.
Render Pass Functions: Deprecation via version 2
VK_KHR_create_renderpass2 was incorporated into Vulkan 1.2, which introduced new versions of several render pass functions. These provide the same functionality as the Vulkan 1.0 functionality but with greater extensibility.
|
Note
|
Render pass objects and all related commands are further deprecated by dynamic rendering in Vulkan 1.4. |
Render Pass Objects: Deprecation via dynamic rendering
In Vulkan 1.3, the VK_KHR_dynamic_rendering extension was promoted into core, which added a new way to specify render passes without needing to create VkFramebuffer and VkRenderPass objects. However, subpass functionality had no equivalent, meaning dynamic rendering was only suitable as a substitute for content not using subpasses.
In Vulkan 1.4 however, VK_KHR_dynamic_rendering_local_read was promoted into core as well, which allows the expression of most subpass functionality in core or extensions. Any subpass functionality which was not replicated is still expressible but requires applications to split work over multiple dynamic render pass instances. Functionality not covered with local reads would result in most or all vendors splitting the subpass internally.
|
Note
|
VK_QCOM_render_pass_shader_resolve does not have equivalent functionality exposed via dynamic rendering. Use of deprecated functionality will be required to use that extension unless/until replacements are created. |
Outside of vendor extensions, applications are advised to make use of vkCmdBeginRendering and vkCmdEndRendering to manage render passes from this API version onward.
Appendix H: 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://registry.khronos.org/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 and / or uses a
small number of C preprocessor macros that are described below.
Vulkan Header File Compile Time Controls
If the VK_NO_PROTOTYPES macro is defined by an application at compile
time, prototypes for Vulkan APIs will not be included.
Only typedefs for API function pointers will be defined.
This is intended for applications using their own function loader and dispatch mechanism.
If the macro is not defined by the application, prototypes for Vulkan APIs will be included.
If the VK_ONLY_EXPORTED_PROTOTYPES macro is defined by an application
at compile time, only prototypes for Vulkan APIs tagged as `"exported"`in
the API XML will be included.
For non-tagged APIs, only typedefs for API function pointers will be
defined.
This is intended to match APIs which are statically exported by the Vulkan loader. At present, the exported APIs are only those defined by Vulkan core versions.
If the macro is not defined by the application, prototypes for all Vulkan APIs will be included.
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 321
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, 4, VK_HEADER_VERSION)
VK_API_VERSION is now commented out of vulkan_core.h and cannot be
used.
|
Warning
|
This functionality is deprecated by Vulkan Version 1.0. See Deprecated Functionality for more information. |
// Provided by VK_VERSION_1_0
//#define VK_API_VERSION VK_MAKE_API_VERSION(0, 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__) || (defined(__riscv) && __riscv_xlen == 64)
#define VK_USE_64_BIT_PTR_DEFINES 1
#else
#define VK_USE_64_BIT_PTR_DEFINES 0
#endif
#endif
|
Note
|
The |
|
Note
|
This macro was introduced starting with the Vulkan 1.2.174 headers, and its
availability can be checked at compile time by requiring
It is not available if you are using older headers, such as may be shipped with an older Vulkan SDK. Developers requiring this functionality may wish to include a copy of the current Vulkan headers with their project in this case. |
Window System-Specific Header Control (Informative)
To use a Vulkan extension supporting a platform-specific window system, header files for that window system must be included at compile time, or platform-specific types must be forward-declared. The Vulkan header files are unable to 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 they need to 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 |
|
|
OHOS |
|
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. |
Video Std Headers
Performing video coding operations usually involves the application having to provide various parameters, data structures, or other syntax elements specific to the particular video compression standard used, and the associated semantics are covered by the specification of those.
The interface descriptions of these are available in the header files
derived from the video.xml XML file, which is the canonical
machine-readable description of data structures and enumerations that are
associated with the externally-provided video compression standards.
| Video Std Header Name | Description | Header File | Related Extensions |
|---|---|---|---|
|
Codec-independent common definitions |
|
- |
|
ITU-T H.264 common definitions |
|
|
|
ITU-T H.264 decode-specific definitions |
|
|
|
ITU-T H.264 encode-specific definitions |
|
|
|
ITU-T H.265 common definitions |
|
|
|
ITU-T H.265 decode-specific definitions |
|
|
|
ITU-T H.265 encode-specific definitions |
|
|
|
VP9 common definitions |
|
|
|
VP9 decode-specific definitions |
|
|
|
AV1 common definitions |
|
|
|
AV1 decode-specific definitions |
|
|
|
AV1 encode-specific definitions |
|
Appendix I: 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 J: 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.
- API command
-
Any command defined in the Vulkan specification. These entry points all have a vk prefix.
- Aspect (Image)
-
Some image types contain multiple kinds (called “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 can 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.
- Backward Prediction
-
Sample prediction performed during video decode and encode operations based on reference pictures that occur temporally (in display order) after the current picture.
- Backward Reference
-
A reference picture that occurs temporally (in display order) after the current picture.
- 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 in which vertex positions (
Positiondecoration) are written 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.
- Coding Block (Video)
-
An element of a video picture, comprising a rectangular block of texel values that are coded as a single unit in video coding. Video coding blocks have a corresponding coding block size (width and height) defining the dimensions of these elements in units of texels. These dimensions are usually codec-specific and a single video compression standard may support more than one coding block type and size. Video compression standards may use multiple coding block types to organize coding blocks of different kinds and sizes into hierarchies.
- 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 Buffer Nesting Level
-
The Command Buffer Nesting Level of a secondary command buffer is equal to the maximum nesting level of all secondary command buffers executed by that command buffer plus one, where a secondary command buffer that executes no other secondary command buffers has a nesting level of zero.
- 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 mip levels that can be provided for an image, from the largest application-specified mip level size down to the minimum mip level size. See Image Mip Level 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.
- Cooperative Vector
-
A SPIR-V vector type optimized for the evaluation of small neural networks.
- 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.
- Decode Output Picture
-
A video picture resource used to store the result of a video decode operation.
- Decoded Picture Buffer
-
An indexed set of reference pictures used by a video session. Abbreviated as DPB.
- Decoded Picture Buffer Slot
-
An entry within a DPB that can be associated with a particular reference picture.
- Decoded Picture Buffer Slot Index
-
The index of a DPB slot within its encompassing DPB.
- 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 compute, mesh, task, or fragment 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. Additionally, physical-device-level functionality defined by a device extension is also considered device-level functionality.
- 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, vkCmdDrawMeshTasksEXT, 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, such as vkCmdDispatch. See Dispatching Commands.
- Drawing Commands
-
Commands that provoke work using a graphics pipeline. Includes vkCmdDraw, vkCmdDrawIndexed, vkCmdDrawIndirectCount, vkCmdDrawIndexedIndirectCount, vkCmdDrawIndirectCountKHR, vkCmdDrawIndexedIndirectCountKHR, vkCmdDrawIndirectCountAMD, vkCmdDrawIndexedIndirectCountAMD, vkCmdDrawMultiIndexedEXT, vkCmdDrawMultiEXT, vkCmdDrawMeshTasksNV, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV, vkCmdDrawMeshTasksEXT, vkCmdDrawMeshTasksIndirectEXT, vkCmdDrawMeshTasksIndirectCountEXT, 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.
- Encode Input Picture
-
A video picture resource used as the input of a video encode operation.
- 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.
- Field (Video)
-
Possibly discontinuous subregions of a frame. Frames may consist of two fields, a top field and a bottom field.
- 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.
- Forward Prediction
-
Sample prediction performed during video decode and encode operations based on reference pictures that occur temporally (in display order) before the current picture.
- Forward Reference
-
A reference picture that occurs temporally (in display order) before the current picture.
- 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. - Frame (Video)
-
A multi-dimensional array of luma samples and an optional multi-dimensional array of chroma samples.
- Fragment Tile Image Interface
-
A fragment shader entry point’s variables with
TileImageEXTstorage class and a decoration ofLocation, which are used to read values from color 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 for a specific binding. This sampler is then used for that binding in all descriptor sets allocated with the layout, and it 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, vkCmdDrawMeshTasksIndirectEXT, vkCmdDrawMeshTasksIndirectCountEXT, 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, vkCmdDrawMeshTasksIndirectEXT, vkCmdDrawMeshTasksIndirectCountEXT, 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.
- Inter Block (Video)
-
A video coding block that uses inter prediction.
- Inter Prediction (Video)
-
Sample prediction derived from reference picture samples or metadata.
- 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.
- Intra Block (Video)
-
A video coding block that only uses intra prediction.
- Intra Prediction (Video)
-
Sample prediction that is not derived from reference picture samples or metadata.
- 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 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 -
a VkAccelerationStructureNV 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 VkTensorARM created with
VK_TENSOR_TILING_LINEAR_ARM
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 -
a VkTensorARM created with
VK_TENSOR_TILING_OPTIMAL_ARM
-
- 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, vkCmdDrawMeshTasksEXT, vkCmdDrawMeshTasksIndirectEXT, and vkCmdDrawMeshTasksIndirectCountEXT .
- Minimum Mip Level Size
-
The smallest size that is permitted for a mip level. For conventional images this is 1x1x1. For corner-sampled images, this is 2x2x2. See Image Mip Level 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. - Nested Command Buffers
-
A nested command buffer is a secondary command buffer that is executed by another secondary command buffer, which may itself execute other secondary command buffers.
- 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 them 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 , a given tensor, 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.
- Packed Tensor
-
A tensor whose elements are densely laid out in memory and thus whose backing memory does not contain any padding data.
- 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.
- Picture Partition (Video)
-
Collective term that refers to a subregion of a video picture resource that may be decoded or encoded independently according to the partitioning scheme defined in the corresponding video compression standard. Picture partitions may be non-rectangular.
- 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 -
OpTraceRayKHR -
OpTraceRayMotionNV -
OpTraceMotionNV -
OpHitObjectTraceRayNV -
OpHitObjectTraceRayMotionNV
-
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 necessary 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 accessible for 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 Android external formats the VkFormatFeatureFlagBits is provided by the implementation. For QNX Screen 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.
- Protected Tensor
-
A tensor 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.
- PTLAS
- 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 .
- Reconstructed Picture
-
A video picture resource reconstructed from a compressed bitstream using video decode or encode operations that can be used as a reference picture by future video decode or encode operations with the same video session.
- Recording State (Command Buffer)
-
A command buffer that is ready to record commands. See also Initial State and Executable State.
- Reference Picture
-
A video picture resource used by video decode and encode operations to provide predictions of the values of samples in the subsequently decoded or encoded pictures.
- Reference Picture Metadata
-
Opaque state associated with a DPB slot, maintained by a video session.
- 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.
- Sampled Tile Image
-
A per-tile sampled image view of a framebuffer attachment, enabled by
VK_QCOM_tile_shading. - 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. A reference in the entry point’s interface list does not constitute a static use. 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 Tensor
-
A descriptor type that represents a tensor view, and supports reads, writes, 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.
- Storage Tile Image
-
A per-tile storage image view of a framebuffer attachment, enabled by
VK_QCOM_tile_shading. - 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.
- Tensor
-
A resource that represents an N-dimensional formatted interpretation of device memory. Represented by a VkTensorARM object.
- Tensor Description
-
Describes the shape, format, usage and layout in memory of a tensor. Represented by VkTensorDescriptionARM.
- Tensor View
-
An object that represents a specific tensor, and state that controls how the contents are interpreted. Represented by a VkTensorViewARM object.
- 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.
- Tile Attachment Interface
-
The set of variables with
TileAttachmentQCOMstorage class that are statically used by a shader entry point, invoked within a tile shading render pass which read values from tiled attachments as described in tile shading.
- Tile Image
-
A per-tile view of a framebuffer attachment. If the
VK_EXT_shader_tile_imageextension is enabled, the framebuffer is considered to be divided into tiles. - 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.
- Unprotected Tensor
-
A tensor 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. - Video Bitstream Buffer
-
A resource that represents a linear array of data in device memory storing encoded video data. Represented by a VkBuffer object.
- Video Coding Scope
-
A series of subsequent commands recorded into a command buffer starting with a vkCmdBeginVideoCodingKHR command and ending with a vkCmdEndVideoCodingKHR command that encompasses a set of video decode or encode operations.
- Video Coding Operations
-
Any operations recorded into a command buffer within a video coding scope, including video decode and encode operations.
- Video Decode Operation
-
An operation consuming data from a video bitstream buffer and zero or more reference pictures, and producing data to a decode output picture and an optional reconstructed picture.
- Video Encode Operation
-
An operation consuming data from an encode input picture and zero or more reference pictures, and producing data to a video bitstream buffer and an optional reconstructed picture.
- Video Picture Resource
-
A resource that represents a multi-dimensional formatted interpretation of device memory to be used with a video session as a decode output picture, encode input picture, reconstructed picture, and/or reference picture. It may contain metadata associated with a particular video session it is used with. Represented by a VkImage object and referred to using VkImageView objects created from it.
- Video Session
-
A resource that represents and maintains the state needed to perform video decode or encode operations. Represented by a VkVideoSessionKHR object.
- Video Session Parameters
-
A resource that stores preprocessed codec-specific parameters used with a compatible video session in video codec operations. Represented by a VkVideoSessionParametersKHR object.
- Video Transcoding
-
The process of using the outputs of video decoding operations as inputs in video encoding operations.
- 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
- Log
-
Logarithm
- 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
Video-Specific Abbreviations
The following abbreviations and acronyms are used in the context of video decode and encode operations to refer to commonly used video compression terms in their usual abbreviated form:
- AVC
-
Advanced Video Coding
- Bipred
-
Bidirectional Prediction
- CABAC
-
Context-Adaptive Binary Arithmetic Coding
- CAVLC
-
Context-Adaptive Variable-Length Coding
- CBR
-
Constant Bit Rate
- CTB
-
Coding Tree Block
- Diff
-
Difference
- DPB
-
Decoded Picture Buffer
- GOP
-
Group Of Pictures
- HDR
-
High Dynamic Range
- HEVC
-
High Efficiency Video Coding
- HRD
-
Hypothetical Reference Decoder
- IDC
-
Indicator
- IDR
-
Instantaneous Decoder Refresh
- MB
-
Macroblock
- MV
-
Motion Vector
- NALU
-
Network Abstraction Layer Unit
- OBU
-
Open Bitstream Unit
- PCM
-
Pulse-Code Modulation
- Pic
-
Picture
- Pred
-
Prediction
- PPS
-
Picture Parameter Set
- QP
-
Quantization Parameter
- RC
-
Rate Control
- SPS
-
Sequence Parameter Set
- Std
-
Standard
- VBR
-
Variable Bit Rate
- VCL
-
Video Coding Layer
- VPS
-
Video Parameter Set
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 K: Credits (Informative)
Vulkan 1.4 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. (versions 1.1, 1.4)
-
Aaron Hagan, AMD (versions 1.1)
-
Abhishek Sashi Nair, Huawei Technologies Co., Ltd. (version 1.4)
-
Adam Jackson, Red Hat (versions 1.0, 1.1)
-
Adam Śmigielski, Mobica (version 1.0)
-
Aditi Verma, Qualcomm Technologies, Inc. (version 1.3)
-
Ahmed Abdelkhalek, AMD (versions 1.3, 1.4) (video subgroup chair)
-
Aidan Fabius, Core Avionics & Industrial Inc. (version 1.2)
-
Aitor Camacho, LunarG (version 1.4)
-
Alan Baker, Google (versions 1.1, 1.2, 1.3, 1.4)
-
Alan Vines, Imagination Technologies (version 1.4)
-
Alan Ward, Google (versions 1.1, 1.2)
-
Alastair Murray, Codeplay (version 1.4)
-
Alejandro Piñeiro, Igalia (version 1.1)
-
Aleks Todorov, Google (version 1.4)
-
Aleksander Netzel, Epic Games (version 1.4)
-
Alex Bourd, Qualcomm Technologies, Inc. (versions 1.0, 1.1, 1.4)
-
Alex Crabb, Caster Communications (versions 1.2, 1.3, 1.4)
-
Alex Dai, Oppo (version 1.4)
-
Alex Krstic, Qualcomm Technologies, Inc. (version 1.4)
-
Alex Todorov, Google (version 1.4)
-
Alex Walters, Imagination Technologies (versions 1.2, 1.3, 1.4)
-
Alexander Galazin, Imagination Technologies (versions 1.0, 1.1, 1.2, 1.3, 1.4) (conformance test subgroup chair)
-
Alexey Knyazev, Independent, Khronos (version 1.4)
-
Alexey Sachkov, Intel (version 1.3)
-
Ali Asif, Huawei Technologies Co., Ltd. (version 1.4)
-
Allan MacKinnon, Google (version 1.3)
-
Allen Hux, Intel (version 1.0)
-
Alon Or-bach, Arm (versions 1.0, 1.1, 1.2, 1.3, 1.4) (system integration subgroup chair)
-
Alyssa Rosenzweig, Valve Software (version 1.4)
-
Anastasia Stulova, Arm (versions 1.2, 1.3, 1.4)
-
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, 1.4) (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)
-
Andrew Zhi, AMD (version 1.4)
-
Ann Thorsnes, Khronos (versions 1.2, 1.3)
-
Anthony Salvi, Adobe (version 1.4)
-
Antoine Labour, Google (versions 1.0, 1.1)
-
Anton Berko, Mediatek (version 1.4)
-
Anuj Phogat, Netflix (version 1.4)
-
Aras Pranckevičius, Unity Technologies (version 1.0)
-
Arpit Agarwal, Qualcomm Technologies, Inc. (version 1.4)
-
Arseny Kapoulkine, Roblox (version 1.3)
-
Ashley Smith, AMD (version 1.4)
-
Ashwin Kolhe, NVIDIA (version 1.0)
-
Aurelio Reis, NVIDIA (version 1.4)
-
Avinash Baliga, NVIDIA (version 1.4)
-
Balaji Calidas, Qualcomm Technologies, Inc. (version 1.4)
-
Baldur Karlsson, Valve Software (versions 1.1, 1.2, 1.3, 1.4)
-
Barthold Lichtenbelt, NVIDIA (version 1.1)
-
Bas Nieuwenhuizen, Google (versions 1.1, 1.2, 1.4)
-
Ben Ashbaugh, Intel (version 1.4)
-
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, 1.4)
-
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)
-
Brad Grantham, LunarG (version 1.4)
-
Brent E. Insko, Intel (version 1.0)
-
Brian Ellis, Qualcomm Technologies, Inc. (version 1.0)
-
Brian Paul, VMware (versions 1.2, 1.3)
-
CAI Kangying, Huawei Technologies Co., Ltd. (version 1.4)
-
Caio Marcelo de Oliveira Filho, Intel (versions 1.2, 1.3)
-
Calle Ledjefors, Tencent (version 1.4)
-
Cass Everitt, Oculus VR (versions 1.0, 1.1)
-
Cemil Azizoglu, Canonical (version 1.0)
-
Chang-Hyo Yu, Samsung Electronics (version 1.0)
-
Charles Giessen, LunarG (versions 1.3, 1.4)
-
Charlie Lao, Google (version 1.4)
-
Charlie Turner, Igalia (version 1.4)
-
Cheng Ge, Tencent (version 1.4)
-
Chengping Luo, Mediatek (version 1.4)
-
Chia-I Wu, LunarG (version 1.0)
-
Chris Bieneman, Microsoft (version 1.4)
-
Chris Frascati, Qualcomm Technologies, Inc. (version 1.0)
-
Chris Glover, Google (versions 1.3, 1.4)
-
Christian Forfang, Arm (version 1.3)
-
Christoph Kubisch, NVIDIA (versions 1.3, 1.4)
-
Christophe Riccio, LunarG (versions 1.0, 1.1, 1.4)
-
Cody Northrop, LunarG (version 1.0)
-
Colin Riley, AMD (version 1.1)
-
Connor Abbott, Valve Software (version 1.4)
-
Caterina Shablia, Collabora (version 1.4)
-
Cort Stratton, Google (versions 1.1, 1.2)
-
Courtney Goeltzenleuchter, Google (versions 1.0, 1.1, 1.3)
-
Craig Davies, Huawei Technologies Co., Ltd. (version 1.2)
-
Craig Graham, Samsung Electronics (version 1.4)
-
Dae Kim, Imagination Technologies (versions 1.1, 1.4)
-
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, 1.4)
-
Dan Sinclair, Google (version 1.4)
-
Daniel Johnston, Intel (versions 1.0, 1.1)
-
Daniel Koch, NVIDIA (versions 1.0, 1.1, 1.2, 1.3, 1.4) (ray tracing subgroup chair)
-
Daniel Rakos, RasterGrid (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Daniel Schürmann, Valve Software (version 1.4)
-
Daniel Stone, Collabora (versions 1.1, 1.2, 1.4)
-
Daniel Story, Nintendo (version 1.4)
-
Daniel Vetter, Intel (version 1.2)
-
Daniele Vettorel, Google (version 1.4)
-
Danny Huynh, Samsung Electronics (version 1.4)
-
Dave Aronson, Adobe (version 1.4)
-
Dave Desormeaux, LunarG (version 1.4)
-
Dave Evans, Samsung Electronics (version 1.4)
-
David Airlie, Red Hat (versions 1.0, 1.1, 1.2, 1.3)
-
David Mao, AMD (versions 1.0, 1.2)
-
David McCloskey, Juice Labs (version 1.4)
-
David Miller, Miller & Mattson (versions 1.0, 1.1) (Vulkan reference card)
-
David Neto, Google (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
David Pankratz, Huawei Technologies Co., Ltd. (version 1.3)
-
David Wilkinson, AMD (version 1.2)
-
David Yu, Pixar (version 1.0)
-
Dean Sekulic, Croteam (version 1.4)
-
Dejan Mircevski, Google (version 1.1)
-
Dennis Adams, Sony (version 1.4)
-
Derek Lamberti, Arm (version 1.4)
-
Diego Novillo, Google (versions 1.3, 1.4)
-
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)
-
Eddie Hatfield, Google (version 1.4)
-
Eduardo Lima, Igalia (version 1.4)
-
Emily Stearns, Khronos (versions 1.2, 1.3, 1.4)
-
Enrique de Lucas, Imagination Technologies (version 1.4)
-
Eric Sullivan, NVIDIA (version 1.4)
-
Faith Ekstrand, Collabora (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Florian Penzkofer, Epic (version 1.4)
-
Frank (LingJun) Chen, Qualcomm Technologies, Inc. (version 1.0)
-
Frank Yang, Google (version 1.4)
-
François Duranleau, Gameloft (versions 1.3, 1.4)
-
Fred Liao, Mediatek (version 1.0)
-
Gabe Dagani, Samsung Electronics (versions 1.0, 1.4)
-
Gabor Sines, AMD (version 1.2)
-
Gang Chen, Intel (version 1.4)
-
George Erfesoglou, OVR Tech (version 1.4)
-
Graeme Leese, Broadcom (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Graham Connor, Imagination Technologies (version 1.0)
-
Graham Sellers, Electronic Arts (versions 1.0, 1.1, 1.4)
-
Graham Wihlidal, Electronic Arts (version 1.3)
-
Greg Fischer, LunarG (versions 1.1, 1.4)
-
Greg Roth, Microsoft (version 1.4)
-
Gregory Grebe, AMD (versions 1.3, 1.4)
-
Hai Nguyen, NVIDIA (versions 1.2, 1.3, 1.4)
-
Hamish Todd, Imagination Technologies (version 1.4)
-
Hans-Kristian Arntzen, Valve Software (versions 1.1, 1.2, 1.3, 1.4)
-
Heman Gala, MAGIX (version 1.4)
-
Henri Verbeet, Codeweavers (version 1.2)
-
Hugo Devillers, Saarland University (version 1.4)
-
Hwanyong Lee, Kyungpook National University (version 1.0)
-
Iago Toral, Igalia (versions 1.1, 1.2)
-
Ian Ameline, Huawei Technologies Co., Ltd. (version 1.4)
-
Ian Elliott, Google (versions 1.0, 1.1, 1.2, 1.4)
-
Ian Richardson, Intel (version 1.4)
-
Ian Romanick, Intel (versions 1.0, 1.1, 1.3, 1.4)
-
Ingrid Kelly, NVIDIA (version 1.4)
-
J. D. Rouan, Google (version 1.4)
-
Jaebaek Seo, Google (version 1.4)
-
Jake Turner, Valve Software (version 1.4)
-
Jakob Bornecrantz, Collabora (version 1.4)
-
James Fitzpatrick, Imagination Technologies (versions 1.3, 1.4)
-
James Hughes, Oculus VR (version 1.0)
-
James Jones, NVIDIA (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
James Riordon, Khronos (versions 1.2, 1.3)
-
Jamie Madill, Google (versions 1.3, 1.4)
-
Jan Hermes, Continental Corporation (versions 1.0, 1.1, 1.4)
-
Jan-Harald Fredriksen, Arm (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Jarred Davies, Imagination Technologies (version 1.4)
-
Jean Geffroy, id Software (version 1.4)
-
Jean-François Roy, Google (versions 1.1, 1.2, 1.3)
-
Jean-Noé Morrisette, Epic Games (version 1.4)
-
Jeff Bolz, NVIDIA (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Jeff Juliano, NVIDIA (versions 1.0, 1.1, 1.2, 1.4)
-
Jeff Kiel, NVIDIA (version 1.4)
-
Jeff Leger, Qualcomm Technologies, Inc. (versions 1.1, 1.3, 1.4)
-
Jeff Phillips, Khronos (versions 1.3, 1.4)
-
Jeff Vigil, Samsung Electronics (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Jens Owen, Google (versions 1.0, 1.1)
-
Jeremy Gebben, LunarG (version 1.4)
-
Jeremy Hayes, LunarG (versions 1.0, 1.4)
-
Jesse Barker, Unity Technologies (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Jesse Hall, Google (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Jessica Heerboth, NVIDIA (version 1.4)
-
Jingye Wang, Huawei Technologies Co., Ltd. (version 1.4)
-
Joe Davis, Samsung Electronics (version 1.1)
-
Johannes van Waveren, Oculus VR (versions 1.0, 1.1)
-
John Anthony, Arm (versions 1.2, 1.3, 1.4)
-
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 Stone, University of Illinois (version 1.4)
-
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, 1.4) (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)
-
Jordan Robinson, Samsung Electronics (version 1.4)
-
Joshua Ashton, Valve Software (versions 1.3, 1.4)
-
Jules Blok, Independent (version 1.4)
-
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, 1.4)
-
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 Software (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 (versions 1.3, 1.4)
-
Kris Rose, Khronos (versions 1.2, 1.3, 1.4)
-
Kristian Kristensen, Intel (versions 1.0, 1.1)
-
Krzysztof Iwanicki, Samsung Electronics (version 1.0)
-
Larry Seiler, Intel (version 1.0)
-
Laura Hermanns, Epic Games (version 1.4)
-
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)
-
Leonid Fedorov, Huawei Technologies Co., Ltd. (version 1.4)
-
Liam Middlebrook, NVIDIA (version 1.3)
-
Lina Versace, Google (versions 1.0, 1.1, 1.2, 1.4) (system integration subgroup chair)
-
Lionel Duc, NVIDIA (version 1.4)
-
Lionel Landwerlin, Intel (versions 1.1, 1.2, 1.4)
-
Lisie Aartsen, Khronos (versions 1.3, 1.4)
-
Liz Maitral, Khronos (version 1.2)
-
Lorenzo Dal Col, Khronos (version 1.4) (conformance test subgroup chair)
-
Lou Kramer, AMD (version 1.3)
-
Lutz Latta, Lucasfilm (version 1.0)
-
Lynne Iribarren, Independent (version 1.4)
-
Maciej Jesionowski, AMD (version 1.1)
-
Mahmoud Kharsa, Samsung Electronics (version 1.4)
-
Mais Alnasser, AMD (versions 1.1, 1.4)
-
Marcin Kantoch, AMD (version 1.3)
-
Marcin Rogucki, Mobica (version 1.1)
-
Maria Rovatsou, Codeplay Software Ltd. (version 1.0)
-
Mariusz Merecki, Intel (versions 1.3, 1.4)
-
Marijn Suijten, Traverse Research (version 1.4)
-
Mark Bellamy, Arm (versions 1.2, 1.3, 1.4)
-
Mark Callow, Independent (versions 1.0, 1.1, 1.2, 1.3)
-
Dhruv Mark Collins, Igalia (version 1.4)
-
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, 1.4)
-
Markus Tavenrath, NVIDIA (version 1.1)
-
Marty Johnson, Khronos (versions 1.3, 1.4)
-
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. (versions 1.1, 1.3, 1.4) (conformance test subgroup chair)
-
Matthew Rusch, NVIDIA (version 1.3)
-
Matthäus Chajdas, Intel (versions 1.1, 1.2, 1.3, 1.4)
-
Maurice Ribble, Qualcomm Technologies, Inc. (versions 1.0, 1.1)
-
Maxim Lukyanov, Samsung Electronics (version 1.0)
-
Maximilien Dagois, Google (version 1.4)
-
Michael Antilla, Google (version 1.4)
-
Michael Blumenkrantz, Valve Software (versions 1.3, 1.4)
-
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, 1.4)
-
Mick Beaver, Electronic Arts (version 1.4)
-
Mika Isojarvi, Google (versions 1.0, 1.1)
-
Mike Schuchardt, LunarG (versions 1.1, 1.2, 1.4)
-
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, 1.4)
-
Mythri Venugopal, Samsung Electronics (version 1.0)
-
Máté Ferenc Nagy-Egri, RasterGrid (version 1.4)
-
Natalie Chouinard, Google (version 1.4)
-
Nathan Gauër, Google (version 1.4)
-
Nathaniel Cesario, LunarG (version 1.4)
-
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, 1.4) (portability subgroup chair)
-
Nick Penwarden, Epic Games (version 1.0)
-
Nicola Zaghen, Innosilicon (version 1.4)
-
Nicolai Hähnle, AMD (version 1.1)
-
Nikhil Joshi, NVIDIA (version 1.4)
-
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)
-
Pan Gao, Huawei Technologies Co., Ltd. (version 1.4)
-
Pat Brown, NVIDIA (version 1.0)
-
Patrick Boyle, Qualcomm Technologies, Inc. (version 1.4)
-
Patrick Cozzi, Independent (version 1.1)
-
Patrick Doane, Activision (versions 1.0, 1.4)
-
Patrick Han, Samsung Electronics (version 1.4)
-
Patrick Mours, NVIDIA (version 1.4)
-
Pau Baiget, Google (version 1.4)
-
Peter Kutz, Adobe (version 1.4)
-
Peter Lohrmann, AMD (versions 1.0, 1.2)
-
Peter Quayle, Imagination Technologies (version 1.4)
-
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, 1.4)
-
Ping Liu, Intel (versions 1.3, 1.4)
-
Piotr Bialecki, Intel (version 1.0)
-
Piotr Byszewski, Mobica (version 1.3)
-
Prabindh Sundareson, Samsung Electronics (version 1.0)
-
Pradyuman Singh, NVIDIA (version 1.4)
-
Pyry Haulos, Google (versions 1.0, 1.1) (conformance test subgroup chair)
-
Rachel Bradshaw, Caster Communications (version 1.3)
-
Rajeev Rao, Qualcomm Technologies, Inc. (version 1.2)
-
Ralph Potter, Samsung Electronics (versions 1.1, 1.2, 1.3, 1.4) (working group chair)
-
Ran Wang, Google (version 1.4)
-
Raun Krisch, Samsung Electronics (version 1.3)
-
Ravi Patlegar, AMD (version 1.4)
-
Ravikiran Pallapatula, Huawei Technologies Co., Ltd. (version 1.4)
-
Ray Smith, Arm (versions 1.0, 1.1, 1.2)
-
Ricardo Garcia, Igalia (versions 1.3, 1.4)
-
Richard Huddy, Samsung Electronics (versions 1.2, 1.3)
-
Richard Van Natta, Firaxis (version 1.4)
-
Richard Wang, Huawei Technologies Co., Ltd. (version 1.4)
-
Rick Hammerstone, Qualcomm Technologies, Inc. (version 1.4)
-
Rob Barris, NVIDIA (version 1.1)
-
Rob Stepinski, Transgaming (version 1.0)
-
Robert Simpson, Qualcomm Technologies, Inc. (versions 1.0, 1.1, 1.3, 1.4)
-
Rohan Garg, Intel (version 1.4)
-
Rolando Caloca Olivares, Epic Games (versions 1.0, 1.1, 1.2, 1.3)
-
Ronan Keryell, Xilinx (versions 1.3, 1.4)
-
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, 1.4)
-
SU Fujia, Huawei Technologies Co., Ltd. (version 1.4)
-
Sam Martin, Arm (version 1.4)
-
Samuel (Sheng-Wen) Huang, Mediatek (versions 1.3, 1.4)
-
Samuel Iglesias Gonsalvez, Igalia (version 1.3)
-
Samuel Pitoiset, Valve Software (version 1.4)
-
Sandeep Kakarlapudi, Arm (version 1.4)
-
Sascha Willems, Self (versions 1.3, 1.4)
-
Sean Ellis, Arm (version 1.0)
-
Sean Harmer, KDAB Group (versions 1.0, 1.1)
-
Serdar Kocdemir, Google (version 1.4)
-
Sergey Solovyev, Tencent (version 1.4)
-
Seth Williams, NVIDIA (version 1.4)
-
Shahbaz Youssefi, Google (version 1.4)
-
Shannon Woods, NVIDIA (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Shaun Heald, Innosilicon (version 1.4)
-
Sinuhe Hardegree, Samsung Electronics (version 1.4)
-
Slawomir Cygan, Intel (versions 1.0, 1.1, 1.3, 1.4)
-
Slawomir Grajewski, Intel (versions 1.0, 1.1, 1.3, 1.4)
-
Sorel Bosan, AMD (version 1.1)
-
Soroush Kashani, Imagination Technologies (version 1.4)
-
Spencer Fricke, LunarG (versions 1.2, 1.3, 1.4)
-
Stefanus Du Toit, Google (version 1.0)
-
Stephane Cerveau, Igalia (version 1.4)
-
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 (versions 1.3, 1.4)
-
Steven Gu, Huawei Technologies Co., Ltd. (version 1.4)
-
Steven Perron, Google (version 1.4)
-
Stuart Smith, AMD (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Sujeevan Rajayogam, Google (version 1.3)
-
Theresa Foley, Intel (version 1.0)
-
Thomas Caissard, Adobe (version 1.4)
-
Tiago Costa, Epic Games (version 1.4)
-
Tilmann Scheller, Samsung Electronics (version 1.1)
-
Tim Lewis, Khronos (versions 1.3, 1.4)
-
Timo Suoranta, AMD (version 1.0)
-
Timothy Lottes, AMD (versions 1.0, 1.1)
-
Timur Kristof, Valve Software (version 1.4)
-
Ting Wei, Arm (version 1.4)
-
Tobias Hector, AMD (versions 1.0, 1.1, 1.2, 1.3, 1.4) (validity language and toolchain)
-
Tobin Ehlis, LunarG (version 1.0)
-
Tom Olson, Arm (versions 1.0, 1.1, 1.2, 1.3, 1.4) (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 (versions 1.3, 1.4)
-
Trevor Black, Google (version 1.4)
-
Tyler Nowicki, AMD (version 1.4)
-
Vassili Nikolaev, NVIDIA (version 1.4)
-
Vatsalya Prasad, Huawei Technologies Co., Ltd. (version 1.4)
-
Victor Eruhimov, Unknown (version 1.1)
-
Vikram Kushwaha, NVIDIA (versions 1.3, 1.4)
-
Vikram Tarikere, Imagination Technologies (version 1.4)
-
Vincent Hindriksen, Stream HPC (versions 1.2, 1.3)
-
Víctor Jáquez, Igalia (version 1.4)
-
Wang Jingye, Huawei Technologies Co., Ltd. (version 1.4)
-
Wasim Abbas, Arm (version 1.3)
-
Wayne Lister, Imagination Technologies (version 1.0)
-
William Wheeler, Imagination Technologies (version 1.4)
-
Wolfgang Engel, Unknown (version 1.1)
-
Wooyoung Kim, Qualcomm Technologies, Inc. (version 1.4)
-
Wyvern Wang, Huawei Technologies Co., Ltd. (version 1.3)
-
Yajun Zhang, Tencent (version 1.4)
-
Yanjun Zhang, VeriSilicon (versions 1.0, 1.1, 1.2, 1.3, 1.4)
-
Youngwang Kim, Arm (version 1.4)
-
Yu Chang Wang, Huawei Technologies Co., Ltd. (version 1.4)
-
Yuehai Du, Qualcomm Technologies, Inc. (version 1.4)
-
Yunxing Zhu, Huawei Technologies Co., Ltd. (version 1.3)
-
Yury Uralsky, NVIDIA (version 1.4)
-
Zehui Lin, Huawei Technologies Co., Ltd. (version 1.4)
-
Žiga Markuš, LunarG (version 1.4)
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 and beyond was provided by Khronos staff including Ann Thorsnes, Blaine Kohl, Dennis Fu, Dominic Agoro-Ombaka, Emily Stearns, Jeff Phillips, Kendra Casper, 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.