42. Debugging
To aid developers in tracking down errors in the application’s use of Vulkan, particularly in combination with an external debugger or profiler, debugging extensions may be available.
The VkObjectType enumeration defines values, each of which corresponds to a specific Vulkan handle type. These values can be used to associate debug information with a particular type of object through one or more extensions.
// Provided by VK_VERSION_1_0
typedef enum VkObjectType {
VK_OBJECT_TYPE_UNKNOWN = 0,
VK_OBJECT_TYPE_INSTANCE = 1,
VK_OBJECT_TYPE_PHYSICAL_DEVICE = 2,
VK_OBJECT_TYPE_DEVICE = 3,
VK_OBJECT_TYPE_QUEUE = 4,
VK_OBJECT_TYPE_SEMAPHORE = 5,
VK_OBJECT_TYPE_COMMAND_BUFFER = 6,
VK_OBJECT_TYPE_FENCE = 7,
VK_OBJECT_TYPE_DEVICE_MEMORY = 8,
VK_OBJECT_TYPE_BUFFER = 9,
VK_OBJECT_TYPE_IMAGE = 10,
VK_OBJECT_TYPE_EVENT = 11,
VK_OBJECT_TYPE_QUERY_POOL = 12,
VK_OBJECT_TYPE_BUFFER_VIEW = 13,
VK_OBJECT_TYPE_IMAGE_VIEW = 14,
VK_OBJECT_TYPE_SHADER_MODULE = 15,
VK_OBJECT_TYPE_PIPELINE_CACHE = 16,
VK_OBJECT_TYPE_PIPELINE_LAYOUT = 17,
VK_OBJECT_TYPE_RENDER_PASS = 18,
VK_OBJECT_TYPE_PIPELINE = 19,
VK_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT = 20,
VK_OBJECT_TYPE_SAMPLER = 21,
VK_OBJECT_TYPE_DESCRIPTOR_POOL = 22,
VK_OBJECT_TYPE_DESCRIPTOR_SET = 23,
VK_OBJECT_TYPE_FRAMEBUFFER = 24,
VK_OBJECT_TYPE_COMMAND_POOL = 25,
// Provided by VK_VERSION_1_1
VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION = 1000156000,
// Provided by VK_VERSION_1_1
VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE = 1000085000,
// Provided by VK_VERSION_1_3
VK_OBJECT_TYPE_PRIVATE_DATA_SLOT = 1000295000,
// Provided by VK_KHR_surface
VK_OBJECT_TYPE_SURFACE_KHR = 1000000000,
// Provided by VK_KHR_swapchain
VK_OBJECT_TYPE_SWAPCHAIN_KHR = 1000001000,
// Provided by VK_KHR_display
VK_OBJECT_TYPE_DISPLAY_KHR = 1000002000,
// Provided by VK_KHR_display
VK_OBJECT_TYPE_DISPLAY_MODE_KHR = 1000002001,
// Provided by VK_KHR_video_queue
VK_OBJECT_TYPE_VIDEO_SESSION_KHR = 1000023000,
// Provided by VK_KHR_video_queue
VK_OBJECT_TYPE_VIDEO_SESSION_PARAMETERS_KHR = 1000023001,
// Provided by VK_KHR_acceleration_structure
VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR = 1000150000,
// Provided by VK_KHR_deferred_host_operations
VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR = 1000268000,
// Provided by VK_KHR_descriptor_update_template
VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR = VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_KHR = VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION,
} VkObjectType;
VkObjectType | Vulkan Handle Type |
---|---|
|
Unknown/Undefined Handle |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If this Specification was generated with any such extensions included, they will be described in the remainder of this chapter.
42.1. Active Tooling Information
Information about tools providing debugging, profiling, or similar services, active for a given physical device, can be obtained by calling:
// Provided by VK_VERSION_1_3
VkResult vkGetPhysicalDeviceToolProperties(
VkPhysicalDevice physicalDevice,
uint32_t* pToolCount,
VkPhysicalDeviceToolProperties* pToolProperties);
-
physicalDevice
is the handle to the physical device to query for active tools. -
pToolCount
is a pointer to an integer describing the number of tools active onphysicalDevice
. -
pToolProperties
is eitherNULL
or a pointer to an array of VkPhysicalDeviceToolProperties structures.
If pToolProperties
is NULL
, then the number of tools currently
active on physicalDevice
is returned in pToolCount
.
Otherwise, pToolCount
must point to a variable set by the user to the
number of elements in the pToolProperties
array, and on return the
variable is overwritten with the number of structures actually written to
pToolProperties
.
If pToolCount
is less than the number of currently active tools, at
most pToolCount
structures will be written.
The count and properties of active tools may change in response to events outside the scope of the specification. An application should assume these properties might change at any given time.
The VkPhysicalDeviceToolProperties structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkPhysicalDeviceToolProperties {
VkStructureType sType;
void* pNext;
char name[VK_MAX_EXTENSION_NAME_SIZE];
char version[VK_MAX_EXTENSION_NAME_SIZE];
VkToolPurposeFlags purposes;
char description[VK_MAX_DESCRIPTION_SIZE];
char layer[VK_MAX_EXTENSION_NAME_SIZE];
} VkPhysicalDeviceToolProperties;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
name
is a null-terminated UTF-8 string containing the name of the tool. -
version
is a null-terminated UTF-8 string containing the version of the tool. -
purposes
is a bitmask of VkToolPurposeFlagBits which is populated with purposes supported by the tool. -
description
is a null-terminated UTF-8 string containing a description of the tool. -
layer
is a null-terminated UTF-8 string containing the name of the layer implementing the tool, if the tool is implemented in a layer - otherwise it may be an empty string.
Bits which can be set in
VkPhysicalDeviceToolProperties::purposes
, specifying the
purposes of an active tool, are:
// Provided by VK_VERSION_1_3
typedef enum VkToolPurposeFlagBits {
VK_TOOL_PURPOSE_VALIDATION_BIT = 0x00000001,
VK_TOOL_PURPOSE_PROFILING_BIT = 0x00000002,
VK_TOOL_PURPOSE_TRACING_BIT = 0x00000004,
VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT = 0x00000008,
VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT = 0x00000010,
VK_TOOL_PURPOSE_VALIDATION_BIT_EXT = VK_TOOL_PURPOSE_VALIDATION_BIT,
VK_TOOL_PURPOSE_PROFILING_BIT_EXT = VK_TOOL_PURPOSE_PROFILING_BIT,
VK_TOOL_PURPOSE_TRACING_BIT_EXT = VK_TOOL_PURPOSE_TRACING_BIT,
VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT_EXT = VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT,
VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT_EXT = VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT,
} VkToolPurposeFlagBits;
-
VK_TOOL_PURPOSE_VALIDATION_BIT
specifies that the tool provides validation of API usage. -
VK_TOOL_PURPOSE_PROFILING_BIT
specifies that the tool provides profiling of API usage. -
VK_TOOL_PURPOSE_TRACING_BIT
specifies that the tool is capturing data about the application’s API usage, including anything from simple logging to capturing data for later replay. -
VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT
specifies that the tool provides additional API features/extensions on top of the underlying implementation. -
VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT
specifies that the tool modifies the API features/limits/extensions presented to the application.
// Provided by VK_VERSION_1_3
typedef VkFlags VkToolPurposeFlags;
VkToolPurposeFlags is a bitmask type for setting a mask of zero or more VkToolPurposeFlagBits.