Vulkan® 1.2.148 - A Specification (with all registered extensions)

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

An application can reserve private data slots at device creation. To reserve private data slots, insert a VkDevicePrivateDataCreateInfoEXT in the pNext chain in VkDeviceCreateInfo before device creation. Multiple VkDevicePrivateDataCreateInfoEXT 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 VkPrivateDataSlotEXT handles:

// Provided by VK_EXT_private_data
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPrivateDataSlotEXT)

To create a private data slot, call:

// Provided by VK_EXT_private_data
VkResult vkCreatePrivateDataSlotEXT(
    VkDevice                                    device,
    const VkPrivateDataSlotCreateInfoEXT*       pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkPrivateDataSlotEXT*                       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 VkPrivateDataSlotCreateInfoEXT
pAllocator controls host memory allocation as described in the Memory Allocation chapter.
pPrivateDataSlot is a pointer to a VkPrivateDataSlotEXT handle in which the resulting private data slot is returned

Valid Usage (Implicit)

device must be a valid VkDevice handle
pCreateInfo must be a valid pointer to a valid VkPrivateDataSlotCreateInfoEXT structure
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
pPrivateDataSlot must be a valid pointer to a VkPrivateDataSlotEXT handle

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY

The VkPrivateDataSlotCreateInfoEXT structure is defined as:

// Provided by VK_EXT_private_data
typedef struct VkPrivateDataSlotCreateInfoEXT {
    VkStructureType                    sType;
    const void*                        pNext;
    VkPrivateDataSlotCreateFlagsEXT    flags;
} VkPrivateDataSlotCreateInfoEXT;

sType is the type of this structure
pNext is NULL or a pointer to a structure extending this structure.
flags is a bitmask of VkPrivateDataSlotCreateFlagsEXT specifying additional parameters of the new private data slot

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO_EXT
pNext must be NULL
flags must be 0

// Provided by VK_EXT_private_data
typedef enum VkPrivateDataSlotCreateFlagBitsEXT {
} VkPrivateDataSlotCreateFlagBitsEXT;

// Provided by VK_EXT_private_data
typedef VkFlags VkPrivateDataSlotCreateFlagsEXT;

VkPrivateDataSlotCreateFlagsEXT is a bitmask type for setting a mask of zero or more VkPrivateDataSlotCreateFlagBitsEXT.

To destroy a private data slot, call:

// Provided by VK_EXT_private_data
void vkDestroyPrivateDataSlotEXT(
    VkDevice                                    device,
    VkPrivateDataSlotEXT                        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

If VkAllocationCallbacks were provided when privateDataSlot was created, a compatible set of callbacks must be provided here
If no VkAllocationCallbacks were provided when privateDataSlot was created, pAllocator must be NULL

Valid Usage (Implicit)

device must be a valid VkDevice handle
If privateDataSlot is not VK_NULL_HANDLE, privateDataSlot must be a valid VkPrivateDataSlotEXT handle
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
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_EXT_private_data
VkResult vkSetPrivateDataEXT(
    VkDevice                                    device,
    VkObjectType                                objectType,
    uint64_t                                    objectHandle,
    VkPrivateDataSlotEXT                        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 VkPrivateDataSlotEXT 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

objectHandle must be device or a child of device
objectHandle must be a valid handle to an object of type objectType

Valid Usage (Implicit)

device must be a valid VkDevice handle
objectType must be a valid VkObjectType value
privateDataSlot must be a valid VkPrivateDataSlotEXT handle
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_EXT_private_data
void vkGetPrivateDataEXT(
    VkDevice                                    device,
    VkObjectType                                objectType,
    uint64_t                                    objectHandle,
    VkPrivateDataSlotEXT                        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 VkPrivateDataSlotEXT 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 vkSetPrivateDataEXT 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 vkGetPrivateDataEXT for VkSwapchainKHR objects on which vkSetPrivateDataEXT has not previously been called. This erratum is exclusive to the Android platform and objects of type VkSwapchainKHR.

Valid Usage

objectType must be VkDevice or an object type whose parent is VkDevice

Valid Usage (Implicit)

device must be a valid VkDevice handle
objectType must be a valid VkObjectType value
privateDataSlot must be a valid VkPrivateDataSlotEXT handle
pData must be a valid pointer to a uint64_t value
privateDataSlot must have been created, allocated, or retrieved from device