VK_NV_private_data_base_handle.proposal

This extension exposes a mechanism for applications and tools to query the implementation’s base handle for any Vulkan object, even when the handle has been wrapped by one or more layers.

Problem Statement

Vulkan layers commonly wrap device-level object handles. A layer intercepts a handle creation call, creates its own wrapper object, and returns the wrapper handle to the caller. When the caller passes the wrapper handle in a subsequent API call, the layer converts it back to the real underlying handle before forwarding to the next layer or driver.

This wrapping mechanism creates problems in the following scenarios:

• A tool (e.g. Nsight Graphics) communicates directly with the driver and must map from the application-visible (possibly wrapped) handle to the driver’s own handle.
• A new extension or capability is introduced after a layer was written; the layer does not intercept the new entry point and therefore forwards the wrapped handle to the driver, which does not recognize it.
• An application uses a handle outside the normal layer dispatch chain (e.g. through a vendor-specific out-of-band channel).

In all these cases, a reliable way to obtain the driver’s real handle from any handle value is needed.

Solution Space

Several approaches were considered:

• New entry point vkGetBaseHandle - introduces a new command just for this purpose. Rejected because it adds API surface that layers must implement for all object types.
• Extend the loader’s dispatch table mechanism - the loader could expose base handles, but this couples the solution to the loader and does not help with non-loader deployments.
• Reuse the private data mechanism - VkPrivateDataSlot already participates in the layer dispatch chain via vkGetPrivateData. Creating a special slot type that causes the driver to return the base handle value reuses existing infrastructure and requires no new dispatch entry points. This is the chosen approach, matching what NVIDIA already ships internally.

Proposal

The extension introduces a single new flag bit: VK_PRIVATE_DATA_SLOT_CREATE_BASE_OBJECT_HANDLE_BIT_NV.

When a VkPrivateDataSlot is created with this flag, calling vkGetPrivateData (or vkGetPrivateDataEXT) with that slot does not return previously set private data. Instead, the implementation returns the handle value that the implementation itself uses for the object - the base handle.

Because vkGetPrivateData calls are forwarded through the layer chain with each layer substituting the real handle for its wrapper, the driver receives the call with its own real handle as objectHandle. It then returns this value in *pData. The caller thus recovers the implementation’s handle regardless of how many layers have wrapped it.

Calling vkSetPrivateData with a base-handle slot is not permitted; the base handle is intrinsic to the implementation and cannot be overridden.

A feature bit privateDataBaseHandle gates the new behavior, allowing implementations to advertise support explicitly.

New Flag Bit

// VkPrivateDataSlotCreateFlagBits addition
VK_PRIVATE_DATA_SLOT_CREATE_BASE_OBJECT_HANDLE_BIT_NV = 0x00000001

New Feature Structure

typedef struct VkPhysicalDevicePrivateDataBaseHandleFeaturesNV {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           privateDataBaseHandle;
} VkPhysicalDevicePrivateDataBaseHandleFeaturesNV;

Usage

// 1. Create the base-handle slot once per device.
VkPrivateDataSlotCreateInfo slotInfo = {
    .sType = VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO,
    .flags = VK_PRIVATE_DATA_SLOT_CREATE_BASE_OBJECT_HANDLE_BIT_NV,
};
VkPrivateDataSlot baseHandleSlot;
vkCreatePrivateDataSlot(device, &slotInfo, NULL, &baseHandleSlot);

// 2. Query the base handle for any object (even a layer-wrapped one).
uint64_t baseHandle;
vkGetPrivateData(device, VK_OBJECT_TYPE_IMAGE, (uint64_t)someImage,
                 baseHandleSlot, &baseHandle);

// baseHandle now contains the driver's VkImage handle.

Examples

A graphics tool that communicates directly with the driver can call vkGetPrivateData with the base-handle slot for each object it encounters. The returned value is the handle the driver recognizes, independent of any layer wrapping.

Issues

None.

Validation and Tools

A layer that supports VK_NV_private_data_base_handle must forward vkGetPrivateData calls with a base-handle slot to the next layer or driver after substituting the real handle for any wrapper, exactly as it must do for all other vkGetPrivateData calls. No special behavior is required from layers beyond correct handle forwarding.

Validation layers should flag calls to vkSetPrivateData that use a slot created with VK_PRIVATE_DATA_SLOT_CREATE_BASE_OBJECT_HANDLE_BIT_NV.

Further Functionality

A future extension could generalize this concept to allow querying base handles for instance-level objects, which are not supported by the current private data mechanism.