Documentation work for GLFW_MOUSE_PASSTHROUGH

Related to #1568.

README.md

@@ -124,6 +124,8 @@ information on what to include when reporting a bug.
  - Added `GLFW_RESIZE_EW_CURSOR` alias for `GLFW_HRESIZE_CURSOR` (#427)
  - Added `GLFW_RESIZE_NS_CURSOR` alias for `GLFW_VRESIZE_CURSOR` (#427)
  - Added `GLFW_POINTING_HAND_CURSOR` alias for `GLFW_HAND_CURSOR` (#427)
+ - Added `GLFW_MOUSE_PASSTHROUGH` window hint for letting mouse input pass
+   through the window (#1236,#1568)
  - Added `GLFW_FEATURE_UNAVAILABLE` error for platform limitations (#1692)
  - Added `GLFW_FEATURE_UNIMPLEMENTED` error for incomplete backends (#1692)
  - Added `GLFW_ANGLE_PLATFORM_TYPE` init hint and `GLFW_ANGLE_PLATFORM_TYPE_*`

docs/news.dox

@@ -27,6 +27,14 @@ are still available.
 For more information see @ref cursor_standard.
 
 
+@subsubsection mouse_passthrough_34 Mouse event passthrough
+
+GLFW now provides the [GLFW_MOUSE_PASSTHROUGH](@ref GLFW_MOUSE_PASSTHROUGH_hint)
+window hint for making a window transparent to mouse input, lettings events pass
+to whatever window is behind it.  This can also be changed after window
+creation with the matching [window attribute](@ref GLFW_MOUSE_PASSTHROUGH_attrib).
+
+
 @subsubsection features_34_angle_backend Support for ANGLE rendering backend selection
 
 GLFW now provides the
@@ -97,6 +105,7 @@ then GLFW will fail to initialize.
  - @ref GLFW_RESIZE_NWSE_CURSOR
  - @ref GLFW_RESIZE_NESW_CURSOR
  - @ref GLFW_RESIZE_ALL_CURSOR
+ - @ref GLFW_MOUSE_PASSTHROUGH
  - @ref GLFW_NOT_ALLOWED_CURSOR
  - @ref GLFW_CURSOR_UNAVAILABLE
  - @ref GLFW_WIN32_KEYBOARD_MENU

docs/window.dox

@@ -255,6 +255,13 @@ This hint only has an effect on platforms where screen coordinates and pixels
 always map 1:1 such as Windows and X11.  On platforms like macOS the resolution
 of the framebuffer is changed independently of the window size.
 
+@anchor GLFW_MOUSE_PASSTHROUGH_hint
+__GLFW_MOUSE_PASSTHROUGH__ specifies whether the window is transparent to mouse
+input, letting any mouse events pass through to whatever window is behind it.
+This is only supported for undecorated windows.  Decorated windows with this
+enabled will behave differently between platforms.  Possible values are
+`GLFW_TRUE` and `GLFW_FALSE`.
+
 
 @subsubsection window_hints_fb Framebuffer related hints
 
@@ -523,6 +530,7 @@ GLFW_CENTER_CURSOR            | `GLFW_TRUE`                 | `GLFW_TRUE` or `GL
 GLFW_TRANSPARENT_FRAMEBUFFER  | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
 GLFW_FOCUS_ON_SHOW            | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
 GLFW_SCALE_TO_MONITOR         | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_MOUSE_PASSTHROUGH        | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
 GLFW_RED_BITS                 | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
 GLFW_GREEN_BITS               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
 GLFW_BLUE_BITS                | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
@@ -1225,6 +1233,10 @@ returns one.
 GLFW comes with a test program that lets you control whole window transparency
 at run-time called `opacity`.
 
+If you want to use either of these transparency methods to display a temporary
+overlay like for example a notification, the @ref GLFW_FLOATING and @ref
+GLFW_MOUSE_PASSTHROUGH window hints and attributes may be useful.
+
 
 @subsection window_attribs Window attributes
 
@@ -1313,6 +1325,15 @@ focus when @ref glfwShowWindow is called. This can be set before creation
 with the [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) window hint or
 after with @ref glfwSetWindowAttrib.
 
+@anchor GLFW_MOUSE_PASSTHROUGH_attrib
+__GLFW_MOUSE_PASSTHROUGH__ specifies whether the window is transparent to mouse
+input, letting any mouse events pass through to whatever window is behind it.
+This can be set before creation with the
+[GLFW_MOUSE_PASSTHROUGH](@ref GLFW_MOUSE_PASSTHROUGH_hint) window hint or after
+with @ref glfwSetWindowAttrib.  This is only supported for undecorated windows.
+Decorated windows with this enabled will behave differently between platforms.
+
+
 @subsubsection window_attribs_ctx Context related attributes
 
 @anchor GLFW_CLIENT_API_attrib

include/GLFW/glfw3.h

@@ -895,9 +895,9 @@ extern "C" {
  */
 #define GLFW_FOCUS_ON_SHOW          0x0002000C
 
-/*! @brief Forward mouse input to window behind.
+/*! @brief Mouse input transparency window hint and attribute
  *
- *  Mouse input forwarding[window hint](@ref GLFW_MOUSE_PASSTHROUGH_hint) or
+ *  Mouse input transparency [window hint](@ref GLFW_MOUSE_PASSTHROUGH_hint) or
  *  [window attribute](@ref GLFW_MOUSE_PASSTHROUGH_attrib).
  */
 #define GLFW_MOUSE_PASSTHROUGH      0x0002000D