docs/xlibdriver.html - platform/external/mesa3d - Gitiles

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html lang="en">
 <head>
   <meta http-equiv="content-type" content="text/html; charset=utf-8">
   <title>Xlib Software Driver</title>
   <link rel="stylesheet" type="text/css" href="mesa.css">
 </head>
 <body>

 <div class="header">
   <h1>The Mesa 3D Graphics Library</h1>
 </div>

 <iframe src="contents.html"></iframe>
 <div class="content">

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

 <p>
 The unique features of the Xlib driver follows.
 </p>


 <h2>X Visual Selection</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 back color buffer when in
 double-buffer mode.
 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>
 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.
 </p>
 <p>
 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.)
 </p>
 <p>
 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 tries 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 <code>demos/gamma.c</code> 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).
 </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 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.
 This incurs a small performance penalty.
 </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="specs/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="specs/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="specs/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>

 </div>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html lang="en">
	<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8">
	<title>Xlib Software Driver</title>
	<link rel="stylesheet" type="text/css" href="mesa.css">
	</head>
	<body>

	<div class="header">
	<h1>The Mesa 3D Graphics Library</h1>
	</div>

	<iframe src="contents.html"></iframe>
	<div class="content">

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

	<p>
	The unique features of the Xlib driver follows.
	</p>


	<h2>X Visual Selection</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 back color buffer when in
	double-buffer mode.
	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>
	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.
	</p>
	<p>
	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.)
	</p>
	<p>
	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 tries 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 <code>demos/gamma.c</code> 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).
	</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 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.
	This incurs a small performance penalty.
	</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="specs/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="specs/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="specs/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>

	</div>
	</body>
	</html>