Documentation work.

docs/Doxyfile.in

@@ -666,6 +666,8 @@ INPUT                  = @GLFW_INTERNAL_DOCS@                         \
                          @GLFW_SOURCE_DIR@/docs/monitor.dox           \
                          @GLFW_SOURCE_DIR@/docs/window.dox            \
                          @GLFW_SOURCE_DIR@/docs/input.dox             \
+                         @GLFW_SOURCE_DIR@/docs/common.dox            \
+                         @GLFW_SOURCE_DIR@/docs/rift.dox              \
                          @GLFW_SOURCE_DIR@/docs/compat.dox
 
 # This tag can be used to specify the character encoding of the source files
@@ -936,7 +938,7 @@ HTML_EXTRA_STYLESHEET  = @GLFW_SOURCE_DIR@/docs/extra.css
 # files. In the HTML_STYLESHEET file, use the file name only. Also note that
 # the files will be copied as-is; there are no commands or markers available.
 
-HTML_EXTRA_FILES       =
+HTML_EXTRA_FILES       = @GLFW_SOURCE_DIR@/docs/spaces.svg
 
 # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output.
 # Doxygen will adjust the colors in the style sheet and background images

docs/build.dox

@@ -1,24 +1,24 @@
 /*!
 
-@page build Building programs that use GLFW
+@page build Building applications
 
 @tableofcontents
 
-This is about compiling and linking programs that use GLFW.  For information on
+This is about compiling and linking applications that use GLFW.  For information on
-how to write such programs, start with the [introductory tutorial](@ref quick).
+how to write such applications, start with the [introductory tutorial](@ref quick).
 For information on how to compile the GLFW library itself, see the @ref compile
 guide.
 
-This is not a tutorial on compilation.  It assumes basic understanding of how to
+This is not a tutorial on compilation or linking.  It assumes basic
-compile a C program as well as how to use the specific compiler of your chosen
+understanding of how to compile and link a C program as well as how to use the
-development environment.  The compilation process should be explained in your
+specific compiler of your chosen development environment.  The compilation
-C programming material and the use of and options for your compiler should be
+and linking process should be explained in your C programming material and in
-described in detail in the documentation for your development environment.
+the documentation for your development environment.
 
 @section build_include Including the GLFW header file
 
-In the files of your program where you use OpenGL or GLFW, you should include
+In the source files of your application where you use OpenGL or GLFW, you should
-the GLFW header file, i.e.:
+include the GLFW header file, i.e.:
 
 @code
 #include <GLFW/glfw3.h>
@@ -30,13 +30,14 @@ types and function prototypes of the OpenGL API.
 
 The GLFW header also defines everything necessary for your OpenGL header to
 function.  For example, under Windows you are normally required to include
-`windows.h` before the OpenGL header.  This would make your source file tied
+`windows.h` before the OpenGL header, which would pollute your code namespace
-to Windows and pollute your code's namespace with the whole Win32 API.
+with the entire Win32 API.
 
 Instead, the GLFW header takes care of this for you, not by including
 `windows.h`, but by duplicating only the very few necessary parts of it.  It
 does this only when needed, so if `windows.h` *is* included, the GLFW header
-does not try to redefine those symbols.
+does not try to redefine those symbols.  The reverse is not true, i.e.
+`windows.h` cannot cope if any of its symbols have already been defined.
 
 In other words:
 
@@ -44,7 +45,7 @@ In other words:
  - Do *not* include `windows.h` or other platform-specific headers unless you
    plan on using those APIs directly
  - If you *do* need to include such headers, do it *before* including
-   the GLFW one and it will detect this
+   the GLFW header and it will handle this
 
 If you are using an OpenGL extension loading library such as
 [glad](https://github.com/Dav1dde/glad), the extension loader header should
@@ -60,28 +61,29 @@ its behavior.
 `GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler
 that the GLFW functions are defined in a DLL.
 
-The following macros control which client API header is included.
+The following macros control which OpenGL or OpenGL ES API header is included.
 
-`GLFW_INCLUDE_GLCOREARB` makes the header include the modern `GL/glcorearb.h`
+`GLFW_INCLUDE_GLCOREARB` makes the GLFW header include the modern
-header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL header.
+`GL/glcorearb.h` header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL
+header.
 
-`GLFW_INCLUDE_ES1` makes the header include the OpenGL ES 1.x `GLES/gl.h` header
+`GLFW_INCLUDE_ES1` makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
-instead of the regular OpenGL header.
-
-`GLFW_INCLUDE_ES2` makes the header include the OpenGL ES 2.0 `GLES2/gl2.h`
 header instead of the regular OpenGL header.
 
-`GLFW_INCLUDE_ES3` makes the header include the OpenGL ES 3.0 `GLES3/gl3.h`
+`GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h`
 header instead of the regular OpenGL header.
 
-`GLFW_INCLUDE_ES31` makes the header include the OpenGL ES 3.1 `GLES3/gl31.h`
+`GLFW_INCLUDE_ES3` makes the GLFW header include the OpenGL ES 3.0 `GLES3/gl3.h`
 header instead of the regular OpenGL header.
 
-`GLFW_INCLUDE_NONE` makes the header not include any client API header.  This is
+`GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h`
-useful in combination with an extension loading library.
+header instead of the regular OpenGL header.
 
-If none of the above inclusion macros are defined, the standard OpenGL header is
+`GLFW_INCLUDE_NONE` makes the GLFW header not include any OpenGL or OpenGL ES API
-included.
+header.  This is useful in combination with an extension loading library.
+
+If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
+header (`OpenGL/gl.h` on OS X) is included.
 
 `GLFW_INCLUDE_GLU` makes the header include the GLU header *in addition to* the
 header selected above.  This should only be used with legacy code.  GLU has been
@@ -104,12 +106,6 @@ hard-coded into your build environment.  See the section for your development
 environment below.  On Linux and other Unix-like operating systems, the list
 varies but can be retrieved in various ways as described below.
 
-This is not a tutorial on linking.  It assumes basic understanding of how to
-link a C program as well as how to use the specific linker of your chosen
-development environment.  The linking process should be explained in your
-C programming material and the use of and options for your linker should be
-described in detail in the documentation for your development environment.
-
 A good general introduction to linking is
 [Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by
 David Drysdale.
@@ -120,20 +116,20 @@ David Drysdale.
 The static version of the GLFW library is named `glfw3`.  When using this
 version, it is also necessary to link with some libraries that GLFW uses.
 
-When linking a program under Windows that uses the static version of GLFW, you
+When linking an application under Windows that uses the static version of GLFW,
-must link with `opengl32`.  On some versions of MinGW, you must also explicitly
+you must link with `opengl32`.  On some versions of MinGW, you must also
-link with `gdi32`, while other versions of MinGW include it in the set of
+explicitly link with `gdi32`, while other versions of MinGW include it in the
-default libraries along with other dependencies like `user32` and `kernel32`.
+set of default libraries along with other dependencies like `user32` and
-If you are using GLU, you must also link with `glu32`.
+`kernel32`.  If you are using GLU, you must also link with `glu32`.
 
-The link library for the GLFW DLL is named `glfw3dll`.  When compiling a program
+The link library for the GLFW DLL is named `glfw3dll`.  When compiling an
-that uses the DLL version of GLFW, you need to define the `GLFW_DLL` macro
+application that uses the DLL version of GLFW, you need to define the `GLFW_DLL`
-*before* any inclusion of the GLFW header.  This can be done either with
+macro *before* any inclusion of the GLFW header.  This can be done either with
 a compiler switch or by defining it in your source code.
 
-A program using the GLFW DLL does not need to link against any of its
+An application using the GLFW DLL does not need to link against any of its
-dependencies, but you still have to link against `opengl32` if your program uses
+dependencies, but you still have to link against `opengl32` if your application
-OpenGL and `glu32` if it uses GLU.
+uses OpenGL and `glu32` if it uses GLU.
 
 
 @subsection build_link_cmake_source With CMake and GLFW source
@@ -266,8 +262,12 @@ If you are using the dynamic library version of GLFW, simply add it to the
 project dependencies.
 
 If you are using the static library version of GLFW, add it and the Cocoa,
-OpenGL, IOKit and CoreVideo frameworks to the project as dependencies.  They can
+OpenGL, IOKit, CoreVideo and Carbon frameworks to the project as dependencies.
-all be found in `/System/Library/Frameworks`.
+They can all be found in `/System/Library/Frameworks`.
+
+@note GLFW needs the Carbon framework only to access the current keyboard layout
+via the Text Input Source Services.  This is one of the non-deprecated parts of
+the Carbon API and the only way to access this information on OS X.
 
 
 @subsection build_link_osx With command-line on OS X

docs/common.dox

@@ -0,0 +1,18 @@
+/*!
+
+@page common Common tasks
+
+@tableofcontents
+
+This guide explains how to 
+
+
+@section common_full_screen Windowed full screen mode
+
+@section common_window_pos Initial window position
+
+GLFW comes with the `windows` test program, which illustrates this method.
+
+@section common_fps_camera First-person camera controls
+
+*/

docs/compat.dox

@@ -4,19 +4,20 @@
 
 @tableofcontents
 
-This chapter describes the various API extensions used by this version of GLFW.
+This guide describes the various API extensions used by this version of GLFW.
 It lists what are essentially implementation details, but which are nonetheless
-vital knowledge for developers wishing to deploy their applications on machines
+vital knowledge for developers intending to deploy their applications on a wide
-with varied specifications.
+range of machines.
+
+@note The information in this guide is not a part of GLFW API, but merely
+preconditions for some parts of the library to function on a given machine.  Any
+part of this information may change in future versions of GLFW and that will not
+be considered a breaking API change.
 
-Note that the information in this appendix is not a part of the API
-specification but merely list some of the preconditions for certain parts of the
-API to function on a given machine.  As such, any part of it may change in
-future versions without this being considered a breaking API change.
 
 @section compat_x11 X11 extensions, protocols and IPC standards
 
-As GLFW uses Xlib, directly, without any intervening toolkit
+As GLFW uses Xlib directly, without any intervening toolkit
 library, it has sole responsibility for interacting well with the many and
 varied window managers in use on Unix-like systems.  In order for applications
 and window managers to work well together, a number of standards and
@@ -79,13 +80,14 @@ GLFW requires the Xkb extension with detectable auto-repeat to provide keyboard
 input.  If the running X server does not support this extension, a non-Xkb
 fallback path is used.
 
+
 @section compat_glx GLX extensions
 
 The GLX API is the default API used to create OpenGL contexts on Unix-like
 systems using the X Window System.
 
-GLFW uses the `GLXFBConfig` API to enumerate and select framebuffer pixel
+GLFW uses the GLX 1.3 `GLXFBConfig` functions to enumerate and select framebuffer pixel
-formats.  This requires GLX 1.3 or greater.
+formats.  If GLX 1.3 is not supported, @ref glfwInit will fail.
 
 GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
 `GLX_SGI_swap_control` extensions to provide vertical retrace synchronization

docs/compile.dox

@@ -5,36 +5,45 @@
 @tableofcontents
 
 This is about compiling the GLFW library itself.  For information on how to
-build programs that use GLFW, see the @ref build guide.
+build applications that use GLFW, see the @ref build guide.
 
 
-@section compile_deps Dependencies
+@section compile_cmake Using CMake
 
