Documentation work.

docs/glext.dox → docs/context.dox

@@ -1,6 +1,57 @@
 /*!
 
-@page glext OpenGL extension handling
+@page context Context handling guide
+
+@tableofcontents
+
+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, each of which has its own context.
+
+
+@section context_object Context handles
+
+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 object pointer is used as both a context and window handle.
+
+
+@section context_hints Context creation hints
+
+There are a number of hints, specified using @ref glfwWindowHint, related to
+what kind of context is created.  See
+[context related hints](@ref window_hints_ctx) in the window handling guide.
+
+
+@section context_current Current context
+
+Before you can use the OpenGL or OpenGL ES APIs, you need to have a current
+context of the proper type.  The context encapsulates all render state and all
+objects like textures and shaders.
+
+Note that a context can only be current for a single thread at a time, and
+a thread can only have a single context at a time.
+
+A context is made current with @ref glfwMakeContextCurrent.
+
+@code
+glfwMakeContextCurrent(window);
+@endcode
+
+The current context is returned by @ref glfwGetCurrentContext.
+
+@code
+GLFWwindow* window = glfwGetCurrentContext();
+@endcode
+
+
+@section context_swap Swapping buffers
+
+See [swapping buffers](@ref window_swap) in the window handling guide.
+
+
+@section context_glext OpenGL extension handling
 
 One of the benefits of OpenGL is its extensibility.  Independent hardware
 vendors (IHVs) may include functionality in their OpenGL implementations that
@@ -16,10 +67,9 @@ An extension is defined by:
 Note the `ARB` affix, which stands for Architecture Review Board and is used
 for official extensions.  There are many different affixes, depending on who
 wrote the extension.  A list of extensions, together with their specifications,
-can be found at the
-[OpenGL Registry](http://www.opengl.org/registry/).
+can be found at the [OpenGL Registry](http://www.opengl.org/registry/).
 
-To use a certain extension, you must first check whether the context exposes
+To use a certain extension, you must first check whether the context supports
 that extension and then, if it introduces new functions, retrieve the pointers
 to those functions.
 
@@ -31,7 +81,7 @@ the OpenGL API.  GLEW in particular has been extensively tested with and works
 well with GLFW.
 
 
-@section glext_header The glext.h header
+@subsection context_glext_header The glext.h header
 
 The `glext.h` header is a continually updated file that defines the interfaces
 for all OpenGL extensions.  The latest version of this can always be found at
@@ -42,30 +92,30 @@ you wish to use.
 
 The header defines function pointer types for all functions of all extensions it
 supports.  These have names like `PFNGLGETDEBUGMESSAGELOGARB` (for
-`glGetDebugMessageLogARB`), i.e. the name is made uppercase, the `gl` prefix is
-removed and `PFN` and `PROC` are added to the ends.
+`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` and `PROC`
+are added to the ends.
 
 
-@section glext_string Checking for extensions
+@subsection context_glext_string Checking for extensions
 
 A given machine may not actually support the extension (it may have older
 drivers or a graphics card that lacks the necessary hardware features), so it
-is necessary to check whether the context exposes the extension.  This is done
+is necessary to check whether the context supports the extension.  This is done
 with @ref glfwExtensionSupported.
 
 @code
 if (glfwExtensionSupported("GL_ARB_debug_output"))
 {
-    // The extension is exposed by the current context
+    // The extension is supported by the current context
 }
 @endcode
 
 The argument is a null terminated ASCII string with the extension name.  If the
-extension is exposed, @ref glfwExtensionSupported returns non-zero, otherwise it
-returns zero.
+extension is supported, @ref glfwExtensionSupported returns non-zero, otherwise
+it returns zero.
 
 
-@section glext_proc Fetching function pointers
+@subsection context_glext_proc Fetching function pointers
 
 Many extensions, though not all, require the use of new OpenGL functions.
 These entry points are often not exposed by your link libraries, making
@@ -89,7 +139,7 @@ when used together.
 #define glGetDebugMessageLogARB pfnGetDebugMessageLog
 PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog;
 
-// Flag indicating whether the extension is present
+// Flag indicating whether the extension is supported
 int has_debug_output = 0;
 
 void load_extensions(void)

docs/monitor.dox

@@ -0,0 +1,31 @@
+/*!
+
+@page monitor Multi-monitor guide
+
+@section monitor_objects Monitor objects
+
+
+@section monitor_modes Querying video modes
+
+Although GLFW generally does a good job at selecting a suitable video
+mode for you when you open a fullscreen window, it is sometimes useful to
+know exactly which modes are available on a certain system. For example,
+you may want to present the user with a list of video modes to select
+from. To get a list of available video modes, you can use the function
+@ref glfwGetVideoModes.
+
+@code
+int count;
+GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
+@endcode
+
+To get the current video mode of a monitor call @ref glfwGetVideoMode.
+
+@code
+const GLFWvidmode* mode = glfwGetVideoMode(monitor);
+@endcode
+
+
+@section monitor_gamma Gamma ramps
+
+*/

