The pointer may be later retrieved as VmaAllocationInfo::pUserData:
It can also be changed using function vmaSetAllocationUserData().
Values of (non-zero) allocations' pUserData are printed in JSON report created by vmaBuildStatsString() in hexadecimal form.
The value of pUserData pointer of the allocation will be different than the one you passed when setting allocation's name - pointing to a buffer managed internally that holds copy of the string.
If you have a preference for putting the resource in GPU (device) memory or CPU (host) memory on systems with discrete graphics card that have the memories separate, you can use VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE or VMA_MEMORY_USAGE_AUTO_PREFER_HOST.
When using VMA_MEMORY_USAGE_AUTO* while you want to map the allocated memory, you also need to specify one of the host access flags: VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT. This will help the library decide about preferred memory type to ensure it has VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT so you can map it.
For more examples of creating different kinds of resources, see chapter Recommended usage patterns.
Usage values VMA_MEMORY_USAGE_AUTO* are legal to use only when the library knows about the resource being created by having VkBufferCreateInfo / VkImageCreateInfo passed, so they work with functions like: vmaCreateBuffer(), vmaCreateImage(), vmaFindMemoryTypeIndexForBufferInfo() etc. If you allocate raw memory using function vmaAllocateMemory(), you have to use other means of selecting memory type, as decribed below.
VMA_MEMORY_USAGE_GPU_ONLY, VMA_MEMORY_USAGE_CPU_ONLY, VMA_MEMORY_USAGE_CPU_TO_GPU, VMA_MEMORY_USAGE_GPU_TO_CPU, VMA_MEMORY_USAGE_CPU_COPY) are still available and work same way as in previous versions of the library for backward compatibility, but they are not recommended.A memory type is chosen that has all the required flags and as many preferred flags set as possible.
Value passed in VmaAllocationCreateInfo::usage is internally converted to a set of required and preferred flags, plus some extra "magic" (heuristics).
If you allocate from custom memory pool, all the ways of specifying memory requirements described above are not applicable and the aforementioned members of VmaAllocationCreateInfo structure are ignored. Memory type is selected explicitly when creating the pool and then used to make all the allocations from that pool. For further details, see Custom memory pools.
diff --git a/docs/html/custom_memory_pools.html b/docs/html/custom_memory_pools.html index 1b9b52d..070866e 100644 --- a/docs/html/custom_memory_pools.html +++ b/docs/html/custom_memory_pools.html @@ -125,14 +125,14 @@ $(function() {You have to free all allocations made from this pool before destroying it.
You can defragment a specific custom pool by setting VmaDefragmentationInfo::pool (like in the example above) or all the default pools by setting this member to null.
Unlike in previous iterations of the defragmentation API, there is no list of "movable" allocations passed as a parameter. Defragmentation algorithm tries to move all suitable allocations. You can, however, refuse to move some of them inside a defragmentation pass, by setting pass.pMoves[i].operation to VMA_DEFRAGMENTATION_MOVE_OPERATION_IGNORE. This is not recommended and may result in suboptimal packing of the allocations after defragmentation. If you cannot ensure any allocation can be moved, it is better to keep movable allocations separate in a custom pool.
You can also decide to destroy an allocation instead of moving it. You should then set pass.pMoves[i].operation to VMA_DEFRAGMENTATION_MOVE_OPERATION_DESTROY.
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT. Set this flag to treat VmaAllocationCreateInfo::pUserData as pointer to a null-terminated string. Instead of copying pointer value, a local copy of the string is made and stored in allocation's pUserData. The string is automatically freed together with the allocation. It is also used in vmaBuildStatsString().
Set this flag to treat VmaAllocationCreateInfo::pUserData as pointer to a null-terminated string. Instead of copying pointer value, a local copy of the string is made and stored in allocation's pName. The string is automatically freed together with the allocation. It is also used in vmaBuildStatsString().
Allocation will be created from upper stack in a double stack pool.
This flag is only allowed for custom pools created with VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT flag.
@@ -1083,10 +1087,15 @@ Functions| allocator | Allocator object. | |
| pInfo | Structure filled with parameters of defragmentation. | |
| [out] | pContext | Context object that must be passed to vmaEndDefragmentation() to finish defragmentation. |
| [out] | pContext | Context object that must be passed to vmaEndDefragmentation() to finish defragmentation. |
VK_SUCCESS if defragmentation can begin.VK_ERROR_FEATURE_NOT_PRESENT if defragmentation is not supported.For more information about defragmentation, see documentation chapter: Defragmentation.
@@ -2443,6 +2452,43 @@ FunctionsThis function fails when used on allocation made in memory type that is not HOST_VISIBLE.
This function doesn't automatically flush or invalidate caches. 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.
| void vmaSetAllocationName | +( | +VmaAllocator | +allocator, | +
| + | + | VmaAllocation | +allocation, | +
| + | + | const char * | +pName | +
| + | ) | ++ |
Sets pName in given allocation to new value.
+pName must be either null, or pointer to a null-terminated string. The function makes local copy of the string and sets it as allocation's pName. String passed as pName doesn't need to be valid for whole lifetime of the allocation - you can free it after this call. String previously pointed by allocation's pName is freed from memory.
Sets pUserData in given allocation to new value.
-If the allocation was created with VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT, pUserData must be either null, or pointer to a null-terminated string. The function makes local copy of the string and sets it as allocation's pUserData. String passed as pUserData doesn't need to be valid for whole lifetime of the allocation - you can free it after this call. String previously pointed by allocation's pUserData is freed from memory.
If the flag was not used, the value of pointer pUserData is just copied to 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.
The value of pointer pUserData is copied to 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.
HOST_VISIBLE, the allocation will be mapped on creation. For an example of how to make use of this fact, see section Advanced data uploading.When you want to create a buffer or image:
@@ -154,8 +154,8 @@ Resource allocationDon't forget to destroy your objects when no longer needed:
Remember that using resources that alias in memory requires proper synchronization. You need to issue a memory barrier to make sure commands that use img1 and img2 don't overlap on GPU timeline. You also need to treat a resource after aliasing as uninitialized - containing garbage data. For example, if you use img1 and then want to use img2, you need to issue an image memory barrier for img2 with oldLayout = VK_IMAGE_LAYOUT_UNDEFINED.
Additional considerations:
diff --git a/docs/html/search/all_11.js b/docs/html/search/all_11.js index f2b008d..df54bf0 100644 --- a/docs/html/search/all_11.js +++ b/docs/html/search/all_11.js @@ -111,7 +111,7 @@ var searchData= ['vmaallocatorcreateflagbits_108',['VmaAllocatorCreateFlagBits',['../group__group__init.html#ga4f87c9100d154a65a4ad495f7763cf7c',1,'VmaAllocatorCreateFlagBits(): vk_mem_alloc.h'],['../group__group__init.html#gafd73b95e737ee7e76f827cb5472f559f',1,'VmaAllocatorCreateFlagBits(): vk_mem_alloc.h']]], ['vmaallocatorcreateflags_109',['VmaAllocatorCreateFlags',['../group__group__init.html#gacfe6863e160722c2c1bbcf7573fddc4d',1,'vk_mem_alloc.h']]], ['vmaallocatorcreateinfo_110',['VmaAllocatorCreateInfo',['../struct_vma_allocator_create_info.html',1,'VmaAllocatorCreateInfo'],['../group__group__init.html#gaad9652301d33759b83e52d4f3605a14a',1,'VmaAllocatorCreateInfo(): vk_mem_alloc.h']]], - ['vmaallocatorinfo_111',['VmaAllocatorInfo',['../group__group__init.html#ga1988031b0223fdbd564250fa1edd942c',1,'VmaAllocatorInfo(): vk_mem_alloc.h'],['../struct_vma_allocator_info.html',1,'VmaAllocatorInfo']]], + ['vmaallocatorinfo_111',['VmaAllocatorInfo',['../struct_vma_allocator_info.html',1,'VmaAllocatorInfo'],['../group__group__init.html#ga1988031b0223fdbd564250fa1edd942c',1,'VmaAllocatorInfo(): vk_mem_alloc.h']]], ['vmabegindefragmentation_112',['vmaBeginDefragmentation',['../group__group__alloc.html#gac3335566858b45541fa9c0d7a6bbb57e',1,'vk_mem_alloc.h']]], ['vmabegindefragmentationpass_113',['vmaBeginDefragmentationPass',['../group__group__alloc.html#ga980d7da2ce3b1fd5c8b8476bc362cc00',1,'vk_mem_alloc.h']]], ['vmabindbuffermemory_114',['vmaBindBufferMemory',['../group__group__alloc.html#ga6b0929b914b60cf2d45cac4bf3547470',1,'vk_mem_alloc.h']]], @@ -136,9 +136,9 @@ var searchData= ['vmadefragmentationcontext_133',['VmaDefragmentationContext',['../struct_vma_defragmentation_context.html',1,'']]], ['vmadefragmentationflagbits_134',['VmaDefragmentationFlagBits',['../group__group__alloc.html#ga13415cc0b443353a7b5abda300b833fc',1,'VmaDefragmentationFlagBits(): vk_mem_alloc.h'],['../group__group__alloc.html#ga6552a65b71d16f378c6994b3ceaef50c',1,'VmaDefragmentationFlagBits(): vk_mem_alloc.h']]], ['vmadefragmentationflags_135',['VmaDefragmentationFlags',['../group__group__alloc.html#ga88a77cef37e5d3c4fc9eb328885d048d',1,'vk_mem_alloc.h']]], - ['vmadefragmentationinfo_136',['VmaDefragmentationInfo',['../struct_vma_defragmentation_info.html',1,'VmaDefragmentationInfo'],['../group__group__alloc.html#ga2bf47f96bf92bed2a49461bd9af3acfa',1,'VmaDefragmentationInfo(): vk_mem_alloc.h']]], + ['vmadefragmentationinfo_136',['VmaDefragmentationInfo',['../group__group__alloc.html#ga2bf47f96bf92bed2a49461bd9af3acfa',1,'VmaDefragmentationInfo(): vk_mem_alloc.h'],['../struct_vma_defragmentation_info.html',1,'VmaDefragmentationInfo']]], ['vmadefragmentationmove_137',['VmaDefragmentationMove',['../struct_vma_defragmentation_move.html',1,'VmaDefragmentationMove'],['../group__group__alloc.html#ga563f4b43d3e31ed603d80cacc9ba8589',1,'VmaDefragmentationMove(): vk_mem_alloc.h']]], - ['vmadefragmentationmoveoperation_138',['VmaDefragmentationMoveOperation',['../group__group__alloc.html#gada9e3861caf96f08894b0bcc160ec257',1,'VmaDefragmentationMoveOperation(): vk_mem_alloc.h'],['../group__group__alloc.html#ga2ea666deeb3c2c74806a097e27cdb4a1',1,'VmaDefragmentationMoveOperation(): vk_mem_alloc.h']]], + ['vmadefragmentationmoveoperation_138',['VmaDefragmentationMoveOperation',['../group__group__alloc.html#ga2ea666deeb3c2c74806a097e27cdb4a1',1,'VmaDefragmentationMoveOperation(): vk_mem_alloc.h'],['../group__group__alloc.html#gada9e3861caf96f08894b0bcc160ec257',1,'VmaDefragmentationMoveOperation(): vk_mem_alloc.h']]], ['vmadefragmentationpassmoveinfo_139',['VmaDefragmentationPassMoveInfo',['../struct_vma_defragmentation_pass_move_info.html',1,'VmaDefragmentationPassMoveInfo'],['../group__group__alloc.html#gad6799e8e2b1527abfc84d33bc44aeaf5',1,'VmaDefragmentationPassMoveInfo(): vk_mem_alloc.h']]], ['vmadefragmentationstats_140',['VmaDefragmentationStats',['../struct_vma_defragmentation_stats.html',1,'VmaDefragmentationStats'],['../group__group__alloc.html#gad94034192259c2e34a4d1c5e27810403',1,'VmaDefragmentationStats(): vk_mem_alloc.h']]], ['vmadestroyallocator_141',['vmaDestroyAllocator',['../group__group__init.html#gaa8d164061c88f22fb1fd3c8f3534bc1d',1,'vk_mem_alloc.h']]], @@ -179,25 +179,26 @@ var searchData= ['vmapoolcreateflagbits_176',['VmaPoolCreateFlagBits',['../group__group__alloc.html#ga9a7c45f9c863695d98c83fa5ac940fe7',1,'VmaPoolCreateFlagBits(): vk_mem_alloc.h'],['../group__group__alloc.html#ga4d4f2efc2509157a9e4ecd4fd7942303',1,'VmaPoolCreateFlagBits(): vk_mem_alloc.h']]], ['vmapoolcreateflags_177',['VmaPoolCreateFlags',['../group__group__alloc.html#ga2770e325ea42e087c1b91fdf46d0292a',1,'vk_mem_alloc.h']]], ['vmapoolcreateinfo_178',['VmaPoolCreateInfo',['../struct_vma_pool_create_info.html',1,'VmaPoolCreateInfo'],['../group__group__alloc.html#ga1017aa83489c0eee8d2163d2bf253f67',1,'VmaPoolCreateInfo(): vk_mem_alloc.h']]], - ['vmasetallocationuserdata_179',['vmaSetAllocationUserData',['../group__group__alloc.html#gaf9147d31ffc11d62fc187bde283ed14f',1,'vk_mem_alloc.h']]], - ['vmasetcurrentframeindex_180',['vmaSetCurrentFrameIndex',['../group__group__init.html#gade56bf8dc9f5a5eaddf5f119ed525236',1,'vk_mem_alloc.h']]], - ['vmasetpoolname_181',['vmaSetPoolName',['../group__group__alloc.html#gadbae3a0b4ab078024462fc85c37f3b58',1,'vk_mem_alloc.h']]], - ['vmasetvirtualallocationuserdata_182',['vmaSetVirtualAllocationUserData',['../group__group__virtual.html#ga001ea1850458a4062b829e09c303fca2',1,'vk_mem_alloc.h']]], - ['vmastatistics_183',['VmaStatistics',['../struct_vma_statistics.html',1,'VmaStatistics'],['../group__group__stats.html#gac94bd1a382a3922ddc8de3af4d3ddd06',1,'VmaStatistics(): vk_mem_alloc.h']]], - ['vmatotalstatistics_184',['VmaTotalStatistics',['../group__group__stats.html#ga68916e729e55d513f88ffafbadddb770',1,'VmaTotalStatistics(): vk_mem_alloc.h'],['../struct_vma_total_statistics.html',1,'VmaTotalStatistics']]], - ['vmaunmapmemory_185',['vmaUnmapMemory',['../group__group__alloc.html#ga9bc268595cb33f6ec4d519cfce81ff45',1,'vk_mem_alloc.h']]], - ['vmavirtualallocate_186',['vmaVirtualAllocate',['../group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01',1,'vk_mem_alloc.h']]], - ['vmavirtualallocation_187',['VmaVirtualAllocation',['../struct_vma_virtual_allocation.html',1,'']]], - ['vmavirtualallocationcreateflagbits_188',['VmaVirtualAllocationCreateFlagBits',['../group__group__virtual.html#ga2e9c64d405b14156fea7e10c4ad06cb6',1,'VmaVirtualAllocationCreateFlagBits(): vk_mem_alloc.h'],['../group__group__virtual.html#ga936815e64946a6b6d812d08d10184c23',1,'VmaVirtualAllocationCreateFlagBits(): vk_mem_alloc.h']]], - ['vmavirtualallocationcreateflags_189',['VmaVirtualAllocationCreateFlags',['../group__group__virtual.html#gae96ffc099bf898257fb19e9410ed08a7',1,'vk_mem_alloc.h']]], - ['vmavirtualallocationcreateinfo_190',['VmaVirtualAllocationCreateInfo',['../struct_vma_virtual_allocation_create_info.html',1,'VmaVirtualAllocationCreateInfo'],['../group__group__virtual.html#gac3c90d80bedc6847a41b82d0e2158c9e',1,'VmaVirtualAllocationCreateInfo(): vk_mem_alloc.h']]], - ['vmavirtualallocationinfo_191',['VmaVirtualAllocationInfo',['../struct_vma_virtual_allocation_info.html',1,'VmaVirtualAllocationInfo'],['../group__group__virtual.html#ga75bc33ff7cf18c98e101f570dc2a5ebc',1,'VmaVirtualAllocationInfo(): vk_mem_alloc.h']]], - ['vmavirtualblock_192',['VmaVirtualBlock',['../struct_vma_virtual_block.html',1,'']]], - ['vmavirtualblockcreateflagbits_193',['VmaVirtualBlockCreateFlagBits',['../group__group__virtual.html#ga88bcf8c1cd3bb1610ff7343811c65bca',1,'VmaVirtualBlockCreateFlagBits(): vk_mem_alloc.h'],['../group__group__virtual.html#ga0860ba1c0a67178fae4aecb63a78573e',1,'VmaVirtualBlockCreateFlagBits(): vk_mem_alloc.h']]], - ['vmavirtualblockcreateflags_194',['VmaVirtualBlockCreateFlags',['../group__group__virtual.html#ga4e49c2f0ab7f6b4868833e5bac78d91e',1,'vk_mem_alloc.h']]], - ['vmavirtualblockcreateinfo_195',['VmaVirtualBlockCreateInfo',['../group__group__virtual.html#ga4753d42d40217a3a652a3cdf253ad773',1,'VmaVirtualBlockCreateInfo(): vk_mem_alloc.h'],['../struct_vma_virtual_block_create_info.html',1,'VmaVirtualBlockCreateInfo']]], - ['vmavirtualfree_196',['vmaVirtualFree',['../group__group__virtual.html#ga09fc688c0c3653ff23723b037e5d5033',1,'vk_mem_alloc.h']]], - ['vmavulkanfunctions_197',['VmaVulkanFunctions',['../group__group__init.html#gabb0a8e3b5040d847571cca6c7f9a8074',1,'VmaVulkanFunctions(): vk_mem_alloc.h'],['../struct_vma_vulkan_functions.html',1,'VmaVulkanFunctions']]], - ['vulkan_20memory_20allocator_198',['Vulkan Memory Allocator',['../index.html',1,'']]], - ['vulkanapiversion_199',['vulkanApiVersion',['../struct_vma_allocator_create_info.html#ae0ffc55139b54520a6bb704b29ffc285',1,'VmaAllocatorCreateInfo']]] + ['vmasetallocationname_179',['vmaSetAllocationName',['../group__group__alloc.html#gabe02cbb0cd913b3f125958179f2020fc',1,'vk_mem_alloc.h']]], + ['vmasetallocationuserdata_180',['vmaSetAllocationUserData',['../group__group__alloc.html#gaf9147d31ffc11d62fc187bde283ed14f',1,'vk_mem_alloc.h']]], + ['vmasetcurrentframeindex_181',['vmaSetCurrentFrameIndex',['../group__group__init.html#gade56bf8dc9f5a5eaddf5f119ed525236',1,'vk_mem_alloc.h']]], + ['vmasetpoolname_182',['vmaSetPoolName',['../group__group__alloc.html#gadbae3a0b4ab078024462fc85c37f3b58',1,'vk_mem_alloc.h']]], + ['vmasetvirtualallocationuserdata_183',['vmaSetVirtualAllocationUserData',['../group__group__virtual.html#ga001ea1850458a4062b829e09c303fca2',1,'vk_mem_alloc.h']]], + ['vmastatistics_184',['VmaStatistics',['../struct_vma_statistics.html',1,'VmaStatistics'],['../group__group__stats.html#gac94bd1a382a3922ddc8de3af4d3ddd06',1,'VmaStatistics(): vk_mem_alloc.h']]], + ['vmatotalstatistics_185',['VmaTotalStatistics',['../group__group__stats.html#ga68916e729e55d513f88ffafbadddb770',1,'VmaTotalStatistics(): vk_mem_alloc.h'],['../struct_vma_total_statistics.html',1,'VmaTotalStatistics']]], + ['vmaunmapmemory_186',['vmaUnmapMemory',['../group__group__alloc.html#ga9bc268595cb33f6ec4d519cfce81ff45',1,'vk_mem_alloc.h']]], + ['vmavirtualallocate_187',['vmaVirtualAllocate',['../group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01',1,'vk_mem_alloc.h']]], + ['vmavirtualallocation_188',['VmaVirtualAllocation',['../struct_vma_virtual_allocation.html',1,'']]], + ['vmavirtualallocationcreateflagbits_189',['VmaVirtualAllocationCreateFlagBits',['../group__group__virtual.html#ga2e9c64d405b14156fea7e10c4ad06cb6',1,'VmaVirtualAllocationCreateFlagBits(): vk_mem_alloc.h'],['../group__group__virtual.html#ga936815e64946a6b6d812d08d10184c23',1,'VmaVirtualAllocationCreateFlagBits(): vk_mem_alloc.h']]], + ['vmavirtualallocationcreateflags_190',['VmaVirtualAllocationCreateFlags',['../group__group__virtual.html#gae96ffc099bf898257fb19e9410ed08a7',1,'vk_mem_alloc.h']]], + ['vmavirtualallocationcreateinfo_191',['VmaVirtualAllocationCreateInfo',['../struct_vma_virtual_allocation_create_info.html',1,'VmaVirtualAllocationCreateInfo'],['../group__group__virtual.html#gac3c90d80bedc6847a41b82d0e2158c9e',1,'VmaVirtualAllocationCreateInfo(): vk_mem_alloc.h']]], + ['vmavirtualallocationinfo_192',['VmaVirtualAllocationInfo',['../struct_vma_virtual_allocation_info.html',1,'VmaVirtualAllocationInfo'],['../group__group__virtual.html#ga75bc33ff7cf18c98e101f570dc2a5ebc',1,'VmaVirtualAllocationInfo(): vk_mem_alloc.h']]], + ['vmavirtualblock_193',['VmaVirtualBlock',['../struct_vma_virtual_block.html',1,'']]], + ['vmavirtualblockcreateflagbits_194',['VmaVirtualBlockCreateFlagBits',['../group__group__virtual.html#ga88bcf8c1cd3bb1610ff7343811c65bca',1,'VmaVirtualBlockCreateFlagBits(): vk_mem_alloc.h'],['../group__group__virtual.html#ga0860ba1c0a67178fae4aecb63a78573e',1,'VmaVirtualBlockCreateFlagBits(): vk_mem_alloc.h']]], + ['vmavirtualblockcreateflags_195',['VmaVirtualBlockCreateFlags',['../group__group__virtual.html#ga4e49c2f0ab7f6b4868833e5bac78d91e',1,'vk_mem_alloc.h']]], + ['vmavirtualblockcreateinfo_196',['VmaVirtualBlockCreateInfo',['../group__group__virtual.html#ga4753d42d40217a3a652a3cdf253ad773',1,'VmaVirtualBlockCreateInfo(): vk_mem_alloc.h'],['../struct_vma_virtual_block_create_info.html',1,'VmaVirtualBlockCreateInfo']]], + ['vmavirtualfree_197',['vmaVirtualFree',['../group__group__virtual.html#ga09fc688c0c3653ff23723b037e5d5033',1,'vk_mem_alloc.h']]], + ['vmavulkanfunctions_198',['VmaVulkanFunctions',['../group__group__init.html#gabb0a8e3b5040d847571cca6c7f9a8074',1,'VmaVulkanFunctions(): vk_mem_alloc.h'],['../struct_vma_vulkan_functions.html',1,'VmaVulkanFunctions']]], + ['vulkan_20memory_20allocator_199',['Vulkan Memory Allocator',['../index.html',1,'']]], + ['vulkanapiversion_200',['vulkanApiVersion',['../struct_vma_allocator_create_info.html#ae0ffc55139b54520a6bb704b29ffc285',1,'VmaAllocatorCreateInfo']]] ]; diff --git a/docs/html/search/all_b.js b/docs/html/search/all_b.js index a2266bc..3fcfe86 100644 --- a/docs/html/search/all_b.js +++ b/docs/html/search/all_b.js @@ -11,11 +11,12 @@ var searchData= ['pmappeddata_8',['pMappedData',['../struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2',1,'VmaAllocationInfo']]], ['pmemoryallocatenext_9',['pMemoryAllocateNext',['../struct_vma_pool_create_info.html#af0f8c58f51a2a7a0a389dc79565044d7',1,'VmaPoolCreateInfo']]], ['pmoves_10',['pMoves',['../struct_vma_defragmentation_pass_move_info.html#adfa7a4994afd9b940e7f1dfaf436a725',1,'VmaDefragmentationPassMoveInfo']]], - ['pool_11',['pool',['../struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150',1,'VmaAllocationCreateInfo::pool()'],['../struct_vma_defragmentation_info.html#a18dd2097d8ab2976cdc7dd3e7b978bd4',1,'VmaDefragmentationInfo::pool()']]], - ['preferredflags_12',['preferredFlags',['../struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d',1,'VmaAllocationCreateInfo']]], - ['preferredlargeheapblocksize_13',['preferredLargeHeapBlockSize',['../struct_vma_allocator_create_info.html#a8e4714298e3121cdd8b214a1ae7a637a',1,'VmaAllocatorCreateInfo']]], - ['priority_14',['priority',['../struct_vma_allocation_create_info.html#a983d39e1a2e63649d78a960aa2fdd0f7',1,'VmaAllocationCreateInfo::priority()'],['../struct_vma_pool_create_info.html#a16e686c688f6725f119ebf6e24ab5274',1,'VmaPoolCreateInfo::priority()']]], - ['ptypeexternalmemoryhandletypes_15',['pTypeExternalMemoryHandleTypes',['../struct_vma_allocator_create_info.html#ae8f0db05e5cb4c43d7713bf4a49a736b',1,'VmaAllocatorCreateInfo']]], - ['puserdata_16',['pUserData',['../struct_vma_device_memory_callbacks.html#a24052de0937ddd54015a2df0363903c6',1,'VmaDeviceMemoryCallbacks::pUserData()'],['../struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19',1,'VmaAllocationCreateInfo::pUserData()'],['../struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13',1,'VmaAllocationInfo::pUserData()'],['../struct_vma_virtual_allocation_create_info.html#a015f8544ca51a7350f7434d42d0587bb',1,'VmaVirtualAllocationCreateInfo::pUserData()'],['../struct_vma_virtual_allocation_info.html#a41d5cb09357656411653d82fee436f45',1,'VmaVirtualAllocationInfo::pUserData()']]], - ['pvulkanfunctions_17',['pVulkanFunctions',['../struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd',1,'VmaAllocatorCreateInfo']]] + ['pname_11',['pName',['../struct_vma_allocation_info.html#a28612f3e897e5b268254a3c63413d759',1,'VmaAllocationInfo']]], + ['pool_12',['pool',['../struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150',1,'VmaAllocationCreateInfo::pool()'],['../struct_vma_defragmentation_info.html#a18dd2097d8ab2976cdc7dd3e7b978bd4',1,'VmaDefragmentationInfo::pool()']]], + ['preferredflags_13',['preferredFlags',['../struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d',1,'VmaAllocationCreateInfo']]], + ['preferredlargeheapblocksize_14',['preferredLargeHeapBlockSize',['../struct_vma_allocator_create_info.html#a8e4714298e3121cdd8b214a1ae7a637a',1,'VmaAllocatorCreateInfo']]], + ['priority_15',['priority',['../struct_vma_allocation_create_info.html#a983d39e1a2e63649d78a960aa2fdd0f7',1,'VmaAllocationCreateInfo::priority()'],['../struct_vma_pool_create_info.html#a16e686c688f6725f119ebf6e24ab5274',1,'VmaPoolCreateInfo::priority()']]], + ['ptypeexternalmemoryhandletypes_16',['pTypeExternalMemoryHandleTypes',['../struct_vma_allocator_create_info.html#ae8f0db05e5cb4c43d7713bf4a49a736b',1,'VmaAllocatorCreateInfo']]], + ['puserdata_17',['pUserData',['../struct_vma_device_memory_callbacks.html#a24052de0937ddd54015a2df0363903c6',1,'VmaDeviceMemoryCallbacks::pUserData()'],['../struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19',1,'VmaAllocationCreateInfo::pUserData()'],['../struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13',1,'VmaAllocationInfo::pUserData()'],['../struct_vma_virtual_allocation_create_info.html#a015f8544ca51a7350f7434d42d0587bb',1,'VmaVirtualAllocationCreateInfo::pUserData()'],['../struct_vma_virtual_allocation_info.html#a41d5cb09357656411653d82fee436f45',1,'VmaVirtualAllocationInfo::pUserData()']]], + ['pvulkanfunctions_18',['pVulkanFunctions',['../struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd',1,'VmaAllocatorCreateInfo']]] ]; diff --git a/docs/html/search/functions_0.js b/docs/html/search/functions_0.js index 4866904..d2633bd 100644 --- a/docs/html/search/functions_0.js +++ b/docs/html/search/functions_0.js @@ -56,11 +56,12 @@ var searchData= ['vmainvalidateallocations_53',['vmaInvalidateAllocations',['../group__group__alloc.html#gab25b558d75f7378ec944a1522fdcc3c5',1,'vk_mem_alloc.h']]], ['vmaisvirtualblockempty_54',['vmaIsVirtualBlockEmpty',['../group__group__virtual.html#gacd53b5b1d23f8fcbad692ccfdc1811f1',1,'vk_mem_alloc.h']]], ['vmamapmemory_55',['vmaMapMemory',['../group__group__alloc.html#gad5bd1243512d099706de88168992f069',1,'vk_mem_alloc.h']]], - ['vmasetallocationuserdata_56',['vmaSetAllocationUserData',['../group__group__alloc.html#gaf9147d31ffc11d62fc187bde283ed14f',1,'vk_mem_alloc.h']]], - ['vmasetcurrentframeindex_57',['vmaSetCurrentFrameIndex',['../group__group__init.html#gade56bf8dc9f5a5eaddf5f119ed525236',1,'vk_mem_alloc.h']]], - ['vmasetpoolname_58',['vmaSetPoolName',['../group__group__alloc.html#gadbae3a0b4ab078024462fc85c37f3b58',1,'vk_mem_alloc.h']]], - ['vmasetvirtualallocationuserdata_59',['vmaSetVirtualAllocationUserData',['../group__group__virtual.html#ga001ea1850458a4062b829e09c303fca2',1,'vk_mem_alloc.h']]], - ['vmaunmapmemory_60',['vmaUnmapMemory',['../group__group__alloc.html#ga9bc268595cb33f6ec4d519cfce81ff45',1,'vk_mem_alloc.h']]], - ['vmavirtualallocate_61',['vmaVirtualAllocate',['../group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01',1,'vk_mem_alloc.h']]], - ['vmavirtualfree_62',['vmaVirtualFree',['../group__group__virtual.html#ga09fc688c0c3653ff23723b037e5d5033',1,'vk_mem_alloc.h']]] + ['vmasetallocationname_56',['vmaSetAllocationName',['../group__group__alloc.html#gabe02cbb0cd913b3f125958179f2020fc',1,'vk_mem_alloc.h']]], + ['vmasetallocationuserdata_57',['vmaSetAllocationUserData',['../group__group__alloc.html#gaf9147d31ffc11d62fc187bde283ed14f',1,'vk_mem_alloc.h']]], + ['vmasetcurrentframeindex_58',['vmaSetCurrentFrameIndex',['../group__group__init.html#gade56bf8dc9f5a5eaddf5f119ed525236',1,'vk_mem_alloc.h']]], + ['vmasetpoolname_59',['vmaSetPoolName',['../group__group__alloc.html#gadbae3a0b4ab078024462fc85c37f3b58',1,'vk_mem_alloc.h']]], + ['vmasetvirtualallocationuserdata_60',['vmaSetVirtualAllocationUserData',['../group__group__virtual.html#ga001ea1850458a4062b829e09c303fca2',1,'vk_mem_alloc.h']]], + ['vmaunmapmemory_61',['vmaUnmapMemory',['../group__group__alloc.html#ga9bc268595cb33f6ec4d519cfce81ff45',1,'vk_mem_alloc.h']]], + ['vmavirtualallocate_62',['vmaVirtualAllocate',['../group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01',1,'vk_mem_alloc.h']]], + ['vmavirtualfree_63',['vmaVirtualFree',['../group__group__virtual.html#ga09fc688c0c3653ff23723b037e5d5033',1,'vk_mem_alloc.h']]] ]; diff --git a/docs/html/search/variables_7.js b/docs/html/search/variables_7.js index 06db0e6..973fb1e 100644 --- a/docs/html/search/variables_7.js +++ b/docs/html/search/variables_7.js @@ -9,11 +9,12 @@ var searchData= ['pmappeddata_6',['pMappedData',['../struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2',1,'VmaAllocationInfo']]], ['pmemoryallocatenext_7',['pMemoryAllocateNext',['../struct_vma_pool_create_info.html#af0f8c58f51a2a7a0a389dc79565044d7',1,'VmaPoolCreateInfo']]], ['pmoves_8',['pMoves',['../struct_vma_defragmentation_pass_move_info.html#adfa7a4994afd9b940e7f1dfaf436a725',1,'VmaDefragmentationPassMoveInfo']]], - ['pool_9',['pool',['../struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150',1,'VmaAllocationCreateInfo::pool()'],['../struct_vma_defragmentation_info.html#a18dd2097d8ab2976cdc7dd3e7b978bd4',1,'VmaDefragmentationInfo::pool()']]], - ['preferredflags_10',['preferredFlags',['../struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d',1,'VmaAllocationCreateInfo']]], - ['preferredlargeheapblocksize_11',['preferredLargeHeapBlockSize',['../struct_vma_allocator_create_info.html#a8e4714298e3121cdd8b214a1ae7a637a',1,'VmaAllocatorCreateInfo']]], - ['priority_12',['priority',['../struct_vma_allocation_create_info.html#a983d39e1a2e63649d78a960aa2fdd0f7',1,'VmaAllocationCreateInfo::priority()'],['../struct_vma_pool_create_info.html#a16e686c688f6725f119ebf6e24ab5274',1,'VmaPoolCreateInfo::priority()']]], - ['ptypeexternalmemoryhandletypes_13',['pTypeExternalMemoryHandleTypes',['../struct_vma_allocator_create_info.html#ae8f0db05e5cb4c43d7713bf4a49a736b',1,'VmaAllocatorCreateInfo']]], - ['puserdata_14',['pUserData',['../struct_vma_device_memory_callbacks.html#a24052de0937ddd54015a2df0363903c6',1,'VmaDeviceMemoryCallbacks::pUserData()'],['../struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19',1,'VmaAllocationCreateInfo::pUserData()'],['../struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13',1,'VmaAllocationInfo::pUserData()'],['../struct_vma_virtual_allocation_create_info.html#a015f8544ca51a7350f7434d42d0587bb',1,'VmaVirtualAllocationCreateInfo::pUserData()'],['../struct_vma_virtual_allocation_info.html#a41d5cb09357656411653d82fee436f45',1,'VmaVirtualAllocationInfo::pUserData()']]], - ['pvulkanfunctions_15',['pVulkanFunctions',['../struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd',1,'VmaAllocatorCreateInfo']]] + ['pname_9',['pName',['../struct_vma_allocation_info.html#a28612f3e897e5b268254a3c63413d759',1,'VmaAllocationInfo']]], + ['pool_10',['pool',['../struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150',1,'VmaAllocationCreateInfo::pool()'],['../struct_vma_defragmentation_info.html#a18dd2097d8ab2976cdc7dd3e7b978bd4',1,'VmaDefragmentationInfo::pool()']]], + ['preferredflags_11',['preferredFlags',['../struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d',1,'VmaAllocationCreateInfo']]], + ['preferredlargeheapblocksize_12',['preferredLargeHeapBlockSize',['../struct_vma_allocator_create_info.html#a8e4714298e3121cdd8b214a1ae7a637a',1,'VmaAllocatorCreateInfo']]], + ['priority_13',['priority',['../struct_vma_allocation_create_info.html#a983d39e1a2e63649d78a960aa2fdd0f7',1,'VmaAllocationCreateInfo::priority()'],['../struct_vma_pool_create_info.html#a16e686c688f6725f119ebf6e24ab5274',1,'VmaPoolCreateInfo::priority()']]], + ['ptypeexternalmemoryhandletypes_14',['pTypeExternalMemoryHandleTypes',['../struct_vma_allocator_create_info.html#ae8f0db05e5cb4c43d7713bf4a49a736b',1,'VmaAllocatorCreateInfo']]], + ['puserdata_15',['pUserData',['../struct_vma_device_memory_callbacks.html#a24052de0937ddd54015a2df0363903c6',1,'VmaDeviceMemoryCallbacks::pUserData()'],['../struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19',1,'VmaAllocationCreateInfo::pUserData()'],['../struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13',1,'VmaAllocationInfo::pUserData()'],['../struct_vma_virtual_allocation_create_info.html#a015f8544ca51a7350f7434d42d0587bb',1,'VmaVirtualAllocationCreateInfo::pUserData()'],['../struct_vma_virtual_allocation_info.html#a41d5cb09357656411653d82fee436f45',1,'VmaVirtualAllocationInfo::pUserData()']]], + ['pvulkanfunctions_16',['pVulkanFunctions',['../struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd',1,'VmaAllocatorCreateInfo']]] ]; diff --git a/docs/html/struct_vma_allocation_info-members.html b/docs/html/struct_vma_allocation_info-members.html index 33ed9d8..bf90dd0 100644 --- a/docs/html/struct_vma_allocation_info-members.html +++ b/docs/html/struct_vma_allocation_info-members.html @@ -72,8 +72,9 @@ $(function() {Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().
@@ -165,6 +168,24 @@ Public AttributesIf the allocation hasn't been mapped using vmaMapMemory() and hasn't been created with VMA_ALLOCATION_CREATE_MAPPED_BIT flag, this value is null.
It can change after call to vmaMapMemory(), vmaUnmapMemory(). It can also change after call to vmaDefragment() if this allocation is passed to the function.
+| const char* VmaAllocationInfo::pName | +
Custom allocation name that was set with vmaSetAllocationName().
+It can change after call to vmaSetAllocationName() for this allocation.
+Another way to set custom name is to pass it in VmaAllocationCreateInfo::pUserData with additional flag VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT set [DEPRECATED].
+Also consider: Consider creating them as dedicated allocations using VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT, especially if they are large or if you plan to destroy and recreate them with different sizes e.g. when display resolution changes. Prefer to create such resources first and all other GPU resources (like textures and vertex buffers) later. When VK_EXT_memory_priority extension is enabled, it is also worth setting high priority to such allocation to decrease chances to be evicted to system memory by the operating system.
Also consider: You can map the allocation using vmaMapMemory() or you can create it as persistenly mapped using VMA_ALLOCATION_CREATE_MAPPED_BIT, as in the example above.
For resources that you frequently write on CPU via mapped pointer and freqnently read on GPU e.g. as a uniform buffer (also called "dynamic"), multiple options are possible:
@@ -223,7 +223,7 @@ Advanced data uploadingHere are some other, less obvious use cases and their recommended settings:
diff --git a/docs/html/virtual_allocator.html b/docs/html/virtual_allocator.html index fb11a9a..4df5f65 100644 --- a/docs/html/virtual_allocator.html +++ b/docs/html/virtual_allocator.html @@ -84,8 +84,8 @@ Creating virtual blockIt feels natural to express sizes and offsets in bytes. If an offset of an allocation needs to be aligned to a multiply of some number (e.g. 4 bytes), you can fill optional member VmaVirtualAllocationCreateInfo::alignment to request it. Example:
@@ -151,7 +151,7 @@ Alignment and unitsAlignments of different allocations made from one block may vary. However, if all alignments and sizes are always multiply of some size e.g. 4 B or sizeof(MyDataStruct), you can express all sizes, alignments, and offsets in multiples of that size instead of individual bytes. It might be more convenient, but you need to make sure to use this new unit consistently in all the places:
You can also request a full list of allocations and free regions as a string in JSON format by calling vmaBuildVirtualBlockStatsString(). Returned string must be later freed using vmaFreeVirtualBlockStatsString(). The format of this string differs from the one returned by the main Vulkan allocator, but it is similar.
VK_EXT_memory_priority is a device extension that allows to pass additional "priority" value to Vulkan memory allocations that the implementation may use prefer certain buffers and images that are critical for performance to stay in device-local memory in cases when the memory is over-subscribed, while some others may be moved to the system memory.
-VMA offers convenient usage of this extension. If you enable it, you can pass "priority" parameter when creating allocations or custom pools, and the library automatically passes the value to Vulkan using this extension.
+VMA offers convenient usage of this extension. If you enable it, you can pass "priority" parameter when creating allocations or custom pools and the library automatically passes the value to Vulkan using this extension.
If you want to use this extension in connection with VMA, follow these steps:
1) Call vkEnumerateDeviceExtensionProperties for the physical device. Check if the extension is supported - if returned array of VkExtensionProperties contains "VK_EXT_memory_priority".
2) Call vkGetPhysicalDeviceFeatures2 for the physical device instead of old vkGetPhysicalDeviceFeatures. Attach additional structure VkPhysicalDeviceMemoryPriorityFeaturesEXT to VkPhysicalDeviceFeatures2::pNext to be returned. Check if the device feature is really supported - check if VkPhysicalDeviceMemoryPriorityFeaturesEXT::memoryPriority is true.
3) While creating device with vkCreateDevice, enable this extension - add "VK_EXT_memory_priority" to the list passed as VkDeviceCreateInfo::ppEnabledExtensionNames.
4) While creating the device, also don't set VkDeviceCreateInfo::pEnabledFeatures. Fill in VkPhysicalDeviceFeatures2 structure instead and pass it as VkDeviceCreateInfo::pNext. Enable this device feature - attach additional structure VkPhysicalDeviceMemoryPriorityFeaturesEXT to VkPhysicalDeviceFeatures2::pNext and set its member memoryPriority to VK_TRUE.
4) While creating the device, also don't set VkDeviceCreateInfo::pEnabledFeatures. Fill in VkPhysicalDeviceFeatures2 structure instead and pass it as VkDeviceCreateInfo::pNext. Enable this device feature - attach additional structure VkPhysicalDeviceMemoryPriorityFeaturesEXT to VkPhysicalDeviceFeatures2::pNext chain and set its member memoryPriority to VK_TRUE.
5) While creating VmaAllocator with vmaCreateAllocator() inform VMA that you have enabled this extension and feature - add VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT to VmaAllocatorCreateInfo::flags.
When using this extension, you should initialize following member:
It should be a floating-point value between 0.0f and 1.0f, where recommended default is 0.5f. Memory allocated with higher value can be treated by the Vulkan implementation as higher priority and so it can have lower chances of being pushed out to system memory, experiencing degraded performance.
priority member is ignored in the following situations: