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