-To compile GLFW and the accompanying example programs, you will need **CMake**,
+GLFW uses [CMake](http://www.cmake.org/) to generate project files or makefiles
-which will generate the project files or makefiles for your particular
+for a particular development environment.  If you are on a Unix-like system such
-development environment.  If you are on a Unix-like system such as Linux or
+as Linux or FreeBSD or have a package system like Fink, MacPorts, Cygwin or
-FreeBSD or have a package system like Fink, MacPorts, Cygwin or Homebrew, you
+Homebrew, you can simply install its CMake package.  If not, you can download
-can simply install its CMake package.  If not, you can get installers for
+installers for Windows and OS X from the [CMake website](http://www.cmake.org/).
-Windows and OS X from the [CMake website](http://www.cmake.org/).
 
-Additional dependencies are listed below.
+@note CMake only generates project files or makefiles.  It does not compile the
-
+actual GLFW library.  To compile GLFW, first generate these files and then use
-If you wish to compile GLFW without CMake, see @ref compile_manual.
+them in your chosen development environment to compile the actual GLFW library.
 
 
-@subsection compile_deps_msvc Dependencies using Visual C++ on Windows
+@subsection compile_deps Dependencies
 
-The Microsoft Platform SDK that is installed along with Visual C++ contains all
+Once you have installed CMake, make sure that all other dependencies are
-the necessary headers, link libraries and tools except for CMake.
+available.  On some platforms, GLFW needs a few additional packages to be
+installed.  See the section for your chosen platform and development environment
+below.
 
 
-@subsection compile_deps_mingw Dependencies with MinGW or MinGW-w64 on Windows
+@subsubsection compile_deps_msvc Dependencies for Visual C++ on Windows
 
-Both the MinGW and the MinGW-w64 packages contain all the necessary headers,
+The Microsoft Platform SDK that is installed along with Visual C++ already
-link libraries and tools except for CMake.
+contains all the necessary headers, link libraries and tools except for CMake.
+Move on to @ref compile_generate.
 
 
-@subsection compile_deps_mingw_cross Dependencies using MinGW or MinGW-w64 cross-compilation
+@subsubsection compile_deps_mingw Dependencies for MinGW or MinGW-w64 on Windows
+
+Both the MinGW and the MinGW-w64 packages already contain all the necessary
+headers, link libraries and tools except for CMake.  Move on to @ref
+compile_generate.
+
+
+@subsubsection compile_deps_mingw_cross Dependencies for MinGW or MinGW-w64 cross-compilation
 
 Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages.  For
 example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
@@ -45,7 +54,9 @@ GLFW has CMake toolchain files in the `CMake/` directory that allow for easy
 cross-compilation of Windows binaries.  To use these files you need to add a
 special parameter when generating the project files or makefiles:
 
+@code{.sh}
 cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
+@endcode
 
 The exact toolchain file to use depends on the prefix used by the MinGW or
 MinGW-w64 binaries on your system.  You can usually see this in the /usr
@@ -53,21 +64,27 @@ directory.  For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages
 have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
 invocation would be:
 
+@code{.sh}
 cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
+@endcode
 
 For more details see the article
 [CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on
 the CMake wiki.
 
-
+Once you have this set up, move on to @ref compile_generate.
-@subsection compile_deps_xcode Dependencies using Xcode on OS X
-
-Xcode contains all necessary tools except for CMake.  The necessary headers and
-libraries are included in the core OS frameworks.  Xcode can be downloaded from
-the Mac App Store or from the ADC Member Center.
 
 
-@subsection compile_deps_x11 Dependencies using Linux and X11
+@subsubsection compile_deps_xcode Dependencies for Xcode on OS X
+
+Xcode comes with all necessary tools except for CMake.  The required headers
+and libraries are included in the core OS X frameworks.  Xcode can be downloaded
+from the Mac App Store or from the ADC Member Center.
+
+Once you have Xcode installed, move on to @ref compile_generate.
+
+
+@subsubsection compile_deps_x11 Dependencies for Linux and X11
 
 To compile GLFW for X11, you need to have the X11 and OpenGL header packages
 installed, as well as the basic development tools like GCC and make.  For
@@ -78,8 +95,11 @@ packages.  GLFW itself doesn't need or use GLU, but some of the examples do.
 Note that using header files and libraries from Mesa during compilation *will
 not* tie your binaries to the Mesa implementation of OpenGL.
 
+Once you have installed the necessary packages, move on to @ref
+compile_generate.
 
-@section compile_cmake Generating files with CMake
+
+@subsection compile_generate Generating build files with CMake
 
 Once you have all necessary dependencies it is time to generate the project
 files or makefiles for your development environment.  CMake needs to know two
@@ -91,36 +111,59 @@ otherwise it is called an out-of-tree build.
 One of several advantages of out-of-tree builds is that you can generate files
 and compile for different development environments using a single source tree.
 
+@note This section is about generating the project files or makefiles necessary
+to compile the GLFW library, not about compiling the actual library.
 
-@subsection compile_cmake_cli Generating files with the CMake command-line tool
+
+@subsubsection compile_generate_cli Generating files with the CMake command-line tool
 
 To make an in-tree build, enter the *root* directory of the GLFW source tree
 (i.e. *not* the `src` subdirectory) and run CMake.  The current directory is
 used as target path, while the path provided as an argument is used to find the
 source tree.
 
+@code{.sh}
 cd <glfw-root-dir>
 cmake .
+@endcode
 
 To make an out-of-tree build, make another directory, enter it and run CMake
 with the (relative or absolute) path to the root of the source tree as an
 argument.
 
+@code{.sh}
 cd <glfw-root-dir>
 mkdir build
 cd build
 cmake ..
+@endcode
+
+Once you have generated the project files or makefiles for your chosen
+development environment, move on to @ref compile_compile.
 
 
-@subsection compile_cmake_gui Generating files with the CMake GUI
+@subsubsection compile_generate_gui Generating files with the CMake GUI
 
 If you are using the GUI version, choose the root of the GLFW source tree as
 source location and the same directory or another, empty directory as the
 destination for binaries.  Choose *Configure*, change any options you wish to,
 *Configure* again to let the changes take effect and then *Generate*.
 
+Once you have generated the project files or makefiles for your chosen
+development environment, move on to @ref compile_compile.
 
-@section compile_options CMake options
+
+@subsection compile_compile Compiling the library
+
+You should now have all required dependencies and the project files or makefiles
+necessary to compile GLFW.  Go ahead and compile the actual GLFW library with
+these files, as you would with any other project.
+
+Once the GLFW library is compiled, you are ready to build your applications,
+linking it to the GLFW library.  See the @ref build guide for more information.
+
+
+@subsection compile_options CMake options
 
 The CMake files for GLFW provide a number of options, although not all are
 available on all supported platforms.  Some of these are de facto standards
@@ -132,7 +175,7 @@ Some package systems like Ubuntu and other distributions based on Debian
 GNU/Linux have this tool in a separate `cmake-curses-gui` package.
 
 
-@subsection compile_options_shared Shared CMake options
+@subsubsection compile_options_shared Shared CMake options
 
 `BUILD_SHARED_LIBS` determines whether GLFW is built as a static
 library or as a DLL / shared library / dynamic library.
@@ -157,7 +200,7 @@ built along with the library.
 the library.
 
 
-@subsection compile_options_osx OS X specific CMake options
+@subsubsection compile_options_osx OS X specific CMake options
 
 `GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
 directory of bundled applications to the `Contents/Resources` directory.
@@ -171,7 +214,7 @@ Retina displays.
 `GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries.
 
 
-@subsection compile_options_win32 Windows specific CMake options
+@subsubsection compile_options_win32 Windows specific CMake options
 
 `USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the
 static library version of the Visual C++ runtime library.  If set to `ON`, the
@@ -189,7 +232,7 @@ symbol, which forces the use of the high-performance GPU on nVidia Optimus
 systems.
 
 
-@subsection compile_options_egl EGL specific CMake options
+@subsubsection compile_options_egl EGL specific CMake options
 
 `GLFW_USE_EGL` determines whether to use EGL instead of the platform-specific
 context creation API.  Note that EGL is not yet provided on all supported

docs/context.dox

@@ -1,6 +1,6 @@
 /*!
 
-@page context Context handling guide
+@page context Context guide
 
 @tableofcontents
 
@@ -8,31 +8,52 @@ The primary purpose of GLFW is to provide a simple interface to window
 management and OpenGL and OpenGL ES context creation.  GLFW supports
 multiple windows, with each window having its own context.
 
+This guide introduces the functions related to managing OpenGL and OpenGL ES
+contexts.  There are also guides for the other areas of the GLFW API.
 
-@section context_object Context handles
+ - @ref intro
+ - @ref window
+ - @ref monitor
+ - @ref input
 
-The @ref GLFWwindow object encapsulates both a [window](@ref window) and
+
-a context.  It is created with @ref glfwCreateWindow and destroyed with @ref
+@section context_object Context objects
+
+@ref window_object encapsulate both the OS level window and a OpenGL or OpenGL
+ES context.  It is created with @ref glfwCreateWindow and destroyed with @ref
 glfwDestroyWindow or @ref glfwTerminate.  As the window and context are
 inseparably linked, the object pointer is used as both a context and window
-handle.
+handle.  See @ref window_creation for more information.
 
 
-@section context_hints Context creation hints
+@subsection context_hints Context creation hints
 
 There are a number of hints, specified using @ref glfwWindowHint, related to
 what kind of context is created.  See
-[context related hints](@ref window_hints_ctx) in the window handling guide.
+[context related hints](@ref window_hints_ctx) in the window guide.
 
 
-@section context_sharing Context object sharing
+@subsection context_sharing Context object sharing
 
-When creating a window and context with @ref glfwCreateWindow, you can specify
+When creating a window and its OpenGL or OpenGL ES context with @ref
-another window whose context the new one should share its objects with.  Object
+glfwCreateWindow, you can specify another window whose context the new one
-sharing is implemented by the operating system and graphics driver and is
+should share its objects (textures, vertex and element buffers, etc.) with.
-described in the OpenGL and OpenGL ES documentation.  On platforms where it is
+
-possible to choose which types of objects are shared, GLFW requests that all are
+@code
-shared.
+GLFWwindow* second_window = glfwCreateWindow(640, 480, "Second Window", NULL, first_window);
+@endcode
+
+Object sharing is implemented by the operating system and graphics driver.  On
+platforms where it is possible to choose which types of objects are shared, GLFW
+requests that all types are shared.
+
+See the relevant chapter of the [OpenGL](https://www.opengl.org/registry/) or
+[OpenGL ES](http://www.khronos.org/opengles/) reference documents for more
+information.  The name and number of this chapter unfortunately varies between
+versions and APIs, but has at times been named *Shared Objects and Multiple
+Contexts*.
+
+GLFW comes with a simple object sharing test program called `sharing`.
 
 
 @section context_current Current context
@@ -53,14 +74,14 @@ The current context is returned by @ref glfwGetCurrentContext.
 GLFWwindow* window = glfwGetCurrentContext();
 @endcode
 
-@note A context must only be current for a single thread at a time, and a thread
+@note A context can only be current for a single thread at a time, and a thread
-must only have a single context current at a time.
+can only have a single context current at a time.
 
 
-@section context_swap Swapping buffers
+@section context_swap Buffer swapping
 
 Buffer swapping is part of the window and framebuffer, not the context.  See
-@ref window_swap in the window handling guide.
+@ref window_swap in the window guide.
 
 
 @section context_glext OpenGL and OpenGL ES extensions
@@ -170,10 +191,8 @@ that extension and then, if it introduces new functions, retrieve the pointers
 to those functions.  GLFW provides @ref glfwExtensionSupported and @ref
 glfwGetProcAddress for manual loading of extensions and new API functions.
 
-@note It is strongly recommended that you use an existing extension loader
+@note It is recommended that you use an existing extension loader library, as
-library like [glad](https://github.com/Dav1dde/glad) instead of loading
+described above, instead of loading manually.
-manually.  Extension loading is a solved problem and you will gain nothing from
-solving it again by hand.
 
 
 @subsubsection context_glext_header The glext.h header

docs/extra.less

@@ -114,6 +114,23 @@ h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em {
 	border-bottom:none;
 }
 
+h1 {
+  padding-top:0.5em;
+  font-size:180%;
+}
+
+h2 {
+  padding-top:0.5em;
+  margin-bottom:0;
+  font-size:140%;
+}
+
+h3 {
+  padding-top:0.5em;
+  margin-bottom:0;
+  font-size:110%;
+}
+
 .glfwheader {
 	font-size:16px;
 	height:64px;

docs/input.dox

@@ -1,13 +1,563 @@
 /*!
 
-@page input Input handling guide
+@page input Input guide
  
 @tableofcontents
 
-@section input_key Keyboard input
+This guide introduces the input related functions of GLFW.  There are also
+guides for the other areas of GLFW.
+
+ - @ref intro
+ - @ref window
+ - @ref context
+ - @ref monitor
+
+GLFW provides many kinds of input.  While some can only be polled, like time, or
+only received via callbacks, like scrolling, there are those that provide both
+callbacks and polling.  Where a callback is provided, that is the recommended
+way to receive that kind of input.  The more you can use callbacks the less time
+your users' machines will need to spend polling.
+
+All input callbacks receive a window handle.  By using the
+[window user pointer](@ref window_userptr), you can access non-global structures
+or objects from your callbacks.
+
+To get a better feel for how the various events callbacks behave, run the
+`events` test program.  It register every callback supported by GLFW and prints
+out all arguments provided for every event, along with time and sequence
+information.
+
+
+@section input_event Event processing
+
+GLFW needs to communicate regularly with the window system both in order to
+receive events and to show that the application hasn't locked up.  Event
+processing must be done regularly while you have visible windows and is normally
+done each frame after [buffer swapping](@ref window_swap).
+
+There are two functions for processing pending events.  @ref glfwPollEvents,
+processes only those events that have already been received and then returns
+immediately.
+
+@code
+glfwPollEvents();
+@endcode
+
+This is the best choice when rendering continually, like most games do.
+
+If you only need to update the contents of the window when you receive new
+input, @ref glfwWaitEvents is a better choice.
+
+@code
+glfwWaitEvents();
+@endcode
+
+It puts the thread to sleep until at least one event has been received and then
+processes all received events.  This saves a great deal of CPU cycles and is
+useful for, for example, editing tools.  There must be at least one GLFW window
+for this function to sleep.
+
+If the main thread is sleeping in @ref glfwWaitEvents, you can wake it from
+another thread by posting an empty event to the event queue with @ref
+glfwPostEmptyEvent.
+
+@code
+glfwPostEmptyEvent();
+@endcode
+
+Do not assume that callbacks will *only* be called through either of the above
+functions.  While it is necessary to process events in the event queue, some
+window systems will send some events directly to the application, which in turn
+causes callbacks to be called outside of regular event processing.
+
+
+@section input_keyboard Keyboard input
+
+GLFW divides keyboard input into two categories; key events and character
+events.  Key events relate to actual physical keyboard keys, whereas character
+events relate to the Unicode code points generated by pressing some of them.
+
+Keys and characters do not map 1:1.  A single key press may produce several
+characters, and a single character may require several keys to produce.  This
+may not be the case on your machine, but your users are likely not all using the
+same keyboard layout, input method or even operating system as you.
+
+
+@subsection input_key Key input
+
+If you wish to be notified when a physical key is pressed or released or when it
+repeats, set a key callback with @ref glfwSetKeyCallback.
+
+@code
+glfwSetKeyCallback(window, key_callback);
+@endcode
+
+The callback function receives the [keyboard key](@ref keys), platform-specific
+scancode, key action and [modifier bits](@ref mods).
+
+@code
+void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
+{
+    if (key == GLFW_KEY_E && action == GLFW_PRESS)
+        activate_airship();
+}
+@endcode
+
+The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`.  The key
+will be `GLFW_KEY_UNKNOWN` if GLFW lacks a key token for it.  These keys still
+have unique, if platform-specific scancodes.
+
+The scancode is unique for every key but is platform-specific, so a scancode
+will map to different keys on different platforms.
+
+The key will be `GLFW_KEY_UNKNOWN` for special keys like *E-mail* or *Play* that
+don't have a key token.  Those keys will still have unique, if platform-specific
+scancodes.
+
+Key states for [named keys](@ref keys) are also saved in per-window state arrays
+that can be polled with @ref glfwGetKey.
+
+@code
+int state = glfwGetKey(window, GLFW_KEY_E);
+if (state == GLFW_PRESS)
+    activate_airship();
+@endcode
+
+The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
+
+This function only returns cached key event state.  It does not poll the
+system for the current state of the key.
+
+Whenever you poll state, you risk missing the state change you are looking for.
+If a pressed key is released again before you poll its state, you will have
+missed the key press.  The recommended solution for this is to use a
+key callback, but there is also the `GLFW_STICKY_KEYS` input mode.
+
+@code
+glfwSetInputMode(window, GLFW_STICKY_KEYS, 1);
+@endcode
+
+When sticky keys mode is enabled, the pollable state of a key will remain
+`GLFW_PRESS` until the state of that key is polled with @ref glfwGetKey.  Once
+it has been polled, if a key release event had been processed in the meantime,
+the state will reset to `GLFW_RELEASE`, otherwise it will remain `GLFW_PRESS`.
+
+The `GLFW_KEY_LAST` constant holds the highest value of any
+[named key](@ref keys).
+
+
+@subsection input_char Unicode character input
+
+If you wish to receive Unicode code point input, set a character callback with
+@ref glfwSetCharCallback.
+
+@code
+glfwSetCharCallback(window, character_callback);
+@endcode
+
+The callback function receives Unicode code points for key events that would
+have led to regular text input on that platform.
+
+@code
+void character_callback(GLFWwindow* window, unsigned int codepoint)
+{
+}
+@endcode
+
+If you wish to receive all Unicode code point events generated by the system, or
+just want to know exactly what modifier keys were used, set a character with
+modifiers callback with @ref glfwSetCharModsCallback.
+
+@code
+glfwSetCharCallback(window, charmods_callback);
+@endcode
+
+The callback function receives Unicode code points and
+[modifier bits](@ref mods).
+
+@code
+void charmods_callback(GLFWwindow* window, unsigned int codepoint, int mods)
+{
+}
+@endcode
+
 
 @section input_mouse Mouse input
 
+Mouse input comes in many forms, including of mouse motion and button presses,
+system cursor appearance and behavior, and two-dimensional scrolling.  All of
+these are supported by GLFW.
+
+
+@subsection input_cursor_pos Cursor position
+
+If you wish to be notified when the system cursor moves over the window, set
+a cursor position callback with @ref glfwSetCursorPosCallback.
+
+@code
+glfwSetCursorPosCallback(window, cursor_pos_callback);
+@endcode
+
+The callback functions receives the cursor position.  On platforms that provide
+it, the full sub-pixel cursor position is passed on.
+
+@code
+static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos)
+{
+}
+@endcode
+
+The cursor position is also saved per-window and can be polled with @ref
+glfwGetCursorPos.
+
+@code
+double xpos, ypos;
+glfwGetCursorPos(window, &xpos, &ypos);
+@endcode
+
+This function only returns cached cursor positions.  It does not poll the
+system for the current position.  Whenever you poll state, you risk missing the
+state change you are looking for.
+
+
+@subsection input_cursor_mode Cursor modes
+
+The `GLFW_CURSOR` input mode provides several cursor modes for special forms of
+mouse motion input.  By default, the `GLFW_CURSOR_NORMAL` cursor mode is used,
+meaning the regular arrow cursor or a [custom cursor](@ref input_cursor) is used
+and cursor motion is not limited.
+
+If you wish to implement mouse motion based camera controls or other input
+schemes that require unlimited mouse movement, set the cursor mode to
+`GLFW_CURSOR_DISABLED`.
+
+@code
+glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED);
+@endcode
+
+This will hide the cursor and lock it to the specified window.  GLFW will then
+take care of all the details of cursor re-centering and offset calculation and
+providing the application with a virtual cursor position.  This virtual position
+is provided normally, both via the cursor position callback and via position
+polling.
+
+@note You should not implement your own version of this functionality using
+other features of GLFW.  It will not work as robustly as `GLFW_CURSOR_DISABLED`,
+as those features are not intended for this purpose.
+
+If you just wish the cursor to become hidden when it is over a window, set
+the cursor mode to `GLFW_CURSOR_HIDDEN`.
+
+@code
+glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN);
+@endcode
+
+This mode puts no limit on the motion of the cursor.
+
+To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL`
+cursor mode.
+
+@code
+glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL);
+@endcode
+
+
+@subsection input_cursor Cursor objects
+
+GLFW supports creating custom system cursor images, encapsulated as @ref
+GLFWcursor objects.  They are created with @ref glfwCreateCursor and destroyed
+with @ref glfwDestroyCursor (or @ref glfwTerminate, if any remain).
+
+
+@subsubsection input_cursor_creation Cursor creation
+
+A cursor is created with @ref glfwCreateCursor, which returns a handle to the
+created cursor object.  For example, this creates a 16x16 white square cursor
+with the hot-spot in the upper-left corner:
+
+@code
+unsigned char pixels[16 * 16 * 4];
+memset(pixels, 0xff, sizeof(pixels));
+
+GLFWimage image;
+image.width = 16;
+image.height = 16;
+image.pixels = pixels;
+
+GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);
+@endcode
+
+The image data is 32-bit RGBA, i.e. eight bits per channel.  The pixels are
+arranged canonically as sequental rows, starting from the top-left corner.
+
+
+@subsubsection input_cursor_destruction Cursor destruction
+
+When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
+
+@code
+glfwDestroyCursor(cursor);
+@endcode
+
+Cursor destruction always succeeds.  All cursors remaining at the time of @ref
+glfwTerminate is called are destroyed as well.
+
+
+@subsubsection input_cursor_set Cursor setting
+
+A cursor can be set as current for a window with @ref glfwSetCursor.
+
+@code
+glfwSetCursor(window, cursor);
+@endcode
+
+Once set, the cursor image will be used as long as the system cursor is over the
+client area of the window and the [cursor mode](@ref input_cursor_mode) is set
+to `GLFW_CURSOR_NORMAL`.
+
+A single cursor may be set for any number of windows.
+
+To remove a cursor from a window, set the cursor of that window to `NULL`.
+
+@code
+glfwSetCursor(window, NULL);
+@endcode
+
+When a cursor is destroyed, it is removed from any window where it is set.  This
+does not affect the cursor modes of those windows.
+
+
+@subsection input_cursor_enter Cursor enter/leave events
+
+If you wish to be notified when the cursor enters or leaves the client area of
+a window, set a cursor enter/leave callback with @ref glfwSetCursorEnterCallback.
+
+@code
+glfwSetCursorEnterCallback(window, cursor_enter_callback);
+@endcode
+
+The callback function receives the new classification of the cursor.
+
+@code
+void cursor_enter_callback(GLFWwindow* window, int entered)
+{
+    if (entered)
+    {
+        // The cursor entered the client area of the window
+    }
+    else
+    {
+        // The cursor left the client area of the window
+    }
+}
+@endcode
+
+
+@subsection input_mouse_button Mouse button input
+
+If you wish to be notified when a mouse button is pressed or released, set
+a mouse button callback with @ref glfwSetMouseButtonCallback.
+
+@code
+glfwSetMouseButtonCallback(window, mouse_button_callback);
+@endcode
+
+The callback function receives the [mouse button](@ref buttons), button action
+and [modifier bits](@ref mods).
+
+@code
+void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)
+{
+    if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS)
+        popup_menu();
+}
+@endcode
+
+The action is one of `GLFW_PRESS` or `GLFW_RELEASE`.
+
+Mouse button states for [named buttons](@ref buttons) are also saved in
+per-window state arrays that can be polled with @ref glfwGetMouseButton.
+
+@code
+int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
+if (state == GLFW_PRESS)
+    upgrade_cow();
+@endcode
+
+The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
+
+This function only returns cached mouse button event state.  It does not poll
+the system for the current state of the mouse button.
+
+Whenever you poll state, you risk missing the state change you are looking for.
+If a pressed mouse button is released again before you poll its state, you will have
+missed the button press.  The recommended solution for this is to use a
+mouse button callback, but there is also the `GLFW_STICKY_MOUSE_BUTTONS`
+input mode.
+
+@code
+glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, 1);
+@endcode
+
+When sticky mouse buttons mode is enabled, the pollable state of a mouse button
+will remain `GLFW_PRESS` until the state of that button is polled with @ref
+glfwGetMouseButton.  Once it has been polled, if a mouse button release event
+had been processed in the meantime, the state will reset to `GLFW_RELEASE`,
+otherwise it will remain `GLFW_PRESS`.
+
+The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
+[named button](@ref buttons).
+
+
+@subsection input_scroll Scroll input
+
+If you wish to be notified when the user scrolls, whether with a mouse wheel or
+touchpad gesture, set a scroll callback with @ref glfwSetScrollCallback.
+
+@code
+glfwSetScrollCallback(window, scroll_callback);
+@endcode
+
+The callback function receives two-dimensional scroll offsets.
+
+@code
+void scroll_callback(GLFWwindow* window, double xoffset, double yoffset)
+{
+}
+@endcode
+
+A simple mouse wheel, being vertical, provides offsets along the Y-axis.
+
+
 @section input_joy Joystick input
 
+The joystick functions expose connected joysticks and controllers, with both
+referred to as joysticks.  It supports up to sixteen joysticks, ranging from
+`GLFW_JOYSTICK_1`, `GLFW_JOYSTICK_2` up to `GLFW_JOYSTICK_LAST`.  You can test
+whether a [joystick](@ref joysticks) is present with @ref glfwJoystickPresent.
+
+@code
+int present = glfwJoystickPresent(GLFW_JOYSTICK_1);
+@endcode
+
+When GLFW is initialized, detected joysticks are added to to the beginning of
+the array, starting with `GLFW_JOYSTICK_1`.  Once a joystick is detected, it
+keeps its assigned index until it is disconnected, so as joysticks are connected
+and disconnected, they will become spread out.
+
+Joystick state is updated as needed when a joystick function is called and does
+not require a window to be created or @ref glfwPollEvents or @ref glfwWaitEvents
+to be called.
+
+
+@subsection input_joy_axis Joystick axis states
+
+The positions of all axes of a joystick are returned by @ref
+glfwGetJoystickAxes.  See the reference documentation for the lifetime of the
+returned array.
+
+@code
+int count;
+const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_1, &count);
+@endcode
+
+Each element in the returned array is a value between -1.0 and 1.0.
+
+
+@subsection input_joy_button Joystick button states
+
+The states of all buttons of a joystick are returned by @ref
+glfwGetJoystickButtons.  See the reference documentation for the lifetime of the
+returned array.
+
+@code
+int count;
+const unsigned char* axes = glfwGetJoystickButtons(GLFW_JOYSTICK_1, &count);
+@endcode
+
+Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`.
+
+
+@subsection input_joy_name Joystick name
+
+The human-readable, UTF-8 encoded name of a joystick is returned by @ref
+glfwGetJoystickName.  See the reference documentation for the lifetime of the
+returned string.           
+
+@code
+const char* name = glfwGetJoystickName(GLFW_JOYSTICK_1);
+@endcode
+
+Joystick names are not guaranteed to be unique.  Two joysticks of the same model
+and make may have the same name.  Only the [joystick token](@ref joysticks) is
+guaranteed to be unique, and only until that joystick is disconnected.
+
+
+@section input_time Time input
+
+GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime.
+
+@code
+double seconds = glfwGetTime();
+@endcode
+
+It returns the number of seconds since the timer was started when the library
+was initialized with @ref glfwInit.  The platform-specific time sources used
+usually have micro- or nanosecond resolution.
+
+You can modify the reference time with @ref glfwSetTime.
+
+@code
+glfwSetTime(4.0);
+@endcode
+
+This sets the timer to the specified time, in seconds.
+
+
+@section input_clipboard Clipboard input and output
+
+If the system clipboard contains a UTF-8 encoded string or if it can be
+converted to one, you can retrieve it with @ref glfwGetClipboardString.  See the
+reference documentation for the lifetime of the returned string.
+
+@code
+const char* clipboard = glfwGetClipboardString(window);
+@endcode
+
+The contents of the system clipboard can be set to a UTF-8 encoded string with
+@ref glfwSetClipboardString.
+
+@code
+glfwSetClipboardString(window, "A string with words in it");
+@endcode
+
+The clipboard functions take a window handle argument because some window
+systems require a window to communicate with the system clipboard.  Any valid
+window may be used.
+
+
+@section input_drop Path drop input
+
+If you wish to receive the paths of files and/or directories dropped on
+a window, set a file drop callback with @ref glfwSetDropCallback.
+
+@code
+glfwSetDropCallback(window, drop_callback);
+@endcode
+
+The callback function receives an array of paths encoded as UTF-8.
+
+@code
+void drop_callback(GLFWwindow* window, int count, const char** paths)
+{
+    int i;
+    for (i = 0;  i < count;  i++)
+        handle_dropped_file(paths[i]);
+}
+@endcode
+
+The path array and its strings are only valid until the file drop callback
+returns, as they may have been generated specifically for that event.  You need
+to make a deep copy of the array if you want to keep the paths.
+
 */

docs/intro.dox

@@ -1,12 +1,13 @@
 /*! 
 
-@page intro Introduction to the GLFW API
+@page intro Introduction to the API
  
 @tableofcontents
 
-This guide will introduce the basic concepts of GLFW and describes
+This guide introduces the basic concepts of GLFW and describes initialization,
-initialization, error handling and version management.  There are other guides
+error handling and API guarantees and limitations.  For a broad but shallow
-for the various areas of the GLFW API.
+tutorial, see @ref quick instead.  There are also guides for the other areas of
+GLFW.
 
  - @ref window
  - @ref context
@@ -22,7 +23,7 @@ enumerates monitors and joysticks, initializes the timer and performs any
 required platform-specific initialization.
 
 Only the following functions may be called before the library has been
-successfully initialized.
+successfully initialized, and only from the main thread.
 
  - @ref glfwGetVersion
  - @ref glfwGetVersionString
@@ -36,8 +37,8 @@ error.
 
 @subsection intro_init_init Initializing GLFW
 
-The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an
+The library is initialized with @ref glfwInit, which returns zero if an error
-error occurred.
+occurred.
 
 @code
 if (!glfwInit())
@@ -49,7 +50,7 @@ if (!glfwInit())
 If any part of initialization fails, all remaining bits are terminated as if
 @ref glfwTerminate was called.  The library only needs to be initialized once
 and additional calls to an already initialized library will simply return
-`GL_TRUE` immediately.
+non-zero immediately.
 
 Once the library has been successfully initialized, it should be terminated
 before the application exits.
@@ -74,23 +75,24 @@ library had not been successfully initialized or had already been terminated,
 additional calls return immediately. 
 
 
-@section intro_error Error handling
+@section error_handling Error handling
 
 Some GLFW functions have return values that indicate an error, but this is often
-not very helpful when trying to figure out *why* the error occurred.  Also, far
+not very helpful when trying to figure out *why* the error occurred.  Some
-from all GLFW functions have such return values.
+functions also return otherwise valid values on error.  Finally, far from all
+GLFW functions have return values.
 
 This is where the error callback comes in.  This callback is called whenever an
 error occurs.  It is set with @ref glfwSetErrorCallback, a function that may be
-called before @ref glfwInit and after @ref glfwTerminate.
+called regardless of whether GLFW is initialized.
 
 @code
 glfwSetErrorCallback(error_callback);
 @endcode
 
 The error callback receives a human-readable description of the error and (when
-possible) its cause.  The description is a regular C string using the UTF-8
+possible) its cause.  The description encoded as UTF-8.  The callback is also
-encoding.  The callback is also provided with an [error code](@ref errors). 
+provided with an [error code](@ref errors). 
 
 @code
 void error_callback(int error, const char* description)
@@ -100,25 +102,177 @@ void error_callback(int error, const char* description)
 @endcode
 
 The error code indicates the general category of the error.  Some error codes,
-such as `GLFW_NOT_INITIALIZED` has only a single meaning, whereas others like
+such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
-`GLFW_PLATFORM_ERROR` are used for many different errors.
+@ref GLFW_PLATFORM_ERROR are used for many different errors.
 
-@note The description string is only valid until the error callback returns, as
+The description string is only valid until the error callback returns, as it may
-it may have been generated specifically for that error.  This lets GLFW provide
+have been generated specifically for that error.  This lets GLFW provide much
-much more specific error descriptions but means you must make a copy if you want
+more specific error descriptions but means you must make a copy if you want to
-to keep the description string.
+keep the description string.
+
+
+@section coordinate_systems Coordinate systems
+
+GLFW has two primary coordinate systems: the _virtual screen_ and the window
+_client area_.  Both use the same unit: _virtual screen coordinates_, or just
+_screen coordinates_, which don't necessarily correspond to pixels.
+
+<img src="spaces.svg" width="90%" />
+
+Window and monitor positions are specified relative to the upper-left corners of
+their content areas, while cursor positions are specified relative to the window
+client area.
+
+The origin of the window client area coordinate system is also the position of
+the window, meaning you can translate client area coordinates to the virtual
+screen by adding the window position.  The window frame, when present, extend
+out from the client area but does not affect the window position.
+
+Almost all positions and sizes in GLFW are measured in screen coordinates
+relative to one of the two origins above.  This includes cursor positions,
+window positions and sizes, window frame sizes, monitor positions and video mode
+resolutions.
+
+Two exceptions are the [monitor physical size](@ref monitor_size), which is
+measured in millimetres, and [framebuffer size](@ref window_fbsize), which is
+measured in pixels.
+
+Pixels and screen coordinates may map 1:1 on your machine, but they won't on
+every other machine, for example on a Mac with a Retina display.  The ratio
+between screen coordinates and pixels may also change at run-time depending on
+which monitor the window is currently on.
+
+
+@section guarantees_limitations Guarantees and limitations
+
+This section describes the conditions under which GLFW can be expected to
+function, barring any bugs in GLFW, the operating system or drivers.  Use of
+GLFW outside of these limits may work on some platforms, or on some machines, or
+some of the time, or on some versions of GLFW, but it may break at any time and
+will not be considered a bug.
+
+
+@subsection lifetime Pointer lifetimes
+
+GLFW will never free any pointer you provide to it and you must never free any
+pointer it provides to you.
+
+Many GLFW functions return pointers to dynamically allocated structures, strings
+or arrays, and some callbacks are provided with strings or arrays.  These are
+always managed by GLFW and should never be freed by the application.  The
+lifetime of these pointers is documented for each GLFW function and callback.
+If you need to keep this data, you must copy it before its lifetime expires.
+
+Many GLFW functions accept pointers to structures or strings allocated by the
+application.  These are never freed by GLFW and are always the responsibility of
+the application.  If GLFW needs to keep the data in these structures or strings,
+they are copied before the function returns.
+
+Pointer lifetimes are guaranteed not to be shortened in future minor releases.
+
+
+@subsection reentrancy Reentrancy
+
+GLFW event processing and object creation and destruction are not reentrant.
+This means that the following functions may not be called from any callback
+function:
+
+ - @ref glfwCreateWindow
+ - @ref glfwDestroyWindow
+ - @ref glfwCreateCursor
+ - @ref glfwDestroyCursor
+ - @ref glfwPollEvents
+ - @ref glfwWaitEvents
+
+
+@subsection thread_safety Thread safety
+
+Most GLFW functions may only be called from the main thread.  The reference
+documentation for every GLFW function states whether it is limited to the main
+thread.
+
+There are some general rules that make it easier to remember which functions are
+limited to the main thread.  The following tasks may only be performed on the
+main thread:
+
+ - Initialization and termination
+ - Event processing
+ - Creation and destruction of window, context and cursor objects
+
+Because event processing must be performed on the main thread, all callbacks
+except for the error callback will only be called on that thread.  The error
+callback may be called on any thread, as any GLFW function may generate errors.
+
+The posting of empty events may be done from any thread.  The window user
+pointer and close flag may also be accessed and modified from any thread, but
+this is not synchronized by GLFW.  The following window related functions may
+be called from any thread:
+
+ - @ref glfwPostEmptyEvent
+ - @ref glfwGetWindowUserPointer
+ - @ref glfwSetWindowUserPointer
+ - @ref glfwWindowShouldClose
+ - @ref glfwSetWindowShouldClose
+
+Rendering may be done on any thread.  The following context related functions
+may be called from any thread:
+
+ - @ref glfwMakeContextCurrent
+ - @ref glfwGetCurrentContext
+ - @ref glfwSwapBuffers
+ - @ref glfwSwapInterval
+ - @ref glfwExtensionSupported
+ - @ref glfwGetProcAddress
+
+The timer may be accessed from any thread, but this is not synchronized by GLFW.
+The following timer related functions may be called from any thread:        
+
+ - @ref glfwGetTime
+
+No GLFW function may be called from any other thread until GLFW has been
+successfully initialized on the main thread, including functions that may called
+before initialization.
+
+GLFW uses no synchronization objects internally except for thread-local storage
+to keep track of the current context for each thread.  Synchronization is left
+to the application.
+
+Functions that may currently be called from any thread will always remain so,
+but functions that are currently limited to the main may be updated to allow
+calls from any thread in future releases.
+
+
+@subsection compatibility Version compatibility
+
+GLFW guarantees binary backward compatibility with earlier minor versions of the
+API.  This means that you can drop in a newer version of the GLFW DLL / shared
+library / dynamic library and existing applications will continue to run.
+
+Once a function or constant has been added, the signature of that function or
+value of that constant will remain unchanged until the next major version of
+GLFW.  No compatibility of any kind is guaranteed between major versions.
+
+Undefined behavior, i.e. behavior that is not described in reference
+documentation, may change at any time until it is documented.
+
+If the reference documentation and the implementation differ, the reference
+documentation is correct and the implementation will be fixed in the next
+release.
+
+
+@subsection event_order Event order
+
+The order of arrival of related events is not guaranteed to be consistent
+across platforms.  The exception is synthetic key and mouse button release
+events, which are always delivered after the window defocus event.
 
 
 @section intro_version Version management
 
 GLFW provides mechanisms for identifying what version of GLFW your application
-was compiled against as well as what version it is currently using.  The GLFW
+was compiled against as well as what version it is currently running against.
-API is binary-compatible with later minor versions, i.e. an executable using the
+If you are loading GLFW dynamically (not just linking dynamically), you can use
-3.0 API will be able to use a version 3.2 DLL.
+this to verify that the library binary is compatible with your application.
-
-As long as an executable does not use any newer functions, it can also use an
-older minor version DLL, although any window hints or other tokens added since
-that older version will cause errors to be reported.
 
 
 @subsection intro_version_compile Compile-time version
@@ -126,15 +280,24 @@ that older version will cause errors to be reported.
 The compile-time version of GLFW is provided by the GLFW header with the
 `GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.
 
+@code
+printf("Compiled against GLFW %i.%i.%i\n",
+       GLFW_VERSION_MAJOR,
+       GLFW_VERSION_MINOR,
+       GLFW_VERSION_REVISION);
+@endcode
+
 
 @subsection intro_version_runtime Run-time version
 
 The run-time version can be retrieved with @ref glfwGetVersion, a function that
-may be called before @ref glfwInit and after @ref glfwTerminate 
+may be called regardless of whether GLFW is initialized.
 
 @code
 int major, minor, revision;
 glfwGetVersion(&major, &minor, &revision);
+
+printf("Running against GLFW %i.%i.%i\n", major, minor, revision);
 @endcode
 
 
@@ -146,7 +309,7 @@ This is primarily intended for submitting bug reports, to allow developers to
 see which code paths are enabled in a binary.
 
 The version string is returned by @ref glfwGetVersionString, a function that may
-be called before @ref glfwInit and after @ref glfwTerminate.
+be called regardless of whether GLFW is initialized.
 
 The format of the string is as follows:
  - The version of GLFW
@@ -157,7 +320,9 @@ The format of the string is as follows:
 For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
 back ends, the version string may look something like this:
 
+@code
 3.0.0 Win32 WGL MinGW
+@endcode
 
 @note Do not parse the version string to find the GLFW library version.  The
 @ref glfwGetVersion function provides the version of the library binary in

docs/main.dox

@@ -4,19 +4,39 @@
 
 @section main_intro Introduction
 
-GLFW is a free, Open Source, multi-platform library for opening a window,
+__GLFW__ is a free, Open Source, multi-platform library for creating windows
-creating an OpenGL context and managing input.  It is easy to integrate into
+with OpenGL or OpenGL ES contexts and receiving many kinds of input.  It is easy
-existing applications and does not lay claim to the main loop.
+to integrate into existing applications and does not lay claim to the main loop.
 
-This is the documentation for version 3.1, which has [many new features](@ref news).
+This is the documentation for version 3.1, which adds many
+[new features](@ref news).
 
-There is a [quick tutorial](@ref quick) for people new to GLFW, which shows how
+@ref quick is a guide for those new to GLFW.  It takes you through how to write
-to write a small but complete program, and guides for
+a small but complete program.  For people coming from GLFW 2, the @ref moving
-[compiling GLFW](@ref compile) and
+guide explains what has changed and how to update existing code to use the new
-[building programs that use GLFW](@ref build).
+API.
 
-If you have used GLFW 2.x in the past, there is a
+There are guides for each of the various areas of the API.
-[transition guide](@ref moving) that explains what has changed and how to update
+
-existing code to use the new API.
+ - @ref intro
+ - @ref window
+ - @ref context
+ - @ref monitor
+ - @ref input
+
+The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
+design, implementation and use of GLFW.
+
+The [reference documentation](modules.html) provides more detailed information
+about specific functions.
+
+Once you have written a program, see the @ref compile and @ref build guides.        
+
+Finally, the @ref compat guide explains what APIs, standards and protocols GLFW
+uses and what happens when they are not present on a given machine.
+
+This documentation was generated with Doxygen.  The sources for it are available
+in both the [source distribution](http://www.glfw.org/download.html) and
+[GitHub repository](https://github.com/glfw/glfw).
 
 */

docs/monitor.dox

@@ -1,9 +1,20 @@
 /*!
 
-@page monitor Multi-monitor guide
+@page monitor Monitor guide
 
 @tableofcontents
 
+This guide introduces the monitor related functions of GLFW.  There are also
+guides for the other areas of GLFW.
+
+ - @ref intro
+ - @ref window
+ - @ref context
+ - @ref input
+
+To see how GLFW views your monitor setup and its available video modes, run the
+`modes` test program.
+
 
 @section monitor_objects Monitor objects
 
@@ -26,22 +37,44 @@ provide into the virtual desktop that spans them.
 
 The primary monitor is returned by @ref glfwGetPrimaryMonitor.  It is the user's
 preferred monitor and is usually the one with global UI elements like task bar
-or menu bar.
+or menu bar.  The returned structure is allocated and freed by GLFW.
 
 @code
 GLFWmonitor* primary = glfwGetPrimaryMonitor();
 @endcode
 
 You can retrieve all currently connected monitors with @ref glfwGetMonitors.
-The primary monitor is always the first monitor in the returned array.
+See the reference documentation for the lifetime of the returned array.
 
 @code
 int count;
 GLFWmonitor** monitors = glfwGetMonitors(&count);
 @endcode
 
-@note Monitors other than the primary monitor may be moved to a different index
+The primary monitor is always the first monitor in the returned array, but other
-in the array if another monitor is disconnected.
+monitors may be moved to a different index when a monitor is connected or
+disconnected.
+
+
+@subsection monitor_event Monitor configuration changes
+
+If you wish to be notified when a monitor is connected or disconnected, set
+a monitor callback with @ref glfwSetMonitorCallback.
+
+@code
+glfwSetMonitorCallback(monitor_callback);
+@endcode
+
+The callback function receives the handle for the monitor that has been
+connected or disconnected and a monitor action.
+
+@code
+void monitor_callback(GLFWmonitor* monitor, int event)
+{
+}
+@endcode
+
+The action is one of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
 
 
 @section monitor_properties Monitor properties
@@ -52,15 +85,19 @@ Although GLFW generally does a good job at selecting a suitable video
 mode for you when you open a full screen window, it is sometimes useful to
 know exactly which modes are available on a certain system. For example,
 you may want to present the user with a list of video modes to select
-from. To get a list of available video modes, you can use the function
+from.
-@ref glfwGetVideoModes.
+
+To get a list of available video modes, you can use the function @ref
+glfwGetVideoModes.  See the reference documentation for the lifetime of the
+returned array.
 
 @code
 int count;
 GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
 @endcode
 
-To get the current video mode of a monitor call @ref glfwGetVideoMode.
+To get the current video mode of a monitor call @ref glfwGetVideoMode.  See the
+reference documentation for the lifetime of the returned structure.
 
 @code
 const GLFWvidmode* mode = glfwGetVideoMode(monitor);
@@ -98,16 +135,17 @@ glfwGetMonitorPos(monitor, &xpos, &ypos);
 
 @subsection monitor_name Human-readable name
 
-The human-readable name of a monitor is returned by @ref glfwGetMonitorName.
+The human-readable, UTF-8 encoded name of a monitor is returned by @ref
-It is a regular C string using the UTF-8 encoding.
+glfwGetMonitorName.  See the reference documentation for the lifetime of the
+returned string.
 
 @code
 const char* name = glfwGetMonitorName(monitor);
 @endcode
 
-@note Monitor names are not guaranteed to be unique.  Two monitors of the same
+Monitor names are not guaranteed to be unique.  Two monitors of the same model
-model and make may have the same name.  Only the address of a monitor object is
+and make may have the same name.  Only the monitor handle is guaranteed to be
-guaranteed to be unique.
+unique, and only until that monitor is disconnected.
 
 
 @subsection monitor_gamma Gamma ramp
@@ -136,10 +174,10 @@ The gamma ramp data is copied before the function returns, so there is no need
 to keep it around once the ramp has been set.
 
 @note It is recommended to use gamma ramps of size 256, as that is the size
-supported by virtually all graphics cards on all platforms.
+supported by all graphics cards on all platforms.
 
-The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp.  The
+The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp.  See
-returned structure and its arrays are allocated and freed by GLFW.
+the reference documentation for the lifetime of the returned structure.
 
 @code
 const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);

docs/moving.dox

@@ -38,7 +38,9 @@ The threading functions have been removed, including the per-thread sleep
 function.  They were fairly primitive, under-used, poorly integrated and took
 time away from the focus of GLFW (i.e.  context, input and window).  There are
 better threading libraries available and native threading support is available
-in both C++11 and C11, both of which are gaining traction. 
+in both [C++11](http://en.cppreference.com/w/cpp/thread) and
+[C11](http://en.cppreference.com/w/c/thread), both of which are gaining
+traction. 
 
 If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
 support them, see the
@@ -148,7 +150,7 @@ into [window hints](@ref window_hints), but as they have been given
 GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
 means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
 Unlike buffer swap, which acts on a single window, **glfwPollEvents** and
-**glfwWaitEvents** process events for all windows at once.
+__glfwWaitEvents__ process events for all windows at once.
 
 @par Old basic main loop
 @code
@@ -412,10 +414,15 @@ these hotkeys to function even when running in full screen mode.
 
 @subsection moving_terminate Automatic termination
 
-GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization.  To
+GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization,
-release all resources allocated by GLFW, you should call @ref glfwTerminate
+because `exit` calls registered functions from the calling thread and while it
-yourself.  Note that this destroys all windows not already destroyed with @ref
+is permitted to call `exit` from any thread, @ref glfwTerminate may only be
-glfwDestroyWindow, invalidating all window handles you may still have.
+called from the main thread.
+
+To release all resources allocated by GLFW, you should call @ref glfwTerminate
+yourself, from the main thread, before the program terminates.  Note that this
+destroys all windows not already destroyed with @ref glfwDestroyWindow,
+invalidating any window handles you may still have.
 
 
 @subsection moving_glu GLU header inclusion

docs/news.dox

@@ -10,17 +10,18 @@
 @subsection news_31_cursor Custom system cursor support
 
 GLFW now supports creating and setting custom system cursors.  They can be
-created with @ref glfwCreateCursor and set with @ref glfwSetCursor.  Note that
+created with @ref glfwCreateCursor, set with @ref glfwSetCursor and destroyed
-custom cursors are only visible in normal cursor mode.
+with @ref glfwDestroyCursor.  Custom cursors are only visible in normal cursor
+mode.
 
 
 @subsection news_31_drop File drop event support
 
 GLFW now provides a callback for receiving the paths of files dropped onto GLFW
-windows.  The callback is set with the @ref glfwSetDropCallback function.
+windows.  The callback is set with @ref glfwSetDropCallback.
 
 
-@subsection news_31_emptyevent Empty event support
+@subsection news_31_emptyevent Main thread waking support
 
 GLFW now provides the @ref glfwPostEmptyEvent function for posting an empty
 event from another thread to the main thread event queue, causing @ref
@@ -36,29 +37,43 @@ client area of a window, with @ref glfwGetWindowFrameSize.
 @subsection news_31_autoiconify Multi-monitor installation support
 
 GLFW now supports disabling auto-iconification of full screen windows with
-[GLFW_AUTO_ICONIFY](@ref window_hints_wnd).  This is intended for people
+the [GLFW_AUTO_ICONIFY](@ref window_hints_wnd) window hint.  This is intended
-building multi-monitor installations, where you need windows to stay in full
+for people building multi-monitor installations, where you need windows to stay
-screen despite losing focus.
+in full screen despite losing focus.
 
 
 @subsection news_31_floating Floating windows
 
 GLFW now supports floating windows, also called topmost or always on top, for
-easier debugging, with the `GLFW_FLOATING` window hint.
+easier debugging with the [GLFW_FLOATING](@ref window_hints_wnd) window hint.
 
 
 @subsection news_31_focused Initially unfocused windows
 
 GLFW now supports preventing a windowed mode window from gaining input focus on
-creation, with the `GLFW_FOCUSED` window hint.
+creation, with the [GLFW_FOCUSED](@ref window_hints_wnd) window hint.
 
 
 @subsection news_31_charmods Character with modifiers callback
 
-GLFW now provides a callback for character events with modifier key bits.
+GLFW now provides a callback for character events with modifier key bits.  The
-Unlike the regular character callback, this will report character events that
+callback is set with @ref glfwSetCharModsCallback.  Unlike the regular character
-will not result in a character being input, for example if the Control key is
+callback, this will report character events that will not result in a character
-held down.
+being input, for example if the Control key is held down.
+
+
+@subsection news_31_release Context release behavior support
+
+GLFW now supports controlling whether the pipeline is flushed when a context is
+made non-current, with the
+[GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint, provided the
+machine supports the `GL_KHR_context_flush_control` extension.
+
+
+@subsection news_31_single Single buffering support
+
+GLFW now supports the creation of single buffered windows, with the
+[GLFW_DOUBLEBUFFER](@ref window_hints_fb) window hint.
 
 
 @subsection news_31_egl Stable EGL support

docs/quick.dox

@@ -1,23 +1,25 @@
 /*!
 
-@page quick Getting started — A quick introduction
+@page quick Getting started
 
 @tableofcontents
 
-This guide will show how to write simple OpenGL applications using GLFW 3.  It
+This guide takes you through writing a simple application using GLFW 3.  The
-will introduce a few of the most commonly used functions, but there are many
+application will create a window and OpenGL context, render a rotating triangle
-others.  To see detailed documentation on any GLFW function, just click on its
+and exit when the user closes the window or presses Escape.  This guide will
-name.
+introduce a few of the most commonly used functions, but there are many more.
 
 This guide assumes no experience with earlier versions of GLFW.  If you
-have used GLFW 2.x in the past, you should also read the
+have used GLFW 2 in the past, read the @ref moving guide, as some functions
-[transition guide](@ref moving).
+behave differently in GLFW 3.
 
 
-@section quick_include Including the GLFW header
+@section quick_steps Step by step
 
-In the files of your program where you use OpenGL or GLFW, you need to include
+@subsection quick_include Including the GLFW header
-the GLFW 3 header file.
+
+In the source files of your application where you use OpenGL or GLFW, you need
+to include the GLFW 3 header file.
 
 @code
 #include <GLFW/glfw3.h>
@@ -54,40 +56,39 @@ inclusion of the GLFW header.
 @endcode
 
 
-@section quick_init_term Initializing and terminating GLFW
+@subsection quick_init_term Initializing and terminating GLFW
 
-Before you can use most GLFW functions, the library must be initialized.  This
+Before you can use most GLFW functions, the library must be initialized.  On
-is done with @ref glfwInit, which returns non-zero if successful, or zero if an
+successful initialization, non-zero is returned.  If an error occurred, zero is
-error occurred.
+returned.
 
 @code
 if (!glfwInit())
     exit(EXIT_FAILURE);
 @endcode
 
-When you are done using GLFW, typically at the very end of the program, you need
+When you are done using GLFW, typically just before the application exits, you
-to call @ref glfwTerminate.
+need to terminate GLFW.
 
 @code
 glfwTerminate();
 @endcode
 
 This destroys any remaining windows and releases any other resources allocated by
-GLFW.  After this call, you must call @ref glfwInit again before using any GLFW
+GLFW.  After this call, you must initialize GLFW again before using any GLFW
 functions that require it.
 
 
-@section quick_capture_error Setting an error callback
+@subsection quick_capture_error Setting an error callback
 
 Most events are reported through callbacks, whether it's a key being pressed,
 a GLFW window being moved, or an error occurring.  Callbacks are simply
 C functions (or C++ static methods) that are called by GLFW with arguments
 describing the event.
 
-In case @ref glfwInit or any other GLFW function fails, an error is reported to
+In case a GLFW function fails, an error is reported to the GLFW error callback.
-the GLFW error callback.  You can receive these reports by setting the error
+You can receive these reports with an error callback.  This function must have
-callback.  The callback function itself should match the signature of @ref
+the signature below.  This simple error callback just prints the error
-GLFWerrorfun.  Here is a simple error callback that just prints the error
 description to `stderr`.
 
 @code
@@ -97,28 +98,28 @@ void error_callback(int error, const char* description)
 }
 @endcode
 
-Setting the callback, so GLFW knows to call it, is done with @ref
+Callback functions must be set, so GLFW knows to call them.  The function to set
-glfwSetErrorCallback.  This is one of the few GLFW functions that may be called
+the error callback is one of the few GLFW functions that may be called before
-before @ref glfwInit, which lets you be notified of errors during
+initialization, which lets you be notified of errors both during and after
-initialization, so you should set it before you do anything else with GLFW.
+initialization.
 
 @code
 glfwSetErrorCallback(error_callback);
 @endcode
 
 
-@section quick_create_window Creating a window and context
+@subsection quick_create_window Creating a window and context
 
-The window (and its context) is created with @ref glfwCreateWindow, which
+The window and its OpenGL context are created with a single call, which returns
-returns a handle to the created window.  For example, this creates a 640 by 480
+a handle to the created combined window and context object.  For example, this
-windowed mode window:
+creates a 640 by 480 windowed mode window with an OpenGL context:
 
 @code
 GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
 @endcode
 
-If window creation fails, `NULL` will be returned, so you need to check whether
+If window or context creation fails, `NULL` will be returned, so it is necessary
-it did.
+to check the return value.
 
 @code
 if (!window)
@@ -128,24 +129,11 @@ if (!window)
 }
 @endcode
 
-This handle is then passed to all window related functions, and is provided to
+The window handle is passed to all window related functions and is provided to
-you along with input events, so you know which window received the input.
+along to all window related callbacks, so they can tell which window received
+the event.
 
-To create a full screen window, you need to specify which monitor the window
+When a window is no longer needed, destroy it.
-should use.  In most cases, the user's primary monitor is a good choice.  You
-can get this with @ref glfwGetPrimaryMonitor.  To make the above window
-full screen, just pass along the monitor handle:
-
-@code
-GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
-@endcode
-
-Full screen windows cover the entire display area of a monitor, have no border
-or decorations, and change the monitor's resolution to the one most closely
-matching the requested window size.
-
-When you are done with the window, destroy it with the @ref glfwDestroyWindow
-function.
 
 @code
 glfwDestroyWindow(window);
@@ -155,22 +143,22 @@ Once this function is called, no more events will be delivered for that window
 and its handle becomes invalid.
 
 
-@section quick_context_current Making the OpenGL context current
+@subsection quick_context_current Making the OpenGL context current
 
 Before you can use the OpenGL API, it must have a current OpenGL context.  You
-make a window's context current with @ref glfwMakeContextCurrent.  It will then
+make a window's context current.
-remain as the current context until you make another context current or until
-the window owning it is destroyed.
 
 @code
 glfwMakeContextCurrent(window);
 @endcode
 
+The context will then remain as current until you make another context current
+or until the window owning the current context is destroyed.                    
 
-@section quick_window_close Checking the window close flag
 
-Each window has a flag indicating whether the window should be closed.  This can
+@subsection quick_window_close Checking the window close flag
-be checked with @ref glfwWindowShouldClose.  
+
+Each window has a flag indicating whether the window should be closed.
 
 When the user attempts to close the window, either by pressing the close widget
 in the title bar or using a key combination like Alt+F4, this flag is set to 1.
@@ -194,11 +182,11 @@ useful if you want to interpret other kinds of input as closing the window, like
 for example pressing the escape key.
 
 
-@section quick_key_input Receiving input events
+@subsection quick_key_input Receiving input events
 
 Each window has a large number of callbacks that can be set to receive all the
-various kinds of events.  To receive key press and release events, a
+various kinds of events.  To receive key press and release events, create a key
-[key callback](@ref GLFWkeyfun) is set using @ref glfwSetKeyCallback.
+callback function.
 
 @code
 static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
@@ -208,16 +196,21 @@ static void key_callback(GLFWwindow* window, int key, int scancode, int action,
 }
 @endcode
 
-For event callbacks to actually be called when an event occurs, you need to
+The key callback, like other window related callbacks, are set per-window.
-process events as described below.
+
+@code
+glfwSetKeyCallback(window, key_callback);
+@endcode
+
+In order for event callbacks to be called when events occur, you need to process
+events as described below.
 
 
-@section quick_render Rendering with OpenGL
+@subsection quick_render Rendering with OpenGL
 
 Once you have a current OpenGL context, you can use OpenGL normally.  In this
 tutorial, a multi-colored rotating triangle will be rendered.  The framebuffer
-size, needed by this example for `glViewport` and `glOrtho`, is retrieved with
+size needs to be retrieved for `glViewport`.
-@ref glfwGetFramebufferSize.
 
 @code
 int width, height;
@@ -225,72 +218,80 @@ glfwGetFramebufferSize(window, &width, &height);
 glViewport(0, 0, width, height);
 @endcode
 
-However, you can also set a framebuffer size callback using @ref
+You can also set a framebuffer size callback using @ref
 glfwSetFramebufferSizeCallback and call `glViewport` from there.
 
-@code
-void framebuffer_size_callback(GLFWwindow* window, int width, int height)
-{
-    glViewport(0, 0, width, height);
-}
-@endcode
 
+@subsection quick_timer Reading the timer
 
-@section quick_timer Reading the timer
+To create smooth animation, a time source is needed.  GLFW provides a timer that
-
+returns the number of seconds since initialization.  The time source used is the
-For the triangle to rotate properly, a time source is needed.  GLFW provides
+most accurate on each platform and generally has micro- or nanosecond
-@ref glfwGetTime, which returns the number of seconds since @ref glfwInit as
+resolution.
-a `double`.  The time source used is the most accurate on each platform and
-generally has micro- or nanosecond resolution.
 
 @code
 double time = glfwGetTime();
 @endcode
 
 
-@section quick_swap_buffers Swapping buffers
+@subsection quick_swap_buffers Swapping buffers
 
-GLFW windows by default use double buffering.  That means that you have two
+GLFW windows by default use double buffering.  That means that each window has
-rendering buffers; a front buffer and a back buffer.  The front buffer is the
+two rendering buffers; a front buffer and a back buffer.  The front buffer is
-one being displayed and the back buffer the one you render to.
+the one being displayed and the back buffer the one you render to.
 
-When the entire frame has been rendered, it is time to swap the back and the
+When the entire frame has been rendered, the buffers need to be swapped with one
-front buffers in order to display the rendered frame, and begin rendering a new
+another, so the back buffer becomes the front buffer and vice versa.
-frame.  This is done with @ref glfwSwapBuffers.
 
 @code
 glfwSwapBuffers(window);
 @endcode
 
+The swap interval indicates how many frames to wait until swapping the buffers,
+commonly known as *vsync*.  By default, the swap interval is zero, meaning
+buffer swapping will occur immediately.  On fast machines, many of those frames
+will never be seen, as the screen is still only updated typically 60-75 times
+per second, so this wastes a lot of CPU and GPU cycles.
 
-@section quick_process_events Processing events
+Also, because the buffers will be swapped in the middle the screen update,
+leading to [screen tearing](https://en.wikipedia.org/wiki/Screen_tearing).
+
+For these reasons, applications will typically want to set the swap interval to
+one.  It can be set to higher values, but this is usually not recommended,
+because of the input latency it leads to.
+
+@code
+glfwSwapInterval(1);
+@endcode
+
+This function acts on the current context and will fail unless a context is
+current.
+
+
+@subsection quick_process_events Processing events
 
 GLFW needs to communicate regularly with the window system both in order to
-receive events and to show that it hasn't locked up.  Event processing must be
+receive events and to show that the application hasn't locked up.  Event
-done regularly and is normally done each frame before rendering but after buffer
+processing must be done regularly while you have visible windows and is normally
-swap.
+done each frame after buffer swapping.
 
-There are two ways to process pending events.  @ref glfwPollEvents processes
+There are two methods for processing pending events; polling and waiting.  This
-only those events that have already been received and then returns immediately.
+example will use event polling, which processes only those events that have
-This is the best choice when rendering continually, like most games do.
+already been received and then returns immediately.  
 
 @code
 glfwPollEvents();
 @endcode
 
-If instead you only need to update your rendering once you have received new
+This is the best choice when rendering continually, like most games do.  If
-input, @ref glfwWaitEvents is a better choice.  It waits until at least one
+instead you only need to update your rendering once you have received new input,
-event has been received, putting the thread to sleep in the meantime, and then
+@ref glfwWaitEvents is a better choice.  It waits until at least one event has
-processes all received events just like @ref glfwPollEvents does.  This saves
+been received, putting the thread to sleep in the meantime, and then processes
-a great deal of CPU cycles and is useful for, for example, many kinds of editing
+all received events.  This saves a great deal of CPU cycles and is useful for,
-tools.
+for example, many kinds of editing tools.
-
-@code
-glfwWaitEvents();
-@endcode
 
 
-@section quick_example Putting it together: A simple application
+@section quick_example Putting it together
 
 Now that you know how to initialize GLFW, create a window and poll for
 keyboard input, it's possible to create a simple program.

docs/rift.dox

@@ -0,0 +1,91 @@
+/*!
+
+@page rift Oculus Rift guide
+ 
+@tableofcontents
+
+GLFW has no explicit support for the Oculus Rift, but 
+
+This guide requires you to use the [native API](@ref native) and assumes
+a certain level of proficiency with system level APIs and the compiler
+toolchain.
+
+
+@section rift_init Initializing libOVR and GLFW
+
+libOVR needs to be initialized before GLFW.  This means calling
+`ovr_Initialize`, `ovrHmd_Create` and `ovrHmd_ConfigureTracking` before @ref
+glfwInit.  Similarly, libOVR must be shut down after GLFW.  This means calling
+`ovrHmd_Destroy` and `ovr_Shutdown` after @ref glfwTerminate.
+
+
+@section rift_extend Extend Desktop mode
+
+@subsection rift_extend_detect Detecting a Rift with GLFW
+
+If you have an actual Rift connected to your machine you can deduce which GLFW
+monitor it corresponds to.  Doing this requires you to use the
+[native API](@ref native).
+
+
+@subsubsection rift_extend_detect_win32 Detecting a Rift on Windows
+
+To identify which monitor corresponds to the Rift, compare Win32 display device
+names.  The display device name of a GLFW monitor is returned by @ref
+glfwGetWin32Monitor and the display device name of the detected Rift is stored
+in the `DisplayDeviceName` member of `ovrHmdDesc`.
+
+@code
+int i, count;
+GLFWmonitor* monitor = NULL;
+GLFWmonitor** monitors = glfwGetMonitors(&count);
+
+for (i = 0;  i < count;  i++)
+{
+    if (strcmp(glfwGetWin32Monitor(monitors[i]), hmd->DisplayDeviceName) == 0)
+    {
+        monitor = monitors[i];
+        break;
+    }
+}
+@endcode
+
+
+@subsubsection rift_extend_detect_osx Detecting a Rift on OS X
+
+To identify which monitor corresponds to the Rift, compare OS X display IDs.
+The display ID of a GLFW monitor is returned by @ref glfwGetCocoaMonitor and the
+display ID of the detected Rift is stored in the `DisplayId` member of
+`ovrHmdDesc`.
+
+@code
+int i, count;
+GLFWmonitor* monitor = NULL;
+GLFWmonitor** monitors = glfwGetMonitors(&count);
+
+for (i = 0;  i < count;  i++)
+{
+    if (glfwGetCocoaMonitor(monitors[i]) == hmd->DisplayId)
+    {
+        monitor = monitors[i];
+        break;
+    }
+}
+@endcode
+
+
+@subsubsection rift_extend_detect_x11 Detecting a Rift on X11
+
+At the time of writing, the 0.4 Rift SDK does not yet support X11.
+
+
+@subsection rift_extend_create Creating a window and context
+
+LOL create.
+
+
+@section rift_direct Direct HMD mode
+
+LOL direct.
+
+*/

docs/spaces.svg

@@ -0,0 +1,352 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="688.48718"
+   height="327.98221"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.4 r9939"
+   sodipodi:docname="spaces.svg">
+  <defs
+     id="defs4">
+    <marker
+       inkscape:stockid="Arrow2Lend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Lend"
+       style="overflow:visible;">
+      <path
+         id="path3888"
+         style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(1.1) rotate(180) translate(1,0)" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="8"
+     inkscape:cx="273.7909"
+     inkscape:cy="186.31212"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1920"
+     inkscape:window-height="1021"
+     inkscape:window-x="0"
+     inkscape:window-y="30"
+     inkscape:window-maximized="1"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     units="px"
+     showborder="false"
+     inkscape:showpageshadow="false" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-12.627039,-339.86462)">
+    <rect
+       style="fill:#ffffff;fill-opacity:1;stroke:#0000ff;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:3,3;stroke-dashoffset:0"
+       id="rect2985"
+       width="687.36469"
+       height="326.85971"
+       x="13.188287"
+       y="340.42587"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113" />
+    <rect
+       style="fill:#f3fff3;fill-opacity:1;stroke:#00b800;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3757"
+       width="318.05698"
+       height="277.04684"
+       x="38.315689"
+       y="366.05841"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113" />
+    <rect
+       style="fill:#f3fff3;fill-opacity:1;stroke:#00b800;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3767"
+       width="319.01456"
+       height="198.09369"
+       x="356.36722"
+       y="366.01291"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       x="363.40543"
+       y="381.11581"
+       id="text3769"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113"><tspan
+         sodipodi:role="line"
+         x="363.40543"
+         y="381.11581"
+         id="tspan3785"
+         style="font-size:10px;text-align:start;text-anchor:start">Primary monitor position</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#00b800;fill-opacity:1;stroke:none;font-family:Sans"
+       x="236.43106"
+       y="633.68793"
+       id="text3773"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113"><tspan
+         sodipodi:role="line"
+         id="tspan3775"
+         x="236.43106"
+         y="633.68793">Secondary Monitor</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#00b800;fill-opacity:1;stroke:none;font-family:Sans"
+       x="572.90869"
+       y="555.30212"
+       id="text3777"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113"><tspan
+         sodipodi:role="line"
+         id="tspan3779"
+         x="572.90869"
+         y="555.30212">Primary Monitor</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#0000ff;fill-opacity:1;stroke:none;font-family:Sans"
+       x="609.20776"
+       y="657.77118"
+       id="text3781"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113"><tspan
+         sodipodi:role="line"
+         id="tspan3783"
+         x="609.20776"
+         y="657.77118">Virtual Screen</tspan></text>
+    <rect
+       style="fill:#b8b8b8;fill-opacity:1;stroke:#b8b8b8;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+       id="rect5577"
+       width="173.25098"
+       height="141.43118"
+       x="157.75581"
+       y="436.97159" />
+    <rect
+       style="fill:#ededed;fill-opacity:1;stroke:#ededed;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3789"
+       width="168.99611"
+       height="136.87178"
+       x="159.87543"
+       y="439.39697"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#454545;fill-opacity:1;stroke:none;font-family:Sans"
+       x="273.8884"
+       y="567.73486"
+       id="text3791"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113"><tspan
+         sodipodi:role="line"
+         id="tspan3793"
+         x="273.8884"
+         y="567.73486">Window</tspan></text>
+    <rect
+       y="439.39581"
+       x="159.87428"
+       height="8.8251209"
+       width="168.99841"
+       id="rect3795"
+       style="fill:#7b7bff;fill-opacity:1;stroke:#7b7bff;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113" />
+    <path
+       sodipodi:type="arc"
+       style="fill:#000000;fill-opacity:1;stroke:none"
+       id="path3797"
+       sodipodi:cx="352.54324"
+       sodipodi:cy="373.03461"
+       sodipodi:rx="2.5253813"
+       sodipodi:ry="2.5253813"
+       d="m 355.06862,373.03461 c 0,1.39473 -1.13065,2.52538 -2.52538,2.52538 -1.39473,0 -2.52538,-1.13065 -2.52538,-2.52538 0,-1.39473 1.13065,-2.52538 2.52538,-2.52538 1.39473,0 2.52538,1.13065 2.52538,2.52538 z"
+       transform="matrix(0.66107369,0,0,0.66107369,123.32145,119.41326)"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113" />
+    <path
+       transform="matrix(0.66107369,0,0,0.66107369,-194.73594,119.44704)"
+       d="m 355.06862,373.03461 c 0,1.39473 -1.13065,2.52538 -2.52538,2.52538 -1.39473,0 -2.52538,-1.13065 -2.52538,-2.52538 0,-1.39473 1.13065,-2.52538 2.52538,-2.52538 1.39473,0 2.52538,1.13065 2.52538,2.52538 z"
+       sodipodi:ry="2.5253813"
+       sodipodi:rx="2.5253813"
+       sodipodi:cy="373.03461"
+       sodipodi:cx="352.54324"
+       id="path3799"
+       style="fill:#000000;fill-opacity:1;stroke:none"
+       sodipodi:type="arc"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113" />
+    <path
+       sodipodi:type="arc"
+       style="fill:#000000;fill-opacity:1;stroke:none"
+       id="path3801"
+       sodipodi:cx="352.54324"
+       sodipodi:cy="373.03461"
+       sodipodi:rx="2.5253813"
+       sodipodi:ry="2.5253813"
+       d="m 355.06862,373.03461 a 2.5253813,2.5253813 0 1 1 -5.05076,0 2.5253813,2.5253813 0 1 1 5.05076,0 z"
+       transform="matrix(0.66107369,0,0,0.66107369,-73.218648,201.61091)"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       x="21.213203"
+       y="340.20465"
+       id="text3803"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113"><tspan
+         sodipodi:role="line"
+         id="tspan3805"
+         x="21.213203"
+         y="340.20465" /></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       x="70.847862"
+       y="462.84561"
+       id="text3807"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113"><tspan
+         sodipodi:role="line"
+         x="70.847862"
+         y="462.84561"
+         style="font-size:10px"
+         id="tspan3815">Window position</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       x="44.446709"
+       y="381.11581"
+       id="text3817"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113"><tspan
+         sodipodi:role="line"
+         id="tspan3819"
+         x="44.446709"
+         y="381.11581"
+         style="font-size:10px">Secondary monitor position</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       x="165.78685"
+       y="462.84561"
+       id="text3826"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
+       inkscape:export-xdpi="109.89113"
+       inkscape:export-ydpi="109.89113"><tspan
+         sodipodi:role="line"
+         id="tspan3828"
+         x="165.78685"
+         y="462.84561"
+         style="font-size:10px">Client area origin</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       x="364.30875"
+       y="356.71783"
+       id="text3017"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3019"
+         x="364.30875"
+         y="356.71783"
+         style="font-size:10px">Virtual screen origin</tspan></text>
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+       d="m 343.73692,26.224389 0.01,294.941191"
+       id="path3861"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc"
+       transform="translate(12.627039,339.86462)" />
+    <path
+       sodipodi:nodetypes="cc"
+       inkscape:connector-curvature="0"
+       id="path4307"
+       d="m 356.48533,366.00457 336.31202,-0.0196"
+       style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend);stroke-miterlimit:4;stroke-dasharray:none" />
+    <path
+       sodipodi:nodetypes="cc"
+       inkscape:connector-curvature="0"
+       id="path4309"
+       d="m 159.89916,447.6257 -0.0625,145.00422"
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+       d="m 160.03997,448.23877 184.95568,-0.0159"
+       id="path4493"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       x="228.4128"
+       y="445.67239"
+       id="text4495"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4497"
+         x="228.4128"
+         y="445.67239"
+         style="font-size:5px;fill:#ffffff;fill-opacity:1">Window Title</tspan></text>
+  </g>
+</svg>

