X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=README;h=0e9ade3bf997c7104f87373e06d0e8c4a88411fb;hb=ecf37415b269e6051b01104740cb8f6ae736e8ad;hp=8fc78a1d6c9b167ccb5b84532b325eddc62bb867;hpb=e4688f2a2fa7bf93eb46ecf978c0bbfd2fe81a25;p=apitrace diff --git a/README b/README index 8fc78a1..0e9ade3 100644 --- a/README +++ b/README @@ -1,31 +1,6 @@ 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: @@ -34,14 +9,6 @@ This includes a set of tools for: - 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: @@ -53,17 +20,23 @@ Requirements to build the GUI (optional): * 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_LINK_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) @@ -73,9 +46,14 @@ To build with Visual Studio invoke CMake as: cmake -G "Visual Studio 9 2008" -H. -Bbuild cmake --build build --config MinSizeRel + +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. +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 = @@ -83,18 +61,62 @@ http://www.cmake.org/Wiki/CmakeMingw for detailed instructions. == Linux == -* Run the application you want to trace as +Run the application you want to trace as 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/tracedump 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 -db option to use a double 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 == @@ -114,19 +136,32 @@ http://www.cmake.org/Wiki/CmakeMingw for detailed instructions. = 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] +