diff options
| -rw-r--r-- | docs/README.X11 | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/docs/README.X11 b/docs/README.X11 new file mode 100644 index 00000000000..c70ba2f0a39 --- /dev/null +++ b/docs/README.X11 @@ -0,0 +1,301 @@ + + 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 $ |