From 95654cfadabb9de4065f726b08390844e7e8e9a7 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Thu, 2 Oct 2014 17:35:10 +0200 Subject: [PATCH] Documentation work. --- docs/build.dox | 16 +++--- docs/compat.dox | 2 +- docs/compile.dox | 20 +++---- docs/context.dox | 4 +- docs/input.dox | 26 +++++---- docs/intro.dox | 2 +- docs/main.dox | 10 ++-- docs/monitor.dox | 17 ++++-- docs/moving.dox | 10 ++-- docs/news.dox | 2 +- docs/quick.dox | 12 ++-- docs/window.dox | 111 +++++++++++++++++++++++-------------- include/GLFW/glfw3.h | 128 ++++++++++++++++++++++++------------------- 13 files changed, 207 insertions(+), 153 deletions(-) diff --git a/docs/build.dox b/docs/build.dox index 2185aff1..60a6e24b 100644 --- a/docs/build.dox +++ b/docs/build.dox @@ -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. */ diff --git a/docs/compat.dox b/docs/compat.dox index dc4620aa..d3d9a6cc 100644 --- a/docs/compat.dox +++ b/docs/compat.dox @@ -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. diff --git a/docs/compile.dox b/docs/compile.dox index 123f7aa4..a8072eff 100644 --- a/docs/compile.dox +++ b/docs/compile.dox @@ -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) diff --git a/docs/context.dox b/docs/context.dox index 9ea9bed8..62d45a64 100644 --- a/docs/context.dox +++ b/docs/context.dox @@ -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`. diff --git a/docs/input.dox b/docs/input.dox index 5105c242..ba7ee70e 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -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); diff --git a/docs/intro.dox b/docs/intro.dox index 93e88a10..6e293e0f 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -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. diff --git a/docs/main.dox b/docs/main.dox index f0dceb9f..c18dcbb0 100644 --- a/docs/main.dox +++ b/docs/main.dox @@ -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. diff --git a/docs/monitor.dox b/docs/monitor.dox index 25cc9e5c..354820cc 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -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. diff --git a/docs/moving.dox b/docs/moving.dox index b30dee23..563c96de 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -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. diff --git a/docs/news.dox b/docs/news.dox index 70a3c1da..d225d22b 100644 --- a/docs/news.dox +++ b/docs/news.dox @@ -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. diff --git a/docs/quick.dox b/docs/quick.dox index b1761efb..21a8a8cc 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -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. diff --git a/docs/window.dox b/docs/window.dox index f8d51a53..816bf228 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -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 diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index b728012d..64ebcc73 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -263,7 +263,7 @@ extern "C" { /*! @defgroup keys Keyboard keys * - * These key codes are inspired by the *USB HID Usage Tables v1.12* (p. 53-60), + * These key codes are inspired by the _USB HID Usage Tables v1.12_ (p. 53-60), * but re-arranged to map to 7-bit ASCII for printable keys (function keys are * put in the 256+ range). * @@ -839,7 +839,7 @@ typedef void (* GLFWscrollfun)(GLFWwindow*,double,double); * @param[in] window The window that received the event. * @param[in] key The [keyboard key](@ref keys) that was pressed or released. * @param[in] scancode The system-specific scancode of the key. - * @param[in] action @ref GLFW_PRESS, @ref GLFW_RELEASE or @ref GLFW_REPEAT. + * @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`. * @param[in] mods Bit field describing which [modifier keys](@ref mods) were * held down. * @@ -997,7 +997,7 @@ typedef struct GLFWimage * @return `GL_TRUE` if successful, or `GL_FALSE` if an * [error](@ref error_handling) occurred. * - * @remarks **OS X:** This function will change the current directory of the + * @remarks __OS X:__ This function will change the current directory of the * application to the `Contents/Resources` subdirectory of the application's * bundle, if present. This can be disabled with a * [compile-time option](@ref compile_options_osx). @@ -1012,7 +1012,7 @@ typedef struct GLFWimage * Added in GLFW 1.0. * * @par - * **GLFW 3:** This function no longer registers @ref glfwTerminate with `atexit`. + * __GLFW 3:__ This function no longer registers @ref glfwTerminate with `atexit`. * * @ingroup init */ @@ -1277,7 +1277,7 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @bug **X11:** This callback is not yet called on monitor configuration + * @bug __X11:__ This callback is not yet called on monitor configuration * changes. * * @par Thread Safety @@ -1320,7 +1320,7 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Changed to return a dynamic array of video modes for a specific + * __GLFW 3:__ Changed to return a dynamic array of video modes for a specific * monitor. * * @ingroup monitor @@ -1463,7 +1463,7 @@ GLFWAPI void glfwDefaultWindowHints(void); * Added in GLFW 2.2. * * @par - * **GLFW 3:** Renamed from `glfwOpenWindowHint`. Hints are no longer reset to + * __GLFW 3:__ Renamed from `glfwOpenWindowHint`. Hints are no longer reset to * default values on window creation. * * @ingroup window @@ -1494,17 +1494,24 @@ GLFWAPI void glfwWindowHint(int target, int hint); * that you pick the primary monitor. For more information on how to query * connected monitors, see @ref monitor_monitors. * + * For full screen windows, the specified size becomes the resolution of the + * window's _desired video mode_. As long as a full screen window has input + * focus, the supported video mode most closely matching the desired video mode + * is set for the specified monitor. For more information about full screen + * windows, including the creation of so called _windowed full screen_ or + * _borderless full screen_ windows, see @ref window_full_screen. + * * By default, newly created windows use the placement recommended by the * window system. To create the window at a specific position, make it - * initially invisible using the `GLFW_VISIBLE` window hint, set its position - * and then show it. + * initially invisible using the `GLFW_VISIBLE` window hint, set its + * [position](@ref window_pos) and then [show](@ref window_hide) it. * - * If a full screen window is active, the screensaver is prohibited from + * If a full screen window is focused, the screensaver is prohibited from * starting. * * Window systems put limits on window sizes. Very large or very small window * dimensions may be overridden by the window system on creation. Check the - * actual [window size](@ref window_size) after creation. + * actual [size](@ref window_size) after creation. * * The [swap interval](@ref window_swap) is not set during window creation and * the initial value may vary depending on driver settings and defaults. @@ -1521,27 +1528,27 @@ GLFWAPI void glfwWindowHint(int target, int hint); * @return The handle of the created window, or `NULL` if an * [error](@ref error_handling) occurred. * - * @remarks **Windows:** Window creation will fail if the Microsoft GDI + * @remarks __Windows:__ Window creation will fail if the Microsoft GDI * software OpenGL implementation is the only one available. * - * @remarks **Windows:** If the executable has an icon resource named + * @remarks __Windows:__ If the executable has an icon resource named * `GLFW_ICON,` it will be set as the icon for the window. If no such icon is * present, the `IDI_WINLOGO` icon will be used instead. * - * @remarks **OS X:** The GLFW window has no icon, as it is not a document + * @remarks __OS X:__ The GLFW window has no icon, as it is not a document * window, but the dock icon will be the same as the application bundle's icon. * For more information on bundles, see the * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) * in the Mac Developer Library. * - * @remarks **OS X:** The first time a window is opened the menu bar is populated with + * @remarks __OS X:__ The first time a window is opened the menu bar is populated with * common commands like Hide, Quit and About. The About entry opens a minimal * about dialog with information from the application's bundle. The menu bar can be * disabled with a [compile-time option](@ref compile_options_osx). * - * @remarks **X11:** There is no mechanism for setting the window icon yet. + * @remarks __X11:__ There is no mechanism for setting the window icon yet. * - * @remarks **X11:** Some window managers will not respect the placement of + * @remarks __X11:__ Some window managers will not respect the placement of * initially hidden windows. * * @note This function may not be called from a callback. @@ -1556,7 +1563,7 @@ GLFWAPI void glfwWindowHint(int target, int hint); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Renamed from `glfwOpenWindow`. Complete signature overhaul. + * __GLFW 3:__ Renamed from `glfwOpenWindow`. Complete signature overhaul. * * @ingroup window */ @@ -1587,7 +1594,7 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G * Added in GLFW 1.0. * * @par - * **GLFW 3:** Renamed from `glfwCloseWindow`. Added window handle parameter. + * __GLFW 3:__ Renamed from `glfwCloseWindow`. Added window handle parameter. * * @ingroup window */ @@ -1650,7 +1657,7 @@ GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. + * __GLFW 3:__ Added window handle parameter. * * @ingroup window */ @@ -1708,7 +1715,7 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. + * __GLFW 3:__ Added window handle parameter. * * @ingroup window */ @@ -1739,7 +1746,7 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. + * __GLFW 3:__ Added window handle parameter. * * @ingroup window */ @@ -1771,7 +1778,7 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. + * __GLFW 3:__ Added window handle parameter. * * @ingroup window */ @@ -1862,7 +1869,7 @@ GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int * Added in GLFW 2.1. * * @par - * **GLFW 3:** Added window handle parameter. + * __GLFW 3:__ Added window handle parameter. * * @ingroup window */ @@ -1888,7 +1895,7 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window); * Added in GLFW 2.1. * * @par - * **GLFW 3:** Added window handle parameter. + * __GLFW 3:__ Added window handle parameter. * * @ingroup window */ @@ -1977,7 +1984,7 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Renamed from `glfwGetWindowParam`. Added window handle + * __GLFW 3:__ Renamed from `glfwGetWindowParam`. Added window handle * parameter. * * @ingroup window @@ -2047,7 +2054,7 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); * Added in GLFW 3.0. * * @par - * **GLFW 3:** Added window handle parameter. Updated callback signature. + * __GLFW 3:__ Added window handle parameter. Updated callback signature. * * @ingroup window */ @@ -2074,7 +2081,7 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. Updated callback signature. + * __GLFW 3:__ Added window handle parameter. Updated callback signature. * * @ingroup window */ @@ -2097,7 +2104,7 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind * @return The previously set callback, or `NULL` if no callback was set or the * library had not been [initialized](@ref intro_init). * - * @remarks **OS X:** Selecting Quit from the application menu will + * @remarks __OS X:__ Selecting Quit from the application menu will * trigger the close callback for all windows. * * @par Thread Safety @@ -2109,7 +2116,7 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind * Added in GLFW 2.5. * * @par - * **GLFW 3:** Added window handle parameter. Updated callback signature. + * __GLFW 3:__ Added window handle parameter. Updated callback signature. * * @ingroup window */ @@ -2140,7 +2147,7 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi * Added in GLFW 2.5. * * @par - * **GLFW 3:** Added window handle parameter. Updated callback signature. + * __GLFW 3:__ Added window handle parameter. Updated callback signature. * * @ingroup window */ @@ -2250,7 +2257,7 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window * Added in GLFW 1.0. * * @par - * **GLFW 3:** This function is no longer called by @ref glfwSwapBuffers. + * __GLFW 3:__ This function is no longer called by @ref glfwSwapBuffers. * * @ingroup window */ @@ -2322,6 +2329,10 @@ GLFWAPI void glfwWaitEvents(void); GLFWAPI void glfwPostEmptyEvent(void); /*! @brief Returns the value of an input option for the specified window. + * + * This function returns the value of an input option for the specified window. + * The mode must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or + * `GLFW_STICKY_MOUSE_BUTTONS`. * * @param[in] window The window to query. * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or @@ -2340,10 +2351,10 @@ GLFWAPI void glfwPostEmptyEvent(void); GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); /*! @brief Sets an input option for the specified window. - * @param[in] window The window whose input mode to set. - * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or + * + * This function sets an input mode option for the specified window. The mode + * must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or * `GLFW_STICKY_MOUSE_BUTTONS`. - * @param[in] value The new value of the specified input mode. * * If the mode is `GLFW_CURSOR`, the value must be one of the following cursor * modes: @@ -2358,18 +2369,23 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); * * If the mode is `GLFW_STICKY_KEYS`, the value must be either `GL_TRUE` to * enable sticky keys, or `GL_FALSE` to disable it. If sticky keys are - * enabled, a key press will ensure that @ref glfwGetKey returns @ref - * GLFW_PRESS the next time it is called even if the key had been released - * before the call. This is useful when you are only interested in whether - * keys have been pressed but not when or in which order. + * enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS` + * the next time it is called even if the key had been released before the + * call. This is useful when you are only interested in whether keys have been + * pressed but not when or in which order. * * If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either * `GL_TRUE` to enable sticky mouse buttons, or `GL_FALSE` to disable it. If * sticky mouse buttons are enabled, a mouse button press will ensure that @ref - * glfwGetMouseButton returns @ref GLFW_PRESS the next time it is called even - * if the mouse button had been released before the call. This is useful when - * you are only interested in whether mouse buttons have been pressed but not - * when or in which order. + * glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even if + * the mouse button had been released before the call. This is useful when you + * are only interested in whether mouse buttons have been pressed but not when + * or in which order. + * + * @param[in] window The window whose input mode to set. + * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or + * `GLFW_STICKY_MOUSE_BUTTONS`. + * @param[in] value The new value of the specified input mode. * * @par Thread Safety * This function may only be called from the main thread. @@ -2416,7 +2432,7 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. + * __GLFW 3:__ Added window handle parameter. * * @ingroup input */ @@ -2447,7 +2463,7 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. + * __GLFW 3:__ Added window handle parameter. * * @ingroup input */ @@ -2487,7 +2503,7 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Renamed from `glfwGetMousePos`. Added window handle parameter. + * __GLFW 3:__ Renamed from `glfwGetMousePos`. Added window handle parameter. * Moved to floating-point coordinates. * * @ingroup input @@ -2512,7 +2528,7 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); * @param[in] ypos The desired y-coordinate, relative to the top edge of the * client area. * - * @remarks **X11:** Due to the asynchronous nature of a modern X desktop, it + * @remarks __X11:__ Due to the asynchronous nature of a modern X desktop, it * may take a moment for the window focus event to arrive. This means you will * not be able to set the cursor position directly after window creation. * @@ -2526,7 +2542,7 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Renamed from `glfwSetMousePos`. Added window handle parameter. + * __GLFW 3:__ Renamed from `glfwSetMousePos`. Added window handle parameter. * Moved to floating-point coordinates. * * @ingroup input @@ -2650,7 +2666,7 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. Updated callback signature. + * __GLFW 3:__ Added window handle parameter. Updated callback signature. * * @ingroup input */ @@ -2690,7 +2706,7 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun); * Added in GLFW 2.4. * * @par - * **GLFW 3:** Added window handle parameter. Updated callback signature. + * __GLFW 3:__ Added window handle parameter. Updated callback signature. * * @ingroup input */ @@ -2755,7 +2771,7 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. Updated callback signature. + * __GLFW 3:__ Added window handle parameter. Updated callback signature. * * @ingroup input */ @@ -2783,7 +2799,7 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo * Added in GLFW 1.0. * * @par - * **GLFW 3:** Renamed from `glfwSetMousePosCallback`. Added window handle + * __GLFW 3:__ Renamed from `glfwSetMousePosCallback`. Added window handle * parameter. Updated callback signature. * * @ingroup input @@ -2838,7 +2854,7 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu * Added in GLFW 2.1. * * @par - * **GLFW 3:** Renamed from `glfwSetMouseWheelCallback`. Added window handle. + * __GLFW 3:__ Renamed from `glfwSetMouseWheelCallback`. Added window handle. * Updated callback signature. * * @ingroup input @@ -2916,7 +2932,7 @@ GLFWAPI int glfwJoystickPresent(int joy); * Added in GLFW 2.2. * * @par - * **GLFW 3:** Renamed from `glfwGetJoystickPos`. Changed to return a dynamic + * __GLFW 3:__ Renamed from `glfwGetJoystickPos`. Changed to return a dynamic * array. * * @ingroup input @@ -2947,7 +2963,7 @@ GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count); * Added in GLFW 2.2. * * @par - * **GLFW 3:** Changed to return a dynamic array. + * __GLFW 3:__ Changed to return a dynamic array. * * @ingroup input */ @@ -3143,7 +3159,7 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void); * Added in GLFW 1.0. * * @par - * **GLFW 3:** Added window handle parameter. Removed call to @ref + * __GLFW 3:__ Added window handle parameter. Removed call to @ref * glfwPollEvents. * * @ingroup window