mirror of
https://github.com/glfw/glfw.git
synced 2024-11-30 05:47:10 +00:00
2d5fb77c90
Added window hints table, added detailed description of all public functions, added project brief and added missing language to transition guide.
266 lines
12 KiB
Plaintext
266 lines
12 KiB
Plaintext
/*!
|
|
|
|
@page moving Moving from GLFW 2 to 3
|
|
|
|
@tableofcontents
|
|
|
|
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.
|
|
|
|
|
|
@section moving_removed Removed features
|
|
|
|
@subsection moving_threads Threading functions
|
|
|
|
The threading functions have been removed, including the sleep function. They
|
|
were fairly primitive, under-used, poorly integrated and took time away from the
|
|
focus of GLFW (i.e. context, input and window). There are better threading
|
|
libraries available and native threading support is available in both C++11 and
|
|
C11, both of which are gaining traction.
|
|
|
|
If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
|
|
support them, see the
|
|
[TinyThread++](https://gitorious.org/tinythread/tinythreadpp) and
|
|
[TinyCThread](https://gitorious.org/tinythread/tinycthread) projects created by
|
|
the original author of GLFW. These libraries implement a usable subset of the
|
|
threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
|
|
TinyCThread.
|
|
|
|
However, GLFW 3 has better support for *use from multiple threads* than GLFW
|
|
2 had. Contexts can be made current on and rendered with from secondary
|
|
threads, and the documentation explicitly states which functions may or may not
|
|
be used from secondary threads.
|
|
|
|
|
|
@subsection moving_image Image and texture loading
|
|
|
|
The image and texture loading functions have been removed. They only supported
|
|
the Targa image format, making them mostly useful for beginner level examples.
|
|
To become of sufficiently high quality to warrant keeping them in GLFW 3, they
|
|
would need not only to support other formats, but also modern extensions to the
|
|
OpenGL texturing facilities. This would either add a number of external
|
|
dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions
|
|
of these libraries.
|
|
|
|
As there already are libraries doing this, it seems unnecessary both to
|
|
duplicate this work and to tie this duplicate to GLFW. Projects similar to
|
|
GLFW, such as freeglut, could also gain from such a library. Also, would be no
|
|
platform-specific part of such a library, as both OpenGL and stdio are available
|
|
wherever GLFW is.
|
|
|
|
|
|
@subsection moving_char_up Character actions
|
|
|
|
The action parameter of the [character callback](@ref GLFWcharfun) has been
|
|
removed. This was an artefact of the origin of GLFW, i.e. being developed in
|
|
English by a Swede. However, many keyboard layouts require more than one key to
|
|
produce characters with diacritical marks. Even the Swedish keyboard layout
|
|
requires this for uncommon cases like ü.
|
|
|
|
Note that this is only the removal of the *action parameter* of the character
|
|
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.
|
|
|
|
|
|
@subsection moving_stdcall GLFWCALL macro
|
|
|
|
The `GLFWCALL` macro, which made callback functions use
|
|
[__stdcall](http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows,
|
|
has been removed. GLFW is written in C, not Pascal. Removing this macro means
|
|
there's one less thing for users of GLFW to remember, i.e. the requirement to
|
|
mark all callback functions with `GLFWCALL`. It also simplifies the creation of
|
|
DLLs and DLL link libraries, as there's no need to explicitly disable `@n` entry
|
|
point suffixes.
|
|
|
|
|
|
@subsection moving_mbcs Win32 MBCS support
|
|
|
|
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
|
|
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
|
|
GLFW itself to support it.
|
|
|
|
|
|
@subsection moving_windows Support for versions of Windows older than XP
|
|
|
|
All explicit support for version of Windows older than XP has been removed.
|
|
There is no code that actively prevents GLFW 3 from running on these earlier
|
|
versions, but it uses Win32 functions that those versions lack.
|
|
|
|
Windows XP was released in 2001, and by now (2013) it has not only
|
|
replaced almost all earlier versions of Windows, but is itself rapidly being
|
|
replaced by Windows 7 and 8. The MSDN library doesn't even provide
|
|
documentation for version older than Windows 2000, making it difficult to
|
|
maintain compatibility with these versions even if it was deemed worth the
|
|
effort.
|
|
|
|
The Win32 API has also not stood still, and GLFW 3 uses many functions only
|
|
present on Windows XP or later. Even supporting an OS as new as XP (new
|
|
from the perspective of GLFW 2, which still supports Windows 95) requires
|
|
runtime checking for a number of functions that are present only on modern
|
|
version of Windows.
|
|
|
|
|
|
@subsection moving_syskeys Capture of system-wide hotkeys
|
|
|
|
The ability to disable and capture system-wide hotkeys like Alt+Tab has been
|
|
removed. Modern applications, whether they're games, scientific visualisations
|
|
or something else, are nowadays expected to be good desktop citizens and allow
|
|
these hotkeys to function even when running in fullscreen mode.
|
|
|
|
|
|
@section moving_changed Changes to existing features
|
|
|
|
@subsection moving_window_handles Window handles
|
|
|
|
Because GLFW 3 supports multiple windows, window handle parameters have been
|
|
added to all window-related GLFW functions and callbacks. The handle of
|
|
a newly created window is returned by @ref glfwCreateWindow (formerly
|
|
`glfwOpenWindow`). Window handles are of the `GLFWwindow*` type, i.e. a pointer
|
|
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.
|
|
|
|
|
|
@subsection moving_window_close Window closing
|
|
|
|
Window closing is now just an event like any other. GLFW 3 windows won't
|
|
disappear from underfoot even when no close callback is set; instead the
|
|
window's close flag is set. You can query this flag using @ref
|
|
glfwWindowShouldClose, or capture close events by setting a close callback. The
|
|
close flag can be modified from any point in your program using @ref
|
|
glfwSetWindowShouldClose.
|
|
|
|
|
|
@subsection moving_context Explicit context management
|
|
|
|
Each GLFW 3 window has its own OpenGL context and only you, the user, can know
|
|
which context should be current on which thread at any given time. Therefore,
|
|
GLFW 3 makes no assumptions about when you want a certain context to be current,
|
|
leaving that decision to you.
|
|
|
|
This means, among other things, that you need to call @ref
|
|
glfwMakeContextCurrent after creating a window before you can call any OpenGL
|
|
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.
|
|
|
|
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`.
|
|
|
|
|
|
@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.
|
|
|
|
|
|
@subsection moving_cursor Cursor positioning
|
|
|
|
GLFW 3 only allows you to position the cursor within a window using @ref
|
|
glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
|
|
Unless the window is active, the function fails silently.
|
|
|
|
|
|
@subsection moving_hints Persistent window hints
|
|
|
|
Window hints are no longer reset to their default values on window creation, but
|
|
instead retain their values until modified by @ref glfwWindowHint (formerly
|
|
`glfwOpenWindowHint`) or @ref glfwDefaultWindowHints, or until the library is
|
|
terminated and re-initialized.
|
|
|
|
|
|
@section moving_renamed Name changes
|
|
|
|
@subsection moving_renamed_files Library and header file
|
|
|
|
The GLFW 3 header is named @ref glfw3.h, to avoid collisions with the GLFW 2
|
|
`glfw.h` header, in case they are both installed. Similarly, the GLFW 3 library
|
|
is named `glfw3,` except when it's installed as a shared library on Unix-like
|
|
systems, where it uses the [soname](https://en.wikipedia.org/wiki/soname)
|
|
`libglfw.so.3`.
|
|
|
|
|
|
@subsection moving_renamed_functions Functions
|
|
|
|
| GLFW 2 | GLFW 3 | Notes |
|
|
| --------------------------- | ----------------------------- | ----- |
|
|
| `glfwOpenWindow` | @ref glfwCreateWindow | All channel bit depths are now hints
|
|
| `glfwCloseWindow` | @ref glfwDestroyWindow | |
|
|
| `glfwOpenWindowHint` | @ref glfwWindowHint | Now accepts all `GLFW_*_BITS` tokens |
|
|
| `glfwEnable` | @ref glfwSetInputMode | |
|
|
| `glfwDisable` | @ref glfwSetInputMode | |
|
|
| `glfwGetMousePos` | @ref glfwGetCursorPos | |
|
|
| `glfwSetMousePos` | @ref glfwSetCursorPos | |
|
|
| `glfwSetMousePosCallback` | @ref glfwSetCursorPosCallback | |
|
|
| `glfwSetMouseWheelCallback` | @ref glfwSetScrollCallback | Accepts two-dimensional scroll offsets as doubles |
|
|
| `glfwGetJoystickPos` | @ref glfwGetJoystickAxes | |
|
|
| `glfwGetGLVersion` | @ref glfwGetWindowParam | Use `GLFW_OPENGL_VERSION_MAJOR`, `GLFW_OPENGL_VERSION_MINOR` and `GLFW_OPENGL_REVISION` |
|
|
| `glfwGetDesktopMode` | @ref glfwGetVideoMode | Returns the current mode of a monitor |
|
|
|
|
@subsection moving_renamed_tokens Tokens
|
|
|
|
| GLFW 2 | GLFW 3 | Notes |
|
|
| --------------------------- | ---------------------------- | ----- |
|
|
| `GLFW_OPENGL_VERSION_MAJOR` | `GLFW_CONTEXT_VERSION_MAJOR` | Renamed as it applies to OpenGL ES as well |
|
|
| `GLFW_OPENGL_VERSION_MINOR` | `GLFW_CONTEXT_VERSION_MINOR` | Renamed as it applies to OpenGL ES as well |
|
|
| `GLFW_FSAA_SAMPLES` | `GLFW_SAMPLES` | Renamed to match the OpenGL API |
|
|
| `GLFW_ACTIVE` | `GLFW_FOCUSED` | Renamed to match the window focus callback |
|
|
| `GLFW_WINDOW_NO_RESIZE` | `GLFW_RESIZABLE` | The default has been inverted |
|
|
| `GLFW_MOUSE_CURSOR` | `GLFW_CURSOR_MODE` | Used with @ref glfwSetInputMode |
|
|
| `GLFW_KEY_ESC` | `GLFW_KEY_ESCAPE` | |
|
|
| `GLFW_KEY_DEL` | `GLFW_KEY_DELETE` | |
|
|
| `GLFW_KEY_PAGEUP` | `GLFW_KEY_PAGE_UP` | |
|
|
| `GLFW_KEY_PAGEDOWN` | `GLFW_KEY_PAGE_DOWN` | |
|
|
| `GLFW_KEY_KP_NUM_LOCK` | `GLFW_KEY_NUM_LOCK` | |
|
|
| `GLFW_KEY_LCTRL` | `GLFW_KEY_LEFT_CONTROL` | |
|
|
| `GLFW_KEY_LSHIFT` | `GLFW_KEY_LEFT_SHIFT` | |
|
|
| `GLFW_KEY_LALT` | `GLFW_KEY_LEFT_ALT` | |
|
|
| `GLFW_KEY_LSUPER` | `GLFW_KEY_LEFT_SUPER` | |
|
|
| `GLFW_KEY_RCTRL` | `GLFW_KEY_RIGHT_CONTROL` | |
|
|
| `GLFW_KEY_RSHIFT` | `GLFW_KEY_RIGHT_SHIFT` | |
|
|
| `GLFW_KEY_RALT` | `GLFW_KEY_RIGHT_ALT` | |
|
|
| `GLFW_KEY_RSUPER` | `GLFW_KEY_RIGHT_SUPER` | |
|
|
|
|
*/
|