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.
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.
|
Resetting or freeing a primary command buffer removes the lifecycle linkage to all secondary command buffers that were recorded into it. |
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.
|
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.
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. -
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.
|
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.
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.
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.Specifying 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.
|
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;
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.
|
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.
|
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.
|
Applications should not rely on the
|
When a command buffer is in the executable state, it can be submitted to a queue for execution.
Command Buffer Submission
|
Submission can be a high overhead operation, and applications should
attempt to batch work together into as few calls to |
To submit command buffers to a queue, call:
// Provided by VK_VERSION_1_3
VkResult vkQueueSubmit2(
VkQueue queue,
uint32_t submitCount,
const VkSubmitInfo2* pSubmits,
VkFence fence);or the equivalent command
// Provided by VK_KHR_synchronization2
VkResult vkQueueSubmit2KHR(
VkQueue queue,
uint32_t submitCount,
const VkSubmitInfo2* pSubmits,
VkFence fence);-
queueis the queue that the command buffers will be submitted to. -
submitCountis the number of elements in thepSubmitsarray. -
pSubmitsis a pointer to an array of VkSubmitInfo2 structures, each specifying a command buffer submission batch. -
fenceis an optional handle to a fence to be signaled once all submitted command buffers have completed execution. Iffenceis not VK_NULL_HANDLE, it defines a fence signal operation.
vkQueueSubmit2 is a queue submission command, with each batch defined by an element of pSubmits.
Semaphore operations submitted with vkQueueSubmit2 have additional ordering constraints compared to other submission commands, with dependencies involving previous and subsequent queue operations. Information about these additional constraints can be found in the semaphore section of the synchronization chapter.
If any command buffer submitted to this queue is in the
executable state, it is moved to the
pending state.
Once execution of all submissions of a command buffer complete, it moves
from the pending state, back to the
executable state.
If a command buffer was recorded with the
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves
back to the invalid state.
If vkQueueSubmit2 fails, it may return
VK_ERROR_OUT_OF_HOST_MEMORY or VK_ERROR_OUT_OF_DEVICE_MEMORY.
If it does, the implementation must ensure that the state and contents of
any resources or synchronization primitives referenced by the submitted
command buffers and any semaphores referenced by pSubmits is
unaffected by the call or its failure.
If vkQueueSubmit2 fails in such a way that the implementation is
unable to make that guarantee, the implementation must return
VK_ERROR_DEVICE_LOST.
See Lost Device.
The VkSubmitInfo2 structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkSubmitInfo2 {
VkStructureType sType;
const void* pNext;
VkSubmitFlags flags;
uint32_t waitSemaphoreInfoCount;
const VkSemaphoreSubmitInfo* pWaitSemaphoreInfos;
uint32_t commandBufferInfoCount;
const VkCommandBufferSubmitInfo* pCommandBufferInfos;
uint32_t signalSemaphoreInfoCount;
const VkSemaphoreSubmitInfo* pSignalSemaphoreInfos;
} VkSubmitInfo2;or the equivalent
// Provided by VK_KHR_synchronization2
typedef VkSubmitInfo2 VkSubmitInfo2KHR;-
sTypeis 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. -
fenceis an optional handle to a fence to be signaled once all submitted command buffers have completed execution. Iffenceis not VK_NULL_HANDLE, it defines a fence signal operation.
vkQueueSubmit is a queue submission command, with each batch defined by an element of pSubmits.
Batches begin execution in the order they appear in pSubmits, but may
complete out of order.
Fence and semaphore operations submitted with vkQueueSubmit have additional ordering constraints compared to other submission commands, with dependencies involving previous and subsequent queue operations. Information about these additional constraints can be found in the semaphore and fence sections of the synchronization chapter.
Details on the interaction of pWaitDstStageMask with synchronization
are described in the semaphore wait operation section of the synchronization chapter.
The order that batches appear in pSubmits is used to determine
submission order, and thus all the
implicit ordering guarantees that respect it.
Other than these implicit ordering guarantees and any explicit synchronization primitives, these batches may overlap or
otherwise execute out of order.
If any command buffer submitted to this queue is in the
executable state, it is moved to the
pending state.
Once execution of all submissions of a command buffer complete, it moves
from the pending state, back to the
executable state.
If a command buffer was recorded with the
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves to
the invalid state.
If vkQueueSubmit fails, it may return
VK_ERROR_OUT_OF_HOST_MEMORY or VK_ERROR_OUT_OF_DEVICE_MEMORY.
If it does, the implementation must ensure that the state and contents of
any resources or synchronization primitives referenced by the submitted
command buffers and any semaphores referenced by pSubmits is
unaffected by the call or its failure.
If vkQueueSubmit fails in such a way that the implementation is unable
to make that guarantee, the implementation must return
VK_ERROR_DEVICE_LOST.
See Lost Device.
The VkSubmitInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkSubmitInfo {
VkStructureType sType;
const void* pNext;
uint32_t waitSemaphoreCount;
const VkSemaphore* pWaitSemaphores;
const VkPipelineStageFlags* pWaitDstStageMask;
uint32_t commandBufferCount;
const VkCommandBuffer* pCommandBuffers;
uint32_t signalSemaphoreCount;
const VkSemaphore* pSignalSemaphores;
} VkSubmitInfo;-
sTypeis 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.
|
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;-
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.
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.
|
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. |
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.
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.
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.