Author: The Khronos® Vulkan Working Group

# Vulkan® 1.3.274 - A Specification (with all registered extensions)

The Khronos® Vulkan Working Group
version 1.3.274, 2023-12-19 13:39:58Z
from git branch: Git branch not available commit: Git commit not available

Loading… please wait.

Search:

## 36. Private Data

The private data extension provides a way for users to associate arbitrary user defined data with Vulkan objects. This association is accomplished by storing 64-bit unsigned integers of user defined data in private data slots. A private data slot represents a storage allocation for one data item for each child object of the device.

An application can reserve private data slots at device creation. To reserve private data slots, insert a VkDevicePrivateDataCreateInfo in the `pNext` chain in VkDeviceCreateInfo before device creation. Multiple VkDevicePrivateDataCreateInfo structures can be chained together, and the sum of the requested slots will be reserved. This is an exception to the specified valid usage for structure pointer chains. Reserving slots in this manner is not strictly necessary but it may improve performance.

Private data slots are represented by `VkPrivateDataSlot` handles:

    // Provided by VK_VERSION_1_3
    VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPrivateDataSlot)

or the equivalent

    // Provided by VK_EXT_private_data
    typedef VkPrivateDataSlot VkPrivateDataSlotEXT;

To create a private data slot, call:

    // Provided by VK_VERSION_1_3
    VkResult vkCreatePrivateDataSlot(
        VkDevice                                    device,
        const VkPrivateDataSlotCreateInfo*          pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkPrivateDataSlot*                          pPrivateDataSlot);

or the equivalent command

    // Provided by VK_EXT_private_data
    VkResult vkCreatePrivateDataSlotEXT(
        VkDevice                                    device,
        const VkPrivateDataSlotCreateInfo*          pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkPrivateDataSlot*                          pPrivateDataSlot);

- `device` is the logical device associated with the creation of the object(s) holding the private data slot.

- `pCreateInfo` is a pointer to a `VkPrivateDataSlotCreateInfo`

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

- `pPrivateDataSlot` is a pointer to a VkPrivateDataSlot handle in which the resulting private data slot is returned

Valid Usage

- VUID-vkCreatePrivateDataSlot-privateData-04564
  The `privateData` feature must be enabled

Valid Usage (Implicit)

- VUID-vkCreatePrivateDataSlot-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkCreatePrivateDataSlot-pCreateInfo-parameter
  `pCreateInfo` must be a valid pointer to a valid VkPrivateDataSlotCreateInfo structure

- VUID-vkCreatePrivateDataSlot-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkCreatePrivateDataSlot-pPrivateDataSlot-parameter
  `pPrivateDataSlot` must be a valid pointer to a VkPrivateDataSlot handle

Return Codes

Success

  - `VK_SUCCESS`

Failure

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

The `VkPrivateDataSlotCreateInfo` structure is defined as:

    // Provided by VK_VERSION_1_3
    typedef struct VkPrivateDataSlotCreateInfo {
        VkStructureType                 sType;
        const void*                     pNext;
        VkPrivateDataSlotCreateFlags    flags;
    } VkPrivateDataSlotCreateInfo;

or the equivalent

    // Provided by VK_EXT_private_data
    typedef VkPrivateDataSlotCreateInfo VkPrivateDataSlotCreateInfoEXT;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `flags` is reserved for future use.

Valid Usage (Implicit)

