C Specification

To retrieve a host virtual address pointer to a region of a mappable memory object, call:

// Provided by VK_VERSION_1_0
VkResult vkMapMemory(
    VkDevice                                    device,
    VkDeviceMemory                              memory,
    VkDeviceSize                                offset,
    VkDeviceSize                                size,
    VkMemoryMapFlags                            flags,
    void**                                      ppData);

Parameters

  • device is the logical device that owns the memory.

  • memory is the VkDeviceMemory object to be mapped.

  • offset is a zero-based byte offset from the beginning of the memory object.

  • size is the size of the memory range to map, or VK_WHOLE_SIZE to map from offset to the end of the allocation.

  • flags is reserved for future use.

  • ppData is a pointer to a void* variable in which a host-accessible pointer to the beginning of the mapped range is returned. This pointer minus offset must be aligned to at least VkPhysicalDeviceLimits::minMemoryMapAlignment.

Description

After a successful call to vkMapMemory the memory object memory is considered to be currently host mapped.

Note

It is an application error to call vkMapMemory on a memory object that is already host mapped.
Note

vkMapMemory will fail if the implementation is unable to allocate an appropriately sized contiguous virtual address range, e.g. due to virtual address space fragmentation or platform limits. In such cases, vkMapMemory must return VK_ERROR_MEMORY_MAP_FAILED. The application can improve the likelihood of success by reducing the size of the mapped range and/or removing unneeded mappings using vkUnmapMemory.

vkMapMemory does not check whether the device memory is currently in use before returning the host-accessible pointer. The application must guarantee that any previously submitted command that writes to this range has completed before the host reads from or writes to that range, and that any previously submitted command that reads from that range has completed before the host writes to that region (see here for details on fulfilling such a guarantee). If the device memory was allocated without the VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, these guarantees must be made for an extended range: the application must round down the start of the range to the nearest multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize, and round the end of the range up to the nearest multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize.

While a range of device memory is host mapped, the application is responsible for synchronizing both device and host access to that memory range.

Note

It is important for the application developer to become meticulously familiar with all of the mechanisms described in the chapter on Synchronization and Cache Control as they are crucial to maintaining memory access ordering.

Calling vkMapMemory is equivalent to calling vkMapMemory2KHR with an empty pNext chain.

Valid Usage

  • VUID-vkMapMemory-memory-00678
    memory must not be currently host mapped

  • VUID-vkMapMemory-offset-00679
    offset must be less than the size of memory

  • VUID-vkMapMemory-size-00680
    If size is not equal to VK_WHOLE_SIZE, size must be greater than 0

  • VUID-vkMapMemory-size-00681
    If size is not equal to VK_WHOLE_SIZE, size must be less than or equal to the size of the memory minus offset

  • VUID-vkMapMemory-memory-00682
    memory must have been created with a memory type that reports VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT

  • VUID-vkMapMemory-memory-00683
    memory must not have been allocated with multiple instances

Valid Usage (Implicit)

  • VUID-vkMapMemory-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkMapMemory-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-vkMapMemory-flags-zerobitmask
    flags must be 0

  • VUID-vkMapMemory-ppData-parameter
    ppData must be a valid pointer to a pointer value

  • VUID-vkMapMemory-memory-parent
    memory must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to memory must be externally synchronized

Return Codes
On success, this command returns

  • VK_SUCCESS

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_MEMORY_MAP_FAILED

See Also

VK_VERSION_1_0, VkDevice, VkDeviceMemory, VkDeviceSize, VkMemoryMapFlags

Document Notes

For more information, see the Vulkan Specification

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

Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0