Browse Source

add docs for glfw

parent
commit
b3bce0faa2

+ 5
- 0
lib/glfw/docs/CMakeLists.txt View File

@@ -0,0 +1,5 @@
1
+
2
+add_custom_target(docs ALL ${DOXYGEN_EXECUTABLE}
3
+                  WORKING_DIRECTORY ${GLFW_BINARY_DIR}/docs
4
+                  COMMENT "Generating HTML documentation" VERBATIM)
5
+

+ 1863
- 0
lib/glfw/docs/Doxyfile.in
File diff suppressed because it is too large
View File


+ 188
- 0
lib/glfw/docs/DoxygenLayout.xml View File

@@ -0,0 +1,188 @@
1
+<doxygenlayout version="1.0">
2
+  <!-- Generated by doxygen 1.8.3.1 -->
3
+  <!-- Navigation index tabs for HTML output -->
4
+  <navindex>
5
+    <tab type="mainpage" visible="yes" title="Introduction"/>
6
+    <tab type="pages" visible="yes" title="Guides" intro=""/>
7
+    <tab type="modules" visible="yes" title="Reference" intro=""/>
8
+    <tab type="namespaces" visible="yes" title="">
9
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
10
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
11
+    </tab>
12
+    <tab type="classes" visible="no" title="">
13
+      <tab type="classlist" visible="yes" title="" intro=""/>
14
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
15
+      <tab type="hierarchy" visible="yes" title="" intro=""/>
16
+      <tab type="classmembers" visible="yes" title="" intro=""/>
17
+    </tab>
18
+    <tab type="files" visible="yes" title="Header Files">
19
+      <tab type="filelist" visible="yes" title="" intro=""/>
20
+      <tab type="globals" visible="yes" title="" intro=""/>
21
+    </tab>
22
+    <tab type="examples" visible="yes" title="" intro=""/>  
23
+  </navindex>
24
+
25
+  <!-- Layout definition for a class page -->
26
+  <class>
27
+    <briefdescription visible="yes"/>
28
+    <includes visible="$SHOW_INCLUDE_FILES"/>
29
+    <inheritancegraph visible="$CLASS_GRAPH"/>
30
+    <collaborationgraph visible="$COLLABORATION_GRAPH"/>
31
+    <memberdecl>
32
+      <nestedclasses visible="yes" title=""/>
33
+      <publictypes title=""/>
34
+      <publicslots title=""/>
35
+      <signals title=""/>
36
+      <publicmethods title=""/>
37
+      <publicstaticmethods title=""/>
38
+      <publicattributes title=""/>
39
+      <publicstaticattributes title=""/>
40
+      <protectedtypes title=""/>
41
+      <protectedslots title=""/>
42
+      <protectedmethods title=""/>
43
+      <protectedstaticmethods title=""/>
44
+      <protectedattributes title=""/>
45
+      <protectedstaticattributes title=""/>
46
+      <packagetypes title=""/>
47
+      <packagemethods title=""/>
48
+      <packagestaticmethods title=""/>
49
+      <packageattributes title=""/>
50
+      <packagestaticattributes title=""/>
51
+      <properties title=""/>
52
+      <events title=""/>
53
+      <privatetypes title=""/>
54
+      <privateslots title=""/>
55
+      <privatemethods title=""/>
56
+      <privatestaticmethods title=""/>
57
+      <privateattributes title=""/>
58
+      <privatestaticattributes title=""/>
59
+      <friends title=""/>
60
+      <related title="" subtitle=""/>
61
+      <membergroups visible="yes"/>
62
+    </memberdecl>
63
+    <detaileddescription title=""/>
64
+    <memberdef>
65
+      <inlineclasses title=""/>
66
+      <typedefs title=""/>
67
+      <enums title=""/>
68
+      <constructors title=""/>
69
+      <functions title=""/>
70
+      <related title=""/>
71
+      <variables title=""/>
72
+      <properties title=""/>
73
+      <events title=""/>
74
+    </memberdef>
75
+    <allmemberslink visible="yes"/>
76
+    <usedfiles visible="$SHOW_USED_FILES"/>
77
+    <authorsection visible="yes"/>
78
+  </class>
79
+
80
+  <!-- Layout definition for a namespace page -->
81
+  <namespace>
82
+    <briefdescription visible="yes"/>
83
+    <memberdecl>
84
+      <nestednamespaces visible="yes" title=""/>
85
+      <classes visible="yes" title=""/>
86
+      <typedefs title=""/>
87
+      <enums title=""/>
88
+      <functions title=""/>
89
+      <variables title=""/>
90
+      <membergroups visible="yes"/>
91
+    </memberdecl>
92
+    <detaileddescription title=""/>
93
+    <memberdef>
94
+      <inlineclasses title=""/>
95
+      <typedefs title=""/>
96
+      <enums title=""/>
97
+      <functions title=""/>
98
+      <variables title=""/>
99
+    </memberdef>
100
+    <authorsection visible="yes"/>
101
+  </namespace>
102
+
103
+  <!-- Layout definition for a file page -->
104
+  <file>
105
+    <briefdescription visible="yes"/>
106
+    <includes visible="$SHOW_INCLUDE_FILES"/>
107
+    <includegraph visible="$INCLUDE_GRAPH"/>
108
+    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
109
+    <sourcelink visible="yes"/>
110
+    <memberdecl>
111
+      <classes visible="yes" title=""/>
112
+      <namespaces visible="yes" title=""/>
113
+      <defines title=""/>
114
+      <typedefs title=""/>
115
+      <enums title=""/>
116
+      <functions title=""/>
117
+      <variables title=""/>
118
+      <membergroups visible="yes"/>
119
+    </memberdecl>
120
+    <detaileddescription title=""/>
121
+    <memberdef>
122
+      <inlineclasses title=""/>
123
+      <defines title=""/>
124
+      <typedefs title=""/>
125
+      <enums title=""/>
126
+      <functions title=""/>
127
+      <variables title=""/>
128
+    </memberdef>
129
+    <authorsection/>
130
+  </file>
131
+
132
+  <!-- Layout definition for a group page -->
133
+  <group>
134
+    <briefdescription visible="yes"/>
135
+    <detaileddescription title="Description"/>
136
+    <groupgraph visible="$GROUP_GRAPHS"/>
137
+    <memberdecl>
138
+      <nestedgroups visible="yes" title=""/>
139
+      <dirs visible="yes" title=""/>
140
+      <files visible="yes" title=""/>
141
+      <namespaces visible="yes" title=""/>
142
+      <classes visible="yes" title=""/>
143
+      <defines title=""/>
144
+      <typedefs title=""/>
145
+      <enums title=""/>
146
+      <enumvalues title=""/>
147
+      <functions title=""/>
148
+      <variables title=""/>
149
+      <signals title=""/>
150
+      <publicslots title=""/>
151
+      <protectedslots title=""/>
152
+      <privateslots title=""/>
153
+      <events title=""/>
154
+      <properties title=""/>
155
+      <friends title=""/>
156
+      <membergroups visible="yes"/>
157
+    </memberdecl>
158
+    <memberdef>
159
+      <pagedocs/>
160
+      <inlineclasses title=""/>
161
+      <defines title=""/>
162
+      <typedefs title=""/>
163
+      <enums title=""/>
164
+      <enumvalues title=""/>
165
+      <functions title=""/>
166
+      <variables title=""/>
167
+      <signals title=""/>
168
+      <publicslots title=""/>
169
+      <protectedslots title=""/>
170
+      <privateslots title=""/>
171
+      <events title=""/>
172
+      <properties title=""/>
173
+      <friends title=""/>
174
+    </memberdef>
175
+    <authorsection visible="yes"/>
176
+  </group>
177
+
178
+  <!-- Layout definition for a directory page -->
179
+  <directory>
180
+    <briefdescription visible="yes"/>
181
+    <directorygraph visible="yes"/>
182
+    <memberdecl>
183
+      <dirs visible="yes"/>
184
+      <files visible="yes"/>
185
+    </memberdecl>
186
+    <detaileddescription title=""/>
187
+  </directory>
188
+</doxygenlayout>

+ 303
- 0
lib/glfw/docs/build.dox View File

