1/** \file mainpage.foo 2 * This file only contains the information useful for the main page of the 3 * documentation - There is no code here. 4 */ 5 6 7/** \mainpage AllegroGL 8 9\section contents Table Of Contents: 10<ul><li> \ref aboutlib </li> 11 <li> \ref license </li> 12 <li> \ref aboutdoc </li> 13 <li> \ref genbuild </li> 14 <li> \ref require </li> 15 <li> \ref install </li> 16 <ul><li> \ref unixinst </li> 17 <li> \ref minginst </li> 18 <li> \ref msvcinst </li> 19 <li> \ref dosinst </li> 20 <li> \ref macinst </li> 21 </ul> 22 <li> \ref usagedocs </li> 23 <li> \ref moreinfo </li> 24 <li> \ref end </li> 25</ul> 26 27 28\section aboutlib About AllegroGL 29 30The library mostly provides functions to allow you to use OpenGL alongside 31Allegro -- you use OpenGL for your rendering to the screen, and Allegro for 32miscellaneous tasks like gathering input, doing timers, getting cross-platform 33portability, loading data, and drawing your textures. So this library fills 34the same hole that things like glut do. 35 36AllegroGL also automatically exposes most, if not all, OpenGL extensions 37available to user programs. This means you no longer have to manually load 38them; extension management is already done for you. 39 40\section license License 41 42The code is (C) AllegroGL contributors, and double licensed under the GPL and 43zlib licenses. See gpl.txt or zlib.txt for details. (You can pick whichever one 44you prefer.) 45 46\section aboutdoc About this document 47 48This document contains installation instructions, description of 49the API, reference manual, and pointers to other resources such 50as the FAQ, web page and the mailing list. 51 52 53\section genbuild General build instructions 54 55From version 0.4.4 onwards, AllegroGL is an addon library for Allegro and the 56usual way to build it is by following the allegro compilation procedure. It 57will configure, build and install AllegroGL using default options (a shared 58release library). 59 60However, you if you need a custom compiled library, e.g. with debug symbols or 61a statically linked one, you can build AllegroGL manually, passing custom build 62options. 63 64 65\section require Requirements 66 67 General requirement: If you are building AllegroGL separatelly (outside Allegro 68 compilation procedure) it will depend on Allegro being successfully built two 69 directories above. 70 71 \b Unix: 72 You need an X server which provides the OpenGL/GLX functionality. 73 If you have successfully installed 3D drivers (NVidia, DRI drivers, ...) 74 then OpenGL/GLX libraries are already installed. 75 Otherwise XFree86 4.x has OpenGL/GLX built in. We have also successfully 76 used an earlier version, with development snapshots of Mesa3D 3.2 and 77 GLX extensions. 78 79 You also need to get the GLU library, preferably the SGI's one (see the 80 Mesa sourceforge webpage - http://Mesa3D.sf.net/ ). 81 82 If you want to build the generic driver you need Mesa 4.0 or higher 83 (only the "MesaLib" archive is mandatory, the "MesaDemos" one is 84 optionnal). 85 86 Links to the relevant sites can be found on the AllegroGL web site. 87 88 \b Windows/MSVC: 89 MSVC6 or MSVC2005 IDE 90 or 91 GNU make is required for MSVC. 92 93 \b Windows/Mingw: 94 If you use Mingw, you'll need the OpenGL header files and 95 libraries. These are normally included with Mingw. 96 97 In case your copy of Mingw does not have the OpenGL headers, 98 you can grab them here: 99 ftp://ftp.microsoft.com/softlib/mslfiles/opengl95.exe 100 This is a self-extracting archive. 101 102 You'll also need GNU make (mingw32-make) to compile AllegroGL. 103 104 \b DOS: 105 You need DJGPP and Mesa 4.0 http://Mesa3D.sf.net/ for OpenGL rendering 106 (only the "MesaLib" archive is mandatory, the "MesaDemos" one is 107 optionnal). 108 109 \b Mac OS X: 110 System version 10.1.x or newer is required to build AllegroGL. 111 Allegro WIP 4.1.11 or newer is also required, as older versions 112 did not support OS X. 113 114 115 116\section install Installation 117 118 \subsection unixinst Unix instructions 119 120For an optimised build, run `./configure' and `make' from the directory 121containing this file. This will build the library (in 'lib/unix/') and the 122examples (in 'examp/'). Use `make install' to install the library and 123header file. For that part you need write access to /usr/local. 124 125If you want to build the generic driver, run `./configure --enable-generic' 126and `make MESADIR=xxx' where xxx is the path to the Mesa 4.0 directory. 127This will build both Mesa (GL and GLU) and AllegroGL 128 129 130For a debug build, add `DEBUGMODE=1' on each of the command lines. 131 132 133If you get errors about missing header files or libraries, 134either for X or GL, see the instructions at the top of 135`makefile'. Note that you need to have the X development 136package installed, if you are using Red Hat Linux or Debian 137GNU/Linux. 138 139 140 141 \subsection minginst Mingw/32 instructions 142 143Mingw 2.0 and higher already come with the OpenGL header files 144and libraries, so you can skip the next step. 145 146If you don't have the OpenGL header files (GL\\gl.h) and libraries, you will 147first need to acquire thrm. These can be obtained from the Microsoft site, 148or from MSVC. 149 150If you obtained the self-extracting archive from the Microsoft site, then 151run it. Move the produced header files (*.h) into C:\\Mingw32\\include\\GL\\ 152(replace C:\\Mingw32 by wherever you happen to have installed Mingw). 153Ignore the other files, as they are only useful for MSVC. 154 155You need to set up your environment if you haven't done that already. 156Environment variable "PATH" should point to the "bin" directory of Mingw. 157You can check that by typing "gcc" in the console. It must display something 158like: "gcc: no input files". If it complains about a unknown command then type 159"set PATH=%PATH%;C:\Mingw32\bin" (replace C:\\Mingw32 by wherever you happen to 160have installed Mingw). 161Also, you need to set MINGDIR env. variable. It must point to Mingw instalation 162directory: "set MINGDIR=C:\Mingw32". You can check that with: "echo %MINGDIR%". 163 164You will need to run 'fix mingw32' in the AllegroGL directory 165to update makefile for Mingw32. 166Since both Allegro and AllegroGL have native Mingw support 167I am happy to say that you can build Allegro/AllegroGL programs 168entirely using free software. 169 170For an optimised build, run `make' from the directory containing 171this file. Use `make install' to install the library and header 172file. Some versions of Mingw come with `mingw32-make' instead of 173`make', so you may need to run that instead. 174 175For a debug build, do the same but write `DEBUGMODE=1' on each 176of the command lines; for example, 'make DEBUGMODE=1' and 177'make install DEBUGMODE=1'. 178 179Add 'STATICLINK=1' to the last two commands to build AllegroGL that can be 180linked to statically linked allegro. 181 182 183 \subsection msvcinst MSVC6/7/8 instructions 184 185There are two completely different ways of compiling AllegroGL using MSVC. You 186can use the old-fashion way decribed bellow (similar to building allegro, using 187a GNU makefile and a command line), or you can locate the project file for your 188MSVC version in "projects" directory and compile AllegroGL lib and examples with 189a few mouse clicks. You'll have to manually copy libs and headers to appropiate 190locations. 191You can choose between several build configuration, depending against which 192Allegro library you want AllegroGL to be linked to. These configurations are: 193<pre> 194 _____________________________________________________________ 195 | Configuration name | AGL lib name | Allegro lib name | 196 |-------------------------------------------------------------| 197 | Release | agl.lib | alleg.lib | 198 | DLL Release | agl.lib & agl.dll | alleg.lib | 199 | Static Release | agl_s.lib | alleg_s.lib | 200 | Static Release CRT | agl_s_crt.lib | alleg_s_crt.lib | 201 | Debug | agld.lib | alld.lib | 202 | Static Debug | agld_s.lib | alld_s.lib | 203 ------------------------------------------------------------- 204</pre> 205 206All configuration except "DLL Release" produce AllegroGL library that is 207statically linked to the executable. 208 209 210Instructione for compiling AllegroGL using command line follow. 211 212You must have a working copy of GNU Make (useful for 213building Allegro, anyway). This can be either DJGPP's or 214Mingw's (recommended). 215 216 \b Step \b 1: 217 218 The first thing you need to do is find `vcvars32.bat', 219 somewhere in your Visual Studio directories (most probably, 220 it's in 'vc98/bin'). Running this batch file will enable 221 the command line compiler for the current DOS session. If you 222 will use it often, or find that typing 223 'c:\\progra~1\\micros~2\\vc98\\bin\\vcvars32.bat' gets annoying after a 224 while, then (under Windows 9X) simply add that command to your 225 autoexec.bat** 226 227 Note: If at any stage, you get an "Out of Environment space" 228 message, then please see the Allegro FAQ for how to fix this. 229 230 231** The procedure is different for Windows ME and later. 232 If you're running Windows ME, you'll need to select "Run" off the 233 start menu, then type in "msconfig". Select the environment 234 tab. Add the lines inside vcvars32.bat in there by copy/pasting them. 235 Reboot your computer for the changes to take effect. 236 237 If you're running Windows 2000/XP (NT?), then open Control Pannel, 238 then the "System" applet, then the "Advanced" tab, and 239 finally the "Environment" button. Add the environment variables as 240 they are in vcvars32.bat. This has to be done manually (yes it's long 241 and painful, please redirect all flames to billg@microsoft.com) 242 You will need to log off and log back in for the changes to take effect. 243 244 245\b Step \b 2: 246 247 Much like making Allegro, to configure AllegroGL for your compiler please run 248 in the command prompt: 249 250 fix.bat msvc6 - for MSVC 6 and older 251 fix.bat msvc7 - for MSVC 7 (.NET) and 7.1 (.NET 2003) 252 fix.bat msvc8 - for MSVC 8 (.NET 2005) 253 254 Then type `make' to build the library in optimized mode, then `make install' 255 to install the library and header files in your MSVC directory. 256 257 For a debugging version, add `DEBUGMODE=1', to the last two command lines. 258 259 To link against a static runtime libraries, rather than the default dynamic 260 runtime libraries, add STATICRUNTIME=1, to the last two command lines. 261 262 To link aginst a static version of allegro, add STATICLINK=1, to the last 263 two command lines. 264 265 If you are using Mingw for GNU make, then you may need to run `mingw32-make' 266 instead of `make'. 267 268 \subsection dosinst Dos instructions 269 270Please note that DOS support is currently in experimental stages. 271 272Unzip the archive files MesaLib-4.0.zip wherever you want. 273Unzip AllegroGL 274 275Create the environment variable MESADIR which defines the Mesa sources path : 276 set MESADIR=xxx 277where 'xxx' is the path to the Mesa root directory 278 279Go to the root directory of AllegroGL type 'fix djgpp' (without 280quotes) followed by 'make'. The GL, GLU and AllegroGL libraries are built. 281Finally type 'make install' to install the library 282 283You're done! You can now use AllegroGL on DOS. Try the example demos... 284 285For a debug build, do the same but write `DEBUGMODE=1' on each 286of the command lines. 287 288Note that you can also build : 289- The GLUT library (based on AMesa, Allegro and Mesa). Type 'make glut' to build it 290 then 'make install-glut' to install it. 291- The Mesa samples to test both Mesa and GLUT (note that you need to download 292 the MesaDemos archive file to compile mesa samples). Type 'make mesa-samples' 293 (Please note that not all the sample programs will be built. Now, as 294 of Mesa 3.4.2, most demos are for GLUT which has not yet been completely 295 ported to AMesa/Allegro). 296 297 298 \subsection macinst Mac OS X instructions 299 300First you will need to run `./fix.sh macosx' in order to prepare the 301makefile for Mac OS X. Then `make' will build the library (in `lib/macosx') 302and the examples (in `examp/'). Use `sudo make install' to install the 303library and the header files; this step will require your system root 304password and will install into /usr/local. 305 306For a debug build, add `DEBUGMODE=1' on `make' and `make install' calls, 307for example, `make DEBUGMODE=1' and `sudo make install DEBUGMODE=1'. 308 309 310 311\section usagedocs Using AllegroGL 312 313A reference to the functions and macros available to user 314programs can be found by clicking on the links on top of this 315document, or online at the web site, and is 316also downloadable from there in various formats. 317 318The quick start guide and the FAQ are included in the 319distribution in the root directory. 320 321 322\section moreinfo More information 323 324 325web site: http://allegrogl.sourceforge.net/ 326 327 The web site has introductory information, system 328 requirements, downloads, and Allegro patches, along with an 329 online version of the reference manual. 330 331 332mailing list: allegrogl-general@lists.sourceforge.net 333 334 335 All the developers are on this mailing list, and most of the 336 discussion here is about future development and bug fixing. 337 General questions about using the library make a welcome 338 change from the hard work of development, so newcomers are 339 very welcome! If you're not subscribed to the list, make 340 this clear when you post, so that people can Cc: their 341 replies to you. 342 343 344 345\section end Closing Words 346 347Good luck... 348 349 350-- The AllegroGL team 351 */ 352