AuroraMiddleware/glfw
1
0
Fork 0
Code Issues Pull Requests 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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -133,6 +133,8 @@ information on what to include when reporting a bug.
- Bugfix: Video modes with a duplicate screen area were discarded (#1555,#1556)
- Bugfix: Compiling with -Wextra-semi caused warnings (#1440)
- Bugfix: Built-in mappings failed because some OEMs re-used VID/PID (#1583)
- Bugfix: Some extension loader headers did not prevent default OpenGL header
inclusion (#1695)
- [Win32] Added the `GLFW_WIN32_KEYBOARD_MENU` window hint for enabling access
to the window menu
- [Win32] Added a version info resource to the GLFW DLL

41
docs/build.dox
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

47
docs/quick.dox
View File

@ -18,43 +18,42 @@ behave differently in GLFW 3.
@subsection quick_include Including the GLFW header
In the source files of your application where you use OpenGL or GLFW, you need
to include the GLFW 3 header file.
In the source files of your application where you use GLFW, you need to include
its header file.
@code
#include <GLFW/glfw3.h>
@endcode
This defines all the constants, types and function prototypes of the GLFW API.
It also includes the OpenGL header from your development environment and
defines all the constants and types necessary for it to work on your platform
without including any platform-specific headers.
This header provides all the constants, types and function prototypes of the
GLFW API.
In other words:
By default it also includes the OpenGL header from your development environment.
On some platforms this header only supports older versions of OpenGL. The most
extreme case is Windows, where it typically only supports OpenGL 1.2.
- Do _not_ include the OpenGL header yourself, as GLFW does this for you in
a platform-independent way
- Do _not_ include `windows.h` or other platform-specific headers unless
you plan on using those APIs yourself
- If you _do_ need to include such headers, include them _before_ the GLFW
header and it will detect this
On some platforms supported by GLFW the OpenGL header and link library only
expose older versions of OpenGL. The most extreme case is Windows, which only
exposes OpenGL 1.2. The easiest way to work around this is to use an
[extension loader library](@ref context_glext_auto).
If you are using such a library then you should include its header _before_ the
GLFW header. This lets it replace the OpenGL header included by GLFW without
conflicts. This example uses
[glad2](https://github.com/Dav1dde/glad), but the same rule applies to all such
libraries.
Most programs will instead use an
[extension loader library](@ref context_glext_auto) and include its header.
This example uses files generated by [glad](https://gen.glad.sh/). The GLFW
header can detect most such headers if they are included first and will then not
include the one from your development environment.
@code
#include <glad/gl.h>
#include <GLFW/glfw3.h>
@endcode
To make sure there will be no header conflicts, you can define @ref
GLFW_INCLUDE_NONE before the GLFW header to explicitly disable inclusion of the
development environment header. This also allows the two headers to be included
in any order.
@code
#define GLFW_INCLUDE_NONE
#include <GLFW/glfw3.h>
#include <glad/gl.h>
@endcode
@subsection quick_init_term Initializing and terminating GLFW