From 8282a8fbe01ecb97672e3c19b3010eb98ca7752a Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Wed, 10 Apr 2013 23:01:12 +0200 Subject: [PATCH] Documentation work. --- README.md | 4 +- docs/compat.dox | 6 +- docs/moving.dox | 27 +++--- docs/news.dox | 8 +- docs/quick.dox | 14 ++-- docs/window.dox | 24 +++++- include/GL/glfw3.h | 205 +++++++++++++++++++++++++++++++-------------- 7 files changed, 191 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index 34951675..b69e17b9 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/compat.dox b/docs/compat.dox index db272032..dc5ce8aa 100644 --- a/docs/compat.dox +++ b/docs/compat.dox @@ -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 diff --git a/docs/moving.dox b/docs/moving.dox index 1473dce1..3da4aefb 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -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 diff --git a/docs/news.dox b/docs/news.dox index 9c2a2b09..545cf4aa 100644 --- a/docs/news.dox +++ b/docs/news.dox @@ -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. */ diff --git a/docs/quick.dox b/docs/quick.dox index 94a4663f..00213277 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -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. diff --git a/docs/window.dox b/docs/window.dox index 26149751..b9928561 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -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 diff --git a/include/GL/glfw3.h b/include/GL/glfw3.h index ec66530a..1259d86f 100644 --- a/include/GL/glfw3.h +++ b/include/GL/glfw3.h @@ -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