docs/moving.dox

@@ -188,6 +188,15 @@ glfwMakeContextCurrent after creating a window before you can call any OpenGL
 functions.
 
 
+@subsection moving_repeat Key repeat
+
+The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled
+for both keys and characters.  A new key action, `GLFW_REPEAT`, has been added
+to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press
+from a repeat.  Note that @ref glfwGetKey still returns only `GLFW_PRESS` or
+`GLFW_RELEASE`.
+
+
 @subsection moving_keys Physical key input
 
 GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
@@ -208,6 +217,16 @@ having to remember whether to check for `'a'` or `'A'`, you now check for
 `GLFW_KEY_A`.
 
 
+@subsection moving_joystick Joystick input
+
+The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes.
+
+The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and
+`GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent
+function as well as axis and button counts returned by the @ref
+glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions.
+
+
 @subsection moving_video_modes Video mode enumeration
 
 Video mode enumeration is now per-monitor.  The @ref glfwGetVideoModes function
@@ -260,6 +279,7 @@ Unix-like systems, where it uses the
 | `glfwGetWindowParam`        | @ref glfwGetWindowAttrib      |       |
 | `glfwGetGLVersion`          | @ref glfwGetWindowAttrib      | Use `GLFW_OPENGL_VERSION_MAJOR`, `GLFW_OPENGL_VERSION_MINOR` and `GLFW_OPENGL_REVISION` |
 | `glfwGetDesktopMode`        | @ref glfwGetVideoMode         | Returns the current mode of a monitor |
+| `glfwGetJoystickParam`      | @ref glfwJoystickPresent      | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons |
 
 @subsection moving_renamed_tokens Tokens
 

docs/news.dox

@@ -128,4 +128,9 @@ Windowed mode windows can now be created without decorations, i.e. things like
 a frame, a title bar, with the `GLFW_DECORATED` window hint.  This allows for
 the creation of things like splash screens.
 
+
+@subsection news_30_jsname Joystick names
+
+The name of a joystick can now be retrieved using @ref glfwGetJoystickName.
+
 */

docs/window.dox

@@ -1,31 +1,32 @@
-/*! @page window Window handling
+/*!
+
+@page window Window handling guide
  
 @tableofcontents
 
 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.
+management and OpenGL and OpenGL ES context creation.  GLFW supports multiple
+windows, which can be either a normal desktop window or a fullscreen window.
+
 
-@section window_object Window objects
+@section window_object Window handles
 
 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.
+linked, the object pointer is used as both a context and window handle.
 
 
-@section window_hints Window hints
+@section window_hints Window creation hints
 
-There are a number of hints that can be set before the creation of a window.
-Some affect the window itself, others its framebuffer or context.  These hints
-are set to their default values each time the library is initialized with @ref
-glfwInit, can be individually set with @ref glfwWindowHint and reset all at once
-to their defaults with @ref glfwDefaultWindowHints.
+There are a number of hints that can be set before the creation of a window and
+context.  Some affect the window itself, others affect the framebuffer or
+context.  These hints are set to their default values each time the library is
+initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint
+and reset all at once to their defaults with @ref glfwDefaultWindowHints.
 
-Note again that they need to be set *before* the creation of the window you wish
-to have the specified attributes.
+Note that hints need to be set *before* the creation of the window and context
+you wish to have the specified attributes.
 
 
 @subsection window_hints_hard Hard and soft constraints
@@ -49,6 +50,21 @@ context:
 Hints that do not apply to a given type of window or context are ignored.
 
 
+@subsection window_hints_wnd Window related hints
+
+The `GLFW_RESIZABLE` hint specifies whether the window will be resizable *by the
+user*.  The window will still be resizable using the @ref glfwSetWindowSize
+function.  This hint is ignored for fullscreen windows.
+
+The `GLFW_VISIBLE` hint specifies whether the window will be initially
+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.  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_fb Framebuffer related hints
 
 The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
@@ -116,21 +132,6 @@ used by the context.  This can be one of `GLFW_NO_RESET_NOTIFICATION` or
 a robustness strategy.
 
 
-@subsection window_hints_wnd Window related hints
-
-The `GLFW_RESIZABLE` hint specifies whether the window will be resizable *by the
-user*.  The window will still be resizable using the @ref glfwSetWindowSize
-function.  This hint is ignored for fullscreen windows.
-
-The `GLFW_VISIBLE` hint specifies whether the window will be initially
-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.  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
 
 | Name                         | Default value            | Supported values        |
@@ -161,20 +162,235 @@ is usually still possible for the user to generate close events.
 | `GLFW_OPENGL_PROFILE`        | `GLFW_OPENGL_NO_PROFILE` | `GLFW_OPENGL_NO_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |
 
 
