Mention DebugView.

[apitrace] / README.markdown

diff --git a/README.markdown b/README.markdown
index 38dfa5e21c357ae47a9187ded3d786b895a9dee4..ce00ca5d123ee39e49bc30337559ab13ad437500 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -15,21 +15,23 @@ About **apitrace**
 Basic usage
 ===========
 
-
-Linux and Mac OS X
-------------------
-
 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 +45,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 +124,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 ###
 
-Emitting annotations to the trace from GL applications
-------------------------------------------------------
+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.
 
-You can emit string and frame annotations through the
+You can specify the written trace filename by setting the `TRACE_FILE`
+environment variable before running.
+
+
+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 +167,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 +208,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
 ======================================