vkAllocateMemory(3)

# vkAllocateMemory(3) Manual Page

## Name

vkAllocateMemory - Allocate device memory

## 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 a 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 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 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. If a call to vkAllocateMemory would cause the total number of allocations to exceed these limits, such a call will fail and must return `VK_ERROR_TOO_MANY_OBJECTS`. The `maxMemoryAllocationCount` feature describes the number of allocations that can exist simultaneously before encountering these internal limits.

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 `https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_AMD_memory_overallocation_behavior` extension.

Valid Usage

- `pAllocateInfo`->allocationSize must be less than or equal to VkPhysicalDeviceMemoryProperties::`memoryHeaps`[memindex].size where `memindex` = VkPhysicalDeviceMemoryProperties::`memoryTypes`[pAllocateInfo->memoryTypeIndex].heapIndex as returned by vkGetPhysicalDeviceMemoryProperties for the VkPhysicalDevice that `device` was created from.

- `pAllocateInfo`->memoryTypeIndex must be less than VkPhysicalDeviceMemoryProperties::`memoryTypeCount` as returned by vkGetPhysicalDeviceMemoryProperties for the VkPhysicalDevice that `device` was created from.

- If the `deviceCoherentMemory` feature is not enabled, `pAllocateInfo`->memoryTypeIndex must not identify a memory type supporting `VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD`

Valid Usage (Implicit)

- `device` must be a valid VkDevice handle

- `pAllocateInfo` must be a valid pointer to a valid VkMemoryAllocateInfo structure

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

- `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_TOO_MANY_OBJECTS`

  - `VK_ERROR_INVALID_EXTERNAL_HANDLE`

  - `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR`

## See Also

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 (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.