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