Changed toolset to vs11, for future Havok implementation.
This commit is contained in:
ViktorLjung
@@ -0,0 +1,5 @@
|
||||
|
||||
add_custom_target(docs ALL ${DOXYGEN_EXECUTABLE}
|
||||
WORKING_DIRECTORY ${GLFW_BINARY_DIR}/docs
|
||||
COMMENT "Generating HTML documentation" VERBATIM)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,217 @@
|
||||
/*!
|
||||
|
||||
@page build Building programs that use GLFW
|
||||
|
||||
@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).
|
||||
For information on how to compile the GLFW library itself, see the @ref compile
|
||||
guide.
|
||||
|
||||
|
||||
@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 3 header file, i.e.:
|
||||
|
||||
@code
|
||||
#include <GLFW/glfw3.h>
|
||||
@endcode
|
||||
|
||||
This defines all the constants, types and function prototypes of the GLFW API.
|
||||
It also includes the chosen client API header files (by default OpenGL), and
|
||||
defines all the constants and types necessary for those headers to work on that
|
||||
platform.
|
||||
|
||||
For example, under Windows you are normally required to include `windows.h`
|
||||
before including `GL/gl.h`. This would make your source file tied to Windows
|
||||
and pollute your code's namespace with the whole Win32 API.
|
||||
|
||||
Instead, the GLFW header takes care of this for you, not by including
|
||||
`windows.h`, but rather by itself duplicating only the necessary parts of it.
|
||||
It does this only where needed, so if `windows.h` *is* included, the GLFW header
|
||||
does not try to redefine those symbols.
|
||||
|
||||
In other words:
|
||||
|
||||
- Do *not* include the OpenGL headers yourself, as GLFW does this for you
|
||||
- Do *not* include `windows.h` or other platform-specific headers unless you
|
||||
plan on using those APIs directly
|
||||
- If you *do* need to include such headers, do it *before* including
|
||||
the GLFW one and it will detect this
|
||||
|
||||
If you are using an OpenGL extension loading library such as
|
||||
[GLEW](http://glew.sourceforge.net/), the GLEW header should also be included
|
||||
*before* the GLFW one. The GLEW header defines macros that disable any OpenGL
|
||||
header that the GLFW header includes and GLEW will work as expected.
|
||||
|
||||
|
||||
@subsection build_macros GLFW header option macros
|
||||
|
||||
These macros may be defined before the inclusion of the GLFW header and affect
|
||||
the behavior of the header. Note that GLFW does not provide any of the OpenGL
|
||||
or OpenGL ES headers mentioned below. These are provided by your development
|
||||
environment or your OpenGL or OpenGL ES SDK.
|
||||
|
||||
`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_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`
|
||||
header instead of the regular OpenGL header.
|
||||
|
||||
`GLFW_INCLUDE_ES3` makes the 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.
|
||||
|
||||
`GLFW_INCLUDE_GLU` makes the header include the GLU header *in addition to* the
|
||||
OpenGL header. This should only be used with the default `GL/gl.h` header
|
||||
(`OpenGL/gl.h` on OS X), i.e. if you are not using any of the above macros.
|
||||
|
||||
`GLFW_DLL` is necessary when using the GLFW DLL on Windows, in order to explain
|
||||
to the compiler that the GLFW functions will be coming from another executable.
|
||||
It has no function on other platforms.
|
||||
|
||||
|
||||
@section build_link Link with the right libraries
|
||||
|
||||
@subsection build_link_win32 With MinGW or Visual C++ on Windows
|
||||
|
||||
The static version of the GLFW library is named `glfw3`. When using this
|
||||
version, it is also necessary to link with some libraries that GLFW uses.
|
||||
|
||||
When 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`.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
|
||||
@subsection build_link_cmake_source With CMake and GLFW source
|
||||
|
||||
You can use the GLFW source tree directly from a project that uses CMake. This
|
||||
way, GLFW will be built along with your application as needed.
|
||||
|
||||
Firstly, add the root directory of the GLFW source tree to your project. This
|
||||
will add the `glfw` target and the necessary cache variables to your project.
|
||||
|
||||
add_subdirectory(path/to/glfw)
|
||||
|
||||
To be able to include the GLFW header from your code, you need to tell the
|
||||
compiler where to find it.
|
||||
|
||||
include_directories(path/to/glfw/include)
|
||||
|
||||
Once GLFW has been added to the project, the `GLFW_LIBRARIES` cache variable
|
||||
contains all link-time dependencies of GLFW as it is currently configured. To
|
||||
link against GLFW, link against them and the `glfw` target.
|
||||
|
||||
target_link_libraries(myapp glfw ${GLFW_LIBRARIES})
|
||||
|
||||
Note that `GLFW_LIBRARIES` does not include GLU, as GLFW does not use it. If
|
||||
your application needs GLU, you can add it to the list of dependencies with the
|
||||
`OPENGL_glu_LIBRARY` cache variable, which is implicitly created when the GLFW
|
||||
CMake files look for OpenGL.
|
||||
|
||||
target_link_libraries(myapp glfw ${OPENGL_glu_LIBRARY} ${GLFW_LIBRARIES})
|
||||
|
||||
|
||||
@subsection build_link_cmake_pkgconfig With CMake on Unix and installed GLFW binaries
|
||||
|
||||
CMake can import settings from pkg-config, which GLFW supports. When you
|
||||
installed GLFW, the pkg-config file `glfw3.pc` was installed along with it.
|
||||
|
||||
First you need to find the PkgConfig package. If this fails, you may need to
|
||||
install the pkg-config package for your distribution.
|
||||
|
||||
find_package(PkgConfig REQUIRED)
|
||||
|
||||
This creates the CMake commands to find pkg-config packages. Then you need to
|
||||
find the GLFW package.
|
||||
|
||||
pkg_search_module(GLFW REQUIRED glfw3)
|
||||
|
||||
This creates the CMake variables you need to use GLFW. To be able to include
|
||||
the GLFW header, you need to tell your compiler where it is.
|
||||
|
||||
include_directories(${GLFW_INCLUDE_DIRS})
|
||||
|
||||
You also need to link against the correct libraries. If you are using the
|
||||
shared library version of GLFW, use the `GLFW_LIBRARIES` variable.
|
||||
|
||||
target_link_libraries(simple ${GLFW_LIBRARIES})
|
||||
|
||||
|
||||
If you are using the static library version of GLFW, use the
|
||||
`GLFW_STATIC_LIBRARIES` variable instead.
|
||||
|
||||
target_link_libraries(simple ${GLFW_STATIC_LIBRARIES})
|
||||
|
||||
|
||||
@subsection build_link_pkgconfig With pkg-config on OS X or other Unix
|
||||
|
||||
GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/),
|
||||
and the `glfw3.pc` file is generated when the GLFW library is built and installed
|
||||
along with it.
|
||||
|
||||
A typical compile and link command-line when using the static may look like this:
|
||||
|
||||
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
|
||||
|
||||
If you are using the shared library, simply omit the `--static` flag.
|
||||
|
||||
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
|
||||
|
||||
You can also use the `glfw3.pc` file without installing it first, by using the
|
||||
`PKG_CONFIG_PATH` environment variable.
|
||||
|
||||
env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
|
||||
|
||||
The dependencies do not include GLU, as GLFW does not need it. On OS X, GLU is
|
||||
built into the OpenGL framework, so if you need GLU you don't need to do
|
||||
anything extra. If you need GLU and are using Linux or BSD, you should add
|
||||
`-lGLU` to your link flags.
|
||||
|
||||
See the manpage and other documentation for pkg-config and your compiler and
|
||||
linker for more information on how to link programs.
|
||||
|
||||
|
||||
@subsection build_link_xcode With Xcode on OS X
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@subsection build_link_osx With command-line on OS X
|
||||
|
||||
If you do not wish to use pkg-config, you need to add the required frameworks
|
||||
and libraries to your command-line using the `-l` and `-framework` switches,
|
||||
i.e.:
|
||||
|
||||
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
|
||||
|
||||
Note that you do not add the `.framework` extension to a framework when adding
|
||||
it from the command-line.
|
||||
|
||||
The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
|
||||
special to do when using GLU. Also note that even though your machine may have
|
||||
`libGL`-style OpenGL libraries, they are for use with the X Window System and
|
||||
will *not* work with the OS X native version of GLFW.
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,137 @@
|
||||
/*!
|
||||
|
||||
@page compat Standards conformance
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This chapter 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.
|
||||
|
||||
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_wm ICCCM and EWMH conformance
|
||||
|
||||
As GLFW uses Xlib, directly, without any intervening toolkit
|
||||
library, it has sole responsibility for interacting well with the many and
|
||||
varied window managers in use on Unix-like systems. In order for applications
|
||||
and window managers to work well together, a number of standards and
|
||||
conventions have been developed that regulate behavior outside the scope of the
|
||||
X11 API; most importantly the
|
||||
[Inter-Client Communication Conventions Manual](http://www.tronche.com/gui/x/icccm/)
|
||||
(ICCCM) and
|
||||
[Extended Window Manager Hints](http://standards.freedesktop.org/wm-spec/wm-spec-latest.html)
|
||||
(EWMH) standards.
|
||||
|
||||
GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user
|
||||
attempting to close the GLFW window. If the running window manager does not
|
||||
support this protocol, the close callback will never be called.
|
||||
|
||||
GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify
|
||||
the user when the application has stopped responding, i.e. when it has ceased to
|
||||
process events. If the running window manager does not support this protocol,
|
||||
the user will not be notified if the application locks up.
|
||||
|
||||
GLFW uses the EWMH `_NET_WM_STATE` protocol to tell the window manager to make
|
||||
the GLFW window full screen. If the running window manager does not support this
|
||||
protocol, full screen windows may not work properly. GLFW has a fallback code
|
||||
path in case this protocol is unavailable, but every window manager behaves
|
||||
slightly differently in this regard.
|
||||
|
||||
GLFW uses the
|
||||
[clipboard manager protocol](http://www.freedesktop.org/wiki/ClipboardManager/)
|
||||
to push a clipboard string (i.e. selection) owned by a GLFW window about to be
|
||||
destroyed to the clipboard manager. If there is no running clipboard manager,
|
||||
the clipboard string will be unavailable once the window has been destroyed.
|
||||
|
||||
@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 either GLX 1.3 or greater, or the `GLX_SGIX_fbconfig`
|
||||
extension. Where both are available, the SGIX extension is preferred. If
|
||||
neither is available, GLFW will be unable to create windows.
|
||||
|
||||
GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
|
||||
`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
|
||||
(or "vsync"), in that order of preference. Where none of these extension are
|
||||
available, calling @ref glfwSwapInterval will have no effect.
|
||||
|
||||
GLFW uses the `GLX_ARB_multisample` extension to create contexts with
|
||||
multisampling anti-aliasing. Where this extension is unavailable, the
|
||||
`GLFW_SAMPLES` hint will have no effect.
|
||||
|
||||
GLFW uses the `GLX_ARB_create_context` extension when available, even when
|
||||
creating OpenGL contexts of version 2.1 and below. Where this extension is
|
||||
unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
|
||||
hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
|
||||
will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
|
||||
`GLFW_OPENGL_FORWARD_COMPAT` hints to a non-zero value will cause @ref
|
||||
glfwCreateWindow to fail.
|
||||
|
||||
GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for
|
||||
context profiles. Where this extension is unavailable, setting the
|
||||
`GLFW_OPENGL_PROFILE` hint to anything but zero, or setting `GLFW_CLIENT_API` to
|
||||
anything but `GLFW_OPENGL_API` will cause @ref glfwCreateWindow to fail.
|
||||
|
||||
@section compat_wgl WGL extensions
|
||||
|
||||
The WGL API is used to create OpenGL contexts on Microsoft Windows and other
|
||||
implementations of the Win32 API, such as Wine.
|
||||
|
||||
GLFW uses either the `WGL_EXT_extension_string` or the
|
||||
`WGL_ARB_extension_string` extension to check for the presence of all other WGL
|
||||
extensions listed below. If both are available, the EXT one is preferred. If
|
||||
neither is available, no other extensions are used and many GLFW features
|
||||
related to context creation will have no effect or cause errors when used.
|
||||
|
||||
GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
|
||||
synchronization (or 'vsync'). Where this extension is unavailable, calling @ref
|
||||
glfwSwapInterval will have no effect.
|
||||
|
||||
GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
|
||||
create contexts with multisampling anti-aliasing. Where these extensions are
|
||||
unavailable, the `GLFW_SAMPLES` hint will have no effect.
|
||||
|
||||
GLFW uses the `WGL_ARB_create_context` extension when available, even when
|
||||
creating OpenGL contexts of version 2.1 and below. Where this extension is
|
||||
unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
|
||||
hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
|
||||
will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
|
||||
`GLFW_OPENGL_FORWARD_COMPAT` hints to a non-zero value will cause @ref
|
||||
glfwCreateWindow to fail.
|
||||
|
||||
GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for
|
||||
context profiles. Where this extension is unavailable, setting the
|
||||
`GLFW_OPENGL_PROFILE` hint to anything but zero will cause @ref glfwCreateWindow
|
||||
to fail.
|
||||
|
||||
@section compat_osx OpenGL 3.2 and later on OS X
|
||||
|
||||
Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then
|
||||
only forward-compatible, core profile contexts are supported. Support for
|
||||
OpenGL 4.1 was introduced with OS X 10.9, also limited to forward-compatible,
|
||||
core profile contexts. There is also still no mechanism for requesting debug
|
||||
contexts. Versions of Mac OS X earlier than 10.7 support at most OpenGL
|
||||
version 2.1.
|
||||
|
||||
Because of this, on OS X 10.7 and later, the `GLFW_CONTEXT_VERSION_MAJOR` and
|
||||
`GLFW_CONTEXT_VERSION_MINOR` hints will cause @ref glfwCreateWindow to fail if
|
||||
given version 3.0 or 3.1, the `GLFW_OPENGL_FORWARD_COMPAT` hint must be set to
|
||||
non-zero and the `GLFW_OPENGL_PROFILE` hint must be set to
|
||||
`GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts and the
|
||||
`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
|
||||
|
||||
Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and
|
||||
`GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 2.1,
|
||||
setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to
|
||||
a non-default value will cause @ref glfwCreateWindow to fail and the
|
||||
`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,261 @@
|
||||
/*!
|
||||
|
||||
@page compile Compiling GLFW
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This is about compiling the GLFW library itself. For information on how to
|
||||
build programs that use GLFW, see the @ref build guide.
|
||||
|
||||
|
||||
@section compile_deps Dependencies
|
||||
|
||||
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/).
|
||||
|
||||
Additional dependencies are listed below.
|
||||
|
||||
If you wish to compile GLFW without CMake, see @ref compile_manual.
|
||||
|
||||
|
||||
@subsection compile_deps_msvc Dependencies using Visual C++ on Windows
|
||||
|
||||
The Microsoft Platform SDK that is installed along with Visual C++ contains all
|
||||
the necessary headers, link libraries and tools except for CMake.
|
||||
|
||||
|
||||
@subsection compile_deps_mingw Dependencies with MinGW or MinGW-w64 on Windows
|
||||
|
||||
Both the MinGW and the MinGW-w64 packages contain all the necessary headers,
|
||||
link libraries and tools except for CMake.
|
||||
|
||||
|
||||
@subsection compile_deps_mingw_cross Dependencies using 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
|
||||
for 32- and 64-bit version of MinGW-w64, while Debian GNU/Linux and derivatives
|
||||
like Ubuntu have the `mingw-w64` package for both.
|
||||
|
||||
GLFW has CMake toolchain files in the `CMake/` 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> .
|
||||
|
||||
The exact toolchain file to use depends on the prefix used by the MinGW or
|
||||
MinGW-w64 binaries on your system. You can usually see this in the /usr
|
||||
directory. For example, both the 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 .
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@subsection compile_deps_x11 Dependencies using 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
|
||||
example, on Ubuntu and other distributions based on Debian GNU/Linux, you need
|
||||
to install the `xorg-dev` and `libglu1-mesa-dev` packages. The former pulls in
|
||||
all X.org header packages and the latter pulls in the Mesa OpenGL and GLU
|
||||
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.
|
||||
|
||||
|
||||
@section compile_cmake Generating 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
|
||||
paths for this: the path to the *root* directory of the GLFW source tree (i.e.
|
||||
*not* the `src` subdirectory) and the target path for the generated files and
|
||||
compiled binaries. If these are the same, it is called an in-tree build,
|
||||
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.
|
||||
|
||||
|
||||
@subsection compile_cmake_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 .
|
||||
|
||||
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 ..
|
||||
|
||||
|
||||
@subsection compile_cmake_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*.
|
||||
|
||||
|
||||
@section compile_options CMake options
|
||||
|
||||
The CMake files for GLFW provide a number of options, although not all are
|
||||
available on all supported platforms. Some of these are de facto standards
|
||||
among CMake users and so have no `GLFW_` prefix.
|
||||
|
||||
If you are using the GUI version of CMake, these are listed and can be changed
|
||||
from there. If you are using the command-line version, use the `ccmake` tool.
|
||||
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
|
||||
|
||||
`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
|
||||
library or as a DLL / shared library / dynamic library.
|
||||
|
||||
`LIB_SUFFIX` affects where the GLFW shared /dynamic library is installed. If it
|
||||
is empty, it is installed to `${CMAKE_INSTALL_PREFIX}/lib`. If it is set to
|
||||
`64`, it is installed to `${CMAKE_INSTALL_PREFIX}/lib64`.
|
||||
|
||||
`GLFW_CLIENT_LIBRARY` determines which client API library to use. If set to
|
||||
`opengl` the OpenGL library is used, if set to `glesv1` for the OpenGL ES 1.x
|
||||
library is used, or if set to `glesv2` the OpenGL ES 2.0 library is used. The
|
||||
selected library and its header files must be present on the system for this to
|
||||
work.
|
||||
|
||||
`GLFW_BUILD_EXAMPLES` determines whether the GLFW examples are built
|
||||
along with the library.
|
||||
|
||||
`GLFW_BUILD_TESTS` determines whether the GLFW test programs are
|
||||
built along with the library.
|
||||
|
||||
`GLFW_BUILD_DOCS` determines whether the GLFW documentation is built along with
|
||||
the library.
|
||||
|
||||
|
||||
@subsection 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.
|
||||
|
||||
`GLFW_USE_MENUBAR` determines whether the first call to
|
||||
`glfwCreateWindow` sets up a minimal menu bar.
|
||||
|
||||
`GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries.
|
||||
|
||||
|
||||
@subsection 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
|
||||
DLL version of the Visual C++ library is used. It is recommended to set this to
|
||||
`ON`, as this keeps the executable smaller and benefits from security and bug
|
||||
fix updates of the Visual C++ runtime.
|
||||
|
||||
`GLFW_USE_DWM_SWAP_INTERVAL` determines whether the swap interval is set even
|
||||
when DWM compositing is enabled. If this is `ON`, the swap interval is set even
|
||||
if DWM is enabled. It is recommended to set this to `OFF`, as doing otherwise
|
||||
can lead to severe jitter.
|
||||
|
||||
`GLFW_USE_OPTIMUS_HPG` determines whether to export the `NvOptimusEnablement`
|
||||
symbol, which forces the use of the high-performance GPU on nVidia Optimus
|
||||
systems.
|
||||
|
||||
|
||||
@subsection 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
|
||||
platforms.
|
||||
|
||||
|
||||
@section compile_manual Compiling GLFW manually
|
||||
|
||||
If you wish to compile GLFW without its CMake build environment then you will
|
||||
have to do at least some of the platform detection yourself. GLFW needs
|
||||
a number of configuration macros to be defined in order to know what it's being
|
||||
compiled for and has many optional, platform-specific ones for various features.
|
||||
|
||||
When building with CMake, the `glfw_config.h` configuration header is generated
|
||||
based on the current platform and CMake options. The GLFW CMake environment
|
||||
defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by
|
||||
`internal.h`. Without this macro, GLFW will expect the necessary configuration
|
||||
macros to be defined on the command-line.
|
||||
|
||||
Three macros *must* be defined when compiling GLFW: one for selecting the window
|
||||
creation API, one selecting the context creation API and one client library.
|
||||
Exactly one of each kind must be defined for GLFW to compile and link.
|
||||
|
||||
The window creation API is used to create windows, handle input, monitors, gamma
|
||||
ramps and clipboard. The options are:
|
||||
|
||||
- `_GLFW_COCOA` to use the Cocoa frameworks
|
||||
- `_GLFW_WIN32` to use the Win32 API
|
||||
- `_GLFW_X11` to use the X Window System
|
||||
|
||||
The context creation API is used to enumerate pixel formats / framebuffer
|
||||
configurations and to create contexts. The options are:
|
||||
|
||||
- `_GLFW_NSGL` to use the Cocoa OpenGL framework
|
||||
- `_GLFW_WGL` to use the Win32 WGL API
|
||||
- `_GLFW_GLX` to use the X11 GLX API
|
||||
- `_GLFW_EGL` to use the EGL API (experimental)
|
||||
|
||||
The client library is the one providing the OpenGL or OpenGL ES API, which is
|
||||
used by GLFW to probe the created context. This is not the same thing as the
|
||||
client API, as many desktop OpenGL client libraries now expose the OpenGL ES API
|
||||
through extensions. The options are:
|
||||
|
||||
- `_GLFW_USE_OPENGL` for the desktop OpenGL (opengl32.dll, libGL.so or
|
||||
OpenGL.framework)
|
||||
- `_GLFW_USE_GLESV1` for OpenGL ES 1.x (experimental)
|
||||
- `_GLFW_USE_GLESV2` for OpenGL ES 2.x (experimental)
|
||||
|
||||
Note that `_GLFW_USE_GLESV1` and `_GLFW_USE_GLESV2` may only be used with EGL,
|
||||
as the other context creation APIs do not interface with OpenGL ES client
|
||||
libraries.
|
||||
|
||||
If you are building GLFW as a shared library / dynamic library / DLL then you
|
||||
must also define `_GLFW_BUILD_DLL`. Otherwise, you may not define it.
|
||||
|
||||
If you are using the X11 window creation API then you *must* also select an entry
|
||||
point retrieval mechanism.
|
||||
|
||||
- `_GLFW_HAS_GLXGETPROCADDRESS` to use `glXGetProcAddress` (recommended)
|
||||
- `_GLFW_HAS_GLXGETPROCADDRESSARB` to use `glXGetProcAddressARB` (legacy)
|
||||
- `_GLFW_HAS_GLXGETPROCADDRESSEXT` to use `glXGetProcAddressEXT` (legacy)
|
||||
- `_GLFW_HAS_DLOPEN` to do manual retrieval with `dlopen` (fallback)
|
||||
|
||||
If you are using the Cocoa window creation API, the following options are
|
||||
available:
|
||||
|
||||
- `_GLFW_USE_CHDIR` to `chdir` to the `Resources` subdirectory of the
|
||||
application bundle during @ref glfwInit (recommended)
|
||||
- `_GLFW_USE_MENUBAR` to create and populate the menu bar when the first window
|
||||
is created (recommended)
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,174 @@
|
||||
/*!
|
||||
|
||||
@page context Context handling guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
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, each of which has its own context.
|
||||
|
||||
|
||||
@section context_object Context handles
|
||||
|
||||
The @ref GLFWwindow object encapsulates both a window and a context. They are
|
||||
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
|
||||
@ref glfwTerminate, if any remain). As the window and context are inseparably
|
||||
linked, the object pointer is used as both a context and window handle.
|
||||
|
||||
|
||||
@section 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.
|
||||
|
||||
|
||||
@section 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. OpenGL
|
||||
object sharing is implemented by the operating system and graphics driver and is
|
||||
described in the OpenGL documentation. On platforms where it is possible to
|
||||
choose which types of objects are shared, GLFW requests that all are shared.
|
||||
|
||||
|
||||
@section context_current Current context
|
||||
|
||||
Before you can use the OpenGL or OpenGL ES APIs, you need to have a current
|
||||
context of the proper type. The context encapsulates all render state and all
|
||||
objects like textures and shaders.
|
||||
|
||||
Note that a context can only be current for a single thread at a time, and
|
||||
a thread can only have a single context at a time.
|
||||
|
||||
A context is made current with @ref glfwMakeContextCurrent.
|
||||
|
||||
@code
|
||||
glfwMakeContextCurrent(window);
|
||||
@endcode
|
||||
|
||||
The current context is returned by @ref glfwGetCurrentContext.
|
||||
|
||||
@code
|
||||
GLFWwindow* window = glfwGetCurrentContext();
|
||||
@endcode
|
||||
|
||||
|
||||
@section context_swap Swapping buffers
|
||||
|
||||
See [swapping buffers](@ref window_swap) in the window handling guide.
|
||||
|
||||
|
||||
@section context_glext OpenGL extension handling
|
||||
|
||||
One of the benefits of OpenGL is its extensibility. Independent hardware
|
||||
vendors (IHVs) may include functionality in their OpenGL implementations that
|
||||
expand upon the OpenGL standard before that functionality is included in a new
|
||||
version of the OpenGL specification.
|
||||
|
||||
An extension is defined by:
|
||||
|
||||
- An extension name (e.g. `GL_ARB_debug_output`)
|
||||
- New OpenGL tokens (e.g. `GL_DEBUG_SEVERITY_HIGH_ARB`)
|
||||
- New OpenGL functions (e.g. `glGetDebugMessageLogARB`)
|
||||
|
||||
Note the `ARB` affix, which stands for Architecture Review Board and is used
|
||||
for official extensions. There are many different affixes, depending on who
|
||||
wrote the extension. A list of extensions, together with their specifications,
|
||||
can be found at the [OpenGL Registry](http://www.opengl.org/registry/).
|
||||
|
||||
To use a certain extension, you must first check whether the context supports
|
||||
that extension and then, if it introduces new functions, retrieve the pointers
|
||||
to those functions.
|
||||
|
||||
This can be done with GLFW, as will be described in this section, but usually
|
||||
you will instead want to use a dedicated extension loading library such as
|
||||
[GLEW](http://glew.sourceforge.net/). This kind of library greatly reduces the
|
||||
amount of work necessary to use both OpenGL extensions and modern versions of
|
||||
the OpenGL API. GLEW in particular has been extensively tested with and works
|
||||
well with GLFW.
|
||||
|
||||
|
||||
@subsection context_glext_header The glext.h header
|
||||
|
||||
The `glext.h` header is a continually updated file that defines the interfaces
|
||||
for all OpenGL extensions. The latest version of this can always be found at
|
||||
the [OpenGL Registry](http://www.opengl.org/registry/). It it strongly
|
||||
recommended that you use your own copy, as the one shipped with your development
|
||||
environment may be several years out of date and may not include the extensions
|
||||
you wish to use.
|
||||
|
||||
The header defines function pointer types for all functions of all extensions it
|
||||
supports. These have names like `PFNGLGETDEBUGMESSAGELOGARB` (for
|
||||
`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` and `PROC`
|
||||
are added to the ends.
|
||||
|
||||
|
||||
@subsection context_glext_string Checking for extensions
|
||||
|
||||
A given machine may not actually support the extension (it may have older
|
||||
drivers or a graphics card that lacks the necessary hardware features), so it
|
||||
is necessary to check whether the context supports the extension. This is done
|
||||
with @ref glfwExtensionSupported.
|
||||
|
||||
@code
|
||||
if (glfwExtensionSupported("GL_ARB_debug_output"))
|
||||
{
|
||||
// The extension is supported by the current context
|
||||
}
|
||||
@endcode
|
||||
|
||||
The argument is a null terminated ASCII string with the extension name. If the
|
||||
extension is supported, @ref glfwExtensionSupported returns non-zero, otherwise
|
||||
it returns zero.
|
||||
|
||||
|
||||
@subsection context_glext_proc Fetching function pointers
|
||||
|
||||
Many extensions, though not all, require the use of new OpenGL functions.
|
||||
These entry points are often not exposed by your link libraries, making
|
||||
it necessary to fetch them at run time. With @ref glfwGetProcAddress you can
|
||||
retrieve the address of extension and non-extension OpenGL functions.
|
||||
|
||||
@code
|
||||
PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog = glfwGetProcAddress("glGetDebugMessageLogARB");
|
||||
@endcode
|
||||
|
||||
In general, you should avoid giving the function pointer variables the (exact)
|
||||
same name as the function, as this may confuse your linker. Instead, you can
|
||||
use a different prefix, like above, or some other naming scheme.
|
||||
|
||||
Now that all the pieces have been introduced, here is what they might look like
|
||||
when used together.
|
||||
|
||||
@code
|
||||
#include "glext.h"
|
||||
|
||||
#define glGetDebugMessageLogARB pfnGetDebugMessageLog
|
||||
PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog;
|
||||
|
||||
// Flag indicating whether the extension is supported
|
||||
int has_debug_output = 0;
|
||||
|
||||
void load_extensions(void)
|
||||
{
|
||||
if (glfwExtensionSupported("GL_ARB_debug_output"))
|
||||
{
|
||||
pfnGetDebugMessageLog = (PFNGLGETDEBUGMESSAGELOGARB) glfwGetProcAddress("glGetDebugMessageLogARB");
|
||||
if (pfnGetDebugMessageLog)
|
||||
{
|
||||
// Both the extension name and the function pointer are present
|
||||
has_debug_output = 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
void some_function(void)
|
||||
{
|
||||
// Now the extension function can be called as usual
|
||||
glGetDebugMessageLogARB(...);
|
||||
}
|
||||
@endcode
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,312 @@
|
||||
html {
|
||||
background-color:hsl(0,0%,95%);
|
||||
}
|
||||
|
||||
.glfwheader {
|
||||
font-size:16px;
|
||||
height:64px;
|
||||
max-width:920px;
|
||||
margin:0em auto;
|
||||
}
|
||||
|
||||
.glfwheader a#glfwhome {
|
||||
line-height:64px;
|
||||
padding-right:48px;
|
||||
float:left;
|
||||
color:hsl(0,0%,40%);
|
||||
font-size:2.5em;
|
||||
background-image:url("http://www.glfw.org/css/arrow.png");
|
||||
background-position:right top;
|
||||
background-repeat:no-repeat;
|
||||
}
|
||||
|
||||
.glfwnavbar {
|
||||
list-style-type:none;
|
||||
margin-top:0px;
|
||||
float:right;
|
||||
}
|
||||
|
||||
.glfwnavbar li {
|
||||
float:left;
|
||||
}
|
||||
|
||||
.glfwnavbar a,.glfwnavbar a:visited {
|
||||
line-height:64px;
|
||||
margin-left:2em;
|
||||
display:block;
|
||||
color:hsl(0,0%,40%);
|
||||
}
|
||||
|
||||
.glfwheader a#glfwhome,.glfwnavbar a,.glfwnavbar a:visited {
|
||||
transition:all 0.35s ease 0s;
|
||||
}
|
||||
|
||||
#titlearea,address.footer {
|
||||
color:hsl(0,0%,40%);
|
||||
background-color:hsl(0,0%,95%);
|
||||
border-bottom:none;
|
||||
}
|
||||
|
||||
address.footer {
|
||||
text-align:center;
|
||||
padding:2em;
|
||||
}
|
||||
|
||||
div#top {
|
||||
background-color:hsl(0,0%,40%);
|
||||
}
|
||||
|
||||
div#navrow1,div#navrow2,div#navrow3,div#navrow4 {
|
||||
background-color:hsl(0,0%,40%);
|
||||
background-image:none;
|
||||
max-width:920px;
|
||||
margin:0em auto;
|
||||
}
|
||||
|
||||
ul.tablist {
|
||||
min-width:700px;
|
||||
}
|
||||
|
||||
.tablist a,.tablist a:hover,.tablist li,.tablist li.current a {
|
||||
background-image:none;
|
||||
text-shadow:none;
|
||||
}
|
||||
|
||||
.tablist a,.tablist a:visited {
|
||||
color:hsl(0,0%,95%);
|
||||
text-shadow:none;
|
||||
}
|
||||
|
||||
.tablist li.current a {
|
||||
background:linear-gradient(to bottom,hsl(34,100%,60%) 0%,hsl(24,100%,50%) 100%);
|
||||
box-shadow:inset 0px 0px 32px hsl(24,100%,50%);
|
||||
text-shadow:0px -1px 1px hsl(24,100%,35%);
|
||||
color:hsl(0,0%,100%);
|
||||
}
|
||||
|
||||
div.contents {
|
||||
min-height:590px;
|
||||
}
|
||||
|
||||
div.contents,div.header {
|
||||
max-width:920px;
|
||||
margin:0em auto;
|
||||
padding:0em 2em 2em 2em;
|
||||
background-color:hsl(0,0%,100%);
|
||||
}
|
||||
|
||||
div.header {
|
||||
background-image:none;
|
||||
border-bottom:none;
|
||||
}
|
||||
|
||||
table.doxtable th,dl.reflist dt,div.levels {
|
||||
background:linear-gradient(to bottom,hsl(34,100%,60%) 0%,hsl(24,100%,50%) 100%);
|
||||
box-shadow:inset 0px 0px 32px hsl(24,100%,50%);
|
||||
text-shadow:0px -1px 1px hsl(24,100%,35%);
|
||||
color:hsl(0,0%,100%);
|
||||
}
|
||||
|
||||
dl.reflist dt a.el,div.levels span {
|
||||
color:hsl(24,100%,50%);
|
||||
padding:0.2em;
|
||||
border-radius:4px;
|
||||
background-color:hsl(24,100%,90%);
|
||||
text-shadow:none;
|
||||
}
|
||||
|
||||
div.memproto,div.qindex,div.ah {
|
||||
background:linear-gradient(to bottom,hsl(34,0%,95%) 0%,hsl(24,0%,90%) 100%);
|
||||
box-shadow:inset 0px 0px 32px hsl(24,0%,90%);
|
||||
text-shadow:0px 1px 1px hsl(24,0%,100%);
|
||||
color:hsl(0,0%,10%);
|
||||
}
|
||||
|
||||
div.memproto a {
|
||||
color:hsl(24,100%,50%);
|
||||
}
|
||||
|
||||
div.memproto td.paramname {
|
||||
text-shadow:0px 1px 1px hsl(24,0%,100%);
|
||||
}
|
||||
|
||||
div.memproto,div.qindex,div.ah {
|
||||
border:2px solid hsl(24,0%,90%);
|
||||
border-radius:4px;
|
||||
}
|
||||
|
||||
div.memdoc {
|
||||
background:none;
|
||||
box-shadow:none;
|
||||
border:none;
|
||||
}
|
||||
|
||||
td.paramname {
|
||||
color:hsl(24,100%,25%);
|
||||
}
|
||||
|
||||
dl.reflist dt {
|
||||
border:2px solid hsl(24,100%,50%);
|
||||
border-top-left-radius:4px;
|
||||
border-top-right-radius:4px;
|
||||
border-bottom:none;
|
||||
}
|
||||
|
||||
dl.reflist dd {
|
||||
border:2px solid hsl(24,100%,50%);
|
||||
border-bottom-right-radius:4px;
|
||||
border-bottom-left-radius:4px;
|
||||
border-top:none;
|
||||
background:none;
|
||||
box-shadow:none;
|
||||
}
|
||||
|
||||
table.doxtable {
|
||||
border-collapse:inherit;
|
||||
border-spacing:0px;
|
||||
border:2px solid hsl(24,100%,50%);
|
||||
border-radius:4px;
|
||||
}
|
||||
|
||||
table.doxtable td,table.doxtable th {
|
||||
border:none;
|
||||
}
|
||||
|
||||
tr.even,.directory tr.even,table.doxtable tr:nth-child(even) {
|
||||
background-color:hsl(0,0%,95%);
|
||||
}
|
||||
|
||||
body {
|
||||
color:hsl(0,0%,30%);
|
||||
}
|
||||
|
||||
h1,h2,h2.groupheader,h3,div.toc h3,h4,h5,h6,strong,em {
|
||||
color:hsl(0,0%,10%);
|
||||
border-bottom:none;
|
||||
}
|
||||
|
||||
a,a:hover,a:visited,a:visited:hover,a.el,a.el:visited,.glfwheader a#glfwhome:hover,.tablist a:hover {
|
||||
color:hsl(24,100%,50%);
|
||||
text-decoration:none;
|
||||
}
|
||||
|
||||
.mdescLeft,.mdescRight,.memItemLeft,.memItemRight {
|
||||
background-color:hsl(0,0%,95%);
|
||||
}
|
||||
|
||||
div.directory {
|
||||
border-collapse:inherit;
|
||||
border-spacing:0px;
|
||||
border:2px solid hsl(24,100%,50%);
|
||||
border-radius:4px;
|
||||
}
|
||||
|
||||
.directory .levels span {
|
||||
color:hsl(24,100%,50%);
|
||||
padding:0.1em 0.5em;
|
||||
margin:auto 0.25em;
|
||||
border-radius:2px;
|
||||
background-color:hsl(24,100%,90%);
|
||||
text-shadow:none;
|
||||
}
|
||||
|
||||
td.memSeparator {
|
||||
height:2px;
|
||||
border:0px;
|
||||
background:linear-gradient(to right,hsl(0,0%,95%) 0%,hsl(0,0%,85%) 50%,hsl(0,0%,95%) 100%);
|
||||
}
|
||||
|
||||
dl.note,dl.pre,dl.post,dl.invariant {
|
||||
background:linear-gradient(to bottom,hsl(103,80%,90%) 0%,hsl(103,80%,85%) 100%);
|
||||
box-shadow:inset 0px 0px 32px hsl(103,40%,80%);
|
||||
color:hsl(103,80%,10%);
|
||||
border:2px solid hsl(103,40%,75%);
|
||||
}
|
||||
|
||||
dl.warning,dl.attention {
|
||||
background:linear-gradient(to bottom,hsl(34,80%,90%) 0%,hsl(34,80%,85%) 100%);
|
||||
box-shadow:inset 0px 0px 32px hsl(34,40%,80%);
|
||||
color:hsl(34,80%,10%);
|
||||
border:2px solid hsl(34,40%,75%);
|
||||
}
|
||||
|
||||
dl.deprecated,dl.bug {
|
||||
background:linear-gradient(to bottom,hsl(333,80%,90%) 0%,hsl(333,80%,85%) 100%);
|
||||
box-shadow:inset 0px 0px 32px hsl(333,40%,80%);
|
||||
color:hsl(333,80%,10%);
|
||||
border:2px solid hsl(333,40%,75%);
|
||||
}
|
||||
|
||||
dl.todo,dl.test {
|
||||
background:linear-gradient(to bottom,hsl(200,80%,90%) 0%,hsl(200,80%,85%) 100%);
|
||||
box-shadow:inset 0px 0px 32px hsl(200,40%,80%);
|
||||
color:hsl(200,80%,10%);
|
||||
border:2px solid hsl(200,40%,75%);
|
||||
}
|
||||
|
||||
dl.note,dl.pre,dl.post,dl.invariant,dl.warning,dl.attention,dl.deprecated,dl.bug,dl.todo,dl.test {
|
||||
border-radius:4px;
|
||||
padding:1em;
|
||||
text-shadow:0px 1px 1px hsl(0,0%,100%);
|
||||
}
|
||||
|
||||
div.toc {
|
||||
background:linear-gradient(to bottom,hsl(34,0%,95%) 0%,hsl(24,0%,90%) 100%);
|
||||
box-shadow:inset 0px 0px 32px hsl(24,0%,90%);
|
||||
text-shadow:0px 1px 1px hsl(24,0%,100%);
|
||||
color:hsl(0,0%,10%);
|
||||
border:2px solid hsl(24,0%,90%);
|
||||
border-radius:4px;
|
||||
float:none;
|
||||
width:auto;
|
||||
}
|
||||
|
||||
div.toc h3 {
|
||||
font-size:1.17em;
|
||||
}
|
||||
|
||||
div.toc ul {
|
||||
padding-left:1.5em;
|
||||
}
|
||||
|
||||
div.toc li {
|
||||
background:none;
|
||||
font-size:1em;
|
||||
padding-left:0em;
|
||||
list-style-type:disc;
|
||||
}
|
||||
|
||||
div.ah {
|
||||
background-image:none;
|
||||
}
|
||||
|
||||
div.fragment,pre.fragment {
|
||||
background-color:hsl(0,0%,20%);
|
||||
border-radius:4px;
|
||||
border-width:0px;
|
||||
padding:0.5em 2em;
|
||||
overflow:auto;
|
||||
border-left:4px solid hsl(0,0%,80%);
|
||||
}
|
||||
|
||||
div.line,pre.fragment {
|
||||
color:hsl(60,30%,96%);
|
||||
}
|
||||
|
||||
a.code,a.code:visited,span.preprocessor,span.comment {
|
||||
color:hsl(80,76%,53%);
|
||||
}
|
||||
|
||||
span.keyword,span.keywordtype,span.keywordflow {
|
||||
color:hsl(190,81%,67%);
|
||||
}
|
||||
|
||||
span.stringliteral {
|
||||
color:hsl(54,70%,68%);
|
||||
}
|
||||
|
||||
code {
|
||||
background-color:hsl(0,0%,95%);
|
||||
padding:0.1em;
|
||||
border-radius: 4px;
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
<address class="footer">
|
||||
<p>
|
||||
Last update on $date for $projectname $projectnumber
|
||||
</p>
|
||||
</address>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,34 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||||
<meta name="generator" content="Doxygen $doxygenversion"/>
|
||||
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
|
||||
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
|
||||
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
|
||||
<script type="text/javascript" src="$relpath^jquery.js"></script>
|
||||
<script type="text/javascript" src="$relpath^dynsections.js"></script>
|
||||
$treeview
|
||||
$search
|
||||
$mathjax
|
||||
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
|
||||
$extrastylesheet
|
||||
</head>
|
||||
<body>
|
||||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||||
|
||||
<!--BEGIN TITLEAREA-->
|
||||
<div id="titlearea">
|
||||
<div class="glfwheader">
|
||||
<a href="http://www.glfw.org/" id="glfwhome">GLFW</a>
|
||||
<ul class="glfwnavbar">
|
||||
<li><a href="http://www.glfw.org/documentation.html">Documentation</a></li>
|
||||
<li><a href="http://www.glfw.org/download.html">Download</a></li>
|
||||
<li><a href="http://www.glfw.org/media.html">Media</a></li>
|
||||
<li><a href="http://www.glfw.org/community.html">Community</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<!--END TITLEAREA-->
|
||||
<!-- end header part -->
|
||||
@@ -0,0 +1,116 @@
|
||||
/*!
|
||||
|
||||
@page internals Internal structure
|
||||
|
||||
@tableofcontents
|
||||
|
||||
There are several interfaces inside GLFW. Each interface has its own area of
|
||||
responsibility and its own naming conventions.
|
||||
|
||||
|
||||
@section internals_public Public interface
|
||||
|
||||
The most well-known is the public interface, described in the glfw3.h header
|
||||
file. This is implemented in source files shared by all platforms and these
|
||||
files contain no platform-specific code. This code usually ends up calling the
|
||||
platform and internal interfaces to do the actual work.
|
||||
|
||||
The public interface uses the OpenGL naming conventions except with GLFW and
|
||||
glfw instead of GL and gl. For struct members, where OpenGL sets no precedent,
|
||||
it use headless camel case.
|
||||
|
||||
Examples: @ref glfwCreateWindow, @ref GLFWwindow, @ref GLFWvidmode.redBits,
|
||||
`GLFW_RED_BITS`
|
||||
|
||||
|
||||
@section internals_native Native interface
|
||||
|
||||
The [native interface](@ref native) is a small set of publicly available
|
||||
but platform-specific functions, described in the glfw3native.h header file and
|
||||
used to gain access to the underlying window, context and (on some platforms)
|
||||
display handles used by the platform interface.
|
||||
|
||||
The function names of the native interface are similar to those of the public
|
||||
interface, but embeds the name of the interface that the returned handle is
|
||||
from.
|
||||
|
||||
Examples: @ref glfwGetX11Window, @ref glfwGetWGLContext
|
||||
|
||||
|
||||
@section internals_internal Internal interface
|
||||
|
||||
The internal interface consists of utility functions used by all other
|
||||
interfaces. It is shared code implemented in the same shared source files as
|
||||
the public and event interfaces. The internal interface is described in the
|
||||
internal.h header file.
|
||||
|
||||
The internal interface is in charge of GLFW's global data, which it stores in
|
||||
a `_GLFWlibrary` struct named `_glfw`.
|
||||
|
||||
The internal interface uses the same style as the public interface, except all
|
||||
global names have a leading underscore.
|
||||
|
||||
Examples: @ref _glfwIsValidContextConfig, @ref _GLFWwindow, `_glfw.currentRamp`
|
||||
|
||||
|
||||
@section internals_platform Platform interface
|
||||
|
||||
The platform interface implements all platform-specific operations as a service
|
||||
to the public interface. This includes event processing. The platform
|
||||
interface is never directly called by users of GLFW and never directly calls the
|
||||
user's code. It is also prohibited from modifying the platform-independent part
|
||||
of the internal structs. Instead, it calls the event interface when events
|
||||
interesting to GLFW are received.
|
||||
|
||||
The platform interface mirrors those parts of the public interface that needs to
|
||||
perform platform-specific operations on some or all platforms. The are also
|
||||
named the same except that the glfw function prefix is replaced by
|
||||
_glfwPlatform.
|
||||
|
||||
Examples: @ref _glfwPlatformCreateWindow
|
||||
|
||||
The platform interface also defines structs that contain platform-specific
|
||||
global and per-object state. Their names mirror those of the internal
|
||||
interface, except that an interface-specific suffix is added.
|
||||
|
||||
Examples: `_GLFWwindowX11`, `_GLFWcontextWGL`
|
||||
|
||||
These structs are incorporated as members into the internal interface structs
|
||||
using special macros that name them after the specific interface used. This
|
||||
prevents shared code from accidentally using these members.
|
||||
|
||||
Examples: `window.win32.handle`, `_glfw.x11.display`
|
||||
|
||||
|
||||
@section internals_event Event interface
|
||||
|
||||
The event interface is implemented in the same shared source files as the public
|
||||
interface and is responsible for delivering the events it receives to the user,
|
||||
either via callbacks, via window state changes or both.
|
||||
|
||||
The function names of the event interface use a `_glfwInput` prefix and the
|
||||
ObjectEvent pattern.
|
||||
|
||||
Examples: @ref _glfwInputWindowFocus, @ref _glfwInputCursorMotion
|
||||
|
||||
|
||||
@section internals_static Static functions
|
||||
|
||||
Static functions may be used by any interface and have no prefixes or suffixes.
|
||||
These use headless camel case.
|
||||
|
||||
Examples: `clearScrollOffsets`
|
||||
|
||||
|
||||
@section internals_config Configuration macros
|
||||
|
||||
GLFW uses a number of configuration macros to select at compile time which
|
||||
interfaces and code paths to use. They are defined in the glfw_config.h header file,
|
||||
which is generated from the `glfw_config.h.in` file by CMake.
|
||||
|
||||
Configuration macros the same style as tokens in the public interface, except
|
||||
with a leading underscore.
|
||||
|
||||
Examples: `_GLFW_HAS_GLXGETPROCADDRESS`
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,22 @@
|
||||
/*!
|
||||
|
||||
@mainpage notitle
|
||||
|
||||
@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.
|
||||
|
||||
This is the documentation for version 3.0, which has [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).
|
||||
|
||||
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.
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,105 @@
|
||||
/*!
|
||||
|
||||
@page monitor Multi-monitor guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
|
||||
@section monitor_objects Monitor objects
|
||||
|
||||
The @ref GLFWmonitor object represents a currently connected monitor.
|
||||
|
||||
|
||||
@section monitor_monitors Retrieving monitors
|
||||
|
||||
The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is usually
|
||||
the user's preferred monitor and the one with global UI elements like task bar
|
||||
or menu bar.
|
||||
|
||||
@code
|
||||
GLFWmonitor* primary = glfwGetPrimaryMonitor();
|
||||
@endcode
|
||||
|
||||
You can retrieve all currently connected monitors with @ref glfwGetMonitors.
|
||||
|
||||
@code
|
||||
int count;
|
||||
GLFWmonitor** monitors = glfwGetMonitors(&count);
|
||||
@endcode
|
||||
|
||||
|
||||
@section monitor_modes Retrieving video modes
|
||||
|
||||
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.
|
||||
|
||||
@code
|
||||
int count;
|
||||
GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
|
||||
@endcode
|
||||
|
||||
To get the current video mode of a monitor call @ref glfwGetVideoMode.
|
||||
|
||||
@code
|
||||
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
|
||||
@endcode
|
||||
|
||||
|
||||
@section monitor_size Monitor physical size
|
||||
|
||||
The physical size in millimetres of a monitor, or an approximation of it, can be
|
||||
retrieved with @ref glfwGetMonitorPhysicalSize.
|
||||
|
||||
@code
|
||||
int widthMM, heightMM;
|
||||
glfwGetMonitorPhysicalSize(monitor, &widthMM, &heightMM);
|
||||
@endcode
|
||||
|
||||
This can, for example, be used together with the current video mode to calculate
|
||||
the DPI of a monitor.
|
||||
|
||||
@code
|
||||
const double dpi = mode->width / (widthMM / 25.4);
|
||||
@endcode
|
||||
|
||||
|
||||
@section monitor_name Monitor name
|
||||
|
||||
The name of a monitor is returned by @ref glfwGetMonitorName.
|
||||
|
||||
@code
|
||||
const char* name = glfwGetMonitorName(monitor);
|
||||
@endcode
|
||||
|
||||
The monitor name is a regular C string using the UTF-8 encoding. Note that
|
||||
monitor names are not guaranteed to be unique.
|
||||
|
||||
|
||||
@section monitor_gamma Monitor gamma ramp
|
||||
|
||||
The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts
|
||||
a monitor handle and a pointer to a @ref GLFWgammaramp structure.
|
||||
|
||||
@code
|
||||
glfwSetGammaRamp(monitor, &ramp);
|
||||
@endcode
|
||||
|
||||
The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp.
|
||||
|
||||
@code
|
||||
const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);
|
||||
@endcode
|
||||
|
||||
If you wish to set a regular gamma ramp, you can have GLFW calculate it for you
|
||||
from the desired exponent with @ref glfwSetGamma, which in turn calls @ref
|
||||
glfwSetGammaRamp with the resulting ramp.
|
||||
|
||||
@code
|
||||
glfwSetGamma(monitor, 1.0);
|
||||
@endcode
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,327 @@
|
||||
/*!
|
||||
|
||||
@page moving Moving from GLFW 2 to 3
|
||||
|
||||
@tableofcontents
|
||||
|
||||
This is a transition guide for moving from GLFW 2 to 3. It describes what has
|
||||
changed or been removed, but does *not* include
|
||||
[new features](@ref news) unless they are required when moving an existing code
|
||||
base onto the new API. For example, use of the new multi-monitor functions are
|
||||
required to create full screen windows with GLFW 3.
|
||||
|
||||
|
||||
@section moving_removed Removed features
|
||||
|
||||
@subsection moving_threads Threading functions
|
||||
|
||||
The threading functions have been removed, including the 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.
|
||||
|
||||
If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
|
||||
support them, see the
|
||||
[TinyThread++](https://gitorious.org/tinythread/tinythreadpp) and
|
||||
[TinyCThread](https://gitorious.org/tinythread/tinycthread) projects created by
|
||||
the original author of GLFW. These libraries implement a usable subset of the
|
||||
threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
|
||||
TinyCThread.
|
||||
|
||||
However, GLFW 3 has better support for *use from multiple threads* than GLFW
|
||||
2 had. Contexts can be made current on and rendered with from secondary
|
||||
threads, and the documentation explicitly states which functions may be used
|
||||
from secondary threads and which may only be used from the main thread, i.e. the
|
||||
thread that calls main.
|
||||
|
||||
|
||||
@subsection moving_image Image and texture loading
|
||||
|
||||
The image and texture loading functions have been removed. They only supported
|
||||
the Targa image format, making them mostly useful for beginner level examples.
|
||||
To become of sufficiently high quality to warrant keeping them in GLFW 3, they
|
||||
would need not only to support other formats, but also modern extensions to the
|
||||
OpenGL texturing facilities. This would either add a number of external
|
||||
dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions
|
||||
of these libraries.
|
||||
|
||||
As there already are libraries doing this, it seems unnecessary both to
|
||||
duplicate this work and to tie this duplicate to GLFW. Projects similar to
|
||||
GLFW, such as freeglut, could also gain from such a library. Also, would be no
|
||||
platform-specific part of such a library, as both OpenGL and stdio are available
|
||||
wherever GLFW is.
|
||||
|
||||
|
||||
@subsection moving_char_up Character actions
|
||||
|
||||
The action parameter of the [character callback](@ref GLFWcharfun) has been
|
||||
removed. This was an artefact of the origin of GLFW, i.e. being developed in
|
||||
English by a Swede. However, many keyboard layouts require more than one key to
|
||||
produce characters with diacritical marks. Even the Swedish keyboard layout
|
||||
requires this for uncommon cases like ü.
|
||||
|
||||
Note that this is only the removal of the *action parameter* of the character
|
||||
callback, *not* the removal of the character callback itself.
|
||||
|
||||
|
||||
@subsection moving_wheel Mouse wheel position
|
||||
|
||||
The `glfwGetMouseWheel` function has been removed. Scroll events do not
|
||||
represent an absolute state, but is instead an interpretation of a relative
|
||||
change in state, like character input. So, like character input, there is no
|
||||
sane 'current state' to return. The mouse wheel callback has been replaced by
|
||||
a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll
|
||||
offsets.
|
||||
|
||||
|
||||
@subsection moving_stdcall GLFWCALL macro
|
||||
|
||||
The `GLFWCALL` macro, which made callback functions use
|
||||
[__stdcall](http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows,
|
||||
has been removed. GLFW is written in C, not Pascal. Removing this macro means
|
||||
there's one less thing for users of GLFW to remember, i.e. the requirement to
|
||||
mark all callback functions with `GLFWCALL`. It also simplifies the creation of
|
||||
DLLs and DLL link libraries, as there's no need to explicitly disable `@n` entry
|
||||
point suffixes.
|
||||
|
||||
|
||||
@subsection moving_mbcs Win32 MBCS support
|
||||
|
||||
The Win32 port of GLFW 3 will not compile in
|
||||
[MBCS mode](http://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
|
||||
However, because the use of the Unicode version of the Win32 API doesn't affect
|
||||
the process as a whole, but only those windows created using it, it's perfectly
|
||||
possible to call MBCS functions from other parts of the same application.
|
||||
Therefore, even if an application using GLFW has MBCS mode code, there's no need
|
||||
for GLFW itself to support it.
|
||||
|
||||
|
||||
@subsection moving_windows Support for versions of Windows older than XP
|
||||
|
||||
All explicit support for version of Windows older than XP has been removed.
|
||||
There is no code that actively prevents GLFW 3 from running on these earlier
|
||||
versions, but it uses Win32 functions that those versions lack.
|
||||
|
||||
Windows XP was released in 2001, and by now (2013) it has not only
|
||||
replaced almost all earlier versions of Windows, but is itself rapidly being
|
||||
replaced by Windows 7 and 8. The MSDN library doesn't even provide
|
||||
documentation for version older than Windows 2000, making it difficult to
|
||||
maintain compatibility with these versions even if it was deemed worth the
|
||||
effort.
|
||||
|
||||
The Win32 API has also not stood still, and GLFW 3 uses many functions only
|
||||
present on Windows XP or later. Even supporting an OS as new as XP (new
|
||||
from the perspective of GLFW 2, which still supports Windows 95) requires
|
||||
runtime checking for a number of functions that are present only on modern
|
||||
version of Windows.
|
||||
|
||||
|
||||
@subsection moving_syskeys Capture of system-wide hotkeys
|
||||
|
||||
The ability to disable and capture system-wide hotkeys like Alt+Tab has been
|
||||
removed. Modern applications, whether they're games, scientific visualisations
|
||||
or something else, are nowadays expected to be good desktop citizens and allow
|
||||
these hotkeys to function even when running in full screen mode.
|
||||
|
||||
|
||||
@subsection moving_opened Window open parameter
|
||||
|
||||
The `GLFW_OPENED` window parameter has been removed. As long as the
|
||||
[window object](@ref window_object) is around, the window is "open". To detect
|
||||
when the user attempts to close the window, see @ref glfwWindowShouldClose and
|
||||
the [close callback](@ref GLFWwindowclosefun).
|
||||
|
||||
|
||||
@subsection moving_autopoll Automatic polling of events
|
||||
|
||||
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, the event processing functions act on all windows at once.
|
||||
|
||||
|
||||
@subsection moving_terminate Automatic termination
|
||||
|
||||
GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization. To
|
||||
properly release all resources allocated by GLFW, you should therefore call @ref
|
||||
glfwTerminate yourself before exiting.
|
||||
|
||||
|
||||
@subsection moving_glu GLU header inclusion
|
||||
|
||||
GLFW 3 does not include the GLU header by default and GLU itself has been
|
||||
deprecated, but you can request that the GLFW 3 header includes it by defining
|
||||
`GLFW_INCLUDE_GLU` before the inclusion of the GLFW 3 header.
|
||||
|
||||
|
||||
@section moving_changed Changes to existing features
|
||||
|
||||
@subsection moving_window_handles Window handles
|
||||
|
||||
Because GLFW 3 supports multiple windows, window handle parameters have been
|
||||
added to all window-related GLFW functions and callbacks. The handle of
|
||||
a newly created window is returned by @ref glfwCreateWindow (formerly
|
||||
`glfwOpenWindow`). Window handles are of the `GLFWwindow*` type, i.e. a pointer
|
||||
to an opaque struct.
|
||||
|
||||
|
||||
@subsection moving_monitor Multi-monitor support
|
||||
|
||||
GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle
|
||||
type and a set of related functions. To request a full screen mode window,
|
||||
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
|
||||
window to use. There is @ref glfwGetPrimaryMonitor that provides behaviour
|
||||
similar to that of GLFW 2.
|
||||
|
||||
|
||||
@subsection moving_window_close Window closing
|
||||
|
||||
Window closing initiated by the user is now just an event like any other.
|
||||
Unlike GLFW 2, windows and contexts created with GLFW 3 will not disappear from
|
||||
underfoot. Each window now has a close flag, which is set when the user
|
||||
attempts to close it. By default, nothing else happens and the window stays
|
||||
open and visible. It is then up to you to either destroy the window, take some
|
||||
other action or simply ignore the request. You can query the close flag at any
|
||||
time with @ref glfwWindowShouldClose and set it at any time with @ref
|
||||
glfwSetWindowShouldClose.
|
||||
|
||||
The close callback no longer returns a value. Instead, it is called after the
|
||||
close flag has been set so it can override its value, if it chooses to, before
|
||||
event processing completes. You may however not call @ref glfwDestroyWindow
|
||||
from the close callback (or any other window related callback).
|
||||
|
||||
GLFW itself never clears the close flag, allowing you to set it for other
|
||||
reasons for the window to close as well, for example the user choosing Quit from
|
||||
the main menu.
|
||||
|
||||
|
||||
@subsection moving_context Explicit context management
|
||||
|
||||
Each GLFW 3 window has its own OpenGL context and only you, the user, can know
|
||||
which context should be current on which thread at any given time. Therefore,
|
||||
GLFW 3 makes no assumptions about when you want a certain context to be current,
|
||||
leaving that decision to you.
|
||||
|
||||
This means, among other things, that you need to call @ref
|
||||
glfwMakeContextCurrent after creating a window before you can call any OpenGL
|
||||
functions.
|
||||
|
||||
|
||||
@subsection moving_repeat Key repeat
|
||||
|
||||
The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled
|
||||
for both keys and characters. A new key action, `GLFW_REPEAT`, has been added
|
||||
to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press
|
||||
from a repeat. Note that @ref glfwGetKey still returns only `GLFW_PRESS` or
|
||||
`GLFW_RELEASE`.
|
||||
|
||||
|
||||
@subsection moving_keys Physical key input
|
||||
|
||||
GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
|
||||
the values generated by the current keyboard layout. The tokens are named
|
||||
according to the values they would have using the standard US layout, but this
|
||||
is only a convenience, as most programmers are assumed to know that layout.
|
||||
This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and
|
||||
is the same key in the same place regardless of what keyboard layouts the users
|
||||
of your program has.
|
||||
|
||||
The key input facility was never meant for text input, although using it that
|
||||
way worked slightly better in GLFW 2. If you were using it to input text, you
|
||||
should be using the character callback instead, on both GLFW 2 and 3. This will
|
||||
give you the characters being input, as opposed to the keys being pressed.
|
||||
|
||||
GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of
|
||||
having to remember whether to check for `'a'` or `'A'`, you now check for
|
||||
`GLFW_KEY_A`.
|
||||
|
||||
|
||||
@subsection moving_joystick Joystick input
|
||||
|
||||
The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes.
|
||||
|
||||
The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and
|
||||
`GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent
|
||||
function as well as axis and button counts returned by the @ref
|
||||
glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions.
|
||||
|
||||
|
||||
@subsection moving_video_modes Video mode enumeration
|
||||
|
||||
Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function
|
||||
now returns all available modes for a specific monitor instead of requiring you
|
||||
to guess how large an array you need. The `glfwGetDesktopMode` function, which
|
||||
had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
|
||||
returns the current mode of a monitor.
|
||||
|
||||
|
||||
@subsection moving_cursor Cursor positioning
|
||||
|
||||
GLFW 3 only allows you to position the cursor within a window using @ref
|
||||
glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
|
||||
Unless the window is active, the function fails silently.
|
||||
|
||||
|
||||
@subsection moving_hints Persistent window hints
|
||||
|
||||
Window hints are no longer reset to their default values on window creation, but
|
||||
instead retain their values until modified by @ref glfwWindowHint (formerly
|
||||
`glfwOpenWindowHint`) or @ref glfwDefaultWindowHints, or until the library is
|
||||
terminated and re-initialized.
|
||||
|
||||
|
||||
@section moving_renamed Name changes
|
||||
|
||||
@subsection moving_renamed_files Library and header file
|
||||
|
||||
The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to
|
||||
avoid collisions with the headers of other major versions. Similarly, the GLFW
|
||||
3 library is named `glfw3,` except when it's installed as a shared library on
|
||||
Unix-like systems, where it uses the
|
||||
[soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`.
|
||||
|
||||
|
||||
@subsection moving_renamed_functions Functions
|
||||
|
||||
| GLFW 2 | GLFW 3 | Notes |
|
||||
| --------------------------- | ----------------------------- | ----- |
|
||||
| `glfwOpenWindow` | @ref glfwCreateWindow | All channel bit depths are now hints
|
||||
| `glfwCloseWindow` | @ref glfwDestroyWindow | |
|
||||
| `glfwOpenWindowHint` | @ref glfwWindowHint | Now accepts all `GLFW_*_BITS` tokens |
|
||||
| `glfwEnable` | @ref glfwSetInputMode | |
|
||||
| `glfwDisable` | @ref glfwSetInputMode | |
|
||||
| `glfwGetMousePos` | @ref glfwGetCursorPos | |
|
||||
| `glfwSetMousePos` | @ref glfwSetCursorPos | |
|
||||
| `glfwSetMousePosCallback` | @ref glfwSetCursorPosCallback | |
|
||||
| `glfwSetMouseWheelCallback` | @ref glfwSetScrollCallback | Accepts two-dimensional scroll offsets as doubles |
|
||||
| `glfwGetJoystickPos` | @ref glfwGetJoystickAxes | |
|
||||
| `glfwGetWindowParam` | @ref glfwGetWindowAttrib | |
|
||||
| `glfwGetGLVersion` | @ref glfwGetWindowAttrib | Use `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and `GLFW_CONTEXT_REVISION` |
|
||||
| `glfwGetDesktopMode` | @ref glfwGetVideoMode | Returns the current mode of a monitor |
|
||||
| `glfwGetJoystickParam` | @ref glfwJoystickPresent | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons |
|
||||
|
||||
@subsection moving_renamed_tokens Tokens
|
||||
|
||||
| GLFW 2 | GLFW 3 | Notes |
|
||||
| --------------------------- | ---------------------------- | ----- |
|
||||
| `GLFW_OPENGL_VERSION_MAJOR` | `GLFW_CONTEXT_VERSION_MAJOR` | Renamed as it applies to OpenGL ES as well |
|
||||
| `GLFW_OPENGL_VERSION_MINOR` | `GLFW_CONTEXT_VERSION_MINOR` | Renamed as it applies to OpenGL ES as well |
|
||||
| `GLFW_FSAA_SAMPLES` | `GLFW_SAMPLES` | Renamed to match the OpenGL API |
|
||||
| `GLFW_ACTIVE` | `GLFW_FOCUSED` | Renamed to match the window focus callback |
|
||||
| `GLFW_WINDOW_NO_RESIZE` | `GLFW_RESIZABLE` | The default has been inverted |
|
||||
| `GLFW_MOUSE_CURSOR` | `GLFW_CURSOR` | Used with @ref glfwSetInputMode |
|
||||
| `GLFW_KEY_ESC` | `GLFW_KEY_ESCAPE` | |
|
||||
| `GLFW_KEY_DEL` | `GLFW_KEY_DELETE` | |
|
||||
| `GLFW_KEY_PAGEUP` | `GLFW_KEY_PAGE_UP` | |
|
||||
| `GLFW_KEY_PAGEDOWN` | `GLFW_KEY_PAGE_DOWN` | |
|
||||
| `GLFW_KEY_KP_NUM_LOCK` | `GLFW_KEY_NUM_LOCK` | |
|
||||
| `GLFW_KEY_LCTRL` | `GLFW_KEY_LEFT_CONTROL` | |
|
||||
| `GLFW_KEY_LSHIFT` | `GLFW_KEY_LEFT_SHIFT` | |
|
||||
| `GLFW_KEY_LALT` | `GLFW_KEY_LEFT_ALT` | |
|
||||
| `GLFW_KEY_LSUPER` | `GLFW_KEY_LEFT_SUPER` | |
|
||||
| `GLFW_KEY_RCTRL` | `GLFW_KEY_RIGHT_CONTROL` | |
|
||||
| `GLFW_KEY_RSHIFT` | `GLFW_KEY_RIGHT_SHIFT` | |
|
||||
| `GLFW_KEY_RALT` | `GLFW_KEY_RIGHT_ALT` | |
|
||||
| `GLFW_KEY_RSUPER` | `GLFW_KEY_RIGHT_SUPER` | |
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,173 @@
|
||||
/*!
|
||||
|
||||
@page news New features
|
||||
|
||||
@tableofcontents
|
||||
|
||||
|
||||
@section news_30 New features in version 3.0
|
||||
|
||||
@subsection news_30_cmake CMake build system
|
||||
|
||||
GLFW now uses the CMake build system instead of the various makefiles and
|
||||
project files used by earlier versions. CMake is available for all platforms
|
||||
supported by GLFW, is present in most package systems and can generate
|
||||
makefiles and/or project files for most popular development environments.
|
||||
|
||||
For more information on how to use CMake, see the
|
||||
[CMake manual](http://cmake.org/cmake/help/documentation.html).
|
||||
|
||||
|
||||
@subsection news_30_multiwnd Multi-window support
|
||||
|
||||
GLFW now supports the creation of multiple windows, each with their own OpenGL
|
||||
or OpenGL ES context, and all window functions now take a window handle. Event
|
||||
callbacks are now per-window and are provided with the handle of the window that
|
||||
received the event. The @ref glfwMakeContextCurrent function has been added to
|
||||
select which context is current on a given thread.
|
||||
|
||||
|
||||
@subsection news_30_multimon Multi-monitor support
|
||||
|
||||
GLFW now explicitly supports multiple monitors. They can be enumerated with
|
||||
@ref glfwGetMonitors, queried with @ref glfwGetVideoModes, @ref
|
||||
glfwGetMonitorPos, @ref glfwGetMonitorName and @ref glfwGetMonitorPhysicalSize,
|
||||
and specified at window creation to make the newly created window full screen on
|
||||
that specific monitor.
|
||||
|
||||
|
||||
@subsection news_30_unicode Unicode support
|
||||
|
||||
All string arguments to GLFW functions and all strings returned by GLFW now use
|
||||
the UTF-8 encoding. This includes the window title, error string, clipboard
|
||||
text, monitor and joystick names as well as the extension function arguments (as
|
||||
ASCII is a subset of UTF-8).
|
||||
|
||||
|
||||
@subsection news_30_clipboard Clipboard text I/O
|
||||
|
||||
GLFW now supports reading and writing plain text to and from the system
|
||||
clipboard, with the @ref glfwGetClipboardString and @ref glfwSetClipboardString
|
||||
functions.
|
||||
|
||||
|
||||
@subsection news_30_gamma Gamma ramp support
|
||||
|
||||
GLFW now supports setting and reading back the gamma ramp of monitors, with the
|
||||
@ref glfwGetGammaRamp and @ref glfwSetGammaRamp functions. There is also @ref
|
||||
glfwSetGamma, which generates a ramp from a gamma value and then sets it.
|
||||
|
||||
|
||||
@subsection news_30_gles OpenGL ES support
|
||||
|
||||
GLFW now supports the creation of OpenGL ES contexts, by setting the
|
||||
`GLFW_CLIENT_API` window hint to `GLFW_OPENGL_ES_API`, where creation of such
|
||||
contexts are supported. Note that GLFW *does not implement* OpenGL ES, so your
|
||||
driver must provide support in a way usable by GLFW. Modern nVidia and Intel
|
||||
drivers support creation of OpenGL ES context using the GLX and WGL APIs, while
|
||||
AMD provides an EGL implementation instead.
|
||||
|
||||
|
||||
@subsection news_30_egl (Experimental) EGL support
|
||||
|
||||
GLFW now has an experimental EGL context creation back end that can be selected
|
||||
through CMake options.
|
||||
|
||||
|
||||
@subsection news_30_hidpi High-DPI support
|
||||
|
||||
GLFW now supports high-DPI monitors on both Windows and OS X, giving windows full
|
||||
resolution framebuffers where other UI elements are scaled up. To achieve this,
|
||||
@ref glfwGetFramebufferSize and @ref glfwSetFramebufferSizeCallback have been
|
||||
added. These work with pixels, while the rest of the GLFW API works with screen
|
||||
coordinates.
|
||||
|
||||
|
||||
@subsection news_30_error Error callback
|
||||
|
||||
GLFW now has an error callback, which can provide your application with much
|
||||
more detailed diagnostics than was previously possible. The callback is passed
|
||||
an error code and a description string.
|
||||
|
||||
|
||||
@subsection news_30_wndptr Per-window user pointer
|
||||
|
||||
Each window now has a user-defined pointer, retrieved with @ref
|
||||
glfwGetWindowUserPointer and set with @ref glfwSetWindowUserPointer, to make it
|
||||
easier to integrate GLFW into C++ code.
|
||||
|
||||
|
||||
@subsection news_30_iconifyfun Window iconification callback
|
||||
|
||||
Each window now has a callback for iconification and restoration events,
|
||||
which is set with @ref glfwSetWindowIconifyCallback.
|
||||
|
||||
|
||||
@subsection news_30_wndposfun Window position callback
|
||||
|
||||
Each window now has a callback for position events, which is set with @ref
|
||||
glfwSetWindowPosCallback.
|
||||
|
||||
|
||||
@subsection news_30_wndpos Window position query
|
||||
|
||||
The position of a window can now be retrieved using @ref glfwGetWindowPos.
|
||||
|
||||
|
||||
@subsection news_30_focusfun Window focus callback
|
||||
|
||||
Each windows now has a callback for focus events, which is set with @ref
|
||||
glfwSetWindowFocusCallback.
|
||||
|
||||
|
||||
@subsection news_30_enterleave Cursor enter/leave callback
|
||||
|
||||
Each window now has a callback for when the mouse cursor enters or leaves its
|
||||
client area, which is set with @ref glfwSetCursorEnterCallback.
|
||||
|
||||
|
||||
@subsection news_30_wndtitle Initial window title
|
||||
|
||||
The title of a window is now specified at creation time, as one of the arguments
|
||||
to @ref glfwCreateWindow.
|
||||
|
||||
|
||||
@subsection news_30_hidden Hidden windows
|
||||
|
||||
Windows can now be hidden with @ref glfwHideWindow, shown using @ref
|
||||
glfwShowWindow and created initially hidden with the `GLFW_VISIBLE` window hint.
|
||||
This allows for off-screen rendering in a way compatible with most drivers, as
|
||||
well as moving a window to a specific position before showing it.
|
||||
|
||||
|
||||
@subsection news_30_undecorated Undecorated windows
|
||||
|
||||
Windowed mode windows can now be created without decorations, i.e. things like
|
||||
a frame, a title bar, with the `GLFW_DECORATED` window hint. This allows for
|
||||
the creation of things like splash screens.
|
||||
|
||||
|
||||
@subsection news_30_keymods Modifier key bit masks
|
||||
|
||||
[Modifier key bit mask](@ref mods) parameters have been added to the
|
||||
[mouse button](@ref GLFWmousebuttonfun) and [key](@ref GLFWkeyfun) callbacks.
|
||||
|
||||
|
||||
@subsection news_30_scancode Platform-specific scancodes
|
||||
|
||||
A scancode parameter has been added to the [key callback](@ref GLFWkeyfun). Keys
|
||||
that don't have a [key token](@ref keys) still get passed on with the key
|
||||
parameter set to `GLFW_KEY_UNKNOWN`. These scancodes will vary between machines
|
||||
and are intended to be used for key bindings.
|
||||
|
||||
|
||||
@subsection news_30_jsname Joystick names
|
||||
|
||||
The name of a joystick can now be retrieved using @ref glfwGetJoystickName.
|
||||
|
||||
|
||||
@subsection news_30_doxygen Doxygen documentation
|
||||
|
||||
You are reading it.
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,308 @@
|
||||
/*!
|
||||
|
||||
@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 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).
|
||||
|
||||
|
||||
@section quick_include Including the GLFW header
|
||||
|
||||
In the files of your program where you use OpenGL or GLFW, you need to include
|
||||
the GLFW 3 header file.
|
||||
|
||||
@code
|
||||
#include <GLFW/glfw3.h>
|
||||
@endcode
|
||||
|
||||
This defines all the constants, types and function prototypes of the GLFW API.
|
||||
It also includes the OpenGL header, and defines all the constants and types
|
||||
necessary for it to work on your platform.
|
||||
|
||||
For example, under Windows you are normally required to include `windows.h`
|
||||
before including `GL/gl.h`. This would make your source file tied to Windows
|
||||
and pollute your code's namespace with the whole Win32 API.
|
||||
|
||||
Instead, the GLFW header takes care of this for you, not by including
|
||||
`windows.h`, but rather by itself duplicating only the necessary parts of it.
|
||||
It does this only where needed, so if `windows.h` *is* included, the GLFW header
|
||||
does not try to redefine those symbols.
|
||||
|
||||
In other words:
|
||||
|
||||
- Do *not* include the OpenGL headers yourself, as GLFW does this for you
|
||||
- Do *not* include `windows.h` or other platform-specific headers unless
|
||||
you plan on using those APIs directly
|
||||
- If you *do* need to include such headers, do it *before* including the
|
||||
GLFW one and it will detect this
|
||||
|
||||
Starting with version 3.0, the GLU header `glu.h` is no longer included by
|
||||
default. If you wish to include it, define `GLFW_INCLUDE_GLU` before the
|
||||
inclusion of the GLFW header.
|
||||
|
||||
@code
|
||||
#define GLFW_INCLUDE_GLU
|
||||
#include <GLFW/glfw3.h>
|
||||
@endcode
|
||||
|
||||
|
||||
@section 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.
|
||||
|
||||
@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.
|
||||
|
||||
@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
|
||||
functions that require it.
|
||||
|
||||
|
||||
@section 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
|
||||
description to `stderr`.
|
||||
|
||||
@code
|
||||
void error_callback(int error, const char* description)
|
||||
{
|
||||
fputs(description, stderr);
|
||||
}
|
||||
@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.
|
||||
|
||||
@code
|
||||
glfwSetErrorCallback(error_callback);
|
||||
@endcode
|
||||
|
||||
|
||||
@section 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:
|
||||
|
||||
@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.
|
||||
|
||||
@code
|
||||
if (!window)
|
||||
{
|
||||
glfwTerminate();
|
||||
exit(EXIT_FAILURE);
|
||||
}
|
||||
@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.
|
||||
|
||||
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.
|
||||
|
||||
@code
|
||||
glfwDestroyWindow(window);
|
||||
@endcode
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
@code
|
||||
glfwMakeContextCurrent(window);
|
||||
@endcode
|
||||
|
||||
|
||||
@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.
|
||||
|
||||
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.
|
||||
Note that **the window isn't actually closed**, so you are expected to monitor
|
||||
this flag and either destroy the window or give some kind of feedback to the
|
||||
user.
|
||||
|
||||
@code
|
||||
while (!glfwWindowShouldClose(window))
|
||||
{
|
||||
// Keep running
|
||||
}
|
||||
@endcode
|
||||
|
||||
You can be notified when user is attempting to close the window by setting
|
||||
a close callback with @ref glfwSetWindowCloseCallback. The callback will be
|
||||
called immediately after the close flag has been set.
|
||||
|
||||
You can also set it yourself with @ref glfwSetWindowShouldClose. This can be
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
@code
|
||||
static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
|
||||
{
|
||||
if (key == GLFW_KEY_ESCAPE && action == GLFW_PRESS)
|
||||
glfwSetWindowShouldClose(window, GL_TRUE);
|
||||
}
|
||||
@endcode
|
||||
|
||||
For event callbacks to actually be called when an event occurs, you need to
|
||||
process events as described below.
|
||||
|
||||
|
||||
@section 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.
|
||||
|
||||
@code
|
||||
int width, height;
|
||||
glfwGetFramebufferSize(window, &width, &height);
|
||||
glViewport(0, 0, width, height);
|
||||
@endcode
|
||||
|
||||
However, 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
|
||||
|
||||
|
||||
@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.
|
||||
|
||||
@code
|
||||
double time = glfwGetTime();
|
||||
@endcode
|
||||
|
||||
|
||||
@section quick_swap_buffers Swapping buffers
|
||||
|
||||
GLFW windows always 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.
|
||||
|
||||
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.
|
||||
|
||||
@code
|
||||
glfwSwapBuffers(window);
|
||||
@endcode
|
||||
|
||||
|
||||
@section 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.
|
||||
|
||||
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.
|
||||
|
||||
@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
|
||||
|
||||
|
||||
@section quick_example Putting it together: A small GLFW application
|
||||
|
||||
Now that you know how to initialize GLFW, create a window and poll for
|
||||
keyboard input, it's possible to create a simple program.
|
||||
|
||||
@snippet simple.c code
|
||||
|
||||
This program creates a 640 by 480 windowed mode window and runs a loop clearing
|
||||
the screen, rendering a triangle and processing events until the user closes the
|
||||
window. It can be found in the source distribution as `examples/simple.c`, and
|
||||
is by default compiled along with all other examples when you build GLFW.
|
||||
|
||||
To learn more about how to compile and link programs that use GLFW, see
|
||||
@ref build.
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,496 @@
|
||||
/*!
|
||||
|
||||
@page window Window handling guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@section window_object Window handles
|
||||
|
||||
The @ref GLFWwindow object encapsulates both a window and a context. They are
|
||||
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
|
||||
@ref glfwTerminate, if any remain). As the window and context are inseparably
|
||||
linked, the object pointer is used as both a context and window handle.
|
||||
|
||||
|
||||
@section 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:
|
||||
|
||||
@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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
@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.
|
||||
|
||||
For more control over how the window and its context are created, see @ref
|
||||
window_hints below.
|
||||
|
||||
|
||||
@section window_destruction Window destruction
|
||||
|
||||
When you are done with the window, destroy it with the @ref glfwDestroyWindow
|
||||
function.
|
||||
|
||||
@code
|
||||
glfwDestroyWindow(window);
|
||||
@endcode
|
||||
|
||||
Once this function is called, no more events will be delivered for that window
|
||||
and its handle becomes invalid.
|
||||
|
||||
|
||||
@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 modified by GLFW throughout
|
||||
the life-time of the window.
|
||||
|
||||
|
||||
@section 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
|
||||
context. These hints are set to their default values each time the library is
|
||||
initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint
|
||||
and reset all at once to their defaults with @ref glfwDefaultWindowHints.
|
||||
|
||||
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
|
||||
|
||||
Some window hints are hard constraints. These must match the available
|
||||
capabilities *exactly* for window and context creation to succeed. Hints
|
||||
that are not hard constraints are matched as closely as possible, but the
|
||||
resulting window and context may differ from what these hints requested. To
|
||||
find out the actual attributes of the created window and context, use the
|
||||
@ref glfwGetWindowAttrib function.
|
||||
|
||||
The following hints are hard constraints:
|
||||
- `GLFW_STEREO`
|
||||
- `GLFW_CLIENT_API`
|
||||
|
||||
The following additional hints are hard constraints if requesting an OpenGL
|
||||
context:
|
||||
- `GLFW_OPENGL_FORWARD_COMPAT`
|
||||
- `GLFW_OPENGL_PROFILE`
|
||||
|
||||
Hints that do not apply to a given type of window or context are ignored.
|
||||
|
||||
|
||||
@subsection window_hints_wnd Window related hints
|
||||
|
||||
The `GLFW_RESIZABLE` hint specifies whether the 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 window will be initially
|
||||
visible. This hint is ignored for full screen windows.
|
||||
|
||||
The `GLFW_DECORATED` hint specifies whether the 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.
|
||||
|
||||
|
||||
@subsection 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.
|
||||
|
||||
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.
|
||||
|
||||
The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary
|
||||
buffers.
|
||||
|
||||
The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering.
|
||||
|
||||
The `GLFW_SAMPLES` hint specifies the desired number of samples to use for
|
||||
multisampling. Zero disables multisampling.
|
||||
|
||||
The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be
|
||||
sRGB capable.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@subsection window_hints_ctx Context 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`.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
For OpenGL ES, these hints are hard constraints.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
|
||||
a robustness strategy.
|
||||
|
||||
|
||||
@subsection 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_RED_BITS` | 8 | 0 to `INT_MAX` |
|
||||
| `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` |
|
||||
| `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` |
|
||||
| `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` |
|
||||
| `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` |
|
||||
| `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` |
|
||||
| `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` |
|
||||
| `GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` |
|
||||
| `GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` |
|
||||
| `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` |
|
||||
| `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` |
|
||||
| `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` |
|
||||
| `GLFW_REFRESH_RATE` | 0 | 0 to `INT_MAX` |
|
||||
| `GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
||||
| `GLFW_SRGB_CAPABLE` | `GL_FALSE` | `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_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
|
||||
|
||||
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.
|
||||
The window is however not actually destroyed and, unless you watch for this
|
||||
state change, nothing further happens.
|
||||
|
||||
The current state of the close flag is returned by @ref glfwWindowShouldClose
|
||||
and can be set or cleared directly with @ref glfwSetWindowShouldClose. A common
|
||||
pattern is to use the close flag as a main loop condition.
|
||||
|
||||
@code
|
||||
while (!glfwWindowShouldClose(window))
|
||||
{
|
||||
render(window);
|
||||
|
||||
glfwSwapBuffers(window);
|
||||
glfwPollEvents();
|
||||
}
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@code
|
||||
void window_close_callback(GLFWwindow* window)
|
||||
{
|
||||
if (!time_to_close)
|
||||
glfwSetWindowShouldClose(window, GL_FALSE);
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@section window_size Window 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.
|
||||
|
||||
@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.
|
||||
|
||||
@code
|
||||
glfwSetWindowSizeCallback(window, window_size_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the new size of the client area of the window.
|
||||
|
||||
@code
|
||||
void window_size_callback(GLFWwindow* window, int width, int height)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
There is also @ref glfwGetWindowSize for directly retrieving the current size of
|
||||
a window.
|
||||
|
||||
@code
|
||||
int width, height;
|
||||
glfwGetWindowSize(window, &width, &height);
|
||||
@endcode
|
||||
|
||||
|
||||
@section window_fbsize Window 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
|
||||
and not screen coordinates. On some platforms screen coordinates and pixels are
|
||||
the same, but this is not the case on all platforms supported by GLFW. There is
|
||||
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
|
||||
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.
|
||||
|
||||
@code
|
||||
void framebuffer_size_callback(GLFWwindow* window, int width, int height)
|
||||
{
|
||||
glViewport(0, 0, width, height);
|
||||
}
|
||||
@endcode
|
||||
|
||||
There is also @ref glfwGetFramebufferSize for directly retrieving the current
|
||||
size of the framebuffer of a window.
|
||||
|
||||
@code
|
||||
int width, height;
|
||||
glfwGetFramebufferSize(window, &width, &height);
|
||||
glViewport(0, 0, width, height);
|
||||
@endcode
|
||||
|
||||
Note that the size of a framebuffer may change independently of the size of
|
||||
a window, for example if the window is dragged between a regular monitor and
|
||||
a high-DPI one.
|
||||
|
||||
|
||||
@section window_pos Window 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.
|
||||
|
||||
@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.
|
||||
|
||||
@code
|
||||
glfwSetWindowPosCallback(window, window_pos_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the new position of the upper-left corner of its
|
||||
client area.
|
||||
|
||||
@code
|
||||
void window_size_callback(GLFWwindow* window, int xpos, int ypos)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
There is also @ref glfwGetWindowPos for directly retrieving the current position
|
||||
of the client area of the window.
|
||||
|
||||
@code
|
||||
int xpos, ypos;
|
||||
glfwGetWindowPos(window, &xpos, &ypos);
|
||||
@endcode
|
||||
|
||||
|
||||
@section window_title Window 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.
|
||||
|
||||
@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.
|
||||
|
||||
@code
|
||||
glfwSetWindowTitle(window, "さよなら絶望先生");
|
||||
@endcode
|
||||
|
||||
|
||||
@section window_attribs Window 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.
|
||||
|
||||
@code
|
||||
if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
|
||||
{
|
||||
// window has input focus
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection window_attribs_window Window attributes
|
||||
|
||||
The `GLFW_FOCUSED` attribute indicates whether the specified window currently
|
||||
has input focus.
|
||||
|
||||
The `GLFW_ICONIFIED` attribute indicates whether the specified window is
|
||||
currently 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.
|
||||
|
||||
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.
|
||||
|
||||
The `GLFW_DECORATED` attribute 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.
|
||||
|
||||
|
||||
@subsection window_attribs_context Context 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`.
|
||||
|
||||
The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
|
||||
`GLFW_CONTEXT_REVISION` attributes 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.
|
||||
|
||||
The `GLFW_OPENGL_DEBUG_CONTEXT` attribute 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@section window_swap Swapping buffers
|
||||
|
||||
GLFW windows are always double buffered. 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.
|
||||
|
||||
When the entire frame has been rendered, it is time to swap the back and the
|
||||
front buffers in order to display what has been rendered and begin rendering
|
||||
a new frame. This is done with @ref glfwSwapBuffers.
|
||||
|
||||
@code
|
||||
glfwSwapBuffers(window);
|
||||
@endcode
|
||||
|
||||
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:
|
||||
|
||||
@code
|
||||
glfwSwapInterval(1);
|
||||
@endcode
|
||||
|
||||
If the interval is zero, the swap will take place immediately when @ref
|
||||
glfwSwapBuffers is called without waiting for a refresh. Otherwise at least
|
||||
interval retraces will pass between each buffer swap. Using a swap interval of
|
||||
zero can be useful for benchmarking purposes, when it is not desirable to
|
||||
measure the time it takes to wait for the vertical retrace. However, a swap
|
||||
interval of one lets you avoid tearing.
|
||||
|
||||
Note that this may not work on all machines, as some drivers have
|
||||
user-controlled settings that override any swap interval the application
|
||||
requests. It is also by default disabled on Windows Vista and later when using
|
||||
DWM (Aero), as using it there sometimes leads to severe jitter. You can
|
||||
forcibly enable it for machines using DWM using @ref compile_options_win32.
|
||||
|
||||
*/
|
||||
Reference in New Issue
Block a user