git.cworth.org Git - apitrace/blob - BUGS.markdown

   1 Reporting bugs
   2 ==============
   3
   4 Before reporting, please skim through the known issues below.
   5
   6 Report any issues on [github](https://github.com/apitrace/apitrace/issues),
   7 always including the following information:
   8
   9 * operating system name and version
  10
  11 * OpenGL/D3D driver name and version
  12
  13
  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 * Huge traces will be generated for applications that make extensive use of
  54   immediate mode drawing (ie., glBegin/glEnd), use vertex/element arrays in
  55   user memory, or generate a lot of dynamic vertex data per frame.
  56
  57   However, this should not be a problem for modern OpenGL applications that
  58   make an efficient use of VBOs and vertex shaders.
  59
  60 * On MacOSX, the internal OpenGL calls done by GLU are not traced yet.
  61
  62
  63 Retracing
  64 ---------
  65
  66 * Replaying can take substantially more CPU due to the overhead of reading the
  67   trace file from disk.
  68
  69   However, the overhead should not be significant for modern 3D applications
  70   that do efficient use of VBOs and vertex shaders.  The communication between
  71   CPU to GPU can easily be a bottleneck on the powerful discrete GPUs of
  72   nowadays, and trace overhead tend to be propotional so it is not a
  73   coincidence that applications that are optimized for modern GPUs will also be
  74   traced and replayed efficiently.
  75
  76 * glretrace needs to infer window sizes from glViewport calls, because calls
  77   that create/resize windows happen outside of OpenGL and are not traced.
  78   Therefore window will be missing if the application relies on the default
  79   viewport instead of explicitly invoking glViewport; or it will to too big if
  80   the window is shrunk.  Most apps call glViewport before rendering.
  81
  82 * OS specific OpenGL APIs (WGL, GLX, CGL, etc), are not retraced literally, but
  83   instead partially emulated.  This is by design, to allow traces to be
  84   retraced on any OS, as the focus is on the OS-independent parts of OpenGL API.
  85
  86 * There is no guarantee that the same visual that was used on tracing will be
  87   used for retracing OpenGL.  Actually currently, glretrace will always choose
  88   a standard 32bit RGBA, 24bit depth, 8bit alpha, double buffer visual.  Unless
  89   overridden on command line.
  90
  91 * Multi-threaded OpenGL is not yet supported.
  92
  93 * OpenGL context sharing is not fully respected -- all contexts are expected to
  94   share state, and most likely there
  95
  96
  97 GUI
  98 ---
  99
 100 * Not all types of arguments can be edited.
 101
 102
 103
 104 Proprietary/confidential applications
 105 =====================================
 106
 107 Issues should be preferably filed on github to facilitate collaborative
 108 development and for future reference.
 109
 110 Access to applications source code is not required -- binaries are sufficient.
 111
 112 If the bug happens with a proprietary application, and you don't want to
 113 publicly release the application and/or any data collected from it, then
 114 alternatively you can provide the necessary application and/or data via e-mail,
 115 to *jose dot r dot fonseca at gmail dot com*.
 116
 117 If it is not technically/legally feasible for you to provide application and/or
 118 data at all, then you must be either:
 119
 120 * develop and provide a test application, stripped-down of all
 121   proprietary/confidential data, but that can reproduce the issue;
 122
 123 * be willing/able to do the investigation of the issue, namely to identify the
 124   root cause of the issue (e.g., which OpenGL call is not properly handled and
 125   why), using all necessary tools (such as debuggers).
 126
 127 Failure to do so will render the apitrace authors powerless to address the
 128 issue.
 129
 130
 131 Attachments
 132 ===========
 133
 134 github issue tracker doesn't support attachments.
 135
 136 Please attach long logs to https://gist.github.com/ and paste the URL into the
 137 issue description.
 138
 139 For big attachments, such as traces, please upload it temporarily to a web
 140 server you control, or use a file upload service such as http://dropbox.com/
 141 and paste the URL into the issue description.
 142
 143 Trace files are only slightly compressed (for performance reasons).  You can
 144 further reduce their size when attaching/uploading by compressing with
 145 [XZ](http://tukaani.org/xz/) or [7-Zip](http://www.7-zip.org/).
 146
 147
 148 Bugs on tracing
 149 ===============
 150
 151 For bugs that happen while tracing (e.g., crashes while tracing the
 152 application, or incorrect traces) please:
 153
 154 * provide information on how to obtain the application;
 155
 156 * describe how you were using it when the issue happened.
 157
 158
 159 Bugs on retracing/GUI
 160 =====================
 161
 162 For bugs on retracing (e.g. crashes when retracing the application,
 163 incorrect inconsistent rendering, or viewing with the GUI) please:
 164
 165 * provide the trace file;
 166
 167 * describe the results you got, and what results you were expecting.
 168
 169
 170 Obtaining stack back-traces
 171 ===========================
 172
 173
 174 Linux/MacOSX
 175 ------------
 176
 177 Please rebuild apitrace with debugging information, by passing
 178 `-DCMAKE_BUILD_TYPE=Debug` to cmake.
 179
 180 To obtain a stack back-trace, run the application with gdb from a terminal:
 181
 182     $ gdb --args application arg1 arg2 ...
 183     (gdb) run
 184     ...
 185     (gdb) bt
 186
 187
 188 See also more detailed and Distro specific instructions:
 189
 190 * http://wiki.debian.org/HowToGetABacktrace
 191
 192 * https://wiki.ubuntu.com/Backtrace
 193
 194 * http://fedoraproject.org/wiki/StackTraces
 195
 196 * http://live.gnome.org/GettingTraces
 197
 198
 199 Windows
 200 -------
 201
 202 See:
 203
 204 * https://developer.mozilla.org/en/how_to_get_a_stacktrace_with_windbg