mirror/VulkanMemoryAllocator
1
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git synced 2024-11-22 23:04:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add annotations for nullability and length

Browse Source 
These are only present on the declarations in the C API.

New macros
- `VMA_NULLABLE`
- `VMA_NOT_NULL`
- `VMA_NULLABLE_NON_DISPATCHABLE`
- `VMA_NOT_NULL_NON_DISPATCHABLE`
- `VMA_LEN_IF_NOT_NULL`

On clang `VMA_NOT_NULL` and `VMA_NULLABLE` are defined as `_Nonnull` and
`_Nullable`. Clang will use these annotations to generate diagnostics
when these functions or structs are incorrectly used.

`VMA_NULLABLE_NON_DISPATCHABLE` and `VMA_NOT_NULL_NON_DISPATCHABLE` are
not defined on platforms where Vulkan's non-dispatchable handles are not
pointers; on platforms where they are, these macros are defined to be
`VMA_NULLABLE` and `VMA_NOT_NULL` respectively.

`LEN_IF_NOT_NULL` is not defined for any compiler. It is included to
mirror the `len` attribute in the Vulkan XML spec in order to aid in
development of other language bindings for this library.

It was tempting to use C's array syntax (`foo(int len, int arr[len])`)to
specify lengths, however this is not possible to use with optional
pointers, nor is it possible to use inside structs. For the sake of
consistency only `VMA_LEN_IF_NOT_NULL` is used (additionally neither
clang not gcc generate warnings for function misuse when the array
length specifier is anything but an integer literal).

- Also correct a couple of typos
- Also add assert on ppName in vmaGetPoolName

Closes #114
This commit is contained in:
Joe Hermaszewski 2020-04-06 17:17:38 +08:00
parent f575c5070b
commit c6f8c86085
1 changed files with 258 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

459
src/vk_mem_alloc.h
View File

