diff options
Diffstat (limited to 'nx-X11/extras/Mesa_6.4.1/docs/README.X11')
| -rw-r--r-- | nx-X11/extras/Mesa_6.4.1/docs/README.X11 | 314 |
1 files changed, 314 insertions, 0 deletions
diff --git a/nx-X11/extras/Mesa_6.4.1/docs/README.X11 b/nx-X11/extras/Mesa_6.4.1/docs/README.X11 new file mode 100644 index 000000000..4cbd12618 --- /dev/null +++ b/nx-X11/extras/Mesa_6.4.1/docs/README.X11 @@ -0,0 +1,314 @@ + + 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 $ |