docs/README.WIN32

   1 File: docs/README.WIN32
   2
   3 Last updated: Mar 31, 2006 - Karl Schultz - kschultz@users.sourceforge.net
   4
   5 Quick Start
   6 ----- -----
   7
   8 Unzip the MesaLib, MesaGLUT, and MesaDemos ZIP files into the same
   9 directory.  The libs and demos build separately, so if you do not care
  10 about the demos or GLUT, you only need to unzip MesaLib.  If you unzip
  11 more than one ZIP file, they all need to be unzipped into the same
  12 directory.  Don't worry, you will not overwrite anything.
  13
  14 The Windows build system uses Microsoft Visual Studio.  Project files
  15 for a specific version of Visual Studio are in their own directory in
  16 the top-level "windows" directory.  For example, Visual Studio 6 files
  17 are in windows/VC6.  If a directory does not exist for your version of
  18 Visual Studio, you can try importing the project files from an earlier
  19 version of Visual Studio.  At this time, project files exist for
  20 Version 6 and Version 7.  The code has been built with a beta version
  21 of Version 8 and it runs on 64-bit Windows.  If you want to try this,
  22 start by importing the VC7 files and create the 64-bit targets in the
  23 configuration manager.
  24
  25 It is likely that the new and free Visual Studio Express can be used
  26 to build Mesa, but it hasn't been tried yet.  Start with the VC7
  27 project files.
  28
  29 The project files to build the core Mesa library, Windows Mesa
  30 drivers, OSMesa, and GLU are in the mesa directory.  The project files
  31 to build GLUT and some demo programs are in the progs directory.
  32
  33 Makefiles are no longer shipped or supported, but can be generated
  34 from the projects using Visual Studio.
  35
  36
  37 Windows Drivers
  38 ------- -------
  39
  40 At this time, only the GDI driver is known to work.  Most of the demos
  41 in progs/demos should work with this driver.
  42
  43 Source code also exists in the tree for other drivers in
  44 src/mesa/drivers/windows, but the status of this code is unknown.
  45
  46 The GDI driver operates basically by writing pixel spans into a DIB
  47 section and then blitting the DIB to the window.  The driver was
  48 recently cleaned up and rewitten and so may have bugs or may be
  49 missing some functionality.  The older versions of the CVS source may
  50 be useful in figuring out any problems, or report them to me.
  51
  52 To build Mesa with the GDI driver, build the mesa, gdi, and glu
  53 projects in the Visual Studio workspace found at
  54
  55         windows/VC6/mesa/mesa.dsw
  56 or
  57         windows/VC7/mesa/mesa.sln
  58
  59 The osmesa DLL can also be built with the osmesa project.
  60
  61 The build system creates a lib top-level directory and copies
  62 resulting LIB and DLL files to this lib directory.  The files are:
  63
  64         OPENGL32.LIB, GLU32.LIB, OSMESA32.LIB
  65         OPENGL32.DLL, GLU32.DLL, OSMESA32.DLL
  66
  67 If the MesaDemos ZIP file was extracted, the DLL files are also copied
  68 to the demos directory.  This facilitates running the demos as described
  69 below.
  70
  71
  72 GLUT and Demos
  73 ---- --- -----
  74
  75 A Visual Studio workspace can be found at
  76
  77         windows/VC6/progs/progs.dsw
  78 or
  79         windows/VC7/progs/progs.sln
  80
  81 It can be used to build GLUT and a few demos.  The GLUT lib and DLL
  82 are copied to the top-level lib directory, along with the Mesa libs.
  83
  84 The demo build system expects to find the LIB files in the top level
  85 lib directory, so you must build the Mesa libs first.  The demo
  86 executables are placed in the demos directory, because some of them
  87 rely on data files found there.  Also, the Mesa lib DLL's were copied
  88 there by the Mesa lib build process.  Therefore, you should be able to
  89 simply run the demo executables from the demo directory.
  90
  91 If you want to run the demos from the Visual Studio, you may have to
  92 change the startup directory and explicitly state where the executables are.
  93
  94 You may also build all the demo programs by using a makefile.  Go to
  95 the progs/demos directory and make sure you have executed VCVARS32.BAT
  96 or whatever setup script is appropriate for your compiler.  Then,
  97
  98         nmake -f Makefile.win
  99
 100 should build all the demos.
 101
 102
 103 Build System Notes
 104 ----- ------ -----
 105
 106 VC6
 107 ---
 108
 109 Visual Studio 6 does not recognize files with the .cc extension as C++
 110 language files, without a lot of unnatural tweaking.  So, the VC6
 111 build process uses custom build steps to compile these files in the
 112 GLU library.
 113
 114 Two additional configurations are provided, Debug x86 and Release x86
 115 that activate the shader code compilation by defining SLANG_86.  It is
 116 unknown if and how this works.
 117
 118 VC7
 119 ---
 120
 121 The above-mentioned .cc problem does not exist in this version.
 122
 123
 124 General
 125 -------
 126
 127 After building, you can copy the above DLL files to a place in your
 128 PATH such as $SystemRoot/SYSTEM32.  If you don't like putting things
 129 in a system directory, place them in the same directory as the
 130 executable(s).  Be careful about accidentially overwriting files of
 131 the same name in the SYSTEM32 directory.
 132
 133 The DLL files are built so that the external entry points use the
 134 stdcall calling convention.
 135
 136 Static LIB files are not built.  The LIB files that are built with are
 137 the linker import files associated with the DLL files.
 138
 139 The si-glu sources are used to build the GLU libs.  This was done
 140 mainly to get the better tessellator code.
 141
 142 To build "mangled" Mesa, add the preprocessor define USE_MGL_NAMESPACE
 143 to the project settings.  You will also need to edit src/mesa.def to
 144 change all the gl* symbols to mgl*.  Because this is easy to do with a
 145 global replace operation in a text editor, no additional mangled
 146 version of mesa.def is maintained or shipped.
 147
 148 If you have a Windows-related build problem or question, it is
 149 probably better to direct it to me (kschultz@users.sourceforge.net),
 150 rather than directly to the other Mesa developers.  I will help you as
 151 much as I can.  I also monitor the Mesa mailing lists and will answer
 152 questions in this area there as well.
 153
 154
 155 Karl Schultz