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
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
===========================
`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)
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
----------------------------------