From 96d230becb0c612b3f3631cb6cf83ebe0a393b71 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Tue, 7 Oct 2014 02:15:36 +0200 Subject: [PATCH] Documentation work. --- docs/context.dox | 33 ++++++++++++++++++++++++++++----- docs/intro.dox | 8 ++++---- docs/main.dox | 2 +- include/GLFW/glfw3.h | 9 +++++---- 4 files changed, 38 insertions(+), 14 deletions(-) diff --git a/docs/context.dox b/docs/context.dox index 62d45a64..844b08da 100644 --- a/docs/context.dox +++ b/docs/context.dox @@ -19,12 +19,13 @@ contexts. There are also guides for the other areas of the GLFW API. @section context_object Context objects -@ref window_object encapsulate both the OS level window and a OpenGL or OpenGL -ES context. It is created with @ref glfwCreateWindow and destroyed with @ref -glfwDestroyWindow or @ref glfwTerminate. As the window and context are -inseparably linked, the object pointer is used as both a context and window -handle. See @ref window_creation for more information. +A window object encapsulates both a top-level window and an OpenGL or OpenGL ES +context. It is created with @ref glfwCreateWindow and destroyed with @ref +glfwDestroyWindow or @ref glfwTerminate. See @ref window_creation for more +information. +As the window and context are inseparably linked, the window object also serves +as the context handle. @subsection context_hints Context creation hints @@ -56,6 +57,28 @@ Contexts_. GLFW comes with a simple object sharing test program called `sharing`. +@subsection context_offscreen Offscreen contexts + +GLFW doesn't support creating contexts without an associated window. However, +contexts with hidden windows can be created with the +[GLFW_VISIBLE](@ref window_hints_wnd) window hint. + +@code +glfwWindowHint(GLFW_VISIBLE, GL_FALSE); + +GLFWwindow* offscreen_context = glfwCreateWindow(640, 480, "", NULL, NULL); +@endcode + +The window never needs to be shown and its context can be used as a plain +offscreen context. The size of a hidden window's framebuffer may not be usable +or modifiable, so framebuffer objects are recommended for rendering with such +contexts. + +__OS X:__ The first time a window is created the menu bar is populated with +common commands like Hide, Quit and About. This can be disabled with a +[compile-time option](@ref compile_options_osx). + + @section context_current Current context Before you can make OpenGL or OpenGL ES calls, you need to have a current diff --git a/docs/intro.dox b/docs/intro.dox index 6e293e0f..5ad070eb 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -31,8 +31,8 @@ successfully initialized, and only from the main thread. - @ref glfwInit - @ref glfwTerminate -Calling any other function before that time will cause a `GLFW_NOT_INITIALIZED` -error. +Calling any other function before that time will cause a @ref +GLFW_NOT_INITIALIZED error. @subsection intro_init_init Initializing GLFW @@ -71,8 +71,8 @@ any resources allocated by GLFW. Once the library is terminated, it is as if it had never been initialized and you will need to initialize it again before being able to use GLFW. If the -library had not been successfully initialized or had already been terminated, -additional calls return immediately. +library was not initialized or had already been terminated, it return +immediately. @section error_handling Error handling diff --git a/docs/main.dox b/docs/main.dox index c18dcbb0..7aa1d45c 100644 --- a/docs/main.dox +++ b/docs/main.dox @@ -9,7 +9,7 @@ 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). +[new features](@ref news_31). @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 diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index e3eb4617..39a07791 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -1544,10 +1544,11 @@ GLFWAPI void glfwWindowHint(int target, int hint); * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) * in the Mac Developer Library. * - * @remarks __OS X:__ The first time a window is opened the menu bar is populated with - * common commands like Hide, Quit and About. The About entry opens a minimal - * about dialog with information from the application's bundle. The menu bar can be - * disabled with a [compile-time option](@ref compile_options_osx). + * @remarks __OS X:__ The first time a window is created the menu bar is + * populated with common commands like Hide, Quit and About. The About entry + * opens a minimal about dialog with information from the application's bundle. + * The menu bar can be disabled with a + * [compile-time option](@ref compile_options_osx). * * @remarks __X11:__ There is no mechanism for setting the window icon yet. *