registry/vulkan/appendices/VK_EXT_tooling_info.txt

// Copyright 2018-2021 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_EXT_tooling_info.txt[]

=== Other Extension Metadata

*Last Modified Date*::
    2018-11-05
*Contributors*::
  - Rolando Caloca
  - Matthaeus Chajdas
  - Baldur Karlsson
  - Daniel Rakos

=== Description

When an error occurs during application development, a common question is
"What tools are actually running right now?" This extension adds the ability
to query that information directly from the Vulkan implementation.

Outdated versions of one tool might not play nicely with another, or perhaps
a tool is not actually running when it should have been.
Trying to figure that out can cause headaches as it is necessary to consult
each known tool to figure out what is going on -- in some cases the tool
might not even be known.

Typically, the expectation is that developers will simply print out this
information for visual inspection when an issue occurs, however a small
amount of semantic information about what the tool is doing is provided to
help identify it programmatically.
For example, if the advertised limits or features of an implementation are
unexpected, is there a tool active which modifies these limits? Or if an
application is providing debug markers, but the implementation is not
actually doing anything with that information, this can quickly point that
out.

include::{generated}/interfaces/VK_EXT_tooling_info.txt[]

=== Examples

.Printing Tool Information

```
uint32_t num_tools;
VkPhysicalDeviceToolPropertiesEXT *pToolProperties;
vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, NULL);

pToolProperties = (VkPhysicalDeviceToolPropertiesEXT*)malloc(sizeof(VkPhysicalDeviceToolPropertiesEXT) * num_tools);

vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, pToolProperties);

for (int i = 0; i < num_tools; ++i) {
    printf("%s:\n", pToolProperties[i].name);
    printf("Version:\n");
    printf("%s:\n", pToolProperties[i].version);
    printf("Description:\n");
    printf("\t%s\n", pToolProperties[i].description);
    printf("Purposes:\n");
    printf("\t%s\n", VkToolPurposeFlagBitsEXT_to_string(pToolProperties[i].purposes));
    if (strnlen_s(pToolProperties[i].layer,VK_MAX_EXTENSION_NAME_SIZE) > 0) {
        printf("Corresponding Layer:\n");
        printf("\t%s\n", pToolProperties[i].layer);
    }
}
```

=== Issues

1) Why is this information separate from the layer mechanism?

Some tooling may be built into a driver, or be part of the Vulkan loader
etc.
- and so tying this information directly to layers would've been awkward at
  best.

=== Version History

 * Revision 1, 2018-11-05 (Tobias Hector)
   - Initial draft