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

   1                               API Trace & Retrace
   2
   3
   4 = About =
   5
   6 This includes a set of tools for:
   7 - trace OpenGL, D3D8, and D3D9 APIs calls to a file;
   8 - retrace OpenGL calls from a file;
   9 - visualize trace files, and inspect state.
  10
  11
  12 = Status =
  13
  14 * It has not been tested with many applications. Bugs in less used features may
  15   cause application crashes.
  16 * Direct3D 8 support is currently broken.
  17 * No Direct3D retrace support
  18
  19
  20 = Building from source =
  21
  22 Requirements common for all platforms:
  23 * Python (requires version 2.6)
  24 * CMake (tested with version 2.8)
  25
  26 Requirements to build the GUI (optional):
  27 * Qt (tested with version 4.7)
  28 * QJSON (tested with version 0.7.1)
  29
  30
  31 == Linux ==
  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_LINK_FLAGS=-m32
  42  make -C build32 glxtrace
  43
  44
  45 == Windows ==
  46
  47 Additional requirements:
  48
  49 * Microsoft Visual Studio (tested with 2008 version) or MinGW (tested with gcc version 4.4)
  50
  51 * Microsoft DirectX SDK (tested with August 2007 release)
  52
  53 To build with Visual Studio invoke CMake as:
  54
  55  cmake -G "Visual Studio 9 2008" -H. -Bbuild
  56  cmake --build build --config MinSizeRel
  57
  58 If you are building with GUI support (i.e, with QT and QJSON), it should detect
  59 the official QT sdk automatically, but you will need to build QJSON yourself
  60 and also set the QJSON_INCLUDE_DIR and QJSON_LIBRARIES variables in the
  61 generated CMakeCache.txt when building apitrace and repeat the above sequence.
  62
  63 It's also possible to build for Windows on Linux with MinGW cross compilers.
  64 See http://www.cmake.org/Wiki/CmakeMingw for detailed instructions.
  65
  66
  67 = Usage =
  68
  69
  70 == Linux ==
  71
  72 Run the application you want to trace as
  73
  74  LD_PRELOAD=/path/to/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 envirnment variable before running.
  79
  80 View the trace with
  81
  82  /path/to/tracedump application.trace | less -R
  83
  84 Replay the trace with
  85
  86  /path/to/glretrace application.trace
  87
  88 Pass the -db option to use a double buffered visual.  Pass --help to glretrace
  89 for more options.
  90
  91 Start the GUI as
  92
  93   /path/to/qapitrace application.trace
  94
  95
  96 The LD_PRELOAD mechanism should work with most applications.  There are some
  97 applications, e.g., Unigine Heaven, which global function pointers with the
  98 same name as GL entrypoints, living in a shared object that wasn't linked with
  99 -Bsymbolic flag, so relocations to those globals function pointers get
 100 overwritten with the address to our wrapper library, and the application will
 101 segfault when trying to write to them.  For these applications it is possible
 102 to trace by using glxtrace.so as an ordinary libGL.so and injecting into
 103 LD_LIBRARY_PATH:
 104
 105   ln -s glxtrace.so libGL.so
 106   ln -s glxtrace.so libGL.so.1
 107   ln -s glxtrace.so libGL.so.1.2
 108   export LD_LIBRARY_PATH=/path/to/directory/where/glxtrace/is:$LD_LIBRARY_PATH
 109   export TRACE_LIBGL=/path/to/real/libGL.so.1
 110   /path/to/application
 111
 112
 113 == Windows ==
 114
 115 * Copy opengl32.dll, d3d8.dll, or d3d9.dll from build/wrappers directory to the
 116   directory with the application you want to trace.
 117
 118 * Run the application.
 119
 120 * View the trace with
 121
 122  /path/to/tracedump application.trace
 123
 124 * Replay the trace with
 125
 126  /path/to/glretrace application.trace
 127
 128
 129 = Links =
 130
 131 * http://zrusin.blogspot.com/2011/04/apitrace.html
 132 * http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html
 133
 134
 135 == Direct3D ==
 136
 137 Open-source:
 138  * [http://www.mikoweb.eu/index.php?node=21 Proxy DLL]
 139    * [http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/ Intercept Calls to DirectX with a Proxy DLL]
 140  * [http://graphics.stanford.edu/~mdfisher/D3D9Interceptor.html Direct3D 9 API Interceptor]
 141
 142 Closed-source:
 143  * [http://msdn.microsoft.com/en-us/library/ee417062.aspx Microsoft PIX]
 144    * [http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm D3DSpy]: the predecessor of PIX
 145  * [http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx AMD GPU PerfStudio]
 146
 147
 148 == OpenGL ==
 149
 150 Open-source:
 151  * [http://www.opengl.org/sdk/tools/BuGLe/ BuGLe]
 152  * [http://code.google.com/p/glintercept/ GLIntercept]
 153  * [https://gitorious.org/tracy tracy]: OpenGL ES and OpenVG trace, retrace, and state inspection
 154
 155 Closed-source:
 156  * [http://www.gremedy.com/products.php gDEBugger]
 157  * [http://cumbia.informatik.uni-stuttgart.de/glsldevil/index.html glslDevil]
 158  * [http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx AMD GPU PerfStudio]
 159