mirror of
https://github.com/glfw/glfw.git
synced 2024-11-25 22:14:34 +00:00
parent
a7b9deb2ca
commit
e8e05d462c
@ -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
187
docs/build.dox
@ -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
|
||||
|
@ -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
|
||||
|
160
docs/context.dox
160
docs/context.dox
@ -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
13
docs/input.dox
Normal 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
|
||||
|
||||
*/
|
@ -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
166
docs/intro.dox
Normal 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.
|
||||
|
||||
*/
|
@ -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
541
docs/moving.dox
@ -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 |
|
||||
| --------------------------- | ---------------------------- | ----- |
|
||||
|
@ -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
|
||||
|
@ -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.
|
||||
|
||||
*/
|
||||
|
@ -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
|
||||
|
||||
|
@ -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.
|
||||
*
|
||||
|
@ -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);
|
||||
|
||||
//========================================================================
|
||||
|
Loading…
Reference in New Issue
Block a user