Mesa Cygwin/X11 Information


WARNING
=======

If you installed X11 (packages xorg-x11-devel and xorg-x11-bin-dlls ) with the
latest setup.exe from Cygwin the GL (Mesa) libraries and include are already
installed in /usr/X11R6.

The following will explain how to "replace" them.

Installation
============

How to compile Mesa on Cygwin/X11 systems:

1. Shared libs:
    type 'make cygwin-sl'.

    When finished, the Mesa DLL will be in the Mesa-x.y/lib/ and
    Mesa-x.y/bin directories.


2. Static libs:
    type 'make cygwin-static'.
    When finished, the Mesa libraries will be in the Mesa-x.y/lib/ directory.

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/X11R6/include:
	cp -a include/GL /usr/X11R6/include

   Copy the Mesa library files to /usr/X11R6/lib:
	cp -a lib/* /usr/X11R6ocal/lib

   Copy the Mesa bin files (used by the DLL stuff) to /usr/X11R6/bin:
	cp -a lib/cyg* /usr/X11R6/bin

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.
   For the Motif widgets you must have downloaded the lesstif package.


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 (Win32 DLLS) you may have to set an
   environment variable to specify where the Mesa libraries are located.
   Set the PATH variable to include /your-dir/Mesa-2.6/bin.
   Otherwise, when you try to run a demo it may fail with a message saying
   that one or more DLL couldn't be found.


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)


----------------------------------------------------------------------
README.CYGWIN - lassauge April 2004 - based on README.X11

			Mesa 3.0 MITS Information


This software is distributed under the terms of the GNU Library
General Public License, see the LICENSE file for details.


This document is a preliminary introduction to help you get
started. For more detaile information consult the web page.

http://10-dencies.zkm.de/~mesa/



Version 0.1 (Yes it's very alpha code so be warned!)
Contributors:
  Emil Briggs    	(briggs@bucky.physics.ncsu.edu)
  David Bucciarelli 	(tech.hmw@plus.it)
  Andreas Schiffler 	(schiffler@zkm.de)



1. Requirements:
     Mesa 3.0.
     An SMP capable machine running Linux 2.x
     libpthread installed on your machine.


2. What does MITS stand for?
     MITS stands for Mesa Internal Threading System. By adding
     internal threading to Mesa it should be possible to improve
     performance of OpenGL applications on SMP machines.


3. Do applications have to be recoded to take advantage of MITS?
     No. The threading is internal to Mesa and transparent to
     applications.


4. Will all applications benefit from the current implementation of MITS?
     No. This implementation splits the processing of the vertex buffer
     over two threads. There is a certain amount of overhead involved
     with the thread synchronization and if there is not enough work
     to be done the extra overhead outweighs any speedup from using
     dual processors. You will not for example see any speedup when
     running Quake because it uses GL_POLYGON and there is only one
     polygon for each vertex buffer processed. Test results on a
     dual 200 Mhz. Pentium Pro system show that one needs around
     100-200 vertices in the vertex buffer before any there is any
     appreciable benefit from the threading.


5. Are there any parameters that I can tune to try to improve performance.
     Yes. You can try to vary the size of the vertex buffer which is
     define in VB_MAX located in the file src/vb.h from your top level
     Mesa distribution. The number needs to be a multiple of 12 and
     the optimum value will probably depend on the capabilities of
     your machine and the particular application you are running.


6. Are there any ways I can modify the application to improve its
   performance with the MITS?
     Yes. Try to use as many vertices between each Begin/End pair
     as possbile. This will reduce the thread synchronization
     overhead.


7. What sort of speedups can I expect?
     On some benchmarks performance gains of up to 30% have been
     observerd. Others may see no gain at all and in a few rare
     cases even some degradation.


8. What still needs to be done?
     Lots of testing and benchmarking.
     A portable implementation that works within the Mesa thread API.
     Threading of additional areas of Mesa to improve performance
     even more.



Installation:

   1. This assumes that you already have a working Mesa 3.0 installation
      from source.
   2. Place the tarball MITS.tar.gz in your top level Mesa directory.
   3. Unzip it and untar it. It will replace the following files in
      your Mesa source tree so back them up if you want to save them.


	 README.MITS
         Make-config
	 Makefile
	 mklib.glide
         src/vbxform.c
	 src/vb.h

   4. Rebuild Mesa using the command

          make linux-386-glide-mits

             Info on using Mesa 3.0 with Linux Quake I and Quake II



Disclaimer
----------

I am _not_ a Quake expert by any means.  I pretty much only run it to
test Mesa.  There have been a lot of questions about Linux Quake and
Mesa so I'm trying to provide some useful info here.  If this file
doesn't help you then you should look elsewhere for help.  The Mesa
mailing list or the news://news.3dfx.com/3dfx.linux.glide newsgroup
might be good.

Again, all the information I have is in this file.  Please don't email
me with questions.

If you have information to contribute to this file please send it to
me at brianp@elastic.avid.com



Linux Quake
-----------

You can get Linux Quake from http://www.idsoftware.com/

Quake I and II for Linux were tested with, and include, Mesa 2.6.  You
shouldn't have too many problems if you simply follow the instructions
in the Quake distribution.



RedHat 5.0 Linux problems
-------------------------

RedHat Linux 5.x uses the GNU C library ("glibc" or "libc6") whereas
previous RedHat and other Linux distributions use "libc5" for its
runtime C library.

Linux Quake I and II were compiled for libc5.  If you compile Mesa
on a RedHat 5.x system the resulting libMesaGL.so file will not work
with Linux Quake because of the different C runtime libraries.
The symptom of this is a segmentation fault soon after starting Quake.

If you want to use a newer version of Mesa (like 3.x) with Quake on
RedHat 5.x then read on.

The solution to the C library problem is to force Mesa to use libc5.
libc5 is in /usr/i486-linux-libc5/lib on RedHat 5.x systems.

Emil Briggs (briggs@tick.physics.ncsu.edu) nicely gave me the following
info:

>   I only know what works on a RedHat 5.0 distribution. RH5 includes
> a full set of libraries for both libc5 and glibc. The loader ld.so
> uses the libc5 libraries in /usr/i486-linux-libc5/lib for programs
> linked against libc5 while it uses the glibc libraries in /lib and
> /usr/lib for programs linked against glibc.
>
> Anyway I changed line 41 of mklib.glide to
>     GLIDELIBS="-L/usr/local/glide/lib -lglide2x -L/usr/i486-linux-libc5/lib"
>
> And I started quake2 up with a script like this
> #!/bin/csh
> setenv LD_LIBRARY_PATH /usr/i486-linux-libc5/lib
> setenv MESA_GLX_FX f
> ./quake2 +set vid_ref gl
> kbd_mode -a
> reset


I've already patched the mklib.glide file.  You'll have to start Quake
with the script shown above though.



**********************

Daryll Strauss writes:

Here's my thoughts on the problem. On a RH 5.x system, you can NOT build
a libc5 executable or library. Red Hat just doesn't include the right
stuff to do it.

Since Quake is a libc5 based application, you are in trouble. You need
libc5 libraries.

What can you do about it? Well there's a package called gcc5 that does
MOST of the right stuff to compile with libc5. (It brings back older
header files, makes appropriate symbolic links for libraries, and sets
up the compiler to use the correct directories) You can find gcc5 here:
ftp://ecg.mit.edu/pub/linux/gcc5-1.0-1.i386.rpm

No, this isn't quite enough. There are still a few tricks to getting
Mesa to compile as a libc5 application. First you have to make sure that
every compile uses gcc5 instead of gcc. Second, in some cases the link
line actually lists -L/usr/lib which breaks gcc5 (because it forces you
to use the glibc version of things)

If you get all the stuff correctly compiled with gcc5 it should work.
I've run Mesa 3.0B6  and its demos in a window with my Rush on a Red Hat
5.1 system. It is a big hassle, but it can be done. I've only made Quake
segfault, but I think that's from my libRush using the wrong libc.

Yes, mixing libc5 and glibc is a major pain. I've been working to get
all my libraries compiling correctly with this setup. Someone should
make an RPM out of it and feed changes back to Brian once they get it
all working. If no one else has done so by the time I get the rest of my
stuff straightened out, I'll try to do it myself.

							- |Daryll



*********************

David Bucciarelli (tech.hmw@plus.it) writes:

I'm using the Mesa-3.0beta7 and the RedHat 5.1 and QuakeII is
working fine for me.  I had only to make a small change to the
Mesa-3.0/mklib.glide file, from:


    GLIDELIBS="-L/usr/local/glide/lib -lglide2x
-L/usr/i486-linux-libc5/lib -lm"

to:

    GLIDELIBS="-L/usr/i486-linux-libc5/lib -lglide2x"

and to make two symbolic links:

[david@localhost Mesa]$ ln -s libMesaGL.so libMesaGL.so.2
[david@localhost Mesa]$ ln -s libMesaGLU.so libMesaGLU.so.2

I'm using the Daryll's Linux glide rpm for the Voodoo2 and glibc (it
includes also the Glide for the libc5). I'm not using the /dev/3Dfx and
running QuakeII as root with the following env. var:

export
LD_LIBRARY_PATH=/dsk1/home/david/src/gl/Mesa/lib:/usr/i486-linux-libc5/lib

I think that all problems are related to the glibc, Quake will never
work if you get the following output:

[david@localhost Mesa]$ ldd lib/libMesaGL.so
        libglide2x.so => /usr/lib/libglide2x.so (0x400f8000)
        libm.so.6 => /lib/libm.so.6 (0x40244000)
        libc.so.6 => /lib/libc.so.6 (0x4025d000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00000000)

You must get the following outputs:

[david@localhost Mesa]# ldd lib/libMesaGL.so
        libglide2x.so => /usr/i486-linux-libc5/lib/libglide2x.so
(0x400f3000)

[root@localhost quake2]# ldd quake2
        libdl.so.1 => /lib/libdl.so.1 (0x40005000)
        libm.so.5 => /usr/i486-linux-libc5/lib/libm.so.5 (0x40008000)
        libc.so.5 => /usr/i486-linux-libc5/lib/libc.so.5 (0x40010000)

[root@localhost quake2]# ldd ref_gl.so
        libMesaGL.so.2 =>
/dsk1/home/david/src/gl/Mesa/lib/libMesaGL.so.2 (0x400eb000)
        libglide2x.so => /usr/i486-linux-libc5/lib/libglide2x.so
(0x401d9000)
        libX11.so.6 => /usr/i486-linux-libc5/lib/libX11.so.6
(0x40324000)
        libXext.so.6 => /usr/i486-linux-libc5/lib/libXext.so.6
(0x403b7000)
        libvga.so.1 => /usr/i486-linux-libc5/lib/libvga.so.1
(0x403c1000)
        libm.so.5 => /usr/i486-linux-libc5/lib/libm.so.5 (0x403f5000)
        libc.so.5 => /usr/i486-linux-libc5/lib/libc.so.5 (0x403fd000)


***********************

Steve Davies (steve@one47.demon.co.uk) writes:


Try using:

    export LD_LIBRARY_PATH=/usr/i486-linux-libc5/lib
    ./quake2 +set vid_ref gl

to start the game... Works for me, but assumes that you have the
compatability libc5 RPMs installed.


***************************

WWW resources - you may find additional Linux Quake help at these URLs:


http://quake.medina.net/howto

http://webpages.mr.net/bobz

http://www.linuxgames.com/quake2/



----------------------------------------------------------------------

Mesa Threads README
-------------------

Thread safety was introduced in Mesa 2.6 by John Stone and
Christoph Poliwoda.

It was redesigned in Mesa 3.3 so that thread safety is
supported by default (on systems which support threads,
that is).  There is no measurable penalty on single
threaded applications.

NOTE that the only _driver_ which is thread safe at this time
is the OS/Mesa driver!


At present the mthreads code supports three thread APIS:
  1) POSIX threads (aka pthreads).
  2) Solaris / Unix International threads.
  3) Win32 threads (Win 95/NT).

Support for other thread libraries can be added src/glthread.[ch]


In order to guarantee proper operation, it is
necessary for both Mesa and application code to use the same threads API.
So, if your application uses Sun's thread API, then you should build Mesa
using one of the targets for Sun threads.

The mtdemos directory contains some example programs which use
multiple threads to render to osmesa rendering context(s).

Linux users should be aware that there exist many different POSIX
threads packages. The best solution is the linuxthreads package
(http://pauillac.inria.fr/~xleroy/linuxthreads/) as this package is the
only one that really supports multiprocessor machines (AFAIK). See
http://pauillac.inria.fr/~xleroy/linuxthreads/README for further
information about the usage of linuxthreads.

If you are interested in helping with thread safety work in Mesa
join the Mesa developers mailing list and post your proposal.


Regards,
  John Stone           -- j.stone@acm.org  johns@cs.umr.edu
  Christoph Poliwoda   -- poliwoda@volumegraphics.com


Version info:
   Mesa 2.6 - initial thread support.
   Mesa 3.3 - thread support mostly rewritten (Brian Paul)

VMS support contributed by Jouk Jansen (joukj@hrem.stm.tudelft.nl)


The latest version was tested on a VMSAlpha7.2 system using DECC6.0, but
probably also works for other versions.

At the moment only the libraries LIBMESGL.EXE/LIBMESGL.OLB,
LIBMESAGLU.EXE/LIBMESAGLU.OLB and LIBGLUT.EXE/LIBGLUT.OLB and the demos of the
directory [.DEMOS] can be build.
However, feel free to create the missing "decrip.mms-files" in the other
directories.

 The make files were tested
using the DIGITAL make utility called MMS.  There is also a public domain
clone available (MMK) and I  think, but it is not tested, that this
utility will give (hardly) any problem.

To make everything just type MMS (or MMK) in the main directory of
mesagl.  For MMS the deafult makefile is called descrip.mms, and
that is what I have called it.  I included alse some config files,
all having mms somewhere in the name which all the makefiles need
(just as your unix makefiles).

On Alpha platforms at default a sharable images for the libraries are created.
To get a static library make it by typing MMS/MACRO=(NOSHARE=1).
On VAX platforms only static libraries can be build.

23-sep-2005
changed default compilation to use /float=ieee/ieee=denorm. The reason for
this is that it makes Mesa on OpenVMS better compatible with other platforms
and other packages for VMS that I maintain.
For more information see
      http://nchrem.tnw.tudelft.nl/openvms
      https://bugs.freedesktop.org/show_bug.cgi?id=4270
You may want to compile Mesa to use VAX-floating point arithmetic, instead
of IEEE floating point by removing the /float=IEEE/denorm flag from the
compiler options in the descrip.mms files.

File: docs/README.WIN32

Last updated: 23 April 2011


Quick Start
----- -----

Windows drivers are build with SCons.  Makefiles or Visual Studio projects are
no longer shipped or supported.

Run

  scons osmesa mesagdi

to build classic mesa Windows GDI drivers; or

  scons libgl-gdi

to build gallium based GDI driver.

This will work both with MSVS or Mingw.


Windows Drivers
------- -------

At this time, only the gallium GDI driver is known to work.

Source code also exists in the tree for other drivers in
src/mesa/drivers/windows, but the status of this code is unknown.


General
-------

After building, you can copy the above DLL files to a place in your
PATH such as $SystemRoot/SYSTEM32.  If you don't like putting things
in a system directory, place them in the same directory as the
executable(s).  Be careful about accidentially overwriting files of
the same name in the SYSTEM32 directory.

The DLL files are built so that the external entry points use the
stdcall calling convention.

Static LIB files are not built.  The LIB files that are built with are
the linker import files associated with the DLL files.

The si-glu sources are used to build the GLU libs.  This was done
mainly to get the better tessellator code.

If you have a Windows-related build problem or question, please post
to the mesa-dev or mesa-users list.