157 lines
7.2 KiB
Plaintext
157 lines
7.2 KiB
Plaintext
// 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::../api/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[]
|
|
|