Documentation work.

This commit is contained in:
Camilla Berglund 2013-04-10 23:01:12 +02:00
parent 7b5b33ee3b
commit 8282a8fbe0
7 changed files with 191 additions and 97 deletions

View File

@ -307,7 +307,7 @@ GLFW.
`GLFWgammaramp` type for monitor gamma ramp control
* Added window parameter to `glfwSwapBuffers`
* Changed buffer bit depth parameters of `glfwOpenWindow` to window hints
* Changed `glfwOpenWindow` and `glfwSetWindowTitle` to use UTF-8 encoded
* Changed `glfwCreateWindow` and `glfwSetWindowTitle` to use UTF-8 encoded
strings
* Changed `glfwGetProcAddress` to return a (generic) function pointer
* Changed `glfwGetVideoModes` to return a dynamic, unlimited number of video
@ -367,7 +367,7 @@ GLFW.
counterparts
* [Cocoa] Bugfix: The `NSOpenGLPFAFullScreen` pixel format attribute caused
creation to fail on some machines
* [Cocoa] Bugfix: `glfwOpenWindow` did not properly enforce the
* [Cocoa] Bugfix: `glfwCreateWindow` did not properly enforce the
forward-compatible and context profile hints
* [Cocoa] Bugfix: The loop condition for saving video modes used the wrong
index variable

View File

@ -37,8 +37,8 @@ process events. If the running window manager does not support this protocol,
the user will not be notified if the application locks up.
GLFW uses the EWMH `_NET_WM_STATE` protocol to tell the window manager to make
the GLFW window fullscreen. If the running window manager does not support this
protocol, fullscreen windows may not work properly. GLFW has a fallback code
the GLFW window full screen. If the running window manager does not support this
protocol, full screen windows may not work properly. GLFW has a fallback code
path in case this protocol is unavailable, but every window manager behaves
slightly differently in this regard.
@ -86,7 +86,7 @@ neither is available, no other extensions are used and many GLFW features
related to context creation will have no effect or cause errors when used.
GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
synchronization (or "vsync"). Where this extension is unavailable, calling @ref
synchronization (or 'vsync'). Where this extension is unavailable, calling @ref
glfwSwapInterval will have no effect.
GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to

View File

@ -5,10 +5,10 @@
@tableofcontents
This is a transition guide for moving from GLFW 2 to 3. It describes what has
changed or been removed, but does *not* include entirely new features unless
they are required when moving an existing code base onto the new API. For example,
use of the new multi-monitor functions are required to create fullscreen windows
with GLFW 3.
changed or been removed, but does *not* include
[new features](@ref news) unless they are required when moving an existing code
base onto the new API. For example, use of the new multi-monitor functions are
required to create full screen windows with GLFW 3.
@section moving_removed Removed features
@ -31,8 +31,9 @@ TinyCThread.
However, GLFW 3 has better support for *use from multiple threads* than GLFW
2 had. Contexts can be made current on and rendered with from secondary
threads, and the documentation explicitly states which functions may or may not
be used from secondary threads.
threads, and the documentation explicitly states which functions may be used
from secondary threads and which may only be used from the main thread, i.e. the
thread that calls main.
@subsection moving_image Image and texture loading
@ -92,8 +93,8 @@ The Win32 port of GLFW 3 will not compile in
However, because the use of the Unicode version of the Win32 API doesn't affect
the process as a whole, but only those windows created using it, it's perfectly
possible to call MBCS functions from other parts of the same application.
Therefore, even if an application using GLFW uses MBCS mode, there's no need for
GLFW itself to support it.
Therefore, even if an application using GLFW has MBCS mode code, there's no need
for GLFW itself to support it.
@subsection moving_windows Support for versions of Windows older than XP
@ -121,7 +122,7 @@ version of Windows.
The ability to disable and capture system-wide hotkeys like Alt+Tab has been
removed. Modern applications, whether they're games, scientific visualisations
or something else, are nowadays expected to be good desktop citizens and allow
these hotkeys to function even when running in fullscreen mode.
these hotkeys to function even when running in full screen mode.
@subsection moving_autopoll Automatic polling of events
@ -159,7 +160,7 @@ to an opaque struct.
@subsection moving_monitor Multi-monitor support
GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle
type and a set of related functions. To request a fullscreen mode window,
type and a set of related functions. To request a full screen mode window,
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
window to use. There is @ref glfwGetPrimaryMonitor that provides behaviour
similar to that of GLFW 2.
@ -211,9 +212,9 @@ having to remember whether to check for `'a'` or `'A'`, you now check for
Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function
now returns all available modes for a specific monitor instead of requiring you
to guess how large an array you need. The `glfwGetDesktopMode` function has
been replaced by @ref glfwGetVideoMode, which returns the current mode of
a monitor.
to guess how large an array you need. The `glfwGetDesktopMode` function, which
had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
returns the current mode of a monitor.
@subsection moving_cursor Cursor positioning