@@ -0,0 +1,303 @@
1
+/*!
2
+
3
+@page build Building applications
4
+
5
+@tableofcontents
6
+
7
+This is about compiling and linking applications that use GLFW.  For information on
8
+how to write such applications, start with the [introductory tutorial](@ref quick).
9
+For information on how to compile the GLFW library itself, see the @ref compile
10
+guide.
11
+
12
+This is not a tutorial on compilation or linking.  It assumes basic
13
+understanding of how to compile and link a C program as well as how to use the
14
+specific compiler of your chosen development environment.  The compilation
15
+and linking process should be explained in your C programming material and in
16
+the documentation for your development environment.
17
+
18
+@section build_include Including the GLFW header file
19
+
20
+In the source files of your application where you use OpenGL or GLFW, you should
21
+include the GLFW header file, i.e.:
22
+
23
+@code
24
+#include <GLFW/glfw3.h>
25
+@endcode
26
+
27
+The GLFW header declares the GLFW API and by default also includes the OpenGL
28
+header of your development environment, which in turn defines all the constants,
29
+types and function prototypes of the OpenGL API.
30
+
31
+The GLFW header also defines everything necessary for your OpenGL header to
32
+function.  For example, under Windows you are normally required to include
33
+`windows.h` before the OpenGL header, which would pollute your code namespace
34
+with the entire Win32 API.
35
+
36
+Instead, the GLFW header takes care of this for you, not by including
37
+`windows.h`, but by duplicating only the very few necessary parts of it.  It
38
+does this only when needed, so if `windows.h` _is_ included, the GLFW header
39
+does not try to redefine those symbols.  The reverse is not true, i.e.
40
+`windows.h` cannot cope if any of its symbols have already been defined.
41
+
42
+In other words:
43
+
44
+ - Do _not_ include the OpenGL headers yourself, as GLFW does this for you
45
+ - Do _not_ include `windows.h` or other platform-specific headers unless you
46
+   plan on using those APIs directly
47
+ - If you _do_ need to include such headers, do it _before_ including
48
+   the GLFW header and it will handle this
49
+
50
+If you are using an OpenGL extension loading library such as
51
+[glad](https://github.com/Dav1dde/glad), the extension loader header should
52
+either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
53
+(described below) should be defined.
54
+
55
+
56
+@subsection build_macros GLFW header option macros
57
+
58
+These macros may be defined before the inclusion of the GLFW header and affect
59
+its behavior.
60
+
61
+`GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler
62
+that the GLFW functions are defined in a DLL.
63
+
64
+The following macros control which OpenGL or OpenGL ES API header is included.
65
+
66
+`GLFW_INCLUDE_GLCOREARB` makes the GLFW header include the modern
67
+`GL/glcorearb.h` header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL
68
+header.
69
+
70
+`GLFW_INCLUDE_ES1` makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
71
+header instead of the regular OpenGL header.
72
+
73
+`GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h`
74
+header instead of the regular OpenGL header.
75
+
76
+`GLFW_INCLUDE_ES3` makes the GLFW header include the OpenGL ES 3.0 `GLES3/gl3.h`
77
+header instead of the regular OpenGL header.
78
+
79
+`GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h`
80
+header instead of the regular OpenGL header.
81
+
82
+`GLFW_INCLUDE_NONE` makes the GLFW header not include any OpenGL or OpenGL ES API
83
+header.  This is useful in combination with an extension loading library.
84
+
85
+If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
86
+header (`OpenGL/gl.h` on OS X) is included.
87
+
88
+`GLFW_INCLUDE_GLEXT` makes the GLFW header include the appropriate extension
89
+header for the OpenGL or OpenGL ES header selected above after and _in addition
90
+to_ that header.
91
+
92
+`GLFW_INCLUDE_GLU` makes the header include the GLU header _in addition to_ the
93
+header selected above.  This should only be used with the standard OpenGL header
94
+and only for legacy code.  GLU has been deprecated and should not be used in new
95
+code.
96
+
97
+@note GLFW does not provide any of the API headers mentioned above.  They must
98
+be provided by your development environment or your OpenGL or OpenGL ES SDK.
99
+
100
+
101
+@section build_link Link with the right libraries
102
+
103
+GLFW is essentially a wrapper of various platform-specific APIs and therefore
104
+needs to link against many different system libraries.  If you are using GLFW as
105
+a shared library / dynamic library / DLL then it takes care of these links.
106
+However, if you are using GLFW as a static library then your executable will
107
+need to link against these libraries.
108
+
109
+On Windows and OS X, the list of system libraries is static and can be
110
+hard-coded into your build environment.  See the section for your development
111
+environment below.  On Linux and other Unix-like operating systems, the list
112
+varies but can be retrieved in various ways as described below.
113
+
114
+A good general introduction to linking is
115
+[Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by
116
+David Drysdale.
117
+
118
+
119
+@subsection build_link_win32 With MinGW or Visual C++ on Windows
120
+
121
+The static version of the GLFW library is named `glfw3`.  When using this
122
+version, it is also necessary to link with some libraries that GLFW uses.
123
+
124
+When linking an application under Windows that uses the static version of GLFW,
125
+you must link with `opengl32`.  On some versions of MinGW, you must also
126
+explicitly link with `gdi32`, while other versions of MinGW include it in the
127
+set of default libraries along with other dependencies like `user32` and
128
+`kernel32`.  If you are using GLU, you must also link with `glu32`.
129
+
130
+The link library for the GLFW DLL is named `glfw3dll`.  When compiling an
131
+application that uses the DLL version of GLFW, you need to define the `GLFW_DLL`
132
+macro _before_ any inclusion of the GLFW header.  This can be done either with
133
+a compiler switch or by defining it in your source code.
134
+
135
+An application using the GLFW DLL does not need to link against any of its
136
+dependencies, but you still have to link against `opengl32` if your application
137
+uses OpenGL and `glu32` if it uses GLU.
138
+
139
+
140
+@subsection build_link_cmake_source With CMake and GLFW source
141
+
142
+With just a few changes to your `CMakeLists.txt` you can have the GLFW source
143
+tree built along with your application.
144
+
145
+Firstly, add the root directory of the GLFW source tree to your project.  This
146
+will add the `glfw` target and the necessary cache variables to your project.
147
+
148
+@code{.cmake}
149
+add_subdirectory(path/to/glfw)
150
+@endcode
151
+
152
+To be able to include the GLFW header from your code, you need to tell the
153
+compiler where to find it.
154
+
155
+@code{.cmake}
156
+include_directories(path/to/glfw/include)
157
+@endcode
158
+
159
+Once GLFW has been added to the project, the `GLFW_LIBRARIES` cache variable
160
+contains all link-time dependencies of GLFW as it is currently configured.  To
161
+link against GLFW, link against them and the `glfw` target.
162
+
163
+@code{.cmake}
164
+target_link_libraries(myapp glfw ${GLFW_LIBRARIES})
165
+@endcode
166
+
167
+Note that `GLFW_LIBRARIES` does not include GLU, as GLFW does not use it.  If
168
+your application needs GLU, you can add it to the list of dependencies with the
169
+`OPENGL_glu_LIBRARY` cache variable, which is implicitly created when the GLFW
170
+CMake files look for OpenGL.
171
+
172
+@code{.cmake}
173
+target_link_libraries(myapp glfw ${OPENGL_glu_LIBRARY} ${GLFW_LIBRARIES})
174
+@endcode
175
+
176
+
177
+@subsection build_link_cmake_pkgconfig With CMake on Unix and installed GLFW binaries
178
+
179
+CMake can import settings from pkg-config, which GLFW supports.  When you
180
+installed GLFW, the pkg-config file `glfw3.pc` was installed along with it.
181
+
182
+First you need to find the PkgConfig package.  If this fails, you may need to
183
+install the pkg-config package for your distribution.
184
+
185
+@code{.cmake}
186
+find_package(PkgConfig REQUIRED)
187
+@endcode
188
+
189
+This creates the CMake commands to find pkg-config packages.  Then you need to
190
+find the GLFW package.
191
+
192
+@code{.cmake}
193
+pkg_search_module(GLFW REQUIRED glfw3)
194
+@endcode
195
+
196
+This creates the CMake variables you need to use GLFW.  To be able to include
197
+the GLFW header, you need to tell your compiler where it is.
198
+
199
+@code{.cmake}
200
+include_directories(${GLFW_INCLUDE_DIRS})
201
+@endcode
202
+
203
+You also need to link against the correct libraries.  If you are using the
204
+shared library version of GLFW, use the `GLFW_LIBRARIES` variable.
205
+
206
+@code{.cmake}
207
+target_link_libraries(simple ${GLFW_LIBRARIES})
208
+@endcode
209
+
210
+If you are using the static library version of GLFW, use the
211
+`GLFW_STATIC_LIBRARIES` variable instead.
212
+
213
+@code{.cmake}
214
+target_link_libraries(simple ${GLFW_STATIC_LIBRARIES})
215
+@endcode
216
+
217
+
218
+@subsection build_link_pkgconfig With pkg-config on OS X or other Unix
219
+
220
+GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/),
221
+and the `glfw3.pc` pkf-config file is generated when the GLFW library is built
222
+and is installed along with it.  A pkg-config file describes all necessary
223
+compile-time and link-time flags and dependencies needed to use a library.  When
224
+they are updated or if they differ between systems, you will get the correct
225
+ones automatically.
226
+
227
+A typical compile and link command-line when using the static version of the
228
+GLFW library may look like this:
229
+
230
+@code{.sh}
231
+cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
232
+@endcode
233
+
234
+If you are using the shared version of the GLFW library, simply omit the
235
+`--static` flag.
236
+
237
+@code{.sh}
238
+cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
239
+@endcode
240
+
241
+You can also use the `glfw3.pc` file without installing it first, by using the
242
+`PKG_CONFIG_PATH` environment variable.
243
+
244
+@code{.sh}
245
+env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
246
+@endcode
247
+
248
+The dependencies do not include GLU, as GLFW does not need it.  On OS X, GLU is
249
+built into the OpenGL framework, so if you need GLU you don't need to do
250
+anything extra.  If you need GLU and are using Linux or BSD, you should add the
251
+`glu` pkg-config module.
252
+
253
+@code{.sh}
254
+cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
255
+@endcode
256
+
257
+If you are using the static version of the GLFW library, make sure you don't link statically against GLU.
258
+
259
+@code{.sh}
260
+cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`
261
+@endcode
262
+
263
+
264
+@subsection build_link_xcode With Xcode on OS X
265
+
266
+If you are using the dynamic library version of GLFW, simply add it to the
267
+project dependencies.
268
+
269
+If you are using the static library version of GLFW, add it and the Cocoa,
270
+OpenGL, IOKit, CoreVideo and Carbon frameworks to the project as dependencies.
271
+They can all be found in `/System/Library/Frameworks`.
272
+
273
+@note GLFW needs the Carbon framework only to access the current keyboard layout
274
+via the Text Input Source Services.  This is one of the non-deprecated parts of
275
+the Carbon API and the only way to access this information on OS X.
276
+
277
+
278
+@subsection build_link_osx With command-line on OS X
279
+
280
+It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when
281
+building from the command line on OS X.  That way you will get any new
282
+dependencies added automatically.  If you still wish to build manually, you need
283
+to add the required frameworks and libraries to your command-line yourself using
284
+the `-l` and `-framework` switches.
285
+
286
+If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do:
287
+
288
+@code{.sh}
289
+cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
290
+@endcode
291
+
292
+If you are using the static library, named `libglfw3.a`, substitute `-lglfw3`
293
+for `-lglfw`.
294
+
295
+Note that you do not add the `.framework` extension to a framework when linking
296
+against it from the command-line.
297
+
298
+The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
299
+special to do when using GLU.  Also note that even though your machine may have
300
+`libGL`-style OpenGL libraries, they are for use with the X Window System and
301
+will _not_ work with the OS X native version of GLFW.
302
+
303
+*/

+ 179
- 0
lib/glfw/docs/compat.dox View File

@@ -0,0 +1,179 @@
1
+/*!
2
+
3
+@page compat Standards conformance
4
+
5
+@tableofcontents
6
+
7
+This guide describes the various API extensions used by this version of GLFW.
8
+It lists what are essentially implementation details, but which are nonetheless
9
+vital knowledge for developers intending to deploy their applications on a wide
10
+range of machines.
11
+
12
+The information in this guide is not a part of GLFW API, but merely
13
+preconditions for some parts of the library to function on a given machine.  Any
14
+part of this information may change in future versions of GLFW and that will not
15
+be considered a breaking API change.
16
+
17
+
18
+@section compat_x11 X11 extensions, protocols and IPC standards
19
+
20
+As GLFW uses Xlib directly, without any intervening toolkit
21
+library, it has sole responsibility for interacting well with the many and
22
+varied window managers in use on Unix-like systems.  In order for applications
23
+and window managers to work well together, a number of standards and
24
+conventions have been developed that regulate behavior outside the scope of the
25
+X11 API; most importantly the
26
+[Inter-Client Communication Conventions Manual](http://www.tronche.com/gui/x/icccm/)
27
+(ICCCM) and
28
+[Extended Window Manager Hints](http://standards.freedesktop.org/wm-spec/wm-spec-latest.html)
29
+(EWMH) standards.
30
+
31
+GLFW uses the `_MOTIF_WM_HINTS` window property to support borderless windows.
32
+If the running window manager does not support this property, the
33
+`GLFW_DECORATED` hint will have no effect.
34
+
35
+GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user
36
+attempting to close the GLFW window.  If the running window manager does not
37
+support this protocol, the close callback will never be called.
38
+
39
+GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify
40
+the user when the application has stopped responding, i.e. when it has ceased to
41
+process events.  If the running window manager does not support this protocol,
42
+the user will not be notified if the application locks up.
43
+
44
+GLFW uses the EWMH `_NET_WM_STATE_FULLSCREEN` window state to tell the window
45
+manager to make the GLFW window full screen.  If the running window manager does
46
+not support this state, full screen windows may not work properly.  GLFW has
47
+a fallback code path in case this state is unavailable, but every window manager
48
+behaves slightly differently in this regard.
49
+
50
+GLFW uses the EWMH `_NET_WM_BYPASS_COMPOSITOR` window property to tell a
51
+compositing window manager to un-redirect full screen GLFW windows.  If the
52
+running window manager uses compositing but does not support this property then
53
+additional copying may be performed for each buffer swap of full screen windows.
54
+
55
+GLFW uses the
56
+[clipboard manager protocol](http://www.freedesktop.org/wiki/ClipboardManager/)
57
+to push a clipboard string (i.e. selection) owned by a GLFW window about to be
58
+destroyed to the clipboard manager.  If there is no running clipboard manager,
59
+the clipboard string will be unavailable once the window has been destroyed.
60
+
61
+GLFW uses the
62
+[X drag-and-drop protocol](http://www.freedesktop.org/wiki/Specifications/XDND/)
63
+to provide file drop events.  If the application originating the drag does not
64
+support this protocol, drag and drop will not work.
65
+
66
+GLFW uses the XInput 2 extension to provide sub-pixel cursor motion events.  If
67
+the running X server does not support this version of this extension, cursor
68
+motion will be snapped to the pixel grid.
69
+
70
+GLFW uses the XRandR 1.3 extension to provide multi-monitor support.  If the
71
+running X server does not support this version of this extension, multi-monitor
72
+support will not function and only a single, desktop-spanning monitor will be
73
+reported.
74
+
75
+GLFW uses the XRandR 1.3 and Xf86vidmode extensions to provide gamma ramp
76
+support.  If the running X server does not support either or both of these
77
+extensions, gamma ramp support will not function.
78
+
79
+GLFW uses the Xkb extension and detectable auto-repeat to provide keyboard
80
+input.  If the running X server does not support this extension, a non-Xkb
81
+fallback path is used.
82
+
83
+
84
+@section compat_glx GLX extensions
85
+
86
+The GLX API is the default API used to create OpenGL contexts on Unix-like
87
+systems using the X Window System.
88
+
89
+GLFW uses the GLX 1.3 `GLXFBConfig` functions to enumerate and select framebuffer pixel
90
+formats.  If GLX 1.3 is not supported, @ref glfwInit will fail.
91
+
92
+GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
93
+`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
94
+(or _vsync_), in that order of preference.  Where none of these extension are
95
+available, calling @ref glfwSwapInterval will have no effect.
96
+
97
+GLFW uses the `GLX_ARB_multisample` extension to create contexts with
98
+multisampling anti-aliasing.  Where this extension is unavailable, the
99
+`GLFW_SAMPLES` hint will have no effect.
100
+
101
+GLFW uses the `GLX_ARB_create_context` extension when available, even when
102
+creating OpenGL contexts of version 2.1 and below.  Where this extension is
103
+unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
104
+hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
105
+will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
106
+`GLFW_OPENGL_FORWARD_COMPAT` hints to `GL_TRUE` will cause @ref
107
+glfwCreateWindow to fail.
108
+
109
+GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for
110
+context profiles.  Where this extension is unavailable, setting the
111
+`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE`, or setting
112
+`GLFW_CLIENT_API` to anything but `GLFW_OPENGL_API` will cause @ref
113
+glfwCreateWindow to fail.
114
+
115
+GLFW uses the `GLX_ARB_context_flush_control` extension to provide control over
116
+whether a context is flushed when it is released (made non-current).  Where this
117
+extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
118
+effect and the context will always be flushed when released.
119
+
120
+@section compat_wgl WGL extensions
121
+
122
+The WGL API is used to create OpenGL contexts on Microsoft Windows and other
123
+implementations of the Win32 API, such as Wine.
124
+
125
+GLFW uses either the `WGL_EXT_extension_string` or the
126
+`WGL_ARB_extension_string` extension to check for the presence of all other WGL
127
+extensions listed below.  If both are available, the EXT one is preferred.  If
128
+neither is available, no other extensions are used and many GLFW features
129
+related to context creation will have no effect or cause errors when used.
130
+
131
+GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
132
+synchronization (or _vsync_).  Where this extension is unavailable, calling @ref
133
+glfwSwapInterval will have no effect.
134
+
135
+GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
136
+create contexts with multisampling anti-aliasing.  Where these extensions are
137
+unavailable, the `GLFW_SAMPLES` hint will have no effect.
138
+
139
+GLFW uses the `WGL_ARB_create_context` extension when available, even when
140
+creating OpenGL contexts of version 2.1 and below.  Where this extension is
141
+unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
142
+hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
143
+will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
144
+`GLFW_OPENGL_FORWARD_COMPAT` hints to `GL_TRUE` will cause @ref
145
+glfwCreateWindow to fail.
146
+
147
+GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for
148
+context profiles.  Where this extension is unavailable, setting the
149
+`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE` will cause
150
+@ref glfwCreateWindow to fail.
151
+
152
+GLFW uses the `WGL_ARB_context_flush_control` extension to provide control over
153
+whether a context is flushed when it is released (made non-current).  Where this
154
+extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
155
+effect and the context will always be flushed when released.
156
+
157
+@section compat_osx OpenGL 3.2 and later on OS X
158
+
159
+Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then
160
+only forward-compatible, core profile contexts are supported.  Support for
161
+OpenGL 4.1 was introduced with OS X 10.9, also limited to forward-compatible,
162
+core profile contexts.  There is also still no mechanism for requesting debug
163
+contexts.  Versions of Mac OS X earlier than 10.7 support at most OpenGL
164
+version 2.1.
165
+
166
+Because of this, on OS X 10.7 and later, the `GLFW_CONTEXT_VERSION_MAJOR` and
167
+`GLFW_CONTEXT_VERSION_MINOR` hints will cause @ref glfwCreateWindow to fail if
168
+given version 3.0 or 3.1, the `GLFW_OPENGL_FORWARD_COMPAT` hint must be set to
169
+`GL_TRUE` and the `GLFW_OPENGL_PROFILE` hint must be set to
170
+`GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts and the
171
+`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
172
+
173
+Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and
174
+`GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 2.1,
175
+setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to
176
+a non-default value will cause @ref glfwCreateWindow to fail and the
177
+`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
178
+
179
+*/

