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