Function vk_mem_alloc::ffi::vmaMapMemory

pub unsafe extern "C" fn vmaMapMemory(
    allocator: VmaAllocator,
    allocation: VmaAllocation,
    ppData: *mut *mut c_void
) -> Result

\brief Maps memory represented by given allocation and returns pointer to it.

Maps memory represented by given allocation to make it accessible to CPU code. When succeeded, *ppData contains pointer to first byte of this memory.

\warning If the allocation is part of a bigger VkDeviceMemory block, returned pointer is correctly offsetted to the beginning of region assigned to this particular allocation. Unlike the result of vkMapMemory, it points to the allocation, not to the beginning of the whole block. You should not add VmaAllocationInfo::offset to it!

Mapping is internally reference-counted and synchronized, so despite raw Vulkan function vkMapMemory() cannot be used to map same block of VkDeviceMemory multiple times simultaneously, it is safe to call this function on allocations assigned to the same memory block. Actual Vulkan memory will be mapped on first mapping and unmapped on last unmapping.

If the function succeeded, you must call vmaUnmapMemory() to unmap the allocation when mapping is no longer needed or before freeing the allocation, at the latest.

It also safe to call this function multiple times on the same allocation. You must call vmaUnmapMemory() same number of times as you called vmaMapMemory().

It is also safe to call this function on allocation created with #VMA_ALLOCATION_CREATE_MAPPED_BIT flag. Its memory stays mapped all the time. You must still call vmaUnmapMemory() same number of times as you called vmaMapMemory(). You must not call vmaUnmapMemory() additional time to free the “0-th” mapping made automatically due to #VMA_ALLOCATION_CREATE_MAPPED_BIT flag.

This 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.