Private Data

The private data extension provides a way for users to associate arbitrary application-defined data with Vulkan objects. This association is accomplished by storing 64-bit unsigned integers of application-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 application-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 application-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 application-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 application-defined data is returned. 0 will be written in the absence of a previous call to vkSetPrivateData using the object specified by objectHandle.

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
    objectHandle must be device or a child of device

  • VUID-vkGetPrivateData-objectHandle-09498
    objectHandle must be a valid handle to an object of type objectType

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