## 10.2. Device Memory

Device memory is memory that is visible to the device, for example the contents of opaque images that can be natively used by the device, or uniform buffer objects that reside in on-device memory.

Memory properties of a physical device describe the memory heaps and memory types available.

To query memory properties, call:

    void vkGetPhysicalDeviceMemoryProperties(
        VkPhysicalDevice                            physicalDevice,
        VkPhysicalDeviceMemoryProperties*           pMemoryProperties);

- `physicalDevice` is the handle to the device to query.
- `pMemoryProperties` points to an instance of `VkPhysicalDeviceMemoryProperties` structure in which the properties are returned.

The `VkPhysicalDeviceMemoryProperties` structure is defined as:

    typedef struct VkPhysicalDeviceMemoryProperties {
        uint32_t        memoryTypeCount;
        VkMemoryType    memoryTypes[VK_MAX_MEMORY_TYPES];
        uint32_t        memoryHeapCount;
        VkMemoryHeap    memoryHeaps[VK_MAX_MEMORY_HEAPS];
    } VkPhysicalDeviceMemoryProperties;

- `memoryTypeCount` is the number of valid elements in the `pMemoryRanges` array.
- `memoryTypes` is an array of `VkMemoryType` structures describing the memory types that can be used to access memory allocated from the heaps specified by `memoryHeaps`.
- `memoryHeapCount` is the number of valid elements in the `pMemoryRanges` array.
- `memoryHeaps` is an array of `VkMemoryHeap` structures describing the memory heaps from which memory can be allocated.

The `VkPhysicalDeviceMemoryProperties` structure describes a number of memory heaps as well as a number of memory types that can be used to access memory allocated in those heaps. Each heap describes a memory resource of a particular size, and each memory type describes a set of memory properties (e.g. host cached vs uncached) that can be used with a given memory heap. Allocations using a particular memory type will consume resources from the heap indicated by that memory type’s heap index. More than one memory type may share each heap, and the heaps and memory types provide a mechanism to advertise an accurate size of the physical memory resources while allowing the memory to be used with a variety of different properties.

The number of memory heaps is given by `memoryHeapCount` and is less than or equal to `VK_MAX_MEMORY_HEAPS`. Each heap is described by an element of the `memoryHeaps` array, as a `VkMemoryHeap` structure. The number of memory types available across all memory heaps is given by `memoryTypeCount` and is less than or equal to `VK_MAX_MEMORY_TYPES`. Each memory type is described by an element of the `memoryTypes` array, as a `VkMemoryType` structure.

At least one heap must include `VK_MEMORY_HEAP_DEVICE_LOCAL_BIT` in `VkMemoryHeap`::`flags`. If there are multiple heaps that all have similar performance characteristics, they may all include `VK_MEMORY_HEAP_DEVICE_LOCAL_BIT`. In a unified memory architecture (UMA) system, there is often only a single memory heap which is considered to be equally “local” to the host and to the device, and such an implementation must advertise the heap as device-local.

Each memory type returned by `vkGetPhysicalDeviceMemoryProperties` must have its `propertyFlags` set to one of the following values:

- 0
- `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` | `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT`
- `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` | `VK_MEMORY_PROPERTY_HOST_CACHED_BIT`
- `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` | `VK_MEMORY_PROPERTY_HOST_CACHED_BIT` | `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT`
- `VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT`
- `VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT` | `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` | `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT`
- `VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT` | `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` | `VK_MEMORY_PROPERTY_HOST_CACHED_BIT`
- `VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT` | `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` | `VK_MEMORY_PROPERTY_HOST_CACHED_BIT` | `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT`
- `VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT` | `VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT`

There must be at least one memory type with both the `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` and `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT` bits set in its `propertyFlags`. There must be at least one memory type with the `VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT` bit set in its `propertyFlags`.

The memory types are sorted according to a preorder which serves to aid in easily selecting an appropriate memory type. Given two memory types X and Y, the preorder defines $X \leq Y$ if:

- the memory property bits set for X are a strict subset of the memory property bits set for Y. Or,
- the memory property bits set for X are the same as the memory property bits set for Y, and X uses a memory heap with greater or equal performance (as determined in an implementation-specific manner).

