mirror of
https://github.com/glfw/glfw.git
synced 2026-09-21 08:39:45 +00:00
Documentation work.
This commit is contained in:
Camilla Berglund
+8
-8
@@ -35,21 +35,21 @@ with the entire Win32 API.
|
||||
|
||||
Instead, the GLFW header takes care of this for you, not by including
|
||||
`windows.h`, but by duplicating only the very few necessary parts of it. It
|
||||
does this only when needed, so if `windows.h` *is* included, the GLFW header
|
||||
does this only when needed, so if `windows.h` _is_ included, the GLFW header
|
||||
does not try to redefine those symbols. The reverse is not true, i.e.
|
||||
`windows.h` cannot cope if any of its symbols have already been defined.
|
||||
|
||||
In other words:
|
||||
|
||||
- Do *not* include the OpenGL headers yourself, as GLFW does this for you
|
||||
- Do *not* include `windows.h` or other platform-specific headers unless you
|
||||
- Do _not_ include the OpenGL headers yourself, as GLFW does this for you
|
||||
- Do _not_ include `windows.h` or other platform-specific headers unless you
|
||||
plan on using those APIs directly
|
||||
- If you *do* need to include such headers, do it *before* including
|
||||
- If you _do_ need to include such headers, do it _before_ including
|
||||
the GLFW header and it will handle this
|
||||
|
||||
If you are using an OpenGL extension loading library such as
|
||||
[glad](https://github.com/Dav1dde/glad), the extension loader header should
|
||||
either be included *before* the GLFW one, or the `GLFW_INCLUDE_NONE` macro
|
||||
either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
|
||||
(described below) should be defined.
|
||||
|
||||
|
||||
@@ -85,7 +85,7 @@ header. This is useful in combination with an extension loading library.
|
||||
If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
|
||||
header (`OpenGL/gl.h` on OS X) is included.
|
||||
|
||||
`GLFW_INCLUDE_GLU` makes the header include the GLU header *in addition to* the
|
||||
`GLFW_INCLUDE_GLU` makes the header include the GLU header _in addition to_ the
|
||||
header selected above. This should only be used with legacy code. GLU has been
|
||||
deprecated and should not be used in new code.
|
||||
|
||||
@@ -124,7 +124,7 @@ set of default libraries along with other dependencies like `user32` and
|
||||
|
||||
The link library for the GLFW DLL is named `glfw3dll`. When compiling an
|
||||
application that uses the DLL version of GLFW, you need to define the `GLFW_DLL`
|
||||
macro *before* any inclusion of the GLFW header. This can be done either with
|
||||
macro _before_ any inclusion of the GLFW header. This can be done either with
|
||||
a compiler switch or by defining it in your source code.
|
||||
|
||||
An application using the GLFW DLL does not need to link against any of its
|
||||
@@ -293,6 +293,6 @@ against it from the command-line.
|
||||
The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
|
||||
special to do when using GLU. Also note that even though your machine may have
|
||||
`libGL`-style OpenGL libraries, they are for use with the X Window System and
|
||||
will *not* work with the OS X native version of GLFW.
|
||||
will _not_ work with the OS X native version of GLFW.
|
||||
|
||||
*/
|
||||
|
||||
+1
-1
@@ -9,7 +9,7 @@ It lists what are essentially implementation details, but which are nonetheless
|
||||
vital knowledge for developers intending to deploy their applications on a wide
|
||||
range of machines.
|
||||
|
||||
@note The information in this guide is not a part of GLFW API, but merely
|
||||
The information in this guide is not a part of GLFW API, but merely
|
||||
preconditions for some parts of the library to function on a given machine. Any
|
||||
part of this information may change in future versions of GLFW and that will not
|
||||
be considered a breaking API change.
|
||||
|
||||
+10
-10
@@ -92,8 +92,8 @@ example, on Ubuntu and other distributions based on Debian GNU/Linux, you need
|
||||
to install the `xorg-dev` and `libglu1-mesa-dev` packages. The former pulls in
|
||||
all X.org header packages and the latter pulls in the Mesa OpenGL and GLU
|
||||
packages. GLFW itself doesn't need or use GLU, but some of the examples do.
|
||||
Note that using header files and libraries from Mesa during compilation *will
|
||||
not* tie your binaries to the Mesa implementation of OpenGL.
|
||||
Note that using header files and libraries from Mesa during compilation
|
||||
_will not_ tie your binaries to the Mesa implementation of OpenGL.
|
||||
|
||||
Once you have installed the necessary packages, move on to @ref
|
||||
compile_generate.
|
||||
@@ -103,8 +103,8 @@ compile_generate.
|
||||
|
||||
Once you have all necessary dependencies it is time to generate the project
|
||||
files or makefiles for your development environment. CMake needs to know two
|
||||
paths for this: the path to the *root* directory of the GLFW source tree (i.e.
|
||||
*not* the `src` subdirectory) and the target path for the generated files and
|
||||
paths for this: the path to the _root_ directory of the GLFW source tree (i.e.
|
||||
_not_ the `src` subdirectory) and the target path for the generated files and
|
||||
compiled binaries. If these are the same, it is called an in-tree build,
|
||||
otherwise it is called an out-of-tree build.
|
||||
|
||||
@@ -117,8 +117,8 @@ to compile the GLFW library, not about compiling the actual library.
|
||||
|
||||
@subsubsection compile_generate_cli Generating files with the CMake command-line tool
|
||||
|
||||
To make an in-tree build, enter the *root* directory of the GLFW source tree
|
||||
(i.e. *not* the `src` subdirectory) and run CMake. The current directory is
|
||||
To make an in-tree build, enter the _root_ directory of the GLFW source tree
|
||||
(i.e. _not_ the `src` subdirectory) and run CMake. The current directory is
|
||||
used as target path, while the path provided as an argument is used to find the
|
||||
source tree.
|
||||
|
||||
@@ -146,8 +146,8 @@ development environment, move on to @ref compile_compile.
|
||||
|
||||
If you are using the GUI version, choose the root of the GLFW source tree as
|
||||
source location and the same directory or another, empty directory as the
|
||||
destination for binaries. Choose *Configure*, change any options you wish to,
|
||||
*Configure* again to let the changes take effect and then *Generate*.
|
||||
destination for binaries. Choose _Configure_, change any options you wish to,
|
||||
_Configure_ again to let the changes take effect and then _Generate_.
|
||||
|
||||
Once you have generated the project files or makefiles for your chosen
|
||||
development environment, move on to @ref compile_compile.
|
||||
@@ -252,7 +252,7 @@ defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by
|
||||
`internal.h`. Without this macro, GLFW will expect the necessary configuration
|
||||
macros to be defined on the command-line.
|
||||
|
||||
Three macros *must* be defined when compiling GLFW: one for selecting the window
|
||||
Three macros _must_ be defined when compiling GLFW: one for selecting the window
|
||||
creation API, one selecting the context creation API and one client library.
|
||||
Exactly one of each kind must be defined for GLFW to compile and link.
|
||||
|
||||
@@ -289,7 +289,7 @@ libraries.
|
||||
If you are building GLFW as a shared library / dynamic library / DLL then you
|
||||
must also define `_GLFW_BUILD_DLL`. Otherwise, you may not define it.
|
||||
|
||||
If you are using the X11 window creation API then you *must* also select an entry
|
||||
If you are using the X11 window creation API then you _must_ also select an entry
|
||||
point retrieval mechanism.
|
||||
|
||||
- `_GLFW_HAS_GLXGETPROCADDRESS` to use `glXGetProcAddress` (recommended)
|
||||
|
||||
+2
-2
@@ -50,8 +50,8 @@ requests that all types are shared.
|
||||
See the relevant chapter of the [OpenGL](https://www.opengl.org/registry/) or
|
||||
[OpenGL ES](http://www.khronos.org/opengles/) reference documents for more
|
||||
information. The name and number of this chapter unfortunately varies between
|
||||
versions and APIs, but has at times been named *Shared Objects and Multiple
|
||||
Contexts*.
|
||||
versions and APIs, but has at times been named _Shared Objects and Multiple
|
||||
Contexts_.
|
||||
|
||||
GLFW comes with a simple object sharing test program called `sharing`.
|
||||
|
||||
|
||||
+14
-12
@@ -65,7 +65,7 @@ glfwPostEmptyEvent.
|
||||
glfwPostEmptyEvent();
|
||||
@endcode
|
||||
|
||||
Do not assume that callbacks will *only* be called through either of the above
|
||||
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.
|
||||
@@ -86,7 +86,7 @@ same keyboard layout, input method or even operating system as you.
|
||||
@subsection input_key Key input
|
||||
|
||||
If you wish to be notified when a physical key is pressed or released or when it
|
||||
repeats, set a key callback with @ref glfwSetKeyCallback.
|
||||
repeats, set a key callback.
|
||||
|
||||
@code
|
||||
glfwSetKeyCallback(window, key_callback);
|
||||
@@ -110,7 +110,7 @@ have unique, if platform-specific scancodes.
|
||||
The scancode is unique for every key but is platform-specific, so a scancode
|
||||
will map to different keys on different platforms.
|
||||
|
||||
The key will be `GLFW_KEY_UNKNOWN` for special keys like *E-mail* or *Play* that
|
||||
The key will be `GLFW_KEY_UNKNOWN` for special keys like _E-mail_ or _Play_ that
|
||||
don't have a key token. Those keys will still have unique, if platform-specific
|
||||
scancodes.
|
||||
|
||||
@@ -148,8 +148,7 @@ The `GLFW_KEY_LAST` constant holds the highest value of any
|
||||
|
||||
@subsection input_char Unicode character input
|
||||
|
||||
If you wish to receive Unicode code point input, set a character callback with
|
||||
@ref glfwSetCharCallback.
|
||||
If you wish to receive Unicode code point input, set a character callback.
|
||||
|
||||
@code
|
||||
glfwSetCharCallback(window, character_callback);
|
||||
@@ -166,7 +165,7 @@ void character_callback(GLFWwindow* window, unsigned int codepoint)
|
||||
|
||||
If you wish to receive all Unicode code point events generated by the system, or
|
||||
just want to know exactly what modifier keys were used, set a character with
|
||||
modifiers callback with @ref glfwSetCharModsCallback.
|
||||
modifiers callback.
|
||||
|
||||
@code
|
||||
glfwSetCharCallback(window, charmods_callback);
|
||||
@@ -192,7 +191,7 @@ these are supported by GLFW.
|
||||
@subsection input_cursor_pos Cursor position
|
||||
|
||||
If you wish to be notified when the system cursor moves over the window, set
|
||||
a cursor position callback with @ref glfwSetCursorPosCallback.
|
||||
a cursor position callback.
|
||||
|
||||
@code
|
||||
glfwSetCursorPosCallback(window, cursor_pos_callback);
|
||||
@@ -287,6 +286,9 @@ image.pixels = pixels;
|
||||
GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);
|
||||
@endcode
|
||||
|
||||
If cursor creation fails, `NULL` will be returned, so it is necessary to check
|
||||
the return value.
|
||||
|
||||
The image data is 32-bit RGBA, i.e. eight bits per channel. The pixels are
|
||||
arranged canonically as sequental rows, starting from the top-left corner.
|
||||
|
||||
@@ -299,7 +301,7 @@ When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
|
||||
glfwDestroyCursor(cursor);
|
||||
@endcode
|
||||
|
||||
Cursor destruction always succeeds. All cursors remaining at the time of @ref
|
||||
Cursor destruction always succeeds. All cursors remaining when @ref
|
||||
glfwTerminate is called are destroyed as well.
|
||||
|
||||
|
||||
@@ -330,7 +332,7 @@ does not affect the cursor modes of those windows.
|
||||
@subsection input_cursor_enter Cursor enter/leave events
|
||||
|
||||
If you wish to be notified when the cursor enters or leaves the client area of
|
||||
a window, set a cursor enter/leave callback with @ref glfwSetCursorEnterCallback.
|
||||
a window, set a cursor enter/leave callback.
|
||||
|
||||
@code
|
||||
glfwSetCursorEnterCallback(window, cursor_enter_callback);
|
||||
@@ -356,7 +358,7 @@ void cursor_enter_callback(GLFWwindow* window, int entered)
|
||||
@subsection input_mouse_button Mouse button input
|
||||
|
||||
If you wish to be notified when a mouse button is pressed or released, set
|
||||
a mouse button callback with @ref glfwSetMouseButtonCallback.
|
||||
a mouse button callback.
|
||||
|
||||
@code
|
||||
glfwSetMouseButtonCallback(window, mouse_button_callback);
|
||||
@@ -412,7 +414,7 @@ The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
|
||||
@subsection input_scroll Scroll input
|
||||
|
||||
If you wish to be notified when the user scrolls, whether with a mouse wheel or
|
||||
touchpad gesture, set a scroll callback with @ref glfwSetScrollCallback.
|
||||
touchpad gesture, set a scroll callback.
|
||||
|
||||
@code
|
||||
glfwSetScrollCallback(window, scroll_callback);
|
||||
@@ -539,7 +541,7 @@ window may be used.
|
||||
@section input_drop Path drop input
|
||||
|
||||
If you wish to receive the paths of files and/or directories dropped on
|
||||
a window, set a file drop callback with @ref glfwSetDropCallback.
|
||||
a window, set a file drop callback.
|
||||
|
||||
@code
|
||||
glfwSetDropCallback(window, drop_callback);
|
||||
|
||||
+1
-1
@@ -78,7 +78,7 @@ additional calls return immediately.
|
||||
@section error_handling Error handling
|
||||
|
||||
Some GLFW functions have return values that indicate an error, but this is often
|
||||
not very helpful when trying to figure out *why* the error occurred. Some
|
||||
not very helpful when trying to figure out _why_ the error occurred. Some
|
||||
functions also return otherwise valid values on error. Finally, far from all
|
||||
GLFW functions have return values.
|
||||
|
||||
|
||||
+5
-5
@@ -18,11 +18,11 @@ API.
|
||||
|
||||
There are guides for each of the various areas of the API.
|
||||
|
||||
- @ref intro
|
||||
- @ref window
|
||||
- @ref context
|
||||
- @ref monitor
|
||||
- @ref input
|
||||
- @ref intro – initialization, error handling and high-level design
|
||||
- @ref window – creating and working with windows and framebuffers
|
||||
- @ref context – working with OpenGL and OpenGL ES contexts
|
||||
- @ref monitor – enumerating and working with monitors and video modes
|
||||
- @ref input – receiving events, polling and processing input
|
||||
|
||||
The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
|
||||
design, implementation and use of GLFW.
|
||||
|
||||
+11
-6
@@ -24,9 +24,9 @@ a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type
|
||||
application and retain their addresses until the monitors they represent are
|
||||
disconnected or until the library is [terminated](@ref intro_init_terminate).
|
||||
|
||||
Each monitor has a human-readable name, a current video mode, a list of
|
||||
supported video modes, a virtual position, an estimated physical size and
|
||||
a gamma ramp.
|
||||
Each monitor has a current video mode, a list of supported video modes,
|
||||
a virtual position, a human-readable name, an estimated physical size and
|
||||
a gamma ramp. One of the monitors is the primary monitor.
|
||||
|
||||
The virtual position of a monitor is in screen coordinates and, together with
|
||||
the current video mode, describes the viewports that the connected monitors
|
||||
@@ -37,7 +37,7 @@ provide into the virtual desktop that spans them.
|
||||
|
||||
The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's
|
||||
preferred monitor and is usually the one with global UI elements like task bar
|
||||
or menu bar. The returned structure is allocated and freed by GLFW.
|
||||
or menu bar.
|
||||
|
||||
@code
|
||||
GLFWmonitor* primary = glfwGetPrimaryMonitor();
|
||||
@@ -59,7 +59,7 @@ disconnected.
|
||||
@subsection monitor_event Monitor configuration changes
|
||||
|
||||
If you wish to be notified when a monitor is connected or disconnected, set
|
||||
a monitor callback with @ref glfwSetMonitorCallback.
|
||||
a monitor callback.
|
||||
|
||||
@code
|
||||
glfwSetMonitorCallback(monitor_callback);
|
||||
@@ -79,6 +79,11 @@ The action is one of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
|
||||
|
||||
@section monitor_properties Monitor properties
|
||||
|
||||
Each monitor has a current video mode, a list of supported video modes,
|
||||
a virtual position, a human-readable name, an estimated physical size and
|
||||
a gamma ramp.
|
||||
|
||||
|
||||
@subsection monitor_modes Video modes
|
||||
|
||||
Although GLFW generally does a good job at selecting a suitable video
|
||||
@@ -87,7 +92,7 @@ know exactly which modes are available on a certain system. For example,
|
||||
you may want to present the user with a list of video modes to select
|
||||
from.
|
||||
|
||||
To get a list of available video modes, you can use the function @ref
|
||||
To get a list of supported video modes, you can use the function @ref
|
||||
glfwGetVideoModes. See the reference documentation for the lifetime of the
|
||||
returned array.
|
||||
|
||||
|
||||
+5
-5
@@ -5,7 +5,7 @@
|
||||
@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
|
||||
changed or been removed, but does _not_ include
|
||||
[new features](@ref news) unless they are required when moving an existing code
|
||||
base onto the new API. For example, the new multi-monitor functions are
|
||||
required to create full screen windows with GLFW 3.
|
||||
@@ -50,7 +50,7 @@ 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
|
||||
However, GLFW 3 has better support for _use from multiple threads_ than GLFW
|
||||
2 had. Contexts can be made current on any thread, although only a single
|
||||
thread at a time, and the documentation explicitly states which functions may be
|
||||
used from any thread and which may only be used from the main thread.
|
||||
@@ -149,7 +149,7 @@ into [window hints](@ref window_hints), but as they have been given
|
||||
|
||||
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, which acts on a single window, **glfwPollEvents** and
|
||||
Unlike buffer swap, which acts on a single window, __glfwPollEvents__ and
|
||||
__glfwWaitEvents__ process events for all windows at once.
|
||||
|
||||
@par Old basic main loop
|
||||
@@ -428,8 +428,8 @@ invalidating any window handles you may still have.
|
||||
@subsection moving_glu GLU header inclusion
|
||||
|
||||
GLFW 3 does not by default include the GLU header and GLU itself has been
|
||||
deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). **New
|
||||
projects should avoid using GLU**, but if you need to compile legacy code that
|
||||
deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). __New
|
||||
projects should avoid using GLU__, but if you need to compile legacy code that
|
||||
has been moved to GLFW 3, you can request that the GLFW header includes it by
|
||||
defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW header.
|
||||
|
||||
|
||||
+1
-1
@@ -139,7 +139,7 @@ glfwSetGamma, which generates a ramp from a gamma value and then sets it.
|
||||
|
||||
GLFW now supports the creation of OpenGL ES contexts, by setting the
|
||||
`GLFW_CLIENT_API` window hint to `GLFW_OPENGL_ES_API`, where creation of such
|
||||
contexts are supported. Note that GLFW *does not implement* OpenGL ES, so your
|
||||
contexts are supported. Note that GLFW _does not implement_ OpenGL ES, so your
|
||||
driver must provide support in a way usable by GLFW. Modern nVidia and Intel
|
||||
drivers support creation of OpenGL ES context using the GLX and WGL APIs, while
|
||||
AMD provides an EGL implementation instead.
|
||||
|
||||
+6
-6
@@ -35,15 +35,15 @@ and pollute your code's namespace with the whole Win32 API.
|
||||
|
||||
Instead, the GLFW header takes care of this for you, not by including
|
||||
`windows.h`, but rather by itself duplicating only the necessary parts of it.
|
||||
It does this only where needed, so if `windows.h` *is* included, the GLFW header
|
||||
It does this only where needed, so if `windows.h` _is_ included, the GLFW header
|
||||
does not try to redefine those symbols.
|
||||
|
||||
In other words:
|
||||
|
||||
- Do *not* include the OpenGL headers yourself, as GLFW does this for you
|
||||
- Do *not* include `windows.h` or other platform-specific headers unless
|
||||
- Do _not_ include the OpenGL headers yourself, as GLFW does this for you
|
||||
- Do _not_ include `windows.h` or other platform-specific headers unless
|
||||
you plan on using those APIs directly
|
||||
- If you *do* need to include such headers, do it *before* including the
|
||||
- If you _do_ need to include such headers, do it _before_ including the
|
||||
GLFW one and it will detect this
|
||||
|
||||
Starting with version 3.0, the GLU header `glu.h` is no longer included by
|
||||
@@ -162,7 +162,7 @@ Each window has a flag indicating whether the window should be closed.
|
||||
|
||||
When the user attempts to close the window, either by pressing the close widget
|
||||
in the title bar or using a key combination like Alt+F4, this flag is set to 1.
|
||||
Note that **the window isn't actually closed**, so you are expected to monitor
|
||||
Note that __the window isn't actually closed__, so you are expected to monitor
|
||||
this flag and either destroy the window or give some kind of feedback to the
|
||||
user.
|
||||
|
||||
@@ -248,7 +248,7 @@ glfwSwapBuffers(window);
|
||||
@endcode
|
||||
|
||||
The swap interval indicates how many frames to wait until swapping the buffers,
|
||||
commonly known as *vsync*. By default, the swap interval is zero, meaning
|
||||
commonly known as _vsync_. By default, the swap interval is zero, meaning
|
||||
buffer swapping will occur immediately. On fast machines, many of those frames
|
||||
will never be seen, as the screen is still only updated typically 60-75 times
|
||||
per second, so this wastes a lot of CPU and GPU cycles.
|
||||
|
||||
+71
-40
@@ -38,32 +38,65 @@ GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
|
||||
If window creation fails, `NULL` will be returned, so it is necessary to check
|
||||
the return value.
|
||||
|
||||
@code
|
||||
if (!window)
|
||||
{
|
||||
// Handle window creation failure
|
||||
}
|
||||
@endcode
|
||||
|
||||
The window handle is passed to all window related functions and is provided to
|
||||
along with all input events, so event handlers can tell which window received
|
||||
the event.
|
||||
|
||||
|
||||
@subsubsection window_full_screen Full screen windows
|
||||
|
||||
To create a full screen window, you need to specify which monitor the window
|
||||
should use. In most cases, the user's primary monitor is a good choice. You
|
||||
can get this with @ref glfwGetPrimaryMonitor. For more information about
|
||||
monitors, see the @ref monitor.
|
||||
should use. In most cases, the user's primary monitor is a good choice.
|
||||
For more information about retrieving monitors, see @ref monitor_monitors.
|
||||
|
||||
@code
|
||||
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
|
||||
@endcode
|
||||
|
||||
Full screen windows cover the entire display area of a monitor, have no border
|
||||
or decorations, and change the monitor's resolution to the one most closely
|
||||
matching the requested window size.
|
||||
or decorations.
|
||||
|
||||
For more control over how the window and its context are created, see @ref
|
||||
window_hints below.
|
||||
The requested window size combined with the window hints below form the _desired
|
||||
video mode_. The supported video mode most closely matching the desired video
|
||||
mode will be set for the chosen monitor as long as the window is focused. For
|
||||
more information about video modes supported by a monitor, see @ref
|
||||
monitor_modes.
|
||||
|
||||
Video mode field | Corresponds to
|
||||
----------------------- | ------------------------
|
||||
GLFWvidmode.width | `width` parameter
|
||||
GLFWvidmode.height | `height` parameter
|
||||
GLFWvidmode.redBits | `GLFW_RED_BITS` hint
|
||||
GLFWvidmode.greenBits | `GLFW_GREEN_BITS` hint
|
||||
GLFWvidmode.blueBits | `GLFW_BLUE_BITS` hint
|
||||
GLFWvidmode.refreshRate | `GLFW_REFRESH_RATE` hint
|
||||
|
||||
Once you have a full screen window, you can change its resolution with @ref
|
||||
glfwSetWindowSize. The new video mode will be selected and set the same way as
|
||||
the video mode chosen by @ref glfwCreateWindow.
|
||||
|
||||
By default, the original video mode of the monitor will be restored and the
|
||||
window iconified if it loses input focus, to allow the user to switch back to
|
||||
the desktop. This can be disabled with the `GLFW_AUTO_ICONIFY` window hint, for
|
||||
example if you wish to simultaneously cover multiple windows with full screen
|
||||
windows.
|
||||
|
||||
To create a so called _windowed full screen_ or _borderless full screen_ window,
|
||||
i.e. a full screen window that doesn't change the video mode of the monitor, you
|
||||
need to request the current video mode of the chosen monitor.
|
||||
|
||||
@code
|
||||
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
|
||||
|
||||
glfwWindowHint(GLFW_RED_BITS, mode->redBits);
|
||||
glfwWindowHint(GLFW_GREEN_BITS, mode->greenBits);
|
||||
glfwWindowHint(GLFW_BLUE_BITS, mode->blueBits);
|
||||
glfwWindowHint(GLFW_REFRESH_RATE, mode->refreshRate);
|
||||
|
||||
GLFWwindow* window = glfwCreateWindow(mode->width, mode->height, "My Title", monitor, NULL);
|
||||
@endcode
|
||||
|
||||
GLFW will detect this and will not perform any mode setting for that window.
|
||||
|
||||
|
||||
@subsection window_destruction Window destruction
|
||||
@@ -80,8 +113,7 @@ callbacks are removed so no further events will be delivered for the window.
|
||||
When a full screen window is destroyed, the original video mode of its monitor
|
||||
is restored, but the gamma ramp is left untouched.
|
||||
|
||||
All windows remaining at the time @ref glfwTerminate is called are destroyed as
|
||||
well.
|
||||
All windows remaining when @ref glfwTerminate is called are destroyed as well.
|
||||
|
||||
|
||||
@subsection window_hints Window creation hints
|
||||
@@ -92,14 +124,14 @@ context. These hints are set to their default values each time the library is
|
||||
initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint
|
||||
and reset all at once to their defaults with @ref glfwDefaultWindowHints.
|
||||
|
||||
Note that hints need to be set *before* the creation of the window and context
|
||||
Note that hints need to be set _before_ the creation of the window and context
|
||||
you wish to have the specified attributes.
|
||||
|
||||
|
||||
@subsubsection window_hints_hard Hard and soft constraints
|
||||
|
||||
Some window hints are hard constraints. These must match the available
|
||||
capabilities *exactly* for window and context creation to succeed. Hints
|
||||
capabilities _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. To
|
||||
find out the actual attributes of the created window and context, use the
|
||||
@@ -119,7 +151,7 @@ context, but are ignored when requesting an OpenGL ES context:
|
||||
@subsubsection window_hints_wnd Window related hints
|
||||
|
||||
`GLFW_RESIZABLE` specifies whether the (windowed mode) window will be resizable
|
||||
*by the user*. The window will still be resizable using the @ref
|
||||
_by the user_. The window will still be resizable using the @ref
|
||||
glfwSetWindowSize function. This hint is ignored for full screen windows.
|
||||
|
||||
`GLFW_VISIBLE` specifies whether the (windowed mode) window will be initially
|
||||
@@ -306,7 +338,7 @@ The initial value of the pointer is `NULL`.
|
||||
@subsection window_close Closing and close flag
|
||||
|
||||
When the user attempts to close the window, for example by clicking the close
|
||||
widget or using a key chord like Alt+F4, the *close flag* of the window is set.
|
||||
widget or using a key chord like Alt+F4, the _close flag_ of the window is set.
|
||||
The window is however not actually destroyed and, unless you watch for this
|
||||
state change, nothing further happens.
|
||||
|
||||
@@ -325,13 +357,13 @@ while (!glfwWindowShouldClose(window))
|
||||
@endcode
|
||||
|
||||
If you wish to be notified when the user attempts to close a window, set a close
|
||||
callback with @ref glfwSetWindowCloseCallback.
|
||||
callback.
|
||||
|
||||
@code
|
||||
glfwSetWindowCloseCallback(window, window_close_callback);
|
||||
@endcode
|
||||
|
||||
The callback function is called directly *after* the close flag has been set.
|
||||
The callback function is called directly _after_ the close flag has been set.
|
||||
It can be used for example to filter close requests and clear the close flag
|
||||
again unless certain conditions are met.
|
||||
|
||||
@@ -344,20 +376,23 @@ void window_close_callback(GLFWwindow* window)
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection window_size Client area size
|
||||
@subsection window_size Size
|
||||
|
||||
The size of a window can be changed with @ref glfwSetWindowSize. For windowed
|
||||
mode windows, this resizes the window so that its *client area* has the
|
||||
specified size. The window system may impose limits on window size. For full
|
||||
screen windows, it selects and sets the video mode most closely matching the
|
||||
specified size and the color bit depth and refresh rate hints set at creation.
|
||||
mode windows, this sets the size of the _client area_ or _content area_ of the
|
||||
window. The window system may impose limits on window size.
|
||||
|
||||
@code
|
||||
void glfwSetWindowSize(window, 640, 480);
|
||||
glfwSetWindowSize(window, 640, 480);
|
||||
@endcode
|
||||
|
||||
For full screen windows, the specified size becomes the new resolution of the
|
||||
window's *desired video mode*. The video mode most closely matching the new
|
||||
desired video mode is set immediately. The window is resized to fit the
|
||||
resolution of the set video mode.
|
||||
|
||||
If you wish to be notified when a window is resized, whether by the user or
|
||||
the system, set a size callback with @ref glfwSetWindowSizeCallback.
|
||||
the system, set a size callback.
|
||||
|
||||
@code
|
||||
glfwSetWindowSizeCallback(window, window_size_callback);
|
||||
@@ -409,8 +444,7 @@ a second set of functions to retrieve the size in pixels of the framebuffer of
|
||||
a window.
|
||||
|
||||
If you wish to be notified when the framebuffer of a window is resized, whether
|
||||
by the user or the system, set a size callback with @ref
|
||||
glfwSetFramebufferSizeCallback.
|
||||
by the user or the system, set a size callback.
|
||||
|
||||
@code
|
||||
glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
|
||||
@@ -452,7 +486,7 @@ glfwSetWindowPos(window, 100, 100);
|
||||
@endcode
|
||||
|
||||
If you wish to be notified when a window is moved, whether by the user, system
|
||||
or your own code, set a position callback with @ref glfwSetWindowPosCallback.
|
||||
or your own code, set a position callback.
|
||||
|
||||
@code
|
||||
glfwSetWindowPosCallback(window, window_pos_callback);
|
||||
@@ -533,8 +567,7 @@ When a full screen window is restored, the desired video mode is restored to its
|
||||
monitor as well.
|
||||
|
||||
If you wish to be notified when a window is iconified or restored, whether by
|
||||
the user, system or your own code, set a iconify callback with @ref
|
||||
glfwSetWindowIconifyCallback.
|
||||
the user, system or your own code, set a iconify callback.
|
||||
|
||||
@code
|
||||
glfwSetWindowIconifyCallback(window, window_iconify_callback);
|
||||
@@ -597,8 +630,7 @@ int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
|
||||
@subsection window_focus Input focus
|
||||
|
||||
If you wish to be notified when a window gains or loses focus, whether by
|
||||
the user, system or your own code, set a focus callback with @ref
|
||||
glfwSetWindowFocusCallback.
|
||||
the user, system or your own code, set a focus callback.
|
||||
|
||||
@code
|
||||
glfwSetWindowFocusCallback(window, window_focus_callback);
|
||||
@@ -630,8 +662,7 @@ int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
|
||||
@subsection window_refresh Damage and refresh
|
||||
|
||||
If you wish to be notified when the contents of a window is damaged and needs
|
||||
to be refreshed, set a window refresh callback with @ref
|
||||
glfwSetWindowRefreshCallback.
|
||||
to be refreshed, set a window refresh callback.
|
||||
|
||||
@code
|
||||
glfwSetWindowRefreshCallback(m_handle, window_refresh_callback);
|
||||
@@ -681,8 +712,8 @@ visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
|
||||
and initial visibility is controlled by the [window hint](@ref window_hints)
|
||||
with the same name.
|
||||
|
||||
`GLFW_RESIZABLE` indicates whether the specified window is resizable *by the
|
||||
user*. This is controlled by the [window hint](@ref window_hints) with the same
|
||||
`GLFW_RESIZABLE` indicates whether the specified window is resizable _by the
|
||||
user_. This is controlled by the [window hint](@ref window_hints) with the same
|
||||
name.
|
||||
|
||||
`GLFW_DECORATED` indicates whether the specified window has decorations such as
|
||||
|
||||
Reference in New Issue
Block a user