+++ /dev/null
-
- Mesa Unix/X11 Information
-
-
-
-Installation
-============
-
-There are two ways to compile Mesa on Unix/X11 systems:
-
-1. The old way:
- First type 'make' alone to see the list of system
- configurations currently supported. If you see your configuration on the
- list, type 'make <config>'. Most popular Unix/X workstations are currently
- supported.
-
- If your system configuration is not listed by 'make', you'll have to modify
- the top-level Makefile and Make-config files. There are instructions in
- each file.
-
- When finished, the Mesa libraries will be in the Mesa-x.y/lib/ directory.
-
-
-2. The new way:
- Type './configure' and then 'make'. This uses GNU autoconfig.
- Run 'make check' to build the demos.
- See docs/INSTALL for more details.
- When finished, the Mesa libraries will be in the Mesa-x.y/src/.libs/,
- Mesa-x.y/si-glu/.libs, etc directories.
-
-
-Notes on assembly language optimizations:
-
- When using the old-style Makefiles, you can specify a configuration
- that uses X86 assembly language optimizations (linux-3dnow for example).
-
- The detection of MMX, 3DNow!, PIII/SSE, etc capability is done at
- runtime. That means you can compile Mesa for 3DNow! optimizations
- even if you don't have an AMD CPU.
-
- However, your Linux binutils and assembler must understand the
- special instructions in order to compile them. If you have
- compilation problems, try upgrading your binutils.
-
-
-Header and library files:
- After you've compiled Mesa and tried the demos I recommend the following
- procedure for "installing" Mesa.
-
- Copy the Mesa include/GL directory to /usr/local/include:
- cp -r include/GL /usr/local/include
-
- Copy the Mesa library files to /usr/local/lib:
- cp lib/* /usr/local/lib
-
- (actually, use "cp -d" on Linux to preserve symbolic links)
-
-
-Xt/Motif widgets:
- If you want to use Mesa or OpenGL in your Xt/Motif program you can build
- the widgets found in either the widgets-mesa or widgets-sgi directories.
- The former were written for Mesa and the later are the original SGI
- widgets. Look in those directories for more information.
-
-
-Notes:
- HP users: a Mesa user reports that the HP-UX 10.01 C compiler has
- a bug which effects glReadPixels. A patch for the compiler (PHSS_5743) is
- available. Otherwise be sure your compiler is version 10.13 or later.
-
- QNX users: if you have problems running the demos try setting the
- stack size to 200K or larger with -N200K, for example.
-
- SunOS 5.x users: The X shared memory extension may not work
- correctly. If Mesa prints an error message to the effect of "Shared memory
- error" then you'll have to append the following three lines to the end of
- your /etc/system file then reboot:
- set shmsys:shminfo_shmmax = 0x2000000
- set shmsys:shminfo_shmmni = 0x1000
- set shmsys:shminfo_shmseg = 0x100
-
-
-
-Using the library
-=================
-
-Configuration options:
- The file src/mesa/main/config.h has many parameters which you can adjust
- such as maximum number of lights, clipping planes, maximum texture size,
- etc. In particular, you may want to change DEPTH_BITS from 16 to 32
- if a 16-bit depth buffer isn't precise enough for your application.
-
-
-Shared libraries:
- If you compile shared libraries you may have to set an environment
- variable to specify where the Mesa libraries are located. On Linux and
- Sun systems for example, set the LD_LIBRARY_PATH variable to include
- /your-dir/Mesa-2.6/lib. Otherwise, when you try to run a demo it
- may fail with a message saying that one or more libraries couldn't be
- found.
-
-
-Remote display of OpenGL/GLX programs:
- As of version 1.2.3, Mesa's header files use the same GLenum and GLUenum
- values as SGI's (and most/all other vendor's) OpenGL headers. This means
- you can freely mix object files compiled with OpenGL or Mesa headers.
- In fact, on systems with dynamic runtime linkers it's possible to dynam-
- ically link with Mesa or OpenGL shared libraries at runtime, without
- recompiling or relinking anything!
-
- Using IRIX 5.x as an example, you can run SGI's OpenGL demos with the
- Mesa shared libraries as follows. Let's assume you're installing Mesa
- in /usr/local/Mesa and using the C-shell:
- % cd /usr/local/Mesa
- % make irix5-dso
- % setenv _RLD_LIST "/usr/local/Mesa/lib/libGL.so:DEFAULT"
- % /usr/demos/bin/ideas_ogl // this is a test
-
- You can now run OpenGL executables on almost any X display! There may
- be some problems from the fact that Mesa supports many X visual types
- that an OpenGL client may not expect (grayscale for example). In this
- case the application may abort, print error messages, or just behave
- strangely. You may have to experiment with the MESA_RGB_VISUAL envi-
- ronment variable.
-
-
-Xt/Motif Widgets:
- Two versions of the Xt/Motif OpenGL drawing area widgets are included:
-
- widgets-sgi/ SGI's stock widgets
- widgets-mesa/ Mesa-tuned widgets
-
- Look in those directories for details
-
-
-Togl:
- Togl is an OpenGL/Mesa widget for Tcl/Tk.
- See http://togl.sourceforge.net for more information.
-
-
-
-X Display Modes:
- Mesa supports RGB(A) rendering into almost any X visual type and depth.
-
- The glXChooseVisual function tries its best to pick an appropriate visual
- for the given attribute list. However, if this doesn't suit your needs
- you can force Mesa to use any X visual you want (any supported by your
- X server that is) by setting the MESA_RGB_VISUAL and MESA_CI_VISUAL
- environment variables. When an RGB visual is requested, glXChooseVisual
- will first look if the MESA_RGB_VISUAL variable is defined. If so, it
- will try to use the specified visual. Similarly, when a color index
- visual is requested, glXChooseVisual will look for the MESA_CI_VISUAL
- variable.
-
- The format of accepted values is: <visual-class> <depth>
- Here are some examples:
-
- using the C-shell:
- % setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor
- % setenv MESA_CI_VISUAL "PseudoColor 12" // 12-bit PseudoColor
- % setenv MESA_RGB_VISUAL "PseudoColor 8" // 8-bit PseudoColor
-
- using the KornShell:
- $ export MESA_RGB_VISUAL="TrueColor 8"
- $ export MESA_CI_VISUAL="PseudoColor 12"
- $ export MESA_RGB_VISUAL="PseudoColor 8"
-
-
-Double buffering:
- Mesa can use either an X Pixmap or XImage as the backbuffer when in
- double buffer mode. Using GLX, the default is to use an XImage. The
- MESA_BACK_BUFFER environment variable can override this. The valid
- values for MESA_BACK_BUFFER are: Pixmap and XImage (only the first
- letter is checked, case doesn't matter).
-
- A pixmap is faster when drawing simple lines and polygons while an
- XImage is faster when Mesa has to do pixel-by-pixel rendering. If you
- need depth buffering the XImage will almost surely be faster. Exper-
- iment with the MESA_BACK_BUFFER variable to see which is faster for
- your application.
-
-
-Colormaps:
- When using Mesa directly or with GLX, it's up to the application writer
- to create a window with an appropriate colormap. The aux, tk, and GLUT
- toolkits try to minimize colormap "flashing" by sharing colormaps when
- possible. Specifically, if the visual and depth of the window matches
- that of the root window, the root window's colormap will be shared by
- the Mesa window. Otherwise, a new, private colormap will be allocated.
-
- When sharing the root colormap, Mesa may be unable to allocate the colors
- it needs, resulting in poor color quality. This can happen when a
- large number of colorcells in the root colormap are already allocated.
- To prevent colormap sharing in aux, tk and GLUT, define the environment
- variable MESA_PRIVATE_CMAP. The value isn't significant.
-
-
-Gamma correction:
- To compensate for the nonlinear relationship between pixel values
- and displayed intensities, there is a gamma correction feature in
- Mesa. Some systems, such as Silicon Graphics, support gamma
- correction in hardware (man gamma) so you won't need to use Mesa's
- gamma facility. Other systems, however, may need gamma adjustment
- to produce images which look correct. If in the past you thought
- Mesa's images were too dim, read on.
-
- Gamma correction is controlled with the MESA_GAMMA environment
- variable. Its value is of the form "Gr Gg Gb" or just "G" where
- Gr is the red gamma value, Gg is the green gamma value, Gb is the
- blue gamma value and G is one gamma value to use for all three
- channels. Each value is a positive real number typically in the
- range 1.0 to 2.5. The defaults are all 1.0, effectively disabling
- gamma correction. Examples using csh:
-
- % setenv MESA_GAMMA "2.3 2.2 2.4" // separate R,G,B values
- % setenv MESA_GAMMA "2.0" // same gamma for R,G,B
-
- The demos/gamma.c program may help you to determine reasonable gamma
- value for your display. With correct gamma values, the color intensities
- displayed in the top row (drawn by dithering) should nearly match those
- in the bottom row (drawn as grays).
-
- Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well
- on HP displays using the HP-ColorRecovery technology.
-
- Mesa implements gamma correction with a lookup table which translates
- a "linear" pixel value to a gamma-corrected pixel value. There is a
- small performance penalty. Gamma correction only works in RGB mode.
- Also be aware that pixel values read back from the frame buffer will
- not be "un-corrected" so glReadPixels may not return the same data
- drawn with glDrawPixels.
-
- For more information about gamma correction see:
- http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html
-
-
-Overlay Planes
-
- Overlay planes in the frame buffer are supported by Mesa but require
- hardware and X server support. To determine if your X server has
- overlay support you can test for the SERVER_OVERLAY_VISUALS property:
-
- xprop -root | grep SERVER_OVERLAY_VISUALS
-
-
-HPCR glClear(GL_COLOR_BUFFER_BIT) dithering
-
- If you set the MESA_HPCR_CLEAR environment variable then dithering
- will be used when clearing the color buffer. This is only applicable
- to HP systems with the HPCR (Color Recovery) system.
-
-
-Extensions
-==========
- There are three Mesa-specific GLX extensions at this time.
-
- GLX_MESA_pixmap_colormap
-
- This extension adds the GLX function:
-
- GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
- Pixmap pixmap, Colormap cmap )
-
- It is an alternative to the standard glXCreateGLXPixmap() function.
- Since Mesa supports RGB rendering into any X visual, not just True-
- Color or DirectColor, Mesa needs colormap information to convert RGB
- values into pixel values. An X window carries this information but a
- pixmap does not. This function associates a colormap to a GLX pixmap.
- See the xdemos/glxpixmap.c file for an example of how to use this
- extension.
-
- GLX_MESA_release_buffers
-
- Mesa associates a set of ancillary (depth, accumulation, stencil and
- alpha) buffers with each X window it draws into. These ancillary
- buffers are allocated for each X window the first time the X window
- is passed to glXMakeCurrent(). Mesa, however, can't detect when an
- X window has been destroyed in order to free the ancillary buffers.
-
- The best it can do is to check for recently destroyed windows whenever
- the client calls the glXCreateContext() or glXDestroyContext()
- functions. This may not be sufficient in all situations though.
-
- The GLX_MESA_release_buffers extension allows a client to explicitly
- deallocate the ancillary buffers by calling glxReleaseBuffersMESA()
- just before an X window is destroyed. For example:
-
- #ifdef GLX_MESA_release_buffers
- glXReleaseBuffersMESA( dpy, window );
- #endif
- XDestroyWindow( dpy, window );
-
- This extension is new in Mesa 2.0.
-
- GLX_MESA_copy_sub_buffer
-
- This extension adds the glXCopySubBufferMESA() function. It works
- like glXSwapBuffers() but only copies a sub-region of the window
- instead of the whole window.
-
- This extension is new in Mesa version 2.6
-
-
-
-Summary of X-related environment variables:
- MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
- MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
- MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
- MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
- MESA_GAMMA - gamma correction coefficients (X only)
-
-
-----------------------------------------------------------------------
-$Id: README.X11,v 3.11 2003/12/17 15:14:31 brianp Exp $
--- /dev/null
+<HTML>
+
+<TITLE>Xlib Software Driver</TITLE>
+
+<link rel="stylesheet" type="text/css" href="mesa.css"></head>
+
+<BODY>
+
+<H1>Xlib Software Driver</H1>
+
+<p>
+Mesa's Xlib driver provides an emulation of the GLX interface so that
+OpenGL programs which use the GLX API can render to any X display, even
+those that don't support the GLX extension.
+Effectively, the Xlib driver converts all OpenGL rendering into Xlib calls.
+</p>
+
+<p>
+The Xlib driver is the oldest Mesa driver and the most mature of Mesa's
+software-only drivers.
+</p>
+
+<p>
+Since the Xlib driver <em>emulates</em> the GLX extension, it's not
+totally conformance with a true GLX implementation.
+The differences are fairly obscure, however.
+</p>
+
+<p>
+The unique features of the Xlib driver follows.
+</p>
+
+
+<H2>X Display Modes</H2>
+<p>
+Mesa supports RGB(A) rendering into almost any X visual type and depth.
+</p>
+<p>
+The glXChooseVisual function tries to choose the best X visual
+for the given attribute list. However, if this doesn't suit your needs
+you can force Mesa to use any X visual you want (any supported by your
+X server that is) by setting the <b>MESA_RGB_VISUAL</b> and
+<b>MESA_CI_VISUAL</b>
+environment variables.
+When an RGB visual is requested, glXChooseVisual
+will first look if the MESA_RGB_VISUAL variable is defined.
+If so, it will try to use the specified visual.
+Similarly, when a color index visual is requested, glXChooseVisual will
+look for the MESA_CI_VISUAL variable.
+</p>
+
+<p>
+The format of accepted values is: <code>visual-class depth</code>
+</p>
+<p>
+Here are some examples:
+</p>
+<pre>
+ using csh:
+ % setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor
+ % setenv MESA_CI_VISUAL "PseudoColor 12" // 12-bit PseudoColor
+ % setenv MESA_RGB_VISUAL "PseudoColor 8" // 8-bit PseudoColor
+
+ using bash:
+ $ export MESA_RGB_VISUAL="TrueColor 8"
+ $ export MESA_CI_VISUAL="PseudoColor 12"
+ $ export MESA_RGB_VISUAL="PseudoColor 8"
+</pre>
+
+
+<H2>Double buffering</H2>
+<p>
+Mesa can use either an X Pixmap or XImage as the backbuffer when in
+double buffer mode. Using GLX, the default is to use an XImage. The
+<b>MESA_BACK_BUFFER</b> environment variable can override this. The valid
+values for <b>MESA_BACK_BUFFER</b> are: <b>Pixmap</b> and <b>XImage</b>
+(only the first letter is checked, case doesn't matter).
+</p>
+
+<p>
+A pixmap is faster when drawing simple lines and polygons while an
+XImage is faster when Mesa has to do pixel-by-pixel rendering. If you
+need depth buffering the XImage will almost surely be faster.
+Experiment with the MESA_BACK_BUFFER variable to see which is faster
+for your application.
+</p>
+
+
+<H2>Colormaps</H2>
+<p>
+When using Mesa directly or with GLX, it's up to the application
+writer to create a window with an appropriate colormap. The GLUT
+toolkit tris to minimize colormap <em>flashing</em> by sharing
+colormaps when possible. Specifically, if the visual and depth of the
+window matches that of the root window, the root window's colormap
+will be shared by the Mesa window. Otherwise, a new, private colormap
+will be allocated.
+</p>
+
+<p>
+When sharing the root colormap, Mesa may be unable to allocate the colors
+it needs, resulting in poor color quality. This can happen when a
+large number of colorcells in the root colormap are already allocated.
+To prevent colormap sharing in GLUT, set the
+<b>MESA_PRIVATE_CMAP</b> environment variable. The value isn't
+significant.
+</p>
+
+
+<H2>Gamma correction</H2>
+<p>
+To compensate for the nonlinear relationship between pixel values
+and displayed intensities, there is a gamma correction feature in
+Mesa. Some systems, such as Silicon Graphics, support gamma
+correction in hardware (man gamma) so you won't need to use Mesa's
+gamma facility. Other systems, however, may need gamma adjustment
+to produce images which look correct. If you believe that
+Mesa's images are too dim, read on.
+</p>
+
+<p>
+Gamma correction is controlled with the <b>MESA_GAMMA</b> environment
+variable. Its value is of the form <b>Gr Gg Gb</b> or just <b>G</b> where
+Gr is the red gamma value, Gg is the green gamma value, Gb is the
+blue gamma value and G is one gamma value to use for all three
+channels. Each value is a positive real number typically in the
+range 1.0 to 2.5.
+The defaults are all 1.0, effectively disabling gamma correction.
+Examples:
+</p>
+<pre>
+ % export MESA_GAMMA="2.3 2.2 2.4" // separate R,G,B values
+ % export MESA_GAMMA="2.0" // same gamma for R,G,B
+</pre>
+<p>
+The progs/demos/gamma.c program may help you to determine reasonable gamma
+value for your display. With correct gamma values, the color intensities
+displayed in the top row (drawn by dithering) should nearly match those
+in the bottom row (drawn as grays).
+</p>
+
+<p>
+Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well
+on HP displays using the HP-ColorRecovery technology.
+</p>
+
+<p>
+Mesa implements gamma correction with a lookup table which translates
+a "linear" pixel value to a gamma-corrected pixel value. There is a
+small performance penalty. Gamma correction only works in RGB mode.
+Also be aware that pixel values read back from the frame buffer will
+not be "un-corrected" so glReadPixels may not return the same data
+drawn with glDrawPixels.
+</p>
+
+<p>
+For more information about gamma correction see:
+<a href="http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html"
+the Gamma FAQ</a>
+</p>
+
+
+<H2>Overlay Planes</H2>
+<p>
+Hardware overlay planes are supported by the Xlib driver. To
+determine if your X server has overlay support you can test for the
+SERVER_OVERLAY_VISUALS property:
+</p>
+<pre>
+ xprop -root | grep SERVER_OVERLAY_VISUALS
+</pre>
+
+
+<H2>HPCR glClear(GL_COLOR_BUFFER_BIT) dithering</H2>
+<p>
+If you set the <b>MESA_HPCR_CLEAR</b> environment variable then dithering
+will be used when clearing the color buffer. This is only applicable
+to HP systems with the HPCR (Color Recovery) feature.
+</p>
+
+
+<H2>Extensions</H2>
+<p>
+The following MESA-specific extensions are implemented in the Xlib driver.
+</p>
+
+<h3>GLX_MESA_pixmap_colormap</h3>
+
+<p>
+This extension adds the GLX function:
+</p>
+<pre>
+ GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
+ Pixmap pixmap, Colormap cmap )
+</pre>
+<p>
+It is an alternative to the standard glXCreateGLXPixmap() function.
+Since Mesa supports RGB rendering into any X visual, not just True-
+Color or DirectColor, Mesa needs colormap information to convert RGB
+values into pixel values. An X window carries this information but a
+pixmap does not. This function associates a colormap to a GLX pixmap.
+See the xdemos/glxpixmap.c file for an example of how to use this
+extension.
+</p>
+<p>
+<a href="MESA_pixmap_colormap.spec">GLX_MESA_pixmap_colormap specification</a>
+</p>
+
+
+<h3>GLX_MESA_release_buffers</h3>
+<p>
+Mesa associates a set of ancillary (depth, accumulation, stencil and
+alpha) buffers with each X window it draws into. These ancillary
+buffers are allocated for each X window the first time the X window
+is passed to glXMakeCurrent(). Mesa, however, can't detect when an
+X window has been destroyed in order to free the ancillary buffers.
+</p>
+<p>
+The best it can do is to check for recently destroyed windows whenever
+the client calls the glXCreateContext() or glXDestroyContext()
+functions. This may not be sufficient in all situations though.
+</p>
+<p>
+The GLX_MESA_release_buffers extension allows a client to explicitly
+deallocate the ancillary buffers by calling glxReleaseBuffersMESA()
+just before an X window is destroyed. For example:
+</p>
+<pre>
+ #ifdef GLX_MESA_release_buffers
+ glXReleaseBuffersMESA( dpy, window );
+ #endif
+ XDestroyWindow( dpy, window );
+</pre>
+<p>
+<a href="MESA_release_buffers.spec">GLX_MESA_release_buffers specification</a>
+</p>
+<p>
+This extension was added in Mesa 2.0.
+</p>
+
+<H3>GLX_MESA_copy_sub_buffer</H3>
+<p>
+This extension adds the glXCopySubBufferMESA() function. It works
+like glXSwapBuffers() but only copies a sub-region of the window
+instead of the whole window.
+</p>
+<p>
+<a href="MESA_copy_sub_buffer.spec">GLX_MESA_copy_sub_buffer specification</a>
+</p>
+<p>
+This extension was added in Mesa 2.6
+</p>
+
+<h2>Summary of X-related environment variables</H2>
+<pre>
+ MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
+ MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
+ MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
+ MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
+ MESA_GAMMA - gamma correction coefficients (X only)
+</pre>
+
+
+</body>
+</html>
projects / mesa.git / commitdiff