docs/window.dox

@@ -1,6 +1,6 @@
 /*!
 
-@page window Window handling guide
+@page window Window guide
  
 @tableofcontents
 
@@ -8,8 +8,16 @@ The primary purpose of GLFW is to provide a simple interface to window
 management and OpenGL and OpenGL ES context creation.  GLFW supports multiple
 windows, which can be either a normal desktop window or a full screen window.
 
+This guide introduces the window related functions of GLFW.  There are also
+guides for the other areas of GLFW.
 
-@section window_object Window handles
+ - @ref intro
+ - @ref context
+ - @ref monitor
+ - @ref input
+
+
+@section window_object Window objects
 
 The @ref GLFWwindow object encapsulates both a window and a context.  They are
 created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
@@ -17,30 +25,34 @@ created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
 linked, the object pointer is used as both a context and window handle.
 
 
-@section window_creation Window creation
+@subsection window_creation Window creation
 
-The window and its context are created with @ref glfwCreateWindow, which
+A window and its OpenGL or OpenGL ES context are created with @ref
-returns a handle to the created window object.  For example, this creates a 640
+glfwCreateWindow, which returns a handle to the created window object.  For
-by 480 windowed mode window:
+example, this creates a 640 by 480 windowed mode window:
 
 @code
 GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
+@endcode
+
+If window creation fails, `NULL` will be returned, so it is necessary to check
+the return value.
+
+@code
 if (!window)
 {
     // Handle window creation failure
 }
 @endcode
 
-If window creation fails, `NULL` will be returned, so you need to check the
+The window handle is passed to all window related functions and is provided to
-return value.  If creation failed, an error will have been reported to the error
+along with all input events, so event handlers can tell which window received
-callback.
+the event.
-
-This handle is then passed to all window related functions, and is provided to
-you along with input events, so you know which window received the input.
 
 To create a full screen window, you need to specify which monitor the window
-should use.  In most cases, the user's primary monitor is a good choice.  For
+should use.  In most cases, the user's primary monitor is a good choice.  You
-more information about monitors, see the @ref monitor.
+can get this with @ref glfwGetPrimaryMonitor.  For more information about
+monitors, see the @ref monitor.
 
 @code
 GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
@@ -54,28 +66,25 @@ For more control over how the window and its context are created, see @ref
 window_hints below.
 
 
-@section window_destruction Window destruction
+@subsection window_destruction Window destruction
 
-When you are done with the window, destroy it with the @ref glfwDestroyWindow
+When a window is no longer needed, destroy it with @ref glfwDestroyWindow.
-function.
 
 @code
 glfwDestroyWindow(window);
 @endcode
 
-Once this function is called, no more events will be delivered for that window
+Window destruction always succeeds.  Before the actual destruction, all
-and its handle becomes invalid.
+callbacks are removed so no further events will be delivered for the window.
+
+When a full screen window is destroyed, the original video mode of its monitor
+is restored, but the gamma ramp is left untouched.
+
+All windows remaining at the time @ref glfwTerminate is called are destroyed as
+well.
 
 
-@section window_userptr Window user pointer
+@subsection window_hints Window creation hints
-
-Each window has a user pointer that can be set with @ref
-glfwSetWindowUserPointer and fetched with @ref glfwGetWindowUserPointer.  This
-can be used for any purpose you need and will not be modified by GLFW throughout
-the life-time of the window.
-
-
-@section window_hints Window creation hints
 
 There are a number of hints that can be set before the creation of a window and
 context.  Some affect the window itself, others affect the framebuffer or
@@ -87,7 +96,7 @@ Note that hints need to be set *before* the creation of the window and context
 you wish to have the specified attributes.
 
 
-@subsection window_hints_hard Hard and soft constraints
+@subsubsection window_hints_hard Hard and soft constraints
 
 Some window hints are hard constraints.  These must match the available
 capabilities *exactly* for window and context creation to succeed.  Hints
@@ -107,126 +116,127 @@ context, but are ignored when requesting an OpenGL ES context:
 - `GLFW_OPENGL_PROFILE`
 
 
-@subsection window_hints_wnd Window related hints
+@subsubsection window_hints_wnd Window related hints
 
-The `GLFW_RESIZABLE` hint specifies whether the (windowed mode) window will be
+`GLFW_RESIZABLE` specifies whether the (windowed mode) window will be resizable
-resizable *by the user*.  The window will still be resizable using the @ref
+*by the user*.  The window will still be resizable using the @ref
 glfwSetWindowSize function.  This hint is ignored for full screen windows.
 
-The `GLFW_VISIBLE` hint specifies whether the (windowed mode) window will be
+`GLFW_VISIBLE` specifies whether the (windowed mode) window will be initially
-initially visible.  This hint is ignored for full screen windows.
+visible.  This hint is ignored for full screen windows.
 
-The `GLFW_DECORATED` hint specifies whether the (windowed mode) window will have
+`GLFW_DECORATED` specifies whether the (windowed mode) window will have window
-window decorations such as a border, a close widget, etc.  This hint is ignored
+decorations such as a border, a close widget, etc.  This hint is ignored for
-for full screen windows.  Note that even though a window may lack a close
+full screen windows.  Note that even though a window may lack a close widget, it
-widget, it is usually still possible for the user to generate close events.
+is usually still possible for the user to generate close events.
 
-The `GLFW_FOCUSED` hint specifies whether the (windowed mode) window will be
+`GLFW_FOCUSED` specifies whether the (windowed mode) window will be given input
-given input focus when created.  This hint is ignored for full screen and
+focus when created.  This hint is ignored for full screen and initially hidden
-initially hidden windows.
+windows.
 
-The `GLFW_AUTO_ICONIFY` hint specifies whether the (full screen) window
+`GLFW_AUTO_ICONIFY` specifies whether the (full screen) window will
-will automatically iconify and restore the previous video mode on focus loss.
+automatically iconify and restore the previous video mode on focus loss.  This
-This hint is ignored for windowed mode windows.
+hint is ignored for windowed mode windows.
 
-The `GLFW_FLOATING` hint specifies whether the window will be floating above
+`GLFW_FLOATING` specifies whether the window will be floating above other
-other regular windows, also called topmost or always-on-top.  This is intended
+regular windows, also called topmost or always-on-top.  This is intended
 primarily for debugging purposes and cannot be used to implement proper full
 screen windows.  This hint is ignored for full screen windows.
 
 
-@subsection window_hints_fb Framebuffer related hints
+@subsubsection window_hints_fb Framebuffer related hints
 
-The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
+`GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
-`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` hints specify the desired bit
+`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` specify the desired bit depths of the
-depths of the various components of the default framebuffer.  `GLFW_DONT_CARE`
+various components of the default framebuffer.  `GLFW_DONT_CARE` means the
-means the application has no preference.
-
-The `GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS`
-and `GLFW_ACCUM_ALPHA_BITS` hints specify the desired bit depths of the
-various components of the accumulation buffer.  `GLFW_DONT_CARE` means the
 application has no preference.
 
+`GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` and
+`GLFW_ACCUM_ALPHA_BITS` specify the desired bit depths of the various components
+of the accumulation buffer.  `GLFW_DONT_CARE` means the application has no
+preference.
+
 @note Accumulation buffers are a legacy OpenGL feature and should not be used in
 new code.
 
-The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary
+`GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers.
-buffers.  `GLFW_DONT_CARE` means the application has no preference.
+`GLFW_DONT_CARE` means the application has no preference.
 
 @note Auxiliary buffers are a legacy OpenGL feature and should not be used in
 new code.
 
-The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering.  This is
+`GLFW_STEREO` specifies whether to use stereoscopic rendering.  This is a hard
-a hard constraint.
-
-The `GLFW_SAMPLES` hint specifies the desired number of samples to use for
-multisampling.  Zero disables multisampling.  `GLFW_DONT_CARE` means the
-application has no preference.
-
-The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be
-sRGB capable.
-
-The `GLFW_DOUBLEBUFFER` hint specifies whether the framebuffer should be double
-buffered.  You nearly always want to use double buffering.  This is a hard
 constraint.
 
-The `GLFW_REFRESH_RATE` hint specifies the desired refresh rate for full screen
+`GLFW_SAMPLES` specifies the desired number of samples to use for multisampling.
-windows.  If set to zero, the highest available refresh rate will be used.  This
+Zero disables multisampling.  `GLFW_DONT_CARE` means the application has no
-hint is ignored for windowed mode windows.
+preference.
+
+`GLFW_SRGB_CAPABLE` specifies whether the framebuffer should be sRGB capable.
+
+`GLFW_DOUBLEBUFFER` specifies whether the framebuffer should be double buffered.
+You nearly always want to use double buffering.  This is a hard constraint.
 
 
-@subsection window_hints_ctx Context related hints
+@subsubsection window_hints_mtr Monitor related hints
 
-The `GLFW_CLIENT_API` hint specifies which client API to create the context
+`GLFW_REFRESH_RATE` specifies the desired refresh rate for full screen windows.
-for.  Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`.  This is
+If set to zero, the highest available refresh rate will be used.  This hint is
-a hard constraint.
+ignored for windowed mode windows.
 
-The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints
-specify the client API version that the created context must be compatible
-with.
 
-For OpenGL, these hints are *not* hard constraints, as they don't have to
+@subsubsection window_hints_ctx Context related hints
-match exactly, but @ref glfwCreateWindow will still fail if the resulting
+
-OpenGL version is less than the one requested.  It is therefore perfectly
+`GLFW_CLIENT_API` specifies which client API to create the context for.
-safe to use the default of version 1.0 for legacy code and you may still
+Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`.  This is a hard
-get backwards-compatible contexts of version 3.0 and above when available.
+constraint.
+
+`GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client
+API version that the created context must be compatible with.
+
+For OpenGL, `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
+not hard constraints, as they don't have to match exactly, but @ref
+glfwCreateWindow will still fail if the resulting OpenGL version is less than
+the one requested.  It is therefore perfectly safe to use the default of version
+1.0 for legacy code and you may still get backwards-compatible contexts of
+version 3.0 and above when available.
 
 While there is no way to ask the driver for a context of the highest supported
-version, most drivers provide this when you ask GLFW for a version
+version, most drivers provide this when you ask GLFW for a version 1.0 context.
-1.0 context.
 
-For OpenGL ES, these hints are hard constraints.
+For OpenGL ES, `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
+hard constraints to the extent that OpenGL ES 1.x cannot be returned if 2.0 or
+later was requested, and vice versa.  This is because OpenGL ES 3.0 and later
+versions are backward compatible, but OpenGL ES 2.0 is not.
 
-If an OpenGL context is requested, the `GLFW_OPENGL_FORWARD_COMPAT` hint
+`GLFW_OPENGL_FORWARD_COMPAT` specifies whether the OpenGL context should be
-specifies whether the OpenGL context should be forward-compatible, i.e. one
+forward-compatible, i.e. one where all functionality deprecated in the requested
-where all functionality deprecated in the requested version of OpenGL is
+version of OpenGL is removed.  This may only be used if the requested OpenGL
-removed.  This may only be used if the requested OpenGL version is 3.0 or
+version is 3.0 or above.  If OpenGL S is requested, this hint is ignored.
-above.  If another client API is requested, this hint is ignored.
 
-@note Forward-compatibility is described in detail in the
+Forward-compatibility is described in detail in the
 [OpenGL Reference Manual](https://www.opengl.org/registry/).
 
-If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
+`GLFW_OPENGL_DEBUG_CONTEXT` specifies whether to create a debug OpenGL context,
-specifies whether to create a debug OpenGL context, which may have
+which may have additional error and performance issue reporting functionality.
-additional error and performance issue reporting functionality.  If another
+If OpenGL ES is requested, this hint is ignored.
-client API is requested, this hint is ignored.
 
-If an OpenGL context is requested, the `GLFW_OPENGL_PROFILE` hint specifies
+`GLFW_OPENGL_PROFILE` specifies which OpenGL profile to create the context for.
-which OpenGL profile to create the context for.  Possible values are one of
+Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or
-`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`, or
+`GLFW_OPENGL_COMPAT_PROFILE`, or `GLFW_OPENGL_ANY_PROFILE` to not request
-`GLFW_OPENGL_ANY_PROFILE` to not request a specific profile.  If requesting
+a specific profile.  If requesting an OpenGL version below 3.2,
-an OpenGL version below 3.2, `GLFW_OPENGL_ANY_PROFILE` must be used.  If
+`GLFW_OPENGL_ANY_PROFILE` must be used.  If another OpenGL ES is requested,
-another client API is requested, this hint is ignored.
+this hint is ignored.
 
-@note OpenGL profiles are described in detail in the
+OpenGL profiles are described in detail in the
 [OpenGL Reference Manual](https://www.opengl.org/registry/).
 
-The `GLFW_CONTEXT_ROBUSTNESS` hint specifies the robustness strategy to be
+`GLFW_CONTEXT_ROBUSTNESS` specifies the robustness strategy to be used by the
-used by the context.  This can be one of `GLFW_NO_RESET_NOTIFICATION` or
+context.  This can be one of `GLFW_NO_RESET_NOTIFICATION` or
 `GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
 a robustness strategy.
 
-The `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint specifies the release behavior to be
+`GLFW_CONTEXT_RELEASE_BEHAVIOR` specifies the release behavior to be
 used by the context.  Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`,
 `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`.  If the
 behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context
@@ -235,48 +245,65 @@ the pipeline will be flushed whenever the context is released from being the
 current one.  If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
 not be flushed on release.
 
-@note Context release behaviors are described in detail by the
+Context release behaviors are described in detail by the
 [GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
 extension.
 
 
-@subsection window_hints_values Supported and default values
+@subsubsection window_hints_values Supported and default values
 
-| Name                            | Default value               | Supported values        |
+Window hint                     | Default value               | Supported values
-| ------------------------------- | --------------------------- | ----------------------- |
+------------------------------- | --------------------------- | ----------------
-| `GLFW_RESIZABLE`                | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE` |
+`GLFW_RESIZABLE`                | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE`
-| `GLFW_VISIBLE`                  | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE` |
+`GLFW_VISIBLE`                  | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE`
-| `GLFW_DECORATED`                | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE` |
+`GLFW_DECORATED`                | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE`
-| `GLFW_FOCUSED`                  | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE` |
+`GLFW_FOCUSED`                  | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE`
-| `GLFW_AUTO_ICONIFY`             | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE` |
+`GLFW_AUTO_ICONIFY`             | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE`
-| `GLFW_FLOATING`                 | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE` |
+`GLFW_FLOATING`                 | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE`
-| `GLFW_RED_BITS`                 | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_RED_BITS`                 | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_GREEN_BITS`               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_GREEN_BITS`               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_BLUE_BITS`                | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_BLUE_BITS`                | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_ALPHA_BITS`               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_ALPHA_BITS`               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_DEPTH_BITS`               | 24                          | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_DEPTH_BITS`               | 24                          | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_STENCIL_BITS`             | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_STENCIL_BITS`             | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_ACCUM_RED_BITS`           | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_ACCUM_RED_BITS`           | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_ACCUM_GREEN_BITS`         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_ACCUM_GREEN_BITS`         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_ACCUM_BLUE_BITS`          | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_ACCUM_BLUE_BITS`          | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_ACCUM_ALPHA_BITS`         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_ACCUM_ALPHA_BITS`         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_AUX_BUFFERS`              | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_AUX_BUFFERS`              | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_SAMPLES`                  | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_SAMPLES`                  | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_REFRESH_RATE`             | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
+`GLFW_REFRESH_RATE`             | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-| `GLFW_STEREO`                   | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE` |
+`GLFW_STEREO`                   | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE`
-| `GLFW_SRGB_CAPABLE`             | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE` |
+`GLFW_SRGB_CAPABLE`             | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE`
-| `GLFW_DOUBLEBUFFER`             | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE` |
+`GLFW_DOUBLEBUFFER`             | `GL_TRUE`                   | `GL_TRUE` or `GL_FALSE`
-| `GLFW_CLIENT_API`               | `GLFW_OPENGL_API`           | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API` |
+`GLFW_CLIENT_API`               | `GLFW_OPENGL_API`           | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`
-| `GLFW_CONTEXT_VERSION_MAJOR`    | 1                           | Any valid major version number of the chosen client API |
+`GLFW_CONTEXT_VERSION_MAJOR`    | 1                           | Any valid major version number of the chosen client API
-| `GLFW_CONTEXT_VERSION_MINOR`    | 0                           | Any valid minor version number of the chosen client API |
+`GLFW_CONTEXT_VERSION_MINOR`    | 0                           | Any valid minor version number of the chosen client API
-| `GLFW_CONTEXT_ROBUSTNESS`       | `GLFW_NO_ROBUSTNESS`        | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET` |
+`GLFW_CONTEXT_ROBUSTNESS`       | `GLFW_NO_ROBUSTNESS`        | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET`
-| `GLFW_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE` |
+`GLFW_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`
-| `GLFW_OPENGL_FORWARD_COMPAT`    | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE` |
+`GLFW_OPENGL_FORWARD_COMPAT`    | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE`
-| `GLFW_OPENGL_DEBUG_CONTEXT`     | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE` |
+`GLFW_OPENGL_DEBUG_CONTEXT`     | `GL_FALSE`                  | `GL_TRUE` or `GL_FALSE`
-| `GLFW_OPENGL_PROFILE`           | `GLFW_OPENGL_ANY_PROFILE`   | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |
+`GLFW_OPENGL_PROFILE`           | `GLFW_OPENGL_ANY_PROFILE`   | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE`
 
 
-@section window_close Window close flag
+@section window_events Window event processing
+
+See @ref input_event in the @ref input.
+
+
+@section window_properties Window properties and events
+
+@subsection window_userptr User pointer
+
+Each window has a user pointer that can be set with @ref
+glfwSetWindowUserPointer and fetched with @ref glfwGetWindowUserPointer.  This
+can be used for any purpose you need and will not be modified by GLFW throughout
+the life-time of the window.
+
+The initial value of the pointer is `NULL`.
+
+
+@subsection window_close Closing and close flag
 
 When the user attempts to close the window, for example by clicking the close
 widget or using a key chord like Alt+F4, the *close flag* of the window is set.
@@ -297,16 +324,16 @@ while (!glfwWindowShouldClose(window))
 }
 @endcode
 
-If you wish to be notified when the user attempts to close a window, you can set
+If you wish to be notified when the user attempts to close a window, set a close
-the close callback with @ref glfwSetWindowCloseCallback.  This callback is
+callback with @ref glfwSetWindowCloseCallback.
-called directly *after* the close flag has been set.
 
 @code
 glfwSetWindowCloseCallback(window, window_close_callback);
 @endcode
 
-The callback function can be used for example to filter close requests and clear
+The callback function is called directly *after* the close flag has been set.
-the close flag again unless certain conditions are met.
+It can be used for example to filter close requests and clear the close flag
+again unless certain conditions are met.
 
 @code
 void window_close_callback(GLFWwindow* window)
@@ -317,26 +344,27 @@ void window_close_callback(GLFWwindow* window)
 @endcode
 
 
-@section window_size Window size
+@subsection window_size Client area size
 
 The size of a window can be changed with @ref glfwSetWindowSize.  For windowed
-mode windows, this resizes the specified window so that its *client area* has
+mode windows, this resizes the window so that its *client area* has the
-the specified size.  Note that the window system may put limitations on size.
+specified size.  The window system may impose limits on window size.  For full
-For full screen windows, it selects and sets the video mode most closely
+screen windows, it selects and sets the video mode most closely matching the
-matching the specified size.
+specified size and the color bit depth and refresh rate hints set at creation.
 
 @code
 void glfwSetWindowSize(window, 640, 480);
 @endcode
 
 If you wish to be notified when a window is resized, whether by the user or
-the system, you can set the size callback with @ref glfwSetWindowSizeCallback.
+the system, set a size callback with @ref glfwSetWindowSizeCallback.
 
 @code
 glfwSetWindowSizeCallback(window, window_size_callback);
 @endcode
 
-The callback function receives the new size of the client area of the window.
+The callback function receives the new size of the client area of the window
+when it is resized.
 
 @code
 void window_size_callback(GLFWwindow* window, int width, int height)
@@ -354,10 +382,24 @@ glfwGetWindowSize(window, &width, &height);
 
 @note Do not pass the window size to `glViewport` or other pixel-based OpenGL
 calls.  The window size is in screen coordinates, not pixels.  Use the
-framebuffer size, which is in pixels, for pixel-based calls.
+[framebuffer size](@ref window_fbsize), which is in pixels, for pixel-based
+calls.
+
+The above functions work with the size of the client area, but decorated windows
+typically have title bars and window frames around this rectangle.  You can
+retrieve the extents of these with @ref glfwGetWindowFrameSize.
+
+@code
+int left, top, right, bottom;
+glfwGetWindowFrameSize(window, &left, &top, &right, &bottom);
+@endcode
+
+The returned values are the distances, in screen coordinates, from the edges of
+the client area to the corresponding edges of the full window.  As they are
+distances and not coordinates, they are always zero or positive.
 
 
-@section window_fbsize Window framebuffer size
+@subsection window_fbsize Framebuffer size
 
 While the size of a window is measured in screen coordinates, OpenGL works with
 pixels.  The size you pass into `glViewport`, for example, should be in pixels
@@ -367,15 +409,15 @@ a second set of functions to retrieve the size in pixels of the framebuffer of
 a window.
 
 If you wish to be notified when the framebuffer of a window is resized, whether
-by the user or the system, you can set the size callback with @ref
+by the user or the system, set a size callback with @ref
 glfwSetFramebufferSizeCallback.
 
 @code
 glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
 @endcode
 
-The callback function receives the new size of the client area of the window,
+The callback function receives the new size of the framebuffer when it is
-which can for example be used to update the OpenGL viewport.
+resized, which can for example be used to update the OpenGL viewport.
 
 @code
 void framebuffer_size_callback(GLFWwindow* window, int width, int height)
@@ -398,26 +440,26 @@ a window, for example if the window is dragged between a regular monitor and
 a high-DPI one.
 
 
-@section window_pos Window position
+@subsection window_pos Position
 
 The position of a windowed-mode window can be changed with @ref
 glfwSetWindowPos.  This moves the window so that the upper-left corner of its
-client area has the specified screen coordinates.  Note that the window system
+client area has the specified screen coordinates.  The window system may put
-may put limitations on placement.
+limitats on window placement.
 
 @code
 glfwSetWindowPos(window, 100, 100);
 @endcode
 
-If you wish to be notified when a window is moved, whether by the user or
+If you wish to be notified when a window is moved, whether by the user, system
-the system, you can set the position callback with @ref glfwSetWindowPosCallback.
+or your own code, set a position callback with @ref glfwSetWindowPosCallback.
 
 @code
 glfwSetWindowPosCallback(window, window_pos_callback);
 @endcode
 
-The callback function receives the new position of the upper-left corner of its
+The callback function receives the new position of the upper-left corner of the 
-client area.
+client area when the window is moved.
 
 @code
 void window_pos_callback(GLFWwindow* window, int xpos, int ypos)
@@ -434,31 +476,190 @@ glfwGetWindowPos(window, &xpos, &ypos);
 @endcode
 
 
-@section window_title Window title
+@subsection window_title Title
 
 All GLFW windows have a title, although undecorated or full screen windows may
-not display it or only display it in a task bar or similar interface.  To change
+not display it or only display it in a task bar or similar interface.  You can
-the title of a window, use @ref glfwSetWindowTitle.
+set a UTF-8 encoded window title with @ref glfwSetWindowTitle.
 
 @code
 glfwSetWindowTitle(window, "My Window");
 @endcode
 
-The window title is a regular C string using the UTF-8 encoding.  This means
+The specified string is copied before the function returns, so there is no need
-for example that, as long as your source file is encoded as UTF-8, you can use
+to keep it around.
-any Unicode characters.
+
+As long as your source file is encoded as UTF-8, you can use any Unicode
+characters directly in the source.
 
 @code
-glfwSetWindowTitle(window, "さよなら絶望先生");
+glfwSetWindowTitle(window, "ヒカルの碁");
 @endcode
 
 
-@section window_attribs Window attributes
+@subsection window_monitor Monitor
+
+Full screen windows are associated with a specific monitor.  You can get the
+handle for this monitor with @ref glfwGetWindowMonitor.
+
+@code
+GLFWmonitor* monitor = glfwGetWindowMonitor(window);
+@endcode
+
+This monitor handle is one of those returned by @ref glfwGetMonitors.
+
+For windowed mode windows, this function returns `NULL`.  This is the
+recommended way to tell full screen windows from windowed mode windows.
+
+
+@subsection window_iconify Iconification
+
+Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow.
+
+@code
+glfwIconifyWindow(window);
+@endcode
+
+When a full screen window is iconified, the original video mode of its monitor
+is restored until the user or application restores the window.
+
+Iconified windows can be restored with @ref glfwRestoreWindow.
+
+@code
+glfwRestoreWindow(window);
+@endcode
+
+When a full screen window is restored, the desired video mode is restored to its
+monitor as well.
+
+If you wish to be notified when a window is iconified or restored, whether by
+the user, system or your own code, set a iconify callback with @ref
+glfwSetWindowIconifyCallback.
+
+@code
+glfwSetWindowIconifyCallback(window, window_iconify_callback);
+@endcode
+
+The callback function receives changes in the iconification state of the window.
+
+@code
+void window_iconify_callback(GLFWwindow* window, int iconified)
+{
+    if (iconified)
+    {
+        // The window was iconified
+    }
+    else
+    {
+        // The window was restored
+    }
+}
+@endcode
+
+You can also get the iconification state with @ref glfwGetWindowAttrib.
+
+@code
+int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED);
+@endcode
+
+
+@subsection window_hide Visibility
+
+Windowed mode windows can be hidden with @ref glfwHideWindow.
+
+@code
+glfwHideWindow(window);
+@endcode
+
+This makes the window completely invisible to the user, including removing it
+from the task bar, dock or window list.  Full screen windows cannot be hidden
+and calling @ref glfwHideWindow on a full screen window does nothing.
+
+Hidden windows can be shown with @ref glfwShowWindow.
+
+@code
+glfwShowWindow(window);
+@endcode
+
+Windowed mode windows can be created initially hidden with the `GLFW_VISIBLE`
+[window hint](@ref window_hints_wnd).  Windows created hidden are completely
+invisible to the user until shown.  This can be useful if you need to set up
+your window further before showing it, for example moving it to a specific
+location.
+
+You can also get the visibility state with @ref glfwGetWindowAttrib.
+
+@code
+int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
+@endcode
+
+
+@subsection window_focus Input focus
+
+If you wish to be notified when a window gains or loses focus, whether by
+the user, system or your own code, set a focus callback with @ref
+glfwSetWindowFocusCallback.
+
+@code
+glfwSetWindowFocusCallback(window, window_focus_callback);
+@endcode
+
+The callback function receives changes in the focus state of the window.
+
+@code
+void window_focus_callback(GLFWwindow* window, int focused)
+{
+    if (focused)
+    {
+        // The window gained focus
+    }
+    else
+    {
+        // The window lost focus
+    }
+}
+@endcode
+
+You can also get the focus state with @ref glfwGetWindowAttrib.
+
+@code
+int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
+@endcode
+
+
+@subsection window_refresh Damage and refresh
+
+If you wish to be notified when the contents of a window is damaged and needs
+to be refreshed, set a window refresh callback with @ref
+glfwSetWindowRefreshCallback.
+
+@code
+glfwSetWindowRefreshCallback(m_handle, window_refresh_callback);
+@endcode
+
+The callback function is called when the contents of the window needs to be
+refreshed.
+
+@code
+void window_refresh_callback(GLFWwindow* window)
+{
+    draw_editor_ui(window);
+    glfwSwapBuffers(window);
+}
+@endcode
+
+@note On compositing window systems such as Aero, Compiz or Aqua, where the
+window contents are saved off-screen, this callback may be called only very
+infrequently or never at all.
+
+
+@subsection window_attribs Attributes
 
 Windows have a number of attributes that can be returned using @ref
 glfwGetWindowAttrib.  Some reflect state that may change during the lifetime of
 the window, while others reflect the corresponding hints and are fixed at the
-time of creation.
+time of creation.  Some are related to the actual window and others to its
+context.
 
 @code
 if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
@@ -468,61 +669,58 @@ if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
 @endcode
 
 
-@subsection window_attribs_window Window attributes
+@subsubsection window_attribs_window Window related attributes
 
-The `GLFW_FOCUSED` attribute indicates whether the specified window currently
+`GLFW_FOCUSED` indicates whether the specified window has input focus.
-has input focus.
 
-The `GLFW_ICONIFIED` attribute indicates whether the specified window is
+`GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by
-currently iconified, whether by the user or with @ref glfwIconifyWindow.
+the user or with @ref glfwIconifyWindow.
 
-The `GLFW_VISIBLE` attribute indicates whether the specified window is currently
+`GLFW_VISIBLE` indicates whether the specified window is visible.  Window
-visible.  Window visibility can be controlled with @ref glfwShowWindow and @ref
+visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
-glfwHideWindow and initial visibility is controlled by the
+and initial visibility is controlled by the [window hint](@ref window_hints)
+with the same name.  
+
+`GLFW_RESIZABLE` indicates whether the specified window is resizable *by the
+user*.  This is controlled by the [window hint](@ref window_hints) with the same
+name.
+
+`GLFW_DECORATED` indicates whether the specified window has decorations such as
+a border, a close widget, etc.  This is controlled by the
 [window hint](@ref window_hints) with the same name. 
 
-The `GLFW_RESIZABLE` attribute indicates whether the specified window is
+`GLFW_FLOATING` indicates whether the specified window is floating, also called
-resizable *by the user*.  This is controlled by the
+topmost or always-on-top.  This is controlled by the
-[window hint](@ref window_hints) with the same name.
-
-The `GLFW_DECORATED` attribute indicates whether the specified window has
-decorations such as a border, a close widget, etc.  This is controlled by the
-[window hint](@ref window_hints) with the same name. 
-
-The `GLFW_FLOATING` attribute indicates whether the specified window is
-floating, also called topmost or always-on-top.  This is controlled by the
 [window hint](@ref window_hints) with the same name. 
 
 
-@subsection window_attribs_context Context attributes
+@subsubsection window_attribs_context Context related attributes
 
-The `GLFW_CLIENT_API` attribute indicates the client API provided by the
+`GLFW_CLIENT_API` indicates the client API provided by the window's context;
-window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`.
+either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`.
 
-The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
+`GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
-`GLFW_CONTEXT_REVISION` attributes indicate the client API version of the
+`GLFW_CONTEXT_REVISION` indicate the client API version of the window's context.
-window's context.
 
-The `GLFW_OPENGL_FORWARD_COMPAT` attribute is `GL_TRUE` if the window's
+`GLFW_OPENGL_FORWARD_COMPAT` is `GL_TRUE` if the window's context is an OpenGL
-context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise.
+forward-compatible one, or `GL_FALSE` otherwise.
 
-The `GLFW_OPENGL_DEBUG_CONTEXT` attribute is `GL_TRUE` if the window's
+`GLFW_OPENGL_DEBUG_CONTEXT` is `GL_TRUE` if the window's context is an OpenGL
-context is an OpenGL debug context, or `GL_FALSE` otherwise.
+debug context, or `GL_FALSE` otherwise.
 
-The `GLFW_OPENGL_PROFILE` attribute indicates the OpenGL profile used by the
+`GLFW_OPENGL_PROFILE` indicates the OpenGL profile used by the context.  This is
-context.  This is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`
+`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context uses
-if the context uses a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the
+a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is unknown
-OpenGL profile is unknown or the context is for another client API.  Note that
+or the context is an OpenGL ES context.  Note that the returned profile may not
-the returned profile may not match the profile bits of the context flags, as
+match the profile bits of the context flags, as GLFW will try other means of
-GLFW will try other means of detecting the profile when no bits are set.
+detecting the profile when no bits are set.
 
-The `GLFW_CONTEXT_ROBUSTNESS` attribute indicates the robustness strategy
+`GLFW_CONTEXT_ROBUSTNESS` indicates the robustness strategy used by the context.
-used by the context.  This is `GLFW_LOSE_CONTEXT_ON_RESET` or
+This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION` if the
-`GLFW_NO_RESET_NOTIFICATION` if the window's context supports robustness, or
+window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
-`GLFW_NO_ROBUSTNESS` otherwise.
 
 
-@section window_swap Swapping buffers
+@section window_swap Buffer swapping
 
 GLFW windows are by default double buffered.  That means that you have two
 rendering buffers; a front buffer and a back buffer.  The front buffer is
@@ -538,7 +736,8 @@ glfwSwapBuffers(window);
 
 Sometimes it can be useful to select when the buffer swap will occur.  With the
 function @ref glfwSwapInterval it is possible to select the minimum number of
-monitor refreshes the driver should wait before swapping the buffers:
+monitor refreshes the driver wait should from the time @ref glfwSwapBuffers was
+called before swapping the buffers:
 
 @code
 glfwSwapInterval(1);

examples/simple.c

@@ -57,6 +57,7 @@ int main(void)
     }
 
     glfwMakeContextCurrent(window);
+    glfwSwapInterval(1);
 
     glfwSetKeyCallback(window, key_callback);
 

include/GLFW/glfw3native.h

@@ -45,8 +45,8 @@ extern "C" {
  *  using it.**
  *
  *  Before the inclusion of @ref glfw3native.h, you must define exactly one
- *  window API macro and exactly one context API macro.  Failure to do this
+ *  window system API macro and exactly one context creation API macro.  Failure
- *  will cause a compile-time error.
+ *  to do this will cause a compile-time error.
  *
  *  The available window API macros are:
  *  * `GLFW_EXPOSE_NATIVE_WIN32`
@@ -109,13 +109,32 @@ extern "C" {
 
 #if defined(GLFW_EXPOSE_NATIVE_WIN32)
 /*! @brief Returns the display device name of the specified monitor.
- *  @return The display device name of the specified monitor.
+ *
+ *  @return The UTF-8 encoded display device name (`DISPLAY_DEVICE.DeviceName`)
+ *  of the specified monitor, or `NULL` if an [error](@ref error_handling)
+ *  occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.1.
+ *
  *  @ingroup native
  */
 GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor);
 
 /*! @brief Returns the `HWND` of the specified window.
- *  @return The `HWND` of the specified window.
+ *
+ *  @return The `HWND` of the specified window, or `NULL` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window);
@@ -123,7 +142,16 @@ GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window);
 
 #if defined(GLFW_EXPOSE_NATIVE_WGL)
 /*! @brief Returns the `HGLRC` of the specified window.
- *  @return The `HGLRC` of the specified window.
+ *
+ *  @return The `HGLRC` of the specified window, or `NULL` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window);
@@ -131,13 +159,31 @@ GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window);
 
 #if defined(GLFW_EXPOSE_NATIVE_COCOA)
 /*! @brief Returns the `CGDirectDisplayID` of the specified monitor.
- *  @return The `CGDirectDisplayID` of the specified monitor.
+ *
+ *  @return The `CGDirectDisplayID` of the specified monitor, or
+ *  `kCGNullDirectDisplay` if an [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.1.
+ *
  *  @ingroup native
  */
 GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor);
 
 /*! @brief Returns the `NSWindow` of the specified window.
- *  @return The `NSWindow` of the specified window.
+ *
+ *  @return The `NSWindow` of the specified window, or `nil` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window);
@@ -145,7 +191,16 @@ GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window);
 
 #if defined(GLFW_EXPOSE_NATIVE_NSGL)
 /*! @brief Returns the `NSOpenGLContext` of the specified window.
- *  @return The `NSOpenGLContext` of the specified window.
+ *
+ *  @return The `NSOpenGLContext` of the specified window, or `nil` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI id glfwGetNSGLContext(GLFWwindow* window);
@@ -153,19 +208,46 @@ GLFWAPI id glfwGetNSGLContext(GLFWwindow* window);
 
 #if defined(GLFW_EXPOSE_NATIVE_X11)
 /*! @brief Returns the `Display` used by GLFW.
- *  @return The `Display` used by GLFW.
+ *
+ *  @return The `Display` used by GLFW, or `NULL` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI Display* glfwGetX11Display(void);
 
 /*! @brief Returns the `RROutput` of the specified monitor.
- *  @return The `RROutput` of the specified monitor.
+ *
+ *  @return The `RROutput` of the specified monitor, or `None` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.1.
+ *
  *  @ingroup native
  */
 GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor);
 
 /*! @brief Returns the `Window` of the specified window.
- *  @return The `Window` of the specified window.
+ *
+ *  @return The `Window` of the specified window, or `None` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI Window glfwGetX11Window(GLFWwindow* window);
@@ -173,7 +255,16 @@ GLFWAPI Window glfwGetX11Window(GLFWwindow* window);
 
 #if defined(GLFW_EXPOSE_NATIVE_GLX)
 /*! @brief Returns the `GLXContext` of the specified window.
- *  @return The `GLXContext` of the specified window.
+ *
+ *  @return The `GLXContext` of the specified window, or `NULL` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window);
@@ -181,19 +272,46 @@ GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window);
 
 #if defined(GLFW_EXPOSE_NATIVE_EGL)
 /*! @brief Returns the `EGLDisplay` used by GLFW.
- *  @return The `EGLDisplay` used by GLFW.
+ *
+ *  @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI EGLDisplay glfwGetEGLDisplay(void);
 
 /*! @brief Returns the `EGLContext` of the specified window.
- *  @return The `EGLContext` of the specified window.
+ *
+ *  @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window);
 
 /*! @brief Returns the `EGLSurface` of the specified window.
- *  @return The `EGLSurface` of the specified window.
+ *
+ *  @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an
+ *  [error](@ref error_handling) occurred.
+ *
+ *  @par Thread Safety
+ *  This function may be called from any thread.  Access is not synchronized.
+ *
+ *  @par History
+ *  Added in GLFW 3.0.
+ *
  *  @ingroup native
  */
 GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);