docs/README.WIN32

   1
   2     Mesa/Readme.win32
   3
   4     Last Updated: Sun, Dec 06 1998, 08:49 EST - tjump@spgs.com
   5
   6     Note: While this build set supports generation of a 3Dfx specific
   7           DLL using Mesa, David Bucciarelli's original build files
   8           are the "supported" method. -Ted
   9
  10 *** What's New
  11
  12 - Build environment change: The Glide SDK is no longer assumed to be in
  13   the global INCLUDE/LIB environment vars, it is required that you set the
  14   value 'GLIDE2X' as either an environment variable pointing to your Glide
  15   SDK install directory or that you configure that as a build option to
  16   nmake.exe when building fxmesagl32.  Examples:
  17
  18     nmake /f nmake.mak GLIDE2X=g:\sdk\glide2x fxmesagl32
  19
  20           <or>
  21
  22     nmake /f nmake.mak GLIDE2X=g:\sdk\glide2x allfx
  23
  24           <or>
  25
  26     nmake /f nmake.mak GLIDE2X=g:\sdk\glide2x progs.3dfx.demos
  27
  28   The DevStudio workspace files for 3Dfx OpenGL require the definition of
  29   GLIDE2SDK as an environment variable pointing to where your copy of the
  30   Glide SDK has been installed. Adding this to your AUTOEXEC.BAT would do
  31   so (change the directories to match):
  32
  33        SET GLIDE2SDK=G:\SDK\GLIDE2X
  34
  35 - Static build/link of all non-3Dfx targets works now, cool. Required some
  36   nontrivial chicanery in the GLUT headers though to allow it to use the
  37   mesa 'wgl' functions statically linked instead of always importing the
  38   sytem wgl functions from GDI32. Mostly this was an extension of an
  39   existing method used in the headers, just taking into account more
  40   functions.
  41
  42 - Handled an undocumented change in how Microsoft NMAKE for DevStudio 6
  43   defines _NMAKE_VER so that the makefiles should work properly.
  44
  45 - Microsoft Compiler/Win32 specific build tuneups in the header files
  46   providing for dramatically faster compilation times of mesa itself and of
  47   code using Mesa. Primarily via the removal of any call sequence which
  48   would invoke WINDOWS.H (which triggers ~6-10K lines of code inclusion).
  49
  50   Supporting this, a macro name change was made in the gl.h/glu.h/glut.h
  51   header files which should be client-code transparent. The change was to
  52   specify function prototypes with the (newly created) macro GLAPI instead
  53   of WINGDIAPI to ease conflicts with multiple definitions of WINGDIAPI
  54   (needs to be one thing to access Win32 API calls, another to define
  55   export funcs when building a Mesa/GLU/GLUT DLL which themselves need to
  56   import functions from Win32, etc.).
  57
  58   Similarly, call sequence definition usage of APIENTRY, CALLBACK, and
  59   WINAPI were renamed to prevent collision/need for windows.h.
  60
  61   Lastly, these changes were incorporated into the GLUT source to
  62   facilitate same compile-time performance increases.
  63
  64   All of these changes should be transparent to code USING
  65   mesa/mesaglu/glut, and in most cases did not require changes in their
  66   source files within the Mesa/GLUT code base (but there were a few).
  67
  68 - 'wgl' function prototypes and supporting data types declared in gl/gl.h
  69   to provide for the usage of these from client Windows code without
  70   requiring WINDOWS.H to be included. If you're using non-trivial functions
  71   (such as any that pass structures around) you will need to include
  72   WINDOWS.H *before* gl/gl.h, however in that case you needed them anyway.
  73
  74   One benefit of this is that glut-based code on Windows may now use
  75   wglGetProcAddress to get the function pointers for all supported OpenGL
  76   extensions, preventing the need for directly importing them into
  77   code. The 3Dfx/Demos/glbpaltx.c has been modified to use this mechanism
  78   by way of example.
  79
  80   This code has also been copied into gl/glut.h to support glut programs on
  81   Windows that do not use Mesa.
  82
  83 - new command line build target: all.debug
  84
  85   Builds all DLL files and test programs in release, then debug builds,
  86   emplacing the requried DLL files in the EXE directories for ready test
  87   runs.
  88
  89 - Expanded MESA_WGL_FX options. When setting it to instruct fxMesa to
  90   render windowed you may provide it a clue to your system's display, or
  91   instruct it to try to detect the pixel format. This information is used
  92   in constructing the windowed-rendering hack to try for optimal
  93   performance, such as it is. You specify this by adding one of the
  94   following tags in the envvar prefixed by a colon.
  95
  96     noconv    - does not do any pixel format conversion
  97                 This is synonymous to '16bgr'.
  98     16bgr     - uses a 16-bit RGB sequenced dib section and does no pixel
  99                 format conversion as this is the internal format of the
 100                 3Dfx hardware when used by fxMesa.
 101                 This is synonymous to 'noconv'.
 102     16rgb     - uses a 16-bit RGB sequenced dib section and does pixel
 103                 format conversion each frame from the 3Dfx internal format
 104                 to 5:6:5 RGB.
 105     15rgb     - uses a 16-bit RGB sequenced dib section and does pixel
 106                 format conversion each frame from the 3Dfx internal format
 107                 to 5:5:5 RGB.
 108     15bgr     - uses a 16-bit RGB sequenced dib section and does pixel
 109                 format conversion each frame from the 3Dfx internal format
 110                 to 5:5:5 RGB.
 111     24rgb     - uses a 24-bit RGB sequenced dib section and does pixel
 112                 format conversion each frame from the 3Dfx internal format
 113                 to 8:8:8 RGB. Also suitable for a 32-bpp display.
 114     24bgr     - uses a 24-bit BGR sequenced dib section and does pixel
 115                 format conversion each frame from the 3Dfx internal format
 116                 to 8:8:8 RGB. Also suitable for a 32-bpp display.
 117     query     - Queries Windows for the displays pixel format and attempts
 118                 to adjust accordingly. This query is done by using
 119                 DirectDraw to allocate a "Primary" surface and then
 120                 checking what that surface's pixel format is (as the Win32
 121                 API for getting the pixel format from a window device or
 122                 screen device context is useless as far as I have been able
 123                 to determine).  This does *NOT* mean that fxMesa is now
 124                 requiring DDraw, however it will use it if found. This
 125                 prevents system incompatabilities with WinNT 4SP2 and
 126                 earlier systems.
 127
 128     Example, put this in your AUTOEXEC.BAT to have fxMesa detect a best
 129     case match on context creation:
 130
 131          set MESA_WGL_FX=windowed:query
 132
 133     Additionally, if you wish to find out *what* it detected, you may add a
 134     ":logged" to this which will cause it to create/append to a file named
 135     FXMESAGL32.LOG whenever a context is created, e.g.:
 136
 137          set MESA_WGL_FX=windowed:query:logged
 138
 139     *** WARNING: Some display drivers/windows version combinations do not
 140         support all of the possible DIB section formats that can be
 141         requested, and thanks to Microsoft there is no way of detecting
 142         (that I have yet discovered) that the requested DIB section will
 143         not work and when it is utilized the application crashes.
 144
 145   Eventually I hope to incorporate support for DirectDraw Overlay surfaces
 146   to facilitate less data crunch overhead when dealing with the in-window
 147   hack. For example: if a primary display support overlays of BGR565
 148   sequence then the data could be read from the 3Dfx framebuffer into a
 149   DDraw "System Memory" or "Non-Local Video Memory" surface - both of which
 150   actually reside in on-board DRAM (the latter in AGP space) which could
 151   then be blitted/flipped in a much faster fashion than the current DIB
 152   section handling.
 153
 154   The DIB section handling will always be the default, as that's much more
 155   compatible since it utilizes GDI features sets that have more longevity
 156   to them.
 157
 158 *** Legalese
 159
 160 These build files are provided as-is and are submitted to be included with
 161 the "Mesa 3-D Graphics Library" package as (currently) maintained by Brian
 162 Paul. These project build files are free software; you can redistribute it
 163 and/or modify it under the terms of the GNU Library General Public License
 164 as published by the Free Software Foundation; either version 2 of the
 165 License, or (at your option) any later version.
 166
 167 These project files are distributed in the hope that they will be useful,
 168 but WITHOUT ANY WARRANTY; without even the implied warranty of
 169 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library
 170 General Public License for more details.
 171
 172 You should have received a copy of the GNU Library General Public License
 173 along with this library; if not, write to the Free Software Foundation,
 174 Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 175
 176 *** Maintenance Responsiblity and Technical Support
 177
 178 While these files are now part of the Mesa core distribution please do NOT
 179 contact Mr. Paul for help with them if you encounter problems as he can't
 180 help you (currently).  I will, however, attempt my straightforward best in
 181 assisting anyone with using these files on their system.  I can NOT
 182 guarantee instant responses owing to other responsiblities, but I do try
 183 dang hard to answer any mail w/in 24 hours.  I may be contacted at the
 184 above email address for the forseeable future.
 185
 186 -Ted
 187 mailto://tjump@spgs.com
 188 http://www.i21.com/~tjump
 189
 190 *** General Information
 191
 192 These build files facilitate convenient building of many variants of Mesa,
 193 both as static link libraries (including mesaglu) and as dynamic link
 194 libraries that in some cases may be used as "drop-in" replacements for
 195 OpenGL32.DLL on both Windows95 and Windows NT.
 196
 197 The construction of the Win32 command-line build files and projects has
 198 been something of a pet project of mine, and is based upon my own
 199 "standard" Win32 build environment as supplied by the "nmake.mif" file.
 200 They have been tested under Windows95 OSR2, Windows NT 4.0SP3, and Windows
 201 NT 5.0 beta 1.  The libraries that they generated have been tested (via the
 202 demo programs) in a *limited* fashion on the above three systems, including
 203 the 3Dfx versions.
 204
 205 The reason I went with command-line build environment instead of the more
 206 convenient IDE-based project files is for two reasons: 1. These appear to
 207 have some amount of portability between versions (the nmake syntax hasn't
 208 changed much since Microsoft C 7.0) while the IDE project files seem to
 209 change drastically each version. and 2. These are readable with any ascii
 210 editor and such are better self-documentation of the file relationships for
 211 more people such that it will facilitate supporting other Win32 compilers.
 212
 213 While these files only deal with building for x86 targeted code it *should*
 214 be possible to add the necessary logic to them to build for the other MSVC
 215 supported CPU targets, I simply have no hardware to test them on nor the
 216 alternative compilers to build with.
 217
 218 *** Prerequisites for use
 219
 220 1. You must have a 32-bit Microsoft compiler installed. I have tested
 221 this with Visual C 5.0 (SP3) and Visual C 4.2, but with minor
 222 (possibly no) modification to the nmake.mak and nmake.mif files this
 223 sequence should work on Visual C 2.0 also. The workspace files
 224 (mesalib.dsw and mesademos-*.dsw) and their included project files
 225 (*.dsp) are specific to the DevStudio IDE - I have made no attempt at
 226 building a VC4 IDE project set as I do not use that any more.  Note
 227 that the VC workspace files NO LONGER use NORE are dependant upon the
 228 nmake.mak and nmake.mif files for construction of definition (*.DEF)
 229 and resource (*.RC) files.
 230
 231 *** Visual C 4.x Users Warning ****
 232
 233 Note that early editions of VC4 do NOT have header files current enough
 234 for use building this code base. If you are using VC4 you will either need
 235 to get an update to version 4.2 *or* you may download the Platform SDK
 236 directly from Microsoft's web site (www.microsoft.com) and update your
 237 build environment that way.
 238
 239 *** Visual C 4.x Users Warning ****
 240
 241 2. You must have the PATH, INCLUDE, and LIB environment variables set
 242 properly. With VC5 you can easily get this by executing the VCVARS32.BAT
 243 file that was created for you upon installation. It is found in the
 244 DevStudio\VC\BIN directory, wherever you installed DevStudio. VC4 provides
 245 a similar batch file in it's BIN directory also.
 246
 247 3. (optional) If you're going to build for 3Dfx/Voodoo you will need to
 248 have previously installed the Glide SDK version 2.3 or later, if I
 249 recall. This may be retrieved from www.3dfx.com for no money and some
 250 download time. ;-) These build files assume that you have the Glide SDK
 251 added to the respective environment variables (LIB and INCLUDE).
 252
 253 4. (optional) If you're going to build for S3/Virge you will need the S3
 254 Developers Toolkit which may be downloaded from www.s3.com for the price of
 255 registering on-line and some time. NOTE: I can build the s3mesa.dll file to
 256 completion, however the compilation of s3mesa.c currently generates a large
 257 amount of compiler warnings and between that and the fact that I can not at
 258 all test it I can make no claims to it's ability to execute.  Again, like
 259 the 3Dfx version before this, these build files assume you have the S3Dtk H
 260 and LIB files in the path of their respective environment variables.
 261 Note 2: As of Mesa3.0beta6 I have build files, both command-line and IDE,
 262 which should be able to build the s3mesa code base if it weren't for updates
 263 being required in the S3 DD code support (Mesa-3.0/src/s3 directory).
 264
 265 I advise putting any include and lib files for secondary toolkits (Glide,
 266 S3Tk, whatever) in their respective environment variables *before* the
 267 Microsoft-assigned default values.
 268
 269 *** FAQ: Frequenty Asked Questions and Other Important Information ***
 270
 271 - When running the 3Dfx demos under Windows NT, they crash on exit, what's
 272   up?
 273
 274   This is apparently a problem in Glide itself. The workaround is to go to
 275   your C:\WINNT\SYSTEM32 directory and rename the file FXOEM2X.DLL to
 276   FXOEM2X.DL_ to prevent Glide from loading and initializing it upon
 277   startup.  This is known to be an issue with cards that do not have "TV
 278   out" and is known to cause crashes on Diamond Monster II 8M and 3Dfx
 279   Reference boards, all using 3Dfx Reference Drivers version 2.53. Other
 280   hardware/driver combinations will also likely exhibit this behavior.
 281
 282 - I'm having a problem building Mesa for static library linking.
 283
 284   This was caused by some incomplete testing on my part, and a fix is now
 285   available in the form of an add-on to the base Mesa 3.0 release.  The
 286   file to get is:
 287
 288        via FTP download from: iris.ssec.wisc.edu
 289          you want to go here: /pub/Mesa/patches_to_3.0/
 290         you want to get file: Mesa-3.0-w32-static-fixes.tar.gz
 291
 292   This required a minor addition to INCLUDE/GL for a clean solution, the
 293   file "include/gl/mesa_wgl.h" is automatically included by
 294   "include/gl/gl.h" when a Win32 non-DLL build is in progress to provide
 295   prototypes for the various wgl functions.
 296
 297   The only remaining hitch in this setup is that the 3Dfx build is not yet
 298   running as a static build, because of problems with conflicts in
 299   existance of the various GDI functions like ChoosePixelFormat,
 300   etc. *sigh*
 301
 302   Anyway, the "allstatic" target now works as expected and builds all
 303   book/sample/demos programs to boot. ;^)
 304
 305 - How do I get fxMesa to render in a window on the desktop instead of only
 306   full-screen?
 307
 308   Use the Microsoft Windows fxMesa-in-a-window hack!
 309
 310   Seriously, if you want fxMesaGL to render using the 3Dfx Voodoo1 or
 311   Voodoo2 hardware into a window on the desktop then all you need to do is
 312   set the MESA_WGL_FX environment variable to anything other than
 313   "fullscreen" and it will render into a window.  If you wish to go
 314   fullscreen then you only need to NOT have the environment variable, or
 315   have it set to "fullscreen".  You may also switch at runtime between
 316   fullscreen-mode and windowed by pressing ALT-ENTER on the keyboard
 317   (unless the application using Mesa does something with those keystrokes,
 318   of course).
 319
 320   As of 8/13/98 this should be running a LOT better for more people as a
 321   low-compatability item was cleaned up which prevented it from working on
 322   many (most?) display drivers under Windows 9x.
 323
 324 - I have my 3Dfx card hooked to it's own monitor and I want the output to
 325   stay on even if I switch to another program, is this possible?
 326
 327   If the Glide environment variable SST_DUALHEAD is set to '1' then fxMesa
 328   will never disable the Voodoo output on a Voodoo1 or Voodoo2 display
 329   regardless of whether the fxMesa application is "current" or not. This
 330   works regardless of whether it's rendering using the window hack
 331   mentioned above or not.
 332
 333 - I want to run the Mesa demos on my Intel740 card using it's own OpenGL
 334   acceleration, how do I do this?
 335
 336   Build GLUT standalone for use with system OpenGL and GLU drivers!
 337
 338   The Command-line project supports building all test/demo programs against
 339   these drivers also! This allows you full use of GLUT on Windows using
 340   hardware accelerated OpenGL. Wheee! This includes the "3dfx/demos"
 341   directory of which only two programs will not run on "standard"
 342   opengl. Note that there are a few of the sample programs which will NOT
 343   work without Mesa as they directly call into Mesa instead of using the
 344   extension mechanism.
 345
 346 *** Included programs that exhibit unfortunate or bad behavior
 347
 348 - demos/bounce - doesn't run on high-colors screens?  It's requesting an
 349   INDEX display from GLUT and that fails on my true-color desktop. Changing
 350   this to _RGB let's the program work, but it doesn't display
 351   properly. This is probably just an idiosyncracy of my machine though, as
 352   if I test the program using GLUT for System OpenGL on my Intel740 OpenGL
 353   accelerated machine it's just hunky-dory.
 354
 355 - demos/glutfx - runs, but crashes on exit (but not on my Intel740 machine)
 356
 357 - demos/texobj - runs, but crashes on exit if ESC is pressed. Exits cleanly
 358   if the Close box on the window frame is pressed with the mouse. Go figure.
 359
 360 - book/aaindex - doesn't run, can't get pixel format, because it wants an
 361   INDEX display maybe (but is okay on my Intel740 machine)?
 362
 363 - most of the book/* demos don't respond to ESC being pressed.
 364
 365 - 3dfx/demos/* - all demos run, however they all crash on exit. I've traced
 366   this so far as to determine the call it's happening with. The crash comes
 367   from within Glide during the processing of the grGlideShutdown() call, as
 368   in invalid memory reference exception. I'm wondering if this is because
 369   of some state or processing not being completed before the call. Dunno,
 370   but putting grSstIdle() in just before grGlideShutdown() does NOT fix the
 371   problem.
 372
 373 - 3dfx/demos/tunnel2 - does not run on my system even with SLI mode
 374   disabled. Hmmmm, maybe I need to disconnect my Voodoo2 cards?
 375
 376 *** Important Notes and Changing Default values
 377
 378 - The optimizer settings have been manually reworked in both command line
 379   and DevStudio IDE files to hopefully prevent possible irrational code on
 380   the part of the code generator.  Formerly, it was configured for "/Ox",
 381   now it is configured for safer handling at a slight potential performance
 382   cost. This may not be required for Visual Studio 6 but I can't test that
 383   (yet).
 384
 385 - These files build with the code targeted for Pentium processors and
 386   8-byte structure padding.
 387
 388 - The IDE-built programs seem to be "happier" in that the command line
 389   build of the 3Dfx demo "fire" will grenade on exit (?). Otherwise pretty
 390   much everything may be built with either interface.
 391
 392 - The currently configured Mesa version is 3.1, and MesaDemos version is
 393   the same. To change this permanently you will need to edit NMAKE.MAK and
 394   change the lines that look like this (they start o/a line 116):
 395
 396     # Currently, Mesa is at rev 3.1 ...
 397     #
 398     !IF "$(MESAVER)" == ""
 399     MESAVER=3.1
 400     !ENDIF
 401
 402     # used in building all of the resource files for the Mesa DLLs
 403     #
 404     !IF "$(MESAFILEVER)" == ""
 405     MESAFILEVER=3,1,0,0
 406     !ENDIF
 407
 408 - Currently the build files are configured to be used from a Win32
 409   directory that is included inside the main Mesa-3.1 heirarchy.
 410
 411 - The build files are smart enough to find the files for the core lib, glu,
 412   glut, and the various demo programs if they are unpacked in the current
 413   Mesa-3.1 heirarchy, like this:
 414
 415     \Mesa-3.1
 416     \Mesa-3.1\src
 417     \Mesa-3.1\src-glu
 418     \Mesa-3.1\src-glut
 419     \Mesa-3.1\Win32
 420     \Mesa-3.1\samples
 421     \Mesa-3.1\demos
 422     \Mesa-3.1\book
 423     \Mesa-3.1\3Dfx\demos
 424
 425     ... should work.  This arose because my initial build tests for the
 426     demo files were done before MesaDemos 2.6 had been released.
 427
 428 - To enable use of MMX instructions by the VC5 compiler you may add the
 429   "USE_MMX=1" option to the NMAKE command line, or edit the default in the
 430   NMAKE.MAK file.  This does appear to have some affect on the performance
 431   on the library and does not seem to harm it in any way *but* I have done
 432   *no* verification of this. I have an MMX processor so I figured what the
 433   heck. This option is only available with VC5 when building from the
 434   command line.
 435
 436   This is probably required if you are going to modify the code to include
 437   inline MMX instructions though.
 438
 439 - With the exception of the static link libraries generated by this file
 440   set (mesagl.lib, mesaglu.lib, mesaglut.lib) all DLLs and executables are
 441   built against the "Multithreaded DLL" runtime - this means that they
 442   require MSVCRT.DLL or MSVCRTD.DLL in the path to execute.
 443
 444   ** CHANGED 8/11/98 ***
 445
 446   Note also that the demos are all built aginst the "OpenGL32, GLU32, and
 447   GLUT32" and as such they are fairly agnostic wrt: building against Mesa
 448   for CPU-rendering, Mesa-for-3Dfx, Mesa-for-S3, or System OpenGL.
 449
 450   If you want to build them for use on your system and your display card
 451   provides full OpenGL acceleration (Permedia, Intel740, Intergraph,
 452   whatever) then you only need to build GLUT prior to building any of the
 453   demo programs. For convenience, the GLUT project is included in each of
 454   the demo projects Workspace files for the DevStudio IDE builds BUT it is
 455   not automatically built - you still need to build it first manually.
 456
 457   Note that if you have GLUT already installed on your system (gl/glut.h in
 458   yoru INCLUDE path, glut32.lib/glut32d.lib in your LIB path, and the DLL
 459   in your PATH) then you do NOT need to build GLUT prior to the test
 460   programs.
 461
 462 - The 3Dfx build of Mesa has primarily been tested with Quake 2 and it runs
 463   (mostly) fine on my PC (take that for what you want it)...
 464
 465   ** CHANGED  8/11/98 ***
 466
 467   There is still something going on that causes Glide to crash on shutdown,
 468   when I run fxMesa under Windows NT, however it does not appear to occur
 469   under Windows 9x on either Voodoo1 or Voodoo2 cards. *sigh*
 470
 471 - I can not test the S3 build as I have no machines available with Virge
 472   based display cards.
 473
 474 - The multithreaded test code is *not* built as it requires pthreads and I
 475   have as of yet spent not time trying to get that running. The latest word
 476   that I saw WRT threading support on win32 was that they are intending to
 477   support it natively within Win32 - so I'm waiting it out until they get
 478   it done.
 479
 480 - Similarly, the 'xdemos' are not currently built because I haven't gotten
 481   around to building the client libs for native win32 and getting it all
 482   setup for use.
 483
 484 *** Output Files
 485
 486 All final output files (DLL/LIB) are placed in the Mesa-3.1/lib directory,
 487 with the exception of the fxMesaGL32 build which is placed in
 488 Mesa-3./lib/FX and the executable images which are placed in their source
 489 directories.
 490
 491 To be able to execute the various test programs, you will need to copy the
 492 requisite DLL files into the same directory as the EXE files. Note that
 493 most of the 3Dfx/demos/* programs WILL run with the non-FX build of Mesa -
 494 just very slowly. The two programs which are hard-linked with the FX build
 495 and will not run without it are "glbpaltx" which uses "gl3DfxSetPaletteEXT"
 496 directly instead of via the extensions mechanism and "tunnel2" which uses
 497 "fxMesaSelectCurrentBoard" API for selecting between multiple 3Dfx cards
 498 installed in one system. Likewise, "paltex" directly uses the
 499 "glColorTableEXT" extension and thus may not run on anything except
 500 Mesa. If these applications used the proper extension mechanism they could
 501 then be used on more than "just" fxMesa to good effect (for example, the
 502 rest of the "3Dfx/demos" run just peachy on the Intel740 card in my test
 503 machine) under WinNT.
 504
 505 Because I'm anal about my computer and it's organization, and I like to
 506 prevent collision between builds, each of the subprojects has their own
 507 intermediate file directory inside .\win32\release (for example, when
 508 building mesagl.lib all of it's intermediate files will be found in
 509 .\win32\release\lib.mesagl).  This makes it very easy to cleanup as you
 510 only need to remove .\win32\release.
 511
 512 *** Okay, Enough, how do I build with this stuff already Ted!
 513
 514 Okay, no major calamity here. The basic way to use the project file is to
 515 call it via NMAKE from the command line. The format is:
 516
 517     nmake[.exe] /f nmake.mak [options] [target]
 518
 519 The most likely [options] values you will use may be any combination of the
 520 following:
 521
 522     DEBUG=1 or DEBUG=0
 523     USE_MMX=1 or USE_MMX=0
 524     USE_CRTDLL=1 or USE_CRTDLL=0
 525
 526     Note that all three of these options are OFF by default.
 527
 528 The [target] includes but is not limited to the following (for full details
 529 please peruse the NMAKE.MAK and NMAKE.MIF files - but be warned that
 530 NMAKE.MIF is rather large and sometimes hard to follow):
 531
 532     --- convenience targets ---
 533
 534     all                 - builds everything
 535     libfiles            - builds all linking library files
 536     progs               - builds all executable images
 537
 538     --- library files, static and dynamic ---
 539
 540     mesagl              - static lib build of Mesa core.
 541     mesaglu             - static lib build of MesaGLU core.
 542     mesaglut            - static lib build of Mesa GLUT core.
 543
 544     mesagl32            - dynamic lib build of Mesa core.
 545
 546     mesaglu32           - dynamic lib build of GLU core, generates
 547                           GLU32.DLL and/or GLU32d.DLL.
 548
 549     mesaglut32          - dynamic lib build of GLUT core, generates
 550                           GLUT32.DLL and/or GLUT32d.dll.
 551
 552     --- hardware accelerated mesa builds ---
 553
 554     fxmesagl32          - builds Mesa for use on top of the 3Dfx
 555                           Glide runtime libs
 556
 557     s3mesagl32          - builds mesa for use on top of the S3
 558                           'S3Tk' runtime libs.
 559
 560     --- executable images ---
 561
 562     progs.book          - builds all programs in \book directory
 563     progs.demos         - builds all programs in \demos directory
 564     progs.samples       - builds all programs in \samples directory
 565
 566         These targets generate all of the programs in their respective
 567         directories and link the executables against OpenGL32.DLL,
 568         GLU32.DLL, and GLUT32.DLL (or their debug equivalents).
 569
 570     progs.3dfx.demos    - builds all programs in \3dfx\demos directory
 571
 572         This target generates the 3Dfx/Demo executables, linking them
 573         against GLUT32.DLL, GLU32.DLL, OPENGL32.DLL and are thus NOT
 574         hard-bound to using Mesa per-se as you can simply NOT build the
 575         Mesa core and GLU libraries.
 576
 577    --- Microsoft/SGI OpenGL-based GLUT and Demo program builds ----
 578
 579    *** IMPORTANT SAFETY TIP: If you're going to build these variants of
 580        GLUT then DO NOT build any other target libraries in this package
 581        first, OR from the command line run the "nmake /f nmake.mak clean"
 582        command first!  This is because generation of the GLUT for SGI
 583        OpenGL target libraries conflicts in naming with the static build
 584        libraries of Mesa and it's supporting GLUT build.
 585
 586    Currently, you may build GLUT as either GLUT32.DLL or GLUT.DLL for
 587    use running against either Microsoft or SGI OpenGL for Window,
 588    respectively.  This allows for the general use of GLUT 3.7 on Windows
 589    systems with fully compliant OpenGL.
 590
 591    You can build the GLUT DLL files either with the command line by
 592    issuing either of these commands:
 593
 594         nmake /f nmake.mak glut.sysgl
 595
 596         <or>
 597
 598         nmake /f nmake.mak glut.sgigl
 599
 600    OR by using the DevStudio MesaLib Worksapce build the GLUT_SGIGL or
 601    GLUT_SYSGL projects within the DevStudio IDE.
 602
 603    Unfortunately, the only way to build the test programs against this
 604    build of GLUT is via the command line, and I will NOT be making
 605    duplicate demo program projects for the IDE as it's just not worth it,
 606    sorry.
 607
 608    To build the test programs against either MS or SGI OpenGL, you do so
 609    via either of these two commands:
 610
 611         nmake /f nmake.mak progs.sysgl
 612
 613         <or>
 614
 615         nmake /f nmake.mak progs.sgigl
 616
 617    To use the GLUT-for-system-OpenGL in your own programs, you need to do
 618    three things by way of preparation, after building GLUT of course:
 619
 620          1. Copy include\gl\glut.h to somewhere in your %INCLUDE% path, one
 621             likely candidate location would be in your
 622             "DevStudio\VC\INCLUDE\GL" directory.
 623
 624          2. Copy the linking libraries to somewhere in your %LIB% path, one
 625             likely candidate location would be in your "DevStudio\VC\LIB"
 626             directory. The linking libraries you need to copy are as
 627             follows:
 628
 629                 .\Release\GLUT32.LIB
 630                 .\Release\GLUT.LIB
 631                 .\Debug\GLUT32.LIB
 632                 .\Debug\GLUT.LIB
 633
 634         3. Copy the runtime libraries to somewhere in your %PATH%, one
 635            likely candidate location would be in WINDOWS\SYSTEM. the files
 636            that you should copy are as follows:
 637
 638                 .\Release\GLUT32.DLL
 639                 .\Release\GLUT32.PDB
 640                 .\Release\GLUT.DLL
 641                 .\Release\GLUT.PDB
 642                 .\Debug\GLUT32d.DLL
 643                 .\Debug\GLUT32d.PDB
 644                 .\Debug\GLUTd.DLL
 645                 .\Debug\GLUTd.PDB
 646
 647 Some examples are in order ...
 648
 649     ... build all dynamic-link libs using MSVCRT.DLL for C runtime:
 650
 651         nmake /f nmake.mak USE_CRTDLL=1 alldynamic
 652
 653     ... To build all library variants and all test and demonstration
 654         programs with the default settings you do this:
 655
 656         nmake /f nmake.mak all
 657
 658     ... to build all static link libs and nothing else you do this:
 659
 660         nmake /f nmake.mak allstatic
 661
 662     ... to build all non-accelerated dynamic link libs you do this:
 663
 664         nmake /f nmake.mak alldynamic
 665
 666     ... to build all 3Dfx targeted dynamic link libs you do this:
 667
 668         nmake /f nmake.mak allaccel
 669
 670     ... to build all S3 Virge targetd dynamic link libs you do this:
 671
 672         nmake /f nmake.mak alls3
 673
 674     ... to build all libraries, static and dynamic, in all versions
 675         you do this:
 676
 677         nmake /f nmake.mak libfiles
 678
 679     ... to subsequently build all demo and test programs you do this:
 680
 681         nmake /f nmake.mak progs
 682
 683     ... to cleanup all intermediate files you do this:
 684
 685         nmake /f clean
 686
 687 You get the picture. (I hope) ;^)  You may also specify specify
 688 single targets in a convenient fashion. The rule is simple, any of the
 689 above named lib files, static or dynamic, may be built by providing it's
 690 name on the command line as the target. Examples:
 691
 692     ... to build only Mesa as OpenGL32.DLL ...
 693
 694         nmake /f nmake.mak opengl32
 695
 696     ... to build only Mesa on top of the 3Dfx Glide API ...
 697
 698         nmake /f nmake.mak fxMesaGL32
 699               <or>
 700         nmake /f nmake.mak fxMesaGL
 701
 702     ... to build only Mesa on top of the S3 Toolkit ...
 703
 704         nmake /f nmake.mak s3MesaGL32
 705               <or>
 706         nmake /f nmake.mak s3mesaGL
 707
 708 *** Revision history for ./win32 project files
 709
 710 1/18/98 - initial cut submitted and included with core mesa
 711 2/5/98  - fixed internal dependency within nmake.mif upon there being
 712           a $(DEVDIR) variable to make some temporary batch files
 713           dependant upon (thanks to Keven T. McDonnell for finding
 714           that there was this particular bug). I also updated the
 715           build files for 2.6beta6.
 716 2/8/98  - added DevStudio workspace and project files for all lib
 717           files and some test programs. Updated readme.win32.
 718 6/25/98 - initial revision for Mesa 3.0, does not include IDE files,
 719           not everything is running. *sigh*
 720 7/20/98 - Mesa 3.0beta6 rev of all build files, all libs built and
 721           minimally tested, all demo programs built and minimally
 722           tested to within limits of my PC. ;^) Eveything looks
 723           MUCH better now ...
 724 7/30/98 - Minor updates/edits based upon feedback from
 725           Eero Pajarre <epajarre@koti.tpo.fi>. These updates include a fix
 726           to the Mesa-on-3Dfx build such that Quake-II now runs almost
 727           properly on my system. It runs, just *very* slowly and with *no*
 728           textures. Hmmm. Doesn't make any difference whether Quake is set
 729           to use 8-bit textures or not.
 730 8/13/98 - Lots of build cleanups, minor bug fixes in fxwgl.c, and
 731           compatability fix in fxapi.c for in-window rendering using 3Dfx
 732           hardware.
 733 8/26/98 - Final revisions for Mesa 3 release checked
 734 9/22/98 - Fixed static builds for all but fxMesaGL32 and s3MesaGL32 targets
 735 9/29/98 - Reorganized FAQ information and added Added faq entry about Glide
 736           bug under NT (crash on exit) and a workaround.
 737 11/21/98 - Updated files for Mesa 3.1 beta 1
 738            Updated fxMesa window-hack code
 739            Updated fxMesa resolution support to handle 1600x1200 & 1280x1024