+ 315
- 0
lib/glfw/docs/compile.dox View File

@@ -0,0 +1,315 @@
1
+/*!
2
+
3
+@page compile Compiling GLFW
4
+
5
+@tableofcontents
6
+
7
+This is about compiling the GLFW library itself.  For information on how to
8
+build applications that use GLFW, see the @ref build guide.
9
+
10
+
11
+@section compile_cmake Using CMake
12
+
13
+GLFW uses [CMake](http://www.cmake.org/) to generate project files or makefiles
14
+for a particular development environment.  If you are on a Unix-like system such
15
+as Linux or FreeBSD or have a package system like Fink, MacPorts, Cygwin or
16
+Homebrew, you can simply install its CMake package.  If not, you can download
17
+installers for Windows and OS X from the [CMake website](http://www.cmake.org/).
18
+
19
+@note CMake only generates project files or makefiles.  It does not compile the
20
+actual GLFW library.  To compile GLFW, first generate these files and then use
21
+them in your chosen development environment to compile the actual GLFW library.
22
+
23
+
24
+@subsection compile_deps Dependencies
25
+
26
+Once you have installed CMake, make sure that all other dependencies are
27
+available.  On some platforms, GLFW needs a few additional packages to be
28
+installed.  See the section for your chosen platform and development environment
29
+below.
30
+
31
+
32
+@subsubsection compile_deps_msvc Dependencies for Visual C++ on Windows
33
+
34
+The Microsoft Platform SDK that is installed along with Visual C++ already
35
+contains all the necessary headers, link libraries and tools except for CMake.
36
+Move on to @ref compile_generate.
37
+
38
+
39
+@subsubsection compile_deps_mingw Dependencies for MinGW or MinGW-w64 on Windows
40
+
41
+Both the MinGW and the MinGW-w64 packages already contain all the necessary
42
+headers, link libraries and tools except for CMake.  Move on to @ref
43
+compile_generate.
44
+
45
+
46
+@subsubsection compile_deps_mingw_cross Dependencies for MinGW or MinGW-w64 cross-compilation
47
+
48
+Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages.  For
49
+example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
50
+for 32- and 64-bit version of MinGW-w64, while Debian GNU/Linux and derivatives
51
+like Ubuntu have the `mingw-w64` package for both.
52
+
53
+GLFW has CMake toolchain files in the `CMake/` directory that allow for easy
54
+cross-compilation of Windows binaries.  To use these files you need to add a
55
+special parameter when generating the project files or makefiles:
56
+
57
+@code{.sh}
58
+cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
59
+@endcode
60
+
61
+The exact toolchain file to use depends on the prefix used by the MinGW or
62
+MinGW-w64 binaries on your system.  You can usually see this in the /usr
63
+directory.  For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages
64
+have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
65
+invocation would be:
66
+
67
+@code{.sh}
68
+cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
69
+@endcode
70
+
71
+For more details see the article
72
+[CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on
73
+the CMake wiki.
74
+
75
+Once you have this set up, move on to @ref compile_generate.
76
+
77
+
78
+@subsubsection compile_deps_xcode Dependencies for Xcode on OS X
79
+
80
+Xcode comes with all necessary tools except for CMake.  The required headers
81
+and libraries are included in the core OS X frameworks.  Xcode can be downloaded
82
+from the Mac App Store or from the ADC Member Center.
83
+
84
+Once you have Xcode installed, move on to @ref compile_generate.
85
+
86
+
87
+@subsubsection compile_deps_x11 Dependencies for Linux and X11
88
+
89
+To compile GLFW for X11, you need to have the X11 and OpenGL header packages
90
+installed, as well as the basic development tools like GCC and make.  For
91
+example, on Ubuntu and other distributions based on Debian GNU/Linux, you need
92
+to install the `xorg-dev` and `libglu1-mesa-dev` packages.  The former pulls in
93
+all X.org header packages and the latter pulls in the Mesa OpenGL and GLU
94
+packages.  GLFW itself doesn't need or use GLU, but some of the examples do.
95
+Note that using header files and libraries from Mesa during compilation
96
+_will not_ tie your binaries to the Mesa implementation of OpenGL.
97
+
98
+Once you have installed the necessary packages, move on to @ref
99
+compile_generate.
100
+
101
+
102
+@subsection compile_generate Generating build files with CMake
103
+
104
+Once you have all necessary dependencies it is time to generate the project
105
+files or makefiles for your development environment.  CMake needs to know two
106
+paths for this: the path to the _root_ directory of the GLFW source tree (i.e.
107
+_not_ the `src` subdirectory) and the target path for the generated files and
108
+compiled binaries.  If these are the same, it is called an in-tree build,
109
+otherwise it is called an out-of-tree build.
110
+
111
+One of several advantages of out-of-tree builds is that you can generate files
112
+and compile for different development environments using a single source tree.
113
+
114
+@note This section is about generating the project files or makefiles necessary
115
+to compile the GLFW library, not about compiling the actual library.
116
+
117
+
118
+@subsubsection compile_generate_cli Generating files with the CMake command-line tool
119
+
120
+To make an in-tree build, enter the _root_ directory of the GLFW source tree
121
+(i.e. _not_ the `src` subdirectory) and run CMake.  The current directory is
122
+used as target path, while the path provided as an argument is used to find the
123
+source tree.
124
+
125
+@code{.sh}
126
+cd <glfw-root-dir>
127
+cmake .
128
+@endcode
129
+
130
+To make an out-of-tree build, make another directory, enter it and run CMake
131
+with the (relative or absolute) path to the root of the source tree as an
132
+argument.
133
+
134
+@code{.sh}
135
+cd <glfw-root-dir>
136
+mkdir build
137
+cd build
138
+cmake ..
139
+@endcode
140
+
141
+Once you have generated the project files or makefiles for your chosen
142
+development environment, move on to @ref compile_compile.
143
+
144
+
145
+@subsubsection compile_generate_gui Generating files with the CMake GUI
146
+
147
+If you are using the GUI version, choose the root of the GLFW source tree as
148
+source location and the same directory or another, empty directory as the
149
+destination for binaries.  Choose _Configure_, change any options you wish to,
150
+_Configure_ again to let the changes take effect and then _Generate_.
151
+
152
+Once you have generated the project files or makefiles for your chosen
153
+development environment, move on to @ref compile_compile.
154
+
155
+
156
+@subsection compile_compile Compiling the library
157
+
158
+You should now have all required dependencies and the project files or makefiles
159
+necessary to compile GLFW.  Go ahead and compile the actual GLFW library with
160
+these files, as you would with any other project.
161
+
162
+Once the GLFW library is compiled, you are ready to build your applications,
163
+linking it to the GLFW library.  See the @ref build guide for more information.
164
+
165
+
166
+@subsection compile_options CMake options
167
+
168
+The CMake files for GLFW provide a number of options, although not all are
169
+available on all supported platforms.  Some of these are de facto standards
170
+among projects using CMake and so have no `GLFW_` prefix.
171
+
172
+If you are using the GUI version of CMake, these are listed and can be changed
173
+from there.  If you are using the command-line version, use the `ccmake` tool.
174
+Some package systems like Ubuntu and other distributions based on Debian
175
+GNU/Linux have this tool in a separate `cmake-curses-gui` package.
176
+
177
+
178
+@subsubsection compile_options_shared Shared CMake options
179
+
180
+`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
181
+library or as a DLL / shared library / dynamic library.
182
+
183
+`LIB_SUFFIX` affects where the GLFW shared /dynamic library is installed.  If it
184
+is empty, it is installed to `${CMAKE_INSTALL_PREFIX}/lib`.  If it is set to
185
+`64`, it is installed to `${CMAKE_INSTALL_PREFIX}/lib64`.
186
+
187
+`GLFW_CLIENT_LIBRARY` determines which client API library to use.  If set to
188
+`opengl` the OpenGL library is used, if set to `glesv1` for the OpenGL ES 1.x
189
+library is used, or if set to `glesv2` the OpenGL ES 2.0 library is used.  The
190
+selected library and its header files must be present on the system for this to
191
+work.
192
+
193
+`GLFW_BUILD_EXAMPLES` determines whether the GLFW examples are built
194
+along with the library.
195
+
196
+`GLFW_BUILD_TESTS` determines whether the GLFW test programs are
197
+built along with the library.
198
+
199
+`GLFW_BUILD_DOCS` determines whether the GLFW documentation is built along with
200
+the library.
201
+
202
+
203
+@subsubsection compile_options_osx OS X specific CMake options
204
+
205
+`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
206
+directory of bundled applications to the `Contents/Resources` directory.
207
+
208
+`GLFW_USE_MENUBAR` determines whether the first call to
209
+`glfwCreateWindow` sets up a minimal menu bar.
210
+
211
+`GLFW_USE_RETINA` determines whether windows will use the full resolution of
212
+Retina displays.
213
+
214
+`GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries.
215
+
216
+
217
+@subsubsection compile_options_win32 Windows specific CMake options
218
+
219
+`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the
220
+static library version of the Visual C++ runtime library.  If set to `ON`, the
221
+DLL version of the Visual C++ library is used.  It is recommended to set this to
222
+`ON`, as this keeps the executable smaller and benefits from security and bug
223
+fix updates of the Visual C++ runtime.
224
+
225
+`GLFW_USE_DWM_SWAP_INTERVAL` determines whether the swap interval is set even
226
+when DWM compositing is enabled.  If this is `ON`, the swap interval is set even
227
+if DWM is enabled.  It is recommended to set this to `OFF`, as doing otherwise
228
+can lead to severe jitter.
229
+
230
+`GLFW_USE_OPTIMUS_HPG` determines whether to export the `NvOptimusEnablement`
231
+symbol, which forces the use of the high-performance GPU on Nvidia Optimus
232
+systems.  This symbol needs to be exported by the EXE to be detected by the
233
+driver, so the override will not work if GLFW is built as a DLL.  See _Enabling
234
+High Performance Graphics Rendering on Optimus Systems_ for more details.
235
+
236
+
237
+@subsubsection compile_options_egl EGL specific CMake options
238
+
239
+`GLFW_USE_EGL` determines whether to use EGL instead of the platform-specific
240
+context creation API.  Note that EGL is not yet provided on all supported
241
+platforms.
242
+
243
+
244
+@section compile_manual Compiling GLFW manually
245
+
246
+If you wish to compile GLFW without its CMake build environment then you will
247
+have to do at least some of the platform detection yourself.  GLFW needs
248
+a number of configuration macros to be defined in order to know what it's being
249
+compiled for and has many optional, platform-specific ones for various features.
250
+
251
+When building with CMake, the `glfw_config.h` configuration header is generated
252
+based on the current platform and CMake options.  The GLFW CMake environment
253
+defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by
254
+`internal.h`.  Without this macro, GLFW will expect the necessary configuration
255
+macros to be defined on the command-line.
256
+
257
+Three macros _must_ be defined when compiling GLFW: one selecting the window
258
+creation API, one selecting the context creation API and one client library.
259
+Exactly one of each kind must be defined for GLFW to compile and link.
260
+
261
+The window creation API is used to create windows, handle input, monitors, gamma
262
+ramps and clipboard.  The options are:
263
+
264
+ - `_GLFW_COCOA` to use the Cocoa frameworks
265
+ - `_GLFW_WIN32` to use the Win32 API
266
+ - `_GLFW_X11` to use the X Window System
267
+ - `_GLFW_WAYLAND` to use the Wayland API (experimental and incomplete)
268
+ - `_GLFW_MIR` to use the Mir API (experimental and incomplete)
269
+
270
+The context creation API is used to enumerate pixel formats / framebuffer
271
+configurations and to create contexts.  The options are:
272
+
273
+ - `_GLFW_NSGL` to use the Cocoa OpenGL framework
274
+ - `_GLFW_WGL` to use the Win32 WGL API
275
+ - `_GLFW_GLX` to use the X11 GLX API
276
+ - `_GLFW_EGL` to use the EGL API
277
+
278
+Wayland and Mir both require the EGL backend.
279
+
280
+The client library is the one providing the OpenGL or OpenGL ES API, which is
281
+used by GLFW to probe the created context.  This is not the same thing as the
282
+client API, as many desktop OpenGL client libraries now expose the OpenGL ES API
283
+through extensions.  The options are:
284
+
285
+ - `_GLFW_USE_OPENGL` for the desktop OpenGL (opengl32.dll, libGL.so or
286
+   OpenGL.framework)
287
+ - `_GLFW_USE_GLESV1` for OpenGL ES 1.x (experimental)
288
+ - `_GLFW_USE_GLESV2` for OpenGL ES 2.x (experimental)
289
+
290
+Note that `_GLFW_USE_GLESV1` and `_GLFW_USE_GLESV2` may only be used with EGL,
291
+as the other context creation APIs do not interface with OpenGL ES client
292
+libraries.
293
+
294
+If you are building GLFW as a shared library / dynamic library / DLL then you
295
+must also define `_GLFW_BUILD_DLL`.  Otherwise, you may not define it.
296
+
297
+If you are using the X11 window creation API then you _must_ also select an entry
298
+point retrieval mechanism.
299
+
300
+ - `_GLFW_HAS_GLXGETPROCADDRESS` to use `glXGetProcAddress` (recommended)
301
+ - `_GLFW_HAS_GLXGETPROCADDRESSARB` to use `glXGetProcAddressARB` (legacy)
302
+ - `_GLFW_HAS_GLXGETPROCADDRESSEXT` to use `glXGetProcAddressEXT` (legacy)
303
+ - `_GLFW_HAS_DLOPEN` to do manual retrieval with `dlopen` (fallback)
304
+
305
+If you are using the Cocoa window creation API, the following options are
306
+available:
307
+
308
+ - `_GLFW_USE_CHDIR` to `chdir` to the `Resources` subdirectory of the
309
+   application bundle during @ref glfwInit (recommended)
310
+ - `_GLFW_USE_MENUBAR` to create and populate the menu bar when the first window
311
+   is created (recommended)
312
+ - `_GLFW_USE_RETINA` to have windows use the full resolution of Retina displays
313
+   (recommended)
314
+
315
+*/

