C Specification

Once a pipeline has been created, it can be bound to the command buffer using the command:

// Provided by VK_VERSION_1_0
void vkCmdBindPipeline(
    VkCommandBuffer                             commandBuffer,
    VkPipelineBindPoint                         pipelineBindPoint,
    VkPipeline                                  pipeline);

Parameters

  • commandBuffer is the command buffer that the pipeline will be bound to.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying to which bind point the pipeline is bound. Binding one does not disturb the others.

  • pipeline is the pipeline to be bound.

Description

Once bound, a pipeline binding affects subsequent commands that interact with the given pipeline type in the command buffer until a different pipeline of the same type is bound to the bind point. Commands that do not interact with the given pipeline type must not be affected by the pipeline state.

Valid Usage

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00777
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_COMPUTE, the VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00778
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, the VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00779
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_COMPUTE, pipeline must be a compute pipeline

  • VUID-vkCmdBindPipeline-pipelineBindPoint-00780
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline must be a graphics pipeline

  • VUID-vkCmdBindPipeline-pipeline-00781
    If the variableMultisampleRate feature is not supported, pipeline is a graphics pipeline, the current subpass uses no attachments, and this is not the first call to this function with a graphics pipeline after transitioning to the current subpass, then the sample count specified by this pipeline must match that set in the previous pipeline

  • VUID-vkCmdBindPipeline-variableSampleLocations-01525
    If VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations is VK_FALSE, and pipeline is a graphics pipeline created with a VkPipelineSampleLocationsStateCreateInfoEXT structure having its sampleLocationsEnable member set to VK_TRUE but without VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT enabled then the current render pass instance must have been begun by specifying a VkRenderPassSampleLocationsBeginInfoEXT structure whose pPostSubpassSampleLocations member contains an element with a subpassIndex matching the current subpass index and the sampleLocationsInfo member of that element must match the sampleLocationsInfo specified in VkPipelineSampleLocationsStateCreateInfoEXT when the pipeline was created

  • VUID-vkCmdBindPipeline-None-02323
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdBindPipeline-pipelineBindPoint-02391
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, the VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-02392
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, pipeline must be a ray tracing pipeline

  • VUID-vkCmdBindPipeline-pipelineBindPoint-06721
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, commandBuffer must not be a protected command buffer

  • VUID-vkCmdBindPipeline-pipeline-03382
    pipeline must not have been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR set

  • VUID-vkCmdBindPipeline-commandBuffer-04808
    If commandBuffer is a secondary command buffer with VkCommandBufferInheritanceViewportScissorInfoNV::viewportScissor2D enabled and pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, then the pipeline must have been created with VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT or VK_DYNAMIC_STATE_VIEWPORT, and VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT or VK_DYNAMIC_STATE_SCISSOR enabled

  • VUID-vkCmdBindPipeline-commandBuffer-04809
    If commandBuffer is a secondary command buffer with VkCommandBufferInheritanceViewportScissorInfoNV::viewportScissor2D enabled and pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS and pipeline was created with VkPipelineDiscardRectangleStateCreateInfoEXT structure and its discardRectangleCount member is not 0, then the pipeline must have been created with VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT enabled

  • VUID-vkCmdBindPipeline-pipelineBindPoint-04881
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS and the provokingVertexModePerPipeline limit is VK_FALSE, then pipeline’s VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::provokingVertexMode must be the same as that of any other pipelines previously bound to this bind point within the current render pass instance, including any pipeline already bound when beginning the render pass instance

  • VUID-vkCmdBindPipeline-pipelineBindPoint-04949
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, the VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBindPipeline-pipelineBindPoint-04950
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, pipeline must be a subpass shading pipeline

  • VUID-vkCmdBindPipeline-pipeline-06195
    If pipeline is a graphics pipeline, this command has been called inside a render pass instance started with vkCmdBeginRendering, and commands using the previously bound graphics pipeline have been recorded within the render pass instance, then the value of VkPipelineRenderingCreateInfo::colorAttachmentCount specified by this pipeline must match that set in the previous pipeline

  • VUID-vkCmdBindPipeline-pipeline-06196
    If pipeline is a graphics pipeline, this command has been called inside a render pass instance started with vkCmdBeginRendering, and commands using the previously bound graphics pipeline have been recorded within the render pass instance, then the elements of VkPipelineRenderingCreateInfo::pColorAttachmentFormats specified by this pipeline must match that set in the previous pipeline

  • VUID-vkCmdBindPipeline-pipeline-06197
    If pipeline is a graphics pipeline, this command has been called inside a render pass instance started with vkCmdBeginRendering, and commands using the previously bound graphics pipeline have been recorded within the render pass instance, then the value of VkPipelineRenderingCreateInfo::depthAttachmentFormat specified by this pipeline must match that set in the previous pipeline

  • VUID-vkCmdBindPipeline-pipeline-06194
    If pipeline is a graphics pipeline, this command has been called inside a render pass instance started with vkCmdBeginRendering, and commands using the previously bound graphics pipeline have been recorded within the render pass instance, then the value of VkPipelineRenderingCreateInfo::stencilAttachmentFormat specified by this pipeline must match that set in the previous pipeline

  • VUID-vkCmdBindPipeline-pipeline-06856
    If pipeline is a graphics pipeline, this command has been called inside a render pass instance started with vkCmdBeginRendering, and the pNext chain of VkRenderingInfo includes a VkMultisampledRenderToSingleSampledInfoEXT structure with multisampledRenderToSingleSampledEnable equal to VK_TRUE, then the value of VkGraphicsPipelineCreateInfo::pMultisampleState::rasterizationSamples must be equal to VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples.

  • VUID-vkCmdBindPipeline-pipelineBindPoint-06653
    If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline must have been created without VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

Valid Usage (Implicit)

  • VUID-vkCmdBindPipeline-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBindPipeline-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-vkCmdBindPipeline-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkCmdBindPipeline-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBindPipeline-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

  • VUID-vkCmdBindPipeline-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBindPipeline-commonparent
    Both of commandBuffer, and pipeline must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

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

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types

Primary
Secondary

Both

Outside

Graphics
Compute

See Also

VK_VERSION_1_0, VkCommandBuffer, VkPipeline, VkPipelineBindPoint

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0