Trivial formatting / consistency fixes.

[apitrace] / BUGS.markdown

diff --git a/BUGS.markdown b/BUGS.markdown
index 09811332e763cfd3d1686dfda58d8440f32d1487..d8258a7be883deae8069dda6e2fbc7da8a699a37 100644 (file)
--- a/BUGS.markdown
+++ b/BUGS.markdown
@@ -27,12 +27,11 @@ is no immediate plan to address them, because either:
 That said, feel free to file an issue and/or send an email to the mailing list
 if:
 
 That said, feel free to file an issue and/or send an email to the mailing list
 if:
 

-* 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;
+* you want discuss the rationale, propose your ideas on how to address it, or
+  volunteer to work on it;

 
 

-* file the issue in the issue tracker (or comment to it if it already exists)
-  if it is important for you and you would like to see it addressed sooner
-  rather than later.
+* a known issue is important for you and you would like to see it addressed
+  sooner rather than later.

 
 
 Tracing
 
 
 Tracing


@@ -50,12 +49,33 @@ Tracing
   There is no way to distinguish the fake calls from those actually
   made by the application yet.
 
   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
 ---------
 
 * 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
 * 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


@@ -71,10 +91,8 @@ Retracing
   a standard 32bit RGBA, 24bit depth, 8bit alpha, double buffer visual.  Unless
   overridden on command line.
 
   a standard 32bit RGBA, 24bit depth, 8bit alpha, double buffer visual.  Unless
   overridden on command line.
 

-* Multi-threaded OpenGL is not yet supported.
-
-* OpenGL context sharing is not fully respected -- all contexts are expected to
-  share state, and most likely there
+* OpenGL context sharing is not fully respected -- all contexts are assumed to
+  share state.  This is by far the most common case though.

 
 
 GUI
 
 
 GUI


@@ -119,7 +137,7 @@ github issue tracker doesn't support attachments.
 Please attach long logs to https://gist.github.com/ and paste the URL into the
 issue description.
 
 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
+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.
 
 server you control, or use a file upload service such as http://dropbox.com/
 and paste the URL into the issue description.
 


@@ -158,7 +176,8 @@ Linux/MacOSX
 ------------
 
 Please rebuild apitrace with debugging information, by passing
 ------------
 
 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:
 
 
 To obtain a stack back-trace, run the application with gdb from a terminal:
 


@@ -167,6 +186,10 @@ To obtain a stack back-trace, run the application with gdb from a terminal:
     ...
     (gdb) bt
 
     ...
     (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:
 
 
 See also more detailed and Distro specific instructions: