mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-10 00:51:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work

Browse Source 
[ci skip]
This commit is contained in:
Camilla Löwy 2016-12-06 01:14:23 +01:00
parent f383f7721c
commit ce161c2c02
11 changed files with 484 additions and 265 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/Doxyfile.in
View File

@ -468,14 +468,14 @@ INLINE_INFO = YES
# alphabetically by member name. If set to NO the members will appear in # alphabetically by member name. If set to NO the members will appear in
# declaration order. # declaration order.
SORT_MEMBER_DOCS = YES SORT_MEMBER_DOCS = NO
# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
# brief documentation of file, namespace and class members alphabetically # brief documentation of file, namespace and class members alphabetically
# by member name. If set to NO (the default) the members will appear in # by member name. If set to NO (the default) the members will appear in
# declaration order. # declaration order.
SORT_BRIEF_DOCS = NO SORT_BRIEF_DOCS = YES
# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen
# will sort the (brief and detailed) documentation of class members so that # will sort the (brief and detailed) documentation of class members so that

54
docs/build.dox
View File

@ -49,7 +49,7 @@ In other words:
If you are using an OpenGL extension loading library such as If you are using an OpenGL extension loading library such as
[glad](https://github.com/Dav1dde/glad), the extension loader header should [glad](https://github.com/Dav1dde/glad), the extension loader header should
either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro either be included _before_ the GLFW one, or the @ref GLFW_INCLUDE_NONE macro
(described below) should be defined. (described below) should be defined.
@ -58,30 +58,37 @@ either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
These macros may be defined before the inclusion of the GLFW header and affect These macros may be defined before the inclusion of the GLFW header and affect
its behavior. its behavior.
`GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler @anchor GLFW_DLL
that the GLFW functions are defined in a DLL. __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 OpenGL or OpenGL ES API header is included. The following macros control which OpenGL or OpenGL ES API header is included.
Only one of these may be defined at a time. Only one of these may be defined at a time.
`GLFW_INCLUDE_GLCOREARB` makes the GLFW header include the modern @anchor GLFW_INCLUDE_GLCOREARB
__GLFW_INCLUDE_GLCOREARB__ makes the GLFW header include the modern
`GL/glcorearb.h` header (`OpenGL/gl3.h` on macOS) instead of the regular OpenGL `GL/glcorearb.h` header (`OpenGL/gl3.h` on macOS) instead of the regular OpenGL
header. header.
`GLFW_INCLUDE_ES1` makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h` @anchor GLFW_INCLUDE_ES1
__GLFW_INCLUDE_ES1__ makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
header instead of the regular OpenGL header. header instead of the regular OpenGL header.
`GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h` @anchor GLFW_INCLUDE_ES2
header instead of the regular OpenGL header. __GLFW_INCLUDE_ES2__ makes the GLFW header include the OpenGL ES 2.0
`GLES2/gl2.h` header instead of the regular OpenGL header.
`GLFW_INCLUDE_ES3` makes the GLFW header include the OpenGL ES 3.0 `GLES3/gl3.h` @anchor GLFW_INCLUDE_ES3
header instead of the regular OpenGL header. __GLFW_INCLUDE_ES3__ makes the GLFW header include the OpenGL ES 3.0
`GLES3/gl3.h` header instead of the regular OpenGL header.
`GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h` @anchor GLFW_INCLUDE_ES31
header instead of the regular OpenGL header. __GLFW_INCLUDE_ES31__ makes the GLFW header include the OpenGL ES 3.1
`GLES3/gl31.h` header instead of the regular OpenGL header.
`GLFW_INCLUDE_NONE` makes the GLFW header not include any OpenGL or OpenGL ES API @anchor GLFW_INCLUDE_NONE
header. This is useful in combination with an extension loading library. __GLFW_INCLUDE_NONE__ makes the GLFW header not include any OpenGL or OpenGL ES
API header. This is useful in combination with an extension loading library.
If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h` If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
header (`OpenGL/gl.h` on macOS) is included. header (`OpenGL/gl.h` on macOS) is included.
@ -90,14 +97,17 @@ The following macros control the inclusion of additional API headers. Any
number of these may be defined simultaneously, and/or together with one of the number of these may be defined simultaneously, and/or together with one of the
above macros. above macros.
`GLFW_INCLUDE_VULKAN` makes the GLFW header include the Vulkan `vulkan/vulkan.h` @anchor GLFW_INCLUDE_VULKAN
header in addition to any selected OpenGL or OpenGL ES header. __GLFW_INCLUDE_VULKAN__ makes the GLFW header include the Vulkan
`vulkan/vulkan.h` header in addition to any selected OpenGL or OpenGL ES header.
`GLFW_INCLUDE_GLEXT` makes the GLFW header include the appropriate extension @anchor GLFW_INCLUDE_GLEXT
__GLFW_INCLUDE_GLEXT__ makes the GLFW header include the appropriate extension
header for the OpenGL or OpenGL ES header selected above after and in addition header for the OpenGL or OpenGL ES header selected above after and in addition
to that header. to that header.
`GLFW_INCLUDE_GLU` makes the header include the GLU header in addition to the @anchor GLFW_INCLUDE_GLU
__GLFW_INCLUDE_GLU__ makes the header include the GLU header in addition to the
header selected above. This should only be used with the standard OpenGL header header selected above. This should only be used with the standard OpenGL header
and only for compatibility with legacy code. GLU has been deprecated and should and only for compatibility with legacy code. GLU has been deprecated and should
not be used in new code. not be used in new code.
@ -141,9 +151,9 @@ set of default libraries along with other dependencies like `user32` and
`kernel32`. If you are using GLU, you must also link with `glu32`. `kernel32`. If you are using GLU, you must also link with `glu32`.
The link library for the GLFW DLL is named `glfw3dll`. When compiling an The link library for the GLFW DLL is named `glfw3dll`. When compiling an
application that uses the DLL version of GLFW, you need to define the `GLFW_DLL` application that uses the DLL version of GLFW, you need to define the @ref
macro _before_ any inclusion of the GLFW header. This can be done either with GLFW_DLL macro _before_ any inclusion of the GLFW header. This can be done
a compiler switch or by defining it in your source code. either with a compiler switch or by defining it in your source code.
An application using the GLFW DLL does not need to link against any of its An application using the GLFW DLL does not need to link against any of its
dependencies, but you still have to link against `opengl32` if your application dependencies, but you still have to link against `opengl32` if your application
@ -178,8 +188,8 @@ add_subdirectory(path/to/glfw)
Once GLFW has been added to the project, link against it with the `glfw` target. Once GLFW has been added to the project, link against it with the `glfw` target.
This adds all link-time dependencies of GLFW as it is currently configured, This adds all link-time dependencies of GLFW as it is currently configured,
the include directory for the GLFW header and, when applicable, the the include directory for the GLFW header and, when applicable, the @ref
[GLFW_DLL](@ref build_macros) macro. GLFW_DLL macro.
@code{.cmake} @code{.cmake}
target_link_libraries(myapp glfw) target_link_libraries(myapp glfw)

67
docs/compile.dox
View File

@ -193,45 +193,56 @@ cmake -DBUILD_SHARED_LIBS=ON .
@subsubsection compile_options_shared Shared CMake options @subsubsection compile_options_shared Shared CMake options
`BUILD_SHARED_LIBS` determines whether GLFW is built as a static @anchor BUILD_SHARED_LIBS
__BUILD_SHARED_LIBS__ determines whether GLFW is built as a static
library or as a DLL / shared library / dynamic library. library or as a DLL / shared library / dynamic library.
`LIB_SUFFIX` affects where the GLFW shared /dynamic library is installed. If it @anchor LIB_SUFFIX
is empty, it is installed to `${CMAKE_INSTALL_PREFIX}/lib`. If it is set to __LIB_SUFFIX__ affects where the GLFW shared /dynamic library is installed. If
it is empty, it is installed to `${CMAKE_INSTALL_PREFIX}/lib`. If it is set to
`64`, it is installed to `${CMAKE_INSTALL_PREFIX}/lib64`. `64`, it is installed to `${CMAKE_INSTALL_PREFIX}/lib64`.
`GLFW_BUILD_EXAMPLES` determines whether the GLFW examples are built @anchor GLFW_BUILD_EXAMPLES
__GLFW_BUILD_EXAMPLES__ determines whether the GLFW examples are built
along with the library. along with the library.
`GLFW_BUILD_TESTS` determines whether the GLFW test programs are @anchor GLFW_BUILD_TESTS
__GLFW_BUILD_TESTS__ determines whether the GLFW test programs are
built along with the library. built along with the library.
`GLFW_BUILD_DOCS` determines whether the GLFW documentation is built along with @anchor GLFW_BUILD_DOCS
the library. __GLFW_BUILD_DOCS__ determines whether the GLFW documentation is built along
with the library.
`GLFW_VULKAN_STATIC` determines whether to use the Vulkan loader linked @anchor GLFW_VULKAN_STATIC
__GLFW_VULKAN_STATIC__ determines whether to use the Vulkan loader linked
statically into the application. statically into the application.
@subsubsection compile_options_osx macOS specific CMake options @subsubsection compile_options_osx macOS specific CMake options
`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current @anchor GLFW_USE_CHDIR
__GLFW_USE_CHDIR__ determines whether @ref glfwInit changes the current
directory of bundled applications to the `Contents/Resources` directory. directory of bundled applications to the `Contents/Resources` directory.
`GLFW_USE_MENUBAR` determines whether the first call to @anchor GLFW_USE_MENUBAR
`glfwCreateWindow` sets up a minimal menu bar. __GLFW_USE_MENUBAR__ determines whether the first call to @ref glfwCreateWindow
sets up a minimal menu bar.
`GLFW_USE_RETINA` determines whether windows will use the full resolution of @anchor GLFW_USE_RETINA
__GLFW_USE_RETINA__ determines whether windows will use the full resolution of
Retina displays. Retina displays.
@subsubsection compile_options_win32 Windows specific CMake options @subsubsection compile_options_win32 Windows specific CMake options
`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the @anchor USE_MSVC_RUNTIME_LIBRARY_DLL
__USE_MSVC_RUNTIME_LIBRARY_DLL__ determines whether to use the DLL version or the
static library version of the Visual C++ runtime library. If set to `ON`, the static library version of the Visual C++ runtime library. If set to `ON`, the
DLL version of the Visual C++ library is used. DLL version of the Visual C++ library is used.
`GLFW_USE_HYBRID_HPG` determines whether to export the `NvOptimusEnablement` and @anchor GLFW_USE_HYBRID_HPG
__GLFW_USE_HYBRID_HPG__ determines whether to export the `NvOptimusEnablement` and
`AmdPowerXpressRequestHighPerformance` symbols, which force the use of the `AmdPowerXpressRequestHighPerformance` symbols, which force the use of the
high-performance GPU on Nvidia Optimus and AMD PowerXpress systems. These symbols high-performance GPU on Nvidia Optimus and AMD PowerXpress systems. These symbols
need to be exported by the EXE to be detected by the driver, so the override need to be exported by the EXE to be detected by the driver, so the override
@ -248,46 +259,46 @@ features.
When building with CMake, the `glfw_config.h` configuration header is generated When building with CMake, the `glfw_config.h` configuration header is generated
based on the current platform and CMake options. The GLFW CMake environment based on the current platform and CMake options. The GLFW CMake environment
defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by defines @b GLFW_USE_CONFIG_H, which causes this header to be included by
`internal.h`. Without this macro, GLFW will expect the necessary configuration `internal.h`. Without this macro, GLFW will expect the necessary configuration
macros to be defined on the command-line. macros to be defined on the command-line.
The window creation API is used to create windows, handle input, monitors, gamma The window creation API is used to create windows, handle input, monitors, gamma
ramps and clipboard. The options are: ramps and clipboard. The options are:
- `_GLFW_COCOA` to use the Cocoa frameworks - @b _GLFW_COCOA to use the Cocoa frameworks
- `_GLFW_WIN32` to use the Win32 API - @b _GLFW_WIN32 to use the Win32 API
- `_GLFW_X11` to use the X Window System - @b _GLFW_X11 to use the X Window System
- `_GLFW_WAYLAND` to use the Wayland API (experimental and incomplete) - @b _GLFW_WAYLAND to use the Wayland API (experimental and incomplete)
- `_GLFW_MIR` to use the Mir API (experimental and incomplete) - @b _GLFW_MIR to use the Mir API (experimental and incomplete)
- `_GLFW_OSMESA` to use the OSMesa API (headless and non-interactive) - @b _GLFW_OSMESA to use the OSMesa API (headless and non-interactive)
If you are building GLFW as a shared library / dynamic library / DLL then you If you are building GLFW as a shared library / dynamic library / DLL then you
must also define `_GLFW_BUILD_DLL`. Otherwise, you must not define it. must also define @b _GLFW_BUILD_DLL. Otherwise, you must not define it.
If you are linking the Vulkan loader statically into your application then you If you are linking the Vulkan loader statically into your application then you
must also define `_GLFW_VULKAN_STATIC`. Otherwise, GLFW will attempt to use the must also define @b _GLFW_VULKAN_STATIC. Otherwise, GLFW will attempt to use the
external version. external version.
For the EGL context creation API, the following options are available: For the EGL context creation API, the following options are available:
- `_GLFW_USE_EGLPLATFORM_H` to use `EGL/eglplatform.h` for native handle - @b _GLFW_USE_EGLPLATFORM_H to use `EGL/eglplatform.h` for native handle
definitions (fallback) definitions (fallback)
If you are using the X11 window creation API, support for the following X11 If you are using the X11 window creation API, support for the following X11
extensions can be enabled: extensions can be enabled:
- `_GLFW_HAS_XF86VM` to use Xxf86vm as a fallback when RandR gamma is broken - @b _GLFW_HAS_XF86VM to use Xxf86vm as a fallback when RandR gamma is broken
(recommended) (recommended)
If you are using the Cocoa window creation API, the following options are If you are using the Cocoa window creation API, the following options are
available: available:
- `_GLFW_USE_CHDIR` to `chdir` to the `Resources` subdirectory of the - @b _GLFW_USE_CHDIR to `chdir` to the `Resources` subdirectory of the
application bundle during @ref glfwInit (recommended) application bundle during @ref glfwInit (recommended)
- `_GLFW_USE_MENUBAR` to create and populate the menu bar when the first window - @b _GLFW_USE_MENUBAR to create and populate the menu bar when the first window
is created (recommended) is created (recommended)
- `_GLFW_USE_RETINA` to have windows use the full resolution of Retina displays - @b _GLFW_USE_RETINA to have windows use the full resolution of Retina displays
(recommended) (recommended)
@note None of the @ref build_macros may be defined during the compilation of @note None of the @ref build_macros may be defined during the compilation of

14
docs/context.dox
View File

@ -30,8 +30,8 @@ the `glfwinfo` test program.
@note Vulkan does not have a context and the Vulkan instance is created via the @note Vulkan does not have a context and the Vulkan instance is created via the
Vulkan API itself. If you will be using Vulkan to render to a window, disable Vulkan API itself. If you will be using Vulkan to render to a window, disable
context creation by setting the [GLFW_CLIENT_API](@ref window_hints_ctx) hint to context creation by setting the [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint)
`GLFW_NO_API`. For more information, see the @ref vulkan_guide. hint to `GLFW_NO_API`. For more information, see the @ref vulkan_guide.
@subsection context_hints Context creation hints @subsection context_hints Context creation hints
@ -68,7 +68,7 @@ GLFW comes with a simple object sharing test program called `sharing`.
GLFW doesn't support creating contexts without an associated window. However, GLFW doesn't support creating contexts without an associated window. However,
contexts with hidden windows can be created with the contexts with hidden windows can be created with the
[GLFW_VISIBLE](@ref window_hints_wnd) window hint. [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window hint.
@code @code
glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE); glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);
@ -93,8 +93,8 @@ disabled with a [compile-time option](@ref compile_options_osx).
@subsection context_less Windows without contexts @subsection context_less Windows without contexts
You can disable context creation by setting the You can disable context creation by setting the
[GLFW_CLIENT_API](@ref window_hints_ctx) hint to `GLFW_NO_API`. Windows without [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_NO_API`. Windows
contexts must not be passed to @ref glfwMakeContextCurrent or @ref without contexts must not be passed to @ref glfwMakeContextCurrent or @ref
glfwSwapBuffers. glfwSwapBuffers.
@ -266,8 +266,8 @@ supports. These have names like `PFNGLGETDEBUGMESSAGELOGARBPROC` (for
`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` (pointer `glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` (pointer
to function) and `PROC` (procedure) are added to the ends. to function) and `PROC` (procedure) are added to the ends.
To include the extension header, define [GLFW_INCLUDE_GLEXT](@ref build_macros) To include the extension header, define @ref GLFW_INCLUDE_GLEXT before including
before including the GLFW header. the GLFW header.
@code @code
#define GLFW_INCLUDE_GLEXT #define GLFW_INCLUDE_GLEXT

5
docs/monitor.dox
View File

@ -213,4 +213,9 @@ glfwSetGammaRamp with the resulting ramp.
glfwSetGamma(monitor, 1.0); glfwSetGamma(monitor, 1.0);
@endcode @endcode
@note The software controlled gamma ramp is applied _in addition_ to the
hardware gamma correction, which today is usually an approximation of sRGB
gamma. This means that setting a perfectly linear ramp, or gamma 1.0, will
produce the default (usually sRGB-like) behavior.
*/ */

2
docs/moving.dox
View File

@ -434,7 +434,7 @@ 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 deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). __New
projects should not use GLU__, but if you need it for legacy code that projects should not use GLU__, but if you need it for legacy code that
has been moved to GLFW 3, you can request that the GLFW header includes it by 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. defining @ref GLFW_INCLUDE_GLU before the inclusion of the GLFW header.
@par Old syntax @par Old syntax
@code @code

69
docs/news.dox
View File

@ -19,7 +19,7 @@ GLFW now supports querying the platform dependent scancode of any key with
@subsection news_33_moltenvk Support for Vulkan on macOS via MoltenVK @subsection news_33_moltenvk Support for Vulkan on macOS via MoltenVK
GLFW now supports the `VK_MVK_macos_surface` window surface creation extension GLFW now supports the `VK_MVK_macos_surface` window surface creation extension
provided by MoltenVK. provided by [MoltenVK](https://moltengl.com/moltenvk/).
@subsection news_33_osmesa OSMesa backend for headless software rendering @subsection news_33_osmesa OSMesa backend for headless software rendering
@ -37,7 +37,7 @@ GLFW now supports basic integration with Vulkan with @ref glfwVulkanSupported,
@ref glfwGetRequiredInstanceExtensions, @ref glfwGetInstanceProcAddress, @ref @ref glfwGetRequiredInstanceExtensions, @ref glfwGetInstanceProcAddress, @ref
glfwGetPhysicalDevicePresentationSupport and @ref glfwCreateWindowSurface. glfwGetPhysicalDevicePresentationSupport and @ref glfwCreateWindowSurface.
Vulkan header inclusion can be selected with Vulkan header inclusion can be selected with
[GLFW_INCLUDE_VULKAN](@ref build_macros). @ref GLFW_INCLUDE_VULKAN.
@subsection news_32_setwindowmonitor Window mode switching @subsection news_32_setwindowmonitor Window mode switching
@ -50,7 +50,7 @@ the monitor and desired resolution and refresh rate of full screen windows with
@subsection news_32_maximize Window maxmimization support @subsection news_32_maximize Window maxmimization support
GLFW now supports window maximization with @ref glfwMaximizeWindow and the GLFW now supports window maximization with @ref glfwMaximizeWindow and the
[GLFW_MAXIMIZED](@ref window_attribs_wnd) window hint and attribute. @ref GLFW_MAXIMIZED window hint and attribute.
@subsection news_32_focus Window input focus control @subsection news_32_focus Window input focus control
@ -95,21 +95,21 @@ with @ref glfwSetJoystickCallback.
@subsection news_32_noapi Context-less windows @subsection news_32_noapi Context-less windows
GLFW now supports creating windows without a OpenGL or OpenGL ES context with GLFW now supports creating windows without a OpenGL or OpenGL ES context by
[GLFW_NO_API](@ref window_hints_ctx). setting the [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_NO_API`.
@subsection news_32_contextapi Run-time context creation API selection @subsection news_32_contextapi Run-time context creation API selection
GLFW now supports selecting the context creation API at run-time with the GLFW now supports selecting and querying the context creation API at run-time
[GLFW_CONTEXT_CREATION_API](@ref window_hints_ctx) window hint value. with the @ref GLFW_CONTEXT_CREATION_API hint and attribute.
@subsection news_32_noerror Error-free context creation @subsection news_32_noerror Error-free context creation
GLFW now supports creating OpenGL and OpenGL ES contexts that do not emit errors GLFW now supports creating and querying OpenGL and OpenGL ES contexts that do
with the [GLFW_CONTEXT_NO_ERROR](@ref window_hints_ctx) window hint, provided not emit errors with the @ref GLFW_CONTEXT_NO_ERROR hint, provided the machine
the machine supports the `GL_KHR_no_error` extension. supports the `GL_KHR_no_error` extension.
@subsection news_32_cmake CMake config-file package support @subsection news_32_cmake CMake config-file package support
@ -163,21 +163,21 @@ client area of a window, with @ref glfwGetWindowFrameSize.
@subsection news_31_autoiconify Simultaneous multi-monitor rendering @subsection news_31_autoiconify Simultaneous multi-monitor rendering
GLFW now supports disabling auto-iconification of full screen windows with GLFW now supports disabling auto-iconification of full screen windows with
the [GLFW_AUTO_ICONIFY](@ref window_hints_wnd) window hint. This is intended the [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_hint) window hint. This is
for people building multi-monitor installations, where you need windows to stay intended for people building multi-monitor installations, where you need windows
in full screen despite losing input focus. to stay in full screen despite losing input focus.
@subsection news_31_floating Floating windows @subsection news_31_floating Floating windows
GLFW now supports floating windows, also called topmost or always on top, for GLFW now supports floating windows, also called topmost or always on top, for
easier debugging with the [GLFW_FLOATING](@ref window_hints_wnd) window hint. easier debugging with the @ref GLFW_FLOATING window hint and attribute.
@subsection news_31_focused Initially unfocused windows @subsection news_31_focused Initially unfocused windows
GLFW now supports preventing a windowed mode window from gaining input focus on GLFW now supports preventing a windowed mode window from gaining input focus on
creation, with the [GLFW_FOCUSED](@ref window_hints_wnd) window hint. creation, with the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) window hint.
@subsection news_31_direct Direct access for window attributes and cursor position @subsection news_31_direct Direct access for window attributes and cursor position
@ -198,24 +198,24 @@ being input, for example if the Control key is held down.
@subsection news_31_single Single buffered framebuffers @subsection news_31_single Single buffered framebuffers
GLFW now supports the creation of single buffered windows, with the GLFW now supports the creation of single buffered windows, with the @ref
[GLFW_DOUBLEBUFFER](@ref window_hints_fb) window hint. GLFW_DOUBLEBUFFER hint.
@subsection news_31_glext Macro for including extension header @subsection news_31_glext Macro for including extension header
GLFW now includes the extension header appropriate for the chosen OpenGL or GLFW now includes the extension header appropriate for the chosen OpenGL or
OpenGL ES header when [GLFW_INCLUDE_GLEXT](@ref build_macros) is defined. GLFW OpenGL ES header when @ref GLFW_INCLUDE_GLEXT is defined. GLFW does not provide
does not provide these headers. They must be provided by your development these headers. They must be provided by your development environment or your
environment or your OpenGL or OpenGL ES SDK. OpenGL or OpenGL ES SDK.
@subsection news_31_release Context release behaviors @subsection news_31_release Context release behaviors
GLFW now supports controlling whether the pipeline is flushed when a context is GLFW now supports controlling and querying whether the pipeline is flushed when
made non-current, with the a context is made non-current, with the @ref GLFW_CONTEXT_RELEASE_BEHAVIOR hint
[GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint, provided the and attribute, provided the machine supports the `GL_KHR_context_flush_control`
machine supports the `GL_KHR_context_flush_control` extension. extension.
@subsection news_31_wayland (Experimental) Wayland support @subsection news_31_wayland (Experimental) Wayland support
@ -290,11 +290,11 @@ glfwSetGamma, which generates a ramp from a gamma value and then sets it.
@subsection news_30_gles OpenGL ES support @subsection news_30_gles OpenGL ES support
GLFW now supports the creation of OpenGL ES contexts, by setting the GLFW now supports the creation of OpenGL ES contexts, by setting the
`GLFW_CLIENT_API` window hint to `GLFW_OPENGL_ES_API`, where creation of such [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_OPENGL_ES_API`, where
contexts are supported. Note that GLFW _does not implement_ OpenGL ES, so your creation of such contexts are supported. Note that GLFW _does not implement_
driver must provide support in a way usable by GLFW. Modern Nvidia and Intel OpenGL ES, so your driver must provide support in a way usable by GLFW. Modern
drivers support creation of OpenGL ES context using the GLX and WGL APIs, while Nvidia and Intel drivers support creation of OpenGL ES context using the GLX and
AMD provides an EGL implementation instead. WGL APIs, while AMD provides an EGL implementation instead.
@subsection news_30_egl (Experimental) EGL support @subsection news_30_egl (Experimental) EGL support
@ -365,16 +365,17 @@ to @ref glfwCreateWindow.
@subsection news_30_hidden Hidden windows @subsection news_30_hidden Hidden windows
Windows can now be hidden with @ref glfwHideWindow, shown using @ref Windows can now be hidden with @ref glfwHideWindow, shown using @ref
glfwShowWindow and created initially hidden with the `GLFW_VISIBLE` window hint. glfwShowWindow and created initially hidden with the @ref GLFW_VISIBLE window
This allows for off-screen rendering in a way compatible with most drivers, as hint and attribute. This allows for off-screen rendering in a way compatible
well as moving a window to a specific position before showing it. with most drivers, as well as moving a window to a specific position before
showing it.
@subsection news_30_undecorated Undecorated windows @subsection news_30_undecorated Undecorated windows
Windowed mode windows can now be created without decorations, e.g. things like Windowed mode windows can now be created without decorations, e.g. things like
a frame, a title bar, with the `GLFW_DECORATED` window hint. This allows for a frame, a title bar, with the @ref GLFW_DECORATED window hint and attribute.
the creation of things like splash screens. This allows for the creation of things like splash screens.
@subsection news_30_keymods Modifier key bit masks @subsection news_30_keymods Modifier key bit masks

19
docs/vulkan.dox
View File

@ -38,22 +38,21 @@ Unix-like systems). This means that GLFW does not need to be linked against the
loader. However, it also means that if you are using the static library form of loader. However, it also means that if you are using the static library form of
the Vulkan loader GLFW will either fail to find it or (worse) use the wrong one. the Vulkan loader GLFW will either fail to find it or (worse) use the wrong one.
The [GLFW_VULKAN_STATIC](@ref compile_options_shared) CMake option makes GLFW The @ref GLFW_VULKAN_STATIC CMake option makes GLFW link directly against the
link directly against the static form. Not linking against the Vulkan loader static form. Not linking against the Vulkan loader will then be a compile-time
will then be a compile-time error. error.
@macos MoltenVK only provides the static library form of the Vulkan loader, but @macos MoltenVK only provides the static library form of the Vulkan loader, but
GLFW is able to find it without GLFW is able to find it without @ref GLFW_VULKAN_STATIC as long as it is linked
[GLFW_VULKAN_STATIC](@ref compile_options_shared) as long as it is linked into into any of the binaries already loaded into the process. As it is a static
any of the binaries already loaded into the process. As it is a static library, library, you must also link against its dependencies: the `Cocoa`, `Metal` and
you must also link against its dependencies: the `Cocoa`, `Metal` and
`QuartzCore` frameworks and the `libc++` library. `QuartzCore` frameworks and the `libc++` library.
@section vulkan_include Including the Vulkan and GLFW header files @section vulkan_include Including the Vulkan and GLFW header files
To include the Vulkan header, define [GLFW_INCLUDE_VULKAN](@ref build_macros) To include the Vulkan header, define @ref GLFW_INCLUDE_VULKAN before including
before including the GLFW header. the GLFW header.
@code @code
#define GLFW_INCLUDE_VULKAN #define GLFW_INCLUDE_VULKAN
@ -203,7 +202,7 @@ an existing Vulkan surface.
Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan, Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan,
there is no need to create a context. You can disable context creation with the there is no need to create a context. You can disable context creation with the
[GLFW_CLIENT_API](@ref window_hints_ctx) hint. [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint.
@code @code
glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API); glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);

364
docs/window.dox
View File

@ -71,10 +71,10 @@ Video mode field | Corresponds to
----------------------- | ------------------------ ----------------------- | ------------------------
GLFWvidmode.width | `width` parameter GLFWvidmode.width | `width` parameter
GLFWvidmode.height | `height` parameter GLFWvidmode.height | `height` parameter
GLFWvidmode.redBits | `GLFW_RED_BITS` hint GLFWvidmode.redBits | @ref GLFW_RED_BITS hint
GLFWvidmode.greenBits | `GLFW_GREEN_BITS` hint GLFWvidmode.greenBits | @ref GLFW_GREEN_BITS hint
GLFWvidmode.blueBits | `GLFW_BLUE_BITS` hint GLFWvidmode.blueBits | @ref GLFW_BLUE_BITS hint
GLFWvidmode.refreshRate | `GLFW_REFRESH_RATE` hint GLFWvidmode.refreshRate | @ref GLFW_REFRESH_RATE hint
Once you have a full screen window, you can change its resolution, refresh rate Once you have a full screen window, you can change its resolution, refresh rate
and monitor with @ref glfwSetWindowMonitor. If you just need change its and monitor with @ref glfwSetWindowMonitor. If you just need change its
@ -85,9 +85,9 @@ unaffected.
By default, the original video mode of the monitor will be restored and the By default, the original video mode of the monitor will be restored and the
window iconified if it loses input focus, to allow the user to switch back to window iconified if it loses input focus, to allow the user to switch back to
the desktop. This behavior can be disabled with the `GLFW_AUTO_ICONIFY` window the desktop. This behavior can be disabled with the
hint, for example if you wish to simultaneously cover multiple windows with full [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_hint) window hint, for example if you
screen windows. wish to simultaneously cover multiple windows with full screen windows.
@subsubsection window_windowed_full_screen "Windowed full screen" windows @subsubsection window_windowed_full_screen "Windowed full screen" windows
@ -158,102 +158,128 @@ that are not hard constraints are matched as closely as possible, but the
resulting context and framebuffer may differ from what these hints requested. resulting context and framebuffer may differ from what these hints requested.
The following hints are always hard constraints: The following hints are always hard constraints:
- `GLFW_STEREO` - @ref GLFW_STEREO
- `GLFW_DOUBLEBUFFER` - @ref GLFW_DOUBLEBUFFER
- `GLFW_CLIENT_API` - [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint)
- `GLFW_CONTEXT_CREATION_API` - [GLFW_CONTEXT_CREATION_API](@ref GLFW_CONTEXT_CREATION_API_hint)
The following additional hints are hard constraints when requesting an OpenGL The following additional hints are hard constraints when requesting an OpenGL
context, but are ignored when requesting an OpenGL ES context: context, but are ignored when requesting an OpenGL ES context:
- `GLFW_OPENGL_FORWARD_COMPAT` - [GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint)
- `GLFW_OPENGL_PROFILE` - [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint)
@subsubsection window_hints_wnd Window related hints @subsubsection window_hints_wnd Window related hints
`GLFW_RESIZABLE` specifies whether the windowed mode window will be resizable @anchor GLFW_RESIZABLE_hint
__GLFW_RESIZABLE__ specifies whether the windowed mode window will be resizable
_by the user_. The window will still be resizable using the @ref _by the user_. The window will still be resizable using the @ref
glfwSetWindowSize function. This hint is ignored for full screen and glfwSetWindowSize function. This hint is ignored for full screen and
undecorated windows. undecorated windows.
`GLFW_VISIBLE` specifies whether the windowed mode window will be initially @anchor GLFW_VISIBLE_hint
__GLFW_VISIBLE__ specifies whether the windowed mode window will be initially
visible. This hint is ignored for full screen windows. visible. This hint is ignored for full screen windows.
`GLFW_DECORATED` specifies whether the windowed mode window will have window @anchor GLFW_DECORATED_hint
__GLFW_DECORATED__ specifies whether the windowed mode window will have window
decorations such as a border, a close widget, etc. An undecorated window will decorations such as a border, a close widget, etc. An undecorated window will
not be resizable by the user but will still allow the user to generate close not be resizable by the user but will still allow the user to generate close
events on some platforms. This hint is ignored for full screen windows. events on some platforms. This hint is ignored for full screen windows.
`GLFW_FOCUSED` specifies whether the windowed mode window will be given input @anchor GLFW_FOCUSED_hint
__GLFW_FOCUSED__ specifies whether the windowed mode window will be given input
focus when created. This hint is ignored for full screen and initially hidden focus when created. This hint is ignored for full screen and initially hidden
windows. windows.
`GLFW_AUTO_ICONIFY` specifies whether the full screen window will @anchor GLFW_AUTO_ICONIFY_hint
__GLFW_AUTO_ICONIFY__ specifies whether the full screen window will
automatically iconify and restore the previous video mode on input focus loss. automatically iconify and restore the previous video mode on input focus loss.
This hint is ignored for windowed mode windows. This hint is ignored for windowed mode windows.
`GLFW_FLOATING` specifies whether the windowed mode window will be floating @anchor GLFW_FLOATING_hint
__GLFW_FLOATING__ specifies whether the windowed mode window will be floating
above other regular windows, also called topmost or always-on-top. This is above other regular windows, also called topmost or always-on-top. This is
intended primarily for debugging purposes and cannot be used to implement proper intended primarily for debugging purposes and cannot be used to implement proper
full screen windows. This hint is ignored for full screen windows. full screen windows. This hint is ignored for full screen windows.
`GLFW_MAXIMIZED` specifies whether the windowed mode window will be maximized @anchor GLFW_MAXIMIZED_hint
__GLFW_MAXIMIZED__ specifies whether the windowed mode window will be maximized
when created. This hint is ignored for full screen windows. when created. This hint is ignored for full screen windows.
@subsubsection window_hints_fb Framebuffer related hints @subsubsection window_hints_fb Framebuffer related hints
`GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`, @anchor GLFW_RED_BITS
`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` specify the desired bit depths of the @anchor GLFW_GREEN_BITS
various components of the default framebuffer. `GLFW_DONT_CARE` means the @anchor GLFW_BLUE_BITS
application has no preference. @anchor GLFW_ALPHA_BITS
@anchor GLFW_DEPTH_BITS
@anchor GLFW_STENCIL_BITS
__GLFW_RED_BITS__, __GLFW_GREEN_BITS__, __GLFW_BLUE_BITS__, __GLFW_ALPHA_BITS__,
__GLFW_DEPTH_BITS__ and __GLFW_STENCIL_BITS__ specify the desired bit depths of
the various components of the default framebuffer. A value of `GLFW_DONT_CARE`
means the application has no preference.
`GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` and @anchor GLFW_ACCUM_RED_BITS
`GLFW_ACCUM_ALPHA_BITS` specify the desired bit depths of the various components @anchor GLFW_ACCUM_GREEN_BITS
of the accumulation buffer. `GLFW_DONT_CARE` means the application has no @anchor GLFW_ACCUM_BLUE_BITS
preference. @anchor GLFW_ACCUM_ALPHA_BITS
__GLFW_ACCUM_RED_BITS__, __GLFW_ACCUM_GREEN_BITS__, __GLFW_ACCUM_BLUE_BITS__ and
__GLFW_ACCUM_ALPHA_BITS__ specify the desired bit depths of the various
components of the accumulation buffer. A value of `GLFW_DONT_CARE` means the
application has no preference.
@par @par
Accumulation buffers are a legacy OpenGL feature and should not be used in new Accumulation buffers are a legacy OpenGL feature and should not be used in new
code. code.
`GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers. @anchor GLFW_AUX_BUFFERS
`GLFW_DONT_CARE` means the application has no preference. __GLFW_AUX_BUFFERS__ specifies the desired number of auxiliary buffers. A value
of `GLFW_DONT_CARE` means the application has no preference.
@par @par
Auxiliary buffers are a legacy OpenGL feature and should not be used in new Auxiliary buffers are a legacy OpenGL feature and should not be used in new
code. code.
`GLFW_STEREO` specifies whether to use stereoscopic rendering. This is a hard @anchor GLFW_STEREO
constraint. __GLFW_STEREO__ specifies whether to use OpenGL stereoscopic rendering. This is
a hard constraint.
`GLFW_SAMPLES` specifies the desired number of samples to use for multisampling. @anchor GLFW_SAMPLES
Zero disables multisampling. `GLFW_DONT_CARE` means the application has no __GLFW_SAMPLES__ specifies the desired number of samples to use for
preference. multisampling. Zero disables multisampling. A value of `GLFW_DONT_CARE` means
the application has no preference.
`GLFW_SRGB_CAPABLE` specifies whether the framebuffer should be sRGB capable. @anchor GLFW_SRGB_CAPABLE
__GLFW_SRGB_CAPABLE__ specifies whether the framebuffer should be sRGB capable.
If supported, a created OpenGL context will support the `GL_FRAMEBUFFER_SRGB` If supported, a created OpenGL context will support the `GL_FRAMEBUFFER_SRGB`
enable, also called `GL_FRAMEBUFFER_SRGB_EXT`) for controlling sRGB rendering enable, also called `GL_FRAMEBUFFER_SRGB_EXT`) for controlling sRGB rendering
and a created OpenGL ES context will always have sRGB rendering enabled. and a created OpenGL ES context will always have sRGB rendering enabled.
`GLFW_DOUBLEBUFFER` specifies whether the framebuffer should be double buffered. @anchor GLFW_DOUBLEBUFFER
You nearly always want to use double buffering. This is a hard constraint. __GLFW_DOUBLEBUFFER__ specifies whether the framebuffer should be double
buffered. You nearly always want to use double buffering. This is a hard
constraint.
@subsubsection window_hints_mtr Monitor related hints @subsubsection window_hints_mtr Monitor related hints
`GLFW_REFRESH_RATE` specifies the desired refresh rate for full screen windows. @anchor GLFW_REFRESH_RATE
If set to `GLFW_DONT_CARE`, the highest available refresh rate will be used. __GLFW_REFRESH_RATE__ specifies the desired refresh rate for full screen
This hint is ignored for windowed mode windows. windows. A value of `GLFW_DONT_CARE` means the highest available refresh rate
will be used. This hint is ignored for windowed mode windows.
@subsubsection window_hints_ctx Context related hints @subsubsection window_hints_ctx Context related hints
`GLFW_CLIENT_API` specifies which client API to create the context for. @anchor GLFW_CLIENT_API_hint
__GLFW_CLIENT_API__ specifies which client API to create the context for.
Possible values are `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` and `GLFW_NO_API`. Possible values are `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` and `GLFW_NO_API`.
This is a hard constraint. This is a hard constraint.
`GLFW_CONTEXT_CREATION_API` specifies which context creation API to use to @anchor GLFW_CONTEXT_CREATION_API_hint
__GLFW_CONTEXT_CREATION_API__ specifies which context creation API to use to
create the context. Possible values are `GLFW_NATIVE_CONTEXT_API` and create the context. Possible values are `GLFW_NATIVE_CONTEXT_API` and
`GLFW_EGL_CONTEXT_API`. This is a hard constraint. If no client API is `GLFW_EGL_CONTEXT_API`. This is a hard constraint. If no client API is
requested, this hint is ignored. requested, this hint is ignored.
@ -275,16 +301,18 @@ the selected API.
in a single process will cause the application to segfault. Stick to one API or in a single process will cause the application to segfault. Stick to one API or
the other on Linux for now. the other on Linux for now.
`GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client @anchor GLFW_CONTEXT_VERSION_MAJOR_hint
API version that the created context must be compatible with. The exact @anchor GLFW_CONTEXT_VERSION_MINOR_hint
__GLFW_CONTEXT_VERSION_MAJOR__ and __GLFW_CONTEXT_VERSION_MINOR__ specify the
client API version that the created context must be compatible with. The exact
behavior of these hints depend on the requested client API. behavior of these hints depend on the requested client API.
@par @par
__OpenGL:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are __OpenGL:__ These hints are not hard constraints, but creation will fail if the
not hard constraints, but creation will fail if the OpenGL version of the OpenGL version of the created context is less than the one requested. It is
created context is less than the one requested. It is therefore perfectly safe therefore perfectly safe to use the default of version 1.0 for legacy code and
to use the default of version 1.0 for legacy code and you will still get you will still get backwards-compatible contexts of version 3.0 and above when
backwards-compatible contexts of version 3.0 and above when available. available.
@par @par
While there is no way to ask the driver for a context of the highest supported While there is no way to ask the driver for a context of the highest supported
@ -292,21 +320,21 @@ version, GLFW will attempt to provide this when you ask for a version 1.0
context, which is the default for these hints. context, which is the default for these hints.
@par @par
__OpenGL ES:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are __OpenGL ES:__ These hints are not hard constraints, but creation will fail if
not hard constraints, but creation will fail if the OpenGL ES version of the the OpenGL ES version of the created context is less than the one requested.
created context is less than the one requested. Additionally, OpenGL ES 1.x Additionally, OpenGL ES 1.x cannot be returned if 2.0 or later was requested,
cannot be returned if 2.0 or later was requested, and vice versa. This is and vice versa. This is because OpenGL ES 3.x is backward compatible with 2.0,
because OpenGL ES 3.x is backward compatible with 2.0, but OpenGL ES 2.0 is not but OpenGL ES 2.0 is not backward compatible with 1.x.
backward compatible with 1.x.
@note @macos The OS only supports forward-compatible core profile contexts for @note @macos The OS only supports forward-compatible core profile contexts for
OpenGL versions 3.2 and later. Before creating an OpenGL context of version OpenGL versions 3.2 and later. Before creating an OpenGL context of version
3.2 or later you must set the `GLFW_OPENGL_FORWARD_COMPAT` and 3.2 or later you must set the
`GLFW_OPENGL_PROFILE` hints accordingly. OpenGL 3.0 and 3.1 contexts are not [GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint) and
supported at all on macOS. [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) hints accordingly. OpenGL
3.0 and 3.1 contexts are not supported at all on macOS.
@anchor GLFW_OPENGL_FORWARD_COMPAT_hint
`GLFW_OPENGL_FORWARD_COMPAT` specifies whether the OpenGL context should be __GLFW_OPENGL_FORWARD_COMPAT__ specifies whether the OpenGL context should be
forward-compatible, i.e. one where all functionality deprecated in the requested forward-compatible, i.e. one where all functionality deprecated in the requested
version of OpenGL is removed. This must only be used if the requested OpenGL version of OpenGL is removed. This must only be used if the requested OpenGL
version is 3.0 or above. If OpenGL ES is requested, this hint is ignored. version is 3.0 or above. If OpenGL ES is requested, this hint is ignored.
@ -315,27 +343,31 @@ version is 3.0 or above. If OpenGL ES is requested, this hint is ignored.
Forward-compatibility is described in detail in the Forward-compatibility is described in detail in the
[OpenGL Reference Manual](https://www.opengl.org/registry/). [OpenGL Reference Manual](https://www.opengl.org/registry/).
`GLFW_OPENGL_DEBUG_CONTEXT` specifies whether to create a debug OpenGL context, @anchor GLFW_OPENGL_DEBUG_CONTEXT_hint
which may have additional error and performance issue reporting functionality. __GLFW_OPENGL_DEBUG_CONTEXT__ specifies whether to create a debug OpenGL
If OpenGL ES is requested, this hint is ignored. context, which may have additional error and performance issue reporting
functionality. If OpenGL ES is requested, this hint is ignored.
`GLFW_OPENGL_PROFILE` specifies which OpenGL profile to create the context for. @anchor GLFW_OPENGL_PROFILE_hint
Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or __GLFW_OPENGL_PROFILE__ specifies which OpenGL profile to create the context
for. Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or
`GLFW_OPENGL_COMPAT_PROFILE`, or `GLFW_OPENGL_ANY_PROFILE` to not request `GLFW_OPENGL_COMPAT_PROFILE`, or `GLFW_OPENGL_ANY_PROFILE` to not request
a specific profile. If requesting an OpenGL version below 3.2, a specific profile. If requesting an OpenGL version below 3.2,
`GLFW_OPENGL_ANY_PROFILE` must be used. If OpenGL ES is requested, `GLFW_OPENGL_ANY_PROFILE` must be used. If OpenGL ES is requested, this hint
this hint is ignored. is ignored.
@par @par
OpenGL profiles are described in detail in the OpenGL profiles are described in detail in the
[OpenGL Reference Manual](https://www.opengl.org/registry/). [OpenGL Reference Manual](https://www.opengl.org/registry/).
`GLFW_CONTEXT_ROBUSTNESS` specifies the robustness strategy to be used by the @anchor GLFW_CONTEXT_ROBUSTNESS_hint
__GLFW_CONTEXT_ROBUSTNESS__ specifies the robustness strategy to be used by the
context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or
`GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request `GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
a robustness strategy. a robustness strategy.
`GLFW_CONTEXT_RELEASE_BEHAVIOR` specifies the release behavior to be @anchor GLFW_CONTEXT_RELEASE_BEHAVIOR_hint
__GLFW_CONTEXT_RELEASE_BEHAVIOR__ specifies the release behavior to be
used by the context. Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`, used by the context. Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`,
`GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`. If the `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`. If the
behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context
@ -349,7 +381,8 @@ Context release behaviors are described in detail by the
[GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt) [GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
extension. extension.
`GLFW_CONTEXT_NO_ERROR` specifies whether errors should be generated by the @anchor GLFW_CONTEXT_NO_ERROR_hint
__GLFW_CONTEXT_NO_ERROR__ specifies whether errors should be generated by the
context. If enabled, situations that would have generated errors instead cause context. If enabled, situations that would have generated errors instead cause
undefined behavior. undefined behavior.
@ -369,40 +402,40 @@ being listed.
@subsubsection window_hints_values Supported and default values @subsubsection window_hints_values Supported and default values
Window hint | Default value | Supported values Window hint | Default value | Supported values
------------------------------- | --------------------------- | ---------------- ----------------------------- | --------------------------- | ----------------
`GLFW_RESIZABLE` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_RESIZABLE | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_VISIBLE` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_VISIBLE | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_DECORATED` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_DECORATED | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_FOCUSED` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_FOCUSED | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_AUTO_ICONIFY` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_AUTO_ICONIFY | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_FLOATING` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_FLOATING | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_MAXIMIZED` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_MAXIMIZED | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_RED_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_RED_BITS | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_GREEN_BITS | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_BLUE_BITS | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_ALPHA_BITS | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_DEPTH_BITS | 24 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_STENCIL_BITS | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_ACCUM_RED_BITS | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_ACCUM_GREEN_BITS | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_ACCUM_BLUE_BITS | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_ACCUM_ALPHA_BITS | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_AUX_BUFFERS | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_SAMPLES` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_SAMPLES | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_REFRESH_RATE` | `GLFW_DONT_CARE` | 0 to `INT_MAX` or `GLFW_DONT_CARE` GLFW_REFRESH_RATE | `GLFW_DONT_CARE` | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_STEREO` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_STEREO | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_SRGB_CAPABLE` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_SRGB_CAPABLE | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_DOUBLEBUFFER` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_DOUBLEBUFFER | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_CLIENT_API` | `GLFW_OPENGL_API` | `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API` GLFW_CLIENT_API | `GLFW_OPENGL_API` | `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`
`GLFW_CONTEXT_CREATION_API` | `GLFW_NATIVE_CONTEXT_API` | `GLFW_NATIVE_CONTEXT_API` or `GLFW_EGL_CONTEXT_API` GLFW_CONTEXT_CREATION_API | `GLFW_NATIVE_CONTEXT_API` | `GLFW_NATIVE_CONTEXT_API` or `GLFW_EGL_CONTEXT_API`
`GLFW_CONTEXT_VERSION_MAJOR` | 1 | Any valid major version number of the chosen client API GLFW_CONTEXT_VERSION_MAJOR | 1 | Any valid major version number of the chosen client API
`GLFW_CONTEXT_VERSION_MINOR` | 0 | Any valid minor version number of the chosen client API GLFW_CONTEXT_VERSION_MINOR | 0 | Any valid minor version number of the chosen client API
`GLFW_CONTEXT_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET` GLFW_CONTEXT_ROBUSTNESS | `GLFW_NO_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET`
`GLFW_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE` GLFW_CONTEXT_RELEASE_BEHAVIOR | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`
`GLFW_OPENGL_FORWARD_COMPAT` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_OPENGL_FORWARD_COMPAT | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_OPENGL_DEBUG_CONTEXT` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE` GLFW_OPENGL_DEBUG_CONTEXT | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
`GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_ANY_PROFILE` | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` GLFW_OPENGL_PROFILE | `GLFW_OPENGL_ANY_PROFILE` | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE`
@section window_events Window event processing @section window_events Window event processing
@ -825,6 +858,14 @@ You can also get the current maximization state with @ref glfwGetWindowAttrib.
int maximized = glfwGetWindowAttrib(window, GLFW_MAXIMIZED); int maximized = glfwGetWindowAttrib(window, GLFW_MAXIMIZED);
@endcode @endcode
By default, newly created windows are not maximized. You can change this
behavior by setting the [GLFW_MAXIMIZED](@ref GLFW_MAXIMIZED_hint) window hint
before creating the window.
@code
glfwWindowHint(GLFW_MAXIMIZED, GLFW_TRUE);
@endcode
@subsection window_hide Window visibility @subsection window_hide Window visibility
@ -844,11 +885,6 @@ Hidden windows can be shown with @ref glfwShowWindow.
glfwShowWindow(window); glfwShowWindow(window);
@endcode @endcode
Windowed mode windows can be created initially hidden with the `GLFW_VISIBLE`
[window hint](@ref window_hints_wnd). Windows created hidden are completely
invisible to the user until shown. This can be useful if you need to set up
your window further before showing it, for example moving it to a specific
location.
You can also get the current visibility state with @ref glfwGetWindowAttrib. You can also get the current visibility state with @ref glfwGetWindowAttrib.
@ -856,6 +892,18 @@ You can also get the current visibility state with @ref glfwGetWindowAttrib.
int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE); int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
@endcode @endcode
By default, newly created windows are visible. You can change this behavior by
setting the [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window hint before creating
the window.
@code
glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);
@endcode
Windows created hidden are completely invisible to the user until shown. This
can be useful if you need to set up your window further before showing it, for
example moving it to a specific location.
@subsection window_focus Window input focus @subsection window_focus Window input focus
@ -895,6 +943,14 @@ You can also get the current input focus state with @ref glfwGetWindowAttrib.
int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED); int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
@endcode @endcode
By default, newly created windows are given input focus. You can change this
behavior by setting the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) window hint
before creating the window.
@code
glfwWindowHint(GLFW_FOCUSED, GLFW_FALSE);
@endcode
@subsection window_refresh Window damage and refresh @subsection window_refresh Window damage and refresh
@ -939,62 +995,76 @@ if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
@subsubsection window_attribs_wnd Window related attributes @subsubsection window_attribs_wnd Window related attributes
`GLFW_FOCUSED` indicates whether the specified window has input focus. Initial @anchor GLFW_FOCUSED_attrib
input focus is controlled by the [window hint](@ref window_hints_wnd) with the __GLFW_FOCUSED__ indicates whether the specified window has input focus. See
same name. @ref window_focus for details.
`GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by @anchor GLFW_ICONIFIED_attrib
the user or with @ref glfwIconifyWindow. __GLFW_ICONIFIED__ indicates whether the specified window is iconified.
See @ref window_iconify for details.
`GLFW_MAXIMIZED` indicates whether the specified window is maximized, whether by @anchor GLFW_MAXIMIZED_attrib
the user or with @ref glfwMaximizeWindow. __GLFW_MAXIMIZED__ indicates whether the specified window is maximized. See
@ref window_maximize for details.
`GLFW_VISIBLE` indicates whether the specified window is visible. Window @anchor GLFW_VISIBLE_attrib
visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow __GLFW_VISIBLE__ indicates whether the specified window is visible. See @ref
and initial visibility is controlled by the [window hint](@ref window_hints_wnd) window_hide for details.
with the same name.
`GLFW_RESIZABLE` indicates whether the specified window is resizable _by the @anchor GLFW_RESIZABLE_attrib
user_. This is set on creation with the [window hint](@ref window_hints_wnd) __GLFW_RESIZABLE__ indicates whether the specified window is resizable _by the
with the same name. user_. This is set before creation with the
[GLFW_RESIZABLE](@ref GLFW_RESIZABLE_hint) window hint.
`GLFW_DECORATED` indicates whether the specified window has decorations such as @anchor GLFW_DECORATED_attrib
a border, a close widget, etc. This is set on creation with the __GLFW_DECORATED__ indicates whether the specified window has decorations such as
[window hint](@ref window_hints_wnd) with the same name. a border, a close widget, etc. This is set before creation with the
[GLFW_DECORATED](@ref GLFW_DECORATED_hint) window hint.
`GLFW_FLOATING` indicates whether the specified window is floating, also called @anchor GLFW_FLOATING_attrib
topmost or always-on-top. This is controlled by the __GLFW_FLOATING__ indicates whether the specified window is floating, also
[window hint](@ref window_hints_wnd) with the same name. called topmost or always-on-top. This is controlled by the
[GLFW_FLOATING](@ref GLFW_FLOATING_hint) window hint.
@subsubsection window_attribs_ctx Context related attributes @subsubsection window_attribs_ctx Context related attributes
`GLFW_CLIENT_API` indicates the client API provided by the window's context; @anchor GLFW_CLIENT_API_attrib
__GLFW_CLIENT_API__ indicates the client API provided by the window's context;
either `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`. either `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`.
`GLFW_CONTEXT_CREATION_API` indicates the context creation API used to create @anchor GLFW_CONTEXT_CREATION_API_attrib
__GLFW_CONTEXT_CREATION_API__ indicates the context creation API used to create
the window's context; either `GLFW_NATIVE_CONTEXT_API` or the window's context; either `GLFW_NATIVE_CONTEXT_API` or
`GLFW_EGL_CONTEXT_API`. `GLFW_EGL_CONTEXT_API`.
`GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and @anchor GLFW_CONTEXT_VERSION_MAJOR_attrib
`GLFW_CONTEXT_REVISION` indicate the client API version of the window's context. @anchor GLFW_CONTEXT_VERSION_MINOR_attrib
@anchor GLFW_CONTEXT_REVISION_attrib
__GLFW_CONTEXT_VERSION_MAJOR__, __GLFW_CONTEXT_VERSION_MINOR__ and
__GLFW_CONTEXT_REVISION__ indicate the client API version of the window's
context.
`GLFW_OPENGL_FORWARD_COMPAT` is `GLFW_TRUE` if the window's context is an OpenGL @anchor GLFW_OPENGL_FORWARD_COMPAT_attrib
forward-compatible one, or `GLFW_FALSE` otherwise. __GLFW_OPENGL_FORWARD_COMPAT__ is `GLFW_TRUE` if the window's context is an
OpenGL forward-compatible one, or `GLFW_FALSE` otherwise.
`GLFW_OPENGL_DEBUG_CONTEXT` is `GLFW_TRUE` if the window's context is an OpenGL @anchor GLFW_OPENGL_DEBUG_CONTEXT_attrib
debug context, or `GLFW_FALSE` otherwise. __GLFW_OPENGL_DEBUG_CONTEXT__ is `GLFW_TRUE` if the window's context is an
OpenGL debug context, or `GLFW_FALSE` otherwise.
`GLFW_OPENGL_PROFILE` indicates the OpenGL profile used by the context. This is @anchor GLFW_OPENGL_PROFILE_attrib
`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context uses __GLFW_OPENGL_PROFILE__ indicates the OpenGL profile used by the context. This
a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is unknown is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context
or the context is an OpenGL ES context. Note that the returned profile may not uses a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is
match the profile bits of the context flags, as GLFW will try other means of unknown or the context is an OpenGL ES context. Note that the returned profile
detecting the profile when no bits are set. may not match the profile bits of the context flags, as GLFW will try other
means of detecting the profile when no bits are set.
`GLFW_CONTEXT_ROBUSTNESS` indicates the robustness strategy used by the context. @anchor GLFW_CONTEXT_ROBUSTNESS_attrib
This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION` if the __GLFW_CONTEXT_ROBUSTNESS__ indicates the robustness strategy used by the
window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise. context. This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION`
if the window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
@subsubsection window_attribs_fb Framebuffer related attributes @subsubsection window_attribs_fb Framebuffer related attributes

149
include/GLFW/glfw3.h
View File

@ -535,8 +535,7 @@ extern "C" {
/*! @brief One of the arguments to the function was an invalid enum value. /*! @brief One of the arguments to the function was an invalid enum value.
* *
* One of the arguments to the function was an invalid enum value, for example * One of the arguments to the function was an invalid enum value, for example
* requesting [GLFW_RED_BITS](@ref window_hints_fb) with @ref * requesting @ref GLFW_RED_BITS with @ref glfwGetWindowAttrib.
* glfwGetWindowAttrib.
* *
* @analysis Application programmer error. Fix the offending call. * @analysis Application programmer error. Fix the offending call.
*/ */
@ -633,31 +632,136 @@ extern "C" {
#define GLFW_NO_WINDOW_CONTEXT 0x0001000A #define GLFW_NO_WINDOW_CONTEXT 0x0001000A
/*! @} */ /*! @} */
/*! @addtogroup window
* @{ */
/*! @brief Input focus window hint and attribute
*
* Input focus [window hint](@ref GLFW_FOCUSED_hint) or
* [window attribute](@ref GLFW_FOCUSED_attrib).
*/
#define GLFW_FOCUSED 0x00020001 #define GLFW_FOCUSED 0x00020001
/*! @brief Window iconification window attribute
*
* Window iconification [window attribute](@ref GLFW_ICONIFIED_attrib).
*/
#define GLFW_ICONIFIED 0x00020002 #define GLFW_ICONIFIED 0x00020002
/*! @brief Window resize-ability window hint and attribute
*
* Window resize-ability [window hint](@ref GLFW_RESIZABLE_hint) or
* [window attribute](@ref GLFW_RESIZABLE_attrib).
*/
#define GLFW_RESIZABLE 0x00020003 #define GLFW_RESIZABLE 0x00020003
/*! @brief Window visibility window hint and attribute
*
* Window visibility [window hint](@ref GLFW_VISIBLE_hint) or
* [window attribute](@ref GLFW_VISIBLE_attrib).
*/
#define GLFW_VISIBLE 0x00020004 #define GLFW_VISIBLE 0x00020004
/*! @brief Window decoration window hint and attribute
*
* Window decoration [window hint](@ref GLFW_DECORATED_hint) or
* [window attribute](@ref GLFW_DECORATED_attrib).
*/
#define GLFW_DECORATED 0x00020005 #define GLFW_DECORATED 0x00020005
/*! @brief Window auto-iconification window hint
*
* Window auto-iconification [window hint](@ref GLFW_AUTO_ICONIFY_hint).
*/
#define GLFW_AUTO_ICONIFY 0x00020006 #define GLFW_AUTO_ICONIFY 0x00020006
/*! @brief Window decoration window hint and attribute
*
* Window decoration [window hint](@ref GLFW_FLOATING_hint) or
* [window attribute](@ref GLFW_FLOATING_attrib).
*/
#define GLFW_FLOATING 0x00020007 #define GLFW_FLOATING 0x00020007
/*! @brief Window maximization window hint and attribute
*
* Window maximization [window hint](@ref GLFW_MAXIMIZED_hint) or
* [window attribute](@ref GLFW_MAXIMIZED_attrib).
*/
#define GLFW_MAXIMIZED 0x00020008 #define GLFW_MAXIMIZED 0x00020008
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_RED_BITS).
*/
#define GLFW_RED_BITS 0x00021001 #define GLFW_RED_BITS 0x00021001
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_GREEN_BITS).
*/
#define GLFW_GREEN_BITS 0x00021002 #define GLFW_GREEN_BITS 0x00021002
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_BLUE_BITS).
*/
#define GLFW_BLUE_BITS 0x00021003 #define GLFW_BLUE_BITS 0x00021003
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_ALPHA_BITS).
*/
#define GLFW_ALPHA_BITS 0x00021004 #define GLFW_ALPHA_BITS 0x00021004
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_DEPTH_BITS).
*/
#define GLFW_DEPTH_BITS 0x00021005 #define GLFW_DEPTH_BITS 0x00021005
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_STENCIL_BITS).
*/
#define GLFW_STENCIL_BITS 0x00021006 #define GLFW_STENCIL_BITS 0x00021006
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_ACCUM_RED_BITS).
*/
#define GLFW_ACCUM_RED_BITS 0x00021007 #define GLFW_ACCUM_RED_BITS 0x00021007
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_ACCUM_GREEN_BITS).
*/
#define GLFW_ACCUM_GREEN_BITS 0x00021008 #define GLFW_ACCUM_GREEN_BITS 0x00021008
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_ACCUM_BLUE_BITS).
*/
#define GLFW_ACCUM_BLUE_BITS 0x00021009 #define GLFW_ACCUM_BLUE_BITS 0x00021009
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_ACCUM_ALPHA_BITS).
*/
#define GLFW_ACCUM_ALPHA_BITS 0x0002100A #define GLFW_ACCUM_ALPHA_BITS 0x0002100A
/*! @brief Framebuffer auxiliary buffer hint.
*
* Framebuffer auxiliary buffer [hint](@ref GLFW_AUX_BUFFERS).
*/
#define GLFW_AUX_BUFFERS 0x0002100B #define GLFW_AUX_BUFFERS 0x0002100B
/*! @brief OpenGL stereoscopic rendering hint.
*
* OpenGL stereoscopic rendering [hint](@ref GLFW_STEREO).
*/
#define GLFW_STEREO 0x0002100C #define GLFW_STEREO 0x0002100C
/*! @brief Framebuffer MSAA samples hint.
*
* Framebuffer MSAA samples [hint](@ref GLFW_SAMPLES).
*/
#define GLFW_SAMPLES 0x0002100D #define GLFW_SAMPLES 0x0002100D
/*! @brief Framebuffer sRGB hint.
*
* Framebuffer sRGB [hint](@ref GLFW_SRGB_CAPABLE).
*/
#define GLFW_SRGB_CAPABLE 0x0002100E #define GLFW_SRGB_CAPABLE 0x0002100E
/*! @brief Monitor refresh rate hint.
*
* Monitor refresh rate [hint](@ref GLFW_REFRESH_RATE).
*/
#define GLFW_REFRESH_RATE 0x0002100F #define GLFW_REFRESH_RATE 0x0002100F
/*! @brief Framebuffer double buffering hint.
*
* Framebuffer double buffering [hint](@ref GLFW_DOUBLEBUFFER).
*/
#define GLFW_DOUBLEBUFFER 0x00021010 #define GLFW_DOUBLEBUFFER 0x00021010
/*! @} */
#define GLFW_CLIENT_API 0x00022001 #define GLFW_CLIENT_API 0x00022001
#define GLFW_CONTEXT_VERSION_MAJOR 0x00022002 #define GLFW_CONTEXT_VERSION_MAJOR 0x00022002
@ -1625,6 +1729,14 @@ GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor);
* and then calls @ref glfwSetGammaRamp with it. The value must be a finite * and then calls @ref glfwSetGammaRamp with it. The value must be a finite
* number greater than zero. * number greater than zero.
* *
* The software controlled gamma ramp is applied _in addition_ to the hardware
* gamma correction, which today is usually an approximation of sRGB gamma.
* This means that setting a perfectly linear ramp, or gamma 1.0, will produce
* the default (usually sRGB-like) behavior.
*
* For gamma correct rendering with OpenGL or OpenGL ES, see the @ref
* GLFW_SRGB_CAPABLE hint.
*
* @param[in] monitor The monitor whose gamma ramp to set. * @param[in] monitor The monitor whose gamma ramp to set.
* @param[in] gamma The desired exponent. * @param[in] gamma The desired exponent.
* *
@ -1679,6 +1791,14 @@ GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor);
* original gamma ramp for that monitor is saved by GLFW the first time this * original gamma ramp for that monitor is saved by GLFW the first time this
* function is called and is restored by @ref glfwTerminate. * function is called and is restored by @ref glfwTerminate.
* *
* The software controlled gamma ramp is applied _in addition_ to the hardware
* gamma correction, which today is usually an approximation of sRGB gamma.
* This means that setting a perfectly linear ramp, or gamma 1.0, will produce
* the default (usually sRGB-like) behavior.
*
* For gamma correct rendering with OpenGL or OpenGL ES, see the @ref
* GLFW_SRGB_CAPABLE hint.
*
* @param[in] monitor The monitor whose gamma ramp to set. * @param[in] monitor The monitor whose gamma ramp to set.
* @param[in] ramp The gamma ramp to use. * @param[in] ramp The gamma ramp to use.
* *
@ -1789,7 +1909,7 @@ GLFWAPI void glfwWindowHint(int hint, int value);
* *
* By default, newly created windows use the placement recommended by the * By default, newly created windows use the placement recommended by the
* window system. To create the window at a specific position, make it * window system. To create the window at a specific position, make it
* initially invisible using the [GLFW_VISIBLE](@ref window_hints_wnd) window * initially invisible using the [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window
* hint, set its [position](@ref window_pos) and then [show](@ref window_hide) * hint, set its [position](@ref window_pos) and then [show](@ref window_hide)
* it. * it.
* *
@ -1834,9 +1954,9 @@ GLFWAPI void glfwWindowHint(int hint, int value);
* @remark @macos The OS only supports forward-compatible core profile contexts * @remark @macos The OS only supports forward-compatible core profile contexts
* for OpenGL versions 3.2 and later. Before creating an OpenGL context of * for OpenGL versions 3.2 and later. Before creating an OpenGL context of
* version 3.2 or later you must set the * version 3.2 or later you must set the
* [GLFW_OPENGL_FORWARD_COMPAT](@ref window_hints_ctx) and * [GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint) and
* [GLFW_OPENGL_PROFILE](@ref window_hints_ctx) accordingly. OpenGL 3.0 and * [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) hints accordingly.
* 3.1 contexts are not supported at all on macOS. * OpenGL 3.0 and 3.1 contexts are not supported at all on macOS.
* *
* @remark @macos The GLFW window has no icon, as it is not a document * @remark @macos The GLFW window has no icon, as it is not a document
* window, but the dock icon will be the same as the application bundle's icon. * window, but the dock icon will be the same as the application bundle's icon.
@ -1868,9 +1988,9 @@ GLFWAPI void glfwWindowHint(int hint, int value);
* creation. * creation.
* *
* @remark @wayland The window frame is currently unimplemented, as if * @remark @wayland The window frame is currently unimplemented, as if
* `GLFW_DECORATED` was always set to `GLFW_FALSE`. A compositor can still * [GLFW_DECORATED](@ref GLFW_DECORATED_hint) was always set to `GLFW_FALSE`.
* emit close, resize or maximize events, using for example a keybind * A compositor can still emit close, resize or maximize events, using for
* mechanism. * example a keybind mechanism.
* *
* @remark @wayland A full screen window will not attempt to change the mode, * @remark @wayland A full screen window will not attempt to change the mode,
* no matter what the requested size or refresh rate. * no matter what the requested size or refresh rate.
@ -2314,8 +2434,8 @@ GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height)
* GLFW_PLATFORM_ERROR. * GLFW_PLATFORM_ERROR.
* *
* @remark @wayland The window frame is currently unimplemented, as if * @remark @wayland The window frame is currently unimplemented, as if
* `GLFW_DECORATED` was always set to `GLFW_FALSE`, so the returned values * [GLFW_DECORATED](@ref GLFW_DECORATED_hint) was always set to `GLFW_FALSE`,
* will always be zero. * so the returned values will always be zero.
* *
* @thread_safety This function must only be called from the main thread. * @thread_safety This function must only be called from the main thread.
* *
@ -2459,8 +2579,8 @@ GLFWAPI void glfwHideWindow(GLFWwindow* window);
* The window should already be visible and not iconified. * The window should already be visible and not iconified.
* *
* By default, both windowed and full screen mode windows are focused when * By default, both windowed and full screen mode windows are focused when
* initially created. Set the [GLFW_FOCUSED](@ref window_hints_wnd) to disable * initially created. Set the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) to
* this behavior. * disable this behavior.
* *
* __Do not use this function__ to steal focus from other applications unless * __Do not use this function__ to steal focus from other applications unless
* you are certain that is what the user wants. Focus stealing can be * you are certain that is what the user wants. Focus stealing can be
@ -3982,7 +4102,8 @@ GLFWAPI uint64_t glfwGetTimerFrequency(void);
* By default, making a context non-current implicitly forces a pipeline flush. * By default, making a context non-current implicitly forces a pipeline flush.
* On machines that support `GL_KHR_context_flush_control`, you can control * On machines that support `GL_KHR_context_flush_control`, you can control
* whether a context performs this flush by setting the * whether a context performs this flush by setting the
* [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint. * [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint)
* hint.
* *
* The specified window must have an OpenGL or OpenGL ES context. Specifying * The specified window must have an OpenGL or OpenGL ES context. Specifying
* a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT

2
include/GLFW/glfw3native.h
View File

@ -455,6 +455,7 @@ GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);
#if defined(GLFW_EXPOSE_NATIVE_OSMESA) #if defined(GLFW_EXPOSE_NATIVE_OSMESA)
/*! @brief Retrieves the color buffer associated with the specified window. /*! @brief Retrieves the color buffer associated with the specified window.
* *
* @param[in] window The window whose color buffer to retrieve.
* @param[out] width Where to store the width of the color buffer, or `NULL`. * @param[out] width Where to store the width of the color buffer, or `NULL`.
* @param[out] height Where to store the height of the color buffer, or `NULL`. * @param[out] height Where to store the height of the color buffer, or `NULL`.
* @param[out] format Where to store the OSMesa pixel format of the color * @param[out] format Where to store the OSMesa pixel format of the color
@ -475,6 +476,7 @@ GLFWAPI int glfwGetOSMesaColorBuffer(GLFWwindow* window, int* width, int* height
/*! @brief Retrieves the depth buffer associated with the specified window. /*! @brief Retrieves the depth buffer associated with the specified window.
* *
* @param[in] window The window whose depth buffer to retrieve.
* @param[out] width Where to store the width of the depth buffer, or `NULL`. * @param[out] width Where to store the width of the depth buffer, or `NULL`.
* @param[out] height Where to store the height of the depth buffer, or `NULL`. * @param[out] height Where to store the height of the depth buffer, or `NULL`.
* @param[out] bytesPerValue Where to store the number of bytes per depth * @param[out] bytesPerValue Where to store the number of bytes per depth