View File

@ -32,7 +32,7 @@ select which context is current on a given thread.
GLFW now explicitly supports multiple monitors. They can be enumerated with
@ref glfwGetMonitors, queried with @ref glfwGetVideoModes, @ref
glfwGetMonitorPos, @ref glfwGetMonitorName and @ref glfwGetMonitorPhysicalSize,
and specified at window creation to make the newly created window fullscren on
and specified at window creation to make the newly created window full screen on
that specific monitor.
@ -65,9 +65,9 @@ GLFW now supports the creation of OpenGL ES contexts, by setting the
contexts are supported. Note that GLFW *does not implement* OpenGL ES, so your
driver must provide support in a way usable by GLFW. Modern nVidia and Intel
drivers support creation of OpenGL ES context using the GLX and WGL APIs, while
AMD currently only provides an EGL implementation.
AMD provides an EGL implementation instead.
GLFW now has an (experimental) EGL context creation backend, which can be
GLFW now has an (experimental) EGL context creation back end, which can be
selected through CMake options.
@ -118,7 +118,7 @@ to @ref glfwCreateWindow.
Windows can now be hidden with @ref glfwHideWindow, shown using @ref
glfwShowWindow and created initially hidden with the `GLFW_VISIBLE` window hint.
This allows for offscreen rendering in a way compatible with most drivers, as
This allows for off-screen rendering in a way compatible with most drivers, as
well as moving a window to a specific position before showing it.
*/

View File

@ -110,8 +110,8 @@ glfwSetErrorCallback(error_callback);
@section 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 an 640 by 480
pixels windowed mode window:
returns a handle to the created window. For example, this creates a 640 by 480
windowed mode window:
@code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
@ -131,16 +131,16 @@ if (!window)
This handle is then passed to all window related functions, and is provided to
you along with input events, so you know which window received the input.
To create a fullscreen window, you need to specify which monitor the window
To create a full screen window, you need to specify which monitor the window
should use. In most cases, the user's primary monitor is a good choice. You
can get this with @ref glfwGetPrimaryMonitor. To make the above window
fullscreen, just pass along the monitor handle:
full screen, just pass along the monitor handle:
@code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
@endcode
Fullscreen windows cover the entire screen, have no border or decorations, and
Full screen windows cover the entire screen, have no border or decorations, and
change the monitor's resolution to the one most closely matching the requested
window size.
@ -272,8 +272,8 @@ keyboard input, it's possible to create a simple program.
@snippet simple.c code
This program creates a 640 by 480 pixels window and runs a loop clearing the
screen, rendering a triangle and processing events until the user closes the
This program creates a 640 by 480 windowed mode window and runs a loop clearing
the screen, rendering a triangle and processing events until the user closes the
window. It can be found in the source distribution as `examples/simple.c`, and
is by default compiled along with all other examples when you build GLFW.

View File

