• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright 2023-2024 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5# VK_KHR_map_memory2
6:toc: left
7:refpage: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/
8:sectnums:
9
10This document proposes adding extensible version of `vkMapMemory()` and
11`vkUnmapMemory()`.
12
13## Problem Statement
14
15The current Vulkan memory mapping entrypoints are not extensible in the
16usual sense.
17`vkMapMemory()` does have a flags argument which is currently unused, but
18neither `vkMapMemory()` nor `vkUnmapMemory()` take an input struct with a
19`pNext` which can be extended.
20
21## Proposal
22
23Add new `vkMapMemory2KHR()` and `vkUnmapMemory2KHR()` entrypoints which
24take input structs which are extensible via the usual `pNext` mechanism:
25[source,c]
26----
27typedef struct VkMemoryMapInfoKHR {
28    VkStructureType     sType;
29    const void*         pNext;
30    VkMemoryMapFlags    flags;
31    VkDeviceMemory      memory;
32    VkDeviceSize        offset;
33    VkDeviceSize        size;
34} VkMemoryMapInfoKHR;
35
36VKAPI_ATTR VkResult VKAPI_CALL vkMapMemory2KHR(
37    VkDevice                                    device,
38    const VkMemoryMapInfoKHR*                   pMemoryMapInfo,
39    void**                                      ppData);
40
41typedef struct VkMemoryUnmapInfoKHR {
42    VkStructureType          sType;
43    const void*              pNext;
44    VkMemoryUnmapFlagsKHR    flags;
45    VkDeviceMemory           memory;
46} VkMemoryUnmapInfoKHR;
47
48VKAPI_ATTR VkResult VKAPI_CALL vkUnmapMemory2KHR(
49    VkDevice                                    device,
50    const VkMemoryUnmapInfoKHR*                 pMemoryUnmapInfo);
51----
52
53While we are at it, two additional changes are made to `vkUnmapMemory()`
54which may be used by upcoming extensions:
55
56 1. It is given a new `VkMemoryUnmapFlagsKHR flags` parameter.  As with
57    `VkMemoryMapFlags`, it is currently unused.
58
59 2. It gets a `VkResult` return value.  Currently, it is required to always
60    return `VK_SUCCESS`.  However, VK_KHR_map_memory_placed will add cases
61    in which unmap can fail.  As long as that extension is not used,
62    clients are free to ignore the return value as it will always be
63    required to be `VK_SUCCESS`.
64
65### API Features
66
67This extension has no independent features
68
69## Issues
70
711) Should we do further reworks of the memory mapping API?
72
73*PROPOSED*: No, further reworks are out-of-scope for this extension.  It is
74intended to solve the extensibility problem to enable new functionality,
75not add functionality itself.  In that sense, it is similar to
76VK_KHR_get_physical_device_properties2 or VK_KHR_copy_commands2.
77