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