C Specification

To allocate memory objects, call:

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 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.

Description

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.
Valid Usage

  • The number of currently valid memory objects, allocated from device, must be less than VkPhysicalDeviceLimits::maxMemoryAllocationCount

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • pAllocateInfo must be a pointer to a valid VkMemoryAllocateInfo structure

  • If pAllocator is not NULL, pAllocator must be a pointer to a valid VkAllocationCallbacks structure

  • pMemory must be a pointer to a VkDeviceMemory handle

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

  • VK_ERROR_TOO_MANY_OBJECTS

See Also

VkAllocationCallbacks, VkDevice, VkDeviceMemory, VkMemoryAllocateInfo

Document Notes

For more information, see the Vulkan Specification at URL

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

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

Copyright

Copyright (c) 2014-2017 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.