vkAllocateCommandBuffers - Allocate command buffers from an existing command pool

Description

allocateCommandBuffers can be used to allocate multiple command buffers. If the allocation of any of those command buffers fails, the implementation must free all successfully allocated command buffer objects from this command, set all entries of the pCommandBuffers array to NULL and return the error.

Note

Filling pCommandBuffers with NULL values on failure is an exception to the default error behavior that output parameters will have undefined contents.

When command buffers are first allocated, they are in the initial state.

Valid Usage (Implicit)

• device must be a valid Device handle

• pAllocateInfo must be a valid pointer to a valid CommandBufferAllocateInfo structure
• pCommandBuffers must be a valid pointer to an array of pAllocateInfo->commandBufferCount CommandBuffer handles
• pAllocateInfo->commandBufferCount must be greater than 0

Host Synchronization

• Host access to pAllocateInfo->commandPool must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_VERSION_1_0, CommandBuffer, CommandBufferAllocateInfo, Device

A convenience wrapper to make a compatible pair of calls to allocateCommandBuffers and freeCommandBuffers

To ensure that freeCommandBuffers is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

vkFreeCommandBuffers - Free command buffers

Description

Any primary command buffer that is in the recording or executable state and has any element of pCommandBuffers recorded into it, becomes invalid.

Valid Usage

• All elements of pCommandBuffers must not be in the pending state

• pCommandBuffers must be a valid pointer to an array of commandBufferCount CommandBuffer handles, each element of which must either be a valid handle or NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• commandPool must be a valid CommandPool handle
• commandBufferCount must be greater than 0
• commandPool must have been created, allocated, or retrieved from device
• Each element of pCommandBuffers that is a valid handle must have been created, allocated, or retrieved from commandPool

Host Synchronization

• Host access to commandPool must be externally synchronized

• Host access to each member of pCommandBuffers must be externally synchronized

See Also

VK_VERSION_1_0, CommandBuffer, CommandPool, Device

vkBeginCommandBuffer - Start recording a command buffer

Valid Usage

• commandBuffer must not be in the recording or pending state

• If commandBuffer was allocated from a CommandPool which did not have the COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, commandBuffer must be in the initial state
• If commandBuffer is a secondary command buffer, the pInheritanceInfo member of pBeginInfo must be a valid CommandBufferInheritanceInfo structure
• If commandBuffer is a secondary command buffer and either the occlusionQueryEnable member of the pInheritanceInfo member of pBeginInfo is FALSE, or the occlusionQueryPrecise feature is not enabled, then pBeginInfo->pInheritanceInfo->queryFlags must not contain QUERY_CONTROL_PRECISE_BIT
• If commandBuffer is a primary command buffer, then pBeginInfo->flags must not set both the COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT and the COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flags

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pBeginInfo must be a valid pointer to a valid CommandBufferBeginInfo structure

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_VERSION_1_0, CommandBuffer, CommandBufferBeginInfo

This function will call the supplied action between calls to beginCommandBuffer and endCommandBuffer

Note that endCommandBuffer is *not* called if an exception is thrown by the inner action.

vkEndCommandBuffer - Finish recording a command buffer

Description

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 endCommandBuffer, and the command buffer will be moved to the invalid state.

In case the application recorded one or more video encode operations into the command buffer, implementations may return the VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error if any of the specified Video Std parameters do not adhere to the syntactic or semantic requirements of the used video compression standard, or if values derived from parameters according to the rules defined by the used video compression standard do not adhere to the capabilities of the video compression standard or the implementation.

Note

Applications should not rely on the VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error being returned by any command as a means to verify Video Std parameters, as implementations are not required to report the error in any specific set of cases.

Valid Usage

• commandBuffer must be in the recording state

• If commandBuffer is a primary command buffer, there must not be an active render pass instance
• All queries made active during the recording of commandBuffer must have been made inactive
• Conditional rendering must not be active
• There must be no video session object bound
• If commandBuffer is a secondary command buffer, there must not be an outstanding cmdBeginDebugUtilsLabelEXT command recorded to commandBuffer that has not previously been ended by a call to cmdEndDebugUtilsLabelEXT
• If commandBuffer is a secondary command buffer, there must not be an outstanding cmdDebugMarkerBeginEXT command recorded to commandBuffer that has not previously been ended by a call to cmdDebugMarkerEndEXT

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR

See Also

VK_VERSION_1_0, CommandBuffer

vkResetCommandBuffer - Reset a command buffer to the initial state

Description

Any primary command buffer that is in the recording or executable state and has commandBuffer recorded into it, becomes invalid.

Valid Usage

• commandBuffer must not be in the pending state

