mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-10 00:51:47 +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@/docs/main.dox \
@GLFW_SOURCE_DIR@/docs/news.dox \
@GLFW_SOURCE_DIR@/docs/quick.dox \
@GLFW_SOURCE_DIR@/docs/moving.dox \
@GLFW_SOURCE_DIR@/docs/quick.dox \
@GLFW_SOURCE_DIR@/docs/compile.dox \
@GLFW_SOURCE_DIR@/docs/build.dox \
@GLFW_SOURCE_DIR@/docs/intro.dox \
@GLFW_SOURCE_DIR@/docs/context.dox \
@GLFW_SOURCE_DIR@/docs/monitor.dox \
@GLFW_SOURCE_DIR@/docs/window.dox \
@GLFW_SOURCE_DIR@/docs/input.dox \
@GLFW_SOURCE_DIR@/docs/compat.dox
# This tag can be used to specify the character encoding of the source files

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

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.
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
auto-repeat, `glfwInit` will fail.
input. If the running X server does not support this extension, a non-Xkb
fallback path is used.
@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.
GLFW uses the `GLXFBConfig` API to enumerate and select framebuffer pixel
formats. This requires either GLX 1.3 or greater, or the `GLX_SGIX_fbconfig`
extension. Where both are available, the SGIX extension is preferred. If
neither is available, GLFW will be unable to create windows.
formats. This requires GLX 1.3 or greater.
GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
`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
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
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_WIN32` to use the Win32 API
- `_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
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_WGL` to use the Win32 WGL 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
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
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
The @ref GLFWwindow object encapsulates both a window and a context. They are
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
@ref glfwTerminate, if any remain). As the window and context are inseparably
linked, the object pointer is used as both a context and window handle.
The @ref GLFWwindow object encapsulates both a [window](@ref window) and
a context. It is created with @ref glfwCreateWindow and destroyed with @ref
glfwDestroyWindow or @ref glfwTerminate. As the window and context are
inseparably linked, the object pointer is used as both a context and window
handle.
@section context_hints Context creation hints
@ -27,21 +28,19 @@ what kind of context is created. See
@section context_sharing Context object sharing
When creating a window and context with @ref glfwCreateWindow, you can specify
another window whose context the new one should share its objects with. OpenGL
object sharing is implemented by the operating system and graphics driver and is
described in the OpenGL documentation. On platforms where it is possible to
choose which types of objects are shared, GLFW requests that all are shared.
another window whose context the new one should share its objects with. Object
sharing is implemented by the operating system and graphics driver and is
described in the OpenGL and OpenGL ES documentation. On platforms where it is
possible to choose which types of objects are shared, GLFW requests that all are
shared.
@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
objects like textures and shaders.
Note that a context can only be current for a single thread at a time, and
a thread can only have a single context at a time.
A context is made current with @ref glfwMakeContextCurrent.
@code
@ -54,18 +53,23 @@ The current context is returned by @ref glfwGetCurrentContext.
GLFWwindow* window = glfwGetCurrentContext();
@endcode
@note A context must only be current for a single thread at a time, and a thread
must only have a single context current at a time.
@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
vendors (IHVs) may include functionality in their OpenGL implementations that
expand upon the OpenGL standard before that functionality is included in a new
version of the OpenGL specification.
One of the benefits of OpenGL and OpenGL ES are their extensibility.
Hardware vendors may include extensions in their implementations that extend the
API before that functionality is included in a new version of the OpenGL or
OpenGL ES specification, and some extensions are never included and remain
as extensions until they become obsolete.
An extension is defined by:
@ -74,23 +78,105 @@ An extension is defined by:
- New OpenGL functions (e.g. `glGetDebugMessageLogARB`)
Note the `ARB` affix, which stands for Architecture Review Board and is used
for official extensions. There are many different affixes, depending on who
wrote the extension. A list of extensions, together with their specifications,
can be found at the [OpenGL Registry](http://www.opengl.org/registry/).
for official extensions. The extension above was created by the ARB, but there
are many different affixes, like `NV` for Nvidia and `AMD` for, well, AMD. Any
group may also use the generic `EXT` affix. Lists of extensions, together with
their specifications, can be found at the
[OpenGL Registry](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
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
you will instead want to use a dedicated extension loading library such as
[GLEW](http://glew.sourceforge.net/). This kind of library greatly reduces the
amount of work necessary to use both OpenGL extensions and modern versions of
the OpenGL API. GLEW in particular has been extensively tested with and works
well with GLFW.
@note It is strongly recommended that you use an existing extension loader
library like [glad](https://github.com/Dav1dde/glad) instead of loading
manually. Extension loading is a solved problem and you will gain nothing from
solving it again by hand.
@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
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
supports. These have names like `PFNGLGETDEBUGMESSAGELOGARB` (for
`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` and `PROC`
are added to the ends.
`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` (pointer
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
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.
@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.
These entry points are often not exposed by your link libraries, making
it necessary to fetch them at run time. With @ref glfwGetProcAddress you can
retrieve the address of extension and non-extension OpenGL functions.
These functions often do not have entry points in the client API libraries of
your operating system, making it necessary to fetch them at run time. You can
retreive pointers to these functions with @ref glfwGetProcAddress.
@code
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
to the public interface. This includes event processing. The platform
interface is never directly called by users of GLFW and never directly calls the
user's code. It is also prohibited from modifying the platform-independent part
of the internal structs. Instead, it calls the event interface when events
interesting to GLFW are received.
interface is never directly called by application code and never directly calls
application-provided callbacks. It is also prohibited from modifying the
platform-independent part of the internal structs. Instead, it calls the event
interface when events interesting to GLFW are received.
The platform interface mirrors those parts of the public interface that needs to
perform platform-specific operations on some or all platforms. The are also
@ -85,8 +85,8 @@ Examples: `window.win32.handle`, `_glfw.x11.display`
@section internals_event Event interface
The event interface is implemented in the same shared source files as the public
interface and is responsible for delivering the events it receives to the user,
either via callbacks, via window state changes or both.
interface and is responsible for delivering the events it receives to the
application, either via callbacks, via window state changes or both.
The function names of the event interface use a `_glfwInput` prefix and the
ObjectEvent pattern.

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
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 user's preferred monitor and the one with global UI elements like task bar
The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's
preferred monitor and is usually the one with global UI elements like task bar
or menu bar.
@code
@ -21,14 +33,20 @@ GLFWmonitor* primary = glfwGetPrimaryMonitor();
@endcode
You can retrieve all currently connected monitors with @ref glfwGetMonitors.
The primary monitor is always the first monitor in the returned array.
@code
int count;
GLFWmonitor** monitors = glfwGetMonitors(&count);
@endcode
@note Monitors other than the primary monitor may be moved to a different index
in the array if another monitor is disconnected.
@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
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
@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.
@code
@ -67,28 +85,61 @@ const double dpi = mode->width / (widthMM / 25.4);
@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
const char* name = glfwGetMonitorName(monitor);
@endcode
The monitor name is a regular C string using the UTF-8 encoding. Note that
monitor names are not guaranteed to be unique.
@note Monitor names are not guaranteed to be unique. Two monitors of the same
model and make may have the same name. Only the address of a monitor object is
guaranteed to be unique.
@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
a monitor handle and a pointer to a @ref GLFWgammaramp structure.
@code
GLFWgammaramp ramp;
unsigned short red[256], green[256], blue[256];
ramp.size = 256;
ramp.red = red;
ramp.green = green;
ramp.blue = blue;
for (i = 0; i < ramp.size; i++)
{
// Fill out gamma ramp arrays as desired
}
glfwSetGammaRamp(monitor, &ramp);
@endcode
The 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
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
changed or been removed, but does *not* include
[new features](@ref news) unless they are required when moving an existing code
base onto the new API. For example, use of the new multi-monitor functions are
base onto the new API. For example, the new multi-monitor functions are
required to create full screen windows with GLFW 3.
@section moving_removed 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
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.
The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to
avoid collisions with the headers of other major versions. Similarly, the GLFW
3 library is named `glfw3,` except when it's installed as a shared library on
Unix-like systems, where it uses the
[soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`.
@par Old syntax
@code
#include <GL/glfw.h>
@endcode
@par New syntax
@code
#include <GLFW/glfw3.h>
@endcode
@subsection moving_threads Removal of threading functions
The threading functions have been removed, including the per-thread sleep
function. They were fairly primitive, under-used, poorly integrated and took
time away from the focus of GLFW (i.e. context, input and window). There are
better threading libraries available and native threading support is available
in both C++11 and C11, both of which are gaining traction.
If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
support them, see the
@ -30,30 +49,233 @@ threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
TinyCThread.
However, GLFW 3 has better support for *use from multiple threads* than GLFW
2 had. Contexts can be made current on and rendered with from secondary
threads, and the documentation explicitly states which functions may be used
from secondary threads and which may only be used from the main thread, i.e. the
thread that calls main.
2 had. Contexts can be made current on any thread, although only a single
thread at a time, and the documentation explicitly states which functions may be
used from any thread and which may only be used from the main thread.
@par Removed functions
`glfwSleep`, `glfwCreateThread`, `glfwDestroyThread`, `glfwWaitThread`,
`glfwGetThreadID`, `glfwCreateMutex`, `glfwDestroyMutex`, `glfwLockMutex`,
`glfwUnlockMutex`, `glfwCreateCond`, `glfwDestroyCond`, `glfwWaitCond`,
`glfwSignalCond`, `glfwBroadcastCond` and `glfwGetNumberOfProcessors`.
@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 Targa image format, making them mostly useful for beginner level examples.
To become of sufficiently high quality to warrant keeping them in GLFW 3, they
would need not only to support other formats, but also modern extensions to the
OpenGL texturing facilities. This would either add a number of external
would need not only to support other formats, but also modern extensions to
OpenGL texturing. This would either add a number of external
dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions
of these libraries.
As there already are libraries doing this, it seems unnecessary both to
duplicate this work and to tie this duplicate to GLFW. Projects similar to
GLFW, such as freeglut, could also gain from such a library. Also, would be no
platform-specific part of such a library, as both OpenGL and stdio are available
wherever GLFW is.
As there already are libraries doing this, it is unnecessary both to duplicate
the work and to tie the duplicate to GLFW. The resulting library would also be
platform-independent, as both OpenGL and stdio are available wherever GLFW is.
@par Removed functions
`glfwReadImage`, `glfwReadMemoryImage`, `glfwFreeImage`, `glfwLoadTexture2D`,
`glfwLoadMemoryTexture2D` and `glfwLoadTextureImage2D`.
@subsection moving_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
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
requires this for uncommon cases like ü.
Note that this is only the removal of the *action parameter* of the character
callback, *not* the removal of the character callback itself.
@par Old syntax
@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
represent an absolute state, but is instead an interpretation of a relative
change in state, like character input. So, like character input, there is no
sane 'current state' to return. The mouse wheel callback has been replaced by
a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll
offsets.
The `glfwGetMousePos` function has been renamed to @ref glfwGetCursorPos,
`glfwSetMousePos` to @ref glfwSetCursorPos and `glfwSetMousePosCallback` to @ref
glfwSetCursorPosCallback.
The cursor position is now `double` instead of `int`, both for the direct
functions and for the callback. Some platforms can provide sub-pixel cursor
movement and this data is now passed on to the application where available. On
platforms where this is not provided, the decimal part is zero.
GLFW 3 only allows you to position the cursor within a window using @ref
glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
Unless the window is active, the function fails silently.
@subsection moving_stdcall GLFWCALL macro
@subsection moving_wheel Wheel position replaced by scroll offsets
The `GLFWCALL` macro, which made callback functions use
[__stdcall](http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows,
has been removed. GLFW is written in C, not Pascal. Removing this macro means
there's one less thing for users of GLFW to remember, i.e. the requirement to
mark all callback functions with `GLFWCALL`. It also simplifies the creation of
DLLs and DLL link libraries, as there's no need to explicitly disable `@n` entry
point suffixes.
The `glfwGetMouseWheel` function has been removed. Scrolling is the input of
offsets and has no absolute position. The mouse wheel callback has been
replaced by a [scroll callback](@ref GLFWscrollfun) that receives
two-dimensional floating point scroll offsets. This allows you to receive
precise scroll data from for example modern touchpads.
@par Old syntax
@code
void GLFWCALL mouse_wheel_callback(int position);
@endcode
@par New syntax
@code
void scroll_callback(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
@ -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.
@subsection moving_opened Window open parameter
The `GLFW_OPENED` window parameter has been removed. As long as the
[window object](@ref window_object) is around, the window is "open". To detect
when the user attempts to close the window, see @ref glfwWindowShouldClose and
the [close callback](@ref GLFWwindowclosefun).
@subsection moving_autopoll Automatic polling of events
GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
Unlike buffer swap, the event processing functions act on all windows at once.
@subsection moving_terminate Automatic termination
GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization. To
properly release all resources allocated by GLFW, you should therefore call @ref
glfwTerminate yourself before exiting.
release all resources allocated by GLFW, you should call @ref glfwTerminate
yourself. Note that this destroys all windows not already destroyed with @ref
glfwDestroyWindow, invalidating all window handles you may still have.
@subsection moving_glu GLU header inclusion
GLFW 3 does not include the GLU header by default and GLU itself has been
deprecated, but you can request that the GLFW 3 header includes it by defining
`GLFW_INCLUDE_GLU` before the inclusion of the GLFW 3 header.
GLFW 3 does not by default include the GLU header and GLU itself has been
deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). **New
projects should 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
@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.
@section moving_tables Name change tables
@subsection moving_monitor Multi-monitor support
GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle
type and a set of related functions. To request a full screen mode window,
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
window to use. There is @ref glfwGetPrimaryMonitor that provides behaviour
similar to that of GLFW 2.
@subsection moving_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
@subsection moving_renamed_functions Renamed functions
| 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 |
| `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 |
| --------------------------- | ---------------------------- | ----- |

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
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.
@ -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.
@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
@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
@ -290,19 +290,39 @@ glfwWaitEvents();
@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
keyboard input, it's possible to create a simple program.
@snippet simple.c code
This program creates a 640 by 480 windowed mode window and runs a loop clearing
the screen, rendering a triangle and processing events until the user closes the
window. It can be found in the source distribution as `examples/simple.c`, and
is by default compiled along with all other examples when you build GLFW.
This program creates a 640 by 480 windowed mode window and starts a loop that
clears the screen, renders a triangle and processes events until the user either
presses Escape or closes the window.
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.
*/

27
docs/window.dox
View File

@ -25,10 +25,15 @@ by 480 windowed mode window:
@code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
if (!window)
{
// Handle window creation failure
}
@endcode
If window creation fails, `NULL` will be returned, so you need to check whether
it did.
If window creation fails, `NULL` will be returned, so you need to check the
return value. If creation failed, an error will have been reported to the error
callback.
This handle is then passed to all window related functions, and is provided to
you along with input events, so you know which window received the input.
@ -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
@ref glfwGetWindowAttrib function.
The following hints are hard constraints:
The following hints are always hard constraints:
- `GLFW_STEREO`
- `GLFW_DOUBLEBUFFER`
- `GLFW_CLIENT_API`
The following additional hints are hard constraints if requesting an OpenGL
context:
The following additional hints are hard constraints when requesting an OpenGL
context, but are ignored when requesting an OpenGL ES context:
- `GLFW_OPENGL_FORWARD_COMPAT`
- `GLFW_OPENGL_PROFILE`
Hints that do not apply to a given type of window or context are ignored.
@subsection window_hints_wnd Window related hints
@ -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
application has no preference.
@note Accumulation buffers are a legacy OpenGL feature and should not be used in
new code.
The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary
buffers. `GLFW_DONT_CARE` means the application has no preference.
@note Auxiliary buffers are a legacy OpenGL feature and should not be used in
new code.
The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering. This is
a hard constraint.
@ -318,6 +327,10 @@ int width, height;
glfwGetWindowSize(window, &width, &height);
@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

206
include/GLFW/glfw3.h
View File

@ -169,9 +169,9 @@ extern "C" {
#endif
#if defined(GLFW_DLL) && defined(_GLFW_BUILD_DLL)
/* GLFW_DLL is defined by users of GLFW when compiling programs that will link
* to the DLL version of the GLFW library. _GLFW_BUILD_DLL is defined by the
* GLFW configuration header when compiling the DLL version of the library.
/* GLFW_DLL must be defined by applications that are linking against the DLL
* version of the GLFW library. _GLFW_BUILD_DLL is defined by the GLFW
* configuration header when compiling the DLL version of the library.
*/
#error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined"
#endif
@ -605,7 +605,7 @@ typedef void (* GLFWerrorfun)(int,const char*);
*
* 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
* upper-left corner of the client area of the window.
* @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.
*
* @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] 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.
*
* 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
* 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] 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 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.
*
* This function returns a static string generated at compile-time according to
* which configuration macros were defined. This is intended for use when
* submitting bug reports, to allow developers to see which code paths are
* enabled in a binary.
*
* The format of the string is as follows:
* - The version of GLFW
* - The name of the window system API
* - The name of the context creation API
* - Any additional options or APIs
*
* For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
* back ends, the version string may look something like this:
*
* 3.0.0 Win32 WGL MinGW
* This function returns the compile-time generated
* [version string](@ref intro_version_string) of the GLFW library binary. It
* describes the version, platform, compiler and any platform-specific
* compile-time options.
*
* @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 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
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set.
*
* @remarks This function always succeeds.
*
* @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
* 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.
*
@ -1049,7 +1045,8 @@ GLFWAPI GLFWmonitor** glfwGetMonitors(int* count);
* 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.
*
* @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.
*
@ -1102,7 +1099,7 @@ GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* width, int* h
*
* @param[in] monitor The monitor to query.
* @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.
*
@ -1121,8 +1118,8 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
*
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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[out] count Where to store the number of video modes in the returned
* 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.
*
@ -1167,6 +1165,7 @@ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count);
*
* @param[in] monitor The monitor to query.
* @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.
*
@ -1187,6 +1186,10 @@ GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor);
* @param[in] monitor The monitor whose gamma ramp to set.
* @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.
*
* @ingroup monitor
@ -1198,7 +1201,8 @@ GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma);
* This function retrieves the current gamma ramp of the specified monitor.
*
* @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.
*
@ -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
* glfwMakeContextCurrent.
*
* Note that the created window and context may differ from what you requested,
* as not all parameters and hints are
* The created window, framebuffer and context may differ from what you
* requested, as not all parameters and hints are
* [hard constraints](@ref window_hints_hard). This includes the size of the
* window, especially for full screen windows. To retrieve the actual
* attributes of the created window and context, use queries like @ref
* glfwGetWindowAttrib and @ref glfwGetWindowSize.
* attributes of the created window, framebuffer and context, use queries like
* @ref glfwGetWindowAttrib and @ref glfwGetWindowSize.
*
* To create a full screen window, you need to specify the monitor to use. If
* no monitor is specified, windowed mode will be used. Unless you have a way
* for the user to choose a specific monitor, it is recommended that you pick
* the primary monitor. For more information on how to retrieve monitors, see
* @ref monitor_monitors.
* To create a full screen window, you need to specify the monitor the window
* will cover. If no monitor is specified, windowed mode will be used. Unless
* you have a way for the user to choose a specific monitor, it is recommended
* that you pick the primary monitor. For more information on how to retrieve
* monitors, see @ref monitor_monitors.
*
* 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.
* By default, newly created windows use the placement recommended by the
* 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
* 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`
* to not share resources.
* @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
* 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
* common commands like Hide, Quit and About. The (minimal) about dialog uses
* 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 The swap interval is not set during window creation, but is left at
* the default value for that platform. For more information, see @ref
* glfwSwapInterval.
* @remarks **X11:** Some window managers will not respect the placement of
* initially hidden windows.
*
* @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
* bottom edge of the window frame.
*
* @remarks This function returns the size of each window frame edge, not its
* offset from the client area edge, so the returned values will always be zero
* or positive.
* @remarks This function retrieves the size of each window frame edge, not the
* offset along a screen coordinate axis, so the retrieved values will always
* be zero or positive.
*
* @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] attrib The [window attribute](@ref window_attribs) whose value to
* 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.
*
@ -1666,8 +1679,8 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
* @param[in] window The window whose callback to set.
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @par New in GLFW 3
* 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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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
* 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] key The desired [keyboard key](@ref keys).
* @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);
/*! @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] xhot The desired x-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
* don't destroy the cursor by calling `glfwDestroyCursor` it will be destroyed
* automatically by `GLFW` on termination.
* @return A new cursor ready to use 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.
*
@ -2064,11 +2086,11 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot)
/*! @brief Destroys a cursor.
*
* This function destroys a cursor previously created by a call to
* `glfwCreateCursor`. `GLFW` will destroy all cursors automatically on
* termination.
* This function destroys a cursor previously created with @ref
* glfwCreateCursor. Any remaining cursors will be destroyed by @ref
* 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.
*
@ -2076,11 +2098,11 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot)
*/
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] cursor The cursor to change to, or `NULL` to switch back to the
* default system cursor.
* @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 default system cursor.
*
* @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] cbfun The new key callback, or `NULL` to remove the currently
* set callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new callback, or `NULL` to remove the currently set
* callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new scroll callback, or `NULL` to remove the currently
* set callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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] cbfun The new file drop callback, or `NULL` to remove the
* currently set callback.
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @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.
* @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.
*
@ -2365,7 +2388,8 @@ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window);
* been set using @ref glfwSetTime, the timer measures time elapsed since GLFW
* 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.
*

12
src/internal.h
View File

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