README
1BRIEF OVERVIEW
2==============
3
4This is the freeglut package.
5
6Freeglut, the Free OpenGL Utility Toolkit, is meant to be a free alternative to
7Mark Kilgard's GLUT library. Freeglut is free software, distributed under an
8MIT/X11 style license. You are free to use, modify, and redistribute FreeGLUT
9with or without modifications (see COPYING for details).
10
11PORTS
12=====
13
14Currently supported platforms:
15 - UNIX systems with X11 and Wayland (such as GNU/Linux, FreeBSD, etc)
16 - MS Windows
17 - macOS with XQuartz (no native Cocoa support yet)
18 - Android (NDK)
19 - BlackBerry
20
21Consult the platform-specific readme files for details on the level of support
22and build instructions.
23
24
25INSTALLATION
26============
27
28See README.cmake as a starting point, as well as the other README
29files for further info.
30
31
32CONTRIBUTING
33============
34
35Patches for bugfixes and new features are certainly welcome. Please send patches
36to the freeglut-developer mailing list (see CONTACT below).
37
38Feel free to report any bugs you encounter, using our bug tracking system:
39https://sourceforge.net/p/freeglut/bugs/
40Feature requests are also welcome at:
41https://sourceforge.net/p/freeglut/feature-requests/
42
43If your bug report needs urgent attention, please also post a message to the
44aforementioned freeglut-developer mailing list, to make sure we'll see it ASAP.
45
46
47CONTACT
48=======
49
50FreeGLUT website: http://freeglut.sourceforge.net
51
52FreeGLUT mailing lists:
53 - developer: https://lists.sourceforge.net/lists/listinfo/freeglut-developer
54 - bugs: https://lists.sourceforge.net/lists/listinfo/freeglut-bugs
55 - announce: https://lists.sourceforge.net/lists/listinfo/freeglut-announce
56
57 You need to subscribe before posting to any of our mailing lists. Make sure
58 to avoid selecting "daily digest mode" if you intend to post, so that you can
59 reply properly to specific messages. Also, please do not top-post, and try to
60 send properly formated emails (text, hard-wrapped at 72 columns, no binary or
61 large attachements).
62
README.android
README.blackberry
1# ------------------------------------------------------------------------------
2# BlackBerry CMake toolchain file, for use with the BlackBerry 10 NDK
3# Requires cmake 2.6.3 or newer (2.8.3 or newer is recommended).
4#
5# Usage Linux:
6# $ source /absolute/path/to/the/bbndk/bbndk-env.sh
7# $ mkdir build
8# $ cd build
9# $ cmake .. -DCMAKE_TOOLCHAIN_FILE="../blackberry.toolchain.cmake" -DBLACKBERRY_ARCHITECTURE=arm -DFREEGLUT_GLES=ON -DFREEGLUT_BUILD_DEMOS=NO -DCMAKE_VERBOSE_MAKEFILE=TRUE -G "Eclipse CDT4 - Unix Makefiles"
10# $ make -j8
11#
12# Usage Mac:
13# Same as the steps on Linux
14#
15# Usage Windows:
16# > /absolute/path/to/the/bbndk/bbndk-env.bat
17# > mkdir build
18# > cd build
19# > cmake .. -DCMAKE_TOOLCHAIN_FILE="../blackberry.toolchain.cmake" -DBLACKBERRY_ARCHITECTURE=arm -DFREEGLUT_GLES=ON -DFREEGLUT_BUILD_DEMOS=NO -DCMAKE_VERBOSE_MAKEFILE=TRUE -G "Eclipse CDT4 - Unix Makefiles"
20# > make -j8
21#
22
23To change which version of OpenGL to use, call glutInitContextVersion(1, 0) for OpenGL ES 1.x, glutInitContextVersion(2, 0) for OpenGL ES 2.0, or glutInitContextVersion(3, 0) for OpenGL ES 3.0.
README.cmake
1How to build freeglut with CMake on Windows (MS Visual Studio)
2--------------------------------------------------------------
31. Download CMake (http://www.cmake.org/cmake/resources/software.html).
4 Get one of the releases from the binary distribution section.
52. Run the CMake installer, install wherever you like.
63. Launch CMake via Start > Program Files > CMake 2.8 > CMake (GUI)
7 (note that the shortcut put by the installer on your desktop does NOT
8 point to the CMake GUI program!)
94. In the "Where is the source code" box, type or browse to the root
10 directory of your freeglut source (so that's /freeglut, not
11 /freeglut/src).
125. In the "Where to build the binaries" box, type or browse to any
13 folder you like - this will be where the Visual Studio solution will be
14 generated. This folder does not have to exist yet.
156. Hit the Configure button near the bottom of the window.
167. Pick your target compiler, make sure that its installed on your
17 system of course!
188. Answer Ok when asked if you want to create the build directory.
199. Wait for the configure process to finish.
2010. The screen will now have some configuration options on it, for
21 instance specifying whether you want to build static and/or shared
22 libraries (see below for a complete list). When you've selected your
23 options, click the Configure button again.
2411. The Generate button at the bottom will now be enabled. Click Generate.
2512. The build files will now be generated in the location you picked.
26
27You can now navigate to the build directory you specified in step 5.
28Open the freeglut.sln file that was generated in your build directory,
29and compile as usual
30
31
32How to build freeglut on UNIX
33-----------------------------
34- Make sure you have cmake installed. Examples:
35 - Debian/Ubuntu: apt-get install cmake
36 - Fedora: yum install cmake
37 - FreeBSD: cd /usr/ports/devel/cmake && make install
38 Or directly from their website:
39 http://www.cmake.org/cmake/resources/software.html
40- Make sure you have the basics for compiling code, such as C compiler
41 (e.g., GCC) and the make package.
42- Also make sure you have packages installed that provide the relevant
43 header files for opengl (e.g., libgl1-mesa-dev on Debian/Ubuntu) and
44 the chosen backend :
45 - X11: x11 (e.g., libx11-dev, libxrandr-devel on Debian/Ubuntu) and
46 XInput (libxi-dev / libXi-devel)
47 - Wayland: wayland (e.g., libwayland-dev and libegl1-mesa-dev on
48 Debian/Ubuntu) and xkbcommon (libxkbcommon-dev /libxkbcommon-devel)
49- Run 'cmake .' (or 'cmake . -DFREEGLUT_WAYLAND=ON' for Wayland) in the
50 freeglut directory to generate the makefile.
51- Run 'make' to build, and 'make install' to install freeglut.
52- If you wish to change any build options run 'ccmake .'
53
54
55Breakdown of CMake configuration options
56----------------------------------------
57CMAKE_BUILD_TYPE [Empty, Debug, Release] Can be overriden by
58 passing it as a make variable during build.
59CMAKE_INSTALL_PREFIX Installation prefix (e.g. /usr/local on UNIX)
60FREEGLUT_BUILD_DEMOS [ON, OFF] Controls whether the demos are
61 built or not.
62FREEGLUT_BUILD_SHARED_LIBS [ON, OFF] Build freeglut as a shared library
63FREEGLUT_BUILD_STATIC_LIBS [ON, OFF] Build freeglut as a static library
64FREEGLUT_GLES [ON, OFF] Link with GLEs libraries instead
65 of OpenGL
66FREEGLUT_WAYLAND [ON, OFF] Link with Wayland libraries instead
67 of X11
68FREEGLUT_PRINT_ERRORS [ON, OFF] Controls whether errors are
69 default handled or not when user does not
70 provide an error callback
71FREEGLUT_PRINT_WARNINGS [ON, OFF] Controls whether warnings are
72 default handled or not when user does not
73 provide an warning callback
74FREEGLUT_REPLACE_GLUT [ON, OFF] For non-Windows platforms,
75 freeglut is by default built as -lglut. if
76 off, built as -lfreeglut. On Windows,
77 libraries are always built as freeglut.
78INSTALL_PDB [ON, OFF] MSVC only: controls whether debug
79 information files are included with the
80 install or not
81
README.cygwin_mingw
1Glut then!
2
3By Jean-Seb on Friday July 10, 2009, 00:18
4Translated by Babelfish with a scrub from John F. Fay. For points of confusion
5please refer to the original French version.
6
7Freeglut is an open-source evolution of GLUT.
8Under Windows, one can use it with Cygwin.
9Easy? Yes, if one agrees to distribute "cygwin1.dll".
10Let us help freeglut gain its independence !
11Update 10/7/2009: generation of a library for linking without the DLL.
12
13
14Grabbing the sources
15
16 * Download the sources for version 2.6.0 which integrates recent changes.
17 * Using version 2.6 is better than the 2.4-stable branch because many
18 bugs have been corrected.
19 * You will find the sources on the site of Freeglut:
20 o http://freeglut.sourceforge.net/
21
22
23Goals
24
25 * We will create a DLL for Cygwin, and an independent static library
26 * We will also create a dynamic library, allowing linking with the DLL.
27
28
29List of generated files
30
31 * freeglut.dll: a traditional DLL for the dynamic linkage.
32 * libfreeglut.a: the static library. The final program is autonomous (at
33 least for OpenGL).
34 * libfreeglutdll.a: the dynamic library. The final program needs
35 freeglut.dll.
36
37
38Preparation
39
40 * Extract the files from the freeglut archive.
41 * Go in the directory src (located at the root of the Freeglut directory),
42 and create a "Gl" sub-directory
43 o In this sub-directory, copy the files of the directory "include/Gl"
44
45 * Why is it necessary to create a "Gl" directory for compilation?
46 o I needed it to simplify things during my tests.
47 o If not you can create the repertories directly, and copy the files
48 as indicated in the point installation (see below).
49
50 * Do a little housekeeping in /lib:
51 o Erase all the references to the glut, so as not to conflict with the
52 linking.
53 o This stage is optional, you can also choose to do the housekeeping
54 only after a successful compilation of Freeglut.
55 o In your enthusiasm to clean things up, be careful not to erase the
56 library glu32.lib (not to be confused with glut32.lib).
57
58
59Compilation
60
61 * Forget the "./configure, make, make install" triptych.
62 o It does not go at all with Cygwin.
63
64 * Here Makefile which will make the deal:
65
66#Makefile for Freeglut 2.6.0-rc and Cygwin
67#To place in the directory 'src/Common'
68
69sources=$ (wildcard *.c)
70objs=$ (sources: .c=.o)
71libname=freeglut
72
73
74CFLAGS=-O2 - DTARGET_HOST_MS_WINDOWS - DX_DISPLAY_MISSING - DFREEGLUT_STATIC - I./
75LDFLAGS=-lopengl32 - lgdi32 - lwinmm
76
77nocyg=-mno-cygwin - mwindows
78
79all: $ (objs)
80 #construction DLL related to cygwin1.dll
81 gcc $(nocyg) $(objs) -shared $(LDFLAGS) -o $(libname).dll
82 nm $(libname).dll | awk 'BEGIN { print "EXPORTS" } /T _glut/ {sub( /^.*T _/, "\t"); print}' > $(libname).def
83 dlltool --dllname $(libname).dll --input-def $(libname).def --output-lib lib$(libname)dll.a
84
85 #construction static library independent of cygwin
86 ar cr lib$(libname).a $(objs)
87 #pas inevitably obligatory (creation of an index to accelerate the accesses)
88 ranlib lib$(libname).a
89
90%.o: %.c
91 gcc $(nocyg) -c $(CFLAGS) $<
92
93clean:
94 rm -f *.o $(libname).dll $(libname).def lib$(libname)dll.a lib$(libname).a
95
96
97
98
99Some remarks on the Makefile
100
101 * This makefile creates a DLL, a static library (a file, in other words) and
102 the dynamic library which will allow the use of the DLL.
103
104 * Do not try to strip the static library! You may not be able to compile
105 applications with static library any more.
106 o On the other hand, you can strip the final executable obtained after
107 compiling your application.
108
109 * I chose to call the DLL and the libraries by their "true names":
110 freeglut.dll libfreeglutdll.a and libfreeglut.a.
111 o Script configures recreated (for reasons of compatibility with the
112 old GLUT library) glut.dll and libglut.a.
113 o During the my tests, I had conflicts with an authentic "glut" which
114 trailed in my "/lib". I decided to call the things by their name, in
115 order to avoid confusions.
116 o Nothing prevents you from renaming the DLL, if you need to use GLUT
117 programs which you cannot recompile.
118
119 * The dynamic library is generated starting from the DLL.
120 o For reasons of brevity, I used awk. It generates the export file
121 used by dlltool.
122 o The only notable thing is the selection of the functions whose name
123 starts with _glut, in order to avoid including in the dynamic
124 library the functions that are not related to freeglut.
125 o then, one uses dlltool in a very traditional way.
126
127nm $(libname).dll | awk 'BEGIN { print "EXPORTS" } /T _glut/ {sub( /^.*T _/, "\t"); print}' > $(libname).def
128dlltool --dllname $(libname).dll --input-def $(libname).def --output-lib lib$(libname)dll.a
129
130
131
132
133Installation
134
135 * Copy libfreeglut.a, libfreeglutdll.a into the Cygwin directory /lib.
136 * Copy freglut.dll in the system32 of Windows (this is practical, but not
137 clean!).
138 * Copy the files headers of Freeglut (/include/gl) into the Cygwin directory
139 /usr/include/Gl.
140 * Copy the files headers (always /include/gl) into /usr/include/mingw/Gl:
141 this is used for compilations with the flag - mno-cygwin, which uses the
142 includes in mingw.
143 o You may need to erase the old GLUT include files if you installed it
144 with Cygwin.
145
146
147Use of the library
148
149 * We will test with the program shapes, found in progs/demonstrations/shapes
150 o -mno-cygwin is used to force the use of Mingw without the large
151 dependence cygwin1.dll.
152 o -mwindows is only used to remove the horrible Shell window (very
153 useful for the settling, on the other hand).
154 o -L. (note the period after the "L"): I left libfreeglut.a,
155 libfreeglutdll.a and freeglut.dll in the test directory, at the time
156 of the tests.
157
158
159Compilation of the static freeglut library, without cygwin
160
161 * All the simplicity lies in the define: -DFREEGLUT_STATIC
162 o It serves to obtain good decoration of the function names in the
163 imports of the lib Freeglut.
164 o You can test without and use a hex editor to see the differences
165 in the objects.
166 * attention with the order of the libraries: -lfreeglut (static) must be
167 before the declaration of the dynamic libraries.
168
169 * gcc shapes.c -L. -lfreeglut -lopengl32 -lwinmm -lgdi32 -mno-cygwin -mwindows -DFREEGLUT_STATIC
170
171
172Compilation with DLL freeglut, without cygwin
173
174 * For the define, see the notices above
175 * The order of the libraries is no longer important.
176
177 * gcc shapes.c -L. -lopengl32 -lwinmm -lgdi32 -lfreeglut -mno-cygwin -DFREEGLUT_STATIC
178
179
180Compilation with DLL freeglut, Cygwin
181
182 * This example is given only for reference, the topic of this ticket being
183 to get rid of Cygwin.
184 o Let us say that can be used to make the point (and later).
185
186 * gcc shapes.c -L. -lopengl32 -lwinmm -lgdi32 -lfreeglut
187
188
189
190Where are the dooooocs?
191
192 * Freeglut is delivered with its documentation, more very up to date.
193 o It seems that there is a problem with the original GLUT
194 documentation. Not only it does not correspond completely to the
195 operation of Freeglut, but moreover, its author (Mark Kilgard)
196 copyrighted it. Its distribution is thus difficult.
197
198 * Jocelyn Fr�chot undertook a levelling of the docs for version 2.6.0. One can find them on his site for the moment:
199 o http://jocelyn.frechot.free.fr/freeglut/
200
201
202Something survived...
203
204 * I also tested the recompiling of the demonstrations of the original lib
205 GLUT (peace with its ashes).
206 o Nothing in particular to be announced.
207
208 * Thank you with all the courageous maintainers for Freeglut, that one
209 believed dead, but which still move.
210
README.mingw_cross
1Cross-compilation from GNU/Linux (static and shared DLL)
2========================================================
3
4Install MinGW, and specify which MinGW you're using:
5
6- on Debian/Ubuntu, mingw-w64, 64-bit executables:
7
8 apt-get install mingw-w64
9 GNU_HOST=x86_64-w64-mingw32
10
11- on Debian/Ubuntu, mingw-w64, 32-bit executables:
12
13 apt-get install mingw-w64
14 GNU_HOST=i686-w64-mingw32
15
16- on Fedora, mingw32, 32-bit executables:
17
18 yum install mingw32-gcc
19 GNU_HOST=i686-pc-mingw32
20
21- on Debian/Ubuntu, mingw32 (deprecated):
22
23 apt-get install mingw32
24 GNU_HOST=i586-mingw32msvc
25
26
27With CMake
28----------
29
30Cross-compile with:
31
32 mkdir cross-woe/ && cd cross-woe/
33 cmake \
34 -D GNU_HOST=$GNU_HOST \
35 -D CMAKE_TOOLCHAIN_FILE=mingw_cross_toolchain.cmake \
36 -D CMAKE_INSTALL_PREFIX=/freeglut \
37 ..
38 make -j4
39 make install DESTDIR=$(pwd)
40
41Everything is now in the new 'freeglut/' directory.
42The .dll is in 'freeglut/lib/'.
43
44
45Compiling your code
46-------------------
47
48Compilation of your own programs is done as usual.
49See README.cygwin_mingw for details.
50
README.win32
1NB
2==================================
3For ancient 16bit compatibility, windef.h (included through windows.h in
4freeglut_std.h) defines near and far. Its best to avoid using variables
5with these names in your own program.
6
7Installing the Libraries with MSVC
8==================================
9
10To install "freeglut" on your system so that your other projects will see it,
11you will need to copy various files to various locations.
12
13 - The header files "freeglut.h", "freeglut_ext.h", "freeglut_std.h", and
14 "glut.h" (distributed in the directory "freeglut\freeglut\include\GL")
15 need to be copied to a "GL" directory under the MSVC include directory.
16 The MSVC include directory generally has a path similar to
17 "C:\Program Files\Microsoft Visual Studio\VC98\Include"
18 The "GL" subdirectory under that will probably already have the header
19 files "gl.h", "glaux.h", and "glu.h".
20 - The library file "freeglut.lib" or "freeglut_static.lib" (from the
21 corresponding debug or release directory) needs to be copied into the
22 MSVC library directory. This usually has a path similar to:
23 "%ProgramFiles%\Microsoft SDKs\Windows\v7.0A\Lib" - x86 32 bits LIB's
24 "%ProgramFiles(x86)%\Microsoft SDKs\Windows\v7.0A\Lib" - x64 32 bits LIB's
25 "%ProgramFiles(x86)%\Microsoft SDKs\Windows\v7.0A\Lib\x64" - x64 64 bits LIB's
26 Note that there is no "GL" subdirectory here. This directory should
27 already have the files "opengl32.lib", "glu32.lib", and "glaux.lib".
28 - If you are using the DLL version of "freeglut", the file "freeglut.dll"
29 needs to be copied from the Debug or the Release directory into the
30 DLL directory. This usually has a path similar to
31 "%SystemRoot%\System32\" - x86 32 bits DLL's
32 "%SystemRoot%\SysWOW64\" - x64 32 bits DLL's
33 "%SystemRoot%\System32\" - x64 64 bits DLL's
34 and will probably already have the files "opengl32.dll" and "glu32.dll".
35
36
37Building and Installing the Libraries with Open Watcom
38======================================================
39
40Start a command prompt and change directory to the freeglut installation
41directory. Type "wmake -f Makefile.wat all" to build the DLL and static
42libraries in both debug and release versions.
43
44To install "freeglut" on your system so that your other projects will see it,
45you will need to copy various files to various locations.
46
47 - The header files "freeglut.h", "freeglut_ext.h", "freeglut_std.h", and
48 "glut.h" (distributed in the directory "freeglut\freeglut\include\GL")
49 need to be copied to a "GL" directory under the Open Watcom 32-bit
50 Windows include directory. This usually has a path similar to
51 "C:\WATCOM\h\nt\GL"
52 - The library file "freeglut.lib" or "freeglut_static.lib" (from the
53 corresponding debug or release directory) needs to be copied into the
54 Open Watcom 32-bit Windows library directory. This usually has a path
55 similar to
56 "C:\WATCOM\lib386\nt"
57 - If you are using the DLL version of "freeglut", the file "freeglut.dll"
58 needs to be copied from the Debug or the Release directory into the
59 DLL directory. This usually has a path similar to
60 "C:\Windows\System32"
61 and will probably already have the files "opengl32.dll" and "glu32.dll".
62
63
64Unlike the *nix release, the library names are NOT automatic replacements for
65the GLUT library names. You may rename them manually if you wish, but this is
66not necessary as the header file includes a pragma telling the compiler which
67library file to look for.
68
69
70Building and Installing the Libraries with Cygwin
71=================================================
72
73To build "freeglut" under Cygwin, you have two choices:
74
75- You can build a normal Cygwin library, which depends on Cygwin's X11
76 libraries. To do this, you can just use the normal autotools incantation:
77 ./configure && make install
78
79- Alternatively, you can build a DLL which does not depend on X11 and links
80 against the opengl32 DLL. To do this, configure need a few more flags:
81 ./configure CPPFLAGS=-mno-cygwin LDFLAGS=-mno-cygwin --without-x && make install
82
83
84If you don't have MSVC, Open Watcom or Cygwin
85=============================================
86
87The "freeglut" developers' community discussed the possibility of distributing
88binaries and decided against it. If you need Windows library files, please
89contact John F. Fay at <john.fay@eglin.af.mil> or put a request on the
90"freeglut" developers' mailing list <freeglut-developer@lists.sourceforge.net>.
91
92