mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-09-19 21:32:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Convert some external links to reference links

Browse Source
This commit is contained in:
Camilla Löwy 2024-02-14 01:36:35 +01:00
parent 532bd66e7f
commit 63397fb0d5
10 changed files with 181 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/build.md
View File

@ -41,12 +41,13 @@ In other words:
- Do not include window system headers unless you will use those APIs directly - 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 do need such headers, include them before the GLFW header
If you are using an OpenGL extension loading library such as If you are using an OpenGL extension loading library such as [glad][], the
[glad](https://github.com/Dav1dde/glad), the extension loader header should extension loader header should be included before the GLFW one. GLFW attempts
be included before the GLFW one. GLFW attempts to detect any OpenGL or OpenGL to detect any OpenGL or OpenGL ES header or extension loader header included
ES header or extension loader header included before it and will then disable before it and will then disable the inclusion of the default OpenGL header.
the inclusion of the default OpenGL header. Most extension loaders also define Most extension loaders also define macros that disable similar headers below it.
macros that disable similar headers below it.
[glad]: https://github.com/Dav1dde/glad
```c ```c
#include <glad/gl.h> #include <glad/gl.h>
@ -80,8 +81,9 @@ Only one of these may be defined at a time.
@note GLFW does not provide any of the API headers mentioned below. They are @note GLFW does not provide any of the API headers mentioned below. They are
provided by your development environment or your OpenGL, OpenGL ES or Vulkan provided by your development environment or your OpenGL, OpenGL ES or Vulkan
SDK, and most of them can be downloaded from the SDK, and most of them can be downloaded from the [Khronos Registry][registry].
[Khronos Registry](https://www.khronos.org/registry/).
[registry]: https://www.khronos.org/registry/
@anchor GLFW_INCLUDE_GLCOREARB @anchor GLFW_INCLUDE_GLCOREARB
__GLFW_INCLUDE_GLCOREARB__ makes the GLFW header include the modern __GLFW_INCLUDE_GLCOREARB__ makes the GLFW header include the modern
@ -153,9 +155,10 @@ hard-coded into your build environment. See the section for your development
environment below. On Linux and other Unix-like operating systems, the list environment below. On Linux and other Unix-like operating systems, the list
varies but can be retrieved in various ways as described below. varies but can be retrieved in various ways as described below.
A good general introduction to linking is A good general introduction to linking is [Beginner's Guide to
[Beginner's Guide to Linkers](https://www.lurklurk.org/linkers/linkers.html) by Linkers][linker_guide] by David Drysdale.
David Drysdale.
[linker_guide]: https://www.lurklurk.org/linkers/linkers.html
### With MinGW or Visual C++ on Windows {#build_link_win32} ### With MinGW or Visual C++ on Windows {#build_link_win32}
@ -217,7 +220,9 @@ target_link_libraries(myapp OpenGL::GL)
``` ```
For a minimal example of a program and GLFW sources built with CMake, see the 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. [GLFW CMake Starter][cmake_starter] on GitHub.
[cmake_starter]: https://github.com/juliettef/GLFW-CMake-starter
### With CMake and installed GLFW binaries {#build_link_cmake_package} ### With CMake and installed GLFW binaries {#build_link_cmake_package}
@ -261,12 +266,13 @@ target_link_libraries(myapp OpenGL::GL)
### With makefiles and pkg-config on Unix {#build_link_pkgconfig} ### With makefiles and pkg-config on Unix {#build_link_pkgconfig}
GLFW supports [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/), GLFW supports [pkg-config][], and the `glfw3.pc` pkg-config file is generated
and the `glfw3.pc` pkg-config file is generated when the GLFW library is built when the GLFW library is built and is installed along with it. A pkg-config
and is installed along with it. A pkg-config file describes all necessary file describes all necessary compile-time and link-time flags and dependencies
compile-time and link-time flags and dependencies needed to use a library. When needed to use a library. When they are updated or if they differ between
they are updated or if they differ between systems, you will get the correct systems, you will get the correct ones automatically.
ones automatically.
[pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/
A typical compile and link command-line when using the static version of the A typical compile and link command-line when using the static version of the
GLFW library may look like this: GLFW library may look like this:

111
docs/compat.md
View File

@ -15,16 +15,16 @@ be considered a breaking API change.
## X11 extensions, protocols and IPC standards {#compat_x11} ## X11 extensions, protocols and IPC standards {#compat_x11}
As GLFW uses Xlib directly, without any intervening toolkit As GLFW uses Xlib directly, without any intervening toolkit library, it has sole
library, it has sole responsibility for interacting well with the many and responsibility for interacting well with the many and varied window managers in
varied window managers in use on Unix-like systems. In order for applications use on Unix-like systems. In order for applications and window managers to work
and window managers to work well together, a number of standards and well together, a number of standards and conventions have been developed that
conventions have been developed that regulate behavior outside the scope of the regulate behavior outside the scope of the X11 API; most importantly the
X11 API; most importantly the [Inter-Client Communication Conventions Manual][ICCCM] (ICCCM) and [Extended
[Inter-Client Communication Conventions Manual](https://www.tronche.com/gui/x/icccm/) Window Manager Hints][EWMH] (EWMH) standards.
(ICCCM) and
[Extended Window Manager Hints](https://standards.freedesktop.org/wm-spec/wm-spec-latest.html) [ICCCM]: https://www.tronche.com/gui/x/icccm/
(EWMH) standards. [EWMH]: https://standards.freedesktop.org/wm-spec/wm-spec-latest.html
GLFW uses the `_MOTIF_WM_HINTS` window property to support borderless windows. GLFW uses the `_MOTIF_WM_HINTS` window property to support borderless windows.
If the running window manager does not support this property, the If the running window manager does not support this property, the
@ -50,16 +50,18 @@ compositing window manager to un-redirect full screen GLFW windows. If the
running window manager uses compositing but does not support this property then running window manager uses compositing but does not support this property then
additional copying may be performed for each buffer swap of full screen windows. additional copying may be performed for each buffer swap of full screen windows.
GLFW uses the GLFW uses the [clipboard manager protocol][ClipboardManager] to push a clipboard
[clipboard manager protocol](https://www.freedesktop.org/wiki/ClipboardManager/) string (i.e. selection) owned by a GLFW window about to be destroyed to the
to push a clipboard string (i.e. selection) owned by a GLFW window about to be clipboard manager. If there is no running clipboard manager, the clipboard
destroyed to the clipboard manager. If there is no running clipboard manager, string will be unavailable once the window has been destroyed.
the clipboard string will be unavailable once the window has been destroyed.
GLFW uses the [clipboardManager]: https://www.freedesktop.org/wiki/ClipboardManager/
[X drag-and-drop protocol](https://www.freedesktop.org/wiki/Specifications/XDND/)
to provide file drop events. If the application originating the drag does not GLFW uses the [X drag-and-drop protocol][XDND] to provide file drop events. If
support this protocol, drag and drop will not work. the application originating the drag does not support this protocol, drag and
drop will not work.
[XDND]: https://www.freedesktop.org/wiki/Specifications/XDND/
GLFW uses the XRandR 1.3 extension to provide multi-monitor support. If the GLFW uses the XRandR 1.3 extension to provide multi-monitor support. If the
running X server does not support this version of this extension, multi-monitor running X server does not support this version of this extension, multi-monitor
@ -104,44 +106,49 @@ Wayland protocols to implement certain features if the compositor supports them.
GLFW uses xkbcommon 0.5.0 to provide key and text input support. Earlier GLFW uses xkbcommon 0.5.0 to provide key and text input support. Earlier
versions are not supported. versions are not supported.
GLFW uses the [xdg-shell protocol](https://wayland.app/protocols/xdg-shell) GLFW uses the [xdg-shell][] protocol to provide better window management. This
to provide better window management. This protocol is mandatory for GLFW to protocol is mandatory for GLFW to display a window.
display a window.
GLFW uses the [xdg-shell]: https://wayland.app/protocols/xdg-shell
[relative pointer protocol](https://wayland.app/protocols/relative-pointer-unstable-v1)
alongside the
[pointer constraints protocol](https://wayland.app/protocols/pointer-constraints-unstable-v1)
to implement disabled cursor. If the running compositor does not support both
of these protocols, disabling the cursor will have no effect.
GLFW uses the GLFW uses the [relative-pointer-unstable-v1][] protocol alongside the
[idle inhibit protocol](https://wayland.app/protocols/idle-inhibit-unstable-v1) [pointer-constraints-unstable-v1][] protocol to implement disabled cursor. If
to prohibit the screensaver from starting. If the running compositor does not the running compositor does not support both of these protocols, disabling the
support this protocol, the screensaver may start even for full screen windows. cursor will have no effect.
GLFW uses the [relative-pointer-unstable-v1]: https://wayland.app/protocols/relative-pointer-unstable-v1
[libdecor library](https://gitlab.freedesktop.org/libdecor/libdecor) for window [pointer-constraints-unstable-v1]: https://wayland.app/protocols/pointer-constraints-unstable-v1
decorations, where available. This in turn provides good quality client-side
decorations (drawn by the application) on desktop systems that do not support
server-side decorations (drawn by the window manager). On systems that do not
provide either libdecor or xdg-decoration, very basic window decorations are
provided. These do not include the window title or any caption buttons.
GLFW uses the GLFW uses the [idle-inhibit-unstable-v1][] protocol to prohibit the screensaver
[xdg-decoration protocol](https://wayland.app/protocols/xdg-decoration-unstable-v1) from starting. If the running compositor does not support this protocol, the
to request decorations to be drawn around its windows. This protocol is part screensaver may start even for full screen windows.
of wayland-protocols 1.15, and mandatory at build time. If the running
compositor does not support this protocol, a very simple frame will be drawn by
GLFW itself, using the
[viewporter protocol](https://wayland.app/protocols/viewporter)
alongside subsurfaces. If the running compositor does not support these
protocols either, no decorations will be drawn around windows.
GLFW uses the [xdg-activation [idle-inhibit-unstable-v1]: https://wayland.app/protocols/idle-inhibit-unstable-v1
protocol](https://wayland.app/protocols/xdg-activation-v1)
to implement window focus and attention requests. If the running compositor GLFW uses the [libdecor][] library for window decorations, where available.
does not support this protocol, window focus and attention requests do nothing. This in turn provides good quality client-side decorations (drawn by the
application) on desktop systems that do not support server-side decorations
(drawn by the window manager). On systems that do not provide either libdecor
or xdg-decoration, very basic window decorations are provided. These do not
include the window title or any caption buttons.
[libdecor]: https://gitlab.freedesktop.org/libdecor/libdecor
GLFW uses the [xdg-decoration-unstable-v1][] protocol to request decorations to
be drawn around its windows. This protocol is part of wayland-protocols 1.15,
and mandatory at build time. If the running compositor does not support this
protocol, a very simple frame will be drawn by GLFW itself, using the
[viewporter][] protocol alongside subsurfaces. If the running compositor does
not support these protocols either, no decorations will be drawn around windows.
[xdg-decoration-unstable-v1]: https://wayland.app/protocols/xdg-decoration-unstable-v1
[viewporter]: https://wayland.app/protocols/viewporter
GLFW uses the [xdg-activation-v1][] protocol to implement window focus and
attention requests. If the running compositor does not support this protocol,
window focus and attention requests do nothing.
[xdg-activation-v1]: https://wayland.app/protocols/xdg-activation-v1
## GLX extensions {#compat_glx} ## GLX extensions {#compat_glx}

21
docs/compile.md
View File

@ -19,8 +19,8 @@ GLFW uses [CMake](https://cmake.org/) to generate project files or makefiles
for your chosen development environment. To compile GLFW, first generate these for your chosen development environment. To compile GLFW, first generate these
files with CMake and then use them to compile the GLFW library. files with CMake and then use them to compile the GLFW library.
If you are on Windows and macOS you can If you are on Windows and macOS you can [download
[download CMake](https://cmake.org/download/) from their site. CMake](https://cmake.org/download/) from their site.
If you are on a Unix-like system such as Linux, FreeBSD or Cygwin or have If you are on a Unix-like system such as Linux, FreeBSD or Cygwin or have
a package system like Fink, MacPorts or Homebrew, you can install its CMake a package system like Fink, MacPorts or Homebrew, you can install its CMake
@ -28,9 +28,10 @@ package.
CMake is a complex tool and this guide will only show a few of the possible ways CMake is a complex tool and this guide will only show a few of the possible ways
to set up and compile GLFW. The CMake project has their own much more detailed to set up and compile GLFW. The CMake project has their own much more detailed
[CMake user guide](https://cmake.org/cmake/help/latest/guide/user-interaction/) [CMake user guide][cmake-guide] that includes everything in this guide not
that includes everything in this guide not specific to GLFW. It may be a useful specific to GLFW. It may be a useful companion to this one.
companion to this one.
[cmake-guide]: https://cmake.org/cmake/help/latest/guide/user-interaction/
### Installing dependencies {#compile_deps} ### Installing dependencies {#compile_deps}
@ -263,10 +264,11 @@ __USE_MSVC_RUNTIME_LIBRARY_DLL__ determines whether to use the DLL version or th
static library version of the Visual C++ runtime library. When enabled, the static library version of the Visual C++ runtime library. When enabled, the
DLL version of the Visual C++ library is used. This is enabled by default. DLL version of the Visual C++ library is used. This is enabled by default.
On CMake 3.15 and later you can set the standard CMake On CMake 3.15 and later you can set the standard CMake [CMAKE_MSVC_RUNTIME_LIBRARY][]
[CMAKE_MSVC_RUNTIME_LIBRARY](https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html)
variable instead of this GLFW-specific option. variable instead of this GLFW-specific option.
[CMAKE_MSVC_RUNTIME_LIBRARY]: https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html
@anchor GLFW_USE_HYBRID_HPG @anchor GLFW_USE_HYBRID_HPG
__GLFW_USE_HYBRID_HPG__ determines whether to export the `NvOptimusEnablement` and __GLFW_USE_HYBRID_HPG__ determines whether to export the `NvOptimusEnablement` and
`AmdPowerXpressRequestHighPerformance` symbols, which force the use of the `AmdPowerXpressRequestHighPerformance` symbols, which force the use of the
@ -326,8 +328,9 @@ cmake -S path/to/glfw -B path/to/build -D CMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-
The path to the toolchain file is relative to the path to the GLFW source tree The path to the toolchain file is relative to the path to the GLFW source tree
passed to the `-S` flag, not to the current directory. passed to the `-S` flag, not to the current directory.
For more details see the For more details see the [CMake toolchain guide][cmake-toolchains].
[CMake toolchain guide](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html).
[cmake-toolchains]: https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html
## Compiling GLFW manually {#compile_manual} ## Compiling GLFW manually {#compile_manual}

11
docs/input.md
View File

@ -735,8 +735,10 @@ indication of where they are located on the device. Their order may also vary
between platforms even with the same device. between platforms even with the same device.
To solve this problem the SDL community crowdsourced the To solve this problem the SDL community crowdsourced the
[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) project, [SDL_GameControllerDB][] project, a database of mappings from many different
a database of mappings from many different devices to an Xbox-like gamepad. devices to an Xbox-like gamepad.
[SDL_GameControllerDB]: https://github.com/gabomdq/SDL_GameControllerDB
GLFW supports this mapping format and contains a copy of the mappings GLFW supports this mapping format and contains a copy of the mappings
available at the time of release. See @ref gamepad_mapping for how to update available at the time of release. See @ref gamepad_mapping for how to update
@ -811,9 +813,8 @@ the largest available index for each array.
### Gamepad mappings {#gamepad_mapping} ### Gamepad mappings {#gamepad_mapping}
GLFW contains a copy of the mappings available in GLFW contains a copy of the mappings available in [SDL_GameControllerDB][] at
[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) at the the time of release. Newer ones can be added at runtime with @ref
time of release. Newer ones can be added at runtime with @ref
glfwUpdateGamepadMappings. glfwUpdateGamepadMappings.
```c ```c

14
docs/intro.md
View File

@ -105,14 +105,15 @@ glfwGetJoystickHats. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
@anchor GLFW_ANGLE_PLATFORM_TYPE_hint @anchor GLFW_ANGLE_PLATFORM_TYPE_hint
__GLFW_ANGLE_PLATFORM_TYPE__ specifies the platform type (rendering backend) to __GLFW_ANGLE_PLATFORM_TYPE__ specifies the platform type (rendering backend) to
request when using OpenGL ES and EGL via request when using OpenGL ES and EGL via [ANGLE][]. If the requested platform
[ANGLE](https://chromium.googlesource.com/angle/angle/). If the requested type is unavailable, ANGLE will use its default. Possible values are one of
platform type is unavailable, ANGLE will use its default. Possible values are `GLFW_ANGLE_PLATFORM_TYPE_NONE`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGL`,
one of `GLFW_ANGLE_PLATFORM_TYPE_NONE`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGL`,
`GLFW_ANGLE_PLATFORM_TYPE_OPENGLES`, `GLFW_ANGLE_PLATFORM_TYPE_D3D9`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGLES`, `GLFW_ANGLE_PLATFORM_TYPE_D3D9`,
`GLFW_ANGLE_PLATFORM_TYPE_D3D11`, `GLFW_ANGLE_PLATFORM_TYPE_VULKAN` and `GLFW_ANGLE_PLATFORM_TYPE_D3D11`, `GLFW_ANGLE_PLATFORM_TYPE_VULKAN` and
`GLFW_ANGLE_PLATFORM_TYPE_METAL`. `GLFW_ANGLE_PLATFORM_TYPE_METAL`.
[ANGLE]: https://chromium.googlesource.com/angle/angle/
The ANGLE platform type is specified via the `EGL_ANGLE_platform_angle` The ANGLE platform type is specified via the `EGL_ANGLE_platform_angle`
extension. This extension is not used if this hint is extension. This extension is not used if this hint is
`GLFW_ANGLE_PLATFORM_TYPE_NONE`, which is the default value. `GLFW_ANGLE_PLATFORM_TYPE_NONE`, which is the default value.
@ -145,11 +146,12 @@ the `VK_KHR_xlib_surface` extension. Possible values are `GLFW_TRUE` and
#### Wayland specific init hints {#init_hints_wayland} #### Wayland specific init hints {#init_hints_wayland}
@anchor GLFW_WAYLAND_LIBDECOR_hint @anchor GLFW_WAYLAND_LIBDECOR_hint
__GLFW_WAYLAND_LIBDECOR__ specifies whether to use __GLFW_WAYLAND_LIBDECOR__ specifies whether to use [libdecor][] for window
[libdecor](https://gitlab.freedesktop.org/libdecor/libdecor) for window
decorations where available. Possible values are `GLFW_WAYLAND_PREFER_LIBDECOR` decorations where available. Possible values are `GLFW_WAYLAND_PREFER_LIBDECOR`
and `GLFW_WAYLAND_DISABLE_LIBDECOR`. This is ignored on other platforms. and `GLFW_WAYLAND_DISABLE_LIBDECOR`. This is ignored on other platforms.
[libdecor]: https://gitlab.freedesktop.org/libdecor/libdecor
#### Supported and default values {#init_hints_values} #### Supported and default values {#init_hints_values}

71
docs/moving.md
View File

@ -16,8 +16,9 @@ required to create full screen windows with GLFW 3.
The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to
avoid collisions with the headers of other major versions. Similarly, the GLFW avoid collisions with the headers of other major versions. Similarly, the GLFW
3 library is named `glfw3,` except when it's installed as a shared library on 3 library is named `glfw3,` except when it's installed as a shared library on
Unix-like systems, where it uses the Unix-like systems, where it uses the [soname][] `libglfw.so.3`.
[soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`.
[soname]: https://en.wikipedia.org/wiki/soname
__Old syntax__ __Old syntax__
```c ```c
@ -36,18 +37,20 @@ The threading functions have been removed, including the per-thread sleep
function. They were fairly primitive, under-used, poorly integrated and took function. They were fairly primitive, under-used, poorly integrated and took
time away from the focus of GLFW (i.e. context, input and window). There are time away from the focus of GLFW (i.e. context, input and window). There are
better threading libraries available and native threading support is available better threading libraries available and native threading support is available
in both [C++11](https://en.cppreference.com/w/cpp/thread) and in both [C++11][] and [C11][], both of which are gaining traction.
[C11](https://en.cppreference.com/w/c/thread), both of which are gaining
traction. [C++11]: https://en.cppreference.com/w/cpp/thread
[C11]: https://en.cppreference.com/w/c/thread
If you wish to use the C++11 or C11 facilities but your compiler doesn't yet If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
support them, see the support them, see the [TinyThread++][] and [TinyCThread][] projects created by
[TinyThread++](https://gitorious.org/tinythread/tinythreadpp) and
[TinyCThread](https://github.com/tinycthread/tinycthread) projects created by
the original author of GLFW. These libraries implement a usable subset of the the original author of GLFW. These libraries implement a usable subset of the
threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
TinyCThread. TinyCThread.
[TinyThread++]: https://gitorious.org/tinythread/tinythreadpp
[TinyCThread]: https://github.com/tinycthread/tinycthread
However, GLFW 3 has better support for _use from multiple threads_ than GLFW However, GLFW 3 has better support for _use from multiple threads_ than GLFW
2 had. Contexts can be made current on any thread, although only a single 2 had. Contexts can be made current on any thread, although only a single
thread at a time, and the documentation explicitly states which functions may be thread at a time, and the documentation explicitly states which functions may be
@ -84,13 +87,14 @@ __Removed functions__
### Removal of GLFWCALL macro {#moving_stdcall} ### Removal of GLFWCALL macro {#moving_stdcall}
The `GLFWCALL` macro, which made callback functions use The `GLFWCALL` macro, which made callback functions use [\_\_stdcall][stdcall]
[\_\_stdcall](https://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows, on Windows, has been removed. GLFW is written in C, not Pascal. Removing this
has been removed. GLFW is written in C, not Pascal. Removing this macro means macro means there's one less thing for application programmers to remember, i.e.
there's one less thing for application programmers to remember, i.e. the the requirement to mark all callback functions with `GLFWCALL`. It also
requirement to mark all callback functions with `GLFWCALL`. It also simplifies simplifies the creation of DLLs and DLL link libraries, as there's no need to
the creation of DLLs and DLL link libraries, as there's no need to explicitly explicitly disable `@n` entry point suffixes.
disable `@n` entry point suffixes.
[stdcall]: https://msdn.microsoft.com/en-us/library/zxk0tw93.aspx
__Old syntax__ __Old syntax__
```c ```c
@ -109,7 +113,9 @@ Because GLFW 3 supports multiple windows, window handle parameters have been
added to all window-related GLFW functions and callbacks. The handle of added to all window-related GLFW functions and callbacks. The handle of
a newly created window is returned by @ref glfwCreateWindow (formerly a newly created window is returned by @ref glfwCreateWindow (formerly
`glfwOpenWindow`). Window handles are pointers to the `glfwOpenWindow`). Window handles are pointers to the
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWwindow. [opaque][opaque-type] type @ref GLFWwindow.
[opaque-type]: https://en.wikipedia.org/wiki/Opaque_data_type
__Old syntax__ __Old syntax__
```c ```c
@ -129,7 +135,7 @@ instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
window to use. The @ref glfwGetPrimaryMonitor function returns the monitor that window to use. The @ref glfwGetPrimaryMonitor function returns the monitor that
GLFW 2 would have selected, but there are many other GLFW 2 would have selected, but there are many other
[monitor functions](@ref monitor_guide). Monitor handles are pointers to the [monitor functions](@ref monitor_guide). Monitor handles are pointers to the
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWmonitor. [opaque][opaque-type] type @ref GLFWmonitor.
__Old basic full screen__ __Old basic full screen__
```c ```c
@ -376,14 +382,15 @@ glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions.
### Win32 MBCS support {#moving_mbcs} ### Win32 MBCS support {#moving_mbcs}
The Win32 port of GLFW 3 will not compile in The Win32 port of GLFW 3 will not compile in [MBCS mode][MBCS]. However,
[MBCS mode](https://msdn.microsoft.com/en-us/library/5z097dxa.aspx). because the use of the Unicode version of the Win32 API doesn't affect the
However, because the use of the Unicode version of the Win32 API doesn't affect process as a whole, but only those windows created using it, it's perfectly
the process as a whole, but only those windows created using it, it's perfectly
possible to call MBCS functions from other parts of the same application. possible to call MBCS functions from other parts of the same application.
Therefore, even if an application using GLFW has MBCS mode code, there's no need Therefore, even if an application using GLFW has MBCS mode code, there's no need
for GLFW itself to support it. for GLFW itself to support it.
[MBCS]: https://msdn.microsoft.com/en-us/library/5z097dxa.aspx
### Support for versions of Windows older than XP {#moving_windows} ### Support for versions of Windows older than XP {#moving_windows}
@ -429,10 +436,12 @@ invalidating any window handles you may still have.
### GLU header inclusion {#moving_glu} ### GLU header inclusion {#moving_glu}
GLFW 3 does not by default include the GLU header and GLU itself has been GLFW 3 does not by default include the GLU header and GLU itself has been
deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). __New deprecated by [Khronos][]. __New projects should not use GLU__, but if you need
projects should not use GLU__, but if you need it for legacy code that it for legacy code that has been moved to GLFW 3, you can request that the GLFW
has been moved to GLFW 3, you can request that the GLFW header includes it by header includes it by defining @ref GLFW_INCLUDE_GLU before the inclusion of the
defining @ref GLFW_INCLUDE_GLU before the inclusion of the GLFW header. GLFW header.
[Khronos]: https://en.wikipedia.org/wiki/Khronos_Group
__Old syntax__ __Old syntax__
```c ```c
@ -446,11 +455,13 @@ __New syntax__
``` ```
There are many libraries that offer replacements for the functionality offered There are many libraries that offer replacements for the functionality offered
by GLU. For the matrix helper functions, see math libraries like by GLU. For the matrix helper functions, see math libraries like [GLM][] (for
[GLM](https://github.com/g-truc/glm) (for C++), C++), [linmath.h][] (for C) and others. For the tessellation functions, see for
[linmath.h](https://github.com/datenwolf/linmath.h) (for C) and others. For the example [libtess2][].
tessellation functions, see for example
[libtess2](https://github.com/memononen/libtess2). [GLM]: https://github.com/g-truc/glm
[linmath.h]: https://github.com/datenwolf/linmath.h
[libtess2]: https://github.com/memononen/libtess2
## Name change tables {#moving_tables} ## Name change tables {#moving_tables}

5
docs/news.md
View File

@ -61,10 +61,11 @@ GLFW now supports specifying the app_id for a Wayland window using the
GLFW now provides the GLFW now provides the
[GLFW_ANGLE_PLATFORM_TYPE](@ref GLFW_ANGLE_PLATFORM_TYPE_hint) init hint for [GLFW_ANGLE_PLATFORM_TYPE](@ref GLFW_ANGLE_PLATFORM_TYPE_hint) init hint for
requesting a specific rendering backend when using requesting a specific rendering backend when using [ANGLE][] to create OpenGL ES
[ANGLE](https://chromium.googlesource.com/angle/angle/) to create OpenGL ES
contexts. contexts.
[ANGLE]: https://chromium.googlesource.com/angle/angle/
#### Captured cursor mode {#captured_cursor_34} #### Captured cursor mode {#captured_cursor_34}

5
docs/quick.md
View File

@ -336,13 +336,14 @@ presses _Escape_ or closes the window.
@snippet triangle-opengl.c code @snippet triangle-opengl.c code
The program above can be found in the The program above can be found in the [source package][download] as
[source package](https://www.glfw.org/download.html) as
`examples/triangle-opengl.c` and is compiled along with all other examples when `examples/triangle-opengl.c` and is compiled along with all other examples when
you build GLFW. If you built GLFW from the source package then you already have you build GLFW. If you built GLFW from the source package then you already have
this as `triangle-opengl.exe` on Windows, `triangle-opengl` on Linux or this as `triangle-opengl.exe` on Windows, `triangle-opengl` on Linux or
`triangle-opengl.app` on macOS. `triangle-opengl.app` on macOS.
[download]: https://www.glfw.org/download.html
This tutorial used only a few of the many functions GLFW provides. There are This tutorial used only a few of the many functions GLFW provides. There are
guides for each of the areas covered by GLFW. Each guide will introduce all the guides for each of the areas covered by GLFW. Each guide will introduce all the
functions for that category. functions for that category.

15
docs/window.md
View File

@ -406,8 +406,9 @@ mode, which may provide additional error and diagnostic reporting functionality.
Possible values are `GLFW_TRUE` and `GLFW_FALSE`. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
Debug contexts for OpenGL and OpenGL ES are described in detail by the Debug contexts for OpenGL and OpenGL ES are described in detail by the
[GL_KHR_debug](https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_debug.txt) [GL_KHR_debug][] extension.
extension.
[GL_KHR_debug]: https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_debug.txt
@note `GLFW_CONTEXT_DEBUG` is the new name introduced in GLFW 3.4. The older @note `GLFW_CONTEXT_DEBUG` is the new name introduced in GLFW 3.4. The older
`GLFW_OPENGL_DEBUG_CONTEXT` name is also available for compatibility. `GLFW_OPENGL_DEBUG_CONTEXT` name is also available for compatibility.
@ -440,8 +441,9 @@ current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
not be flushed on release. not be flushed on release.
Context release behaviors are described in detail by the Context release behaviors are described in detail by the
[GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt) [GL_KHR_context_flush_control][] extension.
extension.
[GL_KHR_context_flush_control]: https://www.opengl.org/registry/specs/KHR/context_flush_control.txt
@anchor GLFW_CONTEXT_NO_ERROR_hint @anchor GLFW_CONTEXT_NO_ERROR_hint
__GLFW_CONTEXT_NO_ERROR__ specifies whether errors should be generated by the __GLFW_CONTEXT_NO_ERROR__ specifies whether errors should be generated by the
@ -449,8 +451,9 @@ context. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. If enabled,
situations that would have generated errors instead cause undefined behavior. situations that would have generated errors instead cause undefined behavior.
The no error mode for OpenGL and OpenGL ES is described in detail by the The no error mode for OpenGL and OpenGL ES is described in detail by the
[GL_KHR_no_error](https://www.opengl.org/registry/specs/KHR/no_error.txt) [GL_KHR_no_error][] extension.
extension.
[GL_KHR_no_error]: https://www.opengl.org/registry/specs/KHR/no_error.txt
#### Win32 specific hints {#window_hints_win32} #### Win32 specific hints {#window_hints_win32}

27
include/GLFW/glfw3.h
View File

@ -2648,9 +2648,10 @@ GLFWAPI void glfwGetMonitorWorkarea(GLFWmonitor* monitor, int* xpos, int* ypos,
* specified monitor. * specified monitor.
* *
* Some platforms do not provide accurate monitor size information, either * Some platforms do not provide accurate monitor size information, either
* because the monitor * because the monitor [EDID][] data is incorrect or because the driver does
* [EDID](https://en.wikipedia.org/wiki/Extended_display_identification_data) * not report it accurately.
* data is incorrect or because the driver does not report it accurately. *
* [EDID]: https://en.wikipedia.org/wiki/Extended_display_identification_data
* *
* Any or all of the size arguments may be `NULL`. If an error occurs, all * Any or all of the size arguments may be `NULL`. If an error occurs, all
* non-`NULL` size arguments will be set to zero. * non-`NULL` size arguments will be set to zero.
@ -3160,18 +3161,21 @@ GLFWAPI void glfwWindowHintString(int hint, const char* value);
* @remark @macos The GLFW window has no icon, as it is not a document * @remark @macos The GLFW window has no icon, as it is not a document
* window, but the dock icon will be the same as the application bundle's icon. * window, but the dock icon will be the same as the application bundle's icon.
* For more information on bundles, see the * For more information on bundles, see the
* [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) * [Bundle Programming Guide][bundle-guide] in the Mac Developer Library.
* in the Mac Developer Library. *
* [bundle-guide]: https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/
* *
* @remark @macos On OS X 10.10 and later the window frame will not be rendered * @remark @macos On OS X 10.10 and later the window frame will not be rendered
* at full resolution on Retina displays unless the * at full resolution on Retina displays unless the
* [GLFW_COCOA_RETINA_FRAMEBUFFER](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint) * [GLFW_COCOA_RETINA_FRAMEBUFFER](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint)
* hint is `GLFW_TRUE` and the `NSHighResolutionCapable` key is enabled in the * hint is `GLFW_TRUE` and the `NSHighResolutionCapable` key is enabled in the
* application bundle's `Info.plist`. For more information, see * application bundle's `Info.plist`. For more information, see
* [High Resolution Guidelines for OS X](https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html) * [High Resolution Guidelines for OS X][hidpi-guide] in the Mac Developer
* in the Mac Developer Library. The GLFW test and example programs use * Library. The GLFW test and example programs use a custom `Info.plist`
* a custom `Info.plist` template for this, which can be found as * template for this, which can be found as `CMake/Info.plist.in` in the source
* `CMake/Info.plist.in` in the source tree. * tree.
*
* [hidpi-guide]: https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html
* *
* @remark @macos When activating frame autosaving with * @remark @macos When activating frame autosaving with
* [GLFW_COCOA_FRAME_NAME](@ref GLFW_COCOA_FRAME_NAME_hint), the specified * [GLFW_COCOA_FRAME_NAME](@ref GLFW_COCOA_FRAME_NAME_hint), the specified
@ -3345,8 +3349,9 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title);
* @remark @macos Regular windows do not have icons on macOS. This function * @remark @macos Regular windows do not have icons on macOS. This function
* will emit @ref GLFW_FEATURE_UNAVAILABLE. The dock icon will be the same as * will emit @ref GLFW_FEATURE_UNAVAILABLE. The dock icon will be the same as
* the application bundle's icon. For more information on bundles, see the * the application bundle's icon. For more information on bundles, see the
* [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) * [Bundle Programming Guide][bundle-guide] in the Mac Developer Library.
* in the Mac Developer Library. *
* [bundle-guide]: https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/
* *
* @remark @wayland There is no existing protocol to change an icon, the * @remark @wayland There is no existing protocol to change an icon, the
* window will thus inherit the one defined in the application's desktop file. * window will thus inherit the one defined in the application's desktop file.