VkPipelineStageFlagBits - Bitmask specifying pipeline stages

Description

• VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT specifies the stage of the pipeline where any commands are initially received by the queue.

• VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX specifies the stage of the pipeline where device-side generation of commands via vkCmdProcessCommandsNVX is handled.
• VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT specifies the stage of the pipeline where Draw/DispatchIndirect data structures are consumed. This stage also includes reading commands written by vkCmdProcessCommandsNVX.
• VK_PIPELINE_STAGE_VERTEX_INPUT_BIT specifies the stage of the pipeline where vertex and index buffers are consumed.
• VK_PIPELINE_STAGE_VERTEX_SHADER_BIT specifies the vertex shader stage.
• VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT specifies the tessellation control shader stage.
• VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT specifies the tessellation evaluation shader stage.
• VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT specifies the geometry shader stage.
• VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT specifies the fragment shader stage.
• VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT specifies the stage of the pipeline where early fragment tests (depth and stencil tests before fragment shading) are performed. This stage also includes subpass load operations for framebuffer attachments with a depth/stencil format.
• VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT specifies the stage of the pipeline where late fragment tests (depth and stencil tests after fragment shading) are performed. This stage also includes subpass store operations for framebuffer attachments with a depth/stencil format.
• VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT specifies the stage of the pipeline after blending where the final color values are output from the pipeline. This stage also includes subpass load and store operations and multisample resolve operations for framebuffer attachments with a color format.
• VK_PIPELINE_STAGE_TRANSFER_BIT specifies the execution of copy commands. This includes the operations resulting from all copy commands, clear commands (with the exception of vkCmdClearAttachments), and vkCmdCopyQueryPoolResults.
• VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT specifies the execution of a compute shader.
• VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT specifies the final stage in the pipeline where operations generated by all commands complete execution.
• VK_PIPELINE_STAGE_HOST_BIT specifies a pseudo-stage indicating execution on the host of reads/writes of device memory. This stage is not invoked by any commands recorded in a command buffer.

• VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT specifies the execution of all graphics pipeline stages, and is equivalent to the logical OR of:

  • VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT

  • VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT

  • VK_PIPELINE_STAGE_VERTEX_INPUT_BIT

  • VK_PIPELINE_STAGE_VERTEX_SHADER_BIT

  • VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT

  • VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT

  • VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT

  • VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT

  • VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT

  • VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT

• VK_PIPELINE_STAGE_ALL_COMMANDS_BIT is equivalent to the logical OR of every other pipeline stage flag that is supported on the queue it is used with.

Note

An execution dependency with only VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT in the destination stage mask will only prevent that stage from executing in subsequently submitted commands. As this stage does not perform any actual execution, this is not observable - in effect, it does not delay processing of subsequent commands. Similarly an execution dependency with only VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT in the source stage mask will effectively not wait for any prior commands to complete.

When defining a memory dependency, using only VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT or VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT would never make any accesses available and/or visible because these stages do not access memory.

VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT and VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT are useful for accomplishing layout transitions and queue ownership operations when the required execution dependency is satisfied by other means - for example, semaphore operations between queues.

See Also

VkPipelineStageFlags, vkCmdWriteBufferMarkerAMD, vkCmdWriteTimestamp

VkQueue - Opaque handle to a queue object

See Also

vkGetDeviceQueue, vkGetDeviceQueue2, vkQueueBeginDebugUtilsLabelEXT, vkQueueBindSparse, vkQueueEndDebugUtilsLabelEXT, vkQueueInsertDebugUtilsLabelEXT, vkQueuePresentKHR, vkQueueSubmit, vkQueueWaitIdle

VkCommandBuffer - Opaque handle to a command buffer object

See Also

