diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 171bd18a..5af0948a 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -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 diff --git a/docs/build.dox b/docs/build.dox index 5778f370..e9794dde 100644 --- a/docs/build.dox +++ b/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 @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 diff --git a/docs/compat.dox b/docs/compat.dox index 7d8a5d7d..fdbb76a7 100644 --- a/docs/compat.dox +++ b/docs/compat.dox @@ -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 diff --git a/docs/compile.dox b/docs/compile.dox index dee7bd9c..ef53e54c 100644 --- a/docs/compile.dox +++ b/docs/compile.dox @@ -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 diff --git a/docs/context.dox b/docs/context.dox index 8057cc70..ccca60c2 100644 --- a/docs/context.dox +++ b/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 +#include +@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"); diff --git a/docs/input.dox b/docs/input.dox new file mode 100644 index 00000000..759ce220 --- /dev/null +++ b/docs/input.dox @@ -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 + +*/ diff --git a/docs/internal.dox b/docs/internal.dox index a2653fea..0389af6e 100644 --- a/docs/internal.dox +++ b/docs/internal.dox @@ -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. diff --git a/docs/intro.dox b/docs/intro.dox new file mode 100644 index 00000000..2de2c8bd --- /dev/null +++ b/docs/intro.dox @@ -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. + +*/ diff --git a/docs/monitor.dox b/docs/monitor.dox index a3ada5a1..ddc87549 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -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,10 +67,10 @@ 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 -retrieved with @ref glfwGetMonitorPhysicalSize. +The physical size in millimetres of a monitor, or an estimation of it, can be +retrieved with @ref glfwGetMonitorPhysicalSize. @code int widthMM, heightMM; @@ -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); diff --git a/docs/moving.dox b/docs/moving.dox index cec12f55..0e5369b3 100644 --- a/docs/moving.dox +++ b/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 +@endcode + +@par New syntax +@code +#include +@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 +@endcode + +@par New syntax +@code +#define GLFW_INCLUDE_GLU +#include +@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 | | --------------------------- | ---------------------------- | ----- | diff --git a/docs/news.dox b/docs/news.dox index ae750ee7..6788faf3 100644 --- a/docs/news.dox +++ b/docs/news.dox @@ -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 diff --git a/docs/quick.dox b/docs/quick.dox index b90a54da..120ca9b2 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -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. */ diff --git a/docs/window.dox b/docs/window.dox index da822ca3..bd6abcfd 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -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 diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 04dc5ca7..51743c90 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -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. * diff --git a/src/internal.h b/src/internal.h index f31f0c26..ddf6f24a 100644 --- a/src/internal.h +++ b/src/internal.h @@ -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); //========================================================================