Mesa/Readme.win32 Last Updated: Friday, July 9th, 1999 - tjump@tertius.com *** What's New - Updated for Mesa 3.1beta2/CVS. - DevStudio projects suspended for compatability reasons: projects modified by DevStudio 6 are not compatible with DevStudio 5. - Build environment change: The Glide SDK is no longer assumed to be in the global INCLUDE/LIB environment vars, it is required that you set the value 'GLIDE2X' as either an environment variable pointing to your Glide SDK install directory or that you configure that as a build option to nmake.exe when building fxmesagl32. Examples: nmake /f nmake.mak GLIDE2X=g:\sdk\glide2x fxmesagl32 nmake /f nmake.mak GLIDE2X=g:\sdk\glide2x allfx nmake /f nmake.mak GLIDE2X=g:\sdk\glide2x progs.3dfx.demos The DevStudio workspace files for 3Dfx OpenGL require the definition of GLIDE2SDK as an environment variable pointing to where your copy of the Glide SDK has been installed. Adding this to your AUTOEXEC.BAT would do so (change the directories to match): SET GLIDE2SDK=G:\SDK\GLIDE2X *** Legalese These build files are provided as-is and are submitted to be included with the "Mesa 3-D Graphics Library" package as (currently) maintained by Brian Paul. These project build files are free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. These project files are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. *** Maintenance Responsiblity and Technical Support While these files are now part of the Mesa core distribution please do NOT contact Mr. Paul for help with them if you encounter problems as he can't help you (currently). I will, however, attempt my straightforward best in assisting anyone with using these files on their system. I can NOT guarantee instant responses owing to other responsiblities, but I do try dang hard to answer any mail w/in 24 hours. I may be contacted at the above email address for the forseeable future. -Ted mailto://tjump@tertius.com http://www.tertius.com/tjump *** General Information These build files facilitate convenient building of many variants of Mesa, both as static link libraries (including mesaglu) and as dynamic link libraries that in some cases may be used as "drop-in" replacements for OpenGL32.DLL on both Windows95 and Windows NT. The construction of the Win32 command-line build files and projects has been something of a pet project of mine, and is based upon my own "standard" Win32 build environment as supplied by the "nmake.mif" file. They have been tested under Windows95 OSR2, Windows NT 4.0SP3, and Windows NT 5.0 beta 1. The libraries that they generated have been tested (via the demo programs) in a *limited* fashion on the above three systems, including the 3Dfx versions. The reason I went with command-line build environment instead of the more convenient IDE-based project files is for two reasons: 1. These appear to have some amount of portability between versions (the nmake syntax hasn't changed much since Microsoft C 7.0) while the IDE project files seem to change drastically each version. and 2. These are readable with any ascii editor and such are better self-documentation of the file relationships for more people such that it will facilitate supporting other Win32 compilers. While these files only deal with building for x86 targeted code it *should* be possible to add the necessary logic to them to build for the other MSVC supported CPU targets, I simply have no hardware to test them on nor the alternative compilers to build with. *** Prerequisites for use 1. You must have a 32-bit Microsoft compiler installed. I have tested this with Visual C 5.0 (SP3) and Visual C 4.2, but with minor (possibly no) modification to the nmake.mak and nmake.mif files this sequence should work on Visual C 2.0 also. The workspace files (mesalib.dsw and mesademos-*.dsw) and their included project files (*.dsp) are specific to the DevStudio IDE - I have made no attempt at building a VC4 IDE project set as I do not use that any more. Note that the VC workspace files NO LONGER use NORE are dependant upon the nmake.mak and nmake.mif files for construction of definition (*.DEF) and resource (*.RC) files. *** Visual C 4.x Users Warning **** Note that early editions of VC4 do NOT have header files current enough for use building this code base. If you are using VC4 you will either need to get an update to version 4.2 *or* you may download the Platform SDK directly from Microsoft's web site (www.microsoft.com) and update your build environment that way. *** Visual C 4.x Users Warning **** 2. You must have the PATH, INCLUDE, and LIB environment variables set properly. With VC5 you can easily get this by executing the VCVARS32.BAT file that was created for you upon installation. It is found in the DevStudio\VC\BIN directory, wherever you installed DevStudio. VC4 provides a similar batch file in it's BIN directory also. 3. (optional) If you're going to build for 3Dfx/Voodoo you will need to have previously installed the Glide SDK version 2.3 or later, if I recall. This may be retrieved from www.3dfx.com for no money and some download time. ;-) These build files assume that you have the Glide SDK added to the respective environment variables (LIB and INCLUDE). 4. (optional) If you're going to build for S3/Virge you will need the S3 Developers Toolkit which may be downloaded from www.s3.com for the price of registering on-line and some time. NOTE: I can build the s3mesa.dll file to completion, however the compilation of s3mesa.c currently generates a large amount of compiler warnings and between that and the fact that I can not at all test it I can make no claims to it's ability to execute. Again, like the 3Dfx version before this, these build files assume you have the S3Dtk H and LIB files in the path of their respective environment variables. Note 2: As of Mesa3.0beta6 I have build files, both command-line and IDE, which should be able to build the s3mesa code base if it weren't for updates being required in the S3 DD code support (Mesa-3.0/src/s3 directory). I advise putting any include and lib files for secondary toolkits (Glide, S3Tk, whatever) in their respective environment variables *before* the Microsoft-assigned default values. *** FAQ: Frequenty Asked Questions and Other Important Information *** - When running the 3Dfx demos under Windows NT, they crash on exit, what's up? This is apparently a problem in Glide itself. The workaround is to go to your C:\WINNT\SYSTEM32 directory and rename the file FXOEM2X.DLL to FXOEM2X.DL_ to prevent Glide from loading and initializing it upon startup. This is known to be an issue with cards that do not have "TV out" and is known to cause crashes on Diamond Monster II 8M and 3Dfx Reference boards, all using 3Dfx Reference Drivers version 2.53. Other hardware/driver combinations will also likely exhibit this behavior. - I'm having a problem building Mesa for static library linking. This was caused by some incomplete testing on my part, and a fix is now available in the form of an add-on to the base Mesa 3.0 release. The file to get is: via FTP download from: iris.ssec.wisc.edu you want to go here: /pub/Mesa/patches_to_3.0/ you want to get file: Mesa-3.0-w32-static-fixes.tar.gz This required a minor addition to INCLUDE/GL for a clean solution, the file "include/gl/mesa_wgl.h" is automatically included by "include/gl/gl.h" when a Win32 non-DLL build is in progress to provide prototypes for the various wgl functions. The only remaining hitch in this setup is that the 3Dfx build is not yet running as a static build, because of problems with conflicts in existance of the various GDI functions like ChoosePixelFormat, etc. *sigh* Anyway, the "allstatic" target now works as expected and builds all book/sample/demos programs to boot. ;^) - How do I get fxMesa to render in a window on the desktop instead of only full-screen? Use the Microsoft Windows fxMesa-in-a-window hack! Seriously, if you want fxMesaGL to render using the 3Dfx Voodoo1 or Voodoo2 hardware into a window on the desktop then all you need to do is set the MESA_WGL_FX environment variable to anything other than "fullscreen" and it will render into a window. If you wish to go fullscreen then you only need to NOT have the environment variable, or have it set to "fullscreen". You may also switch at runtime between fullscreen-mode and windowed by pressing ALT-ENTER on the keyboard (unless the application using Mesa does something with those keystrokes, of course). As of 8/13/98 this should be running a LOT better for more people as a low-compatability item was cleaned up which prevented it from working on many (most?) display drivers under Windows 9x. - I have my 3Dfx card hooked to it's own monitor and I want the output to stay on even if I switch to another program, is this possible? If the Glide environment variable SST_DUALHEAD is set to '1' then fxMesa will never disable the Voodoo output on a Voodoo1 or Voodoo2 display regardless of whether the fxMesa application is "current" or not. This works regardless of whether it's rendering using the window hack mentioned above or not. - I want to run the Mesa demos on my Intel740 card using it's own OpenGL acceleration, how do I do this? Build GLUT standalone for use with system OpenGL and GLU drivers! The Command-line project supports building all test/demo programs against these drivers also! This allows you full use of GLUT on Windows using hardware accelerated OpenGL. Wheee! This includes the "3dfx/demos" directory of which only two programs will not run on "standard" opengl. Note that there are a few of the sample programs which will NOT work without Mesa as they directly call into Mesa instead of using the extension mechanism. *** Included programs that exhibit unfortunate or bad behavior - demos/bounce - doesn't run on high-colors screens? It's requesting an INDEX display from GLUT and that fails on my true-color desktop. Changing this to _RGB let's the program work, but it doesn't display properly. This is probably just an idiosyncracy of my machine though, as if I test the program using GLUT for System OpenGL on my Intel740 OpenGL accelerated machine it's just hunky-dory. - demos/glutfx - runs, but crashes on exit (but not on my Intel740 machine) - demos/texobj - runs, but crashes on exit if ESC is pressed. Exits cleanly if the Close box on the window frame is pressed with the mouse. Go figure. - book/aaindex - doesn't run, can't get pixel format, because it wants an INDEX display maybe (but is okay on my Intel740 machine)? - most of the book/* demos don't respond to ESC being pressed. - 3dfx/demos/* - all demos run, however they all crash on exit. I've traced this so far as to determine the call it's happening with. The crash comes from within Glide during the processing of the grGlideShutdown() call, as in invalid memory reference exception. I'm wondering if this is because of some state or processing not being completed before the call. Dunno, but putting grSstIdle() in just before grGlideShutdown() does NOT fix the problem. - 3dfx/demos/tunnel2 - does not run on my system even with SLI mode disabled. Hmmmm, maybe I need to disconnect my Voodoo2 cards? *** Important Notes and Changing Default values - The optimizer settings have been manually reworked in both command line and DevStudio IDE files to hopefully prevent possible irrational code on the part of the code generator. Formerly, it was configured for "/Ox", now it is configured for safer handling at a slight potential performance cost. This may not be required for Visual Studio 6 but I can't test that (yet). - These files build with the code targeted for Pentium processors and 8-byte structure padding. - The IDE-built programs seem to be "happier" in that the command line build of the 3Dfx demo "fire" will grenade on exit (?). Otherwise pretty much everything may be built with either interface. - The currently configured Mesa version is 3.1, and MesaDemos version is the same. To change this permanently you will need to edit NMAKE.MAK and change the lines that look like this (they start o/a line 116): # Currently, Mesa is at rev 3.1 ... # !IF "$(MESAVER)" == "" MESAVER=3.1 !ENDIF # used in building all of the resource files for the Mesa DLLs # !IF "$(MESAFILEVER)" == "" MESAFILEVER=3,1,0,0 !ENDIF - Currently the build files are configured to be used from a Win32 directory that is included inside the main Mesa-3.1 heirarchy. - The build files are smart enough to find the files for the core lib, glu, glut, and the various demo programs if they are unpacked in the current Mesa-3.1 heirarchy, like this: \Mesa-3.1 \Mesa-3.1\src \Mesa-3.1\src-glu \Mesa-3.1\src-glut \Mesa-3.1\Win32 \Mesa-3.1\samples \Mesa-3.1\demos \Mesa-3.1\book \Mesa-3.1\3Dfx\demos ... should work. This arose because my initial build tests for the demo files were done before MesaDemos 2.6 had been released. - With the exception of the static link libraries generated by this file set (mesagl.lib, mesaglu.lib, mesaglut.lib) all DLLs and executables are built against the "Multithreaded DLL" runtime - this means that they require MSVCRT.DLL or MSVCRTD.DLL in the path to execute. ** CHANGED 8/11/98 *** Note also that the demos are all built aginst the "OpenGL32, GLU32, and GLUT32" and as such they are fairly agnostic wrt: building against Mesa for CPU-rendering, Mesa-for-3Dfx, Mesa-for-S3, or System OpenGL. If you want to build them for use on your system and your display card provides full OpenGL acceleration (Permedia, Intel740, Intergraph, whatever) then you only need to build GLUT prior to building any of the demo programs. For convenience, the GLUT project is included in each of the demo projects Workspace files for the DevStudio IDE builds BUT it is not automatically built - you still need to build it first manually. Note that if you have GLUT already installed on your system (gl/glut.h in yoru INCLUDE path, glut32.lib/glut32d.lib in your LIB path, and the DLL in your PATH) then you do NOT need to build GLUT prior to the test programs. - The 3Dfx build of Mesa has primarily been tested with Quake 2 and it runs (mostly) fine on my PC (take that for what you want it)... ** CHANGED 8/11/98 *** There is still something going on that causes Glide to crash on shutdown, when I run fxMesa under Windows NT, however it does not appear to occur under Windows 9x on either Voodoo1 or Voodoo2 cards. *sigh* - I can not test the S3 build as I have no machines available with Virge based display cards. - The multithreaded test code is *not* built as it requires pthreads and I have as of yet spent not time trying to get that running. The latest word that I saw WRT threading support on win32 was that they are intending to support it natively within Win32 - so I'm waiting it out until they get it done. - Similarly, the 'xdemos' are not currently built because I haven't gotten around to building the client libs for native win32 and getting it all setup for use. *** Output Files All final output files (DLL/LIB) are placed in the Mesa-3.1/lib directory, with the exception of the fxMesaGL32 build which is placed in Mesa-3./lib/FX and the executable images which are placed in their source directories. To be able to execute the various test programs, you will need to copy the requisite DLL files into the same directory as the EXE files. Note that most of the 3Dfx/demos/* programs WILL run with the non-FX build of Mesa - just very slowly. The two programs which are hard-linked with the FX build and will not run without it are "glbpaltx" which uses "gl3DfxSetPaletteEXT" directly instead of via the extensions mechanism and "tunnel2" which uses "fxMesaSelectCurrentBoard" API for selecting between multiple 3Dfx cards installed in one system. Likewise, "paltex" directly uses the "glColorTableEXT" extension and thus may not run on anything except Mesa. If these applications used the proper extension mechanism they could then be used on more than "just" fxMesa to good effect (for example, the rest of the "3Dfx/demos" run just peachy on the Intel740 card in my test machine) under WinNT. Because I'm anal about my computer and it's organization, and I like to prevent collision between builds, each of the subprojects has their own intermediate file directory inside .\win32\release (for example, when building mesagl.lib all of it's intermediate files will be found in .\win32\release\lib.mesagl). This makes it very easy to cleanup as you only need to remove .\win32\release. *** Okay, Enough, how do I build with this stuff already Ted! Okay, no major calamity here. The basic way to use the project file is to call it via NMAKE from the command line. The format is: nmake[.exe] /f nmake.mak [options] [target] The most likely [options] values you will use may be any combination of the following: DEBUG=1 or DEBUG=0 USE_CRTDLL=1 or USE_CRTDLL=0 Note that all three of these options are OFF by default. The [target] includes but is not limited to the following (for full details please peruse the NMAKE.MAK and NMAKE.MIF files - but be warned that NMAKE.MIF is rather large and sometimes hard to follow): --- convenience targets --- all - builds everything libfiles - builds all linking library files progs - builds all executable images --- library files, static and dynamic --- mesagl - static lib build of Mesa core. mesaglu - static lib build of MesaGLU core. mesaglut - static lib build of Mesa GLUT core. mesagl32 - dynamic lib build of Mesa core. mesaglu32 - dynamic lib build of GLU core, generates GLU32.DLL and/or GLU32d.DLL. mesaglut32 - dynamic lib build of GLUT core, generates GLUT32.DLL and/or GLUT32d.dll. --- hardware accelerated mesa builds --- fxmesagl32 - builds Mesa for use on top of the 3Dfx Glide runtime libs s3mesagl32 - builds mesa for use on top of the S3 'S3Tk' runtime libs. --- executable images --- progs.book - builds all programs in \book directory progs.demos - builds all programs in \demos directory progs.samples - builds all programs in \samples directory These targets generate all of the programs in their respective directories and link the executables against OpenGL32.DLL, GLU32.DLL, and GLUT32.DLL (or their debug equivalents). progs.3dfx.demos - builds all programs in \3dfx\demos directory This target generates the 3Dfx/Demo executables, linking them against GLUT32.DLL, GLU32.DLL, OPENGL32.DLL and are thus NOT hard-bound to using Mesa per-se as you can simply NOT build the Mesa core and GLU libraries. --- Microsoft/SGI OpenGL-based GLUT and Demo program builds ---- *** IMPORTANT SAFETY TIP: If you're going to build these variants of GLUT then DO NOT build any other target libraries in this package first, OR from the command line run the "nmake /f nmake.mak clean" command first! This is because generation of the GLUT for SGI OpenGL target libraries conflicts in naming with the static build libraries of Mesa and it's supporting GLUT build. Currently, you may build GLUT as either GLUT32.DLL or GLUT.DLL for use running against either Microsoft or SGI OpenGL for Window, respectively. This allows for the general use of GLUT 3.7 on Windows systems with fully compliant OpenGL. You can build the GLUT DLL files either with the command line by issuing either of these commands: nmake /f nmake.mak glut.sysgl nmake /f nmake.mak glut.sgigl OR by using the DevStudio MesaLib Worksapce build the GLUT_SGIGL or GLUT_SYSGL projects within the DevStudio IDE. Unfortunately, the only way to build the test programs against this build of GLUT is via the command line, and I will NOT be making duplicate demo program projects for the IDE as it's just not worth it, sorry. To build the test programs against either MS or SGI OpenGL, you do so via either of these two commands: nmake /f nmake.mak progs.sysgl nmake /f nmake.mak progs.sgigl To use the GLUT-for-system-OpenGL in your own programs, you need to do three things by way of preparation, after building GLUT of course: 1. Copy include\gl\glut.h to somewhere in your %INCLUDE% path, one likely candidate location would be in your "DevStudio\VC\INCLUDE\GL" directory. 2. Copy the linking libraries to somewhere in your %LIB% path, one likely candidate location would be in your "DevStudio\VC\LIB" directory. The linking libraries you need to copy are as follows: .\Release\GLUT32.LIB .\Release\GLUT.LIB .\Debug\GLUT32.LIB .\Debug\GLUT.LIB 3. Copy the runtime libraries to somewhere in your %PATH%, one likely candidate location would be in WINDOWS\SYSTEM. the files that you should copy are as follows: .\Release\GLUT32.DLL .\Release\GLUT32.PDB .\Release\GLUT.DLL .\Release\GLUT.PDB .\Debug\GLUT32d.DLL .\Debug\GLUT32d.PDB .\Debug\GLUTd.DLL .\Debug\GLUTd.PDB Some examples are in order ... ... build all dynamic-link libs using MSVCRT.DLL for C runtime: nmake /f nmake.mak USE_CRTDLL=1 alldynamic ... To build all library variants and all test and demonstration programs with the default settings you do this: nmake /f nmake.mak all ... to build all static link libs and nothing else you do this: nmake /f nmake.mak allstatic ... to build all non-accelerated dynamic link libs you do this: nmake /f nmake.mak alldynamic ... to build all 3Dfx targeted dynamic link libs you do this: nmake /f nmake.mak allaccel ... to build all S3 Virge targetd dynamic link libs you do this: nmake /f nmake.mak alls3 ... to build all libraries, static and dynamic, in all versions you do this: nmake /f nmake.mak libfiles ... to subsequently build all demo and test programs you do this: nmake /f nmake.mak progs ... to cleanup all intermediate files you do this: nmake /f clean You get the picture. (I hope) ;^) You may also specify specify single targets in a convenient fashion. The rule is simple, any of the above named lib files, static or dynamic, may be built by providing it's name on the command line as the target. Examples: ... to build only Mesa as OpenGL32.DLL ... nmake /f nmake.mak opengl32 ... to build only Mesa on top of the 3Dfx Glide API ... nmake /f nmake.mak fxMesaGL32 nmake /f nmake.mak fxMesaGL ... to build only Mesa on top of the S3 Toolkit ... nmake /f nmake.mak s3MesaGL32 nmake /f nmake.mak s3mesaGL *** Revision history for ./win32 project files 1/18/98 - initial cut submitted and included with core mesa 2/5/98 - fixed internal dependency within nmake.mif upon there being a $(DEVDIR) variable to make some temporary batch files dependant upon (thanks to Keven T. McDonnell for finding that there was this particular bug). I also updated the build files for 2.6beta6. 2/8/98 - added DevStudio workspace and project files for all lib files and some test programs. Updated readme.win32. 6/25/98 - initial revision for Mesa 3.0, does not include IDE files, not everything is running. *sigh* 7/20/98 - Mesa 3.0beta6 rev of all build files, all libs built and minimally tested, all demo programs built and minimally tested to within limits of my PC. ;^) Eveything looks MUCH better now ... 7/30/98 - Minor updates/edits based upon feedback from Eero Pajarre . These updates include a fix to the Mesa-on-3Dfx build such that Quake-II now runs almost properly on my system. It runs, just *very* slowly and with *no* textures. Hmmm. Doesn't make any difference whether Quake is set to use 8-bit textures or not. 8/13/98 - Lots of build cleanups, minor bug fixes in fxwgl.c, and compatability fix in fxapi.c for in-window rendering using 3Dfx hardware. 8/26/98 - Final revisions for Mesa 3 release checked 9/22/98 - Fixed static builds for all but fxMesaGL32 and s3MesaGL32 targets 9/29/98 - Reorganized FAQ information and added Added faq entry about Glide bug under NT (crash on exit) and a workaround. 11/21/98 - Updated files for Mesa 3.1 beta 1 Updated fxMesa window-hack code Updated fxMesa resolution support to handle 1600x1200 & 1280x1024 7/9/99 - Rev'd for Mesa 3.1 beta 2