C Specification

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

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
  • image must not have been created with the VK_IMAGE_CREATE_DISJOINT_BIT set.

  • image must not already be backed by a memory object

  • image must not have been created with any sparse memory binding flags

  • memoryOffset must be less than the size of memory

  • 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

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

  • The size member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with image must be less than or equal to the size of memory minus memoryOffset

  • 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

  • If the VkMemoryAllocateInfo provided when memory was allocated included an instance of VkMemoryDedicatedAllocateInfo in its pNext chain, and VkMemoryDedicatedAllocateInfo::image was not VK_NULL_HANDLE, then image must equal VkMemoryDedicatedAllocateInfo::image and memoryOffset must be zero.

  • 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

  • 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

  • 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

Valid Usage (Implicit)
  • device must be a valid VkDevice handle

  • image must be a valid VkImage handle

  • memory must be a valid VkDeviceMemory handle

  • image must have been created, allocated, or retrieved from device

  • 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

VkDevice, VkDeviceMemory, VkDeviceSize, VkImage

Document Notes

For more information, see the Vulkan Specification at URL

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

Copyright (c) 2014-2018 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.