docs/README.WIN32

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