C Specification

To attach memory to a VkImage object created without the VK_IMAGE_CREATE_DISJOINT_BIT set, call:

// Provided by VK_VERSION_1_0
VkResult vkBindImageMemory(
    VkDevice                                    device,
    VkImage                                     image,
    VkDeviceMemory                              memory,
    VkDeviceSize                                memoryOffset);

Parameters

  • device is the logical device that owns the image and memory.

  • image is the image.

  • memory is the VkDeviceMemory object describing the device memory to attach.

  • memoryOffset is the start offset of the region of memory which is to be bound to the image. The number of bytes returned in the VkMemoryRequirements::size member in memory, starting from memoryOffset bytes, will be bound to the specified image.

Description

vkBindImageMemory is equivalent to passing the same parameters through VkBindImageMemoryInfo to vkBindImageMemory2.

Valid Usage

  • VUID-vkBindImageMemory-image-01044
    image must not already be backed by a memory object

  • VUID-vkBindImageMemory-image-01045
    image must not have been created with any sparse memory binding flags

  • VUID-vkBindImageMemory-memoryOffset-01046
    memoryOffset must be less than the size of memory

  • VUID-vkBindImageMemory-image-01445
    If image requires a dedicated allocation (as reported by vkGetImageMemoryRequirements2 in VkMemoryDedicatedRequirements::requiresDedicatedAllocation for image), memory must have been created with VkMemoryDedicatedAllocateInfo::image equal to image

  • VUID-vkBindImageMemory-memory-02628
    If the dedicated allocation image aliasing feature is not enabled, and the VkMemoryAllocateInfo provided when memory was allocated included a VkMemoryDedicatedAllocateInfo structure in its pNext chain, and VkMemoryDedicatedAllocateInfo::image was not VK_NULL_HANDLE, then image must equal VkMemoryDedicatedAllocateInfo::image and memoryOffset must be zero

  • VUID-vkBindImageMemory-memory-02629
    If the dedicated allocation image aliasing feature is enabled, and the VkMemoryAllocateInfo provided when memory was allocated included a VkMemoryDedicatedAllocateInfo structure in its pNext chain, and VkMemoryDedicatedAllocateInfo::image was not VK_NULL_HANDLE, then memoryOffset must be zero, and image must be either equal to VkMemoryDedicatedAllocateInfo::image or an image that was created using the same parameters in VkImageCreateInfo, with the exception that extent and arrayLayers may differ subject to the following restrictions: every dimension in the extent parameter of the image being bound must be equal to or smaller than the original image for which the allocation was created; and the arrayLayers parameter of the image being bound must be equal to or smaller than the original image for which the allocation was created

  • VUID-vkBindImageMemory-None-01901
    If image was created with the VK_IMAGE_CREATE_PROTECTED_BIT bit set, the image must be bound to a memory object allocated with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT

  • VUID-vkBindImageMemory-None-01902
    If image was created with the VK_IMAGE_CREATE_PROTECTED_BIT bit not set, the image must not be bound to a memory object created with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT

  • VUID-vkBindImageMemory-image-01050
    If image was created with VkDedicatedAllocationImageCreateInfoNV::dedicatedAllocation equal to VK_TRUE, memory must have been created with VkDedicatedAllocationMemoryAllocateInfoNV::image equal to an image handle created with identical creation parameters to image and memoryOffset must be zero

  • VUID-vkBindImageMemory-memory-02728
    If the value of VkExportMemoryAllocateInfo::handleTypes used to allocate memory is not 0, it must include at least one of the handles set in VkExternalMemoryImageCreateInfo::handleTypes when image was created

  • VUID-vkBindImageMemory-memory-02989
    If memory was created by a memory import operation, that is not VkImportAndroidHardwareBufferInfoANDROID with a non-NULL buffer value, the external handle type of the imported memory must also have been set in VkExternalMemoryImageCreateInfo::handleTypes when image was created

  • VUID-vkBindImageMemory-memory-02990
    If memory was created with the VkImportAndroidHardwareBufferInfoANDROID memory import operation with a non-NULL buffer value, VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID must also have been set in VkExternalMemoryImageCreateInfo::handleTypes when image was created

  • VUID-vkBindImageMemory-image-01608
    image must not have been created with the VK_IMAGE_CREATE_DISJOINT_BIT set

  • VUID-vkBindImageMemory-memory-01047
    memory must have been allocated using one of the memory types allowed in the memoryTypeBits member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with image

  • VUID-vkBindImageMemory-memoryOffset-01048
    memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with image

  • VUID-vkBindImageMemory-size-01049
    The difference of the size of memory and memoryOffset must be greater than or equal to the size member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with the same image

  • VUID-vkBindImageMemory-image-06392
    If image was created with VkBufferCollectionImageCreateInfoFUCHSIA chained to VkImageCreateInfo::pNext, memory must be allocated with a VkImportMemoryBufferCollectionFUCHSIA chained to VkMemoryAllocateInfo::pNext

Valid Usage (Implicit)

  • VUID-vkBindImageMemory-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkBindImageMemory-image-parameter
    image must be a valid VkImage handle

  • VUID-vkBindImageMemory-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-vkBindImageMemory-image-parent
    image must have been created, allocated, or retrieved from device

  • VUID-vkBindImageMemory-memory-parent
    memory must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to image must be externally synchronized

Return Codes
On success, this command returns

  • VK_SUCCESS

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_VERSION_1_0, VkDevice, VkDeviceMemory, VkDeviceSize, VkImage

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