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

PFN_vkAllocationFunction(3)
===========================

Name
----
PFN_vkAllocationFunction - application-defined memory allocation function

C Specification
---------------

// refBegin PFN_vkAllocationFunction application-defined memory allocation function

The type of pname:pfnAllocation is:

include::../funcpointers/PFN_vkAllocationFunction.txt[]


Parameters
----------

  * pname:pUserData is the value specified for
    slink:VkAllocationCallbacks.pUserData in the allocator specified by the
    application.
  * pname:size is the size in bytes of the requested allocation.
  * pname:alignment is the requested alignment of the allocation in bytes
    and must: be a power of two.
  * pname:allocationScope is a elink:VkSystemAllocationScope value
    specifying the scope of the lifetime of the allocation, as described
    <<memory-host-allocation-scope,here>>.


Description
-----------

[[vkAllocationFunction_return_rules]]
If pname:pfnAllocation is unable to allocate the requested memory,
it must: return `NULL`. If the allocation was successful, it must: return a
valid pointer to memory allocation containing at least pname:size bytes, and
with the pointer value being a multiple of pname:alignment.

[NOTE]
.Note
====
Correct Vulkan operation cannot: be assumed if the application does not
follow these rules.

For example, pname:pfnAllocation (or pname:pfnReallocation) could cause
termination of running Vulkan instance(s) on a failed allocation for
debugging purposes, either directly or indirectly. In these circumstances,
it cannot: be assumed that any part of any affected VkInstance objects are
going to operate correctly (even flink:vkDestroyInstance), and the
application must: ensure it cleans up properly via other means (e.g.
process termination).
====

If pname:pfnAllocation returns `NULL`, and if the implementation is unable
to continue correct processing of the current command without the requested
allocation, it must: treat this as a run-time error, and generate
ename:VK_ERROR_OUT_OF_HOST_MEMORY at the appropriate time for the command
in which the condition was detected, as described in
<<fundamentals-errorcodes, Return Codes>>.

If the implementation is able to continue correct processing of the current
command without the requested allocation, then it may: do so, and must:
not generate ename:VK_ERROR_OUT_OF_HOST_MEMORY as a result of this failed
allocation.

// refEnd PFN_vkAllocationFunction VkAllocationCallbacks


See Also
--------

slink:VkAllocationCallbacks


Document Notes
--------------

For more information, see the Vulkan Specification at URL

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

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

include::footer.txt[]