Replace old README.X11 with updated xlibdriver.html

3 files changed, 266 insertions, 315 deletions

diff --git a/docs/README.X11 b/docs/README.X11
deleted file mode 100644
index 4cbd126181..0000000000
--- a/docs/README.X11
+++ /dev/null
@@ -1,314 +0,0 @@
-
-                          Mesa Unix/X11 Information
-
-
-
-Installation
-============
-
-There are two ways to compile Mesa on Unix/X11 systems:
-
-1. The old way:
-    First type 'make' alone to see the list of system
-    configurations currently supported.  If you see your configuration on the
-    list, type 'make <config>'.  Most popular Unix/X workstations are currently
-    supported.
-
-    If your system configuration is not listed by 'make', you'll have to modify
-    the top-level Makefile and Make-config files.  There are instructions in
-    each file.
-
-    When finished, the Mesa libraries will be in the Mesa-x.y/lib/ directory.
-
-
-2. The new way:
-    Type './configure' and then 'make'.  This uses GNU autoconfig.
-    Run 'make check' to build the demos.
-    See docs/INSTALL for more details.
-    When finished, the Mesa libraries will be in the Mesa-x.y/src/.libs/,
-    Mesa-x.y/si-glu/.libs, etc directories.
-
-
-Notes on assembly language optimizations:
-
-   When using the old-style Makefiles, you can specify a configuration
-   that uses X86 assembly language optimizations (linux-3dnow for example).
-
-   The detection of MMX, 3DNow!, PIII/SSE, etc capability is done at
-   runtime.  That means you can compile Mesa for 3DNow! optimizations
-   even if you don't have an AMD CPU.
-
-   However, your Linux binutils and assembler must understand the
-   special instructions in order to compile them.  If you have
-   compilation problems, try upgrading your binutils.
-
-
-Header and library files:
-   After you've compiled Mesa and tried the demos I recommend the following
-   procedure for "installing" Mesa.
-
-   Copy the Mesa include/GL directory to /usr/local/include:
-	cp -r include/GL /usr/local/include
-
-   Copy the Mesa library files to /usr/local/lib:
-	cp lib/* /usr/local/lib
-
-	(actually, use "cp -d" on Linux to preserve symbolic links)
-
-
-Xt/Motif widgets:
-   If you want to use Mesa or OpenGL in your Xt/Motif program you can build
-   the widgets found in either the widgets-mesa or widgets-sgi directories.
-   The former were written for Mesa and the later are the original SGI
-   widgets.  Look in those directories for more information.
-
-
-Notes:
-   HP users:  a Mesa user reports that the HP-UX 10.01 C compiler has
-   a bug which effects glReadPixels.  A patch for the compiler (PHSS_5743) is
-   available.  Otherwise be sure your compiler is version 10.13 or later.
-
-   QNX users:  if you have problems running the demos try setting the
-   stack size to 200K or larger with -N200K, for example.
-
-   SunOS 5.x users:  The X shared memory extension may not work
-   correctly.  If Mesa prints an error message to the effect of "Shared memory
-   error" then you'll have to append the following three lines to the end of
-   your /etc/system file then reboot:
-      set shmsys:shminfo_shmmax = 0x2000000
-      set shmsys:shminfo_shmmni = 0x1000
-      set shmsys:shminfo_shmseg = 0x100
-
-
-
-Using the library
-=================
-
-Configuration options:
-   The file src/mesa/main/config.h has many parameters which you can adjust
-   such as maximum number of lights, clipping planes, maximum texture size,
-   etc.  In particular, you may want to change DEPTH_BITS from 16 to 32
-   if a 16-bit depth buffer isn't precise enough for your application.
-
-
-Shared libraries:
-   If you compile shared libraries you may have to set an environment
-   variable to specify where the Mesa libraries are located.  On Linux and
-   Sun systems for example, set the LD_LIBRARY_PATH variable to include
-   /your-dir/Mesa-2.6/lib.   Otherwise, when you try to run a demo it
-   may fail with a message saying that one or more libraries couldn't be
-   found.
-
-
-Remote display of OpenGL/GLX programs:
-   As of version 1.2.3, Mesa's header files use the same GLenum and GLUenum
-   values as SGI's (and most/all other vendor's) OpenGL headers.  This means
-   you can freely mix object files compiled with OpenGL or Mesa headers.
-   In fact, on systems with dynamic runtime linkers it's possible to dynam-
-   ically link with Mesa or OpenGL shared libraries at runtime, without
-   recompiling or relinking anything!
-
-   Using IRIX 5.x as an example, you can run SGI's OpenGL demos with the
-   Mesa shared libraries as follows.  Let's assume you're installing Mesa
-   in /usr/local/Mesa and using the C-shell:
-       % cd /usr/local/Mesa
-       % make irix5-dso
-       % setenv _RLD_LIST "/usr/local/Mesa/lib/libGL.so:DEFAULT"
-       % /usr/demos/bin/ideas_ogl      // this is a test
-
-   You can now run OpenGL executables on almost any X display!  There may
-   be some problems from the fact that Mesa supports many X visual types
-   that an OpenGL client may not expect (grayscale for example).  In this
-   case the application may abort, print error messages, or just behave
-   strangely.  You may have to experiment with the MESA_RGB_VISUAL envi-
-   ronment variable.
-
-
-Xt/Motif Widgets:
-   Two versions of the Xt/Motif OpenGL drawing area widgets are included:
-
-      widgets-sgi/	SGI's stock widgets
-      widgets-mesa/	Mesa-tuned widgets
-
-   Look in those directories for details
-
-
-Togl:
-   Togl is an OpenGL/Mesa widget for Tcl/Tk.
-   See http://togl.sourceforge.net for more information.
-
-
-
-X Display Modes:
-   Mesa supports RGB(A) rendering into almost any X visual type and depth.
-
-   The glXChooseVisual function tries its best to pick an appropriate visual
-   for the given attribute list.  However, if this doesn't suit your needs
-   you can force Mesa to use any X visual you want (any supported by your
-   X server that is) by setting the MESA_RGB_VISUAL and MESA_CI_VISUAL
-   environment variables.  When an RGB visual is requested, glXChooseVisual
-   will first look if the MESA_RGB_VISUAL variable is defined.  If so, it
-   will try to use the specified visual.  Similarly, when a color index
-   visual is requested, glXChooseVisual will look for the MESA_CI_VISUAL
-   variable.
-
-   The format of accepted values is:  <visual-class> <depth>
-   Here are some examples:
-
-   using the C-shell:
-	% setenv MESA_RGB_VISUAL "TrueColor 8"		// 8-bit TrueColor
-	% setenv MESA_CI_VISUAL "PseudoColor 12"	// 12-bit PseudoColor
-	% setenv MESA_RGB_VISUAL "PseudoColor 8"	// 8-bit PseudoColor
-
-   using the KornShell:
-	$ export MESA_RGB_VISUAL="TrueColor 8"
-	$ export MESA_CI_VISUAL="PseudoColor 12"
-	$ export MESA_RGB_VISUAL="PseudoColor 8"
-
-
-Double buffering:
-   Mesa can use either an X Pixmap or XImage as the backbuffer when in
-   double buffer mode.  Using GLX, the default is to use an XImage.  The
-   MESA_BACK_BUFFER environment variable can override this.  The valid
-   values for MESA_BACK_BUFFER are:  Pixmap and XImage (only the first
-   letter is checked, case doesn't matter).
-
-   A pixmap is faster when drawing simple lines and polygons while an
-   XImage is faster when Mesa has to do pixel-by-pixel rendering.  If you
-   need depth buffering the XImage will almost surely be faster.  Exper-
-   iment with the MESA_BACK_BUFFER variable to see which is faster for
-   your application.  
-
-
-Colormaps:
-   When using Mesa directly or with GLX, it's up to the application writer
-   to create a window with an appropriate colormap.  The aux, tk, and GLUT
-   toolkits try to minimize colormap "flashing" by sharing colormaps when
-   possible.  Specifically, if the visual and depth of the window matches
-   that of the root window, the root window's colormap will be shared by
-   the Mesa window.  Otherwise, a new, private colormap will be allocated.
-
-   When sharing the root colormap, Mesa may be unable to allocate the colors
-   it needs, resulting in poor color quality.  This can happen when a
-   large number of colorcells in the root colormap are already allocated.
-   To prevent colormap sharing in aux, tk and GLUT, define the environment
-   variable MESA_PRIVATE_CMAP.  The value isn't significant.
-
-
-Gamma correction:
-   To compensate for the nonlinear relationship between pixel values
-   and displayed intensities, there is a gamma correction feature in
-   Mesa.  Some systems, such as Silicon Graphics, support gamma
-   correction in hardware (man gamma) so you won't need to use Mesa's
-   gamma facility.  Other systems, however, may need gamma adjustment
-   to produce images which look correct.  If in the past you thought
-   Mesa's images were too dim, read on.
-
-   Gamma correction is controlled with the MESA_GAMMA environment
-   variable.  Its value is of the form "Gr Gg Gb" or just "G" where
-   Gr is the red gamma value, Gg is the green gamma value, Gb is the
-   blue gamma value and G is one gamma value to use for all three
-   channels.  Each value is a positive real number typically in the
-   range 1.0 to 2.5.  The defaults are all 1.0, effectively disabling
-   gamma correction.  Examples using csh:
-
-	% setenv MESA_GAMMA "2.3 2.2 2.4"	// separate R,G,B values
-	% setenv MESA_GAMMA "2.0"		// same gamma for R,G,B
-
-   The demos/gamma.c program may help you to determine reasonable gamma
-   value for your display.  With correct gamma values, the color intensities
-   displayed in the top row (drawn by dithering) should nearly match those
-   in the bottom row (drawn as grays).
-
-   Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well
-   on HP displays using the HP-ColorRecovery technology.
-
-   Mesa implements gamma correction with a lookup table which translates
-   a "linear" pixel value to a gamma-corrected pixel value.  There is a
-   small performance penalty.  Gamma correction only works in RGB mode.
-   Also be aware that pixel values read back from the frame buffer will
-   not be "un-corrected" so glReadPixels may not return the same data
-   drawn with glDrawPixels.
-
-   For more information about gamma correction see:
-   http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html
-
-
-Overlay Planes
-
-   Overlay planes in the frame buffer are supported by Mesa but require
-   hardware and X server support.  To determine if your X server has
-   overlay support you can test for the SERVER_OVERLAY_VISUALS property:
-
-	xprop -root | grep SERVER_OVERLAY_VISUALS
-
-
-HPCR glClear(GL_COLOR_BUFFER_BIT) dithering
-
-   If you set the MESA_HPCR_CLEAR environment variable then dithering
-   will be used when clearing the color buffer.  This is only applicable
-   to HP systems with the HPCR (Color Recovery) system.
-
-
-Extensions
-==========
-   There are three Mesa-specific GLX extensions at this time.
-
-   GLX_MESA_pixmap_colormap 
-
-      This extension adds the GLX function:
-
-         GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
-                                           Pixmap pixmap, Colormap cmap )
-
-      It is an alternative to the standard glXCreateGLXPixmap() function.
-      Since Mesa supports RGB rendering into any X visual, not just True-
-      Color or DirectColor, Mesa needs colormap information to convert RGB
-      values into pixel values.  An X window carries this information but a
-      pixmap does not.  This function associates a colormap to a GLX pixmap.
-      See the xdemos/glxpixmap.c file for an example of how to use this
-      extension.
-
-   GLX_MESA_release_buffers
-
-      Mesa associates a set of ancillary (depth, accumulation, stencil and
-      alpha) buffers with each X window it draws into.  These ancillary
-      buffers are allocated for each X window the first time the X window
-      is passed to glXMakeCurrent().  Mesa, however, can't detect when an
-      X window has been destroyed in order to free the ancillary buffers.
-
-      The best it can do is to check for recently destroyed windows whenever
-      the client calls the glXCreateContext() or glXDestroyContext()
-      functions.  This may not be sufficient in all situations though.
-
-      The GLX_MESA_release_buffers extension allows a client to explicitly
-      deallocate the ancillary buffers by calling glxReleaseBuffersMESA()
-      just before an X window is destroyed.  For example:
-
-         #ifdef GLX_MESA_release_buffers
-            glXReleaseBuffersMESA( dpy, window );
-         #endif
-         XDestroyWindow( dpy, window );
-
-      This extension is new in Mesa 2.0.
-
-   GLX_MESA_copy_sub_buffer
-
-      This extension adds the glXCopySubBufferMESA() function.  It works
-      like glXSwapBuffers() but only copies a sub-region of the window
-      instead of the whole window.
-
-      This extension is new in Mesa version 2.6
-
-
-
-Summary of X-related environment variables:
-   MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
-   MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
-   MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
-   MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
-   MESA_GAMMA - gamma correction coefficients (X only)
-
-
-----------------------------------------------------------------------
-$Id: README.X11,v 3.11 2003/12/17 15:14:31 brianp Exp $
diff --git a/docs/systems.html b/docs/systems.html
index 48ac017644..340f528af1 100644
--- a/docs/systems.html
+++ b/docs/systems.html
@@ -32,7 +32,7 @@ Be warned that some drivers may be out of date and no longer function.
 </p>
 
 <UL>
-<LI>Xlib driver for the X Window System <A HREF="README.X11">(README.X11)</A>
+<LI><a href="xlibdriver.html">Xlib driver</a> for the X Window System
 <li><a href="http://dri.freedesktop.org/" target="_parent">
 DRI hardware drivers</a> for the X window system
 <LI>Microsoft Windows <A HREF="README.WIN32">(README.WIN32)</A>
diff --git a/docs/xlibdriver.html b/docs/xlibdriver.html
new file mode 100644
index 0000000000..7734542dcb
--- /dev/null
+++ b/docs/xlibdriver.html
@@ -0,0 +1,265 @@
+<HTML>
+
+<TITLE>Xlib Software Driver</TITLE>
+
+<link rel="stylesheet" type="text/css" href="mesa.css"></head>
+
+<BODY>
+
+<H1>Xlib Software Driver</H1>
+
+<p>
+Mesa's Xlib driver provides an emulation of the GLX interface so that
+OpenGL programs which use the GLX API can render to any X display, even
+those that don't support the GLX extension.
+Effectively, the Xlib driver converts all OpenGL rendering into Xlib calls.
+</p>
+
+<p>
+The Xlib driver is the oldest Mesa driver and the most mature of Mesa's
+software-only drivers.
+</p>
+
+<p>
+Since the Xlib driver <em>emulates</em> the GLX extension, it's not
+totally conformance with a true GLX implementation.
+The differences are fairly obscure, however.
+</p>
+
+<p>
+The unique features of the Xlib driver follows.
+</p>
+
+
+<H2>X Display Modes</H2>
+<p>
+Mesa supports RGB(A) rendering into almost any X visual type and depth.
+</p>
+<p>
+The glXChooseVisual function tries to choose the best X visual
+for the given attribute list.  However, if this doesn't suit your needs
+you can force Mesa to use any X visual you want (any supported by your
+X server that is) by setting the <b>MESA_RGB_VISUAL</b> and
+<b>MESA_CI_VISUAL</b>
+environment variables.
+When an RGB visual is requested, glXChooseVisual
+will first look if the MESA_RGB_VISUAL variable is defined.
+If so, it will try to use the specified visual.
+Similarly, when a color index visual is requested, glXChooseVisual will
+look for the MESA_CI_VISUAL variable.
+</p>
+
+<p>
+The format of accepted values is:  <code>visual-class depth</code>
+</p>
+<p>
+Here are some examples:
+</p>
+<pre>
+   using csh:
+	% setenv MESA_RGB_VISUAL "TrueColor 8"		// 8-bit TrueColor
+	% setenv MESA_CI_VISUAL "PseudoColor 12"	// 12-bit PseudoColor
+	% setenv MESA_RGB_VISUAL "PseudoColor 8"	// 8-bit PseudoColor
+
+   using bash:
+	$ export MESA_RGB_VISUAL="TrueColor 8"
+	$ export MESA_CI_VISUAL="PseudoColor 12"
+	$ export MESA_RGB_VISUAL="PseudoColor 8"
+</pre>
+
+
+<H2>Double buffering</H2>
+<p>
+Mesa can use either an X Pixmap or XImage as the backbuffer when in
+double buffer mode.  Using GLX, the default is to use an XImage.  The
+<b>MESA_BACK_BUFFER</b> environment variable can override this.  The valid
+values for <b>MESA_BACK_BUFFER</b> are:  <b>Pixmap</b> and <b>XImage</b>
+(only the first letter is checked, case doesn't matter).
+</p>
+
+<p>
+A pixmap is faster when drawing simple lines and polygons while an
+XImage is faster when Mesa has to do pixel-by-pixel rendering.  If you
+need depth buffering the XImage will almost surely be faster.
+Experiment with the MESA_BACK_BUFFER variable to see which is faster
+for your application.
+</p>
+
+
+<H2>Colormaps</H2>
+<p>
+When using Mesa directly or with GLX, it's up to the application
+writer to create a window with an appropriate colormap.  The GLUT
+toolkit tris to minimize colormap <em>flashing</em> by sharing
+colormaps when possible.  Specifically, if the visual and depth of the
+window matches that of the root window, the root window's colormap
+will be shared by the Mesa window.  Otherwise, a new, private colormap
+will be allocated.
+</p>
+
+<p>
+When sharing the root colormap, Mesa may be unable to allocate the colors
+it needs, resulting in poor color quality.  This can happen when a
+large number of colorcells in the root colormap are already allocated.
+To prevent colormap sharing in GLUT, set the 
+<b>MESA_PRIVATE_CMAP</b> environment variable.  The value isn't
+significant.
+</p>
+
+
+<H2>Gamma correction</H2>
+<p>
+To compensate for the nonlinear relationship between pixel values
+and displayed intensities, there is a gamma correction feature in
+Mesa.  Some systems, such as Silicon Graphics, support gamma
+correction in hardware (man gamma) so you won't need to use Mesa's
+gamma facility.  Other systems, however, may need gamma adjustment
+to produce images which look correct.  If you believe that 
+Mesa's images are too dim, read on.
+</p>
+
+<p>
+Gamma correction is controlled with the <b>MESA_GAMMA</b> environment
+variable.  Its value is of the form <b>Gr Gg Gb</b> or just <b>G</b> where
+Gr is the red gamma value, Gg is the green gamma value, Gb is the
+blue gamma value and G is one gamma value to use for all three
+channels.  Each value is a positive real number typically in the
+range 1.0 to 2.5.
+The defaults are all 1.0, effectively disabling gamma correction.
+Examples:
+</p>
+<pre>
+	% export MESA_GAMMA="2.3 2.2 2.4"	// separate R,G,B values
+	% export MESA_GAMMA="2.0"		// same gamma for R,G,B
+</pre>
+<p>
+The progs/demos/gamma.c program may help you to determine reasonable gamma
+value for your display.  With correct gamma values, the color intensities
+displayed in the top row (drawn by dithering) should nearly match those
+in the bottom row (drawn as grays).
+</p>
+
+<p>
+Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well
+on HP displays using the HP-ColorRecovery technology.
+</p>
+
+<p>
+Mesa implements gamma correction with a lookup table which translates
+a "linear" pixel value to a gamma-corrected pixel value.  There is a
+small performance penalty.  Gamma correction only works in RGB mode.
+Also be aware that pixel values read back from the frame buffer will
+not be "un-corrected" so glReadPixels may not return the same data
+drawn with glDrawPixels.
+</p>
+
+<p>
+For more information about gamma correction see:
+<a href="http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html"
+the Gamma FAQ</a>
+</p>
+
+
+<H2>Overlay Planes</H2>
+<p>
+Hardware overlay planes are supported by the Xlib driver.  To
+determine if your X server has overlay support you can test for the
+SERVER_OVERLAY_VISUALS property:
+</p>
+<pre>
+	xprop -root | grep SERVER_OVERLAY_VISUALS
+</pre>
+
+
+<H2>HPCR glClear(GL_COLOR_BUFFER_BIT) dithering</H2>
+<p>
+If you set the <b>MESA_HPCR_CLEAR</b> environment variable then dithering
+will be used when clearing the color buffer.  This is only applicable
+to HP systems with the HPCR (Color Recovery) feature.
+</p>
+
+
+<H2>Extensions</H2>
+<p>
+The following MESA-specific extensions are implemented in the Xlib driver.
+</p>
+
+<h3>GLX_MESA_pixmap_colormap</h3>
+
+<p>
+This extension adds the GLX function:
+</p>
+<pre>
+    GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
+                                      Pixmap pixmap, Colormap cmap )
+</pre>
+<p>
+It is an alternative to the standard glXCreateGLXPixmap() function.
+Since Mesa supports RGB rendering into any X visual, not just True-
+Color or DirectColor, Mesa needs colormap information to convert RGB
+values into pixel values.  An X window carries this information but a
+pixmap does not.  This function associates a colormap to a GLX pixmap.
+See the xdemos/glxpixmap.c file for an example of how to use this
+extension.
+</p>
+<p>
+<a href="MESA_pixmap_colormap.spec">GLX_MESA_pixmap_colormap specification</a>
+</p>
+
+
+<h3>GLX_MESA_release_buffers</h3>
+<p>
+Mesa associates a set of ancillary (depth, accumulation, stencil and
+alpha) buffers with each X window it draws into.  These ancillary
+buffers are allocated for each X window the first time the X window
+is passed to glXMakeCurrent().  Mesa, however, can't detect when an
+X window has been destroyed in order to free the ancillary buffers.
+</p>
+<p>
+The best it can do is to check for recently destroyed windows whenever
+the client calls the glXCreateContext() or glXDestroyContext()
+functions.  This may not be sufficient in all situations though.
+</p>
+<p>
+The GLX_MESA_release_buffers extension allows a client to explicitly
+deallocate the ancillary buffers by calling glxReleaseBuffersMESA()
+just before an X window is destroyed.  For example:
+</p>
+<pre>
+         #ifdef GLX_MESA_release_buffers
+            glXReleaseBuffersMESA( dpy, window );
+         #endif
+         XDestroyWindow( dpy, window );
+</pre>
+<p>
+<a href="MESA_release_buffers.spec">GLX_MESA_release_buffers specification</a>
+</p>
+<p>
+This extension was added in Mesa 2.0.
+</p>
+
+<H3>GLX_MESA_copy_sub_buffer</H3>
+<p>
+This extension adds the glXCopySubBufferMESA() function.  It works
+like glXSwapBuffers() but only copies a sub-region of the window
+instead of the whole window.
+</p>
+<p>
+<a href="MESA_copy_sub_buffer.spec">GLX_MESA_copy_sub_buffer specification</a>
+</p>
+<p>
+This extension was added in Mesa 2.6
+</p>
+
+<h2>Summary of X-related environment variables</H2>
+<pre>
+   MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
+   MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
+   MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
+   MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
+   MESA_GAMMA - gamma correction coefficients (X only)
+</pre>
+
+
+</body>
+</html>