1// Copyright 2020-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[private-data]] 6= Private Data 7 8The private data extension provides a way for users to associate arbitrary 9user defined data with Vulkan objects. 10This association is accomplished by storing 64-bit unsigned integers of user 11defined data in private data slots. 12A private data slot represents a storage allocation for one data item for 13each child object of the device. 14 15An application can: reserve private data slots at device creation. 16To reserve private data slots, insert a slink:VkDevicePrivateDataCreateInfo 17in the pname:pNext chain in slink:VkDeviceCreateInfo before device creation. 18Multiple slink:VkDevicePrivateDataCreateInfo structures can: be chained 19together, and the sum of the requested slots will be reserved. 20This is an exception to the specified valid usage for 21<<fundamentals-validusage-pNext,structure pointer chains>>. 22Reserving slots in this manner is not strictly necessary but it may: improve 23performance. 24 25[open,refpage='VkPrivateDataSlot',desc='Opaque handle to a private data slot object',type='handles',alias='VkPrivateDataSlotEXT'] 26-- 27Private data slots are represented by sname:VkPrivateDataSlot handles: 28 29include::{generated}/api/handles/VkPrivateDataSlot.adoc[] 30 31ifdef::VK_EXT_private_data[] 32or the equivalent 33 34include::{generated}/api/handles/VkPrivateDataSlotEXT.adoc[] 35endif::VK_EXT_private_data[] 36-- 37 38[open,refpage='vkCreatePrivateDataSlot',desc='Create a slot for private data storage',type='protos',alias='vkCreatePrivateDataSlotEXT'] 39-- 40To create a private data slot, call: 41 42ifdef::VK_VERSION_1_3[] 43include::{generated}/api/protos/vkCreatePrivateDataSlot.adoc[] 44endif::VK_VERSION_1_3[] 45 46ifdef::VK_VERSION_1_3+VK_EXT_private_data[or the equivalent command] 47 48ifdef::VK_EXT_private_data[] 49include::{generated}/api/protos/vkCreatePrivateDataSlotEXT.adoc[] 50endif::VK_EXT_private_data[] 51 52 * pname:device is the logical device associated with the creation of the 53 object(s) holding the private data slot. 54 * pname:pCreateInfo is a pointer to a sname:VkPrivateDataSlotCreateInfo 55 * pname:pAllocator controls host memory allocation as described in the 56 <<memory-allocation, Memory Allocation>> chapter. 57 * pname:pPrivateDataSlot is a pointer to a slink:VkPrivateDataSlot handle 58 in which the resulting private data slot is returned 59 60.Valid Usage 61**** 62 * [[VUID-vkCreatePrivateDataSlot-privateData-04564]] 63 The <<features-privateData, pname:privateData>> feature must: be enabled 64ifdef::VKSC_VERSION_1_0[] 65 * [[VUID-vkCreatePrivateDataSlotEXT-device-05000]] 66 The number of private data slots currently allocated from pname:device 67 plus 1 must: be less than or equal to the total number of private data 68 slots requested via 69 slink:VkDevicePrivateDataCreateInfoEXT::pname:privateDataSlotRequestCount 70 when pname:device was created 71endif::VKSC_VERSION_1_0[] 72**** 73 74include::{generated}/validity/protos/vkCreatePrivateDataSlot.adoc[] 75-- 76 77[open,refpage='VkPrivateDataSlotCreateInfo',desc='Structure specifying the parameters of private data slot construction',type='structs',alias='VkPrivateDataSlotCreateInfoEXT'] 78-- 79The sname:VkPrivateDataSlotCreateInfo structure is defined as: 80 81include::{generated}/api/structs/VkPrivateDataSlotCreateInfo.adoc[] 82 83ifdef::VK_EXT_private_data[] 84or the equivalent 85 86include::{generated}/api/structs/VkPrivateDataSlotCreateInfoEXT.adoc[] 87endif::VK_EXT_private_data[] 88 89 * pname:sType is a elink:VkStructureType value identifying this structure. 90 * pname:pNext is `NULL` or a pointer to a structure extending this 91 structure. 92 * pname:flags is reserved for future use. 93 94include::{generated}/validity/structs/VkPrivateDataSlotCreateInfo.adoc[] 95-- 96 97[open,refpage='VkPrivateDataSlotCreateFlags',desc='Reserved for future use',type='flags',alias='VkPrivateDataSlotCreateFlagsEXT'] 98-- 99include::{generated}/api/flags/VkPrivateDataSlotCreateFlags.adoc[] 100 101ifdef::VK_EXT_private_data[] 102or the equivalent 103 104include::{generated}/api/flags/VkPrivateDataSlotCreateFlagsEXT.adoc[] 105endif::VK_EXT_private_data[] 106 107tname:VkPrivateDataSlotCreateFlags is a bitmask type for setting a mask, but 108is currently reserved for future use. 109-- 110 111[open,refpage='vkDestroyPrivateDataSlot',desc='Destroy a private data slot',type='protos',alias='vkDestroyPrivateDataSlotEXT'] 112-- 113To destroy a private data slot, call: 114 115ifdef::VK_VERSION_1_3[] 116include::{generated}/api/protos/vkDestroyPrivateDataSlot.adoc[] 117endif::VK_VERSION_1_3[] 118 119ifdef::VK_VERSION_1_3+VK_EXT_private_data[or the equivalent command] 120 121ifdef::VK_EXT_private_data[] 122include::{generated}/api/protos/vkDestroyPrivateDataSlotEXT.adoc[] 123endif::VK_EXT_private_data[] 124 125 * pname:device is the logical device associated with the creation of the 126 object(s) holding the private data slot. 127 * pname:pAllocator controls host memory allocation as described in the 128 <<memory-allocation, Memory Allocation>> chapter. 129 * pname:privateDataSlot is the private data slot to destroy. 130 131ifndef::VKSC_VERSION_1_0[] 132.Valid Usage 133**** 134 * [[VUID-vkDestroyPrivateDataSlot-privateDataSlot-04062]] 135 If sname:VkAllocationCallbacks were provided when pname:privateDataSlot 136 was created, a compatible set of callbacks must: be provided here 137 * [[VUID-vkDestroyPrivateDataSlot-privateDataSlot-04063]] 138 If no sname:VkAllocationCallbacks were provided when 139 pname:privateDataSlot was created, pname:pAllocator must: be `NULL` 140**** 141endif::VKSC_VERSION_1_0[] 142 143include::{generated}/validity/protos/vkDestroyPrivateDataSlot.adoc[] 144-- 145 146[open,refpage='vkSetPrivateData',desc='Associate data with a Vulkan object',type='protos',alias='vkSetPrivateDataEXT'] 147-- 148To store user defined data in a slot associated with a Vulkan object, call: 149 150ifdef::VK_VERSION_1_3[] 151include::{generated}/api/protos/vkSetPrivateData.adoc[] 152endif::VK_VERSION_1_3[] 153 154ifdef::VK_VERSION_1_3+VK_EXT_private_data[or the equivalent command] 155 156ifdef::VK_EXT_private_data[] 157include::{generated}/api/protos/vkSetPrivateDataEXT.adoc[] 158endif::VK_EXT_private_data[] 159 160 * pname:device is the device that created the object. 161 * pname:objectType is a elink:VkObjectType specifying the type of object 162 to associate data with. 163 * pname:objectHandle is a handle to the object to associate data with. 164 * pname:privateDataSlot is a handle to a slink:VkPrivateDataSlot 165 specifying location of private data storage. 166 * pname:data is user defined data to associate the object with. 167 This data will be stored at pname:privateDataSlot. 168 169.Valid Usage 170**** 171 * [[VUID-vkSetPrivateData-objectHandle-04016]] 172 pname:objectHandle must: be pname:device or a child of pname:device 173 * [[VUID-vkSetPrivateData-objectHandle-04017]] 174 pname:objectHandle must: be a valid handle to an object of type 175 pname:objectType 176**** 177 178include::{generated}/validity/protos/vkSetPrivateData.adoc[] 179-- 180 181[open,refpage='vkGetPrivateData',desc='Retrieve data associated with a Vulkan object',type='protos',alias='vkGetPrivateDataEXT'] 182-- 183To retrieve user defined data from a slot associated with a Vulkan object, 184call: 185 186ifdef::VK_VERSION_1_3[] 187include::{generated}/api/protos/vkGetPrivateData.adoc[] 188endif::VK_VERSION_1_3[] 189 190ifdef::VK_VERSION_1_3+VK_EXT_private_data[or the equivalent command] 191 192ifdef::VK_EXT_private_data[] 193include::{generated}/api/protos/vkGetPrivateDataEXT.adoc[] 194endif::VK_EXT_private_data[] 195 196 * pname:device is the device that created the object 197 * pname:objectType is a elink:VkObjectType specifying the type of object 198 data is associated with. 199 * pname:objectHandle is a handle to the object data is associated with. 200 * pname:privateDataSlot is a handle to a slink:VkPrivateDataSlot 201 specifying location of private data pointer storage. 202 * pname:pData is a pointer to specify where user data is returned. 203 `0` will be written in the absence of a previous call to 204 fname:vkSetPrivateData using the object specified by pname:objectHandle. 205 206[NOTE] 207.Note 208==== 209Due to platform details on Android, implementations might not be able to 210reliably return `0` from calls to fname:vkGetPrivateData for 211slink:VkSwapchainKHR objects on which fname:vkSetPrivateData has not 212previously been called. 213This erratum is exclusive to the Android platform and objects of type 214slink:VkSwapchainKHR. 215==== 216 217.Valid Usage 218**** 219 * [[VUID-vkGetPrivateData-objectType-04018]] 220 pname:objectType must: be ename:VK_OBJECT_TYPE_DEVICE, or an object type 221 whose parent is slink:VkDevice 222**** 223 224include::{generated}/validity/protos/vkGetPrivateData.adoc[] 225-- 226