Update docs / scripts for tracedump -> apitrace dump change.

[apitrace] / README.markdown

diff --git a/README.markdown b/README.markdown
index f56412aea7c02914173ca6d9e0af3752ba08495c..d35f2c46d9c96dfa702d3bb29339712c4a9dd0f9 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -7,7 +7,9 @@ About **apitrace**
 
 * retrace OpenGL calls from a file;
 
-* visualize trace files, and inspect state.
+* inspect OpenGL state at any call while retracing;
+
+* visualize and edit trace files.
 
 
 Basic usage
@@ -27,7 +29,7 @@ directory.  You can specify the written trace filename by setting the
 
 View the trace with
 
-    /path/to/tracedump application.trace | less -R
+    /path/to/apitrace dump --color application.trace | less -R
 
 Replay the trace with
 
@@ -86,7 +88,7 @@ Windows
 
 * View the trace with
 
-        \path\to\tracedump application.trace
+        \path\to\apitrace dump application.trace
 
 * Replay the trace with
 
@@ -97,6 +99,39 @@ Advanced command line usage
 ===========================
 
 
+Emitting annotations to the trace from GL applications
+------------------------------------------------------
+
+You can emit string and frame annotations through the
+[`GL_GREMEDY_string_marker`](http://www.opengl.org/registry/specs/GREMEDY/string_marker.txt)
+and
+[`GL_GREMEDY_frame_terminator`](http://www.opengl.org/registry/specs/GREMEDY/frame_terminator.txt)
+GL extensions.
+
+**apitrace** will advertise and intercept these GL extensions independently of
+the GL implementation.  So all you have to do is to use these extensions when
+available.
+
+For example, if you use [GLEW](http://glew.sourceforge.net/) to dynamically
+detect and use GL extensions, you could easily accomplish this by doing:
+
+    void foo() {
+    
+      if (GLEW_GREMEDY_string_marker) {
+        glStringMarkerGREMEDY(0, __FUNCTION__ ": enter");
+      }
+      
+      ...
+      
+      if (GLEW_GREMEDY_string_marker) {
+        glStringMarkerGREMEDY(0, __FUNCTION__ ": leave");
+      }
+      
+    }
+
+This has the added advantage of working equally well with gDEBugger.
+
+
 Dump GL state at a particular call
 ----------------------------------
 
@@ -132,13 +167,13 @@ You can make a video of the output by doing
 Advanced usage for OpenGL implementors
 ======================================
 
-There are several avanced usage examples meant for OpenGL implementors.
+There are several advanced usage examples meant for OpenGL implementors.
 
 
 Regression testing
 ------------------
 
-These are the steps to create a regression testsuite around apitrace:
+These are the steps to create a regression test-suite around **apitrace**:
 
 * obtain a trace
 
@@ -209,7 +244,7 @@ failures.
 
 The `--gl-renderer` option will also cause a commit to be skipped if the
 `GL_RENDERER` is unexpected (e.g., when a software renderer or another GL
-driver is unintentianlly loaded due to missing symbol in the DRI driver, or
+driver is unintentionally loaded due to missing symbol in the DRI driver, or
 another runtime fault).
 
 
@@ -217,11 +252,11 @@ Side by side retracing
 ----------------------
 
 In order to determine which draw call a regression first manifests one could
-generate snapshots for every draw call, using the -S option.  That is, however,
+generate snapshots for every draw call, using the `-S` option.  That is, however,
 very inefficient for big traces with many draw calls.
 
 A faster approach is to run both the bad and a good GL driver side-by-side.
-The latter can be either a preivously known good build of the GL driver, or a
+The latter can be either a previously known good build of the GL driver, or a
 reference software renderer.
 
 This can be achieved with retracediff.py script, which invokes glretrace with