// Copyright 2020-2023 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0
[[private-data]]
= 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 slink:VkDevicePrivateDataCreateInfo
in the pname:pNext chain in slink:VkDeviceCreateInfo before device creation.
Multiple slink: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
<<fundamentals-validusage-pNext,structure pointer chains>>.
Reserving slots in this manner is not strictly necessary but it may: improve
performance.
[open,refpage='VkPrivateDataSlot',desc='Opaque handle to a private data slot object',type='handles',alias='VkPrivateDataSlotEXT']
--
Private data slots are represented by sname:VkPrivateDataSlot handles:
include::{generated}/api/handles/VkPrivateDataSlot.adoc[]
ifdef::VK_EXT_private_data[]
or the equivalent
include::{generated}/api/handles/VkPrivateDataSlotEXT.adoc[]
endif::VK_EXT_private_data[]
--
[open,refpage='vkCreatePrivateDataSlot',desc='Create a slot for private data storage',type='protos',alias='vkCreatePrivateDataSlotEXT']
--
To create a private data slot, call:
ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCreatePrivateDataSlot.adoc[]
endif::VK_VERSION_1_3[]
ifdef::VK_VERSION_1_3+VK_EXT_private_data[or the equivalent command]
ifdef::VK_EXT_private_data[]
include::{generated}/api/protos/vkCreatePrivateDataSlotEXT.adoc[]
endif::VK_EXT_private_data[]
* pname:device is the logical device associated with the creation of the
object(s) holding the private data slot.
* pname:pCreateInfo is a pointer to a sname:VkPrivateDataSlotCreateInfo
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
* pname:pPrivateDataSlot is a pointer to a slink:VkPrivateDataSlot handle
in which the resulting private data slot is returned
.Valid Usage
****
* [[VUID-vkCreatePrivateDataSlot-privateData-04564]]
The <<features-privateData, pname:privateData>> feature must: be enabled
ifdef::VKSC_VERSION_1_0[]
* [[VUID-vkCreatePrivateDataSlotEXT-device-05000]]
The number of private data slots currently allocated from pname:device
plus 1 must: be less than or equal to the total number of private data
slots requested via
slink:VkDevicePrivateDataCreateInfoEXT::pname:privateDataSlotRequestCount
when pname:device was created
endif::VKSC_VERSION_1_0[]
****
include::{generated}/validity/protos/vkCreatePrivateDataSlot.adoc[]
--
[open,refpage='VkPrivateDataSlotCreateInfo',desc='Structure specifying the parameters of private data slot construction',type='structs',alias='VkPrivateDataSlotCreateInfoEXT']
--
The sname:VkPrivateDataSlotCreateInfo structure is defined as:
include::{generated}/api/structs/VkPrivateDataSlotCreateInfo.adoc[]
ifdef::VK_EXT_private_data[]
or the equivalent
include::{generated}/api/structs/VkPrivateDataSlotCreateInfoEXT.adoc[]
endif::VK_EXT_private_data[]
* pname:sType is a elink:VkStructureType value identifying this structure.
* pname:pNext is `NULL` or a pointer to a structure extending this
structure.
* pname:flags is reserved for future use.
include::{generated}/validity/structs/VkPrivateDataSlotCreateInfo.adoc[]
--
[open,refpage='VkPrivateDataSlotCreateFlags',desc='Reserved for future use',type='flags',alias='VkPrivateDataSlotCreateFlagsEXT']
--
include::{generated}/api/flags/VkPrivateDataSlotCreateFlags.adoc[]
ifdef::VK_EXT_private_data[]
or the equivalent
include::{generated}/api/flags/VkPrivateDataSlotCreateFlagsEXT.adoc[]
endif::VK_EXT_private_data[]
tname:VkPrivateDataSlotCreateFlags is a bitmask type for setting a mask, but
is currently reserved for future use.
--
[open,refpage='vkDestroyPrivateDataSlot',desc='Destroy a private data slot',type='protos',alias='vkDestroyPrivateDataSlotEXT']
--
To destroy a private data slot, call:
ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkDestroyPrivateDataSlot.adoc[]
endif::VK_VERSION_1_3[]
ifdef::VK_VERSION_1_3+VK_EXT_private_data[or the equivalent command]
ifdef::VK_EXT_private_data[]
include::{generated}/api/protos/vkDestroyPrivateDataSlotEXT.adoc[]
endif::VK_EXT_private_data[]
* pname:device is the logical device associated with the creation of the
object(s) holding the private data slot.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
* pname:privateDataSlot is the private data slot to destroy.
ifndef::VKSC_VERSION_1_0[]
.Valid Usage
****
* [[VUID-vkDestroyPrivateDataSlot-privateDataSlot-04062]]
If sname:VkAllocationCallbacks were provided when pname:privateDataSlot
was created, a compatible set of callbacks must: be provided here
* [[VUID-vkDestroyPrivateDataSlot-privateDataSlot-04063]]
If no sname:VkAllocationCallbacks were provided when
pname:privateDataSlot was created, pname:pAllocator must: be `NULL`
****
endif::VKSC_VERSION_1_0[]
include::{generated}/validity/protos/vkDestroyPrivateDataSlot.adoc[]
--
[open,refpage='vkSetPrivateData',desc='Associate data with a Vulkan object',type='protos',alias='vkSetPrivateDataEXT']
--
To store user defined data in a slot associated with a Vulkan object, call:
ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkSetPrivateData.adoc[]
endif::VK_VERSION_1_3[]
ifdef::VK_VERSION_1_3+VK_EXT_private_data[or the equivalent command]
ifdef::VK_EXT_private_data[]
include::{generated}/api/protos/vkSetPrivateDataEXT.adoc[]
endif::VK_EXT_private_data[]
* pname:device is the device that created the object.
* pname:objectType is a elink:VkObjectType specifying the type of object
to associate data with.
* pname:objectHandle is a handle to the object to associate data with.
* pname:privateDataSlot is a handle to a slink:VkPrivateDataSlot
specifying location of private data storage.
* pname:data is user defined data to associate the object with.
This data will be stored at pname:privateDataSlot.
.Valid Usage
****
* [[VUID-vkSetPrivateData-objectHandle-04016]]
pname:objectHandle must: be pname:device or a child of pname:device
* [[VUID-vkSetPrivateData-objectHandle-04017]]
pname:objectHandle must: be a valid handle to an object of type
pname:objectType
****
include::{generated}/validity/protos/vkSetPrivateData.adoc[]
--
[open,refpage='vkGetPrivateData',desc='Retrieve data associated with a Vulkan object',type='protos',alias='vkGetPrivateDataEXT']
--
To retrieve user defined data from a slot associated with a Vulkan object,
call:
ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkGetPrivateData.adoc[]
endif::VK_VERSION_1_3[]
ifdef::VK_VERSION_1_3+VK_EXT_private_data[or the equivalent command]
ifdef::VK_EXT_private_data[]
include::{generated}/api/protos/vkGetPrivateDataEXT.adoc[]
endif::VK_EXT_private_data[]
* pname:device is the device that created the object
* pname:objectType is a elink:VkObjectType specifying the type of object
data is associated with.
* pname:objectHandle is a handle to the object data is associated with.
* pname:privateDataSlot is a handle to a slink:VkPrivateDataSlot
specifying location of private data pointer storage.
* pname:pData is a pointer to specify where user data is returned.
`0` will be written in the absence of a previous call to
fname:vkSetPrivateData using the object specified by pname:objectHandle.
[NOTE]
.Note
====
Due to platform details on Android, implementations might not be able to
reliably return `0` from calls to fname:vkGetPrivateData for
slink:VkSwapchainKHR objects on which fname:vkSetPrivateData has not
previously been called.
This erratum is exclusive to the Android platform and objects of type
slink:VkSwapchainKHR.
====
.Valid Usage
****
* [[VUID-vkGetPrivateData-objectType-04018]]
pname:objectType must: be ename:VK_OBJECT_TYPE_DEVICE, or an object type
whose parent is slink:VkDevice
****
include::{generated}/validity/protos/vkGetPrivateData.adoc[]
--