From 2d13eb0920f89f7c9820714026fd524d08b35168 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Mon, 13 Oct 2014 16:00:11 +0200 Subject: [PATCH] Documentation work. --- docs/context.dox | 30 ++++++++++++++++++------------ include/GLFW/glfw3.h | 42 +++++++++++++++++++++++++++++++++++++----- 2 files changed, 55 insertions(+), 17 deletions(-) diff --git a/docs/context.dox b/docs/context.dox index 844b08da..16ad7a6d 100644 --- a/docs/context.dox +++ b/docs/context.dox @@ -70,20 +70,21 @@ 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. +offscreen context. Depending on the window manager, 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). +common commands like Hide, Quit and About. This is not desirable for example +when writing a command-line only application. The menu bar setup 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 -context of the proper type. The context encapsulates all render state and all -objects like textures and shaders. +context of the correct type. A context can only be current for a single thread +at a time, and a thread can only have a single context current at a time. A context is made current with @ref glfwMakeContextCurrent. @@ -97,9 +98,14 @@ The current context is returned by @ref glfwGetCurrentContext. GLFWwindow* window = glfwGetCurrentContext(); @endcode -@note A context can only be current for a single thread at a time, and a thread -can only have a single context current at a time. +The following GLFW functions require a context to be current: + - @ref glfwSwapInterval + - @ref glfwExtensionSupported + - @ref glfwGetProcAddress + +Calling any these functions without a current context will generate a @ref +GLFW_NO_CURRENT_CONTEXT error. @section context_swap Buffer swapping @@ -150,9 +156,9 @@ written to the `output` directory. python main.py --no-loader --out-path output @endcode -@note The `--no-loader` option is used because GLFW already provides a function -for loading OpenGL and OpenGL ES function pointers and glad can use this instead -of having to add its own. +The `--no-loader` option is added because GLFW already provides a function for +loading OpenGL and OpenGL ES function pointers and glad can call this instead of +having to implement its own. Add the generated `output/src/glad.c`, `output/include/glad/glad.h` and `output/include/KHR/khrplatform.h` files to your build. Then you need to diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 869df3c7..0b3cc077 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -527,6 +527,20 @@ extern "C" { #define GLFW_OUT_OF_MEMORY 0x00010005 /*! @brief GLFW could not find support for the requested client API on the * system. + * + * GLFW could not find support for the requested client API on the system. + * + * @par Analysis + * The installed graphics driver does not support the requested client API, or + * does not support it via the chosen context creation backend. Below are + * a few examples. + * + * @par + * Some pre-installed Windows graphics drivers do not support OpenGL. AMD only + * supports OpenGL ES via EGL, while nVidia and Intel only supports it via + * a WGL or GLX extension. OS X does not provide OpenGL ES at all. The Mesa + * EGL, OpenGL and OpenGL ES libraries do not interface with the nVidia binary + * driver. */ #define GLFW_API_UNAVAILABLE 0x00010006 /*! @brief The requested OpenGL or OpenGL ES version is not available. @@ -540,10 +554,11 @@ extern "C" { * Otherwise, inform the user that their machine does not match your * requirements. * - * @note Because GLFW is not psychic, future invalid OpenGL and OpenGL ES - * versions, say for example OpenGL 4.8 if 5.0 comes out before the 4.x series - * gets that far, also fail with this error and not @ref GLFW_INVALID_VALUE. - * The version logic is updated in every patch release, as needed. + * @par + * Future invalid OpenGL and OpenGL ES versions, for example OpenGL 4.8 if 5.0 + * comes out before the 4.x series gets that far, also fail with this error and + * not @ref GLFW_INVALID_VALUE, because GLFW cannot know what future versions + * will exist. */ #define GLFW_VERSION_UNAVAILABLE 0x00010007 /*! @brief A platform-specific error occurred that does not match any of the @@ -557,7 +572,24 @@ extern "C" { * [issue tracker](https://github.com/glfw/glfw/issues). */ #define GLFW_PLATFORM_ERROR 0x00010008 -/*! @brief The clipboard did not contain data in the requested format. +/*! @brief The requested format is not supported or available. + * + * If emitted during window creation, the requested pixel format is not + * supported. + * + * If emitted when querying the clipboard, the contents of the clipboard could + * not be converted to the requested format. + * + * @par Analysis + * If emitted during window creation, one or more + * [hard constraints](@ref window_hints_hard) did not match any of the + * available pixel formats. If your application is sufficiently flexible, + * downgrade your requirements and try again. Otherwise, inform the user that + * their machine does not match your requirements. + * + * @par + * If emitted when querying the clipboard, ignore the error or report it to + * the user, as appropriate. */ #define GLFW_FORMAT_UNAVAILABLE 0x00010009 /*! @} */