Memory types are ordered in the list such that X is assigned a lesser `memoryTypeIndex` than Y if $X \leq Y \land \neg(Y \leq X)$ according to the preorder. Note that the list of all allowed memory property flag combinations above satisfies this preorder, but other orders would as well. The goal of this ordering is to enable applications to use a simple search loop in selecting the proper memory type, along the lines of:

    // Find a memory type in "memoryTypeBits" that includes all of "properties"
    int32_t FindProperties(uint32_t memoryTypeBits, VkMemoryPropertyFlags properties)
    {
        for (int32_t i = 0; i < memoryTypeCount; ++i)
        {
            if ((memoryTypeBits & (1 << i)) &&
                ((memoryTypes[i].propertyFlags & properties) == properties))
                return i;
        }
        return -1;
    }

    // Try to find an optimal memory type, or if it does not exist
    // find any compatible memory type
    VkMemoryRequirements memoryRequirements;
    vkGetImageMemoryRequirements(device, image, &memoryRequirements);
    int32_t memoryType = FindProperties(memoryRequirements.memoryTypeBits, optimalProperties);
    if (memoryType == -1)
        memoryType = FindProperties(memoryRequirements.memoryTypeBits, requiredProperties);

The loop will find the first supported memory type that has all bits requested in `properties` set. If there is no exact match, it will find a closest match (i.e. a memory type with the fewest additional bits set), which has some additional bits set but which are not detrimental to the behaviors requested by `properties`. The application can first search for the optimal properties, e.g. a memory type that is device-local or supports coherent cached accesses, as appropriate for the intended usage, and if such a memory type is not present can fallback to searching for a less optimal but guaranteed set of properties such as "0" or "host-visible and coherent".

The `VkMemoryHeap` structure is defined as:

    typedef struct VkMemoryHeap {
        VkDeviceSize         size;
        VkMemoryHeapFlags    flags;
    } VkMemoryHeap;

- `size` is the total memory size in bytes in the heap.

- `flags` is a bitmask of attribute flags for the heap. The bits specified in `flags` are:

      typedef enum VkMemoryHeapFlagBits {
          VK_MEMORY_HEAP_DEVICE_LOCAL_BIT = 0x00000001,
      } VkMemoryHeapFlagBits;

  - if `flags` contains `VK_MEMORY_HEAP_DEVICE_LOCAL_BIT`, it means the heap corresponds to device local memory. Device local memory may have different performance characteristics than host local memory, and may support different memory property flags.

The `VkMemoryType` structure is defined as:

    typedef struct VkMemoryType {
        VkMemoryPropertyFlags    propertyFlags;
        uint32_t                 heapIndex;
    } VkMemoryType;

- `heapIndex` describes which memory heap this memory type corresponds to, and must be less than `memoryHeapCount` from the `VkPhysicalDeviceMemoryProperties` structure.

- `propertyFlags` is a bitmask of properties for this memory type. The bits specified in `propertyFlags` are:

      typedef enum VkMemoryPropertyFlagBits {
          VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT = 0x00000001,
          VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT = 0x00000002,
          VK_MEMORY_PROPERTY_HOST_COHERENT_BIT = 0x00000004,
          VK_MEMORY_PROPERTY_HOST_CACHED_BIT = 0x00000008,
          VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT = 0x00000010,
      } VkMemoryPropertyFlagBits;

  - if `propertyFlags` has the `VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT` bit set, memory allocated with this type is the most efficient for device access. This property will only be set for memory types belonging to heaps with the `VK_MEMORY_HEAP_DEVICE_LOCAL_BIT` set.
  - if `propertyFlags` has the `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` bit set, memory allocated with this type can be mapped using `vkMapMemory` so that it can be accessed on the host.
  - if `propertyFlags` has the `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT` bit set, host cache management commands `vkFlushMappedMemoryRanges` and `vkInvalidateMappedMemoryRanges` are not needed to make host writes visible to the device or device writes visible to the host, respectively.
  - if `propertyFlags` has the `VK_MEMORY_PROPERTY_HOST_CACHED_BIT` bit set, memory allocated with this type is cached on the host. Host memory accesses to uncached memory are slower than to cached memory, however uncached memory is always host coherent.
  - if `propertyFlags` has the `VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT` bit set, the memory type only allows device access to the memory. Memory types must not have both `VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT` and `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` set. Additionally, the object’s backing memory may be provided by the implementation lazily as specified in Lazily Allocated Memory.

A Vulkan device operates on data in device memory via memory objects that are represented in the API by a `VkDeviceMemory` handle.

Memory objects are represented by `VkDeviceMemory` handles:

    VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDeviceMemory)

To allocate memory objects, call:

    VkResult vkAllocateMemory(
        VkDevice                                    device,
        const VkMemoryAllocateInfo*                 pAllocateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkDeviceMemory*                             pMemory);

- `device` is the logical device that owns the memory.
- `pAllocateInfo` is a pointer to an instance of the `VkMemoryAllocateInfo` structure describing parameters of the allocation. A successful returned allocation must use the requested parameters — no substitution is permitted by the implementation.
- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.
- `pMemory` is a pointer to a `VkDeviceMemory` handle in which information about the allocated memory is returned.

