text:
#version 450
#extension GL_ARB_separate_shader_objects : enable

void main()
{
    vec2 outUV = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
    gl_Position = vec4(outUV * 2.0f + -1.0f, 0.0f, 1.0f);
}

repo_language: C

mime_type: text/x-c


text:
#version 450
#extension GL_ARB_separate_shader_objects : enable

layout(location = 0) in vec3 fragColor;

layout(location = 0) out vec4 outColor;

void main() {
    outColor = vec4(fragColor, 1.0);
}


text:
#version 450
#extension GL_ARB_separate_shader_objects : enable

layout(input_attachment_index = 0, set = 0, binding = 0) uniform subpassInput overlayInput;

layout(location = 0) out vec4 outColor;

void main() {
    outColor = subpassLoad(overlayInput);
}


text:
#version 450
#extension GL_ARB_separate_shader_objects : enable

out gl_PerVertex {
    vec4 gl_Position;
};

layout(location = 0) out vec3 fragColor;

vec2 positions[3] = vec2[](
    vec2(0.0, -0.5),
    vec2(0.5, 0.5),
    vec2(-0.5, 0.5)
);

vec3 colors[3] = vec3[](
    vec3(1.0, 0.0, 0.0),
    vec3(0.0, 1.0, 0.0),
    vec3(0.0, 0.0, 1.0)
);

void main() {
    gl_Position = vec4(positions[gl_VertexIndex], 0.0, 1.0);
    fragColor = colors[gl_VertexIndex];
}


text:
Copyright (c) 2002-2006 Marcus Geelnard
Copyright (c) 2006-2016 Camilla Berglund <elmindreda@glfw.org>

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.


