New debugging markers and annnotations

[timoore]

With the VK_EXT_debug_utils support added in #1042, VSG has gained a cool capability when used with RenderDoc. By the way, I hardly get out of bed these days without using RenderDoc.

The new example nodes/vsgannotation example demonstrates how to emit text labels in the Vulkan command stream. RenderDoc picks these up and shows them in its event view.

The vsgannotation example adds a scene graph node that holds the name of the loaded model from the command line. In this RenderDoc session I've chosen a draw call that is part of the FlightHelment model, and we can see it listed in the corresponding tree widget.

This works recurisvely; I've inserted a node with the annotation "Scene" above the three loaded models.

Very useful for navigating complex scenes...

[robertosfield]

Thanks to @timoore for his work on VK_debug_utils support (now in VSG master and vsgExamples master), this not only means more helpful RenderDoc sessions but you can see the debug annotation when you write out to Vulkan API layer as well, so you can do things like:

 vsgannotation models/lz.vsgt -a > output.txt

If you then search through the output.txt you'll see entries like:

Thread 0, Frame 1:
vkCmdBeginDebugUtilsLabelEXT(commandBuffer, pLabelInfo) returns void:
    commandBuffer:                  VkCommandBuffer = 0x55e047d3c250
    pLabelInfo:                     const VkDebugUtilsLabelEXT* = 0x7ffffdac78a0:
        sType:                          VkStructureType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT (1000128002)
        pNext:                          const void* = NULL
        pLabelName:                     const char* = "Scene"
        color:                          float[4] = 0x7ffffdac78b8
            color[0]:                       float = 0.8
            color[1]:                       float = 0.8
            color[2]:                       float = 0.8
            color[3]:                       float = 1

Thread 0, Frame 1:
vkCmdBeginDebugUtilsLabelEXT(commandBuffer, pLabelInfo) returns void:
    commandBuffer:                  VkCommandBuffer = 0x55e047d3c250
    pLabelInfo:                     const VkDebugUtilsLabelEXT* = 0x7ffffdac7820:
        sType:                          VkStructureType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT (1000128002)
        pNext:                          const void* = NULL
        pLabelName:                     const char* = "/home/robert/Dev/vsgExamples/data/models/lz.vsgt"
        color:                          float[4] = 0x7ffffdac7838
            color[0]:                       float = 1
            color[1]:                       float = 1
            color[2]:                       float = 1
            color[3]:                       float = 1

[robertosfield]

Today I started experimenting with changing vsg::RecordTraversal so the apply() methods can be declared as virtual via cmake, while this will make RecordTraversal a bit slower to run it makes it possible to subclass from RecordTraversal override the apply methods and then do things like add VK_debug_utils style annotation for all nodes traversed in the scene graph. These experimental changes are checked into the VirtualRecordTraversalApply branches of the VSG and vsgExamples:

https://github.com/vsg-dev/VulkanSceneGraph/tree/VirtualRecordTraversalApply
https://github.com/vsg-dev/vsgExamples/tree/VirtualRecordTraversalApply

With the VSG build you need to enable the virtual RecordTraversal::apply() by setting the new VSG_virtual_RecordTraversal_apply variable to 1 then rebuilding the VSG etc.

With the vsgExamples branch I have tested out the ability to write a custom RecordTraversal with Tim's new vsgannotation example, and you can enable the use of this by adding a --cr command line parameters (custom record traversal) and doing so enables naming of all the nodes traversed in the RecordTraversal. So you get to see results like:

It's still very early days for the modifications to RecordTraversal::apply() but it should gives folks a glimpse of how rich an experience we could get with tools like RenderDoc.

[robertosfield]

One of the possibilities I am considering for the VSG to provide variants of the RecordTraversal that can be selected at runtime, with the default providing the lowest overheads and used for deployed applications then alternatives that provide VK_debug_utils annotations like the one used above and ones used for fine grained performance profiling.

Through the coming week I'll be exploring these areas further, if folks have ideas about how to make these features even more useful let us know.

[robertosfield]

Just came across this presentation " XDC 2021: Dissecting and fixing Vulkan rendering issues in drivers with RenderDoc ", might be of interest to see how others are using RenderDoc:

https://www.youtube.com/watch?v=OyIxKX3SRcM

[robertosfield]

This morning I created an experiment with vsg::CommandGraph automatically setting up a vsg::AnnotatedRecordTraversal that builds up the VK_debug_utils support, so that if you enable the Vulkan API debugging layer,, enabled in VSG by setting WindowTraits::apiDebug to true, you can automatically get all the node traversed in the recorded as their className().

https://github.com/vsg-dev/VulkanSceneGraph/tree/AnnotatedRecordTraversal

What this means is you can run VSG applications like vsgviewer and just add -a when you invoke it in RenderDoc and you get the traversed scene graph hierarchy right there in RenderDoc. This morning I was debugging a Vulkan error the new vsgoffscreenshot example, wirtten by @theodoregoetz, and I used this feature to spot what was going wrong all from within RenderDoc. This allowed me to go back to the scene graph setup locate where the oddity was happening and fix it.

This is really helpful and I think we've only just scratching the surface on what we may be to do to make the experience for developers even richer.