From 4e375d0e743eb4dcad8d839e3cc83260c0cbd1f2 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Sun, 11 Jan 2015 18:25:54 +0100 Subject: [PATCH] Documentation work. --- docs/compat.dox | 4 ++-- docs/context.dox | 12 ++++++------ docs/intro.dox | 51 ++++++++++++++++++++++++++++-------------------- docs/monitor.dox | 6 +++--- docs/quick.dox | 7 +++---- docs/window.dox | 7 +++---- 6 files changed, 47 insertions(+), 40 deletions(-) diff --git a/docs/compat.dox b/docs/compat.dox index 32e117dc..dcce843b 100644 --- a/docs/compat.dox +++ b/docs/compat.dox @@ -91,7 +91,7 @@ formats. If GLX 1.3 is not supported, @ref glfwInit will fail. GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and `GLX_SGI_swap_control` extensions to provide vertical retrace synchronization -(or "vsync"), in that order of preference. Where none of these extension are +(or _vsync_), in that order of preference. Where none of these extension are available, calling @ref glfwSwapInterval will have no effect. GLFW uses the `GLX_ARB_multisample` extension to create contexts with @@ -128,7 +128,7 @@ neither is available, no other extensions are used and many GLFW features related to context creation will have no effect or cause errors when used. GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace -synchronization (or 'vsync'). Where this extension is unavailable, calling @ref +synchronization (or _vsync_). Where this extension is unavailable, calling @ref glfwSwapInterval will have no effect. GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to diff --git a/docs/context.dox b/docs/context.dox index ff5f9acd..1d8f284c 100644 --- a/docs/context.dox +++ b/docs/context.dox @@ -4,12 +4,8 @@ @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, with each window having its own context. - -This guide introduces the functions related to managing OpenGL and OpenGL ES -contexts. There are also guides for the other areas of the GLFW API. +This guide introduces the OpenGL and OpenGL ES context related functions of +GLFW. There are also guides for the other areas of the GLFW API. - @ref intro - @ref window @@ -27,6 +23,10 @@ information. As the window and context are inseparably linked, the window object also serves as the context handle. +To test the creation of various kinds of contexts and see their properties, run +the `glfwinfo` test program. + + @subsection context_hints Context creation hints There are a number of hints, specified using @ref glfwWindowHint, related to diff --git a/docs/intro.dox b/docs/intro.dox index 90612ac0..d544b36f 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -151,10 +151,10 @@ which monitor the window is currently considered to be on. @section guarantees_limitations Guarantees and limitations This section describes the conditions under which GLFW can be expected to -function, barring any bugs in GLFW, the operating system or drivers. Use of -GLFW outside of these limits may work on some platforms, or on some machines, or -some of the time, or on some versions of GLFW, but it may break at any time and -will not be considered a bug. +function, barring bugs in the operating system or drivers. Use of GLFW outside +of these limits may work on some platforms, or on some machines, or some of the +time, or on some versions of GLFW, but it may break at any time and this will +not be considered a bug. @subsection lifetime Pointer lifetimes @@ -171,9 +171,10 @@ If you need to keep this data, you must copy it before its lifetime expires. Many GLFW functions accept pointers to structures or strings allocated by the application. These are never freed by GLFW and are always the responsibility of the application. If GLFW needs to keep the data in these structures or strings, -they are copied before the function returns. +it is copied before the function returns. -Pointer lifetimes are guaranteed not to be shortened in future minor releases. +Pointer lifetimes are guaranteed not to be shortened in future minor or patch +releases. @subsection reentrancy Reentrancy @@ -191,16 +192,22 @@ function: - @ref glfwWaitEvents - @ref glfwTerminate +These functions may be made reentrant in future minor or patch releases, but +functions not on this list will not be made non-reentrant. + @subsection thread_safety Thread safety -Most GLFW functions may only be called from the main thread. The reference -documentation for every GLFW function states whether it is limited to the main -thread. +Most GLFW functions may only be called from the main thread, but some may be +called from any thread. However, no GLFW function may be called from any other +thread until GLFW has been successfully initialized on the main thread, +including functions that may called before initialization. -There are some general rules that make it easier to remember which functions are -limited to the main thread. The following tasks may only be performed on the -main thread: +The reference documentation for every GLFW function states whether it is limited +to the main thread. + +The following categories of functions are and will remain limited to the main +thread due to the limitations of one or several platforms: - Initialization and termination - Event processing @@ -236,9 +243,11 @@ The following timer related functions may be called from any thread: - @ref glfwGetTime -No GLFW function may be called from any other thread until GLFW has been -successfully initialized on the main thread, including functions that may called -before initialization. +Library version information may be queried from any thread. The following +version related functions may be called from any thread: + + - @ref glfwGetVersion + - @ref glfwGetVersionString GLFW uses no synchronization objects internally except for thread-local storage to keep track of the current context for each thread. Synchronization is left @@ -259,8 +268,8 @@ Once a function or constant has been added, the signature of that function or value of that constant will remain unchanged until the next major version of GLFW. No compatibility of any kind is guaranteed between major versions. -Undefined behavior, i.e. behavior that is not described in reference -documentation, may change at any time until it is documented. +Undocumented behavior, i.e. behavior that is not described in the documentation, +may change at any time until it is documented. If the reference documentation and the implementation differ, the reference documentation is correct and the implementation will be fixed in the next @@ -318,6 +327,10 @@ see which code paths are enabled in a binary. The version string is returned by @ref glfwGetVersionString, a function that may be called regardless of whether GLFW is initialized. +__Do not use the version string__ to find the GLFW library version. The @ref +glfwGetVersion function already provides the version of the running library +binary. + The format of the string is as follows: - The version of GLFW - The name of the window system API @@ -331,8 +344,4 @@ back ends, the version string may look something like this: 3.0.0 Win32 WGL MinGW @endcode -@note Do not parse the version string to find the GLFW library version. The -@ref glfwGetVersion function provides the version of the library binary in -numeric form. - */ diff --git a/docs/monitor.dox b/docs/monitor.dox index a42d195b..1773d45b 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -12,9 +12,6 @@ guides for the other areas of GLFW. - @ref context - @ref input -To see how GLFW views your monitor setup and its available video modes, run the -`modes` test program. - @section monitor_objects Monitor objects @@ -33,6 +30,9 @@ The virtual position of a monitor is in video mode, describes the viewports that the connected monitors provide into the virtual desktop that spans them. +To see how GLFW views your monitor setup and its available video modes, run the +`modes` test program. + @subsection monitor_monitors Retrieving monitors diff --git a/docs/quick.dox b/docs/quick.dox index 9bc11788..28336fc7 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -145,15 +145,14 @@ and its handle becomes invalid. @subsection quick_context_current Making the OpenGL context current -Before you can use the OpenGL API, it must have a current OpenGL context. You -make a window's context current. +Before you can use the OpenGL API, you must have a current OpenGL context. @code glfwMakeContextCurrent(window); @endcode -The context will then remain as current until you make another context current -or until the window owning the current context is destroyed. +The context will remain current until you make another context current or until +the window owning the current context is destroyed. @subsection quick_window_close Checking the window close flag diff --git a/docs/window.dox b/docs/window.dox index e7557602..316a7158 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -4,10 +4,6 @@ @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 full screen window. - This guide introduces the window related functions of GLFW. There are also guides for the other areas of GLFW. @@ -24,6 +20,9 @@ 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 +the `events` test program. + @subsection window_creation Window creation