Class EXTDebugReport
- java.lang.Object
-
- org.lwjgl.vulkan.EXTDebugReport
-
public class EXTDebugReport extends java.lang.Object
Due to the nature of the Vulkan interface, there is very little error information available to the developer and application. By enabling optional validation layers and using theVK_EXT_debug_report
extension, developers can obtain much more detailed feedback on the application's use of Vulkan. This extension defines a way for layers and the implementation to call back to the application for events of interest to the application.Examples
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 events that occur while creating or destroying an instance an application can link a
VkDebugReportCallbackCreateInfoEXT
structure to thepNext
element of theVkInstanceCreateInfo
structure given toCreateInstance
. This callback is only valid for the duration of theCreateInstance
and theDestroyInstance
call. UseCreateDebugReportCallbackEXT
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.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);
- Name String
VK_EXT_debug_report
- Extension Type
- Instance extension
- Registered Extension Number
- 12
- Revision
- 9
- Extension and Version Dependencies
- Requires Vulkan 1.0
- Deprecation state
- Deprecated by VK_EXT_debug_utils extension
- Contact
- Courtney Goeltzenleuchter courtney-g
- Last Modified Date
- 2017-09-12
- IP Status
- No known IP claims.
- Contributors
- Courtney Goeltzenleuchter, LunarG
- Dan Ginsburg, Valve
- Jon Ashburn, LunarG
- Mark Lobodzinski, LunarG
-
-
Field Summary
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static int
nvkCreateDebugReportCallbackEXT(VkInstance instance, long pCreateInfo, long pAllocator, long pCallback)
Unsafe version of:CreateDebugReportCallbackEXT
static void
nvkDebugReportMessageEXT(VkInstance instance, int flags, int objectType, long object, long location, int messageCode, long pLayerPrefix, long pMessage)
Unsafe version of:DebugReportMessageEXT
static void
nvkDestroyDebugReportCallbackEXT(VkInstance instance, long callback, long pAllocator)
Unsafe version of:DestroyDebugReportCallbackEXT
static int
vkCreateDebugReportCallbackEXT(VkInstance instance, VkDebugReportCallbackCreateInfoEXT pCreateInfo, VkAllocationCallbacks pAllocator, long[] pCallback)
Array version of:CreateDebugReportCallbackEXT
static int
vkCreateDebugReportCallbackEXT(VkInstance instance, VkDebugReportCallbackCreateInfoEXT pCreateInfo, VkAllocationCallbacks pAllocator, java.nio.LongBuffer pCallback)
Create a debug report callback object.static void
vkDebugReportMessageEXT(VkInstance instance, int flags, int objectType, long object, long location, int messageCode, java.lang.CharSequence pLayerPrefix, java.lang.CharSequence pMessage)
Inject a message into a debug stream.static void
vkDebugReportMessageEXT(VkInstance instance, int flags, int objectType, long object, long location, int messageCode, java.nio.ByteBuffer pLayerPrefix, java.nio.ByteBuffer pMessage)
Inject a message into a debug stream.static void
vkDestroyDebugReportCallbackEXT(VkInstance instance, long callback, VkAllocationCallbacks pAllocator)
Destroy a debug report callback object.
-
-
-
Field Detail
-
VK_EXT_DEBUG_REPORT_SPEC_VERSION
The extension specification version.
-
VK_EXT_DEBUG_REPORT_EXTENSION_NAME
The extension name.
-
VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT
ExtendsVkStructureType
.Enum values:
-
VK_ERROR_VALIDATION_FAILED_EXT
ExtendsVkResult
.
-
VK_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT
ExtendsVkObjectType
.
-
VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT
ExtendsVkDebugReportObjectTypeEXT
.Enum values:
-
VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_OBJECT_TABLE_NVX_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NVX_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_VALIDATION_CACHE_EXT_EXT, VK_DEBUG_REPORT_OBJECT_TYPE_VALIDATION_CACHE_EXT
VkDebugReportObjectTypeEXT - Specify the type of an object handleDescription
VkDebugReportObjectTypeEXT and Vulkan Handle Relationship
Note
The primary expected use of
ERROR_VALIDATION_FAILED_EXT
is for validation layer testing. It is not expected that an application would see this error code during normal use of the validation layers.See Also
VkDebugMarkerObjectNameInfoEXT
,VkDebugMarkerObjectTagInfoEXT
,DebugReportMessageEXT
Enum values:
-
VK_DEBUG_REPORT_INFORMATION_BIT_EXT, VK_DEBUG_REPORT_WARNING_BIT_EXT, VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT, VK_DEBUG_REPORT_ERROR_BIT_EXT, VK_DEBUG_REPORT_DEBUG_BIT_EXT
VkDebugReportFlagBitsEXT - Bitmask specifying events which cause a debug report callbackDescription
DEBUG_REPORT_ERROR_BIT_EXT
specifies that the application has violated a valid usage condition of the specification.DEBUG_REPORT_WARNING_BIT_EXT
specifies use of Vulkan that may expose an app bug. Such cases may not be immediately harmful, such as a fragment shader outputting to a location with no attachment. Other cases may point to behavior that is almost certainly bad when unintended such as using an image whose memory has not been filled. In general if you see a warning but you know that the behavior is intended/desired, then simply ignore the warning.DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT
specifies a potentially non-optimal use of Vulkan, e.g. usingCmdClearColorImage
when settingVkAttachmentDescription
::loadOp
toATTACHMENT_LOAD_OP_CLEAR
would have worked.DEBUG_REPORT_INFORMATION_BIT_EXT
specifies an informational message such as resource details that may be handy when debugging an application.DEBUG_REPORT_DEBUG_BIT_EXT
specifies diagnostic information from the implementation and layers.
See Also
VkDebugReportFlagsEXT
-
-
Method Detail
-
nvkCreateDebugReportCallbackEXT
public static int nvkCreateDebugReportCallbackEXT(VkInstance instance, long pCreateInfo, long pAllocator, long pCallback)
Unsafe version of:CreateDebugReportCallbackEXT
-
vkCreateDebugReportCallbackEXT
public static int vkCreateDebugReportCallbackEXT(VkInstance instance, VkDebugReportCallbackCreateInfoEXT pCreateInfo, @Nullable VkAllocationCallbacks pAllocator, java.nio.LongBuffer pCallback)
Create a debug report callback object.C Specification
Debug report callbacks give more detailed feedback on the application's use of Vulkan when events of interest occur.
To register a debug report callback, an application uses
CreateDebugReportCallbackEXT
.VkResult vkCreateDebugReportCallbackEXT( VkInstance instance, const VkDebugReportCallbackCreateInfoEXT* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkDebugReportCallbackEXT* pCallback);
Valid Usage (Implicit)
instance
must be a validVkInstance
handlepCreateInfo
must be a valid pointer to a validVkDebugReportCallbackCreateInfoEXT
structure- If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validVkAllocationCallbacks
structure pCallback
must be a valid pointer to aVkDebugReportCallbackEXT
handle
Return Codes
- On success, this command returns
- On failure, this command returns
See Also
- Parameters:
instance
- the instance the callback will be logged on.pCreateInfo
- points to aVkDebugReportCallbackCreateInfoEXT
structure which defines the conditions under which this callback will be called.pAllocator
- controls host memory allocation as described in the Memory Allocation chapter.pCallback
- a pointer to record theVkDebugReportCallbackEXT
object created.
-
nvkDestroyDebugReportCallbackEXT
public static void nvkDestroyDebugReportCallbackEXT(VkInstance instance, long callback, long pAllocator)
Unsafe version of:DestroyDebugReportCallbackEXT
-
vkDestroyDebugReportCallbackEXT
public static void vkDestroyDebugReportCallbackEXT(VkInstance instance, long callback, @Nullable VkAllocationCallbacks pAllocator)
Destroy a debug report callback object.C Specification
To destroy a
VkDebugReportCallbackEXT
object, call:void vkDestroyDebugReportCallbackEXT( VkInstance instance, VkDebugReportCallbackEXT callback, const VkAllocationCallbacks* pAllocator);
Valid Usage
- If
VkAllocationCallbacks
were provided whencallback
was created, a compatible set of callbacks must be provided here - If no
VkAllocationCallbacks
were provided whencallback
was created,pAllocator
must beNULL
Valid Usage (Implicit)
instance
must be a validVkInstance
handlecallback
must be a validVkDebugReportCallbackEXT
handle- If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validVkAllocationCallbacks
structure callback
must have been created, allocated, or retrieved frominstance
Host Synchronization
- Host access to
callback
must be externally synchronized
See Also
- Parameters:
instance
- the instance where the callback was created.callback
- theVkDebugReportCallbackEXT
object to destroy.callback
is an externally synchronized object and must not be used on more than one thread at a time. This means thatvkDestroyDebugReportCallbackEXT
must not be called when a callback is active.pAllocator
- controls host memory allocation as described in the Memory Allocation chapter.
- If
-
nvkDebugReportMessageEXT
public static void nvkDebugReportMessageEXT(VkInstance instance, int flags, int objectType, long object, long location, int messageCode, long pLayerPrefix, long pMessage)
Unsafe version of:DebugReportMessageEXT
-
vkDebugReportMessageEXT
public static void vkDebugReportMessageEXT(VkInstance instance, int flags, int objectType, long object, long location, int messageCode, java.nio.ByteBuffer pLayerPrefix, java.nio.ByteBuffer pMessage) public static void vkDebugReportMessageEXT(VkInstance instance, int flags, int objectType, long object, long location, int messageCode, java.lang.CharSequence pLayerPrefix, java.lang.CharSequence pMessage)
Inject a message into a debug stream.C Specification
To inject its own messages into the debug stream, call:
void vkDebugReportMessageEXT( VkInstance instance, VkDebugReportFlagsEXT flags, VkDebugReportObjectTypeEXT objectType, uint64_t object, size_t location, int32_t messageCode, const char* pLayerPrefix, const char* pMessage);
Description
The call will propagate through the layers and generate callback(s) as indicated by the message's flags. The parameters are passed on to the callback in addition to the
pUserData
value that was defined at the time the callback was registered.Valid Usage
object
must be a Vulkan object orNULL_HANDLE
- If
objectType
is notDEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT
andobject
is notNULL_HANDLE
,object
must be a Vulkan object of the corresponding type associated withobjectType
as defined inVkDebugReportObjectTypeEXT
and Vulkan Handle Relationship.
Valid Usage (Implicit)
instance
must be a validVkInstance
handleflags
must be a valid combination ofVkDebugReportFlagBitsEXT
valuesflags
must not be 0objectType
must be a validVkDebugReportObjectTypeEXT
valuepLayerPrefix
must be a null-terminated UTF-8 stringpMessage
must be a null-terminated UTF-8 string
- Parameters:
instance
- the debug stream’sVkInstance
.flags
- specifies theVkDebugReportFlagBitsEXT
classification of this event/message.objectType
- aVkDebugReportObjectTypeEXT
specifying the type of object being used or created at the time the event was triggered.object
- this is the object where the issue was detected.object
can beNULL_HANDLE
if there is no object associated with the event.location
- an application defined value.messageCode
- an application defined value.pLayerPrefix
- the abbreviation of the component making this event/message.pMessage
- a null-terminated string detailing the trigger conditions.
-
vkCreateDebugReportCallbackEXT
public static int vkCreateDebugReportCallbackEXT(VkInstance instance, VkDebugReportCallbackCreateInfoEXT pCreateInfo, @Nullable VkAllocationCallbacks pAllocator, long[] pCallback)
Array version of:CreateDebugReportCallbackEXT
-
-