Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 188 lines (115 sloc) 5.711 kB
05ba419 @jrfonseca Add documentation on how to report bugs.
jrfonseca authored
1 Reporting bugs
2 ==============
3
2f634d5 @jrfonseca Document known issues.
jrfonseca authored
4 Before reporting, please skim through the known issues below.
05ba419 @jrfonseca Add documentation on how to report bugs.
jrfonseca authored
5
2f634d5 @jrfonseca Document known issues.
jrfonseca authored
6 Report any issues on [github](https://github.com/apitrace/apitrace/issues),
7 always including the following information:
05ba419 @jrfonseca Add documentation on how to report bugs.
jrfonseca authored
8
9 * operating system name and version
10
11 * OpenGL/D3D driver name and version
12
13
2f634d5 @jrfonseca Document known issues.
jrfonseca authored
14 Known issues
15 ============
16
17 These are issues that the developers are already aware of, but for which there
18 is no immediate plan to address them, because either:
19
20 * they stem from architectural limitations that are difficult to overcome
21 and/or time-consuming;
22
23 * they are corners cases that are thought to be of very little practical use;
24
25 * merely lack of time/opportunity.
26
27 That said, feel free to file an issue and/or send an email to the mailing list
28 if:
29
30 * send an email to the mailing list if you want discuss the rationale, propose
31 your ideas on how to address it, or volunteer to work on it;
32
33 * file the issue in the issue tracker (or comment to it if it already exists)
34 if it is important for you and you would like to see it addressed sooner
35 rather than later.
36
37
38 Tracing
39 -------
40
41 * Fake calls may be emitted in the trace, in order to provide complete
42 information for retracing. The typical case is OpenGL vertex arrays in user
43 memory (as opposed to VBOs): where glXxxPointer calls will be deferred,
44 glInterleavedArrays will be decomposed, etc.
45
46 This should not affect the rendered output, but it may use different paths in
47 the OpenGL driver, exercising different paths and with different performance
48 characteristics.
49
50 There is no way to distinguish the fake calls from those actually
51 made by the application yet.
52
53 * On MacOSX, the internal OpenGL calls done by GLU are not traced yet.
54
55
56 Retracing
57 ---------
58
59 * glretrace needs to infer window sizes from glViewport calls, because calls
60 that create/resize windows happen outside of OpenGL and are not traced.
61 Therefore window will be missing if the application relies on the default
62 viewport instead of explicitly invoking glViewport; or it will to too big if
63 the window is shrunk. Most apps call glViewport before rendering.
64
65 * OS specific OpenGL APIs (WGL, GLX, CGL, etc), are not retraced literally, but
66 instead partially emulated. This is by design, to allow traces to be
67 retraced on any OS, as the focus is on the OS-independent parts of OpenGL API.
68
69 * There is no guarantee that the same visual that was used on tracing will be
70 used for retracing OpenGL. Actually currently, glretrace will always choose
71 a standard 32bit RGBA, 24bit depth, 8bit alpha, double buffer visual. Unless
72 overridden on command line.
73
74 * Multi-threaded OpenGL is not yet supported.
75
76 * OpenGL context sharing is not fully respected -- all contexts are expected to
77 share state, and most likely there
78
79
80 GUI
81 ---
82
83 * Not all types of arguments can be edited.
84
85
86
05ba419 @jrfonseca Add documentation on how to report bugs.
jrfonseca authored
87 Proprietary/confidential applications
88 =====================================
89
90 Issues should be preferably filed on github to facilitate collaborative
91 development and for future reference.
92
93 Access to applications source code is not required -- binaries are sufficient.
94
95 If the bug happens with a proprietary application, and you don't want to
96 publicly release the application and/or any data collected from it, then
97 alternatively you can provide the necessary application and/or data via e-mail,
98 to *jose dot r dot fonseca at gmail dot com*.
99
100 If it is not technically/legally feasible for you to provide application and/or
101 data at all, then you must be either:
102
103 * develop and provide a test application, stripped-down of all
104 proprietary/confidential data, but that can reproduce the issue;
105
106 * be willing/able to do the investigation of the issue, namely to identify the
107 root cause of the issue (e.g., which OpenGL call is not properly handled and
108 why), using all necessary tools (such as debuggers).
109
110 Failure to do so will render the apitrace authors powerless to address the
111 issue.
112
113
114 Attachments
115 ===========
116
117 github issue tracker doesn't support attachments.
118
119 Please attach long logs to https://gist.github.com/ and paste the URL into the
120 issue description.
121
122 For big attachments, such as traces, please upload it temporarily to a web
7a6a32e @jrfonseca Remove references to megaupload
jrfonseca authored
123 server you control, or use a file upload service such as http://dropbox.com/
124 and paste the URL into the issue description.
05ba419 @jrfonseca Add documentation on how to report bugs.
jrfonseca authored
125
126 Trace files are only slightly compressed (for performance reasons). You can
127 further reduce their size when attaching/uploading by compressing with
128 [XZ](http://tukaani.org/xz/) or [7-Zip](http://www.7-zip.org/).
129
130
131 Bugs on tracing
132 ===============
133
134 For bugs that happen while tracing (e.g., crashes while tracing the
135 application, or incorrect traces) please:
136
137 * provide information on how to obtain the application;
138
139 * describe how you were using it when the issue happened.
140
141
142 Bugs on retracing/GUI
143 =====================
144
145 For bugs on retracing (e.g. crashes when retracing the application,
146 incorrect inconsistent rendering, or viewing with the GUI) please:
147
148 * provide the trace file;
149
150 * describe the results you got, and what results you were expecting.
151
152
153 Obtaining stack back-traces
154 ===========================
155
156
157 Linux/MacOSX
158 ------------
159
160 Please rebuild apitrace with debugging information, by passing
161 `-DCMAKE_BUILD_TYPE=Debug` to cmake.
162
163 To obtain a stack back-trace, run the application with gdb from a terminal:
164
165 $ gdb --args application arg1 arg2 ...
166 (gdb) run
167 ...
168 (gdb) bt
169
170
e34099b @jrfonseca Add a few links on how to obtain stack back traces.
jrfonseca authored
171 See also more detailed and Distro specific instructions:
172
173 * http://wiki.debian.org/HowToGetABacktrace
174
175 * https://wiki.ubuntu.com/Backtrace
176
177 * http://fedoraproject.org/wiki/StackTraces
178
179 * http://live.gnome.org/GettingTraces
180
181
05ba419 @jrfonseca Add documentation on how to report bugs.
jrfonseca authored
182 Windows
183 -------
184
ff3abc6 @jrfonseca Minor tweaks to docs.
jrfonseca authored
185 See:
05ba419 @jrfonseca Add documentation on how to report bugs.
jrfonseca authored
186
ff3abc6 @jrfonseca Minor tweaks to docs.
jrfonseca authored
187 * https://developer.mozilla.org/en/how_to_get_a_stacktrace_with_windbg
Something went wrong with that request. Please try again.