X-Git-Url: https://git.cworth.org/git?p=apitrace;a=blobdiff_plain;f=README.markdown;h=7545982e1110556bc9726aa53e261a8c4fdf4afd;hp=1e1d808329770972b0f0e3829c9b626229294634;hb=HEAD;hpb=d01f837047b58415474fe7e842521c4d0fbef471 diff --git a/README.markdown b/README.markdown index 1e1d808..7545982 100644 --- a/README.markdown +++ b/README.markdown @@ -5,7 +5,7 @@ About **apitrace** * trace OpenGL, OpenGL ES, Direct3D, and DirectDraw APIs calls to a file; -* retrace OpenGL and OpenGL ES calls from a file; +* replay OpenGL and OpenGL ES calls from a file; * inspect OpenGL state at any call while retracing; @@ -49,10 +49,10 @@ View the trace with Replay an OpenGL trace with - apitrace retrace application.trace + apitrace replay application.trace Pass the `--sb` option to use a single buffered visual. Pass `--help` to -`apitrace retrace` for more options. +`apitrace replay` for more options. Basic GUI usage @@ -151,68 +151,9 @@ To trace the application inside gdb, invoke gdb as: ### Android ### -The following instructions should work at least for Android Ice Scream -Sandwitch. - -To trace applications started from within the Android VM process -(`app_process` aka zygote) you'll have to wrap this process and enable -tracing dynamically for the application to be traced. - -- Wrapping the android main VM process: - - In the Android root /init.rc add the `LD_PRELOAD` setting to zygote's - environment in the 'service zygote' section: - - service zygote ... - setenv LD_PRELOAD /data/egltrace.so - ... - - Note that ICS will overwrite the /init.rc during each boot with the - version in the recovery image. So you'll have to change the file in - your ICS source tree, rebuild and reflash the device. - Rebuilding/reflashing only the recovery image should be sufficient. - -- Copy egltrace.so to /data - - On the host: - - adb push /path/to/apitrace/build/wrappers/egltrace.so /data - -- Adjust file permissions to store the trace file: - - By default egltrace.so will store the trace in - `/data/app_process.trace`. For this to work for applications running - with a uid other than 0, you have to allow writes to the `/data` - directory on the device: - - chmod 0777 /data - -- Enable tracing for a specific process name: - - To trace for example the Settings application: - - setprop debug.apitrace.procname com.android.settings - - In general this name will match what `ps` reports. - -- Start the application: - - If the application was already running, for example due to ICS's way - of pre-starting the apps, you might have to kill the application - first: - - kill - - Launch the application for example from the application menu. - -To trace standalone applications do: - - adb push /path/to/apitrace/build/wrappers/egltrace.so /data - adb shell - # cd /data/local/tmp - # LD_PRELOAD=/data/egltrace.so test-opengl-gl2_basic - adb pull /data/local/tmp/test-opengl-gl2_basic.trace - eglretrace test-opengl-gl2_basic.trace +To trace standalone native OpenGL ES applications, use +`LD_PRELOAD=/path/to/egltrace.so /path/to/application` like described in the +previous section. To trace Java applications, refer to Dalvik.markdown. ### Mac OS X ### @@ -310,7 +251,7 @@ Dump GL state at a particular call You can get a dump of the bound GL state at call 12345 by doing: - apitrace retrace -D 12345 application.trace > 12345.json + apitrace replay -D 12345 application.trace > 12345.json This is precisely the mechanism the GUI obtains its own state. @@ -367,7 +308,7 @@ table which displays profiling results per shader. For example, to record all profiling data and utilise the per shader script: - apitrace retrace --pgpu --pcpu --ppd foo.trace | ./scripts/profileshader.py + apitrace replay --pgpu --pcpu --ppd foo.trace | ./scripts/profileshader.py Advanced usage for OpenGL implementors @@ -477,4 +418,57 @@ Or on Windows: python scripts\retracediff.py --retrace \path\to\glretrace.exe --ref-env TRACE_LIBGL=\path\to\reference\opengl32.dll application.trace +Advanced GUI usage +================== + +qapitrace has rudimentary support for replaying traces on a remote +target device. This can be useful, for example, when developing for an +embedded system. The primary GUI will run on the local host, while any +replays will be performed on the target device. + +In order to target a remote device, use the command-line: + + qapitrace --remote-target + +In order for this to work, the following must be available in the +system configuration: + +1. It must be possible for the current user to initiate an ssh session + that has access to the target's window system. The command to be + exectuted by qapitrace will be: + + ssh glretrace + + For example, if the target device is using the X window system, one + can test whether an ssh session has access to the target X server + with: + + ssh xdpyinfo + + If this command fails with something like "cannot open display" + then the user will have to configure the target to set the DISPLAY + environment variable, (for example, setting DISPLAY=:0 in the + .bashrc file on the target or similar). + + Also, note that if the ssh session requires a custom username, then + this must be configured on the host side so that ssh can be + initiated without a username. + + For example, if you normally connect with `ssh user@192.168.0.2` + you could configure ~/.ssh/config on the host with a block such as: + + Host target + HostName 192.168.0.2 + User user + + And after this you should be able to connect with `ssh target` so + that you can also use `qapitrace --remote-target target`. + +2. The target host must have a functional glretrace binary available + +3. The target host must have access to at the same path + in the filesystem as the path on the host system being + passed to the qapitrace command line. + + [![githalytics.com alpha](https://cruel-carlota.pagodabox.com/c1062ad633aa7a458e9d7520021307e4 "githalytics.com")](http://githalytics.com/apitrace/apitrace)