From 766a9dc9fd9c9898496b7d7b30f1d182d8fe8a6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Tue, 6 Dec 2016 23:26:53 +0100 Subject: [PATCH] Documentation work Related to glfw/website#34. --- docs/input.dox | 68 +++++++++++++++++++++++--------------------- docs/monitor.dox | 3 ++ include/GLFW/glfw3.h | 36 ++++++++++++++--------- 3 files changed, 62 insertions(+), 45 deletions(-) diff --git a/docs/input.dox b/docs/input.dox index 497fe676..8a67f065 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -15,10 +15,9 @@ for the other areas of GLFW. - @ref monitor_guide GLFW provides many kinds of input. While some can only be polled, like time, or -only received via callbacks, like scrolling, there are those that provide both -callbacks and polling. Where a callback is provided, that is the recommended -way to receive that kind of input. The more you can use callbacks the less time -your users' machines will need to spend polling. +only received via callbacks, like scrolling, many provide both callbacks and +polling. Callbacks are more work to use than polling but is less CPU intensive +and guarantees that you do not miss state changes. All input callbacks receive a window handle. By using the [window user pointer](@ref window_userptr), you can access non-global structures @@ -32,14 +31,13 @@ information. @section events Event processing -GLFW needs to communicate regularly with the window system both in order to -receive events and to show that the application hasn't locked up. Event -processing must be done regularly while you have any windows and is normally -done each frame after [buffer swapping](@ref buffer_swap). Even when you have -no windows, event polling needs to be done in order to receive monitor -connection events. +GLFW needs to poll the window system for events both to provide input to the +application and to prove to the window system that the application hasn't locked +up. Event processing is normally done each frame after [buffer swapping](@ref +buffer_swap). Even when you have no windows, event polling needs to be done in +order to receive monitor and joystick connection events. -There are two functions for processing pending events. @ref glfwPollEvents, +There are three functions for processing pending events. @ref glfwPollEvents, processes only those events that have already been received and then returns immediately. @@ -47,7 +45,7 @@ immediately. glfwPollEvents(); @endcode -This is the best choice when rendering continually, like most games do. +This is the best choice when rendering continuously, like most games do. If you only need to update the contents of the window when you receive new input, @ref glfwWaitEvents is a better choice. @@ -61,8 +59,8 @@ processes all received events. This saves a great deal of CPU cycles and is useful for, for example, editing tools. There must be at least one GLFW window for this function to sleep. -If you want to wait for events but have UI elements that need periodic updates, -call @ref glfwWaitEventsTimeout. +If you want to wait for events but have UI elements or other tasks that need +periodic updates, @ref glfwWaitEventsTimeout lets you specify a timeout. @code glfwWaitEventsTimeout(0.7); @@ -80,10 +78,17 @@ glfwPostEmptyEvent. glfwPostEmptyEvent(); @endcode -Do not assume that callbacks will _only_ be called through either of the above -functions. While it is necessary to process events in the event queue, some -window systems will send some events directly to the application, which in turn -causes callbacks to be called outside of regular event processing. +Do not assume that callbacks will _only_ be called in response to the above +functions. While it is necessary to process events in one or more of the ways +above, 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. + +For example, on Windows the system function that @ref glfwSetWindowSize is +implemented with will send window size events directly to the event callback +that every window has and that GLFW implements for its windows. If you have set +a [window size callback](@ref window_size) GLFW will call it in turn with the +new size before everything returns back out of the @ref glfwSetWindowSize call. @section input_keyboard Keyboard input @@ -125,9 +130,16 @@ _E-mail_ and _Play_ keys. The scancode is unique for every key, regardless of whether it has a key token. Scancodes are platform-specific but consistent over time, so keys will have different scancodes depending on the platform but they are safe to save to disk. +You can query the scancode for any [named key](@ref keys) on the current +platform with @ref glfwGetKeyScancode. -Key states for [named keys](@ref keys) are also saved in per-window state arrays -that can be polled with @ref glfwGetKey. +@code +const int scancode = glfwGetKeyScancode(GLFW_KEY_X); +set_key_mapping(scancode, swap_weapons); +@endcode + +The last reported state for every [named key](@ref keys) is also saved in +per-window state arrays that can be polled with @ref glfwGetKey. @code int state = glfwGetKey(window, GLFW_KEY_E); @@ -138,7 +150,7 @@ if (state == GLFW_PRESS) The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`. This function only returns cached key event state. It does not poll the -system for the current state of the key. +system for the current physical state of the key. Whenever you poll state, you risk missing the state change you are looking for. If a pressed key is released again before you poll its state, you will have @@ -223,17 +235,6 @@ ignored. This matches the behavior of the key callback, meaning the callback arguments can always be passed unmodified to this function. -@subsection input_key_scancode Key scancodes - -If you need the platform dependent scancode for a [named key](@ref keys), you -can query it with @ref glfwGetKeyScancode. - -@code -const int scancode = glfwGetKeyScancode(GLFW_KEY_X); -set_key_mapping(scancode, swap_weapons); -@endcode - - @section input_mouse Mouse input Mouse input comes in many forms, including cursor motion, button presses and @@ -515,6 +516,9 @@ Joystick state is updated as needed when a joystick function is called and does not require a window to be created or @ref glfwPollEvents or @ref glfwWaitEvents to be called. +To see all the properties of all connected joysticks in real-time, run the +`joysticks` test program. + @subsection joystick_axis Joystick axis states diff --git a/docs/monitor.dox b/docs/monitor.dox index c05f601c..ee9fced1 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -213,6 +213,9 @@ glfwSetGammaRamp with the resulting ramp. glfwSetGamma(monitor, 1.0); @endcode +To experiment with gamma correction via the @ref glfwSetGamma function, run the +`gamma` test program. + @note The software controlled gamma ramp is applied _in addition_ to the hardware gamma correction, which today is usually an approximation of sRGB gamma. This means that setting a perfectly linear ramp, or gamma 1.0, will diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 310b5e49..d95a9b7f 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -3026,9 +3026,12 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window * [window refresh callback](@ref window_refresh) to redraw the contents of * your window when necessary during such operations. * - * On some platforms, certain events are sent directly to the application - * without going through the event queue, causing callbacks to be called - * outside of a call to one of the event processing functions. + * 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. * @@ -3068,8 +3071,12 @@ GLFWAPI void glfwPollEvents(void); * [window refresh callback](@ref window_refresh) to redraw the contents of * your window when necessary during such operations. * - * On some platforms, certain callbacks may be called outside of a call to one - * of the event processing functions. + * 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. * * If no windows exist, this function returns immediately. For synchronization * of threads in applications that do not create windows, use your threading @@ -3115,8 +3122,12 @@ GLFWAPI void glfwWaitEvents(void); * [window refresh callback](@ref window_refresh) to redraw the contents of * your window when necessary during such operations. * - * On some platforms, certain callbacks may be called outside of a call to one - * of the event processing functions. + * 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. * * If no windows exist, this function returns immediately. For synchronization * of threads in applications that do not create windows, use your threading @@ -3292,16 +3303,15 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); */ GLFWAPI const char* glfwGetKeyName(int key, int scancode); -/*! @brief Returns the platform dependent scancode of the specified key. +/*! @brief Returns the platform-specific scancode of the specified key. * - * This function returns the platform dependent scancode of the specified key. - * This is intended for platform specific default keybindings. + * 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 The key to query. - * @return The platform dependent scancode for the key, or `-1` if an + * @param[in] key Any [named key](@ref keys). + * @return The platform-specific scancode for the key, or `-1` if an * [error](@ref error_handling) occurred. * * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref @@ -3309,7 +3319,7 @@ GLFWAPI const char* glfwGetKeyName(int key, int scancode); * * @thread_safety This function may be called from any thread. * - * @sa @ref input_key_scancode + * @sa @ref input_key * * @since Added in version 3.3. *