From d2779aa765affd6706d5968080c30b0a09a06ef7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Wed, 7 Jun 2017 12:25:57 +0200 Subject: [PATCH] Documentation work [ci skip] --- docs/build.dox | 41 +++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/docs/build.dox b/docs/build.dox index 97dda32d..e428594e 100644 --- a/docs/build.dox +++ b/docs/build.dox @@ -15,27 +15,27 @@ specific compiler of your chosen development environment. The compilation and linking process should be explained in your C programming material and in the documentation for your development environment. + @section build_include Including the GLFW header file -In the source files of your application where you use OpenGL or GLFW, you should -include the GLFW header file, i.e.: +You should include the GLFW header in the source files where you use OpenGL or +GLFW. @code #include @endcode -The GLFW header declares the GLFW API and by default also includes the OpenGL -header of your development environment, which in turn defines all the constants, -types and function prototypes of the OpenGL API. +This header declares the GLFW API and by default also includes the OpenGL header +from your development environment. See below for how to control this. -The GLFW header also defines everything necessary for your OpenGL header to -function. For example, under Windows you are normally required to include -`windows.h` before the OpenGL header, which would pollute your code namespace -with the entire Win32 API. +The GLFW header also defines any platform-specific macros needed by your OpenGL +header, so it can be included without needing any window system headers. -Instead, the GLFW header takes care of this for you, not by including -`windows.h`, but by duplicating only the very few necessary parts of it. It -does this only when needed, so if `windows.h` _is_ included, the GLFW header +For example, under Windows you are normally required to include `windows.h` +before the OpenGL header, which would bring in the whole Win32 API. The GLFW +header duplicates the small number of macros needed. + +It does this only when needed, so if `windows.h` _is_ included, the GLFW header does not try to redefine those symbols. The reverse is not true, i.e. `windows.h` cannot cope if any of its symbols have already been defined. @@ -49,8 +49,21 @@ In other words: If you are using an OpenGL extension loading library such as [glad](https://github.com/Dav1dde/glad), the extension loader header should -either be included _before_ the GLFW one, or the @ref GLFW_INCLUDE_NONE macro -(described below) should be defined. +be included _before_ the GLFW one. + +@code +#include +#include +@endcode + +Alternatively the @ref GLFW_INCLUDE_NONE macro (described below) can be used to +prevent the GLFW header from including the OpenGL header. + +@code +#define GLFW_INCLUDE_NONE +#include +#include +@endcode @subsection build_macros GLFW header option macros