gwm17/glfw
1
0
Fork 0
mirror of https://github.com/gwm17/glfw.git synced 2024-11-23 02:38:52 -05:00
Code Issues Projects Releases Wiki Activity

Documentation work.

Browse Source
This commit is contained in:
Camilla Berglund 2014-09-18 15:03:29 +02:00
parent c769061a8a
commit 4591ad2d64
21 changed files with 3186 additions and 882 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/Doxyfile.in
View File

@ -666,6 +666,8 @@ INPUT = @GLFW_INTERNAL_DOCS@ \
@GLFW_SOURCE_DIR@/docs/monitor.dox \ @GLFW_SOURCE_DIR@/docs/monitor.dox \
@GLFW_SOURCE_DIR@/docs/window.dox \ @GLFW_SOURCE_DIR@/docs/window.dox \
@GLFW_SOURCE_DIR@/docs/input.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 @GLFW_SOURCE_DIR@/docs/compat.dox
# This tag can be used to specify the character encoding of the source files # 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 # 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. # 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. # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output.
# Doxygen will adjust the colors in the style sheet and background images # Doxygen will adjust the colors in the style sheet and background images

92
docs/build.dox
View File

@ -1,24 +1,24 @@
/*! /*!
@page build Building programs that use GLFW @page build Building applications
@tableofcontents @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 For information on how to compile the GLFW library itself, see the @ref compile
guide. 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 @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 @code
#include <GLFW/glfw3.h> #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 The GLFW header also defines everything necessary for your OpenGL header to
function. For example, under Windows you are normally required to include 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 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 `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 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: In other words:
@ -44,7 +45,7 @@ In other words:
- Do *not* include `windows.h` or other platform-specific headers unless you - Do *not* include `windows.h` or other platform-specific headers unless you
plan on using those APIs directly plan on using those APIs directly
- If you *do* need to include such headers, do it *before* including - 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 If you are using an OpenGL extension loading library such as
[glad](https://github.com/Dav1dde/glad), the extension loader header should [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 `GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler
that the GLFW functions are defined in a DLL. 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. 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. 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. 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 `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 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 environment below. On Linux and other Unix-like operating systems, the list
varies but can be retrieved in various ways as described below. 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 A good general introduction to linking is
[Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by [Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by
David Drysdale. David Drysdale.
@ -120,20 +116,20 @@ David Drysdale.
The static version of the GLFW library is named `glfw3`. When using this 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. 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 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 @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. project dependencies.
If you are using the static library version of GLFW, add it and the Cocoa, 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 @subsection build_link_osx With command-line on OS X

18
docs/common.dox Normal file
View File

@ -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
*/

22
docs/compat.dox
View File

@ -4,19 +4,20 @@
@tableofcontents @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 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 @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 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 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 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 input. If the running X server does not support this extension, a non-Xkb
fallback path is used. fallback path is used.
@section compat_glx GLX extensions @section compat_glx GLX extensions
The GLX API is the default API used to create OpenGL contexts on Unix-like The GLX API is the default API used to create OpenGL contexts on Unix-like
systems using the X Window System. 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 GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization `GLX_SGI_swap_control` extensions to provide vertical retrace synchronization

109
docs/compile.dox
View File

