Document how to get apitrace binaries.

[apitrace] / README.markdown

diff --git a/README.markdown b/README.markdown
index 38dfa5e21c357ae47a9187ded3d786b895a9dee4..3fdcda567998ede748ed403182eb0026a1dc57d8 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -15,21 +15,28 @@ About **apitrace**
 Basic usage
 ===========
 
-
-Linux and Mac OS X
-------------------
+To obtain apitrace either [download the latest
+binaries](https://github.com/apitrace/apitrace/downloads) for your platform if
+available, or follow the (build instructions)[INSTALL.markdown] to build it
+yourself.
 
 Run the application you want to trace as
 
-    apitrace trace /path/to/application [args...]
+    apitrace trace --api API /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
-`TRACE_FILE` environment variable before running.
+directory.  You can specify the written trace filename by passing the
+`--output` command line option.
+
+Problems while tracing (e.g, if the application uses calls/parameters
+unsupported by apitrace) will be reported via stderr output on Unices.  On
+Windows you'll need to run
+[DebugView](http://technet.microsoft.com/en-us/sysinternals/bb896647) to view
+these messages.
 
 View the trace with
 
-    apitrace dump --color application.trace
+    apitrace dump application.trace
 
 Replay an OpenGL trace with
 
@@ -43,23 +50,6 @@ Start the GUI as
     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
 ===========================
 
@@ -139,11 +129,20 @@ Note that although Mac OS X has an `LD_PRELOAD` equivalent,
 `DYLD_FORCE_FLAT_NAMESPACE=1` which breaks most applications.  See the `dyld` man
 page for more details about these environment flags.
 
+### Windows ###
+
+Copy `opengl32.dll`, `d3d8.dll`, or `d3d9.dll` from the wrappers directory
+to the directory with the application you want to trace.  Then run the
+application.
 
-Emitting annotations to the trace from GL applications
-------------------------------------------------------
+You can specify the written trace filename by setting the `TRACE_FILE`
+environment variable before running.
 
-You can emit string and frame annotations through the
+
+Emitting annotations to the trace
+---------------------------------
+
+From OpenGL applications you can embed annotations in the trace file 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)
@@ -173,6 +172,15 @@ detect and use GL extensions, you could easily accomplish this by doing:
 This has the added advantage of working equally well with gDEBugger.
 
 
+From OpenGL ES applications you can embed annotations in the trace file through the
+[`GL_EXT_debug_marker`](http://www.khronos.org/registry/gles/extensions/EXT/EXT_debug_marker.txt)
+extension.
+
+
+For Direct3D applications you can follow the same procedure used for 
+[instrumenting an application for PIX](http://technet.microsoft.com/en-us/query/ee417250)
+
+
 Dump GL state at a particular call
 ----------------------------------
 
@@ -205,6 +213,18 @@ You can make a video of the output by doing
     | ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4
 
 
+Triming a trace
+---------------
+
+You can make a smaller trace by doing:
+
+    apitrace trim --callset 100-1000 -o trimed.trace applicated.trace
+
+If you need precise control over which calls to trim you can specify the
+individual call numbers a plaintext file, as described in the 'Call sets'
+section above.
+
+
 Advanced usage for OpenGL implementors
 ======================================
 
@@ -218,13 +238,11 @@ These are the steps to create a regression test-suite around **apitrace**:
 
 * obtain a trace
 
-* obtain reference snapshots, by doing:
+* obtain reference snapshots, by doing on a reference system:
 
-        mkdir /path/to/snapshots/
+        mkdir /path/to/reference/snapshots/
         glretrace -s /path/to/reference/snapshots/ application.trace
 
-  on reference system.
-
 * prune the snapshots which are not interesting
 
 * to do a regression test, do:
@@ -233,8 +251,8 @@ These are the steps to create a regression test-suite around **apitrace**:
 
   Alternatively, for a HTML summary, use `apitrace diff-images`:
 
-        glretrace -s /path/to/current/snapshots/ application.trace
-        apitrace diff-images --output summary.html /path/to/reference/snapshots/ /path/to/current/snapshots/
+        glretrace -s /path/to/test/snapshots/ application.trace
+        apitrace diff-images --output summary.html /path/to/reference/snapshots/ /path/to/test/snapshots/
 
 
 Automated git-bisection