-@section window_closing Window closing
+@section window_close Window close flag
 
 When the user attempts to close the window, for example by clicking the close
-widget or using a key chord like Alt+F4, the 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.
+widget or using a key chord like Alt+F4, the *close flag* of the window is set.
+The window is however not actually destroyed and, unless you watch for this
+state change, nothing further happens.
+
+The current state of the close flag is returned by @ref glfwWindowShouldClose
+and can be set or cleared directly with @ref glfwSetWindowShouldClose.  A common
+pattern is to use the close flag as a main loop condition.
+
+@code
+while (!glfwWindowShouldClose(window))
+{
+    render(window);
+
+    glfwSwapBuffers(window);
+    glfwPollEvents();
+}
+@endcode
+
+If you wish to be notified when the user attempts to close a window, you can set
+the close callback with @ref glfwSetWindowCloseCallback.  This callback is
+called directly *after* the close flag has been set.
+
+@code
+glfwSetWindowCloseCallback(window, window_close_callback);
+@endcode
+
+The callback function can be used for example to filter close requests and clear
+the close flag again unless certain conditions are met.
+
+@code
+void window_close_callback(GLFWwindow* window)
+{
+    if (!time_to_close)
+        glfwSetWindowShouldClose(window, GL_FALSE);
+}
+@endcode
+
+
+@section window_size Window size
+
+The size of a window can be changed with @ref glfwSetWindowSize.  For windowed
+mode windows, this resizes the specified window so that its *client area* has
+the specified size.  Note that the window system may put limitations on size.
+For full screen windows, it selects and sets the video mode most closely
+matching the specified size.
+
+@code
+void glfwSetWindowSize(window, 640, 480);
+@endcode
+
+If you wish to be notified when a window is resized, whether by the user or
+the system, you can set the size callback with @ref glfwSetWindowSizeCallback.
+
+@code
+glfwSetWindowSizeCallback(window, window_size_callback);
+@endcode
+
+The callback function receives the new size of the client area of the window,
+which can for example be used to update the viewport.
+
+@code
+void window_size_callback(GLFWwindow* window, int width, int height)
+{
+    glViewport(0, 0, width, height);
+}
+@endcode
+
+There is also @ref glfwGetWindowSize for directly retrieving the current size of
+a window.
+
+@code
+int width, height;
+glfwGetWindowSize(window, &width, &height);
+glViewport(0, 0, width, height);
+@endcode
+
+
+@section window_pos Window position
+
+The position of a windowed-mode window can be changed with @ref
+glfwSetWindowPos.  This moves the window so that the upper-left corner of its
+client area has the specified screen coordinates.  Note that the window system
+may put limitations on placement.
+
+@code
+glfwSetWindowPos(window, 100, 100);
+@endcode
+
+If you wish to be notified when a window is moved, whether by the user or
+the system, you can set the position callback with @ref glfwSetWindowPosCallback.
+
+@code
+glfwSetWindowPosCallback(window, window_pos_callback);
+@endcode
+
+The callback function receives the new position of the upper-left corner of its
+client area.
+
+@code
+void window_size_callback(GLFWwindow* window, int xpos, int ypos)
+{
+}
+@endcode
+
+There is also @ref glfwGetWindowPos for directly retrieving the current position
+of the client area of the window.
+
+@code
+int xpos, ypos;
+glfwGetWindowPos(window, &xpos, &ypos);
+@endcode
+
+
+@section window_title Window title
+
+All GLFW windows have a title, although undecorated or full screen windows may
+not display it or only display it in a task bar or similar interface.  To change
+the title of a window, use @ref glfwSetWindowTitle.
+
+@code
+glfwSetWindowTitle(window, "My Window");
+@endcode
+
+The window title is a regular C string using the UTF-8 encoding.  This means
+for example that, as long as your source file is encoded as UTF-8, you can use
+any Unicode characters.
+
+@code
+glfwSetWindowTitle(window, "さよなら絶望先生");
+@endcode
+
+
+@section window_attribs Window attributes
+
+Windows have a number of attributes that can be returned using @ref
+glfwGetWindowAttrib.  Some reflect state that may change during the lifetime of
+the window, while others reflect the corresponding hints and are fixed at the
+time of creation.
+
+@code
+if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
+{
+    // window has input focus
+}
+@endcode
+
+
+@subsection window_attribs_window Window attributes
+
+The `GLFW_FOCUSED` attribute indicates whether the specified window currently
+has input focus.
+
+The `GLFW_ICONIFIED` attribute indicates whether the specified window is
+currently iconified, whether by the user or with @ref glfwIconifyWindow.
+
+The `GLFW_VISIBLE` attribute indicates whether the specified window is currently
+visible.  Window visibility can be controlled with @ref glfwShowWindow and @ref
+glfwHideWindow and initial visibility is controlled by the [window hint](@ref
+window_hints) with the same name.  
+
+The `GLFW_RESIZABLE` attribute indicates whether the specified window is
+resizable *by the user*.  This is controlled by the [window hint](@ref
+window_hints) with the same name.
+
+The `GLFW_DECORATED` attribute indicates whether the specified window has
+decorations such as a border, a close widget, etc.  This is controlled by the
+[window hint](@ref window_hints) with the same name. 
+
+
+@subsection window_attribs_context Context attributes
+
+The `GLFW_CLIENT_API` attribute indicates the client API provided by the
+window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`.
+
+The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
+`GLFW_CONTEXT_REVISION` attributes indicate the client API version of the
+window's context.
+
+The `GLFW_OPENGL_FORWARD_COMPAT` attribute is `GL_TRUE` if the window's
+context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise.
+
+The `GLFW_OPENGL_DEBUG_CONTEXT` attribute is `GL_TRUE` if the window's
+context is an OpenGL debug context, or `GL_FALSE` otherwise.
+
+The `GLFW_OPENGL_PROFILE` attribute indicates the OpenGL profile used by the
+context.  This is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`
+if the context uses a known profile, or `GLFW_OPENGL_NO_PROFILE` if the
+OpenGL profile is unknown or the context is for another client API.
+
+The `GLFW_CONTEXT_ROBUSTNESS` attribute indicates the robustness strategy
+used by the context.  This is `GLFW_LOSE_CONTEXT_ON_RESET` or
+`GLFW_NO_RESET_NOTIFICATION` if the window's context supports robustness, or
+`GLFW_NO_ROBUSTNESS` otherwise.
+
+
+@section window_swap Swapping buffers
+
+GLFW windows are always double buffered.  That means that you have two
+rendering buffers; a front buffer and a back buffer.  The front buffer is
+the one being displayed and the back buffer the one you render to.
+
+When the entire frame has been rendered, it is time to swap the back and the
+front buffers in order to display what has been rendered and begin rendering
+a new frame.  This is done with @ref glfwSwapBuffers.
+
+@code
+glfwSwapBuffers(window);
+@endcode
 
