VK_KHR_map_memory2

This document proposes adding extensible version of vkMapMemory() and vkUnmapMemory().

1. Problem Statement

The current Vulkan memory mapping entrypoints are not extensible in the usual sense. vkMapMemory() does have a flags argument which is currently unused, but neither vkMapMemory() nor vkUnmapMemory() take an input struct with a pNext which can be extended.

2. Proposal

Add new vkMapMemory2KHR() and vkUnmapMemory2KHR() entrypoints which take input structs which are extensible via the usual pNext mechanism:

typedef struct VkMemoryMapInfoKHR {
    VkStructureType     sType;
    const void*         pNext;
    VkMemoryMapFlags    flags;
    VkDeviceMemory      memory;
    VkDeviceSize        offset;
    VkDeviceSize        size;
} VkMemoryMapInfoKHR;

VKAPI_ATTR VkResult VKAPI_CALL vkMapMemory2KHR(
    VkDevice                                    device,
    const VkMemoryMapInfoKHR*                   pMemoryMapInfo,
    void**                                      ppData);

typedef struct VkMemoryUnmapInfoKHR {
    VkStructureType          sType;
    const void*              pNext;
    VkMemoryUnmapFlagsKHR    flags;
    VkDeviceMemory           memory;
} VkMemoryUnmapInfoKHR;

VKAPI_ATTR VkResult VKAPI_CALL vkUnmapMemory2KHR(
    VkDevice                                    device,
    const VkMemoryUnmapInfoKHR*                 pMemoryUnmapInfo);

While we are at it, two additional changes are made to vkUnmapMemory() which may be used by upcoming extensions:

  1. It is given a new VkMemoryUnmapFlagsKHR flags parameter. As with VkMemoryMapFlags, it is currently unused.

  2. It gets a VkResult return value. Currently, it is required to always return VK_SUCCESS. However, VK_KHR_map_memory_placed will add cases in which unmap can fail. As long as that extension is not used, clients are free to ignore the return value as it will always be required to be VK_SUCCESS.

2.1. API Features

This extension has no independent features

3. Issues

1) Should we do further reworks of the memory mapping API?

PROPOSED: No, further reworks are out-of-scope for this extension. It is intended to solve the extensibility problem to enable new functionality, not add functionality itself. In that sense, it is similar to VK_KHR_get_physical_device_properties2 or VK_KHR_copy_commands2.