text:
if (NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")
  message(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")
endif()

file(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)
string(REGEX REPLACE "\n" ";" files "${files}")

foreach (file ${files})
  message(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")
  if (EXISTS "$ENV{DESTDIR}${file}")
    exec_program("@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""
                 OUTPUT_VARIABLE rm_out
                 RETURN_VALUE rm_retval)
    if (NOT "${rm_retval}" STREQUAL 0)
      MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")
    endif()
  elseif (IS_SYMLINK "$ENV{DESTDIR}${file}")
    EXEC_PROGRAM("@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""
                 OUTPUT_VARIABLE rm_out
                 RETURN_VALUE rm_retval)
    if (NOT "${rm_retval}" STREQUAL 0)
      message(FATAL_ERROR "Problem when removing symlink \"$ENV{DESTDIR}${file}\"")
    endif()
  else()
    message(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")
  endif()
endforeach()


text:
set(CMAKE_LEGACY_CYGWIN_WIN32 OFF)

project(GLFW C)

cmake_minimum_required(VERSION 2.8.12)

if (NOT CMAKE_VERSION VERSION_LESS "3.0")
    # Until all major package systems have moved to CMake 3,
    # we stick with the older INSTALL_NAME_DIR mechanism
    cmake_policy(SET CMP0042 OLD)
endif()

set(GLFW_VERSION_MAJOR "3")
set(GLFW_VERSION_MINOR "2")
set(GLFW_VERSION_PATCH "1")
set(GLFW_VERSION_EXTRA "")
set(GLFW_VERSION "${GLFW_VERSION_MAJOR}.${GLFW_VERSION_MINOR}")
set(GLFW_VERSION_FULL "${GLFW_VERSION}.${GLFW_VERSION_PATCH}${GLFW_VERSION_EXTRA}")
set(LIB_SUFFIX "" CACHE STRING "Takes an empty string or 64. Directory where lib will be installed: lib or lib64")

set_property(GLOBAL PROPERTY USE_FOLDERS ON)

option(BUILD_SHARED_LIBS "Build shared libraries" OFF)
option(GLFW_BUILD_EXAMPLES "Build the GLFW example programs" ON)
option(GLFW_BUILD_TESTS "Build the GLFW test programs" ON)
option(GLFW_BUILD_DOCS "Build the GLFW documentation" ON)
option(GLFW_INSTALL "Generate installation target" ON)
option(GLFW_VULKAN_STATIC "Use the Vulkan loader statically linked into application" OFF)
option(GLFW_DOCUMENT_INTERNALS "Include internals in documentation" OFF)

if (WIN32)
    option(GLFW_USE_HYBRID_HPG "Force use of high-performance GPU on hybrid systems" OFF)
endif()

if (APPLE)
    option(GLFW_USE_CHDIR "Make glfwInit chdir to Contents/Resources" ON)
    option(GLFW_USE_MENUBAR "Populate the menu bar on first window creation" ON)
    option(GLFW_USE_RETINA "Use the full resolution of Retina displays" ON)
endif()

if (UNIX AND NOT APPLE)
    option(GLFW_USE_WAYLAND "Use Wayland for window creation" OFF)
    option(GLFW_USE_MIR     "Use Mir for window creation" OFF)
endif()

if (MSVC)
    option(USE_MSVC_RUNTIME_LIBRARY_DLL "Use MSVC runtime library DLL" ON)
endif()

if (BUILD_SHARED_LIBS)
    set(_GLFW_BUILD_DLL 1)
endif()

if (BUILD_SHARED_LIBS AND UNIX)
    # On Unix-like systems, shared libraries can use the soname system.
    set(GLFW_LIB_NAME glfw)
else()
    set(GLFW_LIB_NAME glfw3)
endif()

if (GLFW_VULKAN_STATIC)
    set(_GLFW_VULKAN_STATIC 1)
endif()

list(APPEND CMAKE_MODULE_PATH "${GLFW_SOURCE_DIR}/CMake/modules")

find_package(Threads REQUIRED)
find_package(Vulkan)

if (GLFW_BUILD_DOCS)
    set(DOXYGEN_SKIP_DOT TRUE)
    find_package(Doxygen)
endif()

#--------------------------------------------------------------------
# Set compiler specific flags
#--------------------------------------------------------------------
if (MSVC)
    if (NOT USE_MSVC_RUNTIME_LIBRARY_DLL)
        foreach (flag CMAKE_C_FLAGS
                      CMAKE_C_FLAGS_DEBUG
                      CMAKE_C_FLAGS_RELEASE
                      CMAKE_C_FLAGS_MINSIZEREL
                      CMAKE_C_FLAGS_RELWITHDEBINFO)

            if (${flag} MATCHES "/MD")
                string(REGEX REPLACE "/MD" "/MT" ${flag} "${${flag}}")
            endif()
            if (${flag} MATCHES "/MDd")
                string(REGEX REPLACE "/MDd" "/MTd" ${flag} "${${flag}}")
            endif()

        endforeach()
    endif()
endif()

if (MINGW)
    # Workaround for legacy MinGW not providing XInput and DirectInput
    include(CheckIncludeFile)

    check_include_file(dinput.h DINPUT_H_FOUND)
    check_include_file(xinput.h XINPUT_H_FOUND)
    if (NOT DINPUT_H_FOUND OR NOT XINPUT_H_FOUND)
        list(APPEND glfw_INCLUDE_DIRS "${GLFW_SOURCE_DIR}/deps/mingw")
    endif()

    # Enable link-time exploit mitigation features enabled by default on MSVC
    include(CheckCCompilerFlag)

    # Compatibility with data execution prevention (DEP)
    set(CMAKE_REQUIRED_FLAGS "-Wl,--nxcompat")
    check_c_compiler_flag("" _GLFW_HAS_DEP)
    if (_GLFW_HAS_DEP)
        set(CMAKE_SHARED_LINKER_FLAGS "-Wl,--nxcompat ${CMAKE_SHARED_LINKER_FLAGS}")
    endif()

    # Compatibility with address space layout randomization (ASLR)
    set(CMAKE_REQUIRED_FLAGS "-Wl,--dynamicbase")
    check_c_compiler_flag("" _GLFW_HAS_ASLR)
    if (_GLFW_HAS_ASLR)
        set(CMAKE_SHARED_LINKER_FLAGS "-Wl,--dynamicbase ${CMAKE_SHARED_LINKER_FLAGS}")
    endif()

    # Compatibility with 64-bit address space layout randomization (ASLR)
    set(CMAKE_REQUIRED_FLAGS "-Wl,--high-entropy-va")
    check_c_compiler_flag("" _GLFW_HAS_64ASLR)
    if (_GLFW_HAS_64ASLR)
        set(CMAKE_SHARED_LINKER_FLAGS "-Wl,--high-entropy-va ${CMAKE_SHARED_LINKER_FLAGS}")
    endif()
endif()

#--------------------------------------------------------------------
# Detect and select backend APIs
#--------------------------------------------------------------------
if (WIN32)
    set(_GLFW_WIN32 1)
    message(STATUS "Using Win32 for window creation")
elseif (APPLE)
    set(_GLFW_COCOA 1)
    message(STATUS "Using Cocoa for window creation")
elseif (UNIX)
    if (GLFW_USE_WAYLAND)
        set(_GLFW_WAYLAND 1)
        message(STATUS "Using Wayland for window creation")
    elseif (GLFW_USE_MIR)
        set(_GLFW_MIR 1)
        message(STATUS "Using Mir for window creation")
    else()
        set(_GLFW_X11 1)
        message(STATUS "Using X11 for window creation")
    endif()
else()
    message(FATAL_ERROR "No supported platform was detected")
endif()

#--------------------------------------------------------------------
# Add Vulkan static library if requested
#--------------------------------------------------------------------
if (GLFW_VULKAN_STATIC)
    if (VULKAN_FOUND AND VULKAN_STATIC_LIBRARY)
        list(APPEND glfw_LIBRARIES ${VULKAN_STATIC_LIBRARY})
    else()
        if (BUILD_SHARED_LIBS OR GLFW_BUILD_EXAMPLES OR GLFW_BUILD_TESTS)
            message(FATAL_ERROR "Vulkan loader static library not found")
        else()
            message(WARNING "Vulkan loader static library not found")
        endif()
    endif()
endif()

#--------------------------------------------------------------------
# Find and add Unix math and time libraries
#--------------------------------------------------------------------
if (UNIX AND NOT APPLE)
    find_library(RT_LIBRARY rt)
    mark_as_advanced(RT_LIBRARY)
    if (RT_LIBRARY)
        list(APPEND glfw_LIBRARIES "${RT_LIBRARY}")
        list(APPEND glfw_PKG_LIBS "-lrt")
    endif()

    find_library(MATH_LIBRARY m)
    mark_as_advanced(MATH_LIBRARY)
    if (MATH_LIBRARY)
        list(APPEND glfw_LIBRARIES "${MATH_LIBRARY}")
        list(APPEND glfw_PKG_LIBS "-lm")
    endif()

    if (CMAKE_DL_LIBS)
        list(APPEND glfw_LIBRARIES "${CMAKE_DL_LIBS}")
        list(APPEND glfw_PKG_LIBS "-l${CMAKE_DL_LIBS}")
    endif()
endif()

#--------------------------------------------------------------------
# Use Win32 for window creation
#--------------------------------------------------------------------
if (_GLFW_WIN32)

    list(APPEND glfw_PKG_LIBS "-lgdi32")

    if (GLFW_USE_HYBRID_HPG)
        set(_GLFW_USE_HYBRID_HPG 1)
    endif()
endif()

#--------------------------------------------------------------------
# Use X11 for window creation
#--------------------------------------------------------------------
if (_GLFW_X11)

    find_package(X11 REQUIRED)

    list(APPEND glfw_PKG_DEPS "x11")

    # Set up library and include paths
    list(APPEND glfw_INCLUDE_DIRS "${X11_X11_INCLUDE_PATH}")
    list(APPEND glfw_LIBRARIES "${X11_X11_LIB}" "${CMAKE_THREAD_LIBS_INIT}")

    # Check for XRandR (modern resolution switching and gamma control)
    if (NOT X11_Xrandr_FOUND)
        message(FATAL_ERROR "The RandR library and headers were not found")
    endif()

    list(APPEND glfw_INCLUDE_DIRS "${X11_Xrandr_INCLUDE_PATH}")
    list(APPEND glfw_LIBRARIES "${X11_Xrandr_LIB}")
    list(APPEND glfw_PKG_DEPS "xrandr")

    # Check for Xinerama (legacy multi-monitor support)
    if (NOT X11_Xinerama_FOUND)
        message(FATAL_ERROR "The Xinerama library and headers were not found")
    endif()

    list(APPEND glfw_INCLUDE_DIRS "${X11_Xinerama_INCLUDE_PATH}")
    list(APPEND glfw_LIBRARIES "${X11_Xinerama_LIB}")
    list(APPEND glfw_PKG_DEPS "xinerama")

    # Check for Xf86VidMode (fallback gamma control)
    if (X11_xf86vmode_FOUND)
        list(APPEND glfw_INCLUDE_DIRS "${X11_xf86vmode_INCLUDE_PATH}")
        list(APPEND glfw_PKG_DEPS "xxf86vm")

        if (X11_Xxf86vm_LIB)
            list(APPEND glfw_LIBRARIES "${X11_Xxf86vm_LIB}")
        else()
            # Backwards compatibility (see CMake bug 0006976)
            list(APPEND glfw_LIBRARIES Xxf86vm)
        endif()

        set(_GLFW_HAS_XF86VM TRUE)
    endif()

    # Check for Xkb (X keyboard extension)
    if (NOT X11_Xkb_FOUND)
        message(FATAL_ERROR "The X keyboard extension headers were not found")
    endif()

    list(APPEND glfw_INCLUDE_DIR "${X11_Xkb_INCLUDE_PATH}")

    # Check for Xcursor
    if (NOT X11_Xcursor_FOUND)
        message(FATAL_ERROR "The Xcursor libraries and headers were not found")
    endif()

    list(APPEND glfw_INCLUDE_DIR "${X11_Xcursor_INCLUDE_PATH}")
    list(APPEND glfw_LIBRARIES "${X11_Xcursor_LIB}")
    list(APPEND glfw_PKG_DEPS "xcursor")

endif()

#--------------------------------------------------------------------
# Use Wayland for window creation
#--------------------------------------------------------------------
if (_GLFW_WAYLAND)
    find_package(ECM REQUIRED NO_MODULE)
    list(APPEND CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

    find_package(Wayland REQUIRED)
    find_package(WaylandScanner REQUIRED)
    find_package(WaylandProtocols 1.1 REQUIRED)

    list(APPEND glfw_PKG_DEPS "wayland-egl")

    list(APPEND glfw_INCLUDE_DIRS "${Wayland_INCLUDE_DIR}")
    list(APPEND glfw_LIBRARIES "${Wayland_LIBRARIES}" "${CMAKE_THREAD_LIBS_INIT}")

    find_package(XKBCommon REQUIRED)
    list(APPEND glfw_PKG_DEPS "xkbcommon")
    list(APPEND glfw_INCLUDE_DIRS "${XKBCOMMON_INCLUDE_DIRS}")
    list(APPEND glfw_LIBRARIES "${XKBCOMMON_LIBRARY}")
endif()

#--------------------------------------------------------------------
# Use Mir for window creation
#--------------------------------------------------------------------
if (_GLFW_MIR)
    find_package(Mir REQUIRED)
    list(APPEND glfw_PKG_DEPS "mirclient")

    list(APPEND glfw_INCLUDE_DIRS "${MIR_INCLUDE_DIR}")
    list(APPEND glfw_LIBRARIES "${MIR_LIBRARIES}" "${CMAKE_THREAD_LIBS_INIT}")

    find_package(XKBCommon REQUIRED)
    list(APPEND glfw_PKG_DEPS "xkbcommon")
    list(APPEND glfw_INCLUDE_DIRS "${XKBCOMMON_INCLUDE_DIRS}")
    list(APPEND glfw_LIBRARIES "${XKBCOMMON_LIBRARY}")
endif()

#--------------------------------------------------------------------
# Use Cocoa for window creation and NSOpenGL for context creation
#--------------------------------------------------------------------
if (_GLFW_COCOA)

    if (GLFW_USE_MENUBAR)
        set(_GLFW_USE_MENUBAR 1)
    endif()

    if (GLFW_USE_CHDIR)
        set(_GLFW_USE_CHDIR 1)
    endif()

    if (GLFW_USE_RETINA)
        set(_GLFW_USE_RETINA 1)
    endif()

    # Set up library and include paths
    find_library(COCOA_FRAMEWORK Cocoa)
    find_library(IOKIT_FRAMEWORK IOKit)
    find_library(CORE_FOUNDATION_FRAMEWORK CoreFoundation)
    find_library(CORE_VIDEO_FRAMEWORK CoreVideo)
    mark_as_advanced(COCOA_FRAMEWORK
                     IOKIT_FRAMEWORK
                     CORE_FOUNDATION_FRAMEWORK
                     CORE_VIDEO_FRAMEWORK)
    list(APPEND glfw_LIBRARIES "${COCOA_FRAMEWORK}"
                               "${IOKIT_FRAMEWORK}"
                               "${CORE_FOUNDATION_FRAMEWORK}"
                               "${CORE_VIDEO_FRAMEWORK}")

    set(glfw_PKG_DEPS "")
    set(glfw_PKG_LIBS "-framework Cocoa -framework IOKit -framework CoreFoundation -framework CoreVideo")
endif()

#--------------------------------------------------------------------
# Export GLFW library dependencies
#--------------------------------------------------------------------
foreach(arg ${glfw_PKG_DEPS})
    set(GLFW_PKG_DEPS "${GLFW_PKG_DEPS} ${arg}")
endforeach()
foreach(arg ${glfw_PKG_LIBS})
    set(GLFW_PKG_LIBS "${GLFW_PKG_LIBS} ${arg}")
endforeach()

#--------------------------------------------------------------------
# Create generated files
#--------------------------------------------------------------------
include(CMakePackageConfigHelpers)

set(GLFW_CONFIG_PATH "lib${LIB_SUFFIX}/cmake/glfw3")

configure_package_config_file(src/glfw3Config.cmake.in
                              src/glfw3Config.cmake
                              INSTALL_DESTINATION "${GLFW_CONFIG_PATH}"
                              NO_CHECK_REQUIRED_COMPONENTS_MACRO)

write_basic_package_version_file(src/glfw3ConfigVersion.cmake
                                 VERSION ${GLFW_VERSION_FULL}
                                 COMPATIBILITY SameMajorVersion)

configure_file(src/glfw_config.h.in src/glfw_config.h @ONLY)

configure_file(src/glfw3.pc.in src/glfw3.pc @ONLY)

#--------------------------------------------------------------------
# Add subdirectories
#--------------------------------------------------------------------
add_subdirectory(src)

if (GLFW_BUILD_EXAMPLES)
    add_subdirectory(examples)
endif()

if (GLFW_BUILD_TESTS)
    add_subdirectory(tests)
endif()

if (DOXYGEN_FOUND AND GLFW_BUILD_DOCS)
    add_subdirectory(docs)
endif()

#--------------------------------------------------------------------
# Install files other than the library
# The library is installed by src/CMakeLists.txt
#--------------------------------------------------------------------
if (GLFW_INSTALL)
    install(DIRECTORY include/GLFW DESTINATION include
            FILES_MATCHING PATTERN glfw3.h PATTERN glfw3native.h)

    install(FILES "${GLFW_BINARY_DIR}/src/glfw3Config.cmake"
                  "${GLFW_BINARY_DIR}/src/glfw3ConfigVersion.cmake"
            DESTINATION "${GLFW_CONFIG_PATH}")

    install(EXPORT glfwTargets FILE glfw3Targets.cmake
            EXPORT_LINK_INTERFACE_LIBRARIES
            DESTINATION "${GLFW_CONFIG_PATH}")
    install(FILES "${GLFW_BINARY_DIR}/src/glfw3.pc"
            DESTINATION "lib${LIB_SUFFIX}/pkgconfig")

    # Only generate this target if no higher-level project already has
    if (NOT TARGET uninstall)
        configure_file(cmake_uninstall.cmake.in
                       cmake_uninstall.cmake IMMEDIATE @ONLY)

        add_custom_target(uninstall
                          "${CMAKE_COMMAND}" -P
                          "${GLFW_BINARY_DIR}/cmake_uninstall.cmake")
    endif()
endif()


text:
# GLFW

[![Build status](https://travis-ci.org/glfw/glfw.svg?branch=master)](https://travis-ci.org/glfw/glfw)
[![Build status](https://ci.appveyor.com/api/projects/status/0kf0ct9831i5l6sp/branch/master?svg=true)](https://ci.appveyor.com/project/elmindreda/glfw)
[![Coverity Scan](https://scan.coverity.com/projects/4884/badge.svg)](https://scan.coverity.com/projects/glfw-glfw)

## Introduction

GLFW is an Open Source, multi-platform library for OpenGL, OpenGL ES and Vulkan
application development.  It provides a simple, platform-independent API for
creating windows, contexts and surfaces, reading input, handling events, etc.

GLFW is licensed under the [zlib/libpng
license](https://opensource.org/licenses/Zlib).

This is version 3.2.1, which adds support for statically linking the Vulkan
loader and fixes for a number of bugs that together affect all supported
platforms.

See the [downloads](http://www.glfw.org/download.html) page for details and
files, or fetch the `latest` branch, which always points to the latest stable
release.  Each release starting with 3.0 also has a corresponding [annotated
tag](https://github.com/glfw/glfw/releases) with source and binary archives.

If you are new to GLFW, you may find the
[tutorial](http://www.glfw.org/docs/latest/quick.html) for GLFW
3 useful.  If you have used GLFW 2 in the past, there is a
[transition guide](http://www.glfw.org/docs/latest/moving.html) for moving to
the GLFW 3 API.

## Compiling GLFW

GLFW itself requires only the headers and libraries for your window system.  It
does not need the headers for any context creation API (WGL, GLX, EGL, NSGL) or
rendering API (OpenGL, OpenGL ES, Vulkan) to enable support for them.

GLFW supports compilation on Windows with Visual C++ 2010 and later, MinGW and
MinGW-w64, on OS X with Clang and on Linux and other Unix-like systems with GCC
and Clang.  It will likely compile in other environments as well, but this is
not regularly tested.

There are also [pre-compiled Windows
binaries](http://www.glfw.org/download.html) available for all compilers
supported on that platform.

See the [compilation guide](http://www.glfw.org/docs/latest/compile.html) in the
documentation for more information.

## Using GLFW

See the [building application guide](http://www.glfw.org/docs/latest/build.html)
guide in the documentation for more information.

## System requirements

GLFW supports Windows XP and later, OS X 10.7 Lion and later, and Linux and
other Unix-like systems with the X Window System.  Experimental implementations
for the Wayland protocol and the Mir display server are available but not yet
officially supported.

See the [compatibility guide](http://www.glfw.org/docs/latest/compat.html)
in the documentation for more information.

## Dependencies

GLFW itself depends only on the headers and libraries for your window system.

The examples and test programs depend on a number of tiny libraries.  These are
located in the `deps/` directory.

 - [getopt\_port](https://github.com/kimgr/getopt_port/) for examples
   with command-line options
 - [TinyCThread](https://github.com/tinycthread/tinycthread) for threaded
   examples
 - An OpenGL 3.2 core loader generated by
   [glad](https://github.com/Dav1dde/glad) for examples using modern OpenGL
 - [linmath.h](https://github.com/datenwolf/linmath.h) for linear algebra in
   examples
 - [Vulkan headers](https://www.khronos.org/registry/vulkan/) for Vulkan tests

The Vulkan example additionally requires the Vulkan SDK to be installed, or it
will not be included in the build.

The documentation is generated with [Doxygen](http://doxygen.org/).  If CMake
does not find Doxygen, the documentation will not be generated when you build.

## Reporting bugs

Bugs are reported to our [issue tracker](https://github.com/glfw/glfw/issues).
Please check the [contribution
guide](https://github.com/glfw/glfw/blob/master/.github/CONTRIBUTING.md) for
information on what to include when reporting a bug.

## Changelog

 - Added on-demand loading of Vulkan and context creation API libraries
 - Added `_GLFW_VULKAN_STATIC` build macro to make the library use the Vulkan
   loader linked statically into the application (#820)
 - Bugfix: Single compilation unit builds failed due to naming conflicts (#783)
 - Bugfix: The range checks for `glfwSetCursorPos` used the wrong minimum (#773)
 - Bugfix: Defining `GLFW_INCLUDE_VULKAN` when compiling the library did not
           fail with the expected error message (#823)
 - Bugfix: Inherited value of `CMAKE_MODULE_PATH` was clobbered (#822)
 - [Win32] Bugfix: `glfwSetClipboardString` created an unnecessary intermediate
                   copy of the string
 - [Win32] Bugfix: Examples failed to build on Visual C++ 2010 due to C99 in
                   `linmath.h` (#785)
 - [Win32] Bugfix: The first shown window ignored the `GLFW_MAXIMIZED` hint
                   when the process was provided a `STARTUPINFO` (#780)
 - [Cocoa] Bugfix: Event processing would segfault on some machines due to
                   a previous distributed notification listener not being fully
                   removed (#817,#826)
 - [Cocoa] Bugfix: Some include statements were duplicated (#838)
 - [X11] Bugfix: Window size limits were ignored if the minimum or maximum size
                 was set to `GLFW_DONT_CARE` (#805)
 - [X11] Bugfix: Input focus was set before window was visible, causing
                 `BadMatch` on some non-reparenting WMs (#789,#798)
 - [X11] Bugfix: `glfwGetWindowPos` and `glfwSetWindowPos` operated on the
                 window frame instead of the client area (#800)
 - [WGL] Added reporting of errors from `WGL_ARB_create_context` extension
 - [GLX] Bugfix: Dynamically loaded entry points were not verified
 - [EGL] Added `lib` prefix matching between EGL and OpenGL ES library binaries
 - [EGL] Bugfix: Dynamically loaded entry points were not verified

## Contact

On [glfw.org](http://www.glfw.org/) you can find the latest version of GLFW, as
well as news, documentation and other information about the project.

If you have questions related to the use of GLFW, we have a
[forum](http://discourse.glfw.org/), and the `#glfw` IRC channel on
[Freenode](http://freenode.net/).

If you have a bug to report, a patch to submit or a feature you'd like to
request, please file it in the
[issue tracker](https://github.com/glfw/glfw/issues) on GitHub.

Finally, if you're interested in helping out with the development of GLFW or
porting it to your favorite platform, join us on the forum, GitHub or IRC.

## Acknowledgements

GLFW exists because people around the world donated their time and lent their
skills.

 - Bobyshev Alexander
 - artblanc
 - arturo
 - Matt Arsenault
 - Keith Bauer
 - John Bartholomew
 - Niklas Behrens
 - Niklas Bergström
 - Doug Binks
 - blanco
 - Martin Capitanio
 - Chi-kwan Chan
 - Lambert Clara
 - Andrew Corrigan
 - Noel Cower
 - Jarrod Davis
 - Olivier Delannoy
 - Paul R. Deppe
 - Michael Dickens
 - Роман Донченко
 - Mario Dorn
 - Jonathan Dummer
 - Ralph Eastwood
 - Siavash Eliasi
 - Michael Fogleman
 - Gerald Franz
 - GeO4d
 - Marcus Geelnard
 - Eloi Marín Gratacós
 - Stefan Gustavson
 - Sylvain Hellegouarch
 - Matthew Henry
 - heromyth
 - Lucas Hinderberger
 - Paul Holden
 - Warren Hu
 - IntellectualKitty
 - Aaron Jacobs
 - Erik S. V. Jansson
 - Toni Jovanoski
 - Arseny Kapoulkine
 - Osman Keskin
 - Cameron King
 - Peter Knut
 - Christoph Kubisch
 - Eric Larson
 - Robin Leffmann
 - Glenn Lewis
 - Shane Liesegang
 - Eyal Lotem
 - Дмитри Малышев
 - Martins Mozeiko
 - Tristam MacDonald
 - Hans Mackowiak
 - Zbigniew Mandziejewicz
 - Kyle McDonald
 - David Medlock
 - Bryce Mehring
 - Jonathan Mercier
 - Marcel Metz
 - Jonathan Miller
 - Kenneth Miller
 - Bruce Mitchener
 - Jack Moffitt
 - Jeff Molofee
 - Jon Morton
 - Pierre Moulon
 - Julian Møller
 - Kamil Nowakowski
 - Ozzy
 - Andri Pálsson
 - Peoro
 - Braden Pellett
 - Arturo J. Pérez
 - Orson Peters
 - Emmanuel Gil Peyrot
 - Cyril Pichard
 - Pieroman
 - Philip Rideout
 - Jorge Rodriguez
 - Ed Ropple
 - Aleksey Rybalkin
 - Riku Salminen
 - Brandon Schaefer
 - Sebastian Schuberth
 - Matt Sealey
 - SephiRok
 - Steve Sexton
 - Systemcluster
 - Yoshiki Shibukawa
 - Dmitri Shuralyov
 - Daniel Skorupski
 - Bradley Smith
 - Patrick Snape
 - Julian Squires
 - Johannes Stein
 - Justin Stoecker
 - Elviss Strazdins
 - Nathan Sweet
 - TTK-Bandit
 - Sergey Tikhomirov
 - Arthur Tombs
 - Ioannis Tsakpinis
 - Samuli Tuomola
 - urraka
 - Jari Vetoniemi
 - Ricardo Vieira
 - Nicholas Vitovitch
 - Simon Voordouw
 - Torsten Walluhn
 - Patrick Walton
 - Xo Wang
 - Jay Weisskopf
 - Frank Wille
 - yuriks
 - Santi Zupancic
 - Jonas Ådahl
 - Lasse Öörni
 - All the unmentioned and anonymous contributors in the GLFW community, for bug
   reports, patches, feedback, testing and encouragement


text:
/*!

@page build_guide Building applications

@tableofcontents

This is about compiling and linking applications that use GLFW.  For information on
how to write such applications, start with the
[introductory tutorial](@ref quick_guide).  For information on how to compile
the GLFW library itself, see @ref compile_guide.

This is not a tutorial on compilation or linking.  It assumes basic
understanding of how to compile and link a C program as well as how to use the
specific compiler of your chosen development environment.  The compilation
and linking process should be explained in your C programming material and in
the documentation for your development environment.

@section build_include Including the GLFW header file

In the source files of your application where you use OpenGL or GLFW, you should
include the GLFW header file, i.e.:

@code
#include <GLFW/glfw3.h>
@endcode

The GLFW header declares the GLFW API and by default also includes the OpenGL
header of your development environment, which in turn defines all the constants,
types and function prototypes of the OpenGL API.

The GLFW header also defines everything necessary for your OpenGL header to
function.  For example, under Windows you are normally required to include
`windows.h` before the OpenGL header, which would pollute your code namespace
with the entire Win32 API.

Instead, the GLFW header takes care of this for you, not by including
`windows.h`, but by duplicating only the very few necessary parts of it.  It
does this only when needed, so if `windows.h` _is_ included, the GLFW header
does not try to redefine those symbols.  The reverse is not true, i.e.
`windows.h` cannot cope if any of its symbols have already been defined.

In other words:

 - Do _not_ include the OpenGL headers yourself, as GLFW does this for you
 - Do _not_ include `windows.h` or other platform-specific headers unless you
   plan on using those APIs directly
 - If you _do_ need to include such headers, do it _before_ including
   the GLFW header and it will handle this

If you are using an OpenGL extension loading library such as
[glad](https://github.com/Dav1dde/glad), the extension loader header should
either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
(described below) should be defined.

@subsection build_macros GLFW header option macros

These macros may be defined before the inclusion of the GLFW header and affect
its behavior.

`GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler
that the GLFW functions are defined in a DLL.

The following macros control which OpenGL or OpenGL ES API header is included.
Only one of these may be defined at a time.

`GLFW_INCLUDE_GLCOREARB` makes the GLFW header include the modern
`GL/glcorearb.h` header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL
header.

`GLFW_INCLUDE_ES1` makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
header instead of the regular OpenGL header.

`GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h`
header instead of the regular OpenGL header.

`GLFW_INCLUDE_ES3` makes the GLFW header include the OpenGL ES 3.0 `GLES3/gl3.h`
header instead of the regular OpenGL header.

`GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h`
header instead of the regular OpenGL header.

`GLFW_INCLUDE_VULKAN` makes the GLFW header include the Vulkan `vulkan/vulkan.h`
header instead of the regular OpenGL header.

`GLFW_INCLUDE_NONE` makes the GLFW header not include any OpenGL or OpenGL ES API
header.  This is useful in combination with an extension loading library.

If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
header (`OpenGL/gl.h` on OS X) is included.

The following macros control the inclusion of additional API headers.  Any
number of these may be defined simultaneously, and/or together with one of the
above macros.

`GLFW_INCLUDE_GLEXT` makes the GLFW header include the appropriate extension
header for the OpenGL or OpenGL ES header selected above after and in addition
to that header.

`GLFW_INCLUDE_GLU` makes the header include the GLU header in addition to the
header selected above.  This should only be used with the standard OpenGL header
and only for compatibility with legacy code.  GLU has been deprecated and should
not be used in new code.

@note GLFW does not provide any of the API headers mentioned above.  They must
be provided by your development environment or your OpenGL, OpenGL ES or Vulkan
SDK.

@note None of these macros may be defined during the compilation of GLFW itself.
If your build includes GLFW and you define any these in your build files, make
sure they are not applied to the GLFW sources.

@section build_link Link with the right libraries

GLFW is essentially a wrapper of various platform-specific APIs and therefore
needs to link against many different system libraries.  If you are using GLFW as
a shared library / dynamic library / DLL then it takes care of these links.
However, if you are using GLFW as a static library then your executable will
need to link against these libraries.

On Windows and OS X, the list of system libraries is static and can be
hard-coded into your build environment.  See the section for your development
environment below.  On Linux and other Unix-like operating systems, the list
varies but can be retrieved in various ways as described below.

A good general introduction to linking is
[Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by
David Drysdale.

@subsection build_link_win32 With MinGW or Visual C++ on Windows

The static version of the GLFW library is named `glfw3`.  When using this
version, it is also necessary to link with some libraries that GLFW uses.

When linking an application under Windows that uses the static version of GLFW,
you must link with `opengl32`.  On some versions of MinGW, you must also
explicitly link with `gdi32`, while other versions of MinGW include it in the
set of default libraries along with other dependencies like `user32` and
`kernel32`.  If you are using GLU, you must also link with `glu32`.

The link library for the GLFW DLL is named `glfw3dll`.  When compiling an
application that uses the DLL version of GLFW, you need to define the `GLFW_DLL`
macro _before_ any inclusion of the GLFW header.  This can be done either with
a compiler switch or by defining it in your source code.

An application using the GLFW DLL does not need to link against any of its
dependencies, but you still have to link against `opengl32` if your application
uses OpenGL and `glu32` if it uses GLU.

@subsection build_link_cmake_source With CMake and GLFW source

This section is about using CMake to compile and link GLFW along with your
application.  If you want to use an installed binary instead, see @ref
build_link_cmake_package.

With just a few changes to your `CMakeLists.txt` you can have the GLFW source
tree built along with your application.

When including GLFW as part of your build, you probably don't want to build the
GLFW tests, examples and documentation.  To disable these, set the corresponding
cache variables before adding the GLFW source tree.

@code
set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)
set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
@endcode

Then add the root directory of the GLFW source tree to your project.  This
will add the `glfw` target and the necessary cache variables to your project.

@code{.cmake}
add_subdirectory(path/to/glfw)
@endcode

Once GLFW has been added to the project, link against it with the `glfw` target.
This adds all link-time dependencies of GLFW as it is currently configured,
the include directory for the GLFW header and, when applicable, the
[GLFW_DLL](@ref build_macros) macro.

@code{.cmake}
target_link_libraries(myapp glfw)
@endcode

Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
If your application calls OpenGL directly, instead of using a modern
[extension loader library](@ref context_glext_auto) you can find it by requiring
the OpenGL package.

@code{.cmake}
find_package(OpenGL REQUIRED)
@endcode

If OpenGL is found, the `OPENGL_FOUND` variable is true and the
`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.

@code{.cmake}
target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
@endcode

The OpenGL CMake package also looks for GLU.  If GLU is found, the
`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
`OPENGL_glu_LIBRARY` cache variables can be used.

@code{.cmake}
target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
@endcode

@note GLU has been deprecated and should not be used in new code, but some
legacy code requires it.

@subsection build_link_cmake_package With CMake and installed GLFW binaries

This section is about using CMake to link GLFW after it has been built and
installed.  If you want to build it along with your application instead, see
@ref build_link_cmake_source.

With just a few changes to your `CMakeLists.txt`, you can locate the package and
target files generated when GLFW is installed.

@code{.cmake}
find_package(glfw3 3.2 REQUIRED)
@endcode

Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
If your application calls OpenGL directly, instead of using a modern
[extension loader library](@ref context_glext_auto) you can find it by requiring
the OpenGL package.

@code{.cmake}
find_package(OpenGL REQUIRED)
@endcode

If OpenGL is found, the `OPENGL_FOUND` variable is true and the
`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.

@code{.cmake}
target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
@endcode

The OpenGL CMake package also looks for GLU.  If GLU is found, the
`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
`OPENGL_glu_LIBRARY` cache variables can be used.

@code{.cmake}
target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
@endcode

@note GLU has been deprecated and should not be used in new code, but some
legacy code requires it.

@subsection build_link_pkgconfig With makefiles and pkg-config on Unix

GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/),
and the `glfw3.pc` pkg-config file is generated when the GLFW library is built
and is installed along with it.  A pkg-config file describes all necessary
compile-time and link-time flags and dependencies needed to use a library.  When
they are updated or if they differ between systems, you will get the correct
ones automatically.

A typical compile and link command-line when using the static version of the
GLFW library may look like this:

@code{.sh}
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
@endcode

If you are using the shared version of the GLFW library, simply omit the
`--static` flag.

@code{.sh}
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
@endcode

You can also use the `glfw3.pc` file without installing it first, by using the
`PKG_CONFIG_PATH` environment variable.

@code{.sh}
env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
@endcode

The dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL
ES or Vulkan libraries it needs at runtime and does not use GLU.  On OS X, GLU
is built into the OpenGL framework, so if you need GLU you don't need to do
anything extra.  If you need GLU and are using Linux or BSD, you should add the
`glu` pkg-config package.

@code{.sh}
cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
@endcode

@note GLU has been deprecated and should not be used in new code, but some
legacy code requires it.

If you are using the static version of the GLFW library, make sure you don't
link statically against GLU.

@code{.sh}
cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`
@endcode

@subsection build_link_xcode With Xcode on OS X

If you are using the dynamic library version of GLFW, simply add it to the
project dependencies.

If you are using the static library version of GLFW, add it and the Cocoa,
OpenGL, IOKit and CoreVideo frameworks to the project as dependencies.  They can
all be found in `/System/Library/Frameworks`.

@subsection build_link_osx With command-line on OS X

It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when
building from the command line on OS X.  That way you will get any new
dependencies added automatically.  If you still wish to build manually, you need
to add the required frameworks and libraries to your command-line yourself using
the `-l` and `-framework` switches.

If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do:

@code{.sh}
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
@endcode

If you are using the static library, named `libglfw3.a`, substitute `-lglfw3`
for `-lglfw`.

Note that you do not add the `.framework` extension to a framework when linking
against it from the command-line.

The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
special to do when using GLU.  Also note that even though your machine may have
`libGL`-style OpenGL libraries, they are for use with the X Window System and
will _not_ work with the OS X native version of GLFW.

*/


text:
/*!

@mainpage notitle

@section main_intro Introduction

GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and
Vulkan application development.  It provides a simple, platform-independent API
for creating windows, contexts and surfaces, reading input, handling events, etc.

See @ref news_32 for release highlights or the
[version history](http://www.glfw.org/changelog.html) for details.

@ref quick_guide is a guide for users new to GLFW.  It takes you through how to
write a small but complete program.

There are guides for each section of the API:

 - @ref intro_guide – initialization, error handling and high-level design
 - @ref window_guide – creating and working with windows and framebuffers
 - @ref context_guide – working with OpenGL and OpenGL ES contexts
 - @ref vulkan_guide - working with Vulkan objects and extensions
 - @ref monitor_guide – enumerating and working with monitors and video modes
 - @ref input_guide – receiving events, polling and processing input

Once you have written a program, see @ref compile_guide and @ref build_guide.

The [reference documentation](modules.html) provides more detailed information
about specific functions.

@ref moving_guide explains what has changed and how to update existing code to
use the new API.

There is a section on @ref guarantees_limitations for pointer lifetimes,
reentrancy, thread safety, event order and backward and forward compatibility.

The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
design, implementation and use of GLFW.

Finally, @ref compat_guide explains what APIs, standards and protocols GLFW uses
and what happens when they are not present on a given machine.

This documentation was generated with Doxygen.  The sources for it are available
in both the [source distribution](http://www.glfw.org/download.html) and
[GitHub repository](https://github.com/glfw/glfw).

*/


text:
/*!

@page intro_guide Introduction to the API

@tableofcontents

This guide introduces the basic concepts of GLFW and describes initialization,
error handling and API guarantees and limitations.  For a broad but shallow
tutorial, see @ref quick_guide instead.  For details on a specific function in
this category, see the @ref init.

There are also guides for the other areas of GLFW.

 - @ref window_guide
 - @ref context_guide
 - @ref vulkan_guide
 - @ref monitor_guide
 - @ref input_guide

@section intro_init Initialization and termination

Before most GLFW functions may be called, the library must be initialized.
This initialization checks what features are available on the machine,
enumerates monitors and joysticks, initializes the timer and performs any
required platform-specific initialization.

Only the following functions may be called before the library has been
successfully initialized, and only from the main thread.

 - @ref glfwGetVersion
 - @ref glfwGetVersionString
 - @ref glfwSetErrorCallback
 - @ref glfwInit
 - @ref glfwTerminate

Calling any other function before successful initialization will cause a @ref
GLFW_NOT_INITIALIZED error.

@subsection intro_init_init Initializing GLFW

The library is initialized with @ref glfwInit, which returns `GLFW_FALSE` if an
error occurred.

@code
if (!glfwInit())
{
    // Handle initialization failure
}
@endcode

If any part of initialization fails, any parts that succeeded are terminated as
if @ref glfwTerminate had been called.  The library only needs to be initialized
once and additional calls to an already initialized library will simply return
`GLFW_TRUE` immediately.

Once the library has been successfully initialized, it should be terminated
before the application exits.  Modern systems are very good at freeing resources
allocated by programs that simply exit, but GLFW sometimes has to change global
system settings and these might not be restored without termination.

@subsection intro_init_terminate Terminating GLFW

Before your application exits, you should terminate the GLFW library if it has
been initialized.  This is done with @ref glfwTerminate.

@code
glfwTerminate();
@endcode

This will destroy any remaining window, monitor and cursor objects, restore any
modified gamma ramps, re-enable the screensaver if it had been disabled and free
any other resources allocated by GLFW.

Once the library is terminated, it is as if it had never been initialized and
you will need to initialize it again before being able to use GLFW.  If the
library was not initialized or had already been terminated, it return
immediately.

@section error_handling Error handling

Some GLFW functions have return values that indicate an error, but this is often
not very helpful when trying to figure out _why_ the error occurred.  Some
functions also return otherwise valid values on error.  Finally, far from all
GLFW functions have return values.

This is where the error callback comes in.  This callback is called whenever an
error occurs.  It is set with @ref glfwSetErrorCallback, a function that may be
called regardless of whether GLFW is initialized.

@code
glfwSetErrorCallback(error_callback);
@endcode

The error callback receives a human-readable description of the error and (when
possible) its cause.  The description encoded as UTF-8.  The callback is also
provided with an [error code](@ref errors).

@code
void error_callback(int error, const char* description)
{
    puts(description);
}
@endcode

The error code indicates the general category of the error.  Some error codes,
such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
@ref GLFW_PLATFORM_ERROR are used for many different errors.

The description string is only valid until the error callback returns, as it may
have been generated specifically for that error.  This lets GLFW provide much
more specific error descriptions but means you must make a copy if you want to
keep the description string.

@note Relying on erroneous behavior is not forward compatible.  In other words,
do not rely on a currently invalid call to generate a specific error, as that
same call may in future versions generate a different error or become valid.

@section coordinate_systems Coordinate systems

GLFW has two primary coordinate systems: the _virtual screen_ and the window
_client area_ or _content area_.  Both use the same unit: _virtual screen
coordinates_, or just _screen coordinates_, which don't necessarily correspond
to pixels.

<img src="spaces.svg" width="90%" />

Both the virtual screen and the client area coordinate systems have the X-axis
pointing to the right and the Y-axis pointing down.

Window and monitor positions are specified as the position of the upper-left
corners of their content areas relative to the virtual screen, while cursor
positions are specified relative to a window's client area.

Because the origin of the window's client area coordinate system is also the
point from which the window position is specified, you can translate client area
coordinates to the virtual screen by adding the window position.  The window
frame, when present, extends out from the client area but does not affect the
window position.

Almost all positions and sizes in GLFW are measured in screen coordinates
relative to one of the two origins above.  This includes cursor positions,
window positions and sizes, window frame sizes, monitor positions and video mode
resolutions.

Two exceptions are the [monitor physical size](@ref monitor_size), which is
measured in millimetres, and [framebuffer size](@ref window_fbsize), which is
measured in pixels.

Pixels and screen coordinates may map 1:1 on your machine, but they won't on
every other machine, for example on a Mac with a Retina display.  The ratio
between screen coordinates and pixels may also change at run-time depending on
which monitor the window is currently considered to be on.

@section guarantees_limitations Guarantees and limitations

This section describes the conditions under which GLFW can be expected to
function, barring bugs in the operating system or drivers.  Use of GLFW outside
of these limits may work on some platforms, or on some machines, or some of the
time, or on some versions of GLFW, but it may break at any time and this will
not be considered a bug.

@subsection lifetime Pointer lifetimes

GLFW will never free any pointer you provide to it and you must never free any
pointer it provides to you.

Many GLFW functions return pointers to dynamically allocated structures, strings
or arrays, and some callbacks are provided with strings or arrays.  These are
always managed by GLFW and should never be freed by the application.  The
lifetime of these pointers is documented for each GLFW function and callback.
If you need to keep this data, you must copy it before its lifetime expires.

Many GLFW functions accept pointers to structures or strings allocated by the
application.  These are never freed by GLFW and are always the responsibility of
the application.  If GLFW needs to keep the data in these structures or strings,
it is copied before the function returns.

Pointer lifetimes are guaranteed not to be shortened in future minor or patch
releases.

@subsection reentrancy Reentrancy

GLFW event processing and object creation and destruction are not reentrant.
This means that the following functions must not be called from any callback
function:

 - @ref glfwCreateWindow
 - @ref glfwDestroyWindow
 - @ref glfwCreateCursor
 - @ref glfwCreateStandardCursor
 - @ref glfwDestroyCursor
 - @ref glfwPollEvents
 - @ref glfwWaitEvents
 - @ref glfwWaitEventsTimeout
 - @ref glfwTerminate

These functions may be made reentrant in future minor or patch releases, but
functions not on this list will not be made non-reentrant.

@subsection thread_safety Thread safety

Most GLFW functions must only be called from the main thread, but some may be
called from any thread.  However, no GLFW function may be called from any thread
but the main thread until GLFW has been successfully initialized, including
functions that may called before initialization.

The reference documentation for every GLFW function states whether it is limited
to the main thread.

Initialization and termination, event processing and the creation and
destruction of windows, contexts and cursors are all limited to the main thread
due to limitations of one or several platforms.

Because event processing must be performed on the main thread, all callbacks
except for the error callback will only be called on that thread.  The error
callback may be called on any thread, as any GLFW function may generate errors.

The posting of empty events may be done from any thread.  The window user
pointer and close flag may also be accessed and modified from any thread, but
this is not synchronized by GLFW.  The following window related functions may
be called from any thread:

 - @ref glfwPostEmptyEvent
 - @ref glfwGetWindowUserPointer
 - @ref glfwSetWindowUserPointer
 - @ref glfwWindowShouldClose
 - @ref glfwSetWindowShouldClose

Rendering may be done on any thread.  The following context related functions
may be called from any thread:

 - @ref glfwMakeContextCurrent
 - @ref glfwGetCurrentContext
 - @ref glfwSwapBuffers
 - @ref glfwSwapInterval
 - @ref glfwExtensionSupported
 - @ref glfwGetProcAddress

The raw timer may be queried from any thread.  The following raw timer related
functions may be called from any thread:

 - @ref glfwGetTimerFrequency
 - @ref glfwGetTimerValue

The regular timer may be used from any thread, but the reading and writing of
the timer offset is not synchronized by GLFW.  The following timer related
functions may be called from any thread:

 - @ref glfwGetTime
 - @ref glfwSetTime

Library version information may be queried from any thread.  The following
version related functions may be called from any thread:

 - @ref glfwGetVersion
 - @ref glfwGetVersionString

Vulkan objects may be created and information queried from any thread.  The
following Vulkan related functions may be called from any thread:

 - @ref glfwVulkanSupported
 - @ref glfwGetRequiredInstanceExtensions
 - @ref glfwGetInstanceProcAddress
 - @ref glfwGetPhysicalDevicePresentationSupport
 - @ref glfwCreateWindowSurface

GLFW uses no synchronization objects internally except for thread-local storage
to keep track of the current context for each thread.  Synchronization is left
to the application.

Functions that may currently be called from any thread will always remain so,
but functions that are currently limited to the main thread may be updated to
allow calls from any thread in future releases.

@subsection compatibility Version compatibility

GLFW guarantees source and binary backward compatibility with earlier minor
versions of the API.  This means that you can drop in a newer version of the
library and existing programs will continue to compile and existing binaries
will continue to run.

Once a function or constant has been added, the signature of that function or
value of that constant will remain unchanged until the next major version of
GLFW.  No compatibility of any kind is guaranteed between major versions.

Undocumented behavior, i.e. behavior that is not described in the documentation,
may change at any time until it is documented.

If the reference documentation and the implementation differ, the reference
documentation is correct and the implementation will be fixed in the next
release.

@subsection event_order Event order

The order of arrival of related events is not guaranteed to be consistent
across platforms.  The exception is synthetic key and mouse button release
events, which are always delivered after the window defocus event.

@section intro_version Version management

GLFW provides mechanisms for identifying what version of GLFW your application
was compiled against as well as what version it is currently running against.
If you are loading GLFW dynamically (not just linking dynamically), you can use
this to verify that the library binary is compatible with your application.

@subsection intro_version_compile Compile-time version

The compile-time version of GLFW is provided by the GLFW header with the
`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.

@code
printf("Compiled against GLFW %i.%i.%i\n",
       GLFW_VERSION_MAJOR,
       GLFW_VERSION_MINOR,
       GLFW_VERSION_REVISION);
@endcode

@subsection intro_version_runtime Run-time version

The run-time version can be retrieved with @ref glfwGetVersion, a function that
may be called regardless of whether GLFW is initialized.

@code
int major, minor, revision;
glfwGetVersion(&major, &minor, &revision);

printf("Running against GLFW %i.%i.%i\n", major, minor, revision);
@endcode

@subsection intro_version_string Version string

GLFW 3 also provides a compile-time generated version string that describes the
version, platform, compiler and any platform-specific compile-time options.
This is primarily intended for submitting bug reports, to allow developers to
see which code paths are enabled in a binary.

The version string is returned by @ref glfwGetVersionString, a function that may
be called regardless of whether GLFW is initialized.

__Do not use the version string__ to parse the GLFW library version.  The @ref
glfwGetVersion function already provides the version of the running library
binary.

The format of the string is as follows:
 - The version of GLFW
 - The name of the window system API
 - The name of the context creation API
 - Any additional options or APIs

For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
back ends, the version string may look something like this:

@code
3.0.0 Win32 WGL MinGW
@endcode

*/


text:
/*!

@page context_guide Context guide

@tableofcontents

This guide introduces the OpenGL and OpenGL ES context related functions of
GLFW.  For details on a specific function in this category, see the @ref
context.  There are also guides for the other areas of the GLFW API.

 - @ref intro_guide
 - @ref window_guide
 - @ref vulkan_guide
 - @ref monitor_guide
 - @ref input_guide

@section context_object Context objects

A window object encapsulates both a top-level window and an OpenGL or OpenGL ES
context.  It is created with @ref glfwCreateWindow and destroyed with @ref
glfwDestroyWindow or @ref glfwTerminate.  See @ref window_creation for more
information.

As the window and context are inseparably linked, the window object also serves
as the context handle.

To test the creation of various kinds of contexts and see their properties, run
the `glfwinfo` test program.

@note Vulkan does not have a context and the Vulkan instance is created via the
Vulkan API itself.  If you will be using Vulkan to render to a window, disable
context creation by setting the [GLFW_CLIENT_API](@ref window_hints_ctx) hint to
`GLFW_NO_API`.  For more information, see the @ref vulkan_guide.

@subsection context_hints Context creation hints

There are a number of hints, specified using @ref glfwWindowHint, related to
what kind of context is created.  See
[context related hints](@ref window_hints_ctx) in the window guide.

@subsection context_sharing Context object sharing

When creating a window and its OpenGL or OpenGL ES context with @ref
glfwCreateWindow, you can specify another window whose context the new one
should share its objects (textures, vertex and element buffers, etc.) with.

@code
GLFWwindow* second_window = glfwCreateWindow(640, 480, "Second Window", NULL, first_window);
@endcode

Object sharing is implemented by the operating system and graphics driver.  On
platforms where it is possible to choose which types of objects are shared, GLFW
requests that all types are shared.

See the relevant chapter of the [OpenGL](https://www.opengl.org/registry/) or
[OpenGL ES](http://www.khronos.org/opengles/) reference documents for more
information.  The name and number of this chapter unfortunately varies between
versions and APIs, but has at times been named _Shared Objects and Multiple
Contexts_.

GLFW comes with a simple object sharing test program called `sharing`.

@subsection context_offscreen Offscreen contexts

GLFW doesn't support creating contexts without an associated window.  However,
contexts with hidden windows can be created with the
[GLFW_VISIBLE](@ref window_hints_wnd) window hint.

@code
glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);

GLFWwindow* offscreen_context = glfwCreateWindow(640, 480, "", NULL, NULL);
@endcode

The window never needs to be shown and its context can be used as a plain
offscreen context.  Depending on the window manager, the size of a hidden
window's framebuffer may not be usable or modifiable, so framebuffer
objects are recommended for rendering with such contexts.

You should still [process events](@ref events) as long as you have at least one
window, even if none of them are visible.

__OS X:__ The first time a window is created the menu bar is populated with
common commands like Hide, Quit and About.  This is not desirable for example
when writing a command-line only application.  The menu bar setup can be
disabled with a [compile-time option](@ref compile_options_osx).

@subsection context_less Windows without contexts

You can disable context creation by setting the
[GLFW_CLIENT_API](@ref window_hints_ctx) hint to `GLFW_NO_API`.  Windows without
contexts must not be passed to @ref glfwMakeContextCurrent or @ref
glfwSwapBuffers.

@section context_current Current context

Before you can make OpenGL or OpenGL ES calls, you need to have a current
context of the correct type.  A context can only be current for a single thread
at a time, and a thread can only have a single context current at a time.

The context of a window is made current with @ref glfwMakeContextCurrent.

@code
glfwMakeContextCurrent(window);
@endcode

The window of the current context is returned by @ref glfwGetCurrentContext.

@code
GLFWwindow* window = glfwGetCurrentContext();
@endcode

The following GLFW functions require a context to be current.  Calling any these
functions without a current context will generate a @ref GLFW_NO_CURRENT_CONTEXT
error.

 - @ref glfwSwapInterval
 - @ref glfwExtensionSupported
 - @ref glfwGetProcAddress

@section context_swap Buffer swapping

Buffer swapping is part of the window and framebuffer, not the context.  See
@ref buffer_swap.

@section context_glext OpenGL and OpenGL ES extensions

One of the benefits of OpenGL and OpenGL ES is their extensibility.
Hardware vendors may include extensions in their implementations that extend the
API before that functionality is included in a new version of the OpenGL or
OpenGL ES specification, and some extensions are never included and remain
as extensions until they become obsolete.

An extension is defined by:

- An extension name (e.g. `GL_ARB_debug_output`)
- New OpenGL tokens (e.g. `GL_DEBUG_SEVERITY_HIGH_ARB`)
- New OpenGL functions (e.g. `glGetDebugMessageLogARB`)

Note the `ARB` affix, which stands for Architecture Review Board and is used
for official extensions.  The extension above was created by the ARB, but there
are many different affixes, like `NV` for Nvidia and `AMD` for, well, AMD.  Any
group may also use the generic `EXT` affix.  Lists of extensions, together with
their specifications, can be found at the
[OpenGL Registry](http://www.opengl.org/registry/) and
[OpenGL ES Registry](https://www.khronos.org/registry/gles/).

@subsection context_glext_auto Loading extension with a loader library

An extension loader library is the easiest and best way to access both OpenGL and
OpenGL ES extensions and modern versions of the core OpenGL or OpenGL ES APIs.
They will take care of all the details of declaring and loading everything you
need.  One such library is [glad](https://github.com/Dav1dde/glad) and there are
several others.

The following example will use glad but all extension loader libraries work
similarly.

First you need to generate the source files using the glad Python script.  This
example generates a loader for any version of OpenGL, which is the default for
both GLFW and glad, but loaders for OpenGL ES, as well as loaders for specific
API versions and extension sets can be generated.  The generated files are
written to the `output` directory.

@code{.sh}
python main.py --generator c --no-loader --out-path output
@endcode

The `--no-loader` option is added because GLFW already provides a function for
loading OpenGL and OpenGL ES function pointers, one that automatically uses the
selected context creation API, and glad can call this instead of having to
implement its own.  There are several other command-line options as well.  See
the glad documentation for details.

Add the generated `output/src/glad.c`, `output/include/glad/glad.h` and
`output/include/KHR/khrplatform.h` files to your build.  Then you need to
include the glad header file, which will replace the OpenGL header of your
development environment.  By including the glad header before the GLFW header,
it suppresses the development environment's OpenGL or OpenGL ES header.

@code
#include <glad/glad.h>
#include <GLFW/glfw3.h>
@endcode

Finally you need to initialize glad once you have a suitable current context.

@code
window = glfwCreateWindow(640, 480, "My Window", NULL, NULL);
if (!window)
{
    ...
}

glfwMakeContextCurrent(window);

gladLoadGLLoader((GLADloadproc) glfwGetProcAddress);
@endcode

Once glad has been loaded, you have access to all OpenGL core and extension
functions supported by both the context you created and the glad loader you
generated and you are ready to start rendering.

You can specify a minimum required OpenGL or OpenGL ES version with
[context hints](@ref window_hints_ctx).  If your needs are more complex, you can
check the actual OpenGL or OpenGL ES version with
[context attributes](@ref window_attribs_ctx), or you can check whether
a specific version is supported by the current context with the
`GLAD_GL_VERSION_x_x` booleans.

@code
if (GLAD_GL_VERSION_3_2)
{
    // Call OpenGL 3.2+ specific code
}
@endcode

To check whether a specific extension is supported, use the `GLAD_GL_xxx`
booleans.

@code
if (GLAD_GL_ARB_debug_output)
{
    // Use GL_ARB_debug_output
}
@endcode

@subsection context_glext_manual Loading extensions manually

__Do not use this technique__ unless it is absolutely necessary.  An
[extension loader library](@ref context_glext_auto) will save you a ton of
tedious, repetitive, error prone work.

To use a certain extension, you must first check whether the context supports
that extension and then, if it introduces new functions, retrieve the pointers
to those functions.  GLFW provides @ref glfwExtensionSupported and @ref
glfwGetProcAddress for manual loading of extensions and new API functions.

This section will demonstrate manual loading of OpenGL extensions.  The loading
of OpenGL ES extensions is identical except for the name of the extension header.

@subsubsection context_glext_header The glext.h header

The `glext.h` extension header is a continually updated file that defines the
interfaces for all OpenGL extensions.  The latest version of this can always be
found at the [OpenGL Registry](http://www.opengl.org/registry/).  There are also
extension headers for the various versions of OpenGL ES at the
[OpenGL ES Registry](https://www.khronos.org/registry/gles/).  It it strongly
recommended that you use your own copy of the extension header, as the one
included in your development environment may be several years out of date and
may not include the extensions you wish to use.

The header defines function pointer types for all functions of all extensions it
supports.  These have names like `PFNGLGETDEBUGMESSAGELOGARBPROC` (for
`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` (pointer
to function) and `PROC` (procedure) are added to the ends.

To include the extension header, define [GLFW_INCLUDE_GLEXT](@ref build_macros)
before including the GLFW header.

@code
#define GLFW_INCLUDE_GLEXT
#include <GLFW/glfw3.h>
@endcode

@subsubsection context_glext_string Checking for extensions

A given machine may not actually support the extension (it may have older
drivers or a graphics card that lacks the necessary hardware features), so it
is necessary to check at run-time whether the context supports the extension.
This is done with @ref glfwExtensionSupported.

@code
if (glfwExtensionSupported("GL_ARB_debug_output"))
{
    // The extension is supported by the current context
}
@endcode

The argument is a null terminated ASCII string with the extension name.  If the
extension is supported, @ref glfwExtensionSupported returns `GLFW_TRUE`,
otherwise it returns `GLFW_FALSE`.

@subsubsection context_glext_proc Fetching function pointers

Many extensions, though not all, require the use of new OpenGL functions.
These functions often do not have entry points in the client API libraries of
your operating system, making it necessary to fetch them at run time.  You can
retrieve pointers to these functions with @ref glfwGetProcAddress.

@code
PFNGLGETDEBUGMESSAGELOGARBPROC pfnGetDebugMessageLog = glfwGetProcAddress("glGetDebugMessageLogARB");
@endcode

In general, you should avoid giving the function pointer variables the (exact)
same name as the function, as this may confuse your linker.  Instead, you can
use a different prefix, like above, or some other naming scheme.

Now that all the pieces have been introduced, here is what they might look like
when used together.

@code
#define GLFW_INCLUDE_GLEXT
#include <GLFW/glfw3.h>

#define glGetDebugMessageLogARB pfnGetDebugMessageLog
PFNGLGETDEBUGMESSAGELOGARBPROC pfnGetDebugMessageLog;

// Flag indicating whether the extension is supported
int has_ARB_debug_output = 0;

void load_extensions(void)
{
    if (glfwExtensionSupported("GL_ARB_debug_output"))
    {
        pfnGetDebugMessageLog = (PFNGLGETDEBUGMESSAGELOGARBPROC)
            glfwGetProcAddress("glGetDebugMessageLogARB");
        has_ARB_debug_output = 1;
    }
}

void some_function(void)
{
    if (has_ARB_debug_output)
    {
        // Now the extension function can be called as usual
        glGetDebugMessageLogARB(...);
    }
}
@endcode

*/


text:
/*!

@page compat_guide Standards conformance

@tableofcontents

This guide describes the various API extensions used by this version of GLFW.
It lists what are essentially implementation details, but which are nonetheless
vital knowledge for developers intending to deploy their applications on a wide
range of machines.

The information in this guide is not a part of GLFW API, but merely
preconditions for some parts of the library to function on a given machine.  Any
part of this information may change in future versions of GLFW and that will not
be considered a breaking API change.

@section compat_x11 X11 extensions, protocols and IPC standards

As GLFW uses Xlib directly, without any intervening toolkit
library, it has sole responsibility for interacting well with the many and
varied window managers in use on Unix-like systems.  In order for applications
and window managers to work well together, a number of standards and
conventions have been developed that regulate behavior outside the scope of the
X11 API; most importantly the
[Inter-Client Communication Conventions Manual](http://www.tronche.com/gui/x/icccm/)
(ICCCM) and
[Extended Window Manager Hints](http://standards.freedesktop.org/wm-spec/wm-spec-latest.html)
(EWMH) standards.

GLFW uses the `_MOTIF_WM_HINTS` window property to support borderless windows.
If the running window manager does not support this property, the
`GLFW_DECORATED` hint will have no effect.

GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user
attempting to close the GLFW window.  If the running window manager does not
support this protocol, the close callback will never be called.

GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify
the user when the application has stopped responding, i.e. when it has ceased to
process events.  If the running window manager does not support this protocol,
the user will not be notified if the application locks up.

GLFW uses the EWMH `_NET_WM_STATE_FULLSCREEN` window state to tell the window
manager to make the GLFW window full screen.  If the running window manager does
not support this state, full screen windows may not work properly.  GLFW has
a fallback code path in case this state is unavailable, but every window manager
behaves slightly differently in this regard.

GLFW uses the EWMH `_NET_WM_BYPASS_COMPOSITOR` window property to tell a
compositing window manager to un-redirect full screen GLFW windows.  If the
running window manager uses compositing but does not support this property then
additional copying may be performed for each buffer swap of full screen windows.

GLFW uses the
[clipboard manager protocol](http://www.freedesktop.org/wiki/ClipboardManager/)
to push a clipboard string (i.e. selection) owned by a GLFW window about to be
destroyed to the clipboard manager.  If there is no running clipboard manager,
the clipboard string will be unavailable once the window has been destroyed.

GLFW uses the
[X drag-and-drop protocol](http://www.freedesktop.org/wiki/Specifications/XDND/)
to provide file drop events.  If the application originating the drag does not
support this protocol, drag and drop will not work.

GLFW uses the XRandR 1.3 extension to provide multi-monitor support.  If the
running X server does not support this version of this extension, multi-monitor
support will not function and only a single, desktop-spanning monitor will be
reported.

GLFW uses the XRandR 1.3 and Xf86vidmode extensions to provide gamma ramp
support.  If the running X server does not support either or both of these
extensions, gamma ramp support will not function.

GLFW uses the Xkb extension and detectable auto-repeat to provide keyboard
input.  If the running X server does not support this extension, a non-Xkb
fallback path is used.

@section compat_glx GLX extensions

The GLX API is the default API used to create OpenGL contexts on Unix-like
systems using the X Window System.

GLFW uses the GLX 1.3 `GLXFBConfig` functions to enumerate and select framebuffer pixel
formats.  If GLX 1.3 is not supported, @ref glfwInit will fail.

GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
(or _vsync_), in that order of preference.  Where none of these extension are
available, calling @ref glfwSwapInterval will have no effect.

GLFW uses the `GLX_ARB_multisample` extension to create contexts with
multisampling anti-aliasing.  Where this extension is unavailable, the
`GLFW_SAMPLES` hint will have no effect.

GLFW uses the `GLX_ARB_create_context` extension when available, even when
creating OpenGL contexts of version 2.1 and below.  Where this extension is
unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
glfwCreateWindow to fail.

GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for
context profiles.  Where this extension is unavailable, setting the
`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE`, or setting
`GLFW_CLIENT_API` to anything but `GLFW_OPENGL_API` or `GLFW_NO_API` will cause
@ref glfwCreateWindow to fail.

GLFW uses the `GLX_ARB_context_flush_control` extension to provide control over
whether a context is flushed when it is released (made non-current).  Where this
extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
effect and the context will always be flushed when released.

GLFW uses the `GLX_ARB_framebuffer_sRGB` and `GLX_EXT_framebuffer_sRGB`
extensions to provide support for sRGB framebuffers.  Where both of these
extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.

@section compat_wgl WGL extensions

The WGL API is used to create OpenGL contexts on Microsoft Windows and other
implementations of the Win32 API, such as Wine.

GLFW uses either the `WGL_EXT_extension_string` or the
`WGL_ARB_extension_string` extension to check for the presence of all other WGL
extensions listed below.  If both are available, the EXT one is preferred.  If
neither is available, no other extensions are used and many GLFW features
related to context creation will have no effect or cause errors when used.

GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
synchronization (or _vsync_).  Where this extension is unavailable, calling @ref
glfwSwapInterval will have no effect.

GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
create contexts with multisampling anti-aliasing.  Where these extensions are
unavailable, the `GLFW_SAMPLES` hint will have no effect.

GLFW uses the `WGL_ARB_create_context` extension when available, even when
creating OpenGL contexts of version 2.1 and below.  Where this extension is
unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
glfwCreateWindow to fail.

GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for
context profiles.  Where this extension is unavailable, setting the
`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE` will cause
@ref glfwCreateWindow to fail.

GLFW uses the `WGL_ARB_context_flush_control` extension to provide control over
whether a context is flushed when it is released (made non-current).  Where this
extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
effect and the context will always be flushed when released.

GLFW uses the `WGL_ARB_framebuffer_sRGB` and `WGL_EXT_framebuffer_sRGB`
extensions to provide support for sRGB framebuffers.  Where both of these
extension are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.

@section compat_osx OpenGL 3.2 and later on OS X

Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then
only forward-compatible, core profile contexts are supported.  Support for
OpenGL 4.1 was introduced with OS X 10.9, also limited to forward-compatible,
core profile contexts.  There is also still no mechanism for requesting debug
contexts.  Versions of Mac OS X earlier than 10.7 support at most OpenGL
version 2.1.

Because of this, on OS X 10.7 and later, the `GLFW_CONTEXT_VERSION_MAJOR` and
`GLFW_CONTEXT_VERSION_MINOR` hints will cause @ref glfwCreateWindow to fail if
given version 3.0 or 3.1, the `GLFW_OPENGL_FORWARD_COMPAT` hint must be set to
`GLFW_TRUE` and the `GLFW_OPENGL_PROFILE` hint must be set to
`GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts and the
`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.

Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and
`GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 2.1,
setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to
a non-default value will cause @ref glfwCreateWindow to fail and the
`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.

@section compat_vulkan Vulkan loader and API

GLFW uses the standard system-wide Vulkan loader to access the Vulkan API.
This should be installed by graphics drivers and Vulkan SDKs.  If this is not
available, @ref glfwVulkanSupported will return `GLFW_FALSE` and all other
Vulkan-related functions will fail with an @ref GLFW_API_UNAVAILABLE error.

@section compat_wsi Vulkan WSI extensions

The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on
all supported platforms.

GLFW uses the `VK_KHR_surface` and `VK_KHR_win32_surface` extensions to create
surfaces on Microsoft Windows.  If any of these extensions are not available,
@ref glfwGetRequiredInstanceExtensions will return an empty list and window
surface creation will fail.

GLFW uses the `VK_KHR_surface` and either the `VK_KHR_xlib_surface` or
`VK_KHR_xcb_surface` extensions to create surfaces on X11.  If `VK_KHR_surface`
or both `VK_KHR_xlib_surface` and `VK_KHR_xcb_surface` are not available, @ref
glfwGetRequiredInstanceExtensions will return an empty list and window surface
creation will fail.

GLFW uses the `VK_KHR_surface` and `VK_KHR_wayland_surface` extensions to create
surfaces on Wayland.  If any of these extensions are not available, @ref
glfwGetRequiredInstanceExtensions will return an empty list and window surface
creation will fail.

GLFW uses the `VK_KHR_surface` and `VK_KHR_mir_surface` extensions to create
surfaces on Mir.  If any of these extensions are not available, @ref
glfwGetRequiredInstanceExtensions will return an empty list and window surface
creation will fail.

GLFW does not support any extensions for window surface creation on OS X,
meaning@ref glfwGetRequiredInstanceExtensions will return an empty list and
window surface creation will fail.

*/


text:
// NOTE: Please use this file to perform modifications on default style sheets.
//
// You need to install a few Ruby gems to generate extra.css from this file:
// gem install less therubyracer
//
// Run this command to regenerate extra.css after you're finished with changes:
// lessc --compress extra.less > extra.css
//
// Alternatively you can use online services to regenerate extra.css.

// Default text color for page contents
@default-text-color: hsl(0,0%,30%);

// Page header, footer, table rows, inline codes and definition lists
@header-footer-background-color: hsl(0,0%,95%);

// Page header, footer links and navigation bar background
@header-footer-link-color: hsl(0,0%,40%);

// Doxygen navigation bar links
@navbar-link-color: @header-footer-background-color;

// Page content background color
@content-background-color: hsl(0,0%,100%);

// Bold, italic, h1, h2, ... and table of contents
@heading-color: hsl(0,0%,10%);

// Function, enum and macro definition separator
@def-separator-color: @header-footer-background-color;

// Base color hue
@base-hue: 24;

// Default color used for links
@default-link-color: hsl(@base-hue,100%,50%);

// Doxygen navigation bar active tab
@tab-text-color: hsl(0,0%,100%);
@tab-background-color1: @default-link-color;
@tab-background-color2: lighten(spin(@tab-background-color1, 10), 10%);

// Table borders
@default-border-color: @default-link-color;

// Table header
@table-text-color: @tab-text-color;
@table-background-color1: @tab-background-color1;
@table-background-color2: @tab-background-color2;

// Table of contents, data structure index and prototypes
@toc-background-color1: hsl(0,0%,90%);
@toc-background-color2: lighten(@toc-background-color1, 5%);

// Function prototype parameters color
@prototype-param-color: darken(@default-link-color, 25%);

// Message box color: note, pre, post and invariant
@box-note-color: hsl(103,80%,85%);

// Message box color: warning and attention
@box-warning-color: hsl(34,80%,85%);

// Message box color: deprecated and bug
@box-bug-color: hsl(333,80%,85%);

// Message box color: todo and test
@box-todo-color: hsl(200,80%,85%);

// Message box helper function
.message-box(@base-color) {
	background:linear-gradient(to bottom,lighten(@base-color, 5%) 0%,@base-color 100%);
	box-shadow:inset 0 0 32px darken(@base-color, 5%);
	color:darken(@base-color, 67%);
	border:2px solid desaturate(darken(@base-color, 10%), 20%);
}

#navrow1,#navrow2,#navrow3,#navrow4,.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a,.memdoc,dl.reflist dd,div.toc li,.ah,span.lineno,span.lineno a,span.lineno a:hover,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,.doxtable code {
	background:none;
}

#titlearea,.footer,.contents,div.header,.memdoc,table.doxtable td,table.doxtable th,hr,.memSeparator {
	border:none;
}

.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a,.reflist dt a.el,.levels span,.directory .levels span {
	text-shadow:none;
}

.memdoc,dl.reflist dd {
	box-shadow:none;
}

div.headertitle,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,table.doxtable code {
	padding:0;
}

#nav-path,.directory .levels,span.lineno {
	display:none;
}

html,#titlearea,.footer,tr.even,.directory tr.even,.doxtable tr:nth-child(even),.mdescLeft,.mdescRight,.memItemLeft,.memItemRight,code {
	background:@header-footer-background-color;
}

body {
	color:@default-text-color;
}

h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em {
	color:@heading-color;
	border-bottom:none;
}

h1 {
  padding-top:0.5em;
  font-size:180%;
}

h2 {
  padding-top:0.5em;
  margin-bottom:0;
  font-size:140%;
}

h3 {
  padding-top:0.5em;
  margin-bottom:0;
  font-size:110%;
}

.glfwheader {
	font-size:16px;
	height:64px;
	max-width:920px;
	min-width:800px;
	padding:0 32px;
	margin:0 auto;
}

#glfwhome {
	line-height:64px;
	padding-right:48px;
	color:@header-footer-link-color;
	font-size:2.5em;
	background:url("http://www.glfw.org/css/arrow.png") no-repeat right;
}

.glfwnavbar {
	list-style-type:none;
	margin:0 auto;
	float:right;
}

#glfwhome,.glfwnavbar li {
	float:left;
}

.glfwnavbar a,.glfwnavbar a:visited {
	line-height:64px;
	margin-left:2em;
	display:block;
	color:@header-footer-link-color;
}

#glfwhome,.glfwnavbar a,.glfwnavbar a:visited {
	transition:.35s ease;
}

#titlearea,.footer {
	color:@header-footer-link-color;
}

address.footer {
	text-align:center;
	padding:2em;
	margin-top:3em;
}

#top {
	background:@header-footer-link-color;
}

#navrow1,#navrow2,#navrow3,#navrow4 {
	max-width:920px;
	min-width:800px;
	margin:0 auto;
	font-size:13px;
}

.tablist {
	height:36px;
	display:block;
	position:relative;
}

.tablist a,.tablist a:visited,.tablist a:hover,.tablist li,.tablist li.current a {
	color:@navbar-link-color;
}

.tablist li.current a {
	background:linear-gradient(to bottom,@tab-background-color2 0%,@tab-background-color1 100%);
	box-shadow:inset 0 0 32px @tab-background-color1;
	text-shadow:0 -1px 1px darken(@tab-background-color1, 15%);
	color:@tab-text-color;
}

.contents {
	min-height:590px;
}

div.contents,div.header {
	max-width:920px;
	margin:0 auto;
	padding:0 32px;
	background:@content-background-color none;
}

table.doxtable th,dl.reflist dt {
	background:linear-gradient(to bottom,@table-background-color2 0%,@table-background-color1 100%);
	box-shadow:inset 0 0 32px @table-background-color1;
	text-shadow:0 -1px 1px darken(@table-background-color1, 15%);
	color:@table-text-color;
}

dl.reflist dt a.el {
	color:@default-link-color;
	padding:.2em;
	border-radius:4px;
	background-color:lighten(@default-link-color, 40%);
}

div.toc {
	float:none;
	width:auto;
}

div.toc h3 {
	font-size:1.17em;
}

div.toc ul {
	padding-left:1.5em;
}

div.toc li {
	font-size:1em;
	padding-left:0;
	list-style-type:disc;
}

div.toc,.memproto,div.qindex,div.ah {
	background:linear-gradient(to bottom,@toc-background-color2 0%,@toc-background-color1 100%);
	box-shadow:inset 0 0 32px @toc-background-color1;
	text-shadow:0 1px 1px lighten(@toc-background-color2, 10%);
	color:@heading-color;
	border:2px solid @toc-background-color1;
	border-radius:4px;
}

.paramname {
	color:@prototype-param-color;
}

dl.reflist dt {
	border:2px solid @default-border-color;
	border-top-left-radius:4px;
	border-top-right-radius:4px;
	border-bottom:none;
}

dl.reflist dd {
	border:2px solid @default-border-color;
	border-bottom-right-radius:4px;
	border-bottom-left-radius:4px;
	border-top:none;
}

table.doxtable {
	border-collapse:inherit;
	border-spacing:0;
	border:2px solid @default-border-color;
	border-radius:4px;
}

a,a:hover,a:visited,a:visited:hover,.contents a:visited,.el,a.el:visited,#glfwhome:hover,.tablist a:hover,span.lineno a:hover {
	color:@default-link-color;
	text-decoration:none;
}

div.directory {
	border-collapse:inherit;
	border-spacing:0;
	border:2px solid @default-border-color;
	border-radius:4px;
}

hr,.memSeparator {
	height:2px;
	background:linear-gradient(to right,@def-separator-color 0%,darken(@def-separator-color, 10%) 50%,@def-separator-color 100%);
}

dl.note,dl.pre,dl.post,dl.invariant {
	.message-box(@box-note-color);
}

dl.warning,dl.attention {
	.message-box(@box-warning-color);
}

dl.deprecated,dl.bug {
	.message-box(@box-bug-color);
}

dl.todo,dl.test {
	.message-box(@box-todo-color);
}

dl.note,dl.pre,dl.post,dl.invariant,dl.warning,dl.attention,dl.deprecated,dl.bug,dl.todo,dl.test {
	border-radius:4px;
	padding:1em;
	text-shadow:0 1px 1px hsl(0,0%,100%);
	margin:1em 0;
}

.note a,.pre a,.post a,.invariant a,.warning a,.attention a,.deprecated a,.bug a,.todo a,.test a,.note a:visited,.pre a:visited,.post a:visited,.invariant a:visited,.warning a:visited,.attention a:visited,.deprecated a:visited,.bug a:visited,.todo a:visited,.test a:visited {
	color:inherit;
}

div.line {
	line-height:inherit;
}

div.fragment,pre.fragment {
	background:hsl(0,0%,95%);
	border-radius:4px;
	border:none;
	padding:1em;
	overflow:auto;
	border-left:4px solid hsl(0,0%,80%);
	margin:1em 0;
}

.lineno a,.lineno a:visited,.line,pre.fragment {
	color:@default-text-color;
}

span.preprocessor,span.comment {
	color:hsl(193,100%,30%);
}

a.code,a.code:visited {
	color:hsl(18,100%,45%);
}

span.keyword,span.keywordtype,span.keywordflow {
	color:darken(@default-text-color, 5%);
	font-weight:bold;
}

span.stringliteral {
	color:hsl(261,100%,30%);
}

code {
	padding:.1em;
	border-radius:4px;
}