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:
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_LINK_FLAGS=-m32
+ cmake -H. -Bbuild32 -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32 -DCMAKE_EXE_LINKER_FLAGS=-m32
make -C build32 glxtrace
* 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.
+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.
/path/to/glretrace application.trace
-Pass the -db option to use a double buffered visual. Pass --help to glretrace
+Pass the -sb option to use a single buffered visual. Pass --help to glretrace
for more options.
Start the GUI as
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 ==
== 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 Microsoft 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://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