X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=README;h=f0b8bf2f1df8e710003aca3c26917127f66e6f7a;hb=a3adde5b296a124ea93f7c404e591b629dd05586;hp=d73b76c08fbe05627f9b7f59d0d4d1728daeea78;hpb=933db22c70c741901ccd4fd017cf85ca1287dfa1;p=apitrace diff --git a/README b/README index d73b76c..f0b8bf2 100644 --- a/README +++ b/README @@ -1,77 +1,159 @@ - D3D Trace + API Trace & Retrace = Copyright = -Copyright 2008-2009 VMware, Inc. +Copyright 2011 Jose Fonseca, Zack Rusin +Copyright 2008-2010 VMware, Inc. +All Rights Reserved. -This program is free software: you can redistribute it and/or modify it -under the terms of the GNU Lesser General Public License as published -by the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. +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: -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU Lesser General Public License for more details. +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. -You should have received a copy of the GNU Lesser General Public License -along with this program. If not, see . +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 = -Wrapper DLLs to trace D3D8 and D3D9 APIs calls. - -Based on the idea from Michael Koch. - -See also: -* http://www.mikoweb.eu/index.php?node=21 -* http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/ -* http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm +This includes a set of tools for: +- trace OpenGL, D3D8, and D3D9 APIs calls to a file; +- retrace OpenGL calls from a file; +- visualize trace files, and inspect state. = Status = -* Only Direct3D 8 and 9 are supported at the moment. -* It has not been tested with many applications. Bugs may cause the application to crash. +* 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: +* Python (requires version 2.6) +* CMake (tested with version 2.8) -== MSVC == +Requirements to build the GUI (optional): +* Qt (tested with version 4.7) +* QJSON (tested with version 0.7.1) -Requirements: -* Python (tested with version 2.5) -* SCons (tested with 0.98.4) -* Microsoft Visual Studio (tested with 2005 version) -* Microsoft DirectX SDK (tested with August 2007 release) -Instructions: +== Linux == -* Invoke scons: +Build as: - scons debug=no dxsdk=C:\DXSDK - + cmake -H. -Bbuild + make -C build -== MinGW crosscompiler == +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: -* apt-get install mingw32 -Intructions: +* Microsoft Visual Studio (tested with 2008 version) or MinGW (tested with gcc version 4.4) - scons platform=windows machine=x86 toolchain=crossmingw opengl32.dll +* Microsoft DirectX SDK (tested with August 2007 release) + +To build with Visual Studio invoke CMake as: + + cmake -G "Visual Studio 9 2008" -H. -Bbuild + cmake --build build --config MinSizeRel + +It's also possible to build on Linux with MinGW cross compilers. See +http://www.cmake.org/Wiki/CmakeMingw for detailed instructions. = Usage = -* Copy d3d8.dll, d3d9.dll, or opengl32.dll and apitrace.xsl to the directory with the application you want to trace. + +== 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 + + +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 + + +== 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. -* Decompress the output .xml.gz and open the XML with Firefox or Internet Explorer to view the log. On Firefox hover on the arguments to see their contents. -* For long XML files is better to use xml2txt.py script directly on the .xml.gz file, as: - python xml2txt.py d3d9.xml.gz > d3d9.log +* View the trace with + + /path/to/tracedump application.trace + +* Replay the trace with + + /path/to/glretrace application.trace + + += Links = + +* http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html + + +== Direct3D == + + * [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] + + +== OpenGL == -See also http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html + * [http://www.opengl.org/sdk/tools/BuGLe/ BuGLe] + * [http://glintercept.nutty.org/ GLIntercept] + * [http://www.gremedy.com/products.php gDEBugger]