VkCmdProcessCommandsInfoNVX, VkSubmitInfo, vkAllocateCommandBuffers, vkBeginCommandBuffer, vkCmdBeginDebugUtilsLabelEXT, vkCmdBeginQuery, vkCmdBeginRenderPass, vkCmdBindDescriptorSets, vkCmdBindIndexBuffer, vkCmdBindPipeline, vkCmdBindVertexBuffers, vkCmdBlitImage, vkCmdClearAttachments, vkCmdClearColorImage, vkCmdClearDepthStencilImage, vkCmdCopyBuffer, vkCmdCopyBufferToImage, vkCmdCopyImage, vkCmdCopyImageToBuffer, vkCmdCopyQueryPoolResults, vkCmdDebugMarkerBeginEXT, vkCmdDebugMarkerEndEXT, vkCmdDebugMarkerInsertEXT, vkCmdDispatch, vkCmdDispatchBase, vkCmdDispatchBaseKHR, vkCmdDispatchIndirect, vkCmdDraw, vkCmdDrawIndexed, vkCmdDrawIndexedIndirect, vkCmdDrawIndexedIndirectCountAMD, vkCmdDrawIndirect, vkCmdDrawIndirectCountAMD, vkCmdEndDebugUtilsLabelEXT, vkCmdEndQuery, vkCmdEndRenderPass, vkCmdExecuteCommands, vkCmdFillBuffer, vkCmdInsertDebugUtilsLabelEXT, vkCmdNextSubpass, vkCmdPipelineBarrier, vkCmdProcessCommandsNVX, vkCmdPushConstants, vkCmdPushDescriptorSetKHR, vkCmdPushDescriptorSetWithTemplateKHR, vkCmdReserveSpaceForCommandsNVX, vkCmdResetEvent, vkCmdResetQueryPool, vkCmdResolveImage, vkCmdSetBlendConstants, vkCmdSetDepthBias, vkCmdSetDepthBounds, vkCmdSetDeviceMask, vkCmdSetDeviceMaskKHR, vkCmdSetDiscardRectangleEXT, vkCmdSetEvent, vkCmdSetLineWidth, vkCmdSetSampleLocationsEXT, vkCmdSetScissor, vkCmdSetStencilCompareMask, vkCmdSetStencilReference, vkCmdSetStencilWriteMask, vkCmdSetViewport, vkCmdSetViewportWScalingNV, vkCmdUpdateBuffer, vkCmdWaitEvents, vkCmdWriteBufferMarkerAMD, vkCmdWriteTimestamp, vkEndCommandBuffer, vkFreeCommandBuffers, vkResetCommandBuffer

VkFence - Opaque handle to a fence object

See Also

VkAcquireNextImageInfoKHR, VkFenceGetFdInfoKHR, VkFenceGetWin32HandleInfoKHR, VkImportFenceFdInfoKHR, VkImportFenceWin32HandleInfoKHR, vkAcquireNextImageKHR, vkCreateFence, vkDestroyFence, vkGetFenceStatus, vkQueueBindSparse, vkQueueSubmit, vkRegisterDeviceEventEXT, vkRegisterDisplayEventEXT, vkResetFences, vkWaitForFences

VkSemaphore - Opaque handle to a semaphore object

See Also

VkAcquireNextImageInfoKHR, VkBindSparseInfo, VkImportSemaphoreFdInfoKHR, VkImportSemaphoreWin32HandleInfoKHR, VkPresentInfoKHR, VkSemaphoreGetFdInfoKHR, VkSemaphoreGetWin32HandleInfoKHR, VkSubmitInfo, vkAcquireNextImageKHR, vkCreateSemaphore, vkDestroySemaphore

vkGetDeviceQueue - Get a queue handle from a device

Parameters

• device is the logical device that owns the queue.

• queueFamilyIndex is the index of the queue family to which the queue belongs.
• queueIndex is the index within this queue family of the queue to retrieve.
• pQueue is a pointer to a VkQueue object that will be filled with the handle for the requested queue.

Valid Usage

• queueFamilyIndex must be one of the queue family indices specified when device was created, via the VkDeviceQueueCreateInfo structure

• queueIndex must be less than the number of queues created for the specified queue family index when device was created, via the queueCount member of the VkDeviceQueueCreateInfo structure
• VkDeviceQueueCreateInfo::flags must have been set to zero when device was created

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pQueue must be a valid pointer to a VkQueue handle

See Also

VkDevice, VkQueue

vkQueueSubmit - Submits a sequence of semaphores or command buffers to a queue

Parameters

• queue is the queue that the command buffers will be submitted to.

• submitCount is the number of elements in the pSubmits 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. If fence is not VK_NULL_HANDLE, it defines a fence signal operation.

Description

Note

Submission can be a high overhead operation, and applications should attempt to batch work together into as few calls to vkQueueSubmit as possible.

vkQueueSubmit is a queue submission command, with each batch defined by an element of pSubmits as an instance of the VkSubmitInfo structure. 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 back 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.

Valid Usage

• If fence is not VK_NULL_HANDLE, fence must be unsignaled

