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