mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-21 20:44:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work

Browse Source 
Related to glfw/website#34.
This commit is contained in:
Camilla Löwy 2016-12-06 23:26:53 +01:00
parent 0e8ba24f32
commit 766a9dc9fd
3 changed files with 62 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/input.dox
View File

@ -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

3
docs/monitor.dox
View File

@ -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

36
include/GLFW/glfw3.h
View File

@ -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.
*