X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=README.markdown;h=497351abe99697dc285e2c0607aaa48da2267f0e;hb=905c1283897c27188ef1984f302379befc9de9b5;hp=f551ad2f9cf9a69581d4b864d91261a750d014da;hpb=05ba419f445188f49bb6724b861095a250a79e6c;p=apitrace diff --git a/README.markdown b/README.markdown index f551ad2..497351a 100644 --- a/README.markdown +++ b/README.markdown @@ -7,19 +7,21 @@ About **apitrace** * 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 @@ -27,7 +29,7 @@ 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 @@ -41,6 +43,40 @@ Start the GUI as /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 @@ -50,23 +86,19 @@ 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. +### 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 @@ -76,25 +108,37 @@ 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 +Emitting annotations to the trace from GL applications +------------------------------------------------------ - \path\to\tracedump application.trace +You can emit string and frame annotations 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) +GL extensions. -* Replay the trace with +**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. - \path\to\glretrace application.trace +For example, if you use [GLEW](http://glew.sourceforge.net/) to dynamically +detect and use GL extensions, you could easily accomplish this by doing: + void foo() { + + if (GLEW_GREMEDY_string_marker) { + glStringMarkerGREMEDY(0, __FUNCTION__ ": enter"); + } + + ... + + if (GLEW_GREMEDY_string_marker) { + glStringMarkerGREMEDY(0, __FUNCTION__ ": leave"); + } + + } -Advanced command line usage -=========================== +This has the added advantage of working equally well with gDEBugger. Dump GL state at a particular call @@ -114,7 +158,7 @@ You can compare two state dumps with the jsondiff.py script: 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. @@ -132,13 +176,13 @@ You can make a video of the output by doing 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 @@ -209,7 +253,7 @@ failures. 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). @@ -221,7 +265,7 @@ generate snapshots for every draw call, using the `-S` option. That is, however 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