+ 329
- 0
lib/glfw/docs/context.dox View File

@@ -0,0 +1,329 @@
1
+/*!
2
+
3
+@page context Context guide
4
+
5
+@tableofcontents
6
+
7
+This guide introduces the OpenGL and OpenGL ES context related functions of
8
+GLFW.  There are also guides for the other areas of the GLFW API.
9
+
10
+ - @ref intro
11
+ - @ref window
12
+ - @ref monitor
13
+ - @ref input
14
+
15
+
16
+@section context_object Context objects
17
+
18
+A window object encapsulates both a top-level window and an OpenGL or OpenGL ES
19
+context.  It is created with @ref glfwCreateWindow and destroyed with @ref
20
+glfwDestroyWindow or @ref glfwTerminate.  See @ref window_creation for more
21
+information.
22
+
23
+As the window and context are inseparably linked, the window object also serves
24
+as the context handle.
25
+
26
+To test the creation of various kinds of contexts and see their properties, run
27
+the `glfwinfo` test program.
28
+
29
+
30
+@subsection context_hints Context creation hints
31
+
32
+There are a number of hints, specified using @ref glfwWindowHint, related to
33
+what kind of context is created.  See
34
+[context related hints](@ref window_hints_ctx) in the window guide.
35
+
36
+
37
+@subsection context_sharing Context object sharing
38
+
39
+When creating a window and its OpenGL or OpenGL ES context with @ref
40
+glfwCreateWindow, you can specify another window whose context the new one
41
+should share its objects (textures, vertex and element buffers, etc.) with.
42
+
43
+@code
44
+GLFWwindow* second_window = glfwCreateWindow(640, 480, "Second Window", NULL, first_window);
45
+@endcode
46
+
47
+Object sharing is implemented by the operating system and graphics driver.  On
48
+platforms where it is possible to choose which types of objects are shared, GLFW
49
+requests that all types are shared.
50
+
51
+See the relevant chapter of the [OpenGL](https://www.opengl.org/registry/) or
52
+[OpenGL ES](http://www.khronos.org/opengles/) reference documents for more
53
+information.  The name and number of this chapter unfortunately varies between
54
+versions and APIs, but has at times been named _Shared Objects and Multiple
55
+Contexts_.
56
+
57
+GLFW comes with a simple object sharing test program called `sharing`.
58
+
59
+
60
+@subsection context_offscreen Offscreen contexts
61
+
62
+GLFW doesn't support creating contexts without an associated window.  However,
63
+contexts with hidden windows can be created with the
64
+[GLFW_VISIBLE](@ref window_hints_wnd) window hint.
65
+
66
+@code
67
+glfwWindowHint(GLFW_VISIBLE, GL_FALSE);
68
+
69
+GLFWwindow* offscreen_context = glfwCreateWindow(640, 480, "", NULL, NULL);
70
+@endcode
71
+
72
+The window never needs to be shown and its context can be used as a plain
73
+offscreen context.  Depending on the window manager, the size of a hidden
74
+window's framebuffer may not be usable or modifiable, so framebuffer
75
+objects are recommended for rendering with such contexts.
76
+
77
+__OS X:__ The first time a window is created the menu bar is populated with
78
+common commands like Hide, Quit and About.  This is not desirable for example
79
+when writing a command-line only application.  The menu bar setup can be
80
+disabled with a [compile-time option](@ref compile_options_osx).
81
+
82
+
83
+@section context_current Current context
84
+
85
+Before you can make OpenGL or OpenGL ES calls, you need to have a current
86
+context of the correct type.  A context can only be current for a single thread
87
+at a time, and a thread can only have a single context current at a time.
88
+
89
+The context of a window is made current with @ref glfwMakeContextCurrent.
90
+
91
+@code
92
+glfwMakeContextCurrent(window);
93
+@endcode
94
+
95
+The window of the current context is returned by @ref glfwGetCurrentContext.
96
+
97
+@code
98
+GLFWwindow* window = glfwGetCurrentContext();
99
+@endcode
100
+
101
+The following GLFW functions require a context to be current.  Calling any these
102
+functions without a current context will generate a @ref GLFW_NO_CURRENT_CONTEXT
103
+error.
104
+
105
+ - @ref glfwSwapInterval
106
+ - @ref glfwExtensionSupported
107
+ - @ref glfwGetProcAddress
108
+
109
+
110
+@section context_swap Buffer swapping
111
+
112
+Buffer swapping is part of the window and framebuffer, not the context.  See
113
+@ref buffer_swap.
114
+
115
+
116
+@section context_glext OpenGL and OpenGL ES extensions
117
+
118
+One of the benefits of OpenGL and OpenGL ES are their extensibility.
119
+Hardware vendors may include extensions in their implementations that extend the
120
+API before that functionality is included in a new version of the OpenGL or
121
+OpenGL ES specification, and some extensions are never included and remain
122
+as extensions until they become obsolete.
123
+
124
+An extension is defined by:
125
+
126
+- An extension name (e.g. `GL_ARB_debug_output`)
127
+- New OpenGL tokens (e.g. `GL_DEBUG_SEVERITY_HIGH_ARB`)
128
+- New OpenGL functions (e.g. `glGetDebugMessageLogARB`)
129
+
130
+Note the `ARB` affix, which stands for Architecture Review Board and is used
131
+for official extensions.  The extension above was created by the ARB, but there
132
+are many different affixes, like `NV` for Nvidia and `AMD` for, well, AMD.  Any
133
+group may also use the generic `EXT` affix.  Lists of extensions, together with
134
+their specifications, can be found at the
135
+[OpenGL Registry](http://www.opengl.org/registry/) and
136
+[OpenGL ES Registry](https://www.khronos.org/registry/gles/).
137
+
138
+
139
+@subsection context_glext_auto Loading extension with a loader library
140
+
141
+An extension loader library is the easiest and best way to access both OpenGL and
142
+OpenGL ES extensions and modern versions of the core OpenGL or OpenGL ES APIs.
143
+They will take care of all the details of declaring and loading everything you
144
+need.  One such library is [glad](https://github.com/Dav1dde/glad) and there are
145
+several others.  
146
+
147
+The following example will use glad but all extension loader libraries work
148
+similarly.
149
+
150
+First you need to generate the source files using the glad Python script.  This
151
+example generates a loader for any version of OpenGL, which is the default for
152
+both GLFW and glad, but loaders for OpenGL ES, as well as loaders for specific
153
+API versions and extension sets can be generated.  The generated files are
154
+written to the `output` directory.
155
+
156
+@code{.sh}
157
+python main.py --generator c --no-loader --out-path output
158
+@endcode
159
+
160
+The `--no-loader` option is added because GLFW already provides a function for
161
+loading OpenGL and OpenGL ES function pointers and glad can call this instead of
162
+having to implement its own.  There are several other command-line options as
163
+well.  See the glad documentation for details.
164
+
165
+Add the generated `output/src/glad.c`, `output/include/glad/glad.h` and
166
+`output/include/KHR/khrplatform.h` files to your build.  Then you need to
167
+include the glad header file, which will replace the OpenGL header of your
168
+development environment.  By including the glad header before the GLFW header,
169
+it suppresses the development environment's OpenGL or OpenGL ES header.
170
+
171
+@code
172
+#include <glad/glad.h>
173
+#include <GLFW/glfw3.h>
174
+@endcode
175
+
176
+Finally you need to initialize glad once you have a suitable current context.
177
+
178
+@code
179
+window = glfwCreateWindow(640, 480, "My Window", NULL, NULL);
180
+if (!window)
181
+{
182
+    ...
183
+}
184
+
185
+glfwMakeContextCurrent(window);
186
+
187
+gladLoadGLLoader((GLADloadproc) glfwGetProcAddress);
188
+@endcode
189
+
190
+Once glad has been loaded, you have access to all OpenGL core and extension
191
+functions supported by both the context you created and the glad loader you
192
+generated and you are ready to start rendering.
193
+
194
+You can specify a minimum required OpenGL or OpenGL ES version with
195
+[context hints](@ref window_hints_ctx).  If your needs are more complex, you can
196
+check the actual OpenGL or OpenGL ES version with
197
+[context attributes](@ref window_attribs_ctx), or you can check whether
198
+a specific version is supported by the current context with the
199
+`GLAD_GL_VERSION_x_x` booleans.
200
+
201
+@code
202
+if (GLAD_GL_VERSION_3_2)
203
+{
204
+    // Call OpenGL 3.2+ specific code
205
+}
206
+@endcode
207
+
208
+To check whether a specific extension is supported, use the `GLAD_GL_xxx`
209
+booleans.
210
+
211
+@code
212
+if (GLAD_GL_ARB_debug_output)
213
+{
214
+    // Use GL_ARB_debug_output
215
+}
216
+@endcode
217
+
218
+
219
+@subsection context_glext_manual Loading extensions manually
220
+
221
+__Do not use this technique__ unless it is absolutely necessary.  An
222
+[extension loader library](@ref context_glext_auto) will save you a ton of
223
+tedious, repetitive, error prone work.
224
+
225
+To use a certain extension, you must first check whether the context supports
226
+that extension and then, if it introduces new functions, retrieve the pointers
227
+to those functions.  GLFW provides @ref glfwExtensionSupported and @ref
228
+glfwGetProcAddress for manual loading of extensions and new API functions.
229
+
230
+This section will demonstrate manual loading of OpenGL extensions.  The loading
231
+of OpenGL ES extensions is identical except for the name of the extension header.
232
+
233
+
234
+@subsubsection context_glext_header The glext.h header
235
+
236
+The `glext.h` extension header is a continually updated file that defines the
237
+interfaces for all OpenGL extensions.  The latest version of this can always be
238
+found at the [OpenGL Registry](http://www.opengl.org/registry/).  There are also
239
+extension headers for the various versions of OpenGL ES at the
240
+[OpenGL ES Registry](https://www.khronos.org/registry/gles/).  It it strongly
241
+recommended that you use your own copy of the extension header, as the one
242
+included in your development environment may be several years out of date and
243
+may not include the extensions you wish to use.
244
+
245
+The header defines function pointer types for all functions of all extensions it
246
+supports.  These have names like `PFNGLGETDEBUGMESSAGELOGARBPROC` (for
247
+`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` (pointer
248
+to function) and `PROC` (procedure) are added to the ends.
249
+
250
+To include the extension header, define [GLFW_INCLUDE_GLEXT](@ref build_macros)
251
+before including the GLFW header.
252
+
253
+@code
254
+#define GLFW_INCLUDE_GLEXT
255
+#include <GLFW/glfw3.h>
256
+@endcode
257
+
258
+
259
+@subsubsection context_glext_string Checking for extensions
260
+
261
+A given machine may not actually support the extension (it may have older
262
+drivers or a graphics card that lacks the necessary hardware features), so it
263
+is necessary to check at run-time whether the context supports the extension.
264
+This is done with @ref glfwExtensionSupported.
265
+
266
+@code
267
+if (glfwExtensionSupported("GL_ARB_debug_output"))
268
+{
269
+    // The extension is supported by the current context
270
+}
271
+@endcode
272
+
273
+The argument is a null terminated ASCII string with the extension name.  If the
274
+extension is supported, @ref glfwExtensionSupported returns `GL_TRUE`, otherwise
275
+it returns `GL_FALSE`.
276
+
277
+
278
+@subsubsection context_glext_proc Fetching function pointers
279
+
280
+Many extensions, though not all, require the use of new OpenGL functions.
281
+These functions often do not have entry points in the client API libraries of
282
+your operating system, making it necessary to fetch them at run time.  You can
283
+retrieve pointers to these functions with @ref glfwGetProcAddress.
284
+
285
+@code
286
+PFNGLGETDEBUGMESSAGELOGARBPROC pfnGetDebugMessageLog = glfwGetProcAddress("glGetDebugMessageLogARB");
287
+@endcode
288
+
289
+In general, you should avoid giving the function pointer variables the (exact)
290
+same name as the function, as this may confuse your linker.  Instead, you can
291
+use a different prefix, like above, or some other naming scheme.
292
+
293
+Now that all the pieces have been introduced, here is what they might look like
294
+when used together.
295
+
296
+@code
297
+#define GLFW_INCLUDE_GLEXT
298
+#include <GLFW/glfw3.h>
299
+
300
+#define glGetDebugMessageLogARB pfnGetDebugMessageLog
301
+PFNGLGETDEBUGMESSAGELOGARBPROC pfnGetDebugMessageLog;
302
+
303
+// Flag indicating whether the extension is supported
304
+int has_ARB_debug_output = 0;
305
+
306
+void load_extensions(void)
307
+{
308
+    if (glfwExtensionSupported("GL_ARB_debug_output"))
309
+    {
310
+        pfnGetDebugMessageLog = (PFNGLGETDEBUGMESSAGELOGARBPROC) glfwGetProcAddress("glGetDebugMessageLogARB");
311
+        if (pfnGetDebugMessageLog)
312
+        {
313
+            // Both the extension name and the function pointer are present
314
+            has_ARB_debug_output = 1;
315
+        }
316
+    }
317
+}
318
+
319
+void some_function(void)
320
+{
321
+    if (has_ARB_debug_output)
322
+    {
323
+        // Now the extension function can be called as usual
324
+        glGetDebugMessageLogARB(...);
325
+    }
326
+}
327
+@endcode
328
+
329
+*/

