6. Command Buffers
Command buffers are objects used to record commands which can be subsequently submitted to a device queue for execution. There are two levels of command buffers - primary command buffers, which can execute secondary command buffers, and which are submitted to queues, and secondary command buffers, which can be executed by primary command buffers, and which are not directly submitted to queues.
Command buffers are represented by VkCommandBuffer
handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_HANDLE(VkCommandBuffer)
Recorded commands include commands to bind pipelines and descriptor sets to the command buffer, commands to modify dynamic state, commands to draw (for graphics rendering), commands to dispatch (for compute), commands to execute secondary command buffers (for primary command buffers only), commands to copy buffers and images, and other commands.
Each command buffer manages state independently of other command buffers. There is no inheritance of state across primary and secondary command buffers, or between secondary command buffers. When a command buffer begins recording, all state in that command buffer is undefined. When secondary command buffer(s) are recorded to execute on a primary command buffer, the secondary command buffer inherits no state from the primary command buffer, and all state of the primary command buffer is undefined after an execute secondary command buffer command is recorded. There is one exception to this rule - if the primary command buffer is inside a render pass instance, then the render pass and subpass state is not disturbed by executing secondary command buffers. For state dependent commands (such as draws and dispatches), any state consumed by those commands must not be undefined.
VkCommandBufferInheritanceViewportScissorInfoNV defines an exception allowing limited inheritance of dynamic viewport and scissor state.
Unless otherwise specified, and without explicit synchronization, the various commands submitted to a queue via command buffers may execute in arbitrary order relative to each other, and/or concurrently. Also, the memory side effects of those commands may not be directly visible to other commands without explicit memory dependencies. This is true within a command buffer, and across command buffers submitted to a given queue. See the synchronization chapter for information on implicit and explicit synchronization between commands.
6.1. Command Buffer Lifecycle
Each command buffer is always in one of the following states:
- Initial
-
When a command buffer is allocated, it is in the initial state. Some commands are able to reset a command buffer (or a set of command buffers) back to this state from any of the executable, recording or invalid state. Command buffers in the initial state can only be moved to the recording state, or freed.
- Recording
-
vkBeginCommandBuffer changes the state of a command buffer from the initial state to the recording state. Once a command buffer is in the recording state,
vkCmd*
commands can be used to record to the command buffer. - Executable
-
vkEndCommandBuffer ends the recording of a command buffer, and moves it from the recording state to the executable state. Executable command buffers can be submitted, reset, or recorded to another command buffer.
- Pending
-
Queue submission of a command buffer changes the state of a command buffer from the executable state to the pending state. Whilst in the pending state, applications must not attempt to modify the command buffer in any way - as the device may be processing the commands recorded to it. Once execution of a command buffer completes, the command buffer either reverts back to the executable state, or if it was recorded with
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
, it moves to the invalid state. A synchronization command should be used to detect when this occurs. - Invalid
-
Some operations, such as modifying or deleting a resource that was used in a command recorded to a command buffer, will transition the state of that command buffer into the invalid state. Command buffers in the invalid state can only be reset or freed.
Any given command that operates on a command buffer has its own requirements on what state a command buffer must be in, which are detailed in the valid usage constraints for that command.
Resetting a command buffer is an operation that discards any previously recorded commands and puts a command buffer in the initial state. Resetting occurs as a result of vkResetCommandBuffer or vkResetCommandPool, or as part of vkBeginCommandBuffer (which additionally puts the command buffer in the recording state).
Secondary command buffers can be recorded to a primary command buffer via vkCmdExecuteCommands. This partially ties the lifecycle of the two command buffers together - if the primary is submitted to a queue, both the primary and any secondaries recorded to it move to the pending state. Once execution of the primary completes, so it does for any secondary recorded within it. After all executions of each command buffer complete, they each move to their appropriate completion state (either to the executable state or the invalid state, as specified above).
If a secondary moves to the invalid state or the initial state, then all primary buffers it is recorded in move to the invalid state. A primary moving to any other state does not affect the state of a secondary recorded in it.
Note
Resetting or freeing a primary command buffer removes the lifecycle linkage to all secondary command buffers that were recorded into it. |
6.2. Command Pools
Command pools are opaque objects that command buffer memory is allocated from, and which allow the implementation to amortize the cost of resource creation across multiple command buffers. Command pools are externally synchronized, meaning that a command pool must not be used concurrently in multiple threads. That includes use via recording commands on any command buffers allocated from the pool, as well as operations that allocate, free, and reset command buffers or the pool itself.
Command pools are represented by VkCommandPool
handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCommandPool)
To create a command pool, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateCommandPool(
VkDevice device,
const VkCommandPoolCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkCommandPool* pCommandPool);
-
device
is the logical device that creates the command pool. -
pCreateInfo
is a pointer to a VkCommandPoolCreateInfo structure specifying the state of the command pool object. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pCommandPool
is a pointer to a VkCommandPool handle in which the created pool is returned.
The VkCommandPoolCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkCommandPoolCreateInfo {
VkStructureType sType;
const void* pNext;
VkCommandPoolCreateFlags flags;
uint32_t queueFamilyIndex;
} VkCommandPoolCreateInfo;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkCommandPoolCreateFlagBits indicating usage behavior for the pool and command buffers allocated from it. -
queueFamilyIndex
designates a queue family as described in section Queue Family Properties. All command buffers allocated from this command pool must be submitted on queues from the same queue family.
Bits which can be set in VkCommandPoolCreateInfo::flags
,
specifying usage behavior for a command pool, are:
// Provided by VK_VERSION_1_0
typedef enum VkCommandPoolCreateFlagBits {
VK_COMMAND_POOL_CREATE_TRANSIENT_BIT = 0x00000001,
VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT = 0x00000002,
// Provided by VK_VERSION_1_1
VK_COMMAND_POOL_CREATE_PROTECTED_BIT = 0x00000004,
} VkCommandPoolCreateFlagBits;
-
VK_COMMAND_POOL_CREATE_TRANSIENT_BIT
specifies that command buffers allocated from the pool will be short-lived, meaning that they will be reset or freed in a relatively short timeframe. This flag may be used by the implementation to control memory allocation behavior within the pool. -
VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT
allows any command buffer allocated from a pool to be individually reset to the initial state; either by calling vkResetCommandBuffer, or via the implicit reset when calling vkBeginCommandBuffer. If this flag is not set on a pool, thenvkResetCommandBuffer
must not be called for any command buffer allocated from that pool. -
VK_COMMAND_POOL_CREATE_PROTECTED_BIT
specifies that command buffers allocated from the pool are protected command buffers.
// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandPoolCreateFlags;
VkCommandPoolCreateFlags
is a bitmask type for setting a mask of zero
or more VkCommandPoolCreateFlagBits.
To trim a command pool, call:
// Provided by VK_VERSION_1_1
void vkTrimCommandPool(
VkDevice device,
VkCommandPool commandPool,
VkCommandPoolTrimFlags flags);
or the equivalent command
// Provided by VK_KHR_maintenance1
void vkTrimCommandPoolKHR(
VkDevice device,
VkCommandPool commandPool,
VkCommandPoolTrimFlags flags);
-
device
is the logical device that owns the command pool. -
commandPool
is the command pool to trim. -
flags
is reserved for future use.
Trimming a command pool recycles unused memory from the command pool back to the system. Command buffers allocated from the pool are not affected by the command.
Note
This command provides applications with some control over the internal memory allocations used by command pools. Unused memory normally arises from command buffers that have been recorded and later reset, such that they are no longer using the memory. On reset, a command buffer can return memory to its command pool, but the only way to release memory from a command pool to the system requires calling vkResetCommandPool, which cannot be executed while any command buffers from that pool are still in use. Subsequent recording operations into command buffers will reuse this memory but since total memory requirements fluctuate over time, unused memory can accumulate. In this situation, trimming a command pool may be useful to return unused memory back to the system, returning the total outstanding memory allocated by the pool back to a more “average” value. Implementations utilize many internal allocation strategies that make it impossible to guarantee that all unused memory is released back to the system. For instance, an implementation of a command pool may involve allocating memory in bulk from the system and sub-allocating from that memory. In such an implementation any live command buffer that holds a reference to a bulk allocation would prevent that allocation from being freed, even if only a small proportion of the bulk allocation is in use. In most cases trimming will result in a reduction in allocated but unused memory, but it does not guarantee the “ideal” behavior. Trimming may be an expensive operation, and should not be called frequently. Trimming should be treated as a way to relieve memory pressure after application-known points when there exists enough unused memory that the cost of trimming is “worth” it. |
// Provided by VK_VERSION_1_1
typedef VkFlags VkCommandPoolTrimFlags;
or the equivalent
// Provided by VK_KHR_maintenance1
typedef VkCommandPoolTrimFlags VkCommandPoolTrimFlagsKHR;
VkCommandPoolTrimFlags
is a bitmask type for setting a mask, but is
currently reserved for future use.
To reset a command pool, call:
// Provided by VK_VERSION_1_0
VkResult vkResetCommandPool(
VkDevice device,
VkCommandPool commandPool,
VkCommandPoolResetFlags flags);
-
device
is the logical device that owns the command pool. -
commandPool
is the command pool to reset. -
flags
is a bitmask of VkCommandPoolResetFlagBits controlling the reset operation.
Resetting a command pool recycles all of the resources from all of the command buffers allocated from the command pool back to the command pool. All command buffers that have been allocated from the command pool are put in the initial state.
Any primary command buffer allocated from another VkCommandPool that
is in the recording or executable state and
has a secondary command buffer allocated from commandPool
recorded
into it, becomes invalid.
Bits which can be set in vkResetCommandPool::flags
, controlling
the reset operation, are:
// Provided by VK_VERSION_1_0
typedef enum VkCommandPoolResetFlagBits {
VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT = 0x00000001,
} VkCommandPoolResetFlagBits;
-
VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT
specifies that resetting a command pool recycles all of the resources from the command pool back to the system.
// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandPoolResetFlags;
VkCommandPoolResetFlags
is a bitmask type for setting a mask of zero
or more VkCommandPoolResetFlagBits.
To destroy a command pool, call:
// Provided by VK_VERSION_1_0
void vkDestroyCommandPool(
VkDevice device,
VkCommandPool commandPool,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the command pool. -
commandPool
is the handle of the command pool to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
When a pool is destroyed, all command buffers allocated from the pool are freed.
Any primary command buffer allocated from another VkCommandPool that
is in the recording or executable state and
has a secondary command buffer allocated from commandPool
recorded
into it, becomes invalid.
6.3. Command Buffer Allocation and Management
To allocate command buffers, call:
// Provided by VK_VERSION_1_0
VkResult vkAllocateCommandBuffers(
VkDevice device,
const VkCommandBufferAllocateInfo* pAllocateInfo,
VkCommandBuffer* pCommandBuffers);
-
device
is the logical device that owns the command pool. -
pAllocateInfo
is a pointer to a VkCommandBufferAllocateInfo structure describing parameters of the allocation. -
pCommandBuffers
is a pointer to an array of VkCommandBuffer handles in which the resulting command buffer objects are returned. The array must be at least the length specified by thecommandBufferCount
member ofpAllocateInfo
. Each allocated command buffer begins in the initial state.
vkAllocateCommandBuffers
can be used to allocate multiple command
buffers.
If the allocation of any of those command buffers fails, the implementation
must free all successfully allocated command buffer objects from this
command, set all entries of the pCommandBuffers
array to NULL
and
return the error.
Note
Filling |
When command buffers are first allocated, they are in the initial state.
The VkCommandBufferAllocateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferAllocateInfo {
VkStructureType sType;
const void* pNext;
VkCommandPool commandPool;
VkCommandBufferLevel level;
uint32_t commandBufferCount;
} VkCommandBufferAllocateInfo;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
commandPool
is the command pool from which the command buffers are allocated. -
level
is a VkCommandBufferLevel value specifying the command buffer level. -
commandBufferCount
is the number of command buffers to allocate from the pool.
Possible values of VkCommandBufferAllocateInfo::level
,
specifying the command buffer level, are:
// Provided by VK_VERSION_1_0
typedef enum VkCommandBufferLevel {
VK_COMMAND_BUFFER_LEVEL_PRIMARY = 0,
VK_COMMAND_BUFFER_LEVEL_SECONDARY = 1,
} VkCommandBufferLevel;
-
VK_COMMAND_BUFFER_LEVEL_PRIMARY
specifies a primary command buffer. -
VK_COMMAND_BUFFER_LEVEL_SECONDARY
specifies a secondary command buffer.
To reset a command buffer, call:
// Provided by VK_VERSION_1_0
VkResult vkResetCommandBuffer(
VkCommandBuffer commandBuffer,
VkCommandBufferResetFlags flags);
-
commandBuffer
is the command buffer to reset. The command buffer can be in any state other than pending, and is moved into the initial state. -
flags
is a bitmask of VkCommandBufferResetFlagBits controlling the reset operation.
Any primary command buffer that is in the recording or executable state and has commandBuffer
recorded into
it, becomes invalid.
Bits which can be set in vkResetCommandBuffer::flags
,
controlling the reset operation, are:
// Provided by VK_VERSION_1_0
typedef enum VkCommandBufferResetFlagBits {
VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT = 0x00000001,
} VkCommandBufferResetFlagBits;
-
VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT
specifies that most or all memory resources currently owned by the command buffer should be returned to the parent command pool. If this flag is not set, then the command buffer may hold onto memory resources and reuse them when recording commands.commandBuffer
is moved to the initial state.
// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandBufferResetFlags;
VkCommandBufferResetFlags
is a bitmask type for setting a mask of zero
or more VkCommandBufferResetFlagBits.
To free command buffers, call:
// Provided by VK_VERSION_1_0
void vkFreeCommandBuffers(
VkDevice device,
VkCommandPool commandPool,
uint32_t commandBufferCount,
const VkCommandBuffer* pCommandBuffers);
-
device
is the logical device that owns the command pool. -
commandPool
is the command pool from which the command buffers were allocated. -
commandBufferCount
is the length of thepCommandBuffers
array. -
pCommandBuffers
is a pointer to an array of handles of command buffers to free.
Any primary command buffer that is in the recording or executable state and has any element of pCommandBuffers
recorded into it, becomes invalid.
6.4. Command Buffer Recording
To begin recording a command buffer, call:
// Provided by VK_VERSION_1_0
VkResult vkBeginCommandBuffer(
VkCommandBuffer commandBuffer,
const VkCommandBufferBeginInfo* pBeginInfo);
-
commandBuffer
is the handle of the command buffer which is to be put in the recording state. -
pBeginInfo
is a pointer to a VkCommandBufferBeginInfo structure defining additional information about how the command buffer begins recording.
The VkCommandBufferBeginInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferBeginInfo {
VkStructureType sType;
const void* pNext;
VkCommandBufferUsageFlags flags;
const VkCommandBufferInheritanceInfo* pInheritanceInfo;
} VkCommandBufferBeginInfo;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkCommandBufferUsageFlagBits specifying usage behavior for the command buffer. -
pInheritanceInfo
is a pointer to aVkCommandBufferInheritanceInfo
structure, used ifcommandBuffer
is a secondary command buffer. If this is a primary command buffer, then this value is ignored.
Bits which can be set in VkCommandBufferBeginInfo::flags
,
specifying usage behavior for a command buffer, are:
// Provided by VK_VERSION_1_0
typedef enum VkCommandBufferUsageFlagBits {
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT = 0x00000001,
VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT = 0x00000002,
VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT = 0x00000004,
} VkCommandBufferUsageFlagBits;
-
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
specifies that each recording of the command buffer will only be submitted once, and the command buffer will be reset and recorded again between each submission. -
VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
specifies that a secondary command buffer is considered to be entirely inside a render pass. If this is a primary command buffer, then this bit is ignored. -
VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
specifies that a command buffer can be resubmitted to a queue while it is in the pending state, and recorded into multiple primary command buffers.
// Provided by VK_VERSION_1_0
typedef VkFlags VkCommandBufferUsageFlags;
VkCommandBufferUsageFlags
is a bitmask type for setting a mask of zero
or more VkCommandBufferUsageFlagBits.
If the command buffer is a secondary command buffer, then the
VkCommandBufferInheritanceInfo
structure defines any state that will
be inherited from the primary command buffer:
// Provided by VK_VERSION_1_0
typedef struct VkCommandBufferInheritanceInfo {
VkStructureType sType;
const void* pNext;
VkRenderPass renderPass;
uint32_t subpass;
VkFramebuffer framebuffer;
VkBool32 occlusionQueryEnable;
VkQueryControlFlags queryFlags;
VkQueryPipelineStatisticFlags pipelineStatistics;
} VkCommandBufferInheritanceInfo;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
renderPass
is a VkRenderPass object defining which render passes theVkCommandBuffer
will be compatible with and can be executed within. -
subpass
is the index of the subpass within the render pass instance that theVkCommandBuffer
will be executed within. -
framebuffer
can refer to the VkFramebuffer object that theVkCommandBuffer
will be rendering to if it is executed within a render pass instance. It can be VK_NULL_HANDLE if the framebuffer is not known.NoteSpecifying the exact framebuffer that the secondary command buffer will be executed with may result in better performance at command buffer execution time.
-
occlusionQueryEnable
specifies whether the command buffer can be executed while an occlusion query is active in the primary command buffer. If this isVK_TRUE
, then this command buffer can be executed whether the primary command buffer has an occlusion query active or not. If this isVK_FALSE
, then the primary command buffer must not have an occlusion query active. -
queryFlags
specifies the query flags that can be used by an active occlusion query in the primary command buffer when this secondary command buffer is executed. If this value includes theVK_QUERY_CONTROL_PRECISE_BIT
bit, then the active query can return boolean results or actual sample counts. If this bit is not set, then the active query must not use theVK_QUERY_CONTROL_PRECISE_BIT
bit. -
pipelineStatistics
is a bitmask of VkQueryPipelineStatisticFlagBits specifying the set of pipeline statistics that can be counted by an active query in the primary command buffer when this secondary command buffer is executed. If this value includes a given bit, then this command buffer can be executed whether the primary command buffer has a pipeline statistics query active that includes this bit or not. If this value excludes a given bit, then the active pipeline statistics query must not be from a query pool that counts that statistic.
If the VkCommandBuffer will not be executed within a render pass
instance,
or if the render pass instance was begun with vkCmdBeginRendering,
renderPass
, subpass
, and framebuffer
are ignored.
Note
On some implementations, not using the
|
If a command buffer is in the invalid, or
executable state, and the command buffer was allocated from a command pool
with the VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT
flag set,
then vkBeginCommandBuffer
implicitly resets the command buffer,
behaving as if vkResetCommandBuffer
had been called with
VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT
not set.
After the implicit reset, commandBuffer
is moved to the
recording state.
If the pNext
chain of VkCommandBufferInheritanceInfo includes a
VkCommandBufferInheritanceConditionalRenderingInfoEXT
structure, then
that structure controls whether a command buffer can be executed while
conditional rendering is active in the
primary command buffer.
The VkCommandBufferInheritanceConditionalRenderingInfoEXT
structure is
defined as:
// Provided by VK_EXT_conditional_rendering
typedef struct VkCommandBufferInheritanceConditionalRenderingInfoEXT {
VkStructureType sType;
const void* pNext;
VkBool32 conditionalRenderingEnable;
} VkCommandBufferInheritanceConditionalRenderingInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
conditionalRenderingEnable
specifies whether the command buffer can be executed while conditional rendering is active in the primary command buffer. If this isVK_TRUE
, then this command buffer can be executed whether the primary command buffer has active conditional rendering or not. If this isVK_FALSE
, then the primary command buffer must not have conditional rendering active.
If this structure is not present, the behavior is as if
conditionalRenderingEnable
is VK_FALSE
.
To begin recording a secondary command buffer compatible with execution
inside a render pass using render
pass transform, add the
VkCommandBufferInheritanceRenderPassTransformInfoQCOM to the
pNext
chain of VkCommandBufferInheritanceInfo structure passed
to the vkBeginCommandBuffer command specifying the parameters for
transformed rasterization.
The VkCommandBufferInheritanceRenderPassTransformInfoQCOM
structure is
defined as:
// Provided by VK_QCOM_render_pass_transform
typedef struct VkCommandBufferInheritanceRenderPassTransformInfoQCOM {
VkStructureType sType;
void* pNext;
VkSurfaceTransformFlagBitsKHR transform;
VkRect2D renderArea;
} VkCommandBufferInheritanceRenderPassTransformInfoQCOM;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
transform
is a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to the render pass. -
renderArea
is the render area that is affected by the command buffer.
When the secondary is recorded to execute within a render pass instance
using vkCmdExecuteCommands, the render pass transform parameters of
the secondary command buffer must be consistent with the render pass
transform parameters specified for the render pass instance.
In particular, the transform
and renderArea
for command buffer
must be identical to the transform
and renderArea
of the render
pass instance.
The VkCommandBufferInheritanceViewportScissorInfoNV
structure is
defined as:
// Provided by VK_NV_inherited_viewport_scissor
typedef struct VkCommandBufferInheritanceViewportScissorInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 viewportScissor2D;
uint32_t viewportDepthCount;
const VkViewport* pViewportDepths;
} VkCommandBufferInheritanceViewportScissorInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
viewportScissor2D
specifies whether the listed dynamic state is inherited. -
viewportDepthCount
specifies the maximum number of viewports to inherit. WhenviewportScissor2D
isVK_FALSE
, the behavior is as if this value is zero. -
pViewportDepths
is a pointer to a VkViewport structure specifying the expected depth range for each inherited viewport.
If the pNext
chain of VkCommandBufferInheritanceInfo includes a
VkCommandBufferInheritanceViewportScissorInfoNV
structure, then that
structure controls whether a command buffer can inherit the following state
from other command buffers:
-
VK_DYNAMIC_STATE_SCISSOR
-
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT
-
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT
-
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT
-
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT
as well as the following state, with restrictions on inherited depth values and viewport count:
-
VK_DYNAMIC_STATE_VIEWPORT
-
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT
If viewportScissor2D
is VK_FALSE
, then the command buffer does
not inherit the listed dynamic state, and should set this state itself.
If this structure is not present, the behavior is as if
viewportScissor2D
is VK_FALSE
.
If viewportScissor2D
is VK_TRUE
, then the listed dynamic state
is inherited, and the command buffer must not set this
state, except that the viewport and scissor count may be set by binding a
graphics pipeline that does not specify this state as dynamic.
Note
Due to this restriction, applications should ensure either all or none of the graphics pipelines bound in this secondary command buffer use dynamic viewport/scissor counts. |
When the command buffer is executed as part of a the execution of a vkCmdExecuteCommands command, the inherited state (if enabled) is determined by the following procedure, performed separately for each dynamic state, and separately for each value for dynamic state that consists of multiple values (e.g. multiple viewports).
-
With i being the index of the executed command buffer in the
pCommandBuffers
array of vkCmdExecuteCommands, if i > 0 and any secondary command buffer from index 0 to i-1 modifies the state, the inherited state is provisionally set to the final value set by the last such secondary command buffer. Binding a graphics pipeline defining the state statically is equivalent to setting the state to an undefined value. -
Otherwise, the tentatative inherited state is that of the primary command buffer at the point the vkCmdExecuteCommands command was recorded; if the state is undefined, then so is the provisional inherited state.
-
If the provisional inherited state is an undefined value, then the state is not inherited.
-
If the provisional inherited state is a viewport, with n being its viewport index, then if n ≥
viewportDepthCount
, or if either VkViewport::minDepth
or VkViewport::maxDepth
are not equal to the respective values of the nth element ofpViewportDepths
, then the state is not inherited. -
If the provisional inherited state passes both checks, then it becomes the actual inherited state.
Note
There is no support for inheriting dynamic state from a secondary command
buffer executed as part of a different |
The VkCommandBufferInheritanceRenderingInfo
structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCommandBufferInheritanceRenderingInfo {
VkStructureType sType;
const void* pNext;
VkRenderingFlags flags;
uint32_t viewMask;
uint32_t colorAttachmentCount;
const VkFormat* pColorAttachmentFormats;
VkFormat depthAttachmentFormat;
VkFormat stencilAttachmentFormat;
VkSampleCountFlagBits rasterizationSamples;
} VkCommandBufferInheritanceRenderingInfo;
or the equivalent
// Provided by VK_KHR_dynamic_rendering
typedef VkCommandBufferInheritanceRenderingInfo VkCommandBufferInheritanceRenderingInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure -
flags
is a bitmask of VkRenderingFlagBits used by the render pass instance. -
viewMask
is the view mask used for rendering. -
colorAttachmentCount
is the number of color attachments specified in the render pass instance. -
pColorAttachmentFormats
is a pointer to an array of VkFormat values defining the format of color attachments. -
depthAttachmentFormat
is a VkFormat value defining the format of the depth attachment. -
stencilAttachmentFormat
is a VkFormat value defining the format of the stencil attachment. -
rasterizationSamples
is a VkSampleCountFlagBits specifying the number of samples used in rasterization.
If the pNext
chain of VkCommandBufferInheritanceInfo includes a
VkCommandBufferInheritanceRenderingInfo
structure, then that structure
controls parameters of dynamic render pass instances that the
VkCommandBuffer can be executed within.
If VkCommandBufferInheritanceInfo::renderPass
is not
VK_NULL_HANDLE, or
VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
is not specified in
VkCommandBufferBeginInfo::flags
, parameters of this structure
are ignored.
If colorAttachmentCount
is 0
and the
variableMultisampleRate
feature
is enabled, rasterizationSamples
is ignored.
If depthAttachmentFormat
, stencilAttachmentFormat
, or any
element of pColorAttachmentFormats
is VK_FORMAT_UNDEFINED
, it
indicates that the corresponding attachment is unused within the render pass
and writes to those attachments are discarded.
The
VkAttachmentSampleCountInfoAMD
or
VkAttachmentSampleCountInfoNV
structure is defined as:
// Provided by VK_KHR_dynamic_rendering with VK_AMD_mixed_attachment_samples
typedef struct VkAttachmentSampleCountInfoAMD {
VkStructureType sType;
const void* pNext;
uint32_t colorAttachmentCount;
const VkSampleCountFlagBits* pColorAttachmentSamples;
VkSampleCountFlagBits depthStencilAttachmentSamples;
} VkAttachmentSampleCountInfoAMD;
or the equivalent
// Provided by VK_KHR_dynamic_rendering with VK_NV_framebuffer_mixed_samples
typedef VkAttachmentSampleCountInfoAMD VkAttachmentSampleCountInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure -
colorAttachmentCount
is the number of color attachments specified in a render pass instance. -
pColorAttachmentSamples
is a pointer to an array of VkSampleCountFlagBits values defining the sample count of color attachments. -
depthStencilAttachmentSamples
is a VkSampleCountFlagBits value defining the sample count of a depth/stencil attachment.
If VkCommandBufferInheritanceInfo::renderPass
is
VK_NULL_HANDLE, VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
is specified in VkCommandBufferBeginInfo::flags
, and the
pNext
chain of VkCommandBufferInheritanceInfo includes
VkAttachmentSampleCountInfoAMD
, then this structure defines the sample
counts of each attachment within the render pass instance.
If VkAttachmentSampleCountInfoAMD
is not included, the value of
VkCommandBufferInheritanceRenderingInfo::rasterizationSamples
is
used as the sample count for each attachment.
If VkCommandBufferInheritanceInfo::renderPass
is not
VK_NULL_HANDLE, or
VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
is not specified in
VkCommandBufferBeginInfo::flags
, parameters of this structure
are ignored.
VkAttachmentSampleCountInfoAMD
can also be included in the
pNext
chain of VkGraphicsPipelineCreateInfo.
When a graphics pipeline is created without a VkRenderPass, if this
structure is included in the pNext
chain of
VkGraphicsPipelineCreateInfo, it specifies the sample count of
attachments used for rendering.
If this structure is not specified, and the pipeline does not include a
VkRenderPass, the value of
VkPipelineMultisampleStateCreateInfo::rasterizationSamples
is
used as the sample count for each attachment.
If a graphics pipeline is created with a valid VkRenderPass,
parameters of this structure are ignored.
Once recording starts, an application records a sequence of commands
(vkCmd*
) to set state in the command buffer, draw, dispatch, and other
commands.
Several commands can also be recorded indirectly from VkBuffer
content, see Device-Generated Commands.
To complete recording of a command buffer, call:
// Provided by VK_VERSION_1_0
VkResult vkEndCommandBuffer(
VkCommandBuffer commandBuffer);
-
commandBuffer
is the command buffer to complete recording.
The command buffer must have been in the recording state, and, if successful, is moved to the executable state.
If there was an error during recording, the application will be notified by
an unsuccessful return code returned by vkEndCommandBuffer
, and the
command buffer will be moved to the invalid
state.
In case the application recorded one or more video
encode operations into the command buffer, implementations may return the
VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR
error if any of the
specified Video Std parameters do not adhere to the syntactic or semantic
requirements of the used video compression standard, or if values derived
from parameters according to the rules defined by the used video compression
standard do not adhere to the capabilities of the video compression standard
or the implementation.
Note
Applications should not rely on the
|
When a command buffer is in the executable state, it can be submitted to a queue for execution.
6.5. Command Buffer Submission
Note
Submission can be a high overhead operation, and applications should
attempt to batch work together into as few calls to |
To submit command buffers to a queue, call:
// Provided by VK_VERSION_1_3
VkResult vkQueueSubmit2(
VkQueue queue,
uint32_t submitCount,
const VkSubmitInfo2* pSubmits,
VkFence fence);
or the equivalent command
// Provided by VK_KHR_synchronization2
VkResult vkQueueSubmit2KHR(
VkQueue queue,
uint32_t submitCount,
const VkSubmitInfo2* pSubmits,
VkFence fence);
-
queue
is the queue that the command buffers will be submitted to. -
submitCount
is the number of elements in thepSubmits
array. -
pSubmits
is a pointer to an array of VkSubmitInfo2 structures, each specifying a command buffer submission batch. -
fence
is an optional handle to a fence to be signaled once all submitted command buffers have completed execution. Iffence
is not VK_NULL_HANDLE, it defines a fence signal operation.
vkQueueSubmit2
is a queue submission
command, with each batch defined by an element of pSubmits
.
Semaphore operations submitted with vkQueueSubmit2 have additional ordering constraints compared to other submission commands, with dependencies involving previous and subsequent queue operations. Information about these additional constraints can be found in the semaphore section of the synchronization chapter.
If any command buffer submitted to this queue is in the
executable state, it is moved to the
pending state.
Once execution of all submissions of a command buffer complete, it moves
from the pending state, back to the
executable state.
If a command buffer was recorded with the
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
flag, it instead moves
back to the invalid state.
If vkQueueSubmit2
fails, it may return
VK_ERROR_OUT_OF_HOST_MEMORY
or VK_ERROR_OUT_OF_DEVICE_MEMORY
.
If it does, the implementation must ensure that the state and contents of
any resources or synchronization primitives referenced by the submitted
command buffers and any semaphores referenced by pSubmits
is
unaffected by the call or its failure.
If vkQueueSubmit2
fails in such a way that the implementation is
unable to make that guarantee, the implementation must return
VK_ERROR_DEVICE_LOST
.
See Lost Device.
The VkSubmitInfo2
structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkSubmitInfo2 {
VkStructureType sType;
const void* pNext;
VkSubmitFlags flags;
uint32_t waitSemaphoreInfoCount;
const VkSemaphoreSubmitInfo* pWaitSemaphoreInfos;
uint32_t commandBufferInfoCount;
const VkCommandBufferSubmitInfo* pCommandBufferInfos;
uint32_t signalSemaphoreInfoCount;
const VkSemaphoreSubmitInfo* pSignalSemaphoreInfos;
} VkSubmitInfo2;
or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkSubmitInfo2 VkSubmitInfo2KHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkSubmitFlagBits. -
waitSemaphoreInfoCount
is the number of elements inpWaitSemaphoreInfos
. -
pWaitSemaphoreInfos
is a pointer to an array of VkSemaphoreSubmitInfo structures defining semaphore wait operations. -
commandBufferInfoCount
is the number of elements inpCommandBufferInfos
and the number of command buffers to execute in the batch. -
pCommandBufferInfos
is a pointer to an array of VkCommandBufferSubmitInfo structures describing command buffers to execute in the batch. -
signalSemaphoreInfoCount
is the number of elements inpSignalSemaphoreInfos
. -
pSignalSemaphoreInfos
is a pointer to an array of VkSemaphoreSubmitInfo describing semaphore signal operations.
Bits which can be set in VkSubmitInfo2::flags
, specifying
submission behavior, are:
// Provided by VK_VERSION_1_3
typedef enum VkSubmitFlagBits {
VK_SUBMIT_PROTECTED_BIT = 0x00000001,
VK_SUBMIT_PROTECTED_BIT_KHR = VK_SUBMIT_PROTECTED_BIT,
} VkSubmitFlagBits;
or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkSubmitFlagBits VkSubmitFlagBitsKHR;
-
VK_SUBMIT_PROTECTED_BIT
specifies that this batch is a protected submission.
// Provided by VK_VERSION_1_3
typedef VkFlags VkSubmitFlags;
or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkSubmitFlags VkSubmitFlagsKHR;
VkSubmitFlags
is a bitmask type for setting a mask of zero or more
VkSubmitFlagBits.
The VkSemaphoreSubmitInfo
structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkSemaphoreSubmitInfo {
VkStructureType sType;
const void* pNext;
VkSemaphore semaphore;
uint64_t value;
VkPipelineStageFlags2 stageMask;
uint32_t deviceIndex;
} VkSemaphoreSubmitInfo;
or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkSemaphoreSubmitInfo VkSemaphoreSubmitInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
semaphore
is a VkSemaphore affected by this operation. -
value
is either the value used to signalsemaphore
or the value waited on bysemaphore
, ifsemaphore
is a timeline semaphore. Otherwise it is ignored. -
stageMask
is a VkPipelineStageFlags2 mask of pipeline stages which limit the first synchronization scope of a semaphore signal operation, or second synchronization scope of a semaphore wait operation as described in the semaphore wait operation and semaphore signal operation sections of the synchronization chapter. -
deviceIndex
is the index of the device within a device group that executes the semaphore wait or signal operation.
Whether this structure defines a semaphore wait or signal operation is defined by how it is used.
The VkCommandBufferSubmitInfo
structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkCommandBufferSubmitInfo {
VkStructureType sType;
const void* pNext;
VkCommandBuffer commandBuffer;
uint32_t deviceMask;
} VkCommandBufferSubmitInfo;
or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkCommandBufferSubmitInfo VkCommandBufferSubmitInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
commandBuffer
is a VkCommandBuffer to be submitted for execution. -
deviceMask
is a bitmask indicating which devices in a device group execute the command buffer. AdeviceMask
of0
is equivalent to setting all bits corresponding to valid devices in the group to1
.
To submit command buffers to a queue, call:
// Provided by VK_VERSION_1_0
VkResult vkQueueSubmit(
VkQueue queue,
uint32_t submitCount,
const VkSubmitInfo* pSubmits,
VkFence fence);
-
queue
is the queue that the command buffers will be submitted to. -
submitCount
is the number of elements in thepSubmits
array. -
pSubmits
is a pointer to an array of VkSubmitInfo structures, each specifying a command buffer submission batch. -
fence
is an optional handle to a fence to be signaled once all submitted command buffers have completed execution. Iffence
is not VK_NULL_HANDLE, it defines a fence signal operation.
vkQueueSubmit
is a queue submission
command, with each batch defined by an element of pSubmits
.
Batches begin execution in the order they appear in pSubmits
, but may
complete out of order.
Fence and semaphore operations submitted with vkQueueSubmit have additional ordering constraints compared to other submission commands, with dependencies involving previous and subsequent queue operations. Information about these additional constraints can be found in the semaphore and fence sections of the synchronization chapter.
Details on the interaction of pWaitDstStageMask
with synchronization
are described in the semaphore wait
operation section of the synchronization chapter.
The order that batches appear in pSubmits
is used to determine
submission order, and thus all the
implicit ordering guarantees that respect it.
Other than these implicit ordering guarantees and any explicit synchronization primitives, these batches may overlap or
otherwise execute out of order.
If any command buffer submitted to this queue is in the
executable state, it is moved to the
pending state.
Once execution of all submissions of a command buffer complete, it moves
from the pending state, back to the
executable state.
If a command buffer was recorded with the
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
flag, it instead moves to
the invalid state.
If vkQueueSubmit
fails, it may return
VK_ERROR_OUT_OF_HOST_MEMORY
or VK_ERROR_OUT_OF_DEVICE_MEMORY
.
If it does, the implementation must ensure that the state and contents of
any resources or synchronization primitives referenced by the submitted
command buffers and any semaphores referenced by pSubmits
is
unaffected by the call or its failure.
If vkQueueSubmit
fails in such a way that the implementation is unable
to make that guarantee, the implementation must return
VK_ERROR_DEVICE_LOST
.
See Lost Device.
The VkSubmitInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSubmitInfo {
VkStructureType sType;
const void* pNext;
uint32_t waitSemaphoreCount;
const VkSemaphore* pWaitSemaphores;
const VkPipelineStageFlags* pWaitDstStageMask;
uint32_t commandBufferCount;
const VkCommandBuffer* pCommandBuffers;
uint32_t signalSemaphoreCount;
const VkSemaphore* pSignalSemaphores;
} VkSubmitInfo;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
waitSemaphoreCount
is the number of semaphores upon which to wait before executing the command buffers for the batch. -
pWaitSemaphores
is a pointer to an array of VkSemaphore handles upon which to wait before the command buffers for this batch begin execution. If semaphores to wait on are provided, they define a semaphore wait operation. -
pWaitDstStageMask
is a pointer to an array of pipeline stages at which each corresponding semaphore wait will occur. -
commandBufferCount
is the number of command buffers to execute in the batch. -
pCommandBuffers
is a pointer to an array of VkCommandBuffer handles to execute in the batch. -
signalSemaphoreCount
is the number of semaphores to be signaled once the commands specified inpCommandBuffers
have completed execution. -
pSignalSemaphores
is a pointer to an array of VkSemaphore handles which will be signaled when the command buffers for this batch have completed execution. If semaphores to be signaled are provided, they define a semaphore signal operation.
The order that command buffers appear in pCommandBuffers
is used to
determine submission order, and thus
all the implicit ordering guarantees that
respect it.
Other than these implicit ordering guarantees and any explicit synchronization primitives, these command buffers may overlap or
otherwise execute out of order.
To specify the values to use when waiting for and signaling semaphores
created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE
,
add a VkTimelineSemaphoreSubmitInfo structure to the pNext
chain
of the VkSubmitInfo structure when using vkQueueSubmit
or the VkBindSparseInfo structure when using vkQueueBindSparse
.
The VkTimelineSemaphoreSubmitInfo
structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkTimelineSemaphoreSubmitInfo {
VkStructureType sType;
const void* pNext;
uint32_t waitSemaphoreValueCount;
const uint64_t* pWaitSemaphoreValues;
uint32_t signalSemaphoreValueCount;
const uint64_t* pSignalSemaphoreValues;
} VkTimelineSemaphoreSubmitInfo;
or the equivalent
// Provided by VK_KHR_timeline_semaphore
typedef VkTimelineSemaphoreSubmitInfo VkTimelineSemaphoreSubmitInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
waitSemaphoreValueCount
is the number of semaphore wait values specified inpWaitSemaphoreValues
. -
pWaitSemaphoreValues
is a pointer to an array ofwaitSemaphoreValueCount
values for the corresponding semaphores in VkSubmitInfo::pWaitSemaphores
to wait for. -
signalSemaphoreValueCount
is the number of semaphore signal values specified inpSignalSemaphoreValues
. -
pSignalSemaphoreValues
is a pointer to an arraysignalSemaphoreValueCount
values for the corresponding semaphores in VkSubmitInfo::pSignalSemaphores
to set when signaled.
If the semaphore in VkSubmitInfo::pWaitSemaphores
or
VkSubmitInfo::pSignalSemaphores
corresponding to an entry in
pWaitSemaphoreValues
or pSignalSemaphoreValues
respectively was
not created with a VkSemaphoreType of
VK_SEMAPHORE_TYPE_TIMELINE
, the implementation must ignore the value
in the pWaitSemaphoreValues
or pSignalSemaphoreValues
entry.
To specify the values to use when waiting for and signaling semaphores whose
current payload refers to a
Direct3D 12 fence, add a VkD3D12FenceSubmitInfoKHR structure to the
pNext
chain of the VkSubmitInfo structure.
The VkD3D12FenceSubmitInfoKHR
structure is defined as:
// Provided by VK_KHR_external_semaphore_win32
typedef struct VkD3D12FenceSubmitInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t waitSemaphoreValuesCount;
const uint64_t* pWaitSemaphoreValues;
uint32_t signalSemaphoreValuesCount;
const uint64_t* pSignalSemaphoreValues;
} VkD3D12FenceSubmitInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
waitSemaphoreValuesCount
is the number of semaphore wait values specified inpWaitSemaphoreValues
. -
pWaitSemaphoreValues
is a pointer to an array ofwaitSemaphoreValuesCount
values for the corresponding semaphores in VkSubmitInfo::pWaitSemaphores
to wait for. -
signalSemaphoreValuesCount
is the number of semaphore signal values specified inpSignalSemaphoreValues
. -
pSignalSemaphoreValues
is a pointer to an array ofsignalSemaphoreValuesCount
values for the corresponding semaphores in VkSubmitInfo::pSignalSemaphores
to set when signaled.
If the semaphore in VkSubmitInfo::pWaitSemaphores
or
VkSubmitInfo::pSignalSemaphores
corresponding to an entry in
pWaitSemaphoreValues
or pSignalSemaphoreValues
respectively does
not currently have a payload
referring to a Direct3D 12 fence, the implementation must ignore the value
in the pWaitSemaphoreValues
or pSignalSemaphoreValues
entry.
Note
As the introduction of the external semaphore handle type
|
When submitting work that operates on memory imported from a Direct3D 11
resource to a queue, the keyed mutex mechanism may be used in addition to
Vulkan semaphores to synchronize the work.
Keyed mutexes are a property of a properly created shareable Direct3D 11
resource.
They can only be used if the imported resource was created with the
D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX
flag.
To acquire keyed mutexes before submitted work and/or release them after,
add a VkWin32KeyedMutexAcquireReleaseInfoKHR structure to the
pNext
chain of the VkSubmitInfo structure.
The VkWin32KeyedMutexAcquireReleaseInfoKHR
structure is defined as:
// Provided by VK_KHR_win32_keyed_mutex
typedef struct VkWin32KeyedMutexAcquireReleaseInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t acquireCount;
const VkDeviceMemory* pAcquireSyncs;
const uint64_t* pAcquireKeys;
const uint32_t* pAcquireTimeouts;
uint32_t releaseCount;
const VkDeviceMemory* pReleaseSyncs;
const uint64_t* pReleaseKeys;
} VkWin32KeyedMutexAcquireReleaseInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
acquireCount
is the number of entries in thepAcquireSyncs
,pAcquireKeys
, andpAcquireTimeouts
arrays. -
pAcquireSyncs
is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources. -
pAcquireKeys
is a pointer to an array of mutex key values to wait for prior to beginning the submitted work. Entries refer to the keyed mutex associated with the corresponding entries inpAcquireSyncs
. -
pAcquireTimeouts
is a pointer to an array of timeout values, in millisecond units, for each acquire specified inpAcquireKeys
. -
releaseCount
is the number of entries in thepReleaseSyncs
andpReleaseKeys
arrays. -
pReleaseSyncs
is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources. -
pReleaseKeys
is a pointer to an array of mutex key values to set when the submitted work has completed. Entries refer to the keyed mutex associated with the corresponding entries inpReleaseSyncs
.
When submitting work that operates on memory imported from a Direct3D 11
resource to a queue, the keyed mutex mechanism may be used in addition to
Vulkan semaphores to synchronize the work.
Keyed mutexes are a property of a properly created shareable Direct3D 11
resource.
They can only be used if the imported resource was created with the
D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX
flag.
To acquire keyed mutexes before submitted work and/or release them after,
add a VkWin32KeyedMutexAcquireReleaseInfoNV structure to the
pNext
chain of the VkSubmitInfo structure.
The VkWin32KeyedMutexAcquireReleaseInfoNV
structure is defined as:
// Provided by VK_NV_win32_keyed_mutex
typedef struct VkWin32KeyedMutexAcquireReleaseInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t acquireCount;
const VkDeviceMemory* pAcquireSyncs;
const uint64_t* pAcquireKeys;
const uint32_t* pAcquireTimeoutMilliseconds;
uint32_t releaseCount;
const VkDeviceMemory* pReleaseSyncs;
const uint64_t* pReleaseKeys;
} VkWin32KeyedMutexAcquireReleaseInfoNV;
-
acquireCount
is the number of entries in thepAcquireSyncs
,pAcquireKeys
, andpAcquireTimeoutMilliseconds
arrays. -
pAcquireSyncs
is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources. -
pAcquireKeys
is a pointer to an array of mutex key values to wait for prior to beginning the submitted work. Entries refer to the keyed mutex associated with the corresponding entries inpAcquireSyncs
. -
pAcquireTimeoutMilliseconds
is a pointer to an array of timeout values, in millisecond units, for each acquire specified inpAcquireKeys
. -
releaseCount
is the number of entries in thepReleaseSyncs
andpReleaseKeys
arrays. -
pReleaseSyncs
is a pointer to an array of VkDeviceMemory objects which were imported from Direct3D 11 resources. -
pReleaseKeys
is a pointer to an array of mutex key values to set when the submitted work has completed. Entries refer to the keyed mutex associated with the corresponding entries inpReleaseSyncs
.
If the pNext
chain of VkSubmitInfo includes a
VkProtectedSubmitInfo
structure, then the structure indicates whether
the batch is protected.
The VkProtectedSubmitInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkProtectedSubmitInfo {
VkStructureType sType;
const void* pNext;
VkBool32 protectedSubmit;
} VkProtectedSubmitInfo;
-
protectedSubmit
specifies whether the batch is protected. IfprotectedSubmit
isVK_TRUE
, the batch is protected. IfprotectedSubmit
isVK_FALSE
, the batch is unprotected. If theVkSubmitInfo
::pNext
chain does not include this structure, the batch is unprotected.
If the pNext
chain of VkSubmitInfo includes a
VkDeviceGroupSubmitInfo
structure, then that structure includes device
indices and masks specifying which physical devices execute semaphore
operations and command buffers.
The VkDeviceGroupSubmitInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupSubmitInfo {
VkStructureType sType;
const void* pNext;
uint32_t waitSemaphoreCount;
const uint32_t* pWaitSemaphoreDeviceIndices;
uint32_t commandBufferCount;
const uint32_t* pCommandBufferDeviceMasks;
uint32_t signalSemaphoreCount;
const uint32_t* pSignalSemaphoreDeviceIndices;
} VkDeviceGroupSubmitInfo;
or the equivalent
// Provided by VK_KHR_device_group
typedef VkDeviceGroupSubmitInfo VkDeviceGroupSubmitInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
waitSemaphoreCount
is the number of elements in thepWaitSemaphoreDeviceIndices
array. -
pWaitSemaphoreDeviceIndices
is a pointer to an array ofwaitSemaphoreCount
device indices indicating which physical device executes the semaphore wait operation in the corresponding element of VkSubmitInfo::pWaitSemaphores
. -
commandBufferCount
is the number of elements in thepCommandBufferDeviceMasks
array. -
pCommandBufferDeviceMasks
is a pointer to an array ofcommandBufferCount
device masks indicating which physical devices execute the command buffer in the corresponding element of VkSubmitInfo::pCommandBuffers
. A physical device executes the command buffer if the corresponding bit is set in the mask. -
signalSemaphoreCount
is the number of elements in thepSignalSemaphoreDeviceIndices
array. -
pSignalSemaphoreDeviceIndices
is a pointer to an array ofsignalSemaphoreCount
device indices indicating which physical device executes the semaphore signal operation in the corresponding element of VkSubmitInfo::pSignalSemaphores
.
If this structure is not present, semaphore operations and command buffers execute on device index zero.
If the pNext
chain of VkSubmitInfo includes a
VkPerformanceQuerySubmitInfoKHR structure, then the structure
indicates which counter pass is active for the batch in that submit.
The VkPerformanceQuerySubmitInfoKHR
structure is defined as:
// Provided by VK_KHR_performance_query
typedef struct VkPerformanceQuerySubmitInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t counterPassIndex;
} VkPerformanceQuerySubmitInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
counterPassIndex
specifies which counter pass index is active.
If the VkSubmitInfo
::pNext
chain does not include this
structure, the batch defaults to use counter pass index 0.
6.6. Queue Forward Progress
When using binary semaphores, the application must ensure that command
buffer submissions will be able to complete without any subsequent
operations by the application on any queue.
After any call to vkQueueSubmit
(or other queue operation), for every
queued wait on a semaphore
created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY
there must be a prior signal of that semaphore that will not be consumed by
a different wait on the semaphore.
When using timeline semaphores, wait-before-signal behavior is well-defined
and applications can submit work via vkQueueSubmit
defining a
timeline semaphore wait operation
before submitting a corresponding semaphore signal operation.
For each timeline semaphore wait
operation defined by a call to vkQueueSubmit
, the application must
ensure that a corresponding semaphore signal operation is executed before forward progress can be
made.
If a command buffer submission waits for any events to be signaled, the application must ensure that command buffer submissions will be able to complete without any subsequent operations by the application. Events signaled by the host must be signaled before the command buffer waits on those events.
Note
The ability for commands to wait on the host to set an events was originally added to allow low-latency updates to resources between host and device. However, to ensure quality of service, implementations would necessarily detect extended stalls in execution and timeout after a short period. As this period is not defined in the Vulkan specification, it is impossible to correctly validate any application with any wait period. Since the original users of this functionality were highly limited and platform-specific, this functionality is now considered defunct and should not be used. |
6.7. Secondary Command Buffer Execution
A secondary command buffer must not be directly submitted to a queue. Instead, secondary command buffers are recorded to execute as part of a primary command buffer with the command:
// Provided by VK_VERSION_1_0
void vkCmdExecuteCommands(
VkCommandBuffer commandBuffer,
uint32_t commandBufferCount,
const VkCommandBuffer* pCommandBuffers);
-
commandBuffer
is a handle to a primary command buffer that the secondary command buffers are executed in. -
commandBufferCount
is the length of thepCommandBuffers
array. -
pCommandBuffers
is a pointer to an array ofcommandBufferCount
secondary command buffer handles, which are recorded to execute in the primary command buffer in the order they are listed in the array.
If any element of pCommandBuffers
was not recorded with the
VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
flag, and it was recorded
into any other primary command buffer which is currently in the
executable or recording state, that primary
command buffer becomes invalid.
6.8. Command Buffer Device Mask
Each command buffer has a piece of state storing the current device mask of the command buffer. This mask controls which physical devices within the logical device all subsequent commands will execute on, including state-setting commands, action commands, and synchronization commands.
Scissor, exclusive scissor, and viewport state (excluding the count of each) can be set to different values on each physical device (only when set as dynamic state), and each physical device will render using its local copy of the state. Other state is shared between physical devices, such that all physical devices use the most recently set values for the state. However, when recording an action command that uses a piece of state, the most recent command that set that state must have included all physical devices that execute the action command in its current device mask.
The command buffer’s device mask is orthogonal to the
pCommandBufferDeviceMasks
member of VkDeviceGroupSubmitInfo.
Commands only execute on a physical device if the device index is set in
both device masks.
If the pNext
chain of VkCommandBufferBeginInfo includes a
VkDeviceGroupCommandBufferBeginInfo
structure, then that structure
includes an initial device mask for the command buffer.
The VkDeviceGroupCommandBufferBeginInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupCommandBufferBeginInfo {
VkStructureType sType;
const void* pNext;
uint32_t deviceMask;
} VkDeviceGroupCommandBufferBeginInfo;
or the equivalent
// Provided by VK_KHR_device_group
typedef VkDeviceGroupCommandBufferBeginInfo VkDeviceGroupCommandBufferBeginInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
deviceMask
is the initial value of the command buffer’s device mask.
The initial device mask also acts as an upper bound on the set of devices that can ever be in the device mask in the command buffer.
If this structure is not present, the initial value of a command buffer’s device mask is set to include all physical devices in the logical device when the command buffer begins recording.
To update the current device mask of a command buffer, call:
// Provided by VK_VERSION_1_1
void vkCmdSetDeviceMask(
VkCommandBuffer commandBuffer,
uint32_t deviceMask);
or the equivalent command
// Provided by VK_KHR_device_group
void vkCmdSetDeviceMaskKHR(
VkCommandBuffer commandBuffer,
uint32_t deviceMask);
-
commandBuffer
is command buffer whose current device mask is modified. -
deviceMask
is the new value of the current device mask.
deviceMask
is used to filter out subsequent commands from executing on
all physical devices whose bit indices are not set in the mask, except
commands beginning a render pass instance, commands transitioning to the
next subpass in the render pass instance, and commands ending a render pass
instance, which always execute on the set of physical devices whose bit
indices are included in the deviceMask
member of the
VkDeviceGroupRenderPassBeginInfo structure passed to the command
beginning the corresponding render pass instance.