API Trace & Retrace


= About =

This includes a set of tools for:
- trace OpenGL, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file;
- retrace OpenGL calls from a file;
- visualize trace files, and inspect state.


= Building from source =

Requirements common for all platforms:
* Python (requires version 2.6)
* CMake (tested with version 2.8)

Requirements to build the GUI (optional):
* Qt (tested with version 4.7)
* QJSON (tested with version 0.7.1)


== Linux / Mac OS X ==

Build as:

 cmake -H. -Bbuild
 make -C build

You can also build the 32bit GL wrapper on 64bit distro with a multilib gcc by
doing:

 cmake -H. -Bbuild32 -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32 -DCMAKE_EXE_LINKER_FLAGS=-m32
 make -C build32 glxtrace


== Windows ==

Additional requirements:

* Microsoft Visual Studio (tested with 2008 version) or MinGW (tested with gcc version 4.4)

* Microsoft DirectX SDK (tested with August 2007 release)

To build with Visual Studio first invoke CMake GUI as:

 cmake-gui -H. -B%cd%\build

and press the "Configure" button.

It will try to detect most required/optional dependencies automatically.  When
not found automatically, you can manually specify the location of the
dependencies from the GUI.

If you are building with GUI support (i.e, with QT and QJSON), it should detect
the official QT sdk automatically, but you will need to build QJSON yourself
and also set the QJSON_INCLUDE_DIR and QJSON_LIBRARIES variables in the
generated CMakeCache.txt when building apitrace and repeat the above sequence.
 
After you've succesfully configured, you can start the build by opening the
generated build\apitrace.sln solution file, or invoking cmake as:

 cmake --build build --config MinSizeRel

The steps to build 64bit version are similar, but replacing "Visual Studio 9
2008" with "Visual Studio 9 2008 Win64".

It's also possible to build for Windows on Linux with MinGW cross compilers.
See http://www.cmake.org/Wiki/CmakeMingw for detailed instructions.


= Usage =


== Linux ==

Run the application you want to trace as

 LD_PRELOAD=/path/to/glxtrace.so /path/to/application

and it will generate a trace named "application.trace" in the current
directory.  You can specify the written trace filename by setting the
TRACE_FILE envirnment variable before running.

View the trace with

 /path/to/tracedump application.trace | less -R

Replay the trace with

 /path/to/glretrace application.trace

Pass the -sb option to use a single buffered visual.  Pass --help to glretrace
for more options.

Start the GUI as

  /path/to/qapitrace application.trace


The LD_PRELOAD mechanism should work with most applications.  There are some
applications, e.g., Unigine Heaven, which global function pointers with the
same name as GL entrypoints, living in a shared object that wasn't linked with
-Bsymbolic flag, so relocations to those globals function pointers get
overwritten with the address to our wrapper library, and the application will
segfault when trying to write to them.  For these applications it is possible
to trace by using glxtrace.so as an ordinary libGL.so and injecting into
LD_LIBRARY_PATH:

  ln -s glxtrace.so libGL.so
  ln -s glxtrace.so libGL.so.1
  ln -s glxtrace.so libGL.so.1.2
  export LD_LIBRARY_PATH=/path/to/directory/where/glxtrace/is:$LD_LIBRARY_PATH
  export TRACE_LIBGL=/path/to/real/libGL.so.1
  /path/to/application

See the 'ld.so' man page for more information about LD_PRELOAD and
LD_LIBRARY_PATH environment flags.


== Mac OS X ==

Usage on Mac OS X is similar to Linux above, except for the tracing procedure,
which is instead:

  DYLD_LIBRARY_PATH=/path/to/apitrace/wrappers /path/to/application

Note that although Mac OS X has an LD_PRELOAD equivalent,
DYLD_INSERT_LIBRARIES, it is mostly useless because it only works with
DYLD_FORCE_FLAT_NAMESPACE=1 which breaks most applications.  See the 'dyld' man
page for more details about these environment flags.


== Windows ==

* Copy opengl32.dll, d3d8.dll, or d3d9.dll from build/wrappers directory to the
  directory with the application you want to trace.

* Run the application.

* View the trace with

 /path/to/tracedump application.trace

* Replay the trace with

 /path/to/glretrace application.trace


= Links =

* http://zrusin.blogspot.com/2011/04/apitrace.html
* http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html


== Direct3D ==

Open-source:
 * [http://www.mikoweb.eu/index.php?node=21 Proxy DLL]
   * [http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/ Intercept Calls to DirectX with a Proxy DLL]
 * [http://graphics.stanford.edu/~mdfisher/D3D9Interceptor.html Direct3D 9 API Interceptor]

Closed-source:
 * [http://msdn.microsoft.com/en-us/library/ee417062.aspx Microsoft PIX]
   * [http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm D3DSpy]: the predecessor of PIX
 * [http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx AMD GPU PerfStudio]


== OpenGL ==

Open-source:
 * [http://www.opengl.org/sdk/tools/BuGLe/ BuGLe]
 * [http://code.google.com/p/glintercept/ GLIntercept]
 * [https://gitorious.org/tracy tracy]: OpenGL ES and OpenVG trace, retrace, and state inspection

Closed-source:
 * [http://www.gremedy.com/products.php gDEBugger]
 * [http://cumbia.informatik.uni-stuttgart.de/glsldevil/index.html glslDevil]
 * [http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx AMD GPU PerfStudio]