Vulkan Logo

    36. 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,
} VkObjectType;
    Table 62. VkObjectType and Vulkan Handle Relationship
    VkObjectType Vulkan Handle Type

    VK_OBJECT_TYPE_UNKNOWN

    Unknown/Undefined Handle

    VK_OBJECT_TYPE_INSTANCE

    VkInstance

    VK_OBJECT_TYPE_PHYSICAL_DEVICE

    VkPhysicalDevice

    VK_OBJECT_TYPE_DEVICE

    VkDevice

    VK_OBJECT_TYPE_QUEUE

    VkQueue

    VK_OBJECT_TYPE_SEMAPHORE

    VkSemaphore

    VK_OBJECT_TYPE_COMMAND_BUFFER

    VkCommandBuffer

    VK_OBJECT_TYPE_FENCE

    VkFence

    VK_OBJECT_TYPE_DEVICE_MEMORY

    VkDeviceMemory

    VK_OBJECT_TYPE_BUFFER

    VkBuffer

    VK_OBJECT_TYPE_IMAGE

    VkImage

    VK_OBJECT_TYPE_EVENT

    VkEvent

    VK_OBJECT_TYPE_QUERY_POOL

    VkQueryPool

    VK_OBJECT_TYPE_BUFFER_VIEW

    VkBufferView

    VK_OBJECT_TYPE_IMAGE_VIEW

    VkImageView

    VK_OBJECT_TYPE_SHADER_MODULE

    VkShaderModule

    VK_OBJECT_TYPE_PIPELINE_CACHE

    VkPipelineCache

    VK_OBJECT_TYPE_PIPELINE_LAYOUT

    VkPipelineLayout

    VK_OBJECT_TYPE_RENDER_PASS

    VkRenderPass

    VK_OBJECT_TYPE_PIPELINE

    VkPipeline

    VK_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT

    VkDescriptorSetLayout

    VK_OBJECT_TYPE_SAMPLER

    VkSampler

    VK_OBJECT_TYPE_DESCRIPTOR_POOL

    VkDescriptorPool

    VK_OBJECT_TYPE_DESCRIPTOR_SET

    VkDescriptorSet

    VK_OBJECT_TYPE_FRAMEBUFFER

    VkFramebuffer

    VK_OBJECT_TYPE_COMMAND_POOL

    VkCommandPool

    VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION

    VkSamplerYcbcrConversion

    VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE

    VkDescriptorUpdateTemplate

    VK_OBJECT_TYPE_PRIVATE_DATA_SLOT

    VkPrivateDataSlot

    If this Specification was generated with any such extensions included, they will be described in the remainder of this chapter.

    36.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 on physicalDevice.

    • pToolProperties is either NULL 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.

    Valid Usage (Implicit)

    • VUID-vkGetPhysicalDeviceToolProperties-physicalDevice-parameter
      physicalDevice must be a valid VkPhysicalDevice handle

    • VUID-vkGetPhysicalDeviceToolProperties-pToolCount-parameter
      pToolCount must be a valid pointer to a uint32_t value

    • VUID-vkGetPhysicalDeviceToolProperties-pToolProperties-parameter
      If the value referenced by pToolCount is not 0, and pToolProperties is not NULL, pToolProperties must be a valid pointer to an array of pToolCount VkPhysicalDeviceToolProperties structures

    Return Codes
    Success

    • VK_SUCCESS

    • VK_INCOMPLETE

    Failure

    • VK_ERROR_OUT_OF_HOST_MEMORY

    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 a VkStructureType value identifying this structure.

    • pNext is NULL 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.

    Valid Usage (Implicit)

    • VUID-VkPhysicalDeviceToolProperties-sType-sType
      sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES

    • VUID-VkPhysicalDeviceToolProperties-pNext-pNext
      pNext must be NULL

    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.