fdo-mirrors/mesa
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/mesa/mesa.git synced 2026-05-09 06:48:06 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Replace old README.X11 with updated xlibdriver.html

Browse source
This commit is contained in:
Brian Paul 2006-04-19 03:25:06 +00:00
parent b3282a3b9d
commit 12ad488e59
3 changed files with 266 additions and 315 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

314
docs/README.X11
View file

@ -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 3.11 2003/12/17 15:14:31 brianp Exp $

2
docs/systems.html
View file

@ -32,7 +32,7 @@ Be warned that some drivers may be out of date and no longer function.
</p>
<UL>
<LI>Xlib driver for the X Window System <A HREF="README.X11">(README.X11)</A>
<LI><a href="xlibdriver.html">Xlib driver</a> for the X Window System
<li><a href="http://dri.freedesktop.org/" target="_parent">
DRI hardware drivers</a> for the X window system
<LI>Microsoft Windows <A HREF="README.WIN32">(README.WIN32)</A>

265
docs/xlibdriver.html Normal file
View file

@ -0,0 +1,265 @@
<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>