diff --git a/README.md b/README.md index dde62627..91b3ae5e 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,10 @@ GLFW is a free, Open Source, multi-platform library for OpenGL and OpenGL ES application development. It provides a simple, platform-independent API for creating windows and contexts, reading input, handling events, etc. -Version 3.1 adds support for custom system cursors, file drop events, main -thread wake-up, improved documentation, window frame size retrieval, floating -windows, character input with modifier keys, single buffered windows, build -improvements and fixes for a large number of bugs. +Version 3.1 adds improved documentation, support for custom system cursors, file +drop events, main thread wake-up, window frame size retrieval, floating windows, +character input with modifier keys, single buffered windows, build improvements +and fixes for a large number of bugs. If you are new to GLFW, you may find the [introductory tutorial](http://www.glfw.org/docs/latest/quick.html) for GLFW diff --git a/docs/compat.dox b/docs/compat.dox index dcce843b..7ff4ab04 100644 --- a/docs/compat.dox +++ b/docs/compat.dox @@ -103,13 +103,14 @@ creating OpenGL contexts of version 2.1 and below. Where this extension is unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint will have no effect, and setting the `GLFW_OPENGL_PROFILE` or -`GLFW_OPENGL_FORWARD_COMPAT` hints to a non-zero value will cause @ref +`GLFW_OPENGL_FORWARD_COMPAT` hints to `GL_TRUE` will cause @ref glfwCreateWindow to fail. GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for context profiles. Where this extension is unavailable, setting the -`GLFW_OPENGL_PROFILE` hint to anything but zero, or setting `GLFW_CLIENT_API` to -anything but `GLFW_OPENGL_API` will cause @ref glfwCreateWindow to fail. +`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE`, or setting +`GLFW_CLIENT_API` to anything but `GLFW_OPENGL_API` will cause @ref +glfwCreateWindow to fail. GLFW uses the `GLX_ARB_context_flush_control` extension to provide control over whether a context is flushed when it is released (made non-current). Where this @@ -140,13 +141,13 @@ creating OpenGL contexts of version 2.1 and below. Where this extension is unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint will have no effect, and setting the `GLFW_OPENGL_PROFILE` or -`GLFW_OPENGL_FORWARD_COMPAT` hints to a non-zero value will cause @ref +`GLFW_OPENGL_FORWARD_COMPAT` hints to `GL_TRUE` will cause @ref glfwCreateWindow to fail. GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for context profiles. Where this extension is unavailable, setting the -`GLFW_OPENGL_PROFILE` hint to anything but zero will cause @ref glfwCreateWindow -to fail. +`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE` will cause +@ref glfwCreateWindow to fail. GLFW uses the `WGL_ARB_context_flush_control` extension to provide control over whether a context is flushed when it is released (made non-current). Where this @@ -165,7 +166,7 @@ version 2.1. Because of this, on OS X 10.7 and later, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints will cause @ref glfwCreateWindow to fail if given version 3.0 or 3.1, the `GLFW_OPENGL_FORWARD_COMPAT` hint must be set to -non-zero and the `GLFW_OPENGL_PROFILE` hint must be set to +`GL_TRUE` and the `GLFW_OPENGL_PROFILE` hint must be set to `GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts and the `GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored. diff --git a/docs/context.dox b/docs/context.dox index 1d8f284c..eaa754b8 100644 --- a/docs/context.dox +++ b/docs/context.dox @@ -110,7 +110,7 @@ error. @section context_swap Buffer swapping Buffer swapping is part of the window and framebuffer, not the context. See -@ref window_swap in the window guide. +@ref buffer_swap. @section context_glext OpenGL and OpenGL ES extensions @@ -194,7 +194,7 @@ generated and you are ready to start rendering. You can specify a minimum required OpenGL or OpenGL ES version with [context hints](@ref window_hints_ctx). If your needs are more complex, you can check the actual OpenGL or OpenGL ES version with -[context attributes](@ref window_attribs_context), or you can check whether +[context attributes](@ref window_attribs_ctx), or you can check whether a specific version is supported by the current context with the `GLAD_GL_VERSION_x_x` booleans. @@ -271,8 +271,8 @@ if (glfwExtensionSupported("GL_ARB_debug_output")) @endcode The argument is a null terminated ASCII string with the extension name. If the -extension is supported, @ref glfwExtensionSupported returns non-zero, otherwise -it returns zero. +extension is supported, @ref glfwExtensionSupported returns `GL_TRUE`, otherwise +it returns `GL_FALSE`. @subsubsection context_glext_proc Fetching function pointers diff --git a/docs/input.dox b/docs/input.dox index e679703d..fb38808b 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -28,12 +28,12 @@ out all arguments provided for every event, along with time and sequence information. -@section input_event Event processing +@section events Event processing GLFW needs to communicate regularly with the window system both in order to receive events and to show that the application hasn't locked up. Event processing must be done regularly while you have visible windows and is normally -done each frame after [buffer swapping](@ref window_swap). +done each frame after [buffer swapping](@ref buffer_swap). There are two functions for processing pending events. @ref glfwPollEvents, processes only those events that have already been received and then returns @@ -182,7 +182,7 @@ key combinations that a plain text field would ignore, or just want to know exactly what modifier keys were used, set a character with modifiers callback. @code -glfwSetCharCallback(window, charmods_callback); +glfwSetCharModsCallback(window, charmods_callback); @endcode The callback function receives Unicode code points and @@ -197,15 +197,15 @@ void charmods_callback(GLFWwindow* window, unsigned int codepoint, int mods) @section input_mouse Mouse input -Mouse input comes in many forms, including of mouse motion and button presses, -system cursor appearance and behavior, and two-dimensional scrolling. All of -these are supported by GLFW. +Mouse input comes in many forms, including cursor motion, button presses and +scrolling offsets. The cursor appearance can also be changed, either to +a custom image or a standard cursor shape from the system theme. -@subsection input_cursor_pos Cursor position +@subsection cursor_pos Cursor position -If you wish to be notified when the system cursor moves over the window, set -a cursor position callback. +If you wish to be notified when the cursor moves over the window, set a cursor +position callback. @code glfwSetCursorPosCallback(window, cursor_pos_callback); @@ -229,12 +229,12 @@ glfwGetCursorPos(window, &xpos, &ypos); @endcode -@subsection input_cursor_mode Cursor modes +@subsection cursor_mode Cursor modes The `GLFW_CURSOR` input mode provides several cursor modes for special forms of -mouse motion input. By default, the `GLFW_CURSOR_NORMAL` cursor mode is used, -meaning the regular arrow cursor or a [custom cursor](@ref input_cursor) is used -and cursor motion is not limited. +mouse motion input. By default, the cursor mode is `GLFW_CURSOR_NORMAL`, +meaning the regular arrow cursor (or another cursor set with @ref glfwSetCursor) +is used and cursor motion is not limited. If you wish to implement mouse motion based camera controls or other input schemes that require unlimited mouse movement, set the cursor mode to @@ -247,12 +247,11 @@ glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED); This will hide the cursor and lock it to the specified window. GLFW will then take care of all the details of cursor re-centering and offset calculation and providing the application with a virtual cursor position. This virtual position -is provided normally, both via the cursor position callback and via position -polling. +is provided normally via both the cursor position callback and through polling. @note You should not implement your own version of this functionality using -other features of GLFW. It will not work as robustly as `GLFW_CURSOR_DISABLED`, -as those features are not intended for this purpose. +other features of GLFW. It is not supported and will not work as robustly as +`GLFW_CURSOR_DISABLED`. If you just wish the cursor to become hidden when it is over a window, set the cursor mode to `GLFW_CURSOR_HIDDEN`. @@ -271,18 +270,19 @@ glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL); @endcode -@subsection input_cursor Cursor objects +@subsection cursor_object Cursor objects -GLFW supports creating custom system cursor images, encapsulated as @ref -GLFWcursor objects. They are created with @ref glfwCreateCursor and destroyed -with @ref glfwDestroyCursor (or @ref glfwTerminate, if any remain). +GLFW supports creating both custom and system theme cursor images, encapsulated +as @ref GLFWcursor objects. They are created with @ref glfwCreateCursor or @ref +glfwCreateStandardCursor and destroyed with @ref glfwDestroyCursor, or @ref +glfwTerminate, if any remain. -@subsubsection input_cursor_creation Cursor creation +@subsubsection cursor_custom Custom cursor creation -A cursor is created with @ref glfwCreateCursor, which returns a handle to the -created cursor object. For example, this creates a 16x16 white square cursor -with the hot-spot in the upper-left corner: +A custom cursor is created with @ref glfwCreateCursor, which returns a handle to +the created cursor object. For example, this creates a 16x16 white square +cursor with the hot-spot in the upper-left corner: @code unsigned char pixels[16 * 16 * 4]; @@ -303,7 +303,20 @@ The image data is 32-bit RGBA, i.e. eight bits per channel. The pixels are arranged canonically as sequential rows, starting from the top-left corner. -@subsubsection input_cursor_destruction Cursor destruction +@subsubsection cursor_standard Standard cursor creation + +A cursor with a [standard shape](@ref shapes) from the current system cursor +theme can be can be created with @ref glfwCreateStandardCursor. + +@code +GLFWcursor* cursor = glfwCreateStandardCursor(GLFW_HRESIZE_CURSOR); +@endcode + +These cursor objects behave in the exact same way as those created with @ref +glfwCreateCursor except that the system cursor theme provides the actual image. + + +@subsubsection cursor_destruction Cursor destruction When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor. @@ -315,7 +328,7 @@ Cursor destruction always succeeds. All cursors remaining when @ref glfwTerminate is called are destroyed as well. -@subsubsection input_cursor_set Cursor setting +@subsubsection cursor_set Cursor setting A cursor can be set as current for a window with @ref glfwSetCursor. @@ -324,7 +337,7 @@ glfwSetCursor(window, cursor); @endcode Once set, the cursor image will be used as long as the system cursor is over the -client area of the window and the [cursor mode](@ref input_cursor_mode) is set +client area of the window and the [cursor mode](@ref cursor_mode) is set to `GLFW_CURSOR_NORMAL`. A single cursor may be set for any number of windows. @@ -339,21 +352,7 @@ When a cursor is destroyed, it is removed from any window where it is set. This does not affect the cursor modes of those windows. -@subsubsection input_cursor_standard Standard cursor shapes - -Cursor objects with platform-specific variants of the -[standard shapes](@ref shapes) can be created with @ref -glfwCreateStandardCursor. - -@code -GLFWcursor* cursor = glfwCreateStandardCursor(GLFW_HRESIZE_CURSOR); -@endcode - -These cursor objects behave in the exact same way as those created with @ref -glfwCreateCursor except that the platform provides the cursor image data. - - -@subsection input_cursor_enter Cursor enter/leave events +@subsection 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. @@ -435,7 +434,7 @@ The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any [named button](@ref buttons). -@subsection input_scroll Scroll input +@subsection scrolling Scroll input If you wish to be notified when the user scrolls, whether with a mouse wheel or touchpad gesture, set a scroll callback. @@ -455,7 +454,7 @@ void scroll_callback(GLFWwindow* window, double xoffset, double yoffset) A simple mouse wheel, being vertical, provides offsets along the Y-axis. -@section input_joy Joystick input +@section joystick Joystick input The joystick functions expose connected joysticks and controllers, with both referred to as joysticks. It supports up to sixteen joysticks, ranging from @@ -476,7 +475,7 @@ not require a window to be created or @ref glfwPollEvents or @ref glfwWaitEvents to be called. -@subsection input_joy_axis Joystick axis states +@subsection joystick_axis Joystick axis states The positions of all axes of a joystick are returned by @ref glfwGetJoystickAxes. See the reference documentation for the lifetime of the @@ -490,7 +489,7 @@ const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_1, &count); Each element in the returned array is a value between -1.0 and 1.0. -@subsection input_joy_button Joystick button states +@subsection joystick_button Joystick button states The states of all buttons of a joystick are returned by @ref glfwGetJoystickButtons. See the reference documentation for the lifetime of the @@ -504,7 +503,7 @@ const unsigned char* axes = glfwGetJoystickButtons(GLFW_JOYSTICK_1, &count); Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`. -@subsection input_joy_name Joystick name +@subsection joystick_name Joystick name The human-readable, UTF-8 encoded name of a joystick is returned by @ref glfwGetJoystickName. See the reference documentation for the lifetime of the @@ -519,7 +518,7 @@ and make may have the same name. Only the [joystick token](@ref joysticks) is guaranteed to be unique, and only until that joystick is disconnected. -@section input_time Time input +@section time Time input GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime. @@ -540,7 +539,7 @@ glfwSetTime(4.0); This sets the timer to the specified time, in seconds. -@section input_clipboard Clipboard input and output +@section clipboard Clipboard input and output If the system clipboard contains a UTF-8 encoded string or if it can be converted to one, you can retrieve it with @ref glfwGetClipboardString. See the @@ -562,7 +561,7 @@ systems require a window to communicate with the system clipboard. Any valid window may be used. -@section input_drop Path drop input +@section path_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. diff --git a/docs/intro.dox b/docs/intro.dox index 8d91783f..7888e5fd 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -37,8 +37,8 @@ GLFW_NOT_INITIALIZED error. @subsection intro_init_init Initializing GLFW -The library is initialized with @ref glfwInit, which returns zero if an error -occurred. +The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an +error occurred. @code if (!glfwInit()) @@ -50,7 +50,7 @@ if (!glfwInit()) If any part of initialization fails, all remaining bits are terminated as if @ref glfwTerminate was called. The library only needs to be initialized once and additional calls to an already initialized library will simply return -non-zero immediately. +`GL_TRUE` immediately. Once the library has been successfully initialized, it should be terminated before the application exits. diff --git a/docs/main.dox b/docs/main.dox index 7aa1d45c..e5caae0d 100644 --- a/docs/main.dox +++ b/docs/main.dox @@ -8,8 +8,8 @@ __GLFW__ is a free, Open Source, multi-platform library for creating windows with OpenGL or OpenGL ES contexts and receiving many kinds of input. It is easy to integrate into existing applications and does not lay claim to the main loop. -This is the documentation for version 3.1, which adds many -[new features](@ref news_31). +See @ref news_31 for release highlights or the +[version history](http://www.glfw.org/changelog.html) for details. @ref quick is a guide for those new to GLFW. It takes you through how to write a small but complete program. For people coming from GLFW 2, the @ref moving @@ -24,13 +24,18 @@ There are guides for each of the various areas of the API. - @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. +Once you have written a program, see the @ref compile and @ref build guides. The [reference documentation](modules.html) provides more detailed information about specific functions. -Once you have written a program, see the @ref compile and @ref build guides. +There is a section on @ref guarantees_limitations for pointer lifetimes, +reentrancy, thread safety, event order and backward and forward compatibility. + +The @ref rift fills in the gaps for how to use LibOVR with GLFW. + +The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the +design, implementation and use of GLFW. Finally, the @ref compat guide explains what APIs, standards and protocols GLFW uses and what happens when they are not present on a given machine. diff --git a/docs/monitor.dox b/docs/monitor.dox index 1773d45b..8a5c5d90 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -13,7 +13,7 @@ guides for the other areas of GLFW. - @ref input -@section monitor_objects Monitor objects +@section monitor_object Monitor objects A monitor object represents a currently connected monitor and is represented as a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type diff --git a/docs/moving.dox b/docs/moving.dox index 902aa7d1..0e7ed5e3 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -147,10 +147,10 @@ into [window hints](@ref window_hints), but as they have been given @subsection moving_autopoll Removal of automatic event polling -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 -__glfwWaitEvents__ process events for all windows at once. +GLFW 3 does not automatically poll for events in @ref glfwSwapBuffers, meaning +you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. Unlike +buffer swap, which acts on a single window, the event processing functions act +on all windows at once. @par Old basic main loop @code diff --git a/docs/news.dox b/docs/news.dox index 664b89b1..8ae36aa1 100644 --- a/docs/news.dox +++ b/docs/news.dox @@ -2,7 +2,7 @@ @page news New features -@section news_31 New features in version 3.1 +@section news_31 New features in 3.1 These are the release highlights. For a full list of changes see the [version history](http://www.glfw.org/changelog.html). @@ -10,15 +10,20 @@ These are the release highlights. For a full list of changes see the @subsection news_31_cursor Custom mouse cursor images -GLFW now supports creating and setting both custom and standard system cursors. -They can be created with @ref glfwCreateCursor or @ref glfwCreateStandardCursor, -set with @ref glfwSetCursor and destroyed with @ref glfwDestroyCursor. +GLFW now supports creating and setting both custom cursor images and standard +cursor shapes. They are created with @ref glfwCreateCursor or @ref +glfwCreateStandardCursor, set with @ref glfwSetCursor and destroyed with @ref +glfwDestroyCursor. + +@see @ref cursor_object -@subsection news_31_drop File drop event +@subsection news_31_drop Path drop event -GLFW now provides a callback for receiving the paths of files dropped onto GLFW -windows. The callback is set with @ref glfwSetDropCallback. +GLFW now provides a callback for receiving the paths of files and directories +dropped onto GLFW windows. The callback is set with @ref glfwSetDropCallback. + +@see @ref path_drop @subsection news_31_emptyevent Main thread wake-up @@ -27,19 +32,23 @@ GLFW now provides the @ref glfwPostEmptyEvent function for posting an empty event from another thread to the main thread event queue, causing @ref glfwWaitEvents to return. +@see @ref events + @subsection news_31_framesize Window frame size query GLFW now supports querying the size, on each side, of the frame around the client area of a window, with @ref glfwGetWindowFrameSize. +@see [Window size](@ref window_size) + @subsection news_31_autoiconify Simultaneous multi-monitor rendering GLFW now supports disabling auto-iconification of full screen windows with the [GLFW_AUTO_ICONIFY](@ref window_hints_wnd) window hint. This is intended for people building multi-monitor installations, where you need windows to stay -in full screen despite losing focus. +in full screen despite losing input focus. @subsection news_31_floating Floating windows @@ -56,8 +65,8 @@ creation, with the [GLFW_FOCUSED](@ref window_hints_wnd) window hint. @subsection news_31_direct Direct access for window attributes and cursor position -GLFW now queries the window focus, visibility and iconification attributes and -the cursor position directly instead of returning cached data. +GLFW now queries the window input focus, visibility and iconification attributes +and the cursor position directly instead of returning cached data. @subsection news_31_libovr Better interoperability with Oculus Rift @@ -74,6 +83,8 @@ callback is set with @ref glfwSetCharModsCallback. Unlike the regular character callback, this will report character events that will not result in a character being input, for example if the Control key is held down. +@see @ref input_char + @subsection news_31_single Single buffered framebuffers @@ -109,7 +120,7 @@ GLFW now has an _experimental_ Mir display server backend that can be selected on Linux with a CMake option. -@section news_30 New features in version 3.0 +@section news_30 New features in 3.0 These are the release highlights. For a full list of changes see the [version history](http://www.glfw.org/changelog.html). diff --git a/docs/quick.dox b/docs/quick.dox index 28336fc7..12283a15 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -59,8 +59,8 @@ inclusion of the GLFW header. @subsection quick_init_term Initializing and terminating GLFW Before you can use most GLFW functions, the library must be initialized. On -successful initialization, non-zero is returned. If an error occurred, zero is -returned. +successful initialization, `GL_TRUE` is returned. If an error occurred, +`GL_FALSE` is returned. @code if (!glfwInit()) diff --git a/docs/rift.dox b/docs/rift.dox index 9e49772d..edf206f7 100644 --- a/docs/rift.dox +++ b/docs/rift.dox @@ -8,7 +8,7 @@ This guide is intended to fill in the gaps between the [Oculus PC SDK documentation](https://developer.oculus.com/documentation/) and the rest of the GLFW documentation and is not a replacement for either. It requires you to use [native access](@ref native) and assumes a certain level of -proficiency with LibOVR, OS specific APIs and your chosen development +proficiency with LibOVR, platform specific APIs and your chosen development environment. While GLFW has no explicit support for LibOVR, it is tested with and tries to @@ -16,14 +16,15 @@ interoperate well with it. @note Because of the speed of development of the Oculus SDK, this guide may become outdated before the next release. If this is a local copy of the -documentation, check the GLFW website for an up-to-date version. +documentation, you may want to check the GLFW website for updates. This +revision of the guide is written against version 0.4.4 of the SDK. @section rift_include Including the LibOVR and GLFW header files Both the OpenGL LibOVR header and the GLFW native header need macros telling them what OS you are building for. Because LibOVR only supports three major -desktop OSes, this can be solved with canonical predefined macros. +desktop platforms, this can be solved with canonical predefined macros. @code #if defined(_WIN32) @@ -110,7 +111,11 @@ On OS X, the native display ID of a GLFW monitor corresponds to the display ID of the detected HMD, as stored in the `DisplayId` member of `ovrHmdDesc`. At the time of writing (January 2015), the Oculus SDK does not support detecting -which monitor corresponds to the HMD in any sane fashion. +which monitor corresponds to the HMD in any sane fashion, but as long as the HMD +is set up and rotated properly it can be found via the screen position and +resolution provided by LibOVR. This method may instead find another monitor +that is mirroring the HMD, but this only matters if you intend to change its +video mode. @code int i, count; @@ -125,6 +130,17 @@ for (i = 0; i < count; i++) if (glfwGetCocoaMonitor(monitors[i]) == hmd->DisplayId) return monitors[i]; #elif defined(__linux__) + int xpos, ypos; + const GLFWvidmode* mode = glfwGetVideoMode(monitors[i]); + glfwGetMonitorPos(monitors[i], &xpos, &ypos); + + if (hmd->WindowsPos.x == xpos && + hmd->WindowsPos.y == ypos && + hmd->Resolution.w == mode->width && + hmd->Resolution.h == mode->height) + { + return monitors[i]; + } #endif } @endcode @@ -145,14 +161,16 @@ all monitors in the mirroring set will get the new video mode. @section rift_render Rendering to the HMD -Once the window and context is created, you can render to it the same as any -other application using LibOVR. +@subsection rift_render_sdk SDK distortion rendering If you wish to use SDK distortion rendering you will need some information from GLFW to configure the renderer. Below are the parts of the `ovrGLConfig` union that need to be filled with from GLFW. Note that there are other fields that also need to be filled for `ovrHmd_ConfigureRendering` to succeed. +Before configuring SDK distortion rendering you should make your context +current. + @code int width, height; union ovrGLConfig config; @@ -169,7 +187,13 @@ also need to be filled for `ovrHmd_ConfigureRendering` to succeed. #endif @endcode -When using SDK distortion rendering you should not call @ref glfwSwapBuffers, -as the HMD is updated by `ovrHmd_EndFrame`. +When using SDK distortion rendering you should not swap the buffers yourself, as +the HMD is updated by `ovrHmd_EndFrame`. + + +@subsection rift_render_custom Client distortion rendering + +With client distortion rendering you are in full control of the contents of the +HMD and should render and swap the buffers normally. */ diff --git a/docs/spaces.svg b/docs/spaces.svg index c0b872e1..562fa8be 100644 --- a/docs/spaces.svg +++ b/docs/spaces.svg @@ -38,11 +38,11 @@ borderopacity="1.0" inkscape:pageopacity="0.0" inkscape:pageshadow="2" - inkscape:zoom="8" - inkscape:cx="273.7909" - inkscape:cy="186.31212" + inkscape:zoom="2.5611424" + inkscape:cx="344.24359" + inkscape:cy="163.9911" inkscape:document-units="px" - inkscape:current-layer="layer1" + inkscape:current-layer="svg2" showgrid="false" inkscape:window-width="1920" inkscape:window-height="1021" @@ -64,7 +64,7 @@ image/svg+xml - + @@ -103,63 +103,282 @@ inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png" inkscape:export-xdpi="109.89113" inkscape:export-ydpi="109.89113" /> - Primary monitor position - + + + + + + + + + + + + + + + + + + + + + + + + Secondary Monitor - + + + + + + + + + + + + + + + + + + Primary Monitor - + + + + + + + + + + + + + + + + Virtual Screen + id="text3781"> + + + + + + + + + + + + + + - Window + id="text3791"> + + + + + + + - + Window position - + + + + + + + + + + + + + + + Secondary monitor position - + + + + + + + + + + + + + + + + + + + + + + + + + + Client area origin - + + + + + + + + + + + + + + + + + + Virtual screen origin + id="text3017"> + + + + + + + + + + + + + + + + + + + + - Window Title + id="text4495"> + + + + + + + + + + + + diff --git a/docs/window.dox b/docs/window.dox index 4cb1250e..9aae404e 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -16,8 +16,8 @@ guides for the other areas of GLFW. @section window_object Window objects The @ref GLFWwindow object encapsulates both a window and a context. They are -created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or -@ref glfwTerminate, if any remain). As the window and context are inseparably +created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow, or +@ref glfwTerminate, if any remain. As the window and context are inseparably linked, the object pointer is used as both a context and window handle. To see the event stream provided to the various window related callbacks, run @@ -58,7 +58,7 @@ or decorations. Each field of the @ref GLFWvidmode structure corresponds to a function parameter or window hint and combine to form the _desired video mode_ for that window. 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 +set for the chosen monitor as long as the window has input focus. For more information about retrieving video modes, see @ref monitor_modes. Video mode field | Corresponds to @@ -168,8 +168,8 @@ focus when created. This hint is ignored for full screen and initially hidden windows. `GLFW_AUTO_ICONIFY` specifies whether the (full screen) window will -automatically iconify and restore the previous video mode on focus loss. This -hint is ignored for windowed mode windows. +automatically iconify and restore the previous video mode on input focus loss. +This hint is ignored for windowed mode windows. `GLFW_FLOATING` specifies whether the window will be floating above other regular windows, also called topmost or always-on-top. This is intended @@ -332,7 +332,7 @@ Window hint | Default value | Supported values @section window_events Window event processing -See @ref input_event in the @ref input. +See @ref events. @section window_properties Window properties and events @@ -347,7 +347,7 @@ the life-time of the window. The initial value of the pointer is `NULL`. -@subsection window_close Closing and close flag +@subsection window_close Window 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. @@ -388,7 +388,7 @@ void window_close_callback(GLFWwindow* window) @endcode -@subsection window_size Size +@subsection window_size Window size The size of a window can be changed with @ref glfwSetWindowSize. For windowed mode windows, this sets the size, in @@ -485,7 +485,7 @@ The size of a framebuffer may change independently of the size of a window, for example if the window is dragged between a regular monitor and a high-DPI one. -@subsection window_pos Position +@subsection window_pos Window position The position of a windowed-mode window can be changed with @ref glfwSetWindowPos. This moves the window so that the upper-left corner of its @@ -521,7 +521,7 @@ glfwGetWindowPos(window, &xpos, &ypos); @endcode -@subsection window_title Title +@subsection window_title Window title All GLFW windows have a title, although undecorated or full screen windows may not display it or only display it in a task bar or similar interface. You can @@ -542,7 +542,7 @@ glfwSetWindowTitle(window, "ヒカルの碁"); @endcode -@subsection window_monitor Monitor +@subsection window_monitor Window monitor Full screen windows are associated with a specific monitor. You can get the handle for this monitor with @ref glfwGetWindowMonitor. @@ -557,7 +557,7 @@ For windowed mode windows, this function returns `NULL`. This is the recommended way to tell full screen windows from windowed mode windows. -@subsection window_iconify Iconification +@subsection window_iconify Window iconification Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow. @@ -607,7 +607,7 @@ int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED); @endcode -@subsection window_hide Visibility +@subsection window_hide Window visibility Windowed mode windows can be hidden with @ref glfwHideWindow. @@ -638,39 +638,39 @@ int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE); @endcode -@subsection window_focus Input focus +@subsection window_focus Window input focus -If you wish to be notified when a window gains or loses focus, whether by +If you wish to be notified when a window gains or loses input focus, whether by the user, system or your own code, set a focus callback. @code glfwSetWindowFocusCallback(window, window_focus_callback); @endcode -The callback function receives changes in the focus state of the window. +The callback function receives changes in the input focus state of the window. @code void window_focus_callback(GLFWwindow* window, int focused) { if (focused) { - // The window gained focus + // The window gained input focus } else { - // The window lost focus + // The window lost input focus } } @endcode -You can also get the current focus state with @ref glfwGetWindowAttrib. +You can also get the current input focus state with @ref glfwGetWindowAttrib. @code int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED); @endcode -@subsection window_refresh Damage and refresh +@subsection window_refresh Window 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. @@ -695,7 +695,7 @@ window contents are saved off-screen, this callback might only be called when the window or framebuffer is resized. -@subsection window_attribs Attributes +@subsection window_attribs Window attributes Windows have a number of attributes that can be returned using @ref glfwGetWindowAttrib. Some reflect state that may change during the lifetime of @@ -711,11 +711,11 @@ if (glfwGetWindowAttrib(window, GLFW_FOCUSED)) @endcode -@subsubsection window_attribs_window Window related attributes +@subsubsection window_attribs_wnd Window related attributes `GLFW_FOCUSED` indicates whether the specified window has input focus. Initial -focus is controlled by the [window hint](@ref window_hints_wnd) with the same -name. +input focus is controlled by the [window hint](@ref window_hints_wnd) with the +same name. `GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by the user or with @ref glfwIconifyWindow. @@ -738,7 +738,7 @@ topmost or always-on-top. This is controlled by the [window hint](@ref window_hints_wnd) with the same name. -@subsubsection window_attribs_context Context related attributes +@subsubsection window_attribs_ctx Context related attributes `GLFW_CLIENT_API` indicates the client API provided by the window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`. @@ -764,7 +764,7 @@ This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION` if the window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise. -@section window_swap Buffer swapping +@section buffer_swap Buffer swapping GLFW windows are by default double buffered. That means that you have two rendering buffers; a front buffer and a back buffer. The front buffer is diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index c9c41973..89414491 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -279,20 +279,22 @@ extern "C" { /*! @defgroup keys Keyboard keys * - * 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). + * See [key input](@ref input_key) for how these are used. * - * The naming of the key codes follow these rules: - * - The US keyboard layout is used - * - Names of printable alpha-numeric characters are used (e.g. "A", "R", - * "3", etc.) - * - For non-alphanumeric characters, Unicode:ish names are used (e.g. - * "COMMA", "LEFT_SQUARE_BRACKET", etc.). Note that some names do not - * correspond to the Unicode standard (usually for brevity) - * - Keys that lack a clear US mapping are named "WORLD_x" - * - For non-printable keys, custom names are used (e.g. "F4", - * "BACKSPACE", etc.) + * 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). + * + * The naming of the key codes follow these rules: + * - The US keyboard layout is used + * - Names of printable alpha-numeric characters are used (e.g. "A", "R", + * "3", etc.) + * - For non-alphanumeric characters, Unicode:ish names are used (e.g. + * "COMMA", "LEFT_SQUARE_BRACKET", etc.). Note that some names do not + * correspond to the Unicode standard (usually for brevity) + * - Keys that lack a clear US mapping are named "WORLD_x" + * - For non-printable keys, custom names are used (e.g. "F4", + * "BACKSPACE", etc.) * * @ingroup input * @{ @@ -429,6 +431,9 @@ extern "C" { /*! @} */ /*! @defgroup mods Modifier key flags + * + * See [key input](@ref input_key) for how these are used. + * * @ingroup input * @{ */ @@ -448,6 +453,9 @@ extern "C" { /*! @} */ /*! @defgroup buttons Mouse buttons + * + * See [mouse button input](@ref input_mouse_button) for how these are used. + * * @ingroup input * @{ */ #define GLFW_MOUSE_BUTTON_1 0 @@ -465,6 +473,9 @@ extern "C" { /*! @} */ /*! @defgroup joysticks Joysticks + * + * See [joystick input](@ref joystick) for how these are used. + * * @ingroup input * @{ */ #define GLFW_JOYSTICK_1 0 @@ -487,6 +498,9 @@ extern "C" { /*! @} */ /*! @defgroup errors Error codes + * + * See [error handling](@ref error_handling) for how these are used. + * * @ingroup init * @{ */ /*! @brief GLFW has not been initialized. @@ -669,6 +683,9 @@ extern "C" { #define GLFW_RELEASE_BEHAVIOR_NONE 0x00035002 /*! @defgroup shapes Standard cursor shapes + * + * See [standard cursor creation](@ref cursor_standard) for how these are used. + * * @ingroup input * @{ */ @@ -818,9 +835,9 @@ typedef void (* GLFWwindowrefreshfun)(GLFWwindow*); * * This is the function signature for window focus callback functions. * - * @param[in] window The window that was focused or defocused. - * @param[in] focused `GL_TRUE` if the window was focused, or `GL_FALSE` if - * it was defocused. + * @param[in] window The window that gained or lost input focus. + * @param[in] focused `GL_TRUE` if the window was given input focus, or + * `GL_FALSE` if it lost it. * * @sa glfwSetWindowFocusCallback * @@ -1097,8 +1114,7 @@ typedef struct GLFWimage * @sa @ref intro_init * @sa glfwTerminate * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @ingroup init */ @@ -1130,8 +1146,7 @@ GLFWAPI int glfwInit(void); * @sa @ref intro_init * @sa glfwInit * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @ingroup init */ @@ -1158,8 +1173,7 @@ GLFWAPI void glfwTerminate(void); * @sa @ref intro_version * @sa glfwGetVersionString * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @ingroup init */ @@ -1191,8 +1205,7 @@ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); * @sa @ref intro_version * @sa glfwGetVersion * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup init */ @@ -1225,8 +1238,7 @@ GLFWAPI const char* glfwGetVersionString(void); * * @sa @ref error_handling * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup init */ @@ -1254,8 +1266,7 @@ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun); * @sa @ref monitor_event * @sa glfwGetPrimaryMonitor * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup monitor */ @@ -1275,8 +1286,7 @@ GLFWAPI GLFWmonitor** glfwGetMonitors(int* count); * @sa @ref monitor_monitors * @sa glfwGetMonitors * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup monitor */ @@ -1299,8 +1309,7 @@ GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void); * * @sa @ref monitor_properties * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup monitor */ @@ -1311,6 +1320,11 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); * This function returns the size, in millimetres, of the display area of the * specified monitor. * + * Some systems do not provide accurate monitor size information, either + * because the monitor + * [EDID](https://en.wikipedia.org/wiki/Extended_display_identification_data) + * data is incorrect or because the driver does not report it accurately. + * * Any or all of the size arguments may be `NULL`. If an error occurs, all * non-`NULL` size arguments will be set to zero. * @@ -1320,17 +1334,15 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); * @param[out] heightMM Where to store the height, in millimetres, of the * monitor's display area, or `NULL`. * - * @note Some systems do not provide accurate monitor size information, either - * because the EDID data is incorrect, or because the driver does not report it - * accurately. + * @remarks __Windows:__ The OS calculates the returned physical size from the + * current resolution and system DPI instead of querying the monitor EDID data. * * @par Thread Safety * This function may only be called from the main thread. * * @sa @ref monitor_properties * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup monitor */ @@ -1356,8 +1368,7 @@ GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int* * * @sa @ref monitor_properties * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup monitor */ @@ -1382,8 +1393,7 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); * * @sa @ref monitor_event * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup monitor */ @@ -1413,8 +1423,7 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun); * @sa @ref monitor_modes * @sa glfwGetVideoMode * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Changed to return an array of modes for a specific monitor. @@ -1444,8 +1453,7 @@ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count); * @sa @ref monitor_modes * @sa glfwGetVideoModes * - * @par History - * Added in GLFW 3.0. Replaces `glfwGetDesktopMode`. + * @since Added in GLFW 3.0. Replaces `glfwGetDesktopMode`. * * @ingroup monitor */ @@ -1464,8 +1472,7 @@ GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor); * * @sa @ref monitor_gamma * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup monitor */ @@ -1490,8 +1497,7 @@ GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma); * * @sa @ref monitor_gamma * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup monitor */ @@ -1516,8 +1522,7 @@ GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor); * * @sa @ref monitor_gamma * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup monitor */ @@ -1534,8 +1539,7 @@ GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp); * @sa @ref window_hints * @sa glfwWindowHint * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -1557,8 +1561,7 @@ GLFWAPI void glfwDefaultWindowHints(void); * @sa @ref window_hints * @sa glfwDefaultWindowHints * - * @par History - * Added in GLFW 3.0. Replaces `glfwOpenWindowHint`. + * @since Added in GLFW 3.0. Replaces `glfwOpenWindowHint`. * * @ingroup window */ @@ -1601,14 +1604,14 @@ GLFWAPI void glfwWindowHint(int target, int hint); * hint, set its [position](@ref window_pos) and then [show](@ref window_hide) * it. * - * If a full screen window is focused, the screensaver is prohibited from + * If a full screen window has input focus, 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 [size](@ref window_size) after creation. * - * The [swap interval](@ref window_swap) is not set during window creation and + * The [swap interval](@ref buffer_swap) is not set during window creation and * the initial value may vary depending on driver settings and defaults. * * @param[in] width The desired width, in screen coordinates, of the window. @@ -1659,8 +1662,7 @@ GLFWAPI void glfwWindowHint(int target, int hint); * @sa @ref window_creation * @sa glfwDestroyWindow * - * @par History - * Added in GLFW 3.0. Replaces `glfwOpenWindow`. + * @since Added in GLFW 3.0. Replaces `glfwOpenWindow`. * * @ingroup window */ @@ -1688,8 +1690,7 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G * @sa @ref window_creation * @sa glfwCreateWindow * - * @par History - * Added in GLFW 3.0. Replaces `glfwCloseWindow`. + * @since Added in GLFW 3.0. Replaces `glfwCloseWindow`. * * @ingroup window */ @@ -1707,8 +1708,7 @@ GLFWAPI void glfwDestroyWindow(GLFWwindow* window); * * @sa @ref window_close * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -1728,8 +1728,7 @@ GLFWAPI int glfwWindowShouldClose(GLFWwindow* window); * * @sa @ref window_close * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -1748,8 +1747,7 @@ GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value); * * @sa @ref window_title * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. @@ -1778,8 +1776,7 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); * @sa @ref window_pos * @sa glfwSetWindowPos * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -1807,8 +1804,7 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); * @sa @ref window_pos * @sa glfwGetWindowPos * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. @@ -1838,8 +1834,7 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); * @sa @ref window_size * @sa glfwSetWindowSize * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. @@ -1871,8 +1866,7 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); * @sa @ref window_size * @sa glfwGetWindowSize * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. @@ -1902,8 +1896,7 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); * @sa @ref window_fbsize * @sa glfwSetFramebufferSizeCallback * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -1938,8 +1931,7 @@ GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height) * * @sa @ref window_size * - * @par History - * Added in GLFW 3.1. + * @since Added in GLFW 3.1. * * @ingroup window */ @@ -1962,8 +1954,7 @@ GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int * @sa @ref window_iconify * @sa glfwRestoreWindow * - * @par History - * Added in GLFW 2.1. + * @since Added in GLFW 2.1. * * @par * __GLFW 3:__ Added window handle parameter. @@ -1988,8 +1979,7 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window); * @sa @ref window_iconify * @sa glfwIconifyWindow * - * @par History - * Added in GLFW 2.1. + * @since Added in GLFW 2.1. * * @par * __GLFW 3:__ Added window handle parameter. @@ -2012,8 +2002,7 @@ GLFWAPI void glfwRestoreWindow(GLFWwindow* window); * @sa @ref window_hide * @sa glfwHideWindow * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -2033,8 +2022,7 @@ GLFWAPI void glfwShowWindow(GLFWwindow* window); * @sa @ref window_hide * @sa glfwShowWindow * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -2054,8 +2042,7 @@ GLFWAPI void glfwHideWindow(GLFWwindow* window); * * @sa @ref window_monitor * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -2077,8 +2064,8 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); * * @sa @ref window_attribs * - * @par History - * Added in GLFW 3.0. Replaces `glfwGetWindowParam` and `glfwGetGLVersion`. + * @since Added in GLFW 3.0. Replaces `glfwGetWindowParam` and + * `glfwGetGLVersion`. * * @ingroup window */ @@ -2099,8 +2086,7 @@ GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib); * @sa @ref window_userptr * @sa glfwGetWindowUserPointer * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -2119,8 +2105,7 @@ GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer); * @sa @ref window_userptr * @sa glfwSetWindowUserPointer * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -2143,8 +2128,7 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); * * @sa @ref window_pos * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -2167,8 +2151,7 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow * * @sa @ref window_size * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. Updated callback signature. @@ -2202,8 +2185,7 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind * * @sa @ref window_close * - * @par History - * Added in GLFW 2.5. + * @since Added in GLFW 2.5. * * @par * __GLFW 3:__ Added window handle parameter. Updated callback signature. @@ -2233,8 +2215,7 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi * * @sa @ref window_refresh * - * @par History - * Added in GLFW 2.5. + * @since Added in GLFW 2.5. * * @par * __GLFW 3:__ Added window handle parameter. Updated callback signature. @@ -2246,12 +2227,12 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL /*! @brief Sets the focus callback for the specified window. * * This function sets the focus callback of the specified window, which is - * called when the window gains or loses focus. + * called when the window gains or loses input focus. * - * After the focus callback is called for a window that lost focus, synthetic - * key and mouse button release events will be generated for all such that had - * been pressed. For more information, see @ref glfwSetKeyCallback and @ref - * glfwSetMouseButtonCallback. + * After the focus callback is called for a window that lost input focus, + * synthetic key and mouse button release events will be generated for all such + * that had been pressed. For more information, see @ref glfwSetKeyCallback + * and @ref glfwSetMouseButtonCallback. * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set @@ -2264,8 +2245,7 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL * * @sa @ref window_focus * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -2287,8 +2267,7 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi * * @sa @ref window_iconify * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -2310,8 +2289,7 @@ GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GL * * @sa @ref window_fbsize * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup window */ @@ -2341,11 +2319,10 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_event + * @sa @ref events * @sa glfwWaitEvents * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @ingroup window */ @@ -2370,26 +2347,25 @@ GLFWAPI void glfwPollEvents(void); * [window refresh callback](@ref window_refresh) to redraw the contents of * your window when necessary during such operations. * + * On some platforms, certain callbacks may be called outside of a call to one + * of the event processing functions. + * * If no windows exist, this function returns immediately. For synchronization * of threads in applications that do not create windows, use your threading * library of choice. * * Event processing is not required for joystick input to work. * - * @note On some platforms, certain callbacks may be called outside of a call - * to one of the event processing functions. - * * @par Reentrancy * This function may not be called from a callback. * * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_event + * @sa @ref events * @sa glfwPollEvents * - * @par History - * Added in GLFW 2.5. + * @since Added in GLFW 2.5. * * @ingroup window */ @@ -2407,11 +2383,10 @@ GLFWAPI void glfwWaitEvents(void); * @par Thread Safety * This function may be called from any thread. * - * @sa @ref input_event + * @sa @ref events * @sa glfwWaitEvents * - * @par History - * Added in GLFW 3.1. + * @since Added in GLFW 3.1. * * @ingroup window */ @@ -2432,8 +2407,7 @@ GLFWAPI void glfwPostEmptyEvent(void); * * @sa glfwSetInputMode * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup input */ @@ -2449,9 +2423,7 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); * modes: * - `GLFW_CURSOR_NORMAL` makes the cursor visible and behaving normally. * - `GLFW_CURSOR_HIDDEN` makes the cursor invisible when it is over the client - * area of the window but does not restrict the cursor from leaving. This is - * useful if you wish to render your own cursor or have no visible cursor at - * all. + * area of the window but does not restrict the cursor from leaving. * - `GLFW_CURSOR_DISABLED` hides and grabs the cursor, providing virtual * and unlimited cursor movement. This is useful for implementing for * example 3D camera controls. @@ -2481,8 +2453,7 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); * * @sa glfwGetInputMode * - * @par History - * Added in GLFW 3.0. Replaces `glfwEnable` and `glfwDisable`. + * @since Added in GLFW 3.0. Replaces `glfwEnable` and `glfwDisable`. * * @ingroup input */ @@ -2517,8 +2488,7 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); * * @sa @ref input_key * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. @@ -2547,8 +2517,7 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key); * * @sa @ref input_mouse_button * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. @@ -2584,11 +2553,10 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_cursor_pos + * @sa @ref cursor_pos * @sa glfwSetCursorPos * - * @par History - * Added in GLFW 3.0. Replaces `glfwGetMousePos`. + * @since Added in GLFW 3.0. Replaces `glfwGetMousePos`. * * @ingroup input */ @@ -2599,8 +2567,8 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); * * This function sets the position, in screen coordinates, of the cursor * relative to the upper-left corner of the client area of the specified - * window. The window must be focused. If the window does not have focus when - * this function is called, it fails silently. + * window. The window must have input focus. If the window does not have + * input focus when this function is called, it fails silently. * * __Do not use this function__ to implement things like camera controls. GLFW * already provides the `GLFW_CURSOR_DISABLED` cursor mode that hides the @@ -2624,11 +2592,10 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_cursor_pos + * @sa @ref cursor_pos * @sa glfwGetCursorPos * - * @par History - * Added in GLFW 3.0. Replaces `glfwSetMousePos`. + * @since Added in GLFW 3.0. Replaces `glfwSetMousePos`. * * @ingroup input */ @@ -2636,19 +2603,23 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); /*! @brief Creates a custom cursor. * - * Creates a new cursor that can be made the system cursor for a window with - * @ref glfwSetCursor. The cursor can be destroyed with @ref - * glfwDestroyCursor. Any remaining cursors are destroyed by @ref - * glfwTerminate. + * Creates a new custom cursor image that can be set for a window with @ref + * glfwSetCursor. The cursor can be destroyed with @ref glfwDestroyCursor. + * Any remaining cursors are destroyed by @ref glfwTerminate. * - * The image data is 32-bit RGBA, i.e. eight bits per channel. The pixels are - * arranged canonically as sequential rows, starting from the top-left corner. + * The pixels are 32-bit little-endian RGBA, i.e. eight bits per channel. They + * are arranged canonically as packed sequential rows, starting from the + * top-left corner. + * + * The cursor hotspot is specified in pixels, relative to the upper-left corner + * of the cursor image. Like all other coordinate systems in GLFW, the X-axis + * points to the right and the Y-axis points down. * * @param[in] image The desired cursor image. - * @param[in] xhot The desired x-coordinate of the cursor hotspot. - * @param[in] yhot The desired y-coordinate of the cursor hotspot. + * @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot. + * @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot. * - * @return A new cursor ready to use or `NULL` if an + * @return The handle of the created cursor, or `NULL` if an * [error](@ref error_handling) occurred. * * @par Pointer Lifetime @@ -2660,12 +2631,11 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_cursor + * @sa @ref cursor_object * @sa glfwDestroyCursor * @sa glfwCreateStandardCursor * - * @par History - * Added in GLFW 3.1. + * @since Added in GLFW 3.1. * * @ingroup input */ @@ -2673,8 +2643,8 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot) /*! @brief Creates a cursor with a standard shape. * - * Returns a cursor with a [standard shape](@ref shapes), which can be made the - * system cursor for a window with @ref glfwSetCursor. + * Returns a cursor with a [standard shape](@ref shapes), that can be set for + * a window with @ref glfwSetCursor. * * @param[in] shape One of the [standard shapes](@ref shapes). * @@ -2687,11 +2657,10 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot) * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_cursor + * @sa @ref cursor_object * @sa glfwCreateCursor * - * @par History - * Added in GLFW 3.1. + * @since Added in GLFW 3.1. * * @ingroup input */ @@ -2711,31 +2680,35 @@ GLFWAPI GLFWcursor* glfwCreateStandardCursor(int shape); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_cursor + * @sa @ref cursor_object * @sa glfwCreateCursor * - * @par History - * Added in GLFW 3.1. + * @since Added in GLFW 3.1. * * @ingroup input */ GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor); -/*! @brief Sets the system cursor for a given window. +/*! @brief Sets the cursor for the window. * - * This function sets the system cursor for the specified window. + * This function sets the cursor image to be used when the cursor is over the + * client area of the specified window. The set cursor will only be visible + * when the [cursor mode](@ref cursor_mode) of the window is + * `GLFW_CURSOR_NORMAL`. * - * @param[in] window The window to set the system cursor for. - * @param[in] cursor The cursor to change to, or `NULL` to switch back - * to the default system cursor. + * On some platforms, the set cursor may not be visible unless the window also + * has input focus. + * + * @param[in] window The window to set the cursor for. + * @param[in] cursor The cursor to set, or `NULL` to switch back to the default + * arrow cursor. * * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_cursor + * @sa @ref cursor_object * - * @par History - * Added in GLFW 3.1. + * @since Added in GLFW 3.1. * * @ingroup input */ @@ -2751,10 +2724,11 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); * layout. If you want to input text, use the * [character callback](@ref glfwSetCharCallback) instead. * - * When a window loses focus, it will generate synthetic key release events - * for all pressed keys. You can tell these events from user-generated events - * by the fact that the synthetic ones are generated after the focus loss event - * has been processed, i.e. after the focus callback has been called. + * When a window loses input focus, it will generate synthetic key release + * events for all pressed keys. You can tell these events from user-generated + * events by the fact that the synthetic ones are generated after the focus + * loss event has been processed, i.e. after the + * [window focus callback](@ref glfwSetWindowFocusCallback) has been called. * * The scancode of a key is specific to that platform or sometimes even to that * machine. Scancodes are intended to allow users to bind keys that don't have @@ -2775,8 +2749,7 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); * * @sa @ref input_key * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. Updated callback signature. @@ -2815,8 +2788,7 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun); * * @sa @ref input_char * - * @par History - * Added in GLFW 2.4. + * @since Added in GLFW 2.4. * * @par * __GLFW 3:__ Added window handle parameter. Updated callback signature. @@ -2851,8 +2823,7 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun); * * @sa @ref input_char * - * @par History - * Added in GLFW 3.1. + * @since Added in GLFW 3.1. * * @ingroup input */ @@ -2863,11 +2834,11 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods * This function sets the mouse button callback of the specified window, which * is called when a mouse button is pressed or released. * - * When a window loses focus, it will generate synthetic mouse button release - * events for all pressed mouse buttons. You can tell these events from - * user-generated events by the fact that the synthetic ones are generated - * after the focus loss event has been processed, i.e. after the focus callback - * has been called. + * When a window loses input focus, it will generate synthetic mouse button + * release events for all pressed mouse buttons. You can tell these events + * from user-generated events by the fact that the synthetic ones are generated + * after the focus loss event has been processed, i.e. after the + * [window focus callback](@ref glfwSetWindowFocusCallback) has been called. * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set @@ -2880,8 +2851,7 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods * * @sa @ref input_mouse_button * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. Updated callback signature. @@ -2906,10 +2876,9 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_cursor_pos + * @sa @ref cursor_pos * - * @par History - * Added in GLFW 3.0. Replaces `glfwSetMousePosCallback`. + * @since Added in GLFW 3.0. Replaces `glfwSetMousePosCallback`. * * @ingroup input */ @@ -2930,10 +2899,9 @@ GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursor * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_cursor_enter + * @sa @ref cursor_enter * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup input */ @@ -2957,10 +2925,9 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_scroll + * @sa @ref scrolling * - * @par History - * Added in GLFW 3.0. Replaces `glfwSetMouseWheelCallback`. + * @since Added in GLFW 3.0. Replaces `glfwSetMouseWheelCallback`. * * @ingroup input */ @@ -2985,10 +2952,9 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_drop + * @sa @ref path_drop * - * @par History - * Added in GLFW 3.1. + * @since Added in GLFW 3.1. * * @ingroup input */ @@ -3004,10 +2970,9 @@ GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_joy + * @sa @ref joystick * - * @par History - * Added in GLFW 3.0. Replaces `glfwGetJoystickParam`. + * @since Added in GLFW 3.0. Replaces `glfwGetJoystickParam`. * * @ingroup input */ @@ -3031,10 +2996,9 @@ GLFWAPI int glfwJoystickPresent(int joy); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_joy_axis + * @sa @ref joystick_axis * - * @par History - * Added in GLFW 3.0. Replaces `glfwGetJoystickPos`. + * @since Added in GLFW 3.0. Replaces `glfwGetJoystickPos`. * * @ingroup input */ @@ -3058,10 +3022,9 @@ GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_joy_button + * @sa @ref joystick_button * - * @par History - * Added in GLFW 2.2. + * @since Added in GLFW 2.2. * * @par * __GLFW 3:__ Changed to return a dynamic array. @@ -3088,10 +3051,9 @@ GLFWAPI const unsigned char* glfwGetJoystickButtons(int joy, int* count); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_joy_name + * @sa @ref joystick_name * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup input */ @@ -3111,11 +3073,10 @@ GLFWAPI const char* glfwGetJoystickName(int joy); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_clipboard + * @sa @ref clipboard * @sa glfwGetClipboardString * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup input */ @@ -3139,11 +3100,10 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_clipboard + * @sa @ref clipboard * @sa glfwSetClipboardString * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup input */ @@ -3165,10 +3125,9 @@ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); * @par Thread Safety * This function may be called from any thread. Access is not synchronized. * - * @sa @ref input_time + * @sa @ref time * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @ingroup input */ @@ -3184,10 +3143,9 @@ GLFWAPI double glfwGetTime(void); * @par Thread Safety * This function may only be called from the main thread. * - * @sa @ref input_time + * @sa @ref time * - * @par History - * Added in GLFW 2.2. + * @since Added in GLFW 2.2. * * @ingroup input */ @@ -3215,8 +3173,7 @@ GLFWAPI void glfwSetTime(double time); * @sa @ref context_current * @sa glfwGetCurrentContext * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup context */ @@ -3236,8 +3193,7 @@ GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window); * @sa @ref context_current * @sa glfwMakeContextCurrent * - * @par History - * Added in GLFW 3.0. + * @since Added in GLFW 3.0. * * @ingroup context */ @@ -3254,11 +3210,10 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void); * @par Thread Safety * This function may be called from any thread. * - * @sa @ref window_swap + * @sa @ref buffer_swap * @sa glfwSwapInterval * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @par * __GLFW 3:__ Added window handle parameter. @@ -3300,11 +3255,10 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window); * @par Thread Safety * This function may be called from any thread. * - * @sa @ref window_swap + * @sa @ref buffer_swap * @sa glfwSwapBuffers * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @ingroup context */ @@ -3334,8 +3288,7 @@ GLFWAPI void glfwSwapInterval(int interval); * @sa @ref context_glext * @sa glfwGetProcAddress * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @ingroup context */ @@ -3368,8 +3321,7 @@ GLFWAPI int glfwExtensionSupported(const char* extension); * @sa @ref context_glext * @sa glfwExtensionSupported * - * @par History - * Added in GLFW 1.0. + * @since Added in GLFW 1.0. * * @ingroup context */