Xlib Software Driver

From 12ad488e598499cf17a619b221e8e4afea363d02 Mon Sep 17 00:00:00 2001 From: Brian Paul Date: Wed, 19 Apr 2006 03:25:06 +0000 Subject: [PATCH] Replace old README.X11 with updated xlibdriver.html --- docs/README.X11 | 314 ------------------------------------------- docs/systems.html | 2 +- docs/xlibdriver.html | 265 ++++++++++++++++++++++++++++++++++++ 3 files changed, 266 insertions(+), 315 deletions(-) delete mode 100644 docs/README.X11 create mode 100644 docs/xlibdriver.html diff --git a/docs/README.X11 b/docs/README.X11 deleted file mode 100644 index 4cbd1261817..00000000000 --- 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 '. 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: - 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 48ac0176443..340f528af13 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.

Xlib driver for the X Window System (README.X11) +
Xlib driver for the X Window System
DRI hardware drivers for the X window system
Microsoft Windows (README.WIN32) diff --git a/docs/xlibdriver.html b/docs/xlibdriver.html new file mode 100644 index 00000000000..7734542dcb9 --- /dev/null +++ b/docs/xlibdriver.html @@ -0,0 +1,265 @@ + + +Xlib Software Driver + + + + + +
Xlib Software Driver
+ +
+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. +
+ +
+The Xlib driver is the oldest Mesa driver and the most mature of Mesa's +software-only drivers. +
+ +
+Since the Xlib driver emulates the GLX extension, it's not +totally conformance with a true GLX implementation. +The differences are fairly obscure, however. +
+ +
+The unique features of the Xlib driver follows. +
+ + +
X Display Modes
+
+Mesa supports RGB(A) rendering into almost any X visual type and depth. +
+
+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 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 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"
+
```
+ + +
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. +Experiment 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 GLUT +toolkit tris 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 GLUT, set the +MESA_PRIVATE_CMAP environment variable. 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 you believe that +Mesa's images are 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: +
+
```
+	% 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
+
```
+
+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). +
+ +
+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: + +
+ + +
Overlay Planes
+
+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: +
+
```
+	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) feature. +
+ + +
Extensions
+
+The following MESA-specific extensions are implemented in the Xlib driver. +
+ +
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_pixmap_colormap specification +
+ + +
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 );
+
```
+
+GLX_MESA_release_buffers specification +
+
+This extension was added 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. +
+
+GLX_MESA_copy_sub_buffer specification +
+
+This extension was added in Mesa 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)
+
```
+ + + + -- 2.30.2