Zengtudor/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2025-10-31 12:42:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work.

Browse Source 
Fixes #276.
This commit is contained in:
Camilla Berglund 2014-04-23 13:30:11 +02:00
parent a7b9deb2ca
commit e8e05d462c
15 changed files with 1036 additions and 426 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/Doxyfile.in
View File

@ -657,13 +657,15 @@ INPUT = @GLFW_INTERNAL_DOCS@ \
@GLFW_SOURCE_DIR@/include/GLFW/glfw3native.h \ @GLFW_SOURCE_DIR@/include/GLFW/glfw3native.h \
@GLFW_SOURCE_DIR@/docs/main.dox \ @GLFW_SOURCE_DIR@/docs/main.dox \
@GLFW_SOURCE_DIR@/docs/news.dox \ @GLFW_SOURCE_DIR@/docs/news.dox \
@GLFW_SOURCE_DIR@/docs/quick.dox \
@GLFW_SOURCE_DIR@/docs/moving.dox \ @GLFW_SOURCE_DIR@/docs/moving.dox \
@GLFW_SOURCE_DIR@/docs/quick.dox \
@GLFW_SOURCE_DIR@/docs/compile.dox \ @GLFW_SOURCE_DIR@/docs/compile.dox \
@GLFW_SOURCE_DIR@/docs/build.dox \ @GLFW_SOURCE_DIR@/docs/build.dox \
@GLFW_SOURCE_DIR@/docs/intro.dox \
@GLFW_SOURCE_DIR@/docs/context.dox \ @GLFW_SOURCE_DIR@/docs/context.dox \
@GLFW_SOURCE_DIR@/docs/monitor.dox \ @GLFW_SOURCE_DIR@/docs/monitor.dox \
@GLFW_SOURCE_DIR@/docs/window.dox \ @GLFW_SOURCE_DIR@/docs/window.dox \
@GLFW_SOURCE_DIR@/docs/input.dox \
@GLFW_SOURCE_DIR@/docs/compat.dox @GLFW_SOURCE_DIR@/docs/compat.dox
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files

163
docs/build.dox
View File