Allocations returned by `vkAllocateMemory` are guaranteed to meet any alignment requirement by the implementation. For example, if an implementation requires 128 byte alignment for images and 64 byte alignment for buffers, the device memory returned through this mechanism would be 128-byte aligned. This ensures that applications can correctly suballocate objects of different types (with potentially different alignment requirements) in the same memory object.

When memory is allocated, its contents are undefined.

There is an implementation-dependent maximum number of memory allocations which can be simultaneously created on a device. This is specified by the `maxMemoryAllocationCount` member of the `VkPhysicalDeviceLimits` structure. If `maxMemoryAllocationCount` is exceeded, `vkAllocateMemory` will return `VK_ERROR_TOO_MANY_OBJECTS`.

| Note
Some platforms may have a limit on the maximum size of a single allocation. For example, certain systems may fail to create allocations with a size greater than or equal to 4GB. Such a limit is implementation-dependent, and if such a failure occurs then the error `VK_ERROR_OUT_OF_DEVICE_MEMORY` should be returned.

The `VkMemoryAllocateInfo` structure is defined as:

    typedef struct VkMemoryAllocateInfo {
        VkStructureType    sType;
        const void*        pNext;
        VkDeviceSize       allocationSize;
        uint32_t           memoryTypeIndex;
    } VkMemoryAllocateInfo;

- `sType` is the type of this structure.
- `pNext` is `NULL` or a pointer to an extension-specific structure.
- `allocationSize` is the size of the allocation in bytes
- `memoryTypeIndex` is the memory type index, which selects the properties of the memory to be allocated, as well as the heap the memory will come from.

To free a memory object, call:

    void vkFreeMemory(
        VkDevice                                    device,
        VkDeviceMemory                              memory,
        const VkAllocationCallbacks*                pAllocator);

- `device` is the logical device that owns the memory.
- `memory` is the `VkDeviceMemory` object to be freed.
- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

Before freeing a memory object, an application must ensure the memory object is no longer in use by the device—for example by command buffers queued for execution. The memory can remain bound to images or buffers at the time the memory object is freed, but any further use of them (on host or device) for anything other than destroying those objects will result in undefined behavior. If there are still any bound images or buffers, the memory may not be immediately released by the implementation, but must be released by the time all bound images and buffers have been destroyed. Once memory is released, it is returned to the heap from which it was allocated.

How memory objects are bound to Images and Buffers is described in detail in the Resource Memory Association section.

If a memory object is mapped at the time it is freed, it is implicitly unmapped.

### 10.2.1. Host Access to Device Memory Objects

Memory objects created with `vkAllocateMemory` are not directly host accessible.

Memory objects created with the memory property `VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` are considered mappable. Memory objects must be mappable in order to be successfully mapped on the host.

To retrieve a host virtual address pointer to a region of a mappable memory object, call:

    VkResult vkMapMemory(
        VkDevice                                    device,
        VkDeviceMemory                              memory,
        VkDeviceSize                                offset,
        VkDeviceSize                                size,
        VkMemoryMapFlags                            flags,
        void**                                      ppData);

- `device` is the logical device that owns the memory.
- `memory` is the `VkDeviceMemory` object to be mapped.
- `offset` is a zero-based byte offset from the beginning of the memory object.
- `size` is the size of the memory range to map, or `VK_WHOLE_SIZE` to map from `offset` to the end of the allocation.
- `flags` is reserved for future use.
- `ppData` points to a pointer in which is returned a host-accessible pointer to the beginning of the mapped range. This pointer minus `offset` must be aligned to at least `VkPhysicalDeviceLimits`::`minMemoryMapAlignment`.

It is an application error to call `vkMapMemory` on a memory object that is already mapped.

`vkMapMemory` does not check whether the device memory is currently in use before returning the host-accessible pointer. The application must guarantee that any previously submitted command that writes to this range has completed before the host reads from or writes to that range, and that any previously submitted command that reads from that range has completed before the host writes to that region (see here for details on fulfilling such a guarantee). If the device memory was allocated without the `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT` set, these guarantees must be made for an extended range: the application must round down the start of the range to the nearest multiple of `VkPhysicalDeviceLimits`::`nonCoherentAtomSize`, and round the end of the range up to the nearest multiple of `VkPhysicalDeviceLimits`::`nonCoherentAtomSize`.

While a range of device memory is mapped for host access, the application is responsible for synchronizing both device and host access to that memory range.

| Note
It is important for the application developer to become meticulously familiar with all of the mechanisms described in the chapter on Synchronization and Cache Control as they are crucial to maintaining memory access ordering.

Two commands are provided to enable applications to work with non-coherent memory allocations: `vkFlushMappedMemoryRanges` and `vkInvalidateMappedMemoryRanges`.

