• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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