zig-glfw/glfw/src/TODO

GLFW_INCLUDE_VULKAN
#if defined(GLFW_INCLUDE_ES1)
 #if defined(GLFW_INCLUDE_GLEXT)
#elif defined(GLFW_INCLUDE_ES2)
#elif defined(GLFW_INCLUDE_ES3)
#elif defined(GLFW_INCLUDE_ES31)
#elif defined(GLFW_INCLUDE_ES32)
#elif defined(GLFW_INCLUDE_GLCOREARB)
  #if defined(GLFW_INCLUDE_GLU)

zig build test -Dtarget=x86_64-windows --verbose 2>&1|less

/// One.
///
/// This is only semantic sugar for the number 1. You can instead use `1` or
/// `true` or `_True` or `GL_TRUE` or `VK_TRUE` or anything else that is equal
/// to one.
///
/// @ingroup init
#define GLFW_TRUE                   1
/// Zero.
///
/// This is only semantic sugar for the number 0. You can instead use `0` or
/// `false` or `_False` or `GL_FALSE` or `VK_FALSE` or anything else that is
/// equal to zero.
///
/// @ingroup init
#define GLFW_FALSE                  0


/*************************************************************************
///GLFW API types
 *************************************************************************/

/// Client API function pointer type.
///
/// Generic function pointer used for returning client API function pointers
/// without forcing a cast from a regular pointer.
///
/// see also: context_glext, glfwGetProcAddress
///
///
/// @ingroup context
typedef void (*GLFWglproc)(void);

/// Vulkan API function pointer type.
///
/// Generic function pointer used for returning Vulkan API function pointers
/// without forcing a cast from a regular pointer.
///
/// see also: vulkan_proc, glfwGetInstanceProcAddress
///
///
/// @ingroup vulkan
typedef void (*GLFWvkproc)(void);

/// Opaque cursor object.
///
/// Opaque cursor object.
///
/// see also: cursor_object
///
///
/// @ingroup input
typedef struct GLFWcursor GLFWcursor;

/// The function pointer type for error callbacks.
///
/// This is the function pointer type for error callbacks. An error callback
/// function has the following signature:
/// @code
/// void callback_name(int error_code, const char* description)
/// @endcode
///
/// @param[in] error_code An error code. Future releases may add
/// more error codes.
/// @param[in] description A UTF-8 encoded string describing the error.
///
/// @pointer_lifetime The error description string is valid until the callback
/// function returns.
///
/// see also: error_handling, glfwSetErrorCallback
///
///
/// @ingroup init
typedef void (* GLFWerrorfun)(int,const char*);

/// The function pointer type for window position callbacks.
///
/// This is the function pointer type for window position callbacks. A window
/// position callback function has the following signature:
/// @code
/// void callback_name(GLFWwindow* window, int xpos, int ypos)
/// @endcode
///
/// @param[in] window The window that was moved.
/// @param[in] xpos The new x-coordinate, in screen coordinates, of the
/// upper-left corner of the content area of the window.
/// @param[in] ypos The new y-coordinate, in screen coordinates, of the
/// upper-left corner of the content area of the window.
///
/// see also: window_pos, glfwSetWindowPosCallback
///
typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);

/// The function pointer type for window size callbacks.
///
/// This is the function pointer type for window size callbacks. A window size
/// callback function has the following signature:
/// @code
/// void callback_name(GLFWwindow* window, int width, int height)
/// @endcode
///
/// @param[in] window The window that was resized.
/// @param[in] width The new width, in screen coordinates, of the window.
/// @param[in] height The new height, in screen coordinates, of the window.
///
/// see also: window_size, glfw.Window.setSizeCallback
///
/// @glfw3 Added window handle parameter.
typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int);

/// The function pointer type for window close callbacks.
///
/// This is the function pointer type for window close callbacks. A window
/// close callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window)
/// @endcode
///
/// @param[in] window The window that the user attempted to close.
///
/// see also: window_close, glfw.Window.setCloseCallback
///
/// @glfw3 Added window handle parameter.
typedef void (* GLFWwindowclosefun)(GLFWwindow*);

/// The function pointer type for window content refresh callbacks.
///
/// This is the function pointer type for window content refresh callbacks.
/// A window content refresh callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window);
/// @endcode
///
/// @param[in] window The window whose content needs to be refreshed.
///
/// see also: window_refresh, glfw.Window.setRefreshCallback
///
/// @glfw3 Added window handle parameter.
typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);

/// The function pointer type for window focus callbacks.
///
/// This is the function pointer type for window focus callbacks. A window
/// focus callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, int focused)
/// @endcode
///
/// @param[in] window The window that gained or lost input focus.
/// @param[in] focused `GLFW_TRUE` if the window was given input focus, or
/// `GLFW_FALSE` if it lost it.
///
/// see also: window_focus, glfw.Window.setFocusCallback
///
typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);

/// The function pointer type for window iconify callbacks.
///
/// This is the function pointer type for window iconify callbacks. A window
/// iconify callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, int iconified)
/// @endcode
///
/// @param[in] window The window that was iconified or restored.
/// @param[in] iconified `GLFW_TRUE` if the window was iconified, or
/// `GLFW_FALSE` if it was restored.
///
/// see also: window_iconify, glfw.Window.setIconifyCallback
///
typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);

/// The function pointer type for window maximize callbacks.
///
/// This is the function pointer type for window maximize callbacks. A window
/// maximize callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, int maximized)
/// @endcode
///
/// @param[in] window The window that was maximized or restored.
/// @param[in] maximized `GLFW_TRUE` if the window was maximized, or
/// `GLFW_FALSE` if it was restored.
///
/// see also: window_maximize, /// see also: glfw.Window.setMaximizeCallback
///
typedef void (* GLFWwindowmaximizefun)(GLFWwindow*,int);

/// The function pointer type for framebuffer size callbacks.
///
/// This is the function pointer type for framebuffer size callbacks.
/// A framebuffer size callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, int width, int height)
/// @endcode
///
/// @param[in] window The window whose framebuffer was resized.
/// @param[in] width The new width, in pixels, of the framebuffer.
/// @param[in] height The new height, in pixels, of the framebuffer.
///
/// see also: window_fbsize, glfw.Window.setFramebufferSizeCallback
///
typedef void (* GLFWframebuffersizefun)(GLFWwindow*,int,int);

/// The function pointer type for window content scale callbacks.
///
/// This is the function pointer type for window content scale callbacks.
/// A window content scale callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, float xscale, float yscale)
/// @endcode
///
/// @param[in] window The window whose content scale changed.
/// @param[in] xscale The new x-axis content scale of the window.
/// @param[in] yscale The new y-axis content scale of the window.
///
/// see also: window_scale, glfwSetWindowContentScaleCallback
///
typedef void (* GLFWwindowcontentscalefun)(GLFWwindow*,float,float);

/// The function pointer type for mouse button callbacks.
///
/// This is the function pointer type for mouse button callback functions.
/// A mouse button callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, int button, int action, int mods)
/// @endcode
///
/// @param[in] window The window that received the event.
/// @param[in] button The mouse button that was pressed or
/// released.
/// @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`. Future releases
/// may add more actions.
/// @param[in] mods Bit field describing which [modifier keys](@ref mods) were
/// held down.
///
/// see also: input_mouse_button, glfwSetMouseButtonCallback
///
/// @glfw3 Added window handle and modifier mask parameters.
///
/// @ingroup input
typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int,int);

/// The function pointer type for cursor position callbacks.
///
/// This is the function pointer type for cursor position callbacks. A cursor
/// position callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, double xpos, double ypos);
/// @endcode
///
/// @param[in] window The window that received the event.
/// @param[in] xpos The new cursor x-coordinate, relative to the left edge of
/// the content area.
/// @param[in] ypos The new cursor y-coordinate, relative to the top edge of the
/// content area.
///
/// see also: cursor_pos, glfw.setCursorPosCallback
/// Replaces `GLFWmouseposfun`.
///
/// @ingroup input
typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);

/// The function pointer type for cursor enter/leave callbacks.
///
/// This is the function pointer type for cursor enter/leave callbacks.
/// A cursor enter/leave callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, int entered)
/// @endcode
///
/// @param[in] window The window that received the event.
/// @param[in] entered `GLFW_TRUE` if the cursor entered the window's content
/// area, or `GLFW_FALSE` if it left it.
///
/// see also: cursor_enter, glfwSetCursorEnterCallback
///
///
/// @ingroup input
typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);

/// The function pointer type for scroll callbacks.
///
/// This is the function pointer type for scroll callbacks. A scroll callback
/// function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, double xoffset, double yoffset)
/// @endcode
///
/// @param[in] window The window that received the event.
/// @param[in] xoffset The scroll offset along the x-axis.
/// @param[in] yoffset The scroll offset along the y-axis.
///
/// see also: scrolling, glfwSetScrollCallback
/// Replaces `GLFWmousewheelfun`.
///
/// @ingroup input
typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);

/// The function pointer type for keyboard key callbacks.
///
/// This is the function pointer type for keyboard key callbacks. A keyboard
/// key callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, int key, int scancode, int action, int mods)
/// @endcode
///
/// @param[in] window The window that received the event.
/// @param[in] key The [keyboard key](@ref keys) that was pressed or released.
/// @param[in] scancode The system-specific scancode of the key.
/// @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`. Future
/// releases may add more actions.
/// @param[in] mods Bit field describing which [modifier keys](@ref mods) were
/// held down.
///
/// see also: input_key, glfwSetKeyCallback
///
/// @glfw3 Added window handle, scancode and modifier mask parameters.
///
/// @ingroup input
typedef void (* GLFWkeyfun)(GLFWwindow*,int,int,int,int);

