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