@ -9,7 +9,11 @@ a fullscreen window.
@section window_object Window objects
Text here.
The @ref GLFWwindow object encapsulates both a window and a context. They are
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
@ref glfwTerminate, if any remain). As the window and context are inseparably
linked, the window handle (i.e. window object pointer) is used as a context
handle as well, for example when calling @ref glfwMakeContextCurrent.
@section window_hints Window hints
@ -79,9 +83,13 @@ 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 will still
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.
For OpenGL ES, these hints are hard constraints, as there is no backward
compatibility between OpenGL ES versions.
@ -120,7 +128,8 @@ visible. This hint is ignored for fullscreen windows.
The `GLFW_DECORATED` hint specifies whether the window will have window
decorations such as a border, a close widget, etc. This hint is ignored for
fullscreen windows.
fullscreen windows. Note that even though a window may lack a close widget, it
is usually still possible for the user to generate close events.
@subsection window_hints_values Supported and default values
@ -155,7 +164,14 @@ fullscreen windows.
@section window_closing Window closing
Text here.
When the user attempts to close the window, for example by clicking the close
widget or using a key chord like Alt+F4, the window's close flag is set and then
its close callback is called. The window is not actually destroyed and, unless
you are monitoring the close flag, nothing further happens.
If you do not want the close flag to be set, it can be cleared again from the
close callback (or from any other point in your program) with @ref
glfwSetWindowShouldClose.
@section window_dims Window dimensions

View File

