1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>GLFW: Building programs using GLFW</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">GLFW
 <span id="projectnumber">3.0.2</span>
</div>
<div id="projectbrief">A multi-platform library for OpenGL, window and input</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Building programs using GLFW </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#build_include">Including the GLFW header file</a><ul><li class="level2"><a href="#build_macros">GLFW header option macros</a></li>
</ul>
</li>
<li class="level1"><a href="#build_link">Link with the right libraries</a><ul><li class="level2"><a href="#build_link_win32">With MinGW or Visual C++ on Windows</a></li>
<li class="level2"><a href="#build_link_cmake_source">With CMake and GLFW source</a></li>
<li class="level2"><a href="#build_link_cmake_pkgconfig">With CMake on Unix and installed GLFW binaries</a></li>
<li class="level2"><a href="#build_link_pkgconfig">With pkg-config on OS X or other Unix</a></li>
<li class="level2"><a href="#build_link_xcode">With Xcode on OS X</a></li>
<li class="level2"><a href="#build_link_osx">With command-line on OS X</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>This is about compiling and linking programs that use GLFW. For information on how to <em>write</em> such programs, start with the <a class="el" href="quick.html">introductory tutorial</a>.</p>
<h1><a class="anchor" id="build_include"></a>
Including the GLFW header file</h1>
<p>In the files of your program where you use OpenGL or GLFW, you should include the GLFW 3 header file, i.e.:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="glfw3_8h.html">GLFW/glfw3.h</a>></span></div>
</div><!-- fragment --><p>This defines all the constants, types and function prototypes of the GLFW API. It also includes the chosen client API header files (by default OpenGL), and defines all the constants and types necessary for those headers to work on that platform.</p>
<p>For example, under Windows you are normally required to include <code>windows.h</code> before including <code>GL/gl.h</code>. This would make your source file tied to Windows and pollute your code's namespace with the whole Win32 API.</p>
<p>Instead, the GLFW header takes care of this for you, not by including <code>windows.h</code>, but rather by itself duplicating only the necessary parts of it. It does this only where needed, so if <code>windows.h</code> <em>is</em> included, the GLFW header does not try to redefine those symbols.</p>
<p>In other words:</p>
<ul>
<li>Do <em>not</em> include the OpenGL headers yourself, as GLFW does this for you</li>
<li>Do <em>not</em> include <code>windows.h</code> or other platform-specific headers unless you plan on using those APIs directly</li>
<li>If you <em>do</em> need to include such headers, do it <em>before</em> including the GLFW one and it will detect this</li>
</ul>
<p>If you are using an OpenGL extension loading library such as <a href="http://glew.sourceforge.net/">GLEW</a>, the GLEW header should also be included <em>before</em> the GLFW one. The GLEW header defines macros that disable any OpenGL header that the GLFW header includes and GLEW will work as expected.</p>
<h2><a class="anchor" id="build_macros"></a>
GLFW header option macros</h2>
<p>These macros may be defined before the inclusion of the GLFW header and affect how that header behaves.</p>
<p><code>GLFW_INCLUDE_GLCOREARB</code> makes the header include the modern <code>GL/glcorearb.h</code> header (<code>OpenGL/gl3.h</code> on OS X) instead of the regular OpenGL header.</p>
<p><code>GLFW_INCLUDE_ES1</code> makes the header include the OpenGL ES 1.x <code>GLES/gl.h</code> header instead of the regular OpenGL header.</p>
<p><code>GLFW_INCLUDE_ES2</code> makes the header include the OpenGL ES 2.0 <code>GLES2/gl2.h</code> header instead of the regular OpenGL header.</p>
<p><code>GLFW_INCLUDE_ES3</code> makes the header include the OpenGL ES 3.0 <code>GLES3/gl3.h</code> header instead of the regular OpenGL header.</p>
<p><code>GLFW_INCLUDE_NONE</code> makes the header not include any client API header.</p>
<p><code>GLFW_INCLUDE_GLU</code> makes the header include the GLU header <em>in addition to</em> the OpenGL header. This should only be used with the default <code>GL/gl.h</code> header (<code>OpenGL/gl.h</code> on OS X), i.e. if you are not using any of the above macros.</p>
<p><code>GLFW_DLL</code> is necessary when using the GLFW DLL on Windows, in order to explain to the compiler that the GLFW functions will be coming from another executable. It has no function on other platforms.</p>
<h1><a class="anchor" id="build_link"></a>
Link with the right libraries</h1>
<h2><a class="anchor" id="build_link_win32"></a>
With MinGW or Visual C++ on Windows</h2>
<p>The static version of the GLFW library is named <code>glfw3</code>. When using this version, it is also necessary to link with some libraries that GLFW uses.</p>
<p>When linking a program under Windows that uses the static version of GLFW, you must link with <code>opengl32</code>. If you are using GLU, you must also link with <code>glu32</code>.</p>
<p>The link library for the GLFW DLL is named <code>glfw3dll</code>. When compiling a program that uses the DLL version of GLFW, you need to define the <code>GLFW_DLL</code> macro <em>before</em> any inclusion of the GLFW header. This can be done either with a compiler switch or by defining it in your source code.</p>
<p>A program using the GLFW DLL does not need to link against any of its dependencies, but you still have to link against <code>opengl32</code> if your program uses OpenGL and <code>glu32</code> if it uses GLU.</p>
<h2><a class="anchor" id="build_link_cmake_source"></a>
With CMake and GLFW source</h2>
<p>You can use the GLFW source tree directly from a project that uses CMake. This way, GLFW will be built along with your application as needed.</p>
<p>Firstly, add the root directory of the GLFW source tree to your project. This will add the <code>glfw</code> target and the necessary cache variables to your project. </p>
<pre class="fragment">add_subdirectory(path/to/glfw)
</pre><p>To be able to include the GLFW header from your code, you need to tell the compiler where to find it. </p>
<pre class="fragment">include_directories(path/to/glfw/include)
</pre><p>Once GLFW has been added to the project, the <code>GLFW_LIBRARIES</code> cache variable contains all link-time dependencies of GLFW as it is currently configured. To link against GLFW, link against them and the <code>glfw</code> target. </p>
<pre class="fragment">target_link_libraries(myapp glfw ${GLFW_LIBRARIES})
</pre><p>Note that <code>GLFW_LIBRARIES</code> does not include GLU, as GLFW does not use it. If your application needs GLU, you can add it to the list of dependencies with the <code>OPENGL_glu_LIBRARY</code> cache variable, which is implicitly created when the GLFW CMake files look for OpenGL. </p>
<pre class="fragment">target_link_libraries(myapp glfw ${OPENGL_glu_LIBRARY} ${GLFW_LIBRARIES})
</pre><h2><a class="anchor" id="build_link_cmake_pkgconfig"></a>
With CMake on Unix and installed GLFW binaries</h2>
<p>CMake can import settings from pkg-config, which GLFW supports. When you installed GLFW, the pkg-config file <code>glfw3.pc</code> was installed along with it.</p>
<p>First you need to find the PkgConfig package. If this fails, you may need to install the pkg-config package for your distribution. </p>
<pre class="fragment">find_package(PkgConfig REQUIRED)
</pre><p>This creates the CMake commands to find pkg-config packages. Then you need to find the GLFW package. </p>
<pre class="fragment">pkg_search_module(GLFW REQUIRED glfw3)
</pre><p>This creates the CMake variables you need to use GLFW. To be able to include the GLFW header, you need to tell your compiler where it is. </p>
<pre class="fragment">include_directories(${GLFW_INCLUDE_DIRS})
</pre><p>You also need to link against the correct libraries. If you are using the shared library version of GLFW, use the <code>GLFW_LIBRARIES</code> variable. </p>
<pre class="fragment">target_link_libraries(simple ${GLFW_LIBRARIES})
</pre><p>If you are using the static library version of GLFW, use the <code>GLFW_STATIC_LIBRARIES</code> variable instead. </p>
<pre class="fragment">target_link_libraries(simple ${GLFW_STATIC_LIBRARIES})
</pre><h2><a class="anchor" id="build_link_pkgconfig"></a>
With pkg-config on OS X or other Unix</h2>
<p>GLFW supports <a href="http://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</a>, and <code>glfw3.pc</code> file is generated when the GLFW library is built and installed along with it.</p>
<p>A typical compile and link command-line when using the static may look like this: </p>
<pre class="fragment">cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
</pre><p>If you are using the shared library, simply omit the <code>--static</code> flag. </p>
<pre class="fragment">cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
</pre><p>You can also use the <code>glfw3.pc</code> file without installing it first, by using the <code>PKG_CONFIG_PATH</code> environment variable. </p>
<pre class="fragment">env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
</pre><p>The dependencies do not include GLU, as GLFW does not need it. On OS X, GLU is built into the OpenGL framework, so if you need GLU you don't need to do anything extra. If you need GLU and are using Linux or BSD, you should add <code>-lGLU</code> to your link flags.</p>
<p>See the manpage and other documentation for pkg-config and your compiler and linker for more information on how to link programs.</p>
<h2><a class="anchor" id="build_link_xcode"></a>
With Xcode on OS X</h2>
<p>If you are using the dynamic library version of GLFW, simply add it to the project dependencies.</p>
<p>If you are using the static library version of GLFW, add it and the Cocoa, OpenGL and IOKit frameworks to the project as dependencies.</p>
<h2><a class="anchor" id="build_link_osx"></a>
With command-line on OS X</h2>
<p>If you do not wish to use pkg-config, you need to add the required frameworks and libraries to your command-line using the <code>-l</code> and <code>-framework</code> switches, i.e.: </p>
<pre class="fragment">cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit
</pre><p>Note that you do not add the <code>.framework</code> extension to a framework when adding it from the command-line.</p>
<p>The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing special to do when using GLU. Also note that even though your machine may have <code>libGL</code>-style OpenGL libraries, they are for use with the X Window System and will <em>not</em> work with the OS X native version of GLFW. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sun Aug 25 2013 21:45:13 for GLFW by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.3.1
</small></address>
</body>
</html>
|
