mirror of
https://github.com/glfw/glfw.git
synced 2026-09-19 15:25:50 +00:00
Merge branch '3.3-stable' into new-cursors-on-3.3-stable
This commit is contained in:
Camilla Löwy
+28
-22
@@ -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
|
||||
@@ -105,7 +107,7 @@ __GLFW_INCLUDE_ES31__ makes the GLFW header include the OpenGL ES 3.1
|
||||
`GLES3/gl31.h` header instead of the regular OpenGL header.
|
||||
|
||||
@anchor GLFW_INCLUDE_ES32
|
||||
__GLFW_INCLUDE_ES31__ makes the GLFW header include the OpenGL ES 3.2
|
||||
__GLFW_INCLUDE_ES32__ makes the GLFW header include the OpenGL ES 3.2
|
||||
`GLES3/gl32.h` header instead of the regular OpenGL header.
|
||||
|
||||
@anchor 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
|
||||
@@ -219,12 +222,15 @@ find_package(OpenGL REQUIRED)
|
||||
@endcode
|
||||
|
||||
If OpenGL is found, the `OpenGL::GL` target is added to your project, containing
|
||||
library and include directory paths. Link against this like above.
|
||||
library and include directory paths. Link against this like any other library.
|
||||
|
||||
@code{.cmake}
|
||||
target_link_libraries(myapp OpenGL::GL)
|
||||
@endcode
|
||||
|
||||
For a minimal example of a program and GLFW sources built with CMake, see the
|
||||
[GLFW CMake Starter](https://github.com/juliettef/GLFW-CMake-starter) on GitHub.
|
||||
|
||||
|
||||
@subsection build_link_cmake_package With CMake and installed GLFW binaries
|
||||
|
||||
@@ -258,7 +264,7 @@ find_package(OpenGL REQUIRED)
|
||||
@endcode
|
||||
|
||||
If OpenGL is found, the `OpenGL::GL` target is added to your project, containing
|
||||
library and include directory paths. Link against this like above.
|
||||
library and include directory paths. Link against this like any other library.
|
||||
|
||||
@code{.cmake}
|
||||
target_link_libraries(myapp OpenGL::GL)
|
||||
|
||||
+33
-30
@@ -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
|
||||
|
||||
@@ -246,12 +245,16 @@ glViewport(0, 0, width, height);
|
||||
You can also set a framebuffer size callback using @ref
|
||||
glfwSetFramebufferSizeCallback and be notified when the size changes.
|
||||
|
||||
Actual rendering with OpenGL is outside the scope of this tutorial, but there
|
||||
are [many](https://open.gl/) [excellent](https://learnopengl.com/)
|
||||
[tutorial](http://openglbook.com/) [sites](http://ogldev.atspace.co.uk/) that
|
||||
teach modern OpenGL. Some of them use GLFW to create the context and window
|
||||
while others use GLUT or SDL, but remember that OpenGL itself always works the
|
||||
same.
|
||||
The details of how to render with OpenGL is outside the scope of this tutorial,
|
||||
but there are many excellent resources for learning modern OpenGL. Here are
|
||||
a few of them:
|
||||
|
||||
- [Anton's OpenGL 4 Tutorials](https://antongerdelan.net/opengl/)
|
||||
- [Learn OpenGL](https://learnopengl.com/)
|
||||
- [Open.GL](https://open.gl/)
|
||||
|
||||
These all happen to use GLFW, but OpenGL itself works the same whatever API you
|
||||
use to create the window and context.
|
||||
|
||||
|
||||
@subsection quick_timer Reading the timer
|
||||
|
||||
+8
-3
@@ -4,8 +4,8 @@
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide is intended to fill the gaps between the [Vulkan
|
||||
documentation](https://www.khronos.org/vulkan/) and the rest of the GLFW
|
||||
This guide is intended to fill the gaps between the official [Vulkan
|
||||
resources](https://www.khronos.org/vulkan/) and the rest of the GLFW
|
||||
documentation and is not a replacement for either. It assumes some familiarity
|
||||
with Vulkan concepts like loaders, devices, queues and surfaces and leaves it to
|
||||
the Vulkan documentation to explain the details of Vulkan functions.
|
||||
@@ -14,7 +14,12 @@ To develop for Vulkan you should download the [LunarG Vulkan
|
||||
SDK](https://vulkan.lunarg.com/) for your platform. Apart from headers and link
|
||||
libraries, they also provide the validation layers necessary for development.
|
||||
|
||||
For details on a specific function in this category, see the @ref vulkan. There
|
||||
The [Vulkan Tutorial](https://vulkan-tutorial.com/) has more information on how
|
||||
to use GLFW and Vulkan. The [Khronos Vulkan
|
||||
Samples](https://github.com/KhronosGroup/Vulkan-Samples) also use GLFW, although
|
||||
with a small framework in between.
|
||||
|
||||
For details on a specific Vulkan support function, see the @ref vulkan. There
|
||||
are also guides for the other areas of the GLFW API.
|
||||
|
||||
- @ref intro_guide
|
||||
|
||||
Reference in New Issue
Block a user