-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.
+Sometimes it can be useful to select when the buffer swap will occur.  With the
+function @ref glfwSwapInterval it is possible to select the minimum number of
+monitor refreshes the driver should wait before swapping the buffers:
 
+@code
+glfwSwapInterval(1);
+@endcode
 
-@section window_dims Window dimensions
+If the interval is zero, the swap will take place immediately when @ref
+glfwSwapBuffers is called without waiting for a refresh.  Otherwise at least
+interval retraces will pass between each buffer swap.  Using a swap interval of
+zero can be useful for benchmarking purposes, when it is not desirable to
+measure the time it takes to wait for the vertical retrace.  However, a swap
+interval of one lets you avoid tearing.
 
-Text here.
+Note that not all OpenGL implementations properly implement this function, in
+which case @ref glfwSwapInterval will have no effect.  Some drivers also have
+user settings that override requests by GLFW.
 
 */

include/GLFW/glfw3.h

@@ -1268,7 +1268,7 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title);
  *  @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.
  *
- *  @remarks Either or both coordinate parameters may be `NULL`.
+ *  @remarks Either or both coordinate arguments may be `NULL`.
  *
  *  @bug **Mac OS X:** The screen coordinate system is inverted.
  *
@@ -1441,47 +1441,10 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
  *  attributes, some related to the window and others to its context.
  *
  *  @param[in] window The window to query.