/// The function pointer type for Unicode character callbacks.
///
/// This is the function pointer type for Unicode character callbacks.
/// A Unicode character callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, unsigned int codepoint)
/// @endcode
///
/// @param[in] window The window that received the event.
/// @param[in] codepoint The Unicode code point of the character.
///
/// see also: input_char, glfwSetCharCallback
///
/// @glfw3 Added window handle parameter.
///
/// @ingroup input
typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int);

/// The function pointer type for path drop callbacks.
///
/// This is the function pointer type for path drop callbacks. A path drop
/// callback function has the following signature:
/// @code
/// void function_name(GLFWwindow* window, int path_count, const char* paths[])
/// @endcode
///
/// @param[in] window The window that received the event.
/// @param[in] path_count The number of dropped paths.
/// @param[in] paths The UTF-8 encoded file and/or directory path names.
///
/// @pointer_lifetime The path array and its strings are valid until the
/// callback function returns.
///
/// see also: path_drop, glfwSetDropCallback
///
///
/// @ingroup input
typedef void (* GLFWdropfun)(GLFWwindow*,int,const char*[]);

/// The function pointer type for joystick configuration callbacks.
///
/// This is the function pointer type for joystick configuration callbacks.
/// A joystick configuration callback function has the following signature:
/// @code
/// void function_name(int jid, int event)
/// @endcode
///
/// @param[in] jid The joystick that was connected or disconnected.
/// @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future
/// releases may add more events.
///
/// see also: joystick_event, glfwSetJoystickCallback
///
///
/// @ingroup input
typedef void (* GLFWjoystickfun)(int,int);

/// Gamepad input state
///
/// This describes the input state of a gamepad.
///
/// see also: gamepad, glfwGetGamepadState
///
///
/// @ingroup input
typedef struct GLFWgamepadstate
{
    /*! The states of each [gamepad button](@ref gamepad_buttons), `GLFW_PRESS`
    /// or `GLFW_RELEASE`.
        unsigned char buttons[15];
    /*! The states of each [gamepad axis](@ref gamepad_axes), in the range -1.0
    /// to 1.0 inclusive.
        float axes[6];
} GLFWgamepadstate;


































/*************************************************************************
///GLFW API functions
 *************************************************************************/

/// Restores the specified window.
///
/// This function restores the specified window if it was previously iconified
/// (minimized) or maximized. If the window is already restored, this function
/// does nothing.
///
/// If the specified window is a full screen window, the resolution chosen for
/// the window is restored on the selected monitor.
///
/// @param[in] window The window to restore.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_iconify, glfw.Window.iconify, glfw.Window.maximize
///
/// @glfw3 Added window handle parameter.
GLFWAPI void glfwRestoreWindow(GLFWwindow* window);

/// Maximizes the specified window.
///
/// This function maximizes the specified window if it was previously not
/// maximized. If the window is already maximized, this function does nothing.
///
/// If the specified window is a full screen window, this function does nothing.
///
/// @param[in] window The window to maximize.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @par Thread Safety
/// This function may only be called from the main thread.
///
/// see also: window_iconify, glfw.Window.iconify, glfw.Window.restore
GLFWAPI void glfwMaximizeWindow(GLFWwindow* window);

/// Makes the specified window visible.
///
/// This function makes the specified window visible if it was previously
/// hidden. If the window is already visible or is in full screen mode, this
/// function does nothing.
///
/// By default, windowed mode windows are focused when shown
/// Set the [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) window hint
/// to change this behavior for all newly created windows, or change the
/// behavior for an existing window with glfw.Window.setAttrib.
///
/// @param[in] window The window to make visible.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_hide, glfw.Window.hide
///
GLFWAPI void glfwShowWindow(GLFWwindow* window);

/// Hides the specified window.
///
/// This function hides the specified window if it was previously visible. If
/// the window is already hidden or is in full screen mode, this function does
/// nothing.
///
/// @param[in] window The window to hide.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_hide, glfw.Window.show
///
GLFWAPI void glfwHideWindow(GLFWwindow* window);

/// Brings the specified window to front and sets input focus.
///
/// This function brings the specified window to front and sets input focus.
/// The window should already be visible and not iconified.
///
/// By default, both windowed and full screen mode windows are focused when
/// initially created. Set the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) to
/// disable this behavior.
///
/// Also by default, windowed mode windows are focused when shown
/// with @ref glfwShowWindow. Set the
/// [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) to disable this behavior.
///
/// __Do not use this function__ to steal focus from other applications unless
/// you are certain that is what the user wants. Focus stealing can be
/// extremely disruptive.
///
/// For a less disruptive way of getting the user's attention, see
/// [attention requests](@ref window_attention).
///
/// @param[in] window The window to give input focus.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// wayland: It is not possible for an application to bring its windows
/// to front, this function will always emit glfw.Error.PlatformError.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_focus, window_attention
///
GLFWAPI void glfwFocusWindow(GLFWwindow* window);

/// Requests user attention to the specified window.
///
/// This function requests user attention to the specified window. On
/// platforms where this is not supported, attention is requested to the
/// application as a whole.
///
/// Once the user has given attention, usually by focusing the window or
/// application, the system will end the request automatically.
///
/// @param[in] window The window to request attention to.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// macos: Attention is requested to the application as a whole, not the
/// specific window.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_attention
///
GLFWAPI void glfwRequestWindowAttention(GLFWwindow* window);

/// Returns the monitor that the window uses for full screen mode.
///
/// This function returns the handle of the monitor that the specified window is
/// in full screen on.
///
/// @param[in] window The window to query.
/// @return The monitor, or null if the window is in windowed mode or an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_monitor, glfw.Window.setMonitor
///
GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);

/// Sets the mode, monitor, video mode and placement of a window.
///
/// This function sets the monitor that the window uses for full screen mode or,
/// if the monitor is null, makes it windowed mode.
///
/// When setting a monitor, this function updates the width, height and refresh
/// rate of the desired video mode and switches to the video mode closest to it.
/// The window position is ignored when setting a monitor.
///
/// When the monitor is null, the position, width and height are used to
/// place the window content area. The refresh rate is ignored when no monitor
/// is specified.
///
/// If you only wish to update the resolution of a full screen window or the
/// size of a windowed mode window, see @ref glfwSetWindowSize.
///
/// When a window transitions from full screen to windowed mode, this function
/// restores any previous window settings such as whether it is decorated,
/// floating, resizable, has size or aspect ratio limits, etc.
///
/// @param[in] window The window whose monitor, size or video mode to set.
/// @param[in] monitor The desired monitor, or null to set windowed mode.
/// @param[in] xpos The desired x-coordinate of the upper-left corner of the
/// content area.
/// @param[in] ypos The desired y-coordinate of the upper-left corner of the
/// content area.
/// @param[in] width The desired with, in screen coordinates, of the content
/// area or video mode.
/// @param[in] height The desired height, in screen coordinates, of the content
/// area or video mode.
/// @param[in] refreshRate The desired refresh rate, in Hz, of the video mode,
/// or `GLFW_DONT_CARE`.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// The OpenGL or OpenGL ES context will not be destroyed or otherwise
/// affected by any resizing or mode switching, although you may need to update
/// your viewport if the framebuffer size has changed.
///
/// wayland: The desired window position is ignored, as there is no way
/// for an application to set this property.
///
/// wayland: Setting the window to full screen will not attempt to
/// change the mode, no matter what the requested size or refresh rate.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_monitor, window_full_screen, glfw.Window.getMonitor, glfw.Window.setSize
///
GLFWAPI void glfwSetWindowMonitor(GLFWwindow* window, GLFWmonitor* monitor, int xpos, int ypos, int width, int height, int refreshRate);

/// Returns an attribute of the specified window.
///
/// This function returns the value of an attribute of the specified window or
/// its OpenGL or OpenGL ES context.
///
/// @param[in] window The window to query.
/// @param[in] attrib The [window attribute](@ref window_attribs) whose value to
/// return.
/// @return The value of the attribute, or zero if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// Framebuffer related hints are not window attributes. See @ref
/// window_attribs_fb for more information.
///
/// Zero is a valid value for many window and context related
/// attributes so you cannot use a return value of zero as an indication of
/// errors. However, this function should not fail as long as it is passed
/// valid arguments and the library has been [initialized](@ref intro_init).
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_attribs, glfw.Window.setAttrib
GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib);

/// Sets an attribute of the specified window.
///
/// This function sets the value of an attribute of the specified window.
///
/// The supported attributes are [GLFW_DECORATED](@ref GLFW_DECORATED_attrib),
/// [GLFW_RESIZABLE](@ref GLFW_RESIZABLE_attrib),
/// [GLFW_FLOATING](@ref GLFW_FLOATING_attrib),
/// [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_attrib) and
/// [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_attrib).
///
/// Some of these attributes are ignored for full screen windows. The new
/// value will take effect if the window is later made windowed.
///
/// Some of these attributes are ignored for windowed mode windows. The new
/// value will take effect if the window is later made full screen.
///
/// @param[in] window The window to set the attribute for.
/// @param[in] attrib A supported window attribute.
/// @param[in] value `GLFW_TRUE` or `GLFW_FALSE`.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum, glfw.Error.InvalidValue and glfw.Error.PlatformError.
///
/// Calling glfw.Window.getAttrib will always return the latest
/// value, even if that value is ignored by the current mode of the window.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_attribs, glfw.Window.getAttrib
///
GLFWAPI void glfwSetWindowAttrib(GLFWwindow* window, int attrib, int value);

