Blame - docs/xlibdriver.html - fp2-dev/platform/external/mesa3d

blob: d95f4d579c62bded4f291e6e2077397a1f1b8df9 [file] [log] [blame]

Brian Paul	12ad488	2006-04-19 03:25:06 +0000	[diff] [blame]	1	<HTML>
				2
				3	<TITLE>Xlib Software Driver</TITLE>
				4
				5	<link rel="stylesheet" type="text/css" href="mesa.css"></head>
				6
				7	<BODY>
				8
				9	<H1>Xlib Software Driver</H1>
				10
				11	<p>
				12	Mesa's Xlib driver provides an emulation of the GLX interface so that
				13	OpenGL programs which use the GLX API can render to any X display, even
				14	those that don't support the GLX extension.
				15	Effectively, the Xlib driver converts all OpenGL rendering into Xlib calls.
				16	</p>
				17
				18	<p>
				19	The Xlib driver is the oldest Mesa driver and the most mature of Mesa's
				20	software-only drivers.
				21	</p>
				22
				23	<p>
				24	Since the Xlib driver <em>emulates</em> the GLX extension, it's not
Brian Paul	6e542f1	2006-04-19 16:55:27 +0000	[diff] [blame]	25	totally conformant with a true GLX implementation.
Brian Paul	12ad488	2006-04-19 03:25:06 +0000	[diff] [blame]	26	The differences are fairly obscure, however.
				27	</p>
				28
				29	<p>
				30	The unique features of the Xlib driver follows.
				31	</p>
				32
				33
Brian Paul	6e542f1	2006-04-19 16:55:27 +0000	[diff] [blame]	34	<H2>X Visual Selection</H2>
Brian Paul	12ad488	2006-04-19 03:25:06 +0000	[diff] [blame]	35	<p>
				36	Mesa supports RGB(A) rendering into almost any X visual type and depth.
				37	</p>
				38	<p>
				39	The glXChooseVisual function tries to choose the best X visual
				40	for the given attribute list. However, if this doesn't suit your needs
				41	you can force Mesa to use any X visual you want (any supported by your
				42	X server that is) by setting the <b>MESA_RGB_VISUAL</b> and
				43	<b>MESA_CI_VISUAL</b>
				44	environment variables.
				45	When an RGB visual is requested, glXChooseVisual
				46	will first look if the MESA_RGB_VISUAL variable is defined.
				47	If so, it will try to use the specified visual.
				48	Similarly, when a color index visual is requested, glXChooseVisual will
				49	look for the MESA_CI_VISUAL variable.
				50	</p>
				51
				52	<p>
				53	The format of accepted values is: <code>visual-class depth</code>
				54	</p>
				55	<p>
				56	Here are some examples:
				57	</p>
				58	<pre>
				59	using csh:
				60	% setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor
				61	% setenv MESA_CI_VISUAL "PseudoColor 12" // 12-bit PseudoColor
				62	% setenv MESA_RGB_VISUAL "PseudoColor 8" // 8-bit PseudoColor
				63
				64	using bash:
				65	$ export MESA_RGB_VISUAL="TrueColor 8"
				66	$ export MESA_CI_VISUAL="PseudoColor 12"
				67	$ export MESA_RGB_VISUAL="PseudoColor 8"
				68	</pre>
				69
				70
