tracedump: Add tri-state --color option (auto, always, or never)

[apitrace] / README.markdown

diff --git a/README.markdown b/README.markdown
index f551ad2f9cf9a69581d4b864d91261a750d014da..c38804276664853db5256e8a87eee2ef044451b1 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
@@ -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).
 
 
@@ -221,7 +256,7 @@ 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