+ 1
- 0
lib/glfw/docs/extra.css
File diff suppressed because it is too large
View File


+ 370
- 0
lib/glfw/docs/extra.less View File

@@ -0,0 +1,370 @@
1
+// NOTE: Please use this file to perform modifications on default style sheets.
2
+//
3
+// You need to install a few Ruby gems to generate extra.css from this file:
4
+// gem install less therubyracer
5
+//
6
+// Run this command to regenerate extra.css after you're finished with changes:
7
+// lessc --compress extra.less > extra.css
8
+//
9
+// Alternatively you can use online services to regenerate extra.css.
10
+
11
+
12
+// Default text color for page contents
13
+@default-text-color: hsl(0,0%,30%);
14
+
15
+// Page header, footer, table rows, inline codes and definition lists
16
+@header-footer-background-color: hsl(0,0%,95%);
17
+
18
+// Page header, footer links and navigation bar background
19
+@header-footer-link-color: hsl(0,0%,40%);
20
+
21
+// Doxygen navigation bar links
22
+@navbar-link-color: @header-footer-background-color;
23
+
24
+// Page content background color
25
+@content-background-color: hsl(0,0%,100%);
26
+
27
+// Bold, italic, h1, h2, ... and table of contents
28
+@heading-color: hsl(0,0%,10%);
29
+
30
+// Function, enum and macro definition separator
31
+@def-separator-color: @header-footer-background-color;
32
+
33
+// Base color hue
34
+@base-hue: 24;
35
+
36
+// Default color used for links
37
+@default-link-color: hsl(@base-hue,100%,50%);
38
+
39
+// Doxygen navigation bar active tab
40
+@tab-text-color: hsl(0,0%,100%);
41
+@tab-background-color1: @default-link-color;
42
+@tab-background-color2: lighten(spin(@tab-background-color1, 10), 10%);
43
+
44
+// Table borders
45
+@default-border-color: @default-link-color;
46
+
47
+// Table header
48
+@table-text-color: @tab-text-color;
49
+@table-background-color1: @tab-background-color1;
50
+@table-background-color2: @tab-background-color2;
51
+
52
+// Table of contents, data structure index and prototypes
53
+@toc-background-color1: hsl(0,0%,90%);
54
+@toc-background-color2: lighten(@toc-background-color1, 5%);
55
+
56
+// Function prototype parameters color
57
+@prototype-param-color: darken(@default-link-color, 25%);
58
+
59
+// Message box color: note, pre, post and invariant
60
+@box-note-color: hsl(103,80%,85%);
61
+
62
+// Message box color: warning and attention
63
+@box-warning-color: hsl(34,80%,85%);
64
+
65
+// Message box color: deprecated and bug
66
+@box-bug-color: hsl(333,80%,85%);
67
+
68
+// Message box color: todo and test
69
+@box-todo-color: hsl(200,80%,85%);
70
+
71
+// Message box helper function
72
+.message-box(@base-color) {
73
+	background:linear-gradient(to bottom,lighten(@base-color, 5%) 0%,@base-color 100%);
74
+	box-shadow:inset 0 0 32px darken(@base-color, 5%);
75
+	color:darken(@base-color, 67%);
76
+	border:2px solid desaturate(darken(@base-color, 10%), 20%);
77
+}
78
+
79
+
80
+#navrow1,#navrow2,#navrow3,#navrow4,.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a,.memdoc,dl.reflist dd,div.toc li,.ah,span.lineno,span.lineno a,span.lineno a:hover,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,.doxtable code {
81
+	background:none;
82
+}
83
+
84
+#titlearea,.footer,.contents,div.header,.memdoc,table.doxtable td,table.doxtable th,hr,.memSeparator {
85
+	border:none;
86
+}
87
+
88
+.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a,.reflist dt a.el,.levels span,.directory .levels span {
89
+	text-shadow:none;
90
+}
91
+
92
+.memdoc,dl.reflist dd {
93
+	box-shadow:none;
94
+}
95
+
96
+div.headertitle,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,table.doxtable code {
97
+	padding:0;
98
+}
99
+
100
+#nav-path,.directory .levels,span.lineno {
101
+	display:none;
102
+}
103
+
104
+html,#titlearea,.footer,tr.even,.directory tr.even,.doxtable tr:nth-child(even),.mdescLeft,.mdescRight,.memItemLeft,.memItemRight,code {
105
+	background:@header-footer-background-color;
106
+}
107
+
108
+body {
109
+	color:@default-text-color;
110
+}
111
+
112
+h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em {
113
+	color:@heading-color;
114
+	border-bottom:none;
115
+}
116
+
117
+h1 {
118
+  padding-top:0.5em;
119
+  font-size:180%;
120
+}
121
+
122
+h2 {
123
+  padding-top:0.5em;
124
+  margin-bottom:0;
125
+  font-size:140%;
126
+}
127
+
128
+h3 {
129
+  padding-top:0.5em;
130
+  margin-bottom:0;
131
+  font-size:110%;
132
+}
133
+
134
+.glfwheader {
135
+	font-size:16px;
136
+	height:64px;
137
+	max-width:920px;
138
+	min-width:800px;
139
+	padding:0 32px;
140
+	margin:0 auto;
141
+}
142
+
143
+#glfwhome {
144
+	line-height:64px;
145
+	padding-right:48px;
146
+	color:@header-footer-link-color;
147
+	font-size:2.5em;
148
+	background:url("http://www.glfw.org/css/arrow.png") no-repeat right;
149
+}
150
+
151
+.glfwnavbar {
152
+	list-style-type:none;
153
+	margin:0 auto;
154
+	float:right;
155
+}
156
+
157
+#glfwhome,.glfwnavbar li {
158
+	float:left;
159
+}
160
+
161
+.glfwnavbar a,.glfwnavbar a:visited {
162
+	line-height:64px;
163
+	margin-left:2em;
164
+	display:block;
165
+	color:@header-footer-link-color;
166
+}
167
+
168
+#glfwhome,.glfwnavbar a,.glfwnavbar a:visited {
169
+	transition:.35s ease;
170
+}
171
+
172
+#titlearea,.footer {
173
+	color:@header-footer-link-color;
174
+}
175
+
176
+address.footer {
177
+	text-align:center;
178
+	padding:2em;
179
+	margin-top:3em;
180
+}
181
+
182
+#top {
183
+	background:@header-footer-link-color;
184
+}
185
+
186
+#navrow1,#navrow2,#navrow3,#navrow4 {
187
+	max-width:920px;
188
+	min-width:800px;
189
+	margin:0 auto;
190
+	font-size:13px;
191
+}
192
+
193
+.tablist {
194
+	height:36px;
195
+	display:block;
196
+	position:relative;
197
+}
198
+
199
+.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a {
200
+	color:@navbar-link-color;
201
+}
202
+
203
+.tablist li.current a {
204
+	background:linear-gradient(to bottom,@tab-background-color2 0%,@tab-background-color1 100%);
205
+	box-shadow:inset 0 0 32px @tab-background-color1;
206
+	text-shadow:0 -1px 1px darken(@tab-background-color1, 15%);
207
+	color:@tab-text-color;
208
+}
209
+
210
+.contents {
211
+	min-height:590px;
212
+}
213
+
214
+div.contents,div.header {
215
+	max-width:920px;
216
+	margin:0 auto;
217
+	padding:0 32px;
218
+	background:@content-background-color none;
219
+}
220
+
221
+table.doxtable th,dl.reflist dt {
222
+	background:linear-gradient(to bottom,@table-background-color2 0%,@table-background-color1 100%);
223
+	box-shadow:inset 0 0 32px @table-background-color1;
224
+	text-shadow:0 -1px 1px darken(@table-background-color1, 15%);
225
+	color:@table-text-color;
226
+}
227
+
228
+dl.reflist dt a.el {
229
+	color:@default-link-color;
230
+	padding:.2em;
231
+	border-radius:4px;
232
+	background-color:lighten(@default-link-color, 40%);
233
+}
234
+
235
+div.toc {
236
+	float:none;
237
+	width:auto;
238
+}
239
+
240
+div.toc h3 {
241
+	font-size:1.17em;
242
+}
243
+
244
+div.toc ul {
245
+	padding-left:1.5em;
246
+}
247
+
248
+div.toc li {
249
+	font-size:1em;
250
+	padding-left:0;
251
+	list-style-type:disc;
252
+}
253
+
254
+div.toc,.memproto,div.qindex,div.ah {
255
+	background:linear-gradient(to bottom,@toc-background-color2 0%,@toc-background-color1 100%);
256
+	box-shadow:inset 0 0 32px @toc-background-color1;
257
+	text-shadow:0 1px 1px lighten(@toc-background-color2, 10%);
258
+	color:@heading-color;
259
+	border:2px solid @toc-background-color1;
260
+	border-radius:4px;
261
+}
262
+
263
+.paramname {
264
+	color:@prototype-param-color;
265
+}
266
+
267
+dl.reflist dt {
268
+	border:2px solid @default-border-color;
269
+	border-top-left-radius:4px;
270
+	border-top-right-radius:4px;
271
+	border-bottom:none;
272
+}
273
+
274
+dl.reflist dd {
275
+	border:2px solid @default-border-color;
276
+	border-bottom-right-radius:4px;
277
+	border-bottom-left-radius:4px;
278
+	border-top:none;
279
+}
280
+
281
+table.doxtable {
282
+	border-collapse:inherit;
283
+	border-spacing:0;
284
+	border:2px solid @default-border-color;
285
+	border-radius:4px;
286
+}
287
+
288
+a,a:hover,a:visited,a:visited:hover,.contents a:visited,.el,a.el:visited,#glfwhome:hover,.tablist a:hover,span.lineno a:hover {
289
+	color:@default-link-color;
290
+	text-decoration:none;
291
+}
292
+
293
+div.directory {
294
+	border-collapse:inherit;
295
+	border-spacing:0;
296
+	border:2px solid @default-border-color;
297
+	border-radius:4px;
298
+}
299
+
300
+hr,.memSeparator {
301
+	height:2px;
302
+	background:linear-gradient(to right,@def-separator-color 0%,darken(@def-separator-color, 10%) 50%,@def-separator-color 100%);
303
+}
304
+
305
+dl.note,dl.pre,dl.post,dl.invariant {
306
+	.message-box(@box-note-color);
307
+}
308
+
309
+dl.warning,dl.attention {
310
+	.message-box(@box-warning-color);
311
+}
312
+
313
+dl.deprecated,dl.bug {
314
+	.message-box(@box-bug-color);
315
+}
316
+
317
+dl.todo,dl.test {
318
+	.message-box(@box-todo-color);
319
+}
320
+
321
+dl.note,dl.pre,dl.post,dl.invariant,dl.warning,dl.attention,dl.deprecated,dl.bug,dl.todo,dl.test {
322
+	border-radius:4px;
323
+	padding:1em;
324
+	text-shadow:0 1px 1px hsl(0,0%,100%);
325
+	margin:1em 0;
326
+}
327
+
328
+.note a,.pre a,.post a,.invariant a,.warning a,.attention a,.deprecated a,.bug a,.todo a,.test a,.note a:visited,.pre a:visited,.post a:visited,.invariant a:visited,.warning a:visited,.attention a:visited,.deprecated a:visited,.bug a:visited,.todo a:visited,.test a:visited {
329
+	color:inherit;
330
+}
331
+
332
+div.line {
333
+	line-height:inherit;
334
+}
335
+
336
+div.fragment,pre.fragment {
337
+	background:hsl(0,0%,95%);
338
+	border-radius:4px;
339
+	border:none;
340
+	padding:1em;
341
+	overflow:auto;
342
+	border-left:4px solid hsl(0,0%,80%);
343
+	margin:1em 0;
344
+}
345
+
346
+.lineno a,.lineno a:visited,.line,pre.fragment {
347
+	color:@default-text-color;
348
+}
349
+
350
+span.preprocessor,span.comment {
351
+	color:hsl(193,100%,30%);
352
+}
353
+
354
+a.code,a.code:visited {
355
+	color:hsl(18,100%,45%);
356
+}
357
+
358
+span.keyword,span.keywordtype,span.keywordflow {
359
+	color:darken(@default-text-color, 5%);
360
+	font-weight:bold;
361
+}
362
+
363
+span.stringliteral {
364
+	color:hsl(261,100%,30%);
365
+}
366
+
367
+code {
368
+	padding:.1em;
369
+	border-radius:4px;
370
+}

