4 **apitrace** consists of a set of tools to:
6 * trace OpenGL, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file;
8 * retrace OpenGL calls from a file;
10 * visualize trace files, and inspect state.
17 Requirements common for all platforms:
19 * Python (requires version 2.6)
21 * CMake (tested with version 2.8)
23 Requirements to build the GUI (optional):
25 * Qt (tested with version 4.7)
27 * QJSON (tested with version 0.7.1)
38 You can also build the 32bit GL wrapper on 64bit distro with a multilib gcc by
41 cmake -H. -Bbuild32 -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32 -DCMAKE_EXE_LINKER_FLAGS=-m32
42 make -C build32 glxtrace
48 Additional requirements:
50 * Microsoft Visual Studio (tested with 2008 version) or MinGW (tested with gcc version 4.4)
52 * Microsoft DirectX SDK (tested with August 2007 release)
54 To build with Visual Studio first invoke CMake GUI as:
56 cmake-gui -H. -B%cd%\build
58 and press the _Configure_ button.
60 It will try to detect most required/optional dependencies automatically. When
61 not found automatically, you can manually specify the location of the
62 dependencies from the GUI.
64 If you are building with GUI support (i.e, with QT and QJSON), it should detect
65 the official QT sdk automatically, but you will need to build QJSON yourself
66 and also set the `QJSON_INCLUDE_DIR` and `QJSON_LIBRARIES` variables in the
67 generated `CMakeCache.txt` when building apitrace and repeat the above
70 After you've succesfully configured, you can start the build by opening the
71 generated `build\apitrace.sln` solution file, or invoking `cmake` as:
73 cmake --build build --config MinSizeRel
75 The steps to build 64bit version are similar, but choosing _Visual Studio 9
76 2008 Win64_ instead of _Visual Studio 9 2008_.
78 It's also possible to instruct `cmake` build Windows binaries on Linux with
79 [MinGW cross compilers](http://www.cmake.org/Wiki/CmakeMingw).
89 Run the application you want to trace as
91 LD_PRELOAD=/path/to/glxtrace.so /path/to/application
93 and it will generate a trace named `application.trace` in the current
94 directory. You can specify the written trace filename by setting the
95 `TRACE_FILE` environment variable before running.
99 /path/to/tracedump application.trace | less -R
101 Replay the trace with
103 /path/to/glretrace application.trace
105 Pass the `-sb` option to use a single buffered visual. Pass `--help` to
106 glretrace for more options.
110 /path/to/qapitrace application.trace
113 The `LD_PRELOAD` mechanism should work with most applications. There are some
114 applications, e.g., Unigine Heaven, which global function pointers with the
115 same name as GL entrypoints, living in a shared object that wasn't linked with
116 `-Bsymbolic` flag, so relocations to those globals function pointers get
117 overwritten with the address to our wrapper library, and the application will
118 segfault when trying to write to them. For these applications it is possible
119 to trace by using `glxtrace.so` as an ordinary `libGL.so` and injecting into
122 ln -s glxtrace.so libGL.so
123 ln -s glxtrace.so libGL.so.1
124 ln -s glxtrace.so libGL.so.1.2
125 export LD_LIBRARY_PATH=/path/to/directory/where/glxtrace/is:$LD_LIBRARY_PATH
126 export TRACE_LIBGL=/path/to/real/libGL.so.1
129 See the `ld.so` man page for more information about `LD_PRELOAD` and
130 `LD_LIBRARY_PATH` environment flags.
132 You can make a video of the output by doing
134 /path/to/glretrace -s - application.trace \
135 | ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4
142 Usage on Mac OS X is similar to Linux above, except for the tracing procedure,
145 DYLD_LIBRARY_PATH=/path/to/apitrace/wrappers /path/to/application
147 Note that although Mac OS X has an `LD_PRELOAD` equivalent,
148 `DYLD_INSERT_LIBRARIES`, it is mostly useless because it only works with
149 `DYLD_FORCE_FLAT_NAMESPACE=1` which breaks most applications. See the `dyld` man
150 page for more details about these environment flags.
156 * Copy `opengl32.dll`, `d3d8.dll`, or `d3d9.dll` from build/wrappers directory
157 to the directory with the application you want to trace.
159 * Run the application.
161 * View the trace with
163 \path\to\tracedump application.trace
165 * Replay the trace with
167 \path\to\glretrace application.trace
175 * [Official mailing list](http://lists.freedesktop.org/mailman/listinfo/apitrace)
177 * [Zack Rusin's blog introducing the GUI](http://zrusin.blogspot.com/2011/04/apitrace.html)
179 * [Jose's Fonseca blog introducing the tool](http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html)
187 * [Proxy DLL](http://www.mikoweb.eu/index.php?node=21)
189 * [Intercept Calls to DirectX with a Proxy DLL](http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/)
191 * [Direct3D 9 API Interceptor](http://graphics.stanford.edu/~mdfisher/D3D9Interceptor.html)
195 * [Microsoft PIX](http://msdn.microsoft.com/en-us/library/ee417062.aspx)
197 * [D3DSpy](http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm): the predecessor of PIX
199 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
207 * [BuGLe](http://www.opengl.org/sdk/tools/BuGLe/)
209 * [GLIntercept](http://code.google.com/p/glintercept/)
211 * [tracy](https://gitorious.org/tracy): OpenGL ES and OpenVG trace, retrace, and state inspection
215 * [gDEBugger](http://www.gremedy.com/products.php)
217 * [glslDevil](http://cumbia.informatik.uni-stuttgart.de/glsldevil/index.html)
219 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)