Jiga228/glfw
0
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2026-09-22 08:50:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clarify docs on default GL header inclusion

Browse Source 
The documentation claims that any extension loader library header
included before the GLFW one will prevent the inclusion of the
default OpenGL header.  In reality this only worked if the loader
defined the canonical desktop OpenGL __gl_h_ inclusion guard and even
then relied on the OpenGL header to detect this.

This is the companion to 105cf32e0b, which
added the preprocessor logic to check for many known OpenGL and OpenGL
ES inclusion guards and not even attempt to include the default header
if any are present.

Some clarification of the language around header inclusion has also been
attempted, including making GLFW_INCLUDE_NONE more prominent.

Fixes #1695.
This commit is contained in:
Camilla Löwy
2020-05-28 17:38:21 +02:00
parent 9a87c2a4b4
commit 399c2a1fad
3 changed files with 47 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/build.dox
+22 -19
View File
@@ -25,39 +25,41 @@ GLFW.
#include <GLFW/glfw3.h>
@endcode
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.
This header defines all the constants and declares all the types and function
prototypes of the GLFW API. By default it also includes the OpenGL header from
your development environment. See [option macros](@ref build_macros) below for
how to select OpenGL ES headers and more.
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.
header, so that it can be included without needing any window system headers.
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.
It does this only when needed, so if window system headers are included, the
GLFW header does not try to redefine those symbols. The reverse is not true,
i.e. `windows.h` cannot cope if any Win32 symbols have already been defined.
In other words:
- Do _not_ include the OpenGL headers yourself, as GLFW does this for you
- Do _not_ include `windows.h` or other platform-specific headers unless you
plan on using those APIs directly
- If you _do_ need to include such headers, do it _before_ including
the GLFW header and it will handle this
- Use the GLFW header to include OpenGL or OpenGL ES headers portably
- Do not include window system headers unless you will use those APIs directly
- If you do need such headers, include them before the GLFW header
If you are using an OpenGL extension loading library such as
[glad](https://github.com/Dav1dde/glad), the extension loader header should
be included _before_ the GLFW one.
be included before the GLFW one. GLFW attempts to detect any OpenGL or OpenGL
ES header or extension loader header included before it and will then disable
the inclusion of the default OpenGL header. Most extension loaders also define
macros that disable similar headers below it.
@code
#include <glad/gl.h>
#include <GLFW/glfw3.h>
@endcode
Alternatively the @ref GLFW_INCLUDE_NONE macro (described below) can be used to
prevent the GLFW header from including the OpenGL header.
Both of these mechanisms depend on the extension loader header defining a known
macro. If yours doesn't or you don't know which one your users will pick, the
@ref GLFW_INCLUDE_NONE macro will explicitly to prevent the GLFW header from
including the OpenGL header. This will also allow you to include the two
headers in any order.
@code
#define GLFW_INCLUDE_NONE
@@ -113,7 +115,8 @@ __GLFW_INCLUDE_NONE__ makes the GLFW header not include any OpenGL or OpenGL ES
API header. This is useful in combination with an extension loading library.
If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
header (`OpenGL/gl.h` on macOS) is included.
header (`OpenGL/gl.h` on macOS) is included, unless GLFW detects the inclusion
guards of any OpenGL, OpenGL ES or extension loader header it knows about.
The following macros control the inclusion of additional API headers. Any
number of these may be defined simultaneously, and/or together with one of the