From 1f5f20eeef18b71bc2a8bd8859ec5081bd35c073 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Mon, 27 May 2013 17:10:34 +0200 Subject: [PATCH] Documentation work. --- docs/{glext.dox => context.dox} | 78 +++++++-- docs/monitor.dox | 31 ++++ docs/moving.dox | 20 +++ docs/news.dox | 5 + docs/window.dox | 294 +++++++++++++++++++++++++++----- include/GLFW/glfw3.h | 53 +----- 6 files changed, 383 insertions(+), 98 deletions(-) rename docs/{glext.dox => context.dox} (61%) create mode 100644 docs/monitor.dox diff --git a/docs/glext.dox b/docs/context.dox similarity index 61% rename from docs/glext.dox rename to docs/context.dox index 52021bb8..56d1de76 100644 --- a/docs/glext.dox +++ b/docs/context.dox @@ -1,6 +1,57 @@ /*! -@page glext OpenGL extension handling +@page context Context handling guide + +@tableofcontents + +The primary purpose of GLFW is to provide a simple interface to window +management and OpenGL and OpenGL ES context creation. GLFW supports +multiple windows, each of which has its own context. + + +@section context_object Context handles + +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 +linked, the object pointer is used as both a context and window handle. + + +@section context_hints Context creation hints + +There are a number of hints, specified using @ref glfwWindowHint, related to +what kind of context is created. See +[context related hints](@ref window_hints_ctx) in the window handling guide. + + +@section context_current Current context + +Before you can use the OpenGL or OpenGL ES APIs, you need to have a current +context of the proper type. The context encapsulates all render state and all +objects like textures and shaders. + +Note that a context can only be current for a single thread at a time, and +a thread can only have a single context at a time. + +A context is made current with @ref glfwMakeContextCurrent. + +@code +glfwMakeContextCurrent(window); +@endcode + +The current context is returned by @ref glfwGetCurrentContext. + +@code +GLFWwindow* window = glfwGetCurrentContext(); +@endcode + + +@section context_swap Swapping buffers + +See [swapping buffers](@ref window_swap) in the window handling guide. + + +@section context_glext OpenGL extension handling One of the benefits of OpenGL is its extensibility. Independent hardware vendors (IHVs) may include functionality in their OpenGL implementations that @@ -16,10 +67,9 @@ An extension is defined by: Note the `ARB` affix, which stands for Architecture Review Board and is used for official extensions. There are many different affixes, depending on who wrote the extension. A list of extensions, together with their specifications, -can be found at the -[OpenGL Registry](http://www.opengl.org/registry/). +can be found at the [OpenGL Registry](http://www.opengl.org/registry/). -To use a certain extension, you must first check whether the context exposes +To use a certain extension, you must first check whether the context supports that extension and then, if it introduces new functions, retrieve the pointers to those functions. @@ -31,7 +81,7 @@ the OpenGL API. GLEW in particular has been extensively tested with and works well with GLFW. -@section glext_header The glext.h header +@subsection context_glext_header The glext.h header The `glext.h` header is a continually updated file that defines the interfaces for all OpenGL extensions. The latest version of this can always be found at @@ -42,30 +92,30 @@ you wish to use. The header defines function pointer types for all functions of all extensions it supports. These have names like `PFNGLGETDEBUGMESSAGELOGARB` (for -`glGetDebugMessageLogARB`), i.e. the name is made uppercase, the `gl` prefix is -removed and `PFN` and `PROC` are added to the ends. +`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` and `PROC` +are added to the ends. -@section glext_string Checking for extensions +@subsection context_glext_string Checking for extensions A given machine may not actually support the extension (it may have older drivers or a graphics card that lacks the necessary hardware features), so it -is necessary to check whether the context exposes the extension. This is done +is necessary to check whether the context supports the extension. This is done with @ref glfwExtensionSupported. @code if (glfwExtensionSupported("GL_ARB_debug_output")) { - // The extension is exposed by the current context + // The extension is supported by the current context } @endcode The argument is a null terminated ASCII string with the extension name. If the -extension is exposed, @ref glfwExtensionSupported returns non-zero, otherwise it -returns zero. +extension is supported, @ref glfwExtensionSupported returns non-zero, otherwise +it returns zero. -@section glext_proc Fetching function pointers +@subsection context_glext_proc Fetching function pointers Many extensions, though not all, require the use of new OpenGL functions. These entry points are often not exposed by your link libraries, making @@ -89,7 +139,7 @@ when used together. #define glGetDebugMessageLogARB pfnGetDebugMessageLog PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog; -// Flag indicating whether the extension is present +// Flag indicating whether the extension is supported int has_debug_output = 0; void load_extensions(void) diff --git a/docs/monitor.dox b/docs/monitor.dox new file mode 100644 index 00000000..e6e3dc81 --- /dev/null +++ b/docs/monitor.dox @@ -0,0 +1,31 @@ +/*! + +@page monitor Multi-monitor guide + +@section monitor_objects Monitor objects + + +@section monitor_modes Querying video modes + +Although GLFW generally does a good job at selecting a suitable video +mode for you when you open a fullscreen window, it is sometimes useful to +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 glfwGetVideoModes. + +@code +int count; +GLFWvidmode* modes = glfwGetVideoModes(monitor, &count); +@endcode + +To get the current video mode of a monitor call @ref glfwGetVideoMode. + +@code +const GLFWvidmode* mode = glfwGetVideoMode(monitor); +@endcode + + +@section monitor_gamma Gamma ramps + +*/ diff --git a/docs/moving.dox b/docs/moving.dox index 6ce4443d..ad1a7a00 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -188,6 +188,15 @@ glfwMakeContextCurrent after creating a window before you can call any OpenGL functions. +@subsection moving_repeat Key repeat + +The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled +for both keys and characters. A new key action, `GLFW_REPEAT`, has been added +to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press +from a repeat. Note that @ref glfwGetKey still returns only `GLFW_PRESS` or +`GLFW_RELEASE`. + + @subsection moving_keys Physical key input GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to @@ -208,6 +217,16 @@ having to remember whether to check for `'a'` or `'A'`, you now check for `GLFW_KEY_A`. +@subsection moving_joystick Joystick input + +The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes. + +The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and +`GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent +function as well as axis and button counts returned by the @ref +glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions. + + @subsection moving_video_modes Video mode enumeration Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function @@ -260,6 +279,7 @@ Unix-like systems, where it uses the | `glfwGetWindowParam` | @ref glfwGetWindowAttrib | | | `glfwGetGLVersion` | @ref glfwGetWindowAttrib | Use `GLFW_OPENGL_VERSION_MAJOR`, `GLFW_OPENGL_VERSION_MINOR` and `GLFW_OPENGL_REVISION` | | `glfwGetDesktopMode` | @ref glfwGetVideoMode | Returns the current mode of a monitor | +| `glfwGetJoystickParam` | @ref glfwJoystickPresent | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons | @subsection moving_renamed_tokens Tokens diff --git a/docs/news.dox b/docs/news.dox index b7af7ce2..508bd3aa 100644 --- a/docs/news.dox +++ b/docs/news.dox @@ -128,4 +128,9 @@ Windowed mode windows can now be created without decorations, i.e. things like a frame, a title bar, with the `GLFW_DECORATED` window hint. This allows for the creation of things like splash screens. + +@subsection news_30_jsname Joystick names + +The name of a joystick can now be retrieved using @ref glfwGetJoystickName. + */ diff --git a/docs/window.dox b/docs/window.dox index 55531fd5..029e6b10 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -1,31 +1,32 @@ -/*! @page window Window handling +/*! + +@page window Window handling guide @tableofcontents The primary purpose of GLFW is to provide a simple interface to window -management and OpenGL and OpenGL ES context creation. GLFW supports -multiple windows, which can be either a normal desktop window or -a fullscreen window. +management and OpenGL and OpenGL ES context creation. GLFW supports multiple +windows, which can be either a normal desktop window or a fullscreen window. -@section window_object Window objects + +@section window_object Window handles 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 -linked, the window handle (i.e. window object pointer) is used as a context -handle as well, for example when calling @ref glfwMakeContextCurrent. +linked, the object pointer is used as both a context and window handle. -@section window_hints Window hints +@section window_hints Window creation hints -There are a number of hints that can be set before the creation of a window. -Some affect the window itself, others its framebuffer or context. These hints -are set to their default values each time the library is initialized with @ref -glfwInit, can be individually set with @ref glfwWindowHint and reset all at once -to their defaults with @ref glfwDefaultWindowHints. +There are a number of hints that can be set before the creation of a window and +context. Some affect the window itself, others affect the framebuffer or +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 again that they need to be set *before* the creation of the window you wish -to have the specified attributes. +Note that hints need to be set *before* the creation of the window and context +you wish to have the specified attributes. @subsection window_hints_hard Hard and soft constraints @@ -49,6 +50,21 @@ context: Hints that do not apply to a given type of window or context are ignored. +@subsection window_hints_wnd Window related hints + +The `GLFW_RESIZABLE` hint specifies whether the window will be resizable *by the +user*. The window will still be resizable using the @ref glfwSetWindowSize +function. This hint is ignored for fullscreen windows. + +The `GLFW_VISIBLE` hint specifies whether the window will be initially +visible. This hint is ignored for fullscreen windows. + +The `GLFW_DECORATED` hint specifies whether the window will have window +decorations such as a border, a close widget, etc. This hint is ignored for +fullscreen windows. Note that even though a window may lack a close widget, it +is usually still possible for the user to generate close events. + + @subsection window_hints_fb Framebuffer related hints The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`, @@ -116,21 +132,6 @@ used by the context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or a robustness strategy. -@subsection window_hints_wnd Window related hints - -The `GLFW_RESIZABLE` hint specifies whether the window will be resizable *by the -user*. The window will still be resizable using the @ref glfwSetWindowSize -function. This hint is ignored for fullscreen windows. - -The `GLFW_VISIBLE` hint specifies whether the window will be initially -visible. This hint is ignored for fullscreen windows. - -The `GLFW_DECORATED` hint specifies whether the window will have window -decorations such as a border, a close widget, etc. This hint is ignored for -fullscreen windows. Note that even though a window may lack a close widget, it -is usually still possible for the user to generate close events. - - @subsection window_hints_values Supported and default values | Name | Default value | Supported values | @@ -161,20 +162,235 @@ is usually still possible for the user to generate close events. | `GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_NO_PROFILE` | `GLFW_OPENGL_NO_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` | -@section window_closing Window closing +@section window_close Window 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 window's close flag is set and then -its close callback is called. The window is not actually destroyed and, unless -you are monitoring the close flag, nothing further happens. +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. -If you do not want the close flag to be set, it can be cleared again from the -close callback (or from any other point in your program) with @ref -glfwSetWindowShouldClose. +The current state of the close flag is returned by @ref glfwWindowShouldClose +and can be set or cleared directly with @ref glfwSetWindowShouldClose. A common +pattern is to use the close flag as a main loop condition. + +@code +while (!glfwWindowShouldClose(window)) +{ + render(window); + + glfwSwapBuffers(window); + glfwPollEvents(); +} +@endcode + +If you wish to be notified when the user attempts to close a window, you can set +the close callback with @ref glfwSetWindowCloseCallback. This callback is +called directly *after* the close flag has been set. + +@code +glfwSetWindowCloseCallback(window, window_close_callback); +@endcode + +The callback function can be used for example to filter close requests and clear +the close flag again unless certain conditions are met. + +@code +void window_close_callback(GLFWwindow* window) +{ + if (!time_to_close) + glfwSetWindowShouldClose(window, GL_FALSE); +} +@endcode -@section window_dims Window dimensions +@section window_size Window size -Text here. +The size of a window can be changed with @ref glfwSetWindowSize. For windowed +mode windows, this resizes the specified window so that its *client area* has +the specified size. Note that the window system may put limitations on size. +For full screen windows, it selects and sets the video mode most closely +matching the specified size. + +@code +void glfwSetWindowSize(window, 640, 480); +@endcode + +If you wish to be notified when a window is resized, whether by the user or +the system, you can set the size callback with @ref glfwSetWindowSizeCallback. + +@code +glfwSetWindowSizeCallback(window, window_size_callback); +@endcode + +The callback function receives the new size of the client area of the window, +which can for example be used to update the viewport. + +@code +void window_size_callback(GLFWwindow* window, int width, int height) +{ + glViewport(0, 0, width, height); +} +@endcode + +There is also @ref glfwGetWindowSize for directly retrieving the current size of +a window. + +@code +int width, height; +glfwGetWindowSize(window, &width, &height); +glViewport(0, 0, width, height); +@endcode + + +@section 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 +client area has the specified screen coordinates. Note that the window system +may put limitations on placement. + +@code +glfwSetWindowPos(window, 100, 100); +@endcode + +If you wish to be notified when a window is moved, whether by the user or +the system, you can set the position callback with @ref glfwSetWindowPosCallback. + +@code +glfwSetWindowPosCallback(window, window_pos_callback); +@endcode + +The callback function receives the new position of the upper-left corner of its +client area. + +@code +void window_size_callback(GLFWwindow* window, int xpos, int ypos) +{ +} +@endcode + +There is also @ref glfwGetWindowPos for directly retrieving the current position +of the client area of the window. + +@code +int xpos, ypos; +glfwGetWindowPos(window, &xpos, &ypos); +@endcode + + +@section 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. To change +the title of a window, use @ref glfwSetWindowTitle. + +@code +glfwSetWindowTitle(window, "My Window"); +@endcode + +The window title is a regular C string using the UTF-8 encoding. This means +for example that, as long as your source file is encoded as UTF-8, you can use +any Unicode characters. + +@code +glfwSetWindowTitle(window, "さよなら絶望先生"); +@endcode + + +@section 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 +the window, while others reflect the corresponding hints and are fixed at the +time of creation. + +@code +if (glfwGetWindowAttrib(window, GLFW_FOCUSED)) +{ + // window has input focus +} +@endcode + + +@subsection window_attribs_window Window attributes + +The `GLFW_FOCUSED` attribute indicates whether the specified window currently +has input focus. + +The `GLFW_ICONIFIED` attribute indicates whether the specified window is +currently iconified, whether by the user or with @ref glfwIconifyWindow. + +The `GLFW_VISIBLE` attribute indicates whether the specified window is currently +visible. Window 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. + +The `GLFW_RESIZABLE` attribute indicates whether the specified window is +resizable *by the user*. This is controlled by the [window hint](@ref +window_hints) with the same name. + +The `GLFW_DECORATED` attribute indicates whether the specified window has +decorations such as a border, a close widget, etc. This is controlled by the +[window hint](@ref window_hints) with the same name. + + +@subsection window_attribs_context Context attributes + +The `GLFW_CLIENT_API` attribute indicates the client API provided by the +window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`. + +The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and +`GLFW_CONTEXT_REVISION` attributes indicate the client API version of the +window's context. + +The `GLFW_OPENGL_FORWARD_COMPAT` attribute is `GL_TRUE` if the window's +context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise. + +The `GLFW_OPENGL_DEBUG_CONTEXT` attribute is `GL_TRUE` if the window's +context is an OpenGL debug context, or `GL_FALSE` otherwise. + +The `GLFW_OPENGL_PROFILE` attribute indicates the OpenGL profile used by the +context. This is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` +if the context uses a known profile, or `GLFW_OPENGL_NO_PROFILE` if the +OpenGL profile is unknown or the context is for another client API. + +The `GLFW_CONTEXT_ROBUSTNESS` attribute indicates the robustness strategy +used by the context. 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 Swapping buffers + +GLFW windows are always double buffered. That means that you have two +rendering buffers; a front buffer and a back buffer. The front buffer is +the one being displayed and the back buffer the one you render to. + +When the entire frame has been rendered, it is time to swap the back and the +front buffers in order to display what has been rendered and begin rendering +a new frame. This is done with @ref glfwSwapBuffers. + +@code +glfwSwapBuffers(window); +@endcode + +Sometimes it can be useful to select when the buffer swap will occur. With the +function @ref glfwSwapInterval it is possible to select the minimum number of +monitor refreshes the driver should wait before swapping the buffers: + +@code +glfwSwapInterval(1); +@endcode + +If the interval is zero, the swap will take place immediately when @ref +glfwSwapBuffers is called without waiting for a refresh. Otherwise at least +interval retraces will pass between each buffer swap. Using a swap interval of +zero can be useful for benchmarking purposes, when it is not desirable to +measure the time it takes to wait for the vertical retrace. However, a swap +interval of one lets you avoid tearing. + +Note that not all OpenGL implementations properly implement this function, in +which case @ref glfwSwapInterval will have no effect. Some drivers also have +user settings that override requests by GLFW. */ diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 7a82099c..8e26e5b6 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -1268,7 +1268,7 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); * @param[out] xpos The x-coordinate of the upper-left corner of the client area. * @param[out] ypos The y-coordinate of the upper-left corner of the client area. * - * @remarks Either or both coordinate parameters may be `NULL`. + * @remarks Either or both coordinate arguments may be `NULL`. * * @bug **Mac OS X:** The screen coordinate system is inverted. * @@ -1441,47 +1441,10 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); * attributes, some related to the window and others to its context. * * @param[in] window The window to query. - * @param[in] attrib The attribute whose value to return. + * @param[in] attrib The [window attribute](@ref window_attribs) whose value to + * return. * @return The value of the attribute, or zero if an error occurred. * - * @par Window attributes - * - * The `GLFW_FOCUSED` attribute indicates whether the window is focused. - * - * The `GLFW_ICONIFIED` attribute indicates whether the window is iconified. - * - * The `GLFW_VISIBLE` attribute indicates whether the window is visible. - * - * The `GLFW_RESIZABLE` attribute indicates whether the window is resizable - * by the user. - * - * The `GLFW_DECORATED` attribute indicates whether the window is decorated. - * - * @par Context attributes - * - * The `GLFW_CLIENT_API` attribute indicates the client API provided by the - * window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`. - * - * The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and - * `GLFW_CONTEXT_REVISION` attributes indicate the client API version of the - * window's context. - * - * The `GLFW_OPENGL_FORWARD_COMPAT` attribute is `GL_TRUE` if the window's - * context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise. - * - * The `GLFW_OPENGL_DEBUG_CONTEXT` attribute is `GL_TRUE` if the window's - * context is an OpenGL debug context, or `GL_FALSE` otherwise. - * - * The `GLFW_OPENGL_PROFILE` attribute indicates the OpenGL profile used by the - * context. This is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` - * if the context uses a known profile, or `GLFW_OPENGL_NO_PROFILE` if the - * OpenGL profile is unknown or the context is for another client API. - * - * The `GLFW_CONTEXT_ROBUSTNESS` attribute indicates the robustness strategy - * used by the context. This is `GLFW_LOSE_CONTEXT_ON_RESET` or - * `GLFW_NO_RESET_NOTIFICATION` if the window's context supports robustness, or - * `GLFW_NO_ROBUSTNESS` otherwise. - * * @ingroup window */ GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib); @@ -2138,9 +2101,9 @@ GLFWAPI void glfwSwapInterval(int interval); /*! @brief Returns whether the specified extension is available. * * This function returns whether the specified - * [OpenGL or context creation API extension](@ref glext) is supported by the - * current context. For example, on Windows both the OpenGL and WGL extension - * strings are checked. + * [OpenGL or context creation API extension](@ref context_glext) is supported + * by the current context. For example, on Windows both the OpenGL and WGL + * extension strings are checked. * * @param[in] extension The ASCII encoded name of the extension. * @return `GL_TRUE` if the extension is available, or `GL_FALSE` otherwise. @@ -2160,8 +2123,8 @@ GLFWAPI int glfwExtensionSupported(const char* extension); * context. * * This function returns the address of the specified - * [client API or extension function](@ref glext), if it is supported by the - * current context. + * [client API or extension function](@ref context_glext), if it is supported + * by the current context. * * @param[in] procname The ASCII encoded name of the function. * @return The address of the function, or `NULL` if the function is