/// Sets the user pointer of the specified window.
///
/// This function sets the user-defined pointer of the specified window. The
/// current value is retained until the window is destroyed. The initial value
/// is null.
///
/// @param[in] window The window whose pointer to set.
/// @param[in] pointer The new value.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
///
/// see also: window_userptr, glfwGetWindowUserPointer
///
GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer);

/// Returns the user pointer of the specified window.
///
/// This function returns the current value of the user-defined pointer of the
/// specified window. The initial value is null.
///
/// @param[in] window The window whose pointer to return.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
///
/// see also: window_userptr, glfwSetWindowUserPointer
///
GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);

/// Sets the position callback for the specified window.
///
/// This function sets the position callback of the specified window, which is
/// called when the window is moved. The callback is provided with the
/// position, in screen coordinates, of the upper-left corner of the content
/// area of the window.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int xpos, int ypos)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWwindowposfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// wayland: This callback will never be called, as there is no way for
/// an application to know its global position.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_pos
///
GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun callback);

/// Sets the size callback for the specified window.
///
/// This function sets the size callback of the specified window, which is
/// called when the window is resized. The callback is provided with the size,
/// in screen coordinates, of the content area of the window.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int width, int height)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWwindowsizefun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_size
///
/// @glfw3 Added window handle parameter and return value.
GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun callback);

/// Sets the close callback for the specified window.
///
/// This function sets the close callback of the specified window, which is
/// called when the user attempts to close the window, for example by clicking
/// the close widget in the title bar.
///
/// The close flag is set before this callback is called, but you can modify it
/// at any time with @ref glfwSetWindowShouldClose.
///
/// The close callback is not triggered by @ref glfwDestroyWindow.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWwindowclosefun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// macos: Selecting Quit from the application menu will trigger the
/// close callback for all windows.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_close
///
/// @glfw3 Added window handle parameter and return value.
GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun callback);

/// Sets the refresh callback for the specified window.
///
/// This function sets the refresh callback of the specified window, which is
/// called when the content area of the window needs to be redrawn, for example
/// if the window has been exposed after having been covered by another window.
///
/// On compositing window systems such as Aero, Compiz, Aqua or Wayland, where
/// the window contents are saved off-screen, this callback may be called only
/// very infrequently or never at all.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window);
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWwindowrefreshfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_refresh
///
/// @glfw3 Added window handle parameter and return value.
GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun callback);

/// Sets the focus callback for the specified window.
///
/// This function sets the focus callback of the specified window, which is
/// called when the window gains or loses input focus.
///
/// After the focus callback is called for a window that lost input focus,
/// synthetic key and mouse button release events will be generated for all such
/// that had been pressed. For more information, see @ref glfwSetKeyCallback
/// and @ref glfwSetMouseButtonCallback.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int focused)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWwindowfocusfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_focus
///
GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun callback);

/// Sets the iconify callback for the specified window.
///
/// This function sets the iconification callback of the specified window, which
/// is called when the window is iconified or restored.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int iconified)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWwindowiconifyfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// wayland: The wl_shell protocol has no concept of iconification,
/// this callback will never be called when using this deprecated protocol.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_iconify
///
GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun callback);

/// Sets the maximize callback for the specified window.
///
/// This function sets the maximization callback of the specified window, which
/// is called when the window is maximized or restored.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int maximized)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWwindowmaximizefun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_maximize
///
GLFWAPI GLFWwindowmaximizefun glfwSetWindowMaximizeCallback(GLFWwindow* window, GLFWwindowmaximizefun callback);

/// Sets the framebuffer resize callback for the specified window.
///
/// This function sets the framebuffer resize callback of the specified window,
/// which is called when the framebuffer of the specified window is resized.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int width, int height)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWframebuffersizefun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_fbsize
///
GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun callback);

/// Sets the window content scale callback for the specified window.
///
/// This function sets the window content scale callback of the specified window,
/// which is called when the content scale of the specified window changes.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, float xscale, float yscale)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWwindowcontentscalefun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: window_scale, glfw.Window.getContentScale
///
GLFWAPI GLFWwindowcontentscalefun glfwSetWindowContentScaleCallback(GLFWwindow* window, GLFWwindowcontentscalefun callback);

/// Processes all pending events.
///
/// This function processes only those events that are already in the event
/// queue and then returns immediately. Processing events will cause the window
/// and input callbacks associated with those events to be called.
///
/// On some platforms, a window move, resize or menu operation will cause event
/// processing to block. This is due to how event processing is designed on
/// those platforms. You can use the
/// [window refresh callback](@ref window_refresh) to redraw the contents of
/// your window when necessary during such operations.
///
/// Do not assume that callbacks you set will _only_ be called in response to
/// event processing functions like this one. While it is necessary to poll for
/// events, window systems that require GLFW to register callbacks of its own
/// can pass events to GLFW in response to many window system function calls.
/// GLFW will pass those events on to the application callbacks before
/// returning.
///
/// Event processing is not required for joystick input to work.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @reentrancy This function must not be called from a callback.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: events, glfw.waitEvents, glfw.waitEventsTimeout
///
GLFWAPI void glfwPollEvents(void);

/// Waits until events are queued and processes them.
///
/// This function puts the calling thread to sleep until at least one event is
/// available in the event queue. Once one or more events are available,
/// it behaves exactly like @ref glfwPollEvents, i.e. the events in the queue
/// are processed and the function then returns immediately. Processing events
/// will cause the window and input callbacks associated with those events to be
/// called.
///
/// Since not all events are associated with callbacks, this function may return
/// without a callback having been called even if you are monitoring all
/// callbacks.
///
/// On some platforms, a window move, resize or menu operation will cause event
/// processing to block. This is due to how event processing is designed on
/// those platforms. You can use the
/// [window refresh callback](@ref window_refresh) to redraw the contents of
/// your window when necessary during such operations.
///
/// Do not assume that callbacks you set will _only_ be called in response to
/// event processing functions like this one. While it is necessary to poll for
/// events, window systems that require GLFW to register callbacks of its own
/// can pass events to GLFW in response to many window system function calls.
/// GLFW will pass those events on to the application callbacks before
/// returning.
///
/// Event processing is not required for joystick input to work.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @reentrancy This function must not be called from a callback.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: events, glfw.pollEvents, glfw.waitEventsTimeout
///
GLFWAPI void glfwWaitEvents(void);

/// Waits with timeout until events are queued and processes them.
///
/// This function puts the calling thread to sleep until at least one event is
/// available in the event queue, or until the specified timeout is reached. If
/// one or more events are available, it behaves exactly like @ref
/// glfwPollEvents, i.e. the events in the queue are processed and the function
/// then returns immediately. Processing events will cause the window and input
/// callbacks associated with those events to be called.
///
/// The timeout value must be a positive finite number.
///
/// Since not all events are associated with callbacks, this function may return
/// without a callback having been called even if you are monitoring all
/// callbacks.
///
/// On some platforms, a window move, resize or menu operation will cause event
/// processing to block. This is due to how event processing is designed on
/// those platforms. You can use the
/// [window refresh callback](@ref window_refresh) to redraw the contents of
/// your window when necessary during such operations.
///
/// Do not assume that callbacks you set will _only_ be called in response to
/// event processing functions like this one. While it is necessary to poll for
/// events, window systems that require GLFW to register callbacks of its own
/// can pass events to GLFW in response to many window system function calls.
/// GLFW will pass those events on to the application callbacks before
/// returning.
///
/// Event processing is not required for joystick input to work.
///
/// @param[in] timeout The maximum amount of time, in seconds, to wait.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidValue and glfw.Error.PlatformError.
///
/// @reentrancy This function must not be called from a callback.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: events, glfw.pollEvents, glfw.waitEvents
///
GLFWAPI void glfwWaitEventsTimeout(double timeout);

/// Posts an empty event to the event queue.
///
/// This function posts an empty event from the current thread to the event
/// queue, causing @ref glfwWaitEvents or @ref glfwWaitEventsTimeout to return.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: events, glfw.waitEvents, glfw.waitEventsTimeout
///
GLFWAPI void glfwPostEmptyEvent(void);

/// Returns the value of an input option for the specified window.
///
/// This function returns the value of an input option for the specified window.
/// The mode must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS,
/// @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS or
/// @ref GLFW_RAW_MOUSE_MOTION.
///
/// @param[in] window The window to query.
/// @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`,
/// `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or
/// `GLFW_RAW_MOUSE_MOTION`.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.InvalidEnum.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: glfw.setInputMode
///
///
/// @ingroup input
GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);

