======================
To obtain apitrace either [download the latest
-binaries](https://github.com/apitrace/apitrace/downloads) for your platform if
+binaries](http://apitrace.github.com/#download) for your platform if
available, or follow the instructions in INSTALL.markdown to build it yourself.
On 64bits Linux and Windows platforms you'll need apitrace binaries that match
the architecture (32bits or 64bits) of the application being traced.
Replay an OpenGL trace with
- glretrace application.trace
+ apitrace retrace application.trace
Pass the `--sb` option to use a single buffered visual. Pass `--help` to
-`glretrace` for more options.
-
-EGL traces must be replayed with `eglretrace` instead of `glretrace`.
+`apitrace retrace` for more options.
Basic GUI usage
Several tools take `CALLSET` arguments, e.g:
- apitrace dump --calls CALLSET foo.trace
- glretrace -S CALLSET foo.trace
+ apitrace dump --calls=CALLSET foo.trace
+ apitrace dump-images --calls=CALLSET foo.trace
The call syntax is very flexible. Here are a few examples:
You can specify the written trace filename by setting the `TRACE_FILE`
environment variable before running.
+For D3D10 and higher you really must use `apitrace trace -a DXGI ...`. This is
+because D3D10-11 API span many DLLs which depend on each other, and once a DLL
+with a given name is loaded Windows will reuse it for LoadLibrary calls of the
+same name, causing internal calls to be traced erroneously. `apitrace trace`
+solves this issue by injecting a DLL `dxgitrace.dll` and patching all modules
+to hook only the APIs of interest.
+
Emitting annotations to the trace
---------------------------------
You can get a dump of the bound GL state at call 12345 by doing:
- glretrace -D 12345 application.trace > 12345.json
+ apitrace retrace -D 12345 application.trace > 12345.json
This is precisely the mechanism the GUI obtains its own state.
You can make a video of the output by doing
- glretrace -s - application.trace \
+ apitrace dump-images -o - application.trace \
| ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4
For example, to record all profiling data and utilise the per shader script:
- ./glretrace --pgpu --pcpu --ppd foo.trace | ./scripts/profileshader.py
+ apitrace retrace --pgpu --pcpu --ppd foo.trace | ./scripts/profileshader.py
Advanced usage for OpenGL implementors
* prune the snapshots which are not interesting
-* to do a regression test, do:
-
- glretrace -c /path/to/reference/snapshots/ application.trace
-
- Alternatively, for a HTML summary, use `apitrace diff-images`:
+* to do a regression test, use `apitrace diff-images`:
apitrace dump-images -o /path/to/test/snapshots/ application.trace
apitrace diff-images --output summary.html /path/to/reference/snapshots/ /path/to/test/snapshots/