Vulkan Layer for Live Introspection & Debugging. Allows to view all vulkan state live inside your application.
Vulkan layer that allows to inspect GPU state and submitted commands live inside your applications.
Features:
This is still in an early stage of development, bug reports and feedback welcome. 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.
Downsides:
Supported/Tested platforms:
VIL_CREATE_WINDOW=1
environment var
for a separate window (that works on native wayland). Or make your application use xcb/xlib.
register_layer.bat
after unpacking the zip.Windows+MinGW will hopefully eventually be supported/tested. Please report issues, if you try this.
NOTE: 32-bit platforms are currently not supported. Pull requests are welcome but you'd likely have to maintain it yourself/set up CI.
To build the layer from scratch, 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 /usr
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:
meson build --backend vs2019
(or vs2022
) from command line in the vil folder.build
folder) that you can build.Alternatively, you can also use ninja to build it on windows.
You will still need to install the layer after building it, so that other applications
can find it. Just run the register_layer.bat
in the build folder (running it once
is enough, it just adds the path to the registry).
For more information, manual installation (or if you are vary of running random
bat files from the internet), see here
Once installed, you have to make sure vulkan applications load VK_LAYER_live_introspection
.
Either pass it to your VkInstanceCreateInfo
or enable it via environment variable VK_INSTANCE_LAYERS=VK_LAYER_live_introspection
.
During the early stages of this project, you likely want to load it before any validation layer. If
your application then 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:
VIL_CREATE_WINDOW={0, 1}
.VIL_HOOK_OVERLAY=1
.Using this layer in retail application/games (i.e. applications 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.
SPDX-License-Identifier: GPL-3.0-only
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.