/// Sets an input option for the specified window.
///
/// This function sets an input mode option for the specified window. The mode
/// must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS,
/// @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS or
/// @ref GLFW_RAW_MOUSE_MOTION.
///
/// If the mode is `GLFW_CURSOR`, the value must be one of the following cursor
/// modes:
/// - `GLFW_CURSOR_NORMAL` makes the cursor visible and behaving normally.
/// - `GLFW_CURSOR_HIDDEN` makes the cursor invisible when it is over the
///   content area of the window but does not restrict the cursor from leaving.
/// - `GLFW_CURSOR_DISABLED` hides and grabs the cursor, providing virtual
///   and unlimited cursor movement. This is useful for implementing for
///   example 3D camera controls.
///
/// If the mode is `GLFW_STICKY_KEYS`, the value must be either `GLFW_TRUE` to
/// enable sticky keys, or `GLFW_FALSE` to disable it. If sticky keys are
/// enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS`
/// the next time it is called even if the key had been released before the
/// call. This is useful when you are only interested in whether keys have been
/// pressed but not when or in which order.
///
/// If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either
/// `GLFW_TRUE` to enable sticky mouse buttons, or `GLFW_FALSE` to disable it.
/// If sticky mouse buttons are enabled, a mouse button press will ensure that
/// @ref glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even
/// if the mouse button had been released before the call. This is useful when
/// you are only interested in whether mouse buttons have been pressed but not
/// when or in which order.
///
/// If the mode is `GLFW_LOCK_KEY_MODS`, the value must be either `GLFW_TRUE` to
/// enable lock key modifier bits, or `GLFW_FALSE` to disable them. If enabled,
/// callbacks that receive modifier bits will also have the @ref
/// GLFW_MOD_CAPS_LOCK bit set when the event was generated with Caps Lock on,
/// and the @ref GLFW_MOD_NUM_LOCK bit when Num Lock was on.
///
/// If the mode is `GLFW_RAW_MOUSE_MOTION`, the value must be either `GLFW_TRUE`
/// to enable raw (unscaled and unaccelerated) mouse motion when the cursor is
/// disabled, or `GLFW_FALSE` to disable it. If raw motion is not supported,
/// attempting to set this will emit glfw.Error.PlatformError. Call @ref
/// glfwRawMouseMotionSupported to check for support.
///
/// @param[in] window The window whose input mode to set.
/// @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`,
/// `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or
/// `GLFW_RAW_MOUSE_MOTION`.
/// @param[in] value The new value of the specified input mode.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: glfw.getInputMode
/// Replaces `glfwEnable` and `glfwDisable`.
///
/// @ingroup input
GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);

/// Returns whether raw mouse motion is supported.
///
/// This function returns whether raw mouse motion is supported on the current
/// system. This status does not change after GLFW has been initialized so you
/// only need to check this once. If you attempt to enable raw motion on
/// a system that does not support it, glfw.Error.PlatformError will be emitted.
///
/// Raw mouse motion is closer to the actual motion of the mouse across
/// a surface. It is not affected by the scaling and acceleration applied to
/// the motion of the desktop cursor. That processing is suitable for a cursor
/// while raw motion is better for controlling for example a 3D camera. Because
/// of this, raw mouse motion is only provided when the cursor is disabled.
///
/// @return `GLFW_TRUE` if raw mouse motion is supported on the current machine,
/// or `GLFW_FALSE` otherwise.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: raw_mouse_motion, glfw.setInputMode
///
///
/// @ingroup input
GLFWAPI int glfwRawMouseMotionSupported(void);

/// Returns the layout-specific name of the specified printable key.
///
/// This function returns the name of the specified printable key, encoded as
/// UTF-8. This is typically the character that key would produce without any
/// modifier keys, intended for displaying key bindings to the user. For dead
/// keys, it is typically the diacritic it would add to a character.
///
/// __Do not use this function__ for [text input](@ref input_char). You will
/// break text input for many languages even if it happens to work for yours.
///
/// If the key is `GLFW_KEY_UNKNOWN`, the scancode is used to identify the key,
/// otherwise the scancode is ignored. If you specify a non-printable key, or
/// `GLFW_KEY_UNKNOWN` and a scancode that maps to a non-printable key, this
/// function returns null but does not emit an error.
///
/// This behavior allows you to always pass in the arguments in the
/// [key callback](@ref input_key) without modification.
///
/// The printable keys are:
/// - `GLFW_KEY_APOSTROPHE`
/// - `GLFW_KEY_COMMA`
/// - `GLFW_KEY_MINUS`
/// - `GLFW_KEY_PERIOD`
/// - `GLFW_KEY_SLASH`
/// - `GLFW_KEY_SEMICOLON`
/// - `GLFW_KEY_EQUAL`
/// - `GLFW_KEY_LEFT_BRACKET`
/// - `GLFW_KEY_RIGHT_BRACKET`
/// - `GLFW_KEY_BACKSLASH`
/// - `GLFW_KEY_WORLD_1`
/// - `GLFW_KEY_WORLD_2`
/// - `GLFW_KEY_0` to `GLFW_KEY_9`
/// - `GLFW_KEY_A` to `GLFW_KEY_Z`
/// - `GLFW_KEY_KP_0` to `GLFW_KEY_KP_9`
/// - `GLFW_KEY_KP_DECIMAL`
/// - `GLFW_KEY_KP_DIVIDE`
/// - `GLFW_KEY_KP_MULTIPLY`
/// - `GLFW_KEY_KP_SUBTRACT`
/// - `GLFW_KEY_KP_ADD`
/// - `GLFW_KEY_KP_EQUAL`
///
/// Names for printable keys depend on keyboard layout, while names for
/// non-printable keys are the same across layouts but depend on the application
/// language and should be localized along with other user interface text.
///
/// @param[in] key The key to query, or `GLFW_KEY_UNKNOWN`.
/// @param[in] scancode The scancode of the key to query.
/// @return The UTF-8 encoded, layout-specific name of the key, or null.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// The contents of the returned string may change when a keyboard
/// layout change event is received.
///
/// @pointer_lifetime The returned string is allocated and freed by GLFW. You
/// should not free it yourself. It is valid until the library is terminated.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: input_key_name
///
///
/// @ingroup input
GLFWAPI const char* glfwGetKeyName(int key, int scancode);

/// Returns the platform-specific scancode of the specified key.
///
/// This function returns the platform-specific scancode of the specified key.
///
/// If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this
/// method will return `-1`.
///
/// @param[in] key Any [named key](@ref keys).
/// @return The platform-specific scancode for the key, or `-1` if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: input_key
///
///
/// @ingroup input
GLFWAPI int glfwGetKeyScancode(int key);

/// Returns the last reported state of a keyboard key for the specified
/// window.
///
/// This function returns the last state reported for the specified key to the
/// specified window. The returned state is one of `GLFW_PRESS` or
/// `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to
/// the key callback.
///
/// If the @ref GLFW_STICKY_KEYS input mode is enabled, this function returns
/// `GLFW_PRESS` the first time you call it for a key that was pressed, even if
/// that key has already been released.
///
/// The key functions deal with physical keys, with [key tokens](@ref keys)
/// named after their use on the standard US keyboard layout. If you want to
/// input text, use the Unicode character callback instead.
///
/// The [modifier key bit masks](@ref mods) are not key tokens and cannot be
/// used with this function.
///
/// __Do not use this function__ to implement [text input](@ref input_char).
///
/// @param[in] window The desired window.
/// @param[in] key The desired [keyboard key](@ref keys). `GLFW_KEY_UNKNOWN` is
/// not a valid key for this function.
/// @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.InvalidEnum.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: input_key
///
/// @glfw3 Added window handle parameter.
///
/// @ingroup input
GLFWAPI int glfwGetKey(GLFWwindow* window, int key);

/// Returns the last reported state of a mouse button for the specified
/// window.
///
/// This function returns the last state reported for the specified mouse button
/// to the specified window. The returned state is one of `GLFW_PRESS` or
/// `GLFW_RELEASE`.
///
/// If the @ref GLFW_STICKY_MOUSE_BUTTONS input mode is enabled, this function
/// returns `GLFW_PRESS` the first time you call it for a mouse button that was
/// pressed, even if that mouse button has already been released.
///
/// @param[in] window The desired window.
/// @param[in] button The desired mouse button.
/// @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.InvalidEnum.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: input_mouse_button
///
/// @glfw3 Added window handle parameter.
///
/// @ingroup input
GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button);

/// Retrieves the position of the cursor relative to the content area of
/// the window.
///
/// This function returns the position of the cursor, in screen coordinates,
/// relative to the upper-left corner of the content area of the specified
/// window.
///
/// If the cursor is disabled (with `GLFW_CURSOR_DISABLED`) then the cursor
/// position is unbounded and limited only by the minimum and maximum values of
/// a `double`.
///
/// The coordinate can be converted to their integer equivalents with the
/// `floor` function. Casting directly to an integer type works for positive
/// coordinates, but fails for negative ones.
///
/// Any or all of the position arguments may be null. If an error occurs, all
/// non-null position arguments will be set to zero.
///
/// @param[in] window The desired window.
/// @param[out] xpos Where to store the cursor x-coordinate, relative to the
/// left edge of the content area, or null.
/// @param[out] ypos Where to store the cursor y-coordinate, relative to the to
/// top edge of the content area, or null.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: cursor_pos, glfw.setCursorPos
/// Replaces `glfwGetMousePos`.
///
/// @ingroup input
GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);