• commandBuffer must have been allocated from a pool that was created with the COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• flags must be a valid combination of CommandBufferResetFlagBits values

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_VERSION_1_0, CommandBuffer, CommandBufferResetFlags

VkCommandBufferAllocateInfo - Structure specifying the allocation parameters for command buffer object

Valid Usage (Implicit)

See Also

VK_VERSION_1_0, CommandBufferLevel, CommandPool, StructureType, allocateCommandBuffers

VkCommandBufferInheritanceInfo - Structure specifying command buffer inheritance information

Description

If the CommandBuffer will not be executed within a render pass instance, or if the render pass instance was begun with cmdBeginRendering, renderPass, subpass, and framebuffer are ignored.

Valid Usage

• If the inheritedQueries feature is not enabled, occlusionQueryEnable must be FALSE

• If the inheritedQueries feature is enabled, queryFlags must be a valid combination of QueryControlFlagBits values
• If the inheritedQueries feature is not enabled, queryFlags must be 0
• If the pipelineStatisticsQuery feature is enabled, pipelineStatistics must be a valid combination of QueryPipelineStatisticFlagBits values
• If the pipelineStatisticsQuery feature is not enabled, pipelineStatistics must be 0

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_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 AttachmentSampleCountInfoAMD, CommandBufferInheritanceConditionalRenderingInfoEXT, CommandBufferInheritanceRenderPassTransformInfoQCOM, CommandBufferInheritanceRenderingInfo, CommandBufferInheritanceViewportScissorInfoNV, ExternalFormatANDROID, or MultiviewPerViewAttributesInfoNVX
• The sType value of each struct in the pNext chain must be unique
• Both of framebuffer, and renderPass that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Device

See Also

VK_VERSION_1_0, Bool32, CommandBufferBeginInfo, Framebuffer, QueryControlFlags, QueryPipelineStatisticFlags, RenderPass, StructureType

VkCommandBufferBeginInfo - Structure specifying a command buffer begin operation

Valid Usage

• If flags contains COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the CommandPool that commandBuffer was allocated from must support graphics operations

• If flags contains COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the framebuffer member of pInheritanceInfo must be either NULL_HANDLE, or a valid Framebuffer that is compatible with the renderPass member of pInheritanceInfo
• If flags contains COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the dynamicRendering feature is not enabled, the renderPass member of pInheritanceInfo must not be NULL_HANDLE
• If flags contains COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the renderPass member of pInheritanceInfo is NULL_HANDLE, the pNext chain of pInheritanceInfo must include a CommandBufferInheritanceRenderingInfo structure
• If flags contains COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the renderPass member of pInheritanceInfo is NULL_HANDLE, and the pNext chain of pInheritanceInfo includes a AttachmentSampleCountInfoAMD or AttachmentSampleCountInfoNV structure, the colorAttachmentCount member of that structure must be equal to the value of CommandBufferInheritanceRenderingInfo::colorAttachmentCount
• If flags contains COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the renderPass member of pInheritanceInfo is not NULL_HANDLE, the renderPass member of pInheritanceInfo must be a valid RenderPass
• If flags contains COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the renderPass member of pInheritanceInfo is not NULL_HANDLE, the subpass member of pInheritanceInfo must be a valid subpass index within the renderPass member of pInheritanceInfo

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO

• pNext must be NULL or a pointer to a valid instance of DeviceGroupCommandBufferBeginInfo
• The sType value of each struct in the pNext chain must be unique
• flags must be a valid combination of CommandBufferUsageFlagBits values

See Also

VK_VERSION_1_0, CommandBufferInheritanceInfo, CommandBufferUsageFlags, StructureType, beginCommandBuffer

VkCommandBuffer - Opaque handle to a command buffer object

See Also

