vkBindImageMemory(3)

# vkBindImageMemory(3) Manual Page

## Name

vkBindImageMemory - Bind device memory to an image object

Loading… please wait.

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

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

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

SPDX-License-Identifier: CC-BY-4.0