• If fence is not VK_NULL_HANDLE, fence must not be associated with any other queue command that has not yet completed execution on that queue
• Any calls to vkCmdSetEvent, vkCmdResetEvent or vkCmdWaitEvents that have been recorded into any of the command buffer elements of the pCommandBuffers member of any element of pSubmits, must not reference any VkEvent that is referenced by any of those commands in a command buffer that has been submitted to another queue and is still in the pending state.
• Any stage flag included in any element of the pWaitDstStageMask member of any element of pSubmits must be a pipeline stage supported by one of the capabilities of queue, as specified in the table of supported pipeline stages.
• Each element of the pSignalSemaphores member of any element of pSubmits must be unsignaled when the semaphore signal operation it defines is executed on the device
• When a semaphore unsignal operation defined by any element of the pWaitSemaphores member of any element of pSubmits executes on queue, no other queue must be waiting on the same semaphore.
• All elements of the pWaitSemaphores member of all elements of pSubmits must be semaphores that are signaled, or have semaphore signal operations previously submitted for execution.
• Each element of the pCommandBuffers member of each element of pSubmits must be in the pending or executable state.
• If any element of the pCommandBuffers member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state.
• Any secondary command buffers recorded into any element of the pCommandBuffers member of any element of pSubmits must be in the pending or executable state.
• If any secondary command buffers recorded into any element of the pCommandBuffers member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state.
• Each element of the pCommandBuffers member of each element of pSubmits must have been allocated from a VkCommandPool that was created for the same queue family queue belongs to.

Valid Usage (Implicit)

• queue must be a valid VkQueue handle

• If submitCount is not 0, pSubmits must be a valid pointer to an array of submitCount valid VkSubmitInfo structures
• If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle
• Both of fence, and queue that are valid handles must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

• Host access to queue must be externally synchronized

• Host access to pSubmits[].pWaitSemaphores[] must be externally synchronized
• Host access to pSubmits[].pSignalSemaphores[] must be externally synchronized
• Host access to fence must be externally synchronized

Command Properties

'

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

See Also

VkFence, VkQueue, VkSubmitInfo

vkQueueWaitIdle - Wait for a queue to become idle

Parameters

• queue is the queue on which to wait.

Description

vkQueueWaitIdle is equivalent to submitting a fence to a queue and waiting with an infinite timeout for that fence to signal.

Valid Usage (Implicit)

• queue must be a valid VkQueue handle

Command Properties

'

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

See Also

VkQueue

vkDeviceWaitIdle - Wait for a device to become idle

Parameters

• device is the logical device to idle.

Description

vkDeviceWaitIdle is equivalent to calling vkQueueWaitIdle for all queues owned by device.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

Host Synchronization

• Host access to all VkQueue objects created from device must be externally synchronized

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

See Also

VkDevice

VkSubmitInfo - Structure specifying a queue submit operation

Description

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.

Valid Usage

• Each element of pCommandBuffers must not have been allocated with VK_COMMAND_BUFFER_LEVEL_SECONDARY

• If the geometry shaders feature is not enabled, each element of pWaitDstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
• If the tessellation shaders feature is not enabled, each element of pWaitDstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
• Each element of pWaitDstStageMask must not include VK_PIPELINE_STAGE_HOST_BIT.

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_SUBMIT_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkD3D12FenceSubmitInfoKHR, VkDeviceGroupSubmitInfo, VkProtectedSubmitInfo, VkWin32KeyedMutexAcquireReleaseInfoKHR, or VkWin32KeyedMutexAcquireReleaseInfoNV
• Each sType member in the pNext chain must be unique
• If waitSemaphoreCount is not 0, pWaitSemaphores must be a valid pointer to an array of waitSemaphoreCount valid VkSemaphore handles
• If waitSemaphoreCount is not 0, pWaitDstStageMask must be a valid pointer to an array of waitSemaphoreCount valid combinations of VkPipelineStageFlagBits values
• Each element of pWaitDstStageMask must not be 0
• If commandBufferCount is not 0, pCommandBuffers must be a valid pointer to an array of commandBufferCount valid VkCommandBuffer handles
• If signalSemaphoreCount is not 0, pSignalSemaphores must be a valid pointer to an array of signalSemaphoreCount valid VkSemaphore handles
• Each of the elements of pCommandBuffers, the elements of pSignalSemaphores, and the elements of pWaitSemaphores that are valid handles must have been created, allocated, or retrieved from the same VkDevice

See Also

VkCommandBuffer, VkPipelineStageFlags, VkSemaphore, VkStructureType, vkQueueSubmit

VkPipelineStageFlags - Bitmask of VkPipelineStageFlagBits

Description

VkPipelineStageFlags is a bitmask type for setting a mask of zero or more VkPipelineStageFlagBits.

See Also

VkPipelineStageFlagBits, VkSubmitInfo, VkSubpassDependency, vkCmdPipelineBarrier, vkCmdResetEvent, vkCmdSetEvent, vkCmdWaitEvents