From 4591ad2d64f7b6be1aab63c1964adaf23ebe08be Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Thu, 18 Sep 2014 15:03:29 +0200 Subject: [PATCH] Documentation work. --- docs/Doxyfile.in | 4 +- docs/build.dox | 92 +-- docs/common.dox | 18 + docs/compat.dox | 22 +- docs/compile.dox | 125 ++-- docs/context.dox | 63 +- docs/extra.css | 2 +- docs/extra.less | 17 + docs/input.dox | 554 ++++++++++++++- docs/intro.dox | 225 +++++- docs/main.dox | 42 +- docs/monitor.dox | 70 +- docs/moving.dox | 19 +- docs/news.dox | 41 +- docs/quick.dox | 205 +++--- docs/rift.dox | 91 +++ docs/spaces.svg | 352 ++++++++++ docs/window.dox | 625 +++++++++++------ examples/simple.c | 1 + include/GLFW/glfw3.h | 1352 ++++++++++++++++++++++++++---------- include/GLFW/glfw3native.h | 148 +++- 21 files changed, 3186 insertions(+), 882 deletions(-) create mode 100644 docs/common.dox create mode 100644 docs/rift.dox create mode 100644 docs/spaces.svg diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 5af0948a..aef79748 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -666,6 +666,8 @@ INPUT = @GLFW_INTERNAL_DOCS@ \ @GLFW_SOURCE_DIR@/docs/monitor.dox \ @GLFW_SOURCE_DIR@/docs/window.dox \ @GLFW_SOURCE_DIR@/docs/input.dox \ + @GLFW_SOURCE_DIR@/docs/common.dox \ + @GLFW_SOURCE_DIR@/docs/rift.dox \ @GLFW_SOURCE_DIR@/docs/compat.dox # This tag can be used to specify the character encoding of the source files @@ -936,7 +938,7 @@ HTML_EXTRA_STYLESHEET = @GLFW_SOURCE_DIR@/docs/extra.css # files. In the HTML_STYLESHEET file, use the file name only. Also note that # the files will be copied as-is; there are no commands or markers available. -HTML_EXTRA_FILES = +HTML_EXTRA_FILES = @GLFW_SOURCE_DIR@/docs/spaces.svg # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. # Doxygen will adjust the colors in the style sheet and background images diff --git a/docs/build.dox b/docs/build.dox index e9794dde..2185aff1 100644 --- a/docs/build.dox +++ b/docs/build.dox @@ -1,24 +1,24 @@ /*! -@page build Building programs that use GLFW +@page build Building applications @tableofcontents -This is about compiling and linking programs that use GLFW. For information on -how to write such programs, start with the [introductory tutorial](@ref quick). +This is about compiling and linking applications that use GLFW. For information on +how to write such applications, start with the [introductory tutorial](@ref quick). For information on how to compile the GLFW library itself, see the @ref compile guide. -This is not a tutorial on compilation. It assumes basic understanding of how to -compile a C program as well as how to use the specific compiler of your chosen -development environment. The compilation process should be explained in your -C programming material and the use of and options for your compiler should be -described in detail in the documentation for your development environment. +This is not a tutorial on compilation or linking. It assumes basic +understanding of how to compile and link a C program as well as how to use the +specific compiler of your chosen development environment. The compilation +and linking process should be explained in your C programming material and in +the documentation for your development environment. @section build_include Including the GLFW header file -In the files of your program where you use OpenGL or GLFW, you should include -the GLFW header file, i.e.: +In the source files of your application where you use OpenGL or GLFW, you should +include the GLFW header file, i.e.: @code #include @@ -30,13 +30,14 @@ types and function prototypes of the OpenGL API. The GLFW header also defines everything necessary for your OpenGL header to function. For example, under Windows you are normally required to include -`windows.h` before the OpenGL header. This would make your source file tied -to Windows and pollute your code's namespace with the whole Win32 API. +`windows.h` before the OpenGL header, which would pollute your code namespace +with the entire Win32 API. Instead, the GLFW header takes care of this for you, not by including `windows.h`, but by duplicating only the very few necessary parts of it. It does this only when needed, so if `windows.h` *is* included, the GLFW header -does not try to redefine those symbols. +does not try to redefine those symbols. The reverse is not true, i.e. +`windows.h` cannot cope if any of its symbols have already been defined. In other words: @@ -44,7 +45,7 @@ In other words: - Do *not* include `windows.h` or other platform-specific headers unless you plan on using those APIs directly - If you *do* need to include such headers, do it *before* including - the GLFW one and it will detect this + the GLFW header and it will handle this If you are using an OpenGL extension loading library such as [glad](https://github.com/Dav1dde/glad), the extension loader header should @@ -60,28 +61,29 @@ its behavior. `GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler that the GLFW functions are defined in a DLL. -The following macros control which client API header is included. +The following macros control which OpenGL or OpenGL ES API header is included. -`GLFW_INCLUDE_GLCOREARB` makes the header include the modern `GL/glcorearb.h` -header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL header. +`GLFW_INCLUDE_GLCOREARB` makes the GLFW header include the modern +`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 -instead of the regular OpenGL header. - -`GLFW_INCLUDE_ES2` makes the header include the OpenGL ES 2.0 `GLES2/gl2.h` +`GLFW_INCLUDE_ES1` makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h` header instead of the regular OpenGL header. -`GLFW_INCLUDE_ES3` makes the header include the OpenGL ES 3.0 `GLES3/gl3.h` +`GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h` header instead of the regular OpenGL header. -`GLFW_INCLUDE_ES31` makes the header include the OpenGL ES 3.1 `GLES3/gl31.h` +`GLFW_INCLUDE_ES3` makes the GLFW header include the OpenGL ES 3.0 `GLES3/gl3.h` header instead of the regular OpenGL header. -`GLFW_INCLUDE_NONE` makes the header not include any client API header. This is -useful in combination with an extension loading library. +`GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h` +header instead of the regular OpenGL header. -If none of the above inclusion macros are defined, the standard OpenGL header is -included. +`GLFW_INCLUDE_NONE` makes the GLFW header not include any OpenGL or OpenGL ES API +header. This is useful in combination with an extension loading library. + +If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h` +header (`OpenGL/gl.h` on OS X) is included. `GLFW_INCLUDE_GLU` makes the header include the GLU header *in addition to* the header selected above. This should only be used with legacy code. GLU has been @@ -104,12 +106,6 @@ hard-coded into your build environment. See the section for your development environment below. On Linux and other Unix-like operating systems, the list varies but can be retrieved in various ways as described below. -This is not a tutorial on linking. It assumes basic understanding of how to -link a C program as well as how to use the specific linker of your chosen -development environment. The linking process should be explained in your -C programming material and the use of and options for your linker should be -described in detail in the documentation for your development environment. - A good general introduction to linking is [Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by David Drysdale. @@ -120,20 +116,20 @@ David Drysdale. The static version of the GLFW library is named `glfw3`. When using this version, it is also necessary to link with some libraries that GLFW uses. -When linking a program under Windows that uses the static version of GLFW, you -must link with `opengl32`. On some versions of MinGW, you must also explicitly -link with `gdi32`, while other versions of MinGW include it in the set of -default libraries along with other dependencies like `user32` and `kernel32`. -If you are using GLU, you must also link with `glu32`. +When linking an application under Windows that uses the static version of GLFW, +you must link with `opengl32`. On some versions of MinGW, you must also +explicitly link with `gdi32`, while other versions of MinGW include it in the +set of default libraries along with other dependencies like `user32` and +`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 -that uses the DLL version of GLFW, you need to define the `GLFW_DLL` macro -*before* any inclusion of the GLFW header. This can be done either with +The link library for the GLFW DLL is named `glfw3dll`. When compiling an +application that uses the DLL version of GLFW, you need to define the `GLFW_DLL` +macro *before* any inclusion of the GLFW header. This can be done either with a compiler switch or by defining it in your source code. -A program using the GLFW DLL does not need to link against any of its -dependencies, but you still have to link against `opengl32` if your program uses -OpenGL and `glu32` if it uses GLU. +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 application +uses OpenGL and `glu32` if it uses GLU. @subsection build_link_cmake_source With CMake and GLFW source @@ -266,8 +262,12 @@ If you are using the dynamic library version of GLFW, simply add it to the project dependencies. If you are using the static library version of GLFW, add it and the Cocoa, -OpenGL, IOKit and CoreVideo frameworks to the project as dependencies. They can -all be found in `/System/Library/Frameworks`. +OpenGL, IOKit, CoreVideo and Carbon frameworks to the project as dependencies. +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 diff --git a/docs/common.dox b/docs/common.dox new file mode 100644 index 00000000..e1d7e8b8 --- /dev/null +++ b/docs/common.dox @@ -0,0 +1,18 @@ +/*! + +@page common Common tasks + +@tableofcontents + +This guide explains how to + + +@section common_full_screen Windowed full screen mode + +@section common_window_pos Initial window position + +GLFW comes with the `windows` test program, which illustrates this method. + +@section common_fps_camera First-person camera controls + +*/ diff --git a/docs/compat.dox b/docs/compat.dox index e797e114..dc4620aa 100644 --- a/docs/compat.dox +++ b/docs/compat.dox @@ -4,19 +4,20 @@ @tableofcontents -This chapter describes the various API extensions used by this version of GLFW. +This guide describes the various API extensions used by this version of GLFW. It lists what are essentially implementation details, but which are nonetheless -vital knowledge for developers wishing to deploy their applications on machines -with varied specifications. +vital knowledge for developers intending to deploy their applications on a wide +range of machines. + +@note The information in this guide is not a part of GLFW API, but merely +preconditions for some parts of the library to function on a given machine. Any +part of this information may change in future versions of GLFW and that will not +be considered a breaking API change. -Note that the information in this appendix is not a part of the API -specification but merely list some of the preconditions for certain parts of the -API to function on a given machine. As such, any part of it may change in -future versions without this being considered a breaking API change. @section compat_x11 X11 extensions, protocols and IPC standards -As GLFW uses Xlib, directly, without any intervening toolkit +As GLFW uses Xlib directly, without any intervening toolkit library, it has sole responsibility for interacting well with the many and varied window managers in use on Unix-like systems. In order for applications and window managers to work well together, a number of standards and @@ -79,13 +80,14 @@ GLFW requires the Xkb extension with detectable auto-repeat to provide keyboard input. If the running X server does not support this extension, a non-Xkb fallback path is used. + @section compat_glx GLX extensions The GLX API is the default API used to create OpenGL contexts on Unix-like systems using the X Window System. -GLFW uses the `GLXFBConfig` API to enumerate and select framebuffer pixel -formats. This requires GLX 1.3 or greater. +GLFW uses the GLX 1.3 `GLXFBConfig` functions to enumerate and select framebuffer pixel +formats. If GLX 1.3 is not supported, @ref glfwInit will fail. GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and `GLX_SGI_swap_control` extensions to provide vertical retrace synchronization diff --git a/docs/compile.dox b/docs/compile.dox index ef53e54c..123f7aa4 100644 --- a/docs/compile.dox +++ b/docs/compile.dox @@ -5,36 +5,45 @@ @tableofcontents This is about compiling the GLFW library itself. For information on how to -build programs that use GLFW, see the @ref build guide. +build applications that use GLFW, see the @ref build guide. -@section compile_deps Dependencies +@section compile_cmake Using CMake -To compile GLFW and the accompanying example programs, you will need **CMake**, -which will generate the project files or makefiles for your particular -development environment. If you are on a Unix-like system such as Linux or -FreeBSD or have a package system like Fink, MacPorts, Cygwin or Homebrew, you -can simply install its CMake package. If not, you can get installers for -Windows and OS X from the [CMake website](http://www.cmake.org/). +GLFW uses [CMake](http://www.cmake.org/) to generate project files or makefiles +for a particular development environment. If you are on a Unix-like system such +as Linux or FreeBSD or have a package system like Fink, MacPorts, Cygwin or +Homebrew, you can simply install its CMake package. If not, you can download +installers for Windows and OS X from the [CMake website](http://www.cmake.org/). -Additional dependencies are listed below. - -If you wish to compile GLFW without CMake, see @ref compile_manual. +@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 +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 -the necessary headers, link libraries and tools except for CMake. +Once you have installed CMake, make sure that all other dependencies are +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, -link libraries and tools except for CMake. +The Microsoft Platform SDK that is installed along with Visual C++ already +contains all the necessary headers, link libraries and tools except for CMake. +Move on to @ref compile_generate. -@subsection compile_deps_mingw_cross Dependencies using MinGW or MinGW-w64 cross-compilation +@subsubsection compile_deps_mingw Dependencies for MinGW or MinGW-w64 on Windows + +Both the MinGW and the MinGW-w64 packages already contain all the necessary +headers, link libraries and tools except for CMake. Move on to @ref +compile_generate. + + +@subsubsection compile_deps_mingw_cross Dependencies for MinGW or MinGW-w64 cross-compilation Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages. For example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages @@ -45,7 +54,9 @@ GLFW has CMake toolchain files in the `CMake/` directory that allow for easy cross-compilation of Windows binaries. To use these files you need to add a special parameter when generating the project files or makefiles: - cmake -DCMAKE_TOOLCHAIN_FILE= . +@code{.sh} +cmake -DCMAKE_TOOLCHAIN_FILE= . +@endcode The exact toolchain file to use depends on the prefix used by the MinGW or MinGW-w64 binaries on your system. You can usually see this in the /usr @@ -53,21 +64,27 @@ directory. For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct invocation would be: - cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake . +@code{.sh} +cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake . +@endcode For more details see the article [CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on the CMake wiki. - -@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. +Once you have this set up, move on to @ref compile_generate. -@subsection compile_deps_x11 Dependencies using Linux and X11 +@subsubsection compile_deps_xcode Dependencies for Xcode on OS X + +Xcode comes with all necessary tools except for CMake. The required headers +and libraries are included in the core OS X frameworks. Xcode can be downloaded +from the Mac App Store or from the ADC Member Center. + +Once you have Xcode installed, move on to @ref compile_generate. + + +@subsubsection compile_deps_x11 Dependencies for Linux and X11 To compile GLFW for X11, you need to have the X11 and OpenGL header packages installed, as well as the basic development tools like GCC and make. For @@ -78,8 +95,11 @@ packages. GLFW itself doesn't need or use GLU, but some of the examples do. Note that using header files and libraries from Mesa during compilation *will not* tie your binaries to the Mesa implementation of OpenGL. +Once you have installed the necessary packages, move on to @ref +compile_generate. -@section compile_cmake Generating files with CMake + +@subsection compile_generate Generating build files with CMake Once you have all necessary dependencies it is time to generate the project files or makefiles for your development environment. CMake needs to know two @@ -91,36 +111,59 @@ otherwise it is called an out-of-tree build. One of several advantages of out-of-tree builds is that you can generate files and compile for different development environments using a single source tree. +@note This section is about generating the project files or makefiles necessary +to compile the GLFW library, not about compiling the actual library. -@subsection compile_cmake_cli Generating files with the CMake command-line tool + +@subsubsection compile_generate_cli Generating files with the CMake command-line tool To make an in-tree build, enter the *root* directory of the GLFW source tree (i.e. *not* the `src` subdirectory) and run CMake. The current directory is used as target path, while the path provided as an argument is used to find the source tree. - cd - cmake . +@code{.sh} +cd +cmake . +@endcode To make an out-of-tree build, make another directory, enter it and run CMake with the (relative or absolute) path to the root of the source tree as an argument. - cd - mkdir build - cd build - cmake .. +@code{.sh} +cd +mkdir build +cd build +cmake .. +@endcode + +Once you have generated the project files or makefiles for your chosen +development environment, move on to @ref compile_compile. -@subsection compile_cmake_gui Generating files with the CMake GUI +@subsubsection compile_generate_gui Generating files with the CMake GUI If you are using the GUI version, choose the root of the GLFW source tree as source location and the same directory or another, empty directory as the destination for binaries. Choose *Configure*, change any options you wish to, *Configure* again to let the changes take effect and then *Generate*. +Once you have generated the project files or makefiles for your chosen +development environment, move on to @ref compile_compile. -@section compile_options CMake options + +@subsection compile_compile Compiling the library + +You should now have all required dependencies and the project files or makefiles +necessary to compile GLFW. Go ahead and compile the actual GLFW library with +these files, as you would with any other project. + +Once the GLFW library is compiled, you are ready to build your applications, +linking it to the GLFW library. See the @ref build guide for more information. + + +@subsection compile_options CMake options The CMake files for GLFW provide a number of options, although not all are available on all supported platforms. Some of these are de facto standards @@ -132,7 +175,7 @@ Some package systems like Ubuntu and other distributions based on Debian GNU/Linux have this tool in a separate `cmake-curses-gui` package. -@subsection compile_options_shared Shared CMake options +@subsubsection compile_options_shared Shared CMake options `BUILD_SHARED_LIBS` determines whether GLFW is built as a static library or as a DLL / shared library / dynamic library. @@ -157,7 +200,7 @@ built along with the library. the library. -@subsection compile_options_osx OS X specific CMake options +@subsubsection compile_options_osx OS X specific CMake options `GLFW_USE_CHDIR` determines whether `glfwInit` changes the current directory of bundled applications to the `Contents/Resources` directory. @@ -171,7 +214,7 @@ Retina displays. `GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries. -@subsection compile_options_win32 Windows specific CMake options +@subsubsection compile_options_win32 Windows specific CMake options `USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the static library version of the Visual C++ runtime library. If set to `ON`, the @@ -189,7 +232,7 @@ symbol, which forces the use of the high-performance GPU on nVidia Optimus systems. -@subsection compile_options_egl EGL specific CMake options +@subsubsection compile_options_egl EGL specific CMake options `GLFW_USE_EGL` determines whether to use EGL instead of the platform-specific context creation API. Note that EGL is not yet provided on all supported diff --git a/docs/context.dox b/docs/context.dox index ccca60c2..9ea9bed8 100644 --- a/docs/context.dox +++ b/docs/context.dox @@ -1,6 +1,6 @@ /*! -@page context Context handling guide +@page context Context guide @tableofcontents @@ -8,31 +8,52 @@ The primary purpose of GLFW is to provide a simple interface to window management and OpenGL and OpenGL ES context creation. GLFW supports multiple windows, with each window having its own context. +This guide introduces the functions related to managing OpenGL and OpenGL ES +contexts. There are also guides for the other areas of the GLFW API. -@section context_object Context handles + - @ref intro + - @ref window + - @ref monitor + - @ref input -The @ref GLFWwindow object encapsulates both a [window](@ref window) and -a context. It is created with @ref glfwCreateWindow and destroyed with @ref + +@section context_object Context objects + +@ref window_object encapsulate both the OS level window and a OpenGL or OpenGL +ES context. It is created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow or @ref glfwTerminate. As the window and context are inseparably linked, the object pointer is used as both a context and window -handle. +handle. See @ref window_creation for more information. -@section context_hints Context creation hints +@subsection context_hints Context creation hints There are a number of hints, specified using @ref glfwWindowHint, related to what kind of context is created. See -[context related hints](@ref window_hints_ctx) in the window handling guide. +[context related hints](@ref window_hints_ctx) in the window guide. -@section context_sharing Context object sharing +@subsection context_sharing Context object sharing -When creating a window and context with @ref glfwCreateWindow, you can specify -another window whose context the new one should share its objects with. Object -sharing is implemented by the operating system and graphics driver and is -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 -shared. +When creating a window and its OpenGL or OpenGL ES context with @ref +glfwCreateWindow, you can specify another window whose context the new one +should share its objects (textures, vertex and element buffers, etc.) with. + +@code +GLFWwindow* second_window = glfwCreateWindow(640, 480, "Second Window", NULL, first_window); +@endcode + +Object sharing is implemented by the operating system and graphics driver. On +platforms where it is possible to choose which types of objects are shared, GLFW +requests that all types are shared. + +See the relevant chapter of the [OpenGL](https://www.opengl.org/registry/) or +[OpenGL ES](http://www.khronos.org/opengles/) reference documents for more +information. The name and number of this chapter unfortunately varies between +versions and APIs, but has at times been named *Shared Objects and Multiple +Contexts*. + +GLFW comes with a simple object sharing test program called `sharing`. @section context_current Current context @@ -53,14 +74,14 @@ The current context is returned by @ref glfwGetCurrentContext. GLFWwindow* window = glfwGetCurrentContext(); @endcode -@note A context must only be current for a single thread at a time, and a thread -must only have a single context current at a time. +@note A context can only be current for a single thread at a time, and a thread +can only have a single context current at a time. -@section context_swap Swapping buffers +@section context_swap Buffer swapping Buffer swapping is part of the window and framebuffer, not the context. See -@ref window_swap in the window handling guide. +@ref window_swap in the window guide. @section context_glext OpenGL and OpenGL ES extensions @@ -170,10 +191,8 @@ that extension and then, if it introduces new functions, retrieve the pointers to those functions. GLFW provides @ref glfwExtensionSupported and @ref glfwGetProcAddress for manual loading of extensions and new API functions. -@note It is strongly recommended that you use an existing extension loader -library like [glad](https://github.com/Dav1dde/glad) instead of loading -manually. Extension loading is a solved problem and you will gain nothing from -solving it again by hand. +@note It is recommended that you use an existing extension loader library, as +described above, instead of loading manually. @subsubsection context_glext_header The glext.h header diff --git a/docs/extra.css b/docs/extra.css index 2f55d7f6..a1938cc5 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -1 +1 @@ -#navrow1,#navrow2,#navrow3,#navrow4,.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a,.memdoc,dl.reflist dd,div.toc li,.ah,span.lineno,span.lineno a,span.lineno a:hover,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,.doxtable code{background:none}#titlearea,.footer,.contents,div.header,.memdoc,table.doxtable td,table.doxtable th,hr,.memSeparator{border:none}.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a,.reflist dt a.el,.levels span,.directory .levels span{text-shadow:none}.memdoc,dl.reflist dd{box-shadow:none}div.headertitle,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,table.doxtable code{padding:0}#nav-path,.directory .levels,span.lineno{display:none}html,#titlearea,.footer,tr.even,.directory tr.even,.doxtable tr:nth-child(even),.mdescLeft,.mdescRight,.memItemLeft,.memItemRight,code{background:#f2f2f2}body{color:#4d4d4d}h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em{color:#1a1a1a;border-bottom:none}.glfwheader{font-size:16px;height:64px;max-width:920px;min-width:800px;padding:0 32px;margin:0 auto}#glfwhome{line-height:64px;padding-right:48px;color:#666;font-size:2.5em;background:url("http://www.glfw.org/css/arrow.png") no-repeat right}.glfwnavbar{list-style-type:none;margin:0 auto;float:right}#glfwhome,.glfwnavbar li{float:left}.glfwnavbar a,.glfwnavbar a:visited{line-height:64px;margin-left:2em;display:block;color:#666}#glfwhome,.glfwnavbar a,.glfwnavbar a:visited{transition:.35s ease}#titlearea,.footer{color:#666}address.footer{text-align:center;padding:2em;margin-top:3em}#top{background:#666}#navrow1,#navrow2,#navrow3,#navrow4{max-width:920px;min-width:800px;margin:0 auto;font-size:13px}.tablist{height:36px;display:block;position:relative}.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a{color:#f2f2f2}.tablist li.current a{background:linear-gradient(to bottom, #ffa733 0, #f60 100%);box-shadow:inset 0 0 32px #f60;text-shadow:0 -1px 1px #b34700;color:#fff}.contents{min-height:590px}div.contents,div.header{max-width:920px;margin:0 auto;padding:0 32px;background:#fff none}table.doxtable th,dl.reflist dt{background:linear-gradient(to bottom, #ffa733 0, #f60 100%);box-shadow:inset 0 0 32px #f60;text-shadow:0 -1px 1px #b34700;color:#fff}dl.reflist dt a.el{color:#f60;padding:.2em;border-radius:4px;background-color:#ffe0cc}div.toc{float:none;width:auto}div.toc h3{font-size:1.17em}div.toc ul{padding-left:1.5em}div.toc li{font-size:1em;padding-left:0;list-style-type:disc}div.toc,.memproto,div.qindex,div.ah{background:linear-gradient(to bottom, #f2f2f2 0, #e6e6e6 100%);box-shadow:inset 0 0 32px #e6e6e6;text-shadow:0 1px 1px #fff;color:#1a1a1a;border:2px solid #e6e6e6;border-radius:4px}.paramname{color:#803300}dl.reflist dt{border:2px solid #f60;border-top-left-radius:4px;border-top-right-radius:4px;border-bottom:none}dl.reflist dd{border:2px solid #f60;border-bottom-right-radius:4px;border-bottom-left-radius:4px;border-top:none}table.doxtable{border-collapse:inherit;border-spacing:0;border:2px solid #f60;border-radius:4px}a,a:hover,a:visited,a:visited:hover,.contents a:visited,.el,a.el:visited,#glfwhome:hover,.tablist a:hover,span.lineno a:hover{color:#f60;text-decoration:none}div.directory{border-collapse:inherit;border-spacing:0;border:2px solid #f60;border-radius:4px}hr,.memSeparator{height:2px;background:linear-gradient(to right, #f2f2f2 0, #d9d9d9 50%, #f2f2f2 100%)}dl.note,dl.pre,dl.post,dl.invariant{background:linear-gradient(to bottom, #ddfad1 0, #cbf7ba 100%);box-shadow:inset 0 0 32px #baf5a3;color:#1e5309;border:2px solid #afe599}dl.warning,dl.attention{background:linear-gradient(to bottom, #fae8d1 0, #f7ddba 100%);box-shadow:inset 0 0 32px #f5d1a3;color:#533309;border:2px solid #e5c499}dl.deprecated,dl.bug{background:linear-gradient(to bottom, #fad1e3 0, #f7bad6 100%);box-shadow:inset 0 0 32px #f5a3c8;color:#53092a;border:2px solid #e599bb}dl.todo,dl.test{background:linear-gradient(to bottom, #d1ecfa 0, #bae3f7 100%);box-shadow:inset 0 0 32px #a3daf5;color:#093a53;border:2px solid #99cce5}dl.note,dl.pre,dl.post,dl.invariant,dl.warning,dl.attention,dl.deprecated,dl.bug,dl.todo,dl.test{border-radius:4px;padding:1em;text-shadow:0 1px 1px #fff}.note a,.pre a,.post a,.invariant a,.warning a,.attention a,.deprecated a,.bug a,.todo a,.test a,.note a:visited,.pre a:visited,.post a:visited,.invariant a:visited,.warning a:visited,.attention a:visited,.deprecated a:visited,.bug a:visited,.todo a:visited,.test a:visited{color:inherit}div.line{line-height:inherit}div.fragment,pre.fragment{background:#f2f2f2;border-radius:4px;border:none;padding:1em;overflow:auto;border-left:4px solid #ccc}.lineno a,.lineno a:visited,.line,pre.fragment{color:#4d4d4d}span.preprocessor,span.comment{color:#007899}a.code,a.code:visited{color:#e64500}span.keyword,span.keywordtype,span.keywordflow{color:#404040;font-weight:bold}span.stringliteral{color:#360099}code{padding:.1em;border-radius:4px} +#navrow1,#navrow2,#navrow3,#navrow4,.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a,.memdoc,dl.reflist dd,div.toc li,.ah,span.lineno,span.lineno a,span.lineno a:hover,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,.doxtable code{background:none}#titlearea,.footer,.contents,div.header,.memdoc,table.doxtable td,table.doxtable th,hr,.memSeparator{border:none}.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a,.reflist dt a.el,.levels span,.directory .levels span{text-shadow:none}.memdoc,dl.reflist dd{box-shadow:none}div.headertitle,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,table.doxtable code{padding:0}#nav-path,.directory .levels,span.lineno{display:none}html,#titlearea,.footer,tr.even,.directory tr.even,.doxtable tr:nth-child(even),.mdescLeft,.mdescRight,.memItemLeft,.memItemRight,code{background:#f2f2f2}body{color:#4d4d4d}h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em{color:#1a1a1a;border-bottom:none}h1{padding-top:0.5em;font-size:180%}h2{padding-top:0.5em;margin-bottom:0;font-size:140%}h3{padding-top:0.5em;margin-bottom:0;font-size:110%}.glfwheader{font-size:16px;height:64px;max-width:920px;min-width:800px;padding:0 32px;margin:0 auto}#glfwhome{line-height:64px;padding-right:48px;color:#666;font-size:2.5em;background:url("http://www.glfw.org/css/arrow.png") no-repeat right}.glfwnavbar{list-style-type:none;margin:0 auto;float:right}#glfwhome,.glfwnavbar li{float:left}.glfwnavbar a,.glfwnavbar a:visited{line-height:64px;margin-left:2em;display:block;color:#666}#glfwhome,.glfwnavbar a,.glfwnavbar a:visited{transition:.35s ease}#titlearea,.footer{color:#666}address.footer{text-align:center;padding:2em;margin-top:3em}#top{background:#666}#navrow1,#navrow2,#navrow3,#navrow4{max-width:920px;min-width:800px;margin:0 auto;font-size:13px}.tablist{height:36px;display:block;position:relative}.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a{color:#f2f2f2}.tablist li.current a{background:linear-gradient(to bottom, #ffa733 0, #f60 100%);box-shadow:inset 0 0 32px #f60;text-shadow:0 -1px 1px #b34700;color:#fff}.contents{min-height:590px}div.contents,div.header{max-width:920px;margin:0 auto;padding:0 32px;background:#fff none}table.doxtable th,dl.reflist dt{background:linear-gradient(to bottom, #ffa733 0, #f60 100%);box-shadow:inset 0 0 32px #f60;text-shadow:0 -1px 1px #b34700;color:#fff}dl.reflist dt a.el{color:#f60;padding:.2em;border-radius:4px;background-color:#ffe0cc}div.toc{float:none;width:auto}div.toc h3{font-size:1.17em}div.toc ul{padding-left:1.5em}div.toc li{font-size:1em;padding-left:0;list-style-type:disc}div.toc,.memproto,div.qindex,div.ah{background:linear-gradient(to bottom, #f2f2f2 0, #e6e6e6 100%);box-shadow:inset 0 0 32px #e6e6e6;text-shadow:0 1px 1px #fff;color:#1a1a1a;border:2px solid #e6e6e6;border-radius:4px}.paramname{color:#803300}dl.reflist dt{border:2px solid #f60;border-top-left-radius:4px;border-top-right-radius:4px;border-bottom:none}dl.reflist dd{border:2px solid #f60;border-bottom-right-radius:4px;border-bottom-left-radius:4px;border-top:none}table.doxtable{border-collapse:inherit;border-spacing:0;border:2px solid #f60;border-radius:4px}a,a:hover,a:visited,a:visited:hover,.contents a:visited,.el,a.el:visited,#glfwhome:hover,.tablist a:hover,span.lineno a:hover{color:#f60;text-decoration:none}div.directory{border-collapse:inherit;border-spacing:0;border:2px solid #f60;border-radius:4px}hr,.memSeparator{height:2px;background:linear-gradient(to right, #f2f2f2 0, #d9d9d9 50%, #f2f2f2 100%)}dl.note,dl.pre,dl.post,dl.invariant{background:linear-gradient(to bottom, #ddfad1 0, #cbf7ba 100%);box-shadow:inset 0 0 32px #baf5a3;color:#1e5309;border:2px solid #afe599}dl.warning,dl.attention{background:linear-gradient(to bottom, #fae8d1 0, #f7ddba 100%);box-shadow:inset 0 0 32px #f5d1a3;color:#533309;border:2px solid #e5c499}dl.deprecated,dl.bug{background:linear-gradient(to bottom, #fad1e3 0, #f7bad6 100%);box-shadow:inset 0 0 32px #f5a3c8;color:#53092a;border:2px solid #e599bb}dl.todo,dl.test{background:linear-gradient(to bottom, #d1ecfa 0, #bae3f7 100%);box-shadow:inset 0 0 32px #a3daf5;color:#093a53;border:2px solid #99cce5}dl.note,dl.pre,dl.post,dl.invariant,dl.warning,dl.attention,dl.deprecated,dl.bug,dl.todo,dl.test{border-radius:4px;padding:1em;text-shadow:0 1px 1px #fff}.note a,.pre a,.post a,.invariant a,.warning a,.attention a,.deprecated a,.bug a,.todo a,.test a,.note a:visited,.pre a:visited,.post a:visited,.invariant a:visited,.warning a:visited,.attention a:visited,.deprecated a:visited,.bug a:visited,.todo a:visited,.test a:visited{color:inherit}div.line{line-height:inherit}div.fragment,pre.fragment{background:#f2f2f2;border-radius:4px;border:none;padding:1em;overflow:auto;border-left:4px solid #ccc}.lineno a,.lineno a:visited,.line,pre.fragment{color:#4d4d4d}span.preprocessor,span.comment{color:#007899}a.code,a.code:visited{color:#e64500}span.keyword,span.keywordtype,span.keywordflow{color:#404040;font-weight:bold}span.stringliteral{color:#360099}code{padding:.1em;border-radius:4px} diff --git a/docs/extra.less b/docs/extra.less index 9e4a6c9d..62ff695a 100644 --- a/docs/extra.less +++ b/docs/extra.less @@ -114,6 +114,23 @@ h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em { border-bottom:none; } +h1 { + padding-top:0.5em; + font-size:180%; +} + +h2 { + padding-top:0.5em; + margin-bottom:0; + font-size:140%; +} + +h3 { + padding-top:0.5em; + margin-bottom:0; + font-size:110%; +} + .glfwheader { font-size:16px; height:64px; diff --git a/docs/input.dox b/docs/input.dox index 759ce220..5105c242 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -1,13 +1,563 @@ /*! -@page input Input handling guide +@page input Input guide @tableofcontents -@section input_key Keyboard input +This guide introduces the input related functions of GLFW. There are also +guides for the other areas of GLFW. + + - @ref intro + - @ref window + - @ref context + - @ref monitor + +GLFW provides many kinds of input. While some can only be polled, like time, or +only received via callbacks, like scrolling, there are those that provide both +callbacks and polling. Where a callback is provided, that is the recommended +way to receive that kind of input. The more you can use callbacks the less time +your users' machines will need to spend polling. + +All input callbacks receive a window handle. By using the +[window user pointer](@ref window_userptr), you can access non-global structures +or objects from your callbacks. + +To get a better feel for how the various events callbacks behave, run the +`events` test program. It register every callback supported by GLFW and prints +out all arguments provided for every event, along with time and sequence +information. + + +@section input_event Event processing + +GLFW needs to communicate regularly with the window system both in order to +receive events and to show that the application hasn't locked up. Event +processing must be done regularly while you have visible windows and is normally +done each frame after [buffer swapping](@ref window_swap). + +There are two functions for processing pending events. @ref glfwPollEvents, +processes only those events that have already been received and then returns +immediately. + +@code +glfwPollEvents(); +@endcode + +This is the best choice when rendering continually, like most games do. + +If you only need to update the contents of the window when you receive new +input, @ref glfwWaitEvents is a better choice. + +@code +glfwWaitEvents(); +@endcode + +It puts the thread to sleep until at least one event has been received and then +processes all received events. This saves a great deal of CPU cycles and is +useful for, for example, editing tools. There must be at least one GLFW window +for this function to sleep. + +If the main thread is sleeping in @ref glfwWaitEvents, you can wake it from +another thread by posting an empty event to the event queue with @ref +glfwPostEmptyEvent. + +@code +glfwPostEmptyEvent(); +@endcode + +Do not assume that callbacks will *only* be called through either of the above +functions. While it is necessary to process events in the event queue, some +window systems will send some events directly to the application, which in turn +causes callbacks to be called outside of regular event processing. + + +@section input_keyboard Keyboard input + +GLFW divides keyboard input into two categories; key events and character +events. Key events relate to actual physical keyboard keys, whereas character +events relate to the Unicode code points generated by pressing some of them. + +Keys and characters do not map 1:1. A single key press may produce several +characters, and a single character may require several keys to produce. This +may not be the case on your machine, but your users are likely not all using the +same keyboard layout, input method or even operating system as you. + + +@subsection input_key Key input + +If you wish to be notified when a physical key is pressed or released or when it +repeats, set a key callback with @ref glfwSetKeyCallback. + +@code +glfwSetKeyCallback(window, key_callback); +@endcode + +The callback function receives the [keyboard key](@ref keys), platform-specific +scancode, key action and [modifier bits](@ref mods). + +@code +void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods) +{ + if (key == GLFW_KEY_E && action == GLFW_PRESS) + activate_airship(); +} +@endcode + +The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. The key +will be `GLFW_KEY_UNKNOWN` if GLFW lacks a key token for it. These keys still +have unique, if platform-specific scancodes. + +The scancode is unique for every key but is platform-specific, so a scancode +will map to different keys on different platforms. + +The key will be `GLFW_KEY_UNKNOWN` for special keys like *E-mail* or *Play* that +don't have a key token. Those keys will still have unique, if platform-specific +scancodes. + +Key states for [named keys](@ref keys) are also saved in per-window state arrays +that can be polled with @ref glfwGetKey. + +@code +int state = glfwGetKey(window, GLFW_KEY_E); +if (state == GLFW_PRESS) + activate_airship(); +@endcode + +The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`. + +This function only returns cached key event state. It does not poll the +system for the current state of the key. + +Whenever you poll state, you risk missing the state change you are looking for. +If a pressed key is released again before you poll its state, you will have +missed the key press. The recommended solution for this is to use a +key callback, but there is also the `GLFW_STICKY_KEYS` input mode. + +@code +glfwSetInputMode(window, GLFW_STICKY_KEYS, 1); +@endcode + +When sticky keys mode is enabled, the pollable state of a key will remain +`GLFW_PRESS` until the state of that key is polled with @ref glfwGetKey. Once +it has been polled, if a key release event had been processed in the meantime, +the state will reset to `GLFW_RELEASE`, otherwise it will remain `GLFW_PRESS`. + +The `GLFW_KEY_LAST` constant holds the highest value of any +[named key](@ref keys). + + +@subsection input_char Unicode character input + +If you wish to receive Unicode code point input, set a character callback with +@ref glfwSetCharCallback. + +@code +glfwSetCharCallback(window, character_callback); +@endcode + +The callback function receives Unicode code points for key events that would +have led to regular text input on that platform. + +@code +void character_callback(GLFWwindow* window, unsigned int codepoint) +{ +} +@endcode + +If you wish to receive all Unicode code point events generated by the system, or +just want to know exactly what modifier keys were used, set a character with +modifiers callback with @ref glfwSetCharModsCallback. + +@code +glfwSetCharCallback(window, charmods_callback); +@endcode + +The callback function receives Unicode code points and +[modifier bits](@ref mods). + +@code +void charmods_callback(GLFWwindow* window, unsigned int codepoint, int mods) +{ +} +@endcode + @section input_mouse Mouse input +Mouse input comes in many forms, including of mouse motion and button presses, +system cursor appearance and behavior, and two-dimensional scrolling. All of +these are supported by GLFW. + + +@subsection input_cursor_pos Cursor position + +If you wish to be notified when the system cursor moves over the window, set +a cursor position callback with @ref glfwSetCursorPosCallback. + +@code +glfwSetCursorPosCallback(window, cursor_pos_callback); +@endcode + +The callback functions receives the cursor position. On platforms that provide +it, the full sub-pixel cursor position is passed on. + +@code +static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos) +{ +} +@endcode + +The cursor position is also saved per-window and can be polled with @ref +glfwGetCursorPos. + +@code +double xpos, ypos; +glfwGetCursorPos(window, &xpos, &ypos); +@endcode + +This function only returns cached cursor positions. It does not poll the +system for the current position. Whenever you poll state, you risk missing the +state change you are looking for. + + +@subsection input_cursor_mode Cursor modes + +The `GLFW_CURSOR` input mode provides several cursor modes for special forms of +mouse motion input. By default, the `GLFW_CURSOR_NORMAL` cursor mode is used, +meaning the regular arrow cursor or a [custom cursor](@ref input_cursor) is used +and cursor motion is not limited. + +If you wish to implement mouse motion based camera controls or other input +schemes that require unlimited mouse movement, set the cursor mode to +`GLFW_CURSOR_DISABLED`. + +@code +glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED); +@endcode + +This will hide the cursor and lock it to the specified window. GLFW will then +take care of all the details of cursor re-centering and offset calculation and +providing the application with a virtual cursor position. This virtual position +is provided normally, both via the cursor position callback and via position +polling. + +@note You should not implement your own version of this functionality using +other features of GLFW. It will not work as robustly as `GLFW_CURSOR_DISABLED`, +as those features are not intended for this purpose. + +If you just wish the cursor to become hidden when it is over a window, set +the cursor mode to `GLFW_CURSOR_HIDDEN`. + +@code +glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN); +@endcode + +This mode puts no limit on the motion of the cursor. + +To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL` +cursor mode. + +@code +glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL); +@endcode + + +@subsection input_cursor Cursor objects + +GLFW supports creating custom system cursor images, encapsulated as @ref +GLFWcursor objects. They are created with @ref glfwCreateCursor and destroyed +with @ref glfwDestroyCursor (or @ref glfwTerminate, if any remain). + + +@subsubsection input_cursor_creation Cursor creation + +A cursor is created with @ref glfwCreateCursor, which returns a handle to the +created cursor object. For example, this creates a 16x16 white square cursor +with the hot-spot in the upper-left corner: + +@code +unsigned char pixels[16 * 16 * 4]; +memset(pixels, 0xff, sizeof(pixels)); + +GLFWimage image; +image.width = 16; +image.height = 16; +image.pixels = pixels; + +GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0); +@endcode + +The image data is 32-bit RGBA, i.e. eight bits per channel. The pixels are +arranged canonically as sequental rows, starting from the top-left corner. + + +@subsubsection input_cursor_destruction Cursor destruction + +When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor. + +@code +glfwDestroyCursor(cursor); +@endcode + +Cursor destruction always succeeds. All cursors remaining at the time of @ref +glfwTerminate is called are destroyed as well. + + +@subsubsection input_cursor_set Cursor setting + +A cursor can be set as current for a window with @ref glfwSetCursor. + +@code +glfwSetCursor(window, cursor); +@endcode + +Once set, the cursor image will be used as long as the system cursor is over the +client area of the window and the [cursor mode](@ref input_cursor_mode) is set +to `GLFW_CURSOR_NORMAL`. + +A single cursor may be set for any number of windows. + +To remove a cursor from a window, set the cursor of that window to `NULL`. + +@code +glfwSetCursor(window, NULL); +@endcode + +When a cursor is destroyed, it is removed from any window where it is set. This +does not affect the cursor modes of those windows. + + +@subsection input_cursor_enter Cursor enter/leave events + +If you wish to be notified when the cursor enters or leaves the client area of +a window, set a cursor enter/leave callback with @ref glfwSetCursorEnterCallback. + +@code +glfwSetCursorEnterCallback(window, cursor_enter_callback); +@endcode + +The callback function receives the new classification of the cursor. + +@code +void cursor_enter_callback(GLFWwindow* window, int entered) +{ + if (entered) + { + // The cursor entered the client area of the window + } + else + { + // The cursor left the client area of the window + } +} +@endcode + + +@subsection input_mouse_button Mouse button input + +If you wish to be notified when a mouse button is pressed or released, set +a mouse button callback with @ref glfwSetMouseButtonCallback. + +@code +glfwSetMouseButtonCallback(window, mouse_button_callback); +@endcode + +The callback function receives the [mouse button](@ref buttons), button action +and [modifier bits](@ref mods). + +@code +void mouse_button_callback(GLFWwindow* window, int button, int action, int mods) +{ + if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS) + popup_menu(); +} +@endcode + +The action is one of `GLFW_PRESS` or `GLFW_RELEASE`. + +Mouse button states for [named buttons](@ref buttons) are also saved in +per-window state arrays that can be polled with @ref glfwGetMouseButton. + +@code +int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT); +if (state == GLFW_PRESS) + upgrade_cow(); +@endcode + +The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`. + +This function only returns cached mouse button event state. It does not poll +the system for the current state of the mouse button. + +Whenever you poll state, you risk missing the state change you are looking for. +If a pressed mouse button is released again before you poll its state, you will have +missed the button press. The recommended solution for this is to use a +mouse button callback, but there is also the `GLFW_STICKY_MOUSE_BUTTONS` +input mode. + +@code +glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, 1); +@endcode + +When sticky mouse buttons mode is enabled, the pollable state of a mouse button +will remain `GLFW_PRESS` until the state of that button is polled with @ref +glfwGetMouseButton. Once it has been polled, if a mouse button release event +had been processed in the meantime, the state will reset to `GLFW_RELEASE`, +otherwise it will remain `GLFW_PRESS`. + +The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any +[named button](@ref buttons). + + +@subsection input_scroll Scroll input + +If you wish to be notified when the user scrolls, whether with a mouse wheel or +touchpad gesture, set a scroll callback with @ref glfwSetScrollCallback. + +@code +glfwSetScrollCallback(window, scroll_callback); +@endcode + +The callback function receives two-dimensional scroll offsets. + +@code +void scroll_callback(GLFWwindow* window, double xoffset, double yoffset) +{ +} +@endcode + +A simple mouse wheel, being vertical, provides offsets along the Y-axis. + + @section input_joy Joystick input +The joystick functions expose connected joysticks and controllers, with both +referred to as joysticks. It supports up to sixteen joysticks, ranging from +`GLFW_JOYSTICK_1`, `GLFW_JOYSTICK_2` up to `GLFW_JOYSTICK_LAST`. You can test +whether a [joystick](@ref joysticks) is present with @ref glfwJoystickPresent. + +@code +int present = glfwJoystickPresent(GLFW_JOYSTICK_1); +@endcode + +When GLFW is initialized, detected joysticks are added to to the beginning of +the array, starting with `GLFW_JOYSTICK_1`. Once a joystick is detected, it +keeps its assigned index until it is disconnected, so as joysticks are connected +and disconnected, they will become spread out. + +Joystick state is updated as needed when a joystick function is called and does +not require a window to be created or @ref glfwPollEvents or @ref glfwWaitEvents +to be called. + + +@subsection input_joy_axis Joystick axis states + +The positions of all axes of a joystick are returned by @ref +glfwGetJoystickAxes. See the reference documentation for the lifetime of the +returned array. + +@code +int count; +const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_1, &count); +@endcode + +Each element in the returned array is a value between -1.0 and 1.0. + + +@subsection input_joy_button Joystick button states + +The states of all buttons of a joystick are returned by @ref +glfwGetJoystickButtons. See the reference documentation for the lifetime of the +returned array. + +@code +int count; +const unsigned char* axes = glfwGetJoystickButtons(GLFW_JOYSTICK_1, &count); +@endcode + +Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`. + + +@subsection input_joy_name Joystick name + +The human-readable, UTF-8 encoded name of a joystick is returned by @ref +glfwGetJoystickName. See the reference documentation for the lifetime of the +returned string. + +@code +const char* name = glfwGetJoystickName(GLFW_JOYSTICK_1); +@endcode + +Joystick names are not guaranteed to be unique. Two joysticks of the same model +and make may have the same name. Only the [joystick token](@ref joysticks) is +guaranteed to be unique, and only until that joystick is disconnected. + + +@section input_time Time input + +GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime. + +@code +double seconds = glfwGetTime(); +@endcode + +It returns the number of seconds since the timer was started when the library +was initialized with @ref glfwInit. The platform-specific time sources used +usually have micro- or nanosecond resolution. + +You can modify the reference time with @ref glfwSetTime. + +@code +glfwSetTime(4.0); +@endcode + +This sets the timer to the specified time, in seconds. + + +@section input_clipboard Clipboard input and output + +If the system clipboard contains a UTF-8 encoded string or if it can be +converted to one, you can retrieve it with @ref glfwGetClipboardString. See the +reference documentation for the lifetime of the returned string. + +@code +const char* clipboard = glfwGetClipboardString(window); +@endcode + +The contents of the system clipboard can be set to a UTF-8 encoded string with +@ref glfwSetClipboardString. + +@code +glfwSetClipboardString(window, "A string with words in it"); +@endcode + +The clipboard functions take a window handle argument because some window +systems require a window to communicate with the system clipboard. Any valid +window may be used. + + +@section input_drop Path drop input + +If you wish to receive the paths of files and/or directories dropped on +a window, set a file drop callback with @ref glfwSetDropCallback. + +@code +glfwSetDropCallback(window, drop_callback); +@endcode + +The callback function receives an array of paths encoded as UTF-8. + +@code +void drop_callback(GLFWwindow* window, int count, const char** paths) +{ + int i; + for (i = 0; i < count; i++) + handle_dropped_file(paths[i]); +} +@endcode + +The path array and its strings are only valid until the file drop callback +returns, as they may have been generated specifically for that event. You need +to make a deep copy of the array if you want to keep the paths. + */ diff --git a/docs/intro.dox b/docs/intro.dox index 2de2c8bd..93e88a10 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -1,12 +1,13 @@ /*! -@page intro Introduction to the GLFW API +@page intro Introduction to the API @tableofcontents -This guide will introduce the basic concepts of GLFW and describes -initialization, error handling and version management. There are other guides -for the various areas of the GLFW API. +This guide introduces the basic concepts of GLFW and describes initialization, +error handling and API guarantees and limitations. For a broad but shallow +tutorial, see @ref quick instead. There are also guides for the other areas of +GLFW. - @ref window - @ref context @@ -22,7 +23,7 @@ enumerates monitors and joysticks, initializes the timer and performs any required platform-specific initialization. Only the following functions may be called before the library has been -successfully initialized. +successfully initialized, and only from the main thread. - @ref glfwGetVersion - @ref glfwGetVersionString @@ -36,8 +37,8 @@ error. @subsection intro_init_init Initializing GLFW -The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an -error occurred. +The library is initialized with @ref glfwInit, which returns zero if an error +occurred. @code if (!glfwInit()) @@ -49,7 +50,7 @@ if (!glfwInit()) If any part of initialization fails, all remaining bits are terminated as if @ref glfwTerminate was called. The library only needs to be initialized once and additional calls to an already initialized library will simply return -`GL_TRUE` immediately. +non-zero immediately. Once the library has been successfully initialized, it should be terminated before the application exits. @@ -74,23 +75,24 @@ library had not been successfully initialized or had already been terminated, additional calls return immediately. -@section intro_error Error handling +@section error_handling Error handling Some GLFW functions have return values that indicate an error, but this is often -not very helpful when trying to figure out *why* the error occurred. Also, far -from all GLFW functions have such return values. +not very helpful when trying to figure out *why* the error occurred. Some +functions also return otherwise valid values on error. Finally, far from all +GLFW functions have return values. This is where the error callback comes in. This callback is called whenever an error occurs. It is set with @ref glfwSetErrorCallback, a function that may be -called before @ref glfwInit and after @ref glfwTerminate. +called regardless of whether GLFW is initialized. @code glfwSetErrorCallback(error_callback); @endcode The error callback receives a human-readable description of the error and (when -possible) its cause. The description is a regular C string using the UTF-8 -encoding. The callback is also provided with an [error code](@ref errors). +possible) its cause. The description encoded as UTF-8. The callback is also +provided with an [error code](@ref errors). @code void error_callback(int error, const char* description) @@ -100,25 +102,177 @@ void error_callback(int error, const char* description) @endcode The error code indicates the general category of the error. Some error codes, -such as `GLFW_NOT_INITIALIZED` has only a single meaning, whereas others like -`GLFW_PLATFORM_ERROR` are used for many different errors. +such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like +@ref GLFW_PLATFORM_ERROR are used for many different errors. -@note The description string is only valid until the error callback returns, as -it may have been generated specifically for that error. This lets GLFW provide -much more specific error descriptions but means you must make a copy if you want -to keep the description string. +The description string is only valid until the error callback returns, as it may +have been generated specifically for that error. This lets GLFW provide much +more specific error descriptions but means you must make a copy if you want to +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. + + + +Window and monitor positions are specified relative to the upper-left corners of +their content areas, while cursor positions are specified relative to the window +client area. + +The origin of the window client area coordinate system is also the position of +the window, meaning you can translate client area coordinates to the virtual +screen by adding the window position. The window frame, when present, extend +out from the client area but does not affect the window position. + +Almost all positions and sizes in GLFW are measured in screen coordinates +relative to one of the two origins above. This includes cursor positions, +window positions and sizes, window frame sizes, monitor positions and video mode +resolutions. + +Two exceptions are the [monitor physical size](@ref monitor_size), which is +measured in millimetres, and [framebuffer size](@ref window_fbsize), which is +measured in pixels. + +Pixels and screen coordinates may map 1:1 on your machine, but they won't on +every other machine, for example on a Mac with a Retina display. The ratio +between screen coordinates and pixels may also change at run-time depending on +which monitor the window is currently on. + + +@section guarantees_limitations Guarantees and limitations + +This section describes the conditions under which GLFW can be expected to +function, barring any bugs in GLFW, the operating system or drivers. Use of +GLFW outside of these limits may work on some platforms, or on some machines, or +some of the time, or on some versions of GLFW, but it may break at any time and +will not be considered a bug. + + +@subsection lifetime Pointer lifetimes + +GLFW will never free any pointer you provide to it and you must never free any +pointer it provides to you. + +Many GLFW functions return pointers to dynamically allocated structures, strings +or arrays, and some callbacks are provided with strings or arrays. These are +always managed by GLFW and should never be freed by the application. The +lifetime of these pointers is documented for each GLFW function and callback. +If you need to keep this data, you must copy it before its lifetime expires. + +Many GLFW functions accept pointers to structures or strings allocated by the +application. These are never freed by GLFW and are always the responsibility of +the application. If GLFW needs to keep the data in these structures or strings, +they are copied before the function returns. + +Pointer lifetimes are guaranteed not to be shortened in future minor releases. + + +@subsection reentrancy Reentrancy + +GLFW event processing and object creation and destruction are not reentrant. +This means that the following functions may not be called from any callback +function: + + - @ref glfwCreateWindow + - @ref glfwDestroyWindow + - @ref glfwCreateCursor + - @ref glfwDestroyCursor + - @ref glfwPollEvents + - @ref glfwWaitEvents + + +@subsection thread_safety Thread safety + +Most GLFW functions may only be called from the main thread. The reference +documentation for every GLFW function states whether it is limited to the main +thread. + +There are some general rules that make it easier to remember which functions are +limited to the main thread. The following tasks may only be performed on the +main thread: + + - Initialization and termination + - Event processing + - Creation and destruction of window, context and cursor objects + +Because event processing must be performed on the main thread, all callbacks +except for the error callback will only be called on that thread. The error +callback may be called on any thread, as any GLFW function may generate errors. + +The posting of empty events may be done from any thread. The window user +pointer and close flag may also be accessed and modified from any thread, but +this is not synchronized by GLFW. The following window related functions may +be called from any thread: + + - @ref glfwPostEmptyEvent + - @ref glfwGetWindowUserPointer + - @ref glfwSetWindowUserPointer + - @ref glfwWindowShouldClose + - @ref glfwSetWindowShouldClose + +Rendering may be done on any thread. The following context related functions +may be called from any thread: + + - @ref glfwMakeContextCurrent + - @ref glfwGetCurrentContext + - @ref glfwSwapBuffers + - @ref glfwSwapInterval + - @ref glfwExtensionSupported + - @ref glfwGetProcAddress + +The timer may be accessed from any thread, but this is not synchronized by GLFW. +The following timer related functions may be called from any thread: + + - @ref glfwGetTime + +No GLFW function may be called from any other thread until GLFW has been +successfully initialized on the main thread, including functions that may called +before initialization. + +GLFW uses no synchronization objects internally except for thread-local storage +to keep track of the current context for each thread. Synchronization is left +to the application. + +Functions that may currently be called from any thread will always remain so, +but functions that are currently limited to the main may be updated to allow +calls from any thread in future releases. + + +@subsection compatibility Version compatibility + +GLFW guarantees binary backward compatibility with earlier minor versions of the +API. This means that you can drop in a newer version of the GLFW DLL / shared +library / dynamic library and existing applications will continue to run. + +Once a function or constant has been added, the signature of that function or +value of that constant will remain unchanged until the next major version of +GLFW. No compatibility of any kind is guaranteed between major versions. + +Undefined behavior, i.e. behavior that is not described in reference +documentation, may change at any time until it is documented. + +If the reference documentation and the implementation differ, the reference +documentation is correct and the implementation will be fixed in the next +release. + + +@subsection event_order Event order + +The order of arrival of related events is not guaranteed to be consistent +across platforms. The exception is synthetic key and mouse button release +events, which are always delivered after the window defocus event. @section intro_version Version management GLFW provides mechanisms for identifying what version of GLFW your application -was compiled against as well as what version it is currently using. The GLFW -API is binary-compatible with later minor versions, i.e. an executable using the -3.0 API will be able to use a version 3.2 DLL. - -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. +was compiled against as well as what version it is currently running against. +If you are loading GLFW dynamically (not just linking dynamically), you can use +this to verify that the library binary is compatible with your application. @subsection intro_version_compile Compile-time version @@ -126,15 +280,24 @@ that older version will cause errors to be reported. The compile-time version of GLFW is provided by the GLFW header with the `GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros. +@code +printf("Compiled against GLFW %i.%i.%i\n", + GLFW_VERSION_MAJOR, + GLFW_VERSION_MINOR, + GLFW_VERSION_REVISION); +@endcode + @subsection intro_version_runtime Run-time version The run-time version can be retrieved with @ref glfwGetVersion, a function that -may be called before @ref glfwInit and after @ref glfwTerminate +may be called regardless of whether GLFW is initialized. @code int major, minor, revision; glfwGetVersion(&major, &minor, &revision); + +printf("Running against GLFW %i.%i.%i\n", major, minor, revision); @endcode @@ -146,7 +309,7 @@ This is primarily intended for submitting bug reports, to allow developers to see which code paths are enabled in a binary. The version string is returned by @ref glfwGetVersionString, a function that may -be called before @ref glfwInit and after @ref glfwTerminate. +be called regardless of whether GLFW is initialized. The format of the string is as follows: - The version of GLFW @@ -157,7 +320,9 @@ The format of the string is as follows: For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL back ends, the version string may look something like this: - 3.0.0 Win32 WGL MinGW +@code +3.0.0 Win32 WGL MinGW +@endcode @note Do not parse the version string to find the GLFW library version. The @ref glfwGetVersion function provides the version of the library binary in diff --git a/docs/main.dox b/docs/main.dox index a2d41ea1..f0dceb9f 100644 --- a/docs/main.dox +++ b/docs/main.dox @@ -4,19 +4,39 @@ @section main_intro Introduction -GLFW is a free, Open Source, multi-platform library for opening a window, -creating an OpenGL context and managing input. It is easy to integrate into -existing applications and does not lay claim to the main loop. +__GLFW__ is a free, Open Source, multi-platform library for creating windows +with OpenGL or OpenGL ES contexts and receiving many kinds of input. It is easy +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 -to write a small but complete program, and guides for -[compiling GLFW](@ref compile) and -[building programs that use GLFW](@ref build). +@ref quick is a guide for those new to GLFW. It takes you through how to write +a small but complete program. For people coming from GLFW 2, the @ref moving +guide explains what has changed and how to update existing code to use the new +API. -If you have used GLFW 2.x in the past, there is a -[transition guide](@ref moving) that explains what has changed and how to update -existing code to use the new API. +There are guides for each of the various areas of the 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). */ diff --git a/docs/monitor.dox b/docs/monitor.dox index ddc87549..25cc9e5c 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -1,9 +1,20 @@ /*! -@page monitor Multi-monitor guide +@page monitor Monitor guide @tableofcontents +This guide introduces the monitor related functions of GLFW. There are also +guides for the other areas of GLFW. + + - @ref intro + - @ref window + - @ref context + - @ref input + +To see how GLFW views your monitor setup and its available video modes, run the +`modes` test program. + @section monitor_objects Monitor objects @@ -26,22 +37,44 @@ provide into the virtual desktop that spans them. The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's preferred monitor and is usually the one with global UI elements like task bar -or menu bar. +or menu bar. The returned structure is allocated and freed by GLFW. @code GLFWmonitor* primary = glfwGetPrimaryMonitor(); @endcode You can retrieve all currently connected monitors with @ref glfwGetMonitors. -The primary monitor is always the first monitor in the returned array. +See the reference documentation for the lifetime of the returned array. @code int count; GLFWmonitor** monitors = glfwGetMonitors(&count); @endcode -@note Monitors other than the primary monitor may be moved to a different index -in the array if another monitor is disconnected. +The primary monitor is always the first monitor in the returned array, but other +monitors may be moved to a different index when a monitor is connected or +disconnected. + + +@subsection monitor_event Monitor configuration changes + +If you wish to be notified when a monitor is connected or disconnected, set +a monitor callback with @ref glfwSetMonitorCallback. + +@code +glfwSetMonitorCallback(monitor_callback); +@endcode + +The callback function receives the handle for the monitor that has been +connected or disconnected and a monitor action. + +@code +void monitor_callback(GLFWmonitor* monitor, int event) +{ +} +@endcode + +The action is one of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. @section monitor_properties Monitor properties @@ -52,15 +85,19 @@ Although GLFW generally does a good job at selecting a suitable video mode for you when you open a full screen window, it is sometimes useful to know exactly which modes are available on a certain system. For example, you may want to present the user with a list of video modes to select -from. To get a list of available video modes, you can use the function -@ref glfwGetVideoModes. +from. + +To get a list of available video modes, you can use the function @ref +glfwGetVideoModes. See the reference documentation for the lifetime of the +returned array. @code int count; GLFWvidmode* modes = glfwGetVideoModes(monitor, &count); @endcode -To get the current video mode of a monitor call @ref glfwGetVideoMode. +To get the current video mode of a monitor call @ref glfwGetVideoMode. See the +reference documentation for the lifetime of the returned structure. @code const GLFWvidmode* mode = glfwGetVideoMode(monitor); @@ -98,16 +135,17 @@ glfwGetMonitorPos(monitor, &xpos, &ypos); @subsection monitor_name Human-readable name -The human-readable name of a monitor is returned by @ref glfwGetMonitorName. -It is a regular C string using the UTF-8 encoding. +The human-readable, UTF-8 encoded name of a monitor is returned by @ref +glfwGetMonitorName. See the reference documentation for the lifetime of the +returned string. @code const char* name = glfwGetMonitorName(monitor); @endcode -@note Monitor names are not guaranteed to be unique. Two monitors of the same -model and make may have the same name. Only the address of a monitor object is -guaranteed to be unique. +Monitor names are not guaranteed to be unique. Two monitors of the same model +and make may have the same name. Only the monitor handle is guaranteed to be +unique, and only until that monitor is disconnected. @subsection monitor_gamma Gamma ramp @@ -136,10 +174,10 @@ The gamma ramp data is copied before the function returns, so there is no need to keep it around once the ramp has been set. @note It is recommended to use gamma ramps of size 256, as that is the size -supported by virtually all graphics cards on all platforms. +supported by all graphics cards on all platforms. -The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. The -returned structure and its arrays are allocated and freed by GLFW. +The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. See +the reference documentation for the lifetime of the returned structure. @code const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor); diff --git a/docs/moving.dox b/docs/moving.dox index e08a4b53..b30dee23 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -38,7 +38,9 @@ The threading functions have been removed, including the per-thread sleep function. They were fairly primitive, under-used, poorly integrated and took time away from the focus of GLFW (i.e. context, input and window). There are better threading libraries available and native threading support is available -in both C++11 and C11, both of which are gaining traction. +in both [C++11](http://en.cppreference.com/w/cpp/thread) and +[C11](http://en.cppreference.com/w/c/thread), both of which are gaining +traction. If you wish to use the C++11 or C11 facilities but your compiler doesn't yet support them, see the @@ -148,7 +150,7 @@ into [window hints](@ref window_hints), but as they have been given GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. Unlike buffer swap, which acts on a single window, **glfwPollEvents** and -**glfwWaitEvents** process events for all windows at once. +__glfwWaitEvents__ process events for all windows at once. @par Old basic main loop @code @@ -412,10 +414,15 @@ these hotkeys to function even when running in full screen mode. @subsection moving_terminate Automatic termination -GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization. To -release all resources allocated by GLFW, you should call @ref glfwTerminate -yourself. Note that this destroys all windows not already destroyed with @ref -glfwDestroyWindow, invalidating all window handles you may still have. +GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization, +because `exit` calls registered functions from the calling thread and while it +is permitted to call `exit` from any thread, @ref glfwTerminate may only be +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 diff --git a/docs/news.dox b/docs/news.dox index 04a6b4f3..70a3c1da 100644 --- a/docs/news.dox +++ b/docs/news.dox @@ -10,17 +10,18 @@ @subsection news_31_cursor Custom system cursor support GLFW now supports creating and setting custom system cursors. They can be -created with @ref glfwCreateCursor and set with @ref glfwSetCursor. Note that -custom cursors are only visible in normal cursor mode. +created with @ref glfwCreateCursor, set with @ref glfwSetCursor and destroyed +with @ref glfwDestroyCursor. Custom cursors are only visible in normal cursor +mode. @subsection news_31_drop File drop event support GLFW now provides a callback for receiving the paths of files dropped onto GLFW -windows. The callback is set with the @ref glfwSetDropCallback function. +windows. The callback is set with @ref glfwSetDropCallback. -@subsection news_31_emptyevent Empty event support +@subsection news_31_emptyevent Main thread waking support GLFW now provides the @ref glfwPostEmptyEvent function for posting an empty event from another thread to the main thread event queue, causing @ref @@ -36,29 +37,43 @@ client area of a window, with @ref glfwGetWindowFrameSize. @subsection news_31_autoiconify Multi-monitor installation support GLFW now supports disabling auto-iconification of full screen windows with -[GLFW_AUTO_ICONIFY](@ref window_hints_wnd). This is intended for people -building multi-monitor installations, where you need windows to stay in full -screen despite losing focus. +the [GLFW_AUTO_ICONIFY](@ref window_hints_wnd) window hint. This is intended +for people building multi-monitor installations, where you need windows to stay +in full screen despite losing focus. @subsection news_31_floating Floating windows GLFW now supports floating windows, also called topmost or always on top, for -easier debugging, with the `GLFW_FLOATING` window hint. +easier debugging with the [GLFW_FLOATING](@ref window_hints_wnd) window hint. @subsection news_31_focused Initially unfocused windows GLFW now supports preventing a windowed mode window from gaining input focus on -creation, with the `GLFW_FOCUSED` window hint. +creation, with the [GLFW_FOCUSED](@ref window_hints_wnd) window hint. @subsection news_31_charmods Character with modifiers callback -GLFW now provides a callback for character events with modifier key bits. -Unlike the regular character callback, this will report character events that -will not result in a character being input, for example if the Control key is -held down. +GLFW now provides a callback for character events with modifier key bits. The +callback is set with @ref glfwSetCharModsCallback. Unlike the regular character +callback, this will report character events that will not result in a character +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 diff --git a/docs/quick.dox b/docs/quick.dox index 120ca9b2..b1761efb 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -1,23 +1,25 @@ /*! -@page quick Getting started — A quick introduction +@page quick Getting started @tableofcontents -This guide will show how to write simple OpenGL applications using GLFW 3. It -will introduce a few of the most commonly used functions, but there are many -others. To see detailed documentation on any GLFW function, just click on its -name. +This guide takes you through writing a simple application using GLFW 3. The +application will create a window and OpenGL context, render a rotating triangle +and exit when the user closes the window or presses Escape. This guide will +introduce a few of the most commonly used functions, but there are many more. This guide assumes no experience with earlier versions of GLFW. If you -have used GLFW 2.x in the past, you should also read the -[transition guide](@ref moving). +have used GLFW 2 in the past, read the @ref moving guide, as some functions +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 -the GLFW 3 header file. +@subsection quick_include Including the GLFW header + +In the source files of your application where you use OpenGL or GLFW, you need +to include the GLFW 3 header file. @code #include @@ -54,40 +56,39 @@ inclusion of the GLFW header. @endcode -@section quick_init_term Initializing and terminating GLFW +@subsection quick_init_term Initializing and terminating GLFW -Before you can use most GLFW functions, the library must be initialized. This -is done with @ref glfwInit, which returns non-zero if successful, or zero if an -error occurred. +Before you can use most GLFW functions, the library must be initialized. On +successful initialization, non-zero is returned. If an error occurred, zero is +returned. @code if (!glfwInit()) exit(EXIT_FAILURE); @endcode -When you are done using GLFW, typically at the very end of the program, you need -to call @ref glfwTerminate. +When you are done using GLFW, typically just before the application exits, you +need to terminate GLFW. @code glfwTerminate(); @endcode This destroys any remaining windows and releases any other resources allocated by -GLFW. After this call, you must call @ref glfwInit again before using any GLFW +GLFW. After this call, you must initialize GLFW again before using any GLFW functions that require it. -@section quick_capture_error Setting an error callback +@subsection quick_capture_error Setting an error callback Most events are reported through callbacks, whether it's a key being pressed, a GLFW window being moved, or an error occurring. Callbacks are simply C functions (or C++ static methods) that are called by GLFW with arguments describing the event. -In case @ref glfwInit or any other GLFW function fails, an error is reported to -the GLFW error callback. You can receive these reports by setting the error -callback. The callback function itself should match the signature of @ref -GLFWerrorfun. Here is a simple error callback that just prints the error +In case a GLFW function fails, an error is reported to the GLFW error callback. +You can receive these reports with an error callback. This function must have +the signature below. This simple error callback just prints the error description to `stderr`. @code @@ -97,28 +98,28 @@ void error_callback(int error, const char* description) } @endcode -Setting the callback, so GLFW knows to call it, is done with @ref -glfwSetErrorCallback. This is one of the few GLFW functions that may be called -before @ref glfwInit, which lets you be notified of errors during -initialization, so you should set it before you do anything else with GLFW. +Callback functions must be set, so GLFW knows to call them. The function to set +the error callback is one of the few GLFW functions that may be called before +initialization, which lets you be notified of errors both during and after +initialization. @code glfwSetErrorCallback(error_callback); @endcode -@section quick_create_window Creating a window and context +@subsection quick_create_window Creating a window and context -The window (and its context) is created with @ref glfwCreateWindow, which -returns a handle to the created window. For example, this creates a 640 by 480 -windowed mode window: +The window and its OpenGL context are created with a single call, which returns +a handle to the created combined window and context object. For example, this +creates a 640 by 480 windowed mode window with an OpenGL context: @code GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL); @endcode -If window creation fails, `NULL` will be returned, so you need to check whether -it did. +If window or context creation fails, `NULL` will be returned, so it is necessary +to check the return value. @code if (!window) @@ -128,24 +129,11 @@ if (!window) } @endcode -This handle is then passed to all window related functions, and is provided to -you along with input events, so you know which window received the input. +The window handle is passed to all window related functions and is provided to +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 -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. +When a window is no longer needed, destroy it. @code glfwDestroyWindow(window); @@ -155,22 +143,22 @@ Once this function is called, no more events will be delivered for that window and its handle becomes invalid. -@section quick_context_current Making the OpenGL context current +@subsection quick_context_current Making the OpenGL context current Before you can use the OpenGL API, it must have a current OpenGL context. You -make a window's context current with @ref glfwMakeContextCurrent. It will then -remain as the current context until you make another context current or until -the window owning it is destroyed. +make a window's context current. @code glfwMakeContextCurrent(window); @endcode +The context will then remain as current until you make another context current +or until the window owning the current context is destroyed. -@section quick_window_close Checking the window close flag -Each window has a flag indicating whether the window should be closed. This can -be checked with @ref glfwWindowShouldClose. +@subsection quick_window_close Checking the window close flag + +Each window has a flag indicating whether the window should be closed. When the user attempts to close the window, either by pressing the close widget in the title bar or using a key combination like Alt+F4, this flag is set to 1. @@ -194,11 +182,11 @@ useful if you want to interpret other kinds of input as closing the window, like for example pressing the escape key. -@section quick_key_input Receiving input events +@subsection quick_key_input Receiving input events Each window has a large number of callbacks that can be set to receive all the -various kinds of events. To receive key press and release events, a -[key callback](@ref GLFWkeyfun) is set using @ref glfwSetKeyCallback. +various kinds of events. To receive key press and release events, create a key +callback function. @code static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods) @@ -208,16 +196,21 @@ static void key_callback(GLFWwindow* window, int key, int scancode, int action, } @endcode -For event callbacks to actually be called when an event occurs, you need to -process events as described below. +The key callback, like other window related callbacks, are set per-window. + +@code +glfwSetKeyCallback(window, key_callback); +@endcode + +In order for event callbacks to be called when events occur, you need to process +events as described below. -@section quick_render Rendering with OpenGL +@subsection quick_render Rendering with OpenGL Once you have a current OpenGL context, you can use OpenGL normally. In this tutorial, a multi-colored rotating triangle will be rendered. The framebuffer -size, needed by this example for `glViewport` and `glOrtho`, is retrieved with -@ref glfwGetFramebufferSize. +size needs to be retrieved for `glViewport`. @code int width, height; @@ -225,72 +218,80 @@ glfwGetFramebufferSize(window, &width, &height); glViewport(0, 0, width, height); @endcode -However, you can also set a framebuffer size callback using @ref +You can also set a framebuffer size callback using @ref glfwSetFramebufferSizeCallback and call `glViewport` from there. -@code -void framebuffer_size_callback(GLFWwindow* window, int width, int height) -{ - glViewport(0, 0, width, height); -} -@endcode +@subsection quick_timer Reading the timer -@section quick_timer Reading the timer - -For the triangle to rotate properly, a time source is needed. GLFW provides -@ref glfwGetTime, which returns the number of seconds since @ref glfwInit as -a `double`. The time source used is the most accurate on each platform and -generally has micro- or nanosecond resolution. +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 +most accurate on each platform and generally has micro- or nanosecond +resolution. @code double time = glfwGetTime(); @endcode -@section quick_swap_buffers Swapping buffers +@subsection quick_swap_buffers Swapping buffers -GLFW windows by default use double buffering. That means that you have two -rendering buffers; a front buffer and a back buffer. The front buffer is the -one being displayed and the back buffer the one you render to. +GLFW windows by default use double buffering. That means that each window has +two rendering buffers; a front buffer and a back buffer. The front buffer is +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 -front buffers in order to display the rendered frame, and begin rendering a new -frame. This is done with @ref glfwSwapBuffers. +When the entire frame has been rendered, the buffers need to be swapped with one +another, so the back buffer becomes the front buffer and vice versa. @code glfwSwapBuffers(window); @endcode +The swap interval indicates how many frames to wait until swapping the buffers, +commonly known as *vsync*. By default, the swap interval is zero, meaning +buffer swapping will occur immediately. On fast machines, many of those frames +will never be seen, as the screen is still only updated typically 60-75 times +per second, so this wastes a lot of CPU and GPU cycles. -@section quick_process_events Processing events +Also, because the buffers will be swapped in the middle the screen update, +leading to [screen tearing](https://en.wikipedia.org/wiki/Screen_tearing). + +For these reasons, applications will typically want to set the swap interval to +one. It can be set to higher values, but this is usually not recommended, +because of the input latency it leads to. + +@code +glfwSwapInterval(1); +@endcode + +This function acts on the current context and will fail unless a context is +current. + + +@subsection quick_process_events Processing events GLFW needs to communicate regularly with the window system both in order to -receive events and to show that it hasn't locked up. Event processing must be -done regularly and is normally done each frame before rendering but after buffer -swap. +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. -There are two ways to process pending events. @ref glfwPollEvents processes -only those events that have already been received and then returns immediately. -This is the best choice when rendering continually, like most games do. +There are two methods for processing pending events; polling and waiting. This +example will use event polling, which processes only those events that have +already been received and then returns immediately. @code glfwPollEvents(); @endcode -If instead you only need to update your rendering once you have received new -input, @ref glfwWaitEvents is a better choice. It waits until at least one -event has been received, putting the thread to sleep in the meantime, and then -processes all received events just like @ref glfwPollEvents does. This saves -a great deal of CPU cycles and is useful for, for example, many kinds of editing -tools. - -@code -glfwWaitEvents(); -@endcode +This is the best choice when rendering continually, like most games do. If +instead you only need to update your rendering once you have received new input, +@ref glfwWaitEvents is a better choice. It waits until at least one event has +been received, putting the thread to sleep in the meantime, and then processes +all received events. This saves a great deal of CPU cycles and is useful for, +for example, many kinds of editing tools. -@section quick_example Putting it together: A simple application +@section quick_example Putting it together Now that you know how to initialize GLFW, create a window and poll for keyboard input, it's possible to create a simple program. diff --git a/docs/rift.dox b/docs/rift.dox new file mode 100644 index 00000000..105c5b2e --- /dev/null +++ b/docs/rift.dox @@ -0,0 +1,91 @@ +/*! + +@page rift Oculus Rift guide + +@tableofcontents + +GLFW has no explicit support for the Oculus Rift, but + +This guide requires you to use the [native API](@ref native) and assumes +a certain level of proficiency with system level APIs and the compiler +toolchain. + + +@section rift_init Initializing libOVR and GLFW + +libOVR needs to be initialized before GLFW. This means calling +`ovr_Initialize`, `ovrHmd_Create` and `ovrHmd_ConfigureTracking` before @ref +glfwInit. Similarly, libOVR must be shut down after GLFW. This means calling +`ovrHmd_Destroy` and `ovr_Shutdown` after @ref glfwTerminate. + + +@section rift_extend Extend Desktop mode + +@subsection rift_extend_detect Detecting a Rift with GLFW + +If you have an actual Rift connected to your machine you can deduce which GLFW +monitor it corresponds to. Doing this requires you to use the +[native API](@ref native). + + +@subsubsection rift_extend_detect_win32 Detecting a Rift on Windows + +To identify which monitor corresponds to the Rift, compare Win32 display device +names. The display device name of a GLFW monitor is returned by @ref +glfwGetWin32Monitor and the display device name of the detected Rift is stored +in the `DisplayDeviceName` member of `ovrHmdDesc`. + +@code +int i, count; +GLFWmonitor* monitor = NULL; +GLFWmonitor** monitors = glfwGetMonitors(&count); + +for (i = 0; i < count; i++) +{ + if (strcmp(glfwGetWin32Monitor(monitors[i]), hmd->DisplayDeviceName) == 0) + { + monitor = monitors[i]; + break; + } +} +@endcode + + +@subsubsection rift_extend_detect_osx Detecting a Rift on OS X + +To identify which monitor corresponds to the Rift, compare OS X display IDs. +The display ID of a GLFW monitor is returned by @ref glfwGetCocoaMonitor and the +display ID of the detected Rift is stored in the `DisplayId` member of +`ovrHmdDesc`. + +@code +int i, count; +GLFWmonitor* monitor = NULL; +GLFWmonitor** monitors = glfwGetMonitors(&count); + +for (i = 0; i < count; i++) +{ + if (glfwGetCocoaMonitor(monitors[i]) == hmd->DisplayId) + { + monitor = monitors[i]; + break; + } +} +@endcode + + +@subsubsection rift_extend_detect_x11 Detecting a Rift on X11 + +At the time of writing, the 0.4 Rift SDK does not yet support X11. + + +@subsection rift_extend_create Creating a window and context + +LOL create. + + +@section rift_direct Direct HMD mode + +LOL direct. + +*/ diff --git a/docs/spaces.svg b/docs/spaces.svg new file mode 100644 index 00000000..c0b872e1 --- /dev/null +++ b/docs/spaces.svg @@ -0,0 +1,352 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + Primary monitor position + Secondary Monitor + Primary Monitor + Virtual Screen + + + Window + + + + + + Window position + Secondary monitor position + Client area origin + Virtual screen origin + + + + + Window Title + + diff --git a/docs/window.dox b/docs/window.dox index cf337916..f8d51a53 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -1,6 +1,6 @@ /*! -@page window Window handling guide +@page window Window guide @tableofcontents @@ -8,8 +8,16 @@ The primary purpose of GLFW is to provide a simple interface to window management and OpenGL and OpenGL ES context creation. GLFW supports multiple windows, which can be either a normal desktop window or a full screen window. +This guide introduces the window related functions of GLFW. There are also +guides for the other areas of GLFW. -@section window_object Window handles + - @ref intro + - @ref context + - @ref monitor + - @ref input + + +@section window_object Window objects The @ref GLFWwindow object encapsulates both a window and a context. They are created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or @@ -17,30 +25,34 @@ created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or linked, the object pointer is used as both a context and window handle. -@section window_creation Window creation +@subsection window_creation Window creation -The window and its context are created with @ref glfwCreateWindow, which -returns a handle to the created window object. For example, this creates a 640 -by 480 windowed mode window: +A window and its OpenGL or OpenGL ES context are created with @ref +glfwCreateWindow, which returns a handle to the created window object. For +example, this creates a 640 by 480 windowed mode window: @code GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL); +@endcode + +If window creation fails, `NULL` will be returned, so it is necessary to check +the return value. + +@code if (!window) { // Handle window creation failure } @endcode -If window creation fails, `NULL` will be returned, so you need to check the -return value. If creation failed, an error will have been reported to the error -callback. - -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. +The window handle is passed to all window related functions and is provided to +along with all input events, so event handlers can tell which window received +the event. 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 -more information about monitors, see the @ref monitor. +should use. In most cases, the user's primary monitor is a good choice. You +can get this with @ref glfwGetPrimaryMonitor. For more information about +monitors, see the @ref monitor. @code GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL); @@ -54,28 +66,25 @@ For more control over how the window and its context are created, see @ref window_hints below. -@section window_destruction Window destruction +@subsection window_destruction Window destruction -When you are done with the window, destroy it with the @ref glfwDestroyWindow -function. +When a window is no longer needed, destroy it with @ref glfwDestroyWindow. @code glfwDestroyWindow(window); @endcode -Once this function is called, no more events will be delivered for that window -and its handle becomes invalid. +Window destruction always succeeds. Before the actual destruction, all +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 - -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 +@subsection window_hints Window creation hints There are a number of hints that can be set before the creation of a window and context. Some affect the window itself, others affect the framebuffer or @@ -87,7 +96,7 @@ Note that hints need to be set *before* the creation of the window and context you wish to have the specified attributes. -@subsection window_hints_hard Hard and soft constraints +@subsubsection window_hints_hard Hard and soft constraints Some window hints are hard constraints. These must match the available capabilities *exactly* for window and context creation to succeed. Hints @@ -107,126 +116,127 @@ context, but are ignored when requesting an OpenGL ES context: - `GLFW_OPENGL_PROFILE` -@subsection window_hints_wnd Window related hints +@subsubsection window_hints_wnd Window related hints -The `GLFW_RESIZABLE` hint specifies whether the (windowed mode) window will be -resizable *by the user*. The window will still be resizable using the @ref +`GLFW_RESIZABLE` specifies whether the (windowed mode) window will be resizable +*by the user*. The window will still be resizable using the @ref glfwSetWindowSize function. This hint is ignored for full screen windows. -The `GLFW_VISIBLE` hint specifies whether the (windowed mode) window will be -initially visible. This hint is ignored for full screen windows. +`GLFW_VISIBLE` specifies whether the (windowed mode) window will be initially +visible. This hint is ignored for full screen windows. -The `GLFW_DECORATED` hint specifies whether the (windowed mode) window will have -window decorations such as a border, a close widget, etc. This hint is ignored -for full screen windows. Note that even though a window may lack a close -widget, it is usually still possible for the user to generate close events. +`GLFW_DECORATED` specifies whether the (windowed mode) window will have window +decorations such as a border, a close widget, etc. This hint is ignored for +full screen windows. Note that even though a window may lack a close widget, it +is usually still possible for the user to generate close events. -The `GLFW_FOCUSED` hint specifies whether the (windowed mode) window will be -given input focus when created. This hint is ignored for full screen and -initially hidden windows. +`GLFW_FOCUSED` specifies whether the (windowed mode) window will be given input +focus when created. This hint is ignored for full screen and initially hidden +windows. -The `GLFW_AUTO_ICONIFY` hint specifies whether the (full screen) window -will automatically iconify and restore the previous video mode on focus loss. -This hint is ignored for windowed mode windows. +`GLFW_AUTO_ICONIFY` specifies whether the (full screen) window will +automatically iconify and restore the previous video mode on focus loss. This +hint is ignored for windowed mode windows. -The `GLFW_FLOATING` hint specifies whether the window will be floating above -other regular windows, also called topmost or always-on-top. This is intended +`GLFW_FLOATING` specifies whether the window will be floating above other +regular windows, also called topmost or always-on-top. This is intended primarily for debugging purposes and cannot be used to implement proper full screen windows. This hint is ignored for full screen windows. -@subsection window_hints_fb Framebuffer related hints +@subsubsection window_hints_fb Framebuffer related hints -The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`, -`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` hints specify the desired bit -depths of the various components of the default framebuffer. `GLFW_DONT_CARE` -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 +`GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`, +`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` specify the desired bit depths of the +various components of the default framebuffer. `GLFW_DONT_CARE` means the application has no preference. +`GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` and +`GLFW_ACCUM_ALPHA_BITS` specify the desired bit depths of the various components +of the accumulation buffer. `GLFW_DONT_CARE` means the application has no +preference. + @note Accumulation buffers are a legacy OpenGL feature and should not be used in new code. -The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary -buffers. `GLFW_DONT_CARE` means the application has no preference. +`GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers. +`GLFW_DONT_CARE` means the application has no preference. @note Auxiliary buffers are a legacy OpenGL feature and should not be used in new code. -The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering. This is -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 +`GLFW_STEREO` specifies whether to use stereoscopic rendering. This is a hard constraint. -The `GLFW_REFRESH_RATE` hint specifies the desired refresh rate for full screen -windows. If set to zero, the highest available refresh rate will be used. This -hint is ignored for windowed mode windows. +`GLFW_SAMPLES` specifies the desired number of samples to use for multisampling. +Zero disables multisampling. `GLFW_DONT_CARE` means the application has no +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 -for. Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`. This is -a hard constraint. +`GLFW_REFRESH_RATE` specifies the desired refresh rate for full screen windows. +If set to zero, the highest available refresh rate will be used. This hint is +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 -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. +@subsubsection window_hints_ctx Context related hints + +`GLFW_CLIENT_API` specifies which client API to create the context for. +Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`. This is a hard +constraint. + +`GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client +API version that the created context must be compatible with. + +For OpenGL, `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are +not hard constraints, as they don't have to match exactly, but @ref +glfwCreateWindow will still fail if the resulting OpenGL version is less than +the one requested. It is therefore perfectly safe to use the default of version +1.0 for legacy code and you may still get backwards-compatible contexts of +version 3.0 and above when available. While there is no way to ask the driver for a context of the highest supported -version, most drivers provide this when you ask GLFW for a version -1.0 context. +version, most drivers provide this when you ask GLFW for a version 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 -specifies whether the OpenGL context should be forward-compatible, i.e. one -where all functionality deprecated in the requested version of OpenGL is -removed. This may only be used if the requested OpenGL version is 3.0 or -above. If another client API is requested, this hint is ignored. +`GLFW_OPENGL_FORWARD_COMPAT` specifies whether the OpenGL context should be +forward-compatible, i.e. one where all functionality deprecated in the requested +version of OpenGL is removed. This may only be used if the requested OpenGL +version is 3.0 or above. If OpenGL S is requested, this hint is ignored. -@note Forward-compatibility is described in detail in the +Forward-compatibility is described in detail in the [OpenGL Reference Manual](https://www.opengl.org/registry/). -If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint -specifies whether to create a debug OpenGL context, which may have -additional error and performance issue reporting functionality. If another -client API is requested, this hint is ignored. +`GLFW_OPENGL_DEBUG_CONTEXT` specifies whether to create a debug OpenGL context, +which may have additional error and performance issue reporting functionality. +If OpenGL ES is requested, this hint is ignored. -If an OpenGL context is requested, the `GLFW_OPENGL_PROFILE` hint specifies -which OpenGL profile to create the context for. Possible values are one of -`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`, or -`GLFW_OPENGL_ANY_PROFILE` to not request a specific profile. If requesting -an OpenGL version below 3.2, `GLFW_OPENGL_ANY_PROFILE` must be used. If -another client API is requested, this hint is ignored. +`GLFW_OPENGL_PROFILE` specifies which OpenGL profile to create the context for. +Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or +`GLFW_OPENGL_COMPAT_PROFILE`, or `GLFW_OPENGL_ANY_PROFILE` to not request +a specific profile. If requesting an OpenGL version below 3.2, +`GLFW_OPENGL_ANY_PROFILE` must be used. If another OpenGL ES is requested, +this hint is ignored. -@note OpenGL profiles are described in detail in the +OpenGL profiles are described in detail in the [OpenGL Reference Manual](https://www.opengl.org/registry/). -The `GLFW_CONTEXT_ROBUSTNESS` hint specifies the robustness strategy to be -used by the context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or +`GLFW_CONTEXT_ROBUSTNESS` specifies the robustness strategy to be used by the +context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request a robustness strategy. -The `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint specifies the release behavior to be +`GLFW_CONTEXT_RELEASE_BEHAVIOR` specifies the release behavior to be used by the context. Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`. If the behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context @@ -235,48 +245,65 @@ the pipeline will be flushed whenever the context is released from being the current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will not be flushed on release. -@note Context release behaviors are described in detail by the +Context release behaviors are described in detail by the [GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt) extension. -@subsection window_hints_values Supported and default values +@subsubsection window_hints_values Supported and default values -| Name | Default value | Supported values | -| ------------------------------- | --------------------------- | ----------------------- | -| `GLFW_RESIZABLE` | `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_FOCUSED` | `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_RED_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_ALPHA_BITS` | 8 | 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_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_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_AUX_BUFFERS` | 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_STEREO` | `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_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_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_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_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` | +Window hint | Default value | Supported values +------------------------------- | --------------------------- | ---------------- +`GLFW_RESIZABLE` | `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_FOCUSED` | `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_RED_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_ALPHA_BITS` | 8 | 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_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_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_AUX_BUFFERS` | 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_STEREO` | `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_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_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_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_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` -@section window_close Window close flag +@section window_events Window event processing + +See @ref input_event in the @ref input. + + +@section window_properties Window properties and events + +@subsection window_userptr User pointer + +Each window has a user pointer that can be set with @ref +glfwSetWindowUserPointer and fetched with @ref glfwGetWindowUserPointer. This +can be used for any purpose you need and will not be modified by GLFW throughout +the life-time of the window. + +The initial value of the pointer is `NULL`. + + +@subsection window_close Closing and close flag When the user attempts to close the window, for example by clicking the close widget or using a key chord like Alt+F4, the *close flag* of the window is set. @@ -297,16 +324,16 @@ while (!glfwWindowShouldClose(window)) } @endcode -If you wish to be notified when the user attempts to close a window, you can set -the close callback with @ref glfwSetWindowCloseCallback. This callback is -called directly *after* the close flag has been set. +If you wish to be notified when the user attempts to close a window, set a close +callback with @ref glfwSetWindowCloseCallback. @code glfwSetWindowCloseCallback(window, window_close_callback); @endcode -The callback function can be used for example to filter close requests and clear -the close flag again unless certain conditions are met. +The callback function is called directly *after* the close flag has been set. +It can be used for example to filter close requests and clear the close flag +again unless certain conditions are met. @code void window_close_callback(GLFWwindow* window) @@ -317,26 +344,27 @@ void window_close_callback(GLFWwindow* window) @endcode -@section window_size Window size +@subsection window_size Client area size The size of a window can be changed with @ref glfwSetWindowSize. For windowed -mode windows, this resizes the specified window so that its *client area* has -the specified size. Note that the window system may put limitations on size. -For full screen windows, it selects and sets the video mode most closely -matching the specified size. +mode windows, this resizes the window so that its *client area* has the +specified size. The window system may impose limits on window size. For full +screen windows, it selects and sets the video mode most closely matching the +specified size and the color bit depth and refresh rate hints set at creation. @code void glfwSetWindowSize(window, 640, 480); @endcode If you wish to be notified when a window is resized, whether by the user or -the system, you can set the size callback with @ref glfwSetWindowSizeCallback. +the system, set a size callback with @ref glfwSetWindowSizeCallback. @code glfwSetWindowSizeCallback(window, window_size_callback); @endcode -The callback function receives the new size of the client area of the window. +The callback function receives the new size of the client area of the window +when it is resized. @code void window_size_callback(GLFWwindow* window, int width, int height) @@ -354,10 +382,24 @@ glfwGetWindowSize(window, &width, &height); @note Do not pass the window size to `glViewport` or other pixel-based OpenGL calls. The window size is in screen coordinates, not pixels. Use the -framebuffer size, which is in pixels, for pixel-based calls. +[framebuffer size](@ref window_fbsize), which is in pixels, for pixel-based +calls. + +The above functions work with the size of the client area, but decorated windows +typically have title bars and window frames around this rectangle. You can +retrieve the extents of these with @ref glfwGetWindowFrameSize. + +@code +int left, top, right, bottom; +glfwGetWindowFrameSize(window, &left, &top, &right, &bottom); +@endcode + +The returned values are the distances, in screen coordinates, from the edges of +the client area to the corresponding edges of the full window. As they are +distances and not coordinates, they are always zero or positive. -@section window_fbsize Window framebuffer size +@subsection window_fbsize Framebuffer size While the size of a window is measured in screen coordinates, OpenGL works with pixels. The size you pass into `glViewport`, for example, should be in pixels @@ -367,15 +409,15 @@ a second set of functions to retrieve the size in pixels of the framebuffer of a window. If you wish to be notified when the framebuffer of a window is resized, whether -by the user or the system, you can set the size callback with @ref +by the user or the system, set a size callback with @ref glfwSetFramebufferSizeCallback. @code glfwSetFramebufferSizeCallback(window, framebuffer_size_callback); @endcode -The callback function receives the new size of the client area of the window, -which can for example be used to update the OpenGL viewport. +The callback function receives the new size of the framebuffer when it is +resized, which can for example be used to update the OpenGL viewport. @code void framebuffer_size_callback(GLFWwindow* window, int width, int height) @@ -398,26 +440,26 @@ a window, for example if the window is dragged between a regular monitor and a high-DPI one. -@section window_pos Window position +@subsection window_pos Position The position of a windowed-mode window can be changed with @ref glfwSetWindowPos. This moves the window so that the upper-left corner of its -client area has the specified screen coordinates. Note that the window system -may put limitations on placement. +client area has the specified screen coordinates. The window system may put +limitats on window placement. @code glfwSetWindowPos(window, 100, 100); @endcode -If you wish to be notified when a window is moved, whether by the user or -the system, you can set the position callback with @ref glfwSetWindowPosCallback. +If you wish to be notified when a window is moved, whether by the user, system +or your own code, set a position callback with @ref glfwSetWindowPosCallback. @code glfwSetWindowPosCallback(window, window_pos_callback); @endcode -The callback function receives the new position of the upper-left corner of its -client area. +The callback function receives the new position of the upper-left corner of the +client area when the window is moved. @code void window_pos_callback(GLFWwindow* window, int xpos, int ypos) @@ -434,31 +476,190 @@ glfwGetWindowPos(window, &xpos, &ypos); @endcode -@section window_title Window title +@subsection window_title Title All GLFW windows have a title, although undecorated or full screen windows may -not display it or only display it in a task bar or similar interface. To change -the title of a window, use @ref glfwSetWindowTitle. +not display it or only display it in a task bar or similar interface. You can +set a UTF-8 encoded window title with @ref glfwSetWindowTitle. @code glfwSetWindowTitle(window, "My Window"); @endcode -The window title is a regular C string using the UTF-8 encoding. This means -for example that, as long as your source file is encoded as UTF-8, you can use -any Unicode characters. +The specified string is copied before the function returns, so there is no need +to keep it around. + +As long as your source file is encoded as UTF-8, you can use any Unicode +characters directly in the source. @code -glfwSetWindowTitle(window, "さよなら絶望先生"); +glfwSetWindowTitle(window, "ヒカルの碁"); @endcode -@section window_attribs Window attributes +@subsection window_monitor Monitor + +Full screen windows are associated with a specific monitor. You can get the +handle for this monitor with @ref glfwGetWindowMonitor. + +@code +GLFWmonitor* monitor = glfwGetWindowMonitor(window); +@endcode + +This monitor handle is one of those returned by @ref glfwGetMonitors. + +For windowed mode windows, this function returns `NULL`. This is the +recommended way to tell full screen windows from windowed mode windows. + + +@subsection window_iconify Iconification + +Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow. + +@code +glfwIconifyWindow(window); +@endcode + +When a full screen window is iconified, the original video mode of its monitor +is restored until the user or application restores the window. + +Iconified windows can be restored with @ref glfwRestoreWindow. + +@code +glfwRestoreWindow(window); +@endcode + +When a full screen window is restored, the desired video mode is restored to its +monitor as well. + +If you wish to be notified when a window is iconified or restored, whether by +the user, system or your own code, set a iconify callback with @ref +glfwSetWindowIconifyCallback. + +@code +glfwSetWindowIconifyCallback(window, window_iconify_callback); +@endcode + +The callback function receives changes in the iconification state of the window. + +@code +void window_iconify_callback(GLFWwindow* window, int iconified) +{ + if (iconified) + { + // The window was iconified + } + else + { + // The window was restored + } +} +@endcode + +You can also get the iconification state with @ref glfwGetWindowAttrib. + +@code +int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED); +@endcode + + +@subsection window_hide Visibility + +Windowed mode windows can be hidden with @ref glfwHideWindow. + +@code +glfwHideWindow(window); +@endcode + +This makes the window completely invisible to the user, including removing it +from the task bar, dock or window list. Full screen windows cannot be hidden +and calling @ref glfwHideWindow on a full screen window does nothing. + +Hidden windows can be shown with @ref glfwShowWindow. + +@code +glfwShowWindow(window); +@endcode + +Windowed mode windows can be created initially hidden with the `GLFW_VISIBLE` +[window hint](@ref window_hints_wnd). Windows created hidden are completely +invisible to the user until shown. This can be useful if you need to set up +your window further before showing it, for example moving it to a specific +location. + +You can also get the visibility state with @ref glfwGetWindowAttrib. + +@code +int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE); +@endcode + + +@subsection window_focus Input focus + +If you wish to be notified when a window gains or loses focus, whether by +the user, system or your own code, set a focus callback with @ref +glfwSetWindowFocusCallback. + +@code +glfwSetWindowFocusCallback(window, window_focus_callback); +@endcode + +The callback function receives changes in the focus state of the window. + +@code +void window_focus_callback(GLFWwindow* window, int focused) +{ + if (focused) + { + // The window gained focus + } + else + { + // The window lost focus + } +} +@endcode + +You can also get the focus state with @ref glfwGetWindowAttrib. + +@code +int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED); +@endcode + + +@subsection window_refresh Damage and refresh + +If you wish to be notified when the contents of a window is damaged and needs +to be refreshed, set a window refresh callback with @ref +glfwSetWindowRefreshCallback. + +@code +glfwSetWindowRefreshCallback(m_handle, window_refresh_callback); +@endcode + +The callback function is called when the contents of the window needs to be +refreshed. + +@code +void window_refresh_callback(GLFWwindow* window) +{ + draw_editor_ui(window); + glfwSwapBuffers(window); +} +@endcode + +@note On compositing window systems such as Aero, Compiz or Aqua, where the +window contents are saved off-screen, this callback may be called only very +infrequently or never at all. + + +@subsection window_attribs Attributes Windows have a number of attributes that can be returned using @ref glfwGetWindowAttrib. Some reflect state that may change during the lifetime of the window, while others reflect the corresponding hints and are fixed at the -time of creation. +time of creation. Some are related to the actual window and others to its +context. @code if (glfwGetWindowAttrib(window, GLFW_FOCUSED)) @@ -468,61 +669,58 @@ if (glfwGetWindowAttrib(window, GLFW_FOCUSED)) @endcode -@subsection window_attribs_window Window attributes +@subsubsection window_attribs_window Window related attributes -The `GLFW_FOCUSED` attribute indicates whether the specified window currently -has input focus. +`GLFW_FOCUSED` indicates whether the specified window has input focus. -The `GLFW_ICONIFIED` attribute indicates whether the specified window is -currently iconified, whether by the user or with @ref glfwIconifyWindow. +`GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by +the user or with @ref glfwIconifyWindow. -The `GLFW_VISIBLE` attribute indicates whether the specified window is currently -visible. Window visibility can be controlled with @ref glfwShowWindow and @ref -glfwHideWindow and initial visibility is controlled by the -[window hint](@ref window_hints) with the same name. +`GLFW_VISIBLE` indicates whether the specified window is visible. Window +visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow +and initial visibility is controlled by the [window hint](@ref window_hints) +with the same name. -The `GLFW_RESIZABLE` attribute 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_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. -The `GLFW_DECORATED` attribute indicates whether the specified window has -decorations such as a border, a close widget, etc. This is controlled by the +`GLFW_DECORATED` indicates whether the specified window has decorations such as +a border, a close widget, etc. This is controlled by the [window hint](@ref window_hints) with the same name. -The `GLFW_FLOATING` attribute indicates whether the specified window is -floating, also called topmost or always-on-top. This is controlled by the +`GLFW_FLOATING` indicates whether the specified window is floating, also called +topmost or always-on-top. This is controlled by the [window hint](@ref window_hints) with the same name. -@subsection window_attribs_context Context attributes +@subsubsection window_attribs_context Context related attributes -The `GLFW_CLIENT_API` attribute indicates the client API provided by the -window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`. +`GLFW_CLIENT_API` indicates the client API provided by the window's context; +either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`. -The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and -`GLFW_CONTEXT_REVISION` attributes indicate the client API version of the -window's context. +`GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and +`GLFW_CONTEXT_REVISION` indicate the client API version of the window's context. -The `GLFW_OPENGL_FORWARD_COMPAT` attribute is `GL_TRUE` if the window's -context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise. +`GLFW_OPENGL_FORWARD_COMPAT` is `GL_TRUE` if the window's context is an OpenGL +forward-compatible one, or `GL_FALSE` otherwise. -The `GLFW_OPENGL_DEBUG_CONTEXT` attribute is `GL_TRUE` if the window's -context is an OpenGL debug context, or `GL_FALSE` otherwise. +`GLFW_OPENGL_DEBUG_CONTEXT` is `GL_TRUE` if the window's context is an OpenGL +debug context, or `GL_FALSE` otherwise. -The `GLFW_OPENGL_PROFILE` attribute indicates the OpenGL profile used by the -context. This is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` -if the context uses a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the -OpenGL profile is unknown or the context is for another client API. Note that -the returned profile may not match the profile bits of the context flags, as -GLFW will try other means of detecting the profile when no bits are set. +`GLFW_OPENGL_PROFILE` indicates the OpenGL profile used by the context. This is +`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context uses +a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is unknown +or the context is an OpenGL ES context. Note that the returned profile may not +match the profile bits of the context flags, as GLFW will try other means of +detecting the profile when no bits are set. -The `GLFW_CONTEXT_ROBUSTNESS` attribute indicates the robustness strategy -used by the context. This is `GLFW_LOSE_CONTEXT_ON_RESET` or -`GLFW_NO_RESET_NOTIFICATION` if the window's context supports robustness, or -`GLFW_NO_ROBUSTNESS` otherwise. +`GLFW_CONTEXT_ROBUSTNESS` indicates the robustness strategy used by the context. +This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION` if the +window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise. -@section window_swap Swapping buffers +@section window_swap Buffer swapping GLFW windows are by default double buffered. That means that you have two rendering buffers; a front buffer and a back buffer. The front buffer is @@ -538,7 +736,8 @@ glfwSwapBuffers(window); Sometimes it can be useful to select when the buffer swap will occur. With the function @ref glfwSwapInterval it is possible to select the minimum number of -monitor refreshes the driver should wait before swapping the buffers: +monitor refreshes the driver wait should from the time @ref glfwSwapBuffers was +called before swapping the buffers: @code glfwSwapInterval(1); diff --git a/examples/simple.c b/examples/simple.c index 89eaa022..c39be574 100644 --- a/examples/simple.c +++ b/examples/simple.c @@ -57,6 +57,7 @@ int main(void) } glfwMakeContextCurrent(window); + glfwSwapInterval(1); glfwSetKeyCallback(window, key_callback); diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 6a20f897..b728012d 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -39,20 +39,26 @@ extern "C" { *************************************************************************/ /*! @defgroup context Context handling + * + * This is the reference documentation for context related functions. For more + * information, see the @ref context. */ -/*! @defgroup error Error handling - */ -/*! @defgroup init Initialization and version information +/*! @defgroup init Initialization, version and errors + * + * This is the reference documentation for initialization and termination of + * the library, version management and error handling. For more information, + * see the @ref intro. */ /*! @defgroup input Input handling + * + * This is the reference documentation for input related functions and types. + * For more information, see the @ref input. */ /*! @defgroup monitor Monitor handling * * This is the reference documentation for monitor related functions and types. * For more information, see the @ref monitor. */ -/*! @defgroup time Time input - */ /*! @defgroup window Window handling * * This is the reference documentation for window related functions and types, @@ -232,15 +238,24 @@ extern "C" { /*! @name Key and button actions * @{ */ -/*! @brief The key or button was released. +/*! @brief The key or mouse button was released. + * + * The key or mouse button was released. + * * @ingroup input */ #define GLFW_RELEASE 0 -/*! @brief The key or button was pressed. +/*! @brief The key or mouse button was pressed. + * + * The key or mouse button was pressed. + * * @ingroup input */ #define GLFW_PRESS 1 /*! @brief The key was held down until it repeated. + * + * The key was held down until it repeated. + * * @ingroup input */ #define GLFW_REPEAT 2 @@ -456,33 +471,89 @@ extern "C" { /*! @} */ /*! @defgroup errors Error codes - * @ingroup error + * @ingroup init * @{ */ /*! @brief GLFW has not been initialized. + * + * This occurs if a GLFW function was called that may not be called unless the + * library is [initialized](@ref intro_init). + * + * @par Analysis + * Application programmer error. Initialize GLFW before calling any function + * that requires initialization. */ #define GLFW_NOT_INITIALIZED 0x00010001 /*! @brief No context is current for this thread. + * + * This occurs if a GLFW function was called that needs and operates on the + * current OpenGL or OpenGL ES context but no context is current on the calling + * thread. One such function is @ref glfwSwapInterval. + * + * @par Analysis + * Application programmer error. Ensure a context is current before calling + * functions that require a current context. */ #define GLFW_NO_CURRENT_CONTEXT 0x00010002 -/*! @brief One of the enum parameters for the function was given an invalid - * enum. +/*! @brief One of the arguments to the function was an invalid enum value. + * + * One of the arguments to the function was an invalid enum value, for example + * requesting `GLFW_RED_BITS` with @ref glfwGetWindowAttrib. + * + * @par Analysis + * Application programmer error. Fix the offending call. */ #define GLFW_INVALID_ENUM 0x00010003 -/*! @brief One of the parameters for the function was given an invalid value. +/*! @brief One of the arguments to the function was an invalid value. + * + * One of the arguments to the function was an invalid value, for example + * requesting a non-existent OpenGL or OpenGL ES version like 2.7. + * + * Requesting a valid but unavailable OpenGL or OpenGL ES version will instead + * result in a @ref GLFW_VERSION_UNAVAILABLE error. + * + * @par Analysis + * Application programmer error. Fix the offending call. */ #define GLFW_INVALID_VALUE 0x00010004 /*! @brief A memory allocation failed. + * + * A memory allocation failed. + * + * @par Analysis + * A bug in GLFW or the underlying operating system. Report the bug to our + * [issue tracker](https://github.com/glfw/glfw/issues). */ #define GLFW_OUT_OF_MEMORY 0x00010005 /*! @brief GLFW could not find support for the requested client API on the * system. */ #define GLFW_API_UNAVAILABLE 0x00010006 -/*! @brief The requested client API version is not available. +/*! @brief The requested OpenGL or OpenGL ES version is not available. + * + * The requested OpenGL or OpenGL ES version (including any requested profile + * or context option) is not available on this machine. + * + * @par Analysis + * The machine does not support your requirements. If your application is + * sufficiently flexible, downgrade your requirements and try again. + * Otherwise, inform the user that their machine does not match your + * requirements. + * + * @note Because GLFW is not psychic, future invalid OpenGL and OpenGL ES + * versions, say for example OpenGL 4.8 if 5.0 comes out before the 4.x series + * gets that far, also fail with this error and not @ref GLFW_INVALID_VALUE. + * The version logic is updated in every patch release, as needed. */ #define GLFW_VERSION_UNAVAILABLE 0x00010007 /*! @brief A platform-specific error occurred that does not match any of the * more specific categories. + * + * A platform-specific error occurred that does not match any of the more + * specific categories. + * + * @par Analysis + * A bug in GLFW or the underlying operating system. Report the bug to our + * [issue tracker](https://github.com/glfw/glfw/issues). */ #define GLFW_PLATFORM_ERROR 0x00010008 /*! @brief The clipboard did not contain data in the requested format. @@ -600,7 +671,7 @@ typedef struct GLFWcursor GLFWcursor; * * @sa glfwSetErrorCallback * - * @ingroup error + * @ingroup init */ typedef void (* GLFWerrorfun)(int,const char*); @@ -913,54 +984,66 @@ typedef struct GLFWimage /*! @brief Initializes the GLFW library. * * This function initializes the GLFW library. Before most GLFW functions can - * be used, GLFW must be initialized, and before a program terminates GLFW + * be used, GLFW must be initialized, and before an application terminates GLFW * should be terminated in order to free any resources allocated during or * after initialization. * * If this function fails, it calls @ref glfwTerminate before returning. If it - * succeeds, you should call @ref glfwTerminate before the program exits. + * succeeds, you should call @ref glfwTerminate before the application exits. * * Additional calls to this function after successful initialization but before * termination will return `GL_TRUE` immediately. * - * @return `GL_TRUE` if successful, or `GL_FALSE` if an error occurred. Errors - * are reported to the [error callback](@ref intro_error). + * @return `GL_TRUE` if successful, or `GL_FALSE` if an + * [error](@ref error_handling) occurred. * - * @par New in GLFW 3 - * This function no longer registers @ref glfwTerminate with `atexit`. - * - * @note This function may only be called from the main thread. - * - * @note **OS X:** This function will change the current directory of the + * @remarks **OS X:** This function will change the current directory of the * application to the `Contents/Resources` subdirectory of the application's - * bundle, if present. + * bundle, if present. This can be disabled with a + * [compile-time option](@ref compile_options_osx). * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref intro_init * @sa glfwTerminate * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** This function no longer registers @ref glfwTerminate with `atexit`. + * * @ingroup init */ GLFWAPI int glfwInit(void); /*! @brief Terminates the GLFW library. * - * This function destroys all remaining windows, frees any allocated resources - * and sets the library to an uninitialized state. Once this is called, you - * must again call @ref glfwInit successfully before you will be able to use - * most GLFW functions. + * This function destroys all remaining windows and cursors, restores any + * modified gamma ramps and frees any other allocated resources. Once this + * function is called, you must again call @ref glfwInit successfully before + * you will be able to use most GLFW functions. * * If GLFW has been successfully initialized, this function should be called - * before the program exits. If initialization fails, there is no need to call - * this function, as it is called by @ref glfwInit before it returns failure. + * before the application exits. If initialization fails, there is no need to + * call this function, as it is called by @ref glfwInit before it returns + * failure. * * @remarks This function may be called before @ref glfwInit. * - * @note This function may only be called from the main thread. - * * @warning No window's context may be current on another thread when this * function is called. * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref intro_init * @sa glfwInit * + * @par History + * Added in GLFW 1.0. + * * @ingroup init */ GLFWAPI void glfwTerminate(void); @@ -971,18 +1054,24 @@ GLFWAPI void glfwTerminate(void); * library. It is intended for when you are using GLFW as a shared library and * want to ensure that you are using the minimum required version. * + * Any or all of the version arguments may be `NULL`. This function always + * succeeds. + * * @param[out] major Where to store the major version number, or `NULL`. * @param[out] minor Where to store the minor version number, or `NULL`. * @param[out] rev Where to store the revision number, or `NULL`. * - * @remarks This function always succeeds. - * * @remarks This function may be called before @ref glfwInit. * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. * + * @sa @ref intro_version * @sa glfwGetVersionString * + * @par History + * Added in GLFW 1.0. + * * @ingroup init */ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); @@ -994,16 +1083,24 @@ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); * describes the version, platform, compiler and any platform-specific * compile-time options. * - * @return The GLFW version string. + * This function always succeeds. * - * @remarks This function always succeeds. + * @return The GLFW version string. * * @remarks This function may be called before @ref glfwInit. * - * @remarks This function may be called from any thread. + * @par Pointer Lifetime + * The returned string is static and compile-time generated. * + * @par Thread Safety + * This function may be called from any thread. + * + * @sa @ref intro_version * @sa glfwGetVersion * + * @par History + * Added in GLFW 3.0. + * * @ingroup init */ GLFWAPI const char* glfwGetVersionString(void); @@ -1013,26 +1110,29 @@ GLFWAPI const char* glfwGetVersionString(void); * This function sets the error callback, which is called with an error code * and a human-readable description each time a GLFW error occurs. * + * The error callback is called on the thread where the error occurred. If you + * are using GLFW from multiple threads, your error callback needs to be + * written accordingly. + * + * Because the description string may have been generated specifically for that + * error, it is not guaranteed to be valid after the callback has returned. If + * you wish to use it after the callback returns, you need to make a copy. + * * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @return The previously set callback, or `NULL` if no callback was set. * - * @remarks This function always succeeds. - * * @remarks This function may be called before @ref glfwInit. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * - * @note The error callback is called by the thread where the error occurred. - * If you are using GLFW from multiple threads, your error callback needs to be - * written accordingly. + * @sa @ref error_handling * - * @note Because the description string provided to the callback may have been - * generated specifically for that error, it is not guaranteed to be valid - * after the callback has returned. If you wish to use it after that, you need - * to make your own copy of it before returning. + * @par History + * Added in GLFW 3.0. * - * @ingroup error + * @ingroup init */ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun); @@ -1041,22 +1141,26 @@ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun); * This function returns an array of handles for all currently connected * monitors. * - * @param[out] count Where to store the size of the returned array. This is - * set to zero if an error occurred. - * @return An array of monitor handles, or `NULL` if an error occurred. Errors - * are reported to the [error callback](@ref intro_error). + * @param[out] count Where to store the number of monitors in the returned + * array. This is set to zero if an error occurred. + * @return An array of monitor handles, or `NULL` if an + * [error](@ref error_handling) occurred. * - * @note This function may only be called from the main thread. + * @par Pointer Lifetime + * The returned array is allocated and freed by GLFW. You should not free it + * yourself. It is guaranteed to be valid only until the monitor configuration + * changes. * - * @note The returned array is allocated and freed by GLFW. You should not - * free it yourself. - * - * @note The returned array is valid only until the monitor configuration - * changes. See @ref glfwSetMonitorCallback to receive notifications of - * configuration changes. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref monitor_monitors + * @sa @ref monitor_event * @sa glfwGetPrimaryMonitor * + * @par History + * Added in GLFW 3.0. + * * @ingroup monitor */ GLFWAPI GLFWmonitor** glfwGetMonitors(int* count); @@ -1066,13 +1170,18 @@ GLFWAPI GLFWmonitor** glfwGetMonitors(int* count); * This function returns the primary monitor. This is usually the monitor * where elements like the Windows task bar or the OS X menu bar is located. * - * @return The primary monitor, or `NULL` if an error occurred. Errors are - * reported to the [error callback](@ref intro_error). + * @return The primary monitor, or `NULL` if an [error](@ref error_handling) + * occurred. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref monitor_monitors * @sa glfwGetMonitors * + * @par History + * Added in GLFW 3.0. + * * @ingroup monitor */ GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void); @@ -1082,11 +1191,20 @@ GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void); * This function returns the position, in screen coordinates, of the upper-left * corner of the specified monitor. * + * Any or all of the position arguments may be `NULL`. If an error occurs, all + * non-`NULL` position arguments will be set to zero. + * * @param[in] monitor The monitor to query. * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`. * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref monitor_properties + * + * @par History + * Added in GLFW 3.0. * * @ingroup monitor */ @@ -1097,17 +1215,26 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); * This function returns the size, in millimetres, of the display area of the * specified monitor. * + * Any or all of the size arguments may be `NULL`. If an error occurs, all + * non-`NULL` size arguments will be set to zero. + * * @param[in] monitor The monitor to query. * @param[out] width Where to store the width, in mm, of the monitor's display * area, or `NULL`. * @param[out] height Where to store the height, in mm, of the monitor's * display area, or `NULL`. * - * @note This function may only be called from the main thread. + * @note Some systems do not provide accurate monitor size information, either + * because the EDID data is incorrect, or because the driver does not report it + * accurately. * - * @note Some operating systems do not provide accurate information, either - * because the monitor's EDID data is incorrect, or because the driver does not - * report it accurately. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref monitor_properties + * + * @par History + * Added in GLFW 3.0. * * @ingroup monitor */ @@ -1116,16 +1243,24 @@ GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* width, int* h /*! @brief Returns the name of the specified monitor. * * This function returns a human-readable name, encoded as UTF-8, of the - * specified monitor. + * specified monitor. The name typically reflects the make and model of the + * monitor and is not guaranteed to be unique among the connected monitors. * * @param[in] monitor The monitor to query. - * @return The UTF-8 encoded name of the monitor, or `NULL` if an error - * occurred. Errors are reported to the [error callback](@ref intro_error). + * @return The UTF-8 encoded name of the monitor, or `NULL` if an + * [error](@ref error_handling) occurred. * - * @note This function may only be called from the main thread. + * @par Pointer Lifetime + * The returned string is allocated and freed by GLFW. You should not free it + * yourself. It is valid until the specified monitor is disconnected. * - * @note The returned string is allocated and freed by GLFW. You should not - * free it yourself. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref monitor_properties + * + * @par History + * Added in GLFW 3.0. * * @ingroup monitor */ @@ -1142,11 +1277,17 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. - * * @bug **X11:** This callback is not yet called on monitor configuration * changes. * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref monitor_event + * + * @par History + * Added in GLFW 3.0. + * * @ingroup monitor */ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun); @@ -1161,19 +1302,27 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun); * @param[in] monitor The monitor to query. * @param[out] count Where to store the number of video modes in the returned * array. This is set to zero if an error occurred. - * @return An array of video modes, or `NULL` if an error occurred. Errors are - * reported to the [error callback](@ref intro_error). + * @return An array of video modes, or `NULL` if an + * [error](@ref error_handling) occurred. * - * @note This function may only be called from the main thread. + * @par Pointer Lifetime + * The returned array is allocated and freed by GLFW. You should not free it + * yourself. It is valid until the specified monitor is disconnected or this + * function is called again for that monitor. * - * @note The returned array is allocated and freed by GLFW. You should not - * free it yourself. - * - * @note The returned array is valid only until this function is called again - * for the specified monitor. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref monitor_modes * @sa glfwGetVideoMode * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Changed to return a dynamic array of video modes for a specific + * monitor. + * * @ingroup monitor */ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count); @@ -1181,20 +1330,26 @@ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count); /*! @brief Returns the current mode of the specified monitor. * * This function returns the current video mode of the specified monitor. If - * you are using a full screen window, the return value will therefore depend - * on whether it is focused. + * you have created a full screen window for that monitor, the return value + * will depend on whether that window is iconified. * * @param[in] monitor The monitor to query. - * @return The current mode of the monitor, or `NULL` if an error occurred. - * Errors are reported to the [error callback](@ref intro_error). + * @return The current mode of the monitor, or `NULL` if an + * [error](@ref error_handling) occurred. * - * @note This function may only be called from the main thread. + * @par Pointer Lifetime + * The returned array is allocated and freed by GLFW. You should not free it + * yourself. It is valid until the specified monitor is disconnected. * - * @note The returned struct is allocated and freed by GLFW. You should not - * free it yourself. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref monitor_modes * @sa glfwGetVideoModes * + * @par History + * Added in GLFW 3.0. Replaced `glfwGetDesktopMode`. + * * @ingroup monitor */ GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor); @@ -1207,28 +1362,38 @@ GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor); * @param[in] monitor The monitor whose gamma ramp to set. * @param[in] gamma The desired exponent. * - * @remark You cannot generate sRGB gamma using this function, because although - * it is approximately 2.2 it cannot be accurately expressed as a single - * numerical value. + * @par Thread Safety + * This function may only be called from the main thread. * - * @note This function may only be called from the main thread. + * @sa @ref monitor_gamma + * + * @par History + * Added in GLFW 3.0. * * @ingroup monitor */ GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma); -/*! @brief Retrieves the current gamma ramp for the specified monitor. +/*! @brief Returns the current gamma ramp for the specified monitor. * - * This function retrieves the current gamma ramp of the specified monitor. + * This function returns the current gamma ramp of the specified monitor. * * @param[in] monitor The monitor to query. - * @return The current gamma ramp, or `NULL` if an error occurred. Errors are - * reported to the [error callback](@ref intro_error). + * @return The current gamma ramp, or `NULL` if an + * [error](@ref error_handling) occurred. * - * @note This function may only be called from the main thread. + * @par Pointer Lifetime + * The returned structure and its arrays are allocated and freed by GLFW. You + * should not free them yourself. They are valid until the specified monitor + * is disconnected or this function is called again for that monitor. * - * @note The value arrays of the returned ramp are allocated and freed by GLFW. - * You should not free them yourself. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref monitor_gamma + * + * @par History + * Added in GLFW 3.0. * * @ingroup monitor */ @@ -1236,15 +1401,26 @@ GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor); /*! @brief Sets the current gamma ramp for the specified monitor. * - * This function sets the current gamma ramp for the specified monitor. + * This function sets the current gamma ramp for the specified monitor. The + * original gamma ramp for that monitor is saved by GLFW the first time this + * function is called and is restored by @ref glfwTerminate. * * @param[in] monitor The monitor whose gamma ramp to set. * @param[in] ramp The gamma ramp to use. * - * @note This function may only be called from the main thread. - * * @note Gamma ramp sizes other than 256 are not supported by all hardware. * + * @par Pointer Lifetime + * The specified gamma ramp is copied before this function returns. + * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref monitor_gamma + * + * @par History + * Added in GLFW 3.0. + * * @ingroup monitor */ GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp); @@ -1254,10 +1430,15 @@ GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp); * This function resets all window hints to their * [default values](@ref window_hints_values). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_hints * @sa glfwWindowHint * + * @par History + * Added in GLFW 3.0. + * * @ingroup window */ GLFWAPI void glfwDefaultWindowHints(void); @@ -1272,40 +1453,46 @@ GLFWAPI void glfwDefaultWindowHints(void); * @param[in] target The [window hint](@ref window_hints) to set. * @param[in] hint The new value of the window hint. * - * @par New in GLFW 3 - * Hints are no longer reset to their default values on window creation. To - * set default hint values, use @ref glfwDefaultWindowHints. - * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_hints * @sa glfwDefaultWindowHints * + * @par History + * Added in GLFW 2.2. + * + * @par + * **GLFW 3:** Renamed from `glfwOpenWindowHint`. Hints are no longer reset to + * default values on window creation. + * * @ingroup window */ GLFWAPI void glfwWindowHint(int target, int hint); /*! @brief Creates a window and its associated context. * - * This function creates a window and its associated context. Most of the - * options controlling how the window and its context should be created are - * specified through @ref glfwWindowHint. + * This function creates a window and its associated OpenGL or OpenGL ES + * context. Most of the options controlling how the window and its context + * should be created are specified with [window hints](@ref window_hints). * * Successful creation does not change which context is current. Before you - * can use the newly created context, you need to make it current using @ref - * glfwMakeContextCurrent. + * can use the newly created context, you need to + * [make it current](@ref context_current). For information about the `share` + * parameter, see @ref context_sharing. * * The created window, framebuffer and context may differ from what you * requested, as not all parameters and hints are * [hard constraints](@ref window_hints_hard). This includes the size of the - * window, especially for full screen windows. To retrieve the actual - * attributes of the created window, framebuffer and context, use queries like - * @ref glfwGetWindowAttrib and @ref glfwGetWindowSize. + * window, especially for full screen windows. To query the actual attributes + * of the created window, framebuffer and context, use queries like @ref + * glfwGetWindowAttrib and @ref glfwGetWindowSize. * * To create a full screen window, you need to specify the monitor the window * will cover. If no monitor is specified, windowed mode will be used. Unless * you have a way for the user to choose a specific monitor, it is recommended - * that you pick the primary monitor. For more information on how to retrieve - * monitors, see @ref monitor_monitors. + * that you pick the primary monitor. For more information on how to query + * connected monitors, see @ref monitor_monitors. * * By default, newly created windows use the placement recommended by the * window system. To create the window at a specific position, make it @@ -1315,6 +1502,13 @@ GLFWAPI void glfwWindowHint(int target, int hint); * If a full screen window is active, the screensaver is prohibited from * starting. * + * Window systems put limits on window sizes. Very large or very small window + * dimensions may be overridden by the window system on creation. Check the + * actual [window size](@ref window_size) after creation. + * + * The [swap interval](@ref window_swap) is not set during window creation and + * the initial value may vary depending on driver settings and defaults. + * * @param[in] width The desired width, in screen coordinates, of the window. * This must be greater than zero. * @param[in] height The desired height, in screen coordinates, of the window. @@ -1324,12 +1518,8 @@ GLFWAPI void glfwWindowHint(int target, int hint); * windowed mode. * @param[in] share The window whose context to share resources with, or `NULL` * to not share resources. - * @return The handle of the created window, or `NULL` if an error occurred. - * Errors are reported to the [error callback](@ref intro_error). - * - * @remarks The [swap interval](@ref window_swap) is not set during window - * creation and the initial value may vary depending on driver settings and - * defaults. + * @return The handle of the created window, or `NULL` if an + * [error](@ref error_handling) occurred. * * @remarks **Windows:** Window creation will fail if the Microsoft GDI * software OpenGL implementation is the only one available. @@ -1340,22 +1530,34 @@ GLFWAPI void glfwWindowHint(int target, int hint); * * @remarks **OS X:** The GLFW window has no icon, as it is not a document * window, but the dock icon will be the same as the application bundle's icon. - * Also, the first time a window is opened the menu bar is populated with - * common commands like Hide, Quit and About. The (minimal) about dialog uses - * information from the application's bundle. For more information on bundles, - * see the + * For more information on bundles, see the * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) * in the Mac Developer Library. * + * @remarks **OS X:** The first time a window is opened the menu bar is populated with + * common commands like Hide, Quit and About. The About entry opens a minimal + * about dialog with information from the application's bundle. The menu bar can be + * disabled with a [compile-time option](@ref compile_options_osx). + * * @remarks **X11:** There is no mechanism for setting the window icon yet. * * @remarks **X11:** Some window managers will not respect the placement of * initially hidden windows. * - * @note This function may only be called from the main thread. + * @note This function may not be called from a callback. * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_creation * @sa glfwDestroyWindow * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Renamed from `glfwOpenWindow`. Complete signature overhaul. + * * @ingroup window */ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share); @@ -1365,19 +1567,28 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G * This function destroys the specified window and its context. On calling * this function, no further callbacks will be called for that window. * - * @param[in] window The window to destroy. + * If the context of the specified window is current on the main thread, it is + * detached before being destroyed. * - * @note This function may only be called from the main thread. + * @param[in] window The window to destroy. * * @note This function may not be called from a callback. * - * @note If the window's context is current on the main thread, it is - * detached before being destroyed. + * @note The context of the specified window must not be current on any other + * thread when this function is called. * - * @warning The window's context must not be current on any other thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_creation * @sa glfwCreateWindow * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Renamed from `glfwCloseWindow`. Added window handle parameter. + * * @ingroup window */ GLFWAPI void glfwDestroyWindow(GLFWwindow* window); @@ -1389,7 +1600,13 @@ GLFWAPI void glfwDestroyWindow(GLFWwindow* window); * @param[in] window The window to query. * @return The value of the close flag. * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @sa @ref window_close + * + * @par History + * Added in GLFW 3.0. * * @ingroup window */ @@ -1404,7 +1621,13 @@ GLFWAPI int glfwWindowShouldClose(GLFWwindow* window); * @param[in] window The window whose flag to change. * @param[in] value The new value. * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @sa @ref window_close + * + * @par History + * Added in GLFW 3.0. * * @ingroup window */ @@ -1418,7 +1641,16 @@ GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value); * @param[in] window The window whose title to change. * @param[in] title The UTF-8 encoded window title. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_title + * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. * * @ingroup window */ @@ -1429,16 +1661,24 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); * This function retrieves the position, in screen coordinates, of the * upper-left corner of the client area of the specified window. * + * Any or all of the position arguments may be `NULL`. If an error occurs, all + * non-`NULL` position arguments will be set to zero. + * * @param[in] window The window to query. * @param[out] xpos Where to store the x-coordinate of the upper-left corner of * the client area, or `NULL`. * @param[out] ypos Where to store the y-coordinate of the upper-left corner of * the client area, or `NULL`. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_pos * @sa glfwSetWindowPos * + * @par History + * Added in GLFW 3.0. + * * @ingroup window */ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); @@ -1446,13 +1686,8 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); /*! @brief Sets the position of the client area of the specified window. * * This function sets the position, in screen coordinates, of the upper-left - * corner of the client area of the window. - * - * If the specified window is a full screen window, this function does nothing. - * - * If you wish to set an initial window position you should create a hidden - * window (using @ref glfwWindowHint and `GLFW_VISIBLE`), set its position and - * then show it. + * corner of the client area of the specified windowed mode window. If the + * window is a full screen window, this function does nothing. * * @param[in] window The window to query. * @param[in] xpos The x-coordinate of the upper-left corner of the client area. @@ -1461,12 +1696,20 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); * @note It is very rarely a good idea to move an already visible window, as it * will confuse and annoy the user. * - * @note This function may only be called from the main thread. - * * @note The window manager may put limits on what positions are allowed. * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_pos * @sa glfwGetWindowPos * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. + * * @ingroup window */ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); @@ -1477,16 +1720,27 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); * of the specified window. If you wish to retrieve the size of the * framebuffer in pixels, see @ref glfwGetFramebufferSize. * + * Any or all of the size arguments may be `NULL`. If an error occurs, all + * non-`NULL` size arguments will be set to zero. + * * @param[in] window The window whose size to retrieve. * @param[out] width Where to store the width, in screen coordinates, of the * client area, or `NULL`. * @param[out] height Where to store the height, in screen coordinates, of the * client area, or `NULL`. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_size * @sa glfwSetWindowSize * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. + * * @ingroup window */ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); @@ -1505,12 +1759,20 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); * @param[in] width The desired width of the specified window. * @param[in] height The desired height of the specified window. * - * @note This function may only be called from the main thread. - * * @note The window manager may put limits on what window sizes are allowed. * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_size * @sa glfwGetWindowSize * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. + * * @ingroup window */ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); @@ -1521,16 +1783,24 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); * specified window. If you wish to retrieve the size of the window in screen * coordinates, see @ref glfwGetWindowSize. * + * Any or all of the size arguments may be `NULL`. If an error occurs, all + * non-`NULL` size arguments will be set to zero. + * * @param[in] window The window whose framebuffer to query. * @param[out] width Where to store the width, in pixels, of the framebuffer, * or `NULL`. * @param[out] height Where to store the height, in pixels, of the framebuffer, * or `NULL`. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_fbsize * @sa glfwSetFramebufferSizeCallback * + * @par History + * Added in GLFW 3.0. + * * @ingroup window */ GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height); @@ -1542,21 +1812,30 @@ GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height) * window has one. The size of the frame may vary depending on the * [window-related hints](@ref window_hints_wnd) used to create it. * + * Because this function retrieves the size of each window frame edge and not + * the offset along a particular coordinate axis, the retrieved values will + * always be zero or positive. + * + * Any or all of the size arguments may be `NULL`. If an error occurs, all + * non-`NULL` size arguments will be set to zero. + * * @param[in] window The window whose frame size to query. * @param[out] left Where to store the size, in screen coordinates, of the left - * edge of the window frame. + * edge of the window frame, or `NULL`. * @param[out] top Where to store the size, in screen coordinates, of the top - * edge of the window frame. + * edge of the window frame, or `NULL`. * @param[out] right Where to store the size, in screen coordinates, of the - * right edge of the window frame. + * right edge of the window frame, or `NULL`. * @param[out] bottom Where to store the size, in screen coordinates, of the - * bottom edge of the window frame. + * bottom edge of the window frame, or `NULL`. * - * @remarks This function retrieves the size of each window frame edge, not the - * offset along a screen coordinate axis, so the retrieved values will always - * be zero or positive. + * @par Thread Safety + * This function may only be called from the main thread. * - * @note This function may only be called from the main thread. + * @sa @ref window_size + * + * @par History + * Added in GLFW 3.1. * * @ingroup window */ @@ -1564,66 +1843,95 @@ GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int /*! @brief Iconifies the specified window. * - * This function iconifies/minimizes the specified window, if it was previously - * restored. If it is a full screen window, the original monitor resolution is - * restored until the window is restored. If the window is already iconified, - * this function does nothing. + * This function iconifies (minimizes) the specified window if it was + * previously restored. If the window is already iconified, this function does + * nothing. + * + * If the specified window is a full screen window, the original monitor + * resolution is restored until the window is restored. * * @param[in] window The window to iconify. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_iconify * @sa glfwRestoreWindow * + * @par History + * Added in GLFW 2.1. + * + * @par + * **GLFW 3:** Added window handle parameter. + * * @ingroup window */ GLFWAPI void glfwIconifyWindow(GLFWwindow* window); /*! @brief Restores the specified window. * - * This function restores the specified window, if it was previously - * iconified/minimized. If it is a full screen window, the resolution chosen - * for the window is restored on the selected monitor. If the window is - * already restored, this function does nothing. + * This function restores the specified window if it was previously iconified + * (minimized). If the window is already restored, this function does nothing. + * + * If the specified window is a full screen window, the resolution chosen for + * the window is restored on the selected monitor. * * @param[in] window The window to restore. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_iconify * @sa glfwIconifyWindow * + * @par History + * Added in GLFW 2.1. + * + * @par + * **GLFW 3:** Added window handle parameter. + * * @ingroup window */ GLFWAPI void glfwRestoreWindow(GLFWwindow* window); /*! @brief Makes the specified window visible. * - * This function makes the specified window visible, if it was previously + * This function makes the specified window visible if it was previously * hidden. If the window is already visible or is in full screen mode, this * function does nothing. * * @param[in] window The window to make visible. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_hide * @sa glfwHideWindow * + * @par History + * Added in GLFW 3.0. + * * @ingroup window */ GLFWAPI void glfwShowWindow(GLFWwindow* window); /*! @brief Hides the specified window. * - * This function hides the specified window, if it was previously visible. If + * This function hides the specified window if it was previously visible. If * the window is already hidden or is in full screen mode, this function does * nothing. * * @param[in] window The window to hide. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref window_hide * @sa glfwShowWindow * + * @par History + * Added in GLFW 3.0. + * * @ingroup window */ GLFWAPI void glfwHideWindow(GLFWwindow* window); @@ -1634,9 +1942,16 @@ GLFWAPI void glfwHideWindow(GLFWwindow* window); * in full screen on. * * @param[in] window The window to query. - * @return The monitor, or `NULL` if the window is in windowed mode. + * @return The monitor, or `NULL` if the window is in windowed mode or an error + * occurred. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_monitor + * + * @par History + * Added in GLFW 3.0. * * @ingroup window */ @@ -1644,16 +1959,26 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); /*! @brief Returns an attribute of the specified window. * - * This function returns an attribute of the specified window. There are many - * attributes, some related to the window and others to its context. + * This function returns the value of an attribute of the specified window or + * its OpenGL or OpenGL ES context. * * @param[in] window The window to query. * @param[in] attrib The [window attribute](@ref window_attribs) whose value to * return. - * @return The value of the attribute, or zero if an error occurred. Errors - * are reported to the [error callback](@ref intro_error). + * @return The value of the attribute, or zero if an + * [error](@ref error_handling) occurred. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_attribs + * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Renamed from `glfwGetWindowParam`. Added window handle + * parameter. * * @ingroup window */ @@ -1668,10 +1993,15 @@ GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib); * @param[in] window The window whose pointer to set. * @param[in] pointer The new value. * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. * + * @sa @ref window_userptr * @sa glfwGetWindowUserPointer * + * @par History + * Added in GLFW 3.0. + * * @ingroup window */ GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer); @@ -1683,10 +2013,15 @@ GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer); * * @param[in] window The window whose pointer to return. * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. * + * @sa @ref window_userptr * @sa glfwSetWindowUserPointer * + * @par History + * Added in GLFW 3.0. + * * @ingroup window */ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); @@ -1703,7 +2038,16 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_pos + * + * @par History + * Added in GLFW 3.0. + * + * @par + * **GLFW 3:** Added window handle parameter. Updated callback signature. * * @ingroup window */ @@ -1721,7 +2065,16 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_size + * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. Updated callback signature. * * @ingroup window */ @@ -1744,13 +2097,19 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @par New in GLFW 3 - * The close callback no longer returns a value. - * * @remarks **OS X:** Selecting Quit from the application menu will * trigger the close callback for all windows. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_close + * + * @par History + * Added in GLFW 2.5. + * + * @par + * **GLFW 3:** Added window handle parameter. Updated callback signature. * * @ingroup window */ @@ -1772,11 +2131,16 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * - * @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. + * @sa @ref window_refresh + * + * @par History + * Added in GLFW 2.5. + * + * @par + * **GLFW 3:** Added window handle parameter. Updated callback signature. * * @ingroup window */ @@ -1798,7 +2162,13 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_focus + * + * @par History + * Added in GLFW 3.0. * * @ingroup window */ @@ -1815,7 +2185,13 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_iconify + * + * @par History + * Added in GLFW 3.0. * * @ingroup window */ @@ -1832,7 +2208,13 @@ GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GL * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref window_fbsize + * + * @par History + * Added in GLFW 3.0. * * @ingroup window */ @@ -1840,85 +2222,101 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window /*! @brief Processes all pending events. * - * This function processes only those events that have already been received - * and then returns immediately. Processing events will cause the window and - * input callbacks associated with those events to be called. + * This function processes only those events that are already in the event + * queue and then returns immediately. Processing events will cause the window + * and input callbacks associated with those events to be called. * - * This function is not required for joystick input to work. + * On some platforms, a window move, resize or menu operation will cause event + * processing to block. This is due to how event processing is designed on + * those platforms. You can use the + * [window refresh callback](@ref window_refresh) to redraw the contents of + * your window when necessary during such operations. * - * @par New in GLFW 3 - * This function is no longer called by @ref glfwSwapBuffers. You need to call - * it or @ref glfwWaitEvents yourself. + * On some platforms, certain events are sent directly to the application + * without going through the event queue, causing callbacks to be called + * outside of a call to one of the event processing functions. * - * @remarks On some platforms, a window move, resize or menu operation will - * cause event processing to block. This is due to how event processing is - * designed on those platforms. You can use the - * [window refresh callback](@ref GLFWwindowrefreshfun) to redraw the contents - * of your window when necessary during the operation. - * - * @note This function may only be called from the main thread. + * Event processing is not required for joystick input to work. * * @note This function may not be called from a callback. * - * @note On some platforms, certain callbacks may be called outside of a call - * to one of the event processing functions. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref input_event * @sa glfwWaitEvents * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** This function is no longer called by @ref glfwSwapBuffers. + * * @ingroup window */ GLFWAPI void glfwPollEvents(void); -/*! @brief Waits until events are pending and processes them. +/*! @brief Waits until events are queued and processes them. * - * This function puts the calling thread to sleep until at least one event has - * been received. Once one or more events have been received, it behaves as if - * @ref glfwPollEvents was called, i.e. the events are processed and the - * function then returns immediately. Processing events will cause the window - * and input callbacks associated with those events to be called. + * This function puts the calling thread to sleep until at least one event is + * available in the event queue. Once one or more events are available, + * it behaves exactly like @ref glfwPollEvents, i.e. the events in the queue + * are processed and the function then returns immediately. Processing events + * will cause the window and input callbacks associated with those events to be + * called. * * Since not all events are associated with callbacks, this function may return * without a callback having been called even if you are monitoring all * callbacks. * - * This function is not required for joystick input to work. + * On some platforms, a window move, resize or menu operation will cause event + * processing to block. This is due to how event processing is designed on + * those platforms. You can use the + * [window refresh callback](@ref window_refresh) to redraw the contents of + * your window when necessary during such operations. * - * @remarks On some platforms, a window move, resize or menu operation will - * cause event processing to block. This is due to how event processing is - * designed on those platforms. You can use the - * [window refresh callback](@ref GLFWwindowrefreshfun) to redraw the contents - * of your window when necessary during the operation. + * If no windows exist, this function returns immediately. For synchronization + * of threads in applications that do not create windows, use your threading + * library of choice. * - * @remarks If no windows exist, this function returns immediately. For - * synchronization of threads in applications that do not create windows, use - * your threading library of choice. - * - * @note This function may only be called from the main thread. + * Event processing is not required for joystick input to work. * * @note This function may not be called from a callback. * * @note On some platforms, certain callbacks may be called outside of a call * to one of the event processing functions. * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_event * @sa glfwPollEvents * + * @par History + * Added in GLFW 2.5. + * * @ingroup window */ GLFWAPI void glfwWaitEvents(void); /*! @brief Posts an empty event to the event queue. * - * This function posts an empty event from the current thread to the main - * thread event queue, causing @ref glfwWaitEvents to return. + * This function posts an empty event from the current thread to the event + * queue, causing @ref glfwWaitEvents to return. * - * @remarks If no windows exist, this function returns immediately. For - * synchronization of threads in applications that do not create windows, use - * your threading library of choice. + * If no windows exist, this function returns immediately. For synchronization + * of threads in applications that do not create windows, use your threading + * library of choice. * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. * + * @sa @ref input_event * @sa glfwWaitEvents * + * @par History + * Added in GLFW 3.1. + * * @ingroup window */ GLFWAPI void glfwPostEmptyEvent(void); @@ -1929,10 +2327,14 @@ GLFWAPI void glfwPostEmptyEvent(void); * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or * `GLFW_STICKY_MOUSE_BUTTONS`. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * * @sa glfwSetInputMode * + * @par History + * Added in GLFW 3.0. + * * @ingroup input */ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); @@ -1943,7 +2345,7 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); * `GLFW_STICKY_MOUSE_BUTTONS`. * @param[in] value The new value of the specified input mode. * - * If `mode` is `GLFW_CURSOR`, the value must be one of the supported input + * If the mode is `GLFW_CURSOR`, the value must be one of the following cursor * modes: * - `GLFW_CURSOR_NORMAL` makes the cursor visible and behaving normally. * - `GLFW_CURSOR_HIDDEN` makes the cursor invisible when it is over the client @@ -1954,25 +2356,29 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); * and unlimited cursor movement. This is useful for implementing for * example 3D camera controls. * - * If `mode` is `GLFW_STICKY_KEYS`, the value must be either `GL_TRUE` to + * If the mode is `GLFW_STICKY_KEYS`, the value must be either `GL_TRUE` to * enable sticky keys, or `GL_FALSE` to disable it. If sticky keys are * enabled, a key press will ensure that @ref glfwGetKey returns @ref * GLFW_PRESS the next time it is called even if the key had been released * before the call. This is useful when you are only interested in whether * keys have been pressed but not when or in which order. * - * If `mode` is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either `GL_TRUE` - * to enable sticky mouse buttons, or `GL_FALSE` to disable it. If sticky - * mouse buttons are enabled, a mouse button press will ensure that @ref + * If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either + * `GL_TRUE` to enable sticky mouse buttons, or `GL_FALSE` to disable it. If + * sticky mouse buttons are enabled, a mouse button press will ensure that @ref * glfwGetMouseButton returns @ref GLFW_PRESS the next time it is called even * if the mouse button had been released before the call. This is useful when * you are only interested in whether mouse buttons have been pressed but not * when or in which order. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * * @sa glfwGetInputMode * + * @par History + * Added in GLFW 3.0. Replaced `glfwEnable` and `glfwDisable`. + * * @ingroup input */ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); @@ -1982,12 +2388,12 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); * * This function returns the last state reported for the specified key to the * specified window. The returned state is one of `GLFW_PRESS` or - * `GLFW_RELEASE`. The higher-level state `GLFW_REPEAT` is only reported to + * `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to * the key callback. * * If the `GLFW_STICKY_KEYS` input mode is enabled, this function returns - * `GLFW_PRESS` the first time you call this function after a key has been - * pressed, even if the key has already been released. + * `GLFW_PRESS` the first time you call it for a key that was pressed, even if + * that key has already been released. * * The key functions deal with physical keys, with [key tokens](@ref keys) * named after their use on the standard US keyboard layout. If you want to @@ -1997,12 +2403,20 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); * used with this function. * * @param[in] window The desired window. - * @param[in] key The desired [keyboard key](@ref keys). + * @param[in] key The desired [keyboard key](@ref keys). `GLFW_KEY_UNKNOWN` is + * not a valid key for this function. * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * - * @note `GLFW_KEY_UNKNOWN` is not a valid key for this function. + * @sa @ref input_key + * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. * * @ingroup input */ @@ -2012,17 +2426,28 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key); * window. * * This function returns the last state reported for the specified mouse button - * to the specified window. + * to the specified window. The returned state is one of `GLFW_PRESS` or + * `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to + * the mouse button callback. * * If the `GLFW_STICKY_MOUSE_BUTTONS` input mode is enabled, this function - * returns `GLFW_PRESS` the first time you call this function after a mouse - * button has been pressed, even if the mouse button has already been released. + * `GLFW_PRESS` the first time you call it for a mouse button that was pressed, + * even if that mouse button has already been released. * * @param[in] window The desired window. * @param[in] button The desired [mouse button](@ref buttons). * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_mouse_button + * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. * * @ingroup input */ @@ -2043,16 +2468,28 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); * `floor` function. Casting directly to an integer type works for positive * coordinates, but fails for negative ones. * + * Any or all of the position arguments may be `NULL`. If an error occurs, all + * non-`NULL` position arguments will be set to zero. + * * @param[in] window The desired window. * @param[out] xpos Where to store the cursor x-coordinate, relative to the * left edge of the client area, or `NULL`. * @param[out] ypos Where to store the cursor y-coordinate, relative to the to * top edge of the client area, or `NULL`. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref input_cursor_pos * @sa glfwSetCursorPos * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Renamed from `glfwGetMousePos`. Added window handle parameter. + * Moved to floating-point coordinates. + * * @ingroup input */ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); @@ -2079,10 +2516,19 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); * may take a moment for the window focus event to arrive. This means you will * not be able to set the cursor position directly after window creation. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * + * @sa @ref input_cursor_pos * @sa glfwGetCursorPos * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Renamed from `glfwSetMousePos`. Added window handle parameter. + * Moved to floating-point coordinates. + * * @ingroup input */ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); @@ -2094,16 +2540,29 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); * glfwDestroyCursor. Any remaining cursors are destroyed by @ref * glfwTerminate. * - * The specified image is in 32-bit RGBA format, so eight bits per channel. + * 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. * * @param[in] image The desired cursor image. * @param[in] xhot The desired x-coordinate of the cursor hotspot. * @param[in] yhot The desired y-coordinate of the cursor hotspot. * - * @return A new cursor ready to use or `NULL` if an error occurred. Errors - * are reported to the [error callback](@ref intro_error). + * @return A new cursor ready to use or `NULL` if an + * [error](@ref error_handling) occurred. * - * @note This function may only be called from the main thread. + * @note This function may not be called from a callback. + * + * @par Pointer Lifetime + * The specified image data is copied before this function returns. + * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_cursor + * @sa glfwDestroyCursor + * + * @par History + * Added in GLFW 3.1. * * @ingroup input */ @@ -2117,19 +2576,36 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot) * * @param[in] cursor The cursor object to destroy. * - * @note This function may only be called from the main thread. + * @note This function may not be called from a callback. + * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_cursor + * @sa glfwCreateCursor + * + * @par History + * Added in GLFW 3.1. * * @ingroup input */ GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor); /*! @brief Sets the system cursor for a given window. + * + * This function sets the system cursor for the specified window. * * @param[in] window The window to set the system cursor for. * @param[in] cursor The cursor to change to, or `NULL` to switch back * to the default system cursor. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_cursor + * + * @par History + * Added in GLFW 3.1. * * @ingroup input */ @@ -2137,7 +2613,7 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); /*! @brief Sets the key callback. * - * This function sets the key callback of the specific window, which is called + * This function sets the key callback of the specified window, which is called * when a key is pressed, repeated or released. * * The key functions deal with physical keys, with layout independent @@ -2154,7 +2630,7 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); * The scancode of a key is specific to that platform or sometimes even to that * machine. Scancodes are intended to allow users to bind keys that don't have * a GLFW key token. Such keys have `key` set to `GLFW_KEY_UNKNOWN`, their - * state is not saved and so it cannot be retrieved with @ref glfwGetKey. + * state is not saved and so it cannot be queried with @ref glfwGetKey. * * Sometimes GLFW needs to generate synthetic key events, in which case the * scancode may be zero. @@ -2165,7 +2641,16 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_key + * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. Updated callback signature. * * @ingroup input */ @@ -2173,7 +2658,7 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun); /*! @brief Sets the Unicode character callback. * - * This function sets the character callback of the specific window, which is + * This function sets the character callback of the specified window, which is * called when a Unicode character is input. * * The character callback is intended for Unicode text input. As it deals with @@ -2196,7 +2681,16 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun); * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_char + * + * @par History + * Added in GLFW 2.4. + * + * @par + * **GLFW 3:** Added window handle parameter. Updated callback signature. * * @ingroup input */ @@ -2204,7 +2698,7 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun); /*! @brief Sets the Unicode character with modifiers callback. * - * This function sets the character with modifiers callback of the specific + * This function sets the character with modifiers callback of the specified * window, which is called when a Unicode character is input regardless of what * modifier keys are used. * @@ -2223,7 +2717,13 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun); * @return The previously set callback, or `NULL` if no callback was set or an * error occurred. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_char + * + * @par History + * Added in GLFW 3.1. * * @ingroup input */ @@ -2246,7 +2746,16 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_mouse_button + * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. Updated callback signature. * * @ingroup input */ @@ -2265,7 +2774,17 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_cursor_pos + * + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Renamed from `glfwSetMousePosCallback`. Added window handle + * parameter. Updated callback signature. * * @ingroup input */ @@ -2283,7 +2802,13 @@ GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursor * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_cursor_enter + * + * @par History + * Added in GLFW 3.0. * * @ingroup input */ @@ -2304,7 +2829,17 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_scroll + * + * @par History + * Added in GLFW 2.1. + * + * @par + * **GLFW 3:** Renamed from `glfwSetMouseWheelCallback`. Added window handle. + * Updated callback signature. * * @ingroup input */ @@ -2315,6 +2850,10 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb * This function sets the file drop callback of the specified window, which is * called when one or more dragged files are dropped on the window. * + * Because the path array and its strings may have been generated specifically + * for that event, they are not guaranteed to be valid after the callback has + * returned. If you wish to use them after the callback returns, you need to + * make a deep copy. * * @param[in] window The window whose callback to set. * @param[in] cbfun The new file drop callback, or `NULL` to remove the @@ -2322,7 +2861,13 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_drop + * + * @par History + * Added in GLFW 3.1. * * @ingroup input */ @@ -2332,10 +2877,16 @@ GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun); * * This function returns whether the specified joystick is present. * - * @param[in] joy The joystick to query. + * @param[in] joy The [joystick](@ref joysticks) to query. * @return `GL_TRUE` if the joystick is present, or `GL_FALSE` otherwise. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_joy + * + * @par History + * Added in GLFW 3.0. Replaced `glfwGetJoystickParam`. * * @ingroup input */ @@ -2344,19 +2895,29 @@ GLFWAPI int glfwJoystickPresent(int joy); /*! @brief Returns the values of all axes of the specified joystick. * * This function returns the values of all axes of the specified joystick. + * Each element in the array is a value between -1.0 and 1.0. * - * @param[in] joy The joystick to query. - * @param[out] count Where to store the size of the returned array. This is - * set to zero if an error occurred. + * @param[in] joy The [joystick](@ref joysticks) to query. + * @param[out] count Where to store the number of axis values in the returned + * array. This is set to zero if an error occurred. * @return An array of axis values, or `NULL` if the joystick is not present. * - * @note This function may only be called from the main thread. + * @par Pointer Lifetime + * The returned array is allocated and freed by GLFW. You should not free it + * yourself. It is valid until the specified joystick is disconnected or this + * function is called again for that joystick. * - * @note The returned array is allocated and freed by GLFW. You should not - * free it yourself. + * @par Thread Safety + * This function may only be called from the main thread. * - * @note The returned array is valid only until the next call to @ref - * glfwGetJoystickAxes for that joystick. + * @sa @ref input_joy_axis + * + * @par History + * Added in GLFW 2.2. + * + * @par + * **GLFW 3:** Renamed from `glfwGetJoystickPos`. Changed to return a dynamic + * array. * * @ingroup input */ @@ -2365,19 +2926,28 @@ GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count); /*! @brief Returns the state of all buttons of the specified joystick. * * This function returns the state of all buttons of the specified joystick. + * Each element in the array is either `GLFW_PRESS` or `GLFW_RELEASE`. * - * @param[in] joy The joystick to query. - * @param[out] count Where to store the size of the returned array. This is - * set to zero if an error occurred. + * @param[in] joy The [joystick](@ref joysticks) to query. + * @param[out] count Where to store the number of button states in the returned + * array. This is set to zero if an error occurred. * @return An array of button states, or `NULL` if the joystick is not present. * - * @note This function may only be called from the main thread. + * @par Pointer Lifetime + * The returned array is allocated and freed by GLFW. You should not free it + * yourself. It is valid until the specified joystick is disconnected or this + * function is called again for that joystick. * - * @note The returned array is allocated and freed by GLFW. You should not - * free it yourself. + * @par Thread Safety + * This function may only be called from the main thread. * - * @note The returned array is valid only until the next call to @ref - * glfwGetJoystickButtons for that joystick. + * @sa @ref input_joy_button + * + * @par History + * Added in GLFW 2.2. + * + * @par + * **GLFW 3:** Changed to return a dynamic array. * * @ingroup input */ @@ -2386,18 +2956,25 @@ GLFWAPI const unsigned char* glfwGetJoystickButtons(int joy, int* count); /*! @brief Returns the name of the specified joystick. * * This function returns the name, encoded as UTF-8, of the specified joystick. + * The returned string is allocated and freed by GLFW. You should not free it + * yourself. * - * @param[in] joy The joystick to query. + * @param[in] joy The [joystick](@ref joysticks) to query. * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick * is not present. * - * @note This function may only be called from the main thread. + * @par Pointer Lifetime + * The returned string is allocated and freed by GLFW. You should not free it + * yourself. It is valid until the specified joystick is disconnected or this + * function is called again for that joystick. * - * @note The returned string is allocated and freed by GLFW. You should not - * free it yourself. + * @par Thread Safety + * This function may only be called from the main thread. * - * @note The returned string is valid only until the next call to @ref - * glfwGetJoystickName for that joystick. + * @sa @ref input_joy_name + * + * @par History + * Added in GLFW 3.0. * * @ingroup input */ @@ -2406,40 +2983,50 @@ GLFWAPI const char* glfwGetJoystickName(int joy); /*! @brief Sets the clipboard to the specified string. * * This function sets the system clipboard to the specified, UTF-8 encoded - * string. The string is copied before returning, so you don't have to retain - * it afterwards. + * string. * * @param[in] window The window that will own the clipboard contents. * @param[in] string A UTF-8 encoded string. * - * @note This function may only be called from the main thread. + * @par Pointer Lifetime + * The specified string is copied before this function returns. * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_clipboard * @sa glfwGetClipboardString * + * @par History + * Added in GLFW 3.0. + * * @ingroup input */ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); -/*! @brief Retrieves the contents of the clipboard as a string. +/*! @brief Returns the contents of the clipboard as a string. * * This function returns the contents of the system clipboard, if it contains * or is convertible to a UTF-8 encoded string. * * @param[in] window The window that will request the clipboard contents. * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL` - * if an error occurred. Errors are reported to the - * [error callback](@ref intro_error). + * if an [error](@ref error_handling) occurred. * - * @note This function may only be called from the main thread. - * - * @note The returned string is allocated and freed by GLFW. You should not - * free it yourself. - * - * @note The returned string is valid only until the next call to @ref + * @par Pointer Lifetime + * The returned string is allocated and freed by GLFW. You should not free it + * yourself. It is valid until the next call to @ref * glfwGetClipboardString or @ref glfwSetClipboardString. * + * @par Thread Safety + * This function may only be called from the main thread. + * + * @sa @ref input_clipboard * @sa glfwSetClipboardString * + * @par History + * Added in GLFW 3.0. + * * @ingroup input */ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); @@ -2450,16 +3037,22 @@ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); * been set using @ref glfwSetTime, the timer measures time elapsed since GLFW * was initialized. * - * @return The current value, in seconds, or zero if an error occurred. Errors - * are reported to the [error callback](@ref intro_error). + * The resolution of the timer is system dependent, but is usually on the order + * of a few micro- or nanoseconds. It uses the highest-resolution monotonic + * time source on each supported platform. * - * @remarks This function may be called from any thread. + * @return The current value, in seconds, or zero if an + * [error](@ref error_handling) occurred. * - * @note The resolution of the timer is system dependent, but is usually on the - * order of a few micro- or nanoseconds. It uses the highest-resolution - * monotonic time source on each supported platform. + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. * - * @ingroup time + * @sa @ref input_time + * + * @par History + * Added in GLFW 1.0. + * + * @ingroup input */ GLFWAPI double glfwGetTime(void); @@ -2470,46 +3063,64 @@ GLFWAPI double glfwGetTime(void); * * @param[in] time The new value, in seconds. * - * @note This function may only be called from the main thread. + * @par Thread Safety + * This function may only be called from the main thread. * - * @note The resolution of the timer is system dependent, but is usually on the - * order of a few micro- or nanoseconds. It uses the highest-resolution - * monotonic time source on each supported platform. + * @sa @ref input_time * - * @ingroup time + * @par History + * Added in GLFW 2.2. + * + * @ingroup input */ GLFWAPI void glfwSetTime(double time); /*! @brief Makes the context of the specified window current for the calling * thread. * - * This function makes the context of the specified window current on the - * calling thread. A context can only be made current on a single thread at - * a time and each thread can have only a single current context at a time. + * This function makes the OpenGL or OpenGL ES context of the specified window + * current on the calling thread. A context can only be made current on + * a single thread at a time and each thread can have only a single current + * context at a time. + * + * By default, making a context non-current implicitly forces a pipeline flush. + * On machines that support `GL_KHR_context_flush_control`, you can control + * whether a context performs this flush by setting the + * `GLFW_CONTEXT_RELEASE_BEHAVIOR` [window hint](@ref window_hints_ctx). * * @param[in] window The window whose context to make current, or `NULL` to * detach the current context. * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. * + * @sa @ref context_current * @sa glfwGetCurrentContext * + * @par History + * Added in GLFW 3.0. + * * @ingroup context */ GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window); /*! @brief Returns the window whose context is current on the calling thread. * - * This function returns the window whose context is current on the calling - * thread. + * This function returns the window whose OpenGL or OpenGL ES context is + * current on the calling thread. * * @return The window whose context is current, or `NULL` if no window's * context is current. * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. * + * @sa @ref context_current * @sa glfwMakeContextCurrent * + * @par History + * Added in GLFW 3.0. + * * @ingroup context */ GLFWAPI GLFWwindow* glfwGetCurrentContext(void); @@ -2522,24 +3133,29 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void); * * @param[in] window The window whose buffers to swap. * - * @par New in GLFW 3 - * This function no longer calls @ref glfwPollEvents. You need to call it or - * @ref glfwWaitEvents yourself. - * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. * + * @sa @ref window_swap * @sa glfwSwapInterval * - * @ingroup context + * @par History + * Added in GLFW 1.0. + * + * @par + * **GLFW 3:** Added window handle parameter. Removed call to @ref + * glfwPollEvents. + * + * @ingroup window */ GLFWAPI void glfwSwapBuffers(GLFWwindow* window); /*! @brief Sets the swap interval for the current context. * * This function sets the swap interval for the current context, i.e. the - * number of screen updates to wait before swapping the buffers of a window and - * returning from @ref glfwSwapBuffers. This is sometimes called 'vertical - * synchronization', 'vertical retrace synchronization' or 'vsync'. + * number of screen updates to wait from the time @ref glfwSwapBuffers was + * called before swapping the buffers and returning. This is sometimes called + * 'vertical synchronization', 'vertical retrace synchronization' or 'vsync'. * * Contexts that support either of the `WGL_EXT_swap_control_tear` and * `GLX_EXT_swap_control_tear` extensions also accept negative swap intervals, @@ -2548,11 +3164,12 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window); * glfwExtensionSupported. For more information about swap tearing, see the * extension specifications. * + * A context must be current on the calling thread. Calling this function + * without a current context will cause a `GLFW_NO_CURRENT_CONTEXT` error. + * * @param[in] interval The minimum number of screen updates to wait for * until the buffers are swapped by @ref glfwSwapBuffers. * - * @remarks This function may be called from any thread. - * * @note This function is not called during window creation, leaving the swap * interval set to whatever is the default on that platform. This is done * because some swap interval extensions used by GLFW do not allow the swap @@ -2562,8 +3179,15 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window); * because of user settings that override the request or due to bugs in the * driver. * + * @par Thread Safety + * This function may be called from any thread. + * + * @sa @ref window_swap * @sa glfwSwapBuffers * + * @par History + * Added in GLFW 1.0. + * * @ingroup context */ GLFWAPI void glfwSwapInterval(int interval); @@ -2571,19 +3195,29 @@ GLFWAPI void glfwSwapInterval(int interval); /*! @brief Returns whether the specified extension is available. * * This function returns whether the specified - * [OpenGL or context creation API extension](@ref context_glext) is supported - * by the current context. For example, on Windows both the OpenGL and WGL - * extension strings are checked. + * [API extension](@ref context_glext) is supported by the current OpenGL or + * OpenGL ES context. It searches both for OpenGL and OpenGL ES extension and + * platform-specific context creation API extensions. + * + * A context must be current on the calling thread. Calling this function + * without a current context will cause a `GLFW_NO_CURRENT_CONTEXT` error. + * + * As this functions retrieves and searches one or more extension strings each + * call, it is recommended that you cache its results if it is going to be used + * frequently. The extension strings will not change during the lifetime of + * a context, so there is no danger in doing this. * * @param[in] extension The ASCII encoded name of the extension. * @return `GL_TRUE` if the extension is available, or `GL_FALSE` otherwise. * - * @remarks This function may be called from any thread. + * @par Thread Safety + * This function may be called from any thread. * - * @note As this functions searches one or more extension strings on each call, - * it is recommended that you cache its results if it's going to be used - * frequently. The extension strings will not change during the lifetime of - * a context, so there is no danger in doing this. + * @sa @ref context_glext + * @sa glfwGetProcAddress + * + * @par History + * Added in GLFW 1.0. * * @ingroup context */ @@ -2596,15 +3230,27 @@ GLFWAPI int glfwExtensionSupported(const char* extension); * [client API or extension function](@ref context_glext), if it is supported * by the current context. * + * A context must be current on the calling thread. Calling this function + * without a current context will cause a `GLFW_NO_CURRENT_CONTEXT` error. + * * @param[in] procname The ASCII encoded name of the function. * @return The address of the function, or `NULL` if the function is - * unavailable. + * unavailable or an [error](@ref error_handling) occurred. * - * @remarks This function may be called from any thread. + * @note The addresses of a given function is not guaranteed to be the same + * between contexts. * - * @note The addresses of these functions are not guaranteed to be the same for - * all contexts, especially if they use different client APIs or even different - * context creation hints. + * @par Pointer Lifetime + * The returned function pointer is valid until the context is destroyed. + * + * @par Thread Safety + * This function may be called from any thread. + * + * @sa @ref context_glext + * @sa glfwExtensionSupported + * + * @par History + * Added in GLFW 1.0. * * @ingroup context */ diff --git a/include/GLFW/glfw3native.h b/include/GLFW/glfw3native.h index 0d904067..c00d57c7 100644 --- a/include/GLFW/glfw3native.h +++ b/include/GLFW/glfw3native.h @@ -45,8 +45,8 @@ extern "C" { * using it.** * * Before the inclusion of @ref glfw3native.h, you must define exactly one - * window API macro and exactly one context API macro. Failure to do this - * will cause a compile-time error. + * window system API macro and exactly one context creation API macro. Failure + * to do this will cause a compile-time error. * * The available window API macros are: * * `GLFW_EXPOSE_NATIVE_WIN32` @@ -109,13 +109,32 @@ extern "C" { #if defined(GLFW_EXPOSE_NATIVE_WIN32) /*! @brief Returns the display device name of the specified monitor. - * @return The display device name of the specified monitor. + * + * @return The UTF-8 encoded display device name (`DISPLAY_DEVICE.DeviceName`) + * of the specified monitor, or `NULL` if an [error](@ref error_handling) + * occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.1. + * * @ingroup native */ GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor); /*! @brief Returns the `HWND` of the specified window. - * @return The `HWND` of the specified window. + * + * @return The `HWND` of the specified window, or `NULL` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window); @@ -123,7 +142,16 @@ GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window); #if defined(GLFW_EXPOSE_NATIVE_WGL) /*! @brief Returns the `HGLRC` of the specified window. - * @return The `HGLRC` of the specified window. + * + * @return The `HGLRC` of the specified window, or `NULL` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window); @@ -131,13 +159,31 @@ GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window); #if defined(GLFW_EXPOSE_NATIVE_COCOA) /*! @brief Returns the `CGDirectDisplayID` of the specified monitor. - * @return The `CGDirectDisplayID` of the specified monitor. + * + * @return The `CGDirectDisplayID` of the specified monitor, or + * `kCGNullDirectDisplay` if an [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.1. + * * @ingroup native */ GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor); /*! @brief Returns the `NSWindow` of the specified window. - * @return The `NSWindow` of the specified window. + * + * @return The `NSWindow` of the specified window, or `nil` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window); @@ -145,7 +191,16 @@ GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window); #if defined(GLFW_EXPOSE_NATIVE_NSGL) /*! @brief Returns the `NSOpenGLContext` of the specified window. - * @return The `NSOpenGLContext` of the specified window. + * + * @return The `NSOpenGLContext` of the specified window, or `nil` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI id glfwGetNSGLContext(GLFWwindow* window); @@ -153,19 +208,46 @@ GLFWAPI id glfwGetNSGLContext(GLFWwindow* window); #if defined(GLFW_EXPOSE_NATIVE_X11) /*! @brief Returns the `Display` used by GLFW. - * @return The `Display` used by GLFW. + * + * @return The `Display` used by GLFW, or `NULL` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI Display* glfwGetX11Display(void); /*! @brief Returns the `RROutput` of the specified monitor. - * @return The `RROutput` of the specified monitor. + * + * @return The `RROutput` of the specified monitor, or `None` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.1. + * * @ingroup native */ GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor); /*! @brief Returns the `Window` of the specified window. - * @return The `Window` of the specified window. + * + * @return The `Window` of the specified window, or `None` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI Window glfwGetX11Window(GLFWwindow* window); @@ -173,7 +255,16 @@ GLFWAPI Window glfwGetX11Window(GLFWwindow* window); #if defined(GLFW_EXPOSE_NATIVE_GLX) /*! @brief Returns the `GLXContext` of the specified window. - * @return The `GLXContext` of the specified window. + * + * @return The `GLXContext` of the specified window, or `NULL` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window); @@ -181,19 +272,46 @@ GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window); #if defined(GLFW_EXPOSE_NATIVE_EGL) /*! @brief Returns the `EGLDisplay` used by GLFW. - * @return The `EGLDisplay` used by GLFW. + * + * @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI EGLDisplay glfwGetEGLDisplay(void); /*! @brief Returns the `EGLContext` of the specified window. - * @return The `EGLContext` of the specified window. + * + * @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window); /*! @brief Returns the `EGLSurface` of the specified window. - * @return The `EGLSurface` of the specified window. + * + * @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an + * [error](@ref error_handling) occurred. + * + * @par Thread Safety + * This function may be called from any thread. Access is not synchronized. + * + * @par History + * Added in GLFW 3.0. + * * @ingroup native */ GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);