* retrace OpenGL 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
===========
-Linux
------
+Linux and Mac OS X
+------------------
Run the application you want to trace as
- LD_PRELOAD=/path/to/glxtrace.so /path/to/application
+ /path/to/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
View the trace with
- /path/to/tracedump application.trace | less -R
+ /path/to/apitrace dump --color application.trace | less -R
Replay the trace with
/path/to/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
+===========================
+
+
+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
same name as GL entrypoints, living in a shared object that wasn't linked with
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.
+### 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
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
------------------------------------------------------
[`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.
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.
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
------------------
-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
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).
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