+ 7
- 0
lib/glfw/docs/footer.html View File

@@ -0,0 +1,7 @@
1
+<address class="footer">
2
+<p>
3
+Last update on $date for $projectname $projectnumber
4
+</p>
5
+</address>
6
+</body>
7
+</html>

+ 34
- 0
lib/glfw/docs/header.html View File

@@ -0,0 +1,34 @@
1
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
+<html xmlns="http://www.w3.org/1999/xhtml">
3
+<head>
4
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5
+<meta http-equiv="X-UA-Compatible" content="IE=9"/>
6
+<meta name="generator" content="Doxygen $doxygenversion"/>
7
+<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
8
+<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
9
+<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
10
+<script type="text/javascript" src="$relpath^jquery.js"></script>
11
+<script type="text/javascript" src="$relpath^dynsections.js"></script>
12
+$treeview
13
+$search
14
+$mathjax
15
+<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
16
+$extrastylesheet
17
+</head>
18
+<body>
19
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
20
+
21
+<!--BEGIN TITLEAREA-->
22
+<div id="titlearea">
23
+	<div class="glfwheader">
24
+		<a href="http://www.glfw.org/" id="glfwhome">GLFW</a>
25
+		<ul class="glfwnavbar">
26
+			<li><a href="http://www.glfw.org/documentation.html">Documentation</a></li>
27
+			<li><a href="http://www.glfw.org/download.html">Download</a></li>
28
+			<li><a href="http://www.glfw.org/media.html">Media</a></li>
29
+			<li><a href="http://www.glfw.org/community.html">Community</a></li>
30
+		</ul>
31
+	</div>
32
+</div>
33
+<!--END TITLEAREA-->
34
+<!-- end header part -->

+ 588
- 0
lib/glfw/docs/input.dox View File

