AllegroGL: mainpage.foo Source File

AllegroGL 0.4.4

- Main Page
- Related Pages
- Modules
- Files

- File List
- Globals

mainpage.foo
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
30 The library mostly provides functions to allow you to use OpenGL alongside
31 Allegro -- you use OpenGL for your rendering to the screen, and Allegro for
32 miscellaneous tasks like gathering input, doing timers, getting cross-platform
33 portability, loading data, and drawing your textures. So this library fills
34 the same hole that things like glut do.
35
36 AllegroGL also automatically exposes most, if not all, OpenGL extensions
37 available to user programs. This means you no longer have to manually load
38 them; extension management is already done for you.
39
40 \section license License
41
42 The code is (C) AllegroGL contributors, and double licensed under the GPL and
43 zlib licenses. See gpl.txt or zlib.txt for details. (You can pick whichever one
44 you prefer.)
45
46 \section aboutdoc About this document
47
48 This document contains installation instructions, description of
49 the API, reference manual, and pointers to other resources such
50 as the FAQ, web page and the mailing list.
51
52
53 \section genbuild General build instructions
54
55 From version 0.4.4 onwards, AllegroGL is an addon library for Allegro and the
56 usual way to build it is by following the allegro compilation procedure. It
57 will configure, build and install AllegroGL using default options (a shared
58 release library).
59
60 However, you if you need a custom compiled library, e.g. with debug symbols or
61 a statically linked one, you can build AllegroGL manually, passing custom build
62 options.
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
120 For an optimised build, run `./configure' and `make' from the directory
121 containing this file. This will build the library (in 'lib/unix/') and the
122 examples (in 'examp/'). Use `make install' to install the library and
123 header file. For that part you need write access to /usr/local.
124
125 If you want to build the generic driver, run `./configure --enable-generic'
126 and `make MESADIR=xxx' where xxx is the path to the Mesa 4.0 directory.
127 This will build both Mesa (GL and GLU) and AllegroGL
128
129
130 For a debug build, add `DEBUGMODE=1' on each of the command lines.
131
132
133 If you get errors about missing header files or libraries,
134 either for X or GL, see the instructions at the top of
135 `makefile'. Note that you need to have the X development
136 package installed, if you are using Red Hat Linux or Debian
137 GNU/Linux.
138
139
140
141 \subsection minginst Mingw/32 instructions
142
143 Mingw 2.0 and higher already come with the OpenGL header files
144 and libraries, so you can skip the next step.
145
146 If you don't have the OpenGL header files (GL\\gl.h) and libraries, you will
147 first need to acquire thrm. These can be obtained from the Microsoft site,
148 or from MSVC.
149
150 If you obtained the self-extracting archive from the Microsoft site, then
151 run it. Move the produced header files (*.h) into C:\\Mingw32\\include\\GL\\
152 (replace C:\\Mingw32 by wherever you happen to have installed Mingw).
153 Ignore the other files, as they are only useful for MSVC.
154
155 You need to set up your environment if you haven't done that already.
156 Environment variable "PATH" should point to the "bin" directory of Mingw.
157 You can check that by typing "gcc" in the console. It must display something
158 like: "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
160 have installed Mingw).
161 Also, you need to set MINGDIR env. variable. It must point to Mingw instalation
162 directory: "set MINGDIR=C:\Mingw32". You can check that with: "echo %MINGDIR%".
163
164 You will need to run 'fix mingw32' in the AllegroGL directory
165 to update makefile for Mingw32.
166 Since both Allegro and AllegroGL have native Mingw support
167 I am happy to say that you can build Allegro/AllegroGL programs
168 entirely using free software.
169
170 For an optimised build, run `make' from the directory containing
171 this file. Use `make install' to install the library and header
172 file. Some versions of Mingw come with `mingw32-make' instead of
173 `make', so you may need to run that instead.
174
175 For a debug build, do the same but write `DEBUGMODE=1' on each
176 of the command lines; for example, 'make DEBUGMODE=1' and
177 'make install DEBUGMODE=1'.
178
179 Add 'STATICLINK=1' to the last two commands to build AllegroGL that can be
180 linked to statically linked allegro.
181
182
183 \subsection msvcinst MSVC6/7/8 instructions
184
185 There are two completely different ways of compiling AllegroGL using MSVC. You
186 can use the old-fashion way decribed bellow (similar to building allegro, using
187 a GNU makefile and a command line), or you can locate the project file for your
188 MSVC version in "projects" directory and compile AllegroGL lib and examples with
189 a few mouse clicks. You'll have to manually copy libs and headers to appropiate
190 locations.
191 You can choose between several build configuration, depending against which
192 Allegro 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
206 All configuration except "DLL Release" produce AllegroGL library that is
207 statically linked to the executable.
208
209
210 Instructione for compiling AllegroGL using command line follow.
211
212 You must have a working copy of GNU Make (useful for
213 building Allegro, anyway). This can be either DJGPP's or
214 Mingw'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
270 Please note that DOS support is currently in experimental stages.
271
272 Unzip the archive files MesaLib-4.0.zip wherever you want.
273 Unzip AllegroGL
274
275 Create the environment variable MESADIR which defines the Mesa sources path :
276 set MESADIR=xxx
277 where 'xxx' is the path to the Mesa root directory
278
279 Go to the root directory of AllegroGL type 'fix djgpp' (without
280 quotes) followed by 'make'. The GL, GLU and AllegroGL libraries are built.
281 Finally type 'make install' to install the library
282
283 You're done! You can now use AllegroGL on DOS. Try the example demos...
284
285 For a debug build, do the same but write `DEBUGMODE=1' on each
286 of the command lines.
287
288 Note 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
300 First you will need to run `./fix.sh macosx' in order to prepare the
301 makefile for Mac OS X. Then `make' will build the library (in `lib/macosx')
302 and the examples (in `examp/'). Use `sudo make install' to install the
303 library and the header files; this step will require your system root
304 password and will install into /usr/local.
305
306 For a debug build, add `DEBUGMODE=1' on `make' and `make install' calls,
307 for example, `make DEBUGMODE=1' and `sudo make install DEBUGMODE=1'.
308
309
310
311 \section usagedocs Using AllegroGL
312
313 A reference to the functions and macros available to user
314 programs can be found by clicking on the links on top of this
315 document, or online at the web site, and is
316 also downloadable from there in various formats.
317
318 The quick start guide and the FAQ are included in the
319 distribution in the root directory.
320
321
322 \section moreinfo More information
323
324
325 web 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
332 mailing 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
347 Good luck...
348
349
350 -- The AllegroGL team
351 */