From 6d8cf5181a09913eb856cfd2914d09a1644c26be Mon Sep 17 00:00:00 2001 From: Brian Paul Date: Fri, 17 Jan 2014 08:18:32 -0800 Subject: [PATCH] docs: remove some ancient README.* files None of this info is relevant anymore. Reviewed-by: Ian Romanick --- docs/README.CYGWIN | 256 -------------------------------------------- docs/README.MITS | 102 ------------------ docs/README.QUAKE | 207 ----------------------------------- docs/README.THREADS | 52 --------- 4 files changed, 617 deletions(-) delete mode 100644 docs/README.CYGWIN delete mode 100644 docs/README.MITS delete mode 100644 docs/README.QUAKE delete mode 100644 docs/README.THREADS diff --git a/docs/README.CYGWIN b/docs/README.CYGWIN deleted file mode 100644 index 58d5af3e293..00000000000 --- a/docs/README.CYGWIN +++ /dev/null @@ -1,256 +0,0 @@ - - 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: - 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 diff --git a/docs/README.MITS b/docs/README.MITS deleted file mode 100644 index a89176a62e6..00000000000 --- a/docs/README.MITS +++ /dev/null @@ -1,102 +0,0 @@ - - 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 - diff --git a/docs/README.QUAKE b/docs/README.QUAKE deleted file mode 100644 index e90c76a083e..00000000000 --- a/docs/README.QUAKE +++ /dev/null @@ -1,207 +0,0 @@ - - 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/ - - - ----------------------------------------------------------------------- diff --git a/docs/README.THREADS b/docs/README.THREADS deleted file mode 100644 index fb6e0ff3d1a..00000000000 --- a/docs/README.THREADS +++ /dev/null @@ -1,52 +0,0 @@ - - -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) -- 2.30.2