===========================
+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
----------------------------------
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
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).
----------------------
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