X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=README.markdown;h=38dfa5e21c357ae47a9187ded3d786b895a9dee4;hb=225193db0f50a8f3a1d59d7cff351c9be31e8044;hp=c38804276664853db5256e8a87eee2ef044451b1;hpb=ae2b4d32ed56e3ac193cc7205aeb58082c448ce8;p=apitrace diff --git a/README.markdown b/README.markdown index c388042..38dfa5e 100644 --- a/README.markdown +++ b/README.markdown @@ -3,9 +3,9 @@ About **apitrace** **apitrace** consists of a set of tools to: -* trace OpenGL, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file; +* trace OpenGL, OpenGL ES, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file; -* retrace OpenGL calls from a file; +* retrace OpenGL and OpenGL ES calls from a file; * inspect OpenGL state at any call while retracing; @@ -16,12 +16,12 @@ 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 + 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 @@ -29,19 +29,81 @@ directory. You can specify the written trace filename by setting the View the trace with - /path/to/tracedump application.trace | less -R + apitrace dump --color application.trace -Replay the trace with +Replay an OpenGL trace with - /path/to/glretrace application.trace + glretrace application.trace Pass the `-sb` option to use a single buffered visual. Pass `--help` to glretrace for more options. Start the GUI as - /path/to/qapitrace application.trace + 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 +=========================== + + +Call sets +--------- + +Several tools take `CALLSET` arguments, e.g: + + apitrace dump --calls CALLSET foo.trace + glretrace -S CALLSET foo.trace + +The call syntax is very flexible. Here are a few examples: + + * `4` one call + + * `1,2,4,5` set of calls + + * `"1 2 4 5"` set of calls (commas are optional and can be replaced with whitespace) + + * `1-100/2` calls 1, 3, 5, ..., 99 + + * `1-1000/draw` all draw calls between 1 and 1000 + + * `1-1000/fbo` all fbo changes between calls 1 and 1000 + + * `frame` all calls at end of frames + * `@foo.txt` read call numbers from `foo.txt`, using the same syntax as above + + + +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 @@ -52,23 +114,23 @@ segfault when trying to write to them. For these applications it is possible 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. +To trace the application inside gdb, invoke gdb as: + gdb --ex 'set exec-wrapper env LD_PRELOAD=/path/to/glxtrace.so' --args /path/to/application -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 @@ -78,27 +140,6 @@ Note that although Mac OS X has an `LD_PRELOAD` equivalent, 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 ------------------------------------------------------ @@ -137,19 +178,19 @@ Dump GL state at a particular call You can get a dump of the bound GL state at call 12345 by doing: - /path/to/glretrace -D 12345 application.trace > 12345.json + glretrace -D 12345 application.trace > 12345.json This is precisely the mechanism the GUI obtains its own state. -You can compare two state dumps with the jsondiff.py script: +You can compare two state dumps by doing: - ./scripts/jsondiff.py 12345.json 67890.json + apitrace diff-state 12345.json 67890.json 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. @@ -160,7 +201,7 @@ Recording a video with FFmpeg You can make a video of the output by doing - /path/to/glretrace -s - application.trace \ + glretrace -s - application.trace \ | ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4 @@ -180,7 +221,7 @@ These are the steps to create a regression test-suite around **apitrace**: * obtain reference snapshots, by doing: mkdir /path/to/snapshots/ - /path/to/glretrace -s /path/to/reference/snapshots/ application.trace + glretrace -s /path/to/reference/snapshots/ application.trace on reference system. @@ -188,12 +229,12 @@ These are the steps to create a regression test-suite around **apitrace**: * to do a regression test, do: - /path/to/glretrace -c /path/to/reference/snapshots/ application.trace + glretrace -c /path/to/reference/snapshots/ application.trace - Alternatively, for a HTML summary, use the snapdiff script: + Alternatively, for a HTML summary, use `apitrace diff-images`: - /path/to/glretrace -s /path/to/current/snapshots/ application.trace - ./scripts/snapdiff.py --output summary.html /path/to/reference/snapshots/ /path/to/current/snapshots/ + glretrace -s /path/to/current/snapshots/ application.trace + apitrace diff-images --output summary.html /path/to/reference/snapshots/ /path/to/current/snapshots/ Automated git-bisection