1  // This section is included inside the Debugging chapter (debugging.txt)
  2  
  3  [[debugging-debug-report-callbacks]]
  4  == Debug Report Callbacks
  5  
  6  [open,refpage='VkDebugReportCallbackEXT',desc='Opaque handle to a debug report callback object',type='handles']
  7  --
  8  
  9  Debug report callbacks are represented by sname:VkDebugReportCallbackEXT
 10  handles:
 11  
 12  include::{generated}/api/handles/VkDebugReportCallbackEXT.txt[]
 13  
 14  --
 15  
 16  [open,refpage='vkCreateDebugReportCallbackEXT',desc='Create a debug report callback object',type='protos']
 17  --
 18  
 19  Debug report callbacks give more detailed feedback on the application's use
 20  of Vulkan when events of interest occur.
 21  
 22  To register a debug report callback, an application uses
 23  flink:vkCreateDebugReportCallbackEXT.
 24  
 25  include::{generated}/api/protos/vkCreateDebugReportCallbackEXT.txt[]
 26  
 27    * pname:instance the instance the callback will be logged on.
 28    * pname:pCreateInfo points to a slink:VkDebugReportCallbackCreateInfoEXT
 29      structure which defines the conditions under which this callback will be
 30      called.
 31    * pname:pAllocator controls host memory allocation as described in the
 32      <<memory-allocation, Memory Allocation>> chapter.
 33    * pname:pCallback is a pointer to record the
 34      sname:VkDebugReportCallbackEXT object created.
 35  
 36  include::{generated}/validity/protos/vkCreateDebugReportCallbackEXT.txt[]
 37  --
 38  
 39  [open,refpage='VkDebugReportCallbackCreateInfoEXT',desc='Structure specifying parameters of a newly created debug report callback',type='structs']
 40  --
 41  
 42  The definition of slink:VkDebugReportCallbackCreateInfoEXT is:
 43  
 44  include::{generated}/api/structs/VkDebugReportCallbackCreateInfoEXT.txt[]
 45  
 46    * pname:sType is the type of this structure.
 47    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
 48    * pname:flags is a bitmask of elink:VkDebugReportFlagBitsEXT specifying
 49      which event(s) will cause this callback to be called.
 50    * pname:pfnCallback is the application callback function to call.
 51    * pname:pUserData is user data to be passed to the callback.
 52  
 53  For each sname:VkDebugReportCallbackEXT that is created the
 54  sname:VkDebugReportCallbackCreateInfoEXT::pname:flags determine when that
 55  sname:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback is called.
 56  When an event happens, the implementation will do a bitwise AND of the
 57  event's elink:VkDebugReportFlagBitsEXT flags to each
 58  sname:VkDebugReportCallbackEXT object's flags.
 59  For each non-zero result the corresponding callback will be called.
 60  The callback will come directly from the component that detected the event,
 61  unless some other layer intercepts the calls for its own purposes (filter
 62  them in a different way, log to a system error log, etc.).
 63  
 64  An application may: receive multiple callbacks if multiple
 65  sname:VkDebugReportCallbackEXT objects were created.
 66  A callback will always be executed in the same thread as the originating
 67  Vulkan call.
 68  
 69  A callback may be called from multiple threads simultaneously (if the
 70  application is making Vulkan calls from multiple threads).
 71  
 72  include::{generated}/validity/structs/VkDebugReportCallbackCreateInfoEXT.txt[]
 73  --
 74  
 75  [open,refpage='VkDebugReportFlagBitsEXT',desc='Bitmask specifying events which cause a debug report callback',type='enums']
 76  --
 77  
 78  Bits which can: be set in
 79  slink:VkDebugReportCallbackCreateInfoEXT::pname:flags, specifying events
 80  which cause a debug report, are:
 81  
 82  include::{generated}/api/enums/VkDebugReportFlagBitsEXT.txt[]
 83  
 84    * ename:VK_DEBUG_REPORT_ERROR_BIT_EXT specifies that the application has
 85      violated a valid usage condition of the specification.
 86    * ename:VK_DEBUG_REPORT_WARNING_BIT_EXT specifies use of Vulkan that may:
 87      expose an app bug.
 88      Such cases may not be immediately harmful, such as a fragment shader
 89      outputting to a location with no attachment.
 90      Other cases may: point to behavior that is almost certainly bad when
 91      unintended such as using an image whose memory has not been filled.
 92      In general if you see a warning but you know that the behavior is
 93      intended/desired, then simply ignore the warning.
 94    * ename:VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT specifies a
 95      potentially non-optimal use of Vulkan, e.g. using
 96      flink:vkCmdClearColorImage when setting
 97      slink:VkAttachmentDescription::pname:loadOp to
 98      ename:VK_ATTACHMENT_LOAD_OP_CLEAR would have worked.
 99    * ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT specifies an informational