@ -5,36 +5,45 @@
@tableofcontents @tableofcontents
This is about compiling the GLFW library itself. For information on how to 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 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 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 cross-compilation of Windows binaries. To use these files you need to add a
special parameter when generating the project files or makefiles: special parameter when generating the project files or makefiles:
@code{.sh}
cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> . cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
@endcode
The exact toolchain file to use depends on the prefix used by the MinGW or 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 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 have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
invocation would be: invocation would be:
@code{.sh}
cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake . cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
@endcode
For more details see the article For more details see the article
[CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on [CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on
the CMake wiki. 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 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 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 Note that using header files and libraries from Mesa during compilation *will
not* tie your binaries to the Mesa implementation of OpenGL. 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 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 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 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. 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 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 (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 used as target path, while the path provided as an argument is used to find the
source tree. source tree.
@code{.sh}
cd <glfw-root-dir> cd <glfw-root-dir>
cmake . cmake .
@endcode
To make an out-of-tree build, make another directory, enter it and run CMake 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 with the (relative or absolute) path to the root of the source tree as an
argument. argument.
@code{.sh}
cd <glfw-root-dir> cd <glfw-root-dir>
mkdir build mkdir build
cd build cd build
cmake .. 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 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 source location and the same directory or another, empty directory as the
destination for binaries. Choose *Configure*, change any options you wish to, destination for binaries. Choose *Configure*, change any options you wish to,
*Configure* again to let the changes take effect and then *Generate*. *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 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 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. 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 `BUILD_SHARED_LIBS` determines whether GLFW is built as a static
library or as a DLL / shared library / dynamic library. library or as a DLL / shared library / dynamic library.
@ -157,7 +200,7 @@ built along with the library.
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 `GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
directory of bundled applications to the `Contents/Resources` directory. directory of bundled applications to the `Contents/Resources` directory.
@ -171,7 +214,7 @@ Retina displays.
`GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries. `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 `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 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. 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 `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 context creation API. Note that EGL is not yet provided on all supported

63
docs/context.dox
View File

@ -1,6 +1,6 @@
/*! /*!
@page context Context handling guide @page context Context guide
@tableofcontents @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 management and OpenGL and OpenGL ES context creation. GLFW supports
multiple windows, with each window having its own context. 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 glfwDestroyWindow or @ref glfwTerminate. As the window and context are
inseparably linked, the object pointer is used as both a context and window 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 There are a number of hints, specified using @ref glfwWindowHint, related to
what kind of context is created. See 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 @section context_current Current context
@ -53,14 +74,14 @@ The current context is returned by @ref glfwGetCurrentContext.
GLFWwindow* window = glfwGetCurrentContext(); GLFWwindow* window = glfwGetCurrentContext();
@endcode @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 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 @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 to those functions. GLFW provides @ref glfwExtensionSupported and @ref
glfwGetProcAddress for manual loading of extensions and new API functions. 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 @subsubsection context_glext_header The glext.h header

2
docs/extra.css
View File

File diff suppressed because one or more lines are too long

17
docs/extra.less
View File

@ -114,6 +114,23 @@ h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em {
border-bottom:none; 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 { .glfwheader {
font-size:16px; font-size:16px;
height:64px; height:64px;

554
docs/input.dox
View File

@ -1,13 +1,563 @@
/*! /*!
@page input Input handling guide @page input Input guide
@tableofcontents @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 @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 @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.
*/ */

223
docs/intro.dox
View File

@ -1,12 +1,13 @@
/*! /*!
@page intro Introduction to the GLFW API @page intro Introduction to the API
@tableofcontents @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 window
- @ref context - @ref context
@ -22,7 +23,7 @@ enumerates monitors and joysticks, initializes the timer and performs any
required platform-specific initialization. required platform-specific initialization.
Only the following functions may be called before the library has been 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 glfwGetVersion
- @ref glfwGetVersionString - @ref glfwGetVersionString
@ -36,8 +37,8 @@ error.
@subsection intro_init_init Initializing GLFW @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 @code
if (!glfwInit()) if (!glfwInit())
@ -49,7 +50,7 @@ if (!glfwInit())
If any part of initialization fails, all remaining bits are terminated as if 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 @ref glfwTerminate was called. The library only needs to be initialized once
and additional calls to an already initialized library will simply return 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 Once the library has been successfully initialized, it should be terminated
before the application exits. before the application exits.
@ -74,23 +75,24 @@ library had not been successfully initialized or had already been terminated,
additional calls return immediately. 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 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 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 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 @code
glfwSetErrorCallback(error_callback); glfwSetErrorCallback(error_callback);
@endcode @endcode
The error callback receives a human-readable description of the error and (when 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 @code
void error_callback(int error, const char* description) void error_callback(int error, const char* description)
@ -100,25 +102,177 @@ void error_callback(int error, const char* description)
@endcode @endcode
The error code indicates the general category of the error. Some error codes, 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 @section intro_version Version management
GLFW provides mechanisms for identifying what version of GLFW your application 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 @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 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. `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 @subsection intro_version_runtime Run-time version
The run-time version can be retrieved with @ref glfwGetVersion, a function that 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 @code
int major, minor, revision; int major, minor, revision;
glfwGetVersion(&major, &minor, &revision); glfwGetVersion(&major, &minor, &revision);
printf("Running against GLFW %i.%i.%i\n", major, minor, revision);
@endcode @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. see which code paths are enabled in a binary.
The version string is returned by @ref glfwGetVersionString, a function that may 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 format of the string is as follows:
- The version of GLFW - 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 For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
back ends, the version string may look something like this: back ends, the version string may look something like this:
@code
3.0.0 Win32 WGL MinGW 3.0.0 Win32 WGL MinGW
@endcode
@note Do not parse the version string to find the GLFW library version. The @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 @ref glfwGetVersion function provides the version of the library binary in

42
docs/main.dox
View File

@ -4,19 +4,39 @@
@section main_intro Introduction @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).
*/ */

70
docs/monitor.dox
View File

@ -1,9 +1,20 @@
/*! /*!
@page monitor Multi-monitor guide @page monitor Monitor guide
@tableofcontents @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 @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 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 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 @code
GLFWmonitor* primary = glfwGetPrimaryMonitor(); GLFWmonitor* primary = glfwGetPrimaryMonitor();
@endcode @endcode
You can retrieve all currently connected monitors with @ref glfwGetMonitors. 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 @code
int count; int count;
GLFWmonitor** monitors = glfwGetMonitors(&count); GLFWmonitor** monitors = glfwGetMonitors(&count);
@endcode @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 @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 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, 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 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 @code
int count; int count;
GLFWvidmode* modes = glfwGetVideoModes(monitor, &count); GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
@endcode @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 @code
const GLFWvidmode* mode = glfwGetVideoMode(monitor); const GLFWvidmode* mode = glfwGetVideoMode(monitor);
@ -98,16 +135,17 @@ glfwGetMonitorPos(monitor, &xpos, &ypos);
@subsection monitor_name Human-readable name @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 @code
const char* name = glfwGetMonitorName(monitor); const char* name = glfwGetMonitorName(monitor);
@endcode @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 @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. 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 @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 @code
const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor); const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);

19
docs/moving.dox
View File

@ -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 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 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 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 If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
support them, see the 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 GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
Unlike buffer swap, which acts on a single window, **glfwPollEvents** and 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 @par Old basic main loop
@code @code
@ -412,10 +414,15 @@ these hotkeys to function even when running in full screen mode.
@subsection moving_terminate Automatic termination @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 @subsection moving_glu GLU header inclusion

41
docs/news.dox
View File

@ -10,17 +10,18 @@
@subsection news_31_cursor Custom system cursor support @subsection news_31_cursor Custom system cursor support
GLFW now supports creating and setting custom system cursors. They can be 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 @subsection news_31_drop File drop event support
GLFW now provides a callback for receiving the paths of files dropped onto GLFW 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 GLFW now provides the @ref glfwPostEmptyEvent function for posting an empty
event from another thread to the main thread event queue, causing @ref 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 @subsection news_31_autoiconify Multi-monitor installation support
GLFW now supports disabling auto-iconification of full screen windows with 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 @subsection news_31_floating Floating windows
GLFW now supports floating windows, also called topmost or always on top, for 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 @subsection news_31_focused Initially unfocused windows
GLFW now supports preventing a windowed mode window from gaining input focus on 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 @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 @subsection news_31_egl Stable EGL support

205
docs/quick.dox
View File

@ -1,23 +1,25 @@
/*! /*!
@page quick Getting started — A quick introduction @page quick Getting started
@tableofcontents @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 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 @code
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@ -54,40 +56,39 @@ inclusion of the GLFW header.
@endcode @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 @code
if (!glfwInit()) if (!glfwInit())
exit(EXIT_FAILURE); exit(EXIT_FAILURE);
@endcode @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 @code
glfwTerminate(); glfwTerminate();
@endcode @endcode
This destroys any remaining windows and releases any other resources allocated by 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. 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, 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 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 C functions (or C++ static methods) that are called by GLFW with arguments
describing the event. 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`. description to `stderr`.
@code @code
@ -97,28 +98,28 @@ void error_callback(int error, const char* description)
} }
@endcode @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 @code
glfwSetErrorCallback(error_callback); glfwSetErrorCallback(error_callback);
@endcode @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 @code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL); GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
@endcode @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 @code
if (!window) if (!window)
@ -128,24 +129,11 @@ if (!window)
} }
@endcode @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 @code
glfwDestroyWindow(window); 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. 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 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 @code
glfwMakeContextCurrent(window); glfwMakeContextCurrent(window);
@endcode @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 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. 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. 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 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 @code
static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods) 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 @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 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 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 @code
int width, height; int width, height;
@ -225,72 +218,80 @@ glfwGetFramebufferSize(window, &width, &height);
glViewport(0, 0, width, height); glViewport(0, 0, width, height);
@endcode @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. 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 @code
double time = glfwGetTime(); double time = glfwGetTime();
@endcode @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 @code
glfwSwapBuffers(window); glfwSwapBuffers(window);
@endcode @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 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 @code
glfwPollEvents(); glfwPollEvents();
@endcode @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 Now that you know how to initialize GLFW, create a window and poll for
keyboard input, it's possible to create a simple program. keyboard input, it's possible to create a simple program.

91
docs/rift.dox Normal file
View File

@ -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.
*/

352
docs/spaces.svg Normal file
View File

@ -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>
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

629
docs/window.dox
View File

@ -1,6 +1,6 @@
/*! /*!
@page window Window handling guide @page window Window guide
@tableofcontents @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 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. 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 The @ref GLFWwindow object encapsulates both a window and a context. They are
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or 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. 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 @code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL); 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) if (!window)
{ {
// Handle window creation failure // Handle window creation failure
} }
@endcode @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 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 @code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL); 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. 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 @code
glfwDestroyWindow(window); glfwDestroyWindow(window);
@endcode @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 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 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. 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 Some window hints are hard constraints. These must match the available
capabilities *exactly* for window and context creation to succeed. Hints 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` - `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. 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 primarily for debugging purposes and cannot be used to implement proper full
screen windows. This hint is ignored for full screen windows. 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. 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 @note Accumulation buffers are a legacy OpenGL feature and should not be used in
new code. 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 @note Auxiliary buffers are a legacy OpenGL feature and should not be used in
new code. 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. 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 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/). [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/). [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 `GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
a robustness strategy. 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`, used by the context. Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`,
`GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`. If the `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`. If the
behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context 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 current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
not be flushed on release. 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) [GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
extension. 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 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. 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 @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 @code
glfwSetWindowCloseCallback(window, window_close_callback); glfwSetWindowCloseCallback(window, window_close_callback);
@endcode @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 @code
void window_close_callback(GLFWwindow* window) void window_close_callback(GLFWwindow* window)
@ -317,26 +344,27 @@ void window_close_callback(GLFWwindow* window)
@endcode @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 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 @code
void glfwSetWindowSize(window, 640, 480); void glfwSetWindowSize(window, 640, 480);
@endcode @endcode
If you wish to be notified when a window is resized, whether by the user or 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 @code
glfwSetWindowSizeCallback(window, window_size_callback); glfwSetWindowSizeCallback(window, window_size_callback);
@endcode @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 @code
void window_size_callback(GLFWwindow* window, int width, int height) 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 @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 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 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 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. a window.
If you wish to be notified when the framebuffer of a window is resized, whether 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. glfwSetFramebufferSizeCallback.
@code @code
glfwSetFramebufferSizeCallback(window, framebuffer_size_callback); glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
@endcode @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 @code
void framebuffer_size_callback(GLFWwindow* window, int width, int height) 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. 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 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 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 @code
glfwSetWindowPos(window, 100, 100); glfwSetWindowPos(window, 100, 100);
@endcode @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 @code
glfwSetWindowPosCallback(window, window_pos_callback); glfwSetWindowPosCallback(window, window_pos_callback);
@endcode @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 @code
void window_pos_callback(GLFWwindow* window, int xpos, int ypos) void window_pos_callback(GLFWwindow* window, int xpos, int ypos)
@ -434,31 +476,190 @@ glfwGetWindowPos(window, &xpos, &ypos);
@endcode @endcode
@section window_title Window title @subsection window_title Title
All GLFW windows have a title, although undecorated or full screen windows may 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 @code
glfwSetWindowTitle(window, "My Window"); glfwSetWindowTitle(window, "My Window");
@endcode @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 @code
glfwSetWindowTitle(window, "さよなら絶望先生"); glfwSetWindowTitle(window, "ヒカルの碁");
@endcode @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 Windows have a number of attributes that can be returned using @ref
glfwGetWindowAttrib. Some reflect state that may change during the lifetime of glfwGetWindowAttrib. Some reflect state that may change during the lifetime of
the window, while others reflect the corresponding hints and are fixed at the 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 @code
if (glfwGetWindowAttrib(window, GLFW_FOCUSED)) if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
@ -468,61 +669,58 @@ if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
@endcode @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. [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. [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 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 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 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 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 @code
glfwSwapInterval(1); glfwSwapInterval(1);

1
examples/simple.c
View File

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

1352
include/GLFW/glfw3.h
View File

File diff suppressed because it is too large Load Diff

148
include/GLFW/glfw3native.h
View File

@ -45,8 +45,8 @@ extern "C" {
* using it.** * using it.**
* *
* Before the inclusion of @ref glfw3native.h, you must define exactly one * 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: * The available window API macros are:
* * `GLFW_EXPOSE_NATIVE_WIN32` * * `GLFW_EXPOSE_NATIVE_WIN32`
@ -109,13 +109,32 @@ extern "C" {
#if defined(GLFW_EXPOSE_NATIVE_WIN32) #if defined(GLFW_EXPOSE_NATIVE_WIN32)
/*! @brief Returns the display device name of the specified monitor. /*! @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 * @ingroup native
*/ */
GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor); GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor);
/*! @brief Returns the `HWND` of the specified window. /*! @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 * @ingroup native
*/ */
GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window); GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window);
@ -123,7 +142,16 @@ GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window);
#if defined(GLFW_EXPOSE_NATIVE_WGL) #if defined(GLFW_EXPOSE_NATIVE_WGL)
/*! @brief Returns the `HGLRC` of the specified window. /*! @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 * @ingroup native
*/ */
GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window); GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window);
@ -131,13 +159,31 @@ GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window);
#if defined(GLFW_EXPOSE_NATIVE_COCOA) #if defined(GLFW_EXPOSE_NATIVE_COCOA)
/*! @brief Returns the `CGDirectDisplayID` of the specified monitor. /*! @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 * @ingroup native
*/ */
GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor); GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor);
/*! @brief Returns the `NSWindow` of the specified window. /*! @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 * @ingroup native
*/ */
GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window); GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window);
@ -145,7 +191,16 @@ GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window);
#if defined(GLFW_EXPOSE_NATIVE_NSGL) #if defined(GLFW_EXPOSE_NATIVE_NSGL)
/*! @brief Returns the `NSOpenGLContext` of the specified window. /*! @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 * @ingroup native
*/ */
GLFWAPI id glfwGetNSGLContext(GLFWwindow* window); GLFWAPI id glfwGetNSGLContext(GLFWwindow* window);
@ -153,19 +208,46 @@ GLFWAPI id glfwGetNSGLContext(GLFWwindow* window);
#if defined(GLFW_EXPOSE_NATIVE_X11) #if defined(GLFW_EXPOSE_NATIVE_X11)
/*! @brief Returns the `Display` used by GLFW. /*! @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 * @ingroup native
*/ */
GLFWAPI Display* glfwGetX11Display(void); GLFWAPI Display* glfwGetX11Display(void);
/*! @brief Returns the `RROutput` of the specified monitor. /*! @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 * @ingroup native
*/ */
GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor); GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor);
/*! @brief Returns the `Window` of the specified window. /*! @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 * @ingroup native
*/ */
GLFWAPI Window glfwGetX11Window(GLFWwindow* window); GLFWAPI Window glfwGetX11Window(GLFWwindow* window);
@ -173,7 +255,16 @@ GLFWAPI Window glfwGetX11Window(GLFWwindow* window);
#if defined(GLFW_EXPOSE_NATIVE_GLX) #if defined(GLFW_EXPOSE_NATIVE_GLX)
/*! @brief Returns the `GLXContext` of the specified window. /*! @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 * @ingroup native
*/ */
GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window); GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window);
@ -181,19 +272,46 @@ GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window);
#if defined(GLFW_EXPOSE_NATIVE_EGL) #if defined(GLFW_EXPOSE_NATIVE_EGL)
/*! @brief Returns the `EGLDisplay` used by GLFW. /*! @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 * @ingroup native
*/ */
GLFWAPI EGLDisplay glfwGetEGLDisplay(void); GLFWAPI EGLDisplay glfwGetEGLDisplay(void);
/*! @brief Returns the `EGLContext` of the specified window. /*! @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 * @ingroup native
*/ */
GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window); GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window);
/*! @brief Returns the `EGLSurface` of the specified 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 * @ingroup native
*/ */
GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window); GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);