Merge branch 'master' into multi-monitor

Conflicts:
	include/GL/glfw3.h
	readme.html
	src/CMakeLists.txt
	src/win32_window.c
	src/window.c
	src/x11_window.c
	tests/clipboard.c
	tests/defaults.c
	tests/events.c
	tests/fsfocus.c
	tests/glfwinfo.c
	tests/joysticks.c
	tests/peter.c
	tests/sharing.c
	tests/tearing.c
	tests/title.c
	tests/windows.c

examples/gears.c

@@ -359,8 +359,6 @@ int main(int argc, char *argv[])
     glfwGetWindowSize(window, &width, &height);
     reshape(window, width, height);
 
-    glfwSetInputMode( window, GLFW_KEY_REPEAT, GL_TRUE );
-
     // Parse command-line options
     init(argc, argv);
 

examples/wave.c

@@ -419,8 +419,6 @@ int main(int argc, char* argv[])
     glfwGetWindowSize(window, &width, &height);
     window_size_callback(window, width, height);
 
-    glfwSetInputMode(window, GLFW_KEY_REPEAT, GL_TRUE);
-
     // Initialize OpenGL
     init_opengl();
 

include/GL/glfw3.h

@@ -35,13 +35,48 @@ extern "C" {
 #endif
 
 
+/*************************************************************************
+ * Doxygen documentation
+ *************************************************************************/
+
+/*! @mainpage notitle
+ *
+ *  @section intro Introduction
+ *
+ *  This is the reference documentation for the GLFW library.
+ */
+
+/*! @defgroup clipboard Clipboard support
+ */
+/*! @defgroup error Error handling
+ */
+/*! @defgroup gamma Gamma ramp support
+ */
+/*! @defgroup init Initialization and version information
+ */
+/*! @defgroup input Input handling
+ */
+/*! @defgroup opengl OpenGL support
+ */
+/*! @defgroup time Time input
+ */
+/*! @defgroup window Window handling
+ *
+ *  The primary purpose of GLFW is to provide a simple interface to OpenGL
+ *  context creation and window management.  GLFW supports multiple windows,
+ *  which can be either a normal desktop window or a fullscreen window.
+ */
+/*! @defgroup monitor Monitor handling
+ */
+
+
 /*************************************************************************
  * Global definitions
  *************************************************************************/
 
 /* ------------------- BEGIN SYSTEM/COMPILER SPECIFIC -------------------- */
 
-/* Please report any probles that you find with your compiler, which may
+/* Please report any problems that you find with your compiler, which may
  * be solved in this section! There are several compilers that I have not
  * been able to test this file with yet.
  *
@@ -166,18 +201,46 @@ extern "C" {
  * GLFW version
  *************************************************************************/
 
+/*! @name GLFW version macros
+ *  @{ */
+/*! @brief The major version number of the GLFW library.
+ *
+ *  This is incremented when the API is changed in non-compatible ways.
+ *  @ingroup init
+ */
 #define GLFW_VERSION_MAJOR    3
+/*! @brief The minor version number of the GLFW library.
+ *
+ *  This is incremented when features are added to the API but it remains
+ *  backward-compatible.
+ *  @ingroup init
+ */
 #define GLFW_VERSION_MINOR    0
+/*! @brief The revision number of the GLFW library.
+ *
+ *  This is incremented when a bug fix release is made that does not contain any
+ *  API changes.
+ *  @ingroup init
+ */
 #define GLFW_VERSION_REVISION 0
+/*! @} */
 
 
 /*************************************************************************
  * Input handling definitions
  *************************************************************************/
 
-/* Key and button state/action definitions */
+/*! @name Key and button actions
+ *  @{ */
+/*! @brief The key or button was released.
+ *  @ingroup input
+ */
 #define GLFW_RELEASE            0
+/*! @brief The key or button was pressed.
+ *  @ingroup input
+ */
 #define GLFW_PRESS              1
+/*! @} */
 
 /* Keyboard raw key codes.
  * These key codes are inspired by the USB HID Usage Tables v1.12 (p. 53-60),
@@ -195,6 +258,11 @@ extern "C" {
  *    "BACKSPACE", etc).
  */
 
+/*! @defgroup keys Keyboard keys
+ *  @ingroup input
+ *  @{
+ */
+
 /* Printable keys */
 #define GLFW_KEY_SPACE                  32
 #define GLFW_KEY_APOSTROPHE             39  /* ' */
@@ -335,7 +403,11 @@ extern "C" {
 #define GLFW_KEY_RALT           GLFW_KEY_RIGHT_ALT
 #define GLFW_KEY_RSUPER         GLFW_KEY_RIGHT_SUPER
 
-/* Mouse button definitions */
+/*! @} */
+
+/*! @defgroup buttons Mouse buttons
+ *  @ingroup input
+ *  @{ */
 #define GLFW_MOUSE_BUTTON_1      0
 #define GLFW_MOUSE_BUTTON_2      1
 #define GLFW_MOUSE_BUTTON_3      2
@@ -345,13 +417,14 @@ extern "C" {
 #define GLFW_MOUSE_BUTTON_7      6
 #define GLFW_MOUSE_BUTTON_8      7
 #define GLFW_MOUSE_BUTTON_LAST   GLFW_MOUSE_BUTTON_8
-
-/* Mouse button aliases */
 #define GLFW_MOUSE_BUTTON_LEFT   GLFW_MOUSE_BUTTON_1
 #define GLFW_MOUSE_BUTTON_RIGHT  GLFW_MOUSE_BUTTON_2
 #define GLFW_MOUSE_BUTTON_MIDDLE GLFW_MOUSE_BUTTON_3
+/*! @} */
 
-/* Joystick identifiers */
+/*! @defgroup joysticks Joysticks
+ *  @ingroup input
+ *  @{ */
 #define GLFW_JOYSTICK_1          0
 #define GLFW_JOYSTICK_2          1
 #define GLFW_JOYSTICK_3          2
@@ -369,36 +442,75 @@ extern "C" {
 #define GLFW_JOYSTICK_15         14
 #define GLFW_JOYSTICK_16         15
 #define GLFW_JOYSTICK_LAST       GLFW_JOYSTICK_16
+/*! @} */
 
 
 /*************************************************************************
  * Other definitions
  *************************************************************************/
 
-/* glfwGetWindowParam tokens */
-#define GLFW_ACTIVE               0x00020001
+/*! @defgroup paramhints Window parameters and hints
+ *  @ingroup window
+ *  @{ */
+
+/*! @brief @c GL_TRUE if the window has focus, or @c GL_FALSE otherwise.
+ */
+#define GLFW_FOCUSED              0x00020001
+/*! @brief @c GL_TRUE if the window is iconified, or @c GL_FALSE otherwise.
+ */
 #define GLFW_ICONIFIED            0x00020002
+/*! @brief @c GL_TRUE if the window has been requested to close, or @c GL_FALSE
+ *  otherwise.
+ */
 #define GLFW_CLOSE_REQUESTED      0x00020003
+/*! @brief The OpenGL API version revision.
+ */
 #define GLFW_OPENGL_REVISION      0x00020004
 
-/* glfwWindowHint tokens */
+/*! @brief The bit depth of the red component of the color buffer.
+ */
 #define GLFW_RED_BITS             0x00021000
+/*! @brief The bit depth of the green component of the color buffer.
+ */
 #define GLFW_GREEN_BITS           0x00021001
+/*! @brief The bit depth of the blue component of the color buffer.
+ */
 #define GLFW_BLUE_BITS            0x00021002
+/*! @brief The bit depth of the alpha component of the color buffer.
+ */
 #define GLFW_ALPHA_BITS           0x00021003
+/*! @brief The bit depth of the depth buffer of the default framebuffer.
+ */
 #define GLFW_DEPTH_BITS           0x00021004
+/*! @brief The bit depth of the stencil buffer of the default framebuffer.
+ */
 #define GLFW_STENCIL_BITS         0x00021005
+/*! @brief The monitor refresh rate.
+ */
 #define GLFW_REFRESH_RATE         0x00021006
+/*! @brief The bit depth of the red component of the accumulation buffer.
+ */
 #define GLFW_ACCUM_RED_BITS       0x00021007
+/*! @brief The bit depth of the red component of the accumulation buffer.
+ */
 #define GLFW_ACCUM_GREEN_BITS     0x00021008
+/*! @brief The bit depth of the red component of the accumulation buffer.
+ */
 #define GLFW_ACCUM_BLUE_BITS      0x00021009
+/*! @brief The bit depth of the red component of the accumulation buffer.
+ */
 #define GLFW_ACCUM_ALPHA_BITS     0x0002100A
+/*! @brief The number of auxiliary buffers.
+ */
 #define GLFW_AUX_BUFFERS          0x0002100B
+/*! @brief @c GL_TRUE for stereo rendering, or @c GL_FALSE otherwise.
+ */
 #define GLFW_STEREO               0x0002100C
+/*! @brief The number of samples used for default framebuffer multisampling.
+ */
 #define GLFW_FSAA_SAMPLES         0x0002100E
 
-/* The following constants are used with both glfwGetWindowParam
- * and glfwWindowHint
+/*! @brief The @link clients client API @endlink to create a context for.
  */
 #define GLFW_CLIENT_API           0x00022000
 #define GLFW_OPENGL_VERSION_MAJOR 0x00022001
@@ -407,54 +519,160 @@ extern "C" {
 #define GLFW_OPENGL_DEBUG_CONTEXT 0x00022004
 #define GLFW_OPENGL_PROFILE       0x00022005
 #define GLFW_OPENGL_ROBUSTNESS    0x00022006
+/*! @brief @c GL_TRUE if the window is resizable, or @c GL_FALSE otherwise.
+ */
 #define GLFW_RESIZABLE            0x00022007
+/*! @brief @c GL_TRUE if the window is visible, or @c GL_FALSE otherwise.
+ */
 #define GLFW_VISIBLE              0x00022008
+/*! @brief The x-coordinate, in pixels, of the upper-left corner of the
+ *  client area of the window.
+ */
+#define GLFW_POSITION_X           0x00022009
+/*! @brief The y-coordinate, in pixels, of the upper-left corner of the
+ *  client area of the window.
+ */
+#define GLFW_POSITION_Y           0x0002200A
+
+/*! @} */
 
-/* GLFW_CLIENT_API tokens */
+/*! @name Client APIs
+ *  @{ */
+/*! @brief The OpenGL API.
+ *  @ingroup opengl
+ */
 #define GLFW_OPENGL_API           0x00000001
+/*! @brief The OpenGL ES API.
+ *  @ingroup opengl
+ */
 #define GLFW_OPENGL_ES_API        0x00000002
+/*! @} */
 
-/* GLFW_OPENGL_ROBUSTNESS mode tokens */
+/*! @name OpenGL robustness strategies
+ *  @{ */
+/*! @brief No robustness strategy is used.
+ *
+ *  This is the default.
+ *  @ingroup opengl
+ */
 #define GLFW_OPENGL_NO_ROBUSTNESS         0x00000000
+/*! @brief 
+ *  @ingroup opengl
+ */
 #define GLFW_OPENGL_NO_RESET_NOTIFICATION 0x00000001
+/*! @brief 
+ *  @ingroup opengl
+ */
 #define GLFW_OPENGL_LOSE_CONTEXT_ON_RESET 0x00000002
+/*! @} */
 
-/* GLFW_OPENGL_PROFILE bit tokens */
+/*! @name OpenGL profiles
+ *  @{ */
+/*! @brief No OpenGL profile.
+ *  @ingroup opengl
+ */
 #define GLFW_OPENGL_NO_PROFILE    0x00000000
+/*! @brief The OpenGL core profile.
+ *  @ingroup opengl
+ */
 #define GLFW_OPENGL_CORE_PROFILE  0x00000001
+/*! @brief The OpenGL compatibility profile.
+ *  @ingroup opengl
+ */
 #define GLFW_OPENGL_COMPAT_PROFILE 0x00000002
+/*! @} */
 
-/* glfwGetInputMode/glfwSetInputMode tokens */
+/*! @name Input modes
+ *  @{ */
+/*! @brief The behaviour of the cursor.
+ *  @ingroup input
+ */
 #define GLFW_CURSOR_MODE          0x00030001
+/*! @brief Whether the @ref glfwGetKey function uses sticky state.
+ *  @ingroup input
+ */
 #define GLFW_STICKY_KEYS          0x00030002
+/*! @brief Whether the @ref glfwGetMouseButton function uses sticky state.
+ *  @ingroup input
+ */
 #define GLFW_STICKY_MOUSE_BUTTONS 0x00030003
-#define GLFW_SYSTEM_KEYS          0x00030004
-#define GLFW_KEY_REPEAT           0x00030005
+/*! @} */
 
-/* GLFW_CURSOR_MODE values */
+/*! @name Cursor modes
+ *  @{ */
+/*! @brief The cursor is visible and behaves normally.
+ *  @ingroup input
+ */
 #define GLFW_CURSOR_NORMAL       0x00040001
+/*! @brief The cursor is hidden when over the client area of the window.
+ *  @ingroup input
+ */
 #define GLFW_CURSOR_HIDDEN       0x00040002
+/*! @brief The cursor is disabled and cursor movement is unbounded.
+ *  @ingroup input
+ */
 #define GLFW_CURSOR_CAPTURED     0x00040003
+/*! @} */
 
-/* glfwGetJoystickParam tokens */
+/*! @name Joystick parameters
+ *  @{ */
+/*! @brief @c GL_TRUE if the joystick is present, or @c GL_FALSE otherwise.
+ *  @ingroup input
+ */
 #define GLFW_PRESENT              0x00050001
+/*! @brief The number of axes on the specified joystick, or zero if the joystick
+ *  is not present.
+ *  @ingroup input
+ */
 #define GLFW_AXES                 0x00050002
+/*! @brief The number of buttons on the specified joystick, or zero if the
+ *  joystick is not present.
+ *  @ingroup input
+ */
 #define GLFW_BUTTONS              0x00050003
+/*! @} */
 
-/* glfwGetError/glfwErrorString tokens */
+/*! @defgroup errors Error codes
+ *  @ingroup error
+ *  @{ */
+/*! @brief No error has occurred.
+ */
 #define GLFW_NO_ERROR             0
+/*! @brief GLFW has not been initialized.
+ */
 #define GLFW_NOT_INITIALIZED      0x00070001
+/*! @brief No context is current for this thread.
+ */
 #define GLFW_NO_CURRENT_CONTEXT   0x00070002
+/*! @brief One of the enum parameters for the function was given an invalid
+ *  enum.
+ */
 #define GLFW_INVALID_ENUM         0x00070003
+/*! @brief One of the parameters for the function was given an invalid value.
+ */
 #define GLFW_INVALID_VALUE        0x00070004
+/*! @brief A memory allocation failed.
+ */
 #define GLFW_OUT_OF_MEMORY        0x00070005
-#define GLFW_OPENGL_UNAVAILABLE   0x00070006
+/*! @brief GLFW could not find support for the requested client API on the
+ *  system.
+ */
+#define GLFW_API_UNAVAILABLE      0x00070006
+/*! @brief The requested OpenGL or GLES version is not available.
+ */
 #define GLFW_VERSION_UNAVAILABLE  0x00070007
+/*! @brief A platform-specific error occurred that does not match any of the
+ *  more specific categories.
+ */
 #define GLFW_PLATFORM_ERROR       0x00070008
-#define GLFW_WINDOW_NOT_ACTIVE    0x00070009
-#define GLFW_FORMAT_UNAVAILABLE   0x0007000A
+/*! @brief The clipboard did not contain data in the requested format.
+ */
+#define GLFW_FORMAT_UNAVAILABLE   0x00070009
+/*! @} */
 
-/* Gamma ramps */
+/*! @brief The number of entries in the gamma ramp.
+ *  @ingroup gamma
+ */
 #define GLFW_GAMMA_RAMP_SIZE      256
 
 /* Monitor constants */
@@ -469,31 +687,119 @@ extern "C" {
  * Typedefs
  *************************************************************************/
 
-/* OpenGL function pointer type */
+/*! @brief OpenGL function pointer type.
+ *  @ingroup opengl
+ */
 typedef void (*GLFWglproc)(void);
 
-/* Monitor handle type */
+/*! @brief Monitor handle type.
+ *  @ingroup monitor
+ */
 typedef void* GLFWmonitor;
 
-/* Window handle type */
+/*! @brief Window handle type.
+ *  @ingroup window
+ */
 typedef void* GLFWwindow;
 
-/* Function pointer types */
+/*! @brief The function signature for error callbacks.
+ *  @param[in] error An @link errors error code @endlink.
+ *  @param[in] description A UTF-8 encoded string describing the error.
+ *  @ingroup error
+ */
 typedef void (* GLFWerrorfun)(int,const char*);
+
+/*! @brief The function signature for window resize callbacks.
+ *  @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.
+ *  @ingroup window
+ */
 typedef void (* GLFWwindowsizefun)(GLFWwindow,int,int);
-typedef int  (* GLFWwindowclosefun)(GLFWwindow);
+
+/*! @brief The function signature for window close callbacks.
+ *  @param[in] window The window that the user attempted to close.
+ *  @return @c GL_TRUE to allow the window to be closed, or @c GL_FALSE to
+ *  ignore the attempt.
+ *  @ingroup window
+ */
+typedef int (* GLFWwindowclosefun)(GLFWwindow);
+
+/*! @brief The function signature for window content refresh callbacks.
+ *  @param[in] window The window whose content needs to be refreshed.
+ *  @ingroup window
+ */
 typedef void (* GLFWwindowrefreshfun)(GLFWwindow);
+
+/*! @brief The function signature for window focus/defocus callbacks.
+ *  @param[in] window The window that was focused or defocused.
+ *  @param[in] focused @c GL_TRUE if the window was focused, or @c GL_FALSE if
+ *  it was defocused.
+ *  @ingroup window
+ */
 typedef void (* GLFWwindowfocusfun)(GLFWwindow,int);
+
+/*! @brief The function signature for window iconify/restore callbacks.
+ *  @param[in] window The window that was iconified or restored.
+ *  @param[in] iconified @c GL_TRUE if the window was iconified, or @c GL_FALSE
+ *  if it was restored.
+ *  @ingroup window
+ */
 typedef void (* GLFWwindowiconifyfun)(GLFWwindow,int);
+
+/*! @brief The function signature for mouse button callbacks.
+ *  @param[in] window The window that received the event.
+ *  @param[in] button The @link buttons mouse button @endlink that was pressed
+ *  or released.
+ *  @param[in] action @ref GLFW_PRESS or @ref GLFW_RELEASE.
+ *  @ingroup input
+ */
 typedef void (* GLFWmousebuttonfun)(GLFWwindow,int,int);
+
+/*! @brief The function signature for cursor position callbacks.
+ *  @param[in] window The window that received the event.
+ *  @param[in] x The new x-coordinate of the cursor.
+ *  @param[in] y The new y-coordinate of the cursor.
+ *  @ingroup input
+ */
 typedef void (* GLFWcursorposfun)(GLFWwindow,int,int);
+
+/*! @brief The function signature for cursor enter/exit callbacks.
+ *  @param[in] window The window that received the event.
+ *  @param[in] entered @c GL_TRUE if the cursor entered the window's client
+ *  area, or @c GL_FALSE if it left it.
+ *  @ingroup input
+ */
 typedef void (* GLFWcursorenterfun)(GLFWwindow,int);
+
+/*! @brief The function signature for scroll callbacks.
+ *  @param[in] window The window that received the event.
+ *  @param[in] x The scroll offset along the x-axis.
+ *  @param[in] y The scroll offset along the y-axis.
+ *  @ingroup input
+ */
 typedef void (* GLFWscrollfun)(GLFWwindow,double,double);
+
+/*! @brief The function signature for keyboard key callbacks.
+ *  @param[in] window The window that received the event.
+ *  @param[in] key The @link keys keyboard key @endlink that was pressed or
+ *  released.
+ *  @param[in] action @ref GLFW_PRESS or @ref GLFW_RELEASE.
+ *  @ingroup input
+ */
 typedef void (* GLFWkeyfun)(GLFWwindow,int,int);
+
+/*! @brief The function signature for Unicode character callbacks.
+ *  @param[in] window The window that received the event.
+ *  @param[in] character The Unicode code point of the character.
+ *  @ingroup input
+ */
 typedef void (* GLFWcharfun)(GLFWwindow,int);
 typedef void (* GLFWmonitorfun)(GLFWmonitor,int);
 
-/* The video mode structure used by glfwGetVideoModes */
+/* @brief Video mode type.
+ * @ingroup monitor
+ */
 typedef struct
 {
     int width;
@@ -503,7 +809,9 @@ typedef struct
     int greenBits;
 } GLFWvidmode;
 
-/* Gamma ramp */
+/*! @brief Gamma ramp.
+ *  @ingroup gamma
+ */
 typedef struct
 {
     unsigned short red[GLFW_GAMMA_RAMP_SIZE];
@@ -516,99 +824,809 @@ typedef struct
  * Prototypes
  *************************************************************************/
 
-/* Initialization, termination and version querying */
-GLFWAPI int  glfwInit(void);
+/*! @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.
+ *
+ *  @return @c GL_TRUE if successful, or @c GL_FALSE if an error occurred.
+ *  @ingroup init
+ *
+ *  @remarks Additional calls to this function after successful initialization
+ *  but before termination will succeed but will do nothing.
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @note This function may take several seconds to complete on some systems,
+ *  while on other systems it may take only a fraction of a second to complete.
+ *
+ *  @note On Mac OS X, this function will change the current directory of the
+ *  application to the @c Contents/Resources subdirectory of the application's
+ *  bundle, if present.
+ *
+ *  @sa glfwTerminate
+ */
+GLFWAPI int glfwInit(void);
+
+/*! @brief Terminates the GLFW library.
+ *  @ingroup init
+ *
+ *  @remarks This function may be called before @ref glfwInit.
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @note This function closes all GLFW windows.
+ *
+ *  @note This function should be called before the program exits.
+ *
+ *  @warning No window's context may be current on another thread when this
+ *  function is called.
+ *
+ *  @sa glfwInit
+ */
 GLFWAPI void glfwTerminate(void);
+
+/*! @brief Retrieves the version of the GLFW library.
+ *  @param[out] major Where to store the major version number, or @c NULL.
+ *  @param[out] minor Where to store the minor version number, or @c NULL.
+ *  @param[out] rev Where to store the revision number, or @c NULL.
+ *  @ingroup init
+ *
+ *  @remarks This function may be called before @ref glfwInit.
+ *
+ *  @remarks This function may be called from secondary threads.
+ *
+ *  @sa glfwGetVersionString
+ */
 GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev);
+
+/*! @brief Returns the version string of the GLFW library.
+ *
+ *  The version string contains information about what compile-time options were
+ *  enabled when the library was built.
+ *
+ *  @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.
+ *
+ *  @sa glfwGetVersion
+ */
 GLFWAPI const char* glfwGetVersionString(void);
 
-/* Error handling */
+/*! @brief Retrieves the latest error.
+ *  @return The latest @link errors error code @endlink.
+ *  @ingroup error
+ *
+ *  @remarks This function may be called before @ref glfwInit.
+ */
 GLFWAPI int glfwGetError(void);
+
+/*! @brief Retrieves a generic, human readable description of the specified error.
+ *  @param[in] error The @link errors error code @endlink to be described.
+ *  @return A UTF-8 encoded string describing the error.
+ *  @ingroup error
+ *
+ *  @remarks This function may be called before @ref glfwInit.
+ *
+ *  @remarks This function may be called from secondary threads.
+ */
 GLFWAPI const char* glfwErrorString(int error);
+
+/*! @brief Sets the error callback.
+ *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
+ *  callback.
+ *  @ingroup error
+ *
+ *  @remarks This function may be called before @ref glfwInit.
+ *
+ *  @remarks The error callback is the preferred error retrieval mechanism, as
+ *  it may be provided with a more specific error description than the generic
+ *  one returned by @ref glfwErrorString.
+ *
+ *  @note Because the description string provided to the callback may have been
+ *  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.
+ */
 GLFWAPI void glfwSetErrorCallback(GLFWerrorfun cbfun);
 
-/* Monitor functions */
+/*! @ingroup monitor
+ */
 GLFWAPI GLFWmonitor* glfwGetMonitors(int* count);
+
+/*! @ingroup monitor
+ */
 GLFWAPI GLFWmonitor glfwGetPrimaryMonitor(void);
+
+/*! @ingroup monitor
+ */
 GLFWAPI int  glfwGetMonitorParam(GLFWmonitor monitor, int param);
+
+/*! @ingroup monitor
+ */
 GLFWAPI const char* glfwGetMonitorName(GLFWmonitor monitor);
+
+/*! @ingroup monitor
+ */
 GLFWAPI void glfwSetMonitorUserPointer(GLFWmonitor monitor, void* pointer);
+
+/*! @ingroup monitor
+ */
 GLFWAPI void* glfwGetMonitorUserPointer(GLFWmonitor monitor);
+
+/*! @ingroup monitor
+ */
 GLFWAPI void glfwSetMonitorCallback(GLFWmonitorfun cbfun);
 
-/* Video mode functions */
+/*! @brief Returns the available video modes for the specified monitor.
+ *  @ingroup monitor
+ */
 GLFWAPI GLFWvidmode* glfwGetVideoModes(GLFWmonitor monitor, int* count);
+
+/*! @ingroup monitor
+ */
 GLFWAPI void glfwGetVideoMode(GLFWmonitor monitor, GLFWvidmode* mode);
 
-/* Gamma ramp functions */
+/*! @brief Sets the system gamma ramp to one generated from the specified
+ *  exponent.
+ *  @param[in] The desired exponent.
+ *  @ingroup gamma
+ */
 GLFWAPI void glfwSetGamma(float gamma);
+
+/*! @brief Retrieves the current system gamma ramp.
+ *  @param[out] ramp Where to store the gamma ramp.
+ *  @ingroup gamma
+ */
 GLFWAPI void glfwGetGammaRamp(GLFWgammaramp* ramp);
+
+/*! @brief Sets the system gamma ramp to the one specified.
+ *  @param[in] ramp The gamma ramp to use.
+ *  @ingroup gamma
+ */
 GLFWAPI void glfwSetGammaRamp(const GLFWgammaramp* ramp);
 
-/* Window handling */
+/*! @brief Resets all window hints to their default values
+ *
+ *  The @ref GLFW_RED_BITS, @ref GLFW_GREEN_BITS, @ref GLFW_BLUE_BITS, @ref
+ *  GLFW_ALPHA_BITS and @ref GLFW_STENCIL_BITS hints are set to 8.
+ *
+ *  The @ref GLFW_DEPTH_BITS hint is set to 24.
+ *
+ *  The @ref GLFW_VISIBLE and @ref GLFW_RESIZABLE hints are set to 1.
+ *
+ *  The @ref GLFW_CLIENT_API hint is set to @ref GLFW_OPENGL_API.
+ *
+ *  The @ref GLFW_OPENGL_VERSION_MAJOR and @ref GLFW_OPENGL_VERSION_MINOR hints
+ *  are set to 1 and 0, respectively.
+ *
+ *  All other hints are set to 0.
+ *
+ *  @ingroup window
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @sa glfwWindowHint
+ */
 GLFWAPI void glfwDefaultWindowHints(void);
+
+/*! @brief Sets the specified window hint to the desired value.
+ *  @param[in] target The window hint to set.
+ *  @param[in] target The new value of the window hint.
+ *  @ingroup window
+ *
+ *  The @ref GLFW_RED_BITS, @ref GLFW_GREEN_BITS, @ref GLFW_BLUE_BITS, @ref
+ *  GLFW_ALPHA_BITS, @ref GLFW_DEPTH_BITS and @ref GLFW_STENCIL_BITS hints
+ *  specify the desired bit depths of the various components of the default
+ *  framebuffer.
+ *
+ *  The @ref GLFW_REFRESH_RATE hint specifies the desired monitor refresh rate
+ *  for fullscreen windows.
+ *
+ *  The @ref GLFW_ACCUM_RED_BITS, @ref GLFW_ACCUM_GREEN_BITS, @ref
+ *  GLFW_ACCUM_BLUE_BITS and @ref GLFW_ACCUM_ALPHA_BITS hints specify the
+ *  desired bit depths of the various components of the accumulation buffer.
+ *
+ *  The @ref GLFW_AUX_BUFFERS hint specifies the desired number of auxiliary
+ *  buffers.
+ *
+ *  The @ref GLFW_STEREO hint specifies whether to use stereoscopic rendering.
+ *
+ *  The @ref GLFW_FSAA_SAMPLES hint specifies the desired number of samples to
+ *  use for multisampling.
+ *
+ *  The @ref GLFW_CLIENT_API hint specifies which client API to create the
+ *  context for.  Possible values are @ref GLFW_OPENGL_API and @ref
+ *  GLFW_OPENGL_ES_API.
+ *
+ *  The @ref GLFW_OPENGL_VERSION_MAJOR and @ref GLFW_OPENGL_VERSION_MINOR hints
+ *  specify the OpenGL version that the created context must be compatible with.
+ *
+ *  These hints are @em 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 with hints.  It is therefore
+ *  perfectly safe to use the default of version 1.0 for legacy code and you
+ *  will still get backwards-compatible contexts of version 3.0 and above when
+ *  available.
+ *
+ *  The @ref GLFW_OPENGL_FORWARD_COMPAT hint specifies whether the OpenGL
+ *  context should be forward-compatible.
+ *
+ *  The @ref GLFW_OPENGL_DEBUG_CONTEXT hint specifies whether to create a debug
+ *  OpenGL context.
+ *
+ *  The @ref GLFW_OPENGL_PROFILE hint specifies which OpenGL profile to create
+ *  the context for.  Possible values are @ref GLFW_OPENGL_NO_PROFILE, @ref
+ *  GLFW_OPENGL_CORE_PROFILE and @ref GLFW_OPENGL_COMPAT_PROFILE.
+ *
+ *  The @ref GLFW_OPENGL_ROBUSTNESS hint specifies the robustness strategy to be
+ *  used by the OpenGL context.
+ *
+ *  The @ref GLFW_RESIZABLE hint specifies whether the window will be resizable
+ *  by the user.  This hint is ignored for fullscreen windows.
+ *
+ *  The @ref GLFW_VISIBLE hint specifies whether the window will be initially
+ *  visible.  This hint is ignored for fullscreen windows.
+ *
+ *  The @ref GLFW_POSITION_X and @ref GLFW_POSITION_Y hints specify the initial
+ *  position of the window.  These hints are ignored for fullscreen windows.
+ *
+ *  Some window hints are hard constraints.  These must match the available
+ *  capabilities @em exactly for window and context creation to succeed.  Hints
+ *  that are not hard constraints are matched as closely as possible, but the
+ *  resulting window and context may differ from what these hints requested.
+ *
+ *  The following window hints are hard constraints:
+ *  @arg @ref GLFW_STEREO
+ *  @arg @ref GLFW_CLIENT_API
+ *  @arg @ref GLFW_OPENGL_FORWARD_COMPAT
+ *  @arg @ref GLFW_OPENGL_PROFILE
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @sa glfwDefaultWindowHints
+ */
 GLFWAPI void glfwWindowHint(int target, int hint);
+
+/*! @brief Creates a window and its associated context.
+ *
+ *  @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] title The initial, UTF-8 encoded window title.
+ *  @param[in] monitor The monitor to use for fullscreen mode, or @c NULL to use
+ *  windowed mode.
+ *  @param[in] share The window whose context to share resources with, or @c
+ *  NULL to not share resources.
+ *  @return The handle of the created window, or @c 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 For fullscreen windows the initial cursor mode is @ref
+ *  GLFW_CURSOR_CAPTURED and the screensaver is prohibited from starting.  For
+ *  regular windows the initial cursor mode is @ref GLFW_CURSOR_NORMAL and the
+ *  screensaver is allowed to start.
+ *
+ *  @remarks In order to determine the actual properties of an opened window,
+ *  use @ref glfwGetWindowParam and @ref glfwGetWindowSize.
+ *
+ *  @remarks On Microsoft Windows, if the executable has an icon resource named
+ *  @c GLFW_ICON, it will be set as the icon for the window.  If no such icon is
+ *  present, the @c IDI_WINLOGO icon will be used instead.
+ *
+ *  @remarks On Mac OS X the GLFW window has no icon, but programs using GLFW
+ *  will use the application bundle's icon.  Also, the first time a window is
+ *  opened the menu bar is populated with common commands like Hide, Quit and
+ *  About.  The (minimal) about dialog uses information from the application's
+ *  bundle.  For more information on bundles, see the Bundle Programming Guide
+ *  provided by Apple.
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @sa glfwDestroyWindow
+ */
 GLFWAPI GLFWwindow glfwCreateWindow(int width, int height, const char* title, GLFWmonitor monitor, GLFWwindow share);
+
+/*! @brief Destroys the specified window and its context.
+ *  @param[in] window The window to destroy.
+ *  @ingroup window
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @note If the window's context is current on the main thread, it is
+ *  detached before being destroyed.
+ *
+ *  @warning The window's context must not be current on any other thread.
+ *
+ *  @sa glfwCreateWindow
+ */
 GLFWAPI void glfwDestroyWindow(GLFWwindow window);
+
+/*! @brief Sets the title 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.
+ */
 GLFWAPI void glfwSetWindowTitle(GLFWwindow window, const char* title);
+
+/*! @brief Retrieves the size 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
+ */
 GLFWAPI void glfwGetWindowSize(GLFWwindow window, int* width, int* height);
+
+/*! @brief Sets the size 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.
+ *
+ *  @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
+ */
 GLFWAPI void glfwSetWindowSize(GLFWwindow window, int width, int height);
-GLFWAPI void glfwGetWindowPos(GLFWwindow window, int* xpos, int* ypos);
-GLFWAPI void glfwSetWindowPos(GLFWwindow window, int xpos, int ypos);
+
+/*! @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.
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @sa glfwRestoreWindow
+ */
 GLFWAPI void glfwIconifyWindow(GLFWwindow window);
+
+/*! @brief Restores the specified window.
+ *  @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.
+ *
+ *  @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
+ *  function does nothing.
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @sa glfwHideWindow
+ */
 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.
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @sa glfwShowWindow
+ */
 GLFWAPI void glfwHideWindow(GLFWwindow window);
-GLFWAPI int  glfwGetWindowParam(GLFWwindow window, int param);
+
+/*! @ingroup window
+ */
 GLFWAPI GLFWmonitor glfwGetWindowMonitor(GLFWwindow window);
+
+/*! @brief Returns a property of the specified window.
+ *  @param[in] window The window to query.
+ *  @param[in] param The property whose value to return.
+ *  @ingroup window
+ *
+ *  The @ref GLFW_FOCUSED property indicates whether the window is focused.
+ *
+ *  The @ref GLFW_ICONIFIED property indicates whether the window is iconified.
+ *
+ *  The @ref GLFW_VISIBLE property indicates whether the window is visible.
+ *
+ *  The @ref GLFW_RESIZABLE property indicates whether the window is resizable
+ *  by the user.
+ *
+ *  The @ref GLFW_CLOSE_REQUESTED property indicates whether the window has been
+ *  requested by the user to close.
+ *
+ *  The @ref GLFW_REFRESH_RATE property will be replaced when the @c
+ *  multi-monitor branch is merged.
+ *
+ *  The @ref GLFW_POSITION_X and @ref GLFW_POSITION_Y properties indicate the
+ *  screen position, in pixels, of the upper-left corner of the window's client
+ *  area.
+ *
+ *  The @ref GLFW_CLIENT_API property indicates the client API provided by the
+ *  window's context.
+ *
+ *  The @ref GLFW_OPENGL_VERSION_MAJOR, @ref GLFW_OPENGL_VERSION_MINOR and @ref
+ *  GLFW_OPENGL_REVISION properties indicate the API version of the window's
+ *  context.
+ *
+ *  The @ref GLFW_OPENGL_FORWARD_COMPAT property indicates whether an OpenGL
+ *  context is forward-compatible.
+ *
+ *  The @ref GLFW_OPENGL_DEBUG_CONTEXT property indicates whether the
+ *  corresponding window hint was used when the window was created.
+ *
+ *  The @ref GLFW_OPENGL_PROFILE property indicates the profile used by the
+ *  OpenGL context, or @ref GLFW_OPENGL_NO_PROFILE if the context is for another
+ *  client API than OpenGL.
+ *
+ *  The @ref GLFW_OPENGL_ROBUSTNESS property indicates the robustness strategy
+ *  used by the OpenGL context, or @ref GLFW_OPENGL_NO_ROBUSTNESS if robustness
+ *  is not used.
+ */
+GLFWAPI int glfwGetWindowParam(GLFWwindow window, int param);
+
+/*! @brief Sets the user pointer of the specified window.
+ *  @param[in] window The window whose pointer to set.
+ *  @param[in] pointer The new value.
+ *  @ingroup window
+ *
+ *  @sa glfwGetWindowUserPointer
+ */
 GLFWAPI void glfwSetWindowUserPointer(GLFWwindow window, void* pointer);
+
+/*! @brief Returns the user pointer of the specified window.
+ *  @param[in] window The window whose pointer to return.
+ *  @ingroup window
+ *
+ *  @sa glfwSetWindowUserPointer
+ */
 GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow window);
+
+/*! @brief Sets the size callback for the specified window.
+ *  @param[in] window The window whose callback to set.
+ *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
+ *  callback.
+ *  @ingroup window
+ */
 GLFWAPI void glfwSetWindowSizeCallback(GLFWwindow window, GLFWwindowsizefun cbfun);
+
+/*! @brief Sets the close callback for the specified window.
+ *  @param[in] window The window whose callback to set.
+ *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
+ *  callback.
+ *  @ingroup window
+ */
 GLFWAPI void glfwSetWindowCloseCallback(GLFWwindow window, GLFWwindowclosefun cbfun);
+
+/*! @brief Sets the refresh callback for the specified window.
+ *  @param[in] window The window whose callback to set.
+ *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
+ *  callback.
+ *  @ingroup window
+ */
 GLFWAPI void glfwSetWindowRefreshCallback(GLFWwindow window, GLFWwindowrefreshfun cbfun);
+
+/*! @brief Sets the focus callback for the specified window.
+ *  @param[in] window The window whose callback to set.
+ *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
+ *  callback.
+ *  @ingroup window
+ */
 GLFWAPI void glfwSetWindowFocusCallback(GLFWwindow window, GLFWwindowfocusfun cbfun);
+
+/*! @brief Sets the iconify callback for the specified window.
+ *  @param[in] window The window whose callback to set.
+ *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
+ *  callback.
+ *  @ingroup window
+ */
 GLFWAPI void glfwSetWindowIconifyCallback(GLFWwindow window, GLFWwindowiconifyfun cbfun);
 
-/* Event handling */
+/*! @brief Processes all pending events.
+ *  @ingroup window
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @sa glfwWaitEvents
+ */
 GLFWAPI void glfwPollEvents(void);
+
+/*! @brief Waits until events are pending and processes them.
+ *  @ingroup window
+ *
+ *  @note This function may only be called from the main thread.
+ *
+ *  @sa glfwPollEvents
+ */
 GLFWAPI void glfwWaitEvents(void);
 
-/* Input handling */
-GLFWAPI int  glfwGetInputMode(GLFWwindow window, int mode);
+/*! @brief Returns the value of an input option for the specified window.
+ *  @param[in] window The window to query.
+ *  @param[in] mode One of the following:
+ *  @arg @ref GLFW_CURSOR_MODE Sets the cursor mode.
+ *  @arg @ref GLFW_STICKY_KEYS Sets whether sticky keys are enabled.
+ *  @arg @ref GLFW_STICKY_MOUSE_BUTTONS Sets whether sticky mouse buttons are enabled.
+ *  @ingroup input
+ *
+ *  @sa glfwSetInputMode
+ */
+GLFWAPI int glfwGetInputMode(GLFWwindow window, int mode);
+
+/*! @brief Sets an input option for the specified window.
+ *  @param[in] mode One of the following:
+ *  @arg @ref GLFW_CURSOR_MODE Sets the cursor mode.
+ *  @arg @ref GLFW_STICKY_KEYS Sets whether sticky keys are enabled.
+ *  @arg @ref GLFW_STICKY_MOUSE_BUTTONS Sets whether sticky mouse buttons are enabled.
+ *  @ingroup input
+ *
+ *  @sa glfwGetInputMode
+ */
 GLFWAPI void glfwSetInputMode(GLFWwindow window, int mode, int value);
-GLFWAPI int  glfwGetKey(GLFWwindow window, int key);
-GLFWAPI int  glfwGetMouseButton(GLFWwindow window, int button);
+
+/*! @brief Returns the last reported state of a keyboard key for the specified
+ *  window.
+ *  @param[in] window The desired window.
+ *  @param[in] key The desired @link keys keyboard key @endlink.
+ *  @return @ref GLFW_PRESS or @ref 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.
+ *  @param[in] window The desired window.
+ *  @param[in] key The desired @link buttons mouse buttons @endlink.
+ *  @return @ref GLFW_PRESS or @ref 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.
+ *  @param[in] window The desired window.
+ *  @param[out] xpos The cursor x-coordinate, relative to the left edge of the
+ *  client area, or @c NULL.
+ *  @param[out] ypos The cursor y-coordinate, relative to the to top edge of the
+ *  client area, or @c NULL.
+ *  @ingroup input
+ *
+ *  @sa glfwSetCursorPos
+ */
 GLFWAPI void glfwGetCursorPos(GLFWwindow window, int* xpos, int* ypos);
+
+/*! @brief Sets the position of the cursor, relative to the client area of the window.
+ *  @param[in] window The desired window.
+ *  @param[in] xpos The desired x-coordinate, relative to the left edge of the
+ *  client area, or @c NULL.
+ *  @param[in] ypos The desired y-coordinate, relative to the top edge of the
+ *  client area, or @c NULL.
+ *  @ingroup input
+ *
+ *  @note The specified window must be focused.
+ *
+ *  @sa glfwGetCursorPos
+ */
 GLFWAPI void glfwSetCursorPos(GLFWwindow window, int xpos, int ypos);
+
+/*! @ingroup input
+ */
 GLFWAPI void glfwGetScrollOffset(GLFWwindow window, double* xoffset, double* yoffset);
+
+/*! @brief Sets the key callback.
+ *  @param[in] cbfun The new key callback, or @c NULL to remove the currently
+ *  set callback.
+ *  @ingroup input
+ *
+ *  @note The key callback deals with physical keys, with @link keys tokens
+ *  @endlink named after their use on the standard US keyboard layout.  If you
+ *  want to input text, use the Unicode character callback instead.
+ */
 GLFWAPI void glfwSetKeyCallback(GLFWwindow window, GLFWkeyfun cbfun);
+
+/*! @brief Sets the Unicode character callback.
+ *  @param[in] cbfun The new Unicode character callback, or @c NULL to remove
+ *  the currently set callback.
+ *  @ingroup input
+ *
+ *  @note 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.
+ */
 GLFWAPI void glfwSetCharCallback(GLFWwindow window, GLFWcharfun cbfun);
+
+/*! @brief Sets the mouse button callback.
+ *  @param[in] cbfun The new mouse button callback, or @c NULL to remove the
+ *  currently set callback.
+ *  @ingroup input
+ */
 GLFWAPI void glfwSetMouseButtonCallback(GLFWwindow window, GLFWmousebuttonfun cbfun);
+
+/*! @brief Sets the cursor position callback.
+ *  @param[in] cbfun The new cursor position callback, or @c NULL to remove the
+ *  currently set callback.
+ *  @ingroup input
+ */
 GLFWAPI void glfwSetCursorPosCallback(GLFWwindow window, GLFWcursorposfun cbfun);
+
+/*! @brief Sets the cursor enter/exit callback.
+ *  @param[in] cbfun The new cursor enter/exit callback, or @c NULL to remove
+ *  the currently set callback.
+ *  @ingroup input
+ */
 GLFWAPI void glfwSetCursorEnterCallback(GLFWwindow window, GLFWcursorenterfun cbfun);
+
+/*! @brief Sets the scroll callback.
+ *  @param[in] cbfun The new scroll callback, or @c NULL to remove the currently
+ *  set callback.
+ *  @ingroup input
+ *
+ *  @note This receives all scrolling input, like that from a mouse wheel or
+ *  a touchpad scrolling area.
+ */
 GLFWAPI void glfwSetScrollCallback(GLFWwindow window, GLFWscrollfun cbfun);
 
-/* Joystick input */
+/*! @brief Returns a property of the specified joystick.
+ *  @param[in] joy The joystick to query.
+ *  @param[in] param The property 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.
+ *  @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 @p axes.
+ *  @ingroup input
+ */
 GLFWAPI int glfwGetJoystickAxes(int joy, float* axes, int numaxes);
+
+/*! @brief Returns the values 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 @p buttons.
+ *  @ingroup input
+ */
 GLFWAPI int glfwGetJoystickButtons(int joy, unsigned char* buttons, int numbuttons);
 
-/* Clipboard */
+/*! @brief Sets the clipboard to the specified string.
+ *  @param[in] window The window that will own the clipboard contents.
+ *  @param[in] string A UTF-8 encoded string.
+ *  @ingroup clipboard
+ *
+ *  @sa glfwGetClipboardString
+ */
 GLFWAPI void glfwSetClipboardString(GLFWwindow window, const char* string);
+
+/*! @brief Retrieves the contents of the clipboard as a 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 @c NULL
+ *  if that format was unavailable.
+ *  @ingroup clipboard
+ *
+ *  @note The returned string is valid only until the next call to @ref
+ *  glfwGetClipboardString or @ref glfwSetClipboardString.
+ *
+ *  @sa glfwSetClipboardString
+ */
 GLFWAPI const char* glfwGetClipboardString(GLFWwindow window);
 
-/* Time */
+/*! @brief Retrieves the current value of the GLFW timer.
+ *  @return The current value, in seconds.
+ *  @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.
+ */
 GLFWAPI double glfwGetTime(void);
-GLFWAPI void   glfwSetTime(double time);
 
-/* OpenGL support */
+/*! @brief Sets the GLFW timer.
+ *  @param[in] time The new value, in seconds.
+ *  @ingroup time
+ *
+ *  @note The resolution of the timer is system dependent.
+ */
+GLFWAPI void glfwSetTime(double time);
+
+/*! @brief Makes the context of the specified window current for this thread.
+ *  @param[in] window The window whose context to make current, or @c NULL to
+ *  detach the current context.
+ *  @ingroup opengl
+ *
+ *  @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.
+ *  @return The window whose context is current, or @c NULL if no window's
+ *  context is current.
+ *  @ingroup opengl
+ *
+ *  @remarks This function may be called from secondary threads.
+ *
+ *  @sa glfwMakeContextCurrent
+ */
 GLFWAPI GLFWwindow glfwGetCurrentContext(void);
-GLFWAPI void  glfwSwapBuffers(GLFWwindow window);
-GLFWAPI void  glfwSwapInterval(int interval);
-GLFWAPI int   glfwExtensionSupported(const char* extension);
+
+/*! @brief Swaps the front and back buffers of the specified window.
+ *  @param[in] The window whose buffers to swap.
+ *  @ingroup opengl
+ *
+ *  @remarks This function may be called from secondary threads.
+ *
+ *  @sa glfwSwapInterval
+ */
+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
+ *  until the buffers are swapped by @ref glfwSwapBuffers.
+ *  @ingroup opengl
+ *
+ *  @remarks This function may be called from secondary threads.
+ *
+ *  @sa glfwSwapBuffers
+ */
+GLFWAPI void glfwSwapInterval(int interval);
+
+/*! @brief Checks whether the specified extension is available.
+ *  @param[in] extension The ASCII encoded name of the extension.
+ *  @return @c GL_TRUE if the extension is available, or @c FALSE otherwise.
+ *  @ingroup opengl
+ *
+ *  @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.
+ */
+GLFWAPI int glfwExtensionSupported(const char* extension);
+
+/*! @brief Returns the address of the specified client API function for the
+ *  current context.
+ *  @param[in] procname The ASCII encoded name of the function.
+ *  @return The address of the function, or @c NULL if the function is
+ *  unavailable.
+ *  @ingroup opengl
+ *
+ *  @remarks This function may be called from secondary threads.
+ */
 GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname);
-GLFWAPI void  glfwCopyContext(GLFWwindow src, GLFWwindow dst, unsigned long mask);
 
 
 /*************************************************************************

readme.html

@@ -285,7 +285,6 @@ version of GLFW.</p>
   <li>Added <code>glfwSetWindowIconifyCallback</code> function and <code>GLFWwindowiconifyfun</code> type for receiving window iconification events</li>
   <li>Added <code>glfwGetClipboardString</code> and <code>glfwSetClipboardString</code> functions for interacting with the system clipboard</li>
   <li>Added <code>glfwGetCurrentContext</code> function for retrieving the window whose OpenGL context is current</li>
-  <li>Added <code>glfwCopyContext</code> function for copying OpenGL state categories between contexts</li>
   <li>Added <code>GLFW_CLIENT_API</code>, <code>GLFW_OPENGL_API</code> and <code>GLFW_OPENGL_ES_API</code> for selecting client API</li>
   <li>Added <code>GLFW_OPENGL_ROBUSTNESS</code> window hint and associated strategy tokens for <code>GL_ARB_robustness</code> support</li>
   <li>Added <code>GLFW_OPENGL_REVISION</code> window parameter to make up for removal of <code>glfwGetGLVersion</code></li>
@@ -304,6 +303,7 @@ version of GLFW.</p>
   <li>Changed <code>glfwGetVideoModes</code> to return a dynamic, unlimited number of video modes for the specified monitor</li>
   <li>Renamed <code>glfw.h</code> to <code>glfw3.h</code> to avoid conflicts with 2.x series</li>
   <li>Renamed <code>glfwOpenWindowHint</code> to <code>glfwWindowHint</code></li>
+  <li>Renamed <code>GLFW_ACTIVE</code> to <code>GLFW_FOCUSED</code></li>
   <li>Renamed <code>GLFW_WINDOW_NO_RESIZE</code> to <code>GLFW_RESIZABLE</code></li>
   <li>Renamed <code>GLFW_BUILD_DLL</code> to <code>_GLFW_BUILD_DLL</code></li>
   <li>Renamed <code>version</code> test to <code>glfwinfo</code></li>
@@ -318,7 +318,7 @@ version of GLFW.</p>
   <li>Replaced <code>glfwEnable</code> and <code>glfwDisable</code> with <code>glfwGetInputMode</code> and <code>glfwSetInputMode</code></li>
   <li>Replaced <code>joystick</code> test with graphical version</li>
   <li>Replaced automatic closing of windows with <code>GLFW_CLOSE_REQUESTED</code> window parameter</li>
-  <li>Made Unicode character input unaffected by <code>GLFW_KEY_REPEAT</code></li>
+  <li>Removed the <code>GLFW_KEY_REPEAT</code> input option</li>
   <li>Removed event auto-polling and the <code>GLFW_AUTO_POLL_EVENTS</code> window enable</li>
   <li>Removed the Win32 port .def files</li>
   <li>Removed the entire threading API</li>
@@ -944,8 +944,9 @@ their skills.  Special thanks go out to:</p>
   Leopard</li>
 
   <li>Riku Salminen, for the initial implementation of
-  <code>glfwShowWindow</code> and <code>glfwHideWindow</code>, and for making
-  the X11 event processing able to support multi-threaded rendering</li>
+  <code>glfwShowWindow</code> and <code>glfwHideWindow</code>, for the idea of
+  <code>glfwDefaultWindowHints</code> and for making the X11 event processing
+  able to support multi-threaded rendering</li>
 
   <li>Douglas C. Schmidt and Irfan Pyarali, for their excellent article
   <a href="http://www.cs.wustl.edu/~schmidt/win32-cv-1.html">Strategies for Implementing POSIX Condition Variables on Win32</a></li>

src/CMakeLists.txt

@@ -14,7 +14,7 @@ set(common_SOURCES clipboard.c gamma.c init.c input.c joystick.c monitor.c
 if (_GLFW_COCOA_NSGL)
     set(glfw_HEADERS ${common_HEADERS} cocoa_platform.h)
     set(glfw_SOURCES ${common_SOURCES} cocoa_clipboard.m cocoa_gamma.c
-                     cocoa_init.m cocoa_input.m cocoa_joystick.m cocoa_monitor.m
+                     cocoa_init.m cocoa_joystick.m cocoa_monitor.m
                      cocoa_opengl.m cocoa_time.c cocoa_window.m)
 
     if (GLFW_NATIVE_API)
@@ -26,7 +26,7 @@ if (_GLFW_COCOA_NSGL)
 elseif (_GLFW_WIN32_WGL)
     set(glfw_HEADERS ${common_HEADERS} win32_platform.h)
     set(glfw_SOURCES ${common_SOURCES} win32_clipboard.c win32_gamma.c
-                     win32_init.c win32_input.c win32_joystick.c win32_monitor.c
+                     win32_init.c win32_joystick.c win32_monitor.c
                      win32_opengl.c win32_time.c win32_window.c)
 
     if (GLFW_NATIVE_API)
@@ -35,8 +35,8 @@ elseif (_GLFW_WIN32_WGL)
 elseif (_GLFW_X11_GLX)
     set(glfw_HEADERS ${common_HEADERS} x11_platform.h)
     set(glfw_SOURCES ${common_SOURCES} x11_clipboard.c x11_gamma.c x11_init.c
-                     x11_input.c x11_joystick.c x11_keysym2unicode.c
-                     x11_monitor.c x11_opengl.c x11_time.c x11_window.c)
+                     x11_joystick.c x11_keysym2unicode.c x11_monitor.c
+                     x11_opengl.c x11_time.c x11_window.c)
 
     if (GLFW_NATIVE_API)
         list(APPEND glfw_SOURCES x11_native.c)

src/cocoa_input.m

@@ -1,53 +0,0 @@
-//========================================================================
-// GLFW - An OpenGL library
-// Platform:    Cocoa
-// API Version: 3.0
-// WWW:         http://www.glfw.org/
-//------------------------------------------------------------------------
-// Copyright (c) 2009-2010 Camilla Berglund <[email protected]>
-//
-// This software is provided 'as-is', without any express or implied
-// warranty. In no event will the authors be held liable for any damages
-// arising from the use of this software.
-//
-// Permission is granted to anyone to use this software for any purpose,
-// including commercial applications, and to alter it and redistribute it
-// freely, subject to the following restrictions:
-//
-// 1. The origin of this software must not be misrepresented; you must not
-//    claim that you wrote the original software. If you use this software
-//    in a product, an acknowledgment in the product documentation would
-//    be appreciated but is not required.
-//
-// 2. Altered source versions must be plainly marked as such, and must not
-//    be misrepresented as being the original software.
-//
-// 3. This notice may not be removed or altered from any source
-//    distribution.
-//
-//========================================================================
-
-#include "internal.h"
-
-
-//////////////////////////////////////////////////////////////////////////
-//////                       GLFW platform API                      //////
-//////////////////////////////////////////////////////////////////////////
-
-//========================================================================
-// Enable and disable system keys
-//========================================================================
-
-void _glfwPlatformEnableSystemKeys(_GLFWwindow* window)
-{
-    // This is checked in cocoa_window.m; no action needed here
-}
-
-void _glfwPlatformDisableSystemKeys(_GLFWwindow* window)
-{
-    // This is checked in cocoa_window.m; no action needed here
-
-    // Note that it may not be possible to disable things like Exposé
-    // except in full-screen mode.
-}
-

src/cocoa_opengl.m

@@ -147,13 +147,3 @@ GLFWglproc _glfwPlatformGetProcAddress(const char* procname)
     return symbol;
 }
 
-
-//========================================================================
-// Copies the specified OpenGL state categories from src to dst
-//========================================================================
-
-void _glfwPlatformCopyContext(_GLFWwindow* src, _GLFWwindow* dst, unsigned long mask)
-{
-    [dst->NSGL.context copyAttributesFromContext:src->NSGL.context withMask:mask];
-}
-

src/cocoa_window.m

@@ -455,8 +455,7 @@ static int convertMacKeyCode(unsigned int macKeyCode)
 
         if ([event modifierFlags] & NSCommandKeyMask)
         {
-            if (window->systemKeys)
-                [super keyDown:event];
+            [super keyDown:event];
         }
         else
         {
@@ -686,7 +685,7 @@ static GLboolean createWindow(_GLFWwindow* window,
     }
 
     window->NS.object = [[NSWindow alloc]
-        initWithContentRect:NSMakeRect(0, 0, window->width, window->height)
+        initWithContentRect:NSMakeRect(wndconfig->positionX, wndconfig->positionY, window->width, window->height)
                   styleMask:styleMask
                     backing:NSBackingStoreBuffered
                       defer:NO];
@@ -1006,27 +1005,6 @@ void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height)
 }
 
 
-//========================================================================
-// Set the window position
-//========================================================================
-
-void _glfwPlatformSetWindowPos(_GLFWwindow* window, int x, int y)
-{
-    NSRect contentRect =
-        [window->NS.object contentRectForFrameRect:[window->NS.object frame]];
-
-    // We assume here that the client code wants to position the window within the
-    // screen the window currently occupies
-    NSRect screenRect = [[window->NS.object screen] visibleFrame];
-    contentRect.origin = NSMakePoint(screenRect.origin.x + x,
-                                     screenRect.origin.y + screenRect.size.height -
-                                         y - contentRect.size.height);
-
-    [window->NS.object setFrame:[window->NS.object frameRectForContentRect:contentRect]
-                        display:YES];
-}
-
-
 //========================================================================
 // Iconify the window
 //========================================================================

src/init.c

@@ -221,21 +221,19 @@ GLFWAPI const char* glfwErrorString(int error)
         case GLFW_NOT_INITIALIZED:
             return "The GLFW library is not initialized";
         case GLFW_NO_CURRENT_CONTEXT:
-            return "There is no current OpenGL context";
+            return "There is no current context";
         case GLFW_INVALID_ENUM:
             return "Invalid argument for enum parameter";
         case GLFW_INVALID_VALUE:
             return "Invalid value for parameter";
         case GLFW_OUT_OF_MEMORY:
             return "Out of memory";
-        case GLFW_OPENGL_UNAVAILABLE:
-            return "OpenGL is not available on this machine";
+        case GLFW_API_UNAVAILABLE:
+            return "The requested client API is unavailable";
         case GLFW_VERSION_UNAVAILABLE:
-            return "The requested OpenGL version is unavailable";
+            return "The requested client API version is unavailable";
         case GLFW_PLATFORM_ERROR:
             return "A platform-specific error occurred";
-        case GLFW_WINDOW_NOT_ACTIVE:
-            return "The specified window is not active";
         case GLFW_FORMAT_UNAVAILABLE:
             return "The requested format is unavailable";
     }

src/input.c

@@ -115,34 +115,6 @@ static void setStickyMouseButtons(_GLFWwindow* window, int enabled)
 }
 
 
-//========================================================================
-// Set system keys for the specified window
-//========================================================================
-
-static void setSystemKeys(_GLFWwindow* window, int enabled)
-{
-    if (window->systemKeys == enabled)
-        return;
-
-    if (enabled)
-        _glfwPlatformEnableSystemKeys(window);
-    else
-        _glfwPlatformDisableSystemKeys(window);
-
-    window->systemKeys = enabled;
-}
-
-
-//========================================================================
-// Set key repeat for the specified window
-//========================================================================
-
-static void setKeyRepeat(_GLFWwindow* window, int enabled)
-{
-    window->keyRepeat = enabled;
-}
-
-
 //////////////////////////////////////////////////////////////////////////
 //////                       GLFW internal API                      //////
 //////////////////////////////////////////////////////////////////////////
@@ -172,7 +144,7 @@ void _glfwInputKey(_GLFWwindow* window, int key, int action)
     }
 
     // Call user callback function
-    if (window->keyCallback && (window->keyRepeat || !repeated))
+    if (window->keyCallback && !repeated)
         window->keyCallback(window, key, action);
 }
 
@@ -295,10 +267,6 @@ GLFWAPI int glfwGetInputMode(GLFWwindow handle, int mode)
             return window->stickyKeys;
         case GLFW_STICKY_MOUSE_BUTTONS:
             return window->stickyMouseButtons;
-        case GLFW_SYSTEM_KEYS:
-            return window->systemKeys;
-        case GLFW_KEY_REPEAT:
-            return window->keyRepeat;
         default:
             _glfwSetError(GLFW_INVALID_ENUM, NULL);
             return 0;
@@ -331,12 +299,6 @@ GLFWAPI void glfwSetInputMode(GLFWwindow handle, int mode, int value)
         case GLFW_STICKY_MOUSE_BUTTONS:
             setStickyMouseButtons(window, value ? GL_TRUE : GL_FALSE);
             break;
-        case GLFW_SYSTEM_KEYS:
-            setSystemKeys(window, value ? GL_TRUE : GL_FALSE);
-            break;
-        case GLFW_KEY_REPEAT:
-            setKeyRepeat(window, value ? GL_TRUE : GL_FALSE);
-            break;
         default:
             _glfwSetError(GLFW_INVALID_ENUM, NULL);
             break;
@@ -445,11 +407,8 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow handle, int xpos, int ypos)
         return;
     }
 
-    if (_glfwLibrary.activeWindow != window)
-    {
-        _glfwSetError(GLFW_WINDOW_NOT_ACTIVE, NULL);
+    if (_glfwLibrary.focusedWindow != window)
         return;
-    }
 
     // Don't do anything if the cursor position did not change
     if (xpos == window->cursorPosX && ypos == window->cursorPosY)

src/internal.h

@@ -108,6 +108,8 @@ struct _GLFWhints
     GLboolean   glDebug;
     int         glProfile;
     int         glRobustness;
+    int         positionX;
+    int         positionY;
 };
 
 
@@ -123,6 +125,8 @@ struct _GLFWwndconfig
     int           refreshRate;
     GLboolean     resizable;
     GLboolean     visible;
+    int           positionX;
+    int           positionY;
     int           clientAPI;
     int           glMajor;
     int           glMinor;
@@ -183,8 +187,6 @@ struct _GLFWwindow
     // Window input state
     GLboolean stickyKeys;
     GLboolean stickyMouseButtons;
-    GLboolean keyRepeat;
-    GLboolean systemKeys;      // system keys enabled flag
     int       cursorPosX, cursorPosY;
     int       cursorMode;
     double    scrollX, scrollY;
@@ -249,7 +251,7 @@ struct _GLFWlibrary
     _GLFWhints    hints;
 
     _GLFWwindow*  windowListHead;
-    _GLFWwindow*  activeWindow;
+    _GLFWwindow*  focusedWindow;
 
     _GLFWmonitor** monitors;
     int            monitorCount;
@@ -322,7 +324,6 @@ int  _glfwPlatformCreateWindow(_GLFWwindow* window, const _GLFWwndconfig* wndcon
 void _glfwPlatformDestroyWindow(_GLFWwindow* window);
 void _glfwPlatformSetWindowTitle(_GLFWwindow* window, const char* title);
 void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height);
-void _glfwPlatformSetWindowPos(_GLFWwindow* window, int x, int y);
 void _glfwPlatformIconifyWindow(_GLFWwindow* window);
 void _glfwPlatformRestoreWindow(_GLFWwindow* window);
 void _glfwPlatformShowWindow(_GLFWwindow* window);
@@ -340,7 +341,6 @@ void _glfwPlatformSwapInterval(int interval);
 void _glfwPlatformRefreshWindowParams(_GLFWwindow* window);
 int  _glfwPlatformExtensionSupported(const char* extension);
 GLFWglproc _glfwPlatformGetProcAddress(const char* procname);
-void _glfwPlatformCopyContext(_GLFWwindow* src, _GLFWwindow* dst, unsigned long mask);
 
 
 //========================================================================
@@ -351,7 +351,7 @@ void _glfwPlatformCopyContext(_GLFWwindow* src, _GLFWwindow* dst, unsigned long
 //========================================================================
 
 // Window event notification (window.c)
-void _glfwInputWindowFocus(_GLFWwindow* window, GLboolean activated);
+void _glfwInputWindowFocus(_GLFWwindow* window, GLboolean focused);
 void _glfwInputWindowPos(_GLFWwindow* window, int x, int y);
 void _glfwInputWindowSize(_GLFWwindow* window, int width, int height);
 void _glfwInputWindowIconify(_GLFWwindow* window, int iconified);

src/opengl.c

@@ -682,32 +682,3 @@ GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname)
     return _glfwPlatformGetProcAddress(procname);
 }
 
-
-//========================================================================
-// Copies the specified OpenGL state categories from src to dst
-//========================================================================
-
-GLFWAPI void glfwCopyContext(GLFWwindow hsrc, GLFWwindow hdst, unsigned long mask)
-{
-    _GLFWwindow* src;
-    _GLFWwindow* dst;
-
-    if (!_glfwInitialized)
-    {
-        _glfwSetError(GLFW_NOT_INITIALIZED, NULL);
-        return;
-    }
-
-    src = (_GLFWwindow*) hsrc;
-    dst = (_GLFWwindow*) hdst;
-
-    if (_glfwPlatformGetCurrentContext() == dst)
-    {
-        _glfwSetError(GLFW_INVALID_VALUE,
-                      "glfwCopyContext: Cannot copy OpenGL state to a current context");
-        return;
-    }
-
-    _glfwPlatformCopyContext(src, dst, mask);
-}
-

src/win32_input.c

@@ -1,132 +0,0 @@
-//========================================================================
-// GLFW - An OpenGL library
-// Platform:    Win32
-// API version: 3.0
-// WWW:         http://www.glfw.org/
-//------------------------------------------------------------------------
-// Copyright (c) 2002-2006 Marcus Geelnard
-// Copyright (c) 2006-2010 Camilla Berglund <[email protected]>
-//
-// This software is provided 'as-is', without any express or implied
-// warranty. In no event will the authors be held liable for any damages
-// arising from the use of this software.
-//
-// Permission is granted to anyone to use this software for any purpose,
-// including commercial applications, and to alter it and redistribute it
-// freely, subject to the following restrictions:
-//
-// 1. The origin of this software must not be misrepresented; you must not
-//    claim that you wrote the original software. If you use this software
-//    in a product, an acknowledgment in the product documentation would
-//    be appreciated but is not required.
-//
-// 2. Altered source versions must be plainly marked as such, and must not
-//    be misrepresented as being the original software.
-//
-// 3. This notice may not be removed or altered from any source
-//    distribution.
-//
-//========================================================================
-
-#include "internal.h"
-
-
-//========================================================================
-// Low level keyboard hook (system callback) function
-// Used to disable system keys under Windows NT
-//========================================================================
-
-static LRESULT CALLBACK keyboardHook(int nCode, WPARAM wParam, LPARAM lParam)
-{
-    BOOL syskeys = FALSE;
-    PKBDLLHOOKSTRUCT p;
-
-    // We are only looking for keyboard events - interpret lParam as a
-    // pointer to a KBDLLHOOKSTRUCT
-    p = (PKBDLLHOOKSTRUCT) lParam;
-
-    if (nCode == HC_ACTION)
-    {
-        // We have a keyboard event
-
-        switch (wParam)
-        {
-            case WM_KEYDOWN:
-            case WM_SYSKEYDOWN:
-            case WM_KEYUP:
-            case WM_SYSKEYUP:
-                // Detect: ALT+TAB, ALT+ESC, ALT+F4, CTRL+ESC,
-                // LWIN, RWIN, APPS (mysterious menu key)
-                syskeys = (p->vkCode == VK_TAB &&
-                           p->flags & LLKHF_ALTDOWN) ||
-                          (p->vkCode == VK_ESCAPE &&
-                           p->flags & LLKHF_ALTDOWN) ||
-                          (p->vkCode == VK_F4 &&
-                           p->flags & LLKHF_ALTDOWN) ||
-                          (p->vkCode == VK_ESCAPE &&
-                           (GetKeyState(VK_CONTROL) & 0x8000)) ||
-                          p->vkCode == VK_LWIN ||
-                          p->vkCode == VK_RWIN ||
-                          p->vkCode == VK_APPS;
-                break;
-
-            default:
-                break;
-        }
-    }
-
-    // Was it a system key combination (e.g. ALT+TAB)?
-    if (syskeys)
-    {
-        _GLFWwindow* window = _glfwLibrary.activeWindow;
-
-        // Pass the key event to our window message loop
-        if (window)
-            PostMessage(window->Win32.handle, (UINT) wParam, p->vkCode, 0);
-
-        // We've taken care of it - don't let the system know about this
-        // key event
-        return 1;
-    }
-    else
-    {
-        // It's a harmless key press, let the system deal with it
-        return CallNextHookEx(_glfwLibrary.Win32.keyboardHook, nCode, wParam, lParam);
-    }
-}
-
-
-//////////////////////////////////////////////////////////////////////////
-//////                       GLFW platform API                      //////
-//////////////////////////////////////////////////////////////////////////
-
-//========================================================================
-// Enable system keys
-//========================================================================
-
-void _glfwPlatformEnableSystemKeys(_GLFWwindow* window)
-{
-    UNREFERENCED_PARAMETER(window);
-
-    if (_glfwLibrary.Win32.keyboardHook != NULL)
-    {
-        UnhookWindowsHookEx(_glfwLibrary.Win32.keyboardHook);
-        _glfwLibrary.Win32.keyboardHook = NULL;
-    }
-}
-
-
-//========================================================================
-// Disable system keys
-//========================================================================
-
-void _glfwPlatformDisableSystemKeys(_GLFWwindow* window)
-{
-    UNREFERENCED_PARAMETER(window);
-
-    _glfwLibrary.Win32.keyboardHook = SetWindowsHookEx(WH_KEYBOARD_LL,
-                                                       keyboardHook,
-                                                       _glfwLibrary.Win32.instance,
-                                                       0);
-}
-

src/win32_opengl.c

@@ -189,7 +189,7 @@ static _GLFWfbconfig* getFBConfigs(_GLFWwindow* window, unsigned int* found)
 
     if (!available)
     {
-        _glfwSetError(GLFW_OPENGL_UNAVAILABLE, "WGL: No pixel formats found");
+        _glfwSetError(GLFW_API_UNAVAILABLE, "WGL: No pixel formats found");
         return NULL;
     }
 
@@ -637,17 +637,3 @@ GLFWglproc _glfwPlatformGetProcAddress(const char* procname)
     return (GLFWglproc) wglGetProcAddress(procname);
 }
 
-
-//========================================================================
-// Copies the specified OpenGL state categories from src to dst
-//========================================================================
-
-void _glfwPlatformCopyContext(_GLFWwindow* src, _GLFWwindow* dst, unsigned long mask)
-{
-    if (!wglCopyContext(src->WGL.context, dst->WGL.context, mask))
-    {
-        _glfwSetError(GLFW_PLATFORM_ERROR,
-                      "WGL: Failed to copy OpenGL context attributes");
-    }
-}
-

src/win32_platform.h

@@ -180,7 +180,6 @@ typedef struct _GLFWlibraryWin32
 {
     HINSTANCE                 instance;     // Instance of the application
     ATOM                      classAtom;    // Window class atom
-    HHOOK                     keyboardHook; // Keyboard hook handle
     DWORD                     foregroundLockTimeout;
     char*                     clipboardString;
 

src/win32_window.c

@@ -327,22 +327,22 @@ static LRESULT CALLBACK windowProc(HWND hWnd, UINT uMsg,
 
         case WM_ACTIVATE:
         {
-            // Window was (de)activated and/or (de)iconified
+            // Window was (de)focused and/or (de)iconified
 
-            BOOL active = LOWORD(wParam) != WA_INACTIVE;
+            BOOL focused = LOWORD(wParam) != WA_INACTIVE;
             BOOL iconified = HIWORD(wParam) ? TRUE : FALSE;
 
-            if (active && iconified)
+            if (focused && iconified)
             {
                 // This is a workaround for window iconification using the
-                // taskbar leading to windows being told they're active and
-                // iconified and then never told they're deactivated
-                active = FALSE;
+                // taskbar leading to windows being told they're focused and
+                // iconified and then never told they're defocused
+                focused = FALSE;
             }
 
-            if (!active && _glfwLibrary.activeWindow == window)
+            if (!focused && _glfwLibrary.focusedWindow == window)
             {
-                // The window was deactivated (or iconified, see above)
+                // The window was defocused (or iconified, see above)
 
                 if (window->cursorMode == GLFW_CURSOR_CAPTURED)
                     showCursor(window);
@@ -363,9 +363,9 @@ static LRESULT CALLBACK windowProc(HWND hWnd, UINT uMsg,
                     }
                 }
             }
-            else if (active && _glfwLibrary.activeWindow != window)
+            else if (focused && _glfwLibrary.focusedWindow != window)
             {
-                // The window was activated
+                // The window was focused
 
                 if (window->cursorMode == GLFW_CURSOR_CAPTURED)
                     captureCursor(window);
@@ -385,7 +385,7 @@ static LRESULT CALLBACK windowProc(HWND hWnd, UINT uMsg,
                 }
             }
 
-            _glfwInputWindowFocus(window, active);
+            _glfwInputWindowFocus(window, focused);
             _glfwInputWindowIconify(window, iconified);
             return 0;
         }
@@ -543,7 +543,7 @@ static LRESULT CALLBACK windowProc(HWND hWnd, UINT uMsg,
 
                 if (window->cursorMode == GLFW_CURSOR_CAPTURED)
                 {
-                    if (_glfwLibrary.activeWindow != window)
+                    if (_glfwLibrary.focusedWindow != window)
                         return 0;
 
                     x = newCursorX - window->Win32.oldCursorX;
@@ -787,8 +787,8 @@ static int createWindow(_GLFWwindow* window,
         SystemParametersInfo(SPI_GETWORKAREA, 0, &wa, 0);
 
         // Adjust window position to working area
-        positionX = wa.left;
-        positionY = wa.top;
+        positionX = wndconfig->positionX + wa.left;
+        positionY = wndconfig->positionY + wa.top;
     }
 
     wideTitle = _glfwCreateWideStringFromUTF8(wndconfig->title);
@@ -842,8 +842,8 @@ static void destroyWindow(_GLFWwindow* window)
 
     // This is duplicated from glfwDestroyWindow
     // TODO: Stop duplicating code
-    if (window == _glfwLibrary.activeWindow)
-        _glfwLibrary.activeWindow = NULL;
+    if (window == _glfwLibrary.focusedWindow)
+        _glfwLibrary.focusedWindow = NULL;
 
     if (window->Win32.handle)
     {
@@ -1071,23 +1071,6 @@ void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height)
 }
 
 
-//========================================================================
-// Set the window position
-//========================================================================
-
-void _glfwPlatformSetWindowPos(_GLFWwindow* window, int x, int y)
-{
-    RECT rect;
-
-    GetClientRect(window->Win32.handle, &rect);
-    AdjustWindowRectEx(&rect, window->Win32.dwStyle, FALSE, window->Win32.dwExStyle);
-
-    SetWindowPos(window->Win32.handle, HWND_TOP,
-                 x + rect.left, y + rect.top, 0, 0,
-                 SWP_NOOWNERZORDER | SWP_NOSIZE | SWP_NOZORDER);
-}
-
-
 //========================================================================
 // Window iconification
 //========================================================================
@@ -1162,7 +1145,7 @@ void _glfwPlatformPollEvents(void)
     MSG msg;
     _GLFWwindow* window;
 
-    window = _glfwLibrary.activeWindow;
+    window = _glfwLibrary.focusedWindow;
     if (window)
     {
         window->Win32.cursorCentered = GL_FALSE;
@@ -1198,7 +1181,7 @@ void _glfwPlatformPollEvents(void)
     // LSHIFT/RSHIFT fixup (keys tend to "stick" without this fix)
     // This is the only async event handling in GLFW, but it solves some
     // nasty problems.
-    window = _glfwLibrary.activeWindow;
+    window = _glfwLibrary.focusedWindow;
     if (window)
     {
         int lshift_down, rshift_down;
@@ -1216,8 +1199,8 @@ void _glfwPlatformPollEvents(void)
             _glfwInputKey(window, GLFW_KEY_RIGHT_SHIFT, GLFW_RELEASE);
     }
 
-    // Did the cursor move in an active window that has captured the cursor
-    window = _glfwLibrary.activeWindow;
+    // Did the cursor move in an focused window that has captured the cursor
+    window = _glfwLibrary.focusedWindow;
     if (window)
     {
         if (window->cursorMode == GLFW_CURSOR_CAPTURED &&

src/window.c

@@ -72,43 +72,43 @@ static void clearScrollOffsets(void)
 // Register window focus events
 //========================================================================
 
-void _glfwInputWindowFocus(_GLFWwindow* window, GLboolean activated)
+void _glfwInputWindowFocus(_GLFWwindow* window, GLboolean focused)
 {
-    if (activated)
+    if (focused)
     {
-        if (_glfwLibrary.activeWindow == window)
-            return;
-
-        _glfwLibrary.activeWindow = window;
+        if (_glfwLibrary.focusedWindow != window)
+        {
+            _glfwLibrary.focusedWindow = window;
 
-        if (window->windowFocusCallback)
-            window->windowFocusCallback(window, activated);
+            if (window->windowFocusCallback)
+                window->windowFocusCallback(window, focused);
+        }
     }
     else
     {
-        int i;
-
-        if (_glfwLibrary.activeWindow != window)
-            return;
-
-        // Release all pressed keyboard keys
-        for (i = 0;  i <= GLFW_KEY_LAST;  i++)
-        {
-            if (window->key[i] == GLFW_PRESS)
-                _glfwInputKey(window, i, GLFW_RELEASE);
-        }
-
-        // Release all pressed mouse buttons
-        for (i = 0;  i <= GLFW_MOUSE_BUTTON_LAST;  i++)
+        if (_glfwLibrary.focusedWindow == window)
         {
-            if (window->mouseButton[i] == GLFW_PRESS)
-                _glfwInputMouseClick(window, i, GLFW_RELEASE);
+            int i;
+
+            // Release all pressed keyboard keys
+            for (i = 0;  i <= GLFW_KEY_LAST;  i++)
+            {
+                if (window->key[i] == GLFW_PRESS)
+                    _glfwInputKey(window, i, GLFW_RELEASE);
+            }
+
+            // Release all pressed mouse buttons
+            for (i = 0;  i <= GLFW_MOUSE_BUTTON_LAST;  i++)
+            {
+                if (window->mouseButton[i] == GLFW_PRESS)
+                    _glfwInputMouseClick(window, i, GLFW_RELEASE);
+            }
+
+            _glfwLibrary.focusedWindow = NULL;
+
+            if (window->windowFocusCallback)
+                window->windowFocusCallback(window, focused);
         }
-
-        _glfwLibrary.activeWindow = NULL;
-
-        if (window->windowFocusCallback)
-            window->windowFocusCallback(window, activated);
     }
 }
 
@@ -238,6 +238,8 @@ GLFWAPI GLFWwindow glfwCreateWindow(int width, int height,
     wndconfig.refreshRate    = Max(_glfwLibrary.hints.refreshRate, 0);
     wndconfig.resizable      = _glfwLibrary.hints.resizable ? GL_TRUE : GL_FALSE;
     wndconfig.visible        = _glfwLibrary.hints.visible ? GL_TRUE : GL_FALSE;
+    wndconfig.positionX      = _glfwLibrary.hints.positionX;
+    wndconfig.positionY      = _glfwLibrary.hints.positionY;
     wndconfig.clientAPI      = _glfwLibrary.hints.clientAPI;
     wndconfig.glMajor        = _glfwLibrary.hints.glMajor;
     wndconfig.glMinor        = _glfwLibrary.hints.glMinor;
@@ -255,22 +257,11 @@ GLFWAPI GLFWwindow glfwCreateWindow(int width, int height,
     // Save the currently current context so it can be restored later
     previous = glfwGetCurrentContext();
 
-    // Check width & height
-    if (width > 0 && height <= 0)
-    {
-        // Set the window aspect ratio to 4:3
-        height = (width * 3) / 4;
-    }
-    else if (width <= 0 && height > 0)
-    {
-        // Set the window aspect ratio to 4:3
-        width = (height * 4) / 3;
-    }
-    else if (width <= 0 && height <= 0)
+    if (width <= 0 || height <= 0)
     {
-        // Default window size
-        width  = 640;
-        height = 480;
+        _glfwSetError(GLFW_INVALID_VALUE,
+                      "glfwCreateWindow: Invalid window size");
+        return GL_FALSE;
     }
 
     window = (_GLFWwindow*) calloc(1, sizeof(_GLFWwindow));
@@ -288,7 +279,6 @@ GLFWAPI GLFWwindow glfwCreateWindow(int width, int height,
     window->height     = height;
     window->resizable  = wndconfig.resizable;
     window->cursorMode = GLFW_CURSOR_NORMAL;
-    window->systemKeys = GL_TRUE;
     window->monitor    = (_GLFWmonitor*) monitor;
 
     // Open the actual window and create its context
@@ -363,6 +353,10 @@ void glfwDefaultWindowHints(void)
     _glfwLibrary.hints.resizable = GL_TRUE;
     _glfwLibrary.hints.visible   = GL_TRUE;
 
+    // The default window position is the upper left corner of the screen
+    _glfwLibrary.hints.positionX = 0;
+    _glfwLibrary.hints.positionY = 0;
+
     // The default is 24 bits of color, 24 bits of depth and 8 bits of stencil
     _glfwLibrary.hints.redBits     = 8;
     _glfwLibrary.hints.greenBits   = 8;
@@ -431,6 +425,12 @@ GLFWAPI void glfwWindowHint(int target, int hint)
         case GLFW_VISIBLE:
             _glfwLibrary.hints.visible = hint;
             break;
+        case GLFW_POSITION_X:
+            _glfwLibrary.hints.positionX = hint;
+            break;
+        case GLFW_POSITION_Y:
+            _glfwLibrary.hints.positionY = hint;
+            break;
         case GLFW_FSAA_SAMPLES:
             _glfwLibrary.hints.samples = hint;
             break;
@@ -485,9 +485,9 @@ GLFWAPI void glfwDestroyWindow(GLFWwindow handle)
     if (window == _glfwPlatformGetCurrentContext())
         _glfwPlatformMakeContextCurrent(NULL);
 
-    // Clear the active window pointer if this is the active window
-    if (window == _glfwLibrary.activeWindow)
-        _glfwLibrary.activeWindow = NULL;
+    // Clear the focused window pointer if this is the focused window
+    if (window == _glfwLibrary.focusedWindow)
+        _glfwLibrary.focusedWindow = NULL;
 
     _glfwPlatformDestroyWindow(window);
 
@@ -580,52 +580,6 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow handle, int width, int height)
 }
 
 
-//========================================================================
-// Get the window position
-//========================================================================
-
-GLFWAPI void glfwGetWindowPos(GLFWwindow handle, int* xpos, int* ypos)
-{
-    _GLFWwindow* window = (_GLFWwindow*) handle;
-
-    if (!_glfwInitialized)
-    {
-        _glfwSetError(GLFW_NOT_INITIALIZED, NULL);
-        return;
-    }
-
-    if (xpos != NULL)
-        *xpos = window->positionX;
-
-    if (ypos != NULL)
-        *ypos = window->positionY;
-}
-
-
-//========================================================================
-// Set the window position
-//========================================================================
-
-GLFWAPI void glfwSetWindowPos(GLFWwindow handle, int xpos, int ypos)
-{
-    _GLFWwindow* window = (_GLFWwindow*) handle;
-
-    if (!_glfwInitialized)
-    {
-        _glfwSetError(GLFW_NOT_INITIALIZED, NULL);
-        return;
-    }
-
-    if (window->monitor || window->iconified)
-    {
-        // TODO: Figure out if this is an error
-        return;
-    }
-
-    _glfwPlatformSetWindowPos(window, xpos, ypos);
-}
-
-
 //========================================================================
 // Window iconification
 //========================================================================
@@ -729,8 +683,8 @@ GLFWAPI int glfwGetWindowParam(GLFWwindow handle, int param)
 
     switch (param)
     {
-        case GLFW_ACTIVE:
-            return window == _glfwLibrary.activeWindow;
+        case GLFW_FOCUSED:
+            return window == _glfwLibrary.focusedWindow;
         case GLFW_ICONIFIED:
             return window->iconified;
         case GLFW_CLOSE_REQUESTED:
@@ -741,6 +695,10 @@ GLFWAPI int glfwGetWindowParam(GLFWwindow handle, int param)
             return window->resizable;
         case GLFW_VISIBLE:
             return window->visible;
+        case GLFW_POSITION_X:
+            return window->positionX;
+        case GLFW_POSITION_Y:
+            return window->positionY;
         case GLFW_CLIENT_API:
             return window->clientAPI;
         case GLFW_OPENGL_VERSION_MAJOR:

src/x11_init.c

@@ -491,7 +491,7 @@ static GLboolean initDisplay(void)
     _glfwLibrary.X11.display = XOpenDisplay(NULL);
     if (!_glfwLibrary.X11.display)
     {
-        _glfwSetError(GLFW_OPENGL_UNAVAILABLE, "X11: Failed to open X display");
+        _glfwSetError(GLFW_API_UNAVAILABLE, "X11: Failed to open X display");
         return GL_FALSE;
     }
 

src/x11_input.c

@@ -1,65 +0,0 @@
-//========================================================================
-// GLFW - An OpenGL library
-// Platform:    X11
-// API version: 3.0
-// WWW:         http://www.glfw.org/
-//------------------------------------------------------------------------
-// Copyright (c) 2002-2006 Marcus Geelnard
-// Copyright (c) 2006-2010 Camilla Berglund <[email protected]>
-//
-// This software is provided 'as-is', without any express or implied
-// warranty. In no event will the authors be held liable for any damages
-// arising from the use of this software.
-//
-// Permission is granted to anyone to use this software for any purpose,
-// including commercial applications, and to alter it and redistribute it
-// freely, subject to the following restrictions:
-//
-// 1. The origin of this software must not be misrepresented; you must not
-//    claim that you wrote the original software. If you use this software
-//    in a product, an acknowledgment in the product documentation would
-//    be appreciated but is not required.
-//
-// 2. Altered source versions must be plainly marked as such, and must not
-//    be misrepresented as being the original software.
-//
-// 3. This notice may not be removed or altered from any source
-//    distribution.
-//
-//========================================================================
-
-#include "internal.h"
-
-
-//////////////////////////////////////////////////////////////////////////
-//////                       GLFW platform API                      //////
-//////////////////////////////////////////////////////////////////////////
-
-//========================================================================
-// Enable system keys
-//========================================================================
-
-void _glfwPlatformEnableSystemKeys(_GLFWwindow* window)
-{
-    if (window->X11.keyboardGrabbed)
-    {
-        XUngrabKeyboard(_glfwLibrary.X11.display, CurrentTime);
-        window->X11.keyboardGrabbed = GL_FALSE;
-    }
-}
-
-
-//========================================================================
-// Disable system keys
-//========================================================================
-
-void _glfwPlatformDisableSystemKeys(_GLFWwindow* window)
-{
-    if (XGrabKeyboard(_glfwLibrary.X11.display, window->X11.handle,
-                      True, GrabModeAsync, GrabModeAsync, CurrentTime)
-        == GrabSuccess)
-    {
-        window->X11.keyboardGrabbed = GL_TRUE;
-    }
-}
-

src/x11_opengl.c

@@ -93,7 +93,7 @@ static _GLFWfbconfig* getFBConfigs(_GLFWwindow* window, unsigned int* found)
     {
         if (!_glfwLibrary.GLX.SGIX_fbconfig)
         {
-            _glfwSetError(GLFW_OPENGL_UNAVAILABLE,
+            _glfwSetError(GLFW_API_UNAVAILABLE,
                           "GLX: GLXFBConfig support not found");
             return NULL;
         }
@@ -103,8 +103,8 @@ static _GLFWfbconfig* getFBConfigs(_GLFWwindow* window, unsigned int* found)
 
     if (strcmp(vendor, "Chromium") == 0)
     {
-        // This is a (hopefully temporary) workaround for Chromium (VirtualBox
-        // GL) not setting the window bit on any GLXFBConfigs
+        // HACK: This is a (hopefully temporary) workaround for Chromium
+        // (VirtualBox GL) not setting the window bit on any GLXFBConfigs
         trustWindowBit = GL_FALSE;
     }
 
@@ -116,7 +116,7 @@ static _GLFWfbconfig* getFBConfigs(_GLFWwindow* window, unsigned int* found)
                                                         &count);
         if (!count)
         {
-            _glfwSetError(GLFW_OPENGL_UNAVAILABLE,
+            _glfwSetError(GLFW_API_UNAVAILABLE,
                           "GLX: No GLXFBConfigs returned");
             return NULL;
         }
@@ -128,7 +128,7 @@ static _GLFWfbconfig* getFBConfigs(_GLFWwindow* window, unsigned int* found)
                                     &count);
         if (!count)
         {
-            _glfwSetError(GLFW_OPENGL_UNAVAILABLE,
+            _glfwSetError(GLFW_API_UNAVAILABLE,
                           "GLX: No GLXFBConfigs returned");
             return NULL;
         }
@@ -465,7 +465,7 @@ int _glfwInitOpenGL(void)
     // Check if GLX is supported on this display
     if (!glXQueryExtension(_glfwLibrary.X11.display, NULL, NULL))
     {
-        _glfwSetError(GLFW_OPENGL_UNAVAILABLE, "GLX: GLX support not found");
+        _glfwSetError(GLFW_API_UNAVAILABLE, "GLX: GLX support not found");
         return GL_FALSE;
     }
 
@@ -473,8 +473,7 @@ int _glfwInitOpenGL(void)
                          &_glfwLibrary.GLX.majorVersion,
                          &_glfwLibrary.GLX.minorVersion))
     {
-        _glfwSetError(GLFW_OPENGL_UNAVAILABLE,
-                      "GLX: Failed to query GLX version");
+        _glfwSetError(GLFW_API_UNAVAILABLE, "GLX: Failed to query GLX version");
         return GL_FALSE;
     }
 
@@ -732,16 +731,3 @@ GLFWglproc _glfwPlatformGetProcAddress(const char* procname)
     return _glfw_glXGetProcAddress((const GLubyte*) procname);
 }
 
-
-//========================================================================
-// Copies the specified OpenGL state categories from src to dst
-//========================================================================
-
-void _glfwPlatformCopyContext(_GLFWwindow* src, _GLFWwindow* dst, unsigned long mask)
-{
-    glXCopyContext(_glfwLibrary.X11.display,
-                   src->GLX.context,
-                   dst->GLX.context,
-                   mask);
-}
-

src/x11_platform.h

@@ -138,12 +138,17 @@ typedef struct _GLFWwindowX11
 
     // Various platform specific internal variables
     GLboolean     overrideRedirect; // True if window is OverrideRedirect
-    GLboolean     keyboardGrabbed;  // True if keyboard is currently grabbed
     GLboolean     cursorGrabbed;    // True if cursor is currently grabbed
     GLboolean     cursorHidden;     // True if cursor is currently hidden
     GLboolean     cursorCentered;   // True if cursor was moved since last poll
     int           cursorPosX, cursorPosY;
 
+    // Window position hint (commited the first time the window is shown)
+    GLboolean     windowPosSet;     // False until the window position has
+                                    // been set
+    int           positionX;        // The window position to be set the
+    int           positionY;        // first time the window is shown
+
 } _GLFWwindowX11;
 
 

src/x11_window.c

@@ -119,7 +119,7 @@ static GLboolean createWindow(_GLFWwindow* window,
 
         window->X11.handle = XCreateWindow(_glfwLibrary.X11.display,
                                            _glfwLibrary.X11.root,
-                                           0, 0,
+                                           wndconfig->positionX, wndconfig->positionY,
                                            window->width, window->height,
                                            0,              // Border width
                                            visual->depth,  // Color depth
@@ -136,6 +136,12 @@ static GLboolean createWindow(_GLFWwindow* window,
             _glfwSetError(GLFW_PLATFORM_ERROR, "X11: Failed to create window");
             return GL_FALSE;
         }
+
+        // Request a window position to be set once the window is shown
+        // (see _glfwPlatformShowWindow)
+        window->X11.windowPosSet = GL_FALSE;
+        window->X11.positionX = wndconfig->positionX;
+        window->X11.positionY = wndconfig->positionY;
     }
 
     if (window->monitor && !_glfwLibrary.X11.hasEWMH)
@@ -633,7 +639,7 @@ static void processEvent(XEvent *event)
 
                 if (window->cursorMode == GLFW_CURSOR_CAPTURED)
                 {
-                    if (_glfwLibrary.activeWindow != window)
+                    if (_glfwLibrary.focusedWindow != window)
                         break;
 
                     x = event->xmotion.x - window->X11.cursorPosX;
@@ -1016,16 +1022,6 @@ void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height)
 }
 
 
-//========================================================================
-// Set the window position.
-//========================================================================
-
-void _glfwPlatformSetWindowPos(_GLFWwindow* window, int x, int y)
-{
-    XMoveWindow(_glfwLibrary.X11.display, window->X11.handle, x, y);
-}
-
-
 //========================================================================
 // Window iconification
 //========================================================================
@@ -1070,6 +1066,15 @@ void _glfwPlatformShowWindow(_GLFWwindow* window)
 {
     XMapRaised(_glfwLibrary.X11.display, window->X11.handle);
     XFlush(_glfwLibrary.X11.display);
+
+    // Set the window position the first time the window is shown
+    // Note: XMoveWindow has no effect before the window has been mapped.
+    if (!window->X11.windowPosSet)
+    {
+        XMoveWindow(_glfwLibrary.X11.display, window->X11.handle,
+                    window->X11.positionX, window->X11.positionY);
+        window->X11.windowPosSet = GL_TRUE;
+    }
 }
 
 
@@ -1123,11 +1128,11 @@ void _glfwPlatformPollEvents(void)
         processEvent(&event);
     }
 
-    // Check whether the cursor has moved inside an active window that has
+    // Check whether the cursor has moved inside an focused window that has
     // captured the cursor (because then it needs to be re-centered)
 
     _GLFWwindow* window;
-    window = _glfwLibrary.activeWindow;
+    window = _glfwLibrary.focusedWindow;
     if (window)
     {
         if (window->cursorMode == GLFW_CURSOR_CAPTURED &&

tests/clipboard.c

@@ -125,7 +125,7 @@ int main(int argc, char** argv)
         exit(EXIT_FAILURE);
     }
 
-    window = glfwCreateWindow(0, 0, "Clipboard Test", NULL, NULL);
+    window = glfwCreateWindow(200, 200, "Clipboard Test", NULL, NULL);
     if (!window)
     {
         glfwTerminate();

tests/defaults.c

@@ -85,7 +85,7 @@ int main(void)
 
     glfwWindowHint(GLFW_VISIBLE, GL_FALSE);
 
-    window = glfwCreateWindow(0, 0, "Defaults", NULL, NULL);
+    window = glfwCreateWindow(640, 480, "Defaults", NULL, NULL);
     if (!window)
     {
         glfwTerminate();

tests/events.c

@@ -41,8 +41,6 @@
 #include <locale.h>
 
 // These must match the input mode defaults
-static GLboolean keyrepeat  = GL_FALSE;
-static GLboolean systemkeys = GL_TRUE;
 static GLboolean closeable = GL_TRUE;
 
 // Event index
@@ -249,12 +247,12 @@ static void window_refresh_callback(GLFWwindow window)
     }
 }
 
-static void window_focus_callback(GLFWwindow window, int activated)
+static void window_focus_callback(GLFWwindow window, int focused)
 {
     printf("%08x at %0.3f: Window %s\n",
            counter++,
            glfwGetTime(),
-           activated ? "activated" : "deactivated");
+           focused ? "focused" : "defocused");
 }
 
 static void window_iconify_callback(GLFWwindow window, int iconified)
@@ -311,24 +309,6 @@ static void key_callback(GLFWwindow window, int key, int action)
 
     switch (key)
     {
-        case GLFW_KEY_R:
-        {
-            keyrepeat = !keyrepeat;
-            glfwSetInputMode(window, GLFW_KEY_REPEAT, keyrepeat);
-
-            printf("(( key repeat %s ))\n", keyrepeat ? "enabled" : "disabled");
-            break;
-        }
-
-        case GLFW_KEY_S:
-        {
-            systemkeys = !systemkeys;
-            glfwSetInputMode(window, GLFW_SYSTEM_KEYS, systemkeys);
-
-            printf("(( system keys %s ))\n", systemkeys ? "enabled" : "disabled");
-            break;
-        }
-
         case GLFW_KEY_C:
         {
             closeable = !closeable;
@@ -389,7 +369,7 @@ int main(void)
 
     printf("Library initialized\n");
 
-    window = glfwCreateWindow(0, 0, "Event Linter", NULL, NULL);
+    window = glfwCreateWindow(640, 480, "Event Linter", NULL, NULL);
     if (!window)
     {
         glfwTerminate();
@@ -420,9 +400,6 @@ int main(void)
     glfwGetWindowSize(window, &width, &height);
     printf("Window size should be %ix%i\n", width, height);
 
-    printf("Key repeat should be %s\n", keyrepeat ? "enabled" : "disabled");
-    printf("System keys should be %s\n", systemkeys ? "enabled" : "disabled");
-
     printf("Main loop starting\n");
 
     while (!glfwGetWindowParam(window, GLFW_CLOSE_REQUESTED))

tests/fsfocus.c

@@ -23,8 +23,8 @@
 //
 //========================================================================
 //
-// This test is used to test window activation and iconfication for
-// fullscreen windows with a video mode differing from the current mode
+// This test is used to test window focusing and iconfication for
+// fullscreen windows with a video mode differing from the desktop mode
 //
 //========================================================================
 
@@ -35,11 +35,11 @@
 
 static GLboolean running = GL_TRUE;
 
-static void window_focus_callback(GLFWwindow window, int activated)
+static void window_focus_callback(GLFWwindow window, int focused)
 {
     printf("%0.3f: Window %s\n",
            glfwGetTime(),
-           activated ? "activated" : "deactivated");
+           focused ? "focused" : "defocused");
 }
 
 static void window_key_callback(GLFWwindow window, int key, int action)

tests/gamma.c

@@ -133,8 +133,8 @@ int main(int argc, char** argv)
     }
     else
     {
-        width = 0;
-        height = 0;
+        width = 200;
+        height = 200;
     }
 
     window = glfwCreateWindow(width, height, "Gamma Test", monitor, NULL);

tests/glfwinfo.c

@@ -268,7 +268,7 @@ int main(int argc, char** argv)
     // We assume here that we stand a better chance of success by leaving all
     // possible details of pixel format selection to GLFW
 
-    window = glfwCreateWindow(0, 0, "Version", NULL, NULL);
+    window = glfwCreateWindow(200, 200, "Version", NULL, NULL);
     if (!window)
     {
         glfwTerminate();

tests/iconify.c

@@ -75,11 +75,11 @@ static void window_size_callback(GLFWwindow window, int width, int height)
     glViewport(0, 0, width, height);
 }
 
-static void window_focus_callback(GLFWwindow window, int activated)
+static void window_focus_callback(GLFWwindow window, int focused)
 {
     printf("%0.2f Window %s\n",
            glfwGetTime(),
-           activated ? "activated" : "deactivated");
+           focused ? "focused" : "defocused");
 }
 
 static void window_iconify_callback(GLFWwindow window, int iconified)
@@ -128,8 +128,8 @@ int main(int argc, char** argv)
     }
     else
     {
-        width = 0;
-        height = 0;
+        width = 640;
+        height = 480;
     }
 
     window = glfwCreateWindow(width, height, "Iconify", monitor, NULL);
@@ -152,7 +152,7 @@ int main(int argc, char** argv)
 
     printf("Window is %s and %s\n",
            glfwGetWindowParam(window, GLFW_ICONIFIED) ? "iconified" : "restored",
-           glfwGetWindowParam(window, GLFW_ACTIVE) ? "active" : "inactive");
+           glfwGetWindowParam(window, GLFW_FOCUSED) ? "focused" : "defocused");
 
     glEnable(GL_SCISSOR_TEST);
 

tests/joysticks.c

@@ -186,7 +186,7 @@ int main(void)
         exit(EXIT_FAILURE);
     }
 
-    window = glfwCreateWindow(0, 0, "Joystick Test", NULL, NULL);
+    window = glfwCreateWindow(640, 480, "Joystick Test", NULL, NULL);
     if (!window)
     {
         glfwTerminate();

tests/peter.c

@@ -92,7 +92,7 @@ static void window_size_callback(GLFWwindow window, int width, int height)
 
 static GLboolean open_window(void)
 {
-    window_handle = glfwCreateWindow(0, 0, "Peter Detector", NULL, NULL);
+    window_handle = glfwCreateWindow(640, 480, "Peter Detector", NULL, NULL);
     if (!window_handle)
         return GL_FALSE;
 

tests/sharing.c

@@ -51,10 +51,12 @@ static int window_close_callback(GLFWwindow window)
     return GL_FALSE;
 }
 
-static GLFWwindow open_window(const char* title, GLFWwindow share)
+static GLFWwindow open_window(const char* title, GLFWwindow share, int posX, int posY)
 {
     GLFWwindow window;
 
+    glfwWindowHint(GLFW_POSITION_X, posX);
+    glfwWindowHint(GLFW_POSITION_Y, posY);
     window = glfwCreateWindow(WIDTH, HEIGHT, title, NULL, share);
     if (!window)
         return NULL;
@@ -125,7 +127,6 @@ static void draw_quad(GLuint texture)
 int main(int argc, char** argv)
 {
     GLuint texture;
-    int x, y;
 
     if (!glfwInit())
     {
@@ -133,7 +134,7 @@ int main(int argc, char** argv)
         exit(EXIT_FAILURE);
     }
 
-    windows[0] = open_window("First", NULL);
+    windows[0] = open_window("First", NULL, 0, 0);
     if (!windows[0])
     {
         fprintf(stderr, "Failed to open first GLFW window: %s\n", glfwErrorString(glfwGetError()));
@@ -147,7 +148,8 @@ int main(int argc, char** argv)
     // It will then be shared with the second context, created below
     texture = create_texture();
 
-    windows[1] = open_window("Second", windows[0]);
+    // Put the second window to the right of the first one
+    windows[1] = open_window("Second", windows[0], WIDTH + 50, 0);
     if (!windows[1])
     {
         fprintf(stderr, "Failed to open second GLFW window: %s\n", glfwErrorString(glfwGetError()));
@@ -156,14 +158,13 @@ int main(int argc, char** argv)
         exit(EXIT_FAILURE);
     }
 
-    // Set drawing color for the first context and copy it to the second
+    // Set drawing color for both contexts
     glfwMakeContextCurrent(windows[0]);
     glColor3f(0.6f, 0.f, 0.6f);
-    glfwCopyContext(windows[0], windows[1], GL_CURRENT_BIT);
+    glfwMakeContextCurrent(windows[1]);
+    glColor3f(0.6f, 0.6f, 0.f);
 
-    // Put the second window to the right of the first one
-    glfwGetWindowPos(windows[0], &x, &y);
-    glfwSetWindowPos(windows[1], x + WIDTH + 50, y);
+    glfwMakeContextCurrent(windows[0]);
 
     while (!closed)
     {

tests/tearing.c

@@ -70,7 +70,7 @@ int main(void)
         exit(EXIT_FAILURE);
     }
 
-    window = glfwCreateWindow(0, 0, "", NULL, NULL);
+    window = glfwCreateWindow(640, 480, "", NULL, NULL);
     if (!window)
     {
         fprintf(stderr, "Failed to open GLFW window: %s\n", glfwErrorString(glfwGetError()));

tests/threads.c

@@ -89,6 +89,8 @@ int main(void)
 
     for (i = 0;  i < count;  i++)
     {
+        glfwWindowHint(GLFW_POSITION_X, 200 + 250 * i);
+        glfwWindowHint(GLFW_POSITION_Y, 200);
         threads[i].window = glfwCreateWindow(200, 200,
                                              threads[i].title,
                                              NULL, NULL);
@@ -99,8 +101,6 @@ int main(void)
             exit(EXIT_FAILURE);
         }
 
-        glfwSetWindowPos(threads[i].window, 200 + 250 * i, 200);
-
         if (thrd_create(&threads[i].id, thread_main, threads + i) !=
             thrd_success)
         {

tests/title.c

@@ -47,7 +47,7 @@ int main(void)
         exit(EXIT_FAILURE);
     }
 
-    window = glfwCreateWindow(0, 0, "English 日本語 русский язык 官話", NULL, NULL);
+    window = glfwCreateWindow(400, 400, "English 日本語 русский язык 官話", NULL, NULL);
     if (!window)
     {
         fprintf(stderr, "Failed to open GLFW window: %s\n", glfwErrorString(glfwGetError()));

tests/windows.c

@@ -55,6 +55,8 @@ int main(void)
 
     for (i = 0;  i < 4;  i++)
     {
+        glfwWindowHint(GLFW_POSITION_X, 100 + (i & 1) * 300);
+        glfwWindowHint(GLFW_POSITION_Y, 100 + (i >> 1) * 300);
         windows[i] = glfwCreateWindow(200, 200, titles[i], NULL, NULL);
         if (!windows[i])
         {
@@ -70,8 +72,6 @@ int main(void)
                      (GLclampf) (i >> 1),
                      i ? 0.f : 1.f,
                      0.f);
-
-        glfwSetWindowPos(windows[i], 100 + (i & 1) * 300, 100 + (i >> 1) * 300);
     }
 
     while (running)