Vulkan-Docs/doc/specs/vulkan/man/vkMapMemory.txt

// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

vkMapMemory(3)
==============

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

C Specification
---------------

// refBegin vkMapMemory Map a memory object into application address space.

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

include::../api/protos/vkMapMemory.txt[]


Parameters
----------

  * pname:device is the logical device that owns the memory.
  * pname:memory is the sname:VkDeviceMemory object to be mapped.
  * pname:offset is a zero-based byte offset from the beginning of the
    memory object.
  * pname:size is the size of the memory range to map, or
    ename:VK_WHOLE_SIZE to map from pname:offset to the end of the
    allocation.
  * pname:flags is reserved for future use.
  * pname:ppData points to a pointer in which is returned a host-accessible
    pointer to the beginning of the mapped range. This pointer minus
    pname:offset must: be aligned to at least
    sname:VkPhysicalDeviceLimits::pname:minMemoryMapAlignment.


Description
-----------

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

[[memory-device-hostaccess-hazards]]
fname: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
<<synchronization-fences-devicewrites, here>>
for details on fulfilling such a guarantee). If the device memory was
allocated without the ename: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
sname:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize, and round the end
of the range up to the nearest multiple of
sname:VkPhysicalDeviceLimits::pname: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]
.Note
====
It is important for the application developer to become meticulously
familiar with all of the mechanisms described in the chapter on
<<synchronization, Synchronization and Cache Control>> as they are crucial
to maintaining memory access ordering.
====

include::../validity/protos/vkMapMemory.txt[]


See Also
--------

slink:VkDevice, slink:VkDeviceMemory, basetype:VkDeviceSize, elink: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.

include::footer.txt[]