Use markdown syntax.

4 files changed, 232 insertions, 190 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 55b530f2..1b86790f 100755
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -374,7 +374,7 @@ endif (QT4_FOUND AND QJSON_FOUND)
 ##############################################################################
 # 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")
diff --git a/README b/README
deleted file mode 100644
index 4d6505f5..00000000
--- a/README
+++ /dev/null
@@ -1,180 +0,0 @@
-			      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]
-
diff --git a/README.markdown b/README.markdown
new file mode 100644
index 00000000..790407d4
--- /dev/null
+++ b/README.markdown
@@ -0,0 +1,212 @@
+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)
+
diff --git a/TODO b/TODO.markdown
index d2977a97..f0e0d8e6 100644
--- a/TODO
+++ b/TODO.markdown
@@ -1,14 +1,19 @@
-                                  Things To Do
-                            (in no particular order)
+Things To Do
+============
 
+(in no particular order)
 
-Tracing:
+
+Tracing
+-------
 
 * Allow clamping to a GL version or a number of extensions.
 
-* Trace multiple threads
-  * GetCurrentThreadId()
-  * pthread_self()
+* Trace multiple threads:
+
+  * `GetCurrentThreadId()`
+
+  * `pthread_self()`
 
 * Put zlib (de)compression in a separate thread.
 
@@ -28,7 +33,8 @@ Tracing:
   every call.
 
 
-Retracing:
+Retracing
+---------
 
 * Use visuals that best match those used in the trace; specially auto
   detect single/double buffer visuals.
@@ -38,9 +44,12 @@ Retracing:
 * 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 
+
+  * http://hg.youterm.com/radare/file/87579f8c5087/src/dietline.c
 
 * Plug memory leaks.
 
@@ -50,7 +59,8 @@ Retracing:
 * D3D support.
 
 
-GUI:
+GUI
+---
 
 * Timeline view.