A command buffer is recorded using the vkBeginCommandBuffer() and vkEndCommandBuffer() APIs. These APIs define the scope under which any specified Vulkan commands are recorded. The following example shows the recording of the Render Pass instance creation between these two APIs, which works as the start and end scopes. For more information on creating a Render Pass, refer to the Understanding the Render Pass section in Chapter 7, Buffer Resource, Render Pass, Framebuffer, and Shaders with SPIR-V.
The start of the recording is performed using the vkBeginCommandBuffer() API. This defines the starting scope after which any call specified is considered to be recorded until the end scope is reached (vkEndCommandBuffer()).
The following is the syntax of this API, followed by a description of the necessary parameters:
VkResult vkBeginCommandBuffer(
VkCommandBuffer commandBuffer,
const VkCommandBufferBeginInfo* pBeginInfo);
This API accepts two parameters. The first one is the handle of the command buffer in which the calls are to be recorded. The second parameter is a VkCommandBufferBeginInfo structure object that defines additional information telling you how to begin the command buffer recording process.
The following is the API syntax of the VkCommandBufferBeginInfo structure:
typedef struct VkCommandBufferBeginInfo {
VkStructureType sType;
const void* pNext;
VkCommandBufferUsageFlags flags;
const VkCommandBufferInheritanceInfo* pInheritanceInfo;
} VkCommandBufferBeginInfo;
The accepted parameters in this structure are described as follows:
|
Parameters |
Description |
|
|
This is the type information of this control structure. It must be specified as |
|
|
This field could be a valid pointer to an extension-specific structure or |
|
|
This is a bitwise mask of the type |
|
|
If this field is not |
Command buffer recording is performed using the vkEndCommandBuffer() API. It accepts one parameter, which specifies the command buffer object on which the recording is to be stopped. Here's the syntax for this:
VkResult vkEndCommandBuffer(VkCommandBuffer commandBuffer);
Once the command buffer (VkCommandBuffer) is recorded, it is ready to be submitted to a queue. The vkQueueSubmit() API helps commit the jobs in an appropriate queue. Let's check out the syntax of this:
VkResult vkQueueSubmit(
VkQueue queue,
uint32_t submitCount,
const VkSubmitInfo* pSubmitInfo,
VkFence fence);
The accepted parameters are listed as follows:
|
Parameters |
Description |
|
|
This is the queue's handle to which the command buffer is submitted. |
|
|
This refers to the number of |
|
|
This refers to the |
|
|
This is used as a signaling mechanism indicating command buffer completion of the execution. If |
Let's take a look at VkSubmitInfo. This structure embeds multiple pieces of information into itself. This information is used by the submission process to handle an individual VkSubmitInfo object containing a single command buffer or a bunch of them. The following is the syntax of this:
typedef struct VkSubmitInfo {
VkStructureType type;
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;
The accepted parameters are described as follows:
|
Parameters |
Description |
|
|
This is the type of the
|
|
|
This is a pointer to an extension-specific structure or |
|
|
The refers to the number of semaphores upon which the command buffer is made to wait before it's executed. |
|
|
This is a pointer to an array of semaphores upon which the command buffers are made to wait before they are executed in a batch. |
|
|
This is a pointer to an array of pipeline stages at which each corresponding semaphore wait will occur. |
|
|
This refers to the number of command buffers to be executed in a batch. |
|
|
This is a pointer to an array of command buffers to be executed in a batch. |
|
|
This refers to the number of semaphores to be signaled once the commands specified in |
|
|
This is a pointer to an array of semaphores that will be signaled when the command buffers for the given batch are executed. |
Once committed to the queue, the application must wait for the queue to finish the submitted jobs and be ready for the next batch. The process of waiting for the queue can be done using the vkQueueWaitIdle() API. This API will be blocked until all the command buffers and sparse-binding operations in the queue are not completed. This API accepts one argument, which specifies the handle of the queue upon which the waiting has to be done. The following is the syntax of this API:
VkResult vkQueueWaitIdle(VkQueue queue);