// 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 <>. 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 <> 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 <> 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 <> 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[] --