X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=docs%2Fxlibdriver.html;fp=docs%2Fxlibdriver.html;h=0000000000000000000000000000000000000000;hb=4d066836e3cf307431a74eafcc8a404ce5ccea69;hp=e1740cd730e38135a8a3b9b2edab71b8e3d9f969;hpb=1df5dbf51659000f74ca9511a211a7b026bfa936;p=mesa.git diff --git a/docs/xlibdriver.html b/docs/xlibdriver.html deleted file mode 100644 index e1740cd730e..00000000000 --- a/docs/xlibdriver.html +++ /dev/null @@ -1,282 +0,0 @@ - - - - - Xlib Software Driver - - - - -
- The Mesa 3D Graphics Library -
- - -
- -

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 conformant with a true GLX implementation. -The differences are fairly obscure, however. -

- -

-The unique features of the Xlib driver follows. -

- - -

X Visual Selection

-

-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 back color buffer when in -double-buffer mode. -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). -

- -

-Using XImage is almost always faster than a Pixmap since it resides in -the application's address space. -When glXSwapBuffers() is called, XPutImage() or XShmPutImage() is used -to transfer the XImage to the on-screen window. -

-

-A Pixmap may be faster when doing remote rendering of a simple scene. -Some OpenGL features will be very slow with a Pixmap (for example, blending -will require a round-trip message for pixel readback.) -

-

-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 tries 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 demos/gamma.c program in mesa/demos repository 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 the -Wikipedia article -

- - -

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 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. -This incurs a small performance penalty. -

- - -

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)
-
- -
- -