AuroraMiddleware/glfw
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[-] GLFW specific docs

Browse Source
This commit is contained in:
Reece Wilson 2023-11-05 00:08:55 +00:00
parent 15a7f24fb8
commit 289d8c67c6
4 changed files with 0 additions and 1035 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

391
docs/CONTRIBUTING.md
View File

@ -1,391 +0,0 @@
# Contribution Guide
## Contents
- [Asking a question](#asking-a-question)
- [Reporting a bug](#reporting-a-bug)
- [Reporting a compile or link bug](#reporting-a-compile-or-link-bug)
- [Reporting a segfault or other crash bug](#reporting-a-segfault-or-other-crash-bug)
- [Reporting a context creation bug](#reporting-a-context-creation-bug)
- [Reporting a monitor or video mode bug](#reporting-a-monitor-or-video-mode-bug)
- [Reporting a window, input or event bug](#reporting-a-window-input-or-event-bug)
- [Reporting some other library bug](#reporting-some-other-library-bug)
- [Reporting a documentation bug](#reporting-a-documentation-bug)
- [Reporting a website bug](#reporting-a-website-bug)
- [Requesting a feature](#requesting-a-feature)
- [Contributing a bug fix](#contributing-a-bug-fix)
- [Contributing a feature](#contributing-a-feature)
## Asking a question
Questions about how to use GLFW should be asked either in the [support
section](https://discourse.glfw.org/c/support) of the forum, under the [Stack
Overflow tag](https://stackoverflow.com/questions/tagged/glfw) or [Game
Development tag](https://gamedev.stackexchange.com/questions/tagged/glfw) on
Stack Exchange or in the IRC channel `#glfw` on
[Libera.Chat](https://libera.chat/).
Questions about the design or implementation of GLFW or about future plans
should be asked in the [dev section](https://discourse.glfw.org/c/dev) of the
forum or in the IRC channel. Please don't open a GitHub issue to discuss design
questions without first checking with a maintainer.
## Reporting a bug
If GLFW is behaving unexpectedly at run-time, start by setting an [error
callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling).
GLFW will often tell you the cause of an error via this callback. If it
doesn't, that might be a separate bug.
If GLFW is crashing or triggering asserts, make sure that all your object
handles and other pointers are valid.
For bugs where it makes sense, a short, self contained example is absolutely
invaluable. Just put it inline in the body text. Note that if the bug is
reproducible with one of the test programs that come with GLFW, just mention
that instead.
__Don't worry about adding too much information__. Unimportant information can
be abbreviated or removed later, but missing information can stall bug fixing,
especially when your schedule doesn't align with that of the maintainer.
__Please provide text as text, not as images__. This includes code, error
messages and any other text. Text in images cannot be found by other users
searching for the same problem and may have to be re-typed by maintainers when
debugging.
You don't need to manually indent your code or other text to quote it with
GitHub Markdown; just surround it with triple backticks:
```
Some quoted text.
```
You can also add syntax highlighting by appending the common file extension:
```c
int five(void)
{
return 5;
}
```
There are issue labels for both platforms and GPU manufacturers, so there is no
need to mention these in the subject line. If you do, it will be removed when
the issue is labeled.
If your bug is already reported, please add any new information you have, or if
it already has everything, give it a :+1:.
### Reporting a compile or link bug
__Note:__ GLFW needs many system APIs to do its job, which on some platforms
means linking to many system libraries. If you are using GLFW as a static
library, that means your application needs to link to these in addition to GLFW.
__Note:__ Check the [Compiling
GLFW](https://www.glfw.org/docs/latest/compile.html) guide and or [Building
applications](https://www.glfw.org/docs/latest/build.html) guide for before
opening an issue of this kind. Most issues are caused by a missing package or
linker flag.
Always include the __operating system name and version__ (e.g. `Windows
7 64-bit` or `Ubuntu 15.10`) and the __compiler name and version__ (e.g. `Visual
C++ 2015 Update 2`). If you are using an official release of GLFW,
include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the
__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
Please also include the __complete build log__ from your compiler and linker,
even if it's long. It can always be shortened later, if necessary.
#### Quick template
```
OS and version:
Compiler version:
Release or commit:
Build log:
```
### Reporting a segfault or other crash bug
Always include the __operating system name and version__ (e.g. `Windows
7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW,
include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the
__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
Please also include any __error messages__ provided to your application via the
[error
callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling) and
the __full call stack__ of the crash, or if the crash does not occur in debug
mode, mention that instead.
#### Quick template
```
OS and version:
Release or commit:
Error messages:
Call stack:
```
### Reporting a context creation bug
__Note:__ Windows ships with graphics drivers that do not support OpenGL. If
GLFW says that your machine lacks support for OpenGL, it very likely does.
Install drivers from the computer manufacturer or graphics card manufacturer
([Nvidia](https://www.geforce.com/drivers),
[AMD](https://www.amd.com/en/support),
[Intel](https://www-ssl.intel.com/content/www/us/en/support/detect.html)) to
fix this.
__Note:__ AMD only supports OpenGL ES on Windows via EGL. See the
[GLFW\_CONTEXT\_CREATION\_API](https://www.glfw.org/docs/latest/window_guide.html#window_hints_ctx)
hint for how to select EGL.
Please verify that context creation also fails with the `glfwinfo` tool before
reporting it as a bug. This tool is included in the GLFW source tree as
`tests/glfwinfo.c` and is built along with the library. It has switches for all
GLFW context and framebuffer hints. Run `glfwinfo -h` for a complete list.
Always include the __operating system name and version__ (e.g. `Windows
7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW,
include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the
__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
If you are running your program in a virtual machine, please mention this and
include the __VM name and version__ (e.g. `VirtualBox 5.1`).
Please also include the __GLFW version string__ (`3.2.0 X11 EGL clock_gettime
/dev/js`), as described
[here](https://www.glfw.org/docs/latest/intro.html#intro_version_string), the
__GPU model and driver version__ (e.g. `GeForce GTX660 with 352.79`), and the
__output of `glfwinfo`__ (with switches matching any hints you set in your
code) when reporting this kind of bug. If this tool doesn't run on the machine,
mention that instead.
#### Quick template
```
OS and version:
GPU and driver:
Release or commit:
Version string:
glfwinfo output:
```
### Reporting a monitor or video mode bug
__Note:__ On headless systems on some platforms, no monitors are reported. This
causes glfwGetPrimaryMonitor to return `NULL`, which not all applications are
prepared for.
__Note:__ Some third-party tools report more video modes than are approved of
by the OS. For safety and compatibility, GLFW only reports video modes the OS
wants programs to use. This is not a bug.
The `monitors` tool is included in the GLFW source tree as `tests/monitors.c`
and is built along with the library. It lists all information GLFW provides
about monitors it detects.
Always include the __operating system name and version__ (e.g. `Windows
7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW,
include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the
__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
If you are running your program in a virtual machine, please mention this and
include the __VM name and version__ (e.g. `VirtualBox 5.1`).
Please also include any __error messages__ provided to your application via the
[error
callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling) and
the __output of `monitors`__ when reporting this kind of bug. If this tool
doesn't run on the machine, mention this instead.
#### Quick template
```
OS and version:
Release or commit:
Error messages:
monitors output:
```
### Reporting a window, input or event bug
__Note:__ The exact ordering of related window events will sometimes differ.
__Note:__ Window moving and resizing (by the user) will block the main thread on
some platforms. This is not a bug. Set a [refresh
callback](https://www.glfw.org/docs/latest/window.html#window_refresh) if you
want to keep the window contents updated during a move or size operation.
The `events` tool is included in the GLFW source tree as `tests/events.c` and is
built along with the library. It prints all information provided to every
callback supported by GLFW as events occur. Each event is listed with the time
and a unique number to make discussions about event logs easier. The tool has
command-line options for creating multiple windows and full screen windows.
Always include the __operating system name and version__ (e.g. `Windows
7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW,
include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the
__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
If you are running your program in a virtual machine, please mention this and
include the __VM name and version__ (e.g. `VirtualBox 5.1`).
Please also include any __error messages__ provided to your application via the
[error
callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling) and
if relevant, the __output of `events`__ when reporting this kind of bug. If
this tool doesn't run on the machine, mention this instead.
__X11:__ If possible, please include what desktop environment (e.g. GNOME,
Unity, KDE) and/or window manager (e.g. Openbox, dwm, Window Maker) you are
running. If the bug is related to keyboard input, please include any input
method (e.g. ibus, SCIM) you are using.
#### Quick template
```
OS and version:
Release or commit:
Error messages:
events output:
```
### Reporting some other library bug
Always include the __operating system name and version__ (e.g. `Windows
7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW,
include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the
__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
Please also include any __error messages__ provided to your application via the
[error
callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling), if
relevant.
#### Quick template
```
OS and version:
Release or commit:
Error messages:
```
### Reporting a documentation bug
If you found a bug in the documentation, including this file, then it's fine to
just link to that web page or mention that source file. You don't need to match
the source to the output or vice versa.
### Reporting a website bug
If the bug is in the documentation (anything under `/docs/`) then please see the
section above. Bugs in the rest of the site are reported to the [website
source repository](https://github.com/glfw/website/issues).
## Requesting a feature
Please explain why you need the feature and how you intend to use it. If you
have a specific API design in mind, please add that as well. If you have or are
planning to write code for the feature, see the section below.
If there already is a request for the feature you need, add your specific use
case unless it is already mentioned. If it is, give it a :+1:.
## Contributing a bug fix
__Note:__ You must have all necessary [intellectual
property rights](https://en.wikipedia.org/wiki/Intellectual_property) to any
code you contribute. If you did not write the code yourself, you must explain
where it came from and under what license you received it. Even code using the
same license as GLFW may not be copied without attribution.
__There is no preferred patch size__. A one character fix is just as welcome as
a thousand line one, if that is the appropriate size for the fix.
In addition to the code, a complete bug fix includes:
- Change log entry in `README.md`, describing the incorrect behavior
- Credits entries for all authors of the bug fix
Bug fixes will not be rejected because they don't include all the above parts,
but please keep in mind that maintainer time is finite and that there are many
other bugs and features to work on.
If the patch fixes a bug introduced after the last release, it should not get
a change log entry.
If you haven't already, read the excellent article [How to Write a Git Commit
Message](https://chris.beams.io/posts/git-commit/).
## Contributing a feature
__Note:__ You must have all necessary rights to any code you contribute. If you
did not write the code yourself, you must explain where it came from and under
what license. Even code using the same license as GLFW may not be copied
without attribution.
__Note:__ If you haven't already implemented the feature, check first if there
already is an open issue for it and if it's already being developed in an
[experimental branch](https://github.com/glfw/glfw/branches/all).
__There is no preferred patch size__. A one-character change is just as welcome
as one adding a thousand lines, if that is the appropriate size for the
feature.
In addition to the code, a complete feature includes:
- Change log entry in `README.md`, listing all new symbols
- News page entry, briefly describing the feature
- Guide documentation, with minimal examples, in the relevant guide
- Reference documentation, with all applicable tags
- Cross-references and mentions in appropriate places
- Credits entries for all authors of the feature
If the feature requires platform-specific code, at minimum stubs must be added
for the new platform function to all supported and experimental platforms.
If it adds a new callback, support for it must be added to `tests/event.c`.
If it adds a new monitor property, support for it must be added to
`tests/monitor.c`.
If it adds a new OpenGL, OpenGL ES or Vulkan option or extension, support
for it must be added to `tests/glfwinfo.c` and the behavior of the library when
the extension is missing documented in `docs/compat.dox`.
If you haven't already, read the excellent article [How to Write a Git Commit
Message](https://chris.beams.io/posts/git-commit/).
Features will not be rejected because they don't include all the above parts,
but please keep in mind that maintainer time is finite and that there are many
other features and bugs to work on.
Please also keep in mind that any part of the public API that has been included
in a release cannot be changed until the next _major_ version. Features can be
added and existing parts can sometimes be overloaded (in the general sense of
doing more things, not in the C++ sense), but code written to the API of one
minor release should both compile and run on subsequent minor releases.

14
docs/SUPPORT.md
View File

@ -1,14 +0,0 @@
# Support resources
See the [latest documentation](https://www.glfw.org/docs/latest/) for tutorials,
guides and the API reference.
If you have questions about using GLFW, we have a
[forum](https://discourse.glfw.org/), and the `#glfw` IRC channel on
[Libera.Chat](https://libera.chat/).
Bugs are reported to our [issue tracker](https://github.com/glfw/glfw/issues).
Please check the [contribution
guide](https://github.com/glfw/glfw/blob/master/docs/CONTRIBUTING.md) for
information on what to include when reporting a bug.

338
docs/build.dox
View File

@ -1,338 +0,0 @@
/*!
@page build_guide Building applications
@tableofcontents
This is about compiling and linking applications that use GLFW. For information on
how to write such applications, start with the
[introductory tutorial](@ref quick_guide). For information on how to compile
the GLFW library itself, see @ref compile_guide.
This is not a tutorial on compilation or linking. It assumes basic
understanding of how to compile and link a C program as well as how to use the
specific compiler of your chosen development environment. The compilation
and linking process should be explained in your C programming material and in
the documentation for your development environment.
@section build_include Including the GLFW header file
You should include the GLFW header in the source files where you use OpenGL or
GLFW.
@code
#include <GLFW/glfw3.h>
@endcode
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 that it can be included without needing any window system headers.
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:
- 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. 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
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 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
#include <GLFW/glfw3.h>
#include <glad/gl.h>
@endcode
@subsection build_macros GLFW header option macros
These macros may be defined before the inclusion of the GLFW header and affect
its behavior.
@anchor GLFW_DLL
__GLFW_DLL__ is required on Windows when using the GLFW DLL, to tell the
compiler that the GLFW functions are defined in a DLL.
The following macros control which OpenGL or OpenGL ES API header is included.
Only one of these may be defined at a time.
@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
SDK, and most of them can be downloaded from the
[Khronos Registry](https://www.khronos.org/registry/).
@anchor GLFW_INCLUDE_GLCOREARB
__GLFW_INCLUDE_GLCOREARB__ makes the GLFW header include the modern
`GL/glcorearb.h` header (`OpenGL/gl3.h` on macOS) instead of the regular OpenGL
header.
@anchor GLFW_INCLUDE_ES1
__GLFW_INCLUDE_ES1__ makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
header instead of the regular OpenGL header.
@anchor GLFW_INCLUDE_ES2
__GLFW_INCLUDE_ES2__ makes the GLFW header include the OpenGL ES 2.0
`GLES2/gl2.h` header instead of the regular OpenGL header.
@anchor GLFW_INCLUDE_ES3
__GLFW_INCLUDE_ES3__ makes the GLFW header include the OpenGL ES 3.0
`GLES3/gl3.h` header instead of the regular OpenGL header.
@anchor GLFW_INCLUDE_ES31
__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_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
__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, 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
above macros.
@anchor GLFW_INCLUDE_VULKAN
__GLFW_INCLUDE_VULKAN__ makes the GLFW header include the Vulkan
`vulkan/vulkan.h` header in addition to any selected OpenGL or OpenGL ES header.
@anchor GLFW_INCLUDE_GLEXT
__GLFW_INCLUDE_GLEXT__ makes the GLFW header include the appropriate extension
header for the OpenGL or OpenGL ES header selected above after and in addition
to that header.
@anchor GLFW_INCLUDE_GLU
__GLFW_INCLUDE_GLU__ makes the header include the GLU header in addition to the
header selected above. This should only be used with the standard OpenGL header
and only for compatibility with legacy code. GLU has been deprecated and should
not be used in new code.
@note None of these macros may be defined during the compilation of GLFW itself.
If your build includes GLFW and you define any these in your build files, make
sure they are not applied to the GLFW sources.
@section build_link Link with the right libraries
GLFW is essentially a wrapper of various platform-specific APIs and therefore
needs to link against many different system libraries. If you are using GLFW as
a shared library / dynamic library / DLL then it takes care of these links.
However, if you are using GLFW as a static library then your executable will
need to link against these libraries.
On Windows and macOS, the list of system libraries is static and can be
hard-coded into your build environment. See the section for your development
environment below. On Linux and other Unix-like operating systems, the list
varies but can be retrieved in various ways as described below.
A good general introduction to linking is
[Beginner's Guide to Linkers](https://www.lurklurk.org/linkers/linkers.html) by
David Drysdale.
@subsection build_link_win32 With MinGW or Visual C++ on Windows
The static version of the GLFW library is named `glfw3`. When using this
version, it is also necessary to link with some libraries that GLFW uses.
When using MinGW to link an application with the static version of GLFW, you
must also explicitly link with `gdi32`. Other toolchains including MinGW-w64
include it in the set of default libraries along with other dependencies like
`user32` and `kernel32`.
The link library for the GLFW DLL is named `glfw3dll`. When compiling an
application that uses the DLL version of GLFW, you need to define the @ref
GLFW_DLL macro _before_ any inclusion of the GLFW header. This can be done
either with a compiler switch or by defining it in your source code.
@subsection build_link_cmake_source With CMake and GLFW source
This section is about using CMake to compile and link GLFW along with your
application. If you want to use an installed binary instead, see @ref
build_link_cmake_package.
With a few changes to your `CMakeLists.txt` you can have the GLFW source tree
built along with your application.
Add the root directory of the GLFW source tree to your project. This will add
the `glfw` target to your project.
@code{.cmake}
add_subdirectory(path/to/glfw)
@endcode
Once GLFW has been added, link your application against the `glfw` target.
This adds the GLFW library and its link-time dependencies as it is currently
configured, the include directory for the GLFW header and, when applicable, the
@ref GLFW_DLL macro.
@code{.cmake}
target_link_libraries(myapp glfw)
@endcode
Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL,
OpenGL ES or Vulkan libraries it needs at runtime. If your application calls
OpenGL directly, instead of using a modern
[extension loader library](@ref context_glext_auto), use the OpenGL CMake
package.
@code{.cmake}
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 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
This section is about using CMake to link GLFW after it has been built and
installed. If you want to build it along with your application instead, see
@ref build_link_cmake_source.
With a few changes to your `CMakeLists.txt` you can locate the package and
target files generated when GLFW is installed.
@code{.cmake}
find_package(glfw3 3.4 REQUIRED)
@endcode
Once GLFW has been added to the project, link against it with the `glfw` target.
This adds the GLFW library and its link-time dependencies, the include directory
for the GLFW header and, when applicable, the @ref GLFW_DLL macro.
@code{.cmake}
target_link_libraries(myapp glfw)
@endcode
Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL,
OpenGL ES or Vulkan libraries it needs at runtime. If your application calls
OpenGL directly, instead of using a modern
[extension loader library](@ref context_glext_auto), use the OpenGL CMake
package.
@code{.cmake}
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 any other library.
@code{.cmake}
target_link_libraries(myapp OpenGL::GL)
@endcode
@subsection build_link_pkgconfig With makefiles and pkg-config on Unix
GLFW supports [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/),
and the `glfw3.pc` pkg-config file is generated when the GLFW library is built
and is installed along with it. A pkg-config file describes all necessary
compile-time and link-time flags and dependencies needed to use a library. When
they are updated or if they differ between systems, you will get the correct
ones automatically.
A typical compile and link command-line when using the static version of the
GLFW library may look like this:
@code{.sh}
cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --static --libs glfw3)
@endcode
If you are using the shared version of the GLFW library, omit the `--static`
flag.
@code{.sh}
cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3)
@endcode
You can also use the `glfw3.pc` file without installing it first, by using the
`PKG_CONFIG_PATH` environment variable.
@code{.sh}
env PKG_CONFIG_PATH=path/to/glfw/src cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3)
@endcode
The dependencies do not include OpenGL, as GLFW loads any OpenGL, OpenGL ES or
Vulkan libraries it needs at runtime. If your application calls OpenGL
directly, instead of using a modern
[extension loader library](@ref context_glext_auto), you should add the `gl`
pkg-config package.
@code{.sh}
cc $(pkg-config --cflags glfw3 gl) -o myprog myprog.c $(pkg-config --libs glfw3 gl)
@endcode
@subsection build_link_xcode With Xcode on macOS
If you are using the dynamic library version of GLFW, add it to the project
dependencies.
If you are using the static library version of GLFW, add it and the Cocoa,
OpenGL and IOKit frameworks to the project as dependencies. They can all be
found in `/System/Library/Frameworks`.
@subsection build_link_osx With command-line on macOS
It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when
building from the command line on macOS. That way you will get any new
dependencies added automatically. If you still wish to build manually, you need
to add the required frameworks and libraries to your command-line yourself using
the `-l` and `-framework` switches.
If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do:
@code{.sh}
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit
@endcode
If you are using the static library, named `libglfw3.a`, substitute `-lglfw3`
for `-lglfw`.
Note that you do not add the `.framework` extension to a framework when linking
against it from the command-line.
@note Your machine may have `libGL.*.dylib` style OpenGL library, but that is
for the X Window System and will not work with the macOS native version of GLFW.
*/

292
docs/news.dox
View File

@ -1,292 +0,0 @@
/*!
@page news Release notes
@tableofcontents
@section news_34 Release notes for version 3.4
@subsection features_34 New features in version 3.4
@subsubsection runtime_platform_34 Runtime platform selection
GLFW now supports being compiled for multiple backends and selecting between
them at runtime with the @ref GLFW_PLATFORM init hint. After initialization the
selected platform can be queried with @ref glfwGetPlatform. You can check if
support for a given platform is compiled in with @ref glfwPlatformSupported.
@subsubsection standard_cursors_34 More standard cursors
GLFW now provides the standard cursor shapes @ref GLFW_RESIZE_NWSE_CURSOR and
@ref GLFW_RESIZE_NESW_CURSOR for diagonal resizing, @ref GLFW_RESIZE_ALL_CURSOR
for omnidirectional resizing and @ref GLFW_NOT_ALLOWED_CURSOR for showing an
action is not allowed.
Unlike the original set, these shapes may not be available everywhere and
creation will then fail with the new @ref GLFW_CURSOR_UNAVAILABLE error.
The cursors for horizontal and vertical resizing are now referred to as @ref
GLFW_RESIZE_EW_CURSOR and @ref GLFW_RESIZE_NS_CURSOR, and the pointing hand
cursor is now referred to as @ref GLFW_POINTING_HAND_CURSOR. The older names
are still available.
For more information see @ref cursor_standard.
@subsubsection mouse_passthrough_34 Mouse event passthrough
GLFW now provides the [GLFW_MOUSE_PASSTHROUGH](@ref GLFW_MOUSE_PASSTHROUGH_hint)
window hint for making a window transparent to mouse input, lettings events pass
to whatever window is behind it. This can also be changed after window
creation with the matching [window attribute](@ref GLFW_MOUSE_PASSTHROUGH_attrib).
@subsubsection wayland_libdecor_34 Wayland libdecor decorations
GLFW now supports improved fallback window decorations via
[libdecor](https://gitlab.freedesktop.org/libdecor/libdecor).
Support for libdecor can be toggled before GLFW is initialized with the
[GLFW_WAYLAND_LIBDECOR](@ref GLFW_WAYLAND_LIBDECOR_hint) init hint. It is
enabled by default.
@subsubsection wayland_app_id_34 Wayland app_id specification
GLFW now supports specifying the app_id for a Wayland window using the
[GLFW_WAYLAND_APP_ID](@ref GLFW_WAYLAND_APP_ID_hint) window hint string.
@subsubsection features_34_angle_backend Support for ANGLE rendering backend selection
GLFW now provides the
[GLFW_ANGLE_PLATFORM_TYPE](@ref GLFW_ANGLE_PLATFORM_TYPE_hint) init hint for
requesting a specific rendering backend when using
[ANGLE](https://chromium.googlesource.com/angle/angle/) to create OpenGL ES
contexts.
@subsubsection captured_cursor_34 Captured cursor mode
GLFW now supports confining the cursor to the window content area with the @ref
GLFW_CURSOR_CAPTURED cursor mode.
For more information see @ref cursor_mode.
@subsubsection features_34_init_allocator Support for custom memory allocator
GLFW now supports plugging a custom memory allocator at initialization with @ref
glfwInitAllocator. The allocator is a struct of type @ref GLFWallocator with
function pointers corresponding to the standard library functions `malloc`,
`realloc` and `free`.
For more information see @ref init_allocator.
@subsubsection features_34_position_hint Window hints for initial position
GLFW now provides the @ref GLFW_POSITION_X and @ref GLFW_POSITION_Y window hints for
specifying the initial position of the window. This removes the need to create a hidden
window, move it and then show it. The default value of these hints is
`GLFW_ANY_POSITION`, which selects the previous behavior.
@subsubsection features_34_win32_keymenu Support for keyboard access to Windows window menu
GLFW now provides the
[GLFW_WIN32_KEYBOARD_MENU](@ref GLFW_WIN32_KEYBOARD_MENU_hint) window hint for
enabling keyboard access to the window menu via the Alt+Space and
Alt-and-then-Space shortcuts. This may be useful for more GUI-oriented
applications.
@subsection caveats Caveats for version 3.4
@subsubsection native_34 Multiple sets of native access functions
Because GLFW now supports runtime selection of platform (window system), a library binary
may export native access functions for multiple platforms. Starting with version 3.4 you
must not assume that GLFW is running on a platform just because it exports native access
functions for it. After initialization, you can query the selected platform with @ref
glfwGetPlatform.
@subsubsection version_string_34 Version string format has been changed
Because GLFW now supports runtime selection of platform (window system), the version
string returned by @ref glfwGetVersionString has been expanded. It now contains the names
of all APIs for all the platforms that the library binary supports.
@subsubsection joysticks_34 Joystick support is initialized on demand
The joystick part of GLFW is now initialized when first used, primarily to work
around faulty Windows drivers that cause DirectInput to take up to several
seconds to enumerate devices.
This change will usually not be observable. However, if your application waits
for events without having first called any joystick function or created any
visible windows, the wait may never unblock as GLFW may not yet have subscribed
to joystick related OS events.
To work around this, call any joystick function before waiting for events, for
example by setting a [joystick callback](@ref joystick_event).
@subsubsection wayland_alpha_34 Frambuffer may lack alpha channel on older Wayland systems
On Wayland, when creating an EGL context on a machine lacking the new
`EGL_EXT_present_opaque` extension, the @ref GLFW_ALPHA_BITS window hint will be
ignored and the framebuffer will have no alpha channel. This is because some
Wayland compositors treat any buffer with an alpha channel as per-pixel
transparent.
If you want a per-pixel transparent window, see the
[GLFW_TRANSPARENT_FRAMEBUFFER](@ref GLFW_TRANSPARENT_FRAMEBUFFER_hint) window
hint.
@subsubsection standalone_34 Tests and examples are disabled when built as a subproject
GLFW now does not build the tests and examples when it is added as
a subdirectory of another CMake project. To enable these, set the @ref
GLFW_BUILD_TESTS and @ref GLFW_BUILD_EXAMPLES cache variables before adding the
GLFW subdirectory.
@code{.cmake}
set(GLFW_BUILD_EXAMPLES ON CACHE BOOL "" FORCE)
set(GLFW_BUILD_TESTS ON CACHE BOOL "" FORCE)
add_subdirectory(path/to/glfw)
@endcode
@subsubsection initmenu_34 macOS main menu now created at initialization
GLFW now creates the main menu and completes the initialization of NSApplication
during initialization. Programs that do not want a main menu can disable it
with the [GLFW_COCOA_MENUBAR](@ref GLFW_COCOA_MENUBAR_hint) init hint.
@subsubsection corevideo_34 CoreVideo dependency has been removed
GLFW no longer depends on the CoreVideo framework on macOS and it no longer
needs to be specified during compilation or linking.
@subsubsection caveat_fbtransparency_34 Framebuffer transparency requires DWM transparency
GLFW no longer supports framebuffer transparency enabled via @ref
GLFW_TRANSPARENT_FRAMEBUFFER on Windows 7 if DWM transparency is off
(the Transparency setting under Personalization > Window Color).
@subsubsection emptyevents_34 Empty events on X11 no longer round-trip to server
Events posted with @ref glfwPostEmptyEvent now use a separate unnamed pipe
instead of sending an X11 client event to the helper window.
@subsection deprecations_34 Deprecations in version 3.4
@subsection removals_34 Removals in 3.4
@subsubsection vulkan_static_34 GLFW_VULKAN_STATIC CMake option has been removed
This option was used to compile GLFW directly linked with the Vulkan loader, instead of
using dynamic loading to get hold of `vkGetInstanceProcAddr` at initialization. This is
now done by calling the @ref glfwInitVulkanLoader function before initialization.
If you need backward compatibility, this macro can still be defined for GLFW 3.4 and will
have no effect. The call to @ref glfwInitVulkanLoader can be conditionally enabled in
your code by checking the @ref GLFW_VERSION_MAJOR and @ref GLFW_VERSION_MINOR macros.
@subsubsection osmesa_option_34 GLFW_USE_OSMESA CMake option has been removed
This option was used to compile GLFW for the Null platform. The Null platform is now
always supported. To produce a library binary that only supports this platform, the way
this CMake option used to do, you will instead need to disable the default platform for
the target OS. This means setting the @ref GLFW_BUILD_WIN32, @ref GLFW_BUILD_COCOA or
@ref GLFW_BUILD_X11 CMake option to false.
You can set all of them to false and the ones that don't apply for the target OS will be
ignored.
@subsubsection wl_shell_34 Support for the wl_shell protocol has been removed
Support for the wl_shell protocol has been removed and GLFW now only supports
the XDG-Shell protocol. If your Wayland compositor does not support XDG-Shell
then GLFW will fail to initialize.
@subsection symbols_34 New symbols in version 3.4
@subsubsection functions_34 New functions in version 3.4
- @ref glfwInitAllocator
- @ref glfwGetPlatform
- @ref glfwPlatformSupported
- @ref glfwInitVulkanLoader
@subsubsection types_34 New types in version 3.4
- @ref GLFWallocator
- @ref GLFWallocatefun
- @ref GLFWreallocatefun
- @ref GLFWdeallocatefun
@subsubsection constants_34 New constants in version 3.4
- @ref GLFW_PLATFORM
- @ref GLFW_ANY_PLATFORM
- @ref GLFW_PLATFORM_WIN32
- @ref GLFW_PLATFORM_COCOA
- @ref GLFW_PLATFORM_WAYLAND
- @ref GLFW_PLATFORM_X11
- @ref GLFW_PLATFORM_NULL
- @ref GLFW_PLATFORM_UNAVAILABLE
- @ref GLFW_POINTING_HAND_CURSOR
- @ref GLFW_RESIZE_EW_CURSOR
- @ref GLFW_RESIZE_NS_CURSOR
- @ref GLFW_RESIZE_NWSE_CURSOR
- @ref GLFW_RESIZE_NESW_CURSOR
- @ref GLFW_RESIZE_ALL_CURSOR
- @ref GLFW_MOUSE_PASSTHROUGH
- @ref GLFW_NOT_ALLOWED_CURSOR
- @ref GLFW_CURSOR_UNAVAILABLE
- @ref GLFW_WIN32_KEYBOARD_MENU
- @ref GLFW_CONTEXT_DEBUG
- @ref GLFW_FEATURE_UNAVAILABLE
- @ref GLFW_FEATURE_UNIMPLEMENTED
- @ref GLFW_ANGLE_PLATFORM_TYPE
- @ref GLFW_ANGLE_PLATFORM_TYPE_NONE
- @ref GLFW_ANGLE_PLATFORM_TYPE_OPENGL
- @ref GLFW_ANGLE_PLATFORM_TYPE_OPENGLES
- @ref GLFW_ANGLE_PLATFORM_TYPE_D3D9
- @ref GLFW_ANGLE_PLATFORM_TYPE_D3D11
- @ref GLFW_ANGLE_PLATFORM_TYPE_VULKAN
- @ref GLFW_ANGLE_PLATFORM_TYPE_METAL
- @ref GLFW_X11_XCB_VULKAN_SURFACE
- @ref GLFW_CURSOR_CAPTURED
- @ref GLFW_POSITION_X
- @ref GLFW_POSITION_Y
- @ref GLFW_ANY_POSITION
- @ref GLFW_WAYLAND_LIBDECOR
- @ref GLFW_WAYLAND_PREFER_LIBDECOR
- @ref GLFW_WAYLAND_DISABLE_LIBDECOR
@section news_archive Release notes for earlier versions
- [Release notes for 3.3](https://www.glfw.org/docs/3.3/news.html)
- [Release notes for 3.2](https://www.glfw.org/docs/3.2/news.html)
- [Release notes for 3.1](https://www.glfw.org/docs/3.1/news.html)
- [Release notes for 3.0](https://www.glfw.org/docs/3.0/news.html)
*/