/// Sets the position of the cursor, relative to the content area of the
/// window.
///
/// This function sets the position, in screen coordinates, of the cursor
/// relative to the upper-left corner of the content area of the specified
/// window. The window must have input focus. If the window does not have
/// input focus when this function is called, it fails silently.
///
/// __Do not use this function__ to implement things like camera controls. GLFW
/// already provides the `GLFW_CURSOR_DISABLED` cursor mode that hides the
/// cursor, transparently re-centers it and provides unconstrained cursor
/// motion. See @ref glfwSetInputMode for more information.
///
/// If the cursor mode is `GLFW_CURSOR_DISABLED` then the cursor position is
/// unconstrained and limited only by the minimum and maximum values of
/// a `double`.
///
/// @param[in] window The desired window.
/// @param[in] xpos The desired x-coordinate, relative to the left edge of the
/// content area.
/// @param[in] ypos The desired y-coordinate, relative to the top edge of the
/// content area.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// wayland: This function will only work when the cursor mode is
/// `GLFW_CURSOR_DISABLED`, otherwise it will do nothing.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: cursor_pos, glfw.getCursorPos
/// Replaces `glfwSetMousePos`.
///
/// @ingroup input
GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);

/// Creates a custom cursor.
///
/// Creates a new custom cursor image that can be set for a window with @ref
/// glfwSetCursor. The cursor can be destroyed with @ref glfwDestroyCursor.
/// Any remaining cursors are destroyed by @ref glfwTerminate.
///
/// The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight
/// bits per channel with the red channel first. They are arranged canonically
/// as packed sequential rows, starting from the top-left corner.
///
/// The cursor hotspot is specified in pixels, relative to the upper-left corner
/// of the cursor image. Like all other coordinate systems in GLFW, the X-axis
/// points to the right and the Y-axis points down.
///
/// @param[in] image The desired cursor image.
/// @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot.
/// @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot.
/// @return The handle of the created cursor, or null if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @pointer_lifetime The specified image data is copied before this function
/// returns.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: cursor_object, glfwDestroyCursor, glfwCreateStandardCursor
///
///
/// @ingroup input
GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot);

/// Creates a cursor with a standard shape.
///
/// Returns a cursor with a [standard shape](@ref shapes), that can be set for
/// a window with @ref glfwSetCursor.
///
/// @param[in] shape One of the [standard shapes](@ref shapes).
/// @return A new cursor ready to use or null if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: cursor_object, glfwCreateCursor
///
///
/// @ingroup input
GLFWAPI GLFWcursor* glfwCreateStandardCursor(int shape);

/// Destroys a cursor.
///
/// This function destroys a cursor previously created with @ref
/// glfwCreateCursor. Any remaining cursors will be destroyed by @ref
/// glfwTerminate.
///
/// If the specified cursor is current for any window, that window will be
/// reverted to the default cursor. This does not affect the cursor mode.
///
/// @param[in] cursor The cursor object to destroy.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @reentrancy This function must not be called from a callback.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: cursor_object, glfwCreateCursor
///
///
/// @ingroup input
GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor);

/// Sets the cursor for the window.
///
/// This function sets the cursor image to be used when the cursor is over the
/// content area of the specified window. The set cursor will only be visible
/// when the [cursor mode](@ref cursor_mode) of the window is
/// `GLFW_CURSOR_NORMAL`.
///
/// On some platforms, the set cursor may not be visible unless the window also
/// has input focus.
///
/// @param[in] window The window to set the cursor for.
/// @param[in] cursor The cursor to set, or null to switch back to the default
/// arrow cursor.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: cursor_object
///
///
/// @ingroup input
GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);

/// Sets the key callback.
///
/// This function sets the key callback of the specified window, which is called
/// when a key is pressed, repeated or released.
///
/// The key functions deal with physical keys, with layout independent
/// [key tokens](@ref keys) named after their values in the standard US keyboard
/// layout. If you want to input text, use the
/// [character callback](@ref glfwSetCharCallback) instead.
///
/// When a window loses input focus, it will generate synthetic key release
/// events for all pressed keys. You can tell these events from user-generated
/// events by the fact that the synthetic ones are generated after the focus
/// loss event has been processed, i.e. after the
/// [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
///
/// The scancode of a key is specific to that platform or sometimes even to that
/// machine. Scancodes are intended to allow users to bind keys that don't have
/// a GLFW key token. Such keys have `key` set to `GLFW_KEY_UNKNOWN`, their
/// state is not saved and so it cannot be queried with @ref glfwGetKey.
///
/// Sometimes GLFW needs to generate synthetic key events, in which case the
/// scancode may be zero.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new key callback, or null to remove the currently
/// set callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int key, int scancode, int action, int mods)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWkeyfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: input_key
///
/// @glfw3 Added window handle parameter and return value.
///
/// @ingroup input
GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun callback);

/// Sets the Unicode character callback.
///
/// This function sets the character callback of the specified window, which is
/// called when a Unicode character is input.
///
/// The character callback is intended for Unicode text input. As it deals with
/// characters, it is keyboard layout dependent, whereas the
/// [key callback](@ref glfwSetKeyCallback) is not. Characters do not map 1:1
/// to physical keys, as a key may produce zero, one or more characters. If you
/// want to know whether a specific physical key was pressed or released, see
/// the key callback instead.
///
/// The character callback behaves as system text input normally does and will
/// not be called if modifier keys are held down that would prevent normal text
/// input on that platform, for example a Super (Command) key on macOS or Alt key
/// on Windows.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, unsigned int codepoint)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWcharfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: input_char
///
/// @glfw3 Added window handle parameter and return value.
///
/// @ingroup input
GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun callback);

/// Sets the mouse button callback.
///
/// This function sets the mouse button callback of the specified window, which
/// is called when a mouse button is pressed or released.
///
/// When a window loses input focus, it will generate synthetic mouse button
/// release events for all pressed mouse buttons. You can tell these events
/// from user-generated events by the fact that the synthetic ones are generated
/// after the focus loss event has been processed, i.e. after the
/// [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int button, int action, int mods)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWmousebuttonfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: input_mouse_button
///
/// @glfw3 Added window handle parameter and return value.
///
/// @ingroup input
GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun callback);

/// Sets the cursor position callback.
///
/// This function sets the cursor position callback of the specified window,
/// which is called when the cursor is moved. The callback is provided with the
/// position, in screen coordinates, relative to the upper-left corner of the
/// content area of the window.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, double xpos, double ypos);
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWcursorposfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: cursor_pos
/// Replaces `glfwSetMousePosCallback`.
///
/// @ingroup input
GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun callback);

/// Sets the cursor enter/leave callback.
///
/// This function sets the cursor boundary crossing callback of the specified
/// window, which is called when the cursor enters or leaves the content area of
/// the window.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int entered)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWcursorenterfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: cursor_enter
///
///
/// @ingroup input
GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun callback);

/// Sets the scroll callback.
///
/// This function sets the scroll callback of the specified window, which is
/// called when a scrolling device is used, such as a mouse wheel or scrolling
/// area of a touchpad.
///
/// The scroll callback receives all scrolling input, like that from a mouse
/// wheel or a touchpad scrolling area.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new scroll callback, or null to remove the
/// currently set callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, double xoffset, double yoffset)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWscrollfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: scrolling
/// Replaces `glfwSetMouseWheelCallback`.
///
/// @ingroup input
GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun callback);

/// Sets the path drop callback.
///
/// This function sets the path drop callback of the specified window, which is
/// called when one or more dragged paths are dropped on the window.
///
/// Because the path array and its strings may have been generated specifically
/// for that event, they are not guaranteed to be valid after the callback has
/// returned. If you wish to use them after the callback returns, you need to
/// make a deep copy.
///
/// @param[in] window The window whose callback to set.
/// @param[in] callback The new file drop callback, or null to remove the
/// currently set callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(GLFWwindow* window, int path_count, const char* paths[])
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWdropfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// wayland: File drop is currently unimplemented.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: path_drop
///
///
/// @ingroup input
GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun callback);

/// Returns whether the specified joystick is present.
///
/// This function returns whether the specified joystick is present.
///
/// There is no need to call this function before other functions that accept
/// a joystick ID, as they all check for presence before performing any other
/// work.
///
/// @param[in] jid The [joystick](@ref joysticks) to query.
/// @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: joystick
/// Replaces `glfwGetJoystickParam`.
///
/// @ingroup input
GLFWAPI int glfwJoystickPresent(int jid);

/// Returns the values of all axes of the specified joystick.
///
/// This function returns the values of all axes of the specified joystick.
/// Each element in the array is a value between -1.0 and 1.0.
///
/// If the specified joystick is not present this function will return null
/// but will not generate an error. This can be used instead of first calling
/// @ref glfwJoystickPresent.
///
/// @param[in] jid The [joystick](@ref joysticks) to query.
/// @param[out] count Where to store the number of axis values in the returned
/// array. This is set to zero if the joystick is not present or an error
/// occurred.
/// @return An array of axis values, or null if the joystick is not present or
/// an error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// @pointer_lifetime The returned array is allocated and freed by GLFW. You
/// should not free it yourself. It is valid until the specified joystick is
/// disconnected or the library is terminated.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: joystick_axis
/// Replaces `glfwGetJoystickPos`.
///
/// @ingroup input
GLFWAPI const float* glfwGetJoystickAxes(int jid, int* count);

