source distribution
|
|
GLFW v2.4.2 source distribution |
Welcome to version 2.4.2 of the GLFW OpenGL framework. GLFW is a free, open source, portable framework for OpenGL application development. In short, it is a library that constitutes a powerful API for handling operating system specific tasks, such as opening an OpenGL window, reading keyboard and mouse input, creating threads, and much more.
A top level makefile can be found in the root directory of the GLFW distribution that has been designed to work with several compilers. If you simply enter the GLFW root directory in a shell and type make (or nmake or gmake, depending on the name of your make tool), and a list should appear with the currently supported options for systems and compilers.
For example, one of the options is to compile GLFW for Windows with the LCC-Win32 C compiler. To do that, type make win32-lcc in the shell (as specified in the previously mentioned list). That will compile the GLFW static link library and the supplied example programs. For Windows compilers, a Win32 DLL will also be compiled.
Currently supported compilers and systems are:
If your compiler/system is not in the list, you will have to create new makefiles in the lib\win32, lib/x11, lib/amigaos or lib/macosx directory, and in the examples directory. If you have any problems, do not hesitate to contact me (I may not know how your compiler works, but I know the GLFW source code). I would also like to add support for more compilers and verify that GLFW compiles under as many systems as possible, so if you had to make any modifications or additions to the source and/or makefiles in order to make GLFW compile successfully, I would like to know what you had to do.
When MSVC is installed, you are asked if it should be possible to access the compiler from the command line. For some strange reason, the default answer to this question is NO. If you answered no to this question you will have to run a file named VCVARS32.BAT, which is located in the bin directory of your Visual C++ folder, before you can use the compiler from the command line.
Note that VCVARS32.BAT must be run from the same shell as you intend to use for compiling GLFW (simply clicking on the file from the explorer will not work).
After that is done, it is possible to compile GLFW by entering the GLFW root directory and issuing nmake win32-msvc.
For instance, if MSVC is installed in the directory 'C:\Program Files\Microsoft Developer Studio\VC98', then you should be able to compile GLFW with this procedure:
Do not use the MSYS shell for compiling GLFW, because the supplied batch file "compile.bat" will only work under a Windows command prompt (or MS-DOS prompt).
The top level makefile was designed to run from a Cygwin bash shell. You can not use an MS-DOS prompt (or NT cmd prompt) to compile GLFW with the win32-cygwin option. Similarly, the win32-clean option will not work from a Cygwin shell, which is why there is a special cygwin-clean option.
In order to compile GLFW successfully with OpenWatcom (for Windows), execute "nmake MAKE=nmake win32-ow" in the GLFW root directory. Also make sure that you have all your environment variables set up correctly. It is the default option when installing OpenWatcom to permanently set up all the required environment variables. If nmake does not work, you probably have to run "WATCOM\setvars.bat" from the command prompt before executing nmake, where WATCOM is the directory in which you installed OpenWatcom (e.g. C:\Watcom).
Compiler and link library capabilities are auto-detected with a script called compile.sh. It has been tested under Linux Mandrake 9.1, Mac OS X 10.2, SunOS 5.6 (GCC), IRIX 5.3, FreeBSD 5.0 and QNX, but should hopefully run on the majority of available Unix/Unix-like systems and generate functional Makefiles. You do not have to run the script manually, since it is called from the top level Makefile.
The current AmigaOS implementation of GLFW requires VBCC (an excellent free C compiler) or Geek Gadgets GCC, the StormMesa developer package, and of course the AmigaOS include files (not included with VBCC or GCC due to copyright reasons).
To compile GLFW and the example programs for AmigaOS (68k) with VBCC, you need a make program that understands AmigaDOS paths. I use the SAS/C compiled version of GNU make 3.75, which can be found on Aminet.
It should also be noted that the current version of GLFW for AmigaOS is only a subset of the full GLFW API. Most of the core functionality has been implemented, but there are still some things missing (e.g. hiding the mouse cursor in windowed mode, iconification handling etc).
To compile GLFW for Mac OS X, you will need to have installed the BSD subsystem and the Developer Tools, which can be found on your Mac OS X CD:s. When they are installed, simply open Terminal and go to the lib/macosx directory. From there, you can build the library by running make with the appropriate makefile, i.e. make -f Makefile.macosx.gcc.
The current port for DOS is very preliminiary. It is based on alpha versions of DJGPP and Mesa 5.1, and in my experience the mouse interface seems error prone (random crashes). At the moment the DOS port should be considered experiemental at best, so use it at your own risk.
After compiling GLFW with MinGW32 or Cygwin, three files of interest should have appeared in the lib\win32 directory. They are: libglfw.a (the static link version of GLFW), glfw.dll (the DLL version of GLFW) and libglfwdll.a (the DLL import library).
If you used Borland C++ Builder, LCC-Win32, Microsoft Visual C++ or OpenWatcom, the files are named glfw.lib (the static link version of GLFW), glfw.dll (the DLL version of GLFW) and glfwdll.lib (the DLL import library).
The static link library and the DLL import library should be copied to your compiler's LIB directory (where all other link libraries are located). The DLL can be copied either to your Windows system directory (where opengl32.dll is located), or to the project directory of your GLFW-based projects (where you place your compiled EXEs).
You should also copy the GLFW include file, include\GL\glfw.h, to the GL directory of your compiler's include directory (where gl.h, glu.h etc. are located).
After compiling GLFW, a file named libglfw.a should have appeared in the lib/x11 directory. This is the GLFW static link library, which should be copied to your compiler's lib directory (where all other link libraries are located).
You should also copy the GLFW include file, include/GL/glfw.h, to the GL directory of your compiler's include directory (where gl.h, glu.h etc. are located).
After compiling GLFW, a file named glfw.lib should have appeared in the lib/amigaos directory. This is the GLFW static link library, which should be copied to your compiler's lib directory (where all other link libraries are located).
You should also copy the GLFW include file, include/GL/glfw.h, to the GL directory of your compiler's include directory (where gl.h, glu.h etc. are located).
After compiling GLFW, a file named libglfw.a should have appeared in the lib/macosx directory. This is the GLFW static library, which should be copied to an appropriate lib directory, preferrably /usr/local/lib. Note that you must run ranlib on the library after it has been copied, in order for it to be usable, i.e.
sudo mkdir -p /usr/local/lib
sudo cp libglfw.a /usr/local/lib
sudo ranlib /usr/local/lib/libglfw.a
You should also copy the GLFW include file, include/GL/glfw.h, to the GL directory of an appropriate include directory, preferrably /usr/local/include, i.e.:
sudo mkdir -p /usr/local/include/GL
sudo cp glfw.h /usr/local/include/GL
There are two aspects to using GLFW:
The first point is covered in the GLFW Users Guide and the GLFW Reference Manual, and I suggest that you read at least the Users Guide, since it is a good introduction to the GLFW API.
Designing and compiling programs that use GLFW is not very difficult. A few rules for successfully designing GLFW-based programs are presented in the following sections.
In your program, you should include <GL/glfw.h>. This include file defines all the necessary constants, types and prototypes that are used to interact with the GLFW API. It also includes <GL/gl.h> and <GL/glu.h>, and - this is very important - it defines all the necessary constants and types that are necessary for OpenGL to work on different platforms.
For instance, under Windows you are normally required to include <windows.h> before you include <GL/gl.h>. If you write such a program, it would not compile under e.g. Linux since <windows.h> does not exist under Linux. <GL/glfw.h> takes care of these things for you. Note however that it does not actually include <windows.h>, it merely mimics the parts of it that are needed for <GL/gl.h> and <GL/glu.h> (this way we do not get the thousands of constants, types and prototypes that could otherwise possibly interfere with our own declarations).
In other words:
Note: If you do need to include <windows.h>, do it before including <GL/glfw.h>.
If you link with the static version of GLFW, it is also necessary to link with some system libraries that GLFW uses.
When linking a program under Windows that uses the static version of GLFW, you must also link with the following libraries: opengl32, user32 and kernel32. Some of these libraries may be linked with by default by your compiler. In the table below you can see the minimum required link options for each supported Windows compiler (you may want to add other libraries as well, such as glu32):
| Compiler | Link options |
| Borland C++ Builder | glfw.lib opengl32.lib |
| Cygwin | -lglfw -lopengl32 |
| LCC-Win32 | glfw.lib opengl32.lib |
| Microsoft Visual C++ | glfw.lib opengl32.lib user32.lib |
| MinGW32 | -lglfw -lopengl32 |
| OpenWatcom | glfw.lib opengl32.lib user32.lib |
To compile a program that uses the DLL version of GLFW, you need to define the GLFW_DLL constant. This can either be done with a compiler switch, typically by adding -DGLFW_DLL to the list of compiler options. You can also do it by adding the line:
#define GLFW_DLL
...to all your source files that include glfw.h, before including it.
When linking a program under Windows that uses the DLL version of GLFW, the only library you need to link with for GLFW to work is glfwdll. In the table below you can see the minimum required link options for each supported Windows compiler (you may want to add other libraries as well, such as opengl32 and glu32):
| Compiler | Link options |
| Borland C++ Builder | glfwdll.lib |
| Cygwin | -lglfwdll |
| LCC-Win32 | glfwdll.lib |
| Microsoft Visual C++ | glfwdll.lib |
| MinGW32 | -lglfwdll |
| OpenWatcom | glfwdll.lib |
Since there are so many flavors of Unix and Unix-like systems, it is impossible to give a standard rule for properly linking GLFW applications. In general, it is a good idea to look at the automatically generated Makefile.x11 file in the examples directory, which should contain all the necessary compiler and linker directives. Following is a brief description of what should work for many (but not all) systems:
When compiling and linking a program under Unix/X11 that uses GLFW, you must also link with the following libraries: GL, X11 and pthread. For XFree86 you also need to link with Xxf86vm.
Of course, in all cases you should also link with glfw.
A typical compile and link command line may look like this (using gcc):
gcc myprog.c -o myprog -lglfw -lGL -lX11 -lpthread
For XFree86 you also add -lXxf86vm, and under Linux (and perhaps other environments) you need to specify the location of the X11 library files using -L/usr/X11R6/lib:
gcc myprog.c -o myprog -L/usr/X11R6/lib -lglfw -lGL -lX11 -lpthread -lXxf86vm
FreeBSD systems require that you use -pthread instead of -lpthread.
QNX systems require that you use -lsocket instead of -lpthread. Usually, X11 is installed in /opt instead of /usr under QNX, so use -L/opt/X11R6/lib.
If you use GLU functions in your program you should also add -lGLU.
When compiling and linking a program under AmigaOS that uses GLFW, you must also link with the following libraries: GL, amiga and m (the latter can be m881 or m040 etc, depending on which compiler and CPU you use).
Of course, in all cases you should also link with glfw.
A typical compile and link command line may look like this (using vbcc):
vc -cpu=68020 -fpu=68881 -lglfw -lGL -lamiga -lm881 -o myprog myprog.c
Hint: For VBCC, you can specify -c99 to support things like C++ style comments.
When compiling and linking a program under Mac OS X that uses GLFW, you must also link with the following frameworks: Carbon.framework, AGL.framework and OpenGL.framework.
If you are using an IDE, such as Project Builder or Xcode, you simply add the GLFW library libglfw.a and these frameworks to your project. If, however, you are building your program from the command line, you will need to add them to your command line using the -l and -framework switches, i.e.:
gcc -o myprog myprog.c -lglfw -framework Carbon -framework AGL -framework OpenGL
Note that you do not add the extension to a framework when adding it from the command line.
These frameworks contain all GL and GLU functions, so there is no need to add additional libraries or frameworks when using GLU functionality. Also note that even though your machine may have Unix-style GL libraries, they are for use with the X server, and will not work with the Mac OS X native version of GLFW.
Here is an overview of the directory structure of the GLFW distribution:
| docs | GLFW manuals in PDF format | |
| examples | Several example programs in C | |
| images | Images for this HTML document | |
| include | ||
| GL | Here is the GLFW C/C++ include file | |
| lib | The source code for GLFW | |
| amigaos | AmigaOS specific implementation | |
| dos | DOS specific implementation | |
| macosx | Mac OS X specific implementation | |
| win32 | Windows specific implementation | |
| x11 | Unix/X11 specific implementation | |
| support | ||
| delphi | Delphi support | |
| masm | MASM32 support | |
| win32dll | Compiled version of the GLFW Win32 DLL | |
| visualbasic | Visual Basic support |
My name is Marcus Geelnard, marcus.geelnard@home.se. Please contact me if you have any problems with GLFW, or any questions at all concerning compiling or using GLFW.
The official GLFW web site can be found here: http://glfw.sourceforge.net/. It contains the latest version of GLFW, news and other information that is useful for OpenGL development.
GLFW would not be what it is today without the help from: