// Copyright 2020-2021 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.

An application can: reserve private data slots at device creation.
To reserve private data slots, insert a
slink:VkDevicePrivateDataCreateInfoEXT in the pname:pNext chain in
slink:VkDeviceCreateInfo before device creation.
Multiple slink: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
<<fundamentals-validusage-pNext,structure pointer chains>>.
Reserving slots in this manner is not strictly necessary but it may: improve
performance.

[open,refpage='VkPrivateDataSlotEXT',desc='Opaque handle to a private data slot object',type='handles']
--
Private data slots are represented by sname:VkPrivateDataSlotEXT handles:

include::{generated}/api/handles/VkPrivateDataSlotEXT.txt[]
--

[open,refpage='vkCreatePrivateDataSlotEXT',desc='Create a slot for private data storage',type='protos']
--
To create a private data slot, call:

include::{generated}/api/protos/vkCreatePrivateDataSlotEXT.txt[]

  * 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:VkPrivateDataSlotCreateInfoEXT
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pPrivateDataSlot is a pointer to a slink:VkPrivateDataSlotEXT
    handle in which the resulting private data slot is returned

.Valid Usage
****
  * [[VUID-vkCreatePrivateDataSlotEXT-privateData-04564]]
    The <<features-privateData,pname:privateData>> feature must: be enabled
****

include::{generated}/validity/protos/vkCreatePrivateDataSlotEXT.txt[]
--

[open,refpage='VkPrivateDataSlotCreateInfoEXT',desc='Structure specifying the parameters of private data slot construction',type='structs']
--
The sname:VkPrivateDataSlotCreateInfoEXT structure is defined as:

include::{generated}/api/structs/VkPrivateDataSlotCreateInfoEXT.txt[]

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

include::{generated}/validity/structs/VkPrivateDataSlotCreateInfoEXT.txt[]
--

[open,refpage='VkPrivateDataSlotCreateFlagBitsEXT',desc='Bitmask specifying additional parameters for private data slot creation',type='enums']
--
include::{generated}/api/enums/VkPrivateDataSlotCreateFlagBitsEXT.txt[]
--

[open,refpage='VkPrivateDataSlotCreateFlagsEXT',desc='Bitmask of VkPrivateDataSlotCreateFlagBitsEXT',type='flags']
--
include::{generated}/api/flags/VkPrivateDataSlotCreateFlagsEXT.txt[]

tname:VkPrivateDataSlotCreateFlagsEXT is a bitmask type for setting a mask
of zero or more elink:VkPrivateDataSlotCreateFlagBitsEXT.
--

[open,refpage='vkDestroyPrivateDataSlotEXT',desc='Destroy a private data slot',type='protos']
--
To destroy a private data slot, call:

include::{generated}/api/protos/vkDestroyPrivateDataSlotEXT.txt[]

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

.Valid Usage
****
  * [[VUID-vkDestroyPrivateDataSlotEXT-privateDataSlot-04062]]
    If sname:VkAllocationCallbacks were provided when pname:privateDataSlot
    was created, a compatible set of callbacks must: be provided here
  * [[VUID-vkDestroyPrivateDataSlotEXT-privateDataSlot-04063]]
    If no sname:VkAllocationCallbacks were provided when
    pname:privateDataSlot was created, pname:pAllocator must: be `NULL`
****

include::{generated}/validity/protos/vkDestroyPrivateDataSlotEXT.txt[]
--

[open,refpage='vkSetPrivateDataEXT',desc='Associate data with a Vulkan object',type='protos']
--
To store user defined data in a slot associated with a Vulkan object, call:

include::{generated}/api/protos/vkSetPrivateDataEXT.txt[]

  * 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:VkPrivateDataSlotEXT
    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-vkSetPrivateDataEXT-objectHandle-04016]]
    pname:objectHandle must: be pname:device or a child of pname:device
  * [[VUID-vkSetPrivateDataEXT-objectHandle-04017]]
    pname:objectHandle must: be a valid handle to an object of type
    pname:objectType
****

include::{generated}/validity/protos/vkSetPrivateDataEXT.txt[]
--

[open,refpage='vkGetPrivateDataEXT',desc='Retrieve data associated with a Vulkan object',type='protos']
--
To retrieve user defined data from a slot associated with a Vulkan object,
call:

include::{generated}/api/protos/vkGetPrivateDataEXT.txt[]

  * 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:VkPrivateDataSlotEXT
    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:vkSetPrivateDataEXT 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:vkGetPrivateDataEXT for
slink:VkSwapchainKHR objects on which fname:vkSetPrivateDataEXT has not
previously been called.
This erratum is exclusive to the Android platform and objects of type
slink:VkSwapchainKHR.
====

.Valid Usage
****
  * [[VUID-vkGetPrivateDataEXT-objectType-04018]]
    pname:objectType must: be ename:VK_OBJECT_TYPE_DEVICE, or an object type
    whose parent is slink:VkDevice
****

include::{generated}/validity/protos/vkGetPrivateDataEXT.txt[]
--