X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=BUGS.markdown;h=d8258a7be883deae8069dda6e2fbc7da8a699a37;hb=1e087c7e8518f0f1a99d9a7abc941019ee65af74;hp=34e78e181c908febc0451c3371ee0551f2d2a4b5;hpb=ff3abc666dd2fa955ced1e0d6472ea3d94ab66a2;p=apitrace diff --git a/BUGS.markdown b/BUGS.markdown index 34e78e1..d8258a7 100644 --- a/BUGS.markdown +++ b/BUGS.markdown @@ -1,16 +1,107 @@ Reporting bugs ============== -Please report any issues on -[github](https://github.com/apitrace/apitrace/issues). +Before reporting, please skim through the known issues below. -Always include the following information: +Report any issues on [github](https://github.com/apitrace/apitrace/issues), +always including the following information: * operating system name and version * OpenGL/D3D driver name and version +Known issues +============ + +These are issues that the developers are already aware of, but for which there +is no immediate plan to address them, because either: + +* they stem from architectural limitations that are difficult to overcome + and/or time-consuming; + +* they are corners cases that are thought to be of very little practical use; + +* merely lack of time/opportunity. + +That said, feel free to file an issue and/or send an email to the mailing list +if: + +* you want discuss the rationale, propose your ideas on how to address it, or + volunteer to work on it; + +* a known issue is important for you and you would like to see it addressed + sooner rather than later. + + +Tracing +------- + +* Fake calls may be emitted in the trace, in order to provide complete + information for retracing. The typical case is OpenGL vertex arrays in user + memory (as opposed to VBOs): where glXxxPointer calls will be deferred, + glInterleavedArrays will be decomposed, etc. + + This should not affect the rendered output, but it may use different paths in + the OpenGL driver, exercising different paths and with different performance + characteristics. + + There is no way to distinguish the fake calls from those actually + made by the application yet. + +* Huge traces will be generated for applications that make extensive use of + immediate mode drawing (ie., glBegin/glEnd), use vertex/element arrays in + user memory, or generate a lot of dynamic vertex data per frame. This is + because large quantities of (often redundant) data will be recorded over and + over; and although the traces are compressed, the compression algorithms used + aim a good performance/compression balance, hence fail to identify and remove + the redundancy at this scale. + + However, this should not be a problem for modern OpenGL applications that + make an efficient use of VBOs and vertex shaders. + +* On MacOSX, the internal OpenGL calls done by GLU are not traced yet. + + +Retracing +--------- + +* Replaying can take substantially more CPU due to the overhead of reading the + trace file from disk. + + However, the overhead should not be significant for modern 3D applications + that do efficient use of VBOs and vertex shaders. The communication between + CPU to GPU can easily be a bottleneck on the powerful discrete GPUs of + nowadays, and trace overhead tend to be propotional so it is not a + coincidence that applications that are optimized for modern GPUs will also be + traced and replayed efficiently. + +* glretrace needs to infer window sizes from glViewport calls, because calls + that create/resize windows happen outside of OpenGL and are not traced. + Therefore window will be missing if the application relies on the default + viewport instead of explicitly invoking glViewport; or it will to too big if + the window is shrunk. Most apps call glViewport before rendering. + +* OS specific OpenGL APIs (WGL, GLX, CGL, etc), are not retraced literally, but + instead partially emulated. This is by design, to allow traces to be + retraced on any OS, as the focus is on the OS-independent parts of OpenGL API. + +* There is no guarantee that the same visual that was used on tracing will be + used for retracing OpenGL. Actually currently, glretrace will always choose + a standard 32bit RGBA, 24bit depth, 8bit alpha, double buffer visual. Unless + overridden on command line. + +* OpenGL context sharing is not fully respected -- all contexts are assumed to + share state. This is by far the most common case though. + + +GUI +--- + +* Not all types of arguments can be edited. + + + Proprietary/confidential applications ===================================== @@ -46,10 +137,9 @@ github issue tracker doesn't support attachments. Please attach long logs to https://gist.github.com/ and paste the URL into the issue description. -For big attachments, such as traces, please upload it temporarily to a web -server you control, or use a file upload service such as -http://www.megaupload.com/ or http://dropbox.com/ and paste the URL into the -issue description. +For big attachments, such as traces, please upload them temporarily to a web +server you control, or use a file upload service such as http://dropbox.com/ +and paste the URL into the issue description. Trace files are only slightly compressed (for performance reasons). You can further reduce their size when attaching/uploading by compressing with @@ -86,7 +176,8 @@ Linux/MacOSX ------------ Please rebuild apitrace with debugging information, by passing -`-DCMAKE_BUILD_TYPE=Debug` to cmake. +`-DCMAKE_BUILD_TYPE=Debug` to cmake, or editing its value in `CMakeCache.txt` +and rebuilding. To obtain a stack back-trace, run the application with gdb from a terminal: @@ -95,6 +186,10 @@ To obtain a stack back-trace, run the application with gdb from a terminal: ... (gdb) bt +On Linux, to trace an application inside gdb the `LD_PRELOAD` environment +variable should be set from within gdb like: + + gdb --ex 'set exec-wrapper env LD_PRELOAD=/path/to/glxtrace.so' --args application arg1 ... See also more detailed and Distro specific instructions: