Allow to use call sets instead of call numbers / frequencies.

[apitrace] / README.markdown

diff --git a/README.markdown b/README.markdown
index 497351abe99697dc285e2c0607aaa48da2267f0e..38dfa5e21c357ae47a9187ded3d786b895a9dee4 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -3,9 +3,9 @@ About **apitrace**
 
 **apitrace** consists of a set of tools to:
 
-* trace OpenGL, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file;
+* trace OpenGL, OpenGL ES, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file;
 
-* retrace OpenGL calls from a file;
+* retrace OpenGL and OpenGL ES calls from a file;
 
 * inspect OpenGL state at any call while retracing;
 
@@ -21,7 +21,7 @@ Linux and Mac OS X
 
 Run the application you want to trace as
 
-    /path/to/apitrace trace /path/to/application [args...]
+    apitrace trace /path/to/application [args...]
 
 and it will generate a trace named `application.trace` in the current
 directory.  You can specify the written trace filename by setting the
@@ -29,18 +29,18 @@ directory.  You can specify the written trace filename by setting the
 
 View the trace with
 
-    /path/to/apitrace dump --color application.trace | less -R
+    apitrace dump --color application.trace
 
-Replay the trace with
+Replay an OpenGL trace with
 
-    /path/to/glretrace application.trace
+    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
+    qapitrace application.trace
 
 
 Windows
@@ -64,6 +64,34 @@ Advanced command line usage
 ===========================
 
 
+Call sets
+---------
+
+Several tools take `CALLSET` arguments, e.g:
+
+    apitrace dump --calls CALLSET foo.trace
+    glretrace -S CALLSET foo.trace
+
+The call syntax is very flexible. Here are a few examples:
+
+ * `4`             one call
+
+ * `1,2,4,5`       set of calls
+
+ * `"1 2 4 5"`     set of calls (commas are optional and can be replaced with whitespace)
+
+ * `1-100/2`       calls 1, 3, 5, ...,  99
+
+ * `1-1000/draw`   all draw calls between 1 and 1000
+
+ * `1-1000/fbo`    all fbo changes between calls 1 and 1000
+
+ * `frame`         all calls at end of frames
+
+ * `@foo.txt`      read call numbers from `foo.txt`, using the same syntax as above
+
+
+
 Tracing manually
 ----------------
 
@@ -96,6 +124,10 @@ to trace by using `glxtrace.so` as an ordinary `libGL.so` and injecting into
 See the `ld.so` man page for more information about `LD_PRELOAD` and
 `LD_LIBRARY_PATH` environment flags.
 
+To trace the application inside gdb, invoke gdb as:
+
+    gdb --ex 'set exec-wrapper env LD_PRELOAD=/path/to/glxtrace.so' --args /path/to/application
+
 ### Mac OS X ###
 
 Run the application you want to trace as
@@ -146,13 +178,13 @@ Dump GL state at a particular call
 
 You can get a dump of the bound GL state at call 12345 by doing:
 
-    /path/to/glretrace -D 12345 application.trace > 12345.json
+    glretrace -D 12345 application.trace > 12345.json
 
 This is precisely the mechanism the GUI obtains its own state.
 
-You can compare two state dumps with the jsondiff.py script:
+You can compare two state dumps by doing:
 
-    ./scripts/jsondiff.py 12345.json 67890.json
+    apitrace diff-state 12345.json 67890.json
 
 
 Comparing two traces side by side
@@ -169,7 +201,7 @@ Recording a video with FFmpeg
 
 You can make a video of the output by doing
 
-    /path/to/glretrace -s - application.trace \
+    glretrace -s - application.trace \
     | ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4
 
 
@@ -189,7 +221,7 @@ These are the steps to create a regression test-suite around **apitrace**:
 * obtain reference snapshots, by doing:
 
         mkdir /path/to/snapshots/
-        /path/to/glretrace -s /path/to/reference/snapshots/ application.trace
+        glretrace -s /path/to/reference/snapshots/ application.trace
 
   on reference system.
 
@@ -197,12 +229,12 @@ These are the steps to create a regression test-suite around **apitrace**:
 
 * to do a regression test, do:
 
-        /path/to/glretrace -c /path/to/reference/snapshots/ application.trace
+        glretrace -c /path/to/reference/snapshots/ application.trace
 
-  Alternatively, for a HTML summary, use the snapdiff script:
+  Alternatively, for a HTML summary, use `apitrace diff-images`:
 
-        /path/to/glretrace -s /path/to/current/snapshots/ application.trace
-        ./scripts/snapdiff.py --output summary.html /path/to/reference/snapshots/ /path/to/current/snapshots/
+        glretrace -s /path/to/current/snapshots/ application.trace
+        apitrace diff-images --output summary.html /path/to/reference/snapshots/ /path/to/current/snapshots/
 
 
 Automated git-bisection