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 Queue object that will be filled with the handle for the requested queue.

Description

getDeviceQueue must only be used to get queues that were created with the flags parameter of DeviceQueueCreateInfo set to zero. To get queues that were created with a non-zero flags parameter use getDeviceQueue2.

Valid Usage

• queueFamilyIndex must be one of the queue family indices specified when device was created, via the DeviceQueueCreateInfo 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 DeviceQueueCreateInfo structure
• DeviceQueueCreateInfo::flags must have been set to zero when device was created

Valid Usage (Implicit)

• device must be a valid Device handle

• pQueue must be a valid pointer to a Queue handle

See Also

Device, Queue

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 SubmitInfo 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 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 queueSubmit as possible.

queueSubmit 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 queueSubmit 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 COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves to the invalid state.

If queueSubmit fails, it may return ERROR_OUT_OF_HOST_MEMORY or 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 queueSubmit fails in such a way that the implementation is unable to make that guarantee, the implementation must return ERROR_DEVICE_LOST. See Lost Device.

Valid Usage

• If fence is not NULL_HANDLE, fence must be unsignaled

• If fence is not NULL_HANDLE, fence must not be associated with any other queue command that has not yet completed execution on that queue
• Any calls to cmdSetEvent, cmdResetEvent or cmdWaitEvents that have been recorded into any of the command buffer elements of the pCommandBuffers member of any element of pSubmits, must not reference any Event 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 wait operation referring to a binary semaphore defined by any element of the pWaitSemaphores member of any element of pSubmits executes on queue, there must be no other queues waiting on the same semaphore
• All elements of the pWaitSemaphores member of all elements of pSubmits created with a SemaphoreType of SEMAPHORE_TYPE_BINARY must reference a semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends (if any) must have also been submitted for execution
• 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 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 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 CommandPool that was created for the same queue family queue belongs to
• If any element of pSubmits->pCommandBuffers includes a Queue Family Transfer Acquire Operation, there must exist a previously submitted Queue Family Transfer Release Operation on a queue in the queue family identified by the acquire operation, with parameters matching the acquire operation as defined in the definition of such acquire operations, and which happens-before the acquire operation
• If a command recorded into any element of pCommandBuffers was a cmdBeginQuery whose queryPool was created with a queryType of QUERY_TYPE_PERFORMANCE_QUERY_KHR, the profiling lock must have been held continuously on the Device that queue was retrieved from, throughout recording of those command buffers
• Any resource created with SHARING_MODE_EXCLUSIVE that is read by an operation specified by pSubmits must not be owned by any queue family other than the one which queue belongs to, at the time it is executed

Valid Usage (Implicit)

• queue must be a valid Queue handle

• If submitCount is not 0, pSubmits must be a valid pointer to an array of submitCount valid SubmitInfo structures
• If fence is not NULL_HANDLE, fence must be a valid Fence handle
• Both of fence, and queue that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to queue must be externally synchronized

• Host access to fence must be externally synchronized

Command Properties

'

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST

See Also

Fence, Queue, SubmitInfo

vkQueueWaitIdle - Wait for a queue to become idle

Parameters

• queue is the queue on which to wait.

Description

queueWaitIdle 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 Queue handle

Host Synchronization

• Host access to queue must be externally synchronized

Command Properties

'

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST

See Also

Queue

vkDeviceWaitIdle - Wait for a device to become idle

Parameters

• device is the logical device to idle.

Description

deviceWaitIdle is equivalent to calling queueWaitIdle for all queues owned by device.

Valid Usage (Implicit)

• device must be a valid Device handle

Host Synchronization

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

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST

See Also

Device

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 COMMAND_BUFFER_LEVEL_SECONDARY

• If the geometry shaders feature is not enabled, each element of pWaitDstStageMask must not contain PIPELINE_STAGE_GEOMETRY_SHADER_BIT
• If the tessellation shaders feature is not enabled, each element of pWaitDstStageMask must not contain PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
• Each element of pWaitDstStageMask must not include PIPELINE_STAGE_HOST_BIT
• If any element of pWaitSemaphores or pSignalSemaphores was created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE, then the pNext chain must include a TimelineSemaphoreSubmitInfo structure
• If the pNext chain of this structure includes a TimelineSemaphoreSubmitInfo structure and any element of pWaitSemaphores was created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE, then its waitSemaphoreValueCount member must equal waitSemaphoreCount
• If the pNext chain of this structure includes a TimelineSemaphoreSubmitInfo structure and any element of pSignalSemaphores was created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE, then its signalSemaphoreValueCount member must equal signalSemaphoreCount
• For each element of pSignalSemaphores created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE the corresponding element of TimelineSemaphoreSubmitInfo::pSignalSemaphoreValues must have a value greater than the current value of the semaphore when the semaphore signal operation is executed
• For each element of pWaitSemaphores created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE the corresponding element of TimelineSemaphoreSubmitInfo::pWaitSemaphoreValues must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference
• For each element of pSignalSemaphores created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE the corresponding element of TimelineSemaphoreSubmitInfo::pSignalSemaphoreValues must have a value which does not differ from the current value of the semaphore or the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference
• If the mesh shaders feature is not enabled, each element of pWaitDstStageMask must not contain PIPELINE_STAGE_MESH_SHADER_BIT_NV
• If the task shaders feature is not enabled, each element of pWaitDstStageMask must not contain PIPELINE_STAGE_TASK_SHADER_BIT_NV

Valid Usage (Implicit)

• sType must be 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 D3D12FenceSubmitInfoKHR, DeviceGroupSubmitInfo, PerformanceQuerySubmitInfoKHR, ProtectedSubmitInfo, TimelineSemaphoreSubmitInfo, Win32KeyedMutexAcquireReleaseInfoKHR, or Win32KeyedMutexAcquireReleaseInfoNV
• The sType value of each struct in the pNext chain must be unique
• If waitSemaphoreCount is not 0, pWaitSemaphores must be a valid pointer to an array of waitSemaphoreCount valid Semaphore handles
• If waitSemaphoreCount is not 0, pWaitDstStageMask must be a valid pointer to an array of waitSemaphoreCount valid combinations of PipelineStageFlagBits 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 CommandBuffer handles
• If signalSemaphoreCount is not 0, pSignalSemaphores must be a valid pointer to an array of signalSemaphoreCount valid Semaphore handles
• Each of the elements of pCommandBuffers, the elements of pSignalSemaphores, and the elements of pWaitSemaphores that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Device

See Also

CommandBuffer, PipelineStageFlags, Semaphore, StructureType, queueSubmit