Jiga228/glfw
0
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2026-09-21 08:39:45 +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/quick.dox
+23 -24
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