--- /dev/null
+
+ Mesa 3.0 Unix/X11 Information
+
+
+
+Installation
+============
+
+To compile the library, 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.
+
+The top-level makefile will execute the makefiles in a number of sub-
+directories. When finished, the Mesa libraries will be in the Mesa-2.6/lib/
+directory. A few GLUT demos in the demos/ directory should be ready to run.
+
+If you also downloaded and unpacked the demos there should be executables
+in the "xdemos/", "samples/", and "book/" directories for you to try out.
+If you only want to compile the contents of one subdirectory you can 'cd'
+to that directory and type 'make <config>' there.
+
+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.
+
+If you have compilation problems you should try to fix them and return the
+patches to the author.
+
+
+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)
+
+ Create a few symbolic links so that compiling OpenGL applications is easy:
+ cd /usr/local/lib
+ IF USING STATIC (lib*.a) FILES THEN
+ ln -s libMesaGL.a libGL.a
+ ln -s libMesaGLU.a libGLU.a
+ ELSE
+ ln -s libMesaGL.so libGL.so
+ ln -s libMesaGLU.so libGLU.so
+ ENDIF
+
+
+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/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
+ % cd lib
+ % ln -s libMesaGL.so libGL.so
+ % 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://www.ssec.wisc.edu/~brianp/Togl.html 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 (X11 only):
+ 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 (X11 only):
+ 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 (X11 only):
+ 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
+
+
+
+Extensions:
+ The following OpenGL GLX extensions are currently implemented:
+
+ GLX_EXT_visual_info - GLX visual and transparent pixel extension
+
+ For detailed information about the extensions see www.opengl.org
+
+ There are four Mesa-specific GL/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.0 1998/02/14 17:45:13 brianp Exp $
projects / mesa.git / commitdiff