Commit e8e05d46 authored by Camilla Berglund's avatar Camilla Berglund
Browse files

Documentation work.

Fixes #276.
parent a7b9deb2
......@@ -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
......
......@@ -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.
If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do:
@code{.sh}
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
@endcode
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
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 adding
it from the command-line.
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
......
......@@ -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
......
......@@ -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
......
......@@ -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");
......
/*!
@page input Input handling guide
@tableofcontents
@section input_key Keyboard input
@section input_mouse Mouse input
@section input_joy Joystick input
*/
......@@ -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.
......
/*!
@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,