Brian Paul	6e542f1	2006-04-19 16:55:27 +0000	[diff] [blame]	71	<H2>Double Buffering</H2>
Brian Paul	12ad488	2006-04-19 03:25:06 +0000	[diff] [blame]	72	<p>
Brian Paul	808809b	2006-06-07 14:01:31 +0000	[diff] [blame^]	73	Mesa can use either an X Pixmap or XImage as the back color buffer when in
				74	double-buffer mode.
				75	The default is to use an XImage.
				76	The <b>MESA_BACK_BUFFER</b> environment variable can override this.
				77	The valid values for <b>MESA_BACK_BUFFER</b> are: <b>Pixmap</b> and
				78	<b>XImage</b> (only the first letter is checked, case doesn't matter).
Brian Paul	12ad488	2006-04-19 03:25:06 +0000	[diff] [blame]	79	</p>
				80
				81	<p>
Brian Paul	808809b	2006-06-07 14:01:31 +0000	[diff] [blame^]	82	Using XImage is almost always faster than a Pixmap since it resides in
				83	the application's address space.
				84	When glXSwapBuffers() is called, XPutImage() or XShmPutImage() is used
				85	to transfer the XImage to the on-screen window.
				86	</p>
				87	<p>
				88	A Pixmap may be faster when doing remote rendering of a simple scene.
				89	Some OpenGL features will be very slow with a Pixmap (for example, blending
				90	will require a round-trip message for pixel readback.)
				91	</p>
				92	<p>
Brian Paul	12ad488	2006-04-19 03:25:06 +0000	[diff] [blame]	93	Experiment with the MESA_BACK_BUFFER variable to see which is faster
				94	for your application.
				95	</p>
				96
				97
				98	<H2>Colormaps</H2>
				99	<p>
				100	When using Mesa directly or with GLX, it's up to the application
				101	writer to create a window with an appropriate colormap. The GLUT
				102	toolkit tris to minimize colormap <em>flashing</em> by sharing
				103	colormaps when possible. Specifically, if the visual and depth of the
				104	window matches that of the root window, the root window's colormap
				105	will be shared by the Mesa window. Otherwise, a new, private colormap
				106	will be allocated.
				107	</p>
				108
				109	<p>
				110	When sharing the root colormap, Mesa may be unable to allocate the colors
				111	it needs, resulting in poor color quality. This can happen when a
				112	large number of colorcells in the root colormap are already allocated.
				113	To prevent colormap sharing in GLUT, set the
				114	<b>MESA_PRIVATE_CMAP</b> environment variable. The value isn't
				115	significant.
				116	</p>
				117
				118
Brian Paul	6e542f1	2006-04-19 16:55:27 +0000	[diff] [blame]	119	<H2>Gamma Correction</H2>
Brian Paul	12ad488	2006-04-19 03:25:06 +0000	[diff] [blame]	120	<p>
				121	To compensate for the nonlinear relationship between pixel values
				122	and displayed intensities, there is a gamma correction feature in
				123	Mesa. Some systems, such as Silicon Graphics, support gamma
				124	correction in hardware (man gamma) so you won't need to use Mesa's
				125	gamma facility. Other systems, however, may need gamma adjustment
				126	to produce images which look correct. If you believe that
				127	Mesa's images are too dim, read on.
				128	</p>
				129
				130	<p>
				131	Gamma correction is controlled with the <b>MESA_GAMMA</b> environment
				132	variable. Its value is of the form <b>Gr Gg Gb</b> or just <b>G</b> where
				133	Gr is the red gamma value, Gg is the green gamma value, Gb is the
				134	blue gamma value and G is one gamma value to use for all three
				135	channels. Each value is a positive real number typically in the
				136	range 1.0 to 2.5.
				137	The defaults are all 1.0, effectively disabling gamma correction.
				138	Examples:
				139	</p>
				140	<pre>
				141	% export MESA_GAMMA="2.3 2.2 2.4" // separate R,G,B values
				142	% export MESA_GAMMA="2.0" // same gamma for R,G,B
				143	</pre>
				144	<p>
				145	The progs/demos/gamma.c program may help you to determine reasonable gamma
				146	value for your display. With correct gamma values, the color intensities
				147	displayed in the top row (drawn by dithering) should nearly match those
				148	in the bottom row (drawn as grays).
				149	</p>
				150
				151	<p>
				152	Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well
				153	on HP displays using the HP-ColorRecovery technology.
				154	</p>
				155
				156	<p>
				157	Mesa implements gamma correction with a lookup table which translates
				158	a "linear" pixel value to a gamma-corrected pixel value. There is a
				159	small performance penalty. Gamma correction only works in RGB mode.
				160	Also be aware that pixel values read back from the frame buffer will
				161	not be "un-corrected" so glReadPixels may not return the same data
				162	drawn with glDrawPixels.
				163	</p>
				164
				165	<p>
				166	For more information about gamma correction see:
				167	<a href="http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html"
				168	the Gamma FAQ</a>
				169	</p>
				170
				171
				172	<H2>Overlay Planes</H2>
				173	<p>
				174	Hardware overlay planes are supported by the Xlib driver. To
				175	determine if your X server has overlay support you can test for the
				176	SERVER_OVERLAY_VISUALS property:
				177	</p>
				178	<pre>
				179	xprop -root \| grep SERVER_OVERLAY_VISUALS
				180	</pre>
				181
				182
Brian Paul	6e542f1	2006-04-19 16:55:27 +0000	[diff] [blame]	183	<H2>HPCR Dithering</H2>
Brian Paul	12ad488	2006-04-19 03:25:06 +0000	[diff] [blame]	184	<p>
				185	If you set the <b>MESA_HPCR_CLEAR</b> environment variable then dithering
				186	will be used when clearing the color buffer. This is only applicable
				187	to HP systems with the HPCR (Color Recovery) feature.
Brian Paul	6e542f1	2006-04-19 16:55:27 +0000	[diff] [blame]	188	This incurs a small performance penalty.
Brian Paul	12ad488	2006-04-19 03:25:06 +0000	[diff] [blame]	189	</p>
				190
				191
				192	<H2>Extensions</H2>
				193	<p>
				194	The following MESA-specific extensions are implemented in the Xlib driver.
				195	</p>
				196
				197	<h3>GLX_MESA_pixmap_colormap</h3>
				198
				199	<p>
				200	This extension adds the GLX function:
				201	</p>
				202	<pre>
				203	GLXPixmap glXCreateGLXPixmapMESA( Display dpy, XVisualInfo visual,
				204	Pixmap pixmap, Colormap cmap )
				205	</pre>
				206	<p>
				207	It is an alternative to the standard glXCreateGLXPixmap() function.
				208	Since Mesa supports RGB rendering into any X visual, not just True-
				209	Color or DirectColor, Mesa needs colormap information to convert RGB
				210	values into pixel values. An X window carries this information but a
				211	pixmap does not. This function associates a colormap to a GLX pixmap.
				212	See the xdemos/glxpixmap.c file for an example of how to use this
				213	extension.
				214	</p>
				215	<p>
				216	<a href="MESA_pixmap_colormap.spec">GLX_MESA_pixmap_colormap specification</a>
				217	</p>
				218
				219
				220	<h3>GLX_MESA_release_buffers</h3>
				221	<p>
				222	Mesa associates a set of ancillary (depth, accumulation, stencil and
				223	alpha) buffers with each X window it draws into. These ancillary
				224	buffers are allocated for each X window the first time the X window
				225	is passed to glXMakeCurrent(). Mesa, however, can't detect when an
				226	X window has been destroyed in order to free the ancillary buffers.
				227	</p>
				228	<p>
				229	The best it can do is to check for recently destroyed windows whenever
				230	the client calls the glXCreateContext() or glXDestroyContext()
				231	functions. This may not be sufficient in all situations though.
				232	</p>
				233	<p>
				234	The GLX_MESA_release_buffers extension allows a client to explicitly
				235	deallocate the ancillary buffers by calling glxReleaseBuffersMESA()
				236	just before an X window is destroyed. For example:
				237	</p>
				238	<pre>
				239	#ifdef GLX_MESA_release_buffers
				240	glXReleaseBuffersMESA( dpy, window );
				241	#endif
				242	XDestroyWindow( dpy, window );
				243	</pre>
				244	<p>
				245	<a href="MESA_release_buffers.spec">GLX_MESA_release_buffers specification</a>
				246	</p>
				247	<p>
				248	This extension was added in Mesa 2.0.
				249	</p>
				250
				251	<H3>GLX_MESA_copy_sub_buffer</H3>
				252	<p>
				253	This extension adds the glXCopySubBufferMESA() function. It works
				254	like glXSwapBuffers() but only copies a sub-region of the window
				255	instead of the whole window.
				256	</p>
				257	<p>
				258	<a href="MESA_copy_sub_buffer.spec">GLX_MESA_copy_sub_buffer specification</a>
				259	</p>
				260	<p>
				261	This extension was added in Mesa 2.6
				262	</p>
				263
				264	<h2>Summary of X-related environment variables</H2>
				265	<pre>
				266	MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
				267	MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
				268	MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
				269	MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
				270	MESA_GAMMA - gamma correction coefficients (X only)
				271	</pre>
				272
				273
				274	</body>
				275	</html>