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