/// Returns the state of all buttons of the specified joystick.
///
/// This function returns the state of all buttons of the specified joystick.
/// Each element in the array is either `GLFW_PRESS` or `GLFW_RELEASE`.
///
/// For backward compatibility with earlier versions that did not have @ref
/// glfwGetJoystickHats, the button array also includes all hats, each
/// represented as four buttons. The hats are in the same order as returned by
/// __glfwGetJoystickHats__ and are in the order _up_, _right_, _down_ and
/// _left_. To disable these extra buttons, set the @ref
/// GLFW_JOYSTICK_HAT_BUTTONS init hint before initialization.
///
/// If the specified joystick is not present this function will return null
/// but will not generate an error. This can be used instead of first calling
/// @ref glfwJoystickPresent.
///
/// @param[in] jid The [joystick](@ref joysticks) to query.
/// @param[out] count Where to store the number of button states in the returned
/// array. This is set to zero if the joystick is not present or an error
/// occurred.
/// @return An array of button states, or null if the joystick is not present
/// or an error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// @pointer_lifetime The returned array is allocated and freed by GLFW. You
/// should not free it yourself. It is valid until the specified joystick is
/// disconnected or the library is terminated.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: joystick_button
///
/// @glfw3 Changed to return a dynamic array.
///
/// @ingroup input
GLFWAPI const unsigned char* glfwGetJoystickButtons(int jid, int* count);

/// Returns the state of all hats of the specified joystick.
///
/// This function returns the state of all hats of the specified joystick.
/// Each element in the array is one of the following values:
///
/// Name                  | Value
/// ----                  | -----
/// `GLFW_HAT_CENTERED`   | 0
/// `GLFW_HAT_UP`         | 1
/// `GLFW_HAT_RIGHT`      | 2
/// `GLFW_HAT_DOWN`       | 4
/// `GLFW_HAT_LEFT`       | 8
/// `GLFW_HAT_RIGHT_UP`   | `GLFW_HAT_RIGHT` \| `GLFW_HAT_UP`
/// `GLFW_HAT_RIGHT_DOWN` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_DOWN`
/// `GLFW_HAT_LEFT_UP`    | `GLFW_HAT_LEFT` \| `GLFW_HAT_UP`
/// `GLFW_HAT_LEFT_DOWN`  | `GLFW_HAT_LEFT` \| `GLFW_HAT_DOWN`
///
/// The diagonal directions are bitwise combinations of the primary (up, right,
/// down and left) directions and you can test for these individually by ANDing
/// it with the corresponding direction.
///
/// @code
/// if (hats[2] & GLFW_HAT_RIGHT)
/// {
///     // State of hat 2 could be right-up, right or right-down
/// }
/// @endcode
///
/// If the specified joystick is not present this function will return null
/// but will not generate an error. This can be used instead of first calling
/// @ref glfwJoystickPresent.
///
/// @param[in] jid The [joystick](@ref joysticks) to query.
/// @param[out] count Where to store the number of hat states in the returned
/// array. This is set to zero if the joystick is not present or an error
/// occurred.
/// @return An array of hat states, or null if the joystick is not present
/// or an error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// @pointer_lifetime The returned array is allocated and freed by GLFW. You
/// should not free it yourself. It is valid until the specified joystick is
/// disconnected, this function is called again for that joystick or the library
/// is terminated.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: joystick_hat
///
///
/// @ingroup input
GLFWAPI const unsigned char* glfwGetJoystickHats(int jid, int* count);

/// Returns the name of the specified joystick.
///
/// This function returns the name, encoded as UTF-8, of the specified joystick.
/// The returned string is allocated and freed by GLFW. You should not free it
/// yourself.
///
/// If the specified joystick is not present this function will return null
/// but will not generate an error. This can be used instead of first calling
/// @ref glfwJoystickPresent.
///
/// @param[in] jid The [joystick](@ref joysticks) to query.
/// @return The UTF-8 encoded name of the joystick, or null if the joystick
/// is not present or an error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// @pointer_lifetime The returned string is allocated and freed by GLFW. You
/// should not free it yourself. It is valid until the specified joystick is
/// disconnected or the library is terminated.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: joystick_name
///
///
/// @ingroup input
GLFWAPI const char* glfwGetJoystickName(int jid);

/// Returns the SDL compatible GUID of the specified joystick.
///
/// This function returns the SDL compatible GUID, as a UTF-8 encoded
/// hexadecimal string, of the specified joystick. The returned string is
/// allocated and freed by GLFW. You should not free it yourself.
///
/// The GUID is what connects a joystick to a gamepad mapping. A connected
/// joystick will always have a GUID even if there is no gamepad mapping
/// assigned to it.
///
/// If the specified joystick is not present this function will return null
/// but will not generate an error. This can be used instead of first calling
/// @ref glfwJoystickPresent.
///
/// The GUID uses the format introduced in SDL 2.0.5. This GUID tries to
/// uniquely identify the make and model of a joystick but does not identify
/// a specific unit, e.g. all wired Xbox 360 controllers will have the same
/// GUID on that platform. The GUID for a unit may vary between platforms
/// depending on what hardware information the platform specific APIs provide.
///
/// @param[in] jid The [joystick](@ref joysticks) to query.
/// @return The UTF-8 encoded GUID of the joystick, or null if the joystick
/// is not present or an error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.InvalidEnum and glfw.Error.PlatformError.
///
/// @pointer_lifetime The returned string is allocated and freed by GLFW. You
/// should not free it yourself. It is valid until the specified joystick is
/// disconnected or the library is terminated.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: gamepad
///
///
/// @ingroup input
GLFWAPI const char* glfwGetJoystickGUID(int jid);

/// Sets the user pointer of the specified joystick.
///
/// This function sets the user-defined pointer of the specified joystick. The
/// current value is retained until the joystick is disconnected. The initial
/// value is null.
///
/// This function may be called from the joystick callback, even for a joystick
/// that is being disconnected.
///
/// @param[in] jid The joystick whose pointer to set.
/// @param[in] pointer The new value.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
///
/// see also: joystick_userptr, glfwGetJoystickUserPointer
///
///
/// @ingroup input
GLFWAPI void glfwSetJoystickUserPointer(int jid, void* pointer);

/// Returns the user pointer of the specified joystick.
///
/// This function returns the current value of the user-defined pointer of the
/// specified joystick. The initial value is null.
///
/// This function may be called from the joystick callback, even for a joystick
/// that is being disconnected.
///
/// @param[in] jid The joystick whose pointer to return.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
///
/// see also: joystick_userptr, glfwSetJoystickUserPointer
///
///
/// @ingroup input
GLFWAPI void* glfwGetJoystickUserPointer(int jid);

/// Returns whether the specified joystick has a gamepad mapping.
///
/// This function returns whether the specified joystick is both present and has
/// a gamepad mapping.
///
/// If the specified joystick is present but does not have a gamepad mapping
/// this function will return `GLFW_FALSE` but will not generate an error. Call
/// @ref glfwJoystickPresent to check if a joystick is present regardless of
/// whether it has a mapping.
///
/// @param[in] jid The [joystick](@ref joysticks) to query.
/// @return `GLFW_TRUE` if a joystick is both present and has a gamepad mapping,
/// or `GLFW_FALSE` otherwise.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.InvalidEnum.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: gamepad, glfwGetGamepadState
///
///
/// @ingroup input
GLFWAPI int glfwJoystickIsGamepad(int jid);

/// Sets the joystick configuration callback.
///
/// This function sets the joystick configuration callback, or removes the
/// currently set callback. This is called when a joystick is connected to or
/// disconnected from the system.
///
/// For joystick connection and disconnection events to be delivered on all
/// platforms, you need to call one of the [event processing](@ref events)
/// functions. Joystick disconnection may also be detected and the callback
/// called by joystick functions. The function will then return whatever it
/// returns if the joystick is not present.
///
/// @param[in] callback The new callback, or null to remove the currently set
/// callback.
/// @return The previously set callback, or null if no callback was set or the
/// library had not been [initialized](@ref intro_init).
///
/// @callback_signature
/// @code
/// void function_name(int jid, int event)
/// @endcode
/// For more information about the callback parameters, see the
/// [function pointer type](@ref GLFWjoystickfun).
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: joystick_event
///
///
/// @ingroup input
GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun callback);

/// Adds the specified SDL_GameControllerDB gamepad mappings.
///
/// This function parses the specified ASCII encoded string and updates the
/// internal list with any gamepad mappings it finds. This string may
/// contain either a single gamepad mapping or many mappings separated by
/// newlines. The parser supports the full format of the `gamecontrollerdb.txt`
/// source file including empty lines and comments.
///
/// See @ref gamepad_mapping for a description of the format.
///
/// If there is already a gamepad mapping for a given GUID in the internal list,
/// it will be replaced by the one passed to this function. If the library is
/// terminated and re-initialized the internal list will revert to the built-in
/// default.
///
/// @param[in] string The string containing the gamepad mappings.
/// @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.InvalidValue.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: gamepad, glfwJoystickIsGamepad, glfwGetGamepadName
///
///
/// @ingroup input
GLFWAPI int glfwUpdateGamepadMappings(const char* string);

