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, OpenGL ES, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file;
   7
   8 * retrace OpenGL and OpenGL ES calls from a file;
   9
  10 * inspect OpenGL state at any call while retracing;
  11
  12 * visualize and edit trace files.
  13
  14
  15 Basic usage
  16 ===========
  17
  18
  19 Linux and Mac OS X
  20 ------------------
  21
  22 Run the application you want to trace as
  23
  24     apitrace trace /path/to/application [args...]
  25
  26 and it will generate a trace named `application.trace` in the current
  27 directory.  You can specify the written trace filename by setting the
  28 `TRACE_FILE` environment variable before running.
  29
  30 View the trace with
  31
  32     apitrace dump --color application.trace
  33
  34 Replay an OpenGL trace with
  35
  36     glretrace application.trace
  37
  38 Pass the `-sb` option to use a single buffered visual.  Pass `--help` to
  39 glretrace for more options.
  40
  41 Start the GUI as
  42
  43     qapitrace application.trace
  44
  45
  46 Windows
  47 -------
  48
  49 * Copy `opengl32.dll`, `d3d8.dll`, or `d3d9.dll` from build/wrappers directory
  50   to the directory with the application you want to trace.
  51
  52 * Run the application.
  53
  54 * View the trace with
  55
  56         \path\to\apitrace dump application.trace
  57
  58 * Replay the trace with
  59
  60         \path\to\glretrace application.trace
  61
  62
  63 Advanced command line usage
  64 ===========================
  65
  66
  67 Tracing manually
  68 ----------------
  69
  70 ### Linux ###
  71
  72 Run the application you want to trace as
  73
  74      LD_PRELOAD=/path/to/apitrace/wrappers/glxtrace.so /path/to/application
  75
  76 and it will generate a trace named `application.trace` in the current
  77 directory.  You can specify the written trace filename by setting the
  78 `TRACE_FILE` environment variable before running.
  79
  80 The `LD_PRELOAD` mechanism should work with most applications.  There are some
  81 applications, e.g., Unigine Heaven, which global function pointers with the
  82 same name as GL entrypoints, living in a shared object that wasn't linked with
  83 `-Bsymbolic` flag, so relocations to those globals function pointers get
  84 overwritten with the address to our wrapper library, and the application will
  85 segfault when trying to write to them.  For these applications it is possible
  86 to trace by using `glxtrace.so` as an ordinary `libGL.so` and injecting into
  87 `LD_LIBRARY_PATH`:
  88
  89     ln -s glxtrace.so wrappers/libGL.so
  90     ln -s glxtrace.so wrappers/libGL.so.1
  91     ln -s glxtrace.so wrappers/libGL.so.1.2
  92     export LD_LIBRARY_PATH=/path/to/apitrace/wrappers:$LD_LIBRARY_PATH
  93     export TRACE_LIBGL=/path/to/real/libGL.so.1
  94     /path/to/application
  95
  96 See the `ld.so` man page for more information about `LD_PRELOAD` and
  97 `LD_LIBRARY_PATH` environment flags.
  98
  99 To trace the application inside gdb, invoke gdb as:
 100
 101     gdb --ex 'set exec-wrapper env LD_PRELOAD=/path/to/glxtrace.so' --args /path/to/application
 102
 103 ### Mac OS X ###
 104
 105 Run the application you want to trace as
 106
 107     DYLD_LIBRARY_PATH=/path/to/apitrace/wrappers /path/to/application
 108
 109 Note that although Mac OS X has an `LD_PRELOAD` equivalent,
 110 `DYLD_INSERT_LIBRARIES`, it is mostly useless because it only works with
 111 `DYLD_FORCE_FLAT_NAMESPACE=1` which breaks most applications.  See the `dyld` man
 112 page for more details about these environment flags.
 113
 114
 115 Emitting annotations to the trace from GL applications
 116 ------------------------------------------------------
 117
 118 You can emit string and frame annotations through the
 119 [`GL_GREMEDY_string_marker`](http://www.opengl.org/registry/specs/GREMEDY/string_marker.txt)
 120 and
 121 [`GL_GREMEDY_frame_terminator`](http://www.opengl.org/registry/specs/GREMEDY/frame_terminator.txt)
 122 GL extensions.
 123
 124 **apitrace** will advertise and intercept these GL extensions independently of
 125 the GL implementation.  So all you have to do is to use these extensions when
 126 available.
 127
 128 For example, if you use [GLEW](http://glew.sourceforge.net/) to dynamically
 129 detect and use GL extensions, you could easily accomplish this by doing:
 130
 131     void foo() {
 132
 133       if (GLEW_GREMEDY_string_marker) {
 134         glStringMarkerGREMEDY(0, __FUNCTION__ ": enter");
 135       }
 136
 137       ...
 138
 139       if (GLEW_GREMEDY_string_marker) {
 140         glStringMarkerGREMEDY(0, __FUNCTION__ ": leave");
 141       }
 142
 143     }
 144
 145 This has the added advantage of working equally well with gDEBugger.
 146
 147
 148 Dump GL state at a particular call
 149 ----------------------------------
 150
 151 You can get a dump of the bound GL state at call 12345 by doing:
 152
 153     glretrace -D 12345 application.trace > 12345.json
 154
 155 This is precisely the mechanism the GUI obtains its own state.
 156
 157 You can compare two state dumps by doing:
 158
 159     apitrace diff-state 12345.json 67890.json
 160
 161
 162 Comparing two traces side by side
 163 ---------------------------------
 164
 165     apitrace diff trace1.trace trace2.trace
 166
 167 This works only on Unices, and it will truncate the traces due to performance
 168 limitations.
 169
 170
 171 Recording a video with FFmpeg
 172 -----------------------------
 173
 174 You can make a video of the output by doing
 175
 176     glretrace -s - application.trace \
 177     | ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4
 178
 179
 180 Advanced usage for OpenGL implementors
 181 ======================================
 182
 183 There are several advanced usage examples meant for OpenGL implementors.
 184
 185
 186 Regression testing
 187 ------------------
 188
 189 These are the steps to create a regression test-suite around **apitrace**:
 190
 191 * obtain a trace
 192
 193 * obtain reference snapshots, by doing:
 194
 195         mkdir /path/to/snapshots/
 196         glretrace -s /path/to/reference/snapshots/ application.trace
 197
 198   on reference system.
 199
 200 * prune the snapshots which are not interesting
 201
 202 * to do a regression test, do:
 203
 204         glretrace -c /path/to/reference/snapshots/ application.trace
 205
 206   Alternatively, for a HTML summary, use `apitrace diff-images`:
 207
 208         glretrace -s /path/to/current/snapshots/ application.trace
 209         apitrace diff-images --output summary.html /path/to/reference/snapshots/ /path/to/current/snapshots/
 210
 211
 212 Automated git-bisection
 213 -----------------------
 214
 215 With tracecheck.py it is possible to automate git bisect and pinpoint the
 216 commit responsible for a regression.
 217
 218 Below is an example of using tracecheck.py to bisect a regression in the
 219 Mesa-based Intel 965 driver.  But the procedure could be applied to any GL
 220 driver hosted on a git repository.
 221
 222 First, create a build script, named build-script.sh, containing:
 223
 224     #!/bin/sh
 225     set -e
 226     export PATH=/usr/lib/ccache:$PATH
 227     export CFLAGS='-g'
 228     export CXXFLAGS='-g'
 229     ./autogen.sh --disable-egl --disable-gallium --disable-glut --disable-glu --disable-glw --with-dri-drivers=i965
 230     make clean
 231     make "$@"
 232
 233 It is important that builds are both robust, and efficient.  Due to broken
 234 dependency discovery in Mesa's makefile system, it was necessary invoke `make
 235 clean` in every iteration step.  `ccache` should be installed to avoid
 236 recompiling unchanged source files.
 237
 238 Then do:
 239
 240     cd /path/to/mesa
 241     export LIBGL_DEBUG=verbose
 242     export LD_LIBRARY_PATH=$PWD/lib
 243     export LIBGL_DRIVERS_DIR=$PWD/lib
 244     git bisect start \
 245         6491e9593d5cbc5644eb02593a2f562447efdcbb 71acbb54f49089b03d3498b6f88c1681d3f649ac \
 246         -- src/mesa/drivers/dri/intel src/mesa/drivers/dri/i965/
 247     git bisect run /path/to/tracecheck.py \
 248         --precision-threshold 8.0 \
 249         --build /path/to/build-script.sh \
 250         --gl-renderer '.*Mesa.*Intel.*' \
 251         --retrace=/path/to/glretrace \
 252         -c /path/to/reference/snapshots/ \
 253         topogun-1.06-orc-84k.trace
 254
 255 The trace-check.py script will skip automatically when there are build
 256 failures.
 257
 258 The `--gl-renderer` option will also cause a commit to be skipped if the
 259 `GL_RENDERER` is unexpected (e.g., when a software renderer or another GL
 260 driver is unintentionally loaded due to missing symbol in the DRI driver, or
 261 another runtime fault).
 262
 263
 264 Side by side retracing
 265 ----------------------
 266
 267 In order to determine which draw call a regression first manifests one could
 268 generate snapshots for every draw call, using the `-S` option.  That is, however,
 269 very inefficient for big traces with many draw calls.
 270
 271 A faster approach is to run both the bad and a good GL driver side-by-side.
 272 The latter can be either a previously known good build of the GL driver, or a
 273 reference software renderer.
 274
 275 This can be achieved with retracediff.py script, which invokes glretrace with
 276 different environments, allowing to choose the desired GL driver by
 277 manipulating variables such as `LD_LIBRARY_PATH` or `LIBGL_DRIVERS_DIR`.
 278
 279 For example:
 280
 281     ./scripts/retracediff.py \
 282         --ref-env LD_LIBRARY_PATH=/path/to/reference/GL/implementation \
 283         -r ./glretrace \
 284         --diff-prefix=/path/to/output/diffs \
 285         application.trace
 286
 287
 288
 289 Links
 290 =====
 291
 292 About **apitrace**:
 293
 294 * [Official mailing list](http://lists.freedesktop.org/mailman/listinfo/apitrace)
 295
 296 * [Zack Rusin's blog introducing the GUI](http://zrusin.blogspot.com/2011/04/apitrace.html)
 297
 298 * [Jose's Fonseca blog introducing the tool](http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html)
 299
 300
 301 Direct3D
 302 --------
 303
 304 Open-source:
 305
 306 * [Proxy DLL](http://www.mikoweb.eu/index.php?node=21)
 307
 308   * [Intercept Calls to DirectX with a Proxy DLL](http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/)
 309
 310 * [Direct3D 9 API Interceptor](http://graphics.stanford.edu/~mdfisher/D3D9Interceptor.html)
 311
 312 Closed-source:
 313
 314 * [Microsoft PIX](http://msdn.microsoft.com/en-us/library/ee417062.aspx)
 315
 316   * [D3DSpy](http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm): the predecessor of PIX
 317
 318 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
 319
 320
 321 OpenGL
 322 ------
 323
 324 Open-source:
 325
 326 * [BuGLe](http://www.opengl.org/sdk/tools/BuGLe/)
 327
 328 * [GLIntercept](http://code.google.com/p/glintercept/)
 329
 330 * [tracy](https://gitorious.org/tracy): OpenGL ES and OpenVG trace, retrace, and state inspection
 331
 332 Closed-source:
 333
 334 * [gDEBugger](http://www.gremedy.com/products.php)
 335
 336 * [glslDevil](http://cumbia.informatik.uni-stuttgart.de/glsldevil/index.html)
 337
 338 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
 339