// Copyright 2023-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

# VK_KHR_map_memory2
:toc: left
:refpage: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/
:sectnums:

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

## 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.

## Proposal

Add new `vkMapMemory2KHR()` and `vkUnmapMemory2KHR()` entrypoints which
take input structs which are extensible via the usual `pNext` mechanism:
[source,c]
----
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`.

### API Features

This extension has no independent features

## 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.
