Remove GLFW's docs, examples, and tests
This commit is contained in:
parent
18a1fbc4f8
commit
39c325eaba
59 changed files with 0 additions and 23047 deletions
34
src/external/glfw/docs/CMakeLists.txt
vendored
34
src/external/glfw/docs/CMakeLists.txt
vendored
|
|
@ -1,34 +0,0 @@
|
|||
|
||||
# NOTE: The order of this list determines the order of items in the Guides
|
||||
# (i.e. Pages) list in the generated documentation
|
||||
set(GLFW_DOXYGEN_SOURCES
|
||||
"include/GLFW/glfw3.h"
|
||||
"include/GLFW/glfw3native.h"
|
||||
"docs/main.dox"
|
||||
"docs/news.dox"
|
||||
"docs/quick.dox"
|
||||
"docs/moving.dox"
|
||||
"docs/compile.dox"
|
||||
"docs/build.dox"
|
||||
"docs/intro.dox"
|
||||
"docs/context.dox"
|
||||
"docs/monitor.dox"
|
||||
"docs/window.dox"
|
||||
"docs/input.dox"
|
||||
"docs/vulkan.dox"
|
||||
"docs/compat.dox"
|
||||
"docs/internal.dox")
|
||||
|
||||
# Format the source list into a Doxyfile INPUT value that Doxygen can parse
|
||||
foreach(path IN LISTS GLFW_DOXYGEN_SOURCES)
|
||||
set(GLFW_DOXYGEN_INPUT "${GLFW_DOXYGEN_INPUT} \\\n\"${GLFW_SOURCE_DIR}/${path}\"")
|
||||
endforeach()
|
||||
|
||||
configure_file(Doxyfile.in Doxyfile @ONLY)
|
||||
|
||||
add_custom_target(docs ALL "${DOXYGEN_EXECUTABLE}"
|
||||
WORKING_DIRECTORY "${GLFW_BINARY_DIR}/docs"
|
||||
COMMENT "Generating HTML documentation" VERBATIM)
|
||||
|
||||
set_target_properties(docs PROPERTIES FOLDER "GLFW3")
|
||||
|
||||
391
src/external/glfw/docs/CONTRIBUTING.md
vendored
391
src/external/glfw/docs/CONTRIBUTING.md
vendored
|
|
@ -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.
|
||||
|
||||
2737
src/external/glfw/docs/Doxyfile.in
vendored
2737
src/external/glfw/docs/Doxyfile.in
vendored
File diff suppressed because it is too large
Load diff
71
src/external/glfw/docs/DoxygenLayout.xml
vendored
71
src/external/glfw/docs/DoxygenLayout.xml
vendored
|
|
@ -1,71 +0,0 @@
|
|||
<doxygenlayout version="1.0">
|
||||
<!-- Generated by doxygen 1.8.14 -->
|
||||
<!-- Navigation index tabs for HTML output -->
|
||||
<navindex>
|
||||
<tab type="mainpage" visible="yes" title="Introduction"/>
|
||||
<tab type="user" url="quick_guide.html" title="Tutorial"/>
|
||||
<tab type="pages" visible="yes" title="Guides" intro=""/>
|
||||
<tab type="modules" visible="yes" title="Reference" intro=""/>
|
||||
<tab type="filelist" visible="yes" title="Files"/>
|
||||
</navindex>
|
||||
|
||||
<!-- Layout definition for a file page -->
|
||||
<file>
|
||||
<detaileddescription title="Description"/>
|
||||
<includes visible="$SHOW_INCLUDE_FILES"/>
|
||||
<sourcelink visible="yes"/>
|
||||
<memberdecl>
|
||||
<constantgroups visible="yes" title=""/>
|
||||
<defines title=""/>
|
||||
<typedefs title=""/>
|
||||
<enums title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
<membergroups visible="yes"/>
|
||||
</memberdecl>
|
||||
<memberdef>
|
||||
<defines title=""/>
|
||||
<typedefs title=""/>
|
||||
<enums title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
</memberdef>
|
||||
<authorsection/>
|
||||
</file>
|
||||
|
||||
<!-- Layout definition for a group page -->
|
||||
<group>
|
||||
<detaileddescription title="Description"/>
|
||||
<memberdecl>
|
||||
<nestedgroups visible="yes" title=""/>
|
||||
<dirs visible="yes" title=""/>
|
||||
<files visible="yes" title=""/>
|
||||
<defines title=""/>
|
||||
<typedefs title=""/>
|
||||
<enums title=""/>
|
||||
<enumvalues title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
</memberdecl>
|
||||
<memberdef>
|
||||
<pagedocs/>
|
||||
<defines title=""/>
|
||||
<typedefs title=""/>
|
||||
<enums title=""/>
|
||||
<enumvalues title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
</memberdef>
|
||||
<authorsection visible="yes"/>
|
||||
</group>
|
||||
|
||||
<!-- Layout definition for a directory page -->
|
||||
<directory>
|
||||
<briefdescription visible="yes"/>
|
||||
<memberdecl>
|
||||
<dirs visible="yes"/>
|
||||
<files visible="yes"/>
|
||||
</memberdecl>
|
||||
<detaileddescription title=""/>
|
||||
</directory>
|
||||
</doxygenlayout>
|
||||
14
src/external/glfw/docs/SUPPORT.md
vendored
14
src/external/glfw/docs/SUPPORT.md
vendored
|
|
@ -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.
|
||||
|
||||
348
src/external/glfw/docs/build.dox
vendored
348
src/external/glfw/docs/build.dox
vendored
|
|
@ -1,348 +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.
|
||||
|
||||
When including GLFW as part of your build, you probably don't want to build the
|
||||
GLFW tests, examples and documentation. To disable these, set the corresponding
|
||||
cache variables before adding the GLFW source tree.
|
||||
|
||||
@code
|
||||
set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)
|
||||
set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
|
||||
set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
|
||||
@endcode
|
||||
|
||||
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.3 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.
|
||||
|
||||
*/
|
||||
289
src/external/glfw/docs/compat.dox
vendored
289
src/external/glfw/docs/compat.dox
vendored
|
|
@ -1,289 +0,0 @@
|
|||
/*!
|
||||
|
||||
@page compat_guide Standards conformance
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide describes the various API extensions used by this version of GLFW.
|
||||
It lists what are essentially implementation details, but which are nonetheless
|
||||
vital knowledge for developers intending to deploy their applications on a wide
|
||||
range of machines.
|
||||
|
||||
The information in this guide is not a part of GLFW API, but merely
|
||||
preconditions for some parts of the library to function on a given machine. Any
|
||||
part of this information may change in future versions of GLFW and that will not
|
||||
be considered a breaking API change.
|
||||
|
||||
|
||||
@section compat_x11 X11 extensions, protocols and IPC standards
|
||||
|
||||
As GLFW uses Xlib directly, without any intervening toolkit
|
||||
library, it has sole responsibility for interacting well with the many and
|
||||
varied window managers in use on Unix-like systems. In order for applications
|
||||
and window managers to work well together, a number of standards and
|
||||
conventions have been developed that regulate behavior outside the scope of the
|
||||
X11 API; most importantly the
|
||||
[Inter-Client Communication Conventions Manual](https://www.tronche.com/gui/x/icccm/)
|
||||
(ICCCM) and
|
||||
[Extended Window Manager Hints](https://standards.freedesktop.org/wm-spec/wm-spec-latest.html)
|
||||
(EWMH) standards.
|
||||
|
||||
GLFW uses the `_MOTIF_WM_HINTS` window property to support borderless windows.
|
||||
If the running window manager does not support this property, the
|
||||
`GLFW_DECORATED` hint will have no effect.
|
||||
|
||||
GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user
|
||||
attempting to close the GLFW window. If the running window manager does not
|
||||
support this protocol, the close callback will never be called.
|
||||
|
||||
GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify
|
||||
the user when the application has stopped responding, i.e. when it has ceased to
|
||||
process events. If the running window manager does not support this protocol,
|
||||
the user will not be notified if the application locks up.
|
||||
|
||||
GLFW uses the EWMH `_NET_WM_STATE_FULLSCREEN` window state to tell the window
|
||||
manager to make the GLFW window full screen. If the running window manager does
|
||||
not support this state, full screen windows may not work properly. GLFW has
|
||||
a fallback code path in case this state is unavailable, but every window manager
|
||||
behaves slightly differently in this regard.
|
||||
|
||||
GLFW uses the EWMH `_NET_WM_BYPASS_COMPOSITOR` window property to tell a
|
||||
compositing window manager to un-redirect full screen GLFW windows. If the
|
||||
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.
|
||||
|
||||
GLFW uses the
|
||||
[clipboard manager protocol](https://www.freedesktop.org/wiki/ClipboardManager/)
|
||||
to push a clipboard string (i.e. selection) owned by a GLFW window about to be
|
||||
destroyed to the clipboard manager. If there is no running clipboard manager,
|
||||
the clipboard string will be unavailable once the window has been destroyed.
|
||||
|
||||
GLFW uses the
|
||||
[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
|
||||
support this protocol, drag and drop will not work.
|
||||
|
||||
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
|
||||
support will not function and only a single, desktop-spanning monitor will be
|
||||
reported.
|
||||
|
||||
GLFW uses the XRandR 1.3 and Xf86vidmode extensions to provide gamma ramp
|
||||
support. If the running X server does not support either or both of these
|
||||
extensions, gamma ramp support will not function.
|
||||
|
||||
GLFW uses the Xkb extension and detectable auto-repeat to provide keyboard
|
||||
input. If the running X server does not support this extension, a non-Xkb
|
||||
fallback path is used.
|
||||
|
||||
GLFW uses the XInput2 extension to provide raw, non-accelerated mouse motion
|
||||
when the cursor is disabled. If the running X server does not support this
|
||||
extension, regular accelerated mouse motion will be used.
|
||||
|
||||
GLFW uses both the XRender extension and the compositing manager to support
|
||||
transparent window framebuffers. If the running X server does not support this
|
||||
extension or there is no running compositing manager, the
|
||||
`GLFW_TRANSPARENT_FRAMEBUFFER` framebuffer hint will have no effect.
|
||||
|
||||
|
||||
@section compat_wayland Wayland protocols and IPC standards
|
||||
|
||||
As GLFW uses libwayland directly, without any intervening toolkit library, it
|
||||
has sole responsibility for interacting well with every compositor in use on
|
||||
Unix-like systems. Most of the features are provided by the core protocol,
|
||||
while cursor support is provided by the libwayland-cursor helper library, EGL
|
||||
integration by libwayland-egl, and keyboard handling by
|
||||
[libxkbcommon](https://xkbcommon.org/). In addition, GLFW uses some protocols
|
||||
from wayland-protocols to provide additional features if the compositor
|
||||
supports them.
|
||||
|
||||
GLFW uses xkbcommon 0.5.0 to provide compose key support. When it has been
|
||||
built against an older xkbcommon, the compose key will be disabled even if it
|
||||
has been configured in the compositor.
|
||||
|
||||
GLFW uses the [xdg-shell
|
||||
protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/stable/xdg-shell/xdg-shell.xml)
|
||||
to provide better window management. This protocol is part of
|
||||
wayland-protocols 1.12, and mandatory at build time.
|
||||
|
||||
GLFW uses the [relative pointer
|
||||
protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/relative-pointer/relative-pointer-unstable-v1.xml)
|
||||
alongside the [pointer constraints
|
||||
protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/pointer-constraints/pointer-constraints-unstable-v1.xml)
|
||||
to implement disabled cursor. These two protocols are part of
|
||||
wayland-protocols 1.1, and mandatory at build time. If the running compositor
|
||||
does not support both of these protocols, disabling the cursor will have no
|
||||
effect.
|
||||
|
||||
GLFW uses the [idle inhibit
|
||||
protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/idle-inhibit/idle-inhibit-unstable-v1.xml)
|
||||
to prohibit the screensaver from starting. This protocol is part of
|
||||
wayland-protocols 1.6, and mandatory at build time. If the running compositor
|
||||
does not support this protocol, the screensaver may start even for full screen
|
||||
windows.
|
||||
|
||||
GLFW uses the [libdecor library](https://gitlab.freedesktop.org/libdecor/libdecor)
|
||||
for window 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 [xdg-decoration
|
||||
protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml)
|
||||
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](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/stable/viewporter/viewporter.xml)
|
||||
alongside
|
||||
[subsurfaces](https://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml#n2598).
|
||||
This protocol is part of wayland-protocols 1.4, and mandatory at build time.
|
||||
If the running compositor does not support this protocol either, no decorations
|
||||
will be drawn around windows.
|
||||
|
||||
|
||||
@section compat_glx GLX extensions
|
||||
|
||||
The GLX API is the default API used to create OpenGL contexts on Unix-like
|
||||
systems using the X Window System.
|
||||
|
||||
GLFW uses the GLX 1.3 `GLXFBConfig` functions to enumerate and select framebuffer pixel
|
||||
formats. If GLX 1.3 is not supported, @ref glfwInit will fail.
|
||||
|
||||
GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
|
||||
`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
|
||||
(or _vsync_), in that order of preference. When none of these extensions are
|
||||
available, calling @ref glfwSwapInterval will have no effect.
|
||||
|
||||
GLFW uses the `GLX_ARB_multisample` extension to create contexts with
|
||||
multisampling anti-aliasing. Where this extension is unavailable, the
|
||||
`GLFW_SAMPLES` hint will have no effect.
|
||||
|
||||
GLFW uses the `GLX_ARB_create_context` extension when available, even when
|
||||
creating OpenGL contexts of version 2.1 and below. Where this extension is
|
||||
unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
|
||||
hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
|
||||
will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
|
||||
`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
|
||||
glfwCreateWindow to fail.
|
||||
|
||||
GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for
|
||||
context profiles. Where this extension is unavailable, setting the
|
||||
`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE`, or setting
|
||||
`GLFW_CLIENT_API` to anything but `GLFW_OPENGL_API` or `GLFW_NO_API` will cause
|
||||
@ref glfwCreateWindow to fail.
|
||||
|
||||
GLFW uses the `GLX_ARB_context_flush_control` extension to provide control over
|
||||
whether a context is flushed when it is released (made non-current). Where this
|
||||
extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
|
||||
effect and the context will always be flushed when released.
|
||||
|
||||
GLFW uses the `GLX_ARB_framebuffer_sRGB` and `GLX_EXT_framebuffer_sRGB`
|
||||
extensions to provide support for sRGB framebuffers. Where both of these
|
||||
extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
|
||||
|
||||
|
||||
@section compat_wgl WGL extensions
|
||||
|
||||
The WGL API is used to create OpenGL contexts on Microsoft Windows and other
|
||||
implementations of the Win32 API, such as Wine.
|
||||
|
||||
GLFW uses either the `WGL_EXT_extension_string` or the
|
||||
`WGL_ARB_extension_string` extension to check for the presence of all other WGL
|
||||
extensions listed below. If both are available, the EXT one is preferred. If
|
||||
neither is available, no other extensions are used and many GLFW features
|
||||
related to context creation will have no effect or cause errors when used.
|
||||
|
||||
GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
|
||||
synchronization (or _vsync_). Where this extension is unavailable, calling @ref
|
||||
glfwSwapInterval will have no effect.
|
||||
|
||||
GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
|
||||
create contexts with multisampling anti-aliasing. Where these extensions are
|
||||
unavailable, the `GLFW_SAMPLES` hint will have no effect.
|
||||
|
||||
GLFW uses the `WGL_ARB_create_context` extension when available, even when
|
||||
creating OpenGL contexts of version 2.1 and below. Where this extension is
|
||||
unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
|
||||
hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
|
||||
will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
|
||||
`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
|
||||
glfwCreateWindow to fail.
|
||||
|
||||
GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for
|
||||
context profiles. Where this extension is unavailable, setting the
|
||||
`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE` will cause
|
||||
@ref glfwCreateWindow to fail.
|
||||
|
||||
GLFW uses the `WGL_ARB_context_flush_control` extension to provide control over
|
||||
whether a context is flushed when it is released (made non-current). Where this
|
||||
extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
|
||||
effect and the context will always be flushed when released.
|
||||
|
||||
GLFW uses the `WGL_ARB_framebuffer_sRGB` and `WGL_EXT_framebuffer_sRGB`
|
||||
extensions to provide support for sRGB framebuffers. When both of these
|
||||
extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
|
||||
|
||||
|
||||
@section compat_osx OpenGL on macOS
|
||||
|
||||
Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then
|
||||
only forward-compatible, core profile contexts are supported. Support for
|
||||
OpenGL 4.1 was introduced with OS X 10.9, also limited to forward-compatible,
|
||||
core profile contexts. There is also still no mechanism for requesting debug
|
||||
contexts or no-error contexts. Versions of Mac OS X earlier than 10.7 support
|
||||
at most OpenGL version 2.1.
|
||||
|
||||
Because of this, on OS X 10.7 and later, the `GLFW_CONTEXT_VERSION_MAJOR` and
|
||||
`GLFW_CONTEXT_VERSION_MINOR` hints will cause @ref glfwCreateWindow to fail if
|
||||
given version 3.0 or 3.1. The `GLFW_OPENGL_FORWARD_COMPAT` hint must be set to
|
||||
`GLFW_TRUE` and the `GLFW_OPENGL_PROFILE` hint must be set to
|
||||
`GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts. The
|
||||
`GLFW_OPENGL_DEBUG_CONTEXT` and `GLFW_CONTEXT_NO_ERROR` hints are ignored.
|
||||
|
||||
Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and
|
||||
`GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 2.1,
|
||||
setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to
|
||||
a non-default value will cause @ref glfwCreateWindow to fail and the
|
||||
`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
|
||||
|
||||
|
||||
@section compat_vulkan Vulkan loader and API
|
||||
|
||||
By default, GLFW uses the standard system-wide Vulkan loader to access the
|
||||
Vulkan API on all platforms except macOS. This is installed by both graphics
|
||||
drivers and Vulkan SDKs. If either the loader or at least one minimally
|
||||
functional ICD is missing, @ref glfwVulkanSupported will return `GLFW_FALSE` and
|
||||
all other Vulkan-related functions will fail with an @ref GLFW_API_UNAVAILABLE
|
||||
error.
|
||||
|
||||
|
||||
@section compat_wsi Vulkan WSI extensions
|
||||
|
||||
The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on
|
||||
all supported platforms.
|
||||
|
||||
GLFW uses the `VK_KHR_surface` and `VK_KHR_win32_surface` extensions to create
|
||||
surfaces on Microsoft Windows. If any of these extensions are not available,
|
||||
@ref glfwGetRequiredInstanceExtensions will return an empty list and window
|
||||
surface creation will fail.
|
||||
|
||||
GLFW uses the `VK_KHR_surface` and either the `VK_MVK_macos_surface` or
|
||||
`VK_EXT_metal_surface` extensions to create surfaces on macOS. If any of these
|
||||
extensions are not available, @ref glfwGetRequiredInstanceExtensions will
|
||||
return an empty list and window surface creation will fail.
|
||||
|
||||
GLFW uses the `VK_KHR_surface` and either the `VK_KHR_xlib_surface` or
|
||||
`VK_KHR_xcb_surface` extensions to create surfaces on X11. If `VK_KHR_surface`
|
||||
or both `VK_KHR_xlib_surface` and `VK_KHR_xcb_surface` are not available, @ref
|
||||
glfwGetRequiredInstanceExtensions will return an empty list and window surface
|
||||
creation will fail.
|
||||
|
||||
GLFW uses the `VK_KHR_surface` and `VK_KHR_wayland_surface` extensions to create
|
||||
surfaces on Wayland. If any of these extensions are not available, @ref
|
||||
glfwGetRequiredInstanceExtensions will return an empty list and window surface
|
||||
creation will fail.
|
||||
|
||||
*/
|
||||
368
src/external/glfw/docs/compile.dox
vendored
368
src/external/glfw/docs/compile.dox
vendored
|
|
@ -1,368 +0,0 @@
|
|||
/*!
|
||||
|
||||
@page compile_guide Compiling GLFW
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This is about compiling the GLFW library itself. For information on how to
|
||||
build applications that use GLFW, see @ref build_guide.
|
||||
|
||||
|
||||
@section compile_cmake Using CMake
|
||||
|
||||
@note GLFW behaves like most other libraries that use CMake so this guide mostly
|
||||
describes the basic configure/generate/compile sequence. If you are already
|
||||
familiar with this from other projects, you may want to focus on the @ref
|
||||
compile_deps and @ref compile_options sections for GLFW-specific information.
|
||||
|
||||
GLFW uses [CMake](https://cmake.org/) to generate project files or makefiles
|
||||
for your chosen development environment. To compile GLFW, first generate these
|
||||
files with CMake and then use them to compile the GLFW library.
|
||||
|
||||
If you are on Windows and macOS you can
|
||||
[download CMake](https://cmake.org/download/) from their site.
|
||||
|
||||
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
|
||||
package.
|
||||
|
||||
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
|
||||
[CMake user guide](https://cmake.org/cmake/help/latest/guide/user-interaction/)
|
||||
that includes everything in this guide not specific to GLFW. It may be a useful
|
||||
companion to this one.
|
||||
|
||||
|
||||
@subsection compile_deps Installing dependencies
|
||||
|
||||
The C/C++ development environments in Visual Studio, Xcode and MinGW come with
|
||||
all necessary dependencies for compiling GLFW, but on Unix-like systems like
|
||||
Linux and FreeBSD you will need a few extra packages.
|
||||
|
||||
|
||||
@subsubsection compile_deps_x11 Dependencies for X11 on Unix-like systems
|
||||
|
||||
To compile GLFW for X11, you need to have the X11 development packages
|
||||
installed. They are not needed to build or run programs that use GLFW.
|
||||
|
||||
On Debian and derivatives like Ubuntu and Linux Mint the `xorg-dev` meta-package
|
||||
pulls in the development packages for all of X11.
|
||||
|
||||
@code{.sh}
|
||||
sudo apt install xorg-dev
|
||||
@endcode
|
||||
|
||||
On Fedora and derivatives like Red Hat the X11 extension packages
|
||||
`libXcursor-devel`, `libXi-devel`, `libXinerama-devel` and `libXrandr-devel`
|
||||
required by GLFW pull in all its other dependencies.
|
||||
|
||||
@code{.sh}
|
||||
sudo dnf install libXcursor-devel libXi-devel libXinerama-devel libXrandr-devel
|
||||
@endcode
|
||||
|
||||
On FreeBSD the X11 headers are installed along the end-user X11 packages, so if
|
||||
you have an X server running you should have the headers as well. If not,
|
||||
install the `xorgproto` package.
|
||||
|
||||
@code{.sh}
|
||||
pkg install xorgproto
|
||||
@endcode
|
||||
|
||||
On Cygwin the `libXcursor-devel`, `libXi-devel`, `libXinerama-devel`,
|
||||
`libXrandr-devel` and `libXrender-devel` packages in the Libs section of the GUI
|
||||
installer will install all the headers and other development related files GLFW
|
||||
requires for X11.
|
||||
|
||||
Once you have the required depdendencies, move on to @ref compile_generate.
|
||||
|
||||
|
||||
@subsubsection compile_deps_wayland Dependencies for Wayland on Unix-like systems
|
||||
|
||||
To compile GLFW for Wayland, you need to have the Wayland and xkbcommon
|
||||
development packages installed. They are not needed to build or run programs
|
||||
that use GLFW.
|
||||
|
||||
On Debian and derivatives like Ubuntu and Linux Mint you will need the `libwayland-dev`,
|
||||
`libxkbcommon-dev`, `wayland-protocols` and `extra-cmake-modules` packages.
|
||||
These will pull in all other dependencies.
|
||||
|
||||
@code{.sh}
|
||||
sudo apt install libwayland-dev libxkbcommon-dev wayland-protocols extra-cmake-modules
|
||||
@endcode
|
||||
|
||||
On Fedora and derivatives like Red Hat you will need the `wayland-devel`,
|
||||
`libxkbcommon-devel`, `wayland-protocols-devel` and `extra-cmake-modules` packages.
|
||||
|
||||
@code{.sh}
|
||||
sudo dnf install wayland-devel libxkbcommon-devel wayland-protocols-devel extra-cmake-modules
|
||||
@endcode
|
||||
|
||||
On FreeBSD you will need the `wayland`, `libxkbcommon`, `wayland-protocols` and
|
||||
`kf5-extra-cmake-modules` packages.
|
||||
|
||||
@code{.sh}
|
||||
pkg install wayland libxkbcommon wayland-protocols kf5-extra-cmake-modules
|
||||
@endcode
|
||||
|
||||
Once you have the required depdendencies, move on to @ref compile_generate.
|
||||
|
||||
|
||||
@subsection compile_generate Generating build files with CMake
|
||||
|
||||
Once you have all necessary dependencies it is time to generate the project
|
||||
files or makefiles for your development environment. CMake needs two paths for
|
||||
this:
|
||||
|
||||
- the path to the root directory of the GLFW source tree (not its `src`
|
||||
subdirectory)
|
||||
- the path to the directory where the generated build files and compiled
|
||||
binaries will be placed
|
||||
|
||||
If these are the same, it is called an in-tree build, otherwise it is called an
|
||||
out-of-tree build.
|
||||
|
||||
Out-of-tree builds are recommended as they avoid cluttering up the source tree.
|
||||
They also allow you to have several build directories for different
|
||||
configurations all using the same source tree.
|
||||
|
||||
A common pattern when building a single configuration is to have a build
|
||||
directory named `build` in the root of the source tree.
|
||||
|
||||
|
||||
@subsubsection compile_generate_gui Generating files with the CMake GUI
|
||||
|
||||
Start the CMake GUI and set the paths to the source and build directories
|
||||
described above. Then press _Configure_ and _Generate_.
|
||||
|
||||
If you wish change any CMake variables in the list, press _Configure_ and then
|
||||
_Generate_ to have the new values take effect. The variable list will be
|
||||
populated after the first configure step.
|
||||
|
||||
By default, GLFW will use X11 on Linux and other Unix-like systems other
|
||||
than macOS. To use Wayland instead, set the `GLFW_USE_WAYLAND` option in the
|
||||
GLFW section of the variable list, then apply the new value as described above.
|
||||
|
||||
Once you have generated the project files or makefiles for your chosen
|
||||
development environment, move on to @ref compile_compile.
|
||||
|
||||
|
||||
@subsubsection compile_generate_cli Generating files with the CMake command-line tool
|
||||
|
||||
To make a build directory, pass the source and build directories to the `cmake`
|
||||
command. These can be relative or absolute paths. The build directory is
|
||||
created if it doesn't already exist.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build
|
||||
@endcode
|
||||
|
||||
It is common to name the build directory `build` and place it in the root of the
|
||||
source tree when only planning to build a single configuration.
|
||||
|
||||
@code{.sh}
|
||||
cd path/to/glfw
|
||||
cmake -S . -B build
|
||||
@endcode
|
||||
|
||||
Without other flags these will generate Visual Studio project files on Windows
|
||||
and makefiles on other platforms. You can choose other targets using the `-G`
|
||||
flag.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -G Xcode
|
||||
@endcode
|
||||
|
||||
By default, GLFW will use X11 on Linux and other Unix-like systems other
|
||||
than macOS. To use Wayland instead, set the `GLFW_USE_WAYLAND` CMake option.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -D GLFW_USE_WAYLAND=1
|
||||
@endcode
|
||||
|
||||
Once you have generated the project files or makefiles for your chosen
|
||||
development environment, move on to @ref compile_compile.
|
||||
|
||||
|
||||
@subsection compile_compile Compiling the library
|
||||
|
||||
You should now have all required dependencies and the project files or makefiles
|
||||
necessary to compile GLFW. Go ahead and compile the actual GLFW library with
|
||||
these files as you would with any other project.
|
||||
|
||||
With Visual Studio open `GLFW.sln` and use the Build menu. With Xcode open
|
||||
`GLFW.xcodeproj` and use the Project menu.
|
||||
|
||||
With Linux, macOS and other forms of Unix, run `make`.
|
||||
|
||||
@code{.sh}
|
||||
cd path/to/build
|
||||
make
|
||||
@endcode
|
||||
|
||||
With MinGW, it is `mingw32-make`.
|
||||
|
||||
@code{.sh}
|
||||
cd path/to/build
|
||||
mingw32-make
|
||||
@endcode
|
||||
|
||||
Any CMake build directory can also be built with the `cmake` command and the
|
||||
`--build` flag.
|
||||
|
||||
@code{.sh}
|
||||
cmake --build path/to/build
|
||||
@endcode
|
||||
|
||||
This will run the platform specific build tool the directory was generated for.
|
||||
|
||||
Once the GLFW library is compiled you are ready to build your application,
|
||||
linking it to the GLFW library. See @ref build_guide for more information.
|
||||
|
||||
|
||||
@section compile_options CMake options
|
||||
|
||||
The CMake files for GLFW provide a number of options, although not all are
|
||||
available on all supported platforms. Some of these are de facto standards
|
||||
among projects using CMake and so have no `GLFW_` prefix.
|
||||
|
||||
If you are using the GUI version of CMake, these are listed and can be changed
|
||||
from there. If you are using the command-line version of CMake you can use the
|
||||
`ccmake` ncurses GUI to set options. Some package systems like Ubuntu and other
|
||||
distributions based on Debian GNU/Linux have this tool in a separate
|
||||
`cmake-curses-gui` package.
|
||||
|
||||
Finally, if you don't want to use any GUI, you can set options from the `cmake`
|
||||
command-line with the `-D` flag.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -D BUILD_SHARED_LIBS=ON
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection compile_options_shared Shared CMake options
|
||||
|
||||
@anchor BUILD_SHARED_LIBS
|
||||
__BUILD_SHARED_LIBS__ determines whether GLFW is built as a static
|
||||
library or as a DLL / shared library / dynamic library. This is disabled by
|
||||
default, producing a static GLFW library.
|
||||
|
||||
@anchor GLFW_BUILD_EXAMPLES
|
||||
__GLFW_BUILD_EXAMPLES__ determines whether the GLFW examples are built
|
||||
along with the library.
|
||||
|
||||
@anchor GLFW_BUILD_TESTS
|
||||
__GLFW_BUILD_TESTS__ determines whether the GLFW test programs are
|
||||
built along with the library.
|
||||
|
||||
@anchor GLFW_BUILD_DOCS
|
||||
__GLFW_BUILD_DOCS__ determines whether the GLFW documentation is built along
|
||||
with the library. This is enabled by default if
|
||||
[Doxygen](https://www.doxygen.nl/) is found by CMake during configuration.
|
||||
|
||||
@anchor GLFW_VULKAN_STATIC
|
||||
__GLFW_VULKAN_STATIC__ determines whether to use the Vulkan loader linked
|
||||
directly with the application. This is disabled by default.
|
||||
|
||||
|
||||
@subsection compile_options_win32 Windows specific CMake options
|
||||
|
||||
@anchor USE_MSVC_RUNTIME_LIBRARY_DLL
|
||||
__USE_MSVC_RUNTIME_LIBRARY_DLL__ determines whether to use the DLL version or 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.
|
||||
|
||||
On CMake 3.15 and later you can set the standard CMake
|
||||
[CMAKE_MSVC_RUNTIME_LIBRARY](https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html)
|
||||
variable instead of this GLFW-specific option.
|
||||
|
||||
@anchor GLFW_USE_HYBRID_HPG
|
||||
__GLFW_USE_HYBRID_HPG__ determines whether to export the `NvOptimusEnablement` and
|
||||
`AmdPowerXpressRequestHighPerformance` symbols, which force the use of the
|
||||
high-performance GPU on Nvidia Optimus and AMD PowerXpress systems. These symbols
|
||||
need to be exported by the EXE to be detected by the driver, so the override
|
||||
will not work if GLFW is built as a DLL. This is disabled by default, letting
|
||||
the operating system and driver decide.
|
||||
|
||||
|
||||
@subsection compile_options_wayland Wayland specific CMake options
|
||||
|
||||
@anchor GLFW_USE_WAYLAND
|
||||
__GLFW_USE_WAYLAND__ determines whether to compile the library for Wayland.
|
||||
This option is only available on Linux and other Unix-like systems other than
|
||||
macOS. This is disabled by default.
|
||||
|
||||
|
||||
@section compile_mingw_cross Cross-compilation with CMake and MinGW
|
||||
|
||||
Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages. For
|
||||
example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
|
||||
for 32- and 64-bit version of MinGW-w64, while Debian GNU/Linux and derivatives
|
||||
like Ubuntu have the `mingw-w64` package for both.
|
||||
|
||||
GLFW has CMake toolchain files in the `CMake` subdirectory that set up
|
||||
cross-compilation of Windows binaries. To use these files you set the
|
||||
`CMAKE_TOOLCHAIN_FILE` CMake variable with the `-D` flag add an option when
|
||||
configuring and generating the build files.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -D CMAKE_TOOLCHAIN_FILE=path/to/file
|
||||
@endcode
|
||||
|
||||
The exact toolchain file to use depends on the prefix used by the MinGW or
|
||||
MinGW-w64 binaries on your system. You can usually see this in the /usr
|
||||
directory. For example, both the Ubuntu and Cygwin MinGW-w64 packages have
|
||||
`/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct invocation
|
||||
would be:
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -D CMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake
|
||||
@endcode
|
||||
|
||||
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.
|
||||
|
||||
For more details see the
|
||||
[CMake toolchain guide](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html).
|
||||
|
||||
|
||||
@section compile_manual Compiling GLFW manually
|
||||
|
||||
If you wish to compile GLFW without its CMake build environment then you will
|
||||
have to do at least some of the platform-detection yourself. GLFW needs
|
||||
a configuration macro to be defined in order to know what window system it is
|
||||
being compiled for and also has optional, platform-specific ones for various
|
||||
features.
|
||||
|
||||
When building with CMake, the `glfw_config.h` configuration header is generated
|
||||
based on the current platform and CMake options. The GLFW CMake environment
|
||||
defines @b GLFW_USE_CONFIG_H, which causes this header to be included by
|
||||
`internal.h`. Without this macro, GLFW will expect the necessary configuration
|
||||
macros to be defined on the command-line.
|
||||
|
||||
The window creation API is used to create windows, handle input, monitors, gamma
|
||||
ramps and clipboard. The options are:
|
||||
|
||||
- @b _GLFW_COCOA to use the Cocoa frameworks
|
||||
- @b _GLFW_WIN32 to use the Win32 API
|
||||
- @b _GLFW_X11 to use the X Window System
|
||||
- @b _GLFW_WAYLAND to use the Wayland API (experimental and incomplete)
|
||||
- @b _GLFW_OSMESA to use the OSMesa API (headless and non-interactive)
|
||||
|
||||
If you are building GLFW as a shared library / dynamic library / DLL then you
|
||||
must also define @b _GLFW_BUILD_DLL. Otherwise, you must not define it.
|
||||
|
||||
If you are linking the Vulkan loader directly with your application then you
|
||||
must also define @b _GLFW_VULKAN_STATIC. Otherwise, GLFW will attempt to use the
|
||||
external version.
|
||||
|
||||
If you are using a custom name for the Vulkan, EGL, GLX, OSMesa, OpenGL, GLESv1
|
||||
or GLESv2 library, you can override the default names by defining those you need
|
||||
of @b _GLFW_VULKAN_LIBRARY, @b _GLFW_EGL_LIBRARY, @b _GLFW_GLX_LIBRARY, @b
|
||||
_GLFW_OSMESA_LIBRARY, @b _GLFW_OPENGL_LIBRARY, @b _GLFW_GLESV1_LIBRARY and @b
|
||||
_GLFW_GLESV2_LIBRARY. Otherwise, GLFW will use the built-in default names.
|
||||
|
||||
@note None of the @ref build_macros may be defined during the compilation of
|
||||
GLFW. If you define any of these in your build files, make sure they are not
|
||||
applied to the GLFW sources.
|
||||
|
||||
*/
|
||||
347
src/external/glfw/docs/context.dox
vendored
347
src/external/glfw/docs/context.dox
vendored
|
|
@ -1,347 +0,0 @@
|
|||
/*!
|
||||
|
||||
@page context_guide Context guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide introduces the OpenGL and OpenGL ES context related functions of
|
||||
GLFW. For details on a specific function in this category, see the @ref
|
||||
context. There are also guides for the other areas of the GLFW API.
|
||||
|
||||
- @ref intro_guide
|
||||
- @ref window_guide
|
||||
- @ref vulkan_guide
|
||||
- @ref monitor_guide
|
||||
- @ref input_guide
|
||||
|
||||
|
||||
@section context_object Context objects
|
||||
|
||||
A window object encapsulates both a top-level window and an OpenGL or OpenGL ES
|
||||
context. It is created with @ref glfwCreateWindow and destroyed with @ref
|
||||
glfwDestroyWindow or @ref glfwTerminate. See @ref window_creation for more
|
||||
information.
|
||||
|
||||
As the window and context are inseparably linked, the window object also serves
|
||||
as the context handle.
|
||||
|
||||
To test the creation of various kinds of contexts and see their properties, run
|
||||
the `glfwinfo` test program.
|
||||
|
||||
@note Vulkan does not have a context and the Vulkan instance is created via the
|
||||
Vulkan API itself. If you will be using Vulkan to render to a window, disable
|
||||
context creation by setting the [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint)
|
||||
hint to `GLFW_NO_API`. For more information, see the @ref vulkan_guide.
|
||||
|
||||
|
||||
@subsection context_hints Context creation hints
|
||||
|
||||
There are a number of hints, specified using @ref glfwWindowHint, related to
|
||||
what kind of context is created. See
|
||||
[context related hints](@ref window_hints_ctx) in the window guide.
|
||||
|
||||
|
||||
@subsection context_sharing Context object sharing
|
||||
|
||||
When creating a window and its OpenGL or OpenGL ES context with @ref
|
||||
glfwCreateWindow, you can specify another window whose context the new one
|
||||
should share its objects (textures, vertex and element buffers, etc.) with.
|
||||
|
||||
@code
|
||||
GLFWwindow* second_window = glfwCreateWindow(640, 480, "Second Window", NULL, first_window);
|
||||
@endcode
|
||||
|
||||
Object sharing is implemented by the operating system and graphics driver. On
|
||||
platforms where it is possible to choose which types of objects are shared, GLFW
|
||||
requests that all types are shared.
|
||||
|
||||
See the relevant chapter of the [OpenGL](https://www.opengl.org/registry/) or
|
||||
[OpenGL ES](https://www.khronos.org/opengles/) reference documents for more
|
||||
information. The name and number of this chapter unfortunately varies between
|
||||
versions and APIs, but has at times been named _Shared Objects and Multiple
|
||||
Contexts_.
|
||||
|
||||
GLFW comes with a bare-bones object sharing example program called `sharing`.
|
||||
|
||||
|
||||
@subsection context_offscreen Offscreen contexts
|
||||
|
||||
GLFW doesn't support creating contexts without an associated window. However,
|
||||
contexts with hidden windows can be created with the
|
||||
[GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window hint.
|
||||
|
||||
@code
|
||||
glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);
|
||||
|
||||
GLFWwindow* offscreen_context = glfwCreateWindow(640, 480, "", NULL, NULL);
|
||||
@endcode
|
||||
|
||||
The window never needs to be shown and its context can be used as a plain
|
||||
offscreen context. Depending on the window manager, the size of a hidden
|
||||
window's framebuffer may not be usable or modifiable, so framebuffer
|
||||
objects are recommended for rendering with such contexts.
|
||||
|
||||
You should still [process events](@ref events) as long as you have at least one
|
||||
window, even if none of them are visible.
|
||||
|
||||
@macos The first time a window is created the menu bar is created. This is not
|
||||
desirable for example when writing a command-line only application. Menu bar
|
||||
creation can be disabled with the @ref GLFW_COCOA_MENUBAR init hint.
|
||||
|
||||
|
||||
@subsection context_less Windows without contexts
|
||||
|
||||
You can disable context creation by setting the
|
||||
[GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_NO_API`.
|
||||
|
||||
Windows without contexts should not be passed to @ref glfwMakeContextCurrent or
|
||||
@ref glfwSwapBuffers. Doing this generates a @ref GLFW_NO_WINDOW_CONTEXT error.
|
||||
|
||||
|
||||
@section context_current Current context
|
||||
|
||||
Before you can make OpenGL or OpenGL ES calls, you need to have a current
|
||||
context of the correct type. A context can only be current for a single thread
|
||||
at a time, and a thread can only have a single context current at a time.
|
||||
|
||||
When moving a context between threads, you must make it non-current on the old
|
||||
thread before making it current on the new one.
|
||||
|
||||
The context of a window is made current with @ref glfwMakeContextCurrent.
|
||||
|
||||
@code
|
||||
glfwMakeContextCurrent(window);
|
||||
@endcode
|
||||
|
||||
The window of the current context is returned by @ref glfwGetCurrentContext.
|
||||
|
||||
@code
|
||||
GLFWwindow* window = glfwGetCurrentContext();
|
||||
@endcode
|
||||
|
||||
The following GLFW functions require a context to be current. Calling any these
|
||||
functions without a current context will generate a @ref GLFW_NO_CURRENT_CONTEXT
|
||||
error.
|
||||
|
||||
- @ref glfwSwapInterval
|
||||
- @ref glfwExtensionSupported
|
||||
- @ref glfwGetProcAddress
|
||||
|
||||
|
||||
@section context_swap Buffer swapping
|
||||
|
||||
See @ref buffer_swap in the window guide.
|
||||
|
||||
|
||||
@section context_glext OpenGL and OpenGL ES extensions
|
||||
|
||||
One of the benefits of OpenGL and OpenGL ES is their extensibility.
|
||||
Hardware vendors may include extensions in their implementations that extend the
|
||||
API before that functionality is included in a new version of the OpenGL or
|
||||
OpenGL ES specification, and some extensions are never included and remain
|
||||
as extensions until they become obsolete.
|
||||
|
||||
An extension is defined by:
|
||||
|
||||
- An extension name (e.g. `GL_ARB_gl_spirv`)
|
||||
- New OpenGL tokens (e.g. `GL_SPIR_V_BINARY_ARB`)
|
||||
- New OpenGL functions (e.g. `glSpecializeShaderARB`)
|
||||
|
||||
Note the `ARB` affix, which stands for Architecture Review Board and is used
|
||||
for official extensions. The extension above was created by the ARB, but there
|
||||
are many different affixes, like `NV` for Nvidia and `AMD` for, well, AMD. Any
|
||||
group may also use the generic `EXT` affix. Lists of extensions, together with
|
||||
their specifications, can be found at the
|
||||
[OpenGL Registry](https://www.opengl.org/registry/) and
|
||||
[OpenGL ES Registry](https://www.khronos.org/registry/gles/).
|
||||
|
||||
|
||||
@subsection context_glext_auto Loading extension with a loader library
|
||||
|
||||
An extension loader library is the easiest and best way to access both OpenGL and
|
||||
OpenGL ES extensions and modern versions of the core OpenGL or OpenGL ES APIs.
|
||||
They will take care of all the details of declaring and loading everything you
|
||||
need. One such library is [glad](https://github.com/Dav1dde/glad) and there are
|
||||
several others.
|
||||
|
||||
The following example will use glad but all extension loader libraries work
|
||||
similarly.
|
||||
|
||||
First you need to generate the source files using the glad Python script. This
|
||||
example generates a loader for any version of OpenGL, which is the default for
|
||||
both GLFW and glad, but loaders for OpenGL ES, as well as loaders for specific
|
||||
API versions and extension sets can be generated. The generated files are
|
||||
written to the `output` directory.
|
||||
|
||||
@code{.sh}
|
||||
python main.py --generator c --no-loader --out-path output
|
||||
@endcode
|
||||
|
||||
The `--no-loader` option is added because GLFW already provides a function for
|
||||
loading OpenGL and OpenGL ES function pointers, one that automatically uses the
|
||||
selected context creation API, and glad can call this instead of having to
|
||||
implement its own. There are several other command-line options as well. See
|
||||
the glad documentation for details.
|
||||
|
||||
Add the generated `output/src/glad.c`, `output/include/glad/glad.h` and
|
||||
`output/include/KHR/khrplatform.h` files to your build. Then you need to
|
||||
include the glad header file, which will replace the OpenGL header of your
|
||||
development environment. By including the glad header before the GLFW header,
|
||||
it suppresses the development environment's OpenGL or OpenGL ES header.
|
||||
|
||||
@code
|
||||
#include <glad/glad.h>
|
||||
#include <GLFW/glfw3.h>
|
||||
@endcode
|
||||
|
||||
Finally, you need to initialize glad once you have a suitable current context.
|
||||
|
||||
@code
|
||||
window = glfwCreateWindow(640, 480, "My Window", NULL, NULL);
|
||||
if (!window)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
glfwMakeContextCurrent(window);
|
||||
|
||||
gladLoadGLLoader((GLADloadproc) glfwGetProcAddress);
|
||||
@endcode
|
||||
|
||||
Once glad has been loaded, you have access to all OpenGL core and extension
|
||||
functions supported by both the context you created and the glad loader you
|
||||
generated. After that, you are ready to start rendering.
|
||||
|
||||
You can specify a minimum required OpenGL or OpenGL ES version with
|
||||
[context hints](@ref window_hints_ctx). If your needs are more complex, you can
|
||||
check the actual OpenGL or OpenGL ES version with
|
||||
[context attributes](@ref window_attribs_ctx), or you can check whether
|
||||
a specific version is supported by the current context with the
|
||||
`GLAD_GL_VERSION_x_x` booleans.
|
||||
|
||||
@code
|
||||
if (GLAD_GL_VERSION_3_2)
|
||||
{
|
||||
// Call OpenGL 3.2+ specific code
|
||||
}
|
||||
@endcode
|
||||
|
||||
To check whether a specific extension is supported, use the `GLAD_GL_xxx`
|
||||
booleans.
|
||||
|
||||
@code
|
||||
if (GLAD_GL_ARB_gl_spirv)
|
||||
{
|
||||
// Use GL_ARB_gl_spirv
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection context_glext_manual Loading extensions manually
|
||||
|
||||
__Do not use this technique__ unless it is absolutely necessary. An
|
||||
[extension loader library](@ref context_glext_auto) will save you a ton of
|
||||
tedious, repetitive, error prone work.
|
||||
|
||||
To use a certain extension, you must first check whether the context supports
|
||||
that extension and then, if it introduces new functions, retrieve the pointers
|
||||
to those functions. GLFW provides @ref glfwExtensionSupported and @ref
|
||||
glfwGetProcAddress for manual loading of extensions and new API functions.
|
||||
|
||||
This section will demonstrate manual loading of OpenGL extensions. The loading
|
||||
of OpenGL ES extensions is identical except for the name of the extension header.
|
||||
|
||||
|
||||
@subsubsection context_glext_header The glext.h header
|
||||
|
||||
The `glext.h` extension header is a continually updated file that defines the
|
||||
interfaces for all OpenGL extensions. The latest version of this can always be
|
||||
found at the [OpenGL Registry](https://www.opengl.org/registry/). There are also
|
||||
extension headers for the various versions of OpenGL ES at the
|
||||
[OpenGL ES Registry](https://www.khronos.org/registry/gles/). It it strongly
|
||||
recommended that you use your own copy of the extension header, as the one
|
||||
included in your development environment may be several years out of date and
|
||||
may not include the extensions you wish to use.
|
||||
|
||||
The header defines function pointer types for all functions of all extensions it
|
||||
supports. These have names like `PFNGLSPECIALIZESHADERARBPROC` (for
|
||||
`glSpecializeShaderARB`), i.e. the name is made uppercase and `PFN` (pointer
|
||||
to function) and `PROC` (procedure) are added to the ends.
|
||||
|
||||
To include the extension header, define @ref GLFW_INCLUDE_GLEXT before including
|
||||
the GLFW header.
|
||||
|
||||
@code
|
||||
#define GLFW_INCLUDE_GLEXT
|
||||
#include <GLFW/glfw3.h>
|
||||
@endcode
|
||||
|
||||
|
||||
@subsubsection context_glext_string Checking for extensions
|
||||
|
||||
A given machine may not actually support the extension (it may have older
|
||||
drivers or a graphics card that lacks the necessary hardware features), so it
|
||||
is necessary to check at run-time whether the context supports the extension.
|
||||
This is done with @ref glfwExtensionSupported.
|
||||
|
||||
@code
|
||||
if (glfwExtensionSupported("GL_ARB_gl_spirv"))
|
||||
{
|
||||
// The extension is supported by the current context
|
||||
}
|
||||
@endcode
|
||||
|
||||
The argument is a null terminated ASCII string with the extension name. If the
|
||||
extension is supported, @ref glfwExtensionSupported returns `GLFW_TRUE`,
|
||||
otherwise it returns `GLFW_FALSE`.
|
||||
|
||||
|
||||
@subsubsection context_glext_proc Fetching function pointers
|
||||
|
||||
Many extensions, though not all, require the use of new OpenGL functions.
|
||||
These functions often do not have entry points in the client API libraries of
|
||||
your operating system, making it necessary to fetch them at run time. You can
|
||||
retrieve pointers to these functions with @ref glfwGetProcAddress.
|
||||
|
||||
@code
|
||||
PFNGLSPECIALIZESHADERARBPROC pfnSpecializeShaderARB = glfwGetProcAddress("glSpecializeShaderARB");
|
||||
@endcode
|
||||
|
||||
In general, you should avoid giving the function pointer variables the (exact)
|
||||
same name as the function, as this may confuse your linker. Instead, you can
|
||||
use a different prefix, like above, or some other naming scheme.
|
||||
|
||||
Now that all the pieces have been introduced, here is what they might look like
|
||||
when used together.
|
||||
|
||||
@code
|
||||
#define GLFW_INCLUDE_GLEXT
|
||||
#include <GLFW/glfw3.h>
|
||||
|
||||
#define glSpecializeShaderARB pfnSpecializeShaderARB
|
||||
PFNGLSPECIALIZESHADERARBPROC pfnSpecializeShaderARB;
|
||||
|
||||
// Flag indicating whether the extension is supported
|
||||
int has_ARB_gl_spirv = 0;
|
||||
|
||||
void load_extensions(void)
|
||||
{
|
||||
if (glfwExtensionSupported("GL_ARB_gl_spirv"))
|
||||
{
|
||||
pfnSpecializeShaderARB = (PFNGLSPECIALIZESHADERARBPROC)
|
||||
glfwGetProcAddress("glSpecializeShaderARB");
|
||||
has_ARB_gl_spirv = 1;
|
||||
}
|
||||
}
|
||||
|
||||
void some_function(void)
|
||||
{
|
||||
if (has_ARB_gl_spirv)
|
||||
{
|
||||
// Now the extension function can be called as usual
|
||||
glSpecializeShaderARB(...);
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
*/
|
||||
1
src/external/glfw/docs/extra.css
vendored
1
src/external/glfw/docs/extra.css
vendored
File diff suppressed because one or more lines are too long
1
src/external/glfw/docs/extra.css.map
vendored
1
src/external/glfw/docs/extra.css.map
vendored
|
|
@ -1 +0,0 @@
|
|||
{"version":3,"sourceRoot":"","sources":["extra.scss"],"names":[],"mappings":"AA8EA,4GACI,gBACA,iBAGJ,yBACC,yDAGD,6HACC,sDAGD,yIACC,sDAGD,mBACI,WA9EuB,KA+EvB,iBAGJ,uBACC,MAzFoB,QA0FjB,iBAGJ,6UACC,gBAGD,mJACC,YAGD,yHACC,iBAGD,sBACC,gBAGD,4LACC,UAGD,yCACC,aAGD,kMACC,WAnHgC,QAsHjC,KACC,MA1HoB,QA6HrB,sDACC,MA/Ge,QAgHf,mBAGD,GACE,iBACA,eAGF,GACE,iBACA,gBACA,eAGF,GACE,iBACA,gBACA,eAGF,YACC,eACA,gBACA,gBACA,eACA,cAEA,aACA,mBACA,eACA,2BACA,mBACA,sBAGD,UACC,iBACA,mBACA,MA/J0B,KAgK1B,gBACA,qEAGD,YACC,qBACA,kBACA,YAGD,yBACC,WAGD,oCACC,iBACA,gBACA,cACA,MAlL0B,KAqL3B,YACC,eAGD,8CACC,qBAGD,mBACC,MA9L0B,KAiM3B,eACC,kBACA,YACA,eAGD,KACC,WAxM0B,KA2M3B,UACC,gBACA,cACA,eAGD,WACC,gBACA,cACA,eAGD,UACI,aAGJ,mBACI,iBACA,iBAGJ,WACC,gBACA,aACA,mBACA,eACA,2BACA,mBACA,sBAGD,mEACC,MA9OgC,QAiPjC,gCACC,MArPoB,QAwPrB,sCACC,MAjOoB,KAoOrB,yBACC,kBAGD,UACC,iBAGD,wBACC,gBACA,cACA,eACA,qBAGD,uDACC,gEACA,+BACA,+BACA,gBACA,MArPgB,KAwPjB,mBACC,MA5PoB,KA6PpB,aACA,kBACA,yBAGD,QACC,WACA,WAGD,WACC,iBAGD,WACC,mBAGD,WACC,cACA,eACA,qBAGD,oCACC,gEACA,kCACA,2BACA,MAlSe,QAmSf,yBACA,kBAGD,WACC,MA3QuB,QA8QxB,cACC,sBACA,2BACA,4BACA,mBAGD,cACC,sBACA,+BACA,8BACA,gBAGD,mCACC,wBACA,iBACA,sBACA,kBAGD,gIACC,MAxToB,KAyTpB,qBAGD,cACC,wBACA,iBACA,sBACA,kBAGD,iBACC,WACA,4EAGD,oCApSC,gEACA,kCACA,cACA,yBAqSD,wBAxSC,gEACA,kCACA,cACA,yBAySD,qBA5SC,gEACA,kCACA,cACA,yBA6SD,gBAhTC,gEACA,kCACA,cACA,yBAiTD,iGACC,kBACA,YACA,2BACA,aAGD,kRACC,cAGD,SACC,oBAGD,0BACC,mBACA,kBACA,YACA,YACA,cACA,2BACA,aAGD,+CACC,MA1YoB,QA6YrB,+BACC,cAGD,sBACC,cAGD,+CACC,cACA,iBAGD,mBACC,cAGD,KACC,aACA","file":"extra.css"}
|
||||
430
src/external/glfw/docs/extra.scss
vendored
430
src/external/glfw/docs/extra.scss
vendored
|
|
@ -1,430 +0,0 @@
|
|||
// NOTE: Please use this file to perform modifications on default style sheets.
|
||||
//
|
||||
// You need to install the official Sass CLI tool:
|
||||
// npm install -g sass
|
||||
//
|
||||
// Run this command to regenerate extra.css after you're finished with changes:
|
||||
// sass --style=compressed extra.scss extra.css
|
||||
//
|
||||
// Alternatively you can use online services to regenerate extra.css.
|
||||
|
||||
|
||||
// Default text color for page contents
|
||||
$default-text-color: hsl(0,0%,30%);
|
||||
|
||||
// Page header, footer, table rows, inline codes and definition lists
|
||||
$header-footer-background-color: hsl(0,0%,95%);
|
||||
|
||||
// Page header, footer links and navigation bar background
|
||||
$header-footer-link-color: hsl(0,0%,40%);
|
||||
|
||||
// Doxygen navigation bar links
|
||||
$navbar-link-color: $header-footer-background-color;
|
||||
|
||||
// Page content background color
|
||||
$content-background-color: hsl(0,0%,100%);
|
||||
|
||||
// Bold, italic, h1, h2, ... and table of contents
|
||||
$heading-color: hsl(0,0%,10%);
|
||||
|
||||
// Function, enum and macro definition separator
|
||||
$def-separator-color: $header-footer-background-color;
|
||||
|
||||
// Base color hue
|
||||
$base-hue: 24;
|
||||
|
||||
// Default color used for links
|
||||
$default-link-color: hsl($base-hue,100%,50%);
|
||||
|
||||
// Doxygen navigation bar active tab
|
||||
$tab-text-color: hsl(0,0%,100%);
|
||||
$tab-background-color1: $default-link-color;
|
||||
$tab-background-color2: lighten(adjust-hue($tab-background-color1, 10), 10%);
|
||||
|
||||
// Table borders
|
||||
$default-border-color: $default-link-color;
|
||||
|
||||
// Table header
|
||||
$table-text-color: $tab-text-color;
|
||||
$table-background-color1: $tab-background-color1;
|
||||
$table-background-color2: $tab-background-color2;
|
||||
|
||||
// Table of contents, data structure index and prototypes
|
||||
$toc-background-color1: hsl(0,0%,90%);
|
||||
$toc-background-color2: lighten($toc-background-color1, 5%);
|
||||
|
||||
// Function prototype parameters color
|
||||
$prototype-param-color: darken($default-link-color, 25%);
|
||||
|
||||
// Message box color: note, pre, post and invariant
|
||||
$box-note-color: hsl(103,80%,85%);
|
||||
|
||||
// Message box color: warning and attention
|
||||
$box-warning-color: hsl(34,80%,85%);
|
||||
|
||||
// Message box color: deprecated and bug
|
||||
$box-bug-color: hsl(333,80%,85%);
|
||||
|
||||
// Message box color: todo and test
|
||||
$box-todo-color: hsl(200,80%,85%);
|
||||
|
||||
// Message box helper function
|
||||
@mixin message-box($base-color){
|
||||
background:linear-gradient(to bottom,lighten($base-color, 5%) 0%,$base-color 100%);
|
||||
box-shadow:inset 0 0 32px darken($base-color, 5%);
|
||||
color:darken($base-color, 67%);
|
||||
border:2px solid desaturate(darken($base-color, 10%), 20%);
|
||||
}
|
||||
|
||||
.sm-dox,.sm-dox a,.sm-dox a:focus,.sm-dox a:active,.sm-dox a:hover,.sm-dox a.highlighted,.sm-dox ul a:hover {
|
||||
background:none;
|
||||
text-shadow:none;
|
||||
}
|
||||
|
||||
.sm-dox a span.sub-arrow {
|
||||
border-color:$navbar-link-color transparent transparent transparent;
|
||||
}
|
||||
|
||||
.sm-dox a span.sub-arrow:active,.sm-dox a span.sub-arrow:focus,.sm-dox a span.sub-arrow:hover,.sm-dox a:hover span.sub-arrow {
|
||||
border-color:$default-link-color transparent transparent transparent;
|
||||
}
|
||||
|
||||
.sm-dox ul a span.sub-arrow:active,.sm-dox ul a span.sub-arrow:focus,.sm-dox ul a span.sub-arrow:hover,.sm-dox ul a:hover span.sub-arrow {
|
||||
border-color:transparent transparent transparent $default-link-color;
|
||||
}
|
||||
|
||||
.sm-dox ul a:hover {
|
||||
background:$header-footer-link-color;
|
||||
text-shadow:none;
|
||||
}
|
||||
|
||||
.sm-dox ul.sm-nowrap a {
|
||||
color:$default-text-color;
|
||||
text-shadow:none;
|
||||
}
|
||||
|
||||
#main-nav,#main-menu,#main-menu a,#main-menu a:visited,#main-menu a:hover,#main-menu li,.memdoc,dl.reflist dd,div.toc li,.ah,span.lineno,span.lineno a,span.lineno a:hover,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,.doxtable code,.markdownTable code {
|
||||
background:none;
|
||||
}
|
||||
|
||||
#titlearea,.footer,.contents,div.header,.memdoc,table.doxtable td,table.doxtable th,table.markdownTable td,table.markdownTable th,hr,.memSeparator {
|
||||
border:none;
|
||||
}
|
||||
|
||||
#main-menu a,#main-menu a:visited,#main-menu a:hover,#main-menu li,.reflist dt a.el,.levels span,.directory .levels span {
|
||||
text-shadow:none;
|
||||
}
|
||||
|
||||
.memdoc,dl.reflist dd {
|
||||
box-shadow:none;
|
||||
}
|
||||
|
||||
div.headertitle,.note code,.pre code,.post code,.invariant code,.warning code,.attention code,.deprecated code,.bug code,.todo code,.test code,table.doxtable code,table.markdownTable code {
|
||||
padding:0;
|
||||
}
|
||||
|
||||
#nav-path,.directory .levels,span.lineno {
|
||||
display:none;
|
||||
}
|
||||
|
||||
html,#titlearea,.footer,tr.even,.directory tr.even,.doxtable tr:nth-child(even),tr.markdownTableBody:nth-child(even),.mdescLeft,.mdescRight,.memItemLeft,.memItemRight,code,.markdownTableRowEven {
|
||||
background:$header-footer-background-color;
|
||||
}
|
||||
|
||||
body {
|
||||
color:$default-text-color;
|
||||
}
|
||||
|
||||
h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em {
|
||||
color:$heading-color;
|
||||
border-bottom:none;
|
||||
}
|
||||
|
||||
h1 {
|
||||
padding-top:0.5em;
|
||||
font-size:180%;
|
||||
}
|
||||
|
||||
h2 {
|
||||
padding-top:0.5em;
|
||||
margin-bottom:0;
|
||||
font-size:140%;
|
||||
}
|
||||
|
||||
h3 {
|
||||
padding-top:0.5em;
|
||||
margin-bottom:0;
|
||||
font-size:110%;
|
||||
}
|
||||
|
||||
.glfwheader {
|
||||
font-size:16px;
|
||||
min-height:64px;
|
||||
max-width:920px;
|
||||
padding:0 32px;
|
||||
margin:0 auto;
|
||||
|
||||
display: flex;
|
||||
flex-direction: row;
|
||||
flex-wrap: wrap;
|
||||
justify-content: flex-start;
|
||||
align-items: center;
|
||||
align-content: stretch;
|
||||
}
|
||||
|
||||
#glfwhome {
|
||||
line-height:64px;
|
||||
padding-right:48px;
|
||||
color:$header-footer-link-color;
|
||||
font-size:2.5em;
|
||||
background:url("https://www.glfw.org/css/arrow.png") no-repeat right;
|
||||
}
|
||||
|
||||
.glfwnavbar {
|
||||
list-style-type:none;
|
||||
margin:0 0 0 auto;
|
||||
float:right;
|
||||
}
|
||||
|
||||
#glfwhome,.glfwnavbar li {
|
||||
float:left;
|
||||
}
|
||||
|
||||
.glfwnavbar a,.glfwnavbar a:visited {
|
||||
line-height:64px;
|
||||
margin-left:2em;
|
||||
display:block;
|
||||
color:$header-footer-link-color;
|
||||
}
|
||||
|
||||
.glfwnavbar {
|
||||
padding-left: 0;
|
||||
}
|
||||
|
||||
#glfwhome,.glfwnavbar a,.glfwnavbar a:visited {
|
||||
transition:.35s ease;
|
||||
}
|
||||
|
||||
#titlearea,.footer {
|
||||
color:$header-footer-link-color;
|
||||
}
|
||||
|
||||
address.footer {
|
||||
text-align:center;
|
||||
padding:2em;
|
||||
margin-top:3em;
|
||||
}
|
||||
|
||||
#top {
|
||||
background:$header-footer-link-color;
|
||||
}
|
||||
|
||||
#main-nav {
|
||||
max-width:960px;
|
||||
margin:0 auto;
|
||||
font-size:13px;
|
||||
}
|
||||
|
||||
#main-menu {
|
||||
max-width:920px;
|
||||
margin:0 auto;
|
||||
font-size:13px;
|
||||
}
|
||||
|
||||
.memtitle {
|
||||
display:none;
|
||||
}
|
||||
|
||||
.memproto,.memname {
|
||||
font-weight:bold;
|
||||
text-shadow:none;
|
||||
}
|
||||
|
||||
#main-menu {
|
||||
min-height:36px;
|
||||
display: flex;
|
||||
flex-direction: row;
|
||||
flex-wrap: wrap;
|
||||
justify-content: flex-start;
|
||||
align-items: center;
|
||||
align-content: stretch;
|
||||
}
|
||||
|
||||
#main-menu a,#main-menu a:visited,#main-menu a:hover,#main-menu li {
|
||||
color:$navbar-link-color;
|
||||
}
|
||||
|
||||
#main-menu li ul.sm-nowrap li a {
|
||||
color:$default-text-color;
|
||||
}
|
||||
|
||||
#main-menu li ul.sm-nowrap li a:hover {
|
||||
color:$default-link-color;
|
||||
}
|
||||
|
||||
#main-menu > li:last-child {
|
||||
margin: 0 0 0 auto;
|
||||
}
|
||||
|
||||
.contents {
|
||||
min-height:590px;
|
||||
}
|
||||
|
||||
div.contents,div.header {
|
||||
max-width:920px;
|
||||
margin:0 auto;
|
||||
padding:0 32px;
|
||||
background:$content-background-color none;
|
||||
}
|
||||
|
||||
table.doxtable th,table.markdownTable th,dl.reflist dt {
|
||||
background:linear-gradient(to bottom,$table-background-color2 0%,$table-background-color1 100%);
|
||||
box-shadow:inset 0 0 32px $table-background-color1;
|
||||
text-shadow:0 -1px 1px darken($table-background-color1, 15%);
|
||||
text-align:left;
|
||||
color:$table-text-color;
|
||||
}
|
||||
|
||||
dl.reflist dt a.el {
|
||||
color:$default-link-color;
|
||||
padding:.2em;
|
||||
border-radius:4px;
|
||||
background-color:lighten($default-link-color, 40%);
|
||||
}
|
||||
|
||||
div.toc {
|
||||
float:none;
|
||||
width:auto;
|
||||
}
|
||||
|
||||
div.toc h3 {
|
||||
font-size:1.17em;
|
||||
}
|
||||
|
||||
div.toc ul {
|
||||
padding-left:1.5em;
|
||||
}
|
||||
|
||||
div.toc li {
|
||||
font-size:1em;
|
||||
padding-left:0;
|
||||
list-style-type:disc;
|
||||
}
|
||||
|
||||
div.toc,.memproto,div.qindex,div.ah {
|
||||
background:linear-gradient(to bottom,$toc-background-color2 0%,$toc-background-color1 100%);
|
||||
box-shadow:inset 0 0 32px $toc-background-color1;
|
||||
text-shadow:0 1px 1px lighten($toc-background-color2, 10%);
|
||||
color:$heading-color;
|
||||
border:2px solid $toc-background-color1;
|
||||
border-radius:4px;
|
||||
}
|
||||
|
||||
.paramname {
|
||||
color:$prototype-param-color;
|
||||
}
|
||||
|
||||
dl.reflist dt {
|
||||
border:2px solid $default-border-color;
|
||||
border-top-left-radius:4px;
|
||||
border-top-right-radius:4px;
|
||||
border-bottom:none;
|
||||
}
|
||||
|
||||
dl.reflist dd {
|
||||
border:2px solid $default-border-color;
|
||||
border-bottom-right-radius:4px;
|
||||
border-bottom-left-radius:4px;
|
||||
border-top:none;
|
||||
}
|
||||
|
||||
table.doxtable,table.markdownTable {
|
||||
border-collapse:inherit;
|
||||
border-spacing:0;
|
||||
border:2px solid $default-border-color;
|
||||
border-radius:4px;
|
||||
}
|
||||
|
||||
a,a:hover,a:visited,a:visited:hover,.contents a:visited,.el,a.el:visited,#glfwhome:hover,#main-menu a:hover,span.lineno a:hover {
|
||||
color:$default-link-color;
|
||||
text-decoration:none;
|
||||
}
|
||||
|
||||
div.directory {
|
||||
border-collapse:inherit;
|
||||
border-spacing:0;
|
||||
border:2px solid $default-border-color;
|
||||
border-radius:4px;
|
||||
}
|
||||
|
||||
hr,.memSeparator {
|
||||
height:2px;
|
||||
background:linear-gradient(to right,$def-separator-color 0%,darken($def-separator-color, 10%) 50%,$def-separator-color 100%);
|
||||
}
|
||||
|
||||
dl.note,dl.pre,dl.post,dl.invariant {
|
||||
@include message-box($box-note-color);
|
||||
}
|
||||
|
||||
dl.warning,dl.attention {
|
||||
@include message-box($box-warning-color);
|
||||
}
|
||||
|
||||
dl.deprecated,dl.bug {
|
||||
@include message-box($box-bug-color);
|
||||
}
|
||||
|
||||
dl.todo,dl.test {
|
||||
@include message-box($box-todo-color);
|
||||
}
|
||||
|
||||
dl.note,dl.pre,dl.post,dl.invariant,dl.warning,dl.attention,dl.deprecated,dl.bug,dl.todo,dl.test {
|
||||
border-radius:4px;
|
||||
padding:1em;
|
||||
text-shadow:0 1px 1px hsl(0,0%,100%);
|
||||
margin:1em 0;
|
||||
}
|
||||
|
||||
.note a,.pre a,.post a,.invariant a,.warning a,.attention a,.deprecated a,.bug a,.todo a,.test a,.note a:visited,.pre a:visited,.post a:visited,.invariant a:visited,.warning a:visited,.attention a:visited,.deprecated a:visited,.bug a:visited,.todo a:visited,.test a:visited {
|
||||
color:inherit;
|
||||
}
|
||||
|
||||
div.line {
|
||||
line-height:inherit;
|
||||
}
|
||||
|
||||
div.fragment,pre.fragment {
|
||||
background:hsl(0,0%,95%);
|
||||
border-radius:4px;
|
||||
border:none;
|
||||
padding:1em;
|
||||
overflow:auto;
|
||||
border-left:4px solid hsl(0,0%,80%);
|
||||
margin:1em 0;
|
||||
}
|
||||
|
||||
.lineno a,.lineno a:visited,.line,pre.fragment {
|
||||
color:$default-text-color;
|
||||
}
|
||||
|
||||
span.preprocessor,span.comment {
|
||||
color:hsl(193,100%,30%);
|
||||
}
|
||||
|
||||
a.code,a.code:visited {
|
||||
color:hsl(18,100%,45%);
|
||||
}
|
||||
|
||||
span.keyword,span.keywordtype,span.keywordflow {
|
||||
color:darken($default-text-color, 5%);
|
||||
font-weight:bold;
|
||||
}
|
||||
|
||||
span.stringliteral {
|
||||
color:hsl(261,100%,30%);
|
||||
}
|
||||
|
||||
code {
|
||||
padding:.1em;
|
||||
border-radius:4px;
|
||||
}
|
||||
7
src/external/glfw/docs/footer.html
vendored
7
src/external/glfw/docs/footer.html
vendored
|
|
@ -1,7 +0,0 @@
|
|||
<address class="footer">
|
||||
<p>
|
||||
Last update on $date for $projectname $projectnumber
|
||||
</p>
|
||||
</address>
|
||||
</body>
|
||||
</html>
|
||||
34
src/external/glfw/docs/header.html
vendored
34
src/external/glfw/docs/header.html
vendored
|
|
@ -1,34 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||||
<meta name="generator" content="Doxygen $doxygenversion"/>
|
||||
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
|
||||
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
|
||||
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
|
||||
<script type="text/javascript" src="$relpath^jquery.js"></script>
|
||||
<script type="text/javascript" src="$relpath^dynsections.js"></script>
|
||||
$treeview
|
||||
$search
|
||||
$mathjax
|
||||
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
|
||||
$extrastylesheet
|
||||
</head>
|
||||
<body>
|
||||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||||
|
||||
<!--BEGIN TITLEAREA-->
|
||||
<div id="titlearea">
|
||||
<div class="glfwheader">
|
||||
<a href="https://www.glfw.org/" id="glfwhome">GLFW</a>
|
||||
<ul class="glfwnavbar">
|
||||
<li><a href="https://www.glfw.org/documentation.html">Documentation</a></li>
|
||||
<li><a href="https://www.glfw.org/download.html">Download</a></li>
|
||||
<li><a href="https://www.glfw.org/community.html">Community</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<!--END TITLEAREA-->
|
||||
<!-- end header part -->
|
||||
968
src/external/glfw/docs/input.dox
vendored
968
src/external/glfw/docs/input.dox
vendored
|
|
@ -1,968 +0,0 @@
|
|||
/*!
|
||||
|
||||
@page input_guide Input guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide introduces the input related functions of GLFW. For details on
|
||||
a specific function in this category, see the @ref input. There are also guides
|
||||
for the other areas of GLFW.
|
||||
|
||||
- @ref intro_guide
|
||||
- @ref window_guide
|
||||
- @ref context_guide
|
||||
- @ref vulkan_guide
|
||||
- @ref monitor_guide
|
||||
|
||||
GLFW provides many kinds of input. While some can only be polled, like time, or
|
||||
only received via callbacks, like scrolling, many provide both callbacks and
|
||||
polling. Callbacks are more work to use than polling but is less CPU intensive
|
||||
and guarantees that you do not miss state changes.
|
||||
|
||||
All input callbacks receive a window handle. By using the
|
||||
[window user pointer](@ref window_userptr), you can access non-global structures
|
||||
or objects from your callbacks.
|
||||
|
||||
To get a better feel for how the various events callbacks behave, run the
|
||||
`events` test program. It registers every callback supported by GLFW and prints
|
||||
out all arguments provided for every event, along with time and sequence
|
||||
information.
|
||||
|
||||
|
||||
@section events Event processing
|
||||
|
||||
GLFW needs to poll the window system for events both to provide input to the
|
||||
application and to prove to the window system that the application hasn't locked
|
||||
up. Event processing is normally done each frame after
|
||||
[buffer swapping](@ref buffer_swap). Even when you have no windows, event
|
||||
polling needs to be done in order to receive monitor and joystick connection
|
||||
events.
|
||||
|
||||
There are three functions for processing pending events. @ref glfwPollEvents,
|
||||
processes only those events that have already been received and then returns
|
||||
immediately.
|
||||
|
||||
@code
|
||||
glfwPollEvents();
|
||||
@endcode
|
||||
|
||||
This is the best choice when rendering continuously, like most games do.
|
||||
|
||||
If you only need to update the contents of the window when you receive new
|
||||
input, @ref glfwWaitEvents is a better choice.
|
||||
|
||||
@code
|
||||
glfwWaitEvents();
|
||||
@endcode
|
||||
|
||||
It puts the thread to sleep until at least one event has been received and then
|
||||
processes all received events. This saves a great deal of CPU cycles and is
|
||||
useful for, for example, editing tools.
|
||||
|
||||
If you want to wait for events but have UI elements or other tasks that need
|
||||
periodic updates, @ref glfwWaitEventsTimeout lets you specify a timeout.
|
||||
|
||||
@code
|
||||
glfwWaitEventsTimeout(0.7);
|
||||
@endcode
|
||||
|
||||
It puts the thread to sleep until at least one event has been received, or until
|
||||
the specified number of seconds have elapsed. It then processes any received
|
||||
events.
|
||||
|
||||
If the main thread is sleeping in @ref glfwWaitEvents, you can wake it from
|
||||
another thread by posting an empty event to the event queue with @ref
|
||||
glfwPostEmptyEvent.
|
||||
|
||||
@code
|
||||
glfwPostEmptyEvent();
|
||||
@endcode
|
||||
|
||||
Do not assume that callbacks will _only_ be called in response to the above
|
||||
functions. While it is necessary to process events in one or more of the ways
|
||||
above, window systems that require GLFW to register callbacks of its own can
|
||||
pass events to GLFW in response to many window system function calls. GLFW will
|
||||
pass those events on to the application callbacks before returning.
|
||||
|
||||
For example, on Windows the system function that @ref glfwSetWindowSize is
|
||||
implemented with will send window size events directly to the event callback
|
||||
that every window has and that GLFW implements for its windows. If you have set
|
||||
a [window size callback](@ref window_size) GLFW will call it in turn with the
|
||||
new size before everything returns back out of the @ref glfwSetWindowSize call.
|
||||
|
||||
|
||||
@section input_keyboard Keyboard input
|
||||
|
||||
GLFW divides keyboard input into two categories; key events and character
|
||||
events. Key events relate to actual physical keyboard keys, whereas character
|
||||
events relate to the text that is generated by pressing some of them.
|
||||
|
||||
Keys and characters do not map 1:1. A single key press may produce several
|
||||
characters, and a single character may require several keys to produce. This
|
||||
may not be the case on your machine, but your users are likely not all using the
|
||||
same keyboard layout, input method or even operating system as you.
|
||||
|
||||
|
||||
@subsection input_key Key input
|
||||
|
||||
If you wish to be notified when a physical key is pressed or released or when it
|
||||
repeats, set a key callback.
|
||||
|
||||
@code
|
||||
glfwSetKeyCallback(window, key_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the [keyboard key](@ref keys), platform-specific
|
||||
scancode, key action and [modifier bits](@ref mods).
|
||||
|
||||
@code
|
||||
void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
|
||||
{
|
||||
if (key == GLFW_KEY_E && action == GLFW_PRESS)
|
||||
activate_airship();
|
||||
}
|
||||
@endcode
|
||||
|
||||
The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. Events with
|
||||
`GLFW_PRESS` and `GLFW_RELEASE` actions are emitted for every key press. Most
|
||||
keys will also emit events with `GLFW_REPEAT` actions while a key is held down.
|
||||
|
||||
Note that many keyboards have a limit on how many keys being simultaneous held
|
||||
down that they can detect. This limit is called
|
||||
[key rollover](https://en.wikipedia.org/wiki/Key_rollover).
|
||||
|
||||
Key events with `GLFW_REPEAT` actions are intended for text input. They are
|
||||
emitted at the rate set in the user's keyboard settings. At most one key is
|
||||
repeated even if several keys are held down. `GLFW_REPEAT` actions should not
|
||||
be relied on to know which keys are being held down or to drive animation.
|
||||
Instead you should either save the state of relevant keys based on `GLFW_PRESS`
|
||||
and `GLFW_RELEASE` actions, or call @ref glfwGetKey, which provides basic cached
|
||||
key state.
|
||||
|
||||
The key will be one of the existing [key tokens](@ref keys), or
|
||||
`GLFW_KEY_UNKNOWN` if GLFW lacks a token for it, for example _E-mail_ and _Play_
|
||||
keys.
|
||||
|
||||
The scancode is unique for every key, regardless of whether it has a key token.
|
||||
Scancodes are platform-specific but consistent over time, so keys will have
|
||||
different scancodes depending on the platform but they are safe to save to disk.
|
||||
You can query the scancode for any [key token](@ref keys) supported on the
|
||||
current platform with @ref glfwGetKeyScancode.
|
||||
|
||||
@code
|
||||
const int scancode = glfwGetKeyScancode(GLFW_KEY_X);
|
||||
set_key_mapping(scancode, swap_weapons);
|
||||
@endcode
|
||||
|
||||
The last reported state for every physical key with a [key token](@ref keys) is
|
||||
also saved in per-window state arrays that can be polled with @ref glfwGetKey.
|
||||
|
||||
@code
|
||||
int state = glfwGetKey(window, GLFW_KEY_E);
|
||||
if (state == GLFW_PRESS)
|
||||
{
|
||||
activate_airship();
|
||||
}
|
||||
@endcode
|
||||
|
||||
The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
|
||||
|
||||
This function only returns cached key event state. It does not poll the
|
||||
system for the current state of the physical key. It also does not provide any
|
||||
key repeat information.
|
||||
|
||||
@anchor GLFW_STICKY_KEYS
|
||||
Whenever you poll state, you risk missing the state change you are looking for.
|
||||
If a pressed key is released again before you poll its state, you will have
|
||||
missed the key press. The recommended solution for this is to use a
|
||||
key callback, but there is also the `GLFW_STICKY_KEYS` input mode.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_STICKY_KEYS, GLFW_TRUE);
|
||||
@endcode
|
||||
|
||||
When sticky keys mode is enabled, the pollable state of a key will remain
|
||||
`GLFW_PRESS` until the state of that key is polled with @ref glfwGetKey. Once
|
||||
it has been polled, if a key release event had been processed in the meantime,
|
||||
the state will reset to `GLFW_RELEASE`, otherwise it will remain `GLFW_PRESS`.
|
||||
|
||||
@anchor GLFW_LOCK_KEY_MODS
|
||||
If you wish to know what the state of the Caps Lock and Num Lock keys was when
|
||||
input events were generated, set the `GLFW_LOCK_KEY_MODS` input mode.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_LOCK_KEY_MODS, GLFW_TRUE);
|
||||
@endcode
|
||||
|
||||
When this input mode is enabled, any callback that receives
|
||||
[modifier bits](@ref mods) will have the @ref GLFW_MOD_CAPS_LOCK bit set if Caps
|
||||
Lock was on when the event occurred and the @ref GLFW_MOD_NUM_LOCK bit set if
|
||||
Num Lock was on.
|
||||
|
||||
The `GLFW_KEY_LAST` constant holds the highest value of any
|
||||
[key token](@ref keys).
|
||||
|
||||
|
||||
@subsection input_char Text input
|
||||
|
||||
GLFW supports text input in the form of a stream of
|
||||
[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the
|
||||
operating system text input system. Unlike key input, text input is affected by
|
||||
keyboard layouts and modifier keys and supports composing characters using
|
||||
[dead keys](https://en.wikipedia.org/wiki/Dead_key). Once received, you can
|
||||
encode the code points into UTF-8 or any other encoding you prefer.
|
||||
|
||||
Because an `unsigned int` is 32 bits long on all platforms supported by GLFW,
|
||||
you can treat the code point argument as native endian UTF-32.
|
||||
|
||||
If you wish to offer regular text input, set a character callback.
|
||||
|
||||
@code
|
||||
glfwSetCharCallback(window, character_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives Unicode code points for key events that would
|
||||
have led to regular text input and generally behaves as a standard text field on
|
||||
that platform.
|
||||
|
||||
@code
|
||||
void character_callback(GLFWwindow* window, unsigned int codepoint)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection input_key_name Key names
|
||||
|
||||
If you wish to refer to keys by name, you can query the keyboard layout
|
||||
dependent name of printable keys with @ref glfwGetKeyName.
|
||||
|
||||
@code
|
||||
const char* key_name = glfwGetKeyName(GLFW_KEY_W, 0);
|
||||
show_tutorial_hint("Press %s to move forward", key_name);
|
||||
@endcode
|
||||
|
||||
This function can handle both [keys and scancodes](@ref input_key). If the
|
||||
specified key is `GLFW_KEY_UNKNOWN` then the scancode is used, otherwise it is
|
||||
ignored. This matches the behavior of the key callback, meaning the callback
|
||||
arguments can always be passed unmodified to this function.
|
||||
|
||||
|
||||
@section input_mouse Mouse input
|
||||
|
||||
Mouse input comes in many forms, including mouse motion, button presses and
|
||||
scrolling offsets. The cursor appearance can also be changed, either to
|
||||
a custom image or a standard cursor shape from the system theme.
|
||||
|
||||
|
||||
@subsection cursor_pos Cursor position
|
||||
|
||||
If you wish to be notified when the cursor moves over the window, set a cursor
|
||||
position callback.
|
||||
|
||||
@code
|
||||
glfwSetCursorPosCallback(window, cursor_position_callback);
|
||||
@endcode
|
||||
|
||||
The callback functions receives the cursor position, measured in screen
|
||||
coordinates but relative to the top-left corner of the window content area. On
|
||||
platforms that provide it, the full sub-pixel cursor position is passed on.
|
||||
|
||||
@code
|
||||
static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
The cursor position is also saved per-window and can be polled with @ref
|
||||
glfwGetCursorPos.
|
||||
|
||||
@code
|
||||
double xpos, ypos;
|
||||
glfwGetCursorPos(window, &xpos, &ypos);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection cursor_mode Cursor mode
|
||||
|
||||
@anchor GLFW_CURSOR
|
||||
The `GLFW_CURSOR` input mode provides several cursor modes for special forms of
|
||||
mouse motion input. By default, the cursor mode is `GLFW_CURSOR_NORMAL`,
|
||||
meaning the regular arrow cursor (or another cursor set with @ref glfwSetCursor)
|
||||
is used and cursor motion is not limited.
|
||||
|
||||
If you wish to implement mouse motion based camera controls or other input
|
||||
schemes that require unlimited mouse movement, set the cursor mode to
|
||||
`GLFW_CURSOR_DISABLED`.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED);
|
||||
@endcode
|
||||
|
||||
This will hide the cursor and lock it to the specified window. GLFW will then
|
||||
take care of all the details of cursor re-centering and offset calculation and
|
||||
providing the application with a virtual cursor position. This virtual position
|
||||
is provided normally via both the cursor position callback and through polling.
|
||||
|
||||
@note You should not implement your own version of this functionality using
|
||||
other features of GLFW. It is not supported and will not work as robustly as
|
||||
`GLFW_CURSOR_DISABLED`.
|
||||
|
||||
If you only wish the cursor to become hidden when it is over a window but still
|
||||
want it to behave normally, set the cursor mode to `GLFW_CURSOR_HIDDEN`.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN);
|
||||
@endcode
|
||||
|
||||
This mode puts no limit on the motion of the cursor.
|
||||
|
||||
To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL`
|
||||
cursor mode.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL);
|
||||
@endcode
|
||||
|
||||
|
||||
@anchor GLFW_RAW_MOUSE_MOTION
|
||||
@subsection raw_mouse_motion Raw mouse motion
|
||||
|
||||
When the cursor is disabled, raw (unscaled and unaccelerated) mouse motion can
|
||||
be enabled if available.
|
||||
|
||||
Raw mouse motion is closer to the actual motion of the mouse across a surface.
|
||||
It is not affected by the scaling and acceleration applied to the motion of the
|
||||
desktop cursor. That processing is suitable for a cursor while raw motion is
|
||||
better for controlling for example a 3D camera. Because of this, raw mouse
|
||||
motion is only provided when the cursor is disabled.
|
||||
|
||||
Call @ref glfwRawMouseMotionSupported to check if the current machine provides
|
||||
raw motion and set the `GLFW_RAW_MOUSE_MOTION` input mode to enable it. It is
|
||||
disabled by default.
|
||||
|
||||
@code
|
||||
if (glfwRawMouseMotionSupported())
|
||||
glfwSetInputMode(window, GLFW_RAW_MOUSE_MOTION, GLFW_TRUE);
|
||||
@endcode
|
||||
|
||||
If supported, raw mouse motion can be enabled or disabled per-window and at any
|
||||
time but it will only be provided when the cursor is disabled.
|
||||
|
||||
|
||||
@subsection cursor_object Cursor objects
|
||||
|
||||
GLFW supports creating both custom and system theme cursor images, encapsulated
|
||||
as @ref GLFWcursor objects. They are created with @ref glfwCreateCursor or @ref
|
||||
glfwCreateStandardCursor and destroyed with @ref glfwDestroyCursor, or @ref
|
||||
glfwTerminate, if any remain.
|
||||
|
||||
|
||||
@subsubsection cursor_custom Custom cursor creation
|
||||
|
||||
A custom cursor is created with @ref glfwCreateCursor, which returns a handle to
|
||||
the created cursor object. For example, this creates a 16x16 white square
|
||||
cursor with the hot-spot in the upper-left corner:
|
||||
|
||||
@code
|
||||
unsigned char pixels[16 * 16 * 4];
|
||||
memset(pixels, 0xff, sizeof(pixels));
|
||||
|
||||
GLFWimage image;
|
||||
image.width = 16;
|
||||
image.height = 16;
|
||||
image.pixels = pixels;
|
||||
|
||||
GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);
|
||||
@endcode
|
||||
|
||||
If cursor creation fails, `NULL` will be returned, so it is necessary to check
|
||||
the return value.
|
||||
|
||||
The image data is 32-bit, little-endian, non-premultiplied RGBA, i.e. eight bits
|
||||
per channel with the red channel first. The pixels are arranged canonically as
|
||||
sequential rows, starting from the top-left corner.
|
||||
|
||||
|
||||
@subsubsection cursor_standard Standard cursor creation
|
||||
|
||||
A cursor with a [standard shape](@ref shapes) from the current system cursor
|
||||
theme can be created with @ref glfwCreateStandardCursor.
|
||||
|
||||
@code
|
||||
GLFWcursor* cursor = glfwCreateStandardCursor(GLFW_HRESIZE_CURSOR);
|
||||
@endcode
|
||||
|
||||
These cursor objects behave in the exact same way as those created with @ref
|
||||
glfwCreateCursor except that the system cursor theme provides the actual image.
|
||||
|
||||
|
||||
@subsubsection cursor_destruction Cursor destruction
|
||||
|
||||
When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
|
||||
|
||||
@code
|
||||
glfwDestroyCursor(cursor);
|
||||
@endcode
|
||||
|
||||
Cursor destruction always succeeds. If the cursor is current for any window,
|
||||
that window will revert to the default cursor. This does not affect the cursor
|
||||
mode. All remaining cursors are destroyed when @ref glfwTerminate is called.
|
||||
|
||||
|
||||
@subsubsection cursor_set Cursor setting
|
||||
|
||||
A cursor can be set as current for a window with @ref glfwSetCursor.
|
||||
|
||||
@code
|
||||
glfwSetCursor(window, cursor);
|
||||
@endcode
|
||||
|
||||
Once set, the cursor image will be used as long as the system cursor is over the
|
||||
content area of the window and the [cursor mode](@ref cursor_mode) is set
|
||||
to `GLFW_CURSOR_NORMAL`.
|
||||
|
||||
A single cursor may be set for any number of windows.
|
||||
|
||||
To revert to the default cursor, set the cursor of that window to `NULL`.
|
||||
|
||||
@code
|
||||
glfwSetCursor(window, NULL);
|
||||
@endcode
|
||||
|
||||
When a cursor is destroyed, any window that has it set will revert to the
|
||||
default cursor. This does not affect the cursor mode.
|
||||
|
||||
|
||||
@subsection cursor_enter Cursor enter/leave events
|
||||
|
||||
If you wish to be notified when the cursor enters or leaves the content area of
|
||||
a window, set a cursor enter/leave callback.
|
||||
|
||||
@code
|
||||
glfwSetCursorEnterCallback(window, cursor_enter_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the new classification of the cursor.
|
||||
|
||||
@code
|
||||
void cursor_enter_callback(GLFWwindow* window, int entered)
|
||||
{
|
||||
if (entered)
|
||||
{
|
||||
// The cursor entered the content area of the window
|
||||
}
|
||||
else
|
||||
{
|
||||
// The cursor left the content area of the window
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
You can query whether the cursor is currently inside the content area of the
|
||||
window with the [GLFW_HOVERED](@ref GLFW_HOVERED_attrib) window attribute.
|
||||
|
||||
@code
|
||||
if (glfwGetWindowAttrib(window, GLFW_HOVERED))
|
||||
{
|
||||
highlight_interface();
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection input_mouse_button Mouse button input
|
||||
|
||||
If you wish to be notified when a mouse button is pressed or released, set
|
||||
a mouse button callback.
|
||||
|
||||
@code
|
||||
glfwSetMouseButtonCallback(window, mouse_button_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the [mouse button](@ref buttons), button action
|
||||
and [modifier bits](@ref mods).
|
||||
|
||||
@code
|
||||
void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)
|
||||
{
|
||||
if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS)
|
||||
popup_menu();
|
||||
}
|
||||
@endcode
|
||||
|
||||
The action is one of `GLFW_PRESS` or `GLFW_RELEASE`.
|
||||
|
||||
The last reported state for every [supported mouse button](@ref buttons) is also
|
||||
saved in per-window state arrays that can be polled with @ref
|
||||
glfwGetMouseButton.
|
||||
|
||||
@code
|
||||
int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
|
||||
if (state == GLFW_PRESS)
|
||||
{
|
||||
upgrade_cow();
|
||||
}
|
||||
@endcode
|
||||
|
||||
The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
|
||||
|
||||
This function only returns cached mouse button event state. It does not poll
|
||||
the system for the current state of the mouse button.
|
||||
|
||||
@anchor GLFW_STICKY_MOUSE_BUTTONS
|
||||
Whenever you poll state, you risk missing the state change you are looking for.
|
||||
If a pressed mouse button is released again before you poll its state, you will have
|
||||
missed the button press. The recommended solution for this is to use a
|
||||
mouse button callback, but there is also the `GLFW_STICKY_MOUSE_BUTTONS`
|
||||
input mode.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, GLFW_TRUE);
|
||||
@endcode
|
||||
|
||||
When sticky mouse buttons mode is enabled, the pollable state of a mouse button
|
||||
will remain `GLFW_PRESS` until the state of that button is polled with @ref
|
||||
glfwGetMouseButton. Once it has been polled, if a mouse button release event
|
||||
had been processed in the meantime, the state will reset to `GLFW_RELEASE`,
|
||||
otherwise it will remain `GLFW_PRESS`.
|
||||
|
||||
The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
|
||||
[supported mouse button](@ref buttons).
|
||||
|
||||
|
||||
@subsection scrolling Scroll input
|
||||
|
||||
If you wish to be notified when the user scrolls, whether with a mouse wheel or
|
||||
touchpad gesture, set a scroll callback.
|
||||
|
||||
@code
|
||||
glfwSetScrollCallback(window, scroll_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives two-dimensional scroll offsets.
|
||||
|
||||
@code
|
||||
void scroll_callback(GLFWwindow* window, double xoffset, double yoffset)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
A normal mouse wheel, being vertical, provides offsets along the Y-axis.
|
||||
|
||||
|
||||
@section joystick Joystick input
|
||||
|
||||
The joystick functions expose connected joysticks and controllers, with both
|
||||
referred to as joysticks. It supports up to sixteen joysticks, ranging from
|
||||
`GLFW_JOYSTICK_1`, `GLFW_JOYSTICK_2` up to and including `GLFW_JOYSTICK_16` or
|
||||
`GLFW_JOYSTICK_LAST`. You can test whether a [joystick](@ref joysticks) is
|
||||
present with @ref glfwJoystickPresent.
|
||||
|
||||
@code
|
||||
int present = glfwJoystickPresent(GLFW_JOYSTICK_1);
|
||||
@endcode
|
||||
|
||||
Each joystick has zero or more axes, zero or more buttons, zero or more hats,
|
||||
a human-readable name, a user pointer and an SDL compatible GUID.
|
||||
|
||||
When GLFW is initialized, detected joysticks are added to the beginning of
|
||||
the array. Once a joystick is detected, it keeps its assigned ID until it is
|
||||
disconnected or the library is terminated, so as joysticks are connected and
|
||||
disconnected, there may appear gaps in the IDs.
|
||||
|
||||
Joystick axis, button and hat state is updated when polled and does not require
|
||||
a window to be created or events to be processed. However, if you want joystick
|
||||
connection and disconnection events reliably delivered to the
|
||||
[joystick callback](@ref joystick_event) then you must
|
||||
[process events](@ref events).
|
||||
|
||||
To see all the properties of all connected joysticks in real-time, run the
|
||||
`joysticks` test program.
|
||||
|
||||
|
||||
@subsection joystick_axis Joystick axis states
|
||||
|
||||
The positions of all axes of a joystick are returned by @ref
|
||||
glfwGetJoystickAxes. See the reference documentation for the lifetime of the
|
||||
returned array.
|
||||
|
||||
@code
|
||||
int count;
|
||||
const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_5, &count);
|
||||
@endcode
|
||||
|
||||
Each element in the returned array is a value between -1.0 and 1.0.
|
||||
|
||||
|
||||
@subsection joystick_button Joystick button states
|
||||
|
||||
The states of all buttons of a joystick are returned by @ref
|
||||
glfwGetJoystickButtons. See the reference documentation for the lifetime of the
|
||||
returned array.
|
||||
|
||||
@code
|
||||
int count;
|
||||
const unsigned char* buttons = glfwGetJoystickButtons(GLFW_JOYSTICK_3, &count);
|
||||
@endcode
|
||||
|
||||
Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`.
|
||||
|
||||
For backward compatibility with earlier versions that did not have @ref
|
||||
glfwGetJoystickHats, the button array by default also includes all hats. See
|
||||
the reference documentation for @ref glfwGetJoystickButtons for details.
|
||||
|
||||
|
||||
@subsection joystick_hat Joystick hat states
|
||||
|
||||
The states of all hats are returned by @ref glfwGetJoystickHats. See the
|
||||
reference documentation for the lifetime of the returned array.
|
||||
|
||||
@code
|
||||
int count;
|
||||
const unsigned char* hats = glfwGetJoystickHats(GLFW_JOYSTICK_7, &count);
|
||||
@endcode
|
||||
|
||||
Each element in the returned array is one of the following:
|
||||
|
||||
Name | Value
|
||||
---- | -----
|
||||
`GLFW_HAT_CENTERED` | 0
|
||||
`GLFW_HAT_UP` | 1
|
||||
`GLFW_HAT_RIGHT` | 2
|
||||
`GLFW_HAT_DOWN` | 4
|
||||
`GLFW_HAT_LEFT` | 8
|
||||
`GLFW_HAT_RIGHT_UP` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_UP`
|
||||
`GLFW_HAT_RIGHT_DOWN` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_DOWN`
|
||||
`GLFW_HAT_LEFT_UP` | `GLFW_HAT_LEFT` \| `GLFW_HAT_UP`
|
||||
`GLFW_HAT_LEFT_DOWN` | `GLFW_HAT_LEFT` \| `GLFW_HAT_DOWN`
|
||||
|
||||
The diagonal directions are bitwise combinations of the primary (up, right, down
|
||||
and left) directions and you can test for these individually by ANDing it with
|
||||
the corresponding direction.
|
||||
|
||||
@code
|
||||
if (hats[2] & GLFW_HAT_RIGHT)
|
||||
{
|
||||
// State of hat 2 could be right-up, right or right-down
|
||||
}
|
||||
@endcode
|
||||
|
||||
For backward compatibility with earlier versions that did not have @ref
|
||||
glfwGetJoystickHats, all hats are by default also included in the button array.
|
||||
See the reference documentation for @ref glfwGetJoystickButtons for details.
|
||||
|
||||
|
||||
@subsection joystick_name Joystick name
|
||||
|
||||
The human-readable, UTF-8 encoded name of a joystick is returned by @ref
|
||||
glfwGetJoystickName. See the reference documentation for the lifetime of the
|
||||
returned string.
|
||||
|
||||
@code
|
||||
const char* name = glfwGetJoystickName(GLFW_JOYSTICK_4);
|
||||
@endcode
|
||||
|
||||
Joystick names are not guaranteed to be unique. Two joysticks of the same model
|
||||
and make may have the same name. Only the [joystick ID](@ref joysticks) is
|
||||
guaranteed to be unique, and only until that joystick is disconnected.
|
||||
|
||||
|
||||
@subsection joystick_userptr Joystick user pointer
|
||||
|
||||
Each joystick has a user pointer that can be set with @ref
|
||||
glfwSetJoystickUserPointer and queried with @ref glfwGetJoystickUserPointer.
|
||||
This can be used for any purpose you need and will not be modified by GLFW. The
|
||||
value will be kept until the joystick is disconnected or until the library is
|
||||
terminated.
|
||||
|
||||
The initial value of the pointer is `NULL`.
|
||||
|
||||
|
||||
@subsection joystick_event Joystick configuration changes
|
||||
|
||||
If you wish to be notified when a joystick is connected or disconnected, set
|
||||
a joystick callback.
|
||||
|
||||
@code
|
||||
glfwSetJoystickCallback(joystick_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the ID of the joystick that has been connected
|
||||
and disconnected and the event that occurred.
|
||||
|
||||
@code
|
||||
void joystick_callback(int jid, int event)
|
||||
{
|
||||
if (event == GLFW_CONNECTED)
|
||||
{
|
||||
// The joystick was connected
|
||||
}
|
||||
else if (event == GLFW_DISCONNECTED)
|
||||
{
|
||||
// The joystick was disconnected
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
For joystick connection and disconnection events to be delivered on all
|
||||
platforms, you need to call one of the [event processing](@ref events)
|
||||
functions. Joystick disconnection may also be detected and the callback
|
||||
called by joystick functions. The function will then return whatever it
|
||||
returns for a disconnected joystick.
|
||||
|
||||
Only @ref glfwGetJoystickName and @ref glfwGetJoystickUserPointer will return
|
||||
useful values for a disconnected joystick and only before the monitor callback
|
||||
returns.
|
||||
|
||||
|
||||
@subsection gamepad Gamepad input
|
||||
|
||||
The joystick functions provide unlabeled axes, buttons and hats, with no
|
||||
indication of where they are located on the device. Their order may also vary
|
||||
between platforms even with the same device.
|
||||
|
||||
To solve this problem the SDL community crowdsourced the
|
||||
[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) project,
|
||||
a database of mappings from many different devices to an Xbox-like gamepad.
|
||||
|
||||
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
|
||||
this at runtime. Mappings will be assigned to joysticks automatically any time
|
||||
a joystick is connected or the mappings are updated.
|
||||
|
||||
You can check whether a joystick is both present and has a gamepad mapping with
|
||||
@ref glfwJoystickIsGamepad.
|
||||
|
||||
@code
|
||||
if (glfwJoystickIsGamepad(GLFW_JOYSTICK_2))
|
||||
{
|
||||
// Use as gamepad
|
||||
}
|
||||
@endcode
|
||||
|
||||
If you are only interested in gamepad input you can use this function instead of
|
||||
@ref glfwJoystickPresent.
|
||||
|
||||
You can query the human-readable name provided by the gamepad mapping with @ref
|
||||
glfwGetGamepadName. This may or may not be the same as the
|
||||
[joystick name](@ref joystick_name).
|
||||
|
||||
@code
|
||||
const char* name = glfwGetGamepadName(GLFW_JOYSTICK_7);
|
||||
@endcode
|
||||
|
||||
To retrieve the gamepad state of a joystick, call @ref glfwGetGamepadState.
|
||||
|
||||
@code
|
||||
GLFWgamepadstate state;
|
||||
|
||||
if (glfwGetGamepadState(GLFW_JOYSTICK_3, &state))
|
||||
{
|
||||
if (state.buttons[GLFW_GAMEPAD_BUTTON_A])
|
||||
{
|
||||
input_jump();
|
||||
}
|
||||
|
||||
input_speed(state.axes[GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER]);
|
||||
}
|
||||
@endcode
|
||||
|
||||
The @ref GLFWgamepadstate struct has two arrays; one for button states and one
|
||||
for axis states. The values for each button and axis are the same as for the
|
||||
@ref glfwGetJoystickButtons and @ref glfwGetJoystickAxes functions, i.e.
|
||||
`GLFW_PRESS` or `GLFW_RELEASE` for buttons and -1.0 to 1.0 inclusive for axes.
|
||||
|
||||
The sizes of the arrays and the positions within each array are fixed.
|
||||
|
||||
The [button indices](@ref gamepad_buttons) are `GLFW_GAMEPAD_BUTTON_A`,
|
||||
`GLFW_GAMEPAD_BUTTON_B`, `GLFW_GAMEPAD_BUTTON_X`, `GLFW_GAMEPAD_BUTTON_Y`,
|
||||
`GLFW_GAMEPAD_BUTTON_LEFT_BUMPER`, `GLFW_GAMEPAD_BUTTON_RIGHT_BUMPER`,
|
||||
`GLFW_GAMEPAD_BUTTON_BACK`, `GLFW_GAMEPAD_BUTTON_START`,
|
||||
`GLFW_GAMEPAD_BUTTON_GUIDE`, `GLFW_GAMEPAD_BUTTON_LEFT_THUMB`,
|
||||
`GLFW_GAMEPAD_BUTTON_RIGHT_THUMB`, `GLFW_GAMEPAD_BUTTON_DPAD_UP`,
|
||||
`GLFW_GAMEPAD_BUTTON_DPAD_RIGHT`, `GLFW_GAMEPAD_BUTTON_DPAD_DOWN` and
|
||||
`GLFW_GAMEPAD_BUTTON_DPAD_LEFT`.
|
||||
|
||||
For those who prefer, there are also the `GLFW_GAMEPAD_BUTTON_CROSS`,
|
||||
`GLFW_GAMEPAD_BUTTON_CIRCLE`, `GLFW_GAMEPAD_BUTTON_SQUARE` and
|
||||
`GLFW_GAMEPAD_BUTTON_TRIANGLE` aliases for the A, B, X and Y button indices.
|
||||
|
||||
The [axis indices](@ref gamepad_axes) are `GLFW_GAMEPAD_AXIS_LEFT_X`,
|
||||
`GLFW_GAMEPAD_AXIS_LEFT_Y`, `GLFW_GAMEPAD_AXIS_RIGHT_X`,
|
||||
`GLFW_GAMEPAD_AXIS_RIGHT_Y`, `GLFW_GAMEPAD_AXIS_LEFT_TRIGGER` and
|
||||
`GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER`.
|
||||
|
||||
The `GLFW_GAMEPAD_BUTTON_LAST` and `GLFW_GAMEPAD_AXIS_LAST` constants equal
|
||||
the largest available index for each array.
|
||||
|
||||
|
||||
@subsection gamepad_mapping Gamepad mappings
|
||||
|
||||
GLFW contains a copy of the mappings available in
|
||||
[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) at the
|
||||
time of release. Newer ones can be added at runtime with @ref
|
||||
glfwUpdateGamepadMappings.
|
||||
|
||||
@code
|
||||
const char* mappings = load_file_contents("game/data/gamecontrollerdb.txt");
|
||||
|
||||
glfwUpdateGamepadMappings(mappings);
|
||||
@endcode
|
||||
|
||||
This function supports everything from single lines up to and including the
|
||||
unmodified contents of the whole `gamecontrollerdb.txt` file.
|
||||
|
||||
If you are compiling GLFW from source with CMake you can update the built-in mappings by
|
||||
building the _update_mappings_ target. This runs the `GenerateMappings.cmake` CMake
|
||||
script, which downloads `gamecontrollerdb.txt` and regenerates the `mappings.h` header
|
||||
file.
|
||||
|
||||
Below is a description of the mapping format. Please keep in mind that __this
|
||||
description is not authoritative__. The format is defined by the SDL and
|
||||
SDL_GameControllerDB projects and their documentation and code takes precedence.
|
||||
|
||||
Each mapping is a single line of comma-separated values describing the GUID,
|
||||
name and layout of the gamepad. Lines that do not begin with a hexadecimal
|
||||
digit are ignored.
|
||||
|
||||
The first value is always the gamepad GUID, a 32 character long hexadecimal
|
||||
string that typically identifies its make, model, revision and the type of
|
||||
connection to the computer. When this information is not available, the GUID is
|
||||
generated using the gamepad name. GLFW uses the SDL 2.0.5+ GUID format but can
|
||||
convert from the older formats.
|
||||
|
||||
The second value is always the human-readable name of the gamepad.
|
||||
|
||||
All subsequent values are in the form `<field>:<value>` and describe the layout
|
||||
of the mapping. These fields may not all be present and may occur in any order.
|
||||
|
||||
The button fields are `a`, `b`, `x`, `y`, `back`, `start`, `guide`, `dpup`,
|
||||
`dpright`, `dpdown`, `dpleft`, `leftshoulder`, `rightshoulder`, `leftstick` and
|
||||
`rightstick`.
|
||||
|
||||
The axis fields are `leftx`, `lefty`, `rightx`, `righty`, `lefttrigger` and
|
||||
`righttrigger`.
|
||||
|
||||
The value of an axis or button field can be a joystick button, a joystick axis,
|
||||
a hat bitmask or empty. Joystick buttons are specified as `bN`, for example
|
||||
`b2` for the third button. Joystick axes are specified as `aN`, for example
|
||||
`a7` for the eighth button. Joystick hat bit masks are specified as `hN.N`, for
|
||||
example `h0.8` for left on the first hat. More than one bit may be set in the
|
||||
mask.
|
||||
|
||||
Before an axis there may be a `+` or `-` range modifier, for example `+a3` for
|
||||
the positive half of the fourth axis. This restricts input to only the positive
|
||||
or negative halves of the joystick axis. After an axis or half-axis there may
|
||||
be the `~` inversion modifier, for example `a2~` or `-a7~`. This negates the
|
||||
values of the gamepad axis.
|
||||
|
||||
The hat bit mask match the [hat states](@ref hat_state) in the joystick
|
||||
functions.
|
||||
|
||||
There is also the special `platform` field that specifies which platform the
|
||||
mapping is valid for. Possible values are `Windows`, `Mac OS X` and `Linux`.
|
||||
|
||||
Below is an example of what a gamepad mapping might look like. It is the
|
||||
one built into GLFW for Xbox controllers accessed via the XInput API on Windows.
|
||||
This example has been broken into several lines to fit on the page, but real
|
||||
gamepad mappings must be a single line.
|
||||
|
||||
@code{.unparsed}
|
||||
78696e70757401000000000000000000,XInput Gamepad (GLFW),platform:Windows,a:b0,
|
||||
b:b1,x:b2,y:b3,leftshoulder:b4,rightshoulder:b5,back:b6,start:b7,leftstick:b8,
|
||||
rightstick:b9,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:a4,
|
||||
righttrigger:a5,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8,
|
||||
@endcode
|
||||
|
||||
@note GLFW does not yet support the output range and modifiers `+` and `-` that
|
||||
were recently added to SDL. The input modifiers `+`, `-` and `~` are supported
|
||||
and described above.
|
||||
|
||||
|
||||
@section time Time input
|
||||
|
||||
GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime.
|
||||
|
||||
@code
|
||||
double seconds = glfwGetTime();
|
||||
@endcode
|
||||
|
||||
It returns the number of seconds since the library was initialized with @ref
|
||||
glfwInit. The platform-specific time sources used typically have micro- or
|
||||
nanosecond resolution.
|
||||
|
||||
You can modify the base time with @ref glfwSetTime.
|
||||
|
||||
@code
|
||||
glfwSetTime(4.0);
|
||||
@endcode
|
||||
|
||||
This sets the time to the specified time, in seconds, and it continues to count
|
||||
from there.
|
||||
|
||||
You can also access the raw timer used to implement the functions above,
|
||||
with @ref glfwGetTimerValue.
|
||||
|
||||
@code
|
||||
uint64_t value = glfwGetTimerValue();
|
||||
@endcode
|
||||
|
||||
This value is in 1 / frequency seconds. The frequency of the raw
|
||||
timer varies depending on the operating system and hardware. You can query the
|
||||
frequency, in Hz, with @ref glfwGetTimerFrequency.
|
||||
|
||||
@code
|
||||
uint64_t frequency = glfwGetTimerFrequency();
|
||||
@endcode
|
||||
|
||||
|
||||
@section clipboard Clipboard input and output
|
||||
|
||||
If the system clipboard contains a UTF-8 encoded string or if it can be
|
||||
converted to one, you can retrieve it with @ref glfwGetClipboardString. See the
|
||||
reference documentation for the lifetime of the returned string.
|
||||
|
||||
@code
|
||||
const char* text = glfwGetClipboardString(NULL);
|
||||
if (text)
|
||||
{
|
||||
insert_text(text);
|
||||
}
|
||||
@endcode
|
||||
|
||||
If the clipboard is empty or if its contents could not be converted, `NULL` is
|
||||
returned.
|
||||
|
||||
The contents of the system clipboard can be set to a UTF-8 encoded string with
|
||||
@ref glfwSetClipboardString.
|
||||
|
||||
@code
|
||||
glfwSetClipboardString(NULL, "A string with words in it");
|
||||
@endcode
|
||||
|
||||
|
||||
@section path_drop Path drop input
|
||||
|
||||
If you wish to receive the paths of files and/or directories dropped on
|
||||
a window, set a file drop callback.
|
||||
|
||||
@code
|
||||
glfwSetDropCallback(window, drop_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives an array of paths encoded as UTF-8.
|
||||
|
||||
@code
|
||||
void drop_callback(GLFWwindow* window, int count, const char** paths)
|
||||
{
|
||||
int i;
|
||||
for (i = 0; i < count; i++)
|
||||
handle_dropped_file(paths[i]);
|
||||
}
|
||||
@endcode
|
||||
|
||||
The path array and its strings are only valid until the file drop callback
|
||||
returns, as they may have been generated specifically for that event. You need
|
||||
to make a deep copy of the array if you want to keep the paths.
|
||||
|
||||
*/
|
||||
115
src/external/glfw/docs/internal.dox
vendored
115
src/external/glfw/docs/internal.dox
vendored
|
|
@ -1,115 +0,0 @@
|
|||
/*!
|
||||
|
||||
@page internals_guide Internal structure
|
||||
|
||||
@tableofcontents
|
||||
|
||||
There are several interfaces inside GLFW. Each interface has its own area of
|
||||
responsibility and its own naming conventions.
|
||||
|
||||
|
||||
@section internals_public Public interface
|
||||
|
||||
The most well-known is the public interface, described in the glfw3.h header
|
||||
file. This is implemented in source files shared by all platforms and these
|
||||
files contain no platform-specific code. This code usually ends up calling the
|
||||
platform and internal interfaces to do the actual work.
|
||||
|
||||
The public interface uses the OpenGL naming conventions except with GLFW and
|
||||
glfw instead of GL and gl. For struct members, where OpenGL sets no precedent,
|
||||
it use headless camel case.
|
||||
|
||||
Examples: `glfwCreateWindow`, `GLFWwindow`, `GLFW_RED_BITS`
|
||||
|
||||
|
||||
@section internals_native Native interface
|
||||
|
||||
The [native interface](@ref native) is a small set of publicly available
|
||||
but platform-specific functions, described in the glfw3native.h header file and
|
||||
used to gain access to the underlying window, context and (on some platforms)
|
||||
display handles used by the platform interface.
|
||||
|
||||
The function names of the native interface are similar to those of the public
|
||||
interface, but embeds the name of the interface that the returned handle is
|
||||
from.
|
||||
|
||||
Examples: `glfwGetX11Window`, `glfwGetWGLContext`
|
||||
|
||||
|
||||
@section internals_internal Internal interface
|
||||
|
||||
The internal interface consists of utility functions used by all other
|
||||
interfaces. It is shared code implemented in the same shared source files as
|
||||
the public and event interfaces. The internal interface is described in the
|
||||
internal.h header file.
|
||||
|
||||
The internal interface is in charge of GLFW's global data, which it stores in
|
||||
a `_GLFWlibrary` struct named `_glfw`.
|
||||
|
||||
The internal interface uses the same style as the public interface, except all
|
||||
global names have a leading underscore.
|
||||
|
||||
Examples: `_glfwIsValidContextConfig`, `_GLFWwindow`, `_glfw.monitorCount`
|
||||
|
||||
|
||||
@section internals_platform Platform interface
|
||||
|
||||
The platform interface implements all platform-specific operations as a service
|
||||
to the public interface. This includes event processing. The platform
|
||||
interface is never directly called by application code and never directly calls
|
||||
application-provided callbacks. It is also prohibited from modifying the
|
||||
platform-independent part of the internal structs. Instead, it calls the event
|
||||
interface when events interesting to GLFW are received.
|
||||
|
||||
The platform interface mirrors those parts of the public interface that needs to
|
||||
perform platform-specific operations on some or all platforms. The are also
|
||||
named the same except that the glfw function prefix is replaced by
|
||||
_glfwPlatform.
|
||||
|
||||
Examples: `_glfwPlatformCreateWindow`
|
||||
|
||||
The platform interface also defines structs that contain platform-specific
|
||||
global and per-object state. Their names mirror those of the internal
|
||||
interface, except that an interface-specific suffix is added.
|
||||
|
||||
Examples: `_GLFWwindowX11`, `_GLFWcontextWGL`
|
||||
|
||||
These structs are incorporated as members into the internal interface structs
|
||||
using special macros that name them after the specific interface used. This
|
||||
prevents shared code from accidentally using these members.
|
||||
|
||||
Examples: `window->win32.handle`, `_glfw.x11.display`
|
||||
|
||||
|
||||
@section internals_event Event interface
|
||||
|
||||
The event interface is implemented in the same shared source files as the public
|
||||
interface and is responsible for delivering the events it receives to the
|
||||
application, either via callbacks, via window state changes or both.
|
||||
|
||||
The function names of the event interface use a `_glfwInput` prefix and the
|
||||
ObjectEvent pattern.
|
||||
|
||||
Examples: `_glfwInputWindowFocus`, `_glfwInputCursorPos`
|
||||
|
||||
|
||||
@section internals_static Static functions
|
||||
|
||||
Static functions may be used by any interface and have no prefixes or suffixes.
|
||||
These use headless camel case.
|
||||
|
||||
Examples: `isValidElementForJoystick`
|
||||
|
||||
|
||||
@section internals_config Configuration macros
|
||||
|
||||
GLFW uses a number of configuration macros to select at compile time which
|
||||
interfaces and code paths to use. They are defined in the glfw_config.h header file,
|
||||
which is generated from the `glfw_config.h.in` file by CMake.
|
||||
|
||||
Configuration macros the same style as tokens in the public interface, except
|
||||
with a leading underscore.
|
||||
|
||||
Examples: `_GLFW_WIN32`, `_GLFW_BUILD_DLL`
|
||||
|
||||
*/
|
||||
479
src/external/glfw/docs/intro.dox
vendored
479
src/external/glfw/docs/intro.dox
vendored
|
|
@ -1,479 +0,0 @@
|
|||
/*!
|
||||
|
||||
@page intro_guide Introduction to the API
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide introduces the basic concepts of GLFW and describes initialization,
|
||||
error handling and API guarantees and limitations. For a broad but shallow
|
||||
tutorial, see @ref quick_guide instead. For details on a specific function in
|
||||
this category, see the @ref init.
|
||||
|
||||
There are also guides for the other areas of GLFW.
|
||||
|
||||
- @ref window_guide
|
||||
- @ref context_guide
|
||||
- @ref vulkan_guide
|
||||
- @ref monitor_guide
|
||||
- @ref input_guide
|
||||
|
||||
|
||||
@section intro_init Initialization and termination
|
||||
|
||||
Before most GLFW functions may be called, the library must be initialized.
|
||||
This initialization checks what features are available on the machine,
|
||||
enumerates monitors and joysticks, initializes the timer and performs any
|
||||
required platform-specific initialization.
|
||||
|
||||
Only the following functions may be called before the library has been
|
||||
successfully initialized, and only from the main thread.
|
||||
|
||||
- @ref glfwGetVersion
|
||||
- @ref glfwGetVersionString
|
||||
- @ref glfwGetError
|
||||
- @ref glfwSetErrorCallback
|
||||
- @ref glfwInitHint
|
||||
- @ref glfwInit
|
||||
- @ref glfwTerminate
|
||||
|
||||
Calling any other function before successful initialization will cause a @ref
|
||||
GLFW_NOT_INITIALIZED error.
|
||||
|
||||
|
||||
@subsection intro_init_init Initializing GLFW
|
||||
|
||||
The library is initialized with @ref glfwInit, which returns `GLFW_FALSE` if an
|
||||
error occurred.
|
||||
|
||||
@code
|
||||
if (!glfwInit())
|
||||
{
|
||||
// Handle initialization failure
|
||||
}
|
||||
@endcode
|
||||
|
||||
If any part of initialization fails, any parts that succeeded are terminated as
|
||||
if @ref glfwTerminate had been called. The library only needs to be initialized
|
||||
once and additional calls to an already initialized library will return
|
||||
`GLFW_TRUE` immediately.
|
||||
|
||||
Once the library has been successfully initialized, it should be terminated
|
||||
before the application exits. Modern systems are very good at freeing resources
|
||||
allocated by programs that exit, but GLFW sometimes has to change global system
|
||||
settings and these might not be restored without termination.
|
||||
|
||||
|
||||
@subsection init_hints Initialization hints
|
||||
|
||||
Initialization hints are set before @ref glfwInit and affect how the library
|
||||
behaves until termination. Hints are set with @ref glfwInitHint.
|
||||
|
||||
@code
|
||||
glfwInitHint(GLFW_JOYSTICK_HAT_BUTTONS, GLFW_FALSE);
|
||||
@endcode
|
||||
|
||||
The values you set hints to are never reset by GLFW, but they only take effect
|
||||
during initialization. Once GLFW has been initialized, any values you set will
|
||||
be ignored until the library is terminated and initialized again.
|
||||
|
||||
Some hints are platform specific. These may be set on any platform but they
|
||||
will only affect their specific platform. Other platforms will ignore them.
|
||||
Setting these hints requires no platform specific headers or functions.
|
||||
|
||||
|
||||
@subsubsection init_hints_shared Shared init hints
|
||||
|
||||
@anchor GLFW_JOYSTICK_HAT_BUTTONS
|
||||
__GLFW_JOYSTICK_HAT_BUTTONS__ specifies whether to also expose joystick hats as
|
||||
buttons, for compatibility with earlier versions of GLFW that did not have @ref
|
||||
glfwGetJoystickHats. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
|
||||
|
||||
|
||||
@subsubsection init_hints_osx macOS specific init hints
|
||||
|
||||
@anchor GLFW_COCOA_CHDIR_RESOURCES_hint
|
||||
__GLFW_COCOA_CHDIR_RESOURCES__ specifies whether to set the current directory to
|
||||
the application to the `Contents/Resources` subdirectory of the application's
|
||||
bundle, if present. Set this with @ref glfwInitHint.
|
||||
|
||||
@anchor GLFW_COCOA_MENUBAR_hint
|
||||
__GLFW_COCOA_MENUBAR__ specifies whether to create a basic menu bar, either from
|
||||
a nib or manually, when the first window is created, which is when AppKit is
|
||||
initialized. Set this with @ref glfwInitHint.
|
||||
|
||||
|
||||
@subsubsection init_hints_wayland Wayland specific init hints
|
||||
|
||||
@anchor GLFW_WAYLAND_LIBDECOR_hint
|
||||
__GLFW_WAYLAND_LIBDECOR__ specifies whether to use
|
||||
[libdecor](https://gitlab.freedesktop.org/libdecor/libdecor) for window
|
||||
decorations where available. Possible values are `GLFW_WAYLAND_PREFER_LIBDECOR`
|
||||
and `GLFW_WAYLAND_DISABLE_LIBDECOR`. This is ignored on other platforms.
|
||||
|
||||
@note This init hint was added in 3.3.9 and is not present in earlier patch releases. It
|
||||
is safe to attempt to set this hint on earlier versions of GLFW 3.3 but it will emit
|
||||
a harmless @ref GLFW_INVALID_ENUM error. If you need to avoid causing any errors, you can
|
||||
check the library version first with @ref glfwGetVersion.
|
||||
|
||||
@note To set this hint while also building against earlier versions of GLFW 3.3, you can
|
||||
use the numerical constants directly.
|
||||
|
||||
@note @code
|
||||
int minor, patch;
|
||||
glfwGetVersion(NULL, &minor, &patch);
|
||||
if (minor > 3 || (minor == 3 && patch >= 9))
|
||||
glfwInitHint(0x00053001 /*GLFW_WAYLAND_LIBDECOR*/, 0x00038002 /*GLFW_WAYLAND_DISABLE_LIBDECOR*/);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsubsection init_hints_values Supported and default values
|
||||
|
||||
Initialization hint | Default value | Supported values
|
||||
------------------------------- | ------------- | ----------------
|
||||
@ref GLFW_JOYSTICK_HAT_BUTTONS | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
||||
@ref GLFW_COCOA_CHDIR_RESOURCES | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
||||
@ref GLFW_COCOA_MENUBAR | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
||||
@ref GLFW_WAYLAND_LIBDECOR | `GLFW_WAYLAND_PREFER_LIBDECOR` | `GLFW_WAYLAND_PREFER_LIBDECOR` or `GLFW_WAYLAND_DISABLE_LIBDECOR`
|
||||
|
||||
|
||||
@subsection intro_init_terminate Terminating GLFW
|
||||
|
||||
Before your application exits, you should terminate the GLFW library if it has
|
||||
been initialized. This is done with @ref glfwTerminate.
|
||||
|
||||
@code
|
||||
glfwTerminate();
|
||||
@endcode
|
||||
|
||||
This will destroy any remaining window, monitor and cursor objects, restore any
|
||||
modified gamma ramps, re-enable the screensaver if it had been disabled and free
|
||||
any other resources allocated by GLFW.
|
||||
|
||||
Once the library is terminated, it is as if it had never been initialized, therefore
|
||||
you will need to initialize it again before being able to use GLFW. If the
|
||||
library was not initialized or had already been terminated, it returns
|
||||
immediately.
|
||||
|
||||
|
||||
@section error_handling Error handling
|
||||
|
||||
Some GLFW functions have return values that indicate an error, but this is often
|
||||
not very helpful when trying to figure out what happened or why it occurred.
|
||||
Other functions have no return value reserved for errors, so error notification
|
||||
needs a separate channel. Finally, far from all GLFW functions have return
|
||||
values.
|
||||
|
||||
The last [error code](@ref errors) for the calling thread can be queried at any
|
||||
time with @ref glfwGetError.
|
||||
|
||||
@code
|
||||
int code = glfwGetError(NULL);
|
||||
|
||||
if (code != GLFW_NO_ERROR)
|
||||
handle_error(code);
|
||||
@endcode
|
||||
|
||||
If no error has occurred since the last call, @ref GLFW_NO_ERROR (zero) is
|
||||
returned. The error is cleared before the function returns.
|
||||
|
||||
The error code indicates the general category of the error. Some error codes,
|
||||
such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
|
||||
@ref GLFW_PLATFORM_ERROR are used for many different errors.
|
||||
|
||||
GLFW often has more information about an error than its general category. You
|
||||
can retrieve a UTF-8 encoded human-readable description along with the error
|
||||
code. If no error has occurred since the last call, the description is set to
|
||||
`NULL`.
|
||||
|
||||
@code
|
||||
const char* description;
|
||||
int code = glfwGetError(&description);
|
||||
|
||||
if (description)
|
||||
display_error_message(code, description);
|
||||
@endcode
|
||||
|
||||
The retrieved description string is only valid until the next error occurs.
|
||||
This means you must make a copy of it if you want to keep it.
|
||||
|
||||
You can also set an error callback, which will be called each time an error
|
||||
occurs. It is set with @ref glfwSetErrorCallback.
|
||||
|
||||
@code
|
||||
glfwSetErrorCallback(error_callback);
|
||||
@endcode
|
||||
|
||||
The error callback receives the same error code and human-readable description
|
||||
returned by @ref glfwGetError.
|
||||
|
||||
@code
|
||||
void error_callback(int code, const char* description)
|
||||
{
|
||||
display_error_message(code, description);
|
||||
}
|
||||
@endcode
|
||||
|
||||
The error callback is called after the error is stored, so calling @ref
|
||||
glfwGetError from within the error callback returns the same values as the
|
||||
callback argument.
|
||||
|
||||
The description string passed to the callback is only valid until the error
|
||||
callback returns. This means you must make a copy of it if you want to keep it.
|
||||
|
||||
__Reported errors are never fatal.__ As long as GLFW was successfully
|
||||
initialized, it will remain initialized and in a safe state until terminated
|
||||
regardless of how many errors occur. If an error occurs during initialization
|
||||
that causes @ref glfwInit to fail, any part of the library that was initialized
|
||||
will be safely terminated.
|
||||
|
||||
Do not rely on a currently invalid call to generate a specific error, as in the
|
||||
future that same call may generate a different error or become valid.
|
||||
|
||||
|
||||
@section coordinate_systems Coordinate systems
|
||||
|
||||
GLFW has two primary coordinate systems: the _virtual screen_ and the window
|
||||
_content area_ or _content area_. Both use the same unit: _virtual screen
|
||||
coordinates_, or just _screen coordinates_, which don't necessarily correspond
|
||||
to pixels.
|
||||
|
||||
<img src="spaces.svg" width="90%" />
|
||||
|
||||
Both the virtual screen and the content area coordinate systems have the X-axis
|
||||
pointing to the right and the Y-axis pointing down.
|
||||
|
||||
Window and monitor positions are specified as the position of the upper-left
|
||||
corners of their content areas relative to the virtual screen, while cursor
|
||||
positions are specified relative to a window's content area.
|
||||
|
||||
Because the origin of the window's content area coordinate system is also the
|
||||
point from which the window position is specified, you can translate content
|
||||
area coordinates to the virtual screen by adding the window position. The
|
||||
window frame, when present, extends out from the content area but does not
|
||||
affect the window position.
|
||||
|
||||
Almost all positions and sizes in GLFW are measured in screen coordinates
|
||||
relative to one of the two origins above. This includes cursor positions,
|
||||
window positions and sizes, window frame sizes, monitor positions and video mode
|
||||
resolutions.
|
||||
|
||||
Two exceptions are the [monitor physical size](@ref monitor_size), which is
|
||||
measured in millimetres, and [framebuffer size](@ref window_fbsize), which is
|
||||
measured in pixels.
|
||||
|
||||
Pixels and screen coordinates may map 1:1 on your machine, but they won't on
|
||||
every other machine, for example on a Mac with a Retina display. The ratio
|
||||
between screen coordinates and pixels may also change at run-time depending on
|
||||
which monitor the window is currently considered to be on.
|
||||
|
||||
|
||||
@section guarantees_limitations Guarantees and limitations
|
||||
|
||||
This section describes the conditions under which GLFW can be expected to
|
||||
function, barring bugs in the operating system or drivers. Use of GLFW outside
|
||||
these limits may work on some platforms, or on some machines, or some of the
|
||||
time, or on some versions of GLFW, but it may break at any time and this will
|
||||
not be considered a bug.
|
||||
|
||||
|
||||
@subsection lifetime Pointer lifetimes
|
||||
|
||||
GLFW will never free any pointer you provide to it, and you must never free any
|
||||
pointer it provides to you.
|
||||
|
||||
Many GLFW functions return pointers to dynamically allocated structures, strings
|
||||
or arrays, and some callbacks are provided with strings or arrays. These are
|
||||
always managed by GLFW and should never be freed by the application. The
|
||||
lifetime of these pointers is documented for each GLFW function and callback.
|
||||
If you need to keep this data, you must copy it before its lifetime expires.
|
||||
|
||||
Many GLFW functions accept pointers to structures or strings allocated by the
|
||||
application. These are never freed by GLFW and are always the responsibility of
|
||||
the application. If GLFW needs to keep the data in these structures or strings,
|
||||
it is copied before the function returns.
|
||||
|
||||
Pointer lifetimes are guaranteed not to be shortened in future minor or patch
|
||||
releases.
|
||||
|
||||
|
||||
@subsection reentrancy Reentrancy
|
||||
|
||||
GLFW event processing and object destruction are not reentrant. This means that
|
||||
the following functions must not be called from any callback function:
|
||||
|
||||
- @ref glfwDestroyWindow
|
||||
- @ref glfwDestroyCursor
|
||||
- @ref glfwPollEvents
|
||||
- @ref glfwWaitEvents
|
||||
- @ref glfwWaitEventsTimeout
|
||||
- @ref glfwTerminate
|
||||
|
||||
These functions may be made reentrant in future minor or patch releases, but
|
||||
functions not on this list will not be made non-reentrant.
|
||||
|
||||
|
||||
@subsection thread_safety Thread safety
|
||||
|
||||
Most GLFW functions must only be called from the main thread (the thread that
|
||||
calls main), but some may be called from any thread once the library has been
|
||||
initialized. Before initialization the whole library is thread-unsafe.
|
||||
|
||||
The reference documentation for every GLFW function states whether it is limited
|
||||
to the main thread.
|
||||
|
||||
Initialization, termination, event processing and the creation and
|
||||
destruction of windows, cursors and OpenGL and OpenGL ES contexts are all
|
||||
restricted to the main thread due to limitations of one or several platforms.
|
||||
|
||||
Because event processing must be performed on the main thread, all callbacks
|
||||
except for the error callback will only be called on that thread. The error
|
||||
callback may be called on any thread, as any GLFW function may generate errors.
|
||||
|
||||
The error code and description may be queried from any thread.
|
||||
|
||||
- @ref glfwGetError
|
||||
|
||||
Empty events may be posted from any thread.
|
||||
|
||||
- @ref glfwPostEmptyEvent
|
||||
|
||||
The window user pointer and close flag may be read and written from any thread,
|
||||
but this is not synchronized by GLFW.
|
||||
|
||||
- @ref glfwGetWindowUserPointer
|
||||
- @ref glfwSetWindowUserPointer
|
||||
- @ref glfwWindowShouldClose
|
||||
- @ref glfwSetWindowShouldClose
|
||||
|
||||
These functions for working with OpenGL and OpenGL ES contexts may be called
|
||||
from any thread, but the window object is not synchronized by GLFW.
|
||||
|
||||
- @ref glfwMakeContextCurrent
|
||||
- @ref glfwGetCurrentContext
|
||||
- @ref glfwSwapBuffers
|
||||
- @ref glfwSwapInterval
|
||||
- @ref glfwExtensionSupported
|
||||
- @ref glfwGetProcAddress
|
||||
|
||||
The raw timer functions may be called from any thread.
|
||||
|
||||
- @ref glfwGetTimerFrequency
|
||||
- @ref glfwGetTimerValue
|
||||
|
||||
The regular timer may be used from any thread, but reading and writing the timer
|
||||
offset is not synchronized by GLFW.
|
||||
|
||||
- @ref glfwGetTime
|
||||
- @ref glfwSetTime
|
||||
|
||||
Library version information may be queried from any thread.
|
||||
|
||||
- @ref glfwGetVersion
|
||||
- @ref glfwGetVersionString
|
||||
|
||||
All Vulkan related functions may be called from any thread.
|
||||
|
||||
- @ref glfwVulkanSupported
|
||||
- @ref glfwGetRequiredInstanceExtensions
|
||||
- @ref glfwGetInstanceProcAddress
|
||||
- @ref glfwGetPhysicalDevicePresentationSupport
|
||||
- @ref glfwCreateWindowSurface
|
||||
|
||||
GLFW uses synchronization objects internally only to manage the per-thread
|
||||
context and error states. Additional synchronization is left to the
|
||||
application.
|
||||
|
||||
Functions that may currently be called from any thread will always remain so,
|
||||
but functions that are currently limited to the main thread may be updated to
|
||||
allow calls from any thread in future releases.
|
||||
|
||||
|
||||
@subsection compatibility Version compatibility
|
||||
|
||||
GLFW uses [Semantic Versioning](https://semver.org/). This guarantees source
|
||||
and binary backward compatibility with earlier minor versions of the API. This
|
||||
means that you can drop in a newer version of the library and existing programs
|
||||
will continue to compile and existing binaries will continue to run.
|
||||
|
||||
Once a function or constant has been added, the signature of that function or
|
||||
value of that constant will remain unchanged until the next major version of
|
||||
GLFW. No compatibility of any kind is guaranteed between major versions.
|
||||
|
||||
Undocumented behavior, i.e. behavior that is not described in the documentation,
|
||||
may change at any time until it is documented.
|
||||
|
||||
If the reference documentation and the implementation differ, the reference
|
||||
documentation will almost always take precedence and the implementation will be
|
||||
fixed in the next release. The reference documentation will also take
|
||||
precedence over anything stated in a guide.
|
||||
|
||||
|
||||
@subsection event_order Event order
|
||||
|
||||
The order of arrival of related events is not guaranteed to be consistent
|
||||
across platforms. The exception is synthetic key and mouse button release
|
||||
events, which are always delivered after the window defocus event.
|
||||
|
||||
|
||||
@section intro_version Version management
|
||||
|
||||
GLFW provides mechanisms for identifying what version of GLFW your application
|
||||
was compiled against as well as what version it is currently running against.
|
||||
If you are loading GLFW dynamically (not just linking dynamically), you can use
|
||||
this to verify that the library binary is compatible with your application.
|
||||
|
||||
|
||||
@subsection intro_version_compile Compile-time version
|
||||
|
||||
The compile-time version of GLFW is provided by the GLFW header with the
|
||||
`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.
|
||||
|
||||
@code
|
||||
printf("Compiled against GLFW %i.%i.%i\n",
|
||||
GLFW_VERSION_MAJOR,
|
||||
GLFW_VERSION_MINOR,
|
||||
GLFW_VERSION_REVISION);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection intro_version_runtime Run-time version
|
||||
|
||||
The run-time version can be retrieved with @ref glfwGetVersion, a function that
|
||||
may be called regardless of whether GLFW is initialized.
|
||||
|
||||
@code
|
||||
int major, minor, revision;
|
||||
glfwGetVersion(&major, &minor, &revision);
|
||||
|
||||
printf("Running against GLFW %i.%i.%i\n", major, minor, revision);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection intro_version_string Version string
|
||||
|
||||
GLFW 3 also provides a compile-time generated version string that describes the
|
||||
version, platform, compiler and any platform-specific compile-time options.
|
||||
This is primarily intended for submitting bug reports, to allow developers to
|
||||
see which code paths are enabled in a binary.
|
||||
|
||||
The version string is returned by @ref glfwGetVersionString, a function that may
|
||||
be called regardless of whether GLFW is initialized.
|
||||
|
||||
__Do not use the version string__ to parse the GLFW library version. The @ref
|
||||
glfwGetVersion function already provides the version of the running library
|
||||
binary.
|
||||
|
||||
The format of the string is as follows:
|
||||
- The version of GLFW
|
||||
- The name of the window system API
|
||||
- The name of the context creation API
|
||||
- Any additional options or APIs
|
||||
|
||||
For example, when compiling GLFW 3.3.9 with MinGW for Windows, may result in
|
||||
a version string like this:
|
||||
|
||||
@code
|
||||
3.3.9 Win32 WGL EGL OSMesa MinGW
|
||||
@endcode
|
||||
|
||||
*/
|
||||
46
src/external/glfw/docs/main.dox
vendored
46
src/external/glfw/docs/main.dox
vendored
|
|
@ -1,46 +0,0 @@
|
|||
/*!
|
||||
|
||||
@mainpage notitle
|
||||
|
||||
@section main_intro Introduction
|
||||
|
||||
GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and
|
||||
Vulkan application development. It provides a simple, platform-independent API
|
||||
for creating windows, contexts and surfaces, reading input, handling events, etc.
|
||||
|
||||
@ref news_33 list new features, caveats and deprecations.
|
||||
|
||||
@ref quick_guide is a guide for users new to GLFW. It takes you through how to
|
||||
write a small but complete program.
|
||||
|
||||
There are guides for each section of the API:
|
||||
|
||||
- @ref intro_guide – initialization, error handling and high-level design
|
||||
- @ref window_guide – creating and working with windows and framebuffers
|
||||
- @ref context_guide – working with OpenGL and OpenGL ES contexts
|
||||
- @ref vulkan_guide - working with Vulkan objects and extensions
|
||||
- @ref monitor_guide – enumerating and working with monitors and video modes
|
||||
- @ref input_guide – receiving events, polling and processing input
|
||||
|
||||
Once you have written a program, see @ref compile_guide and @ref build_guide.
|
||||
|
||||
The [reference documentation](modules.html) provides more detailed information
|
||||
about specific functions.
|
||||
|
||||
@ref moving_guide explains what has changed and how to update existing code to
|
||||
use the new API.
|
||||
|
||||
There is a section on @ref guarantees_limitations for pointer lifetimes,
|
||||
reentrancy, thread safety, event order and backward and forward compatibility.
|
||||
|
||||
The [FAQ](https://www.glfw.org/faq.html) answers many common questions about the
|
||||
design, implementation and use of GLFW.
|
||||
|
||||
Finally, @ref compat_guide explains what APIs, standards and protocols GLFW uses
|
||||
and what happens when they are not present on a given machine.
|
||||
|
||||
This documentation was generated with Doxygen. The sources for it are available
|
||||
in both the [source distribution](https://www.glfw.org/download.html) and
|
||||
[GitHub repository](https://github.com/glfw/glfw).
|
||||
|
||||
*/
|
||||
268
src/external/glfw/docs/monitor.dox
vendored
268
src/external/glfw/docs/monitor.dox
vendored
|
|
@ -1,268 +0,0 @@
|
|||
/*!
|
||||
|
||||
@page monitor_guide Monitor guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide introduces the monitor related functions of GLFW. For details on
|
||||
a specific function in this category, see the @ref monitor. There are also
|
||||
guides for the other areas of GLFW.
|
||||
|
||||
- @ref intro_guide
|
||||
- @ref window_guide
|
||||
- @ref context_guide
|
||||
- @ref vulkan_guide
|
||||
- @ref input_guide
|
||||
|
||||
|
||||
@section monitor_object Monitor objects
|
||||
|
||||
A monitor object represents a currently connected monitor and is represented as
|
||||
a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type
|
||||
@ref GLFWmonitor. Monitor objects cannot be created or destroyed by the
|
||||
application and retain their addresses until the monitors they represent are
|
||||
disconnected or until the library is [terminated](@ref intro_init_terminate).
|
||||
|
||||
Each monitor has a current video mode, a list of supported video modes,
|
||||
a virtual position, a human-readable name, an estimated physical size and
|
||||
a gamma ramp. One of the monitors is the primary monitor.
|
||||
|
||||
The virtual position of a monitor is in
|
||||
[screen coordinates](@ref coordinate_systems) and, together with the current
|
||||
video mode, describes the viewports that the connected monitors provide into the
|
||||
virtual desktop that spans them.
|
||||
|
||||
To see how GLFW views your monitor setup and its available video modes, run the
|
||||
`monitors` test program.
|
||||
|
||||
|
||||
@subsection monitor_monitors Retrieving monitors
|
||||
|
||||
The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's
|
||||
preferred monitor and is usually the one with global UI elements like task bar
|
||||
or menu bar.
|
||||
|
||||
@code
|
||||
GLFWmonitor* primary = glfwGetPrimaryMonitor();
|
||||
@endcode
|
||||
|
||||
You can retrieve all currently connected monitors with @ref glfwGetMonitors.
|
||||
See the reference documentation for the lifetime of the returned array.
|
||||
|
||||
@code
|
||||
int count;
|
||||
GLFWmonitor** monitors = glfwGetMonitors(&count);
|
||||
@endcode
|
||||
|
||||
The primary monitor is always the first monitor in the returned array, but other
|
||||
monitors may be moved to a different index when a monitor is connected or
|
||||
disconnected.
|
||||
|
||||
|
||||
@subsection monitor_event Monitor configuration changes
|
||||
|
||||
If you wish to be notified when a monitor is connected or disconnected, set
|
||||
a monitor callback.
|
||||
|
||||
@code
|
||||
glfwSetMonitorCallback(monitor_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the handle for the monitor that has been
|
||||
connected or disconnected and the event that occurred.
|
||||
|
||||
@code
|
||||
void monitor_callback(GLFWmonitor* monitor, int event)
|
||||
{
|
||||
if (event == GLFW_CONNECTED)
|
||||
{
|
||||
// The monitor was connected
|
||||
}
|
||||
else if (event == GLFW_DISCONNECTED)
|
||||
{
|
||||
// The monitor was disconnected
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
If a monitor is disconnected, all windows that are full screen on it will be
|
||||
switched to windowed mode before the callback is called. Only @ref
|
||||
glfwGetMonitorName and @ref glfwGetMonitorUserPointer will return useful values
|
||||
for a disconnected monitor and only before the monitor callback returns.
|
||||
|
||||
|
||||
@section monitor_properties Monitor properties
|
||||
|
||||
Each monitor has a current video mode, a list of supported video modes,
|
||||
a virtual position, a content scale, a human-readable name, a user pointer, an
|
||||
estimated physical size and a gamma ramp.
|
||||
|
||||
|
||||
@subsection monitor_modes Video modes
|
||||
|
||||
GLFW generally does a good job selecting a suitable video mode when you create
|
||||
a full screen window, change its video mode or make a windowed one full
|
||||
screen, but it is sometimes useful to know exactly which video modes are
|
||||
supported.
|
||||
|
||||
Video modes are represented as @ref GLFWvidmode structures. You can get an
|
||||
array of the video modes supported by a monitor with @ref glfwGetVideoModes.
|
||||
See the reference documentation for the lifetime of the returned array.
|
||||
|
||||
@code
|
||||
int count;
|
||||
GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
|
||||
@endcode
|
||||
|
||||
To get the current video mode of a monitor call @ref glfwGetVideoMode. See the
|
||||
reference documentation for the lifetime of the returned pointer.
|
||||
|
||||
@code
|
||||
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
|
||||
@endcode
|
||||
|
||||
The resolution of a video mode is specified in
|
||||
[screen coordinates](@ref coordinate_systems), not pixels.
|
||||
|
||||
|
||||
@subsection monitor_size Physical size
|
||||
|
||||
The physical size of a monitor in millimetres, or an estimation of it, can be
|
||||
retrieved with @ref glfwGetMonitorPhysicalSize. This has no relation to its
|
||||
current _resolution_, i.e. the width and height of its current
|
||||
[video mode](@ref monitor_modes).
|
||||
|
||||
@code
|
||||
int width_mm, height_mm;
|
||||
glfwGetMonitorPhysicalSize(monitor, &width_mm, &height_mm);
|
||||
@endcode
|
||||
|
||||
While this can be used to calculate the raw DPI of a monitor, this is often not
|
||||
useful. Instead, use the [monitor content scale](@ref monitor_scale) and
|
||||
[window content scale](@ref window_scale) to scale your content.
|
||||
|
||||
|
||||
@subsection monitor_scale Content scale
|
||||
|
||||
The content scale for a monitor can be retrieved with @ref
|
||||
glfwGetMonitorContentScale.
|
||||
|
||||
@code
|
||||
float xscale, yscale;
|
||||
glfwGetMonitorContentScale(monitor, &xscale, &yscale);
|
||||
@endcode
|
||||
|
||||
The content scale is the ratio between the current DPI and the platform's
|
||||
default DPI. This is especially important for text and any UI elements. If the
|
||||
pixel dimensions of your UI scaled by this look appropriate on your machine then
|
||||
it should appear at a reasonable size on other machines regardless of their DPI
|
||||
and scaling settings. This relies on the system DPI and scaling settings being
|
||||
somewhat correct.
|
||||
|
||||
The content scale may depend on both the monitor resolution and pixel density
|
||||
and on user settings. It may be very different from the raw DPI calculated from
|
||||
the physical size and current resolution.
|
||||
|
||||
|
||||
@subsection monitor_pos Virtual position
|
||||
|
||||
The position of the monitor on the virtual desktop, in
|
||||
[screen coordinates](@ref coordinate_systems), can be retrieved with @ref
|
||||
glfwGetMonitorPos.
|
||||
|
||||
@code
|
||||
int xpos, ypos;
|
||||
glfwGetMonitorPos(monitor, &xpos, &ypos);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection monitor_workarea Work area
|
||||
|
||||
The area of a monitor not occupied by global task bars or menu bars is the work
|
||||
area. This is specified in [screen coordinates](@ref coordinate_systems) and
|
||||
can be retrieved with @ref glfwGetMonitorWorkarea.
|
||||
|
||||
@code
|
||||
int xpos, ypos, width, height;
|
||||
glfwGetMonitorWorkarea(monitor, &xpos, &ypos, &width, &height);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection monitor_name Human-readable name
|
||||
|
||||
The human-readable, UTF-8 encoded name of a monitor is returned by @ref
|
||||
glfwGetMonitorName. See the reference documentation for the lifetime of the
|
||||
returned string.
|
||||
|
||||
@code
|
||||
const char* name = glfwGetMonitorName(monitor);
|
||||
@endcode
|
||||
|
||||
Monitor names are not guaranteed to be unique. Two monitors of the same model
|
||||
and make may have the same name. Only the monitor handle is guaranteed to be
|
||||
unique, and only until that monitor is disconnected.
|
||||
|
||||
|
||||
@subsection monitor_userptr User pointer
|
||||
|
||||
Each monitor has a user pointer that can be set with @ref
|
||||
glfwSetMonitorUserPointer and queried with @ref glfwGetMonitorUserPointer. This
|
||||
can be used for any purpose you need and will not be modified by GLFW. The
|
||||
value will be kept until the monitor is disconnected or until the library is
|
||||
terminated.
|
||||
|
||||
The initial value of the pointer is `NULL`.
|
||||
|
||||
|
||||
@subsection monitor_gamma Gamma ramp
|
||||
|
||||
The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts
|
||||
a monitor handle and a pointer to a @ref GLFWgammaramp structure.
|
||||
|
||||
@code
|
||||
GLFWgammaramp ramp;
|
||||
unsigned short red[256], green[256], blue[256];
|
||||
|
||||
ramp.size = 256;
|
||||
ramp.red = red;
|
||||
ramp.green = green;
|
||||
ramp.blue = blue;
|
||||
|
||||
for (i = 0; i < ramp.size; i++)
|
||||
{
|
||||
// Fill out gamma ramp arrays as desired
|
||||
}
|
||||
|
||||
glfwSetGammaRamp(monitor, &ramp);
|
||||
@endcode
|
||||
|
||||
The gamma ramp data is copied before the function returns, so there is no need
|
||||
to keep it around once the ramp has been set.
|
||||
|
||||
It is recommended that your gamma ramp have the same size as the current gamma
|
||||
ramp for that monitor.
|
||||
|
||||
The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. See
|
||||
the reference documentation for the lifetime of the returned structure.
|
||||
|
||||
@code
|
||||
const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);
|
||||
@endcode
|
||||
|
||||
If you wish to set a regular gamma ramp, you can have GLFW calculate it for you
|
||||
from the desired exponent with @ref glfwSetGamma, which in turn calls @ref
|
||||
glfwSetGammaRamp with the resulting ramp.
|
||||
|
||||
@code
|
||||
glfwSetGamma(monitor, 1.0);
|
||||
@endcode
|
||||
|
||||
To experiment with gamma correction via the @ref glfwSetGamma function, run the
|
||||
`gamma` test program.
|
||||
|
||||
@note The software controlled gamma ramp is applied _in addition_ to the
|
||||
hardware gamma correction, which today is typically an approximation of sRGB
|
||||
gamma. This means that setting a perfectly linear ramp, or gamma 1.0, will
|
||||
produce the default (usually sRGB-like) behavior.
|
||||
|
||||
*/
|
||||
513
src/external/glfw/docs/moving.dox
vendored
513
src/external/glfw/docs/moving.dox
vendored
|
|
@ -1,513 +0,0 @@
|
|||
/*!
|
||||
|
||||
@page moving_guide Moving from GLFW 2 to 3
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This is a transition guide for moving from GLFW 2 to 3. It describes what has
|
||||
changed or been removed, but does _not_ include
|
||||
[new features](@ref news) unless they are required when moving an existing code
|
||||
base onto the new API. For example, the new multi-monitor functions are
|
||||
required to create full screen windows with GLFW 3.
|
||||
|
||||
|
||||
@section moving_removed Changed and removed features
|
||||
|
||||
@subsection moving_renamed_files Renamed library and header file
|
||||
|
||||
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
|
||||
3 library is named `glfw3,` except when it's installed as a shared library on
|
||||
Unix-like systems, where it uses the
|
||||
[soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`.
|
||||
|
||||
@par Old syntax
|
||||
@code
|
||||
#include <GL/glfw.h>
|
||||
@endcode
|
||||
|
||||
@par New syntax
|
||||
@code
|
||||
#include <GLFW/glfw3.h>
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection moving_threads Removal of threading functions
|
||||
|
||||
The threading functions have been removed, including the per-thread sleep
|
||||
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
|
||||
better threading libraries available and native threading support is available
|
||||
in both [C++11](https://en.cppreference.com/w/cpp/thread) and
|
||||
[C11](https://en.cppreference.com/w/c/thread), both of which are gaining
|
||||
traction.
|
||||
|
||||
If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
|
||||
support them, see the
|
||||
[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
|
||||
threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
|
||||
TinyCThread.
|
||||
|
||||
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
|
||||
thread at a time, and the documentation explicitly states which functions may be
|
||||
used from any thread and which must only be used from the main thread.
|
||||
|
||||
@par Removed functions
|
||||
`glfwSleep`, `glfwCreateThread`, `glfwDestroyThread`, `glfwWaitThread`,
|
||||
`glfwGetThreadID`, `glfwCreateMutex`, `glfwDestroyMutex`, `glfwLockMutex`,
|
||||
`glfwUnlockMutex`, `glfwCreateCond`, `glfwDestroyCond`, `glfwWaitCond`,
|
||||
`glfwSignalCond`, `glfwBroadcastCond` and `glfwGetNumberOfProcessors`.
|
||||
|
||||
@par Removed types
|
||||
`GLFWthreadfun`
|
||||
|
||||
|
||||
@subsection moving_image Removal of image and texture loading
|
||||
|
||||
The image and texture loading functions have been removed. They only supported
|
||||
the Targa image format, making them mostly useful for beginner level examples.
|
||||
To become of sufficiently high quality to warrant keeping them in GLFW 3, they
|
||||
would need not only to support other formats, but also modern extensions to
|
||||
OpenGL texturing. This would either add a number of external
|
||||
dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions
|
||||
of these libraries.
|
||||
|
||||
As there already are libraries doing this, it is unnecessary both to duplicate
|
||||
the work and to tie the duplicate to GLFW. The resulting library would also be
|
||||
platform-independent, as both OpenGL and stdio are available wherever GLFW is.
|
||||
|
||||
@par Removed functions
|
||||
`glfwReadImage`, `glfwReadMemoryImage`, `glfwFreeImage`, `glfwLoadTexture2D`,
|
||||
`glfwLoadMemoryTexture2D` and `glfwLoadTextureImage2D`.
|
||||
|
||||
|
||||
@subsection moving_stdcall Removal of GLFWCALL macro
|
||||
|
||||
The `GLFWCALL` macro, which made callback functions use
|
||||
[__stdcall](https://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows,
|
||||
has been removed. GLFW is written in C, not Pascal. Removing this macro means
|
||||
there's one less thing for application programmers to remember, i.e. the
|
||||
requirement to mark all callback functions with `GLFWCALL`. It also simplifies
|
||||
the creation of DLLs and DLL link libraries, as there's no need to explicitly
|
||||
disable `@n` entry point suffixes.
|
||||
|
||||
@par Old syntax
|
||||
@code
|
||||
void GLFWCALL callback_function(...);
|
||||
@endcode
|
||||
|
||||
@par New syntax
|
||||
@code
|
||||
void callback_function(...);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection moving_window_handles Window handle parameters
|
||||
|
||||
Because GLFW 3 supports multiple windows, window handle parameters have been
|
||||
added to all window-related GLFW functions and callbacks. The handle of
|
||||
a newly created window is returned by @ref glfwCreateWindow (formerly
|
||||
`glfwOpenWindow`). Window handles are pointers to the
|
||||
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWwindow.
|
||||
|
||||
@par Old syntax
|
||||
@code
|
||||
glfwSetWindowTitle("New Window Title");
|
||||
@endcode
|
||||
|
||||
@par New syntax
|
||||
@code
|
||||
glfwSetWindowTitle(window, "New Window Title");
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection moving_monitor Explicit monitor selection
|
||||
|
||||
GLFW 3 provides support for multiple monitors. To request a full screen mode window,
|
||||
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
|
||||
window to use. The @ref glfwGetPrimaryMonitor function returns the monitor that
|
||||
GLFW 2 would have selected, but there are many other
|
||||
[monitor functions](@ref monitor_guide). Monitor handles are pointers to the
|
||||
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWmonitor.
|
||||
|
||||
@par Old basic full screen
|
||||
@code
|
||||
glfwOpenWindow(640, 480, 8, 8, 8, 0, 24, 0, GLFW_FULLSCREEN);
|
||||
@endcode
|
||||
|
||||
@par New basic full screen
|
||||
@code
|
||||
window = glfwCreateWindow(640, 480, "My Window", glfwGetPrimaryMonitor(), NULL);
|
||||
@endcode
|
||||
|
||||
@note The framebuffer bit depth parameters of `glfwOpenWindow` have been turned
|
||||
into [window hints](@ref window_hints), but as they have been given
|
||||
[sane defaults](@ref window_hints_values) you rarely need to set these hints.
|
||||
|
||||
|
||||
@subsection moving_autopoll Removal of automatic event polling
|
||||
|
||||
GLFW 3 does not automatically poll for events in @ref glfwSwapBuffers, meaning
|
||||
you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. Unlike
|
||||
buffer swap, which acts on a single window, the event processing functions act
|
||||
on all windows at once.
|
||||
|
||||
@par Old basic main loop
|
||||
@code
|
||||
while (...)
|
||||
{
|
||||
// Process input
|
||||
// Render output
|
||||
glfwSwapBuffers();
|
||||
}
|
||||
@endcode
|
||||
|
||||
@par New basic main loop
|
||||
@code
|
||||
while (...)
|
||||
{
|
||||
// Process input
|
||||
// Render output
|
||||
glfwSwapBuffers(window);
|
||||
glfwPollEvents();
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection moving_context Explicit context management
|
||||
|
||||
Each GLFW 3 window has its own OpenGL context and only you, the application
|
||||
programmer, can know which context should be current on which thread at any
|
||||
given time. Therefore, GLFW 3 leaves that decision to you.
|
||||
|
||||
This means that you need to call @ref glfwMakeContextCurrent after creating
|
||||
a window before you can call any OpenGL functions.
|
||||
|
||||
|
||||
@subsection moving_hidpi Separation of window and framebuffer sizes
|
||||
|
||||
Window positions and sizes now use screen coordinates, which may not be the same
|
||||
as pixels on machines with high-DPI monitors. This is important as OpenGL uses
|
||||
pixels, not screen coordinates. For example, the rectangle specified with
|
||||
`glViewport` needs to use pixels. Therefore, framebuffer size functions have
|
||||
been added. You can retrieve the size of the framebuffer of a window with @ref
|
||||
glfwGetFramebufferSize function. A framebuffer size callback has also been
|
||||
added, which can be set with @ref glfwSetFramebufferSizeCallback.
|
||||
|
||||
@par Old basic viewport setup
|
||||
@code
|
||||
glfwGetWindowSize(&width, &height);
|
||||
glViewport(0, 0, width, height);
|
||||
@endcode
|
||||
|
||||
@par New basic viewport setup
|
||||
@code
|
||||
glfwGetFramebufferSize(window, &width, &height);
|
||||
glViewport(0, 0, width, height);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection moving_window_close Window closing changes
|
||||
|
||||
The `GLFW_OPENED` window parameter has been removed. As long as the window has
|
||||
not been destroyed, whether through @ref glfwDestroyWindow or @ref
|
||||
glfwTerminate, the window is "open".
|
||||
|
||||
A user attempting to close a window is now just an event like any other. Unlike
|
||||
GLFW 2, windows and contexts created with GLFW 3 will never be destroyed unless
|
||||
you choose them to be. Each window now has a close flag that is set to
|
||||
`GLFW_TRUE` when the user attempts to close that window. By default, nothing else
|
||||
happens and the window stays visible. It is then up to you to either destroy
|
||||
the window, take some other action or ignore the request.
|
||||
|
||||
You can query the close flag at any time with @ref glfwWindowShouldClose and set
|
||||
it at any time with @ref glfwSetWindowShouldClose.
|
||||
|
||||
@par Old basic main loop
|
||||
@code
|
||||
while (glfwGetWindowParam(GLFW_OPENED))
|
||||
{
|
||||
...
|
||||
}
|
||||
@endcode
|
||||
|
||||
@par New basic main loop
|
||||
@code
|
||||
while (!glfwWindowShouldClose(window))
|
||||
{
|
||||
...
|
||||
}
|
||||
@endcode
|
||||
|
||||
The close callback no longer returns a value. Instead, it is called after the
|
||||
close flag has been set, so it can optionally override its value, before
|
||||
event processing completes. You may however not call @ref glfwDestroyWindow
|
||||
from the close callback (or any other window related callback).
|
||||
|
||||
@par Old syntax
|
||||
@code
|
||||
int GLFWCALL window_close_callback(void);
|
||||
@endcode
|
||||
|
||||
@par New syntax
|
||||
@code
|
||||
void window_close_callback(GLFWwindow* window);
|
||||
@endcode
|
||||
|
||||
@note GLFW never clears the close flag to `GLFW_FALSE`, meaning you can use it
|
||||
for other reasons to close the window as well, for example the user choosing
|
||||
Quit from an in-game menu.
|
||||
|
||||
|
||||
@subsection moving_hints Persistent window hints
|
||||
|
||||
The `glfwOpenWindowHint` function has been renamed to @ref glfwWindowHint.
|
||||
|
||||
Window hints are no longer reset to their default values on window creation, but
|
||||
instead retain their values until modified by @ref glfwWindowHint or @ref
|
||||
glfwDefaultWindowHints, or until the library is terminated and re-initialized.
|
||||
|
||||
|
||||
@subsection moving_video_modes Video mode enumeration
|
||||
|
||||
Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function
|
||||
now returns all available modes for a specific monitor instead of requiring you
|
||||
to guess how large an array you need. The `glfwGetDesktopMode` function, which
|
||||
had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
|
||||
returns the current mode of a monitor.
|
||||
|
||||
|
||||
@subsection moving_char_up Removal of character actions
|
||||
|
||||
The action parameter of the [character callback](@ref GLFWcharfun) has been
|
||||
removed. This was an artefact of the origin of GLFW, i.e. being developed in
|
||||
English by a Swede. However, many keyboard layouts require more than one key to
|
||||
produce characters with diacritical marks. Even the Swedish keyboard layout
|
||||
requires this for uncommon cases like ü.
|
||||
|
||||
@par Old syntax
|
||||
@code
|
||||
void GLFWCALL character_callback(int character, int action);
|
||||
@endcode
|
||||
|
||||
@par New syntax
|
||||
@code
|
||||
void character_callback(GLFWwindow* window, int character);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection moving_cursorpos Cursor position changes
|
||||
|
||||
The `glfwGetMousePos` function has been renamed to @ref glfwGetCursorPos,
|
||||
`glfwSetMousePos` to @ref glfwSetCursorPos and `glfwSetMousePosCallback` to @ref
|
||||
glfwSetCursorPosCallback.
|
||||
|
||||
The cursor position is now `double` instead of `int`, both for the direct
|
||||
functions and for the callback. Some platforms can provide sub-pixel cursor
|
||||
movement and this data is now passed on to the application where available. On
|
||||
platforms where this is not provided, the decimal part is zero.
|
||||
|
||||
GLFW 3 only allows you to position the cursor within a window using @ref
|
||||
glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
|
||||
Unless the window is active, the function fails silently.
|
||||
|
||||
|
||||
@subsection moving_wheel Wheel position replaced by scroll offsets
|
||||
|
||||
The `glfwGetMouseWheel` function has been removed. Scrolling is the input of
|
||||
offsets and has no absolute position. The mouse wheel callback has been
|
||||
replaced by a [scroll callback](@ref GLFWscrollfun) that receives
|
||||
two-dimensional floating point scroll offsets. This allows you to receive
|
||||
precise scroll data from for example modern touchpads.
|
||||
|
||||
@par Old syntax
|
||||
@code
|
||||
void GLFWCALL mouse_wheel_callback(int position);
|
||||
@endcode
|
||||
|
||||
@par New syntax
|
||||
@code
|
||||
void scroll_callback(GLFWwindow* window, double xoffset, double yoffset);
|
||||
@endcode
|
||||
|
||||
@par Removed functions
|
||||
`glfwGetMouseWheel`
|
||||
|
||||
|
||||
@subsection moving_repeat Key repeat action
|
||||
|
||||
The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled
|
||||
for both keys and characters. A new key action, `GLFW_REPEAT`, has been added
|
||||
to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press
|
||||
from a repeat. Note that @ref glfwGetKey still returns only `GLFW_PRESS` or
|
||||
`GLFW_RELEASE`.
|
||||
|
||||
|
||||
@subsection moving_keys Physical key input
|
||||
|
||||
GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
|
||||
the values generated by the current keyboard layout. The tokens are named
|
||||
according to the values they would have in the standard US layout, but this
|
||||
is only a convenience, as most programmers are assumed to know that layout.
|
||||
This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and
|
||||
is the same key in the same place regardless of what keyboard layouts the users
|
||||
of your program have.
|
||||
|
||||
The key input facility was never meant for text input, although using it that
|
||||
way worked slightly better in GLFW 2. If you were using it to input text, you
|
||||
should be using the character callback instead, on both GLFW 2 and 3. This will
|
||||
give you the characters being input, as opposed to the keys being pressed.
|
||||
|
||||
GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of
|
||||
having to remember whether to check for `a` or `A`, you now check for
|
||||
@ref GLFW_KEY_A.
|
||||
|
||||
|
||||
@subsection moving_joystick Joystick function changes
|
||||
|
||||
The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes.
|
||||
|
||||
The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and
|
||||
`GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent
|
||||
function as well as axis and button counts returned by the @ref
|
||||
glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions.
|
||||
|
||||
|
||||
@subsection moving_mbcs Win32 MBCS support
|
||||
|
||||
The Win32 port of GLFW 3 will not compile in
|
||||
[MBCS mode](https://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
|
||||
However, because the use of the Unicode version of the Win32 API doesn't affect
|
||||
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.
|
||||
Therefore, even if an application using GLFW has MBCS mode code, there's no need
|
||||
for GLFW itself to support it.
|
||||
|
||||
|
||||
@subsection moving_windows Support for versions of Windows older than XP
|
||||
|
||||
All explicit support for version of Windows older than XP has been removed.
|
||||
There is no code that actively prevents GLFW 3 from running on these earlier
|
||||
versions, but it uses Win32 functions that those versions lack.
|
||||
|
||||
Windows XP was released in 2001, and by now (January 2015) it has not only
|
||||
replaced almost all earlier versions of Windows, but is itself rapidly being
|
||||
replaced by Windows 7 and 8. The MSDN library doesn't even provide
|
||||
documentation for version older than Windows 2000, making it difficult to
|
||||
maintain compatibility with these versions even if it was deemed worth the
|
||||
effort.
|
||||
|
||||
The Win32 API has also not stood still, and GLFW 3 uses many functions only
|
||||
present on Windows XP or later. Even supporting an OS as new as XP (new
|
||||
from the perspective of GLFW 2, which still supports Windows 95) requires
|
||||
runtime checking for a number of functions that are present only on modern
|
||||
version of Windows.
|
||||
|
||||
|
||||
@subsection moving_syskeys Capture of system-wide hotkeys
|
||||
|
||||
The ability to disable and capture system-wide hotkeys like Alt+Tab has been
|
||||
removed. Modern applications, whether they're games, scientific visualisations
|
||||
or something else, are nowadays expected to be good desktop citizens and allow
|
||||
these hotkeys to function even when running in full screen mode.
|
||||
|
||||
|
||||
@subsection moving_terminate Automatic termination
|
||||
|
||||
GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization,
|
||||
because `exit` calls registered functions from the calling thread and while it
|
||||
is permitted to call `exit` from any thread, @ref glfwTerminate must only be
|
||||
called from the main thread.
|
||||
|
||||
To release all resources allocated by GLFW, you should call @ref glfwTerminate
|
||||
yourself, from the main thread, before the program terminates. Note that this
|
||||
destroys all windows not already destroyed with @ref glfwDestroyWindow,
|
||||
invalidating any window handles you may still have.
|
||||
|
||||
|
||||
@subsection moving_glu GLU header inclusion
|
||||
|
||||
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
|
||||
projects should not use GLU__, but if you need it for legacy code that
|
||||
has been moved to GLFW 3, you can request that the GLFW header includes it by
|
||||
defining @ref GLFW_INCLUDE_GLU before the inclusion of the GLFW header.
|
||||
|
||||
@par Old syntax
|
||||
@code
|
||||
#include <GL/glfw.h>
|
||||
@endcode
|
||||
|
||||
@par New syntax
|
||||
@code
|
||||
#define GLFW_INCLUDE_GLU
|
||||
#include <GLFW/glfw3.h>
|
||||
@endcode
|
||||
|
||||
There are many libraries that offer replacements for the functionality offered
|
||||
by GLU. For the matrix helper functions, see math libraries like
|
||||
[GLM](https://github.com/g-truc/glm) (for C++),
|
||||
[linmath.h](https://github.com/datenwolf/linmath.h) (for C) and others. For the
|
||||
tessellation functions, see for example
|
||||
[libtess2](https://github.com/memononen/libtess2).
|
||||
|
||||
|
||||
@section moving_tables Name change tables
|
||||
|
||||
|
||||
@subsection moving_renamed_functions Renamed functions
|
||||
|
||||
| GLFW 2 | GLFW 3 | Notes |
|
||||
| --------------------------- | ----------------------------- | ----- |
|
||||
| `glfwOpenWindow` | @ref glfwCreateWindow | All channel bit depths are now hints
|
||||
| `glfwCloseWindow` | @ref glfwDestroyWindow | |
|
||||
| `glfwOpenWindowHint` | @ref glfwWindowHint | Now accepts all `GLFW_*_BITS` tokens |
|
||||
| `glfwEnable` | @ref glfwSetInputMode | |
|
||||
| `glfwDisable` | @ref glfwSetInputMode | |
|
||||
| `glfwGetMousePos` | @ref glfwGetCursorPos | |
|
||||
| `glfwSetMousePos` | @ref glfwSetCursorPos | |
|
||||
| `glfwSetMousePosCallback` | @ref glfwSetCursorPosCallback | |
|
||||
| `glfwSetMouseWheelCallback` | @ref glfwSetScrollCallback | Accepts two-dimensional scroll offsets as doubles |
|
||||
| `glfwGetJoystickPos` | @ref glfwGetJoystickAxes | |
|
||||
| `glfwGetWindowParam` | @ref glfwGetWindowAttrib | |
|
||||
| `glfwGetGLVersion` | @ref glfwGetWindowAttrib | Use `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and `GLFW_CONTEXT_REVISION` |
|
||||
| `glfwGetDesktopMode` | @ref glfwGetVideoMode | Returns the current mode of a monitor |
|
||||
| `glfwGetJoystickParam` | @ref glfwJoystickPresent | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons |
|
||||
|
||||
|
||||
@subsection moving_renamed_types Renamed types
|
||||
|
||||
| GLFW 2 | GLFW 3 | Notes |
|
||||
| ------------------- | --------------------- | |
|
||||
| `GLFWmousewheelfun` | @ref GLFWscrollfun | |
|
||||
| `GLFWmouseposfun` | @ref GLFWcursorposfun | |
|
||||
|
||||
|
||||
@subsection moving_renamed_tokens Renamed tokens
|
||||
|
||||
| GLFW 2 | GLFW 3 | Notes |
|
||||
| --------------------------- | ---------------------------- | ----- |
|
||||
| `GLFW_OPENGL_VERSION_MAJOR` | `GLFW_CONTEXT_VERSION_MAJOR` | Renamed as it applies to OpenGL ES as well |
|
||||
| `GLFW_OPENGL_VERSION_MINOR` | `GLFW_CONTEXT_VERSION_MINOR` | Renamed as it applies to OpenGL ES as well |
|
||||
| `GLFW_FSAA_SAMPLES` | `GLFW_SAMPLES` | Renamed to match the OpenGL API |
|
||||
| `GLFW_ACTIVE` | `GLFW_FOCUSED` | Renamed to match the window focus callback |
|
||||
| `GLFW_WINDOW_NO_RESIZE` | `GLFW_RESIZABLE` | The default has been inverted |
|
||||
| `GLFW_MOUSE_CURSOR` | `GLFW_CURSOR` | Used with @ref glfwSetInputMode |
|
||||
| `GLFW_KEY_ESC` | `GLFW_KEY_ESCAPE` | |
|
||||
| `GLFW_KEY_DEL` | `GLFW_KEY_DELETE` | |
|
||||
| `GLFW_KEY_PAGEUP` | `GLFW_KEY_PAGE_UP` | |
|
||||
| `GLFW_KEY_PAGEDOWN` | `GLFW_KEY_PAGE_DOWN` | |
|
||||
| `GLFW_KEY_KP_NUM_LOCK` | `GLFW_KEY_NUM_LOCK` | |
|
||||
| `GLFW_KEY_LCTRL` | `GLFW_KEY_LEFT_CONTROL` | |
|
||||
| `GLFW_KEY_LSHIFT` | `GLFW_KEY_LEFT_SHIFT` | |
|
||||
| `GLFW_KEY_LALT` | `GLFW_KEY_LEFT_ALT` | |
|
||||
| `GLFW_KEY_LSUPER` | `GLFW_KEY_LEFT_SUPER` | |
|
||||
| `GLFW_KEY_RCTRL` | `GLFW_KEY_RIGHT_CONTROL` | |
|
||||
| `GLFW_KEY_RSHIFT` | `GLFW_KEY_RIGHT_SHIFT` | |
|
||||
| `GLFW_KEY_RALT` | `GLFW_KEY_RIGHT_ALT` | |
|
||||
| `GLFW_KEY_RSUPER` | `GLFW_KEY_RIGHT_SUPER` | |
|
||||
|
||||
*/
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue