X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=README.markdown;h=4bf809e9e0946d5cc0aac360852ea86229a608f6;hb=ff6dad3ca0f52fb91b5035843df7da79126291e1;hp=685f221c13a0c4c9c74eb7af672ac4db6b636620;hpb=3801952b80cd7a7160f6410518f6e3740d461b60;p=apitrace diff --git a/README.markdown b/README.markdown index 685f221..4bf809e 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,60 +151,9 @@ To trace the application inside gdb, invoke gdb as: ### Android ### -The following instructions should work at least for Android Ice Scream -Sandwitch: - -For standalone applications the instructions above for Linux should -work. 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 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 ### @@ -302,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. @@ -359,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 @@ -470,3 +419,54 @@ Or on Windows: [![githalytics.com alpha](https://cruel-carlota.pagodabox.com/c1062ad633aa7a458e9d7520021307e4 "githalytics.com")](http://githalytics.com/apitrace/apitrace) + +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.