- *  @param[in] attrib The attribute whose value to return.
+ *  @param[in] attrib The [window attribute](@ref window_attribs) whose value to
+ *  return.
  *  @return The value of the attribute, or zero if an error occurred.
  *
- *  @par Window attributes
- *
- *  The `GLFW_FOCUSED` attribute indicates whether the window is focused.
- *
- *  The `GLFW_ICONIFIED` attribute indicates whether the window is iconified.
- *
- *  The `GLFW_VISIBLE` attribute indicates whether the window is visible.
- *
- *  The `GLFW_RESIZABLE` attribute indicates whether the window is resizable
- *  by the user.
- *
- *  The `GLFW_DECORATED` attribute indicates whether the window is decorated.
- *
- *  @par Context attributes
- *
- *  The `GLFW_CLIENT_API` attribute indicates the client API provided by the
- *  window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`.
- *
- *  The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
- *  `GLFW_CONTEXT_REVISION` attributes indicate the client API version of the
- *  window's context.
- *
- *  The `GLFW_OPENGL_FORWARD_COMPAT` attribute is `GL_TRUE` if the window's
- *  context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise.
- *
- *  The `GLFW_OPENGL_DEBUG_CONTEXT` attribute is `GL_TRUE` if the window's
- *  context is an OpenGL debug context, or `GL_FALSE` otherwise.
- *
- *  The `GLFW_OPENGL_PROFILE` attribute indicates the OpenGL profile used by the
- *  context.  This is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`
- *  if the context uses a known profile, or `GLFW_OPENGL_NO_PROFILE` if the
- *  OpenGL profile is unknown or the context is for another client API.
- *
- *  The `GLFW_CONTEXT_ROBUSTNESS` attribute indicates the robustness strategy
- *  used by the context.  This is `GLFW_LOSE_CONTEXT_ON_RESET` or
- *  `GLFW_NO_RESET_NOTIFICATION` if the window's context supports robustness, or
- *  `GLFW_NO_ROBUSTNESS` otherwise.
- *
  *  @ingroup window
  */
 GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib);
@@ -2138,9 +2101,9 @@ GLFWAPI void glfwSwapInterval(int interval);
 /*! @brief Returns whether the specified extension is available.
  *
  *  This function returns whether the specified
- *  [OpenGL or context creation API extension](@ref glext) is supported by the
- *  current context.  For example, on Windows both the OpenGL and WGL extension
- *  strings are checked.
+ *  [OpenGL or context creation API extension](@ref context_glext) is supported
+ *  by the current context.  For example, on Windows both the OpenGL and WGL
+ *  extension strings are checked.
  *
  *  @param[in] extension The ASCII encoded name of the extension.
  *  @return `GL_TRUE` if the extension is available, or `GL_FALSE` otherwise.
@@ -2160,8 +2123,8 @@ GLFWAPI int glfwExtensionSupported(const char* extension);
  *  context.
  *
  *  This function returns the address of the specified
- *  [client API or extension function](@ref glext), if it is supported by the
- *  current context.
+ *  [client API or extension function](@ref context_glext), 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