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, D3D9, D3D8, D3D7, and DDRAW 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 / Mac OS X ==
  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_EXE_LINKER_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 first invoke CMake GUI as:
  46
  47  cmake-gui -H. -B%cd%\build
  48
  49 and press the "Configure" button.
  50
  51 It will try to detect most required/optional dependencies automatically.  When
  52 not found automatically, you can manually specify the location of the
  53 dependencies from the GUI.
  54
  55 If you are building with GUI support (i.e, with QT and QJSON), it should detect
  56 the official QT sdk automatically, but you will need to build QJSON yourself
  57 and also set the QJSON_INCLUDE_DIR and QJSON_LIBRARIES variables in the
  58 generated CMakeCache.txt when building apitrace and repeat the above sequence.
  59
  60 After you've succesfully configured, you can start the build by opening the
  61 generated build\apitrace.sln solution file, or invoking cmake as:
  62
  63  cmake --build build --config MinSizeRel
  64
  65 The steps to build 64bit version are similar, but replacing "Visual Studio 9
  66 2008" with "Visual Studio 9 2008 Win64".
  67
  68 It's also possible to build for Windows on Linux with MinGW cross compilers.
  69 See http://www.cmake.org/Wiki/CmakeMingw for detailed instructions.
  70
  71
  72 = Usage =
  73
  74
  75 == Linux ==
  76
  77 Run the application you want to trace as
  78
  79  LD_PRELOAD=/path/to/glxtrace.so /path/to/application
  80
  81 and it will generate a trace named "application.trace" in the current
  82 directory.  You can specify the written trace filename by setting the
  83 TRACE_FILE envirnment variable before running.
  84
  85 View the trace with
  86
  87  /path/to/tracedump application.trace | less -R
  88
  89 Replay the trace with
  90
  91  /path/to/glretrace application.trace
  92
  93 Pass the -sb option to use a single buffered visual.  Pass --help to glretrace
  94 for more options.
  95
  96 Start the GUI as
  97
  98   /path/to/qapitrace application.trace
  99
 100
 101 The LD_PRELOAD mechanism should work with most applications.  There are some
 102 applications, e.g., Unigine Heaven, which global function pointers with the
 103 same name as GL entrypoints, living in a shared object that wasn't linked with
 104 -Bsymbolic flag, so relocations to those globals function pointers get
 105 overwritten with the address to our wrapper library, and the application will
 106 segfault when trying to write to them.  For these applications it is possible
 107 to trace by using glxtrace.so as an ordinary libGL.so and injecting into
 108 LD_LIBRARY_PATH:
 109
 110   ln -s glxtrace.so libGL.so
 111   ln -s glxtrace.so libGL.so.1
 112   ln -s glxtrace.so libGL.so.1.2
 113   export LD_LIBRARY_PATH=/path/to/directory/where/glxtrace/is:$LD_LIBRARY_PATH
 114   export TRACE_LIBGL=/path/to/real/libGL.so.1
 115   /path/to/application
 116
 117 See the 'ld.so' man page for more information about LD_PRELOAD and
 118 LD_LIBRARY_PATH environment flags.
 119
 120
 121 == Mac OS X ==
 122
 123 Usage on Mac OS X is similar to Linux above, except for the tracing procedure,
 124 which is instead:
 125
 126   DYLD_LIBRARY_PATH=/path/to/apitrace/wrappers /path/to/application
 127
 128 Note that although Mac OS X has an LD_PRELOAD equivalent,
 129 DYLD_INSERT_LIBRARIES, it is mostly useless because it only works with
 130 DYLD_FORCE_FLAT_NAMESPACE=1 which breaks most applications.  See the 'dyld' man
 131 page for more details about these environment flags.
 132
 133
 134 == Windows ==
 135
 136 * Copy opengl32.dll, d3d8.dll, or d3d9.dll from build/wrappers directory to the
 137   directory with the application you want to trace.
 138
 139 * Run the application.
 140
 141 * View the trace with
 142
 143  /path/to/tracedump application.trace
 144
 145 * Replay the trace with
 146
 147  /path/to/glretrace application.trace
 148
 149
 150 = Links =
 151
 152 * http://zrusin.blogspot.com/2011/04/apitrace.html
 153 * http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html
 154
 155
 156 == Direct3D ==
 157
 158 Open-source:
 159  * [http://www.mikoweb.eu/index.php?node=21 Proxy DLL]
 160    * [http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/ Intercept Calls to DirectX with a Proxy DLL]
 161  * [http://graphics.stanford.edu/~mdfisher/D3D9Interceptor.html Direct3D 9 API Interceptor]
 162
 163 Closed-source:
 164  * [http://msdn.microsoft.com/en-us/library/ee417062.aspx Microsoft PIX]
 165    * [http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm D3DSpy]: the predecessor of PIX
 166  * [http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx AMD GPU PerfStudio]
 167
 168
 169 == OpenGL ==
 170
 171 Open-source:
 172  * [http://www.opengl.org/sdk/tools/BuGLe/ BuGLe]
 173  * [http://code.google.com/p/glintercept/ GLIntercept]
 174  * [https://gitorious.org/tracy tracy]: OpenGL ES and OpenVG trace, retrace, and state inspection
 175
 176 Closed-source:
 177  * [http://www.gremedy.com/products.php gDEBugger]
 178  * [http://cumbia.informatik.uni-stuttgart.de/glsldevil/index.html glslDevil]
 179  * [http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx AMD GPU PerfStudio]
 180