AuroraMiddleware/glfw
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Documentation work.

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

4
docs/Doxyfile.in
View File

@ -666,6 +666,8 @@ INPUT = @GLFW_INTERNAL_DOCS@ \
@GLFW_SOURCE_DIR@/docs/monitor.dox \
@GLFW_SOURCE_DIR@/docs/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

92
docs/build.dox
View File

@ -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 <GLFW/glfw3.h>
@ -30,13 +30,14 @@ types and function prototypes of the OpenGL API.
The GLFW header also defines everything necessary for your OpenGL header to
function. For example, under Windows you are normally required to include
`windows.h` before the OpenGL header. This would make your source file tied
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

18
docs/common.dox Normal file
View File

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

22
docs/compat.dox
View File

@ -4,19 +4,20 @@
@tableofcontents
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

125
docs/compile.dox
View File

@ -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=<toolchain-file> .
@code{.sh}
cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
@endcode
The exact toolchain file to use depends on the prefix used by the MinGW or
MinGW-w64 binaries on your system. You can usually see this in the /usr
@ -53,21 +64,27 @@ directory. For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages
have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
invocation would be:
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 <glfw-root-dir>
cmake .
@code{.sh}
cd <glfw-root-dir>
cmake .
@endcode
To make an out-of-tree build, make another directory, enter it and run CMake
with the (relative or absolute) path to the root of the source tree as an
argument.
cd <glfw-root-dir>
mkdir build
cd build
cmake ..
@code{.sh}
cd <glfw-root-dir>
mkdir build
cd build
cmake ..
@endcode
Once you have generated the project files or makefiles for your chosen
development environment, move on to @ref compile_compile.
@subsection compile_cmake_gui Generating files with the CMake GUI
@subsubsection compile_generate_gui Generating files with the CMake GUI
If you are using the GUI version, choose the root of the GLFW source tree as
source location and the same directory or another, empty directory as the
destination for binaries. Choose *Configure*, change any options you wish to,
*Configure* again to let the changes take effect and then *Generate*.
Once you have generated the project files or makefiles for your chosen
development environment, move on to @ref compile_compile.
@section compile_options CMake options
@subsection compile_compile Compiling the library
You should now have all required dependencies and the project files or makefiles
necessary to compile GLFW. Go ahead and compile the actual GLFW library with
these files, as you would with any other project.
Once the GLFW library is compiled, you are ready to build your applications,
linking it to the GLFW library. See the @ref build guide for more information.
@subsection compile_options CMake options
The CMake files for GLFW provide a number of options, although not all are
available on all supported platforms. Some of these are de facto standards
@ -132,7 +175,7 @@ Some package systems like Ubuntu and other distributions based on Debian
GNU/Linux have this tool in a separate `cmake-curses-gui` package.
@subsection compile_options_shared Shared CMake options
@subsubsection compile_options_shared Shared CMake options
`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
library or as a DLL / shared library / dynamic library.
@ -157,7 +200,7 @@ built along with the library.
the library.
@subsection compile_options_osx OS X specific CMake options
@subsubsection compile_options_osx OS X specific CMake options
`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
directory of bundled applications to the `Contents/Resources` directory.
@ -171,7 +214,7 @@ Retina displays.
`GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries.
@subsection compile_options_win32 Windows specific CMake options
@subsubsection compile_options_win32 Windows specific CMake options
`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the
static library version of the Visual C++ runtime library. If set to `ON`, the
@ -189,7 +232,7 @@ symbol, which forces the use of the high-performance GPU on nVidia Optimus
systems.
@subsection compile_options_egl EGL specific CMake options
@subsubsection compile_options_egl EGL specific CMake options
`GLFW_USE_EGL` determines whether to use EGL instead of the platform-specific
context creation API. Note that EGL is not yet provided on all supported

63
docs/context.dox
View File

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

2
docs/extra.css
View File

File diff suppressed because one or more lines are too long

17
docs/extra.less
View File

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

554
docs/input.dox
View File

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

225
docs/intro.dox
View File

