vkCmdBindPipeline(3)

# vkCmdBindPipeline(3) Manual Page

## Name

vkCmdBindPipeline - Bind a pipeline object to a command buffer

Loading… please wait.

## 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.

- The pipeline bound to `VK_PIPELINE_BIND_POINT_COMPUTE` controls the behavior of all dispatching commands.

- The pipeline bound to `VK_PIPELINE_BIND_POINT_GRAPHICS` controls the behavior of all drawing commands.

- The pipeline bound to `VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR` controls the behavior of vkCmdTraceRaysKHR and vkCmdTraceRaysIndirectKHR.

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 variable multisample rate 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`, the `pipeline` must be a ray tracing pipeline

- VUID-vkCmdBindPipeline-pipeline-03382
  The `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_EXT` or `VK_DYNAMIC_STATE_VIEWPORT`, and `VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT` 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.

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-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 | Supported Queue Types | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Both | Graphics Compute |

## See Also

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-2021 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0