[appendix] Debug Report Extension ====================== Due to the nature of the Vulkan interface, there is very little error information available to the developer/application. By enabling optional validation layers and using the Debug Report extension a developer has much more detailed feedback on the application's use of Vulkan. This extension adds two entry points (fname:vkCreateDebugReportCallbackEXT, fname:vkDestroyDebugReportCallbackEXT) and an extension structure that together define a way for layers and the implementation to call back to the application for events of interest to the application. An application enables this extension by including +"VK_EXT_debug_report"+ in the list of pname:ppEnabledExtensionNames at flink:vkCreateInstance. Layers indicating support will return +VK_EXT_debug_report+ in the extension list queried via flink:vkEnumerateInstanceExtensionProperties. To register a callback, an application uses fname:vkCreateDebugReportCallbackEXT. include::../api/protos/vkCreateDebugReportCallbackEXT.txt[] * pname:instance the instance the callback will be logged on. * pname:pCreateInfo points to a sname:VkDebugReportCallbackCreateInfoEXT structure which defines the conditions under which this callback will be called. * pname:pCallback is a pointer to record the sname:VkDebugReportCallbackEXT object created. include::../validity/protos/vkCreateDebugReportCallbackEXT.txt[] The definition of sname:VkDebugReportCallbackCreateInfoEXT is: include::../api/structs/VkDebugReportCallbackCreateInfoEXT.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:flags indicate which event(s) will cause this callback to be called. Flags are interpreted as bit fields and multiple may be set. Bits which can: be set include: + -- // refBegin VkDebugReportCallbackCreateInfoEXT - Bitmask specifying events which cause a debug report callback include::../api/enums/VkDebugReportFlagBitsEXT.txt[] * ename:VK_DEBUG_REPORT_ERROR_BIT_EXT indicates an error that may cause undefined results, including an application crash. * ename:VK_DEBUG_REPORT_WARNING_BIT_EXT indicates an unexpected use. E.g. Not destroying objects prior to destroying the containing object or potential inconsistencies between descriptor set layout and the layout in the corresponding shader, etc. * ename:VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT indicates a potentially non-optimal use of Vulkan. E.g. using fname:vkCmdClearImage when a RenderPass load_op would have worked. * ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT indicates an informational message such as resource details that may be handy when debugging an application. * ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT indicates diagnostic information from the loader and layers. * pname:pfnCallback is the application callback function to call. * pname:pUserData is user data to be passed to the callback. -- For each sname:VkDebugReportCallbackEXT that is created the flags determine when that function is called. A callback will be made for issues that match any bit set in its flags. The callback will come directly from the component that detected the event, unless some other layer intercepts the calls for its own purposes (filter them in different way, log to system error log, etc.) An application may receive multiple callbacks if multiple sname:VkDebugReportCallbackEXT objects were created. A callback will always be executed in the same thread as the originating Vulkan call. A callback may be called from multiple threads simultaneously (if the application is making Vulkan calls from multiple threads). include::../validity/structs/VkDebugReportCallbackCreateInfoEXT.txt[] // refBegin PFN_vkDebugReportCallbackEXT application-defined debug report callback function The prototype for the callback function implemented by the app is: include::../api/funcpointers/PFN_vkDebugReportCallbackEXT.txt[] * pname:flags indicates the ename:VkDebugReportFlagBitsEXT that triggered this callback. * pname:objType the type of object being used / created at the time the event was triggered. Object types are defined by ename:VkDebugReportObjectTypeEXT. * pname:object gives the object where the issue was detected. pname:object may be ename:VK_NULL_OBJECT if there is no object associated with the event. * pname:location is a component (layer, driver, loader) defined value that indicates the _location_ of the trigger. This is an optional value. * pname:messageCode a layer defined value indicating what test triggered this callback. * pname:pLayerPrefix is the abbreviation of the component making the callback. * pname:pMessage is a null-terminated string detailing the trigger conditions. * pname:pUserData is the user data given when the DebugReportCallback was created. The callback returns a basetype:VkBool32 that indicates to the calling layer if the Vulkan call should be aborted or not. Applications should always return ename:VK_FALSE so that they see the same behavior with and without validation layers enabled. If the application returns ename:VK_TRUE from it's callback and the Vulkan call being aborted returns a basetype:VkResult, the layer will return ename:VK_ERROR_VALIDATION_FAILED_EXT. [NOTE] .Note ==== The primary expected use of ename:VK_ERROR_VALIDATION_FAILED_EXT is for validation layer testing. It's not expected that an application would see this this error code during normal use of the validation layers. ==== // refEnd PFN_vkDebugReportCallbackEXT To inject its own messages into the debug stream an application uses fname:vkDebugReportMessageEXT. include::../api/protos/vkDebugReportMessageEXT.txt[] * pname:instance the instance the callback will be logged on. * pname:flags indicates the ename:VkDebugReportFlagBitsEXT that triggered this callback. * pname:objType is the type of object being used / created at the time the event was triggered. Object types are defined by ename:VkDebugReportObjectTypeEXT. * pname:object is object where the issue was detected. pname:object may be ename:VK_NULL_OBJECT if there is no object associated with the event. * pname:location is a component (layer, driver, loader) defined value that indicates the _location_ of the trigger. This is an optional value. * pname:messageCode is a layer defined value indicating what test triggered this callback. * pname:pLayerPrefix is the abbreviation of the component making the callback. * pname:pMessage is a null-terminated string detailing the trigger conditions. The call will propagate through the layers and cause a callback to the application. The parameters are passed on to the callback in addition to the pname:pUserData value that was defined at the time the callback was registered. include::../validity/protos/vkDebugReportMessageEXT.txt[] To destroy a sname:VkDebugReportCallbackEXT object an application calls fname:vkDestroyDebugReportCallbackEXT. include::../api/protos/vkDestroyDebugReportCallbackEXT.txt[] * pname:instance the instance where the callback was created. * pname:callback the sname:VkDebugReportCallbackEXT object to destroy. include::../validity/protos/vkDestroyDebugReportCallbackEXT.txt[] Using the ename:VK_EXT_debug_report allows an application to register multiple callbacks with the validation layers. Some callbacks may log the information to a file, others may cause a debug break point or other application defined behavior. An application can register callbacks even when no validation layers are enabled, but they will only be called for loader and, if implemented, driver events. To capture issues found while creating or destroying an instance an application can link a sname:VkDebugReportCallbackCreateInfoEXT structure to the pNext element of the sname:VkInstanceCreateInfo structure given to fname:vkCreateInstance. This callback is only valid for the duration of the fname:vkCreateInstance and the fname:vkDestroyInstance call. Use fname:vkCreateDebugReportCallbackEXT to create persistent callback objects. Example uses: Create three callback objects. One will log errors and warnings to the debug console using Windows OutputDebugString. The second will cause the debugger to break at that callback when an error happens and the third will log warnings to stdout. [source,{basebackend@docbook:c++:cpp}] ------------------------------------------------------------------------------ VkResult res; VkDebugReportCallbackEXT cb1, cb2, cb3; VkDebugReportCallbackCreateInfoEXT callback1 = { VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, // sType NULL, // pNext VK_DEBUG_REPORT_ERROR_BIT_EXT | // flags VK_DEBUG_REPORT_WARNING_BIT_EXT, myOutputDebugString, // pfnCallback NULL // pUserData }; res = vkCreateDebugReportCallbackEXT(instance, &callback1, &cb1); if (res != VK_SUCCESS) /* Do error handling for VK_ERROR_OUT_OF_MEMORY */ callback.flags = VK_DEBUG_REPORT_ERROR_BIT_EXT; callback.pfnCallback = myDebugBreak; callback.pUserData = NULL; res = vkCreateDebugReportCallbackEXT(instance, &callback, &cb2); if (res != VK_SUCCESS) /* Do error handling for VK_ERROR_OUT_OF_MEMORY */ VkDebugReportCallbackCreateInfoEXT callback3 = { VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, // sType NULL, // pNext VK_DEBUG_REPORT_WARNING_BIT_EXT, // flags mystdOutLogger, // pfnCallback NULL // pUserData }; res = vkCreateDebugReportCallbackEXT(instance, &callback3, &cb3); if (res != VK_SUCCESS) /* Do error handling for VK_ERROR_OUT_OF_MEMORY */ ... /* remove callbacks when cleaning up */ vkDestroyDebugReportCallbackEXT(instance, cb1); vkDestroyDebugReportCallbackEXT(instance, cb2); vkDestroyDebugReportCallbackEXT(instance, cb3); ------------------------------------------------------------------------------ [NOTE] .Note ==== In the initial release of the +VK_EXT_debug_report extension+, the token ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT was used. Starting in ename:VK_EXT_DEBUG_REPORT_SPEC_VERSION 2 of the extension branch, ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT is used instead for consistency with Vulkan naming rules. The older enum is still available for backwards compatibility. ====