VKMAPMEMORY(3)

NAME
vkMapMemory - Map a memory object into application address space.

C SPECIFICATION

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

    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 points to a pointer in which is returned a host-accessible pointer to the beginning of the mapped range. This pointer minus offset must be aligned to at least VkPhysicalDeviceLimits::minMemoryMapAlignment.

DESCRIPTION

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

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 mapped for host access, 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.

VALID USAGE

    • device must be a valid VkDevice handle

    • memory must be a valid VkDeviceMemory handle

    • flags must be 0

    • ppData must be a pointer to a pointer

    • memory must have been created, allocated, or retrieved from device

    • memory must not currently be mapped

    • offset must be less than the size of memory

    • If size is not equal to VK_WHOLE_SIZE, size must be greater than 0

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

    • memory must have been created with a memory type that reports VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT

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

VkDevice, VkDeviceMemory, VkDeviceSize, VkMemoryMapFlags

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkMapMemory

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

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.