@@ -0,0 +1,588 @@
1
+/*!
2
+
3
+@page input Input guide
4
+ 
5
+@tableofcontents
6
+
7
+This guide introduces the input related functions of GLFW.  There are also
8
+guides for the other areas of GLFW.
9
+
10
+ - @ref intro
11
+ - @ref window
12
+ - @ref context
13
+ - @ref monitor
14
+
15
+GLFW provides many kinds of input.  While some can only be polled, like time, or
16
+only received via callbacks, like scrolling, there are those that provide both
17
+callbacks and polling.  Where a callback is provided, that is the recommended
18
+way to receive that kind of input.  The more you can use callbacks the less time
19
+your users' machines will need to spend polling.
20
+
21
+All input callbacks receive a window handle.  By using the
22
+[window user pointer](@ref window_userptr), you can access non-global structures
23
+or objects from your callbacks.
24
+
25
+To get a better feel for how the various events callbacks behave, run the
26
+`events` test program.  It register every callback supported by GLFW and prints
27
+out all arguments provided for every event, along with time and sequence
28
+information.
29
+
30
+
31
+@section events Event processing
32
+
33
+GLFW needs to communicate regularly with the window system both in order to
34
+receive events and to show that the application hasn't locked up.  Event
35
+processing must be done regularly while you have visible windows and is normally
36
+done each frame after [buffer swapping](@ref buffer_swap).
37
+
38
+There are two functions for processing pending events.  @ref glfwPollEvents,
39
+processes only those events that have already been received and then returns
40
+immediately.
41
+
42
+@code
43
+glfwPollEvents();
44
+@endcode
45
+
46
+This is the best choice when rendering continually, like most games do.
47
+
48
+If you only need to update the contents of the window when you receive new
49
+input, @ref glfwWaitEvents is a better choice.
50
+
51
+@code
52
+glfwWaitEvents();
53
+@endcode
54
+
55
+It puts the thread to sleep until at least one event has been received and then
56
+processes all received events.  This saves a great deal of CPU cycles and is
57
+useful for, for example, editing tools.  There must be at least one GLFW window
58
+for this function to sleep.
59
+
60
+If the main thread is sleeping in @ref glfwWaitEvents, you can wake it from
61
+another thread by posting an empty event to the event queue with @ref
62
+glfwPostEmptyEvent.
63
+
64
+@code
65
+glfwPostEmptyEvent();
66
+@endcode
67
+
68
+Do not assume that callbacks will _only_ be called through either of the above
69
+functions.  While it is necessary to process events in the event queue, some
70
+window systems will send some events directly to the application, which in turn
71
+causes callbacks to be called outside of regular event processing.
72
+
73
+
74
+@section input_keyboard Keyboard input
75
+
76
+GLFW divides keyboard input into two categories; key events and character
77
+events.  Key events relate to actual physical keyboard keys, whereas character
78
+events relate to the Unicode code points generated by pressing some of them.
79
+
80
+Keys and characters do not map 1:1.  A single key press may produce several
81
+characters, and a single character may require several keys to produce.  This
82
+may not be the case on your machine, but your users are likely not all using the
83
+same keyboard layout, input method or even operating system as you.
84
+
85
+
86
+@subsection input_key Key input
87
+
88
+If you wish to be notified when a physical key is pressed or released or when it
89
+repeats, set a key callback.
90
+
91
+@code
92
+glfwSetKeyCallback(window, key_callback);
93
+@endcode
94
+
95
+The callback function receives the [keyboard key](@ref keys), platform-specific
96
+scancode, key action and [modifier bits](@ref mods).
97
+
98
+@code
99
+void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
100
+{
101
+    if (key == GLFW_KEY_E && action == GLFW_PRESS)
102
+        activate_airship();
103
+}
104
+@endcode
105
+
106
+The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`.  The key
107
+will be `GLFW_KEY_UNKNOWN` if GLFW lacks a key token for it.  These keys still
108
+have unique, if platform-specific scancodes.
109
+
110
+The scancode is unique for every key but is platform-specific, so a scancode
111
+will map to different keys on different platforms.
112
+
113
+The key will be `GLFW_KEY_UNKNOWN` for special keys like _E-mail_ or _Play_ that
114
+don't have a key token.  Those keys will still have unique, if platform-specific
115
+scancodes.
116
+
117
+Key states for [named keys](@ref keys) are also saved in per-window state arrays
118
+that can be polled with @ref glfwGetKey.
119
+
120
+@code
121
+int state = glfwGetKey(window, GLFW_KEY_E);
122
+if (state == GLFW_PRESS)
123
+    activate_airship();
124
+@endcode
125
+
126
+The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
127
+
128
+This function only returns cached key event state.  It does not poll the
129
+system for the current state of the key.
130
+
131
+Whenever you poll state, you risk missing the state change you are looking for.
132
+If a pressed key is released again before you poll its state, you will have
133
+missed the key press.  The recommended solution for this is to use a
134
+key callback, but there is also the `GLFW_STICKY_KEYS` input mode.
135
+
136
+@code
137
+glfwSetInputMode(window, GLFW_STICKY_KEYS, 1);
138
+@endcode
139
+
140
+When sticky keys mode is enabled, the pollable state of a key will remain
141
+`GLFW_PRESS` until the state of that key is polled with @ref glfwGetKey.  Once
142
+it has been polled, if a key release event had been processed in the meantime,
143
+the state will reset to `GLFW_RELEASE`, otherwise it will remain `GLFW_PRESS`.
144
+
145
+The `GLFW_KEY_LAST` constant holds the highest value of any
146
+[named key](@ref keys).
147
+
148
+
149
+@subsection input_char Text input
150
+
151
+GLFW supports text input in the form of a stream of
152
+[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the
153
+operating system text input system.  Unlike key input, text input obeys keyboard
154
+layouts and modifier keys and supports composing characters using
155
+[dead keys](https://en.wikipedia.org/wiki/Dead_key).  Once received, you can
156
+encode the code points into
157
+[UTF-8](https://en.wikipedia.org/wiki/UTF-8) or any other encoding you prefer.
158
+
159
+Because an `unsigned int` is 32 bits long on all platforms supported by GLFW,
160
+you can treat the code point argument as native endian
161
+[UTF-32](https://en.wikipedia.org/wiki/UTF-32).
162
+
163
+There are two callbacks for receiving Unicode code points.  If you wish to
164
+offer regular text input, set a character callback.
165
+
166
+@code
167
+glfwSetCharCallback(window, character_callback);
168
+@endcode
169
+
170
+The callback function receives Unicode code points for key events that would
171
+have led to regular text input and generally behaves as a standard text field on
172
+that platform.
173
+
174
+@code
175
+void character_callback(GLFWwindow* window, unsigned int codepoint)
176
+{
177
+}
178
+@endcode
179
+
180
+If you wish to receive even those Unicode code points generated with modifier
181
+key combinations that a plain text field would ignore, or just want to know
182
+exactly what modifier keys were used, set a character with modifiers callback.
183
+
184
+@code
185
+glfwSetCharModsCallback(window, charmods_callback);
186
+@endcode
187
+
188
+The callback function receives Unicode code points and
189
+[modifier bits](@ref mods).
190
+
191
+@code
192
+void charmods_callback(GLFWwindow* window, unsigned int codepoint, int mods)
193
+{
194
+}
195
+@endcode
196
+
197
+
198
+@section input_mouse Mouse input
199
+
200
+Mouse input comes in many forms, including cursor motion, button presses and
201
+scrolling offsets.  The cursor appearance can also be changed, either to
202
+a custom image or a standard cursor shape from the system theme.
203
+
204
+
205
+@subsection cursor_pos Cursor position
206
+
207
+If you wish to be notified when the cursor moves over the window, set a cursor
208
+position callback.
209
+
210
+@code
211
+glfwSetCursorPosCallback(window, cursor_pos_callback);
212
+@endcode
213
+
214
+The callback functions receives the cursor position.  On platforms that provide
215
+it, the full sub-pixel cursor position is passed on.
216
+
217
+@code
218
+static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos)
219
+{
220
+}
221
+@endcode
222
+
223
+The cursor position is also saved per-window and can be polled with @ref
224
+glfwGetCursorPos.
225
+
226
+@code
227
+double xpos, ypos;
228
+glfwGetCursorPos(window, &xpos, &ypos);
229
+@endcode
230
+
231
+
232
+@subsection cursor_mode Cursor modes
233
+
234
+The `GLFW_CURSOR` input mode provides several cursor modes for special forms of
235
+mouse motion input.  By default, the cursor mode is `GLFW_CURSOR_NORMAL`,
236
+meaning the regular arrow cursor (or another cursor set with @ref glfwSetCursor)
237
+is used and cursor motion is not limited.
238
+
239
+If you wish to implement mouse motion based camera controls or other input
240
+schemes that require unlimited mouse movement, set the cursor mode to
241
+`GLFW_CURSOR_DISABLED`.
242
+
243
+@code
244
+glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED);
245
+@endcode
246
+
247
+This will hide the cursor and lock it to the specified window.  GLFW will then
248
+take care of all the details of cursor re-centering and offset calculation and
249
+providing the application with a virtual cursor position.  This virtual position
250
+is provided normally via both the cursor position callback and through polling.
251
+
252
+@note You should not implement your own version of this functionality using
253
+other features of GLFW.  It is not supported and will not work as robustly as
254
+`GLFW_CURSOR_DISABLED`.
255
+
256
+If you just wish the cursor to become hidden when it is over a window, set
257
+the cursor mode to `GLFW_CURSOR_HIDDEN`.
258
+
259
+@code
260
+glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN);
261
+@endcode
262
+
263
+This mode puts no limit on the motion of the cursor.
264
+
265
+To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL`
266
+cursor mode.
267
+
268
+@code
269
+glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL);
270
+@endcode
271
+
272
+
273
+@subsection cursor_object Cursor objects
274
+
275
+GLFW supports creating both custom and system theme cursor images, encapsulated
276
+as @ref GLFWcursor objects.  They are created with @ref glfwCreateCursor or @ref
277
+glfwCreateStandardCursor and destroyed with @ref glfwDestroyCursor, or @ref
278
+glfwTerminate, if any remain.
279
+
280
+
281
+@subsubsection cursor_custom Custom cursor creation
282
+
283
+A custom cursor is created with @ref glfwCreateCursor, which returns a handle to
284
+the created cursor object.  For example, this creates a 16x16 white square
285
+cursor with the hot-spot in the upper-left corner:
286
+
287
+@code
288
+unsigned char pixels[16 * 16 * 4];
289
+memset(pixels, 0xff, sizeof(pixels));
290
+
291
+GLFWimage image;
292
+image.width = 16;
293
+image.height = 16;
294
+image.pixels = pixels;
295
+
296
+GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);
297
+@endcode
298
+
299
+If cursor creation fails, `NULL` will be returned, so it is necessary to check
300
+the return value.
301
+
302
+The image data is 32-bit RGBA, i.e. eight bits per channel.  The pixels are
303
+arranged canonically as sequential rows, starting from the top-left corner.
304
+
305
+
306
+@subsubsection cursor_standard Standard cursor creation
307
+
308
+A cursor with a [standard shape](@ref shapes) from the current system cursor
309
+theme can be can be created with @ref glfwCreateStandardCursor.
310
+
311
+@code
312
+GLFWcursor* cursor = glfwCreateStandardCursor(GLFW_HRESIZE_CURSOR);
313
+@endcode
314
+
315
+These cursor objects behave in the exact same way as those created with @ref
316
+glfwCreateCursor except that the system cursor theme provides the actual image.
317
+
318
+
319
+@subsubsection cursor_destruction Cursor destruction
320
+
321
+When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
322
+
323
+@code
324
+glfwDestroyCursor(cursor);
325
+@endcode
326
+
327
+Cursor destruction always succeeds.  All cursors remaining when @ref
328
+glfwTerminate is called are destroyed as well.
329
+
330
+
331
+@subsubsection cursor_set Cursor setting
332
+
333
+A cursor can be set as current for a window with @ref glfwSetCursor.
334
+
335
+@code
336
+glfwSetCursor(window, cursor);
337
+@endcode
338
+
339
+Once set, the cursor image will be used as long as the system cursor is over the
340
+client area of the window and the [cursor mode](@ref cursor_mode) is set
341
+to `GLFW_CURSOR_NORMAL`.
342
+
343
+A single cursor may be set for any number of windows.
344
+
345
+To remove a cursor from a window, set the cursor of that window to `NULL`.
346
+
347
+@code
348
+glfwSetCursor(window, NULL);
349
+@endcode
350
+
351
+When a cursor is destroyed, it is removed from any window where it is set.  This
352
+does not affect the cursor modes of those windows.
353
+
354
+
355
+@subsection cursor_enter Cursor enter/leave events
356
+
357
+If you wish to be notified when the cursor enters or leaves the client area of
358
+a window, set a cursor enter/leave callback.
359
+
360
+@code
361
+glfwSetCursorEnterCallback(window, cursor_enter_callback);
362
+@endcode
363
+
364
+The callback function receives the new classification of the cursor.
365
+
366
+@code
367
+void cursor_enter_callback(GLFWwindow* window, int entered)
368
+{
369
+    if (entered)
370
+    {
371
+        // The cursor entered the client area of the window
372
+    }
373
+    else
374
+    {
375
+        // The cursor left the client area of the window
376
+    }
377
+}
378
+@endcode
379
+
380
+
381
+@subsection input_mouse_button Mouse button input
382
+
383
+If you wish to be notified when a mouse button is pressed or released, set
384
+a mouse button callback.
385
+
386
+@code
387
+glfwSetMouseButtonCallback(window, mouse_button_callback);
388
+@endcode
389
+
390
+The callback function receives the [mouse button](@ref buttons), button action
391
+and [modifier bits](@ref mods).
392
+
393
+@code
394
+void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)
395
+{
396
+    if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS)
397
+        popup_menu();
398
+}
399
+@endcode
400
+
401
+The action is one of `GLFW_PRESS` or `GLFW_RELEASE`.
402
+
403
+Mouse button states for [named buttons](@ref buttons) are also saved in
404
+per-window state arrays that can be polled with @ref glfwGetMouseButton.
405
+
406
+@code
407
+int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
408
+if (state == GLFW_PRESS)
409
+    upgrade_cow();
410
+@endcode
411
+
412
+The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
413
+
414
+This function only returns cached mouse button event state.  It does not poll
415
+the system for the current state of the mouse button.
416
+
417
+Whenever you poll state, you risk missing the state change you are looking for.
418
+If a pressed mouse button is released again before you poll its state, you will have
419
+missed the button press.  The recommended solution for this is to use a
420
+mouse button callback, but there is also the `GLFW_STICKY_MOUSE_BUTTONS`
421
+input mode.
422
+
423
+@code
424
+glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, 1);
425
+@endcode
426
+
427
+When sticky mouse buttons mode is enabled, the pollable state of a mouse button
428
+will remain `GLFW_PRESS` until the state of that button is polled with @ref
429
+glfwGetMouseButton.  Once it has been polled, if a mouse button release event
430
+had been processed in the meantime, the state will reset to `GLFW_RELEASE`,
431
+otherwise it will remain `GLFW_PRESS`.
432
+
433
+The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
434
+[named button](@ref buttons).
435
+
436
+
437
+@subsection scrolling Scroll input
438
+
439
+If you wish to be notified when the user scrolls, whether with a mouse wheel or
440
+touchpad gesture, set a scroll callback.
441
+
442
+@code
443
+glfwSetScrollCallback(window, scroll_callback);
444
+@endcode
445
+
446
+The callback function receives two-dimensional scroll offsets.
447
+
448
+@code
449
+void scroll_callback(GLFWwindow* window, double xoffset, double yoffset)
450
+{
451
+}
452
+@endcode
453
+
454
+A simple mouse wheel, being vertical, provides offsets along the Y-axis.
455
+
456
+
457
+@section joystick Joystick input
458
+
459
+The joystick functions expose connected joysticks and controllers, with both
460
+referred to as joysticks.  It supports up to sixteen joysticks, ranging from
461
+`GLFW_JOYSTICK_1`, `GLFW_JOYSTICK_2` up to `GLFW_JOYSTICK_LAST`.  You can test
462
+whether a [joystick](@ref joysticks) is present with @ref glfwJoystickPresent.
463
+
464
+@code
465
+int present = glfwJoystickPresent(GLFW_JOYSTICK_1);
466
+@endcode
467
+
468
+When GLFW is initialized, detected joysticks are added to to the beginning of
469
+the array, starting with `GLFW_JOYSTICK_1`.  Once a joystick is detected, it
470
+keeps its assigned index until it is disconnected, so as joysticks are connected
471
+and disconnected, they will become spread out.
472
+
473
+Joystick state is updated as needed when a joystick function is called and does
474
+not require a window to be created or @ref glfwPollEvents or @ref glfwWaitEvents
475
+to be called.
476
+
477
+
478
+@subsection joystick_axis Joystick axis states
479
+
480
+The positions of all axes of a joystick are returned by @ref
481
+glfwGetJoystickAxes.  See the reference documentation for the lifetime of the
482
+returned array.
483
+
484
+@code
485
+int count;
486
+const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_1, &count);
487
+@endcode
488
+
489
+Each element in the returned array is a value between -1.0 and 1.0.
490
+
491
+
492
+@subsection joystick_button Joystick button states
493
+
494
+The states of all buttons of a joystick are returned by @ref
495
+glfwGetJoystickButtons.  See the reference documentation for the lifetime of the
496
+returned array.
497
+
498
+@code
499
+int count;
500
+const unsigned char* axes = glfwGetJoystickButtons(GLFW_JOYSTICK_1, &count);
501
+@endcode
502
+
503
+Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`.
504
+
505
+
506
+@subsection joystick_name Joystick name
507
+
508
+The human-readable, UTF-8 encoded name of a joystick is returned by @ref
509
+glfwGetJoystickName.  See the reference documentation for the lifetime of the
510
+returned string.           
511
+
512
+@code
513
+const char* name = glfwGetJoystickName(GLFW_JOYSTICK_1);
514
+@endcode
515
+
516
+Joystick names are not guaranteed to be unique.  Two joysticks of the same model
517
+and make may have the same name.  Only the [joystick token](@ref joysticks) is
518
+guaranteed to be unique, and only until that joystick is disconnected.
519
+
520
+
521
+@section time Time input
522
+
523
+GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime.
524
+
525
+@code
526
+double seconds = glfwGetTime();
527
+@endcode
528
+
529
+It returns the number of seconds since the timer was started when the library
530
+was initialized with @ref glfwInit.  The platform-specific time sources used
531
+usually have micro- or nanosecond resolution.
532
+
533
+You can modify the reference time with @ref glfwSetTime.
534
+
535
+@code
536
+glfwSetTime(4.0);
537
+@endcode
538
+
539
+This sets the timer to the specified time, in seconds.
540
+
541
+
542
+@section clipboard Clipboard input and output
543
+
544
+If the system clipboard contains a UTF-8 encoded string or if it can be
545
+converted to one, you can retrieve it with @ref glfwGetClipboardString.  See the
546
+reference documentation for the lifetime of the returned string.
547
+
548
+@code
549
+const char* clipboard = glfwGetClipboardString(window);
550
+@endcode
551
+
552
+The contents of the system clipboard can be set to a UTF-8 encoded string with
553
+@ref glfwSetClipboardString.
554
+
555
+@code
556
+glfwSetClipboardString(window, "A string with words in it");
557
+@endcode
558
+
559
+The clipboard functions take a window handle argument because some window
560
+systems require a window to communicate with the system clipboard.  Any valid
561
+window may be used.
562
+
563
+
564
+@section path_drop Path drop input
565
+
566
+If you wish to receive the paths of files and/or directories dropped on
567
+a window, set a file drop callback.
568
+
569
+@code
570
+glfwSetDropCallback(window, drop_callback);
571
+@endcode
572
+
573
+The callback function receives an array of paths encoded as UTF-8.
574
+
575
+@code
576
+void drop_callback(GLFWwindow* window, int count, const char** paths)
577
+{
578
+    int i;
579
+    for (i = 0;  i < count;  i++)
580
+        handle_dropped_file(paths[i]);
581
+}
582
+@endcode
583
+
584
+The path array and its strings are only valid until the file drop callback
585
+returns, as they may have been generated specifically for that event.  You need
586
+to make a deep copy of the array if you want to keep the paths.
587
+
588
+*/

