pixo 0.1.0

data/ext/pixo/ext/glfw/docs/window.dox

@@ -0,0 +1,1008 @@
+/*!
+
+@page window_guide Window guide
+ 
+@tableofcontents
+
+This guide introduces the window related functions of GLFW.  For details on
+a specific function in this category, see the @ref window.  There are also
+guides for the other areas of GLFW.
+
+ - @ref intro_guide
+ - @ref context_guide
+ - @ref vulkan_guide
+ - @ref monitor_guide
+ - @ref input_guide
+
+
+@section window_object Window objects
+
+The @ref GLFWwindow object encapsulates both a window and a context.  They are
+created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow, or
+@ref glfwTerminate, if any remain.  As the window and context are inseparably
+linked, the object pointer is used as both a context and window handle.
+
+To see the event stream provided to the various window related callbacks, run
+the `events` test program.
+
+
+@subsection window_creation Window creation
+
+A window and its OpenGL or OpenGL ES context are created with @ref
+glfwCreateWindow, which returns a handle to the created window object.  For
+example, this creates a 640 by 480 windowed mode window:
+
+@code
+GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
+@endcode
+
+If window creation fails, `NULL` will be returned, so it is necessary to check
+the return value.
+
+The window handle is passed to all window related functions and is provided to
+along with all input events, so event handlers can tell which window received
+the event.
+
+
+@subsubsection window_full_screen Full screen windows
+
+To create a full screen window, you need to specify which monitor the window
+should use.  In most cases, the user's primary monitor is a good choice.
+For more information about retrieving monitors, see @ref monitor_monitors. 
+
+@code
+GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
+@endcode
+
+Full screen windows cover the entire display area of a monitor, have no border
+or decorations.
+
+Windowed mode windows can be made full screen by setting a monitor with @ref
+glfwSetWindowMonitor, and full screen ones can be made windowed by unsetting it
+with the same function.
+
+Each field of the @ref GLFWvidmode structure corresponds to a function parameter
+or window hint and combine to form the _desired video mode_ for that window.
+The supported video mode most closely matching the desired video mode will be
+set for the chosen monitor as long as the window has input focus.  For more
+information about retrieving video modes, see @ref monitor_modes.
+
+Video mode field        | Corresponds to
+----------------------- | ------------------------
+GLFWvidmode.width       | `width` parameter
+GLFWvidmode.height      | `height` parameter
+GLFWvidmode.redBits     | `GLFW_RED_BITS` hint
+GLFWvidmode.greenBits   | `GLFW_GREEN_BITS` hint
+GLFWvidmode.blueBits    | `GLFW_BLUE_BITS` hint
+GLFWvidmode.refreshRate | `GLFW_REFRESH_RATE` hint
+
+Once you have a full screen window, you can change its resolution, refresh rate
+and monitor with @ref glfwSetWindowMonitor.  If you just need change its
+resolution you can also call @ref glfwSetWindowSize.  In all cases, the new
+video mode will be selected the same way as the video mode chosen by @ref
+glfwCreateWindow.  If the window has an OpenGL or OpenGL ES context, it will be
+unaffected.
+
+By default, the original video mode of the monitor will be restored and the
+window iconified if it loses input focus, to allow the user to switch back to
+the desktop.  This behavior can be disabled with the `GLFW_AUTO_ICONIFY` window
+hint, for example if you wish to simultaneously cover multiple windows with full
+screen windows.
+
+
+@subsubsection window_windowed_full_screen "Windowed full screen" windows
+
+If the closest match for the desired video mode is the current one, the video
+mode will not be changed, making window creation faster and application
+switching much smoother.  This is sometimes called _windowed full screen_ or
+_borderless full screen_ window and counts as a full screen window.  To create
+such a window, simply request the current video mode.
+
+@code
+const GLFWvidmode* mode = glfwGetVideoMode(monitor);
+
+glfwWindowHint(GLFW_RED_BITS, mode->redBits);
+glfwWindowHint(GLFW_GREEN_BITS, mode->greenBits);
+glfwWindowHint(GLFW_BLUE_BITS, mode->blueBits);
+glfwWindowHint(GLFW_REFRESH_RATE, mode->refreshRate);
+
+GLFWwindow* window = glfwCreateWindow(mode->width, mode->height, "My Title", monitor, NULL);
+@endcode
+
+This also works for windowed mode windows that are made full screen.
+
+@code
+const GLFWvidmode* mode = glfwGetVideoMode(monitor);
+
+glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate);
+@endcode
+
+Note that @ref glfwGetVideoMode returns the _current_ video mode of a monitor,
+so if you already have a full screen window on that monitor that you want to
+make windowed full screen, you need to have saved the desktop resolution before.
+
+
+@subsection window_destruction Window destruction
+
+When a window is no longer needed, destroy it with @ref glfwDestroyWindow.
+
+@code
+glfwDestroyWindow(window);
+@endcode
+
+Window destruction always succeeds.  Before the actual destruction, all
+callbacks are removed so no further events will be delivered for the window.
+All windows remaining when @ref glfwTerminate is called are destroyed as well.
+
+When a full screen window is destroyed, the original video mode of its monitor
+is restored, but the gamma ramp is left untouched.
+
+
+@subsection window_hints Window creation hints
+
+There are a number of hints that can be set before the creation of a window and
+context.  Some affect the window itself, others affect the framebuffer or
+context.  These hints are set to their default values each time the library is
+initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint
+and reset all at once to their defaults with @ref glfwDefaultWindowHints.
+
+Note that hints need to be set _before_ the creation of the window and context
+you wish to have the specified attributes.
+
+
+@subsubsection window_hints_hard Hard and soft constraints
+
+Some window hints are hard constraints.  These must match the available
+capabilities _exactly_ for window and context creation to succeed.  Hints
+that are not hard constraints are matched as closely as possible, but the
+resulting context and framebuffer may differ from what these hints requested.
+
+The following hints are always hard constraints:
+- `GLFW_STEREO`
+- `GLFW_DOUBLEBUFFER`
+- `GLFW_CLIENT_API`
+- `GLFW_CONTEXT_CREATION_API`
+
+The following additional hints are hard constraints when requesting an OpenGL
+context, but are ignored when requesting an OpenGL ES context:
+- `GLFW_OPENGL_FORWARD_COMPAT`
+- `GLFW_OPENGL_PROFILE`
+
+
+@subsubsection window_hints_wnd Window related hints
+
+`GLFW_RESIZABLE` specifies whether the windowed mode window will be resizable
+_by the user_.  The window will still be resizable using the @ref
+glfwSetWindowSize function.  This hint is ignored for full screen windows.
+
+`GLFW_VISIBLE` specifies whether the windowed mode window will be initially
+visible.  This hint is ignored for full screen windows.
+
+`GLFW_DECORATED` specifies whether the windowed mode window will have window
+decorations such as a border, a close widget, etc.  An undecorated window may
+still allow the user to generate close events on some platforms.  This hint is
+ignored for full screen windows.
+
+`GLFW_FOCUSED` specifies whether the windowed mode window will be given input
+focus when created.  This hint is ignored for full screen and initially hidden
+windows.
+
+`GLFW_AUTO_ICONIFY` specifies whether the full screen window will
+automatically iconify and restore the previous video mode on input focus loss.
+This hint is ignored for windowed mode windows.
+
+`GLFW_FLOATING` specifies whether the windowed mode window will be floating
+above other regular windows, also called topmost or always-on-top.  This is
+intended primarily for debugging purposes and cannot be used to implement proper
+full screen windows.  This hint is ignored for full screen windows.
+
+`GLFW_MAXIMIZED` specifies whether the windowed mode window will be maximized
+when created.  This hint is ignored for full screen windows.
+
+
+@subsubsection window_hints_fb Framebuffer related hints
+
+`GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
+`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` specify the desired bit depths of the
+various components of the default framebuffer.  `GLFW_DONT_CARE` means the
+application has no preference.
+
+`GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` and
+`GLFW_ACCUM_ALPHA_BITS` specify the desired bit depths of the various components
+of the accumulation buffer.  `GLFW_DONT_CARE` means the application has no
+preference.
+
+@par
+Accumulation buffers are a legacy OpenGL feature and should not be used in new
+code.
+
+`GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers.
+`GLFW_DONT_CARE` means the application has no preference.
+
+@par
+Auxiliary buffers are a legacy OpenGL feature and should not be used in new
+code.
+
+`GLFW_STEREO` specifies whether to use stereoscopic rendering.  This is a hard
+constraint.
+
+`GLFW_SAMPLES` specifies the desired number of samples to use for multisampling.
+Zero disables multisampling.  `GLFW_DONT_CARE` means the application has no
+preference.
+
+`GLFW_SRGB_CAPABLE` specifies whether the framebuffer should be sRGB capable.
+If supported, a created OpenGL context will support the `GL_FRAMEBUFFER_SRGB`
+enable, also called `GL_FRAMEBUFFER_SRGB_EXT`) for controlling sRGB rendering
+and a created OpenGL ES context will always have sRGB rendering enabled.
+
+`GLFW_DOUBLEBUFFER` specifies whether the framebuffer should be double buffered.
+You nearly always want to use double buffering.  This is a hard constraint.
+
+
+@subsubsection window_hints_mtr Monitor related hints
+
+`GLFW_REFRESH_RATE` specifies the desired refresh rate for full screen windows.
+If set to `GLFW_DONT_CARE`, the highest available refresh rate will be used.
+This hint is ignored for windowed mode windows.
+
+
+@subsubsection window_hints_ctx Context related hints
+
+`GLFW_CLIENT_API` specifies which client API to create the context for.
+Possible values are `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` and `GLFW_NO_API`.
+This is a hard constraint.
+
+`GLFW_CONTEXT_CREATION_API` specifies which context creation API to use to
+create the context.  Possible values are `GLFW_NATIVE_CONTEXT_API` and
+`GLFW_EGL_CONTEXT_API`.  This is a hard constraint.  If no client API is
+requested, this hint is ignored.
+
+@par
+__OS X:__ The EGL API is not available on this platform and requests to use it
+will fail.
+
+@par
+__Wayland, Mir:__ The EGL API _is_ the native context creation API, so this hint
+will have no effect.
+
+@note An OpenGL extension loader library that assumes it knows which context
+creation API is used on a given platform may fail if you change this hint.  This
+can be resolved by having it load via @ref glfwGetProcAddress, which always uses
+the selected API.
+
+@bug On some Linux systems, creating contexts via both the native and EGL APIs
+in a single process will cause the application to segfault.  Stick to one API or
+the other on Linux for now.
+
+`GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client
+API version that the created context must be compatible with.  The exact
+behavior of these hints depend on the requested client API.
+
+@par
+__OpenGL:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
+not hard constraints, but creation will fail if the OpenGL version of the
+created context is less than the one requested.  It is therefore perfectly safe
+to use the default of version 1.0 for legacy code and you will still get
+backwards-compatible contexts of version 3.0 and above when available.
+
+@par
+While there is no way to ask the driver for a context of the highest supported
+version, GLFW will attempt to provide this when you ask for a version 1.0
+context, which is the default for these hints.
+
+@par
+__OpenGL ES:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
+not hard constraints, but creation will fail if the OpenGL ES version of the
+created context is less than the one requested.  Additionally, OpenGL ES 1.x
+cannot be returned if 2.0 or later was requested, and vice versa.  This is
+because OpenGL ES 3.x is backward compatible with 2.0, but OpenGL ES 2.0 is not
+backward compatible with 1.x.
+
+`GLFW_OPENGL_FORWARD_COMPAT` specifies whether the OpenGL context should be
+forward-compatible, i.e. one where all functionality deprecated in the requested
+version of OpenGL is removed.  This must only be used if the requested OpenGL
+version is 3.0 or above.  If OpenGL ES is requested, this hint is ignored.
+
+@par
+Forward-compatibility is described in detail in the
+[OpenGL Reference Manual](https://www.opengl.org/registry/).
+
+`GLFW_OPENGL_DEBUG_CONTEXT` specifies whether to create a debug OpenGL context,
+which may have additional error and performance issue reporting functionality.
+If OpenGL ES is requested, this hint is ignored.
+
+`GLFW_OPENGL_PROFILE` specifies which OpenGL profile to create the context for.
+Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or
+`GLFW_OPENGL_COMPAT_PROFILE`, or `GLFW_OPENGL_ANY_PROFILE` to not request
+a specific profile.  If requesting an OpenGL version below 3.2,
+`GLFW_OPENGL_ANY_PROFILE` must be used.  If OpenGL ES is requested,
+this hint is ignored.
+
+@par
+OpenGL profiles are described in detail in the
+[OpenGL Reference Manual](https://www.opengl.org/registry/).
+
+`GLFW_CONTEXT_ROBUSTNESS` specifies the robustness strategy to be used by the
+context.  This can be one of `GLFW_NO_RESET_NOTIFICATION` or
+`GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
+a robustness strategy.
+
+`GLFW_CONTEXT_RELEASE_BEHAVIOR` specifies the release behavior to be
+used by the context.  Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`,
+`GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`.  If the
+behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context
+creation API will be used.  If the behavior is `GLFW_RELEASE_BEHAVIOR_FLUSH`,
+the pipeline will be flushed whenever the context is released from being the
+current one.  If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
+not be flushed on release.
+
+@par
+Context release behaviors are described in detail by the
+[GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
+extension.
+
+`GLFW_CONTEXT_NO_ERROR` specifies whether errors should be generated by the
+context.  If enabled, situations that would have generated errors instead cause
+undefined behavior.
+
+@par
+The no error mode for OpenGL and OpenGL ES is described in detail by the
+[GL_KHR_no_error](https://www.opengl.org/registry/specs/KHR/no_error.txt)
+extension.
+
+@note This hint is experimental in its current state.  There are currently
+(October 2015) no corresponding WGL or GLX extensions.  That makes this hint
+a [hard constraint](@ref window_hints_hard) for those backends, as creation will
+fail if unsupported context flags are requested.  Once the extensions are
+available, they will be required and creation of `GL_KHR_no_error` contexts may
+fail on early drivers where this flag is supported without those extensions
+being listed.
+
+
+@subsubsection window_hints_values Supported and default values
+
+Window hint                     | Default value               | Supported values
+------------------------------- | --------------------------- | ----------------
+`GLFW_RESIZABLE`                | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_VISIBLE`                  | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_DECORATED`                | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_FOCUSED`                  | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_AUTO_ICONIFY`             | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_FLOATING`                 | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_MAXIMIZED`                | `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`
+`GLFW_ALPHA_BITS`               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_DEPTH_BITS`               | 24                          | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_STENCIL_BITS`             | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_ACCUM_RED_BITS`           | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_ACCUM_GREEN_BITS`         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_ACCUM_BLUE_BITS`          | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_ACCUM_ALPHA_BITS`         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_AUX_BUFFERS`              | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_SAMPLES`                  | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_REFRESH_RATE`             | `GLFW_DONT_CARE`            | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+`GLFW_STEREO`                   | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_SRGB_CAPABLE`             | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_DOUBLEBUFFER`             | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_CLIENT_API`               | `GLFW_OPENGL_API`           | `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`
+`GLFW_CONTEXT_CREATION_API`     | `GLFW_NATIVE_CONTEXT_API`   | `GLFW_NATIVE_CONTEXT_API` or `GLFW_EGL_CONTEXT_API`
+`GLFW_CONTEXT_VERSION_MAJOR`    | 1                           | Any valid major version number of the chosen client API
+`GLFW_CONTEXT_VERSION_MINOR`    | 0                           | Any valid minor version number of the chosen client API
+`GLFW_CONTEXT_ROBUSTNESS`       | `GLFW_NO_ROBUSTNESS`        | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET`
+`GLFW_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`
+`GLFW_OPENGL_FORWARD_COMPAT`    | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_OPENGL_DEBUG_CONTEXT`     | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+`GLFW_OPENGL_PROFILE`           | `GLFW_OPENGL_ANY_PROFILE`   | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE`
+
+
+@section window_events Window event processing
+
+See @ref events.
+
+
+@section window_properties Window properties and events
+
+@subsection window_userptr User pointer
+
+Each window has a user pointer that can be set with @ref
+glfwSetWindowUserPointer and fetched with @ref glfwGetWindowUserPointer.  This
+can be used for any purpose you need and will not be modified by GLFW throughout
+the life-time of the window.
+
+The initial value of the pointer is `NULL`.
+
+
+@subsection window_close Window closing and close flag
+
+When the user attempts to close the window, for example by clicking the close
+widget or using a key chord like Alt+F4, the _close flag_ of the window is set.
+The window is however not actually destroyed and, unless you watch for this
+state change, nothing further happens.
+
+The current state of the close flag is returned by @ref glfwWindowShouldClose
+and can be set or cleared directly with @ref glfwSetWindowShouldClose.  A common
+pattern is to use the close flag as a main loop condition.
+
+@code
+while (!glfwWindowShouldClose(window))
+{
+    render(window);
+
+    glfwSwapBuffers(window);
+    glfwPollEvents();
+}
+@endcode
+
+If you wish to be notified when the user attempts to close a window, set a close
+callback.
+
+@code
+glfwSetWindowCloseCallback(window, window_close_callback);
+@endcode
+
+The callback function is called directly _after_ the close flag has been set.
+It can be used for example to filter close requests and clear the close flag
+again unless certain conditions are met.
+
+@code
+void window_close_callback(GLFWwindow* window)
+{
+    if (!time_to_close)
+        glfwSetWindowShouldClose(window, GLFW_FALSE);
+}
+@endcode
+
+
+@subsection window_size Window size
+
+The size of a window can be changed with @ref glfwSetWindowSize.  For windowed
+mode windows, this sets the size, in
+[screen coordinates](@ref coordinate_systems) of the _client area_ or _content
+area_ of the window.  The window system may impose limits on window size.
+
+@code
+glfwSetWindowSize(window, 640, 480);
+@endcode
+
+For full screen windows, the specified size becomes the new resolution of the
+window's desired video mode.  The video mode most closely matching the new
+desired video mode is set immediately.  The window is resized to fit the
+resolution of the set video mode.
+
+If you wish to be notified when a window is resized, whether by the user or
+the system, set a size callback.
+
+@code
+glfwSetWindowSizeCallback(window, window_size_callback);
+@endcode
+
+The callback function receives the new size, in screen coordinates, of the
+client area of the window when it is resized.
+
+@code
+void window_size_callback(GLFWwindow* window, int width, int height)
+{
+}
+@endcode
+
+There is also @ref glfwGetWindowSize for directly retrieving the current size of
+a window.
+
+@code
+int width, height;
+glfwGetWindowSize(window, &width, &height);
+@endcode
+
+@note Do not pass the window size to `glViewport` or other pixel-based OpenGL
+calls.  The window size is in screen coordinates, not pixels.  Use the
+[framebuffer size](@ref window_fbsize), which is in pixels, for pixel-based
+calls.
+
+The above functions work with the size of the client area, but decorated windows
+typically have title bars and window frames around this rectangle.  You can
+retrieve the extents of these with @ref glfwGetWindowFrameSize.
+
+@code
+int left, top, right, bottom;
+glfwGetWindowFrameSize(window, &left, &top, &right, &bottom);
+@endcode
+
+The returned values are the distances, in screen coordinates, from the edges of
+the client area to the corresponding edges of the full window.  As they are
+distances and not coordinates, they are always zero or positive.
+
+
+@subsection window_fbsize Framebuffer size
+
+While the size of a window is measured in screen coordinates, OpenGL works with
+pixels.  The size you pass into `glViewport`, for example, should be in pixels.
+On some machines screen coordinates and pixels are the same, but on others they
+will not be.  There is a second set of functions to retrieve the size, in
+pixels, of the framebuffer of a window.
+
+If you wish to be notified when the framebuffer of a window is resized, whether
+by the user or the system, set a size callback.
+
+@code
+glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
+@endcode
+
+The callback function receives the new size of the framebuffer when it is
+resized, which can for example be used to update the OpenGL viewport.
+
+@code
+void framebuffer_size_callback(GLFWwindow* window, int width, int height)
+{
+    glViewport(0, 0, width, height);
+}
+@endcode
+
+There is also @ref glfwGetFramebufferSize for directly retrieving the current
+size of the framebuffer of a window.
+
+@code
+int width, height;
+glfwGetFramebufferSize(window, &width, &height);
+glViewport(0, 0, width, height);
+@endcode
+
+The size of a framebuffer may change independently of the size of a window, for
+example if the window is dragged between a regular monitor and a high-DPI one.
+
+
+@subsection window_sizelimits Window size limits
+
+The minimum and maximum size of the client area of a windowed mode window can be
+enforced with @ref glfwSetWindowSizeLimits.  The user may resize the window to
+any size and aspect ratio within the specified limits, unless the aspect ratio
+is also set.
+
+@code
+glfwSetWindowSizeLimits(window, 200, 200, 400, 400);
+@endcode
+
+To specify only a minimum size or only a maximum one, set the other pair to
+`GLFW_DONT_CARE`.
+
+@code
+glfwSetWindowSizeLimits(window, 640, 480, GLFW_DONT_CARE, GLFW_DONT_CARE);
+@endcode
+
+To disable size limits for a window, set them all to `GLFW_DONT_CARE`.
+
+The aspect ratio of the client area of a windowed mode window can be enforced
+with @ref glfwSetWindowAspectRatio.  The user may resize the window freely
+unless size limits are also set, but the size will be constrained to maintain
+the aspect ratio.
+
+@code
+glfwSetWindowAspectRatio(window, 16, 9);
+@endcode
+
+The aspect ratio is specified as a numerator and denominator, corresponding to
+the width and height, respectively.  If you want a window to maintain its
+current aspect ratio, simply use its current size as the ratio.
+
+@code
+int width, height;
+glfwGetWindowSize(window, &width, &height);
+glfwSetWindowAspectRatio(window, width, height);
+@endcode
+
+To disable the aspect ratio limit for a window, set both terms to
+`GLFW_DONT_CARE`.
+
+You can have both size limits and aspect ratio set for a window, but the results
+are undefined if they conflict.
+
+
+@subsection window_pos Window position
+
+The position of a windowed-mode window can be changed with @ref
+glfwSetWindowPos.  This moves the window so that the upper-left corner of its
+client area has the specified [screen coordinates](@ref coordinate_systems).
+The window system may put limitations on window placement.
+
+@code
+glfwSetWindowPos(window, 100, 100);
+@endcode
+
+If you wish to be notified when a window is moved, whether by the user, system
+or your own code, set a position callback.
+
+@code
+glfwSetWindowPosCallback(window, window_pos_callback);
+@endcode
+
+The callback function receives the new position of the upper-left corner of the 
+client area when the window is moved.
+
+@code
+void window_pos_callback(GLFWwindow* window, int xpos, int ypos)
+{
+}
+@endcode
+
+There is also @ref glfwGetWindowPos for directly retrieving the current position
+of the client area of the window.
+
+@code
+int xpos, ypos;
+glfwGetWindowPos(window, &xpos, &ypos);
+@endcode
+
+
+@subsection window_title Window title
+
+All GLFW windows have a title, although undecorated or full screen windows may
+not display it or only display it in a task bar or similar interface.  You can
+set a UTF-8 encoded window title with @ref glfwSetWindowTitle.
+
+@code
+glfwSetWindowTitle(window, "My Window");
+@endcode
+
+The specified string is copied before the function returns, so there is no need
+to keep it around.
+
+As long as your source file is encoded as UTF-8, you can use any Unicode
+characters directly in the source.
+
+@code
+glfwSetWindowTitle(window, "カウボーイビバップ");
+@endcode
+
+If you are using C++11 or C11, you can use a UTF-8 string literal.
+
+@code
+glfwSetWindowTitle(window, u8"This is always a UTF-8 string");
+@endcode
+
+
+@subsection window_icon Window icon
+
+Decorated windows have icons on some platforms.  You can set this icon by
+specifying a list of candidate images with @ref glfwSetWindowIcon.
+
+@code
+GLFWimage images[2];
+images[0] = load_icon("my_icon.png");
+images[1] = load_icon("my_icon_small.png");
+
+glfwSetWindowIcon(window, 2, images);
+@endcode
+
+To revert to the default window icon, pass in an empty image array.
+
+@code
+glfwSetWindowIcon(window, 0, NULL);
+@endcode
+
+
+@subsection window_monitor Window monitor
+
+Full screen windows are associated with a specific monitor.  You can get the
+handle for this monitor with @ref glfwGetWindowMonitor.
+
+@code
+GLFWmonitor* monitor = glfwGetWindowMonitor(window);
+@endcode
+
+This monitor handle is one of those returned by @ref glfwGetMonitors.
+
+For windowed mode windows, this function returns `NULL`.  This is how to tell
+full screen windows from windowed mode windows.
+
+You can move windows between monitors or between full screen and windowed mode
+with @ref glfwSetWindowMonitor.  When making a window full screen on the same or
+on a different monitor, specify the desired monitor, resolution and refresh
+rate.  The position arguments are ignored.
+
+@code
+const GLFWvidmode* mode = glfwGetVideoMode(monitor);
+
+glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate);
+@endcode
+
+When making the window windowed, specify the desired position and size.  The
+refresh rate argument is ignored.
+
+@code
+glfwSetWindowMonitor(window, NULL, xpos, ypos, width, height, 0);
+@endcode
+
+This restores any previous window settings such as whether it is decorated,
+floating, resizable, has size or aspect ratio limits, etc..  To restore a window
+that was originally windowed to its original size and position, save these
+before making it full screen and then pass them in as above.
+
+
+@subsection window_iconify Window iconification
+
+Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow.
+
+@code
+glfwIconifyWindow(window);
+@endcode
+
+When a full screen window is iconified, the original video mode of its monitor
+is restored until the user or application restores the window.
+
+Iconified windows can be restored with @ref glfwRestoreWindow.
+
+@code
+glfwRestoreWindow(window);
+@endcode
+
+When a full screen window is restored, the desired video mode is restored to its
+monitor as well.
+
+If you wish to be notified when a window is iconified or restored, whether by
+the user, system or your own code, set a iconify callback.
+
+@code
+glfwSetWindowIconifyCallback(window, window_iconify_callback);
+@endcode
+
+The callback function receives changes in the iconification state of the window.
+
+@code
+void window_iconify_callback(GLFWwindow* window, int iconified)
+{
+    if (iconified)
+    {
+        // The window was iconified
+    }
+    else
+    {
+        // The window was restored
+    }
+}
+@endcode
+
+You can also get the current iconification state with @ref glfwGetWindowAttrib.
+
+@code
+int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED);
+@endcode
+
+
+@subsection window_hide Window visibility
+
+Windowed mode windows can be hidden with @ref glfwHideWindow.
+
+@code
+glfwHideWindow(window);
+@endcode
+
+This makes the window completely invisible to the user, including removing it
+from the task bar, dock or window list.  Full screen windows cannot be hidden
+and calling @ref glfwHideWindow on a full screen window does nothing.
+
+Hidden windows can be shown with @ref glfwShowWindow.
+
+@code
+glfwShowWindow(window);
+@endcode
+
+Windowed mode windows can be created initially hidden with the `GLFW_VISIBLE`
+[window hint](@ref window_hints_wnd).  Windows created hidden are completely
+invisible to the user until shown.  This can be useful if you need to set up
+your window further before showing it, for example moving it to a specific
+location.
+
+You can also get the current visibility state with @ref glfwGetWindowAttrib.
+
+@code
+int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
+@endcode
+
+
+@subsection window_focus Window input focus
+
+Windows can be given input focus and brought to the front with @ref
+glfwFocusWindow.
+
+@code
+glfwFocusWindow(window);
+@endcode
+
+If you wish to be notified when a window gains or loses input focus, whether by
+the user, system or your own code, set a focus callback.
+
+@code
+glfwSetWindowFocusCallback(window, window_focus_callback);
+@endcode
+
+The callback function receives changes in the input focus state of the window.
+
+@code
+void window_focus_callback(GLFWwindow* window, int focused)
+{
+    if (focused)
+    {
+        // The window gained input focus
+    }
+    else
+    {
+        // The window lost input focus
+    }
+}
+@endcode
+
+You can also get the current input focus state with @ref glfwGetWindowAttrib.
+
+@code
+int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
+@endcode
+
+
+@subsection window_refresh Window damage and refresh
+
+If you wish to be notified when the contents of a window is damaged and needs
+to be refreshed, set a window refresh callback.
+
+@code
+glfwSetWindowRefreshCallback(m_handle, window_refresh_callback);
+@endcode
+
+The callback function is called when the contents of the window needs to be
+refreshed.
+
+@code
+void window_refresh_callback(GLFWwindow* window)
+{
+    draw_editor_ui(window);
+    glfwSwapBuffers(window);
+}
+@endcode
+
+@note On compositing window systems such as Aero, Compiz or Aqua, where the
+window contents are saved off-screen, this callback might only be called when
+the window or framebuffer is resized.
+
+
+@subsection window_attribs Window attributes
+
+Windows have a number of attributes that can be returned using @ref
+glfwGetWindowAttrib.  Some reflect state that may change during the lifetime of
+the window, while others reflect the corresponding hints and are fixed at the
+time of creation.  Some are related to the actual window and others to its
+context.
+
+@code
+if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
+{
+    // window has input focus
+}
+@endcode
+
+
+@subsubsection window_attribs_wnd Window related attributes
+
+`GLFW_FOCUSED` indicates whether the specified window has input focus.  Initial
+input focus is controlled by the [window hint](@ref window_hints_wnd) with the
+same name.   
+
+`GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by
+the user or with @ref glfwIconifyWindow.
+
+`GLFW_MAXIMIZED` indicates whether the specified window is maximized, whether by
+the user or with @ref glfwMaximizeWindow.
+
+`GLFW_VISIBLE` indicates whether the specified window is visible.  Window
+visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
+and initial visibility is controlled by the [window hint](@ref window_hints_wnd)
+with the same name.  
+
+`GLFW_RESIZABLE` indicates whether the specified window is resizable _by the
+user_.  This is set on creation with the [window hint](@ref window_hints_wnd)
+  with the same name.
+
+`GLFW_DECORATED` indicates whether the specified window has decorations such as
+a border, a close widget, etc.  This is set on creation with the
+[window hint](@ref window_hints_wnd) with the same name. 
+
+`GLFW_FLOATING` indicates whether the specified window is floating, also called
+topmost or always-on-top.  This is controlled by the
+[window hint](@ref window_hints_wnd) with the same name. 
+
+
+@subsubsection window_attribs_ctx Context related attributes
+
+`GLFW_CLIENT_API` indicates the client API provided by the window's context;
+either `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`.
+
+`GLFW_CONTEXT_CREATION_API` indicates the context creation API used to create
+the window's context; either `GLFW_NATIVE_CONTEXT_API` or
+`GLFW_EGL_CONTEXT_API`.
+
+`GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
+`GLFW_CONTEXT_REVISION` indicate the client API version of the window's context.
+
+`GLFW_OPENGL_FORWARD_COMPAT` is `GLFW_TRUE` if the window's context is an OpenGL
+forward-compatible one, or `GLFW_FALSE` otherwise.
+
+`GLFW_OPENGL_DEBUG_CONTEXT` is `GLFW_TRUE` if the window's context is an OpenGL
+debug context, or `GLFW_FALSE` otherwise.
+
+`GLFW_OPENGL_PROFILE` indicates the OpenGL profile used by the context.  This is
+`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context uses
+a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is unknown
+or the context is an OpenGL ES context.  Note that the returned profile may not
+match the profile bits of the context flags, as GLFW will try other means of
+detecting the profile when no bits are set.
+
+`GLFW_CONTEXT_ROBUSTNESS` indicates the robustness strategy used by the context.
+This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION` if the
+window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
+
+
+@subsubsection window_attribs_fb Framebuffer related attributes
+
+GLFW does not expose attributes of the default framebuffer (i.e. the framebuffer
+attached to the window) as these can be queried directly with either OpenGL,
+OpenGL ES or Vulkan.
+
+If you are using version 3.0 or later of OpenGL or OpenGL ES, the
+`glGetFramebufferAttachmentParameteriv` function can be used to retrieve the
+number of bits for the red, green, blue, alpha, depth and stencil buffer
+channels.  Otherwise, the `glGetIntegerv` function can be used.
+
+The number of MSAA samples are always retrieved with `glGetIntegerv`.  For
+contexts supporting framebuffer objects, the number of samples of the currently
+bound framebuffer is returned.
+
+Attribute    | glGetIntegerv     | glGetFramebufferAttachmentParameteriv
+------------ | ----------------- | -------------------------------------
+Red bits     | `GL_RED_BITS`     | `GL_FRAMEBUFFER_ATTACHMENT_RED_SIZE`
+Green bits   | `GL_GREEN_BITS`   | `GL_FRAMEBUFFER_ATTACHMENT_GREEN_SIZE`
+Blue bits    | `GL_BLUE_BITS`    | `GL_FRAMEBUFFER_ATTACHMENT_BLUE_SIZE`
+Alpha bits   | `GL_ALPHA_BITS`   | `GL_FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE`
+Depth bits   | `GL_DEPTH_BITS`   | `GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE`
+Stencil bits | `GL_STENCIL_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE`
+MSAA samples | `GL_SAMPLES`      | _Not provided by this function_
+
+When calling `glGetFramebufferAttachmentParameteriv`, the red, green, blue and
+alpha sizes are queried from the `GL_BACK_LEFT`, while the depth and stencil
+sizes are queried from the `GL_DEPTH` and `GL_STENCIL` attachments,
+respectively.
+
+
+@section buffer_swap Buffer swapping
+
+GLFW windows are by default double buffered.  That means that you have two
+rendering buffers; a front buffer and a back buffer.  The front buffer is
+the one being displayed and the back buffer the one you render to.
+
+When the entire frame has been rendered, it is time to swap the back and the
+front buffers in order to display what has been rendered and begin rendering
+a new frame.  This is done with @ref glfwSwapBuffers.
+
+@code
+glfwSwapBuffers(window);
+@endcode
+
+Sometimes it can be useful to select when the buffer swap will occur.  With the
+function @ref glfwSwapInterval it is possible to select the minimum number of
+monitor refreshes the driver wait should from the time @ref glfwSwapBuffers was
+called before swapping the buffers:
+
+@code
+glfwSwapInterval(1);
+@endcode
+
+If the interval is zero, the swap will take place immediately when @ref
+glfwSwapBuffers is called without waiting for a refresh.  Otherwise at least
+interval retraces will pass between each buffer swap.  Using a swap interval of
+zero can be useful for benchmarking purposes, when it is not desirable to
+measure the time it takes to wait for the vertical retrace.  However, a swap
+interval of one lets you avoid tearing.
+
+Note that this may not work on all machines, as some drivers have
+user-controlled settings that override any swap interval the application
+requests.
+
+*/