s/all_types/getAllTypes/

[apitrace] / README.markdown

diff --git a/README.markdown b/README.markdown
index f8b51ad3c7eeddaea30c41caaf65496e7385f7a8..38dfa5e21c357ae47a9187ded3d786b895a9dee4 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -3,23 +3,25 @@ About **apitrace**
 
 **apitrace** consists of a set of tools to:
 
 
 **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;

 
 

-* visualize trace files, and inspect state.
+* inspect OpenGL state at any call while retracing;
+
+* visualize and edit trace files.

 
 
 Basic usage
 ===========
 
 
 
 
 Basic usage
 ===========
 
 

-Linux
------
+Linux and Mac OS X
+------------------

 
 Run the application you want to trace as
 
 
 Run the application you want to trace as
 

-     LD_PRELOAD=/path/to/glxtrace.so /path/to/application
+    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
 
 and it will generate a trace named `application.trace` in the current
 directory.  You can specify the written trace filename by setting the


@@ -27,19 +29,81 @@ directory.  You can specify the written trace filename by setting the
 
 View the trace with
 
 
 View the trace with
 

-    /path/to/tracedump 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
 
 
 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
+-------
+
+* 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\apitrace dump application.trace
+
+* Replay the trace with
+
+        \path\to\glretrace application.trace
+
+
+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
+----------------
+
+### Linux ###
+
+Run the application you want to trace as
+
+     LD_PRELOAD=/path/to/apitrace/wrappers/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.

 
 The `LD_PRELOAD` mechanism should work with most applications.  There are some
 applications, e.g., Unigine Heaven, which global function pointers with the
 
 The `LD_PRELOAD` mechanism should work with most applications.  There are some
 applications, e.g., Unigine Heaven, which global function pointers with the


@@ -50,23 +114,23 @@ 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`:
 
 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
+    ln -s glxtrace.so wrappers/libGL.so
+    ln -s glxtrace.so wrappers/libGL.so.1
+    ln -s glxtrace.so wrappers/libGL.so.1.2
+    export LD_LIBRARY_PATH=/path/to/apitrace/wrappers:$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.
 
     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.
 

+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
---------
+### Mac OS X ###

 
 

-Usage on Mac OS X is similar to Linux above, except for the tracing procedure,
-which is instead:
+Run the application you want to trace as

 
     DYLD_LIBRARY_PATH=/path/to/apitrace/wrappers /path/to/application
 
 
     DYLD_LIBRARY_PATH=/path/to/apitrace/wrappers /path/to/application
 


@@ -76,27 +140,6 @@ Note that although Mac OS X has an `LD_PRELOAD` equivalent,
 page for more details about these environment flags.
 
 
 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
-
-
-Advanced command line usage
-===========================
-
-

 Emitting annotations to the trace from GL applications
 ------------------------------------------------------
 
 Emitting annotations to the trace from GL applications
 ------------------------------------------------------
 


@@ -106,7 +149,7 @@ and
 [`GL_GREMEDY_frame_terminator`](http://www.opengl.org/registry/specs/GREMEDY/frame_terminator.txt)
 GL extensions.
 
 [`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
+**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.
 
 the GL implementation.  So all you have to do is to use these extensions when
 available.
 


@@ -135,19 +178,19 @@ Dump GL state at a particular call
 
 You can get a dump of the bound GL state at call 12345 by doing:
 
 
 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.
 
 
 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
 ---------------------------------
 
 
 
 Comparing two traces side by side
 ---------------------------------
 

-    ./scripts/tracediff.sh trace1.trace trace2.trace
+    apitrace diff trace1.trace trace2.trace

 
 This works only on Unices, and it will truncate the traces due to performance
 limitations.
 
 This works only on Unices, and it will truncate the traces due to performance
 limitations.


@@ -158,27 +201,27 @@ Recording a video with FFmpeg
 
 You can make a video of the output by doing
 
 
 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
 
 
 Advanced usage for OpenGL implementors
 ======================================
 
     | ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4
 
 
 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
 ------------------
 
 
 
 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
 
 * obtain reference snapshots, by doing:
 
         mkdir /path/to/snapshots/
 
 * obtain a trace
 
 * 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.
 
 
   on reference system.
 


@@ -186,12 +229,12 @@ These are the steps to create a regression testsuite around apitrace:
 
 * to do a regression test, do:
 
 
 * 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
 
 
 Automated git-bisection


@@ -242,7 +285,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
 
 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).
 
 
 another runtime fault).
 
 


@@ -254,7 +297,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.
 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
 reference software renderer.
 
 This can be achieved with retracediff.py script, which invokes glretrace with