+ 116
- 0
lib/glfw/docs/internal.dox View File

@@ -0,0 +1,116 @@
1
+/*!
2
+
3
+@page internals Internal structure
4
+
5
+@tableofcontents
6
+
7
+There are several interfaces inside GLFW.  Each interface has its own area of
8
+responsibility and its own naming conventions.
9
+
10
+
11
+@section internals_public Public interface
12
+
13
+The most well-known is the public interface, described in the glfw3.h header
14
+file.  This is implemented in source files shared by all platforms and these
15
+files contain no platform-specific code.  This code usually ends up calling the
16
+platform and internal interfaces to do the actual work.
17
+
18
+The public interface uses the OpenGL naming conventions except with GLFW and
19
+glfw instead of GL and gl.  For struct members, where OpenGL sets no precedent,
20
+it use headless camel case.
21
+
22
+Examples: @ref glfwCreateWindow, @ref GLFWwindow, @ref GLFWvidmode.redBits,
23
+`GLFW_RED_BITS`
24
+
25
+
26
+@section internals_native Native interface
27
+
28
+The [native interface](@ref native) is a small set of publicly available
29
+but platform-specific functions, described in the glfw3native.h header file and
30
+used to gain access to the underlying window, context and (on some platforms)
31
+display handles used by the platform interface.
32
+
33
+The function names of the native interface are similar to those of the public
34
+interface, but embeds the name of the interface that the returned handle is
35
+from.
36
+
37
+Examples: @ref glfwGetX11Window, @ref glfwGetWGLContext
38
+
39
+
40
+@section internals_internal Internal interface
41
+
42
+The internal interface consists of utility functions used by all other
43
+interfaces.  It is shared code implemented in the same shared source files as
44
+the public and event interfaces.  The internal interface is described in the
45
+internal.h header file.
46
+
47
+The internal interface is in charge of GLFW's global data, which it stores in
48
+a `_GLFWlibrary` struct named `_glfw`.
49
+
50
+The internal interface uses the same style as the public interface, except all
51
+global names have a leading underscore.
52
+
53
+Examples: @ref _glfwIsValidContextConfig, @ref _GLFWwindow, `_glfw.currentRamp`
54
+
55
+
56
+@section internals_platform Platform interface
57
+
58
+The platform interface implements all platform-specific operations as a service
59
+to the public interface.  This includes event processing.  The platform
60
+interface is never directly called by application code and never directly calls
61
+application-provided callbacks.  It is also prohibited from modifying the
62
+platform-independent part of the internal structs.  Instead, it calls the event
63
+interface when events interesting to GLFW are received.
64
+
65
+The platform interface mirrors those parts of the public interface that needs to
66
+perform platform-specific operations on some or all platforms.  The are also
67
+named the same except that the glfw function prefix is replaced by
68
+_glfwPlatform.
69
+
70
+Examples: @ref _glfwPlatformCreateWindow
71
+
72
+The platform interface also defines structs that contain platform-specific
73
+global and per-object state.  Their names mirror those of the internal
74
+interface, except that an interface-specific suffix is added.
75
+
76
+Examples: `_GLFWwindowX11`, `_GLFWcontextWGL`
77
+
78
+These structs are incorporated as members into the internal interface structs
79
+using special macros that name them after the specific interface used.  This
80
+prevents shared code from accidentally using these members.
81
+
82
+Examples: `window.win32.handle`, `_glfw.x11.display`
83
+
84
+
85
+@section internals_event Event interface
86
+
87
+The event interface is implemented in the same shared source files as the public
88
+interface and is responsible for delivering the events it receives to the
89
+application, either via callbacks, via window state changes or both.
90
+
91
+The function names of the event interface use a `_glfwInput` prefix and the
92
+ObjectEvent pattern.
93
+
94
+Examples: @ref _glfwInputWindowFocus, @ref _glfwInputCursorMotion
95
+
96
+
97
+@section internals_static Static functions
98
+
99
+Static functions may be used by any interface and have no prefixes or suffixes.
100
+These use headless camel case.
101
+
102
+Examples: `clearScrollOffsets`
103
+
104
+
105
+@section internals_config Configuration macros
106
+
107
+GLFW uses a number of configuration macros to select at compile time which
108
+interfaces and code paths to use.  They are defined in the glfw_config.h header file,
109
+which is generated from the `glfw_config.h.in` file by CMake.
110
+
111
+Configuration macros the same style as tokens in the public interface, except
112
+with a leading underscore.
113
+
114
+Examples: `_GLFW_HAS_GLXGETPROCADDRESS` 
115
+
116
+*/

+ 347
- 0
lib/glfw/docs/intro.dox View File

@@ -0,0 +1,347 @@
1
+/*! 
2
+
3
+@page intro Introduction to the API
4
+ 
5
+@tableofcontents
6
+
7
+This guide introduces the basic concepts of GLFW and describes initialization,
8
+error handling and API guarantees and limitations.  For a broad but shallow
9
+tutorial, see @ref quick instead.  There are also guides for the other areas of
10
+GLFW.
11
+
12
+ - @ref window
13
+ - @ref context
14
+ - @ref monitor
15
+ - @ref input
16
+
17
+
18
+@section intro_init Initialization and termination
19
+
20
+Before most GLFW functions may be called, the library must be initialized.
21
+This initialization checks what features are available on the machine,
22
+enumerates monitors and joysticks, initializes the timer and performs any
23
+required platform-specific initialization.
24
+
25
+Only the following functions may be called before the library has been
26
+successfully initialized, and only from the main thread.
27
+
28
+ - @ref glfwGetVersion
29
+ - @ref glfwGetVersionString
30
+ - @ref glfwSetErrorCallback
31
+ - @ref glfwInit
32
+ - @ref glfwTerminate
33
+
34
+Calling any other function before that time will cause a @ref
35
+GLFW_NOT_INITIALIZED error. 
36
+
37
+
38
+@subsection intro_init_init Initializing GLFW
39
+
40
+The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an
41
+error occurred.
42
+
43
+@code
44
+if (!glfwInit())
45
+{
46
+    // Handle initialization failure
47
+}
48
+@endcode
49
+
50
+If any part of initialization fails, all remaining bits are terminated as if
51
+@ref glfwTerminate was called.  The library only needs to be initialized once
52
+and additional calls to an already initialized library will simply return
53
+`GL_TRUE` immediately.
54
+
55
+Once the library has been successfully initialized, it should be terminated
56
+before the application exits.
57
+
58
+
59
+@subsection intro_init_terminate Terminating GLFW
60
+
61
+Before your application exits, you should terminate the GLFW library if it has
62
+been initialized.  This is done with @ref glfwTerminate.
63
+
64
+@code
65
+glfwTerminate();
66
+@endcode
67
+
68
+This will destroy any remaining window, monitor and cursor objects, restore any
69
+modified gamma ramps, re-enable the screensaver if it had been disabled and free
70
+any resources allocated by GLFW.
71
+
72
+Once the library is terminated, it is as if it had never been initialized and
73
+you will need to initialize it again before being able to use GLFW.  If the
74
+library was not initialized or had already been terminated, it return
75
+immediately. 
76
+
77
+
78
+@section error_handling Error handling
79
+
80
+Some GLFW functions have return values that indicate an error, but this is often
81
+not very helpful when trying to figure out _why_ the error occurred.  Some
82
+functions also return otherwise valid values on error.  Finally, far from all
83
+GLFW functions have return values.
84
+
85
+This is where the error callback comes in.  This callback is called whenever an
86
+error occurs.  It is set with @ref glfwSetErrorCallback, a function that may be
87
+called regardless of whether GLFW is initialized.
88
+
89
+@code
90
+glfwSetErrorCallback(error_callback);
91
+@endcode
92
+
93
+The error callback receives a human-readable description of the error and (when
94
+possible) its cause.  The description encoded as UTF-8.  The callback is also
95
+provided with an [error code](@ref errors). 
96
+
97
+@code
98
+void error_callback(int error, const char* description)
99
+{
100
+    puts(description);
101
+}
102
+@endcode
103
+
104
+The error code indicates the general category of the error.  Some error codes,
105
+such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
106
+@ref GLFW_PLATFORM_ERROR are used for many different errors.
107
+
108
+The description string is only valid until the error callback returns, as it may
109
+have been generated specifically for that error.  This lets GLFW provide much
110
+more specific error descriptions but means you must make a copy if you want to
111
+keep the description string.
112
+
113
+
114
+@section coordinate_systems Coordinate systems
115
+
116
+GLFW has two primary coordinate systems: the _virtual screen_ and the window
117
+_client area_ or _content area_.  Both use the same unit: _virtual screen
118
+coordinates_, or just _screen coordinates_, which don't necessarily correspond
119
+to pixels.
120
+
121
+<img src="spaces.svg" width="90%" />
122
+
123
+Both the virtual screen and the client area coordinate systems have the X-axis
124
+pointing to the right and the Y-axis pointing down.
125
+
126
+Window and monitor positions are specified as the position of the upper-left
127
+corners of their content areas relative to the virtual screen, while cursor
128
+positions are specified relative to a window's client area.
129
+
130
+Because the origin of the window's client area coordinate system is also the
131
+point from which the window position is specified, you can translate client area
132
+coordinates to the virtual screen by adding the window position.  The window
133
+frame, when present, extends out from the client area but does not affect the
134
+window position.
135
+
136
+Almost all positions and sizes in GLFW are measured in screen coordinates
137
+relative to one of the two origins above.  This includes cursor positions,
138
+window positions and sizes, window frame sizes, monitor positions and video mode
139
+resolutions.
140
+
141
+Two exceptions are the [monitor physical size](@ref monitor_size), which is
142
+measured in millimetres, and [framebuffer size](@ref window_fbsize), which is
143
+measured in pixels.
144
+
145
+Pixels and screen coordinates may map 1:1 on your machine, but they won't on
146
+every other machine, for example on a Mac with a Retina display.  The ratio
147
+between screen coordinates and pixels may also change at run-time depending on
148
+which monitor the window is currently considered to be on.
149
+
150
+
151
+@section guarantees_limitations Guarantees and limitations
152
+
153
+This section describes the conditions under which GLFW can be expected to
154
+function, barring bugs in the operating system or drivers.  Use of GLFW outside
155
+of these limits may work on some platforms, or on some machines, or some of the
156
+time, or on some versions of GLFW, but it may break at any time and this will
157
+not be considered a bug.
158
+
159