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

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 VK_MEMORY_PROPERTY_PROTECTED_BIT property) than for non-protected memory allocations. These limits can be system-wide, and depend on a variety of factors outside of the Vulkan implementation, so they cannot be queried in Vulkan. Applications should use as few allocations as possible from such memory types by suballocating aggressively, and be prepared for allocation failure even when there is apparently plenty of capacity remaining in the memory heap. As a guideline, the Vulkan conformance test suite requires that at least 80 minimum-size allocations can exist concurrently when no other uses of protected memory are active in the system.

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.

If VkPhysicalDeviceVulkanSC10Properties::deviceNoDynamicHostAllocations is VK_TRUE, vkAllocateMemory must not return VK_ERROR_OUT_OF_HOST_MEMORY.

Valid Usage

  • VUID-vkAllocateMemory-device-05068
    The number of device memory objects currently allocated from device plus 1 must be less than or equal to the total number of device memory objects requested via VkDeviceObjectReservationCreateInfo::deviceMemoryRequestCount specified when device was created

Valid Usage (Implicit)

  • VUID-vkAllocateMemory-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkAllocateMemory-pAllocateInfo-parameter
    pAllocateInfo must be a valid pointer to a valid VkMemoryAllocateInfo structure

  • VUID-vkAllocateMemory-pAllocator-null
    pAllocator must be NULL

  • VUID-vkAllocateMemory-pMemory-parameter
    pMemory must be a valid 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_INVALID_EXTERNAL_HANDLE

See Also

VK_VERSION_1_0, VkAllocationCallbacks, VkDevice, VkDeviceMemory, VkMemoryAllocateInfo

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.

Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0