VK_VERSION_1_0, CommandBufferSubmitInfo, SubmitInfo, allocateCommandBuffers, beginCommandBuffer, cmdBeginConditionalRenderingEXT, cmdBeginDebugUtilsLabelEXT, cmdBeginQuery, cmdBeginQueryIndexedEXT, cmdBeginRenderPass, cmdBeginRenderPass2, cmdBeginRenderPass2KHR, cmdBeginRendering, cmdBeginRenderingKHR, cmdBeginTransformFeedbackEXT, vkCmdBeginVideoCodingKHR, cmdBindDescriptorBufferEmbeddedSamplersEXT, cmdBindDescriptorBuffersEXT, cmdBindDescriptorSets, cmdBindIndexBuffer, cmdBindIndexBuffer2KHR, cmdBindInvocationMaskHUAWEI, cmdBindPipeline, cmdBindPipelineShaderGroupNV, cmdBindShadersEXT, cmdBindShadingRateImageNV, cmdBindTransformFeedbackBuffersEXT, cmdBindVertexBuffers, cmdBindVertexBuffers2, cmdBindVertexBuffers2EXT, cmdBlitImage, cmdBlitImage2, cmdBlitImage2KHR, cmdBuildAccelerationStructureNV, cmdBuildAccelerationStructuresIndirectKHR, cmdBuildAccelerationStructuresKHR, cmdBuildMicromapsEXT, cmdClearAttachments, cmdClearColorImage, cmdClearDepthStencilImage, vkCmdControlVideoCodingKHR, cmdCopyAccelerationStructureKHR, cmdCopyAccelerationStructureNV, cmdCopyAccelerationStructureToMemoryKHR, cmdCopyBuffer, cmdCopyBuffer2, cmdCopyBuffer2KHR, cmdCopyBufferToImage, cmdCopyBufferToImage2, cmdCopyBufferToImage2KHR, cmdCopyImage, cmdCopyImage2, cmdCopyImage2KHR, cmdCopyImageToBuffer, cmdCopyImageToBuffer2, cmdCopyImageToBuffer2KHR, cmdCopyMemoryIndirectNV, cmdCopyMemoryToAccelerationStructureKHR, cmdCopyMemoryToImageIndirectNV, cmdCopyMemoryToMicromapEXT, cmdCopyMicromapEXT, cmdCopyMicromapToMemoryEXT, cmdCopyQueryPoolResults, cmdCuLaunchKernelNVX, cmdCudaLaunchKernelNV, cmdDebugMarkerBeginEXT, cmdDebugMarkerEndEXT, cmdDebugMarkerInsertEXT, vkCmdDecodeVideoKHR, cmdDecompressMemoryIndirectCountNV, cmdDecompressMemoryNV, cmdDispatch, cmdDispatchBase, cmdDispatchBaseKHR, cmdDispatchGraphAMDX, cmdDispatchGraphIndirectAMDX, cmdDispatchGraphIndirectCountAMDX, cmdDispatchIndirect, cmdDraw, cmdDrawClusterHUAWEI, cmdDrawClusterIndirectHUAWEI, cmdDrawIndexed, cmdDrawIndexedIndirect, cmdDrawIndexedIndirectCount, cmdDrawIndexedIndirectCountAMD, cmdDrawIndexedIndirectCountKHR, cmdDrawIndirect, cmdDrawIndirectByteCountEXT, cmdDrawIndirectCount, cmdDrawIndirectCountAMD, cmdDrawIndirectCountKHR, cmdDrawMeshTasksEXT, cmdDrawMeshTasksIndirectCountEXT, cmdDrawMeshTasksIndirectCountNV, cmdDrawMeshTasksIndirectEXT, cmdDrawMeshTasksIndirectNV, cmdDrawMeshTasksNV, cmdDrawMultiEXT, cmdDrawMultiIndexedEXT, vkCmdEncodeVideoKHR, cmdEndConditionalRenderingEXT, cmdEndDebugUtilsLabelEXT, cmdEndQuery, cmdEndQueryIndexedEXT, cmdEndRenderPass, cmdEndRenderPass2, cmdEndRenderPass2KHR, cmdEndRendering, cmdEndRenderingKHR, cmdEndTransformFeedbackEXT, vkCmdEndVideoCodingKHR, cmdExecuteCommands, cmdExecuteGeneratedCommandsNV, cmdFillBuffer, cmdInitializeGraphScratchMemoryAMDX, cmdInsertDebugUtilsLabelEXT, cmdNextSubpass, cmdNextSubpass2, cmdNextSubpass2KHR, cmdOpticalFlowExecuteNV, cmdPipelineBarrier, cmdPipelineBarrier2, cmdPipelineBarrier2KHR, cmdPreprocessGeneratedCommandsNV, cmdPushConstants, cmdPushDescriptorSetKHR, cmdPushDescriptorSetWithTemplateKHR, cmdResetEvent, cmdResetEvent2, cmdResetEvent2KHR, cmdResetQueryPool, cmdResolveImage, cmdResolveImage2, cmdResolveImage2KHR, cmdSetAlphaToCoverageEnableEXT, cmdSetAlphaToOneEnableEXT, cmdSetAttachmentFeedbackLoopEnableEXT, cmdSetBlendConstants, cmdSetCheckpointNV, cmdSetCoarseSampleOrderNV, cmdSetColorBlendAdvancedEXT, cmdSetColorBlendEnableEXT, cmdSetColorBlendEquationEXT, cmdSetColorWriteEnableEXT, cmdSetColorWriteMaskEXT, cmdSetConservativeRasterizationModeEXT, cmdSetCoverageModulationModeNV, cmdSetCoverageModulationTableEnableNV, cmdSetCoverageModulationTableNV, cmdSetCoverageReductionModeNV, cmdSetCoverageToColorEnableNV, cmdSetCoverageToColorLocationNV, cmdSetCullMode, cmdSetCullModeEXT, cmdSetDepthBias, cmdSetDepthBias2EXT, cmdSetDepthBiasEnable, cmdSetDepthBiasEnableEXT, cmdSetDepthBounds, cmdSetDepthBoundsTestEnable, cmdSetDepthBoundsTestEnableEXT, cmdSetDepthClampEnableEXT, cmdSetDepthClipEnableEXT, cmdSetDepthClipNegativeOneToOneEXT, cmdSetDepthCompareOp, cmdSetDepthCompareOpEXT, cmdSetDepthTestEnable, cmdSetDepthTestEnableEXT, cmdSetDepthWriteEnable, cmdSetDepthWriteEnableEXT, cmdSetDescriptorBufferOffsetsEXT, cmdSetDeviceMask, cmdSetDeviceMaskKHR, cmdSetDiscardRectangleEXT, cmdSetDiscardRectangleEnableEXT, cmdSetDiscardRectangleModeEXT, cmdSetEvent, cmdSetEvent2, cmdSetEvent2KHR, cmdSetExclusiveScissorEnableNV, cmdSetExclusiveScissorNV, cmdSetExtraPrimitiveOverestimationSizeEXT, cmdSetFragmentShadingRateEnumNV, cmdSetFragmentShadingRateKHR, cmdSetFrontFace, cmdSetFrontFaceEXT, cmdSetLineRasterizationModeEXT, cmdSetLineStippleEXT, cmdSetLineStippleEnableEXT, cmdSetLineWidth, cmdSetLogicOpEXT, cmdSetLogicOpEnableEXT, cmdSetPatchControlPointsEXT, cmdSetPerformanceMarkerINTEL, cmdSetPerformanceOverrideINTEL, cmdSetPerformanceStreamMarkerINTEL, cmdSetPolygonModeEXT, cmdSetPrimitiveRestartEnable, cmdSetPrimitiveRestartEnableEXT, cmdSetPrimitiveTopology, cmdSetPrimitiveTopologyEXT, cmdSetProvokingVertexModeEXT, cmdSetRasterizationSamplesEXT, cmdSetRasterizationStreamEXT, cmdSetRasterizerDiscardEnable, cmdSetRasterizerDiscardEnableEXT, cmdSetRayTracingPipelineStackSizeKHR, cmdSetRepresentativeFragmentTestEnableNV, cmdSetSampleLocationsEXT, cmdSetSampleLocationsEnableEXT, cmdSetSampleMaskEXT, cmdSetScissor, cmdSetScissorWithCount, cmdSetScissorWithCountEXT, cmdSetShadingRateImageEnableNV, cmdSetStencilCompareMask, cmdSetStencilOp, cmdSetStencilOpEXT, cmdSetStencilReference, cmdSetStencilTestEnable, cmdSetStencilTestEnableEXT, cmdSetStencilWriteMask, cmdSetTessellationDomainOriginEXT, cmdSetVertexInputEXT, cmdSetViewport, cmdSetViewportShadingRatePaletteNV, cmdSetViewportSwizzleNV, cmdSetViewportWScalingEnableNV, cmdSetViewportWScalingNV, cmdSetViewportWithCount, cmdSetViewportWithCountEXT, cmdSubpassShadingHUAWEI, cmdTraceRaysIndirect2KHR, cmdTraceRaysIndirectKHR, cmdTraceRaysKHR, cmdTraceRaysNV, cmdUpdateBuffer, cmdUpdatePipelineIndirectBufferNV, cmdWaitEvents, cmdWaitEvents2, cmdWaitEvents2KHR, cmdWriteAccelerationStructuresPropertiesKHR, cmdWriteAccelerationStructuresPropertiesNV, cmdWriteBufferMarker2AMD, cmdWriteBufferMarkerAMD, cmdWriteMicromapsPropertiesEXT, cmdWriteTimestamp, cmdWriteTimestamp2, cmdWriteTimestamp2KHR, endCommandBuffer, freeCommandBuffers, resetCommandBuffer

VkCommandBufferLevel - Enumerant specifying a command buffer level

See Also

VK_VERSION_1_0, CommandBufferAllocateInfo

VkQueryControlFlagBits - Bitmask specifying constraints on a query

See Also

VK_VERSION_1_0, QueryControlFlags

VkCommandBufferUsageFlagBits - Bitmask specifying usage behavior for command buffer

See Also

VK_VERSION_1_0, CommandBufferUsageFlags

VkCommandBufferResetFlagBits - Bitmask controlling behavior of a command buffer reset

See Also

VK_VERSION_1_0, CommandBufferResetFlags