2 Mesa 3.3 Unix/X11 Information
9 There are two ways to compile Mesa on Unix/X11 systems:
12 First type 'make' alone to see the list of system
13 configurations currently supported. If you see your configuration on the
14 list, type 'make <config>'. Most popular Unix/X workstations are currently
17 If your system configuration is not listed by 'make', you'll have to modify
18 the top-level Makefile and Make-config files. There are instructions in
23 Type './configure' and then 'make'. This uses GNU autoconfig.
24 See docs/INSTALL for more details.
27 The top-level makefile will execute the makefiles in a number of sub-
28 directories. When finished, the Mesa libraries will be in the Mesa-3.3/lib/
29 directory. A few GLUT demos in the demos/ directory should be ready to run.
31 If you also downloaded and unpacked the demos there should be executables
32 in the "xdemos/", "samples/", and "book/" directories for you to try out.
34 If you have compilation problems you should try to fix them and return the
35 patches to the author.
38 Notes on assembly language optimizations:
40 When using the old-style Makefiles, you can specify a configuration
41 that uses X86 assembly language optimizations (linux-3dnow for example).
43 The detection of MMX, 3DNow!, PIII/SSE, etc capability is done at
44 runtime. That means you can compile Mesa for 3DNow! optimizations
45 even if you don't have an AMD CPU.
47 However, your Linux binutils and assembler must understand the
48 special instructions in order to compile them. If you have
49 compilation problems, try upgrading your binutils.
52 Header and library files:
53 After you've compiled Mesa and tried the demos I recommend the following
54 procedure for "installing" Mesa.
56 Copy the Mesa include/GL directory to /usr/local/include:
57 cp -r include/GL /usr/local/include
59 Copy the Mesa library files to /usr/local/lib:
60 cp lib/* /usr/local/lib
62 (actually, use "cp -d" on Linux to preserve symbolic links)
66 If you want to use Mesa or OpenGL in your Xt/Motif program you can build
67 the widgets found in either the widgets-mesa or widgets-sgi directories.
68 The former were written for Mesa and the later are the original SGI
69 widgets. Look in those directories for more information.
73 HP users: a Mesa user reports that the HP-UX 10.01 C compiler has
74 a bug which effects glReadPixels. A patch for the compiler (PHSS_5743) is
75 available. Otherwise be sure your compiler is version 10.13 or later.
77 QNX users: if you have problems running the demos try setting the
78 stack size to 200K or larger with -N200K, for example.
80 SunOS 5.x users: The X shared memory extension may not work
81 correctly. If Mesa prints an error message to the effect of "Shared memory
82 error" then you'll have to append the following three lines to the end of
83 your /etc/system file then reboot:
84 set shmsys:shminfo_shmmax = 0x2000000
85 set shmsys:shminfo_shmmni = 0x1000
86 set shmsys:shminfo_shmseg = 0x100
93 Configuration options:
94 The file src/config.h has many parameters which you can adjust such
95 as maximum number of lights, clipping planes, maximum texture size,
96 etc. In particular, you may want to change DEPTH_BITS from 16 to 32
97 if a 16-bit depth buffer isn't precise enough for your application.
101 If you compile shared libraries you may have to set an environment
102 variable to specify where the Mesa libraries are located. On Linux and
103 Sun systems for example, set the LD_LIBRARY_PATH variable to include
104 /your-dir/Mesa-2.6/lib. Otherwise, when you try to run a demo it
105 may fail with a message saying that one or more libraries couldn't be
109 Remote display of OpenGL/GLX programs:
110 As of version 1.2.3, Mesa's header files use the same GLenum and GLUenum
111 values as SGI's (and most/all other vendor's) OpenGL headers. This means
112 you can freely mix object files compiled with OpenGL or Mesa headers.
113 In fact, on systems with dynamic runtime linkers it's possible to dynam-
114 ically link with Mesa or OpenGL shared libraries at runtime, without
115 recompiling or relinking anything!
117 Using IRIX 5.x as an example, you can run SGI's OpenGL demos with the
118 Mesa shared libraries as follows. Let's assume you're installing Mesa
119 in /usr/local/Mesa and using the C-shell:
122 % setenv _RLD_LIST "/usr/local/Mesa/lib/libGL.so:DEFAULT"
123 % /usr/demos/bin/ideas_ogl // this is a test
125 You can now run OpenGL executables on almost any X display! There may
126 be some problems from the fact that Mesa supports many X visual types
127 that an OpenGL client may not expect (grayscale for example). In this
128 case the application may abort, print error messages, or just behave
129 strangely. You may have to experiment with the MESA_RGB_VISUAL envi-
134 Two versions of the Xt/Motif OpenGL drawing area widgets are included:
136 widgets-sgi/ SGI's stock widgets
137 widgets-mesa/ Mesa-tuned widgets
139 Look in those directories for details
143 Togl is an OpenGL/Mesa widget for Tcl/Tk.
144 See http://togl.sourceforge.net for more information.
149 Mesa supports RGB(A) rendering into almost any X visual type and depth.
151 The glXChooseVisual function tries its best to pick an appropriate visual
152 for the given attribute list. However, if this doesn't suit your needs
153 you can force Mesa to use any X visual you want (any supported by your
154 X server that is) by setting the MESA_RGB_VISUAL and MESA_CI_VISUAL
155 environment variables. When an RGB visual is requested, glXChooseVisual
156 will first look if the MESA_RGB_VISUAL variable is defined. If so, it
157 will try to use the specified visual. Similarly, when a color index
158 visual is requested, glXChooseVisual will look for the MESA_CI_VISUAL
161 The format of accepted values is: <visual-class> <depth>
162 Here are some examples:
165 % setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor
166 % setenv MESA_CI_VISUAL "PseudoColor 12" // 12-bit PseudoColor
167 % setenv MESA_RGB_VISUAL "PseudoColor 8" // 8-bit PseudoColor
170 $ export MESA_RGB_VISUAL="TrueColor 8"
171 $ export MESA_CI_VISUAL="PseudoColor 12"
172 $ export MESA_RGB_VISUAL="PseudoColor 8"
176 Mesa can use either an X Pixmap or XImage as the backbuffer when in
177 double buffer mode. Using GLX, the default is to use an XImage. The
178 MESA_BACK_BUFFER environment variable can override this. The valid
179 values for MESA_BACK_BUFFER are: Pixmap and XImage (only the first
180 letter is checked, case doesn't matter).
182 A pixmap is faster when drawing simple lines and polygons while an
183 XImage is faster when Mesa has to do pixel-by-pixel rendering. If you
184 need depth buffering the XImage will almost surely be faster. Exper-
185 iment with the MESA_BACK_BUFFER variable to see which is faster for
190 When using Mesa directly or with GLX, it's up to the application writer
191 to create a window with an appropriate colormap. The aux, tk, and GLUT
192 toolkits try to minimize colormap "flashing" by sharing colormaps when
193 possible. Specifically, if the visual and depth of the window matches
194 that of the root window, the root window's colormap will be shared by
195 the Mesa window. Otherwise, a new, private colormap will be allocated.
197 When sharing the root colormap, Mesa may be unable to allocate the colors
198 it needs, resulting in poor color quality. This can happen when a
199 large number of colorcells in the root colormap are already allocated.
200 To prevent colormap sharing in aux, tk and GLUT, define the environment
201 variable MESA_PRIVATE_CMAP. The value isn't significant.
205 To compensate for the nonlinear relationship between pixel values
206 and displayed intensities, there is a gamma correction feature in
207 Mesa. Some systems, such as Silicon Graphics, support gamma
208 correction in hardware (man gamma) so you won't need to use Mesa's
209 gamma facility. Other systems, however, may need gamma adjustment
210 to produce images which look correct. If in the past you thought
211 Mesa's images were too dim, read on.
213 Gamma correction is controlled with the MESA_GAMMA environment
214 variable. Its value is of the form "Gr Gg Gb" or just "G" where
215 Gr is the red gamma value, Gg is the green gamma value, Gb is the
216 blue gamma value and G is one gamma value to use for all three
217 channels. Each value is a positive real number typically in the
218 range 1.0 to 2.5. The defaults are all 1.0, effectively disabling
219 gamma correction. Examples using csh:
221 % setenv MESA_GAMMA "2.3 2.2 2.4" // separate R,G,B values
222 % setenv MESA_GAMMA "2.0" // same gamma for R,G,B
224 The demos/gamma.c program may help you to determine reasonable gamma
225 value for your display. With correct gamma values, the color intensities
226 displayed in the top row (drawn by dithering) should nearly match those
227 in the bottom row (drawn as grays).
229 Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well
230 on HP displays using the HP-ColorRecovery technology.
232 Mesa implements gamma correction with a lookup table which translates
233 a "linear" pixel value to a gamma-corrected pixel value. There is a
234 small performance penalty. Gamma correction only works in RGB mode.
235 Also be aware that pixel values read back from the frame buffer will
236 not be "un-corrected" so glReadPixels may not return the same data
237 drawn with glDrawPixels.
239 For more information about gamma correction see:
240 http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html
245 Overlay planes in the frame buffer are supported by Mesa but require
246 hardware and X server support. To determine if your X server has
247 overlay support you can test for the SERVER_OVERLAY_VISUALS property:
249 xprop -root | grep SERVER_OVERLAY_VISUALS
252 HPCR glClear(GL_COLOR_BUFFER_BIT) dithering
254 If you set the MESA_HPCR_CLEAR environment variable then dithering
255 will be used when clearing the color buffer. This is only applicable
256 to HP systems with the HPCR (Color Recovery) system.
260 The following OpenGL GLX extensions are currently implemented:
262 GLX_EXT_visual_info - GLX visual and transparent pixel extension
263 GLX_EXT_visual_rating - GLX visual caveats
265 For detailed information about the extensions see www.opengl.org
267 There are four Mesa-specific GL/GLX extensions at this time.
269 GLX_MESA_pixmap_colormap
271 This extension adds the GLX function:
273 GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
274 Pixmap pixmap, Colormap cmap )
276 It is an alternative to the standard glXCreateGLXPixmap() function.
277 Since Mesa supports RGB rendering into any X visual, not just True-
278 Color or DirectColor, Mesa needs colormap information to convert RGB
279 values into pixel values. An X window carries this information but a
280 pixmap does not. This function associates a colormap to a GLX pixmap.
281 See the xdemos/glxpixmap.c file for an example of how to use this
284 GLX_MESA_release_buffers
286 Mesa associates a set of ancillary (depth, accumulation, stencil and
287 alpha) buffers with each X window it draws into. These ancillary
288 buffers are allocated for each X window the first time the X window
289 is passed to glXMakeCurrent(). Mesa, however, can't detect when an
290 X window has been destroyed in order to free the ancillary buffers.
292 The best it can do is to check for recently destroyed windows whenever
293 the client calls the glXCreateContext() or glXDestroyContext()
294 functions. This may not be sufficient in all situations though.
296 The GLX_MESA_release_buffers extension allows a client to explicitly
297 deallocate the ancillary buffers by calling glxReleaseBuffersMESA()
298 just before an X window is destroyed. For example:
300 #ifdef GLX_MESA_release_buffers
301 glXReleaseBuffersMESA( dpy, window );
303 XDestroyWindow( dpy, window );
305 This extension is new in Mesa 2.0.
307 GLX_MESA_copy_sub_buffer
309 This extension adds the glXCopySubBufferMESA() function. It works
310 like glXSwapBuffers() but only copies a sub-region of the window
311 instead of the whole window.
313 This extension is new in Mesa version 2.6
317 Summary of X-related environment variables:
318 MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
319 MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
320 MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
321 MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
322 MESA_GAMMA - gamma correction coefficients (X only)
325 ----------------------------------------------------------------------
326 $Id: README.X11,v 3.5 2000/04/04 15:14:48 brianp Exp $