API Trace & Retrace
-= Copyright =
-
-Copyright 2011 Jose Fonseca, Zack Rusin
-Copyright 2008-2010 VMware, Inc.
-All Rights Reserved.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
-
= About =
This includes a set of tools for:
-- trace OpenGL, D3D8, and D3D9 APIs calls to a file;
+- trace OpenGL, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file;
- retrace OpenGL calls from a file;
- visualize trace files, and inspect state.
-= Status =
-
-* It has not been tested with many applications. Bugs in less used features may
- cause application crashes.
-* Direct3D 8 support is currently broken.
-* No Direct3D retrace support
-
-
= Building from source =
Requirements common for all platforms:
* QJSON (tested with version 0.7.1)
-== Linux ==
+== 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 ==
-Requirements:
+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 invoke CMake as:
+To build with Visual Studio first invoke CMake GUI as:
- cmake -G "Visual Studio 9 2008" -H. -Bbuild
- cmake --build build --config MinSizeRel
+ 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.
-It's also possible to build on Linux with MinGW cross compilers. See
-http://www.cmake.org/Wiki/CmakeMingw for detailed instructions.
+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
+Run the application you want to trace as
- LD_PRELOAD=/path/to/libglxtrace.so /path/to/application
+ LD_PRELOAD=/path/to/glxtrace.so /path/to/application
-* View the trace with
+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.
- /path/to/dump application.trace
+View the trace with
-* Replay 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 ==
* View the trace with
- /path/to/dump application.trace
+ /path/to/tracedump application.trace
* Replay the trace with
= 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://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm D3DSpy]
- * [http://msdn.microsoft.com/en-us/library/ee417062.aspx PIX]
+ * [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://glintercept.nutty.org/ GLIntercept]
+ * [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]
+
projects / apitrace / blobdiff