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