aboutsummaryrefslogtreecommitdiff
path: root/nx-X11/extras/Mesa/docs/README.X11
diff options
context:
space:
mode:
Diffstat (limited to 'nx-X11/extras/Mesa/docs/README.X11')
-rw-r--r--nx-X11/extras/Mesa/docs/README.X11314
1 files changed, 0 insertions, 314 deletions
diff --git a/nx-X11/extras/Mesa/docs/README.X11 b/nx-X11/extras/Mesa/docs/README.X11
deleted file mode 100644
index 45c424273..000000000
--- a/nx-X11/extras/Mesa/docs/README.X11
+++ /dev/null
@@ -1,314 +0,0 @@
-
- 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 1.1.1.3 2004/08/12 23:43:27 anholt Exp $