added section on libGL/dlopen problems

1 files changed, 45 insertions, 1 deletions

diff --git a/xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml b/xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml
index 795c01c62..a4dd1f4f6 100644
--- a/xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml
+++ b/xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml
@@ -10,7 +10,7 @@
       <title>DRI User Guide
       <author><htmlurl url="http://www.precisioninsight.com/"
                        name="Precision Insight, Inc.">
-      <date>5 April 2000
+      <date>15 April 2000
 
     <ident>
     $XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml,v 1.3 2000/04/05 05:38:41 brianp Exp $
@@ -747,6 +747,50 @@
           which will be addressed in the future.
 
 
+      <sect1>libGL.so and dlopen()
+<p>
+          A number of popular OpenGL applications on Linux (such as Quake3,
+          HereticII, Heavy Gear 2, etc) dynamically open the libGL.so
+          library at runtime with dlopen(), rather than linking with -lGL
+          at compile/link time.
+<p>
+          If dynamic loading of libGL.so is not implemented carefully, there
+          can be a number of serious problems.
+          Here are the things to be careful of in your application:
+          <itemize>
+          <item>Specify the RTLD_GLOBAL flag to dlopen().
+            If you don't do this then you'll likely see a runtime error message
+            complaining that _glapi_Context is undefined when libGL.so
+            tries to open a hardware-specific driver.
+            Without this flag, <em>nested</em> opening of dynamic libraries
+            does not work.
+          <item>Do not close the library with dlclose() until after
+            XCloseDisplay() has been called.
+            When libGL.so initializes itself it registers several callbacks
+            functions with Xlib.
+            When XCloseDisplay() is called those callback functions are
+            called.
+            If libGL.so has already been unloaded with dlclose() this will
+            cause a segmentation fault.
+          <item>
+            Your application should link with -lpthread.
+            On Linux, libGL.so uses the pthreads library in order to provide
+            thread safety.
+            There is apparently a bug in the dlopen()/dlclose() code which
+            causes crashes if the library uses pthreads but the parent
+            application doesn't.
+            The only known work-around is to link the application with
+            -lpthread.
+          </itemize>
+
+          Some applications don't yet incorporate these procedures and
+          may fail.
+          For example, changing the graphics settings in some video games
+          will expose this problem.
+          The DRI developers are working with game vendors to prevent this
+          problem in the future.
+
+
       <sect1>Bug Database
 <p>
           The DRI bug database which includes bugs related to specific