1// Copyright 2020-2021 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. 12 13An application can: reserve private data slots at device creation. 14To reserve private data slots, insert a 15slink:VkDevicePrivateDataCreateInfoEXT in the pname:pNext chain in 16slink:VkDeviceCreateInfo before device creation. 17Multiple slink:VkDevicePrivateDataCreateInfoEXT structures can: be chained 18together, and the sum of the requested slots will be reserved. 19This is an exception to the specified valid usage for 20<<fundamentals-validusage-pNext,structure pointer chains>>. 21Reserving slots in this manner is not strictly necessary but it may: improve 22performance. 23 24[open,refpage='VkPrivateDataSlotEXT',desc='Opaque handle to a private data slot object',type='handles'] 25-- 26Private data slots are represented by sname:VkPrivateDataSlotEXT handles: 27 28include::{generated}/api/handles/VkPrivateDataSlotEXT.txt[] 29-- 30 31[open,refpage='vkCreatePrivateDataSlotEXT',desc='Create a slot for private data storage',type='protos'] 32-- 33To create a private data slot, call: 34 35include::{generated}/api/protos/vkCreatePrivateDataSlotEXT.txt[] 36 37 * pname:device is the logical device associated with the creation of the 38 object(s) holding the private data slot. 39 * pname:pCreateInfo is a pointer to a sname:VkPrivateDataSlotCreateInfoEXT 40 * pname:pAllocator controls host memory allocation as described in the 41 <<memory-allocation, Memory Allocation>> chapter. 42 * pname:pPrivateDataSlot is a pointer to a slink:VkPrivateDataSlotEXT 43 handle in which the resulting private data slot is returned 44 45.Valid Usage 46**** 47 * [[VUID-vkCreatePrivateDataSlotEXT-privateData-04564]] 48 The <<features-privateData,pname:privateData>> feature must: be enabled 49**** 50 51include::{generated}/validity/protos/vkCreatePrivateDataSlotEXT.txt[] 52-- 53 54[open,refpage='VkPrivateDataSlotCreateInfoEXT',desc='Structure specifying the parameters of private data slot construction',type='structs'] 55-- 56The sname:VkPrivateDataSlotCreateInfoEXT structure is defined as: 57 58include::{generated}/api/structs/VkPrivateDataSlotCreateInfoEXT.txt[] 59 60 * pname:sType is the type of this structure. 61 * pname:pNext is `NULL` or a pointer to a structure extending this 62 structure. 63 * pname:flags is a bitmask of tlink:VkPrivateDataSlotCreateFlagsEXT 64 specifying additional parameters of the new private data slot 65 66include::{generated}/validity/structs/VkPrivateDataSlotCreateInfoEXT.txt[] 67-- 68 69[open,refpage='VkPrivateDataSlotCreateFlagBitsEXT',desc='Bitmask specifying additional parameters for private data slot creation',type='enums'] 70-- 71include::{generated}/api/enums/VkPrivateDataSlotCreateFlagBitsEXT.txt[] 72-- 73 74[open,refpage='VkPrivateDataSlotCreateFlagsEXT',desc='Bitmask of VkPrivateDataSlotCreateFlagBitsEXT',type='flags'] 75-- 76include::{generated}/api/flags/VkPrivateDataSlotCreateFlagsEXT.txt[] 77 78tname:VkPrivateDataSlotCreateFlagsEXT is a bitmask type for setting a mask 79of zero or more elink:VkPrivateDataSlotCreateFlagBitsEXT. 80-- 81 82[open,refpage='vkDestroyPrivateDataSlotEXT',desc='Destroy a private data slot',type='protos'] 83-- 84To destroy a private data slot, call: 85 86include::{generated}/api/protos/vkDestroyPrivateDataSlotEXT.txt[] 87 88 * pname:device is the logical device associated with the creation of the 89 object(s) holding the private data slot. 90 * pname:pAllocator controls host memory allocation as described in the 91 <<memory-allocation, Memory Allocation>> chapter. 92 * pname:privateDataSlot is the private data slot to destroy. 93 94.Valid Usage 95**** 96 * [[VUID-vkDestroyPrivateDataSlotEXT-privateDataSlot-04062]] 97 If sname:VkAllocationCallbacks were provided when pname:privateDataSlot 98 was created, a compatible set of callbacks must: be provided here 99 * [[VUID-vkDestroyPrivateDataSlotEXT-privateDataSlot-04063]] 100 If no sname:VkAllocationCallbacks were provided when 101 pname:privateDataSlot was created, pname:pAllocator must: be `NULL` 102**** 103 104include::{generated}/validity/protos/vkDestroyPrivateDataSlotEXT.txt[] 105-- 106 107[open,refpage='vkSetPrivateDataEXT',desc='Associate data with a Vulkan object',type='protos'] 108-- 109To store user defined data in a slot associated with a Vulkan object, call: 110 111include::{generated}/api/protos/vkSetPrivateDataEXT.txt[] 112 113 * pname:device is the device that created the object. 114 * pname:objectType is a elink:VkObjectType specifying the type of object 115 to associate data with. 116 * pname:objectHandle is a handle to the object to associate data with. 117 * pname:privateDataSlot is a handle to a slink:VkPrivateDataSlotEXT 118 specifying location of private data storage. 119 * pname:data is user defined data to associate the object with. 120 This data will be stored at pname:privateDataSlot. 121 122.Valid Usage 123**** 124 * [[VUID-vkSetPrivateDataEXT-objectHandle-04016]] 125 pname:objectHandle must: be pname:device or a child of pname:device 126 * [[VUID-vkSetPrivateDataEXT-objectHandle-04017]] 127 pname:objectHandle must: be a valid handle to an object of type 128 pname:objectType 129**** 130 131include::{generated}/validity/protos/vkSetPrivateDataEXT.txt[] 132-- 133 134[open,refpage='vkGetPrivateDataEXT',desc='Retrieve data associated with a Vulkan object',type='protos'] 135-- 136To retrieve user defined data from a slot associated with a Vulkan object, 137call: 138 139include::{generated}/api/protos/vkGetPrivateDataEXT.txt[] 140 141 * pname:device is the device that created the object 142 * pname:objectType is a elink:VkObjectType specifying the type of object 143 data is associated with. 144 * pname:objectHandle is a handle to the object data is associated with. 145 * pname:privateDataSlot is a handle to a slink:VkPrivateDataSlotEXT 146 specifying location of private data pointer storage. 147 * pname:pData is a pointer to specify where user data is returned. 148 `0` will be written in the absence of a previous call to 149 fname:vkSetPrivateDataEXT using the object specified by 150 pname:objectHandle. 151 152[NOTE] 153.Note 154==== 155Due to platform details on Android, implementations might not be able to 156reliably return `0` from calls to fname:vkGetPrivateDataEXT for 157slink:VkSwapchainKHR objects on which fname:vkSetPrivateDataEXT has not 158previously been called. 159This erratum is exclusive to the Android platform and objects of type 160slink:VkSwapchainKHR. 161==== 162 163.Valid Usage 164**** 165 * [[VUID-vkGetPrivateDataEXT-objectType-04018]] 166 pname:objectType must: be ename:VK_OBJECT_TYPE_DEVICE, or an object type 167 whose parent is slink:VkDevice 168**** 169 170include::{generated}/validity/protos/vkGetPrivateDataEXT.txt[] 171-- 172