/// Returns the human-readable gamepad name for the specified joystick.
///
/// This function returns the human-readable name of the gamepad from the
/// gamepad mapping assigned to the specified joystick.
///
/// If the specified joystick is not present or does not have a gamepad mapping
/// this function will return null but will not generate an error. Call
/// @ref glfwJoystickPresent to check whether it is present regardless of
/// whether it has a mapping.
///
/// @param[in] jid The [joystick](@ref joysticks) to query.
/// @return The UTF-8 encoded name of the gamepad, or null if the
/// joystick is not present, does not have a mapping or an
/// error occurred.
///
/// @pointer_lifetime The returned string is allocated and freed by GLFW. You
/// should not free it yourself. It is valid until the specified joystick is
/// disconnected, the gamepad mappings are updated or the library is terminated.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: gamepad, glfwJoystickIsGamepad
///
///
/// @ingroup input
GLFWAPI const char* glfwGetGamepadName(int jid);

/// Retrieves the state of the specified joystick remapped as a gamepad.
///
/// This function retrieves the state of the specified joystick remapped to
/// an Xbox-like gamepad.
///
/// If the specified joystick is not present or does not have a gamepad mapping
/// this function will return `GLFW_FALSE` but will not generate an error. Call
/// @ref glfwJoystickPresent to check whether it is present regardless of
/// whether it has a mapping.
///
/// The Guide button may not be available for input as it is often hooked by the
/// system or the Steam client.
///
/// Not all devices have all the buttons or axes provided by @ref
/// GLFWgamepadstate. Unavailable buttons and axes will always report
/// `GLFW_RELEASE` and 0.0 respectively.
///
/// @param[in] jid The [joystick](@ref joysticks) to query.
/// @param[out] state The gamepad input state of the joystick.
/// @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if no joystick is
/// connected, it has no gamepad mapping or an error
/// occurred.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.InvalidEnum.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: gamepad, glfwUpdateGamepadMappings, glfwJoystickIsGamepad
///
///
/// @ingroup input
GLFWAPI int glfwGetGamepadState(int jid, GLFWgamepadstate* state);

/// Sets the clipboard to the specified string.
///
/// This function sets the system clipboard to the specified, UTF-8 encoded
/// string.
///
/// @param[in] window Deprecated. Any valid window or null.
/// @param[in] string A UTF-8 encoded string.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @pointer_lifetime The specified string is copied before this function
/// returns.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: clipboard, glfwGetClipboardString
///
///
/// @ingroup input
GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string);

/// Returns the contents of the clipboard as a string.
///
/// This function returns the contents of the system clipboard, if it contains
/// or is convertible to a UTF-8 encoded string. If the clipboard is empty or
/// if its contents cannot be converted, null is returned and a glfw.Error.FormatUnavailable error is generated.
///
/// @param[in] window Deprecated. Any valid window or null.
/// @return The contents of the clipboard as a UTF-8 encoded string, or null
/// if an error occurred.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// @pointer_lifetime The returned string is allocated and freed by GLFW. You
/// should not free it yourself. It is valid until the next call to @ref
/// glfwGetClipboardString or @ref glfwSetClipboardString, or until the library
/// is terminated.
///
/// @thread_safety This function must only be called from the main thread.
///
/// see also: clipboard, glfwSetClipboardString
///
///
/// @ingroup input
GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window);

/// Returns the GLFW time.
///
/// This function returns the current GLFW time, in seconds. Unless the time
/// has been set using @ref glfwSetTime it measures time elapsed since GLFW was
/// initialized.
///
/// This function and @ref glfwSetTime are helper functions on top of @ref
/// glfwGetTimerFrequency and @ref glfwGetTimerValue.
///
/// The resolution of the timer is system dependent, but is usually on the order
/// of a few micro- or nanoseconds. It uses the highest-resolution monotonic
/// time source on each supported platform.
///
/// @return The current time, in seconds, or zero if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function may be called from any thread. Reading and
/// writing of the internal base time is not atomic, so it needs to be
/// externally synchronized with calls to @ref glfwSetTime.
///
/// see also: time
///
///
/// @ingroup input
GLFWAPI double glfwGetTime(void);

/// Sets the GLFW time.
///
/// This function sets the current GLFW time, in seconds. The value must be
/// a positive finite number less than or equal to 18446744073.0, which is
/// approximately 584.5 years.
///
/// This function and @ref glfwGetTime are helper functions on top of @ref
/// glfwGetTimerFrequency and @ref glfwGetTimerValue.
///
/// @param[in] time The new value, in seconds.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.InvalidValue.
///
/// The upper limit of GLFW time is calculated as
/// floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations
/// storing nanoseconds in 64 bits. The limit may be increased in the future.
///
/// @thread_safety This function may be called from any thread. Reading and
/// writing of the internal base time is not atomic, so it needs to be
/// externally synchronized with calls to @ref glfwGetTime.
///
/// see also: time
///
///
/// @ingroup input
GLFWAPI void glfwSetTime(double time);

/// Returns the current value of the raw timer.
///
/// This function returns the current value of the raw timer, measured in
/// 1&nbsp;/&nbsp;frequency seconds. To get the frequency, call @ref
/// glfwGetTimerFrequency.
///
/// @return The value of the timer, or zero if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: time, glfwGetTimerFrequency
///
///
/// @ingroup input
GLFWAPI uint64_t glfwGetTimerValue(void);

/// Returns the frequency, in Hz, of the raw timer.
///
/// This function returns the frequency, in Hz, of the raw timer.
///
/// @return The frequency of the timer, in Hz, or zero if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: time, glfwGetTimerValue
///
///
/// @ingroup input
GLFWAPI uint64_t glfwGetTimerFrequency(void);

/// Makes the context of the specified window current for the calling
/// thread.
///
/// This function makes the OpenGL or OpenGL ES context of the specified window
/// current on the calling thread. A context must only be made current on
/// a single thread at a time and each thread can have only a single current
/// context at a time.
///
/// When moving a context between threads, you must make it non-current on the
/// old thread before making it current on the new one.
///
/// By default, making a context non-current implicitly forces a pipeline flush.
/// On machines that support `GL_KHR_context_flush_control`, you can control
/// whether a context performs this flush by setting the
/// [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint)
/// hint.
///
/// The specified window must have an OpenGL or OpenGL ES context. Specifying
/// a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT
/// error.
///
/// @param[in] window The window whose context to make current, or null to
/// detach the current context.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.NoWindowContext and glfw.Error.PlatformError.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: context_current, glfwGetCurrentContext
///
///
/// @ingroup context
GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window);

/// Returns the window whose context is current on the calling thread.
///
/// This function returns the window whose OpenGL or OpenGL ES context is
/// current on the calling thread.
///
/// @return The window whose context is current, or null if no window's
/// context is current.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: context_current, glfwMakeContextCurrent
///
///
/// @ingroup context
GLFWAPI GLFWwindow* glfwGetCurrentContext(void);

/// Swaps the front and back buffers of the specified window.
///
/// This function swaps the front and back buffers of the specified window when
/// rendering with OpenGL or OpenGL ES. If the swap interval is greater than
/// zero, the GPU driver waits the specified number of screen updates before
/// swapping the buffers.
///
/// The specified window must have an OpenGL or OpenGL ES context. Specifying
/// a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT
/// error.
///
/// This function does not apply to Vulkan. If you are rendering with Vulkan,
/// see `vkQueuePresentKHR` instead.
///
/// @param[in] window The window whose buffers to swap.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.NoWindowContext and glfw.Error.PlatformError.
///
/// __EGL:__ The context of the specified window must be current on the
/// calling thread.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: buffer_swap, glfwSwapInterval
///
/// @glfw3 Added window handle parameter.
GLFWAPI void glfwSwapBuffers(GLFWwindow* window);

/// Sets the swap interval for the current context.
///
/// This function sets the swap interval for the current OpenGL or OpenGL ES
/// context, i.e. the number of screen updates to wait from the time @ref
/// glfwSwapBuffers was called before swapping the buffers and returning. This
/// is sometimes called _vertical synchronization_, _vertical retrace
/// synchronization_ or just _vsync_.
///
/// A context that supports either of the `WGL_EXT_swap_control_tear` and
/// `GLX_EXT_swap_control_tear` extensions also accepts _negative_ swap
/// intervals, which allows the driver to swap immediately even if a frame
/// arrives a little bit late. You can check for these extensions with @ref
/// glfwExtensionSupported.
///
/// A context must be current on the calling thread. Calling this function
/// without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
///
/// This function does not apply to Vulkan. If you are rendering with Vulkan,
/// see the present mode of your swapchain instead.
///
/// @param[in] interval The minimum number of screen updates to wait for
/// until the buffers are swapped by @ref glfwSwapBuffers.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.NoCurrentContext and glfw.Error.PlatformError.
///
/// This function is not called during context creation, leaving the
/// swap interval set to whatever is the default on that platform. This is done
/// because some swap interval extensions used by GLFW do not allow the swap
/// interval to be reset to zero once it has been set to a non-zero value.
///
/// Some GPU drivers do not honor the requested swap interval, either
/// because of a user setting that overrides the application's request or due to
/// bugs in the driver.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: buffer_swap, glfwSwapBuffers
///
///
/// @ingroup context
GLFWAPI void glfwSwapInterval(int interval);