@ -9,28 +9,33 @@ 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 For information on how to compile the GLFW library itself, see the @ref compile
guide. guide.
This is not a tutorial on compilation. It assumes basic understanding of how to
compile a C program as well as how to use the specific compiler of your chosen
development environment. The compilation process should be explained in your
C programming material and the use of and options for your compiler should be
described in detail in the documentation for your development environment.
@section build_include Including the GLFW header file @section build_include Including the GLFW header file
In the files of your program where you use OpenGL or GLFW, you should include In the files of your program where you use OpenGL or GLFW, you should include
the GLFW 3 header file, i.e.: the GLFW header file, i.e.:
@code @code
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode @endcode
This defines all the constants, types and function prototypes of the GLFW API. The GLFW header declares the GLFW API and by default also includes the OpenGL
It also includes the chosen client API header files (by default OpenGL), and header of your development environment, which in turn defines all the constants,
defines all the constants and types necessary for those headers to work on that types and function prototypes of the OpenGL API.
platform.
For example, under Windows you are normally required to include `windows.h` The GLFW header also defines everything necessary for your OpenGL header to
before including `GL/gl.h`. This would make your source file tied to Windows function. For example, under Windows you are normally required to include
and pollute your code's namespace with the whole Win32 API. `windows.h` before the OpenGL header. This would make your source file tied
to Windows and pollute your code's namespace with the whole Win32 API.
Instead, the GLFW header takes care of this for you, not by including 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. `windows.h`, but by duplicating only the very few necessary parts of it. It
It does this only where needed, so if `windows.h` *is* included, the GLFW header does this only when needed, so if `windows.h` *is* included, the GLFW header
does not try to redefine those symbols. does not try to redefine those symbols.
In other words: In other words:
@ -42,17 +47,20 @@ In other words:
the GLFW one and it will detect this the GLFW one and it will detect this
If you are using an OpenGL extension loading library such as If you are using an OpenGL extension loading library such as
[GLEW](http://glew.sourceforge.net/), the GLEW header should also be included [glad](https://github.com/Dav1dde/glad), the extension loader header should
*before* the GLFW one. The GLEW header defines macros that disable any OpenGL either be included *before* the GLFW one, or the `GLFW_INCLUDE_NONE` macro
header that the GLFW header includes and GLEW will work as expected. (described below) should be defined.
@subsection build_macros GLFW header option macros @subsection build_macros GLFW header option macros
These macros may be defined before the inclusion of the GLFW header and affect 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 its behavior.
or OpenGL ES headers mentioned below. These are provided by your development
environment or your OpenGL or OpenGL ES SDK. `GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler
that the GLFW functions are defined in a DLL.
The following macros control which client API header is included.
`GLFW_INCLUDE_GLCOREARB` makes the header include the modern `GL/glcorearb.h` `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. header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL header.
@ -66,25 +74,43 @@ header instead of the regular OpenGL header.
`GLFW_INCLUDE_ES3` makes the header include the OpenGL ES 3.0 `GLES3/gl3.h` `GLFW_INCLUDE_ES3` makes the header include the OpenGL ES 3.0 `GLES3/gl3.h`
header instead of the regular OpenGL header. header instead of the regular OpenGL header.
`GLFW_INCLUDE_NONE` makes the header not include any client API header. `GLFW_INCLUDE_ES31` makes the header include the OpenGL ES 3.1 `GLES3/gl31.h`
header instead of the regular OpenGL header.
`GLFW_INCLUDE_NONE` makes the header not include any client API header. This is
useful in combination with an extension loading library.
If none of the above inclusion macros are defined, the standard OpenGL header is
included.
`GLFW_INCLUDE_GLU` makes the header include the GLU header *in addition to* the `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 header selected above. This should only be used with legacy code. GLU has been
(`OpenGL/gl.h` on OS X), i.e. if you are not using any of the above macros. deprecated and should not be used in new code.
`GLFW_DLL` is necessary when using the GLFW DLL on Windows, in order to explain @note GLFW does not provide any of the API headers mentioned above. They must
to the compiler that the GLFW functions will be coming from another executable. be provided by your development environment or your OpenGL or OpenGL ES SDK.
It has no function on other platforms.
@section build_link Link with the right libraries @section build_link Link with the right libraries
This section assumes basic understanding of how to link a C/C++ program as well GLFW is essentially a wrapper of various platform-specific APIs and therefore
as how to use the specific linker of your chosen development environment. needs to link against many different system libraries. If you are using GLFW as
**This is not a tutorial on linking.** The linking process should be explained a shared library / dynamic library / DLL then it takes care of these links.
in your C/C++ programming material and the use and options for your linker However, if you are using GLFW as a static library then your executable will
should be described in detail in the documentation for your development need to link against these libraries.
environment. A good general introduction to linking is
On Windows and OS X, the list of system libraries is static and can be
hard-coded into your build environment. See the section for your development
environment below. On Linux and other Unix-like operating systems, the list
varies but can be retrieved in various ways as described below.
This is not a tutorial on linking. It assumes basic understanding of how to
link a C program as well as how to use the specific linker of your chosen
development environment. The linking process should be explained in your
C programming material and the use of and options for your linker should be
described in detail in the documentation for your development environment.
A good general introduction to linking is
[Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by [Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by
David Drysdale. David Drysdale.
@ -112,31 +138,39 @@ OpenGL and `glu32` if it uses GLU.
@subsection build_link_cmake_source With CMake and GLFW source @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 With just a few changes to your `CMakeLists.txt` you can have the GLFW source
way, GLFW will be built along with your application as needed. tree built along with your application.
Firstly, add the root directory of the GLFW source tree to your project. This 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. will add the `glfw` target and the necessary cache variables to your project.
@code{.cmake}
add_subdirectory(path/to/glfw) add_subdirectory(path/to/glfw)
@endcode
To be able to include the GLFW header from your code, you need to tell the To be able to include the GLFW header from your code, you need to tell the
compiler where to find it. compiler where to find it.
@code{.cmake}
include_directories(path/to/glfw/include) include_directories(path/to/glfw/include)
@endcode
Once GLFW has been added to the project, the `GLFW_LIBRARIES` cache variable 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 contains all link-time dependencies of GLFW as it is currently configured. To
link against GLFW, link against them and the `glfw` target. link against GLFW, link against them and the `glfw` target.
@code{.cmake}
target_link_libraries(myapp glfw ${GLFW_LIBRARIES}) target_link_libraries(myapp glfw ${GLFW_LIBRARIES})
@endcode
Note that `GLFW_LIBRARIES` does not include GLU, as GLFW does not use it. If 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 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 `OPENGL_glu_LIBRARY` cache variable, which is implicitly created when the GLFW
CMake files look for OpenGL. CMake files look for OpenGL.
@code{.cmake}
target_link_libraries(myapp glfw ${OPENGL_glu_LIBRARY} ${GLFW_LIBRARIES}) target_link_libraries(myapp glfw ${OPENGL_glu_LIBRARY} ${GLFW_LIBRARIES})
@endcode
@subsection build_link_cmake_pkgconfig With CMake on Unix and installed GLFW binaries @subsection build_link_cmake_pkgconfig With CMake on Unix and installed GLFW binaries
@ -147,56 +181,83 @@ 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 First you need to find the PkgConfig package. If this fails, you may need to
install the pkg-config package for your distribution. install the pkg-config package for your distribution.
@code{.cmake}
find_package(PkgConfig REQUIRED) find_package(PkgConfig REQUIRED)
@endcode
This creates the CMake commands to find pkg-config packages. Then you need to This creates the CMake commands to find pkg-config packages. Then you need to
find the GLFW package. find the GLFW package.
@code{.cmake}
pkg_search_module(GLFW REQUIRED glfw3) pkg_search_module(GLFW REQUIRED glfw3)
@endcode
This creates the CMake variables you need to use GLFW. To be able to include 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. the GLFW header, you need to tell your compiler where it is.
@code{.cmake}
include_directories(${GLFW_INCLUDE_DIRS}) include_directories(${GLFW_INCLUDE_DIRS})
@endcode
You also need to link against the correct libraries. If you are using the You also need to link against the correct libraries. If you are using the
shared library version of GLFW, use the `GLFW_LIBRARIES` variable. shared library version of GLFW, use the `GLFW_LIBRARIES` variable.
@code{.cmake}
target_link_libraries(simple ${GLFW_LIBRARIES}) target_link_libraries(simple ${GLFW_LIBRARIES})
@endcode
If you are using the static library version of GLFW, use the If you are using the static library version of GLFW, use the
`GLFW_STATIC_LIBRARIES` variable instead. `GLFW_STATIC_LIBRARIES` variable instead.
@code{.cmake}
target_link_libraries(simple ${GLFW_STATIC_LIBRARIES}) target_link_libraries(simple ${GLFW_STATIC_LIBRARIES})
@endcode
@subsection build_link_pkgconfig With pkg-config on OS X or other Unix @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/), 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 and the `glfw3.pc` pkf-config file is generated when the GLFW library is built
along with it. and is installed along with it. A pkg-config file describes all necessary
compile-time and link-time flags and dependencies needed to use a library. When
they are updated or if they differ between systems, you will get the correct
ones automatically.
A typical compile and link command-line when using the static may look like this: A typical compile and link command-line when using the static version of the
GLFW library may look like this:
@code{.sh}
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3` cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
@endcode
If you are using the shared library, simply omit the `--static` flag. If you are using the shared version of the GLFW library, simply omit the
`--static` flag.
@code{.sh}
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3` cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
@endcode
You can also use the `glfw3.pc` file without installing it first, by using the You can also use the `glfw3.pc` file without installing it first, by using the
`PKG_CONFIG_PATH` environment variable. `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` @code{.sh}
env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
@endcode
The dependencies do not include GLU, as GLFW does not need it. On OS X, GLU is 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 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 anything extra. If you need GLU and are using Linux or BSD, you should add the
`-lGLU` to your link flags. `glu` pkg-config module.
See the manpage and other documentation for pkg-config and your compiler and @code{.sh}
linker for more information on how to link programs. cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
@endcode
If you are using the static version of the GLFW library, make sure you don't link statically against GLU.
@code{.sh}
cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`
@endcode
@subsection build_link_xcode With Xcode on OS X @subsection build_link_xcode With Xcode on OS X
@ -205,19 +266,29 @@ If you are using the dynamic library version of GLFW, simply add it to the
project dependencies. project dependencies.
If you are using the static library version of GLFW, add it and the Cocoa, 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. OpenGL, IOKit and CoreVideo frameworks to the project as dependencies. They can
all be found in `/System/Library/Frameworks`.
@subsection build_link_osx With command-line on OS X @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 It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when
and libraries to your command-line using the `-l` and `-framework` switches, building from the command line on OS X. That way you will get any new
i.e.: dependencies added automatically. If you still wish to build manually, you need
to add the required frameworks and libraries to your command-line yourself using
the `-l` and `-framework` switches.
If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do:
@code{.sh}
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
@endcode
Note that you do not add the `.framework` extension to a framework when adding If you are using the static library, named `libglfw3.a`, substitute `-lglfw3`
it from the command-line. for `-lglfw`.
Note that you do not add the `.framework` extension to a framework when linking
against it from the command-line.
The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing 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 special to do when using GLU. Also note that even though your machine may have

8
docs/compat.dox
View File

@ -76,8 +76,8 @@ support. If the running X server does not support either or both of these
extensions, gamma ramp support will not function. extensions, gamma ramp support will not function.
GLFW requires the Xkb extension with detectable auto-repeat to provide keyboard GLFW requires the Xkb extension with detectable auto-repeat to provide keyboard
input. If the running X server does not support this extension and detectable input. If the running X server does not support this extension, a non-Xkb
auto-repeat, `glfwInit` will fail. fallback path is used.
@section compat_glx GLX extensions @section compat_glx GLX extensions
@ -85,9 +85,7 @@ The GLX API is the default API used to create OpenGL contexts on Unix-like
systems using the X Window System. systems using the X Window System.
GLFW uses the `GLXFBConfig` API to enumerate and select framebuffer pixel 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` formats. This requires GLX 1.3 or greater.
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 GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization `GLX_SGI_swap_control` extensions to provide vertical retrace synchronization

5
docs/compile.dox
View File

@ -124,7 +124,7 @@ destination for binaries. Choose *Configure*, change any options you wish to,
The CMake files for GLFW provide a number of options, although not all are 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 available on all supported platforms. Some of these are de facto standards
among CMake users and so have no `GLFW_` prefix. among projects using CMake and so have no `GLFW_` prefix.
If you are using the GUI version of CMake, these are listed and can be changed 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. from there. If you are using the command-line version, use the `ccmake` tool.
@ -219,6 +219,7 @@ ramps and clipboard. The options are:
- `_GLFW_COCOA` to use the Cocoa frameworks - `_GLFW_COCOA` to use the Cocoa frameworks
- `_GLFW_WIN32` to use the Win32 API - `_GLFW_WIN32` to use the Win32 API
- `_GLFW_X11` to use the X Window System - `_GLFW_X11` to use the X Window System
- `_GLFW_WAYLAND` to use the Wayland API (experimental and incomplete)
The context creation API is used to enumerate pixel formats / framebuffer The context creation API is used to enumerate pixel formats / framebuffer
configurations and to create contexts. The options are: configurations and to create contexts. The options are:
@ -226,7 +227,7 @@ configurations and to create contexts. The options are:
- `_GLFW_NSGL` to use the Cocoa OpenGL framework - `_GLFW_NSGL` to use the Cocoa OpenGL framework
- `_GLFW_WGL` to use the Win32 WGL API - `_GLFW_WGL` to use the Win32 WGL API
- `_GLFW_GLX` to use the X11 GLX API - `_GLFW_GLX` to use the X11 GLX API
- `_GLFW_EGL` to use the EGL API (experimental) - `_GLFW_EGL` to use the EGL API
The client library is the one providing the OpenGL or OpenGL ES API, which is 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 used by GLFW to probe the created context. This is not the same thing as the

160
docs/context.dox
View File

@ -6,15 +6,16 @@
The primary purpose of GLFW is to provide a simple interface to window The primary purpose of GLFW is to provide a simple interface to window
management and OpenGL and OpenGL ES context creation. GLFW supports management and OpenGL and OpenGL ES context creation. GLFW supports
multiple windows, each of which has its own context. multiple windows, with each window having its own context.
@section context_object Context handles @section context_object Context handles
The @ref GLFWwindow object encapsulates both a window and a context. They are The @ref GLFWwindow object encapsulates both a [window](@ref window) and
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or a context. It is created with @ref glfwCreateWindow and destroyed with @ref
@ref glfwTerminate, if any remain). As the window and context are inseparably glfwDestroyWindow or @ref glfwTerminate. As the window and context are
linked, the object pointer is used as both a context and window handle. inseparably linked, the object pointer is used as both a context and window
handle.
@section context_hints Context creation hints @section context_hints Context creation hints
@ -27,21 +28,19 @@ what kind of context is created. See
@section context_sharing Context object sharing @section context_sharing Context object sharing
When creating a window and context with @ref glfwCreateWindow, you can specify 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 another window whose context the new one should share its objects with. Object
object sharing is implemented by the operating system and graphics driver and is sharing is implemented by the operating system and graphics driver and is
described in the OpenGL documentation. On platforms where it is possible to described in the OpenGL and OpenGL ES documentation. On platforms where it is
choose which types of objects are shared, GLFW requests that all are shared. possible to choose which types of objects are shared, GLFW requests that all are
shared.
@section context_current Current context @section context_current Current context
Before you can use the OpenGL or OpenGL ES APIs, you need to have a current Before you can make OpenGL or OpenGL ES calls, you need to have a current
context of the proper type. The context encapsulates all render state and all context of the proper type. The context encapsulates all render state and all
objects like textures and shaders. 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. A context is made current with @ref glfwMakeContextCurrent.
@code @code
@ -54,18 +53,23 @@ The current context is returned by @ref glfwGetCurrentContext.
GLFWwindow* window = glfwGetCurrentContext(); GLFWwindow* window = glfwGetCurrentContext();
@endcode @endcode
@note A context must only be current for a single thread at a time, and a thread
must only have a single context current at a time.
@section context_swap Swapping buffers @section context_swap Swapping buffers
See [swapping buffers](@ref window_swap) in the window handling guide. Buffer swapping is part of the window and framebuffer, not the context. See
@ref window_swap in the window handling guide.
@section context_glext OpenGL extension handling @section context_glext OpenGL and OpenGL ES extensions
One of the benefits of OpenGL is its extensibility. Independent hardware One of the benefits of OpenGL and OpenGL ES are their extensibility.
vendors (IHVs) may include functionality in their OpenGL implementations that Hardware vendors may include extensions in their implementations that extend the
expand upon the OpenGL standard before that functionality is included in a new API before that functionality is included in a new version of the OpenGL or
version of the OpenGL specification. OpenGL ES specification, and some extensions are never included and remain
as extensions until they become obsolete.
An extension is defined by: An extension is defined by:
@ -74,23 +78,105 @@ An extension is defined by:
- New OpenGL functions (e.g. `glGetDebugMessageLogARB`) - New OpenGL functions (e.g. `glGetDebugMessageLogARB`)
Note the `ARB` affix, which stands for Architecture Review Board and is used Note the `ARB` affix, which stands for Architecture Review Board and is used
for official extensions. There are many different affixes, depending on who for official extensions. The extension above was created by the ARB, but there
wrote the extension. A list of extensions, together with their specifications, are many different affixes, like `NV` for Nvidia and `AMD` for, well, AMD. Any
can be found at the [OpenGL Registry](http://www.opengl.org/registry/). group may also use the generic `EXT` affix. Lists of extensions, together with
their specifications, can be found at the
[OpenGL Registry](http://www.opengl.org/registry/) and
[OpenGL ES Registry](https://www.khronos.org/registry/gles/).
@subsection context_glext_auto Using an extension loader library
This is the easiest and best way to load extensions and newer versions of the
OpenGL or OpenGL ES API. One such library is
[glad](https://github.com/Dav1dde/glad) and there are several others. They will
take care of all the details of declaring and loading everything you need.
The following example will use glad, but other extension loader libraries work
similary.
First you need to generate the source files using the glad Python script. This
example generates a loader for any version of OpenGL, which is the default for
both GLFW and glad, but loaders for OpenGL ES, as well as loaders for specific
API versions and extension sets can be generated. The generated files are
written to the `output` directory.
@code{.sh}
python main.py --no-loader --out-path output
@endcode
@note The `--no-loader` option is used because GLFW already provides a function
for loading OpenGL and OpenGL ES function pointers and glad can use this instead
of having to add its own.
Add the generated `output/src/glad.c`, `output/include/glad/glad.h` and
`output/include/KHR/khrplatform.h` files to your build. Then you need to
include the glad header file, which will replace the OpenGL header of your
development environment.
@code
#include <glad/glad.h>
#include <GLFW/glfw3.h>
@endcode
Finally you need to initialize glad once you have a matching current context.
@code
window = glfwCreateWindow(640, 480, "My Window", NULL, NULL);
if (!window)
{
...
}
glfwMakeContextCurrent(window);
gladLoadGLLoader((GLADloadproc) glfwGetProcAddress);
@endcode
Once glad has been loaded, you have access to all OpenGL core and extension
functions supported by the context you created and you are ready to start
rendering.
You can specify a minimum required OpenGL or OpenGL ES version with
[context hints](@ref window_hints_ctx). If your needs are more complex, you can
check the actual OpenGL or OpenGL ES version with
[context attributes](@ref window_attribs_context), or you can check whether
a specific version is supported by the current context with the
`GLAD_GL_VERSION_x_x` booleans.
@code
if (GLAD_GL_VERSION_3_2)
{
// Call OpenGL 3.2+ specific code
}
@endcode
To check whether a specific extension is supported, use the `GLAD_GL_xxx`
booleans.
@code
if (GLAD_GL_ARB_debug_output)
{
// Use GL_ARB_debug_output
}
@endcode
@subsection context_glext_manual Loading extensions manually
To use a certain extension, you must first check whether the context supports 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 that extension and then, if it introduces new functions, retrieve the pointers
to those functions. to those functions. GLFW provides @ref glfwExtensionSupported and @ref
glfwGetProcAddress for manual loading of extensions and new API functions.
This can be done with GLFW, as will be described in this section, but usually @note It is strongly recommended that you use an existing extension loader
you will instead want to use a dedicated extension loading library such as library like [glad](https://github.com/Dav1dde/glad) instead of loading
[GLEW](http://glew.sourceforge.net/). This kind of library greatly reduces the manually. Extension loading is a solved problem and you will gain nothing from
amount of work necessary to use both OpenGL extensions and modern versions of solving it again by hand.
the OpenGL API. GLEW in particular has been extensively tested with and works
well with GLFW.
@subsection context_glext_header The glext.h header @subsubsection context_glext_header The glext.h header
The `glext.h` header is a continually updated file that defines the interfaces 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 for all OpenGL extensions. The latest version of this can always be found at
@ -101,11 +187,11 @@ you wish to use.
The header defines function pointer types for all functions of all extensions it The header defines function pointer types for all functions of all extensions it
supports. These have names like `PFNGLGETDEBUGMESSAGELOGARB` (for supports. These have names like `PFNGLGETDEBUGMESSAGELOGARB` (for
`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` and `PROC` `glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` (pointer
are added to the ends. to function) and `PROC` (procedure) are added to the ends.
@subsection context_glext_string Checking for extensions @subsubsection context_glext_string Checking for extensions
A given machine may not actually support the extension (it may have older 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 drivers or a graphics card that lacks the necessary hardware features), so it
@ -124,12 +210,12 @@ extension is supported, @ref glfwExtensionSupported returns non-zero, otherwise
it returns zero. it returns zero.
@subsection context_glext_proc Fetching function pointers @subsubsection context_glext_proc Fetching function pointers
Many extensions, though not all, require the use of new OpenGL functions. Many extensions, though not all, require the use of new OpenGL functions.
These entry points are often not exposed by your link libraries, making These functions often do not have entry points in the client API libraries of
it necessary to fetch them at run time. With @ref glfwGetProcAddress you can your operating system, making it necessary to fetch them at run time. You can
retrieve the address of extension and non-extension OpenGL functions. retreive pointers to these functions with @ref glfwGetProcAddress.
@code @code
PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog = glfwGetProcAddress("glGetDebugMessageLogARB"); PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog = glfwGetProcAddress("glGetDebugMessageLogARB");

13
docs/input.dox Normal file
View File

@ -0,0 +1,13 @@
/*!
@page input Input handling guide
@tableofcontents
@section input_key Keyboard input
@section input_mouse Mouse input
@section input_joy Joystick input
*/

12
docs/internal.dox
View File

@ -57,10 +57,10 @@ Examples: @ref _glfwIsValidContextConfig, @ref _GLFWwindow, `_glfw.currentRamp`
The platform interface implements all platform-specific operations as a service The platform interface implements all platform-specific operations as a service
to the public interface. This includes event processing. The platform to the public interface. This includes event processing. The platform
interface is never directly called by users of GLFW and never directly calls the interface is never directly called by application code and never directly calls
user's code. It is also prohibited from modifying the platform-independent part application-provided callbacks. It is also prohibited from modifying the
of the internal structs. Instead, it calls the event interface when events platform-independent part of the internal structs. Instead, it calls the event
interesting to GLFW are received. interface when events interesting to GLFW are received.
The platform interface mirrors those parts of the public interface that needs to 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 perform platform-specific operations on some or all platforms. The are also
@ -85,8 +85,8 @@ Examples: `window.win32.handle`, `_glfw.x11.display`
@section internals_event Event interface @section internals_event Event interface
The event interface is implemented in the same shared source files as the public 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, interface and is responsible for delivering the events it receives to the
either via callbacks, via window state changes or both. application, either via callbacks, via window state changes or both.
The function names of the event interface use a `_glfwInput` prefix and the The function names of the event interface use a `_glfwInput` prefix and the
ObjectEvent pattern. ObjectEvent pattern.

166
docs/intro.dox Normal file
View File

@ -0,0 +1,166 @@
/*!
@page intro Introduction to the GLFW API
@tableofcontents
This guide will introduce the basic concepts of GLFW and describes
initialization, error handling and version management. There are other guides
for the various areas of the GLFW API.
- @ref window
- @ref context
- @ref monitor
- @ref input
@section intro_init Initialization and termination
Before most GLFW functions may be called, the library must be initialized.
This initialization checks what features are available on the machine,
enumerates monitors and joysticks, initializes the timer and performs any
required platform-specific initialization.
Only the following functions may be called before the library has been
successfully initialized.
- @ref glfwGetVersion
- @ref glfwGetVersionString
- @ref glfwSetErrorCallback
- @ref glfwInit
- @ref glfwTerminate
Calling any other function before that time will cause a `GLFW_NOT_INITIALIZED`
error.
@subsection intro_init_init Initializing GLFW
The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an
error occurred.
@code
if (!glfwInit())
{
// Handle initialization failure
}
@endcode
If any part of initialization fails, all remaining bits are terminated as if
@ref glfwTerminate was called. The library only needs to be initialized once
and additional calls to an already initialized library will simply return
`GL_TRUE` immediately.
Once the library has been successfully initialized, it should be terminated
before the application exits.
@subsection intro_init_terminate Terminating GLFW
Before your application exits, you should terminate the GLFW library if it has
been initialized. This is done with @ref glfwTerminate.
@code
glfwTerminate();
@endcode
This will destroy any remaining window, monitor and cursor objects, restore any
modified gamma ramps, re-enable the screensaver if it had been disabled and free
any resources allocated by GLFW.
Once the library is terminated, it is as if it had never been initialized and
you will need to initialize it again before being able to use GLFW. If the
library had not been successfully initialized or had already been terminated,
additional calls return immediately.
@section intro_error Error handling
Some GLFW functions have return values that indicate an error, but this is often
not very helpful when trying to figure out *why* the error occurred. Also, far
from all GLFW functions have such return values.
This is where the error callback comes in. This callback is called whenever an
error occurs. It is set with @ref glfwSetErrorCallback, a function that may be
called before @ref glfwInit and after @ref glfwTerminate.
@code
glfwSetErrorCallback(error_callback);
@endcode
The error callback receives a human-readable description of the error and (when
possible) its cause. The description is a regular C string using the UTF-8
encoding. The callback is also provided with an [error code](@ref errors).
@code
void error_callback(int error, const char* description)
{
puts(description);
}
@endcode
The error code indicates the general category of the error. Some error codes,
such as `GLFW_NOT_INITIALIZED` has only a single meaning, whereas others like
`GLFW_PLATFORM_ERROR` are used for many different errors.
@note The description string is only valid until the error callback returns, as
it may have been generated specifically for that error. This lets GLFW provide
much more specific error descriptions but means you must make a copy if you want
to keep the description string.
@section intro_version Version management
GLFW provides mechanisms for identifying what version of GLFW your application
was compiled against as well as what version it is currently using. The GLFW
API is binary-compatible with later minor versions, i.e. an executable using the
3.0 API will be able to use a version 3.2 DLL.
As long as an executable does not use any newer functions, it can also use an
older minor version DLL, although any window hints or other tokens added since
that older version will cause errors to be reported.
@subsection intro_version_compile Compile-time version
The compile-time version of GLFW is provided by the GLFW header with the
`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.
@subsection intro_version_runtime Run-time version
The run-time version can be retrieved with @ref glfwGetVersion, a function that
may be called before @ref glfwInit and after @ref glfwTerminate
@code
int major, minor, revision;
glfwGetVersion(&major, &minor, &revision);
@endcode
@subsection intro_version_string Version string
GLFW 3 also provides a compile-time generated version string that describes the
version, platform, compiler and any platform-specific compile-time options.
This is primarily intended for submitting bug reports, to allow developers to
see which code paths are enabled in a binary.
The version string is returned by @ref glfwGetVersionString, a function that may
be called before @ref glfwInit and after @ref glfwTerminate.
The format of the string is as follows:
- The version of GLFW
- The name of the window system API
- The name of the context creation API
- Any additional options or APIs
For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
back ends, the version string may look something like this:
3.0.0 Win32 WGL MinGW
@note Do not parse the version string to find the GLFW library version. The
@ref glfwGetVersion function provides the version of the library binary in
numeric form.
*/

77
docs/monitor.dox
View File

@ -7,13 +7,25 @@
@section monitor_objects Monitor objects @section monitor_objects Monitor objects
The @ref GLFWmonitor object represents a currently connected monitor. A monitor object represents a currently connected monitor and is represented as
a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type
@ref GLFWmonitor. Monitor objects cannot be created or destroyed by the
application and retain their addresses until the monitors they represent are
disconnected or until the library is [terminated](@ref intro_init_terminate).
Each monitor has a human-readable name, a current video mode, a list of
supported video modes, a virtual position, an estimated physical size and
a gamma ramp.
The virtual position of a monitor is in screen coordinates and, together with
the current video mode, describes the viewports that the connected monitors
provide into the virtual desktop that spans them.
@section monitor_monitors Retrieving monitors @subsection monitor_monitors Retrieving monitors
The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is usually The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's
the user's preferred monitor and the one with global UI elements like task bar preferred monitor and is usually the one with global UI elements like task bar
or menu bar. or menu bar.
@code @code
@ -21,14 +33,20 @@ GLFWmonitor* primary = glfwGetPrimaryMonitor();
@endcode @endcode
You can retrieve all currently connected monitors with @ref glfwGetMonitors. You can retrieve all currently connected monitors with @ref glfwGetMonitors.
The primary monitor is always the first monitor in the returned array.
@code @code
int count; int count;
GLFWmonitor** monitors = glfwGetMonitors(&count); GLFWmonitor** monitors = glfwGetMonitors(&count);
@endcode @endcode
@note Monitors other than the primary monitor may be moved to a different index
in the array if another monitor is disconnected.
@section monitor_modes Retrieving video modes
@section monitor_properties Monitor properties
@subsection monitor_modes Video modes
Although GLFW generally does a good job at selecting a suitable video 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 mode for you when you open a full screen window, it is sometimes useful to
@ -49,9 +67,9 @@ const GLFWvidmode* mode = glfwGetVideoMode(monitor);
@endcode @endcode
@section monitor_size Monitor physical size @subsection monitor_size Physical size
The physical size in millimetres of a monitor, or an approximation of it, can be The physical size in millimetres of a monitor, or an estimation of it, can be
retrieved with @ref glfwGetMonitorPhysicalSize. retrieved with @ref glfwGetMonitorPhysicalSize.
@code @code
@ -67,28 +85,61 @@ const double dpi = mode->width / (widthMM / 25.4);
@endcode @endcode
@section monitor_name Monitor name @subsection monitor_pos Virtual position
The name of a monitor is returned by @ref glfwGetMonitorName. The position of the monitor on the virtual desktop, in screen coordinates, can
be retrieved with @ref glfwGetMonitorPos.
@code
int xpos, ypos;
glfwGetMonitorPos(monitor, &xpos, &ypos);
@endcode
@subsection monitor_name Human-readable name
The human-readable name of a monitor is returned by @ref glfwGetMonitorName.
It is a regular C string using the UTF-8 encoding.
@code @code
const char* name = glfwGetMonitorName(monitor); const char* name = glfwGetMonitorName(monitor);
@endcode @endcode
The monitor name is a regular C string using the UTF-8 encoding. Note that @note Monitor names are not guaranteed to be unique. Two monitors of the same
monitor names are not guaranteed to be unique. model and make may have the same name. Only the address of a monitor object is
guaranteed to be unique.
@section monitor_gamma Monitor gamma ramp @subsection monitor_gamma Gamma ramp
The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts 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. a monitor handle and a pointer to a @ref GLFWgammaramp structure.
@code @code
GLFWgammaramp ramp;
unsigned short red[256], green[256], blue[256];
ramp.size = 256;
ramp.red = red;
ramp.green = green;
ramp.blue = blue;
for (i = 0; i < ramp.size; i++)
{
// Fill out gamma ramp arrays as desired
}
glfwSetGammaRamp(monitor, &ramp); glfwSetGammaRamp(monitor, &ramp);
@endcode @endcode
The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. The gamma ramp data is copied before the function returns, so there is no need
to keep it around once the ramp has been set.
@note It is recommended to use gamma ramps of size 256, as that is the size
supported by virtually all graphics cards on all platforms.
The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. The
returned structure and its arrays are allocated and freed by GLFW.
@code @code
const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor); const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);

