C Specification

To copy data between image objects, call:

// Provided by VK_VERSION_1_3
void vkCmdCopyImage2(
    VkCommandBuffer                             commandBuffer,
    const VkCopyImageInfo2*                     pCopyImageInfo);
// Provided by VK_KHR_copy_commands2
// Equivalent to vkCmdCopyImage2
void vkCmdCopyImage2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyImageInfo2*                     pCopyImageInfo);

Parameters

  • commandBuffer is the command buffer into which the command will be recorded.

  • pCopyImageInfo is a pointer to a VkCopyImageInfo2 structure describing the copy parameters.

Description

This command is functionally identical to vkCmdCopyImage, but includes extensible sub-structures that include sType and pNext parameters, allowing them to be more easily extended.

Valid Usage

  • VUID-vkCmdCopyImage2-commandBuffer-01825
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdCopyImage2-commandBuffer-01826
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

  • VUID-vkCmdCopyImage2-commandBuffer-01827
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

  • VUID-vkCmdCopyImage2-commandBuffer-10217
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT, and the maintenance10 feature is not enabled, for each element of pCopyImageInfo->pRegions, where the aspectMask member of srcSubresource is VK_IMAGE_ASPECT_COLOR_BIT, the aspectMask of dstSubresource must not be VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkCmdCopyImage2-commandBuffer-11782
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT but does support VK_QUEUE_COMPUTE_BIT, and in any element of pCopyImageInfo->pRegions the aspectMask member of srcSubresource is VK_IMAGE_ASPECT_COLOR_BIT and the aspectMask of dstSubresource is VK_IMAGE_ASPECT_DEPTH_BIT, then the format features of dstImage must contain VK_FORMAT_FEATURE_2_DEPTH_COPY_ON_COMPUTE_QUEUE_BIT_KHR

  • VUID-vkCmdCopyImage2-commandBuffer-11783
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT and VK_QUEUE_COMPUTE_BIT, but does support VK_QUEUE_TRANSFER_BIT, and in any element of pCopyImageInfo->pRegions the aspectMask member of srcSubresource is VK_IMAGE_ASPECT_COLOR_BIT and the aspectMask of dstSubresource is VK_IMAGE_ASPECT_DEPTH_BIT, then the format features of dstImage must contain VK_FORMAT_FEATURE_2_DEPTH_COPY_ON_TRANSFER_QUEUE_BIT_KHR

  • VUID-vkCmdCopyImage2-commandBuffer-11784
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT but does support VK_QUEUE_COMPUTE_BIT, and in any element of pCopyImageInfo->pRegions the aspectMask member of srcSubresource is VK_IMAGE_ASPECT_COLOR_BIT and the aspectMask of dstSubresource is VK_IMAGE_ASPECT_STENCIL_BIT, then the format features of dstImage must contain VK_FORMAT_FEATURE_2_STENCIL_COPY_ON_COMPUTE_QUEUE_BIT_KHR

  • VUID-vkCmdCopyImage2-commandBuffer-11785
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT and VK_QUEUE_COMPUTE_BIT, but does support VK_QUEUE_TRANSFER_BIT, and in any element of pCopyImageInfo->pRegions the aspectMask member of srcSubresource is VK_IMAGE_ASPECT_COLOR_BIT and the aspectMask of dstSubresource is VK_IMAGE_ASPECT_STENCIL_BIT, then the format features of dstImage must contain VK_FORMAT_FEATURE_2_STENCIL_COPY_ON_TRANSFER_QUEUE_BIT_KHR

  • VUID-vkCmdCopyImage2-commandBuffer-10218
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT, and the maintenance10 feature is not enabled, for each element of pCopyImageInfo->pRegions, where the aspectMask member of dstSubresource is VK_IMAGE_ASPECT_COLOR_BIT then the aspectMask of srcSubresource must not be VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkCmdCopyImage2-commandBuffer-11786
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT but does support VK_QUEUE_COMPUTE_BIT, and in any element of pCopyImageInfo->pRegions the aspectMask member of dstSubresource is VK_IMAGE_ASPECT_COLOR_BIT and the aspectMask of srcSubresource is VK_IMAGE_ASPECT_DEPTH_BIT, then the format features of srcImage must contain VK_FORMAT_FEATURE_2_DEPTH_COPY_ON_COMPUTE_QUEUE_BIT_KHR

  • VUID-vkCmdCopyImage2-commandBuffer-11787
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT and VK_QUEUE_COMPUTE_BIT, but does support VK_QUEUE_TRANSFER_BIT, and in any element of pCopyImageInfo->pRegions the aspectMask member of dstSubresource is VK_IMAGE_ASPECT_COLOR_BIT and the aspectMask of srcSubresource is VK_IMAGE_ASPECT_DEPTH_BIT, then the format features of srcImage must contain VK_FORMAT_FEATURE_2_DEPTH_COPY_ON_TRANSFER_QUEUE_BIT_KHR

  • VUID-vkCmdCopyImage2-commandBuffer-11788
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT but does support VK_QUEUE_COMPUTE_BIT, and in any element of pCopyImageInfo->pRegions the aspectMask member of dstSubresource is VK_IMAGE_ASPECT_COLOR_BIT and the aspectMask of srcSubresource is VK_IMAGE_ASPECT_STENCIL_BIT, then the format features of srcImage must contain VK_FORMAT_FEATURE_2_STENCIL_COPY_ON_COMPUTE_QUEUE_BIT_KHR

  • VUID-vkCmdCopyImage2-commandBuffer-11789
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT and VK_QUEUE_COMPUTE_BIT, but does support VK_QUEUE_TRANSFER_BIT, and in any element of pCopyImageInfo->pRegions the aspectMask member of dstSubresource is VK_IMAGE_ASPECT_COLOR_BIT and the aspectMask of srcSubresource is VK_IMAGE_ASPECT_STENCIL_BIT, then the format features of srcImage must contain VK_FORMAT_FEATURE_2_STENCIL_COPY_ON_TRANSFER_QUEUE_BIT_KHR

Valid Usage (Implicit)

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

  • VUID-vkCmdCopyImage2-pCopyImageInfo-parameter
    pCopyImageInfo must be a valid pointer to a valid VkCopyImageInfo2 structure

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

  • VUID-vkCmdCopyImage2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT, VK_QUEUE_GRAPHICS_BIT, or VK_QUEUE_TRANSFER_BIT operations

  • VUID-vkCmdCopyImage2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyImage2-suspended
    This command must not be called between suspended render pass instances

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

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

Outside

Outside

VK_QUEUE_COMPUTE_BIT
VK_QUEUE_GRAPHICS_BIT
VK_QUEUE_TRANSFER_BIT

Action
Conditional Rendering

vkCmdCopyImage2 is not affected by conditional rendering

See Also

VK_KHR_copy_commands2, VK_VERSION_1_3, VkCommandBuffer, VkCopyImageInfo2

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

SPDX-License-Identifier: CC-BY-4.0