/// Returns whether the specified extension is available.
///
/// This function returns whether the specified
/// [API extension](@ref context_glext) is supported by the current OpenGL or
/// OpenGL ES context. It searches both for client API extension and context
/// creation API extensions.
///
/// A context must be current on the calling thread. Calling this function
/// without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
///
/// As this functions retrieves and searches one or more extension strings each
/// call, it is recommended that you cache its results if it is going to be used
/// frequently. The extension strings will not change during the lifetime of
/// a context, so there is no danger in doing this.
///
/// This function does not apply to Vulkan. If you are using Vulkan, see @ref
/// glfw.getRequiredInstanceExtensions, `vkEnumerateInstanceExtensionProperties`
/// and `vkEnumerateDeviceExtensionProperties` instead.
///
/// @param[in] extension The ASCII encoded name of the extension.
/// @return `GLFW_TRUE` if the extension is available, or `GLFW_FALSE`
/// otherwise.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.NoCurrentContext, glfw.Error.InvalidValue and glfw.Error.PlatformError.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: context_glext, glfwGetProcAddress
///
///
/// @ingroup context
GLFWAPI int glfwExtensionSupported(const char* extension);

/// Returns the address of the specified function for the current
/// context.
///
/// This function returns the address of the specified OpenGL or OpenGL ES
/// [core or extension function](@ref context_glext), if it is supported
/// by the current context.
///
/// A context must be current on the calling thread. Calling this function
/// without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
///
/// This function does not apply to Vulkan. If you are rendering with Vulkan,
/// see @ref glfwGetInstanceProcAddress, `vkGetInstanceProcAddr` and
/// `vkGetDeviceProcAddr` instead.
///
/// @param[in] procname The ASCII encoded name of the function.
/// @return The address of the function, or null if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.NoCurrentContext and glfw.Error.PlatformError.
///
/// The address of a given function is not guaranteed to be the same
/// between contexts.
///
/// This function may return a non-null address despite the
/// associated version or extension not being available. Always check the
/// context version or extension string first.
///
/// @pointer_lifetime The returned function pointer is valid until the context
/// is destroyed or the library is terminated.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: context_glext, glfwExtensionSupported
///
///
/// @ingroup context
GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname);


























/// Returns whether the Vulkan loader and an ICD have been found.
///
/// This function returns whether the Vulkan loader and any minimally functional ICD have been
/// found.
///
/// The availability of a Vulkan loader and even an ICD does not by itself guarantee that surface
/// creation or even instance creation is possible. For example, on Fermi systems Nvidia will
/// install an ICD that provides no actual Vulkan support. Call glfw.getRequiredInstanceExtensions
/// to check whether the extensions necessary for Vulkan surface creation are available and
/// glfw.getPhysicalDevicePresentationSupport to check whether a queue family of a physical device
/// supports image presentation.
///
/// @return `GLFW_TRUE` if Vulkan is minimally available, or `GLFW_FALSE` otherwise.
///
/// Possible errors include glfw.Error.NotInitialized.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: vulkan_support
GLFWAPI int glfwVulkanSupported(void);

/// Returns the Vulkan instance extensions required by GLFW.
///
/// This function returns an array of names of Vulkan instance extensions required by GLFW for
/// creating Vulkan surfaces for GLFW windows. If successful, the list will always contain
/// `VK_KHR_surface`, so if you don't require any additional extensions you can pass this list
/// directly to the `VkInstanceCreateInfo` struct.
///
/// If Vulkan is not available on the machine, this function returns null and generates a
/// glfw.Error.APIUnavailable error. Call glfw.vulkanSupported to check whether Vulkan is at least
/// minimally available.
///
/// If Vulkan is available but no set of extensions allowing window surface
/// creation was found, this function returns null. You may still use Vulkan
/// for off-screen rendering and compute work.
///
/// @param[out] count Where to store the number of extensions in the returned
/// array. This is set to zero if an error occurred.
/// @return An array of ASCII encoded extension names, or null if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.APIUnavailable.
///
/// Additional extensions may be required by future versions of GLFW. You should check if any
/// extensions you wish to enable are already in the returned array, as it is an error to specify
/// an extension more than once in the `VkInstanceCreateInfo` struct.
///
/// macos: This function currently supports either the `VK_MVK_macos_surface` extension from
/// MoltenVK or `VK_EXT_metal_surface` extension.
///
/// @pointer_lifetime The returned array is allocated and freed by GLFW. You should not free it
/// yourself. It is guaranteed to be valid only until the library is terminated.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: vulkan_ext, glfwCreateWindowSurface
GLFWAPI const char** glfwGetRequiredInstanceExtensions(uint32_t* count);

/// Returns the address of the specified Vulkan instance function.
///
/// This function returns the address of the specified Vulkan core or extension function for the
/// specified instance. If instance is set to null it can return any function exported from the
/// Vulkan loader, including at least the following functions:
///
/// - `vkEnumerateInstanceExtensionProperties`
/// - `vkEnumerateInstanceLayerProperties`
/// - `vkCreateInstance`
/// - `vkGetInstanceProcAddr`
///
/// If Vulkan is not available on the machine, this function returns null and generates a
/// glfw.Error.APIUnavailable error. Call glfw.vulkanSupported to check whether Vulkan is at least
/// minimally available.
///
/// This function is equivalent to calling `vkGetInstanceProcAddr` with a platform-specific query
/// of the Vulkan loader as a fallback.
///
/// @param[in] instance The Vulkan instance to query, or null to retrieve
/// functions related to instance creation.
/// @param[in] procname The ASCII encoded name of the function.
/// @return The address of the function, or null if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.APIUnavailable.
///
/// @pointer_lifetime The returned function pointer is valid until the library is terminated.
///
/// @thread_safety This function may be called from any thread.
///
/// see also: vulkan_proc
GLFWAPI GLFWvkproc glfwGetInstanceProcAddress(VkInstance instance, const char* procname);

/// Returns whether the specified queue family can present images.
///
/// This function returns whether the specified queue family of the specified physical device
/// supports presentation to the platform GLFW was built for.
///
/// If Vulkan or the required window surface creation instance extensions are not available on the
/// machine, or if the specified instance was not created with the required extensions, this
/// function returns `GLFW_FALSE` and generates a glfw.Error.APIUnavailable error. Call
/// glfw.vulkanSupported to check whether Vulkan is at least minimally available and
/// glfw.getRequiredInstanceExtensions to check what instance extensions are required.
///
/// @param[in] instance The instance that the physical device belongs to.
/// @param[in] device The physical device that the queue family belongs to.
/// @param[in] queuefamily The index of the queue family to query.
/// @return `GLFW_TRUE` if the queue family supports presentation, or
/// `GLFW_FALSE` otherwise.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.APIUnavailable and glfw.Error.PlatformError.
///
/// macos: This function currently always returns `GLFW_TRUE`, as the `VK_MVK_macos_surface`
/// extension does not provide a `vkGetPhysicalDevice*PresentationSupport` type function.
///
/// @thread_safety This function may be called from any thread. For synchronization details of
/// Vulkan objects, see the Vulkan specification.
///
/// see also: vulkan_present
GLFWAPI int glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhysicalDevice device, uint32_t queuefamily);

/// Creates a Vulkan surface for the specified window.
///
/// This function creates a Vulkan surface for the specified window.
///
/// If the Vulkan loader or at least one minimally functional ICD were not found, this function
/// returns `VK_ERROR_INITIALIZATION_FAILED` and generates a glfw.Error.APIUnavailable error. Call
/// glfw.vulkanSupported to check whether Vulkan is at least minimally available.
///
/// If the required window surface creation instance extensions are not available or if the
/// specified instance was not created with these extensions enabled, this function returns `VK_ERROR_EXTENSION_NOT_PRESENT`
/// and generates a glfw.Error.APIUnavailable error. Call glfw.getRequiredInstanceExtensions to
/// check what instance extensions are required.
///
/// The window surface cannot be shared with another API so the window must have been created with
/// the client api hint set to `GLFW_NO_API` otherwise it generates a glfw.Error.InvalidValue error
/// and returns `VK_ERROR_NATIVE_WINDOW_IN_USE_KHR`.
///
/// The window surface must be destroyed before the specified Vulkan instance. It is the
/// responsibility of the caller to destroy the window surface. GLFW does not destroy it for you.
/// Call `vkDestroySurfaceKHR` to destroy the surface.
///
/// @param[in] instance The Vulkan instance to create the surface in.
/// @param[in] window The window to create the surface for.
/// @param[in] allocator The allocator to use, or null to use the default
/// allocator.
/// @param[out] surface Where to store the handle of the surface. This is set
/// to `VK_NULL_HANDLE` if an error occurred.
/// @return `VK_SUCCESS` if successful, or a Vulkan error code if an
/// error occurred.
///
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.APIUnavailable, glfw.Error.PlatformError and glfw.Error.InvalidValue
///
/// If an error occurs before the creation call is made, GLFW returns the Vulkan error code most
/// appropriate for the error. Appropriate use of glfw.vulkanSupported and glfw.getRequiredInstanceExtensions
/// should eliminate almost all occurrences of these errors.
///
/// macos: This function currently only supports the `VK_MVK_macos_surface` extension from MoltenVK.
///
/// macos: This function creates and sets a `CAMetalLayer` instance for the window content view,
/// which is required for MoltenVK to function.
///
/// @thread_safety This function may be called from any thread. For synchronization details of
/// Vulkan objects, see the Vulkan specification.
///
/// see also: vulkan_surface, glfw.getRequiredInstanceExtensions
GLFWAPI VkResult glfwCreateWindowSurface(VkInstance instance, GLFWwindow* window, const VkAllocationCallbacks* allocator, VkSurfaceKHR* surface);