intel/gits

API capture-replay tool for Vulkan, OpenCL, Intel oneAPI Level Zero and OpenGL

Graphics Intercept and Trace Solution (GITS)

Graphics Intercept and Trace Solution is a capture-replay tool for Vulkan, OpenCL, Intel oneAPI Level Zero and OpenGL.

GITS allows you to record sequences of API calls. You can either serialize them into binary traces that can be replayed later (we call them streams), or you can generate a C++ project from them (we call it CCode). See the Usage section for more info.

GITS has been used for years to help develop and validate Intel GPU drivers. It is a collection of command line tools aimed at driver developers, but we think it can be useful to other users as well. If you are a game developer who wants to analyze frames using a graphical tool, GPA or a similar tool is what you should look at.

Installation

Currently we do not provide prebuilt binaries. You will have to build it yourself.

Building

GITS is written in C++. You will need a compiler and a build system.

We use CMake to generate the build files. You will need to specify a generator, architecture, and install prefix.

We use Python 3 and Mako Templates for code generation, make sure you have them installed.

For more info, see BUILDING.md

Usage

To record an application, you will have to inject our dynamic library (called the interceptor) into it. On Windows, this is typically done by copying a DLL into the app directory. On Linux, by manipulating loader environment variables. When recording Vulkan, it is also possible to use GITS as a Vulkan layer instead.

To replay the stream, pass it as an argument to the gitsPlayer executable. See the player's built-in help (gitsPlayer --help) for usage info.

GITS allows recording streams containing only a subset of API calls made by the application (e.g., only select frames). We call them substreams or subcaptures.

GITS development is focused on enabling applications, not APIs or extensions. We implement support for API calls when we encounter apps using them.

For more info, see USAGE.md

Contributing

For information on how to contribute, see CONTRIBUTING.md. Contributions are subject to our code of conduct.

If you want to report security issues, see SECURITY.md.

License

GITS is licensed under the terms in LICENSE.md.

GITS uses third-party software which are available under their own licenses. See doc/GITS_third-party-programs.txt for more info.

gits's Issues

GITS Android support

I really like the GITS project. I've gotten it built on Windows and have been using it without issue on my personal projects.

I was wondering about Android support? GITS seems to be heavily dependent on X11 and wayland for Linux machines, but those libraries aren't supported by Android. Is there a known way to go around this? Even only for OpenCL which shouldn't require the libraries? With how extensively used X11 and wayland are in the codebase, it doesn't seem wise to remove them for Android and OpenCL support.

Failed to compile the program. undefined reference to `gits::CMappedHandle::currentVersion_'

I followed the building commands in BUILDING.md and got a compiling error:

...
[100%] Linking CXX executable gitsPlayer
[100%] Built target GitsRecorder
/usr/bin/ld: ../common/libcommon.a(argument.cpp.o): in function `gits::CMappedHandle::Read(gits::CBinIStream&)':
argument.cpp:(.text+0x19dd): undefined reference to `gits::CMappedHandle::currentVersion_'
collect2: error: ld returned 1 exit status
gmake[2]: *** [player/CMakeFiles/gitsPlayer.dir/build.make:178: player/gitsPlayer] Error 1
gmake[1]: *** [CMakeFiles/Makefile2:1065: player/CMakeFiles/gitsPlayer.dir/all] Error 2
gmake: *** [Makefile:136: all] Error 2

System: Linux Ubuntu-2204 5.19.0-50-generic #50-Ubuntu SMP PREEMPT_DYNAMIC Mon Jul 10 18:24:29 UTC 2023 x86_64 x86_64 x86_64 GNU/Linux

git repo commit: f2e97348c54493746e4cd3012b38a9db9863b776