##############################################################################
# Packaging
-install (FILES LICENSE README TODO DESTINATION doc)
+install (FILES LICENSE README.markdown TODO.markdown DESTINATION doc)
set (CPACK_PACKAGE_VERSION_MAJOR "1")
set (CPACK_PACKAGE_VERSION_MINOR "0")
+++ /dev/null
- 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]
-
--- /dev/null
+About **apitrace**
+==================
+
+**apitrace** consists of a set of tools to:
+
+* 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 choosing _Visual Studio 9
+2008 Win64_ instead of _Visual Studio 9 2008_.
+
+It's also possible to instruct `cmake` build Windows binaries on Linux with
+[MinGW cross compilers](http://www.cmake.org/Wiki/CmakeMingw).
+
+
+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` environment 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
+=====
+
+About **apitrace**:
+
+* [Zack Rusin's blog introducing the GUI](http://zrusin.blogspot.com/2011/04/apitrace.html)
+
+* [Jose's Fonseca blog introducing the tool](http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html)
+
+
+Direct3D
+--------
+
+Open-source:
+
+* [Proxy DLL](http://www.mikoweb.eu/index.php?node=21)
+
+ * [Intercept Calls to DirectX with a Proxy DLL](http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/)
+
+* [Direct3D 9 API Interceptor](http://graphics.stanford.edu/~mdfisher/D3D9Interceptor.html)
+
+Closed-source:
+
+* [Microsoft PIX](http://msdn.microsoft.com/en-us/library/ee417062.aspx)
+
+ * [D3DSpy](http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm): the predecessor of PIX
+
+* [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
+
+
+OpenGL
+------
+
+Open-source:
+
+* [BuGLe](http://www.opengl.org/sdk/tools/BuGLe/)
+
+* [GLIntercept](http://code.google.com/p/glintercept/)
+
+* [tracy](https://gitorious.org/tracy): OpenGL ES and OpenVG trace, retrace, and state inspection
+
+Closed-source:
+
+* [gDEBugger](http://www.gremedy.com/products.php)
+
+* [glslDevil](http://cumbia.informatik.uni-stuttgart.de/glsldevil/index.html)
+
+* [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
+
+++ /dev/null
- Things To Do
- (in no particular order)
-
-
-Tracing:
-
-* Allow clamping to a GL version or a number of extensions.
-
-* Trace multiple threads
- * GetCurrentThreadId()
- * pthread_self()
-
-* Put zlib (de)compression in a separate thread.
-
-* Trace TSCs
-
-* Trace window sizes somehow
-
-* Allow to distinguish between the calls really done by the program, vs the
- fakes one necessary to retrace correctly.
-
-* Start tracing on demand (e.g., key-press, or by frame no), emitting calls
- that recreate all current state.
-
-* Add option to include call stack frames in the trace
-
-* Call gzflush() only when there is a signal/exception, except of doing it on
- every call.
-
-
-Retracing:
-
-* Use visuals that best match those used in the trace; specially auto
- detect single/double buffer visuals.
-
-* Respect multiple context sharing of the traces.
-
-* Support multiple threads
-
-* Provide a readline-like interactive mode to gltrace
- * http://github.com/antirez/linenoise
- * https://github.com/antirez/linenoise/issues#issue/8
- * http://hg.youterm.com/radare/file/87579f8c5087/src/dietline.c
-
-* Plug memory leaks.
-
-* Allow to retrace with two libGL.so in parallel, and output differences in
- rendered frames / draw calls.
-
-* D3D support.
-
-
-GUI:
-
-* Timeline view.
-
-* Visualize meshes in draw commands.
-
-
-Other:
-
-* Side-by-side trace diffing; either as a separate tool on or the GUI.
-
-* Side-by-side state diffing.
-
-* Ability to extract just a single frame from a trace, and all previous calls
- that contributed to it:
-
- * via a state tracker (i.e., knowledge of how calls affect the state);
-
- * or by leveragine retrace, dumping the calls to emit all state at beginning
- of the frame.
-
-
-See also FIXME, TODO, and XXX comments on the source code.
--- /dev/null
+Things To Do
+============
+
+(in no particular order)
+
+
+Tracing
+-------
+
+* Allow clamping to a GL version or a number of extensions.
+
+* Trace multiple threads:
+
+ * `GetCurrentThreadId()`
+
+ * `pthread_self()`
+
+* Put zlib (de)compression in a separate thread.
+
+* Trace TSCs
+
+* Trace window sizes somehow
+
+* Allow to distinguish between the calls really done by the program, vs the
+ fakes one necessary to retrace correctly.
+
+* Start tracing on demand (e.g., key-press, or by frame no), emitting calls
+ that recreate all current state.
+
+* Add option to include call stack frames in the trace
+
+* Call gzflush() only when there is a signal/exception, except of doing it on
+ every call.
+
+
+Retracing
+---------
+
+* Use visuals that best match those used in the trace; specially auto
+ detect single/double buffer visuals.
+
+* Respect multiple context sharing of the traces.
+
+* Support multiple threads
+
+* Provide a readline-like interactive mode to gltrace
+
+ * http://github.com/antirez/linenoise
+
+ * https://github.com/antirez/linenoise/issues#issue/8
+
+ * http://hg.youterm.com/radare/file/87579f8c5087/src/dietline.c
+
+* Plug memory leaks.
+
+* Allow to retrace with two libGL.so in parallel, and output differences in
+ rendered frames / draw calls.
+
+* D3D support.
+
+
+GUI
+---
+
+* Timeline view.
+
+* Visualize meshes in draw commands.
+
+
+Other:
+
+* Side-by-side trace diffing; either as a separate tool on or the GUI.
+
+* Side-by-side state diffing.
+
+* Ability to extract just a single frame from a trace, and all previous calls
+ that contributed to it:
+
+ * via a state tracker (i.e., knowledge of how calls affect the state);
+
+ * or by leveragine retrace, dumping the calls to emit all state at beginning
+ of the frame.
+
+
+See also FIXME, TODO, and XXX comments on the source code.
projects / apitrace / commitdiff