Vulkan-Docs/doc/specs/vulkan/man/VkPhysicalDeviceMemoryProperties.txt

// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

VkPhysicalDeviceMemoryProperties(3)
===================================

Name
----
VkPhysicalDeviceMemoryProperties - Structure specifying physical device memory properties

C Specification
---------------

// refBegin VkPhysicalDeviceMemoryProperties - Structure specifying physical device memory properties

The sname:VkPhysicalDeviceMemoryProperties structure is defined as:

include::../structs/VkPhysicalDeviceMemoryProperties.txt[]


Members
-------

  * pname:memoryTypeCount is the number of valid elements in the
    pname:pMemoryRanges array.
  * pname:memoryTypes is an array of slink:VkMemoryType structures
    describing the _memory types_ that can: be used to access memory
    allocated from the heaps specified by pname:memoryHeaps.
  * pname:memoryHeapCount is the number of valid elements in the
    pname:pMemoryRanges array.
  * pname:memoryHeaps is an array of slink:VkMemoryHeap structures
    describing the _memory heaps_ from which memory can: be allocated.


Description
-----------

The sname: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 pname:memoryHeapCount and is less
than or equal to ename:VK_MAX_MEMORY_HEAPS. Each heap is described by an
element of the pname:memoryHeaps array, as a sname:VkMemoryHeap structure.
The number of memory types available across all memory heaps is given by
pname:memoryTypeCount and is less than or equal to
ename:VK_MAX_MEMORY_TYPES. Each memory type is described by an element of
the pname:memoryTypes array, as a sname:VkMemoryType structure.

At least one heap must: include ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT in
slink:VkMemoryHeap::pname:flags. If there are multiple heaps that all have similar performance
characteristics, they may: all include ename: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 flink:vkGetPhysicalDeviceMemoryProperties must:
have its pname:propertyFlags set to one of the following values:

  * 0
  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT
  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT
  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT

There must: be at least one memory type with both the
ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT and
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bits set in its pname:propertyFlags.
There must: be at least one memory type with the
ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set in its pname: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 latexmath:[$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
pname:memoryTypeIndex than Y if latexmath:[$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:

[source,{basebackend@docbook:c++:cpp}]
---------------------------------------------------
// 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
code: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 code: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".

include::../validity/structs/VkPhysicalDeviceMemoryProperties.txt[]


See Also
--------

slink:VkMemoryHeap, slink:VkMemoryType, flink:vkGetPhysicalDeviceMemoryProperties


Document Notes
--------------

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkPhysicalDeviceMemoryProperties

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

include::footer.txt[]