| Note
If the memory object was created with the `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT` set, `vkFlushMappedMemoryRanges` and `vkInvalidateMappedMemoryRanges` are unnecessary and may have performance cost.

To flush ranges of non-coherent memory from the host caches, call:

    VkResult vkFlushMappedMemoryRanges(
        VkDevice                                    device,
        uint32_t                                    memoryRangeCount,
        const VkMappedMemoryRange*                  pMemoryRanges);

- `device` is the logical device that owns the memory ranges.
- `memoryRangeCount` is the length of the `pMemoryRanges` array.
- `pMemoryRanges` is a pointer to an array of `VkMappedMemoryRange` structures describing the memory ranges to flush.

`vkFlushMappedMemoryRanges` must be used to guarantee that host writes to non-coherent memory are visible to the device. It must be called after the host writes to non-coherent memory have completed and before command buffers that will read or write any of those memory locations are submitted to a queue.

To invalidate ranges of non-coherent memory from the host caches, call:

    VkResult vkInvalidateMappedMemoryRanges(
        VkDevice                                    device,
        uint32_t                                    memoryRangeCount,
        const VkMappedMemoryRange*                  pMemoryRanges);

- `device` is the logical device that owns the memory ranges.
- `memoryRangeCount` is the length of the `pMemoryRanges` array.
- `pMemoryRanges` is a pointer to an array of `VkMappedMemoryRange` structures describing the memory ranges to invalidate.

`vkInvalidateMappedMemoryRanges` must be used to guarantee that device writes to non-coherent memory are visible to the host. It must be called after command buffers that execute and flush (via memory barriers) the device writes have completed, and before the host will read or write any of those locations. If a range of non-coherent memory is written by the host and then invalidated without first being flushed, its contents are undefined.

The `VkMappedMemoryRange` structure is defined as:

    typedef struct VkMappedMemoryRange {
        VkStructureType    sType;
        const void*        pNext;
        VkDeviceMemory     memory;
        VkDeviceSize       offset;
        VkDeviceSize       size;
    } VkMappedMemoryRange;

- `sType` is the type of this structure.
- `pNext` is `NULL` or a pointer to an extension-specific structure.
- `memory` is the memory object to which this range belongs.
- `offset` is the zero-based byte offset from the beginning of the memory object.
- `size` is either the size of range, or `VK_WHOLE_SIZE` to affect the range from `offset` to the end of the current mapping of the allocation.

| editing-note
TODO (Tobias) - There’s a circular section reference between this next section and the synchronization section. The information is all covered by both places, but it seems a bit weird to have them reference each other. Not sure how to resolve it.

Host-visible memory types that advertise the `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT` property still require memory barriers between host and device in order to be coherent, but do not require additional cache management operations to achieve coherency. For host writes to be seen by subsequent command buffer operations, a pipeline barrier from a source of `VK_ACCESS_HOST_WRITE_BIT` and `VK_PIPELINE_STAGE_HOST_BIT` to a destination of the relevant device pipeline stages and access types must be performed. Note that such a barrier is performed implicitly upon each command buffer submission, so an explicit barrier is only rarely needed (e.g. if a command buffer waits upon an event signaled by the host, where the host wrote some data after submission). For device writes to be seen by subsequent host reads, a pipeline barrier is required to make the writes visible.

To unmap a memory object once host access to it is no longer needed by the application, call:

    void vkUnmapMemory(
        VkDevice                                    device,
        VkDeviceMemory                              memory);

- `device` is the logical device that owns the memory.
- `memory` is the memory object to be unmapped.

### 10.2.2. Lazily Allocated Memory

If the memory object is allocated from a heap with the `VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT` bit set, that object’s backing memory may be provided by the implementation lazily. The actual committed size of the memory may initially be as small as zero (or as large as the requested size), and monotonically increases as additional memory is needed.

A memory type with this flag set is only allowed to be bound to a `VkImage` whose usage flags include `VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT`.

| Note
Using lazily allocated memory objects for framebuffer attachments that are not needed once a render pass instance has completed may allow some implementations to never allocate memory for such attachments.

To determine the amount of lazily-allocated memory that is currently committed for a memory object, call:

    void vkGetDeviceMemoryCommitment(
        VkDevice                                    device,
        VkDeviceMemory                              memory,
        VkDeviceSize*                               pCommittedMemoryInBytes);

- `device` is the logical device that owns the memory.
- `memory` is the memory object being queried.
- `pCommittedMemoryInBytes` is a pointer to a `VkDeviceSize` value in which the number of bytes currently committed is returned, on success.

The implementation may update the commitment at any time, and the value returned by this query may be out of date.

The implementation guarantees to allocate any committed memory from the heapIndex indicated by the memory type that the memory object was created with.