- VUID-VkPrivateDataSlotCreateInfo-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO`

- VUID-VkPrivateDataSlotCreateInfo-pNext-pNext
  `pNext` must be `NULL`

- VUID-VkPrivateDataSlotCreateInfo-flags-zerobitmask
  `flags` must be `0`

    // Provided by VK_VERSION_1_3
    typedef VkFlags VkPrivateDataSlotCreateFlags;

or the equivalent

    // Provided by VK_EXT_private_data
    typedef VkPrivateDataSlotCreateFlags VkPrivateDataSlotCreateFlagsEXT;

`VkPrivateDataSlotCreateFlags` is a bitmask type for setting a mask, but is currently reserved for future use.

To destroy a private data slot, call:

    // Provided by VK_VERSION_1_3
    void vkDestroyPrivateDataSlot(
        VkDevice                                    device,
        VkPrivateDataSlot                           privateDataSlot,
        const VkAllocationCallbacks*                pAllocator);

or the equivalent command

    // Provided by VK_EXT_private_data
    void vkDestroyPrivateDataSlotEXT(
        VkDevice                                    device,
        VkPrivateDataSlot                           privateDataSlot,
        const VkAllocationCallbacks*                pAllocator);

- `device` is the logical device associated with the creation of the object(s) holding the private data slot.

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

- `privateDataSlot` is the private data slot to destroy.

Valid Usage

- VUID-vkDestroyPrivateDataSlot-privateDataSlot-04062
  If `VkAllocationCallbacks` were provided when `privateDataSlot` was created, a compatible set of callbacks must be provided here

- VUID-vkDestroyPrivateDataSlot-privateDataSlot-04063
  If no `VkAllocationCallbacks` were provided when `privateDataSlot` was created, `pAllocator` must be `NULL`

Valid Usage (Implicit)

- VUID-vkDestroyPrivateDataSlot-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkDestroyPrivateDataSlot-privateDataSlot-parameter
  If `privateDataSlot` is not VK_NULL_HANDLE, `privateDataSlot` must be a valid VkPrivateDataSlot handle

- VUID-vkDestroyPrivateDataSlot-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkDestroyPrivateDataSlot-privateDataSlot-parent
  If `privateDataSlot` is a valid handle, it must have been created, allocated, or retrieved from `device`

Host Synchronization

- Host access to `privateDataSlot` must be externally synchronized

To store user defined data in a slot associated with a Vulkan object, call:

    // Provided by VK_VERSION_1_3
    VkResult vkSetPrivateData(
        VkDevice                                    device,
        VkObjectType                                objectType,
        uint64_t                                    objectHandle,
        VkPrivateDataSlot                           privateDataSlot,
        uint64_t                                    data);

or the equivalent command

    // Provided by VK_EXT_private_data
    VkResult vkSetPrivateDataEXT(
        VkDevice                                    device,
        VkObjectType                                objectType,
        uint64_t                                    objectHandle,
        VkPrivateDataSlot                           privateDataSlot,
        uint64_t                                    data);

- `device` is the device that created the object.

- `objectType` is a VkObjectType specifying the type of object to associate data with.

- `objectHandle` is a handle to the object to associate data with.

- `privateDataSlot` is a handle to a VkPrivateDataSlot specifying location of private data storage.

- `data` is user defined data to associate the object with. This data will be stored at `privateDataSlot`.

Valid Usage

- VUID-vkSetPrivateData-objectHandle-04016
  `objectHandle` must be `device` or a child of `device`

- VUID-vkSetPrivateData-objectHandle-04017
  `objectHandle` must be a valid handle to an object of type `objectType`

Valid Usage (Implicit)

- VUID-vkSetPrivateData-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkSetPrivateData-objectType-parameter
  `objectType` must be a valid VkObjectType value

- VUID-vkSetPrivateData-privateDataSlot-parameter
  `privateDataSlot` must be a valid VkPrivateDataSlot handle

- VUID-vkSetPrivateData-privateDataSlot-parent
  `privateDataSlot` must have been created, allocated, or retrieved from `device`

Return Codes

Success

  - `VK_SUCCESS`

Failure

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

To retrieve user defined data from a slot associated with a Vulkan object, call:

    // Provided by VK_VERSION_1_3
    void vkGetPrivateData(
        VkDevice                                    device,
        VkObjectType                                objectType,
        uint64_t                                    objectHandle,
        VkPrivateDataSlot                           privateDataSlot,
        uint64_t*                                   pData);

or the equivalent command

    // Provided by VK_EXT_private_data
    void vkGetPrivateDataEXT(
        VkDevice                                    device,
        VkObjectType                                objectType,
        uint64_t                                    objectHandle,
        VkPrivateDataSlot                           privateDataSlot,
        uint64_t*                                   pData);

- `device` is the device that created the object

- `objectType` is a VkObjectType specifying the type of object data is associated with.

- `objectHandle` is a handle to the object data is associated with.

- `privateDataSlot` is a handle to a VkPrivateDataSlot specifying location of private data pointer storage.

- `pData` is a pointer to specify where user data is returned. `0` will be written in the absence of a previous call to `vkSetPrivateData` using the object specified by `objectHandle`.

| Note Due to platform details on Android, implementations might not be able to reliably return `0` from calls to `vkGetPrivateData` for VkSwapchainKHR objects on which `vkSetPrivateData` has not previously been called. This erratum is exclusive to the Android platform and objects of type VkSwapchainKHR.

Valid Usage

- VUID-vkGetPrivateData-objectType-04018
  `objectType` must be `VK_OBJECT_TYPE_DEVICE`, or an object type whose parent is VkDevice

Valid Usage (Implicit)

- VUID-vkGetPrivateData-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkGetPrivateData-objectType-parameter
  `objectType` must be a valid VkObjectType value

- VUID-vkGetPrivateData-privateDataSlot-parameter
  `privateDataSlot` must be a valid VkPrivateDataSlot handle

- VUID-vkGetPrivateData-pData-parameter
  `pData` must be a valid pointer to a `uint64_t` value

- VUID-vkGetPrivateData-privateDataSlot-parent
  `privateDataSlot` must have been created, allocated, or retrieved from `device`