mirror of
https://github.com/glfw/glfw.git
synced 2024-11-10 00:51:47 +00:00
Documentation work.
This commit is contained in:
parent
c769061a8a
commit
4591ad2d64
@ -666,6 +666,8 @@ INPUT = @GLFW_INTERNAL_DOCS@ \
|
||||
@GLFW_SOURCE_DIR@/docs/monitor.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/window.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/input.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/common.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/rift.dox \
|
||||
@GLFW_SOURCE_DIR@/docs/compat.dox
|
||||
|
||||
# This tag can be used to specify the character encoding of the source files
|
||||
@ -936,7 +938,7 @@ HTML_EXTRA_STYLESHEET = @GLFW_SOURCE_DIR@/docs/extra.css
|
||||
# files. In the HTML_STYLESHEET file, use the file name only. Also note that
|
||||
# the files will be copied as-is; there are no commands or markers available.
|
||||
|
||||
HTML_EXTRA_FILES =
|
||||
HTML_EXTRA_FILES = @GLFW_SOURCE_DIR@/docs/spaces.svg
|
||||
|
||||
# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output.
|
||||
# Doxygen will adjust the colors in the style sheet and background images
|
||||
|
@ -1,24 +1,24 @@
|
||||
/*!
|
||||
|
||||
@page build Building programs that use GLFW
|
||||
@page build Building applications
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This is about compiling and linking programs that use GLFW. For information on
|
||||
how to write such programs, start with the [introductory tutorial](@ref quick).
|
||||
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).
|
||||
For information on how to compile the GLFW library itself, see the @ref compile
|
||||
guide.
|
||||
|
||||
This is not a tutorial on compilation. It assumes basic understanding of how to
|
||||
compile a C program as well as how to use the specific compiler of your chosen
|
||||
development environment. The compilation process should be explained in your
|
||||
C programming material and the use of and options for your compiler should be
|
||||
described in detail in the documentation for your development environment.
|
||||
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
|
||||
|
||||
In the files of your program where you use OpenGL or GLFW, you should include
|
||||
the GLFW header file, i.e.:
|
||||
In the source files of your application where you use OpenGL or GLFW, you should
|
||||
include the GLFW header file, i.e.:
|
||||
|
||||
@code
|
||||
#include <GLFW/glfw3.h>
|
||||
@ -30,13 +30,14 @@ types and function prototypes of the OpenGL API.
|
||||
|
||||
The GLFW header also defines everything necessary for your OpenGL header to
|
||||
function. For example, under Windows you are normally required to include
|
||||
`windows.h` before the OpenGL header. This would make your source file tied
|
||||
to Windows and pollute your code's namespace with the whole Win32 API.
|
||||
`windows.h` before the OpenGL header, which would pollute your code namespace
|
||||
with the entire Win32 API.
|
||||
|
||||
Instead, the GLFW header takes care of this for you, not by including
|
||||
`windows.h`, but by duplicating only the very few necessary parts of it. It
|
||||
does this only when needed, so if `windows.h` *is* included, the GLFW header
|
||||
does not try to redefine those symbols.
|
||||
does not try to redefine those symbols. The reverse is not true, i.e.
|
||||
`windows.h` cannot cope if any of its symbols have already been defined.
|
||||
|
||||
In other words:
|
||||
|
||||
@ -44,7 +45,7 @@ In other words:
|
||||
- Do *not* include `windows.h` or other platform-specific headers unless you
|
||||
plan on using those APIs directly
|
||||
- If you *do* need to include such headers, do it *before* including
|
||||
the GLFW one and it will detect this
|
||||
the GLFW header and it will handle this
|
||||
|
||||
If you are using an OpenGL extension loading library such as
|
||||
[glad](https://github.com/Dav1dde/glad), the extension loader header should
|
||||
@ -60,28 +61,29 @@ its behavior.
|
||||
`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 client API header is included.
|
||||
The following macros control which OpenGL or OpenGL ES API header is included.
|
||||
|
||||
`GLFW_INCLUDE_GLCOREARB` makes the header include the modern `GL/glcorearb.h`
|
||||
header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL header.
|
||||
`GLFW_INCLUDE_GLCOREARB` makes the GLFW header include the modern
|
||||
`GL/glcorearb.h` header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL
|
||||
header.
|
||||
|
||||
`GLFW_INCLUDE_ES1` makes the header include the OpenGL ES 1.x `GLES/gl.h` header
|
||||
instead of the regular OpenGL header.
|
||||
|
||||
`GLFW_INCLUDE_ES2` makes the header include the OpenGL ES 2.0 `GLES2/gl2.h`
|
||||
`GLFW_INCLUDE_ES1` makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
|
||||
header instead of the regular OpenGL header.
|
||||
|
||||
`GLFW_INCLUDE_ES3` makes the header include the OpenGL ES 3.0 `GLES3/gl3.h`
|
||||
`GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h`
|
||||
header instead of the regular OpenGL header.
|
||||
|
||||
`GLFW_INCLUDE_ES31` makes the header include the OpenGL ES 3.1 `GLES3/gl31.h`
|
||||
`GLFW_INCLUDE_ES3` makes the GLFW header include the OpenGL ES 3.0 `GLES3/gl3.h`
|
||||
header instead of the regular OpenGL header.
|
||||
|
||||
`GLFW_INCLUDE_NONE` makes the header not include any client API header. This is
|
||||
useful in combination with an extension loading library.
|
||||
`GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h`
|
||||
header instead of the regular OpenGL header.
|
||||
|
||||
If none of the above inclusion macros are defined, the standard OpenGL header is
|
||||
included.
|
||||
`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 OS X) is included.
|
||||
|
||||
`GLFW_INCLUDE_GLU` makes the header include the GLU header *in addition to* the
|
||||
header selected above. This should only be used with legacy code. GLU has been
|
||||
@ -104,12 +106,6 @@ 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.
|
||||
|
||||
This is not a tutorial on linking. It assumes basic understanding of how to
|
||||
link a C program as well as how to use the specific linker of your chosen
|
||||
development environment. The linking process should be explained in your
|
||||
C programming material and the use of and options for your linker should be
|
||||
described in detail in the documentation for your development environment.
|
||||
|
||||
A good general introduction to linking is
|
||||
[Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by
|
||||
David Drysdale.
|
||||
@ -120,20 +116,20 @@ David Drysdale.
|
||||
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 linking a program under Windows that uses the static version of GLFW, you
|
||||
must link with `opengl32`. On some versions of MinGW, you must also explicitly
|
||||
link with `gdi32`, while other versions of MinGW include it in the set of
|
||||
default libraries along with other dependencies like `user32` and `kernel32`.
|
||||
If you are using GLU, you must also link with `glu32`.
|
||||
When linking an application under Windows that uses the static version of GLFW,
|
||||
you must link with `opengl32`. On some versions of MinGW, you must also
|
||||
explicitly link with `gdi32`, while other versions of MinGW include it in the
|
||||
set of default libraries along with other dependencies like `user32` and
|
||||
`kernel32`. If you are using GLU, you must also link with `glu32`.
|
||||
|
||||
The link library for the GLFW DLL is named `glfw3dll`. When compiling a program
|
||||
that uses the DLL version of GLFW, you need to define the `GLFW_DLL` macro
|
||||
*before* any inclusion of the GLFW header. This can be done either with
|
||||
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 `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.
|
||||
|
||||
A program using the GLFW DLL does not need to link against any of its
|
||||
dependencies, but you still have to link against `opengl32` if your program uses
|
||||
OpenGL and `glu32` if it uses GLU.
|
||||
An application using the GLFW DLL does not need to link against any of its
|
||||
dependencies, but you still have to link against `opengl32` if your application
|
||||
uses OpenGL and `glu32` if it uses GLU.
|
||||
|
||||
|
||||
@subsection build_link_cmake_source With CMake and GLFW source
|
||||
@ -266,8 +262,12 @@ If you are using the dynamic library version of GLFW, simply add it to the
|
||||
project dependencies.
|
||||
|
||||
If you are using the static library version of GLFW, add it and the Cocoa,
|
||||
OpenGL, IOKit and CoreVideo frameworks to the project as dependencies. They can
|
||||
all be found in `/System/Library/Frameworks`.
|
||||
OpenGL, IOKit, CoreVideo and Carbon frameworks to the project as dependencies.
|
||||
They can all be found in `/System/Library/Frameworks`.
|
||||
|
||||
@note GLFW needs the Carbon framework only to access the current keyboard layout
|
||||
via the Text Input Source Services. This is one of the non-deprecated parts of
|
||||
the Carbon API and the only way to access this information on OS X.
|
||||
|
||||
|
||||
@subsection build_link_osx With command-line on OS X
|
||||
|
18
docs/common.dox
Normal file
18
docs/common.dox
Normal file
@ -0,0 +1,18 @@
|
||||
/*!
|
||||
|
||||
@page common Common tasks
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide explains how to
|
||||
|
||||
|
||||
@section common_full_screen Windowed full screen mode
|
||||
|
||||
@section common_window_pos Initial window position
|
||||
|
||||
GLFW comes with the `windows` test program, which illustrates this method.
|
||||
|
||||
@section common_fps_camera First-person camera controls
|
||||
|
||||
*/
|
@ -4,19 +4,20 @@
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This chapter describes the various API extensions used by this version of GLFW.
|
||||
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 wishing to deploy their applications on machines
|
||||
with varied specifications.
|
||||
vital knowledge for developers intending to deploy their applications on a wide
|
||||
range of machines.
|
||||
|
||||
@note 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.
|
||||
|
||||
Note that the information in this appendix is not a part of the API
|
||||
specification but merely list some of the preconditions for certain parts of the
|
||||
API to function on a given machine. As such, any part of it may change in
|
||||
future versions without this being considered a breaking API change.
|
||||
|
||||
@section compat_x11 X11 extensions, protocols and IPC standards
|
||||
|
||||
As GLFW uses Xlib, directly, without any intervening toolkit
|
||||
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
|
||||
@ -79,13 +80,14 @@ GLFW requires the Xkb extension with detectable auto-repeat to provide keyboard
|
||||
input. If the running X server does not support this extension, a non-Xkb
|
||||
fallback path is used.
|
||||
|
||||
|
||||
@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 `GLXFBConfig` API to enumerate and select framebuffer pixel
|
||||
formats. This requires GLX 1.3 or greater.
|
||||
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
|
||||
|
125
docs/compile.dox
125
docs/compile.dox
@ -5,36 +5,45 @@
|
||||
@tableofcontents
|
||||
|
||||
This is about compiling the GLFW library itself. For information on how to
|
||||
build programs that use GLFW, see the @ref build guide.
|
||||
build applications that use GLFW, see the @ref build guide.
|
||||
|
||||
|
||||
@section compile_deps Dependencies
|
||||
@section compile_cmake Using CMake
|
||||
|
||||
To compile GLFW and the accompanying example programs, you will need **CMake**,
|
||||
which will generate the project files or makefiles for your particular
|
||||
development environment. If you are on a Unix-like system such as Linux or
|
||||
FreeBSD or have a package system like Fink, MacPorts, Cygwin or Homebrew, you
|
||||
can simply install its CMake package. If not, you can get installers for
|
||||
Windows and OS X from the [CMake website](http://www.cmake.org/).
|
||||
GLFW uses [CMake](http://www.cmake.org/) to generate project files or makefiles
|
||||
for a particular development environment. If you are on a Unix-like system such
|
||||
as Linux or FreeBSD or have a package system like Fink, MacPorts, Cygwin or
|
||||
Homebrew, you can simply install its CMake package. If not, you can download
|
||||
installers for Windows and OS X from the [CMake website](http://www.cmake.org/).
|
||||
|
||||
Additional dependencies are listed below.
|
||||
|
||||
If you wish to compile GLFW without CMake, see @ref compile_manual.
|
||||
@note CMake only generates project files or makefiles. It does not compile the
|
||||
actual GLFW library. To compile GLFW, first generate these files and then use
|
||||
them in your chosen development environment to compile the actual GLFW library.
|
||||
|
||||
|
||||
@subsection compile_deps_msvc Dependencies using Visual C++ on Windows
|
||||
@subsection compile_deps Dependencies
|
||||
|
||||
The Microsoft Platform SDK that is installed along with Visual C++ contains all
|
||||
the necessary headers, link libraries and tools except for CMake.
|
||||
Once you have installed CMake, make sure that all other dependencies are
|
||||
available. On some platforms, GLFW needs a few additional packages to be
|
||||
installed. See the section for your chosen platform and development environment
|
||||
below.
|
||||
|
||||
|
||||
@subsection compile_deps_mingw Dependencies with MinGW or MinGW-w64 on Windows
|
||||
@subsubsection compile_deps_msvc Dependencies for Visual C++ on Windows
|
||||
|
||||
Both the MinGW and the MinGW-w64 packages contain all the necessary headers,
|
||||
link libraries and tools except for CMake.
|
||||
The Microsoft Platform SDK that is installed along with Visual C++ already
|
||||
contains all the necessary headers, link libraries and tools except for CMake.
|
||||
Move on to @ref compile_generate.
|
||||
|
||||
|
||||
@subsection compile_deps_mingw_cross Dependencies using MinGW or MinGW-w64 cross-compilation
|
||||
@subsubsection compile_deps_mingw Dependencies for MinGW or MinGW-w64 on Windows
|
||||
|
||||
Both the MinGW and the MinGW-w64 packages already contain all the necessary
|
||||
headers, link libraries and tools except for CMake. Move on to @ref
|
||||
compile_generate.
|
||||
|
||||
|
||||
@subsubsection compile_deps_mingw_cross Dependencies for MinGW or MinGW-w64 cross-compilation
|
||||
|
||||
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
|
||||
@ -45,7 +54,9 @@ GLFW has CMake toolchain files in the `CMake/` directory that allow for easy
|
||||
cross-compilation of Windows binaries. To use these files you need to add a
|
||||
special parameter when generating the project files or makefiles:
|
||||
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
|
||||
@code{.sh}
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-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
|
||||
@ -53,21 +64,27 @@ directory. For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages
|
||||
have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
|
||||
invocation would be:
|
||||
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
|
||||
@code{.sh}
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
|
||||
@endcode
|
||||
|
||||
For more details see the article
|
||||
[CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on
|
||||
the CMake wiki.
|
||||
|
||||
|
||||
@subsection compile_deps_xcode Dependencies using Xcode on OS X
|
||||
|
||||
Xcode contains all necessary tools except for CMake. The necessary headers and
|
||||
libraries are included in the core OS frameworks. Xcode can be downloaded from
|
||||
the Mac App Store or from the ADC Member Center.
|
||||
Once you have this set up, move on to @ref compile_generate.
|
||||
|
||||
|
||||
@subsection compile_deps_x11 Dependencies using Linux and X11
|
||||
@subsubsection compile_deps_xcode Dependencies for Xcode on OS X
|
||||
|
||||
Xcode comes with all necessary tools except for CMake. The required headers
|
||||
and libraries are included in the core OS X frameworks. Xcode can be downloaded
|
||||
from the Mac App Store or from the ADC Member Center.
|
||||
|
||||
Once you have Xcode installed, move on to @ref compile_generate.
|
||||
|
||||
|
||||
@subsubsection compile_deps_x11 Dependencies for Linux and X11
|
||||
|
||||
To compile GLFW for X11, you need to have the X11 and OpenGL header packages
|
||||
installed, as well as the basic development tools like GCC and make. For
|
||||
@ -78,8 +95,11 @@ packages. GLFW itself doesn't need or use GLU, but some of the examples do.
|
||||
Note that using header files and libraries from Mesa during compilation *will
|
||||
not* tie your binaries to the Mesa implementation of OpenGL.
|
||||
|
||||
Once you have installed the necessary packages, move on to @ref
|
||||
compile_generate.
|
||||
|
||||
@section compile_cmake Generating files with CMake
|
||||
|
||||
@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 to know two
|
||||
@ -91,36 +111,59 @@ otherwise it is called an out-of-tree build.
|
||||
One of several advantages of out-of-tree builds is that you can generate files
|
||||
and compile for different development environments using a single source tree.
|
||||
|
||||
@note This section is about generating the project files or makefiles necessary
|
||||
to compile the GLFW library, not about compiling the actual library.
|
||||
|
||||
@subsection compile_cmake_cli Generating files with the CMake command-line tool
|
||||
|
||||
@subsubsection compile_generate_cli Generating files with the CMake command-line tool
|
||||
|
||||
To make an in-tree build, enter the *root* directory of the GLFW source tree
|
||||
(i.e. *not* the `src` subdirectory) and run CMake. The current directory is
|
||||
used as target path, while the path provided as an argument is used to find the
|
||||
source tree.
|
||||
|
||||
cd <glfw-root-dir>
|
||||
cmake .
|
||||
@code{.sh}
|
||||
cd <glfw-root-dir>
|
||||
cmake .
|
||||
@endcode
|
||||
|
||||
To make an out-of-tree build, make another directory, enter it and run CMake
|
||||
with the (relative or absolute) path to the root of the source tree as an
|
||||
argument.
|
||||
|
||||
cd <glfw-root-dir>
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
@code{.sh}
|
||||
cd <glfw-root-dir>
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
@endcode
|
||||
|
||||
Once you have generated the project files or makefiles for your chosen
|
||||
development environment, move on to @ref compile_compile.
|
||||
|
||||
|
||||
@subsection compile_cmake_gui Generating files with the CMake GUI
|
||||
@subsubsection compile_generate_gui Generating files with the CMake GUI
|
||||
|
||||
If you are using the GUI version, choose the root of the GLFW source tree as
|
||||
source location and the same directory or another, empty directory as the
|
||||
destination for binaries. Choose *Configure*, change any options you wish to,
|
||||
*Configure* again to let the changes take effect and then *Generate*.
|
||||
|
||||
Once you have generated the project files or makefiles for your chosen
|
||||
development environment, move on to @ref compile_compile.
|
||||
|
||||
@section compile_options CMake options
|
||||
|
||||
@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.
|
||||
|
||||
Once the GLFW library is compiled, you are ready to build your applications,
|
||||
linking it to the GLFW library. See the @ref build guide for more information.
|
||||
|
||||
|
||||
@subsection 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
|
||||
@ -132,7 +175,7 @@ Some package systems like Ubuntu and other distributions based on Debian
|
||||
GNU/Linux have this tool in a separate `cmake-curses-gui` package.
|
||||
|
||||
|
||||
@subsection compile_options_shared Shared CMake options
|
||||
@subsubsection compile_options_shared Shared CMake options
|
||||
|
||||
`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
|
||||
library or as a DLL / shared library / dynamic library.
|
||||
@ -157,7 +200,7 @@ built along with the library.
|
||||
the library.
|
||||
|
||||
|
||||
@subsection compile_options_osx OS X specific CMake options
|
||||
@subsubsection compile_options_osx OS X specific CMake options
|
||||
|
||||
`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
|
||||
directory of bundled applications to the `Contents/Resources` directory.
|
||||
@ -171,7 +214,7 @@ Retina displays.
|
||||
`GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries.
|
||||
|
||||
|
||||
@subsection compile_options_win32 Windows specific CMake options
|
||||
@subsubsection compile_options_win32 Windows specific CMake options
|
||||
|
||||
`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the
|
||||
static library version of the Visual C++ runtime library. If set to `ON`, the
|
||||
@ -189,7 +232,7 @@ symbol, which forces the use of the high-performance GPU on nVidia Optimus
|
||||
systems.
|
||||
|
||||
|
||||
@subsection compile_options_egl EGL specific CMake options
|
||||
@subsubsection compile_options_egl EGL specific CMake options
|
||||
|
||||
`GLFW_USE_EGL` determines whether to use EGL instead of the platform-specific
|
||||
context creation API. Note that EGL is not yet provided on all supported
|
||||
|
@ -1,6 +1,6 @@
|
||||
/*!
|
||||
|
||||
@page context Context handling guide
|
||||
@page context Context guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
@ -8,31 +8,52 @@ The primary purpose of GLFW is to provide a simple interface to window
|
||||
management and OpenGL and OpenGL ES context creation. GLFW supports
|
||||
multiple windows, with each window having its own context.
|
||||
|
||||
This guide introduces the functions related to managing OpenGL and OpenGL ES
|
||||
contexts. There are also guides for the other areas of the GLFW API.
|
||||
|
||||
@section context_object Context handles
|
||||
- @ref intro
|
||||
- @ref window
|
||||
- @ref monitor
|
||||
- @ref input
|
||||
|
||||
The @ref GLFWwindow object encapsulates both a [window](@ref window) and
|
||||
a context. It is created with @ref glfwCreateWindow and destroyed with @ref
|
||||
|
||||
@section context_object Context objects
|
||||
|
||||
@ref window_object encapsulate both the OS level window and a OpenGL or OpenGL
|
||||
ES context. It is created with @ref glfwCreateWindow and destroyed with @ref
|
||||
glfwDestroyWindow or @ref glfwTerminate. As the window and context are
|
||||
inseparably linked, the object pointer is used as both a context and window
|
||||
handle.
|
||||
handle. See @ref window_creation for more information.
|
||||
|
||||
|
||||
@section context_hints Context creation hints
|
||||
@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 handling guide.
|
||||
[context related hints](@ref window_hints_ctx) in the window guide.
|
||||
|
||||
|
||||
@section context_sharing Context object sharing
|
||||
@subsection context_sharing Context object sharing
|
||||
|
||||
When creating a window and context with @ref glfwCreateWindow, you can specify
|
||||
another window whose context the new one should share its objects with. Object
|
||||
sharing is implemented by the operating system and graphics driver and is
|
||||
described in the OpenGL and OpenGL ES documentation. On platforms where it is
|
||||
possible to choose which types of objects are shared, GLFW requests that all are
|
||||
shared.
|
||||
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](http://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 simple object sharing test program called `sharing`.
|
||||
|
||||
|
||||
@section context_current Current context
|
||||
@ -53,14 +74,14 @@ The current context is returned by @ref glfwGetCurrentContext.
|
||||
GLFWwindow* window = glfwGetCurrentContext();
|
||||
@endcode
|
||||
|
||||
@note A context must only be current for a single thread at a time, and a thread
|
||||
must only have a single context current at a time.
|
||||
@note 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.
|
||||
|
||||
|
||||
@section context_swap Swapping buffers
|
||||
@section context_swap Buffer swapping
|
||||
|
||||
Buffer swapping is part of the window and framebuffer, not the context. See
|
||||
@ref window_swap in the window handling guide.
|
||||
@ref window_swap in the window guide.
|
||||
|
||||
|
||||
@section context_glext OpenGL and OpenGL ES extensions
|
||||
@ -170,10 +191,8 @@ 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.
|
||||
|
||||
@note It is strongly recommended that you use an existing extension loader
|
||||
library like [glad](https://github.com/Dav1dde/glad) instead of loading
|
||||
manually. Extension loading is a solved problem and you will gain nothing from
|
||||
solving it again by hand.
|
||||
@note It is recommended that you use an existing extension loader library, as
|
||||
described above, instead of loading manually.
|
||||
|
||||
|
||||
@subsubsection context_glext_header The glext.h header
|
||||
|
File diff suppressed because one or more lines are too long
@ -114,6 +114,23 @@ h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em {
|
||||
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;
|
||||
height:64px;
|
||||
|
554
docs/input.dox
554
docs/input.dox
@ -1,13 +1,563 @@
|
||||
/*!
|
||||
|
||||
@page input Input handling guide
|
||||
@page input Input guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
@section input_key Keyboard input
|
||||
This guide introduces the input related functions of GLFW. There are also
|
||||
guides for the other areas of GLFW.
|
||||
|
||||
- @ref intro
|
||||
- @ref window
|
||||
- @ref context
|
||||
- @ref monitor
|
||||
|
||||
GLFW provides many kinds of input. While some can only be polled, like time, or
|
||||
only received via callbacks, like scrolling, there are those that provide both
|
||||
callbacks and polling. Where a callback is provided, that is the recommended
|
||||
way to receive that kind of input. The more you can use callbacks the less time
|
||||
your users' machines will need to spend polling.
|
||||
|
||||
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 register every callback supported by GLFW and prints
|
||||
out all arguments provided for every event, along with time and sequence
|
||||
information.
|
||||
|
||||
|
||||
@section input_event Event processing
|
||||
|
||||
GLFW needs to communicate regularly with the window system both in order to
|
||||
receive events and to show that the application hasn't locked up. Event
|
||||
processing must be done regularly while you have visible windows and is normally
|
||||
done each frame after [buffer swapping](@ref window_swap).
|
||||
|
||||
There are two 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 continually, 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. There must be at least one GLFW window
|
||||
for this function to sleep.
|
||||
|
||||
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 through either of the above
|
||||
functions. While it is necessary to process events in the event queue, some
|
||||
window systems will send some events directly to the application, which in turn
|
||||
causes callbacks to be called outside of regular event processing.
|
||||
|
||||
|
||||
@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 Unicode code points 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 with @ref glfwSetKeyCallback.
|
||||
|
||||
@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`. The key
|
||||
will be `GLFW_KEY_UNKNOWN` if GLFW lacks a key token for it. These keys still
|
||||
have unique, if platform-specific scancodes.
|
||||
|
||||
The scancode is unique for every key but is platform-specific, so a scancode
|
||||
will map to different keys on different platforms.
|
||||
|
||||
The key will be `GLFW_KEY_UNKNOWN` for special keys like *E-mail* or *Play* that
|
||||
don't have a key token. Those keys will still have unique, if platform-specific
|
||||
scancodes.
|
||||
|
||||
Key states for [named keys](@ref keys) are 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 key.
|
||||
|
||||
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, 1);
|
||||
@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`.
|
||||
|
||||
The `GLFW_KEY_LAST` constant holds the highest value of any
|
||||
[named key](@ref keys).
|
||||
|
||||
|
||||
@subsection input_char Unicode character input
|
||||
|
||||
If you wish to receive Unicode code point input, set a character callback with
|
||||
@ref glfwSetCharCallback.
|
||||
|
||||
@code
|
||||
glfwSetCharCallback(window, character_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives Unicode code points for key events that would
|
||||
have led to regular text input on that platform.
|
||||
|
||||
@code
|
||||
void character_callback(GLFWwindow* window, unsigned int codepoint)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
If you wish to receive all Unicode code point events generated by the system, or
|
||||
just want to know exactly what modifier keys were used, set a character with
|
||||
modifiers callback with @ref glfwSetCharModsCallback.
|
||||
|
||||
@code
|
||||
glfwSetCharCallback(window, charmods_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives Unicode code points and
|
||||
[modifier bits](@ref mods).
|
||||
|
||||
@code
|
||||
void charmods_callback(GLFWwindow* window, unsigned int codepoint, int mods)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@section input_mouse Mouse input
|
||||
|
||||
Mouse input comes in many forms, including of mouse motion and button presses,
|
||||
system cursor appearance and behavior, and two-dimensional scrolling. All of
|
||||
these are supported by GLFW.
|
||||
|
||||
|
||||
@subsection input_cursor_pos Cursor position
|
||||
|
||||
If you wish to be notified when the system cursor moves over the window, set
|
||||
a cursor position callback with @ref glfwSetCursorPosCallback.
|
||||
|
||||
@code
|
||||
glfwSetCursorPosCallback(window, cursor_pos_callback);
|
||||
@endcode
|
||||
|
||||
The callback functions receives the cursor position. 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
|
||||
|
||||
This function only returns cached cursor positions. It does not poll the
|
||||
system for the current position. Whenever you poll state, you risk missing the
|
||||
state change you are looking for.
|
||||
|
||||
|
||||
@subsection input_cursor_mode Cursor modes
|
||||
|
||||
The `GLFW_CURSOR` input mode provides several cursor modes for special forms of
|
||||
mouse motion input. By default, the `GLFW_CURSOR_NORMAL` cursor mode is used,
|
||||
meaning the regular arrow cursor or a [custom cursor](@ref input_cursor) 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, both via the cursor position callback and via position
|
||||
polling.
|
||||
|
||||
@note You should not implement your own version of this functionality using
|
||||
other features of GLFW. It will not work as robustly as `GLFW_CURSOR_DISABLED`,
|
||||
as those features are not intended for this purpose.
|
||||
|
||||
If you just wish the cursor to become hidden when it is over a window, 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
|
||||
|
||||
|
||||
@subsection input_cursor Cursor objects
|
||||
|
||||
GLFW supports creating custom system cursor images, encapsulated as @ref
|
||||
GLFWcursor objects. They are created with @ref glfwCreateCursor and destroyed
|
||||
with @ref glfwDestroyCursor (or @ref glfwTerminate, if any remain).
|
||||
|
||||
|
||||
@subsubsection input_cursor_creation Cursor creation
|
||||
|
||||
A 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
|
||||
|
||||
The image data is 32-bit RGBA, i.e. eight bits per channel. The pixels are
|
||||
arranged canonically as sequental rows, starting from the top-left corner.
|
||||
|
||||
|
||||
@subsubsection input_cursor_destruction Cursor destruction
|
||||
|
||||
When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
|
||||
|
||||
@code
|
||||
glfwDestroyCursor(cursor);
|
||||
@endcode
|
||||
|
||||
Cursor destruction always succeeds. All cursors remaining at the time of @ref
|
||||
glfwTerminate is called are destroyed as well.
|
||||
|
||||
|
||||
@subsubsection input_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
|
||||
client area of the window and the [cursor mode](@ref input_cursor_mode) is set
|
||||
to `GLFW_CURSOR_NORMAL`.
|
||||
|
||||
A single cursor may be set for any number of windows.
|
||||
|
||||
To remove a cursor from a window, set the cursor of that window to `NULL`.
|
||||
|
||||
@code
|
||||
glfwSetCursor(window, NULL);
|
||||
@endcode
|
||||
|
||||
When a cursor is destroyed, it is removed from any window where it is set. This
|
||||
does not affect the cursor modes of those windows.
|
||||
|
||||
|
||||
@subsection input_cursor_enter Cursor enter/leave events
|
||||
|
||||
If you wish to be notified when the cursor enters or leaves the client area of
|
||||
a window, set a cursor enter/leave callback with @ref glfwSetCursorEnterCallback.
|
||||
|
||||
@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 client area of the window
|
||||
}
|
||||
else
|
||||
{
|
||||
// The cursor left the client area of the window
|
||||
}
|
||||
}
|
||||
@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 with @ref glfwSetMouseButtonCallback.
|
||||
|
||||
@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`.
|
||||
|
||||
Mouse button states for [named buttons](@ref buttons) are 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.
|
||||
|
||||
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, 1);
|
||||
@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
|
||||
[named button](@ref buttons).
|
||||
|
||||
|
||||
@subsection input_scroll Scroll input
|
||||
|
||||
If you wish to be notified when the user scrolls, whether with a mouse wheel or
|
||||
touchpad gesture, set a scroll callback with @ref glfwSetScrollCallback.
|
||||
|
||||
@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 simple mouse wheel, being vertical, provides offsets along the Y-axis.
|
||||
|
||||
|
||||
@section input_joy 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 `GLFW_JOYSTICK_LAST`. You can test
|
||||
whether a [joystick](@ref joysticks) is present with @ref glfwJoystickPresent.
|
||||
|
||||
@code
|
||||
int present = glfwJoystickPresent(GLFW_JOYSTICK_1);
|
||||
@endcode
|
||||
|
||||
When GLFW is initialized, detected joysticks are added to to the beginning of
|
||||
the array, starting with `GLFW_JOYSTICK_1`. Once a joystick is detected, it
|
||||
keeps its assigned index until it is disconnected, so as joysticks are connected
|
||||
and disconnected, they will become spread out.
|
||||
|
||||
Joystick state is updated as needed when a joystick function is called and does
|
||||
not require a window to be created or @ref glfwPollEvents or @ref glfwWaitEvents
|
||||
to be called.
|
||||
|
||||
|
||||
@subsection input_joy_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_1, &count);
|
||||
@endcode
|
||||
|
||||
Each element in the returned array is a value between -1.0 and 1.0.
|
||||
|
||||
|
||||
@subsection input_joy_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* axes = glfwGetJoystickButtons(GLFW_JOYSTICK_1, &count);
|
||||
@endcode
|
||||
|
||||
Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`.
|
||||
|
||||
|
||||
@subsection input_joy_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_1);
|
||||
@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 token](@ref joysticks) is
|
||||
guaranteed to be unique, and only until that joystick is disconnected.
|
||||
|
||||
|
||||
@section input_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 timer was started when the library
|
||||
was initialized with @ref glfwInit. The platform-specific time sources used
|
||||
usually have micro- or nanosecond resolution.
|
||||
|
||||
You can modify the reference time with @ref glfwSetTime.
|
||||
|
||||
@code
|
||||
glfwSetTime(4.0);
|
||||
@endcode
|
||||
|
||||
This sets the timer to the specified time, in seconds.
|
||||
|
||||
|
||||
@section input_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* clipboard = glfwGetClipboardString(window);
|
||||
@endcode
|
||||
|
||||
The contents of the system clipboard can be set to a UTF-8 encoded string with
|
||||
@ref glfwSetClipboardString.
|
||||
|
||||
@code
|
||||
glfwSetClipboardString(window, "A string with words in it");
|
||||
@endcode
|
||||
|
||||
The clipboard functions take a window handle argument because some window
|
||||
systems require a window to communicate with the system clipboard. Any valid
|
||||
window may be used.
|
||||
|
||||
|
||||
@section input_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 with @ref glfwSetDropCallback.
|
||||
|
||||
@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.
|
||||
|
||||
*/
|
||||
|
225
docs/intro.dox
225
docs/intro.dox
@ -1,12 +1,13 @@
|
||||
/*!
|
||||
|
||||
@page intro Introduction to the GLFW API
|
||||
@page intro Introduction to the API
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide will introduce the basic concepts of GLFW and describes
|
||||
initialization, error handling and version management. There are other guides
|
||||
for the various areas of the GLFW API.
|
||||
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 instead. There are also guides for the other areas of
|
||||
GLFW.
|
||||
|
||||
- @ref window
|
||||
- @ref context
|
||||
@ -22,7 +23,7 @@ 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.
|
||||
successfully initialized, and only from the main thread.
|
||||
|
||||
- @ref glfwGetVersion
|
||||
- @ref glfwGetVersionString
|
||||
@ -36,8 +37,8 @@ error.
|
||||
|
||||
@subsection intro_init_init Initializing GLFW
|
||||
|
||||
The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an
|
||||
error occurred.
|
||||
The library is initialized with @ref glfwInit, which returns zero if an error
|
||||
occurred.
|
||||
|
||||
@code
|
||||
if (!glfwInit())
|
||||
@ -49,7 +50,7 @@ if (!glfwInit())
|
||||
If any part of initialization fails, all remaining bits are terminated as if
|
||||
@ref glfwTerminate was called. The library only needs to be initialized once
|
||||
and additional calls to an already initialized library will simply return
|
||||
`GL_TRUE` immediately.
|
||||
non-zero immediately.
|
||||
|
||||
Once the library has been successfully initialized, it should be terminated
|
||||
before the application exits.
|
||||
@ -74,23 +75,24 @@ library had not been successfully initialized or had already been terminated,
|
||||
additional calls return immediately.
|
||||
|
||||
|
||||
@section intro_error Error handling
|
||||
@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 *why* the error occurred. Also, far
|
||||
from all GLFW functions have such return values.
|
||||
not very helpful when trying to figure out *why* the error occurred. Some
|
||||
functions also return otherwise valid values on error. Finally, far from all
|
||||
GLFW functions have return values.
|
||||
|
||||
This is where the error callback comes in. This callback is called whenever an
|
||||
error occurs. It is set with @ref glfwSetErrorCallback, a function that may be
|
||||
called before @ref glfwInit and after @ref glfwTerminate.
|
||||
called regardless of whether GLFW is initialized.
|
||||
|
||||
@code
|
||||
glfwSetErrorCallback(error_callback);
|
||||
@endcode
|
||||
|
||||
The error callback receives a human-readable description of the error and (when
|
||||
possible) its cause. The description is a regular C string using the UTF-8
|
||||
encoding. The callback is also provided with an [error code](@ref errors).
|
||||
possible) its cause. The description encoded as UTF-8. The callback is also
|
||||
provided with an [error code](@ref errors).
|
||||
|
||||
@code
|
||||
void error_callback(int error, const char* description)
|
||||
@ -100,25 +102,177 @@ void error_callback(int error, const char* description)
|
||||
@endcode
|
||||
|
||||
The error code indicates the general category of the error. Some error codes,
|
||||
such as `GLFW_NOT_INITIALIZED` has only a single meaning, whereas others like
|
||||
`GLFW_PLATFORM_ERROR` are used for many different errors.
|
||||
such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
|
||||
@ref GLFW_PLATFORM_ERROR are used for many different errors.
|
||||
|
||||
@note The description string is only valid until the error callback returns, as
|
||||
it may have been generated specifically for that error. This lets GLFW provide
|
||||
much more specific error descriptions but means you must make a copy if you want
|
||||
to keep the description string.
|
||||
The description string is only valid until the error callback returns, as it may
|
||||
have been generated specifically for that error. This lets GLFW provide much
|
||||
more specific error descriptions but means you must make a copy if you want to
|
||||
keep the description string.
|
||||
|
||||
|
||||
@section coordinate_systems Coordinate systems
|
||||
|
||||
GLFW has two primary coordinate systems: the _virtual screen_ and the window
|
||||
_client 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%" />
|
||||
|
||||
Window and monitor positions are specified relative to the upper-left corners of
|
||||
their content areas, while cursor positions are specified relative to the window
|
||||
client area.
|
||||
|
||||
The origin of the window client area coordinate system is also the position of
|
||||
the window, meaning you can translate client area coordinates to the virtual
|
||||
screen by adding the window position. The window frame, when present, extend
|
||||
out from the client 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 on.
|
||||
|
||||
|
||||
@section guarantees_limitations Guarantees and limitations
|
||||
|
||||
This section describes the conditions under which GLFW can be expected to
|
||||
function, barring any bugs in GLFW, the operating system or drivers. Use of
|
||||
GLFW outside of 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
|
||||
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,
|
||||
they are copied before the function returns.
|
||||
|
||||
Pointer lifetimes are guaranteed not to be shortened in future minor releases.
|
||||
|
||||
|
||||
@subsection reentrancy Reentrancy
|
||||
|
||||
GLFW event processing and object creation and destruction are not reentrant.
|
||||
This means that the following functions may not be called from any callback
|
||||
function:
|
||||
|
||||
- @ref glfwCreateWindow
|
||||
- @ref glfwDestroyWindow
|
||||
- @ref glfwCreateCursor
|
||||
- @ref glfwDestroyCursor
|
||||
- @ref glfwPollEvents
|
||||
- @ref glfwWaitEvents
|
||||
|
||||
|
||||
@subsection thread_safety Thread safety
|
||||
|
||||
Most GLFW functions may only be called from the main thread. The reference
|
||||
documentation for every GLFW function states whether it is limited to the main
|
||||
thread.
|
||||
|
||||
There are some general rules that make it easier to remember which functions are
|
||||
limited to the main thread. The following tasks may only be performed on the
|
||||
main thread:
|
||||
|
||||
- Initialization and termination
|
||||
- Event processing
|
||||
- Creation and destruction of window, context and cursor objects
|
||||
|
||||
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 posting of empty events may be done from any thread. The window user
|
||||
pointer and close flag may also be accessed and modified from any thread, but
|
||||
this is not synchronized by GLFW. The following window related functions may
|
||||
be called from any thread:
|
||||
|
||||
- @ref glfwPostEmptyEvent
|
||||
- @ref glfwGetWindowUserPointer
|
||||
- @ref glfwSetWindowUserPointer
|
||||
- @ref glfwWindowShouldClose
|
||||
- @ref glfwSetWindowShouldClose
|
||||
|
||||
Rendering may be done on any thread. The following context related functions
|
||||
may be called from any thread:
|
||||
|
||||
- @ref glfwMakeContextCurrent
|
||||
- @ref glfwGetCurrentContext
|
||||
- @ref glfwSwapBuffers
|
||||
- @ref glfwSwapInterval
|
||||
- @ref glfwExtensionSupported
|
||||
- @ref glfwGetProcAddress
|
||||
|
||||
The timer may be accessed from any thread, but this is not synchronized by GLFW.
|
||||
The following timer related functions may be called from any thread:
|
||||
|
||||
- @ref glfwGetTime
|
||||
|
||||
No GLFW function may be called from any other thread until GLFW has been
|
||||
successfully initialized on the main thread, including functions that may called
|
||||
before initialization.
|
||||
|
||||
GLFW uses no synchronization objects internally except for thread-local storage
|
||||
to keep track of the current context for each thread. 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 may be updated to allow
|
||||
calls from any thread in future releases.
|
||||
|
||||
|
||||
@subsection compatibility Version compatibility
|
||||
|
||||
GLFW guarantees binary backward compatibility with earlier minor versions of the
|
||||
API. This means that you can drop in a newer version of the GLFW DLL / shared
|
||||
library / dynamic library and existing applications 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.
|
||||
|
||||
Undefined behavior, i.e. behavior that is not described in reference
|
||||
documentation, may change at any time until it is documented.
|
||||
|
||||
If the reference documentation and the implementation differ, the reference
|
||||
documentation is correct and the implementation will be fixed in the next
|
||||
release.
|
||||
|
||||
|
||||
@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 using. The GLFW
|
||||
API is binary-compatible with later minor versions, i.e. an executable using the
|
||||
3.0 API will be able to use a version 3.2 DLL.
|
||||
|
||||
As long as an executable does not use any newer functions, it can also use an
|
||||
older minor version DLL, although any window hints or other tokens added since
|
||||
that older version will cause errors to be reported.
|
||||
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
|
||||
@ -126,15 +280,24 @@ that older version will cause errors to be reported.
|
||||
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 before @ref glfwInit and after @ref glfwTerminate
|
||||
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
|
||||
|
||||
|
||||
@ -146,7 +309,7 @@ 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 before @ref glfwInit and after @ref glfwTerminate.
|
||||
be called regardless of whether GLFW is initialized.
|
||||
|
||||
The format of the string is as follows:
|
||||
- The version of GLFW
|
||||
@ -157,7 +320,9 @@ The format of the string is as follows:
|
||||
For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
|
||||
back ends, the version string may look something like this:
|
||||
|
||||
3.0.0 Win32 WGL MinGW
|
||||
@code
|
||||
3.0.0 Win32 WGL MinGW
|
||||
@endcode
|
||||
|
||||
@note Do not parse the version string to find the GLFW library version. The
|
||||
@ref glfwGetVersion function provides the version of the library binary in
|
||||
|
@ -4,19 +4,39 @@
|
||||
|
||||
@section main_intro Introduction
|
||||
|
||||
GLFW is a free, Open Source, multi-platform library for opening a window,
|
||||
creating an OpenGL context and managing input. It is easy to integrate into
|
||||
existing applications and does not lay claim to the main loop.
|
||||
__GLFW__ is a free, Open Source, multi-platform library for creating windows
|
||||
with OpenGL or OpenGL ES contexts and receiving many kinds of input. It is easy
|
||||
to integrate into existing applications and does not lay claim to the main loop.
|
||||
|
||||
This is the documentation for version 3.1, which has [many new features](@ref news).
|
||||
This is the documentation for version 3.1, which adds many
|
||||
[new features](@ref news).
|
||||
|
||||
There is a [quick tutorial](@ref quick) for people new to GLFW, which shows how
|
||||
to write a small but complete program, and guides for
|
||||
[compiling GLFW](@ref compile) and
|
||||
[building programs that use GLFW](@ref build).
|
||||
@ref quick is a guide for those new to GLFW. It takes you through how to write
|
||||
a small but complete program. For people coming from GLFW 2, the @ref moving
|
||||
guide explains what has changed and how to update existing code to use the new
|
||||
API.
|
||||
|
||||
If you have used GLFW 2.x in the past, there is a
|
||||
[transition guide](@ref moving) that explains what has changed and how to update
|
||||
existing code to use the new API.
|
||||
There are guides for each of the various areas of the API.
|
||||
|
||||
- @ref intro
|
||||
- @ref window
|
||||
- @ref context
|
||||
- @ref monitor
|
||||
- @ref input
|
||||
|
||||
The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
|
||||
design, implementation and use of GLFW.
|
||||
|
||||
The [reference documentation](modules.html) provides more detailed information
|
||||
about specific functions.
|
||||
|
||||
Once you have written a program, see the @ref compile and @ref build guides.
|
||||
|
||||
Finally, the @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](http://www.glfw.org/download.html) and
|
||||
[GitHub repository](https://github.com/glfw/glfw).
|
||||
|
||||
*/
|
||||
|
@ -1,9 +1,20 @@
|
||||
/*!
|
||||
|
||||
@page monitor Multi-monitor guide
|
||||
@page monitor Monitor guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide introduces the monitor related functions of GLFW. There are also
|
||||
guides for the other areas of GLFW.
|
||||
|
||||
- @ref intro
|
||||
- @ref window
|
||||
- @ref context
|
||||
- @ref input
|
||||
|
||||
To see how GLFW views your monitor setup and its available video modes, run the
|
||||
`modes` test program.
|
||||
|
||||
|
||||
@section monitor_objects Monitor objects
|
||||
|
||||
@ -26,22 +37,44 @@ provide into the virtual desktop that spans them.
|
||||
|
||||
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.
|
||||
or menu bar. The returned structure is allocated and freed by GLFW.
|
||||
|
||||
@code
|
||||
GLFWmonitor* primary = glfwGetPrimaryMonitor();
|
||||
@endcode
|
||||
|
||||
You can retrieve all currently connected monitors with @ref glfwGetMonitors.
|
||||
The primary monitor is always the first monitor in the returned array.
|
||||
See the reference documentation for the lifetime of the returned array.
|
||||
|
||||
@code
|
||||
int count;
|
||||
GLFWmonitor** monitors = glfwGetMonitors(&count);
|
||||
@endcode
|
||||
|
||||
@note Monitors other than the primary monitor may be moved to a different index
|
||||
in the array if another monitor is disconnected.
|
||||
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 with @ref glfwSetMonitorCallback.
|
||||
|
||||
@code
|
||||
glfwSetMonitorCallback(monitor_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the handle for the monitor that has been
|
||||
connected or disconnected and a monitor action.
|
||||
|
||||
@code
|
||||
void monitor_callback(GLFWmonitor* monitor, int event)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
The action is one of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
|
||||
|
||||
|
||||
@section monitor_properties Monitor properties
|
||||
@ -52,15 +85,19 @@ Although GLFW generally does a good job at selecting a suitable video
|
||||
mode for you when you open a full screen window, it is sometimes useful to
|
||||
know exactly which modes are available on a certain system. For example,
|
||||
you may want to present the user with a list of video modes to select
|
||||
from. To get a list of available video modes, you can use the function
|
||||
@ref glfwGetVideoModes.
|
||||
from.
|
||||
|
||||
To get a list of available video modes, you can use the function @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.
|
||||
To get the current video mode of a monitor call @ref glfwGetVideoMode. See the
|
||||
reference documentation for the lifetime of the returned structure.
|
||||
|
||||
@code
|
||||
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
|
||||
@ -98,16 +135,17 @@ glfwGetMonitorPos(monitor, &xpos, &ypos);
|
||||
|
||||
@subsection monitor_name Human-readable name
|
||||
|
||||
The human-readable name of a monitor is returned by @ref glfwGetMonitorName.
|
||||
It is a regular C string using the UTF-8 encoding.
|
||||
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
|
||||
|
||||
@note Monitor names are not guaranteed to be unique. Two monitors of the same
|
||||
model and make may have the same name. Only the address of a monitor object is
|
||||
guaranteed to be unique.
|
||||
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_gamma Gamma ramp
|
||||
@ -136,10 +174,10 @@ 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.
|
||||
|
||||
@note It is recommended to use gamma ramps of size 256, as that is the size
|
||||
supported by virtually all graphics cards on all platforms.
|
||||
supported by all graphics cards on all platforms.
|
||||
|
||||
The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. The
|
||||
returned structure and its arrays are allocated and freed by GLFW.
|
||||
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);
|
||||
|
@ -38,7 +38,9 @@ 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 and C11, both of which are gaining traction.
|
||||
in both [C++11](http://en.cppreference.com/w/cpp/thread) and
|
||||
[C11](http://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
|
||||
@ -148,7 +150,7 @@ into [window hints](@ref window_hints), but as they have been given
|
||||
GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
|
||||
means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
|
||||
Unlike buffer swap, which acts on a single window, **glfwPollEvents** and
|
||||
**glfwWaitEvents** process events for all windows at once.
|
||||
__glfwWaitEvents__ process events for all windows at once.
|
||||
|
||||
@par Old basic main loop
|
||||
@code
|
||||
@ -412,10 +414,15 @@ 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. To
|
||||
release all resources allocated by GLFW, you should call @ref glfwTerminate
|
||||
yourself. Note that this destroys all windows not already destroyed with @ref
|
||||
glfwDestroyWindow, invalidating all window handles you may still have.
|
||||
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 may 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
|
||||
|
@ -10,17 +10,18 @@
|
||||
@subsection news_31_cursor Custom system cursor support
|
||||
|
||||
GLFW now supports creating and setting custom system cursors. They can be
|
||||
created with @ref glfwCreateCursor and set with @ref glfwSetCursor. Note that
|
||||
custom cursors are only visible in normal cursor mode.
|
||||
created with @ref glfwCreateCursor, set with @ref glfwSetCursor and destroyed
|
||||
with @ref glfwDestroyCursor. Custom cursors are only visible in normal cursor
|
||||
mode.
|
||||
|
||||
|
||||
@subsection news_31_drop File drop event support
|
||||
|
||||
GLFW now provides a callback for receiving the paths of files dropped onto GLFW
|
||||
windows. The callback is set with the @ref glfwSetDropCallback function.
|
||||
windows. The callback is set with @ref glfwSetDropCallback.
|
||||
|
||||
|
||||
@subsection news_31_emptyevent Empty event support
|
||||
@subsection news_31_emptyevent Main thread waking support
|
||||
|
||||
GLFW now provides the @ref glfwPostEmptyEvent function for posting an empty
|
||||
event from another thread to the main thread event queue, causing @ref
|
||||
@ -36,29 +37,43 @@ client area of a window, with @ref glfwGetWindowFrameSize.
|
||||
@subsection news_31_autoiconify Multi-monitor installation support
|
||||
|
||||
GLFW now supports disabling auto-iconification of full screen windows with
|
||||
[GLFW_AUTO_ICONIFY](@ref window_hints_wnd). This is intended for people
|
||||
building multi-monitor installations, where you need windows to stay in full
|
||||
screen despite losing focus.
|
||||
the [GLFW_AUTO_ICONIFY](@ref window_hints_wnd) window hint. This is intended
|
||||
for people building multi-monitor installations, where you need windows to stay
|
||||
in full screen despite losing focus.
|
||||
|
||||
|
||||
@subsection news_31_floating Floating windows
|
||||
|
||||
GLFW now supports floating windows, also called topmost or always on top, for
|
||||
easier debugging, with the `GLFW_FLOATING` window hint.
|
||||
easier debugging with the [GLFW_FLOATING](@ref window_hints_wnd) window hint.
|
||||
|
||||
|
||||
@subsection news_31_focused Initially unfocused windows
|
||||
|
||||
GLFW now supports preventing a windowed mode window from gaining input focus on
|
||||
creation, with the `GLFW_FOCUSED` window hint.
|
||||
creation, with the [GLFW_FOCUSED](@ref window_hints_wnd) window hint.
|
||||
|
||||
|
||||
@subsection news_31_charmods Character with modifiers callback
|
||||
|
||||
GLFW now provides a callback for character events with modifier key bits.
|
||||
Unlike the regular character callback, this will report character events that
|
||||
will not result in a character being input, for example if the Control key is
|
||||
held down.
|
||||
GLFW now provides a callback for character events with modifier key bits. The
|
||||
callback is set with @ref glfwSetCharModsCallback. Unlike the regular character
|
||||
callback, this will report character events that will not result in a character
|
||||
being input, for example if the Control key is held down.
|
||||
|
||||
|
||||
@subsection news_31_release Context release behavior support
|
||||
|
||||
GLFW now supports controlling whether the pipeline is flushed when a context is
|
||||
made non-current, with the
|
||||
[GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint, provided the
|
||||
machine supports the `GL_KHR_context_flush_control` extension.
|
||||
|
||||
|
||||
@subsection news_31_single Single buffering support
|
||||
|
||||
GLFW now supports the creation of single buffered windows, with the
|
||||
[GLFW_DOUBLEBUFFER](@ref window_hints_fb) window hint.
|
||||
|
||||
|
||||
@subsection news_31_egl Stable EGL support
|
||||
|
205
docs/quick.dox
205
docs/quick.dox
@ -1,23 +1,25 @@
|
||||
/*!
|
||||
|
||||
@page quick Getting started — A quick introduction
|
||||
@page quick Getting started
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This guide will show how to write simple OpenGL applications using GLFW 3. It
|
||||
will introduce a few of the most commonly used functions, but there are many
|
||||
others. To see detailed documentation on any GLFW function, just click on its
|
||||
name.
|
||||
This guide takes you through writing a simple application using GLFW 3. The
|
||||
application will create a window and OpenGL context, render a rotating triangle
|
||||
and exit when the user closes the window or presses Escape. This guide will
|
||||
introduce a few of the most commonly used functions, but there are many more.
|
||||
|
||||
This guide assumes no experience with earlier versions of GLFW. If you
|
||||
have used GLFW 2.x in the past, you should also read the
|
||||
[transition guide](@ref moving).
|
||||
have used GLFW 2 in the past, read the @ref moving guide, as some functions
|
||||
behave differently in GLFW 3.
|
||||
|
||||
|
||||
@section quick_include Including the GLFW header
|
||||
@section quick_steps Step by step
|
||||
|
||||
In the files of your program where you use OpenGL or GLFW, you need to include
|
||||
the GLFW 3 header file.
|
||||
@subsection quick_include Including the GLFW header
|
||||
|
||||
In the source files of your application where you use OpenGL or GLFW, you need
|
||||
to include the GLFW 3 header file.
|
||||
|
||||
@code
|
||||
#include <GLFW/glfw3.h>
|
||||
@ -54,40 +56,39 @@ inclusion of the GLFW header.
|
||||
@endcode
|
||||
|
||||
|
||||
@section quick_init_term Initializing and terminating GLFW
|
||||
@subsection quick_init_term Initializing and terminating GLFW
|
||||
|
||||
Before you can use most GLFW functions, the library must be initialized. This
|
||||
is done with @ref glfwInit, which returns non-zero if successful, or zero if an
|
||||
error occurred.
|
||||
Before you can use most GLFW functions, the library must be initialized. On
|
||||
successful initialization, non-zero is returned. If an error occurred, zero is
|
||||
returned.
|
||||
|
||||
@code
|
||||
if (!glfwInit())
|
||||
exit(EXIT_FAILURE);
|
||||
@endcode
|
||||
|
||||
When you are done using GLFW, typically at the very end of the program, you need
|
||||
to call @ref glfwTerminate.
|
||||
When you are done using GLFW, typically just before the application exits, you
|
||||
need to terminate GLFW.
|
||||
|
||||
@code
|
||||
glfwTerminate();
|
||||
@endcode
|
||||
|
||||
This destroys any remaining windows and releases any other resources allocated by
|
||||
GLFW. After this call, you must call @ref glfwInit again before using any GLFW
|
||||
GLFW. After this call, you must initialize GLFW again before using any GLFW
|
||||
functions that require it.
|
||||
|
||||
|
||||
@section quick_capture_error Setting an error callback
|
||||
@subsection quick_capture_error Setting an error callback
|
||||
|
||||
Most events are reported through callbacks, whether it's a key being pressed,
|
||||
a GLFW window being moved, or an error occurring. Callbacks are simply
|
||||
C functions (or C++ static methods) that are called by GLFW with arguments
|
||||
describing the event.
|
||||
|
||||
In case @ref glfwInit or any other GLFW function fails, an error is reported to
|
||||
the GLFW error callback. You can receive these reports by setting the error
|
||||
callback. The callback function itself should match the signature of @ref
|
||||
GLFWerrorfun. Here is a simple error callback that just prints the error
|
||||
In case a GLFW function fails, an error is reported to the GLFW error callback.
|
||||
You can receive these reports with an error callback. This function must have
|
||||
the signature below. This simple error callback just prints the error
|
||||
description to `stderr`.
|
||||
|
||||
@code
|
||||
@ -97,28 +98,28 @@ void error_callback(int error, const char* description)
|
||||
}
|
||||
@endcode
|
||||
|
||||
Setting the callback, so GLFW knows to call it, is done with @ref
|
||||
glfwSetErrorCallback. This is one of the few GLFW functions that may be called
|
||||
before @ref glfwInit, which lets you be notified of errors during
|
||||
initialization, so you should set it before you do anything else with GLFW.
|
||||
Callback functions must be set, so GLFW knows to call them. The function to set
|
||||
the error callback is one of the few GLFW functions that may be called before
|
||||
initialization, which lets you be notified of errors both during and after
|
||||
initialization.
|
||||
|
||||
@code
|
||||
glfwSetErrorCallback(error_callback);
|
||||
@endcode
|
||||
|
||||
|
||||
@section quick_create_window Creating a window and context
|
||||
@subsection quick_create_window Creating a window and context
|
||||
|
||||
The window (and its context) is created with @ref glfwCreateWindow, which
|
||||
returns a handle to the created window. For example, this creates a 640 by 480
|
||||
windowed mode window:
|
||||
The window and its OpenGL context are created with a single call, which returns
|
||||
a handle to the created combined window and context object. For example, this
|
||||
creates a 640 by 480 windowed mode window with an OpenGL context:
|
||||
|
||||
@code
|
||||
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
|
||||
@endcode
|
||||
|
||||
If window creation fails, `NULL` will be returned, so you need to check whether
|
||||
it did.
|
||||
If window or context creation fails, `NULL` will be returned, so it is necessary
|
||||
to check the return value.
|
||||
|
||||
@code
|
||||
if (!window)
|
||||
@ -128,24 +129,11 @@ if (!window)
|
||||
}
|
||||
@endcode
|
||||
|
||||
This handle is then passed to all window related functions, and is provided to
|
||||
you along with input events, so you know which window received the input.
|
||||
The window handle is passed to all window related functions and is provided to
|
||||
along to all window related callbacks, so they can tell which window received
|
||||
the event.
|
||||
|
||||
To create a full screen window, you need to specify which monitor the window
|
||||
should use. In most cases, the user's primary monitor is a good choice. You
|
||||
can get this with @ref glfwGetPrimaryMonitor. To make the above window
|
||||
full screen, just pass along the monitor handle:
|
||||
|
||||
@code
|
||||
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
|
||||
@endcode
|
||||
|
||||
Full screen windows cover the entire display area of a monitor, have no border
|
||||
or decorations, and change the monitor's resolution to the one most closely
|
||||
matching the requested window size.
|
||||
|
||||
When you are done with the window, destroy it with the @ref glfwDestroyWindow
|
||||
function.
|
||||
When a window is no longer needed, destroy it.
|
||||
|
||||
@code
|
||||
glfwDestroyWindow(window);
|
||||
@ -155,22 +143,22 @@ Once this function is called, no more events will be delivered for that window
|
||||
and its handle becomes invalid.
|
||||
|
||||
|
||||
@section quick_context_current Making the OpenGL context current
|
||||
@subsection quick_context_current Making the OpenGL context current
|
||||
|
||||
Before you can use the OpenGL API, it must have a current OpenGL context. You
|
||||
make a window's context current with @ref glfwMakeContextCurrent. It will then
|
||||
remain as the current context until you make another context current or until
|
||||
the window owning it is destroyed.
|
||||
make a window's context current.
|
||||
|
||||
@code
|
||||
glfwMakeContextCurrent(window);
|
||||
@endcode
|
||||
|
||||
The context will then remain as current until you make another context current
|
||||
or until the window owning the current context is destroyed.
|
||||
|
||||
@section quick_window_close Checking the window close flag
|
||||
|
||||
Each window has a flag indicating whether the window should be closed. This can
|
||||
be checked with @ref glfwWindowShouldClose.
|
||||
@subsection quick_window_close Checking the window close flag
|
||||
|
||||
Each window has a flag indicating whether the window should be closed.
|
||||
|
||||
When the user attempts to close the window, either by pressing the close widget
|
||||
in the title bar or using a key combination like Alt+F4, this flag is set to 1.
|
||||
@ -194,11 +182,11 @@ useful if you want to interpret other kinds of input as closing the window, like
|
||||
for example pressing the escape key.
|
||||
|
||||
|
||||
@section quick_key_input Receiving input events
|
||||
@subsection quick_key_input Receiving input events
|
||||
|
||||
Each window has a large number of callbacks that can be set to receive all the
|
||||
various kinds of events. To receive key press and release events, a
|
||||
[key callback](@ref GLFWkeyfun) is set using @ref glfwSetKeyCallback.
|
||||
various kinds of events. To receive key press and release events, create a key
|
||||
callback function.
|
||||
|
||||
@code
|
||||
static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
|
||||
@ -208,16 +196,21 @@ static void key_callback(GLFWwindow* window, int key, int scancode, int action,
|
||||
}
|
||||
@endcode
|
||||
|
||||
For event callbacks to actually be called when an event occurs, you need to
|
||||
process events as described below.
|
||||
The key callback, like other window related callbacks, are set per-window.
|
||||
|
||||
@code
|
||||
glfwSetKeyCallback(window, key_callback);
|
||||
@endcode
|
||||
|
||||
In order for event callbacks to be called when events occur, you need to process
|
||||
events as described below.
|
||||
|
||||
|
||||
@section quick_render Rendering with OpenGL
|
||||
@subsection quick_render Rendering with OpenGL
|
||||
|
||||
Once you have a current OpenGL context, you can use OpenGL normally. In this
|
||||
tutorial, a multi-colored rotating triangle will be rendered. The framebuffer
|
||||
size, needed by this example for `glViewport` and `glOrtho`, is retrieved with
|
||||
@ref glfwGetFramebufferSize.
|
||||
size needs to be retrieved for `glViewport`.
|
||||
|
||||
@code
|
||||
int width, height;
|
||||
@ -225,72 +218,80 @@ glfwGetFramebufferSize(window, &width, &height);
|
||||
glViewport(0, 0, width, height);
|
||||
@endcode
|
||||
|
||||
However, you can also set a framebuffer size callback using @ref
|
||||
You can also set a framebuffer size callback using @ref
|
||||
glfwSetFramebufferSizeCallback and call `glViewport` from there.
|
||||
|
||||
@code
|
||||
void framebuffer_size_callback(GLFWwindow* window, int width, int height)
|
||||
{
|
||||
glViewport(0, 0, width, height);
|
||||
}
|
||||
@endcode
|
||||
|
||||
@subsection quick_timer Reading the timer
|
||||
|
||||
@section quick_timer Reading the timer
|
||||
|
||||
For the triangle to rotate properly, a time source is needed. GLFW provides
|
||||
@ref glfwGetTime, which returns the number of seconds since @ref glfwInit as
|
||||
a `double`. The time source used is the most accurate on each platform and
|
||||
generally has micro- or nanosecond resolution.
|
||||
To create smooth animation, a time source is needed. GLFW provides a timer that
|
||||
returns the number of seconds since initialization. The time source used is the
|
||||
most accurate on each platform and generally has micro- or nanosecond
|
||||
resolution.
|
||||
|
||||
@code
|
||||
double time = glfwGetTime();
|
||||
@endcode
|
||||
|
||||
|
||||
@section quick_swap_buffers Swapping buffers
|
||||
@subsection quick_swap_buffers Swapping buffers
|
||||
|
||||
GLFW windows by default use double buffering. That means that you have two
|
||||
rendering buffers; a front buffer and a back buffer. The front buffer is the
|
||||
one being displayed and the back buffer the one you render to.
|
||||
GLFW windows by default use double buffering. That means that each window has
|
||||
two rendering buffers; a front buffer and a back buffer. The front buffer is
|
||||
the one being displayed and the back buffer the one you render to.
|
||||
|
||||
When the entire frame has been rendered, it is time to swap the back and the
|
||||
front buffers in order to display the rendered frame, and begin rendering a new
|
||||
frame. This is done with @ref glfwSwapBuffers.
|
||||
When the entire frame has been rendered, the buffers need to be swapped with one
|
||||
another, so the back buffer becomes the front buffer and vice versa.
|
||||
|
||||
@code
|
||||
glfwSwapBuffers(window);
|
||||
@endcode
|
||||
|
||||
The swap interval indicates how many frames to wait until swapping the buffers,
|
||||
commonly known as *vsync*. By default, the swap interval is zero, meaning
|
||||
buffer swapping will occur immediately. On fast machines, many of those frames
|
||||
will never be seen, as the screen is still only updated typically 60-75 times
|
||||
per second, so this wastes a lot of CPU and GPU cycles.
|
||||
|
||||
@section quick_process_events Processing events
|
||||
Also, because the buffers will be swapped in the middle the screen update,
|
||||
leading to [screen tearing](https://en.wikipedia.org/wiki/Screen_tearing).
|
||||
|
||||
For these reasons, applications will typically want to set the swap interval to
|
||||
one. It can be set to higher values, but this is usually not recommended,
|
||||
because of the input latency it leads to.
|
||||
|
||||
@code
|
||||
glfwSwapInterval(1);
|
||||
@endcode
|
||||
|
||||
This function acts on the current context and will fail unless a context is
|
||||
current.
|
||||
|
||||
|
||||
@subsection quick_process_events Processing events
|
||||
|
||||
GLFW needs to communicate regularly with the window system both in order to
|
||||
receive events and to show that it hasn't locked up. Event processing must be
|
||||
done regularly and is normally done each frame before rendering but after buffer
|
||||
swap.
|
||||
receive events and to show that the application hasn't locked up. Event
|
||||
processing must be done regularly while you have visible windows and is normally
|
||||
done each frame after buffer swapping.
|
||||
|
||||
There are two ways to process pending events. @ref glfwPollEvents processes
|
||||
only those events that have already been received and then returns immediately.
|
||||
This is the best choice when rendering continually, like most games do.
|
||||
There are two methods for processing pending events; polling and waiting. This
|
||||
example will use event polling, which processes only those events that have
|
||||
already been received and then returns immediately.
|
||||
|
||||
@code
|
||||
glfwPollEvents();
|
||||
@endcode
|
||||
|
||||
If instead you only need to update your rendering once you have received new
|
||||
input, @ref glfwWaitEvents is a better choice. It waits until at least one
|
||||
event has been received, putting the thread to sleep in the meantime, and then
|
||||
processes all received events just like @ref glfwPollEvents does. This saves
|
||||
a great deal of CPU cycles and is useful for, for example, many kinds of editing
|
||||
tools.
|
||||
|
||||
@code
|
||||
glfwWaitEvents();
|
||||
@endcode
|
||||
This is the best choice when rendering continually, like most games do. If
|
||||
instead you only need to update your rendering once you have received new input,
|
||||
@ref glfwWaitEvents is a better choice. It waits until at least one event has
|
||||
been received, putting the thread to sleep in the meantime, and then processes
|
||||
all received events. This saves a great deal of CPU cycles and is useful for,
|
||||
for example, many kinds of editing tools.
|
||||
|
||||
|
||||
@section quick_example Putting it together: A simple application
|
||||
@section quick_example Putting it together
|
||||
|
||||
Now that you know how to initialize GLFW, create a window and poll for
|
||||
keyboard input, it's possible to create a simple program.
|
||||
|
91
docs/rift.dox
Normal file
91
docs/rift.dox
Normal file
@ -0,0 +1,91 @@
|
||||
/*!
|
||||
|
||||
@page rift Oculus Rift guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
GLFW has no explicit support for the Oculus Rift, but
|
||||
|
||||
This guide requires you to use the [native API](@ref native) and assumes
|
||||
a certain level of proficiency with system level APIs and the compiler
|
||||
toolchain.
|
||||
|
||||
|
||||
@section rift_init Initializing libOVR and GLFW
|
||||
|
||||
libOVR needs to be initialized before GLFW. This means calling
|
||||
`ovr_Initialize`, `ovrHmd_Create` and `ovrHmd_ConfigureTracking` before @ref
|
||||
glfwInit. Similarly, libOVR must be shut down after GLFW. This means calling
|
||||
`ovrHmd_Destroy` and `ovr_Shutdown` after @ref glfwTerminate.
|
||||
|
||||
|
||||
@section rift_extend Extend Desktop mode
|
||||
|
||||
@subsection rift_extend_detect Detecting a Rift with GLFW
|
||||
|
||||
If you have an actual Rift connected to your machine you can deduce which GLFW
|
||||
monitor it corresponds to. Doing this requires you to use the
|
||||
[native API](@ref native).
|
||||
|
||||
|
||||
@subsubsection rift_extend_detect_win32 Detecting a Rift on Windows
|
||||
|
||||
To identify which monitor corresponds to the Rift, compare Win32 display device
|
||||
names. The display device name of a GLFW monitor is returned by @ref
|
||||
glfwGetWin32Monitor and the display device name of the detected Rift is stored
|
||||
in the `DisplayDeviceName` member of `ovrHmdDesc`.
|
||||
|
||||
@code
|
||||
int i, count;
|
||||
GLFWmonitor* monitor = NULL;
|
||||
GLFWmonitor** monitors = glfwGetMonitors(&count);
|
||||
|
||||
for (i = 0; i < count; i++)
|
||||
{
|
||||
if (strcmp(glfwGetWin32Monitor(monitors[i]), hmd->DisplayDeviceName) == 0)
|
||||
{
|
||||
monitor = monitors[i];
|
||||
break;
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@subsubsection rift_extend_detect_osx Detecting a Rift on OS X
|
||||
|
||||
To identify which monitor corresponds to the Rift, compare OS X display IDs.
|
||||
The display ID of a GLFW monitor is returned by @ref glfwGetCocoaMonitor and the
|
||||
display ID of the detected Rift is stored in the `DisplayId` member of
|
||||
`ovrHmdDesc`.
|
||||
|
||||
@code
|
||||
int i, count;
|
||||
GLFWmonitor* monitor = NULL;
|
||||
GLFWmonitor** monitors = glfwGetMonitors(&count);
|
||||
|
||||
for (i = 0; i < count; i++)
|
||||
{
|
||||
if (glfwGetCocoaMonitor(monitors[i]) == hmd->DisplayId)
|
||||
{
|
||||
monitor = monitors[i];
|
||||
break;
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@subsubsection rift_extend_detect_x11 Detecting a Rift on X11
|
||||
|
||||
At the time of writing, the 0.4 Rift SDK does not yet support X11.
|
||||
|
||||
|
||||
@subsection rift_extend_create Creating a window and context
|
||||
|
||||
LOL create.
|
||||
|
||||
|
||||
@section rift_direct Direct HMD mode
|
||||
|
||||
LOL direct.
|
||||
|
||||
*/
|
352
docs/spaces.svg
Normal file
352
docs/spaces.svg
Normal file
@ -0,0 +1,352 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!-- Created with Inkscape (http://www.inkscape.org/) -->
|
||||
|
||||
<svg
|
||||
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
||||
xmlns:cc="http://creativecommons.org/ns#"
|
||||
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||
width="688.48718"
|
||||
height="327.98221"
|
||||
id="svg2"
|
||||
version="1.1"
|
||||
inkscape:version="0.48.4 r9939"
|
||||
sodipodi:docname="spaces.svg">
|
||||
<defs
|
||||
id="defs4">
|
||||
<marker
|
||||
inkscape:stockid="Arrow2Lend"
|
||||
orient="auto"
|
||||
refY="0.0"
|
||||
refX="0.0"
|
||||
id="Arrow2Lend"
|
||||
style="overflow:visible;">
|
||||
<path
|
||||
id="path3888"
|
||||
style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
|
||||
d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
|
||||
transform="scale(1.1) rotate(180) translate(1,0)" />
|
||||
</marker>
|
||||
</defs>
|
||||
<sodipodi:namedview
|
||||
id="base"
|
||||
pagecolor="#ffffff"
|
||||
bordercolor="#666666"
|
||||
borderopacity="1.0"
|
||||
inkscape:pageopacity="0.0"
|
||||
inkscape:pageshadow="2"
|
||||
inkscape:zoom="8"
|
||||
inkscape:cx="273.7909"
|
||||
inkscape:cy="186.31212"
|
||||
inkscape:document-units="px"
|
||||
inkscape:current-layer="layer1"
|
||||
showgrid="false"
|
||||
inkscape:window-width="1920"
|
||||
inkscape:window-height="1021"
|
||||
inkscape:window-x="0"
|
||||
inkscape:window-y="30"
|
||||
inkscape:window-maximized="1"
|
||||
fit-margin-top="0"
|
||||
fit-margin-left="0"
|
||||
fit-margin-right="0"
|
||||
fit-margin-bottom="0"
|
||||
units="px"
|
||||
showborder="false"
|
||||
inkscape:showpageshadow="false" />
|
||||
<metadata
|
||||
id="metadata7">
|
||||
<rdf:RDF>
|
||||
<cc:Work
|
||||
rdf:about="">
|
||||
<dc:format>image/svg+xml</dc:format>
|
||||
<dc:type
|
||||
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
|
||||
<dc:title></dc:title>
|
||||
</cc:Work>
|
||||
</rdf:RDF>
|
||||
</metadata>
|
||||
<g
|
||||
inkscape:label="Layer 1"
|
||||
inkscape:groupmode="layer"
|
||||
id="layer1"
|
||||
transform="translate(-12.627039,-339.86462)">
|
||||
<rect
|
||||
style="fill:#ffffff;fill-opacity:1;stroke:#0000ff;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:3,3;stroke-dashoffset:0"
|
||||
id="rect2985"
|
||||
width="687.36469"
|
||||
height="326.85971"
|
||||
x="13.188287"
|
||||
y="340.42587"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113" />
|
||||
<rect
|
||||
style="fill:#f3fff3;fill-opacity:1;stroke:#00b800;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
|
||||
id="rect3757"
|
||||
width="318.05698"
|
||||
height="277.04684"
|
||||
x="38.315689"
|
||||
y="366.05841"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113" />
|
||||
<rect
|
||||
style="fill:#f3fff3;fill-opacity:1;stroke:#00b800;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
|
||||
id="rect3767"
|
||||
width="319.01456"
|
||||
height="198.09369"
|
||||
x="356.36722"
|
||||
y="366.01291"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113" />
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="363.40543"
|
||||
y="381.11581"
|
||||
id="text3769"
|
||||
sodipodi:linespacing="125%"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113"><tspan
|
||||
sodipodi:role="line"
|
||||
x="363.40543"
|
||||
y="381.11581"
|
||||
id="tspan3785"
|
||||
style="font-size:10px;text-align:start;text-anchor:start">Primary monitor position</tspan></text>
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#00b800;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="236.43106"
|
||||
y="633.68793"
|
||||
id="text3773"
|
||||
sodipodi:linespacing="125%"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3775"
|
||||
x="236.43106"
|
||||
y="633.68793">Secondary Monitor</tspan></text>
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#00b800;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="572.90869"
|
||||
y="555.30212"
|
||||
id="text3777"
|
||||
sodipodi:linespacing="125%"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3779"
|
||||
x="572.90869"
|
||||
y="555.30212">Primary Monitor</tspan></text>
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#0000ff;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="609.20776"
|
||||
y="657.77118"
|
||||
id="text3781"
|
||||
sodipodi:linespacing="125%"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3783"
|
||||
x="609.20776"
|
||||
y="657.77118">Virtual Screen</tspan></text>
|
||||
<rect
|
||||
style="fill:#b8b8b8;fill-opacity:1;stroke:#b8b8b8;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
|
||||
id="rect5577"
|
||||
width="173.25098"
|
||||
height="141.43118"
|
||||
x="157.75581"
|
||||
y="436.97159" />
|
||||
<rect
|
||||
style="fill:#ededed;fill-opacity:1;stroke:#ededed;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
|
||||
id="rect3789"
|
||||
width="168.99611"
|
||||
height="136.87178"
|
||||
x="159.87543"
|
||||
y="439.39697"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113" />
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#454545;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="273.8884"
|
||||
y="567.73486"
|
||||
id="text3791"
|
||||
sodipodi:linespacing="125%"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3793"
|
||||
x="273.8884"
|
||||
y="567.73486">Window</tspan></text>
|
||||
<rect
|
||||
y="439.39581"
|
||||
x="159.87428"
|
||||
height="8.8251209"
|
||||
width="168.99841"
|
||||
id="rect3795"
|
||||
style="fill:#7b7bff;fill-opacity:1;stroke:#7b7bff;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113" />
|
||||
<path
|
||||
sodipodi:type="arc"
|
||||
style="fill:#000000;fill-opacity:1;stroke:none"
|
||||
id="path3797"
|
||||
sodipodi:cx="352.54324"
|
||||
sodipodi:cy="373.03461"
|
||||
sodipodi:rx="2.5253813"
|
||||
sodipodi:ry="2.5253813"
|
||||
d="m 355.06862,373.03461 c 0,1.39473 -1.13065,2.52538 -2.52538,2.52538 -1.39473,0 -2.52538,-1.13065 -2.52538,-2.52538 0,-1.39473 1.13065,-2.52538 2.52538,-2.52538 1.39473,0 2.52538,1.13065 2.52538,2.52538 z"
|
||||
transform="matrix(0.66107369,0,0,0.66107369,123.32145,119.41326)"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113" />
|
||||
<path
|
||||
transform="matrix(0.66107369,0,0,0.66107369,-194.73594,119.44704)"
|
||||
d="m 355.06862,373.03461 c 0,1.39473 -1.13065,2.52538 -2.52538,2.52538 -1.39473,0 -2.52538,-1.13065 -2.52538,-2.52538 0,-1.39473 1.13065,-2.52538 2.52538,-2.52538 1.39473,0 2.52538,1.13065 2.52538,2.52538 z"
|
||||
sodipodi:ry="2.5253813"
|
||||
sodipodi:rx="2.5253813"
|
||||
sodipodi:cy="373.03461"
|
||||
sodipodi:cx="352.54324"
|
||||
id="path3799"
|
||||
style="fill:#000000;fill-opacity:1;stroke:none"
|
||||
sodipodi:type="arc"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113" />
|
||||
<path
|
||||
sodipodi:type="arc"
|
||||
style="fill:#000000;fill-opacity:1;stroke:none"
|
||||
id="path3801"
|
||||
sodipodi:cx="352.54324"
|
||||
sodipodi:cy="373.03461"
|
||||
sodipodi:rx="2.5253813"
|
||||
sodipodi:ry="2.5253813"
|
||||
d="m 355.06862,373.03461 a 2.5253813,2.5253813 0 1 1 -5.05076,0 2.5253813,2.5253813 0 1 1 5.05076,0 z"
|
||||
transform="matrix(0.66107369,0,0,0.66107369,-73.218648,201.61091)"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113" />
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="21.213203"
|
||||
y="340.20465"
|
||||
id="text3803"
|
||||
sodipodi:linespacing="125%"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3805"
|
||||
x="21.213203"
|
||||
y="340.20465" /></text>
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="70.847862"
|
||||
y="462.84561"
|
||||
id="text3807"
|
||||
sodipodi:linespacing="125%"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113"><tspan
|
||||
sodipodi:role="line"
|
||||
x="70.847862"
|
||||
y="462.84561"
|
||||
style="font-size:10px"
|
||||
id="tspan3815">Window position</tspan></text>
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="44.446709"
|
||||
y="381.11581"
|
||||
id="text3817"
|
||||
sodipodi:linespacing="125%"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3819"
|
||||
x="44.446709"
|
||||
y="381.11581"
|
||||
style="font-size:10px">Secondary monitor position</tspan></text>
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="165.78685"
|
||||
y="462.84561"
|
||||
id="text3826"
|
||||
sodipodi:linespacing="125%"
|
||||
inkscape:export-filename="/home/elmindreda/projects/glfw/glfw/docs/spaces.png"
|
||||
inkscape:export-xdpi="109.89113"
|
||||
inkscape:export-ydpi="109.89113"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3828"
|
||||
x="165.78685"
|
||||
y="462.84561"
|
||||
style="font-size:10px">Client area origin</tspan></text>
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="364.30875"
|
||||
y="356.71783"
|
||||
id="text3017"
|
||||
sodipodi:linespacing="125%"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3019"
|
||||
x="364.30875"
|
||||
y="356.71783"
|
||||
style="font-size:10px">Virtual screen origin</tspan></text>
|
||||
<path
|
||||
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
|
||||
d="m 343.73692,26.224389 0.01,294.941191"
|
||||
id="path3861"
|
||||
inkscape:connector-curvature="0"
|
||||
sodipodi:nodetypes="cc"
|
||||
transform="translate(12.627039,339.86462)" />
|
||||
<path
|
||||
sodipodi:nodetypes="cc"
|
||||
inkscape:connector-curvature="0"
|
||||
id="path4307"
|
||||
d="m 356.48533,366.00457 336.31202,-0.0196"
|
||||
style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend);stroke-miterlimit:4;stroke-dasharray:none" />
|
||||
<path
|
||||
sodipodi:nodetypes="cc"
|
||||
inkscape:connector-curvature="0"
|
||||
id="path4309"
|
||||
d="m 159.89916,447.6257 -0.0625,145.00422"
|
||||
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)" />
|
||||
<path
|
||||
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
|
||||
d="m 160.03997,448.23877 184.95568,-0.0159"
|
||||
id="path4493"
|
||||
inkscape:connector-curvature="0"
|
||||
sodipodi:nodetypes="cc" />
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
|
||||
x="228.4128"
|
||||
y="445.67239"
|
||||
id="text4495"
|
||||
sodipodi:linespacing="125%"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan4497"
|
||||
x="228.4128"
|
||||
y="445.67239"
|
||||
style="font-size:5px;fill:#ffffff;fill-opacity:1">Window Title</tspan></text>
|
||||
</g>
|
||||
</svg>
|
After Width: | Height: | Size: 14 KiB |
625
docs/window.dox
625
docs/window.dox
@ -1,6 +1,6 @@
|
||||
/*!
|
||||
|
||||
@page window Window handling guide
|
||||
@page window Window guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
@ -8,8 +8,16 @@ The primary purpose of GLFW is to provide a simple interface to window
|
||||
management and OpenGL and OpenGL ES context creation. GLFW supports multiple
|
||||
windows, which can be either a normal desktop window or a full screen window.
|
||||
|
||||
This guide introduces the window related functions of GLFW. There are also
|
||||
guides for the other areas of GLFW.
|
||||
|
||||
@section window_object Window handles
|
||||
- @ref intro
|
||||
- @ref context
|
||||
- @ref monitor
|
||||
- @ref input
|
||||
|
||||
|
||||
@section window_object Window objects
|
||||
|
||||
The @ref GLFWwindow object encapsulates both a window and a context. They are
|
||||
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
|
||||
@ -17,30 +25,34 @@ created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
|
||||
linked, the object pointer is used as both a context and window handle.
|
||||
|
||||
|
||||
@section window_creation Window creation
|
||||
@subsection window_creation Window creation
|
||||
|
||||
The window and its context are created with @ref glfwCreateWindow, which
|
||||
returns a handle to the created window object. For example, this creates a 640
|
||||
by 480 windowed mode window:
|
||||
A window and its OpenGL or OpenGL ES context are created with @ref
|
||||
glfwCreateWindow, which returns a handle to the created window object. For
|
||||
example, this creates a 640 by 480 windowed mode window:
|
||||
|
||||
@code
|
||||
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
|
||||
@endcode
|
||||
|
||||
If window creation fails, `NULL` will be returned, so it is necessary to check
|
||||
the return value.
|
||||
|
||||
@code
|
||||
if (!window)
|
||||
{
|
||||
// Handle window creation failure
|
||||
}
|
||||
@endcode
|
||||
|
||||
If window creation fails, `NULL` will be returned, so you need to check the
|
||||
return value. If creation failed, an error will have been reported to the error
|
||||
callback.
|
||||
|
||||
This handle is then passed to all window related functions, and is provided to
|
||||
you along with input events, so you know which window received the input.
|
||||
The window handle is passed to all window related functions and is provided to
|
||||
along with all input events, so event handlers can tell which window received
|
||||
the event.
|
||||
|
||||
To create a full screen window, you need to specify which monitor the window
|
||||
should use. In most cases, the user's primary monitor is a good choice. For
|
||||
more information about monitors, see the @ref monitor.
|
||||
should use. In most cases, the user's primary monitor is a good choice. You
|
||||
can get this with @ref glfwGetPrimaryMonitor. For more information about
|
||||
monitors, see the @ref monitor.
|
||||
|
||||
@code
|
||||
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
|
||||
@ -54,28 +66,25 @@ For more control over how the window and its context are created, see @ref
|
||||
window_hints below.
|
||||
|
||||
|
||||
@section window_destruction Window destruction
|
||||
@subsection window_destruction Window destruction
|
||||
|
||||
When you are done with the window, destroy it with the @ref glfwDestroyWindow
|
||||
function.
|
||||
When a window is no longer needed, destroy it with @ref glfwDestroyWindow.
|
||||
|
||||
@code
|
||||
glfwDestroyWindow(window);
|
||||
@endcode
|
||||
|
||||
Once this function is called, no more events will be delivered for that window
|
||||
and its handle becomes invalid.
|
||||
Window destruction always succeeds. Before the actual destruction, all
|
||||
callbacks are removed so no further events will be delivered for the window.
|
||||
|
||||
When a full screen window is destroyed, the original video mode of its monitor
|
||||
is restored, but the gamma ramp is left untouched.
|
||||
|
||||
All windows remaining at the time @ref glfwTerminate is called are destroyed as
|
||||
well.
|
||||
|
||||
|
||||
@section window_userptr Window user pointer
|
||||
|
||||
Each window has a user pointer that can be set with @ref
|
||||
glfwSetWindowUserPointer and fetched with @ref glfwGetWindowUserPointer. This
|
||||
can be used for any purpose you need and will not be modified by GLFW throughout
|
||||
the life-time of the window.
|
||||
|
||||
|
||||
@section window_hints Window creation hints
|
||||
@subsection window_hints Window creation hints
|
||||
|
||||
There are a number of hints that can be set before the creation of a window and
|
||||
context. Some affect the window itself, others affect the framebuffer or
|
||||
@ -87,7 +96,7 @@ Note that hints need to be set *before* the creation of the window and context
|
||||
you wish to have the specified attributes.
|
||||
|
||||
|
||||
@subsection window_hints_hard Hard and soft constraints
|
||||
@subsubsection window_hints_hard Hard and soft constraints
|
||||
|
||||
Some window hints are hard constraints. These must match the available
|
||||
capabilities *exactly* for window and context creation to succeed. Hints
|
||||
@ -107,126 +116,127 @@ context, but are ignored when requesting an OpenGL ES context:
|
||||
- `GLFW_OPENGL_PROFILE`
|
||||
|
||||
|
||||
@subsection window_hints_wnd Window related hints
|
||||
@subsubsection window_hints_wnd Window related hints
|
||||
|
||||
The `GLFW_RESIZABLE` hint specifies whether the (windowed mode) window will be
|
||||
resizable *by the user*. The window will still be resizable using the @ref
|
||||
`GLFW_RESIZABLE` specifies whether the (windowed mode) window will be resizable
|
||||
*by the user*. The window will still be resizable using the @ref
|
||||
glfwSetWindowSize function. This hint is ignored for full screen windows.
|
||||
|
||||
The `GLFW_VISIBLE` hint specifies whether the (windowed mode) window will be
|
||||
initially visible. This hint is ignored for full screen windows.
|
||||
`GLFW_VISIBLE` specifies whether the (windowed mode) window will be initially
|
||||
visible. This hint is ignored for full screen windows.
|
||||
|
||||
The `GLFW_DECORATED` hint specifies whether the (windowed mode) window will have
|
||||
window decorations such as a border, a close widget, etc. This hint is ignored
|
||||
for full screen windows. Note that even though a window may lack a close
|
||||
widget, it is usually still possible for the user to generate close events.
|
||||
`GLFW_DECORATED` specifies whether the (windowed mode) window will have window
|
||||
decorations such as a border, a close widget, etc. This hint is ignored for
|
||||
full screen windows. Note that even though a window may lack a close widget, it
|
||||
is usually still possible for the user to generate close events.
|
||||
|
||||
The `GLFW_FOCUSED` hint specifies whether the (windowed mode) window will be
|
||||
given input focus when created. This hint is ignored for full screen and
|
||||
initially hidden windows.
|
||||
`GLFW_FOCUSED` specifies whether the (windowed mode) window will be given input
|
||||
focus when created. This hint is ignored for full screen and initially hidden
|
||||
windows.
|
||||
|
||||
The `GLFW_AUTO_ICONIFY` hint specifies whether the (full screen) window
|
||||
will automatically iconify and restore the previous video mode on focus loss.
|
||||
This hint is ignored for windowed mode windows.
|
||||
`GLFW_AUTO_ICONIFY` specifies whether the (full screen) window will
|
||||
automatically iconify and restore the previous video mode on focus loss. This
|
||||
hint is ignored for windowed mode windows.
|
||||
|
||||
The `GLFW_FLOATING` hint specifies whether the window will be floating above
|
||||
other regular windows, also called topmost or always-on-top. This is intended
|
||||
`GLFW_FLOATING` specifies whether the window will be floating above other
|
||||
regular windows, also called topmost or always-on-top. This is intended
|
||||
primarily for debugging purposes and cannot be used to implement proper full
|
||||
screen windows. This hint is ignored for full screen windows.
|
||||
|
||||
|
||||
@subsection window_hints_fb Framebuffer related hints
|
||||
@subsubsection window_hints_fb Framebuffer related hints
|
||||
|
||||
The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
|
||||
`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` hints specify the desired bit
|
||||
depths of the various components of the default framebuffer. `GLFW_DONT_CARE`
|
||||
means the application has no preference.
|
||||
|
||||
The `GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS`
|
||||
and `GLFW_ACCUM_ALPHA_BITS` hints specify the desired bit depths of the
|
||||
various components of the accumulation buffer. `GLFW_DONT_CARE` means the
|
||||
`GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
|
||||
`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` specify the desired bit depths of the
|
||||
various components of the default framebuffer. `GLFW_DONT_CARE` means the
|
||||
application has no preference.
|
||||
|
||||
`GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` and
|
||||
`GLFW_ACCUM_ALPHA_BITS` specify the desired bit depths of the various components
|
||||
of the accumulation buffer. `GLFW_DONT_CARE` means the application has no
|
||||
preference.
|
||||
|
||||
@note Accumulation buffers are a legacy OpenGL feature and should not be used in
|
||||
new code.
|
||||
|
||||
The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary
|
||||
buffers. `GLFW_DONT_CARE` means the application has no preference.
|
||||
`GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers.
|
||||
`GLFW_DONT_CARE` means the application has no preference.
|
||||
|
||||
@note Auxiliary buffers are a legacy OpenGL feature and should not be used in
|
||||
new code.
|
||||
|
||||
The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering. This is
|
||||
a hard constraint.
|
||||
|
||||
The `GLFW_SAMPLES` hint specifies the desired number of samples to use for
|
||||
multisampling. Zero disables multisampling. `GLFW_DONT_CARE` means the
|
||||
application has no preference.
|
||||
|
||||
The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be
|
||||
sRGB capable.
|
||||
|
||||
The `GLFW_DOUBLEBUFFER` hint specifies whether the framebuffer should be double
|
||||
buffered. You nearly always want to use double buffering. This is a hard
|
||||
`GLFW_STEREO` specifies whether to use stereoscopic rendering. This is a hard
|
||||
constraint.
|
||||
|
||||
The `GLFW_REFRESH_RATE` hint specifies the desired refresh rate for full screen
|
||||
windows. If set to zero, the highest available refresh rate will be used. This
|
||||
hint is ignored for windowed mode windows.
|
||||
`GLFW_SAMPLES` specifies the desired number of samples to use for multisampling.
|
||||
Zero disables multisampling. `GLFW_DONT_CARE` means the application has no
|
||||
preference.
|
||||
|
||||
`GLFW_SRGB_CAPABLE` specifies whether the framebuffer should be sRGB capable.
|
||||
|
||||
`GLFW_DOUBLEBUFFER` specifies whether the framebuffer should be double buffered.
|
||||
You nearly always want to use double buffering. This is a hard constraint.
|
||||
|
||||
|
||||
@subsection window_hints_ctx Context related hints
|
||||
@subsubsection window_hints_mtr Monitor related hints
|
||||
|
||||
The `GLFW_CLIENT_API` hint specifies which client API to create the context
|
||||
for. Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`. This is
|
||||
a hard constraint.
|
||||
`GLFW_REFRESH_RATE` specifies the desired refresh rate for full screen windows.
|
||||
If set to zero, the highest available refresh rate will be used. This hint is
|
||||
ignored for windowed mode windows.
|
||||
|
||||
The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints
|
||||
specify the client API version that the created context must be compatible
|
||||
with.
|
||||
|
||||
For OpenGL, these hints are *not* hard constraints, as they don't have to
|
||||
match exactly, but @ref glfwCreateWindow will still fail if the resulting
|
||||
OpenGL version is less than the one requested. It is therefore perfectly
|
||||
safe to use the default of version 1.0 for legacy code and you may still
|
||||
get backwards-compatible contexts of version 3.0 and above when available.
|
||||
@subsubsection window_hints_ctx Context related hints
|
||||
|
||||
`GLFW_CLIENT_API` specifies which client API to create the context for.
|
||||
Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`. This is a hard
|
||||
constraint.
|
||||
|
||||
`GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client
|
||||
API version that the created context must be compatible with.
|
||||
|
||||
For OpenGL, `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
|
||||
not hard constraints, as they don't have to match exactly, but @ref
|
||||
glfwCreateWindow will still fail if the resulting OpenGL version is less than
|
||||
the one requested. It is therefore perfectly safe to use the default of version
|
||||
1.0 for legacy code and you may still get backwards-compatible contexts of
|
||||
version 3.0 and above when available.
|
||||
|
||||
While there is no way to ask the driver for a context of the highest supported
|
||||
version, most drivers provide this when you ask GLFW for a version
|
||||
1.0 context.
|
||||
version, most drivers provide this when you ask GLFW for a version 1.0 context.
|
||||
|
||||
For OpenGL ES, these hints are hard constraints.
|
||||
For OpenGL ES, `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
|
||||
hard constraints to the extent that OpenGL ES 1.x cannot be returned if 2.0 or
|
||||
later was requested, and vice versa. This is because OpenGL ES 3.0 and later
|
||||
versions are backward compatible, but OpenGL ES 2.0 is not.
|
||||
|
||||
If an OpenGL context is requested, the `GLFW_OPENGL_FORWARD_COMPAT` hint
|
||||
specifies whether the OpenGL context should be forward-compatible, i.e. one
|
||||
where all functionality deprecated in the requested version of OpenGL is
|
||||
removed. This may only be used if the requested OpenGL version is 3.0 or
|
||||
above. If another client API is requested, this hint is ignored.
|
||||
`GLFW_OPENGL_FORWARD_COMPAT` specifies whether the OpenGL context should be
|
||||
forward-compatible, i.e. one where all functionality deprecated in the requested
|
||||
version of OpenGL is removed. This may only be used if the requested OpenGL
|
||||
version is 3.0 or above. If OpenGL S is requested, this hint is ignored.
|
||||
|
||||
@note Forward-compatibility is described in detail in the
|
||||
Forward-compatibility is described in detail in the
|
||||
[OpenGL Reference Manual](https://www.opengl.org/registry/).
|
||||
|
||||
If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
|
||||
specifies whether to create a debug OpenGL context, which may have
|
||||
additional error and performance issue reporting functionality. If another
|
||||
client API is requested, this hint is ignored.
|
||||
`GLFW_OPENGL_DEBUG_CONTEXT` specifies whether to create a debug OpenGL context,
|
||||
which may have additional error and performance issue reporting functionality.
|
||||
If OpenGL ES is requested, this hint is ignored.
|
||||
|
||||
If an OpenGL context is requested, the `GLFW_OPENGL_PROFILE` hint specifies
|
||||
which OpenGL profile to create the context for. Possible values are one of
|
||||
`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`, or
|
||||
`GLFW_OPENGL_ANY_PROFILE` to not request a specific profile. If requesting
|
||||
an OpenGL version below 3.2, `GLFW_OPENGL_ANY_PROFILE` must be used. If
|
||||
another client API is requested, this hint is ignored.
|
||||
`GLFW_OPENGL_PROFILE` specifies which OpenGL profile to create the context for.
|
||||
Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or
|
||||
`GLFW_OPENGL_COMPAT_PROFILE`, or `GLFW_OPENGL_ANY_PROFILE` to not request
|
||||
a specific profile. If requesting an OpenGL version below 3.2,
|
||||
`GLFW_OPENGL_ANY_PROFILE` must be used. If another OpenGL ES is requested,
|
||||
this hint is ignored.
|
||||
|
||||
@note OpenGL profiles are described in detail in the
|
||||
OpenGL profiles are described in detail in the
|
||||
[OpenGL Reference Manual](https://www.opengl.org/registry/).
|
||||
|
||||
The `GLFW_CONTEXT_ROBUSTNESS` hint specifies the robustness strategy to be
|
||||
used by the context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or
|
||||
`GLFW_CONTEXT_ROBUSTNESS` specifies the robustness strategy to be used by the
|
||||
context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or
|
||||
`GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
|
||||
a robustness strategy.
|
||||
|
||||
The `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint specifies the release behavior to be
|
||||
`GLFW_CONTEXT_RELEASE_BEHAVIOR` specifies the release behavior to be
|
||||
used by the context. Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`,
|
||||
`GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`. If the
|
||||
behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context
|
||||
@ -235,48 +245,65 @@ the pipeline will be flushed whenever the context is released from being the
|
||||
current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
|
||||
not be flushed on release.
|
||||
|
||||
@note Context release behaviors are described in detail by the
|
||||
Context release behaviors are described in detail by the
|
||||
[GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
|
||||
extension.
|
||||
|
||||
|
||||
@subsection window_hints_values Supported and default values
|
||||
@subsubsection window_hints_values Supported and default values
|
||||
|
||||
| Name | Default value | Supported values |
|
||||
| ------------------------------- | --------------------------- | ----------------------- |
|
||||
| `GLFW_RESIZABLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_VISIBLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_DECORATED` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_FOCUSED` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_AUTO_ICONIFY` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_FLOATING` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_RED_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_REFRESH_RATE` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
||||
| `GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_SRGB_CAPABLE` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_DOUBLEBUFFER` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_CLIENT_API` | `GLFW_OPENGL_API` | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API` |
|
||||
| `GLFW_CONTEXT_VERSION_MAJOR` | 1 | Any valid major version number of the chosen client API |
|
||||
| `GLFW_CONTEXT_VERSION_MINOR` | 0 | Any valid minor version number of the chosen client API |
|
||||
| `GLFW_CONTEXT_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET` |
|
||||
| `GLFW_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE` |
|
||||
| `GLFW_OPENGL_FORWARD_COMPAT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_OPENGL_DEBUG_CONTEXT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_ANY_PROFILE` | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |
|
||||
Window hint | Default value | Supported values
|
||||
------------------------------- | --------------------------- | ----------------
|
||||
`GLFW_RESIZABLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_VISIBLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_DECORATED` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_FOCUSED` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_AUTO_ICONIFY` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_FLOATING` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_RED_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_SAMPLES` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_REFRESH_RATE` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
||||
`GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_SRGB_CAPABLE` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_DOUBLEBUFFER` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_CLIENT_API` | `GLFW_OPENGL_API` | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`
|
||||
`GLFW_CONTEXT_VERSION_MAJOR` | 1 | Any valid major version number of the chosen client API
|
||||
`GLFW_CONTEXT_VERSION_MINOR` | 0 | Any valid minor version number of the chosen client API
|
||||
`GLFW_CONTEXT_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET`
|
||||
`GLFW_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`
|
||||
`GLFW_OPENGL_FORWARD_COMPAT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_OPENGL_DEBUG_CONTEXT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE`
|
||||
`GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_ANY_PROFILE` | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE`
|
||||
|
||||
|
||||
@section window_close Window close flag
|
||||
@section window_events Window event processing
|
||||
|
||||
See @ref input_event in the @ref input.
|
||||
|
||||
|
||||
@section window_properties Window properties and events
|
||||
|
||||
@subsection window_userptr User pointer
|
||||
|
||||
Each window has a user pointer that can be set with @ref
|
||||
glfwSetWindowUserPointer and fetched with @ref glfwGetWindowUserPointer. This
|
||||
can be used for any purpose you need and will not be modified by GLFW throughout
|
||||
the life-time of the window.
|
||||
|
||||
The initial value of the pointer is `NULL`.
|
||||
|
||||
|
||||
@subsection window_close Closing and close flag
|
||||
|
||||
When the user attempts to close the window, for example by clicking the close
|
||||
widget or using a key chord like Alt+F4, the *close flag* of the window is set.
|
||||
@ -297,16 +324,16 @@ while (!glfwWindowShouldClose(window))
|
||||
}
|
||||
@endcode
|
||||
|
||||
If you wish to be notified when the user attempts to close a window, you can set
|
||||
the close callback with @ref glfwSetWindowCloseCallback. This callback is
|
||||
called directly *after* the close flag has been set.
|
||||
If you wish to be notified when the user attempts to close a window, set a close
|
||||
callback with @ref glfwSetWindowCloseCallback.
|
||||
|
||||
@code
|
||||
glfwSetWindowCloseCallback(window, window_close_callback);
|
||||
@endcode
|
||||
|
||||
The callback function can be used for example to filter close requests and clear
|
||||
the close flag again unless certain conditions are met.
|
||||
The callback function is called directly *after* the close flag has been set.
|
||||
It can be used for example to filter close requests and clear the close flag
|
||||
again unless certain conditions are met.
|
||||
|
||||
@code
|
||||
void window_close_callback(GLFWwindow* window)
|
||||
@ -317,26 +344,27 @@ void window_close_callback(GLFWwindow* window)
|
||||
@endcode
|
||||
|
||||
|
||||
@section window_size Window size
|
||||
@subsection window_size Client area size
|
||||
|
||||
The size of a window can be changed with @ref glfwSetWindowSize. For windowed
|
||||
mode windows, this resizes the specified window so that its *client area* has
|
||||
the specified size. Note that the window system may put limitations on size.
|
||||
For full screen windows, it selects and sets the video mode most closely
|
||||
matching the specified size.
|
||||
mode windows, this resizes the window so that its *client area* has the
|
||||
specified size. The window system may impose limits on window size. For full
|
||||
screen windows, it selects and sets the video mode most closely matching the
|
||||
specified size and the color bit depth and refresh rate hints set at creation.
|
||||
|
||||
@code
|
||||
void glfwSetWindowSize(window, 640, 480);
|
||||
@endcode
|
||||
|
||||
If you wish to be notified when a window is resized, whether by the user or
|
||||
the system, you can set the size callback with @ref glfwSetWindowSizeCallback.
|
||||
the system, set a size callback with @ref glfwSetWindowSizeCallback.
|
||||
|
||||
@code
|
||||
glfwSetWindowSizeCallback(window, window_size_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the new size of the client area of the window.
|
||||
The callback function receives the new size of the client area of the window
|
||||
when it is resized.
|
||||
|
||||
@code
|
||||
void window_size_callback(GLFWwindow* window, int width, int height)
|
||||
@ -354,10 +382,24 @@ glfwGetWindowSize(window, &width, &height);
|
||||
|
||||
@note Do not pass the window size to `glViewport` or other pixel-based OpenGL
|
||||
calls. The window size is in screen coordinates, not pixels. Use the
|
||||
framebuffer size, which is in pixels, for pixel-based calls.
|
||||
[framebuffer size](@ref window_fbsize), which is in pixels, for pixel-based
|
||||
calls.
|
||||
|
||||
The above functions work with the size of the client area, but decorated windows
|
||||
typically have title bars and window frames around this rectangle. You can
|
||||
retrieve the extents of these with @ref glfwGetWindowFrameSize.
|
||||
|
||||
@code
|
||||
int left, top, right, bottom;
|
||||
glfwGetWindowFrameSize(window, &left, &top, &right, &bottom);
|
||||
@endcode
|
||||
|
||||
The returned values are the distances, in screen coordinates, from the edges of
|
||||
the client area to the corresponding edges of the full window. As they are
|
||||
distances and not coordinates, they are always zero or positive.
|
||||
|
||||
|
||||
@section window_fbsize Window framebuffer size
|
||||
@subsection window_fbsize Framebuffer size
|
||||
|
||||
While the size of a window is measured in screen coordinates, OpenGL works with
|
||||
pixels. The size you pass into `glViewport`, for example, should be in pixels
|
||||
@ -367,15 +409,15 @@ a second set of functions to retrieve the size in pixels of the framebuffer of
|
||||
a window.
|
||||
|
||||
If you wish to be notified when the framebuffer of a window is resized, whether
|
||||
by the user or the system, you can set the size callback with @ref
|
||||
by the user or the system, set a size callback with @ref
|
||||
glfwSetFramebufferSizeCallback.
|
||||
|
||||
@code
|
||||
glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the new size of the client area of the window,
|
||||
which can for example be used to update the OpenGL viewport.
|
||||
The callback function receives the new size of the framebuffer when it is
|
||||
resized, which can for example be used to update the OpenGL viewport.
|
||||
|
||||
@code
|
||||
void framebuffer_size_callback(GLFWwindow* window, int width, int height)
|
||||
@ -398,26 +440,26 @@ a window, for example if the window is dragged between a regular monitor and
|
||||
a high-DPI one.
|
||||
|
||||
|
||||
@section window_pos Window position
|
||||
@subsection window_pos Position
|
||||
|
||||
The position of a windowed-mode window can be changed with @ref
|
||||
glfwSetWindowPos. This moves the window so that the upper-left corner of its
|
||||
client area has the specified screen coordinates. Note that the window system
|
||||
may put limitations on placement.
|
||||
client area has the specified screen coordinates. The window system may put
|
||||
limitats on window placement.
|
||||
|
||||
@code
|
||||
glfwSetWindowPos(window, 100, 100);
|
||||
@endcode
|
||||
|
||||
If you wish to be notified when a window is moved, whether by the user or
|
||||
the system, you can set the position callback with @ref glfwSetWindowPosCallback.
|
||||
If you wish to be notified when a window is moved, whether by the user, system
|
||||
or your own code, set a position callback with @ref glfwSetWindowPosCallback.
|
||||
|
||||
@code
|
||||
glfwSetWindowPosCallback(window, window_pos_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the new position of the upper-left corner of its
|
||||
client area.
|
||||
The callback function receives the new position of the upper-left corner of the
|
||||
client area when the window is moved.
|
||||
|
||||
@code
|
||||
void window_pos_callback(GLFWwindow* window, int xpos, int ypos)
|
||||
@ -434,31 +476,190 @@ glfwGetWindowPos(window, &xpos, &ypos);
|
||||
@endcode
|
||||
|
||||
|
||||
@section window_title Window title
|
||||
@subsection window_title Title
|
||||
|
||||
All GLFW windows have a title, although undecorated or full screen windows may
|
||||
not display it or only display it in a task bar or similar interface. To change
|
||||
the title of a window, use @ref glfwSetWindowTitle.
|
||||
not display it or only display it in a task bar or similar interface. You can
|
||||
set a UTF-8 encoded window title with @ref glfwSetWindowTitle.
|
||||
|
||||
@code
|
||||
glfwSetWindowTitle(window, "My Window");
|
||||
@endcode
|
||||
|
||||
The window title is a regular C string using the UTF-8 encoding. This means
|
||||
for example that, as long as your source file is encoded as UTF-8, you can use
|
||||
any Unicode characters.
|
||||
The specified string is copied before the function returns, so there is no need
|
||||
to keep it around.
|
||||
|
||||
As long as your source file is encoded as UTF-8, you can use any Unicode
|
||||
characters directly in the source.
|
||||
|
||||
@code
|
||||
glfwSetWindowTitle(window, "さよなら絶望先生");
|
||||
glfwSetWindowTitle(window, "ヒカルの碁");
|
||||
@endcode
|
||||
|
||||
|
||||
@section window_attribs Window attributes
|
||||
@subsection window_monitor Monitor
|
||||
|
||||
Full screen windows are associated with a specific monitor. You can get the
|
||||
handle for this monitor with @ref glfwGetWindowMonitor.
|
||||
|
||||
@code
|
||||
GLFWmonitor* monitor = glfwGetWindowMonitor(window);
|
||||
@endcode
|
||||
|
||||
This monitor handle is one of those returned by @ref glfwGetMonitors.
|
||||
|
||||
For windowed mode windows, this function returns `NULL`. This is the
|
||||
recommended way to tell full screen windows from windowed mode windows.
|
||||
|
||||
|
||||
@subsection window_iconify Iconification
|
||||
|
||||
Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow.
|
||||
|
||||
@code
|
||||
glfwIconifyWindow(window);
|
||||
@endcode
|
||||
|
||||
When a full screen window is iconified, the original video mode of its monitor
|
||||
is restored until the user or application restores the window.
|
||||
|
||||
Iconified windows can be restored with @ref glfwRestoreWindow.
|
||||
|
||||
@code
|
||||
glfwRestoreWindow(window);
|
||||
@endcode
|
||||
|
||||
When a full screen window is restored, the desired video mode is restored to its
|
||||
monitor as well.
|
||||
|
||||
If you wish to be notified when a window is iconified or restored, whether by
|
||||
the user, system or your own code, set a iconify callback with @ref
|
||||
glfwSetWindowIconifyCallback.
|
||||
|
||||
@code
|
||||
glfwSetWindowIconifyCallback(window, window_iconify_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives changes in the iconification state of the window.
|
||||
|
||||
@code
|
||||
void window_iconify_callback(GLFWwindow* window, int iconified)
|
||||
{
|
||||
if (iconified)
|
||||
{
|
||||
// The window was iconified
|
||||
}
|
||||
else
|
||||
{
|
||||
// The window was restored
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
You can also get the iconification state with @ref glfwGetWindowAttrib.
|
||||
|
||||
@code
|
||||
int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection window_hide Visibility
|
||||
|
||||
Windowed mode windows can be hidden with @ref glfwHideWindow.
|
||||
|
||||
@code
|
||||
glfwHideWindow(window);
|
||||
@endcode
|
||||
|
||||
This makes the window completely invisible to the user, including removing it
|
||||
from the task bar, dock or window list. Full screen windows cannot be hidden
|
||||
and calling @ref glfwHideWindow on a full screen window does nothing.
|
||||
|
||||
Hidden windows can be shown with @ref glfwShowWindow.
|
||||
|
||||
@code
|
||||
glfwShowWindow(window);
|
||||
@endcode
|
||||
|
||||
Windowed mode windows can be created initially hidden with the `GLFW_VISIBLE`
|
||||
[window hint](@ref window_hints_wnd). Windows created hidden are completely
|
||||
invisible to the user until shown. This can be useful if you need to set up
|
||||
your window further before showing it, for example moving it to a specific
|
||||
location.
|
||||
|
||||
You can also get the visibility state with @ref glfwGetWindowAttrib.
|
||||
|
||||
@code
|
||||
int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection window_focus Input focus
|
||||
|
||||
If you wish to be notified when a window gains or loses focus, whether by
|
||||
the user, system or your own code, set a focus callback with @ref
|
||||
glfwSetWindowFocusCallback.
|
||||
|
||||
@code
|
||||
glfwSetWindowFocusCallback(window, window_focus_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives changes in the focus state of the window.
|
||||
|
||||
@code
|
||||
void window_focus_callback(GLFWwindow* window, int focused)
|
||||
{
|
||||
if (focused)
|
||||
{
|
||||
// The window gained focus
|
||||
}
|
||||
else
|
||||
{
|
||||
// The window lost focus
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
You can also get the focus state with @ref glfwGetWindowAttrib.
|
||||
|
||||
@code
|
||||
int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection window_refresh Damage and refresh
|
||||
|
||||
If you wish to be notified when the contents of a window is damaged and needs
|
||||
to be refreshed, set a window refresh callback with @ref
|
||||
glfwSetWindowRefreshCallback.
|
||||
|
||||
@code
|
||||
glfwSetWindowRefreshCallback(m_handle, window_refresh_callback);
|
||||
@endcode
|
||||
|
||||
The callback function is called when the contents of the window needs to be
|
||||
refreshed.
|
||||
|
||||
@code
|
||||
void window_refresh_callback(GLFWwindow* window)
|
||||
{
|
||||
draw_editor_ui(window);
|
||||
glfwSwapBuffers(window);
|
||||
}
|
||||
@endcode
|
||||
|
||||
@note On compositing window systems such as Aero, Compiz or Aqua, where the
|
||||
window contents are saved off-screen, this callback may be called only very
|
||||
infrequently or never at all.
|
||||
|
||||
|
||||
@subsection window_attribs Attributes
|
||||
|
||||
Windows have a number of attributes that can be returned using @ref
|
||||
glfwGetWindowAttrib. Some reflect state that may change during the lifetime of
|
||||
the window, while others reflect the corresponding hints and are fixed at the
|
||||
time of creation.
|
||||
time of creation. Some are related to the actual window and others to its
|
||||
context.
|
||||
|
||||
@code
|
||||
if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
|
||||
@ -468,61 +669,58 @@ if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection window_attribs_window Window attributes
|
||||
@subsubsection window_attribs_window Window related attributes
|
||||
|
||||
The `GLFW_FOCUSED` attribute indicates whether the specified window currently
|
||||
has input focus.
|
||||
`GLFW_FOCUSED` indicates whether the specified window has input focus.
|
||||
|
||||
The `GLFW_ICONIFIED` attribute indicates whether the specified window is
|
||||
currently iconified, whether by the user or with @ref glfwIconifyWindow.
|
||||
`GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by
|
||||
the user or with @ref glfwIconifyWindow.
|
||||
|
||||
The `GLFW_VISIBLE` attribute indicates whether the specified window is currently
|
||||
visible. Window visibility can be controlled with @ref glfwShowWindow and @ref
|
||||
glfwHideWindow and initial visibility is controlled by the
|
||||
[window hint](@ref window_hints) with the same name.
|
||||
`GLFW_VISIBLE` indicates whether the specified window is visible. Window
|
||||
visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
|
||||
and initial visibility is controlled by the [window hint](@ref window_hints)
|
||||
with the same name.
|
||||
|
||||
The `GLFW_RESIZABLE` attribute indicates whether the specified window is
|
||||
resizable *by the user*. This is controlled by the
|
||||
[window hint](@ref window_hints) with the same name.
|
||||
`GLFW_RESIZABLE` indicates whether the specified window is resizable *by the
|
||||
user*. This is controlled by the [window hint](@ref window_hints) with the same
|
||||
name.
|
||||
|
||||
The `GLFW_DECORATED` attribute indicates whether the specified window has
|
||||
decorations such as a border, a close widget, etc. This is controlled by the
|
||||
`GLFW_DECORATED` indicates whether the specified window has decorations such as
|
||||
a border, a close widget, etc. This is controlled by the
|
||||
[window hint](@ref window_hints) with the same name.
|
||||
|
||||
The `GLFW_FLOATING` attribute indicates whether the specified window is
|
||||
floating, also called topmost or always-on-top. This is controlled by the
|
||||
`GLFW_FLOATING` indicates whether the specified window is floating, also called
|
||||
topmost or always-on-top. This is controlled by the
|
||||
[window hint](@ref window_hints) with the same name.
|
||||
|
||||
|
||||
@subsection window_attribs_context Context attributes
|
||||
@subsubsection window_attribs_context Context related attributes
|
||||
|
||||
The `GLFW_CLIENT_API` attribute indicates the client API provided by the
|
||||
window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`.
|
||||
`GLFW_CLIENT_API` indicates the client API provided by the window's context;
|
||||
either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`.
|
||||
|
||||
The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
|
||||
`GLFW_CONTEXT_REVISION` attributes indicate the client API version of the
|
||||
window's context.
|
||||
`GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
|
||||
`GLFW_CONTEXT_REVISION` indicate the client API version of the window's context.
|
||||
|
||||
The `GLFW_OPENGL_FORWARD_COMPAT` attribute is `GL_TRUE` if the window's
|
||||
context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise.
|
||||
`GLFW_OPENGL_FORWARD_COMPAT` is `GL_TRUE` if the window's context is an OpenGL
|
||||
forward-compatible one, or `GL_FALSE` otherwise.
|
||||
|
||||
The `GLFW_OPENGL_DEBUG_CONTEXT` attribute is `GL_TRUE` if the window's
|
||||
context is an OpenGL debug context, or `GL_FALSE` otherwise.
|
||||
`GLFW_OPENGL_DEBUG_CONTEXT` is `GL_TRUE` if the window's context is an OpenGL
|
||||
debug context, or `GL_FALSE` otherwise.
|
||||
|
||||
The `GLFW_OPENGL_PROFILE` attribute indicates the OpenGL profile used by the
|
||||
context. This is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`
|
||||
if the context uses a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the
|
||||
OpenGL profile is unknown or the context is for another client API. Note that
|
||||
the returned profile may not match the profile bits of the context flags, as
|
||||
GLFW will try other means of detecting the profile when no bits are set.
|
||||
`GLFW_OPENGL_PROFILE` indicates the OpenGL profile used by the context. This is
|
||||
`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context uses
|
||||
a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is unknown
|
||||
or the context is an OpenGL ES context. Note that the returned profile may not
|
||||
match the profile bits of the context flags, as GLFW will try other means of
|
||||
detecting the profile when no bits are set.
|
||||
|
||||
The `GLFW_CONTEXT_ROBUSTNESS` attribute indicates the robustness strategy
|
||||
used by the context. This is `GLFW_LOSE_CONTEXT_ON_RESET` or
|
||||
`GLFW_NO_RESET_NOTIFICATION` if the window's context supports robustness, or
|
||||
`GLFW_NO_ROBUSTNESS` otherwise.
|
||||
`GLFW_CONTEXT_ROBUSTNESS` indicates the robustness strategy used by the context.
|
||||
This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION` if the
|
||||
window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
|
||||
|
||||
|
||||
@section window_swap Swapping buffers
|
||||
@section window_swap Buffer swapping
|
||||
|
||||
GLFW windows are by default double buffered. That means that you have two
|
||||
rendering buffers; a front buffer and a back buffer. The front buffer is
|
||||
@ -538,7 +736,8 @@ glfwSwapBuffers(window);
|
||||
|
||||
Sometimes it can be useful to select when the buffer swap will occur. With the
|
||||
function @ref glfwSwapInterval it is possible to select the minimum number of
|
||||
monitor refreshes the driver should wait before swapping the buffers:
|
||||
monitor refreshes the driver wait should from the time @ref glfwSwapBuffers was
|
||||
called before swapping the buffers:
|
||||
|
||||
@code
|
||||
glfwSwapInterval(1);
|
||||
|
@ -57,6 +57,7 @@ int main(void)
|
||||
}
|
||||
|
||||
glfwMakeContextCurrent(window);
|
||||
glfwSwapInterval(1);
|
||||
|
||||
glfwSetKeyCallback(window, key_callback);
|
||||
|
||||
|
1352
include/GLFW/glfw3.h
1352
include/GLFW/glfw3.h
File diff suppressed because it is too large
Load Diff
@ -45,8 +45,8 @@ extern "C" {
|
||||
* using it.**
|
||||
*
|
||||
* Before the inclusion of @ref glfw3native.h, you must define exactly one
|
||||
* window API macro and exactly one context API macro. Failure to do this
|
||||
* will cause a compile-time error.
|
||||
* window system API macro and exactly one context creation API macro. Failure
|
||||
* to do this will cause a compile-time error.
|
||||
*
|
||||
* The available window API macros are:
|
||||
* * `GLFW_EXPOSE_NATIVE_WIN32`
|
||||
@ -109,13 +109,32 @@ extern "C" {
|
||||
|
||||
#if defined(GLFW_EXPOSE_NATIVE_WIN32)
|
||||
/*! @brief Returns the display device name of the specified monitor.
|
||||
* @return The display device name of the specified monitor.
|
||||
*
|
||||
* @return The UTF-8 encoded display device name (`DISPLAY_DEVICE.DeviceName`)
|
||||
* of the specified monitor, or `NULL` if an [error](@ref error_handling)
|
||||
* occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.1.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor);
|
||||
|
||||
/*! @brief Returns the `HWND` of the specified window.
|
||||
* @return The `HWND` of the specified window.
|
||||
*
|
||||
* @return The `HWND` of the specified window, or `NULL` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window);
|
||||
@ -123,7 +142,16 @@ GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window);
|
||||
|
||||
#if defined(GLFW_EXPOSE_NATIVE_WGL)
|
||||
/*! @brief Returns the `HGLRC` of the specified window.
|
||||
* @return The `HGLRC` of the specified window.
|
||||
*
|
||||
* @return The `HGLRC` of the specified window, or `NULL` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window);
|
||||
@ -131,13 +159,31 @@ GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window);
|
||||
|
||||
#if defined(GLFW_EXPOSE_NATIVE_COCOA)
|
||||
/*! @brief Returns the `CGDirectDisplayID` of the specified monitor.
|
||||
* @return The `CGDirectDisplayID` of the specified monitor.
|
||||
*
|
||||
* @return The `CGDirectDisplayID` of the specified monitor, or
|
||||
* `kCGNullDirectDisplay` if an [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.1.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor);
|
||||
|
||||
/*! @brief Returns the `NSWindow` of the specified window.
|
||||
* @return The `NSWindow` of the specified window.
|
||||
*
|
||||
* @return The `NSWindow` of the specified window, or `nil` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window);
|
||||
@ -145,7 +191,16 @@ GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window);
|
||||
|
||||
#if defined(GLFW_EXPOSE_NATIVE_NSGL)
|
||||
/*! @brief Returns the `NSOpenGLContext` of the specified window.
|
||||
* @return The `NSOpenGLContext` of the specified window.
|
||||
*
|
||||
* @return The `NSOpenGLContext` of the specified window, or `nil` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI id glfwGetNSGLContext(GLFWwindow* window);
|
||||
@ -153,19 +208,46 @@ GLFWAPI id glfwGetNSGLContext(GLFWwindow* window);
|
||||
|
||||
#if defined(GLFW_EXPOSE_NATIVE_X11)
|
||||
/*! @brief Returns the `Display` used by GLFW.
|
||||
* @return The `Display` used by GLFW.
|
||||
*
|
||||
* @return The `Display` used by GLFW, or `NULL` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI Display* glfwGetX11Display(void);
|
||||
|
||||
/*! @brief Returns the `RROutput` of the specified monitor.
|
||||
* @return The `RROutput` of the specified monitor.
|
||||
*
|
||||
* @return The `RROutput` of the specified monitor, or `None` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.1.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor);
|
||||
|
||||
/*! @brief Returns the `Window` of the specified window.
|
||||
* @return The `Window` of the specified window.
|
||||
*
|
||||
* @return The `Window` of the specified window, or `None` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI Window glfwGetX11Window(GLFWwindow* window);
|
||||
@ -173,7 +255,16 @@ GLFWAPI Window glfwGetX11Window(GLFWwindow* window);
|
||||
|
||||
#if defined(GLFW_EXPOSE_NATIVE_GLX)
|
||||
/*! @brief Returns the `GLXContext` of the specified window.
|
||||
* @return The `GLXContext` of the specified window.
|
||||
*
|
||||
* @return The `GLXContext` of the specified window, or `NULL` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window);
|
||||
@ -181,19 +272,46 @@ GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window);
|
||||
|
||||
#if defined(GLFW_EXPOSE_NATIVE_EGL)
|
||||
/*! @brief Returns the `EGLDisplay` used by GLFW.
|
||||
* @return The `EGLDisplay` used by GLFW.
|
||||
*
|
||||
* @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI EGLDisplay glfwGetEGLDisplay(void);
|
||||
|
||||
/*! @brief Returns the `EGLContext` of the specified window.
|
||||
* @return The `EGLContext` of the specified window.
|
||||
*
|
||||
* @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window);
|
||||
|
||||
/*! @brief Returns the `EGLSurface` of the specified window.
|
||||
* @return The `EGLSurface` of the specified window.
|
||||
*
|
||||
* @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @par Thread Safety
|
||||
* This function may be called from any thread. Access is not synchronized.
|
||||
*
|
||||
* @par History
|
||||
* Added in GLFW 3.0.
|
||||
*
|
||||
* @ingroup native
|
||||
*/
|
||||
GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);
|
||||
|
Loading…
Reference in New Issue
Block a user