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.

- The pipeline bound to `VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI` controls the behavior of vkCmdSubpassShadingHUAWEI.

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-pipelineProtectedAccess-07408
  If the `pipelineProtectedAccess` feature is enabled, and `commandBuffer` is a protected command buffer, `pipeline` must have been created without `VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT`

- VUID-vkCmdBindPipeline-pipelineProtectedAccess-07409
  If the `pipelineProtectedAccess` feature is enabled, and `commandBuffer` is not a protected command buffer, `pipeline` must have been created without `VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT`

- 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-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 | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Both | Outside | Graphics Compute | State

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