@ -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.
<img src="spaces.svg" width="90%" />
Window and monitor positions are specified relative to the upper-left corners of
their content areas, while cursor positions are specified relative to the window
client area.
The origin of the window client area coordinate system is also the position of
the window, meaning you can translate client area coordinates to the virtual
screen by adding the window position. The window frame, when present, extend
out from the client area but does not affect the window position.
Almost all positions and sizes in GLFW are measured in screen coordinates
relative to one of the two origins above. This includes cursor positions,
window positions and sizes, window frame sizes, monitor positions and video mode
resolutions.
Two exceptions are the [monitor physical size](@ref monitor_size), which is
measured in millimetres, and [framebuffer size](@ref window_fbsize), which is
measured in pixels.
Pixels and screen coordinates may map 1:1 on your machine, but they won't on
every other machine, for example on a Mac with a Retina display. The ratio
between screen coordinates and pixels may also change at run-time depending on
which monitor the window is currently on.
@section guarantees_limitations Guarantees and limitations
This section describes the conditions under which GLFW can be expected to
function, barring any bugs in GLFW, the operating system or drivers. Use of
GLFW outside of these limits may work on some platforms, or on some machines, or
some of the time, or on some versions of GLFW, but it may break at any time and
will not be considered a bug.
@subsection lifetime Pointer lifetimes
GLFW will never free any pointer you provide to it and you must never free any
pointer it provides to you.
Many GLFW functions return pointers to dynamically allocated structures, strings
or arrays, and some callbacks are provided with strings or arrays. These are
always managed by GLFW and should never be freed by the application. The
lifetime of these pointers is documented for each GLFW function and callback.
If you need to keep this data, you must copy it before its lifetime expires.
Many GLFW functions accept pointers to structures or strings allocated by the
application. These are never freed by GLFW and are always the responsibility of
the application. If GLFW needs to keep the data in these structures or strings,
they are copied before the function returns.
Pointer lifetimes are guaranteed not to be shortened in future minor releases.
@subsection reentrancy Reentrancy
GLFW event processing and object creation and destruction are not reentrant.
This means that the following functions may not be called from any callback
function:
- @ref glfwCreateWindow
- @ref glfwDestroyWindow
- @ref glfwCreateCursor
- @ref glfwDestroyCursor
- @ref glfwPollEvents
- @ref glfwWaitEvents
@subsection thread_safety Thread safety
Most GLFW functions may only be called from the main thread. The reference
documentation for every GLFW function states whether it is limited to the main
thread.
There are some general rules that make it easier to remember which functions are
limited to the main thread. The following tasks may only be performed on the
main thread:
- Initialization and termination
- Event processing
- Creation and destruction of window, context and cursor objects
Because event processing must be performed on the main thread, all callbacks
except for the error callback will only be called on that thread. The error
callback may be called on any thread, as any GLFW function may generate errors.
The posting of empty events may be done from any thread. The window user
pointer and close flag may also be accessed and modified from any thread, but
this is not synchronized by GLFW. The following window related functions may
be called from any thread:
- @ref glfwPostEmptyEvent
- @ref glfwGetWindowUserPointer
- @ref glfwSetWindowUserPointer
- @ref glfwWindowShouldClose
- @ref glfwSetWindowShouldClose
Rendering may be done on any thread. The following context related functions
may be called from any thread:
- @ref glfwMakeContextCurrent
- @ref glfwGetCurrentContext
- @ref glfwSwapBuffers
- @ref glfwSwapInterval
- @ref glfwExtensionSupported
- @ref glfwGetProcAddress
The timer may be accessed from any thread, but this is not synchronized by GLFW.
The following timer related functions may be called from any thread:
- @ref glfwGetTime
No GLFW function may be called from any other thread until GLFW has been
successfully initialized on the main thread, including functions that may called
before initialization.
GLFW uses no synchronization objects internally except for thread-local storage
to keep track of the current context for each thread. Synchronization is left
to the application.
Functions that may currently be called from any thread will always remain so,
but functions that are currently limited to the main may be updated to allow
calls from any thread in future releases.
@subsection compatibility Version compatibility
GLFW guarantees binary backward compatibility with earlier minor versions of the
API. This means that you can drop in a newer version of the GLFW DLL / shared
library / dynamic library and existing applications will continue to run.
Once a function or constant has been added, the signature of that function or
value of that constant will remain unchanged until the next major version of
GLFW. No compatibility of any kind is guaranteed between major versions.
Undefined behavior, i.e. behavior that is not described in reference
documentation, may change at any time until it is documented.
If the reference documentation and the implementation differ, the reference
documentation is correct and the implementation will be fixed in the next
release.
@subsection event_order Event order
The order of arrival of related events is not guaranteed to be consistent
across platforms. The exception is synthetic key and mouse button release
events, which are always delivered after the window defocus event.
@section intro_version Version management
GLFW provides mechanisms for identifying what version of GLFW your application
was compiled against as well as what version it is currently using. The GLFW
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

42
docs/main.dox
View File

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

70
docs/monitor.dox
View File

@ -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);

19
docs/moving.dox
View File

@ -38,7 +38,9 @@ The threading functions have been removed, including the per-thread sleep
function. They were fairly primitive, under-used, poorly integrated and took
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

41
docs/news.dox
View File

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

205
docs/quick.dox
View File

@ -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 <GLFW/glfw3.h>
@ -54,40 +56,39 @@ inclusion of the GLFW header.
@endcode
@section quick_init_term Initializing and terminating GLFW
@subsection quick_init_term Initializing and terminating GLFW
Before you can use most GLFW functions, the library must be initialized. This
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.

91
docs/rift.dox Normal file
View File

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

352
docs/spaces.svg Normal file
View File

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

After

Width:  |  Height:  |  Size: 14 KiB

629
docs/window.dox
View File

@ -1,6 +1,6 @@
/*!
@page window Window handling guide
@page window Window guide
@tableofcontents
@ -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
`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.
`GLFW_RESIZABLE` indicates whether the specified window is resizable *by the
user*. This is controlled by the [window hint](@ref window_hints) with the same
name.
`GLFW_DECORATED` indicates whether the specified window has decorations such as
a border, a close widget, etc. This is controlled by the
[window hint](@ref window_hints) with the same name.
The `GLFW_RESIZABLE` attribute indicates whether the specified window is
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
[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);

1
examples/simple.c
View File

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

1352
include/GLFW/glfw3.h
View File

File diff suppressed because it is too large Load Diff

148
include/GLFW/glfw3native.h
View File

@ -45,8 +45,8 @@ extern "C" {
* using it.**
*
* 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);