C Specification
To allocate memory objects, call:
// Provided by VK_VERSION_1_0
VkResult vkAllocateMemory(
VkDevice device,
const VkMemoryAllocateInfo* pAllocateInfo,
const VkAllocationCallbacks* pAllocator,
VkDeviceMemory* pMemory);
Parameters
-
device
is the logical device that owns the memory. -
pAllocateInfo
is a pointer to a VkMemoryAllocateInfo structure describing parameters of the allocation. A successfully 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.
Description
Allocations returned by vkAllocateMemory
are guaranteed to meet any
alignment requirement of 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 with the following constraint:
-
The contents of unprotected memory must not be a function of the contents of data protected memory objects, even if those memory objects were previously freed.
Note
The contents of memory allocated by one application should not be a function of data from protected memory objects of another application, even if those memory objects were previously freed. |
The maximum number of valid memory allocations that can exist
simultaneously within a VkDevice may be restricted by implementation-
or platform-dependent limits.
The maxMemoryAllocationCount
feature describes the number of allocations that can exist simultaneously
before encountering these internal limits.
Note
For historical reasons, if |
Note
Many protected memory implementations involve complex hardware and system
software support, and often have additional and much lower limits on the
number of simultaneous protected memory allocations (from memory types with
the |
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
must be returned.
This limit is advertised in
VkPhysicalDeviceMaintenance3Properties::maxMemoryAllocationSize
.
The cumulative memory size allocated to a heap can be limited by the size
of the specified heap.
In such cases, allocated memory is tracked on a per-device and per-heap
basis.
Some platforms allow overallocation into other heaps.
The overallocation behavior can be specified through the
VK_AMD_memory_overallocation_behavior
extension.
If the
VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT::pageableDeviceLocalMemory
feature is enabled, memory allocations made from a heap that includes
VK_MEMORY_HEAP_DEVICE_LOCAL_BIT
in VkMemoryHeap::flags
may be transparently moved to host-local memory allowing multiple
applications to share device-local memory.
If there is no space left in device-local memory when this new allocation is
made, other allocations may be moved out transparently to make room.
The operating system will determine which allocations to move to
device-local memory or host-local memory based on platform-specific
criteria.
To help the operating system make good choices, the application should set
the appropriate memory priority with VkMemoryPriorityAllocateInfoEXT
and adjust it as necessary with vkSetDeviceMemoryPriorityEXT.
Higher priority allocations will moved to device-local memory first.
Memory allocations made on heaps without the
VK_MEMORY_HEAP_DEVICE_LOCAL_BIT
property will not be transparently
promoted to device-local memory by the operating system.
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.