vkMapMemory

vkMapMemory is a Vulkan API function that maps a region of a device memory object into the host address space. It enables the CPU to access memory that is bound to Vulkan resources, such as buffers or images, by obtaining a pointer to the mapped region.

The function signature is VkResult vkMapMemory(VkDevice device, VkDeviceMemory memory, VkDeviceSize offset, VkDeviceSize size, VkMemoryMapFlags flags, void** ppData). On success, ppData receives a host-accessible pointer to the mapped memory. The size parameter can be a specific range or VK_WHOLE_SIZE to map from the given offset to the end of the allocation. The offset and size must reference the allocated memory region and respect alignment rules of the implementation.

Mapping requires that the memory object was allocated from a memory type that has the VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT property. If the memory type lacks host visibility, vkMapMemory will fail with VK_ERROR_MEMORY_MAP_FAILED or a related error. If the memory type does not include VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, the application must explicitly flush or invalidate mapped ranges using vkFlushMappedMemoryRanges and vkInvalidateMappedMemoryRanges when data is transferred between the host and device.

The host can read from and write to the mapped region, but synchronization with device operations is required. Accesses should be coordinated with command submission and data visibility rules; after host writes to non-coherent memory, flush is necessary before the device uses the data, and after device writes to non-coherent memory, invalidation may be required before host reads it. The memory can be unmapped with vkUnmapMemory when access is complete or before freeing the memory.

Typical errors include VK_ERROR_OUT_OF_HOST_MEMORY and VK_ERROR_MEMORY_MAP_FAILED.