// Copyright 2020-2024 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:objectHandle must: be pname:device or a child of pname:device
  * [[VUID-vkGetPrivateData-objectHandle-09498]]
    pname:objectHandle must: be a valid handle to an object of type
    pname:objectType
****

include::{generated}/validity/protos/vkGetPrivateData.adoc[]
--
