Vulkan in-app debugging layer that is able to provide live introspection and debugging via an overlay or window GUI.
This is still in a very early stage of development. Bug reports are welcome. There are various known issues and some of the features below are work-in-progess. See the rough overview over the currently implemented vulkan commands/extensions. Keep in mind that using extensions/features not supported by the layer at the moment might cause crashes.
Intended much more as a live debugging tool than a profiling tool. Does not have all the features of existing debugging tools (such as renderdoc) at the moment, but can already be useful to debug problems that are hard to find in traditional debugging tools. Unlike capture-based tools, this allows a live introspection. This can be useful to debug temporal or synchronization issues (doing this with per-frame captures can be bothersome) or as first-try debugging approach to figure out roughly where a problem is, without having to wait for a capture to load. It also is useful as a general-purpose introspection tool, capture-based tools are usually optimized to only show resources important for their capture, leaving out the rest. It also allows to easily debug compute-only vulkan applications that don't have a swapchain (renderdoc can do that but requires the application to explicitly call renderdoc api).
VIL_CREATE_WINDOWfor a separate window (that works on native wayland). Or make your application use xcb/xlib.
NOTE: 32-bit platforms are currently not supported. Pull requests are welcome but you'd likely have to maintain it yourself/set up CI.
Currently (as there isn't even an official release), there are no prepackaged binaries or build scripts, you have to build and install it yourself. You'll need an up-to-date version of meson.
Just clone the repository and run:
meson build ninja -C build
To install the layer you can just run
ninja -C build install (you might need superuser rights for that).
By default, meson will install to
/usr/local so - depending on your system - the layer configuration file or
layer library itself might not be found by the vulkan loader. Either make sure that
/usr/local is properly
included in your system's library and vulkan loader search paths or change the install prefix to
via meson (e.g. run
meson --prefix=/usr build in the beginning).
Be warned that using the
/usr prefix for manually built libs/applications is generally not recommended since it might mess
with your package manager.
On windows, this is actively tested with MSVC 2019, older version will likely not work due to incomplete/incorrect C++17 support. Since we require c11, MSVC >= 19.28 is required (visual studio 16.8). The recommended/tested way to build it:
x64 Native Tools command promptfor your visual studio version. You can just search for that using the start menu when you have visual studio installed.
meson build --backend vs2019
You will still need to install the layer after building it.
On windows, layers are installed via registry entries, you have to add
a registry entry in
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers pointing to the generated layer config
json (that must be located in the same folder as
See here or here for more details.
You can simply run the
register_layer.bat script in the build directory. Note that it will require admin privileges
to add the registry key. You should usually not run random batch scripts from the internet that require admin privileges,
so feel free to do it manually in an admin prompt:
REG ADD HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers /v <filepath of VkLayer_live_introspection.json> /t REG_DWORD /d 0
<filepath of VkLayer_live_introspection.json> with full file path of the generated
VkLayer_live_introspection.json file, e.g.
When building with something else than MSVC, you might have to adjust the name of the dll. For instance, MinGW might add a
lib prefix. In that case, when using
vil_api.h, you'll also have to redefine
VIL_LIB_NAME before including the header to the name of the dll.
Once installed, you have to make sure vulkan applications load
Either pass it to your
VkInstanceCreateInfo or enable it via environment variable
During the early stages of this project, you likely want to load it before any validation layer. If
your application then causes triggers validation errors with vil that are not there without it,
make sure to report them here!
There are multiple ways of using the introspection gui:
Using this layer in retail application/games (i.e. games you don't develop yourself, without available source code or debugging symbols) IS NOT OFFICIALLY SUPPORTED. There are multiple reasons for this:
With that out of the way, there is nothing per se wrong with using the layer in retail products and games you have not written yourself. As long as you don't expect us to make it to work or distribute the results. When you can point out what exactly is causing the layer to crash with a specific game or fix a problem inside the layer to allow using it with a retail product, we definitely want to hear of it. But additional code paths inside the layer that work around specific game issues will not be accepted.
Using the layer via an overlay inside the demo level of vkQuake2:
Unless stated otherwise, code and assets in this repository are licensed under GPLv3. Contributors don't have to sign a CLA.
Note that since this is a dynamically loaded vulkan layer and not a library you link your application against, using this in production of proprietary products should not be a problem and is inside the intended usecase.