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
 133 Mac OS X
 134 --------
 135
 136 Usage on Mac OS X is similar to Linux above, except for the tracing procedure,
 137 which is instead:
 138
 139     DYLD_LIBRARY_PATH=/path/to/apitrace/wrappers /path/to/application
 140
 141 Note that although Mac OS X has an `LD_PRELOAD` equivalent,
 142 `DYLD_INSERT_LIBRARIES`, it is mostly useless because it only works with
 143 `DYLD_FORCE_FLAT_NAMESPACE=1` which breaks most applications.  See the `dyld` man
 144 page for more details about these environment flags.
 145
 146
 147 Windows
 148 -------
 149
 150 * Copy `opengl32.dll`, `d3d8.dll`, or `d3d9.dll` from build/wrappers directory
 151   to the directory with the application you want to trace.
 152
 153 * Run the application.
 154
 155 * View the trace with
 156
 157         /path/to/tracedump application.trace
 158
 159 * Replay the trace with
 160
 161         /path/to/glretrace application.trace
 162
 163
 164 Links
 165 =====
 166
 167 About **apitrace**:
 168
 169 * [Zack Rusin's blog introducing the GUI](http://zrusin.blogspot.com/2011/04/apitrace.html)
 170
 171 * [Jose's Fonseca blog introducing the tool](http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html)
 172
 173
 174 Direct3D
 175 --------
 176
 177 Open-source:
 178
 179 * [Proxy DLL](http://www.mikoweb.eu/index.php?node=21)
 180
 181   * [Intercept Calls to DirectX with a Proxy DLL](http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/)
 182
 183 * [Direct3D 9 API Interceptor](http://graphics.stanford.edu/~mdfisher/D3D9Interceptor.html)
 184
 185 Closed-source:
 186
 187 * [Microsoft PIX](http://msdn.microsoft.com/en-us/library/ee417062.aspx)
 188
 189   * [D3DSpy](http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm): the predecessor of PIX
 190
 191 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
 192
 193
 194 OpenGL
 195 ------
 196
 197 Open-source:
 198
 199 * [BuGLe](http://www.opengl.org/sdk/tools/BuGLe/)
 200
 201 * [GLIntercept](http://code.google.com/p/glintercept/)
 202
 203 * [tracy](https://gitorious.org/tracy): OpenGL ES and OpenVG trace, retrace, and state inspection
 204
 205 Closed-source:
 206
 207 * [gDEBugger](http://www.gremedy.com/products.php)
 208
 209 * [glslDevil](http://cumbia.informatik.uni-stuttgart.de/glsldevil/index.html)
 210
 211 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
 212