diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index a04c8bab..271036b5 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -38,7 +38,7 @@ PROJECT_NUMBER = @GLFW_VERSION_FULL@ # for a project that appears at the top of each page and should give viewer # a quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = +PROJECT_BRIEF = "A multi-platform library for OpenGL, window and input" # With the PROJECT_LOGO tag one can specify an logo or icon that is # included in the documentation. The maximum height of the logo should not @@ -88,7 +88,7 @@ BRIEF_MEMBER_DESC = YES # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. -REPEAT_BRIEF = YES +REPEAT_BRIEF = NO # This tag implements a quasi-intelligent brief description abbreviator # that is used to form the text in various listings. Each string @@ -106,7 +106,7 @@ ABBREVIATE_BRIEF = # Doxygen will generate a detailed section even if there is only a brief # description. -ALWAYS_DETAILED_SEC = NO +ALWAYS_DETAILED_SEC = YES # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all # inherited members of a class in the documentation of that class as if those diff --git a/docs/hints.dox b/docs/hints.dox new file mode 100644 index 00000000..370bdc49 --- /dev/null +++ b/docs/hints.dox @@ -0,0 +1,39 @@ +/*! + +@page hints Window hints + +These are all window hints. Some relate to the window itself, others to its +framebuffer or context. They are set to their default values by @ref glfwInit, +can be individually set with @ref glfwWindowHint and reset all at once to their +defaults with @ref glfwDefaultWindowHints. + +Note that hints need to be set *before* the creation of the window you wish to +have the specified properties. + +| Name | Default values | Supported values | +| ---------------------------- | ------------------------ | ----------------------- | +| `GLFW_RESIZABLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` | +| `GLFW_VISIBLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` | +| `GLFW_RED_BITS` | 8 | 0 to `INT_MAX` | +| `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` | +| `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` | +| `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` | +| `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` | +| `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` | +| `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` | +| `GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` | +| `GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` | +| `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` | +| `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` | +| `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` | +| `GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` | +| `GLFW_SRGB_CAPABLE` | `GL_FALSE` | `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_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_NO_PROFILE` | `GLFW_OPENGL_NO_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` | + +*/ diff --git a/docs/moving.dox b/docs/moving.dox index 76e5446a..3bede0ef 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -68,7 +68,7 @@ callback, *not* the removal of the character callback itself. Scroll events do not represent an absolute state. Instead, it's an interpretation of a relative change in state, like character input. So, like character input, there is no sane 'current state' to return. The mouse wheel -callback has been replaced by a [scroll callback](@ref GFLWscrollfun) that +callback has been replaced by a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll offsets. @@ -127,8 +127,10 @@ these hotkeys to function even when running in fullscreen mode. @subsection moving_window_handles Window handles Because GLFW 3 supports multiple windows, window handle parameters have been -added to all window-related GLFW functions and callbacks. Window handles are of -the `GLFWwindow*` type, i.e. a pointer to an opaque struct. +added to all window-related GLFW functions and callbacks. The handle of +a newly created window is returned by @ref glfwCreateWindow (formerly +`glfwOpenWindow`). Window handles are of the `GLFWwindow*` type, i.e. a pointer +to an opaque struct. @subsection moving_monitor Multi-monitor support @@ -195,9 +197,17 @@ make it do so by defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW @subsection moving_cursor Cursor positioning -GLFW 3 only allows you to position the cursor within a window (using @ref -glfwSetCursorPos) when that window is active. Unless the window is active, the -function fails silently. +GLFW 3 only allows you to position the cursor within a window using @ref +glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active. +Unless the window is active, the function fails silently. + + +@subsection moving_hints Persistent window hints + +Window hints are no longer reset to their default values on window creation, but +instead retain their values until modified by @ref glfwWindowHint (formerly +`glfwOpenWindowHint`) or @ref glfwDefaultWindowHints, or until the library is +terminated and re-initialized. @section moving_renamed Name changes diff --git a/include/GL/glfw3.h b/include/GL/glfw3.h index f3117a6c..829df946 100644 --- a/include/GL/glfw3.h +++ b/include/GL/glfw3.h @@ -723,18 +723,18 @@ typedef struct /*! @brief Initializes the GLFW library. * - * Before most GLFW functions can be used, GLFW must be initialized, and before - * a program terminates GLFW should be terminated in order to free allocated - * resources, memory, etc. + * This function initializes the GLFW library. Before most GLFW functions can + * be used, GLFW must be initialized, and before a program terminates GLFW + * should be terminated in order to free any resources allocated during or + * after initialization. * * If this function fails, it calls @ref glfwTerminate before returning. If it * succeeds, you should call @ref glfwTerminate before the program exits. * - * @return `GL_TRUE` if successful, or `GL_FALSE` if an error occurred. - * @ingroup init + * Additional calls to this function after successful initialization but before + * termination will succeed but will do nothing. * - * @remarks Additional calls to this function after successful initialization - * but before termination will succeed but will do nothing. + * @return `GL_TRUE` if successful, or `GL_FALSE` if an error occurred. * * @par New in GLFW 3 * This function no longer registers @ref glfwTerminate with `atexit`. @@ -749,11 +749,12 @@ typedef struct * bundle, if present. * * @sa glfwTerminate + * + * @ingroup init */ GLFWAPI int glfwInit(void); /*! @brief Terminates the GLFW library. - * @ingroup init * * This function destroys all remaining windows, frees any allocated resources * and sets the library to an uninitialized state. Once this is called, you @@ -761,8 +762,8 @@ GLFWAPI int glfwInit(void); * most GLFW functions. * * If GLFW has been successfully initialized, this function should be called - * before the program exits. If @ref glfwInit fails, there is no need to call - * this function, as it is called before @ref glfwInit returns failure. + * before the program exits. If initialization fails, there is no need to call + * this function, as it is called by @ref glfwInit before it returns failure. * * @remarks This function may be called before @ref glfwInit. * @@ -772,45 +773,68 @@ GLFWAPI int glfwInit(void); * function is called. * * @sa glfwInit + * + * @ingroup init */ GLFWAPI void glfwTerminate(void); /*! @brief Retrieves the version of the GLFW library. + * + * This function retrieves the major, minor and revision numbers of the GLFW + * library. It is intended for when you are using GLFW as a shared library and + * want to ensure that you are using the minimum required version. + * * @param[out] major Where to store the major version number, or `NULL`. * @param[out] minor Where to store the minor version number, or `NULL`. * @param[out] rev Where to store the revision number, or `NULL`. - * @ingroup init * * @remarks This function may be called before @ref glfwInit. * - * @remarks This function may be called from secondary threads. + * @remarks This function may be called from any thread. * * @sa glfwGetVersionString + * + * @ingroup init */ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); /*! @brief Returns a string describing the compile-time configuration. + * + * This function returns a static string generated at compile-time according to + * which configuration macros were defined. This is intended for use when + * submitting bug reports, to allow developers to see which code paths are + * enabled in a binary. * * The format of the string is as follows: + * * The version of GLFW * * The name of the window system API * * The name of the context creation API * * 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: + * + * 3.0.0 Win32 WGL MinGW + * * @return The GLFW version string. - * @ingroup init * * @remarks This function may be called before @ref glfwInit. * - * @remarks This function may be called from secondary threads. + * @remarks This function may be called from any thread. * * @sa glfwGetVersion + * + * @ingroup init */ GLFWAPI const char* glfwGetVersionString(void); /*! @brief Sets the error callback. + * + * This function sets the error callback, which is called with an error code + * and a human-readable description each time a GLFW error occurs. + * * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * @ingroup error * * @remarks This function may be called before @ref glfwInit. * @@ -822,143 +846,192 @@ GLFWAPI const char* glfwGetVersionString(void); * generated specifically for that error, it is not guaranteed to be valid * after the callback has returned. If you wish to use it after that, you need * to make your own copy of it before returning. + * + * @ingroup error */ GLFWAPI void glfwSetErrorCallback(GLFWerrorfun cbfun); /*! @brief Returns the currently connected monitors. + * + * This function returns an array of handles for all currently connected + * monitors. + * * @param[out] count The size of the returned array. * @return An array of monitor handles, or `NULL` if an error occurred. - * @ingroup monitor + * + * @note The returned array is valid only until the monitor configuration + * changes. See @ref glfwSetMonitorCallback to receive notifications of + * configuration changes. * * @sa glfwGetPrimaryMonitor + * + * @ingroup monitor */ GLFWAPI GLFWmonitor** glfwGetMonitors(int* count); /*! @brief Returns the primary monitor. + * + * This function returns the primary monitor. This is usually the monitor + * where elements like the Windows task bar or the OS X menu bar is located. + * * @return The primary monitor, or `NULL` if an error occurred. - * @ingroup monitor * * @sa glfwGetMonitors + * + * @ingroup monitor */ GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void); /*! @brief Returns the position of the monitor's viewport on the virtual screen. + * + * This function returns the position, in screen coordinates, of the upper-left + * corner of the specified monitor. + * * @param[in] monitor The monitor to query. * @param[out] xpos The monitor x-coordinate. * @param[out] ypos The monitor y-coordinate. + * * @ingroup monitor */ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); /*! @brief Returns the physical size of the monitor. + * + * This function returns the size, in millimetres, of the display area of the + * specified monitor. + * * @param[in] monitor The monitor to query. * @param[out] width The width, in mm, of the monitor's display * @param[out] height The height, in mm, of the monitor's display. + * + * @note Some operating systems do not provide accurate information, either + * because the monitor's EDID data is incorrect, or because the driver does not + * report it accurately. + * * @ingroup monitor */ GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* width, int* height); /*! @brief Returns the name of the specified monitor. + * + * This function returns a human-readable name, encoded as UTF-8, of the + * specified monitor. + * * @param[in] monitor The monitor to query. * @return The UTF-8 encoded name of the monitor, or `NULL` if an error * occurred. + * * @ingroup monitor */ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); /*! @brief Sets the monitor configuration callback. + * + * This function sets the monitor configuration callback, or removes the + * currently set callback. This is called when a monitor is connected to or + * disconnected from the system. + * * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. + * * @ingroup monitor */ GLFWAPI void glfwSetMonitorCallback(GLFWmonitorfun cbfun); /*! @brief Returns the available video modes for the specified monitor. + * + * This function returns an array of all video modes supported by the specified + * monitor. + * * @param[in] monitor The monitor to query. * @param[out] count The number of video modes in the returned array. * @return An array of video modes, or `NULL` if an error occurred. - * @ingroup monitor + * + * @note The returned array is valid only until this function is called again + * for this monitor. * * @sa glfwGetVideoMode + * + * @ingroup monitor */ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count); /*! @brief Returns the current mode of the specified monitor. + * + * This function returns the current video mode of the specified monitor. + * * @param[in] monitor The monitor to query. * @return The current mode of the monitor, or all zeroes if an error occurred. - * @ingroup monitor * * @sa glfwGetVideoModes + * + * @ingroup monitor */ GLFWAPI GLFWvidmode glfwGetVideoMode(GLFWmonitor* monitor); /*! @brief Generates a gamma ramp and sets it for the specified monitor. + * + * This function generates a gamma ramp from the specified exponent and then + * calls @ref glfwSetGamma with it. + * * @param[in] monitor The monitor whose gamma ramp to set. * @param[in] gamma The desired exponent. - * @ingroup gamma * - * @remarks This is a helper function on top of @ref glfwSetGammaRamp. + * @ingroup gamma */ GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma); /*! @brief Retrieves the current gamma ramp for the specified monitor. + * + * This function retrieves the current gamma ramp of the specified monitor. + * * @param[in] monitor The monitor to query. * @param[out] ramp Where to store the gamma ramp. - * @ingroup gamma * * @bug This function does not yet support monitors whose original gamma ramp * has more or less than 256 entries. + * + * @ingroup gamma */ GLFWAPI void glfwGetGammaRamp(GLFWmonitor* monitor, GLFWgammaramp* ramp); -/*! @brief Sets the gamma ramp for the specified monitor. +/*! @brief Sets the current gamma ramp for the specified monitor. + * + * This function sets the current gamma ramp for the specified monitor. + * * @param[in] monitor The monitor whose gamma ramp to set. * @param[in] ramp The gamma ramp to use. - * @ingroup gamma * * @bug This function does not yet support monitors whose original gamma ramp * has more or less than 256 entries. + * + * @ingroup gamma */ GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp); -/*! @brief Resets all window hints to their default values +/*! @brief Resets all window hints to their default values. * - * The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS` - * and `GLFW_STENCIL_BITS` hints are set to 8. - * - * The `GLFW_DEPTH_BITS` hint is set to 24. - * - * The `GLFW_VISIBLE` and `GLFW_RESIZABLE` hints are set to 1. - * - * The `GLFW_CLIENT_API` hint is set to `GLFW_OPENGL_API`. - * - * The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints are - * set to 1 and 0, respectively. - * - * The `GLFW_CONTEXT_ROBUSTNESS` hint is set to `GLFW_NO_ROBUSTNESS`. - * - * The `GLFW_OPENGL_PROFILE` hint is set to `GLFW_OPENGL_NO_PROFILE`. - * - * All other hints are set to 0. - * - * @ingroup window + * This function resets all window hints to their + * [default values](@ref hints). * * @note This function may only be called from the main thread. * * @sa glfwWindowHint + * + * @ingroup window */ GLFWAPI void glfwDefaultWindowHints(void); /*! @brief Sets the specified window hint to the desired value. - * @param[in] target The window hint to set. - * @param[in] hint The new value of the window hint. - * @ingroup window * * This function sets hints for the next call to @ref glfwCreateWindow. The * hints, once set, retain their values until changed by a call to @ref * glfwWindowHint or @ref glfwDefaultWindowHints, or until the library is * terminated with @ref glfwTerminate. * + * @param[in] target The [window hint](@ref hints) to set. + * @param[in] hint The new value of the window hint. + * * @par Hard and soft constraints * * Some window hints are hard constraints. These must match the available @@ -1057,10 +1130,23 @@ GLFWAPI void glfwDefaultWindowHints(void); * @note This function may only be called from the main thread. * * @sa glfwDefaultWindowHints + * + * @ingroup window */ GLFWAPI void glfwWindowHint(int target, int hint); /*! @brief Creates a window and its associated context. + * + * This function creates a window and its associated context. Most of the + * options controlling how the window and its context should be created are + * specified via the @ref glfwWindowHint function. + * + * Successful creation does not change which context is current. Before you + * can use the newly created context, you need to make it current using @ref + * glfwMakeContextCurrent. + * + * 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. * * @param[in] width The desired width, in pixels, of the window. This must be * greater than zero. @@ -1072,14 +1158,6 @@ GLFWAPI void glfwWindowHint(int target, int hint); * @param[in] share The window whose context to share resources with, or `NULL` * to not share resources. * @return The handle of the created window, or `NULL` if an error occurred. - * @ingroup window - * - * @remarks Most of the options for how the window and its context should be - * created are specified via the @ref glfwWindowHint function. - * - * @remarks This function does not change which context is current. Before you - * can use the newly created context, you need to make it current using @ref - * glfwMakeContextCurrent. * * @remarks To create the window at a specific position, make it initially * invisible using the `GLFW_VISIBLE` window hint, set its position and then @@ -1090,9 +1168,6 @@ GLFWAPI void glfwWindowHint(int target, int hint); * regular windows the initial cursor mode is `GLFW_CURSOR_NORMAL` and the * screensaver is allowed to start. * - * @remarks In order to determine the actual parameters of an opened window, - * use @ref glfwGetWindowParam and @ref glfwGetWindowSize. - * * @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 * present, the `IDI_WINLOGO` icon will be used instead. @@ -1110,12 +1185,17 @@ GLFWAPI void glfwWindowHint(int target, int hint); * windows, regardless of which monitor was specified. * * @sa glfwDestroyWindow + * + * @ingroup window */ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share); /*! @brief Destroys the specified window and its context. + * + * This function destroys the specified window and its context. On calling + * this function, no further callbacks will be called for that window. + * * @param[in] window The window to destroy. - * @ingroup window * * @note This function may only be called from the main thread. * @@ -1124,59 +1204,79 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G * @note If the window's context is current on the main thread, it is * detached before being destroyed. * - * @note On calling this function, no further callbacks will be called for - * the specified window, even if their associated events occur during window - * destruction. - * * @warning The window's context must not be current on any other thread. * * @sa glfwCreateWindow + * + * @ingroup window */ GLFWAPI void glfwDestroyWindow(GLFWwindow* window); /*! @brief Checks the close flag of the specified window. + * + * This function returns the value of the close flag of the specified window. + * * @param[in] window The window to query. * @return The value of the close flag. + * * @ingroup window */ GLFWAPI int glfwWindowShouldClose(GLFWwindow* window); /*! @brief Sets the close flag of the specified window. + * + * This function sets the value of the close flag of the specified window. + * This can be used to override the user's attempt to close the window, or + * to signal that it should be closed. + * * @param[in] window The window whose flag to change. * @param[in] value The new value. + * * @ingroup window */ GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value); /*! @brief Sets the title of the specified window. + * + * This function sets the window title, encoded as UTF-8, of the specified + * window. + * * @param[in] window The window whose title to change. * @param[in] title The UTF-8 encoded window title. - * @ingroup window * * @note This function may only be called from the main thread. + * + * @ingroup window */ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); /*! @brief Retrieves the position of the client area of the specified window. + * + * This function retrieves the position, in screen coordinates, of the + * upper-left corner of the client area of the specified window. + * * @param[in] window The window to query. * @param[out] xpos The x-coordinate of the upper-left corner of the client area. * @param[out] ypos The y-coordinate of the upper-left corner of the client area. - * @ingroup window * * @remarks Either or both coordinate parameters may be `NULL`. * + * @bug **Mac OS X:** The screen coordinate system is inverted. + * * @sa glfwSetWindowPos + * + * @ingroup window */ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); /*! @brief Sets the position of the client area of the specified window. + * + * This function sets the position, in screen coordinates, of the upper-left + * corner of the client area of the window. + * * @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. - * @ingroup window - * - * @remarks The position is the screen coordinate of the upper-left corner of - * the client area of the window. * * @remarks If you wish to set an initial window position you should create * a hidden window (using @ref glfwWindowHint and `GLFW_VISIBLE`), set its @@ -1196,24 +1296,34 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); * @bug **Mac OS X:** The screen coordinate system is inverted. * * @sa glfwGetWindowPos + * + * @ingroup window */ 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. + * * @param[in] window The window whose size to retrieve. * @param[out] width The width of the client area. * @param[out] height The height of the client area. - * @ingroup window * * @sa glfwSetWindowSize + * + * @ingroup window */ 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. + * * @param[in] window The window to resize. * @param[in] width The desired width of the specified window. * @param[in] height The desired height of the specified window. - * @ingroup window * * @note This function may only be called from the main thread. * @@ -1224,14 +1334,19 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); * context. * * @sa glfwGetWindowSize + * + * @ingroup window */ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); /*! @brief Iconifies the specified window. - * @param[in] window The window to iconify. - * @ingroup window * - * @remarks If the window is already iconified, this function does nothing. + * This function iconifies/minimizes the specified window, if it was previously + * restored. If it is a fullscreen window, the original monitor resolution is + * restored until the window is restored. If the window is already iconified, + * this function does nothing. + * + * @param[in] window The window to iconify. * * @note This function may only be called from the main thread. * @@ -1239,62 +1354,81 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); * fullscreen windows. * * @sa glfwRestoreWindow + * + * @ingroup window */ GLFWAPI void glfwIconifyWindow(GLFWwindow* window); /*! @brief Restores the specified window. + * + * This function restores the specified window, if it was previously + * iconified/minimized. If the window is already restored, this function does + * nothing. + * * @param[in] window The window to restore. * @ingroup window * - * @remarks If the window is already restored, this function does nothing. - * * @note This function may only be called from the main thread. * - * @bug **Mac OS X:** This function is not yet implemented for - * fullscreen windows. + * @bug **Mac OS X:** This function is not yet implemented for fullscreen + * windows. * * @sa glfwIconifyWindow */ GLFWAPI void glfwRestoreWindow(GLFWwindow* window); /*! @brief Makes the specified window visible. - * @param[in] window The window to make visible. - * @ingroup window * - * @remarks If the window is already visible or is in fullscreen mode, this + * This function makes the specified window visible, if it was previously + * hidden. If the window is already visible or is in fullscreen mode, this * function does nothing. * + * @param[in] window The window to make visible. + * * @note This function may only be called from the main thread. * * @sa glfwHideWindow + * + * @ingroup window */ GLFWAPI void glfwShowWindow(GLFWwindow* window); /*! @brief Hides the specified window. - * @param[in] window The window to hide. - * @ingroup window * - * @remarks If the window is already hidden or is in fullscreen mode, this - * function does nothing. + * 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 + * nothing. + * + * @param[in] window The window to hide. * * @note This function may only be called from the main thread. * * @sa glfwShowWindow + * + * @ingroup 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 fullscreen mode. + * + * This function returns the handle of the monitor that the specified window is + * in fullscreen on. + * * @param[in] window The window to query. * @return The monitor, or `NULL` if the window is in windowed mode. + * * @ingroup window */ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); /*! @brief Returns a parameter of the specified window. + * + * This function returns a property of the specified window. There are many + * different properties, some related to the window and others to its context. + * * @param[in] window The window to query. * @param[in] param The parameter whose value to return. * @return The value of the parameter, or zero if an error occurred. - * @ingroup window * * @par Window parameters * @@ -1331,100 +1465,138 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); * 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. + * + * @ingroup window */ GLFWAPI int glfwGetWindowParam(GLFWwindow* window, int param); /*! @brief Sets the user pointer of the specified window. + * + * This function sets the user-defined pointer of the specified window. The + * current value is retained until the window is destroyed. The initial value + * is `NULL`. + * * @param[in] window The window whose pointer to set. * @param[in] pointer The new value. - * @ingroup window * * @sa glfwGetWindowUserPointer + * + * @ingroup window */ GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer); /*! @brief Returns the user pointer of the specified window. + * + * This function returns the current value of the user-defined pointer of the + * specified window. The initial value is `NULL`. + * * @param[in] window The window whose pointer to return. - * @ingroup window * * @sa glfwSetWindowUserPointer + * + * @ingroup window */ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); /*! @brief Sets the position callback for the specified window. + * + * This function sets the position callback of the specified window, which is + * called when the window is moved. The callback is provided with the screen + * position of the upper-left corner 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 * callback. + * * @ingroup window */ GLFWAPI void glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun); /*! @brief Sets the size callback for the specified window. + * + * 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. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * @ingroup window * - * This callback is called when the window is resized. + * @ingroup window */ GLFWAPI void glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun cbfun); /*! @brief Sets the close callback for the specified window. + * + * This function sets the close callback of the specified window, which is + * called when the user attempts to close the window, for example by clicking + * the close widget in the title bar. + * + * The close flag is set before this callback is called, but you can modify it + * at any time with @ref glfwSetWindowShouldClose. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * @ingroup window - * - * This callback is called when the user attempts to close the window, i.e. - * for example by clicking the window's close widget. It is called immediately - * after the window's close flag has been set. * * @remarks Calling @ref glfwDestroyWindow does not cause this callback to be * called. * * @remarks **Mac OS X:** Selecting Quit from the application menu will * trigger the close callback for all windows. + * + * @ingroup window */ GLFWAPI void glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun cbfun); /*! @brief Sets the refresh callback for the specified window. + * + * This function sets the refresh callback of the specified window, which is + * 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. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * @ingroup window - * - * This callback is 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. * * @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); /*! @brief Sets the focus callback for the specified window. + * + * This function sets the focus callback of the specified window, which is + * called when the window gains or loses focus. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * @ingroup window * - * This callback is called when the window gains or loses focus. + * @ingroup window */ GLFWAPI void glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun cbfun); /*! @brief Sets the iconify callback for the specified window. + * + * This function sets the iconification callback of the specified window, which + * is called when the window is iconified or restored. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * @ingroup window * - * This callback is called when the window is iconified or restored. + * @ingroup window */ GLFWAPI void glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun cbfun); /*! @brief Processes all pending events. - * @ingroup window + * + * This function processes only those events that have already been recevied + * and then returns immediately. * * @par New in GLFW 3 * This function is no longer called by @ref glfwSwapBuffers. You need to call @@ -1436,11 +1608,15 @@ GLFWAPI void glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyf * @note This function may not be called from a callback. * * @sa glfwWaitEvents + * + * @ingroup window */ GLFWAPI void glfwPollEvents(void); /*! @brief Waits until events are pending and processes them. - * @ingroup window + * + * This function blocks until at least one event has been recevied 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. @@ -1448,16 +1624,20 @@ GLFWAPI void glfwPollEvents(void); * @note This function may not be called from a callback. * * @sa glfwPollEvents + * + * @ingroup window */ GLFWAPI void glfwWaitEvents(void); /*! @brief Returns the value of an input option for the specified window. + * * @param[in] window The window to query. * @param[in] mode One of `GLFW_CURSOR_MODE`, `GLFW_STICKY_KEYS` or * `GLFW_STICKY_MOUSE_BUTTONS`. - * @ingroup input * * @sa glfwSetInputMode + * + * @ingroup input */ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); @@ -1497,95 +1677,153 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); /*! @brief Returns the last reported state of a keyboard key for the specified * window. + * + * This function returns the last state reported for the specified key to the + * specified window. The returned state is one of `GLFW_PRESS` or + * `GLFW_RELEASE`. The higher-level state `GLFW_REPEAT` is only reported to + * the key callback. + * + * If the `GLFW_STICKY_KEYS` input mode is enabled, this function returns + * `GLFW_PRESS` the first time you call this function after a key has been + * pressed, even if the key has already been released. + * + * The key functions deal with physical keys, with [key tokens](@ref keys) + * named after their use on the standard US keyboard layout. If you want to + * input text, use the Unicode character callback instead. + * * @param[in] window The desired window. * @param[in] key The desired [keyboard key](@ref keys). * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. + * * @ingroup input */ GLFWAPI int glfwGetKey(GLFWwindow* window, int key); /*! @brief Returns the last reported state of a mouse button for the specified * window. + * + * This function returns the last state reported for the specified mouse button + * to the specified window. + * + * If the `GLFW_STICKY_MOUSE_BUTTONS` input mode is enabled, this function + * returns `GLFW_PRESS` the first time you call this function after a mouse + * button has been pressed, even if the mouse button has already been released. + * * @param[in] window The desired window. * @param[in] button The desired [mouse button](@ref buttons). * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. + * * @ingroup input */ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); /*! @brief Retrieves the last reported cursor position, relative to the client * area of the window. + * + * This function returns the last reported position of the cursor to the + * specified window. + * * @param[in] window The desired window. * @param[out] xpos The cursor x-coordinate, relative to the left edge of the * client area, or `NULL`. * @param[out] ypos The cursor y-coordinate, relative to the to top edge of the * client area, or `NULL`. - * @ingroup input * * @sa glfwSetCursorPos + * + * @ingroup input */ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, int* xpos, int* ypos); /*! @brief Sets the position of the cursor, relative to the client area of the window. + * + * This function sets the position of the cursor. The specified window must be + * focused. If the window does not have focus when this function is called, it + * fails silently. + * * @param[in] window The desired window. * @param[in] xpos The desired x-coordinate, relative to the left edge of the * client area, or `NULL`. * @param[in] ypos The desired y-coordinate, relative to the top edge of the * client area, or `NULL`. - * @ingroup input - * - * @note The specified window must be focused. * * @sa glfwGetCursorPos + * + * @ingroup input */ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, int xpos, int ypos); /*! @brief Sets the key callback. + * + * This function sets the key callback of the specific window, which is called + * when a key is pressed, repeated or released. + * + * The key functions deal with physical keys, with [key tokens](@ref keys) + * named after their use on the standard US keyboard layout. If you want to + * input text, use the [character callback](@ref glfwSetCharCallback) instead. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new key callback, or `NULL` to remove the currently * set callback. - * @ingroup input * - * @remarks The key callback deals with physical keys, with [key tokens](@ref - * keys) named after their use on the standard US keyboard layout. If you - * want to input text, use the Unicode character callback instead. + * @ingroup input */ GLFWAPI void glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun); /*! @brief Sets the Unicode character callback. + * + * This function sets the character callback of the specific window, which is + * called when a Unicode character is input. + * + * The character callback is intended for text input. If you want to know + * whether a specific key was pressed or released, use the + * [key callback](@ref glfwSetKeyCallback) instead. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * @ingroup input * - * @remarks The Unicode character callback is for text input. If you want to - * know whether a specific key was pressed or released, use the key callback. + * @ingroup input */ GLFWAPI void glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun); /*! @brief Sets the mouse button callback. + * + * This function sets the mouse button callback of the specified window, which + * is called when a mouse button is pressed or released. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. + * * @ingroup input */ GLFWAPI void glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun cbfun); /*! @brief Sets the cursor position callback. + * + * This function sets the cursor position callback of the specified window, + * which is called when the cursor is moved. The callback is provided with the + * position relative to the upper-left corner 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 * callback. - * @ingroup input * - * @remarks The position is relative to the upper-left corner of the client - * area of the window. + * @ingroup input */ GLFWAPI void glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun cbfun); /*! @brief Sets the cursor enter/exit callback. + * + * This function sets the cursor boundary crossing callback of the specified + * window, which is called when the cursor enters or leaves 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 * callback. + * * @ingroup input */ GLFWAPI void glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun cbfun); @@ -1602,61 +1840,88 @@ GLFWAPI void glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun c GLFWAPI void glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cbfun); /*! @brief Returns a parameter of the specified joystick. + * + * This function returns a parameter of the specified joystick. + * * @param[in] joy The joystick to query. * @param[in] param The parameter whose value to return. * @return The specified joystick's current value, or zero if the joystick is * not present. + * * @ingroup input */ GLFWAPI int glfwGetJoystickParam(int joy, int param); /*! @brief Returns the values of axes of the specified joystick. + * + * This function returns the current positions of axes of the specified + * joystick. + * * @param[in] joy The joystick to query. * @param[out] axes The array to hold the values. * @param[in] numaxes The size of the provided array. - * @return The number of values written to `axes,` or zero if an error + * @return The number of values written to `axes`, or zero if an error * occurred. + * * @ingroup input */ GLFWAPI int glfwGetJoystickAxes(int joy, float* axes, int numaxes); /*! @brief Returns the values of buttons of the specified joystick. + * + * This function returns the current state of buttons of the specified + * joystick. + * * @param[in] joy The joystick to query. * @param[out] buttons The array to hold the values. * @param[in] numbuttons The size of the provided array. - * @return The number of values written to `buttons,` or zero if an error + * @return The number of values written to `buttons`, or zero if an error * occurred. + * * @ingroup input */ GLFWAPI int glfwGetJoystickButtons(int joy, unsigned char* buttons, int numbuttons); /*! @brief Returns the name of the specified joystick. + * + * This function returns the name, encoded as UTF-8, of the specified joystick. + * * @param[in] joy The joystick to query. * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick * is not present. - * @ingroup input * * @note The returned string is valid only until the next call to @ref - * glfwGetJoystickName. + * glfwGetJoystickName for that joystick. + * + * @ingroup input */ GLFWAPI const char* glfwGetJoystickName(int joy); /*! @brief Sets the clipboard to the specified string. + * + * This function sets the system clipboard to the specified, UTF-8 encoded + * string. The string is copied before returning, so you don't have to retain + * it afterwards. + * * @param[in] window The window that will own the clipboard contents. * @param[in] string A UTF-8 encoded string. - * @ingroup clipboard * * @note This function may only be called from the main thread. * * @sa glfwGetClipboardString + * + * @ingroup clipboard */ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); /*! @brief Retrieves the contents of the clipboard as a string. + * + * This function returns the contents of the system clipboard, if it contains + * or is convertible to a UTF-8 encoded string. + * * @param[in] window The window that will request the clipboard contents. * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL` * if an error occurred. - * @ingroup clipboard * * @note This function may only be called from the main thread. * @@ -1664,44 +1929,66 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); * glfwGetClipboardString or @ref glfwSetClipboardString. * * @sa glfwSetClipboardString + * + * @ingroup clipboard */ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); -/*! @brief Retrieves the current value of the GLFW timer. +/*! @brief Returns the value of the GLFW timer. + * + * This function returns the value of the GLFW timer. Unless the timer has + * been set using @ref glfwSetTime, the timer measures time elapsed since GLFW + * was initialized. + * * @return The current value, in seconds, or zero if an error occurred. - * @ingroup time * * @remarks This function may be called from secondary threads. * - * @remarks Unless the timer has been set using @ref glfwSetTime, the timer - * measures time elapsed since GLFW was initialized. + * @note The resolution of the timer is system dependent, but is usually on the + * order of a few micro- or nanoseconds. It uses the highest-resolution + * monotonic time source on each supported platform. * - * @note The resolution of the timer is system dependent. + * @ingroup time */ GLFWAPI double glfwGetTime(void); /*! @brief Sets the GLFW timer. + * + * This function sets the value of the GLFW timer. It then continues to count + * up from that value. + * * @param[in] time The new value, in seconds. * @ingroup time * - * @note The resolution of the timer is system dependent. + * @note The resolution of the timer is system dependent, but is usually on the + * order of a few micro- or nanoseconds. It uses the highest-resolution + * monotonic time source on each supported platform. */ GLFWAPI void glfwSetTime(double time); -/*! @brief Makes the context of the specified window current for this thread. +/*! @brief Makes the context of the specified window current for the calling + * thread. + * + * This function makes the context of the specified window current on the + * calling thread. A context can only be made current on a single thread at + * a time and each thread can have only a single current context for a given + * client API (such as OpenGL or OpenGL ES). + * * @param[in] window The window whose context to make current, or `NULL` to * detach the current context. * @ingroup context * * @remarks This function may be called from secondary threads. * - * @note A context may only be current for a single thread at a time. - * * @sa glfwGetCurrentContext */ GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window); -/*! @brief Returns the window whose context is current on this thread. +/*! @brief Returns the window whose context is current on the calling thread. + * + * This function returns the window whose context is current on the calling + * thread. + * * @return The window whose context is current, or `NULL` if no window's * context is current. * @ingroup context @@ -1713,6 +2000,11 @@ GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window); GLFWAPI GLFWwindow* glfwGetCurrentContext(void); /*! @brief Swaps the front and back buffers of the specified window. + * + * This function swaps the front and back buffers of the specified window. If + * the swap interval is greater than zero, the GPU driver waits the specified + * number of screen updates before swapping the buffers. + * * @param[in] window The window whose buffers to swap. * @ingroup context * @@ -1727,7 +2019,12 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void); GLFWAPI void glfwSwapBuffers(GLFWwindow* window); /*! @brief Sets the swap interval for the current context. - * @param[in] interval The minimum number of video frame periods to wait for + * + * 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. + * + * @param[in] interval The minimum number of screen updates to wait for * until the buffers are swapped by @ref glfwSwapBuffers. * @ingroup context * @@ -1737,26 +2034,42 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window); */ GLFWAPI void glfwSwapInterval(int interval); -/*! @brief Checks whether the specified extension is available. +/*! @brief Returns whether the specified extension is available. + * + * This function returns whether the specified OpenGL or platform-specific + * context creation API extension is supported by the current context. For + * example, on Windows both the OpenGL and WGL extension strings are checked. + * * @param[in] extension The ASCII encoded name of the extension. * @return `GL_TRUE` if the extension is available, or `GL_FALSE` otherwise. * @ingroup context * * @remarks This function may be called from secondary threads. * - * @note This function checks not only the client API extension string, but - * also any platform-specific context creation API extension strings. + * @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 + * a context, so there is no danger in doing this. */ GLFWAPI int glfwExtensionSupported(const char* extension); -/*! @brief Returns the address of the specified client API function for the - * current context. +/*! @brief Returns the address of the specified function for the current + * context. + * + * This function returns the address of the specified client API function, if + * it is supported by the current context. + * * @param[in] procname The ASCII encoded name of the function. * @return The address of the function, or `NULL` if the function is * unavailable. - * @ingroup context * * @remarks This function may be called from secondary threads. + * + * @note The addresses of these functions are not guaranteed to be the same for + * all contexts, especially if they use different client APIs or even different + * context creation hints. + * + * @ingroup context */ GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname);