]> git.cworth.org Git - apitrace/blob - README.markdown
Update glext headers.
[apitrace] / README.markdown
1 About **apitrace**
2 ==================
3
4 **apitrace** consists of a set of tools to:
5
6 * trace OpenGL, D3D9, D3D8, D3D7, and DDRAW APIs calls to a file;
7
8 * retrace OpenGL calls from a file;
9
10 * visualize trace files, and inspect state.
11
12
13 Basic usage
14 ===========
15
16
17 Linux
18 -----
19
20 Run the application you want to trace as
21
22      LD_PRELOAD=/path/to/glxtrace.so /path/to/application
23
24 and it will generate a trace named `application.trace` in the current
25 directory.  You can specify the written trace filename by setting the
26 `TRACE_FILE` environment variable before running.
27
28 View the trace with
29
30     /path/to/tracedump application.trace | less -R
31
32 Replay the trace with
33
34     /path/to/glretrace application.trace
35
36 Pass the `-sb` option to use a single buffered visual.  Pass `--help` to
37 glretrace for more options.
38
39 Start the GUI as
40
41     /path/to/qapitrace application.trace
42
43
44 The `LD_PRELOAD` mechanism should work with most applications.  There are some
45 applications, e.g., Unigine Heaven, which global function pointers with the
46 same name as GL entrypoints, living in a shared object that wasn't linked with
47 `-Bsymbolic` flag, so relocations to those globals function pointers get
48 overwritten with the address to our wrapper library, and the application will
49 segfault when trying to write to them.  For these applications it is possible
50 to trace by using `glxtrace.so` as an ordinary `libGL.so` and injecting into
51 `LD_LIBRARY_PATH`:
52
53     ln -s glxtrace.so libGL.so
54     ln -s glxtrace.so libGL.so.1
55     ln -s glxtrace.so libGL.so.1.2
56     export LD_LIBRARY_PATH=/path/to/directory/where/glxtrace/is:$LD_LIBRARY_PATH
57     export TRACE_LIBGL=/path/to/real/libGL.so.1
58     /path/to/application
59
60 See the `ld.so` man page for more information about `LD_PRELOAD` and
61 `LD_LIBRARY_PATH` environment flags.
62
63
64
65 Mac OS X
66 --------
67
68 Usage on Mac OS X is similar to Linux above, except for the tracing procedure,
69 which is instead:
70
71     DYLD_LIBRARY_PATH=/path/to/apitrace/wrappers /path/to/application
72
73 Note that although Mac OS X has an `LD_PRELOAD` equivalent,
74 `DYLD_INSERT_LIBRARIES`, it is mostly useless because it only works with
75 `DYLD_FORCE_FLAT_NAMESPACE=1` which breaks most applications.  See the `dyld` man
76 page for more details about these environment flags.
77
78
79 Windows
80 -------
81
82 * Copy `opengl32.dll`, `d3d8.dll`, or `d3d9.dll` from build/wrappers directory
83   to the directory with the application you want to trace.
84
85 * Run the application.
86
87 * View the trace with
88
89         \path\to\tracedump application.trace
90
91 * Replay the trace with
92
93         \path\to\glretrace application.trace
94
95
96 Advanced command line usage
97 ===========================
98
99
100 Dump GL state at a particular call
101 ----------------------------------
102
103 You can get a dump of the bound GL state at call 12345 by doing:
104
105     /path/to/glretrace -D 12345 application.trace > 12345.json
106
107 This is precisely the mechanism the GUI obtains its own state.
108
109 You can compare two state dumps with the jsondiff.py script:
110
111     ./scripts/jsondiff.py 12345.json 67890.json
112
113
114 Comparing two traces side by side
115 ---------------------------------
116
117     ./scripts/tracediff.sh trace1.trace trace2.trace
118
119 This works only on Unices, and it will truncate the traces due to performance
120 limitations.
121
122
123 Recording a video with FFmpeg
124 -----------------------------
125
126 You can make a video of the output by doing
127
128     /path/to/glretrace -s - application.trace \
129     | ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4
130
131
132 Advanced usage for OpenGL implementors
133 ======================================
134
135 There are several avanced usage examples meant for OpenGL implementors.
136
137
138 Regression testing
139 ------------------
140
141 These are the steps to create a regression testsuite around apitrace:
142
143 * obtain a trace
144
145 * obtain reference snapshots, by doing:
146
147         mkdir /path/to/snapshots/
148         /path/to/glretrace -s /path/to/reference/snapshots/ application.trace
149
150   on reference system.
151
152 * prune the snapshots which are not interesting
153
154 * to do a regression test, do:
155
156         /path/to/glretrace -c /path/to/reference/snapshots/ application.trace
157
158   Alternatively, for a HTML summary, use the snapdiff script:
159
160         /path/to/glretrace -s /path/to/current/snapshots/ application.trace
161         ./scripts/snapdiff.py --output summary.html /path/to/reference/snapshots/ /path/to/current/snapshots/
162
163
164 Automated git-bisection
165 -----------------------
166
167 With tracecheck.py it is possible to automate git bisect and pinpoint the
168 commit responsible for a regression.
169
170 Below is an example of using tracecheck.py to bisect a regression in the
171 Mesa-based Intel 965 driver.  But the procedure could be applied to any GL
172 driver hosted on a git repository.
173
174 First, create a build script, named build-script.sh, containing:
175
176     #!/bin/sh
177     set -e
178     export PATH=/usr/lib/ccache:$PATH
179     export CFLAGS='-g'
180     export CXXFLAGS='-g'
181     ./autogen.sh --disable-egl --disable-gallium --disable-glut --disable-glu --disable-glw --with-dri-drivers=i965
182     make clean
183     make "$@"
184
185 It is important that builds are both robust, and efficient.  Due to broken
186 dependency discovery in Mesa's makefile system, it was necessary invoke `make
187 clean` in every iteration step.  `ccache` should be installed to avoid
188 recompiling unchanged source files.
189
190 Then do:
191
192     cd /path/to/mesa
193     export LIBGL_DEBUG=verbose
194     export LD_LIBRARY_PATH=$PWD/lib
195     export LIBGL_DRIVERS_DIR=$PWD/lib
196     git bisect start \
197         6491e9593d5cbc5644eb02593a2f562447efdcbb 71acbb54f49089b03d3498b6f88c1681d3f649ac \
198         -- src/mesa/drivers/dri/intel src/mesa/drivers/dri/i965/
199     git bisect run /path/to/tracecheck.py \
200         --precision-threshold 8.0 \
201         --build /path/to/build-script.sh \
202         --gl-renderer '.*Mesa.*Intel.*' \
203         --retrace=/path/to/glretrace \
204         -c /path/to/reference/snapshots/ \
205         topogun-1.06-orc-84k.trace
206
207 The trace-check.py script will skip automatically when there are build
208 failures.
209
210 The `--gl-renderer` option will also cause a commit to be skipped if the
211 `GL_RENDERER` is unexpected (e.g., when a software renderer or another GL
212 driver is unintentianlly loaded due to missing symbol in the DRI driver, or
213 another runtime fault).
214
215
216 Side by side retracing
217 ----------------------
218
219 In order to determine which draw call a regression first manifests one could
220 generate snapshots for every draw call, using the -S option.  That is, however,
221 very inefficient for big traces with many draw calls.
222
223 A faster approach is to run both the bad and a good GL driver side-by-side.
224 The latter can be either a preivously known good build of the GL driver, or a
225 reference software renderer.
226
227 This can be achieved with retracediff.py script, which invokes glretrace with
228 different environments, allowing to choose the desired GL driver by
229 manipulating variables such as `LD_LIBRARY_PATH` or `LIBGL_DRIVERS_DIR`.
230
231 For example:
232
233     ./scripts/retracediff.py \
234         --ref-env LD_LIBRARY_PATH=/path/to/reference/GL/implementation \
235         -r ./glretrace \
236         --diff-prefix=/path/to/output/diffs \
237         application.trace
238
239
240
241 Links
242 =====
243
244 About **apitrace**:
245
246 * [Official mailing list](http://lists.freedesktop.org/mailman/listinfo/apitrace)
247
248 * [Zack Rusin's blog introducing the GUI](http://zrusin.blogspot.com/2011/04/apitrace.html)
249
250 * [Jose's Fonseca blog introducing the tool](http://jrfonseca.blogspot.com/2008/07/tracing-d3d-applications.html)
251
252
253 Direct3D
254 --------
255
256 Open-source:
257
258 * [Proxy DLL](http://www.mikoweb.eu/index.php?node=21)
259
260   * [Intercept Calls to DirectX with a Proxy DLL](http://www.codeguru.com/cpp/g-m/directx/directx8/article.php/c11453/)
261
262 * [Direct3D 9 API Interceptor](http://graphics.stanford.edu/~mdfisher/D3D9Interceptor.html)
263
264 Closed-source:
265
266 * [Microsoft PIX](http://msdn.microsoft.com/en-us/library/ee417062.aspx)
267
268   * [D3DSpy](http://doc.51windows.net/Directx9_SDK/?url=/directx9_sdk/graphics/programmingguide/TutorialsAndSamplesAndToolsAndTips/Tools/D3DSpy.htm): the predecessor of PIX
269
270 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
271
272
273 OpenGL
274 ------
275
276 Open-source:
277
278 * [BuGLe](http://www.opengl.org/sdk/tools/BuGLe/)
279
280 * [GLIntercept](http://code.google.com/p/glintercept/)
281
282 * [tracy](https://gitorious.org/tracy): OpenGL ES and OpenVG trace, retrace, and state inspection
283
284 Closed-source:
285
286 * [gDEBugger](http://www.gremedy.com/products.php)
287
288 * [glslDevil](http://cumbia.informatik.uni-stuttgart.de/glsldevil/index.html)
289
290 * [AMD GPU PerfStudio](http://developer.amd.com/gpu/PerfStudio/pages/APITraceWindow.aspx)
291