@ -60,7 +60,7 @@ extern "C" {
* 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 fullscreen window.
* a full screen window.
*/
@ -241,23 +241,23 @@ extern "C" {
#define GLFW_REPEAT 2
/*! @} */
/* Keyboard raw key codes.
* These key codes are inspired by the USB HID Usage Tables v1.12 (p. 53-60),
/*! @defgroup keys Keyboard keys
*
* These key codes are inspired by the *USB HID Usage Tables v1.12* (p. 53-60),
* but re-arranged to map to 7-bit ASCII for printable keys (function keys are
* put in the 256+ range).
*
* The naming of the key codes follow these rules:
* - The US keyboard layout is used.
* - The US keyboard layout is used
* - Names of printable alpha-numeric characters are used (e.g. "A", "R",
* "3", etc).
* "3", etc.)
* - For non-alphanumeric characters, Unicode:ish names are used (e.g.
* "COMMA", "LEFT_SQUARE_BRACKET", etc). Note that some names do not
* correspond to the Unicode standard (usually for brevity).
* - Keys that lack a clear US mapping are named "WORLD_x".
* "COMMA", "LEFT_SQUARE_BRACKET", etc.). Note that some names do not
* correspond to the Unicode standard (usually for brevity)
* - Keys that lack a clear US mapping are named "WORLD_x"
* - For non-printable keys, custom names are used (e.g. "F4",
* "BACKSPACE", etc).
*/
/*! @defgroup keys Keyboard keys
* "BACKSPACE", etc.)
*
* @ingroup input
* @{
*/
@ -542,21 +542,34 @@ extern "C" {
*************************************************************************/
/*! @brief Client API function pointer type.
*
* Generic function pointer used for returning client API function pointers
* without forcing a cast from a regular pointer.
*
* @ingroup context
*/
typedef void (*GLFWglproc)(void);
/*! @brief Opaque monitor object.
*
* Opaque monitor object.
*
* @ingroup monitor
*/
typedef struct GLFWmonitor GLFWmonitor;
/*! @brief Opaque window object.
*
* Opaque window object.
*
* @ingroup window
*/
typedef struct GLFWwindow GLFWwindow;
/*! @brief The function signature for error callbacks.
*
* This is the function signature for error callback functions.
*
* @param[in] error An [error code](@ref errors).
* @param[in] description A UTF-8 encoded string describing the error.
*
@ -567,11 +580,14 @@ typedef struct GLFWwindow GLFWwindow;
typedef void (* GLFWerrorfun)(int,const char*);
/*! @brief The function signature for window position callbacks.
*
* This is the function signature for window position callback functions.
*
* @param[in] window The window that the user moved.
* @param[in] xpos The new x-coordinate, in pixels, of the upper-left corner of
* the client area of the window.
* @param[in] ypos The new y-coordinate, in pixels, of the upper-left corner of
* the client area of the window.
* @param[in] xpos The new x-coordinate, in screen coordinates, of the
* upper-left corner of the client area of the window.
* @param[in] ypos The new y-coordinate, in screen coordinates, of the
* upper-left corner of the client area of the window.
*
* @sa glfwSetWindowPosCallback
*
@ -580,9 +596,12 @@ typedef void (* GLFWerrorfun)(int,const char*);
typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
/*! @brief The function signature for window resize callbacks.
*
* This is the function signature for window size callback functions.
*
* @param[in] window The window that the user resized.
* @param[in] width The new width, in pixels, of the window.
* @param[in] height The new height, in pixels, of the window.
* @param[in] width The new width, in screen coordinates, of the window.
* @param[in] height The new height, in screen coordinates, of the window.
*
* @sa glfwSetWindowSizeCallback
*
@ -591,6 +610,9 @@ typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int);
/*! @brief The function signature for window close callbacks.
*
* This is the function signature for window close callback functions.
*
* @param[in] window The window that the user attempted to close.
*
* @sa glfwSetWindowCloseCallback
@ -600,6 +622,9 @@ typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int);
typedef void (* GLFWwindowclosefun)(GLFWwindow*);
/*! @brief The function signature for window content refresh callbacks.
*
* This is the function signature for window refresh callback functions.
*
* @param[in] window The window whose content needs to be refreshed.
*
* @sa glfwSetWindowRefreshCallback
@ -609,6 +634,9 @@ typedef void (* GLFWwindowclosefun)(GLFWwindow*);
typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);
/*! @brief The function signature for window focus/defocus callbacks.
*
* This is the function signature for window focus callback functions.
*
* @param[in] window The window that was focused or defocused.
* @param[in] focused `GL_TRUE` if the window was focused, or `GL_FALSE` if
* it was defocused.
@ -620,6 +648,10 @@ typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);
typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);
/*! @brief The function signature for window iconify/restore callbacks.
*
* This is the function signature for window iconify/restore callback
* functions.
*
* @param[in] window The window that was iconified or restored.
* @param[in] iconified `GL_TRUE` if the window was iconified, or `GL_FALSE`
* if it was restored.
@ -631,6 +663,9 @@ typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);
typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);
/*! @brief The function signature for mouse button callbacks.
*
* This is the function signature for mouse button callback functions.
*
* @param[in] window The window that received the event.
* @param[in] button The [mouse button](@ref buttons) that was pressed or
* released.
@ -643,6 +678,9 @@ typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);
typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int);
/*! @brief The function signature for cursor position callbacks.
*
* This is the function signature for cursor position callback functions.
*
* @param[in] window The window that received the event.
* @param[in] xpos The new x-coordinate of the cursor.
* @param[in] ypos The new y-coordinate of the cursor.
@ -653,7 +691,10 @@ typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int);
*/
typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);
/*! @brief The function signature for cursor enter/exit callbacks.
/*! @brief The function signature for cursor enter/leave callbacks.
*
* This is the function signature for cursor enter/leave callback functions.
*
* @param[in] window The window that received the event.
* @param[in] entered `GL_TRUE` if the cursor entered the window's client
* area, or `GL_FALSE` if it left it.
@ -665,6 +706,9 @@ typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);
typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);
/*! @brief The function signature for scroll callbacks.
*
* This is the function signature for scroll callback functions.
*
* @param[in] window The window that received the event.
* @param[in] xpos The scroll offset along the x-axis.
* @param[in] ypos The scroll offset along the y-axis.
@ -676,6 +720,9 @@ typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);
typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
/*! @brief The function signature for keyboard key callbacks.
*
* This is the function signature for keyboard key callback functions.
*
* @param[in] window The window that received the event.
* @param[in] key The [keyboard key](@ref keys) that was pressed or released.
* @param[in] action @ref GLFW_PRESS, @ref GLFW_RELEASE or @ref GLFW_REPEAT.
@ -687,6 +734,9 @@ typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
typedef void (* GLFWkeyfun)(GLFWwindow*,int,int);
/*! @brief The function signature for Unicode character callbacks.
*
* This is the function signature for Unicode character callback functions.
*
* @param[in] window The window that received the event.
* @param[in] character The Unicode code point of the character.
*
@ -697,6 +747,9 @@ typedef void (* GLFWkeyfun)(GLFWwindow*,int,int);
typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int);
/*! @brief The function signature for monitor configuration callbacks.
*
* This is the function signature for monitor configuration callback functions.
*
* @param[in] monitor The monitor that was connected or disconnected.
* @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
*
@ -706,8 +759,11 @@ typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int);
*/
typedef void (* GLFWmonitorfun)(GLFWmonitor*,int);
/* @brief Video mode type.
* @ingroup monitor
/*! @brief Video mode type.
*
* This describes a single video mode.
*
* @ingroup monitor
*/
typedef struct
{
@ -719,6 +775,11 @@ typedef struct
} GLFWvidmode;
/*! @brief Gamma ramp.
*
* This describes the gamma ramp for a monitor.
*
* @sa glfwGetGammaRamp glfwSetGammaRamp
*
* @ingroup gamma
*/
typedef struct
@ -824,7 +885,7 @@ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev);
* - Any additional options or APIs
*
* For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
* backends, the version string may look something like this:
* back ends, the version string may look something like this:
*
* 3.0.0 Win32 WGL MinGW
*
@ -1066,15 +1127,18 @@ GLFWAPI void glfwWindowHint(int target, int hint);
* can use the newly created context, you need to make it current using @ref
* glfwMakeContextCurrent.
*
* Note that the actual properties of the window and context may differ from
* what you requested, as not all parameters and hints are hard constraints.
* Note that the created window and context may differ from what you requested,
* as not all parameters and hints are hard constraints. This includes the
* size of the window, especially for full screen windows. To retrieve the
* actual properties of the window and context, use queries like @ref
* glfwGetWindowParam and @ref glfwGetWindowSize.
*
* @param[in] width The desired width, in pixels, of the window. This must be
* greater than zero.
* @param[in] height The desired height, in pixels, of the window. This must
* be greater than zero.
* @param[in] width The desired width, in screen coordinates, of the window.
* This must be greater than zero.
* @param[in] height The desired height, in screen coordinates, of the window.
* This must be greater than zero.
* @param[in] title The initial, UTF-8 encoded window title.
* @param[in] monitor The monitor to use for fullscreen mode, or `NULL` to use
* @param[in] monitor The monitor to use for full screen mode, or `NULL` to use
* windowed mode.
* @param[in] share The window whose context to share resources with, or `NULL`
* to not share resources.
@ -1084,10 +1148,10 @@ GLFWAPI void glfwWindowHint(int target, int hint);
* invisible using the `GLFW_VISIBLE` window hint, set its position and then
* show it.
*
* @remarks For fullscreen windows the initial cursor mode is
* `GLFW_CURSOR_CAPTURED` and the screensaver is prohibited from starting. For
* regular windows the initial cursor mode is `GLFW_CURSOR_NORMAL` and the
* screensaver is allowed to start.
* @remarks For full screen windows the initial cursor mode is
* `GLFW_CURSOR_CAPTURED` and the screen saver is prohibited from starting.
* For regular windows the initial cursor mode is `GLFW_CURSOR_NORMAL` and the
* screen saver is allowed to start.
*
* @remarks **Windows:** If the executable has an icon resource named
* `GLFW_ICON,` it will be set as the icon for the window. If no such icon is
@ -1102,7 +1166,7 @@ GLFWAPI void glfwWindowHint(int target, int hint);
*
* @note This function may only be called from the main thread.
*
* @bug **Mac OS X:** The primary monitor is always used for fullscreen
* @bug **Mac OS X:** The primary monitor is always used for full screen
* windows, regardless of which monitor was specified.
*
* @sa glfwDestroyWindow
@ -1195,6 +1259,8 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
* This function sets the position, in screen coordinates, of the upper-left
* corner of the client area of the window.
*
* If it is a full screen window, this function does nothing.
*
* @param[in] window The window to query.
* @param[in] xpos The x-coordinate of the upper-left corner of the client area.
* @param[in] ypos The y-coordinate of the upper-left corner of the client area.
@ -1224,8 +1290,8 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
/*! @brief Retrieves the size of the client area of the specified window.
*
* This function retrieves the size, in pixels, of the client area of the
* specified window.
* This function retrieves the size, in screen coordinates, of the client area
* of the specified window.
*
* @param[in] window The window whose size to retrieve.
* @param[out] width The width of the client area.
@ -1239,8 +1305,13 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
/*! @brief Sets the size of the client area of the specified window.
*
* This function sets the size, in pixels, of the client area of the specified
* window.
* This function sets the size, in screen coordinates, of the client area of
* the specified window.
*
* For full screen windows, this function selects and switches to the resolution
* closest to the specified size, without affecting the window's context. As
* the context is unaffected, the bit depths of the framebuffer remain
* unchanged.
*
* @param[in] window The window to resize.
* @param[in] width The desired width of the specified window.
@ -1250,10 +1321,6 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
*
* @note The window manager may put limits on what window sizes are allowed.
*
* @note For fullscreen windows, this function selects and switches to the
* resolution closest to the specified size, without destroying the window's
* context.
*
* @sa glfwGetWindowSize
*
* @ingroup window
@ -1263,7 +1330,7 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height);
/*! @brief Iconifies the specified window.
*
* This function iconifies/minimizes the specified window, if it was previously
* restored. If it is a fullscreen window, the original monitor resolution is
* restored. If it is a full screen window, the original monitor resolution is
* restored until the window is restored. If the window is already iconified,
* this function does nothing.
*
@ -1272,7 +1339,7 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height);
* @note This function may only be called from the main thread.
*
* @bug **Mac OS X:** This function is not yet implemented for
* fullscreen windows.
* full screen windows.
*
* @sa glfwRestoreWindow
*
@ -1283,14 +1350,15 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
/*! @brief Restores the specified window.
*
* This function restores the specified window, if it was previously
* iconified/minimized. If the window is already restored, this function does
* nothing.
* iconified/minimized. If it is a full screen window, the resolution chosen
* for the window is restored on the selected monitor. If the window is
* already restored, this function does nothing.
*
* @param[in] window The window to restore.
*
* @note This function may only be called from the main thread.
*
* @bug **Mac OS X:** This function is not yet implemented for fullscreen
* @bug **Mac OS X:** This function is not yet implemented for full screen
* windows.
*
* @sa glfwIconifyWindow
@ -1302,7 +1370,7 @@ GLFWAPI void glfwRestoreWindow(GLFWwindow* window);
/*! @brief Makes the specified window visible.
*
* This function makes the specified window visible, if it was previously
* hidden. If the window is already visible or is in fullscreen mode, this
* hidden. If the window is already visible or is in full screen mode, this
* function does nothing.
*
* @param[in] window The window to make visible.
@ -1318,7 +1386,7 @@ GLFWAPI void glfwShowWindow(GLFWwindow* window);
/*! @brief Hides the specified window.
*
* This function hides the specified window, if it was previously visible. If
* the window is already hidden or is in fullscreen mode, this function does
* the window is already hidden or is in full screen mode, this function does
* nothing.
*
* @param[in] window The window to hide.
@ -1331,10 +1399,10 @@ GLFWAPI void glfwShowWindow(GLFWwindow* window);
*/
GLFWAPI void glfwHideWindow(GLFWwindow* window);
/*! @brief Returns the monitor that the window uses for fullscreen mode.
/*! @brief Returns the monitor that the window uses for full screen mode.
*
* This function returns the handle of the monitor that the specified window is
* in fullscreen on.
* in full screen on.
*
* @param[in] window The window to query.
* @return The monitor, or `NULL` if the window is in windowed mode.
@ -1440,7 +1508,7 @@ GLFWAPI void glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun
*
* This function sets the size callback of the specified window, which is
* called when the window is resized. The callback is provided with the size,
* in pixels, of the client area of the window.
* in screen coordinates, of the client area of the window.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
@ -1479,14 +1547,14 @@ GLFWAPI void glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun c
* called when the client area of the window needs to be redrawn, for example
* if the window has been exposed after having been covered by another window.
*
* 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.
*
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback.
*
* @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.
*
* @ingroup window
*/
GLFWAPI void glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun cbfun);
@ -1519,7 +1587,7 @@ GLFWAPI void glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyf
/*! @brief Processes all pending events.
*
* This function processes only those events that have already been recevied
* This function processes only those events that have already been received
* and then returns immediately.
*
* @par New in GLFW 3
@ -1527,7 +1595,6 @@ GLFWAPI void glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyf
* it or @ref glfwWaitEvents yourself.
*
* @note This function may only be called from the main thread.
* @note This function may not be called from a callback.
*
* @note This function may not be called from a callback.
*
@ -1539,11 +1606,10 @@ GLFWAPI void glfwPollEvents(void);
/*! @brief Waits until events are pending and processes them.
*
* This function blocks until at least one event has been recevied and then
* This function blocks until at least one event has been received and then
* processes all received events before returning.
*
* @note This function may only be called from the main thread.
* @note This function may not be called from a callback.
*
* @note This function may not be called from a callback.
*
@ -1903,8 +1969,7 @@ GLFWAPI void glfwSetTime(double time);
*
* This function makes the context of the specified window current on the
* calling thread. A context can only be made current on a single thread at
* a time and each thread can have only a single current context for a given
* client API (such as OpenGL or OpenGL ES).
* a time and each thread can have only a single current context at a time.
*
* @param[in] window The window whose context to make current, or `NULL` to
* detach the current context.
@ -1957,13 +2022,25 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
*
* This function sets the swap interval for the current context, i.e. the
* number of screen updates to wait before swapping the buffers of a window and
* returning from @ref glfwSwapBuffers.
* returning from @ref glfwSwapBuffers. This is sometimes called 'vertical
* synchronization', 'vertical retrace synchronization' or 'vsync'.
*
* @param[in] interval The minimum number of screen updates to wait for
* until the buffers are swapped by @ref glfwSwapBuffers.
*
* @remarks This function may be called from secondary threads.
*
* @remarks Contexts that support either of the `WGL_EXT_swap_control_tear` and
* `GLX_EXT_swap_control_tear` extensions also accept negative swap intervals,
* which allow the driver to swap even if a frame arrives a little bit late.
* You can check for the presence of these extensions using @ref
* glfwExtensionSupported. For more information about swap tearing, see the
* extension specifications.
*
* @note Some GPU drivers do not honor the requested swap interval, either
* because of user settings that override the request or due to bugs in the
* driver.
*
* @sa glfwSwapBuffers
*
* @ingroup context
@ -1983,7 +2060,7 @@ GLFWAPI void glfwSwapInterval(int interval);
*
* @note As this functions searches one or more extension strings on each call,
* it is recommended that you cache its results if it's going to be used
* freqently. The extension strings will not change during the lifetime of
* frequently. The extension strings will not change during the lifetime of
* a context, so there is no danger in doing this.
*
* @ingroup context