Documentation work.

This commit is contained in:
Camilla Berglund
2013-03-29 14:06:23 +01:00
parent 98063d2957
commit e248fb6056
8 changed files with 501 additions and 220 deletions
+43 -29
View File
@@ -7,7 +7,8 @@
This is a transition guide for moving from GLFW 2 to 3. It describes what has
changed or been removed, but does *not* include entirely new features unless
they are required when moving an existing code base onto the new API. For example,
use of the new multi-monitor support is required to create fullscreen windows.
use of the new multi-monitor functions are required to create fullscreen windows
with GLFW 3.
@section moving_removed Removed features
@@ -65,11 +66,12 @@ callback, *not* the removal of the character callback itself.
@subsection moving_wheel Mouse wheel position
Scroll events do not represent an absolute state. Instead, it's an
interpretation of a relative change in state, like character input. So, like
character input, there is no sane 'current state' to return. The mouse wheel
callback has been replaced by a [scroll callback](@ref GLFWscrollfun) that
receives two-dimensional scroll offsets.
The `glfwGetMouseWheel` function has been removed. Scroll events do not
represent an absolute state, but is instead an interpretation of a relative
change in state, like character input. So, like character input, there is no
sane 'current state' to return. The mouse wheel callback has been replaced by
a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll
offsets.
@subsection moving_stdcall GLFWCALL macro
@@ -87,7 +89,7 @@ point suffixes.
The Win32 port of GLFW 3 will not compile in
[MBCS mode](http://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
Hoever, because the use of the Unicode version of the Win32 API doesn't affect
However, because the use of the Unicode version of the Win32 API doesn't affect
the process as a whole, but only those windows created using it, it's perfectly
possible to call MBCS functions from other parts of the same application.
Therefore, even if an application using GLFW uses MBCS mode, there's no need for
@@ -122,13 +124,27 @@ or something else, are nowadays expected to be good desktop citizens and allow
these hotkeys to function even when running in fullscreen mode.
@subsection moving_autopoll Automatic polling of events
GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
Unlike buffer swap, the event processing functions act on all windows at once.
@subsection moving_terminate Automatic termination
@ref glfwTerminate is no longer registered with `atexit` at initialization. To
GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization. To
properly release all resources allocated by GLFW, you should therefore call @ref
glfwTerminate yourself before exiting.
@subsection moving_glu GLU header inclusion
GLFW 3 does not include the GLU header by default and GLU itself has been
deprecated, but you can request that the GLFW 3 header includes it by defining
`GLFW_INCLUDE_GLU` before the inclusion of the GLFW 3 header.
@section moving_changed Changes to existing features
@subsection moving_window_handles Window handles
@@ -143,9 +159,10 @@ to an opaque struct.
@subsection moving_monitor Multi-monitor support
GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle
type and a set of related functions. To request a fullscreen mode window, you
need to specify which monitor you wish the window to use. There is @ref
glfwGetPrimaryMonitor that provides behaviour similar to that of GLFW 2.
type and a set of related functions. To request a fullscreen mode window,
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
window to use. There is @ref glfwGetPrimaryMonitor that provides behaviour
similar to that of GLFW 2.
@subsection moving_window_close Window closing
@@ -172,34 +189,31 @@ functions.
@subsection moving_keys Physical key input
GLFW 3 uses the physical key locations named after the symbols they generate
using the US keyboard layout, instead of layout-dependent characters like in
GLFW 2. This means that (for example) `GLFW_KEY_BACKSLASH` is always a single
key and is the same key in the same place regardless of what keyboard layouts
the users of your program has.
GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
the values generated by the current keyboard layout. The tokens are named
according to the values they would have using the standard US layout, but this
is only a convenience, as most programmers are assumed to know that layout.
This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and
is the same key in the same place regardless of what keyboard layouts the users
of your program has.
The key input facility was never meant for text input, although using it that
way worked slightly better in GLFW 2. If you were using it to input text, you
should be using the character callback instead, on both GLFW 2 and 3. This will
give you the characters being input, as opposed to the keys being pressed.
GLFW 3 has key tokens for all keys on a standard keyboard, so instead of having
to remember whether to check for `'a'` or `'A'`, you now check for `GLFW_KEY_A`.
GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of
having to remember whether to check for `'a'` or `'A'`, you now check for
`GLFW_KEY_A`.
@subsection moving_video_modes Video mode enumeration
Video mode enumeration is now per-monitor. The `glfwGetDesktopMode` function
has been replaced by @ref glfwGetVideoMode, which returns the current mode of
a monitor. The @ref glfwGetVideoModes function now returns all available modes
for a monitor instead of requiring you to guess how large an array you need.
@subsection moving_glu GLU header inclusion
Unlike GLFW 2, GLFW 3 doesn't include the GLU header by default, but you can
make it do so by defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW
3 header.
Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function
now returns all available modes for a specific monitor instead of requiring you
to guess how large an array you need. The `glfwGetDesktopMode` function has
been replaced by @ref glfwGetVideoMode, which returns the current mode of
a monitor.
@subsection moving_cursor Cursor positioning