vkMapMemory(3)

# vkMapMemory(3) Manual Page

## Name

vkMapMemory - Map a memory object into application address space

Loading… please wait.

## 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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0