541
docs/moving.dox
View File

@ -7,19 +7,38 @@
This is a transition guide for moving from GLFW 2 to 3. It describes what has This is a transition guide for moving from GLFW 2 to 3. It describes what has
changed or been removed, but does *not* include changed or been removed, but does *not* include
[new features](@ref news) unless they are required when moving an existing code [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 base onto the new API. For example, the new multi-monitor functions are
required to create full screen windows with GLFW 3. required to create full screen windows with GLFW 3.
@section moving_removed Removed features @section moving_removed Changed and removed features
@subsection moving_threads Threading functions @subsection moving_renamed_files Renamed library and header file
The threading functions have been removed, including the sleep function. They The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to
were fairly primitive, under-used, poorly integrated and took time away from the avoid collisions with the headers of other major versions. Similarly, the GLFW
focus of GLFW (i.e. context, input and window). There are better threading 3 library is named `glfw3,` except when it's installed as a shared library on
libraries available and native threading support is available in both C++11 and Unix-like systems, where it uses the
C11, both of which are gaining traction. [soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`.
@par Old syntax
@code
#include <GL/glfw.h>
@endcode
@par New syntax
@code
#include <GLFW/glfw3.h>
@endcode
@subsection moving_threads Removal of threading functions
The threading functions have been removed, including the per-thread sleep
function. They were fairly primitive, under-used, poorly integrated and took
time away from the focus of GLFW (i.e. context, input and window). There are
better threading libraries available and native threading support is available
in both C++11 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 If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
support them, see the support them, see the
@ -30,30 +49,233 @@ threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
TinyCThread. TinyCThread.
However, GLFW 3 has better support for *use from multiple threads* than GLFW However, GLFW 3 has better support for *use from multiple threads* than GLFW
2 had. Contexts can be made current on and rendered with from secondary 2 had. Contexts can be made current on any thread, although only a single
threads, and the documentation explicitly states which functions may be used thread at a time, and the documentation explicitly states which functions may be
from secondary threads and which may only be used from the main thread, i.e. the used from any thread and which may only be used from the main thread.
thread that calls main.
@par Removed functions
`glfwSleep`, `glfwCreateThread`, `glfwDestroyThread`, `glfwWaitThread`,
`glfwGetThreadID`, `glfwCreateMutex`, `glfwDestroyMutex`, `glfwLockMutex`,
`glfwUnlockMutex`, `glfwCreateCond`, `glfwDestroyCond`, `glfwWaitCond`,
`glfwSignalCond`, `glfwBroadcastCond` and `glfwGetNumberOfProcessors`.
@subsection moving_image Image and texture loading @subsection moving_image Removal of image and texture loading
The image and texture loading functions have been removed. They only supported The image and texture loading functions have been removed. They only supported
the Targa image format, making them mostly useful for beginner level examples. 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 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 would need not only to support other formats, but also modern extensions to
OpenGL texturing facilities. This would either add a number of external OpenGL texturing. This would either add a number of external
dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions
of these libraries. of these libraries.
As there already are libraries doing this, it seems unnecessary both to As there already are libraries doing this, it is unnecessary both to duplicate
duplicate this work and to tie this duplicate to GLFW. Projects similar to the work and to tie the duplicate to GLFW. The resulting library would also be
GLFW, such as freeglut, could also gain from such a library. Also, would be no platform-independent, as both OpenGL and stdio are available wherever GLFW is.
platform-specific part of such a library, as both OpenGL and stdio are available
wherever GLFW is. @par Removed functions
`glfwReadImage`, `glfwReadMemoryImage`, `glfwFreeImage`, `glfwLoadTexture2D`,
`glfwLoadMemoryTexture2D` and `glfwLoadTextureImage2D`.
@subsection moving_char_up Character actions @subsection moving_stdcall Removal of 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 application programmers to remember, i.e. the
requirement to mark all callback functions with `GLFWCALL`. It also simplifies
the creation of DLLs and DLL link libraries, as there's no need to explicitly
disable `@n` entry point suffixes.
@par Old syntax
@code
void GLFWCALL callback_function(...);
@endcode
@par New syntax
@code
void callback_function(...);
@endcode
@subsection moving_window_handles Window handle parameters
Because GLFW 3 supports multiple windows, window handle parameters have been
added to all window-related GLFW functions and callbacks. The handle of
a newly created window is returned by @ref glfwCreateWindow (formerly
`glfwOpenWindow`). Window handles are pointers to the
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWwindow.
@par Old syntax
@code
glfwSetWindowTitle("New Window Title");
@endcode
@par New syntax
@code
glfwSetWindowTitle(window, "New Window Title");
@endcode
@subsection moving_monitor Explicit monitor selection
GLFW 3 provides support for multiple monitors. To request a full screen mode window,
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
window to use. The @ref glfwGetPrimaryMonitor function returns the monitor that
GLFW 2 would have selected, but there are many other
[monitor functions](@ref monitor). Monitor handles are pointers to the
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWmonitor.
@par Old basic full screen
@code
glfwOpenWindow(640, 480, 8, 8, 8, 0, 24, 0, GLFW_FULLSCREEN);
@endcode
@par New basic full screen
@code
window = glfwCreateWindow(640, 480, "My Window", glfwGetPrimaryMonitor(), NULL);
@endcode
@note The framebuffer bit depth parameters of `glfwOpenWindow` have been turned
into [window hints](@ref window_hints), but as they have been given
[sane defaults](@ref window_hints_values) you rarely need to set these hints.
@subsection moving_autopoll Removal of automatic event polling
GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
Unlike buffer swap, which acts on a single window, **glfwPollEvents** and
**glfwWaitEvents** process events for all windows at once.
@par Old basic main loop
@code
while (...)
{
// Process input
// Render output
glfwSwapBuffers();
}
@endcode
@par New basic main loop
@code
while (...)
{
// Process input
// Render output
glfwSwapBuffers(window);
glfwPollEvents();
}
@endcode
@subsection moving_context Explicit context management
Each GLFW 3 window has its own OpenGL context and only you, the application
programmer, can know which context should be current on which thread at any
given time. Therefore, GLFW 3 leaves that decision to you.
This means that you need to call @ref glfwMakeContextCurrent after creating
a window before you can call any OpenGL functions.
@subsection moving_hidpi Separation of window and framebuffer sizes
Window positions and sizes now use screen coordinates, which may not be the same
as pixels on machines with high-DPI monitors. This is important as OpenGL uses
pixels, not screen coordinates. For example, the rectangle specified with
`glViewport` needs to use pixels. Therefore, framebuffer size functions have
been added. You can retrieve the size of the framebuffer of a window with @ref
glfwGetFramebufferSize function. A framebuffer size callback has also been
added, which can be set with @ref glfwSetFramebufferSizeCallback.
@par Old basic viewport setup
@code
glfwGetWindowSize(&width, &height);
glViewport(0, 0, width, height);
@endcode
@par New basic viewport setup
@code
glfwGetFramebufferSize(window, &width, &height);
glViewport(0, 0, width, height);
@endcode
@subsection moving_window_close Window closing changes
The `GLFW_OPENED` window parameter has been removed. As long as the window has
not been destroyed, whether through @ref glfwDestroyWindow or @ref
glfwTerminate, the window is "open".
A user attempting to close a window is now just an event like any other. Unlike
GLFW 2, windows and contexts created with GLFW 3 will never be destroyed unless
you choose them to be. Each window now has a close flag that is set to
`GL_TRUE` when the user attempts to close that window. By default, nothing else
happens and the window stays visible. It is then up to you to either destroy
the window, take some other action or 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.
@par Old basic main loop
@code
while (glfwGetWindowParam(GLFW_OPENED))
{
...
}
@endcode
@par New basic main loop
@code
while (!glfwWindowShouldClose(window))
{
...
}
@endcode
The close callback no longer returns a value. Instead, it is called after the
close flag has been set so it can 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).
@par Old syntax
@code
int GLFWCALL window_close_callback(void);
@endcode
@par New syntax
@code
void window_close_callback(GLFWwindow* window);
@endcode
@note GLFW never clears the close flag to `GL_FALSE`, meaning you can use it
for other reasons to close the window as well, for example the user choosing
Quit from an in-game menu.
@subsection moving_hints Persistent window hints
The `glfwOpenWindowHint` function has been renamed to @ref glfwWindowHint.
Window hints are no longer reset to their default values on window creation, but
instead retain their values until modified by @ref glfwWindowHint or @ref
glfwDefaultWindowHints, or until the library is terminated and re-initialized.
@subsection moving_video_modes Video mode enumeration
Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function
now returns all available modes for a specific monitor instead of requiring you
to guess how large an array you need. The `glfwGetDesktopMode` function, which
had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
returns the current mode of a monitor.
@subsection moving_char_up Removal of character actions
The action parameter of the [character callback](@ref GLFWcharfun) has been 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 removed. This was an artefact of the origin of GLFW, i.e. being developed in
@ -61,29 +283,92 @@ English by a Swede. However, many keyboard layouts require more than one key to
produce characters with diacritical marks. Even the Swedish keyboard layout produce characters with diacritical marks. Even the Swedish keyboard layout
requires this for uncommon cases like ü. requires this for uncommon cases like ü.
Note that this is only the removal of the *action parameter* of the character @par Old syntax
callback, *not* the removal of the character callback itself. @code
void GLFWCALL character_callback(int character, int action);
@endcode
@par New syntax
@code
void character_callback(int character);
@endcode
@subsection moving_wheel Mouse wheel position @subsection moving_cursorpos Cursor position changes
The `glfwGetMouseWheel` function has been removed. Scroll events do not The `glfwGetMousePos` function has been renamed to @ref glfwGetCursorPos,
represent an absolute state, but is instead an interpretation of a relative `glfwSetMousePos` to @ref glfwSetCursorPos and `glfwSetMousePosCallback` to @ref
change in state, like character input. So, like character input, there is no glfwSetCursorPosCallback.
sane 'current state' to return. The mouse wheel callback has been replaced by
a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll The cursor position is now `double` instead of `int`, both for the direct
offsets. functions and for the callback. Some platforms can provide sub-pixel cursor
movement and this data is now passed on to the application where available. On
platforms where this is not provided, the decimal part is zero.
GLFW 3 only allows you to position the cursor within a window using @ref
glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
Unless the window is active, the function fails silently.
@subsection moving_stdcall GLFWCALL macro @subsection moving_wheel Wheel position replaced by scroll offsets
The `GLFWCALL` macro, which made callback functions use The `glfwGetMouseWheel` function has been removed. Scrolling is the input of
[__stdcall](http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows, offsets and has no absolute position. The mouse wheel callback has been
has been removed. GLFW is written in C, not Pascal. Removing this macro means replaced by a [scroll callback](@ref GLFWscrollfun) that receives
there's one less thing for users of GLFW to remember, i.e. the requirement to two-dimensional floating point scroll offsets. This allows you to receive
mark all callback functions with `GLFWCALL`. It also simplifies the creation of precise scroll data from for example modern touchpads.
DLLs and DLL link libraries, as there's no need to explicitly disable `@n` entry
point suffixes. @par Old syntax
@code
void GLFWCALL mouse_wheel_callback(int position);
@endcode
@par New syntax
@code
void scroll_callback(double xoffset, double yoffset);
@endcode
@par Removed functions
`glfwGetMouseWheel`
@subsection moving_repeat Key repeat action
The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled
for both keys and characters. A new key action, `GLFW_REPEAT`, has been added
to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press
from a repeat. Note that @ref glfwGetKey still returns only `GLFW_PRESS` or
`GLFW_RELEASE`.
@subsection moving_keys Physical key input
GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
the values generated by the current keyboard layout. The tokens are named
according to the values they would have 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 function changes
The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes.
The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and
`GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent
function as well as axis and button counts returned by the @ref
glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions.
@subsection moving_mbcs Win32 MBCS support @subsection moving_mbcs Win32 MBCS support
@ -125,174 +410,38 @@ or something else, are nowadays expected to be good desktop citizens and allow
these hotkeys to function even when running in full screen mode. 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 @subsection moving_terminate Automatic termination
GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization. To GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization. To
properly release all resources allocated by GLFW, you should therefore call @ref release all resources allocated by GLFW, you should call @ref glfwTerminate
glfwTerminate yourself before exiting. yourself. Note that this destroys all windows not already destroyed with @ref
glfwDestroyWindow, invalidating all window handles you may still have.
@subsection moving_glu GLU header inclusion @subsection moving_glu GLU header inclusion
GLFW 3 does not include the GLU header by default and GLU itself has been GLFW 3 does not by default include the GLU header and GLU itself has been
deprecated, but you can request that the GLFW 3 header includes it by defining deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). **New
`GLFW_INCLUDE_GLU` before the inclusion of the GLFW 3 header. projects should avoid using GLU**, but if you need to compile legacy code that
has been moved to GLFW 3, you can request that the GLFW header includes it by
defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW header.
@par Old syntax
@code
#include <GL/glfw.h>
@endcode
@par New syntax
@code
#define GLFW_INCLUDE_GLU
#include <GLFW/glfw3.h>
@endcode
@section moving_changed Changes to existing features @section moving_tables Name change tables
@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 @subsection moving_renamed_functions Renamed functions
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_hidpi Separation of window and framebuffer sizes
Window positions and sizes now use screen coordinates, which may not be the same
as pixels on machines with high-DPI monitors. This is important as OpenGL uses
pixels, not screen coordinates. Most commonly, the rectangle specified with
`glViewport` needs to use pixels. Therefore, framebuffer size functions have
been added. You can retrieve the size of the framebuffer of a window with @ref
glfwGetFramebufferSize function. A framebuffer size callback has been added,
which can be set with @ref glfwSetFramebufferSizeCallback.
@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 | | GLFW 2 | GLFW 3 | Notes |
| --------------------------- | ----------------------------- | ----- | | --------------------------- | ----------------------------- | ----- |
@ -311,7 +460,7 @@ Unix-like systems, where it uses the
| `glfwGetDesktopMode` | @ref glfwGetVideoMode | Returns the current mode of a monitor | | `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 | | `glfwGetJoystickParam` | @ref glfwJoystickPresent | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons |
@subsection moving_renamed_tokens Tokens @subsection moving_renamed_tokens Renamed tokens
| GLFW 2 | GLFW 3 | Notes | | GLFW 2 | GLFW 3 | Notes |
| --------------------------- | ---------------------------- | ----- | | --------------------------- | ---------------------------- | ----- |

8
docs/news.dox
View File

@ -23,7 +23,7 @@ windows. The callback is set with the @ref glfwSetDropCallback function.
@subsection news_31_emptyevent Empty event support @subsection news_31_emptyevent Empty event support
GLFW now provides the @ref glfwPostEmptyEvent function for posting an empty GLFW now provides the @ref glfwPostEmptyEvent function for posting an empty
event from a secondary thread to the main thread event queue, causing @ref event from another thread to the main thread event queue, causing @ref
glfwWaitEvents to return. glfwWaitEvents to return.
@ -47,6 +47,12 @@ GLFW not supports floating windows, also called topmost or always on top, for
easier debugging, with the `GLFW_FLOATING` window hint. easier debugging, with the `GLFW_FLOATING` window hint.
@subsection news_31_egl Stable EGL support
The support for EGL is now stable, successfully running on PandaBoards, Mesa,
ANGLE, Wayland, AMD EGL and others.
@section news_30 New features in version 3.0 @section news_30 New features in version 3.0
@subsection news_30_cmake CMake build system @subsection news_30_cmake CMake build system

34
docs/quick.dox
View File

@ -1,6 +1,6 @@
/*! /*!
@page quick Getting started @page quick Getting started — A quick introduction
@tableofcontents @tableofcontents
@ -290,19 +290,39 @@ glfwWaitEvents();
@endcode @endcode
@section quick_example Putting it together: A small GLFW application @section quick_example Putting it together: A simple application
Now that you know how to initialize GLFW, create a window and poll for Now that you know how to initialize GLFW, create a window and poll for
keyboard input, it's possible to create a simple program. keyboard input, it's possible to create a simple program.
@snippet simple.c code @snippet simple.c code
This program creates a 640 by 480 windowed mode window and runs a loop clearing This program creates a 640 by 480 windowed mode window and starts a loop that
the screen, rendering a triangle and processing events until the user closes the clears the screen, renders a triangle and processes events until the user either
window. It can be found in the source distribution as `examples/simple.c`, and presses Escape or closes the window.
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 This program uses only a few of the many functions GLFW provides. There are
guides for each of the areas covered by GLFW. Each guide will introduce all the
functions for that category.
- @ref intro
- @ref window
- @ref context
- @ref monitor
- @ref input
@section quick_build Compiling and linking the program
The complete program above can be found in the source distribution as
`examples/simple.c` and is compiled along with all other examples when you
build GLFW. That is, if you have compiled GLFW then you have already built this
as `simple.exe` on Windows, `simple` on Linux or `simple.app` on OS X.
This tutorial ends here. Once you have written a program that uses GLFW, you
will need to compile and link it. How to do that depends on the development
environment you are using and is best explained by the documentation for that
environment. To learn about the details that are specific to GLFW, see
@ref build. @ref build.
*/ */

27
docs/window.dox
View File

@ -25,10 +25,15 @@ by 480 windowed mode window:
@code @code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL); GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
if (!window)
{
// Handle window creation failure
}
@endcode @endcode
If window creation fails, `NULL` will be returned, so you need to check whether If window creation fails, `NULL` will be returned, so you need to check the
it did. return value. If creation failed, an error will have been reported to the error
callback.
This handle is then passed to all window related functions, and is provided to 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. you along with input events, so you know which window received the input.
@ -91,18 +96,16 @@ 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 find out the actual attributes of the created window and context, use the
@ref glfwGetWindowAttrib function. @ref glfwGetWindowAttrib function.
The following hints are hard constraints: The following hints are always hard constraints:
- `GLFW_STEREO` - `GLFW_STEREO`
- `GLFW_DOUBLEBUFFER` - `GLFW_DOUBLEBUFFER`
- `GLFW_CLIENT_API` - `GLFW_CLIENT_API`
The following additional hints are hard constraints if requesting an OpenGL The following additional hints are hard constraints when requesting an OpenGL
context: context, but are ignored when requesting an OpenGL ES context:
- `GLFW_OPENGL_FORWARD_COMPAT` - `GLFW_OPENGL_FORWARD_COMPAT`
- `GLFW_OPENGL_PROFILE` - `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 @subsection window_hints_wnd Window related hints
@ -140,9 +143,15 @@ and `GLFW_ACCUM_ALPHA_BITS` hints specify the desired bit depths of the
various components of the accumulation buffer. `GLFW_DONT_CARE` means the various components of the accumulation buffer. `GLFW_DONT_CARE` means the
application has no preference. application has no preference.
@note Accumulation buffers are a legacy OpenGL feature and should not be used in
new code.
The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary
buffers. `GLFW_DONT_CARE` means the application has no preference. buffers. `GLFW_DONT_CARE` means the application has no preference.
@note Auxiliary buffers are a legacy OpenGL feature and should not be used in
new code.
The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering. This is The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering. This is
a hard constraint. a hard constraint.
@ -318,6 +327,10 @@ int width, height;
glfwGetWindowSize(window, &width, &height); glfwGetWindowSize(window, &width, &height);
@endcode @endcode
@note Do not pass the window size to `glViewport` or other pixel-based OpenGL
calls. The window size is in screen coordinates, not pixels. Use the
framebuffer size, which is in pixels, for pixel-based calls.
@section window_fbsize Window framebuffer size @section window_fbsize Window framebuffer size

206
include/GLFW/glfw3.h
View File

@ -169,9 +169,9 @@ extern "C" {
#endif #endif
#if defined(GLFW_DLL) && defined(_GLFW_BUILD_DLL) #if defined(GLFW_DLL) && defined(_GLFW_BUILD_DLL)
/* GLFW_DLL is defined by users of GLFW when compiling programs that will link /* GLFW_DLL must be defined by applications that are linking against the DLL
* to the DLL version of the GLFW library. _GLFW_BUILD_DLL is defined by the * version of the GLFW library. _GLFW_BUILD_DLL is defined by the GLFW
* GLFW configuration header when compiling the DLL version of the library. * configuration header when compiling the DLL version of the library.
*/ */
#error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined" #error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined"
#endif #endif
@ -605,7 +605,7 @@ typedef void (* GLFWerrorfun)(int,const char*);
* *
* This is the function signature for window position callback functions. * This is the function signature for window position callback functions.
* *
* @param[in] window The window that the user moved. * @param[in] window The window that was moved.
* @param[in] xpos The new x-coordinate, in screen coordinates, of the * @param[in] xpos The new x-coordinate, in screen coordinates, of the
* upper-left corner of the client area of the window. * upper-left corner of the client area of the window.
* @param[in] ypos The new y-coordinate, in screen coordinates, of the * @param[in] ypos The new y-coordinate, in screen coordinates, of the
@ -621,7 +621,7 @@ typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
* *
* This is the function signature for window size callback functions. * This is the function signature for window size callback functions.
* *
* @param[in] window The window that the user resized. * @param[in] window The window that was resized.
* @param[in] width The new width, in screen coordinates, of the window. * @param[in] width The new width, in screen coordinates, of the window.
* @param[in] height The new height, in screen coordinates, of the window. * @param[in] height The new height, in screen coordinates, of the window.
* *
@ -900,9 +900,10 @@ typedef struct GLFWimage
* succeeds, you should call @ref glfwTerminate before the program exits. * succeeds, you should call @ref glfwTerminate before the program exits.
* *
* Additional calls to this function after successful initialization but before * Additional calls to this function after successful initialization but before
* termination will succeed but will do nothing. * termination will return `GL_TRUE` immediately.
* *
* @return `GL_TRUE` if successful, or `GL_FALSE` if an error occurred. * @return `GL_TRUE` if successful, or `GL_FALSE` if an error occurred. Errors
* are reported to the [error callback](@ref intro_error).
* *
* @par New in GLFW 3 * @par New in GLFW 3
* This function no longer registers @ref glfwTerminate with `atexit`. * This function no longer registers @ref glfwTerminate with `atexit`.
@ -953,6 +954,8 @@ GLFWAPI void glfwTerminate(void);
* @param[out] minor Where to store the minor version number, or `NULL`. * @param[out] minor Where to store the minor version number, or `NULL`.
* @param[out] rev Where to store the revision number, or `NULL`. * @param[out] rev Where to store the revision number, or `NULL`.
* *
* @remarks This function always succeeds.
*
* @remarks This function may be called before @ref glfwInit. * @remarks This function may be called before @ref glfwInit.
* *
* @remarks This function may be called from any thread. * @remarks This function may be called from any thread.
@ -965,24 +968,15 @@ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev);
/*! @brief Returns a string describing the compile-time configuration. /*! @brief Returns a string describing the compile-time configuration.
* *
* This function returns a static string generated at compile-time according to * This function returns the compile-time generated
* which configuration macros were defined. This is intended for use when * [version string](@ref intro_version_string) of the GLFW library binary. It
* submitting bug reports, to allow developers to see which code paths are * describes the version, platform, compiler and any platform-specific
* enabled in a binary. * compile-time options.
*
* The format of the string is as follows:
* - The version of GLFW
* - The name of the window system API
* - The name of the context creation API
* - Any additional options or APIs
*
* For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
* back ends, the version string may look something like this:
*
* 3.0.0 Win32 WGL MinGW
* *
* @return The GLFW version string. * @return The GLFW version string.
* *
* @remarks This function always succeeds.
*
* @remarks This function may be called before @ref glfwInit. * @remarks This function may be called before @ref glfwInit.
* *
* @remarks This function may be called from any thread. * @remarks This function may be called from any thread.
@ -1000,8 +994,9 @@ GLFWAPI const char* glfwGetVersionString(void);
* *
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set.
* error occurred. *
* @remarks This function always succeeds.
* *
* @remarks This function may be called before @ref glfwInit. * @remarks This function may be called before @ref glfwInit.
* *
@ -1027,7 +1022,8 @@ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun);
* *
* @param[out] count Where to store the size of the returned array. This is * @param[out] count Where to store the size of the returned array. This is
* set to zero if an error occurred. * set to zero if an error occurred.
* @return An array of monitor handles, or `NULL` if an error occurred. * @return An array of monitor handles, or `NULL` if an error occurred. Errors
* are reported to the [error callback](@ref intro_error).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1049,7 +1045,8 @@ GLFWAPI GLFWmonitor** glfwGetMonitors(int* count);
* This function returns the primary monitor. This is usually the monitor * This function returns the primary monitor. This is usually the monitor
* where elements like the Windows task bar or the OS X menu bar is located. * where elements like the Windows task bar or the OS X menu bar is located.
* *
* @return The primary monitor, or `NULL` if an error occurred. * @return The primary monitor, or `NULL` if an error occurred. Errors are
* reported to the [error callback](@ref intro_error).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1102,7 +1099,7 @@ GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* width, int* h
* *
* @param[in] monitor The monitor to query. * @param[in] monitor The monitor to query.
* @return The UTF-8 encoded name of the monitor, or `NULL` if an error * @return The UTF-8 encoded name of the monitor, or `NULL` if an error
* occurred. * occurred. Errors are reported to the [error callback](@ref intro_error).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1121,8 +1118,8 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
* *
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1143,7 +1140,8 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun);
* @param[in] monitor The monitor to query. * @param[in] monitor The monitor to query.
* @param[out] count Where to store the number of video modes in the returned * @param[out] count Where to store the number of video modes in the returned
* array. This is set to zero if an error occurred. * array. This is set to zero if an error occurred.
* @return An array of video modes, or `NULL` if an error occurred. * @return An array of video modes, or `NULL` if an error occurred. Errors are
* reported to the [error callback](@ref intro_error).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1167,6 +1165,7 @@ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count);
* *
* @param[in] monitor The monitor to query. * @param[in] monitor The monitor to query.
* @return The current mode of the monitor, or `NULL` if an error occurred. * @return The current mode of the monitor, or `NULL` if an error occurred.
* Errors are reported to the [error callback](@ref intro_error).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1187,6 +1186,10 @@ GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor);
* @param[in] monitor The monitor whose gamma ramp to set. * @param[in] monitor The monitor whose gamma ramp to set.
* @param[in] gamma The desired exponent. * @param[in] gamma The desired exponent.
* *
* @remark You cannot generate sRGB gamma using this function, because although
* it is approximately 2.2 it cannot be accurately expressed as a single
* numerical value.
*
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
* @ingroup monitor * @ingroup monitor
@ -1198,7 +1201,8 @@ GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma);
* This function retrieves the current gamma ramp of the specified monitor. * This function retrieves the current gamma ramp of the specified monitor.
* *
* @param[in] monitor The monitor to query. * @param[in] monitor The monitor to query.
* @return The current gamma ramp, or `NULL` if an error occurred. * @return The current gamma ramp, or `NULL` if an error occurred. Errors are
* reported to the [error callback](@ref intro_error).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1269,21 +1273,23 @@ GLFWAPI void glfwWindowHint(int target, int hint);
* can use the newly created context, you need to make it current using @ref * can use the newly created context, you need to make it current using @ref
* glfwMakeContextCurrent. * glfwMakeContextCurrent.
* *
* Note that the created window and context may differ from what you requested, * The created window, framebuffer and context may differ from what you
* as not all parameters and hints are * requested, as not all parameters and hints are
* [hard constraints](@ref window_hints_hard). This includes the size of the * [hard constraints](@ref window_hints_hard). This includes the size of the
* window, especially for full screen windows. To retrieve the actual * window, especially for full screen windows. To retrieve the actual
* attributes of the created window and context, use queries like @ref * attributes of the created window, framebuffer and context, use queries like
* glfwGetWindowAttrib and @ref glfwGetWindowSize. * @ref glfwGetWindowAttrib and @ref glfwGetWindowSize.
* *
* To create a full screen window, you need to specify the monitor to use. If * To create a full screen window, you need to specify the monitor the window
* no monitor is specified, windowed mode will be used. Unless you have a way * will cover. If no monitor is specified, windowed mode will be used. Unless
* for the user to choose a specific monitor, it is recommended that you pick * you have a way for the user to choose a specific monitor, it is recommended
* the primary monitor. For more information on how to retrieve monitors, see * that you pick the primary monitor. For more information on how to retrieve
* @ref monitor_monitors. * monitors, see @ref monitor_monitors.
* *
* To create the window at a specific position, make it initially invisible * By default, newly created windows use the placement recommended by the
* using the `GLFW_VISIBLE` window hint, set its position and then show it. * window system. To create the window at a specific position, make it
* initially invisible using the `GLFW_VISIBLE` window hint, set its position
* and then show it.
* *
* If a full screen window is active, the screensaver is prohibited from * If a full screen window is active, the screensaver is prohibited from
* starting. * starting.
@ -1298,6 +1304,11 @@ GLFWAPI void glfwWindowHint(int target, int hint);
* @param[in] share The window whose context to share resources with, or `NULL` * @param[in] share The window whose context to share resources with, or `NULL`
* to not share resources. * to not share resources.
* @return The handle of the created window, or `NULL` if an error occurred. * @return The handle of the created window, or `NULL` if an error occurred.
* Errors are reported to the [error callback](@ref intro_error).
*
* @remarks The [swap interval](@ref window_swap) is not set during window
* creation and the initial value may vary depending on driver settings and
* defaults.
* *
* @remarks **Windows:** Window creation will fail if the Microsoft GDI * @remarks **Windows:** Window creation will fail if the Microsoft GDI
* software OpenGL implementation is the only one available. * software OpenGL implementation is the only one available.
@ -1311,13 +1322,14 @@ GLFWAPI void glfwWindowHint(int target, int hint);
* Also, the first time a window is opened the menu bar is populated with * Also, the first time a window is opened the menu bar is populated with
* common commands like Hide, Quit and About. The (minimal) about dialog uses * common commands like Hide, Quit and About. The (minimal) about dialog uses
* information from the application's bundle. For more information on bundles, * information from the application's bundle. For more information on bundles,
* see the Bundle Programming Guide provided by Apple. * see the
* [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
* in the Mac Developer Library.
* *
* @remarks **X11:** There is no mechanism for setting the window icon yet. * @remarks **X11:** There is no mechanism for setting the window icon yet.
* *
* @remarks The swap interval is not set during window creation, but is left at * @remarks **X11:** Some window managers will not respect the placement of
* the default value for that platform. For more information, see @ref * initially hidden windows.
* glfwSwapInterval.
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1519,9 +1531,9 @@ GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height)
* @param[out] bottom Where to store the size, in screen coordinates, of the * @param[out] bottom Where to store the size, in screen coordinates, of the
* bottom edge of the window frame. * bottom edge of the window frame.
* *
* @remarks This function returns the size of each window frame edge, not its * @remarks This function retrieves the size of each window frame edge, not the
* offset from the client area edge, so the returned values will always be zero * offset along a screen coordinate axis, so the retrieved values will always
* or positive. * be zero or positive.
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1617,7 +1629,8 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
* @param[in] window The window to query. * @param[in] window The window to query.
* @param[in] attrib The [window attribute](@ref window_attribs) whose value to * @param[in] attrib The [window attribute](@ref window_attribs) whose value to
* return. * return.
* @return The value of the attribute, or zero if an error occurred. * @return The value of the attribute, or zero if an error occurred. Errors
* are reported to the [error callback](@ref intro_error).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1666,8 +1679,8 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1684,8 +1697,8 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1707,8 +1720,8 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @par New in GLFW 3 * @par New in GLFW 3
* The close callback no longer returns a value. * The close callback no longer returns a value.
@ -1735,8 +1748,8 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1761,8 +1774,8 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1778,8 +1791,8 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1795,8 +1808,8 @@ GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GL
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -1959,6 +1972,9 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
* named after their use on the standard US keyboard layout. If you want to * named after their use on the standard US keyboard layout. If you want to
* input text, use the Unicode character callback instead. * input text, use the Unicode character callback instead.
* *
* The [modifier key bit masks](@ref mods) are not key tokens and cannot be
* used with this function.
*
* @param[in] window The desired window. * @param[in] window The desired window.
* @param[in] key The desired [keyboard key](@ref keys). * @param[in] key The desired [keyboard key](@ref keys).
* @return One of `GLFW_PRESS` or `GLFW_RELEASE`. * @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
@ -2047,14 +2063,20 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);
/*! @brief Creates a cursor. /*! @brief Creates a cursor.
*
* Creates a new cursor that can be made the system cursor for a window with
* @ref glfwSetCursor. The cursor can be destroyed with @ref
* glfwDestroyCursor. Any remaining cursors are destroyed by @ref
* glfwTerminate.
*
* The specified image is in 32-bit RGBA format, so eight bits per channel.
* *
* @param[in] image The desired cursor image. * @param[in] image The desired cursor image.
* @param[in] xhot The desired x-coordinate of the cursor hotspot. * @param[in] xhot The desired x-coordinate of the cursor hotspot.
* @param[in] yhot The desired y-coordinate of the cursor hotspot. * @param[in] yhot The desired y-coordinate of the cursor hotspot.
* *
* @return A new cursor ready to use or `NULL` if an error occurred. If you * @return A new cursor ready to use or `NULL` if an error occurred. Errors
* don't destroy the cursor by calling `glfwDestroyCursor` it will be destroyed * are reported to the [error callback](@ref intro_error).
* automatically by `GLFW` on termination.
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2064,11 +2086,11 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot)
/*! @brief Destroys a cursor. /*! @brief Destroys a cursor.
* *
* This function destroys a cursor previously created by a call to * This function destroys a cursor previously created with @ref
* `glfwCreateCursor`. `GLFW` will destroy all cursors automatically on * glfwCreateCursor. Any remaining cursors will be destroyed by @ref
* termination. * glfwTerminate.
* *
* @param[in] cursor The cursor to destroy. * @param[in] cursor The cursor object to destroy.
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2076,11 +2098,11 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot)
*/ */
GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor); GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor);
/*! @brief Sets the cursor for a given window. /*! @brief Sets the system cursor for a given window.
* *
* @param[in] window The window to set the cursor for. * @param[in] window The window to set the system cursor for.
* @param[in] cursor The cursor to change to, or `NULL` to switch back to the * @param[in] cursor The cursor to change to, or `NULL` to switch back
* default system cursor. * to the default system cursor.
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2115,8 +2137,8 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new key callback, or `NULL` to remove the currently * @param[in] cbfun The new key callback, or `NULL` to remove the currently
* set callback. * set callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2136,8 +2158,8 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2159,8 +2181,8 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2178,8 +2200,8 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2196,8 +2218,8 @@ GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursor
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set * @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback. * callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2217,8 +2239,8 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new scroll callback, or `NULL` to remove the currently * @param[in] cbfun The new scroll callback, or `NULL` to remove the currently
* set callback. * set callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2235,8 +2257,8 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb
* @param[in] window The window whose callback to set. * @param[in] window The window whose callback to set.
* @param[in] cbfun The new file drop callback, or `NULL` to remove the * @param[in] cbfun The new file drop callback, or `NULL` to remove the
* currently set callback. * currently set callback.
* @return The previously set callback, or `NULL` if no callback was set or an * @return The previously set callback, or `NULL` if no callback was set or the
* error occurred. * library had not been [initialized](@ref intro_init).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2343,7 +2365,8 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string);
* *
* @param[in] window The window that will request the clipboard contents. * @param[in] window The window that will request the clipboard contents.
* @return The contents of the clipboard as a UTF-8 encoded string, or `NULL` * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL`
* if an error occurred. * if an error occurred. Errors are reported to the
* [error callback](@ref intro_error).
* *
* @note This function may only be called from the main thread. * @note This function may only be called from the main thread.
* *
@ -2365,7 +2388,8 @@ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window);
* been set using @ref glfwSetTime, the timer measures time elapsed since GLFW * been set using @ref glfwSetTime, the timer measures time elapsed since GLFW
* was initialized. * was initialized.
* *
* @return The current value, in seconds, or zero if an error occurred. * @return The current value, in seconds, or zero if an error occurred. Errors
* are reported to the [error callback](@ref intro_error).
* *
* @remarks This function may be called from any thread. * @remarks This function may be called from any thread.
* *

12
src/internal.h
View File

@ -599,7 +599,8 @@ void _glfwPlatformSwapBuffers(_GLFWwindow* window);
*/ */
void _glfwPlatformSwapInterval(int interval); void _glfwPlatformSwapInterval(int interval);
/*! @ingroup platform /*! @copydoc glfwExtensionSupported
* @ingroup platform
*/ */
int _glfwPlatformExtensionSupported(const char* extension); int _glfwPlatformExtensionSupported(const char* extension);
@ -608,10 +609,19 @@ int _glfwPlatformExtensionSupported(const char* extension);
*/ */
GLFWglproc _glfwPlatformGetProcAddress(const char* procname); GLFWglproc _glfwPlatformGetProcAddress(const char* procname);
/*! @copydoc glfwCreateCursor
* @ingroup platform
*/
int _glfwPlatformCreateCursor(_GLFWcursor* cursor, const GLFWimage* image, int xhot, int yhot); int _glfwPlatformCreateCursor(_GLFWcursor* cursor, const GLFWimage* image, int xhot, int yhot);
/*! @copydoc glfwDestroyCursor
* @ingroup platform
*/
void _glfwPlatformDestroyCursor(_GLFWcursor* cursor); void _glfwPlatformDestroyCursor(_GLFWcursor* cursor);
/*! @copydoc glfwSetCursor
* @ingroup platform
*/
void _glfwPlatformSetCursor(_GLFWwindow* window, _GLFWcursor* cursor); void _glfwPlatformSetCursor(_GLFWwindow* window, _GLFWcursor* cursor);
//======================================================================== //========================================================================