100      message such as resource details that may be handy when debugging an
101      application.
102    * ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT specifies diagnostic information
103      from the implementation and layers.
104  
105  --
106  
107  [open,refpage='VkDebugReportFlagsEXT',desc='Bitmask of VkDebugReportFlagBitsEXT',type='flags']
108  --
109  include::{generated}/api/flags/VkDebugReportFlagsEXT.txt[]
110  
111  tname:VkDebugReportFlagsEXT is a bitmask type for setting a mask of zero or
112  more elink:VkDebugReportFlagBitsEXT.
113  --
114  
115  [open,refpage='PFN_vkDebugReportCallbackEXT',desc='Application-defined debug report callback function',type='funcpointers']
116  --
117  
118  The prototype for the
119  slink:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback function
120  implemented by the application is:
121  
122  include::{generated}/api/funcpointers/PFN_vkDebugReportCallbackEXT.txt[]
123  
124    * pname:flags specifies the elink:VkDebugReportFlagBitsEXT that triggered
125      this callback.
126    * pname:objectType is a elink:VkDebugReportObjectTypeEXT value specifying
127      the type of object being used or created at the time the event was
128      triggered.
129    * pname:object is the object where the issue was detected.
130      If pname:objectType is ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT,
131      pname:object is undefined:.
132    * pname:location is a component (layer, driver, loader) defined value that
133      specifies the _location_ of the trigger.
134      This is an optional: value.
135    * pname:messageCode is a layer-defined value indicating what test
136      triggered this callback.
137    * pname:pLayerPrefix is a null-terminated string that is an abbreviation
138      of the name of the component making the callback.
139      pname:pLayerPrefix is only valid for the duration of the callback.
140    * pname:pMessage is a null-terminated string detailing the trigger
141      conditions.
142      pname:pMessage is only valid for the duration of the callback.
143    * pname:pUserData is the user data given when the
144      slink:VkDebugReportCallbackEXT was created.
145  
146  The callback must: not call fname:vkDestroyDebugReportCallbackEXT.
147  
148  The callback returns a basetype:VkBool32, which is interpreted in a
149  layer-specified manner.
150  The application should: always return ename:VK_FALSE.
151  The ename:VK_TRUE value is reserved for use in layer development.
152  
153  pname:object must: be a Vulkan object or dlink:VK_NULL_HANDLE.
154  If pname:objectType is not ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT and
155  pname:object is not dlink:VK_NULL_HANDLE, pname:object must: be a Vulkan
156  object of the corresponding type associated with pname:objectType as defined
157  in <<debug-report-object-types>>.
158  --
159  
160  [open,refpage='VkDebugReportObjectTypeEXT',desc='Specify the type of an object handle',type='enums']
161  --
162  
163  Possible values passed to the pname:objectType parameter of the callback
164  function specified by
165  slink:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback, specifying the
166  type of object handle being reported, are:
167  
168  include::{generated}/api/enums/VkDebugReportObjectTypeEXT.txt[]
169  
170  [[debug-report-object-types]]
171  .VkDebugReportObjectTypeEXT and Vulkan Handle Relationship
172  [width="80%",cols="<35,<23",options="header"]
173  |====
174  | elink:VkDebugReportObjectTypeEXT                            | Vulkan Handle Type
175  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT               | Unknown/Undefined Handle
176  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT              | slink:VkInstance
177  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT       | slink:VkPhysicalDevice
178  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT                | slink:VkDevice
179  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT                 | slink:VkQueue
180  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT             | slink:VkSemaphore
181  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT        | slink:VkCommandBuffer
182  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT                 | slink:VkFence
183  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT         | slink:VkDeviceMemory
184  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT                | slink:VkBuffer
185  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT                 | slink:VkImage
186  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT                 | slink:VkEvent
187  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT            | slink:VkQueryPool
188  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT           | slink:VkBufferView
189  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT            | slink:VkImageView
190  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT         | slink:VkShaderModule
191  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT        | slink:VkPipelineCache
192  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT       | slink:VkPipelineLayout
193  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT           | slink:VkRenderPass
194  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT              | slink:VkPipeline
195  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT | slink:VkDescriptorSetLayout
196  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT               | slink:VkSampler
197  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT       | slink:VkDescriptorPool
198  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT        | slink:VkDescriptorSet
199  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT           | slink:VkFramebuffer
200  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT          | slink:VkCommandPool
201  ifdef::VK_KHR_surface[]
202  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT           | slink:VkSurfaceKHR
203  endif::VK_KHR_surface[]
204  ifdef::VK_KHR_surface[]
205  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT         | slink:VkSwapchainKHR
206  endif::VK_KHR_surface[]
207  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT | slink:VkDebugReportCallbackEXT
208  ifdef::VK_KHR_display[]
209  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT           | slink:VkDisplayKHR
210  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT      | slink:VkDisplayModeKHR
211  endif::VK_KHR_display[]
212  ifdef::VK_NVX_device_generated_commands[]
213  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_OBJECT_TABLE_NVX_EXT | slink:VkObjectTableNVX
214  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NVX_EXT | slink:VkIndirectCommandsLayoutNVX
215  endif::VK_NVX_device_generated_commands[]
216  ifndef::VK_VERSION_1_1[]
217  ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
218  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT | slink:VkDescriptorUpdateTemplate
219  endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
220  endif::VK_VERSION_1_1[]
221  ifdef::VK_VERSION_1_1[]
222  | ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT | slink:VkDescriptorUpdateTemplate
223  endif::VK_VERSION_1_1[]
224  |====
225  
226  [NOTE]
227  .Note
228  ====
229  The primary expected use of ename:VK_ERROR_VALIDATION_FAILED_EXT is for
230  validation layer testing.
231  It is not expected that an application would see this error code during
232  normal use of the validation layers.
233  ====
234  
235  --
236  
237  [open,refpage='vkDebugReportMessageEXT',desc='Inject a message into a debug stream',type='protos']
238  --
239  
240  To inject its own messages into the debug stream, call:
241  
242  include::{generated}/api/protos/vkDebugReportMessageEXT.txt[]
243  
244    * pname:instance is the debug stream's slink:VkInstance.
245    * pname:flags specifies the elink:VkDebugReportFlagBitsEXT classification
246      of this event/message.
247    * pname:objectType is a elink:VkDebugReportObjectTypeEXT specifying the
248      type of object being used or created at the time the event was
249      triggered.
250    * pname:object this is the object where the issue was detected.
251      pname:object can: be dlink:VK_NULL_HANDLE if there is no object
252      associated with the event.
253    * pname:location is an application defined value.
254    * pname:messageCode is an application defined value.
255    * pname:pLayerPrefix is the abbreviation of the component making this
256      event/message.
257    * pname:pMessage is a null-terminated string detailing the trigger
258      conditions.
259  
260  The call will propagate through the layers and generate callback(s) as
261  indicated by the message's flags.
262  The parameters are passed on to the callback in addition to the
263  pname:pUserData value that was defined at the time the callback was
264  registered.
265  
266  .Valid Usage
267  ****
268    * [[VUID-vkDebugReportMessageEXT-object-01241]]
269      pname:object must: be a Vulkan object or dlink:VK_NULL_HANDLE
270    * [[VUID-vkDebugReportMessageEXT-objectType-01498]]
271      If pname:objectType is not ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT
272      and pname:object is not dlink:VK_NULL_HANDLE, pname:object must: be a
273      Vulkan object of the corresponding type associated with pname:objectType
274      as defined in <<debug-report-object-types>>.
275  ****
276  
277  include::{generated}/validity/protos/vkDebugReportMessageEXT.txt[]
278  --
279  
280  [open,refpage='vkDestroyDebugReportCallbackEXT',desc='Destroy a debug report callback object',type='protos']
281  --
282  
283  To destroy a sname:VkDebugReportCallbackEXT object, call:
284  
285  include::{generated}/api/protos/vkDestroyDebugReportCallbackEXT.txt[]
286  
287    * pname:instance the instance where the callback was created.
288    * pname:callback the slink:VkDebugReportCallbackEXT object to destroy.
289      pname:callback is an externally synchronized object and must: not be
290      used on more than one thread at a time.
291      This means that fname:vkDestroyDebugReportCallbackEXT must: not be
292      called when a callback is active.
293    * pname:pAllocator controls host memory allocation as described in the
294      <<memory-allocation, Memory Allocation>> chapter.
295  
296  .Valid Usage
297  ****
298    * [[VUID-vkDestroyDebugReportCallbackEXT-instance-01242]]
299      If sname:VkAllocationCallbacks were provided when pname:callback was
300      created, a compatible set of callbacks must: be provided here
301    * [[VUID-vkDestroyDebugReportCallbackEXT-instance-01243]]
302      If no sname:VkAllocationCallbacks were provided when pname:callback was
303      created, pname:pAllocator must: be `NULL`
304  ****
305  
306  include::{generated}/validity/protos/vkDestroyDebugReportCallbackEXT.txt[]
307  --