git.cworth.org Git - apitrace/blob - README.markdown

   1 About **apitrace**
   2 ==================
   3
   4 **apitrace** consists of a set of tools to:
   5
   6 * trace OpenGL, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file;
   7
   8 * retrace OpenGL calls from a file;
   9
  10 * visualize trace files, and inspect state.
  11
  12
  13 Building from source
  14 ====================
  15
  16
  17 Requirements common for all platforms:
  18
  19 * Python (requires version 2.6)
  20
  21 * CMake (tested with version 2.8)
  22
  23 Requirements to build the GUI (optional):
  24
  25 * Qt (tested with version 4.7)
  26
  27 * QJSON (tested with version 0.7.1)
  28
  29
  30 Linux / Mac OS X
  31 ----------------
  32
  33 Build as:
  34
  35     cmake -H. -Bbuild
  36     make -C build
  37
  38 You can also build the 32bit GL wrapper on 64bit distro with a multilib gcc by
  39 doing:
  40
  41     cmake -H. -Bbuild32 -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32 -DCMAKE_EXE_LINKER_FLAGS=-m32
  42     make -C build32 glxtrace
  43
  44
  45 Windows
  46 -------
  47
  48 Additional requirements:
  49
  50 * Microsoft Visual Studio (tested with 2008 version) or MinGW (tested with gcc version 4.4)
  51
  52 * Microsoft DirectX SDK (tested with August 2007 release)
  53
  54 To build with Visual Studio first invoke CMake GUI as:
  55
  56     cmake-gui -H. -B%cd%\build
  57
  58 and press the _Configure_ button.
  59
  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.
  63
  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
  68 sequence.
  69
  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:
  72
  73     cmake --build build --config MinSizeRel
  74
  75 The steps to build 64bit version are similar, but choosing _Visual Studio 9
  76 2008 Win64_ instead of _Visual Studio 9 2008_.
  77
  78 It's also possible to instruct `cmake` build Windows binaries on Linux with
  79 [MinGW cross compilers](http://www.cmake.org/Wiki/CmakeMingw).
  80
  81
  82 Usage
  83 =====
  84
  85
  86 Linux
  87 -----
  88
  89 Run the application you want to trace as
  90
  91      LD_PRELOAD=/path/to/glxtrace.so /path/to/application
  92
  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.
  96
  97 View the trace with
  98
  99     /path/to/tracedump application.trace | less -R
 100
 101 Replay the trace with
 102
 103     /path/to/glretrace application.trace
 104
 105 Pass the `-sb` option to use a single buffered visual.  Pass `--help` to
 106 glretrace for more options.
 107
 108 Start the GUI as
 109
 110     /path/to/qapitrace application.trace
 111
 112
 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
 120 `LD_LIBRARY_PATH`:
 121
 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
 127     /path/to/application
 128
 129 See the 'ld.so' man page for more information about `LD_PRELOAD` and
 130 `LD_LIBRARY_PATH` environment flags.
 131
 132 You can make a video of the output by doing
 133
 134     /path/to/glretrace -s - application.trace \
 135     | ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4
 136
 137
 138
 139 Mac OS X
 140 --------
 141
 142 Usage on Mac OS X is similar to Linux above, except for the tracing procedure,
 143 which is instead:
 144
 145     DYLD_LIBRARY_PATH=/path/to/apitrace/wrappers /path/to/application
 146
 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.
 151
 152
 153 Windows
 154 -------
 155
 156 * Copy `opengl32.dll`, `d3d8.dll`, or `d3d9.dll` from build/wrappers directory
 157   to the directory with the application you want to trace.
 158
 159 * Run the application.
 160
 161 * View the trace with
 162
 163         /path/to/tracedump application.trace
 164
 165 * Replay the trace with
 166
 167         /path/to/glretrace application.trace
 168
 169
 170 Links
 171 =====
 172
 173 About **apitrace**:
 174
 175 * [Zack Rusin's blog introducing the GUI](http://zrusin.blogspot.com/2011/04/apitrace.html)
 176
 177 * [Jose's Fonseca blog introducing the tool](http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html)
 178
 179
 180 Direct3D
 181 --------
 182
 183 Open-source:
 184
 185 * [Proxy DLL](http://www.mikoweb.eu/index.php?node=21)
 186
 187   * [Intercept Calls to DirectX with a Proxy DLL](http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/)
 188
 189 * [Direct3D 9 API Interceptor](http://graphics.stanford.edu/~mdfisher/D3D9Interceptor.html)
 190
 191 Closed-source:
 192
 193 * [Microsoft PIX](http://msdn.microsoft.com/en-us/library/ee417062.aspx)
 194
 195   * [D3DSpy](http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm): the predecessor of PIX
 196
 197 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
 198
 199
 200 OpenGL
 201 ------
 202
 203 Open-source:
 204
 205 * [BuGLe](http://www.opengl.org/sdk/tools/BuGLe/)
 206
 207 * [GLIntercept](http://code.google.com/p/glintercept/)
 208
 209 * [tracy](https://gitorious.org/tracy): OpenGL ES and OpenVG trace, retrace, and state inspection
 210
 211 Closed-source:
 212
 213 * [gDEBugger](http://www.gremedy.com/products.php)
 214
 215 * [glslDevil](http://cumbia.informatik.uni-stuttgart.de/glsldevil/index.html)
 216
 217 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
 218