docs/README.WIN32

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