@ -1993,6 +1993,54 @@ available through VmaAllocatorCreateInfo::pRecordSettings.
#define VMA_CALL_POST #define VMA_CALL_POST
#endif #endif
// Define this macro to decorate pointers with an attribute specifying the
// length of the array they point to if they are not null.
//
// The length may be one of
// - The name of another parameter in the argument list where the pointer is declared
// - The name of another member in the struct where the pointer is declared
#ifndef VMA_LEN_IF_NOT_NULL
#define VMA_LEN_IF_NOT_NULL(len)
#endif
// The VMA_NULLABLE macro is defined to be _Nullable when compiling with Clang.
// see: https://clang.llvm.org/docs/AttributeReference.html#nullable
#ifndef VMA_NULLABLE
#ifdef __clang__
#define VMA_NULLABLE _Nullable
#else
#define VMA_NULLABLE
#endif
#endif
// The VMA_NOT_NULL macro is defined to be _Nonnull when compiling with Clang.
// see: https://clang.llvm.org/docs/AttributeReference.html#nonnull
#ifndef VMA_NOT_NULL
#ifdef __clang__
#define VMA_NOT_NULL _Nonnull
#else
#define VMA_NOT_NULL
#endif
#endif
// If non-dispatchable handles are represented as pointers then we can give
// then nullability annotations
#ifndef VMA_NOT_NULL_NON_DISPATCHABLE
#if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__) ) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
#define VMA_NOT_NULL_NON_DISPATCHABLE VMA_NOT_NULL
#else
#define VMA_NOT_NULL_NON_DISPATCHABLE
#endif
#endif
#ifndef VMA_NULLABLE_NON_DISPATCHABLE
#if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__) ) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
#define VMA_NULLABLE_NON_DISPATCHABLE VMA_NULLABLE
#else
#define VMA_NULLABLE_NON_DISPATCHABLE
#endif
#endif
/** \struct VmaAllocator /** \struct VmaAllocator
\brief Represents main object of this library initialized. \brief Represents main object of this library initialized.
@ -2006,18 +2054,18 @@ VK_DEFINE_HANDLE(VmaAllocator)
/// Callback function called after successful vkAllocateMemory. /// Callback function called after successful vkAllocateMemory.
typedef void (VKAPI_PTR *PFN_vmaAllocateDeviceMemoryFunction)( typedef void (VKAPI_PTR *PFN_vmaAllocateDeviceMemoryFunction)(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
uint32_t memoryType, uint32_t memoryType,
VkDeviceMemory memory, VkDeviceMemory VMA_NOT_NULL_NON_DISPATCHABLE memory,
VkDeviceSize size, VkDeviceSize size,
void* pUserData); void* VMA_NULLABLE pUserData);
/// Callback function called before vkFreeMemory. /// Callback function called before vkFreeMemory.
typedef void (VKAPI_PTR *PFN_vmaFreeDeviceMemoryFunction)( typedef void (VKAPI_PTR *PFN_vmaFreeDeviceMemoryFunction)(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
uint32_t memoryType, uint32_t memoryType,
VkDeviceMemory memory, VkDeviceMemory VMA_NOT_NULL_NON_DISPATCHABLE memory,
VkDeviceSize size, VkDeviceSize size,
void* pUserData); void* VMA_NULLABLE pUserData);
/** \brief Set of callbacks that the library will call for `vkAllocateMemory` and `vkFreeMemory`. /** \brief Set of callbacks that the library will call for `vkAllocateMemory` and `vkFreeMemory`.
@ -2028,11 +2076,11 @@ Used in VmaAllocatorCreateInfo::pDeviceMemoryCallbacks.
*/ */
typedef struct VmaDeviceMemoryCallbacks { typedef struct VmaDeviceMemoryCallbacks {
/// Optional, can be null. /// Optional, can be null.
PFN_vmaAllocateDeviceMemoryFunction pfnAllocate; PFN_vmaAllocateDeviceMemoryFunction VMA_NULLABLE pfnAllocate;
/// Optional, can be null. /// Optional, can be null.
PFN_vmaFreeDeviceMemoryFunction pfnFree; PFN_vmaFreeDeviceMemoryFunction VMA_NULLABLE pfnFree;
/// Optional, can be null. /// Optional, can be null.
void* pUserData; void* VMA_NULLABLE pUserData;
} VmaDeviceMemoryCallbacks; } VmaDeviceMemoryCallbacks;
/// Flags for created #VmaAllocator. /// Flags for created #VmaAllocator.
@ -2140,33 +2188,33 @@ typedef VkFlags VmaAllocatorCreateFlags;
Used in VmaAllocatorCreateInfo::pVulkanFunctions. Used in VmaAllocatorCreateInfo::pVulkanFunctions.
*/ */
typedef struct VmaVulkanFunctions { typedef struct VmaVulkanFunctions {
PFN_vkGetPhysicalDeviceProperties vkGetPhysicalDeviceProperties; PFN_vkGetPhysicalDeviceProperties VMA_NOT_NULL vkGetPhysicalDeviceProperties;
PFN_vkGetPhysicalDeviceMemoryProperties vkGetPhysicalDeviceMemoryProperties; PFN_vkGetPhysicalDeviceMemoryProperties VMA_NOT_NULL vkGetPhysicalDeviceMemoryProperties;
PFN_vkAllocateMemory vkAllocateMemory; PFN_vkAllocateMemory VMA_NOT_NULL vkAllocateMemory;
PFN_vkFreeMemory vkFreeMemory; PFN_vkFreeMemory VMA_NOT_NULL vkFreeMemory;
PFN_vkMapMemory vkMapMemory; PFN_vkMapMemory VMA_NOT_NULL vkMapMemory;
PFN_vkUnmapMemory vkUnmapMemory; PFN_vkUnmapMemory VMA_NOT_NULL vkUnmapMemory;
PFN_vkFlushMappedMemoryRanges vkFlushMappedMemoryRanges; PFN_vkFlushMappedMemoryRanges VMA_NOT_NULL vkFlushMappedMemoryRanges;
PFN_vkInvalidateMappedMemoryRanges vkInvalidateMappedMemoryRanges; PFN_vkInvalidateMappedMemoryRanges VMA_NOT_NULL vkInvalidateMappedMemoryRanges;
PFN_vkBindBufferMemory vkBindBufferMemory; PFN_vkBindBufferMemory VMA_NOT_NULL vkBindBufferMemory;
PFN_vkBindImageMemory vkBindImageMemory; PFN_vkBindImageMemory VMA_NOT_NULL vkBindImageMemory;
PFN_vkGetBufferMemoryRequirements vkGetBufferMemoryRequirements; PFN_vkGetBufferMemoryRequirements VMA_NOT_NULL vkGetBufferMemoryRequirements;
PFN_vkGetImageMemoryRequirements vkGetImageMemoryRequirements; PFN_vkGetImageMemoryRequirements VMA_NOT_NULL vkGetImageMemoryRequirements;
PFN_vkCreateBuffer vkCreateBuffer; PFN_vkCreateBuffer VMA_NOT_NULL vkCreateBuffer;
PFN_vkDestroyBuffer vkDestroyBuffer; PFN_vkDestroyBuffer VMA_NOT_NULL vkDestroyBuffer;
PFN_vkCreateImage vkCreateImage; PFN_vkCreateImage VMA_NOT_NULL vkCreateImage;
PFN_vkDestroyImage vkDestroyImage; PFN_vkDestroyImage VMA_NOT_NULL vkDestroyImage;
PFN_vkCmdCopyBuffer vkCmdCopyBuffer; PFN_vkCmdCopyBuffer VMA_NOT_NULL vkCmdCopyBuffer;
#if VMA_DEDICATED_ALLOCATION || VMA_VULKAN_VERSION >= 1001000 #if VMA_DEDICATED_ALLOCATION || VMA_VULKAN_VERSION >= 1001000
PFN_vkGetBufferMemoryRequirements2KHR vkGetBufferMemoryRequirements2KHR; PFN_vkGetBufferMemoryRequirements2KHR VMA_NOT_NULL vkGetBufferMemoryRequirements2KHR;
PFN_vkGetImageMemoryRequirements2KHR vkGetImageMemoryRequirements2KHR; PFN_vkGetImageMemoryRequirements2KHR VMA_NOT_NULL vkGetImageMemoryRequirements2KHR;
#endif #endif
#if VMA_BIND_MEMORY2 || VMA_VULKAN_VERSION >= 1001000 #if VMA_BIND_MEMORY2 || VMA_VULKAN_VERSION >= 1001000
PFN_vkBindBufferMemory2KHR vkBindBufferMemory2KHR; PFN_vkBindBufferMemory2KHR VMA_NOT_NULL vkBindBufferMemory2KHR;
PFN_vkBindImageMemory2KHR vkBindImageMemory2KHR; PFN_vkBindImageMemory2KHR VMA_NOT_NULL vkBindImageMemory2KHR;
#endif #endif
#if VMA_MEMORY_BUDGET || VMA_VULKAN_VERSION >= 1001000 #if VMA_MEMORY_BUDGET || VMA_VULKAN_VERSION >= 1001000
PFN_vkGetPhysicalDeviceMemoryProperties2KHR vkGetPhysicalDeviceMemoryProperties2KHR; PFN_vkGetPhysicalDeviceMemoryProperties2KHR VMA_NOT_NULL vkGetPhysicalDeviceMemoryProperties2KHR;
#endif #endif
} VmaVulkanFunctions; } VmaVulkanFunctions;
@ -2195,7 +2243,7 @@ typedef struct VmaRecordSettings
It will be opened for the whole time #VmaAllocator object is alive. It will be opened for the whole time #VmaAllocator object is alive.
If opening this file fails, creation of the whole allocator object fails. If opening this file fails, creation of the whole allocator object fails.
*/ */
const char* pFilePath; const char* VMA_NOT_NULL pFilePath;
} VmaRecordSettings; } VmaRecordSettings;
/// Description of a Allocator to be created. /// Description of a Allocator to be created.
@ -2205,19 +2253,19 @@ typedef struct VmaAllocatorCreateInfo
VmaAllocatorCreateFlags flags; VmaAllocatorCreateFlags flags;
/// Vulkan physical device. /// Vulkan physical device.
/** It must be valid throughout whole lifetime of created allocator. */ /** It must be valid throughout whole lifetime of created allocator. */
VkPhysicalDevice physicalDevice; VkPhysicalDevice VMA_NOT_NULL physicalDevice;
/// Vulkan device. /// Vulkan device.
/** It must be valid throughout whole lifetime of created allocator. */ /** It must be valid throughout whole lifetime of created allocator. */
VkDevice device; VkDevice VMA_NOT_NULL device;
/// Preferred size of a single `VkDeviceMemory` block to be allocated from large heaps > 1 GiB. Optional. /// Preferred size of a single `VkDeviceMemory` block to be allocated from large heaps > 1 GiB. Optional.
/** Set to 0 to use default, which is currently 256 MiB. */ /** Set to 0 to use default, which is currently 256 MiB. */
VkDeviceSize preferredLargeHeapBlockSize; VkDeviceSize preferredLargeHeapBlockSize;
/// Custom CPU memory allocation callbacks. Optional. /// Custom CPU memory allocation callbacks. Optional.
/** Optional, can be null. When specified, will also be used for all CPU-side memory allocations. */ /** Optional, can be null. When specified, will also be used for all CPU-side memory allocations. */
const VkAllocationCallbacks* pAllocationCallbacks; const VkAllocationCallbacks* VMA_NULLABLE pAllocationCallbacks;
/// Informative callbacks for `vkAllocateMemory`, `vkFreeMemory`. Optional. /// Informative callbacks for `vkAllocateMemory`, `vkFreeMemory`. Optional.
/** Optional, can be null. */ /** Optional, can be null. */
const VmaDeviceMemoryCallbacks* pDeviceMemoryCallbacks; const VmaDeviceMemoryCallbacks* VMA_NULLABLE pDeviceMemoryCallbacks;
/** \brief Maximum number of additional frames that are in use at the same time as current frame. /** \brief Maximum number of additional frames that are in use at the same time as current frame.
This value is used only when you make allocations with This value is used only when you make allocations with
@ -2256,24 +2304,25 @@ typedef struct VmaAllocatorCreateInfo
blocks to system RAM. This driver behavior can also be controlled using blocks to system RAM. This driver behavior can also be controlled using
VK_AMD_memory_overallocation_behavior extension. VK_AMD_memory_overallocation_behavior extension.
*/ */
const VkDeviceSize* pHeapSizeLimit; const VkDeviceSize* VMA_NULLABLE pHeapSizeLimit;
/** \brief Pointers to Vulkan functions. Can be null. /** \brief Pointers to Vulkan functions. Can be null.
For details see [Pointers to Vulkan functions](@ref config_Vulkan_functions). For details see [Pointers to Vulkan functions](@ref config_Vulkan_functions).
*/ */
const VmaVulkanFunctions* pVulkanFunctions; const VmaVulkanFunctions* VMA_NULLABLE pVulkanFunctions;
/** \brief Parameters for recording of VMA calls. Can be null. /** \brief Parameters for recording of VMA calls. Can be null.
If not null, it enables recording of calls to VMA functions to a file. If not null, it enables recording of calls to VMA functions to a file.
If support for recording is not enabled using `VMA_RECORDING_ENABLED` macro, If support for recording is not enabled using `VMA_RECORDING_ENABLED` macro,
creation of the allocator object fails with `VK_ERROR_FEATURE_NOT_PRESENT`. creation of the allocator object fails with `VK_ERROR_FEATURE_NOT_PRESENT`.
*/ */
const VmaRecordSettings* pRecordSettings; const VmaRecordSettings* VMA_NULLABLE pRecordSettings;
/** \brief Handle to Vulkan instance object. /** \brief Handle to Vulkan instance object.
Starting from version 3.0.0 this member is no longer optional, it must be set! Starting from version 3.0.0 this member is no longer optional, it must be set!
*/ */
VkInstance instance; VkInstance VMA_NOT_NULL instance;
/** \brief Optional. The highest version of Vulkan that the application is designed to use. /** \brief Optional. The highest version of Vulkan that the application is designed to use.
It must be a value in the format as created by macro `VK_MAKE_VERSION` or a constant like: `VK_API_VERSION_1_1`, `VK_API_VERSION_1_0`. It must be a value in the format as created by macro `VK_MAKE_VERSION` or a constant like: `VK_API_VERSION_1_1`, `VK_API_VERSION_1_0`.
@ -2287,12 +2336,12 @@ typedef struct VmaAllocatorCreateInfo
/// Creates Allocator object. /// Creates Allocator object.
VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreateAllocator( VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreateAllocator(
const VmaAllocatorCreateInfo* pCreateInfo, const VmaAllocatorCreateInfo* VMA_NOT_NULL pCreateInfo,
VmaAllocator* pAllocator); VmaAllocator* VMA_NOT_NULL pAllocator);
/// Destroys allocator object. /// Destroys allocator object.
VMA_CALL_PRE void VMA_CALL_POST vmaDestroyAllocator( VMA_CALL_PRE void VMA_CALL_POST vmaDestroyAllocator(
VmaAllocator allocator); VmaAllocator VMA_NULLABLE allocator);
/** \brief Information about existing #VmaAllocator object. /** \brief Information about existing #VmaAllocator object.
*/ */
@ -2302,17 +2351,17 @@ typedef struct VmaAllocatorInfo
This is the same value as has been passed through VmaAllocatorCreateInfo::instance. This is the same value as has been passed through VmaAllocatorCreateInfo::instance.
*/ */
VkInstance instance; VkInstance VMA_NOT_NULL instance;
/** \brief Handle to Vulkan physical device object. /** \brief Handle to Vulkan physical device object.
This is the same value as has been passed through VmaAllocatorCreateInfo::physicalDevice. This is the same value as has been passed through VmaAllocatorCreateInfo::physicalDevice.
*/ */
VkPhysicalDevice physicalDevice; VkPhysicalDevice VMA_NOT_NULL physicalDevice;
/** \brief Handle to Vulkan device object. /** \brief Handle to Vulkan device object.
This is the same value as has been passed through VmaAllocatorCreateInfo::device. This is the same value as has been passed through VmaAllocatorCreateInfo::device.
*/ */
VkDevice device; VkDevice VMA_NOT_NULL device;
} VmaAllocatorInfo; } VmaAllocatorInfo;
/** \brief Returns information about existing #VmaAllocator object - handle to Vulkan device etc. /** \brief Returns information about existing #VmaAllocator object - handle to Vulkan device etc.
@ -2320,23 +2369,23 @@ typedef struct VmaAllocatorInfo
It might be useful if you want to keep just the #VmaAllocator handle and fetch other required handles to It might be useful if you want to keep just the #VmaAllocator handle and fetch other required handles to
`VkPhysicalDevice`, `VkDevice` etc. every time using this function. `VkPhysicalDevice`, `VkDevice` etc. every time using this function.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaGetAllocatorInfo(VmaAllocator allocator, VmaAllocatorInfo* pAllocatorInfo); VMA_CALL_PRE void VMA_CALL_POST vmaGetAllocatorInfo(VmaAllocator VMA_NOT_NULL allocator, VmaAllocatorInfo* VMA_NOT_NULL pAllocatorInfo);
/** /**
PhysicalDeviceProperties are fetched from physicalDevice by the allocator. PhysicalDeviceProperties are fetched from physicalDevice by the allocator.
You can access it here, without fetching it again on your own. You can access it here, without fetching it again on your own.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaGetPhysicalDeviceProperties( VMA_CALL_PRE void VMA_CALL_POST vmaGetPhysicalDeviceProperties(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VkPhysicalDeviceProperties** ppPhysicalDeviceProperties); const VkPhysicalDeviceProperties** VMA_NOT_NULL ppPhysicalDeviceProperties);
/** /**
PhysicalDeviceMemoryProperties are fetched from physicalDevice by the allocator. PhysicalDeviceMemoryProperties are fetched from physicalDevice by the allocator.
You can access it here, without fetching it again on your own. You can access it here, without fetching it again on your own.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaGetMemoryProperties( VMA_CALL_PRE void VMA_CALL_POST vmaGetMemoryProperties(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VkPhysicalDeviceMemoryProperties** ppPhysicalDeviceMemoryProperties); const VkPhysicalDeviceMemoryProperties** VMA_NOT_NULL ppPhysicalDeviceMemoryProperties);
/** /**
\brief Given Memory Type Index, returns Property Flags of this memory type. \brief Given Memory Type Index, returns Property Flags of this memory type.
@ -2345,9 +2394,9 @@ This is just a convenience function. Same information can be obtained using
vmaGetMemoryProperties(). vmaGetMemoryProperties().
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaGetMemoryTypeProperties( VMA_CALL_PRE void VMA_CALL_POST vmaGetMemoryTypeProperties(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
uint32_t memoryTypeIndex, uint32_t memoryTypeIndex,
VkMemoryPropertyFlags* pFlags); VkMemoryPropertyFlags* VMA_NOT_NULL pFlags);
/** \brief Sets index of the current frame. /** \brief Sets index of the current frame.
@ -2358,7 +2407,7 @@ when a new frame begins. Allocations queried using vmaGetAllocationInfo() cannot
become lost in the current frame. become lost in the current frame.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaSetCurrentFrameIndex( VMA_CALL_PRE void VMA_CALL_POST vmaSetCurrentFrameIndex(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
uint32_t frameIndex); uint32_t frameIndex);
/** \brief Calculated statistics of memory usage in entire allocator. /** \brief Calculated statistics of memory usage in entire allocator.
@ -2397,8 +2446,8 @@ Note that when using allocator from multiple threads, returned information may i
become outdated. become outdated.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaCalculateStats( VMA_CALL_PRE void VMA_CALL_POST vmaCalculateStats(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaStats* pStats); VmaStats* VMA_NOT_NULL pStats);
/** \brief Statistics of current memory usage and available budget, in bytes, for specific memory heap. /** \brief Statistics of current memory usage and available budget, in bytes, for specific memory heap.
*/ */
@ -2452,8 +2501,8 @@ Note that when using allocator from multiple threads, returned information may i
become outdated. become outdated.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaGetBudget( VMA_CALL_PRE void VMA_CALL_POST vmaGetBudget(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaBudget* pBudget); VmaBudget* VMA_NOT_NULL pBudget);
#ifndef VMA_STATS_STRING_ENABLED #ifndef VMA_STATS_STRING_ENABLED
#define VMA_STATS_STRING_ENABLED 1 #define VMA_STATS_STRING_ENABLED 1
@ -2465,13 +2514,13 @@ VMA_CALL_PRE void VMA_CALL_POST vmaGetBudget(
/** @param[out] ppStatsString Must be freed using vmaFreeStatsString() function. /** @param[out] ppStatsString Must be freed using vmaFreeStatsString() function.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaBuildStatsString( VMA_CALL_PRE void VMA_CALL_POST vmaBuildStatsString(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
char** ppStatsString, char** VMA_NOT_NULL ppStatsString,
VkBool32 detailedMap); VkBool32 detailedMap);
VMA_CALL_PRE void VMA_CALL_POST vmaFreeStatsString( VMA_CALL_PRE void VMA_CALL_POST vmaFreeStatsString(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
char* pStatsString); char* VMA_NULLABLE pStatsString);
#endif // #if VMA_STATS_STRING_ENABLED #endif // #if VMA_STATS_STRING_ENABLED
@ -2697,14 +2746,14 @@ typedef struct VmaAllocationCreateInfo
Leave `VK_NULL_HANDLE` to allocate from default pool. If not null, members: Leave `VK_NULL_HANDLE` to allocate from default pool. If not null, members:
`usage`, `requiredFlags`, `preferredFlags`, `memoryTypeBits` are ignored. `usage`, `requiredFlags`, `preferredFlags`, `memoryTypeBits` are ignored.
*/ */
VmaPool pool; VmaPool VMA_NULLABLE pool;
/** \brief Custom general-purpose pointer that will be stored in #VmaAllocation, can be read as VmaAllocationInfo::pUserData and changed using vmaSetAllocationUserData(). /** \brief Custom general-purpose pointer that will be stored in #VmaAllocation, can be read as VmaAllocationInfo::pUserData and changed using vmaSetAllocationUserData().
If #VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT is used, it must be either If #VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT is used, it must be either
null or pointer to a null-terminated string. The string will be then copied to null or pointer to a null-terminated string. The string will be then copied to
internal buffer, so it doesn't need to be valid after allocation call. internal buffer, so it doesn't need to be valid after allocation call.
*/ */
void* pUserData; void* VMA_NULLABLE pUserData;
} VmaAllocationCreateInfo; } VmaAllocationCreateInfo;
/** /**
@ -2724,10 +2773,10 @@ type of resource you want to use it for. Please check parameters of your
resource, like image layout (OPTIMAL versus LINEAR) or mip level count. resource, like image layout (OPTIMAL versus LINEAR) or mip level count.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaFindMemoryTypeIndex( VMA_CALL_PRE VkResult VMA_CALL_POST vmaFindMemoryTypeIndex(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
uint32_t memoryTypeBits, uint32_t memoryTypeBits,
const VmaAllocationCreateInfo* pAllocationCreateInfo, const VmaAllocationCreateInfo* VMA_NOT_NULL pAllocationCreateInfo,
uint32_t* pMemoryTypeIndex); uint32_t* VMA_NOT_NULL pMemoryTypeIndex);
/** /**
\brief Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo. \brief Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.
@ -2742,10 +2791,10 @@ It is just a convenience function, equivalent to calling:
- `vkDestroyBuffer` - `vkDestroyBuffer`
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaFindMemoryTypeIndexForBufferInfo( VMA_CALL_PRE VkResult VMA_CALL_POST vmaFindMemoryTypeIndexForBufferInfo(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VkBufferCreateInfo* pBufferCreateInfo, const VkBufferCreateInfo* VMA_NOT_NULL pBufferCreateInfo,
const VmaAllocationCreateInfo* pAllocationCreateInfo, const VmaAllocationCreateInfo* VMA_NOT_NULL pAllocationCreateInfo,
uint32_t* pMemoryTypeIndex); uint32_t* VMA_NOT_NULL pMemoryTypeIndex);
/** /**
\brief Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo. \brief Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo.
@ -2760,10 +2809,10 @@ It is just a convenience function, equivalent to calling:
- `vkDestroyImage` - `vkDestroyImage`
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaFindMemoryTypeIndexForImageInfo( VMA_CALL_PRE VkResult VMA_CALL_POST vmaFindMemoryTypeIndexForImageInfo(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VkImageCreateInfo* pImageCreateInfo, const VkImageCreateInfo* VMA_NOT_NULL pImageCreateInfo,
const VmaAllocationCreateInfo* pAllocationCreateInfo, const VmaAllocationCreateInfo* VMA_NOT_NULL pAllocationCreateInfo,
uint32_t* pMemoryTypeIndex); uint32_t* VMA_NOT_NULL pMemoryTypeIndex);
/// Flags to be passed as VmaPoolCreateInfo::flags. /// Flags to be passed as VmaPoolCreateInfo::flags.
typedef enum VmaPoolCreateFlagBits { typedef enum VmaPoolCreateFlagBits {
@ -2905,15 +2954,15 @@ typedef struct VmaPoolStats {
@param[out] pPool Handle to created pool. @param[out] pPool Handle to created pool.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreatePool( VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreatePool(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VmaPoolCreateInfo* pCreateInfo, const VmaPoolCreateInfo* VMA_NOT_NULL pCreateInfo,
VmaPool* pPool); VmaPool* VMA_NOT_NULL pPool);
/** \brief Destroys #VmaPool object and frees Vulkan device memory. /** \brief Destroys #VmaPool object and frees Vulkan device memory.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaDestroyPool( VMA_CALL_PRE void VMA_CALL_POST vmaDestroyPool(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaPool pool); VmaPool VMA_NULLABLE pool);
/** \brief Retrieves statistics of existing #VmaPool object. /** \brief Retrieves statistics of existing #VmaPool object.
@ -2922,9 +2971,9 @@ VMA_CALL_PRE void VMA_CALL_POST vmaDestroyPool(
@param[out] pPoolStats Statistics of specified pool. @param[out] pPoolStats Statistics of specified pool.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaGetPoolStats( VMA_CALL_PRE void VMA_CALL_POST vmaGetPoolStats(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaPool pool, VmaPool VMA_NOT_NULL pool,
VmaPoolStats* pPoolStats); VmaPoolStats* VMA_NOT_NULL pPoolStats);
/** \brief Marks all allocations in given pool as lost if they are not used in current frame or VmaPoolCreateInfo::frameInUseCount back from now. /** \brief Marks all allocations in given pool as lost if they are not used in current frame or VmaPoolCreateInfo::frameInUseCount back from now.
@ -2933,9 +2982,9 @@ VMA_CALL_PRE void VMA_CALL_POST vmaGetPoolStats(
@param[out] pLostAllocationCount Number of allocations marked as lost. Optional - pass null if you don't need this information. @param[out] pLostAllocationCount Number of allocations marked as lost. Optional - pass null if you don't need this information.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaMakePoolAllocationsLost( VMA_CALL_PRE void VMA_CALL_POST vmaMakePoolAllocationsLost(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaPool pool, VmaPool VMA_NOT_NULL pool,
size_t* pLostAllocationCount); size_t* VMA_NULLABLE pLostAllocationCount);
/** \brief Checks magic number in margins around all allocations in given memory pool in search for corruptions. /** \brief Checks magic number in margins around all allocations in given memory pool in search for corruptions.
@ -2951,7 +3000,7 @@ Possible return values:
`VMA_ASSERT` is also fired in that case. `VMA_ASSERT` is also fired in that case.
- Other value: Error returned by Vulkan, e.g. memory mapping failure. - Other value: Error returned by Vulkan, e.g. memory mapping failure.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaCheckPoolCorruption(VmaAllocator allocator, VmaPool pool); VMA_CALL_PRE VkResult VMA_CALL_POST vmaCheckPoolCorruption(VmaAllocator VMA_NOT_NULL allocator, VmaPool VMA_NOT_NULL pool);
/** \brief Retrieves name of a custom pool. /** \brief Retrieves name of a custom pool.
@ -2960,9 +3009,9 @@ containing name of the pool that was previously set. The pointer becomes invalid
destroyed or its name is changed using vmaSetPoolName(). destroyed or its name is changed using vmaSetPoolName().
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaGetPoolName( VMA_CALL_PRE void VMA_CALL_POST vmaGetPoolName(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaPool pool, VmaPool VMA_NOT_NULL pool,
const char** ppName); const char** VMA_NOT_NULL ppName);
/** \brief Sets name of a custom pool. /** \brief Sets name of a custom pool.
@ -2970,9 +3019,9 @@ VMA_CALL_PRE void VMA_CALL_POST vmaGetPoolName(
Function makes internal copy of the string, so it can be changed or freed immediately after this call. Function makes internal copy of the string, so it can be changed or freed immediately after this call.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaSetPoolName( VMA_CALL_PRE void VMA_CALL_POST vmaSetPoolName(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaPool pool, VmaPool VMA_NOT_NULL pool,
const char* pName); const char* VMA_NULLABLE pName);
/** \struct VmaAllocation /** \struct VmaAllocation
\brief Represents single memory allocation. \brief Represents single memory allocation.
@ -3016,7 +3065,7 @@ typedef struct VmaAllocationInfo {
If the allocation is lost, it is equal to `VK_NULL_HANDLE`. If the allocation is lost, it is equal to `VK_NULL_HANDLE`.
*/ */
VkDeviceMemory deviceMemory; VkDeviceMemory VMA_NULLABLE_NON_DISPATCHABLE deviceMemory;
/** \brief Offset into deviceMemory object to the beginning of this allocation, in bytes. (deviceMemory, offset) pair is unique to this allocation. /** \brief Offset into deviceMemory object to the beginning of this allocation, in bytes. (deviceMemory, offset) pair is unique to this allocation.
It can change after call to vmaDefragment() if this allocation is passed to the function, or if allocation is lost. It can change after call to vmaDefragment() if this allocation is passed to the function, or if allocation is lost.
@ -3030,17 +3079,17 @@ typedef struct VmaAllocationInfo {
/** \brief Pointer to the beginning of this allocation as mapped data. /** \brief Pointer to the beginning of this allocation as mapped data.
If the allocation hasn't been mapped using vmaMapMemory() and hasn't been If the allocation hasn't been mapped using vmaMapMemory() and hasn't been
created with #VMA_ALLOCATION_CREATE_MAPPED_BIT flag, this value null. created with #VMA_ALLOCATION_CREATE_MAPPED_BIT flag, this value is null.
It can change after call to vmaMapMemory(), vmaUnmapMemory(). It can change after call to vmaMapMemory(), vmaUnmapMemory().
It can also change after call to vmaDefragment() if this allocation is passed to the function. It can also change after call to vmaDefragment() if this allocation is passed to the function.
*/ */
void* pMappedData; void* VMA_NULLABLE pMappedData;
/** \brief Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vmaSetAllocationUserData(). /** \brief Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vmaSetAllocationUserData().
It can change after call to vmaSetAllocationUserData() for this allocation. It can change after call to vmaSetAllocationUserData() for this allocation.
*/ */
void* pUserData; void* VMA_NULLABLE pUserData;
} VmaAllocationInfo; } VmaAllocationInfo;
/** \brief General purpose memory allocation. /** \brief General purpose memory allocation.
@ -3054,11 +3103,11 @@ It is recommended to use vmaAllocateMemoryForBuffer(), vmaAllocateMemoryForImage
vmaCreateBuffer(), vmaCreateImage() instead whenever possible. vmaCreateBuffer(), vmaCreateImage() instead whenever possible.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaAllocateMemory( VMA_CALL_PRE VkResult VMA_CALL_POST vmaAllocateMemory(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VkMemoryRequirements* pVkMemoryRequirements, const VkMemoryRequirements* VMA_NOT_NULL pVkMemoryRequirements,
const VmaAllocationCreateInfo* pCreateInfo, const VmaAllocationCreateInfo* VMA_NOT_NULL pCreateInfo,
VmaAllocation* pAllocation, VmaAllocation* VMA_NOT_NULL pAllocation,
VmaAllocationInfo* pAllocationInfo); VmaAllocationInfo* VMA_NULLABLE pAllocationInfo);
/** \brief General purpose memory allocation for multiple allocation objects at once. /** \brief General purpose memory allocation for multiple allocation objects at once.
@ -3080,12 +3129,12 @@ If any allocation fails, all allocations already made within this function call
returned result is not `VK_SUCCESS`, `pAllocation` array is always entirely filled with `VK_NULL_HANDLE`. returned result is not `VK_SUCCESS`, `pAllocation` array is always entirely filled with `VK_NULL_HANDLE`.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaAllocateMemoryPages( VMA_CALL_PRE VkResult VMA_CALL_POST vmaAllocateMemoryPages(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VkMemoryRequirements* pVkMemoryRequirements, const VkMemoryRequirements* VMA_NOT_NULL pVkMemoryRequirements,
const VmaAllocationCreateInfo* pCreateInfo, const VmaAllocationCreateInfo* VMA_NOT_NULL pCreateInfo,
size_t allocationCount, size_t allocationCount,
VmaAllocation* pAllocations, VmaAllocation* VMA_NOT_NULL pAllocations VMA_LEN_IF_NOT_NULL(allocationCount),
VmaAllocationInfo* pAllocationInfo); VmaAllocationInfo* VMA_NULLABLE pAllocationInfo VMA_LEN_IF_NOT_NULL(allocationCount));
/** /**
@param[out] pAllocation Handle to allocated memory. @param[out] pAllocation Handle to allocated memory.
@ -3094,27 +3143,27 @@ VMA_CALL_PRE VkResult VMA_CALL_POST vmaAllocateMemoryPages(
You should free the memory using vmaFreeMemory(). You should free the memory using vmaFreeMemory().
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaAllocateMemoryForBuffer( VMA_CALL_PRE VkResult VMA_CALL_POST vmaAllocateMemoryForBuffer(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VkBuffer buffer, VkBuffer VMA_NOT_NULL_NON_DISPATCHABLE buffer,
const VmaAllocationCreateInfo* pCreateInfo, const VmaAllocationCreateInfo* VMA_NOT_NULL pCreateInfo,
VmaAllocation* pAllocation, VmaAllocation* VMA_NOT_NULL pAllocation,
VmaAllocationInfo* pAllocationInfo); VmaAllocationInfo* VMA_NULLABLE pAllocationInfo);
/// Function similar to vmaAllocateMemoryForBuffer(). /// Function similar to vmaAllocateMemoryForBuffer().
VMA_CALL_PRE VkResult VMA_CALL_POST vmaAllocateMemoryForImage( VMA_CALL_PRE VkResult VMA_CALL_POST vmaAllocateMemoryForImage(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VkImage image, VkImage VMA_NOT_NULL_NON_DISPATCHABLE image,
const VmaAllocationCreateInfo* pCreateInfo, const VmaAllocationCreateInfo* VMA_NOT_NULL pCreateInfo,
VmaAllocation* pAllocation, VmaAllocation* VMA_NOT_NULL pAllocation,
VmaAllocationInfo* pAllocationInfo); VmaAllocationInfo* VMA_NULLABLE pAllocationInfo);
/** \brief Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(), or vmaAllocateMemoryForImage(). /** \brief Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(), or vmaAllocateMemoryForImage().
Passing `VK_NULL_HANDLE` as `allocation` is valid. Such function call is just skipped. Passing `VK_NULL_HANDLE` as `allocation` is valid. Such function call is just skipped.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaFreeMemory( VMA_CALL_PRE void VMA_CALL_POST vmaFreeMemory(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation); const VmaAllocation VMA_NULLABLE allocation);
/** \brief Frees memory and destroys multiple allocations. /** \brief Frees memory and destroys multiple allocations.
@ -3127,9 +3176,9 @@ Allocations in `pAllocations` array can come from any memory pools and types.
Passing `VK_NULL_HANDLE` as elements of `pAllocations` array is valid. Such entries are just skipped. Passing `VK_NULL_HANDLE` as elements of `pAllocations` array is valid. Such entries are just skipped.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaFreeMemoryPages( VMA_CALL_PRE void VMA_CALL_POST vmaFreeMemoryPages(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
size_t allocationCount, size_t allocationCount,
VmaAllocation* pAllocations); const VmaAllocation VMA_NULLABLE * VMA_NOT_NULL pAllocations VMA_LEN_IF_NOT_NULL(allocationCount));
/** \brief Deprecated. /** \brief Deprecated.
@ -3139,8 +3188,8 @@ In current version it returns `VK_SUCCESS` only if `newSize` equals current allo
Otherwise returns `VK_ERROR_OUT_OF_POOL_MEMORY`, indicating that allocation's size could not be changed. Otherwise returns `VK_ERROR_OUT_OF_POOL_MEMORY`, indicating that allocation's size could not be changed.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaResizeAllocation( VMA_CALL_PRE VkResult VMA_CALL_POST vmaResizeAllocation(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation, VmaAllocation VMA_NOT_NULL allocation,
VkDeviceSize newSize); VkDeviceSize newSize);
/** \brief Returns current information about specified allocation and atomically marks it as used in current frame. /** \brief Returns current information about specified allocation and atomically marks it as used in current frame.
@ -3160,9 +3209,9 @@ you can avoid calling it too often.
- If you just want to check if allocation is not lost, vmaTouchAllocation() will work faster. - If you just want to check if allocation is not lost, vmaTouchAllocation() will work faster.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaGetAllocationInfo( VMA_CALL_PRE void VMA_CALL_POST vmaGetAllocationInfo(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation, VmaAllocation VMA_NOT_NULL allocation,
VmaAllocationInfo* pAllocationInfo); VmaAllocationInfo* VMA_NOT_NULL pAllocationInfo);
/** \brief Returns `VK_TRUE` if allocation is not lost and atomically marks it as used in current frame. /** \brief Returns `VK_TRUE` if allocation is not lost and atomically marks it as used in current frame.
@ -3179,8 +3228,8 @@ If the allocation has been created without #VMA_ALLOCATION_CREATE_CAN_BECOME_LOS
this function always returns `VK_TRUE`. this function always returns `VK_TRUE`.
*/ */
VMA_CALL_PRE VkBool32 VMA_CALL_POST vmaTouchAllocation( VMA_CALL_PRE VkBool32 VMA_CALL_POST vmaTouchAllocation(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation); VmaAllocation VMA_NOT_NULL allocation);
/** \brief Sets pUserData in given allocation to new value. /** \brief Sets pUserData in given allocation to new value.
@ -3196,9 +3245,9 @@ allocation's `pUserData`. It is opaque, so you can use it however you want - e.g
as a pointer, ordinal number or some handle to you own data. as a pointer, ordinal number or some handle to you own data.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaSetAllocationUserData( VMA_CALL_PRE void VMA_CALL_POST vmaSetAllocationUserData(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation, VmaAllocation VMA_NOT_NULL allocation,
void* pUserData); void* VMA_NULLABLE pUserData);
/** \brief Creates new allocation that is in lost state from the beginning. /** \brief Creates new allocation that is in lost state from the beginning.
@ -3211,8 +3260,8 @@ not bound to any image or buffer. It has size = 0. It cannot be turned into
a real, non-empty allocation. a real, non-empty allocation.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaCreateLostAllocation( VMA_CALL_PRE void VMA_CALL_POST vmaCreateLostAllocation(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation* pAllocation); VmaAllocation* VMA_NOT_NULL pAllocation);
/** \brief Maps memory represented by given allocation and returns pointer to it. /** \brief Maps memory represented by given allocation and returns pointer to it.
@ -3253,9 +3302,9 @@ If the allocation is made from a memory types that is not `HOST_COHERENT`,
you also need to use vmaInvalidateAllocation() / vmaFlushAllocation(), as required by Vulkan specification. you also need to use vmaInvalidateAllocation() / vmaFlushAllocation(), as required by Vulkan specification.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaMapMemory( VMA_CALL_PRE VkResult VMA_CALL_POST vmaMapMemory(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation, VmaAllocation VMA_NOT_NULL allocation,
void** ppData); void** VMA_NOT_NULL ppData);
/** \brief Unmaps memory represented by given allocation, mapped previously using vmaMapMemory(). /** \brief Unmaps memory represented by given allocation, mapped previously using vmaMapMemory().
@ -3266,8 +3315,8 @@ If the allocation is made from a memory types that is not `HOST_COHERENT`,
you also need to use vmaInvalidateAllocation() / vmaFlushAllocation(), as required by Vulkan specification. you also need to use vmaInvalidateAllocation() / vmaFlushAllocation(), as required by Vulkan specification.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaUnmapMemory( VMA_CALL_PRE void VMA_CALL_POST vmaUnmapMemory(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation); VmaAllocation VMA_NOT_NULL allocation);
/** \brief Flushes memory of given allocation. /** \brief Flushes memory of given allocation.
@ -3287,7 +3336,11 @@ Warning! `offset` and `size` are relative to the contents of given `allocation`.
If you mean whole allocation, you can pass 0 and `VK_WHOLE_SIZE`, respectively. If you mean whole allocation, you can pass 0 and `VK_WHOLE_SIZE`, respectively.
Do not pass allocation's offset as `offset`!!! Do not pass allocation's offset as `offset`!!!
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaFlushAllocation(VmaAllocator allocator, VmaAllocation allocation, VkDeviceSize offset, VkDeviceSize size); VMA_CALL_PRE void VMA_CALL_POST vmaFlushAllocation(
VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation VMA_NOT_NULL allocation,
VkDeviceSize offset,
VkDeviceSize size);
/** \brief Invalidates memory of given allocation. /** \brief Invalidates memory of given allocation.
@ -3307,7 +3360,11 @@ Warning! `offset` and `size` are relative to the contents of given `allocation`.
If you mean whole allocation, you can pass 0 and `VK_WHOLE_SIZE`, respectively. If you mean whole allocation, you can pass 0 and `VK_WHOLE_SIZE`, respectively.
Do not pass allocation's offset as `offset`!!! Do not pass allocation's offset as `offset`!!!
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaInvalidateAllocation(VmaAllocator allocator, VmaAllocation allocation, VkDeviceSize offset, VkDeviceSize size); VMA_CALL_PRE void VMA_CALL_POST vmaInvalidateAllocation(
VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation VMA_NOT_NULL allocation,
VkDeviceSize offset,
VkDeviceSize size);
/** \brief Checks magic number in margins around all allocations in given memory types (in both default and custom pools) in search for corruptions. /** \brief Checks magic number in margins around all allocations in given memory types (in both default and custom pools) in search for corruptions.
@ -3325,7 +3382,7 @@ Possible return values:
`VMA_ASSERT` is also fired in that case. `VMA_ASSERT` is also fired in that case.
- Other value: Error returned by Vulkan, e.g. memory mapping failure. - Other value: Error returned by Vulkan, e.g. memory mapping failure.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaCheckCorruption(VmaAllocator allocator, uint32_t memoryTypeBits); VMA_CALL_PRE VkResult VMA_CALL_POST vmaCheckCorruption(VmaAllocator VMA_NOT_NULL allocator, uint32_t memoryTypeBits);
/** \struct VmaDefragmentationContext /** \struct VmaDefragmentationContext
\brief Represents Opaque object that represents started defragmentation process. \brief Represents Opaque object that represents started defragmentation process.
@ -3361,13 +3418,13 @@ typedef struct VmaDefragmentationInfo2 {
It is safe to pass allocations that are in the lost state - they are ignored. It is safe to pass allocations that are in the lost state - they are ignored.
All allocations not present in this array are considered non-moveable during this defragmentation. All allocations not present in this array are considered non-moveable during this defragmentation.
*/ */
VmaAllocation* pAllocations; VmaAllocation VMA_NOT_NULL * VMA_NOT_NULL pAllocations VMA_LEN_IF_NOT_NULL(allocationCount);
/** \brief Optional, output. Pointer to array that will be filled with information whether the allocation at certain index has been changed during defragmentation. /** \brief Optional, output. Pointer to array that will be filled with information whether the allocation at certain index has been changed during defragmentation.
The array should have `allocationCount` elements. The array should have `allocationCount` elements.
You can pass null if you are not interested in this information. You can pass null if you are not interested in this information.
*/ */
VkBool32* pAllocationsChanged; VkBool32* VMA_NULLABLE pAllocationsChanged VMA_LEN_IF_NOT_NULL(allocationCount);
/** \brief Numer of pools in `pPools` array. /** \brief Numer of pools in `pPools` array.
*/ */
uint32_t poolCount; uint32_t poolCount;
@ -3386,7 +3443,7 @@ typedef struct VmaDefragmentationInfo2 {
Using this array is equivalent to specifying all allocations from the pools in `pAllocations`. Using this array is equivalent to specifying all allocations from the pools in `pAllocations`.
It might be more efficient. It might be more efficient.
*/ */
VmaPool* pPools; VmaPool VMA_NOT_NULL * VMA_NULLABLE pPools VMA_LEN_IF_NOT_NULL(poolCount);
/** \brief Maximum total numbers of bytes that can be copied while moving allocations to different places using transfers on CPU side, like `memcpy()`, `memmove()`. /** \brief Maximum total numbers of bytes that can be copied while moving allocations to different places using transfers on CPU side, like `memcpy()`, `memmove()`.
`VK_WHOLE_SIZE` means no limit. `VK_WHOLE_SIZE` means no limit.
@ -3415,12 +3472,12 @@ typedef struct VmaDefragmentationInfo2 {
Passing null means that only CPU defragmentation will be performed. Passing null means that only CPU defragmentation will be performed.
*/ */
VkCommandBuffer commandBuffer; VkCommandBuffer VMA_NULLABLE commandBuffer;
} VmaDefragmentationInfo2; } VmaDefragmentationInfo2;
typedef struct VmaDefragmentationPassMoveInfo { typedef struct VmaDefragmentationPassMoveInfo {
VmaAllocation allocation; VmaAllocation VMA_NOT_NULL allocation;
VkDeviceMemory memory; VkDeviceMemory VMA_NOT_NULL_NON_DISPATCHABLE memory;
VkDeviceSize offset; VkDeviceSize offset;
} VmaDefragmentationPassMoveInfo; } VmaDefragmentationPassMoveInfo;
@ -3430,7 +3487,7 @@ To be used with function vmaBeginDefragmentationPass().
*/ */
typedef struct VmaDefragmentationPassInfo { typedef struct VmaDefragmentationPassInfo {
uint32_t moveCount; uint32_t moveCount;
VmaDefragmentationPassMoveInfo* pMoves; VmaDefragmentationPassMoveInfo* VMA_NOT_NULL pMoves VMA_LEN_IF_NOT_NULL(moveCount);
} VmaDefragmentationPassInfo; } VmaDefragmentationPassInfo;
/** \brief Deprecated. Optional configuration parameters to be passed to function vmaDefragment(). /** \brief Deprecated. Optional configuration parameters to be passed to function vmaDefragment().
@ -3492,10 +3549,10 @@ For more information and important limitations regarding defragmentation, see do
[Defragmentation](@ref defragmentation). [Defragmentation](@ref defragmentation).
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaDefragmentationBegin( VMA_CALL_PRE VkResult VMA_CALL_POST vmaDefragmentationBegin(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VmaDefragmentationInfo2* pInfo, const VmaDefragmentationInfo2* VMA_NOT_NULL pInfo,
VmaDefragmentationStats* pStats, VmaDefragmentationStats* VMA_NULLABLE pStats,
VmaDefragmentationContext *pContext); VmaDefragmentationContext* VMA_NOT_NULL pContext);
/** \brief Ends defragmentation process. /** \brief Ends defragmentation process.
@ -3503,17 +3560,17 @@ Use this function to finish defragmentation started by vmaDefragmentationBegin()
It is safe to pass `context == null`. The function then does nothing. It is safe to pass `context == null`. The function then does nothing.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaDefragmentationEnd( VMA_CALL_PRE VkResult VMA_CALL_POST vmaDefragmentationEnd(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaDefragmentationContext context); VmaDefragmentationContext VMA_NULLABLE context);
VMA_CALL_PRE VkResult VMA_CALL_POST vmaBeginDefragmentationPass( VMA_CALL_PRE VkResult VMA_CALL_POST vmaBeginDefragmentationPass(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaDefragmentationContext context, VmaDefragmentationContext VMA_NULLABLE context,
VmaDefragmentationPassInfo* pInfo VmaDefragmentationPassInfo* VMA_NOT_NULL pInfo
); );
VMA_CALL_PRE VkResult VMA_CALL_POST vmaEndDefragmentationPass( VMA_CALL_PRE VkResult VMA_CALL_POST vmaEndDefragmentationPass(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaDefragmentationContext context VmaDefragmentationContext VMA_NULLABLE context
); );
/** \brief Deprecated. Compacts memory by moving allocations. /** \brief Deprecated. Compacts memory by moving allocations.
@ -3557,12 +3614,12 @@ you should measure that on your platform.
For more information, see [Defragmentation](@ref defragmentation) chapter. For more information, see [Defragmentation](@ref defragmentation) chapter.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaDefragment( VMA_CALL_PRE VkResult VMA_CALL_POST vmaDefragment(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation* pAllocations, VmaAllocation VMA_NOT_NULL * VMA_NOT_NULL pAllocations VMA_LEN_IF_NOT_NULL(allocationCount),
size_t allocationCount, size_t allocationCount,
VkBool32* pAllocationsChanged, VkBool32* VMA_NULLABLE pAllocationsChanged VMA_LEN_IF_NOT_NULL(allocationCount),
const VmaDefragmentationInfo *pDefragmentationInfo, const VmaDefragmentationInfo* VMA_NULLABLE pDefragmentationInfo,
VmaDefragmentationStats* pDefragmentationStats); VmaDefragmentationStats* VMA_NULLABLE pDefragmentationStats);
/** \brief Binds buffer to allocation. /** \brief Binds buffer to allocation.
@ -3577,9 +3634,9 @@ allocations, calls to `vkBind*Memory()` or `vkMapMemory()` won't happen from mul
It is recommended to use function vmaCreateBuffer() instead of this one. It is recommended to use function vmaCreateBuffer() instead of this one.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaBindBufferMemory( VMA_CALL_PRE VkResult VMA_CALL_POST vmaBindBufferMemory(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation, VmaAllocation VMA_NOT_NULL allocation,
VkBuffer buffer); VkBuffer VMA_NOT_NULL_NON_DISPATCHABLE buffer);
/** \brief Binds buffer to allocation with additional parameters. /** \brief Binds buffer to allocation with additional parameters.
@ -3592,11 +3649,11 @@ If `pNext` is not null, #VmaAllocator object must have been created with #VMA_AL
or with VmaAllocatorCreateInfo::vulkanApiVersion `== VK_API_VERSION_1_1`. Otherwise the call fails. or with VmaAllocatorCreateInfo::vulkanApiVersion `== VK_API_VERSION_1_1`. Otherwise the call fails.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaBindBufferMemory2( VMA_CALL_PRE VkResult VMA_CALL_POST vmaBindBufferMemory2(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation, VmaAllocation VMA_NOT_NULL allocation,
VkDeviceSize allocationLocalOffset, VkDeviceSize allocationLocalOffset,
VkBuffer buffer, VkBuffer VMA_NOT_NULL_NON_DISPATCHABLE buffer,
const void* pNext); const void* VMA_NULLABLE pNext);
/** \brief Binds image to allocation. /** \brief Binds image to allocation.
@ -3611,9 +3668,9 @@ allocations, calls to `vkBind*Memory()` or `vkMapMemory()` won't happen from mul
It is recommended to use function vmaCreateImage() instead of this one. It is recommended to use function vmaCreateImage() instead of this one.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaBindImageMemory( VMA_CALL_PRE VkResult VMA_CALL_POST vmaBindImageMemory(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation, VmaAllocation VMA_NOT_NULL allocation,
VkImage image); VkImage VMA_NOT_NULL_NON_DISPATCHABLE image);
/** \brief Binds image to allocation with additional parameters. /** \brief Binds image to allocation with additional parameters.
@ -3626,11 +3683,11 @@ If `pNext` is not null, #VmaAllocator object must have been created with #VMA_AL
or with VmaAllocatorCreateInfo::vulkanApiVersion `== VK_API_VERSION_1_1`. Otherwise the call fails. or with VmaAllocatorCreateInfo::vulkanApiVersion `== VK_API_VERSION_1_1`. Otherwise the call fails.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaBindImageMemory2( VMA_CALL_PRE VkResult VMA_CALL_POST vmaBindImageMemory2(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VmaAllocation allocation, VmaAllocation VMA_NOT_NULL allocation,
VkDeviceSize allocationLocalOffset, VkDeviceSize allocationLocalOffset,
VkImage image, VkImage VMA_NOT_NULL_NON_DISPATCHABLE image,
const void* pNext); const void* VMA_NULLABLE pNext);
/** /**
@param[out] pBuffer Buffer that was created. @param[out] pBuffer Buffer that was created.
@ -3659,12 +3716,12 @@ allocation for this buffer, just like when using
VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT. VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT.
*/ */
VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreateBuffer( VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreateBuffer(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VkBufferCreateInfo* pBufferCreateInfo, const VkBufferCreateInfo* VMA_NOT_NULL pBufferCreateInfo,
const VmaAllocationCreateInfo* pAllocationCreateInfo, const VmaAllocationCreateInfo* VMA_NOT_NULL pAllocationCreateInfo,
VkBuffer* pBuffer, VkBuffer* VMA_NOT_NULL pBuffer,
VmaAllocation* pAllocation, VmaAllocation* VMA_NOT_NULL pAllocation,
VmaAllocationInfo* pAllocationInfo); VmaAllocationInfo* VMA_NULLABLE pAllocationInfo);
/** \brief Destroys Vulkan buffer and frees allocated memory. /** \brief Destroys Vulkan buffer and frees allocated memory.
@ -3678,18 +3735,18 @@ vmaFreeMemory(allocator, allocation);
It it safe to pass null as buffer and/or allocation. It it safe to pass null as buffer and/or allocation.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaDestroyBuffer( VMA_CALL_PRE void VMA_CALL_POST vmaDestroyBuffer(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VkBuffer buffer, VkBuffer VMA_NULLABLE_NON_DISPATCHABLE buffer,
VmaAllocation allocation); VmaAllocation VMA_NULLABLE allocation);
/// Function similar to vmaCreateBuffer(). /// Function similar to vmaCreateBuffer().
VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreateImage( VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreateImage(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
const VkImageCreateInfo* pImageCreateInfo, const VkImageCreateInfo* VMA_NOT_NULL pImageCreateInfo,
const VmaAllocationCreateInfo* pAllocationCreateInfo, const VmaAllocationCreateInfo* VMA_NOT_NULL pAllocationCreateInfo,
VkImage* pImage, VkImage* VMA_NOT_NULL pImage,
VmaAllocation* pAllocation, VmaAllocation* VMA_NOT_NULL pAllocation,
VmaAllocationInfo* pAllocationInfo); VmaAllocationInfo* VMA_NULLABLE pAllocationInfo);
/** \brief Destroys Vulkan image and frees allocated memory. /** \brief Destroys Vulkan image and frees allocated memory.
@ -3703,9 +3760,9 @@ vmaFreeMemory(allocator, allocation);
It it safe to pass null as image and/or allocation. It it safe to pass null as image and/or allocation.
*/ */
VMA_CALL_PRE void VMA_CALL_POST vmaDestroyImage( VMA_CALL_PRE void VMA_CALL_POST vmaDestroyImage(
VmaAllocator allocator, VmaAllocator VMA_NOT_NULL allocator,
VkImage image, VkImage VMA_NULLABLE_NON_DISPATCHABLE image,
VmaAllocation allocation); VmaAllocation VMA_NULLABLE allocation);
#ifdef __cplusplus #ifdef __cplusplus
} }
@ -17614,7 +17671,7 @@ VMA_CALL_PRE void VMA_CALL_POST vmaGetPoolName(
VmaPool pool, VmaPool pool,
const char** ppName) const char** ppName)
{ {
VMA_ASSERT(allocator && pool); VMA_ASSERT(allocator && pool && ppName);
VMA_DEBUG_LOG("vmaGetPoolName"); VMA_DEBUG_LOG("vmaGetPoolName");