mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-22 04:54:35 +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
# 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
# brief documentation of file, namespace and class members alphabetically
# by member name. If set to NO (the default) the members will appear in
# declaration order.
SORT_BRIEF_DOCS = NO
SORT_BRIEF_DOCS = YES
# 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

54
docs/build.dox
View File

@ -49,7 +49,7 @@ In other words:
If you are using an OpenGL extension loading library such as
[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.
@ -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
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.
@anchor GLFW_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.
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
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.
`GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h`
header instead of the regular OpenGL header.
@anchor GLFW_INCLUDE_ES2
__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`
header instead of the regular OpenGL header.
@anchor GLFW_INCLUDE_ES3
__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`
header instead of the regular OpenGL header.
@anchor GLFW_INCLUDE_ES31
__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
header. This is useful in combination with an extension loading library.
@anchor GLFW_INCLUDE_NONE
__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`
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
above macros.
`GLFW_INCLUDE_VULKAN` makes the GLFW header include the Vulkan `vulkan/vulkan.h`
header in addition to any selected OpenGL or OpenGL ES header.
@anchor GLFW_INCLUDE_VULKAN
__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
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
and only for compatibility with legacy code. GLU has been deprecated and should
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`.
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`
macro _before_ any inclusion of the GLFW header. This can be done either with
a compiler switch or by defining it in your source code.
application that uses the DLL version of GLFW, you need to define the @ref
GLFW_DLL macro _before_ any inclusion of the GLFW header. This can be done
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
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.
This adds all link-time dependencies of GLFW as it is currently configured,
the include directory for the GLFW header and, when applicable, the
[GLFW_DLL](@ref build_macros) macro.
the include directory for the GLFW header and, when applicable, the @ref
GLFW_DLL macro.
@code{.cmake}
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
`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.
`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
@anchor LIB_SUFFIX
__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`.
`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.
`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.
`GLFW_BUILD_DOCS` determines whether the GLFW documentation is built along with
the library.
@anchor GLFW_BUILD_DOCS
__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.
@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.
`GLFW_USE_MENUBAR` determines whether the first call to
`glfwCreateWindow` sets up a minimal menu bar.
@anchor GLFW_USE_MENUBAR
__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.
@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
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
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
@ -248,46 +259,46 @@ features.
When building with CMake, the `glfw_config.h` configuration header is generated
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
macros to be defined on the command-line.
The window creation API is used to create windows, handle input, monitors, gamma
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)
- `_GLFW_MIR` to use the Mir API (experimental and incomplete)
- `_GLFW_OSMESA` to use the OSMesa API (headless and non-interactive)
- @b _GLFW_COCOA to use the Cocoa frameworks
- @b _GLFW_WIN32 to use the Win32 API
- @b _GLFW_X11 to use the X Window System
- @b _GLFW_WAYLAND to use the Wayland API (experimental and incomplete)
- @b _GLFW_MIR to use the Mir API (experimental and incomplete)
- @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
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
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.
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)
If you are using the X11 window creation API, support for the following X11
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)
If you are using the Cocoa window creation API, the following options are
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)
- `_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)
- `_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)
@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
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
`GLFW_NO_API`. For more information, see the @ref vulkan_guide.
context creation by setting the [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint)
hint to `GLFW_NO_API`. For more information, see the @ref vulkan_guide.
@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,
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
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
You can disable context creation by setting the
[GLFW_CLIENT_API](@ref window_hints_ctx) hint to `GLFW_NO_API`. Windows without
contexts must not be passed to @ref glfwMakeContextCurrent or @ref
[GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_NO_API`. Windows
without contexts must not be passed to @ref glfwMakeContextCurrent or @ref
glfwSwapBuffers.
@ -266,8 +266,8 @@ supports. These have names like `PFNGLGETDEBUGMESSAGELOGARBPROC` (for
`glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` (pointer
to function) and `PROC` (procedure) are added to the ends.
To include the extension header, define [GLFW_INCLUDE_GLEXT](@ref build_macros)
before including the GLFW header.
To include the extension header, define @ref GLFW_INCLUDE_GLEXT before including
the GLFW header.
@code
#define GLFW_INCLUDE_GLEXT

5
docs/monitor.dox
View File

@ -213,4 +213,9 @@ glfwSetGammaRamp with the resulting ramp.
glfwSetGamma(monitor, 1.0);
@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
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
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
@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
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
@ -37,7 +37,7 @@ GLFW now supports basic integration with Vulkan with @ref glfwVulkanSupported,
@ref glfwGetRequiredInstanceExtensions, @ref glfwGetInstanceProcAddress, @ref
glfwGetPhysicalDevicePresentationSupport and @ref glfwCreateWindowSurface.
Vulkan header inclusion can be selected with
[GLFW_INCLUDE_VULKAN](@ref build_macros).
@ref GLFW_INCLUDE_VULKAN.
@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
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
@ -95,21 +95,21 @@ with @ref glfwSetJoystickCallback.
@subsection news_32_noapi Context-less windows
GLFW now supports creating windows without a OpenGL or OpenGL ES context with
[GLFW_NO_API](@ref window_hints_ctx).
GLFW now supports creating windows without a OpenGL or OpenGL ES context by
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
GLFW now supports selecting the context creation API at run-time with the
[GLFW_CONTEXT_CREATION_API](@ref window_hints_ctx) window hint value.
GLFW now supports selecting and querying the context creation API at run-time
with the @ref GLFW_CONTEXT_CREATION_API hint and attribute.
@subsection news_32_noerror Error-free context creation
GLFW now supports creating OpenGL and OpenGL ES contexts that do not emit errors
with the [GLFW_CONTEXT_NO_ERROR](@ref window_hints_ctx) window hint, provided
the machine supports the `GL_KHR_no_error` extension.
GLFW now supports creating and querying OpenGL and OpenGL ES contexts that do
not emit errors with the @ref GLFW_CONTEXT_NO_ERROR hint, provided the machine
supports the `GL_KHR_no_error` extension.
@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
GLFW now supports disabling auto-iconification of full screen windows with
the [GLFW_AUTO_ICONIFY](@ref window_hints_wnd) window hint. This is intended
for people building multi-monitor installations, where you need windows to stay
in full screen despite losing input focus.
the [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_hint) window hint. This is
intended for people building multi-monitor installations, where you need windows
to stay in full screen despite losing input focus.
@subsection news_31_floating Floating windows
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
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
@ -198,24 +198,24 @@ being input, for example if the Control key is held down.
@subsection news_31_single Single buffered framebuffers
GLFW now supports the creation of single buffered windows, with the
[GLFW_DOUBLEBUFFER](@ref window_hints_fb) window hint.
GLFW now supports the creation of single buffered windows, with the @ref
GLFW_DOUBLEBUFFER hint.
@subsection news_31_glext Macro for including extension header
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
does not provide these headers. They must be provided by your development
environment or your OpenGL or OpenGL ES SDK.
OpenGL ES header when @ref GLFW_INCLUDE_GLEXT is defined. GLFW does not provide
these headers. They must be provided by your development environment or your
OpenGL or OpenGL ES SDK.
@subsection news_31_release Context release behaviors
GLFW now supports controlling whether the pipeline is flushed when a context is
made non-current, with the
[GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint, provided the
machine supports the `GL_KHR_context_flush_control` extension.
GLFW now supports controlling and querying whether the pipeline is flushed when
a context is made non-current, with the @ref GLFW_CONTEXT_RELEASE_BEHAVIOR hint
and attribute, provided the machine supports the `GL_KHR_context_flush_control`
extension.
@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
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
contexts are supported. Note that GLFW _does not implement_ OpenGL ES, so your
driver must provide support in a way usable by GLFW. Modern Nvidia and Intel
drivers support creation of OpenGL ES context using the GLX and WGL APIs, while
AMD provides an EGL implementation instead.
[GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_OPENGL_ES_API`, where
creation of such contexts are supported. Note that GLFW _does not implement_
OpenGL ES, so your driver must provide support in a way usable by GLFW. Modern
Nvidia and Intel drivers support creation of OpenGL ES context using the GLX and
WGL APIs, while AMD provides an EGL implementation instead.
@subsection news_30_egl (Experimental) EGL support
@ -365,16 +365,17 @@ to @ref glfwCreateWindow.
@subsection news_30_hidden Hidden windows
Windows can now be hidden with @ref glfwHideWindow, shown using @ref
glfwShowWindow and created initially hidden with the `GLFW_VISIBLE` window hint.
This allows for off-screen rendering in a way compatible with most drivers, as
well as moving a window to a specific position before showing it.
glfwShowWindow and created initially hidden with the @ref GLFW_VISIBLE window
hint and attribute. This allows for off-screen rendering in a way compatible
with most drivers, as well as moving a window to a specific position before
showing it.
@subsection news_30_undecorated Undecorated windows
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
the creation of things like splash screens.
a frame, a title bar, with the @ref GLFW_DECORATED window hint and attribute.
This allows for the creation of things like splash screens.
@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
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
link directly against the static form. Not linking against the Vulkan loader
will then be a compile-time error.
The @ref GLFW_VULKAN_STATIC CMake option makes GLFW link directly against the
static form. Not linking against the Vulkan loader will then be a compile-time
error.
@macos MoltenVK only provides the static library form of the Vulkan loader, but
GLFW is able to find it without
[GLFW_VULKAN_STATIC](@ref compile_options_shared) as long as it is linked into
any of the binaries already loaded into the process. As it is a static library,
you must also link against its dependencies: the `Cocoa`, `Metal` and
GLFW is able to find it without @ref GLFW_VULKAN_STATIC as long as it is linked
into any of the binaries already loaded into the process. As it is a static
library, you must also link against its dependencies: the `Cocoa`, `Metal` and
`QuartzCore` frameworks and the `libc++` library.
@section vulkan_include Including the Vulkan and GLFW header files
To include the Vulkan header, define [GLFW_INCLUDE_VULKAN](@ref build_macros)
before including the GLFW header.
To include the Vulkan header, define @ref GLFW_INCLUDE_VULKAN before including
the GLFW header.
@code
#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,
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
glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);

362
docs/window.dox
View File

@ -71,10 +71,10 @@ Video mode field | Corresponds to
----------------------- | ------------------------
GLFWvidmode.width | `width` parameter
GLFWvidmode.height | `height` parameter
GLFWvidmode.redBits | `GLFW_RED_BITS` hint
GLFWvidmode.greenBits | `GLFW_GREEN_BITS` hint
GLFWvidmode.blueBits | `GLFW_BLUE_BITS` hint
GLFWvidmode.refreshRate | `GLFW_REFRESH_RATE` hint
GLFWvidmode.redBits | @ref GLFW_RED_BITS hint
GLFWvidmode.greenBits | @ref GLFW_GREEN_BITS hint
GLFWvidmode.blueBits | @ref GLFW_BLUE_BITS hint
GLFWvidmode.refreshRate | @ref GLFW_REFRESH_RATE hint
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
@ -85,9 +85,9 @@ unaffected.
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
the desktop. This behavior can be disabled with the `GLFW_AUTO_ICONIFY` window
hint, for example if you wish to simultaneously cover multiple windows with full
screen windows.
the desktop. This behavior can be disabled with the
[GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_hint) window hint, for example if you
wish to simultaneously cover multiple windows with 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.
The following hints are always hard constraints:
- `GLFW_STEREO`
- `GLFW_DOUBLEBUFFER`
- `GLFW_CLIENT_API`
- `GLFW_CONTEXT_CREATION_API`
- @ref GLFW_STEREO
- @ref GLFW_DOUBLEBUFFER
- [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint)
- [GLFW_CONTEXT_CREATION_API](@ref GLFW_CONTEXT_CREATION_API_hint)
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`
- [GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint)
- [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint)
@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
glfwSetWindowSize function. This hint is ignored for full screen and
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.
`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
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.
`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
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.
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
intended primarily for debugging purposes and cannot be used to implement proper
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.
@subsubsection window_hints_fb Framebuffer related hints
`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. `GLFW_DONT_CARE` means the
application has no preference.
@anchor GLFW_RED_BITS
@anchor GLFW_GREEN_BITS
@anchor GLFW_BLUE_BITS
@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
`GLFW_ACCUM_ALPHA_BITS` specify the desired bit depths of the various components
of the accumulation buffer. `GLFW_DONT_CARE` means the application has no
preference.
@anchor GLFW_ACCUM_RED_BITS
@anchor GLFW_ACCUM_GREEN_BITS
@anchor GLFW_ACCUM_BLUE_BITS
@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
Accumulation buffers are a legacy OpenGL feature and should not be used in new
code.
`GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers.
`GLFW_DONT_CARE` means the application has no preference.
@anchor GLFW_AUX_BUFFERS
__GLFW_AUX_BUFFERS__ specifies the desired number of auxiliary buffers. A value
of `GLFW_DONT_CARE` means the application has no preference.
@par
Auxiliary buffers are a legacy OpenGL feature and should not be used in new
code.
`GLFW_STEREO` specifies whether to use stereoscopic rendering. This is a hard
constraint.
@anchor GLFW_STEREO
__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.
Zero disables multisampling. `GLFW_DONT_CARE` means the application has no
preference.
@anchor GLFW_SAMPLES
__GLFW_SAMPLES__ specifies the desired number of samples to use for
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`
enable, also called `GL_FRAMEBUFFER_SRGB_EXT`) for controlling sRGB rendering
and a created OpenGL ES context will always have sRGB rendering enabled.
`GLFW_DOUBLEBUFFER` specifies whether the framebuffer should be double buffered.
You nearly always want to use double buffering. This is a hard constraint.
@anchor GLFW_DOUBLEBUFFER
__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
`GLFW_REFRESH_RATE` specifies the desired refresh rate for full screen windows.
If set to `GLFW_DONT_CARE`, the highest available refresh rate will be used.
This hint is ignored for windowed mode windows.
@anchor GLFW_REFRESH_RATE
__GLFW_REFRESH_RATE__ specifies the desired refresh rate for full screen
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
`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`.
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
`GLFW_EGL_CONTEXT_API`. This is a hard constraint. If no client API is
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
the other on Linux for now.
`GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client
API version that the created context must be compatible with. The exact
@anchor GLFW_CONTEXT_VERSION_MAJOR_hint
@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.
@par
__OpenGL:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
not hard constraints, but creation will fail if the OpenGL version of the
created context is less than the one requested. It is therefore perfectly safe
to use the default of version 1.0 for legacy code and you will still get
backwards-compatible contexts of version 3.0 and above when available.
__OpenGL:__ These hints are not hard constraints, but creation will fail if the
OpenGL version of the created context is less than the one requested. It is
therefore perfectly safe to use the default of version 1.0 for legacy code and
you will still get backwards-compatible contexts of version 3.0 and above when
available.
@par
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.
@par
__OpenGL ES:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
not hard constraints, but creation will fail if the OpenGL ES version of the
created context is less than the one requested. Additionally, OpenGL ES 1.x
cannot be returned if 2.0 or later was requested, and vice versa. This is
because OpenGL ES 3.x is backward compatible with 2.0, but OpenGL ES 2.0 is not
backward compatible with 1.x.
__OpenGL ES:__ These hints are not hard constraints, but creation will fail if
the OpenGL ES version of the created context is less than the one requested.
Additionally, OpenGL ES 1.x cannot be returned if 2.0 or later was requested,
and vice versa. This is because OpenGL ES 3.x is backward compatible with 2.0,
but OpenGL ES 2.0 is not backward compatible with 1.x.
@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
3.2 or later you must set the `GLFW_OPENGL_FORWARD_COMPAT` and
`GLFW_OPENGL_PROFILE` hints accordingly. OpenGL 3.0 and 3.1 contexts are not
supported at all on macOS.
3.2 or later you must set the
[GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint) and
[GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) hints accordingly. OpenGL
3.0 and 3.1 contexts are not supported at all on macOS.
`GLFW_OPENGL_FORWARD_COMPAT` specifies whether the OpenGL context should be
@anchor GLFW_OPENGL_FORWARD_COMPAT_hint
__GLFW_OPENGL_FORWARD_COMPAT__ specifies whether the OpenGL context should be
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 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
[OpenGL Reference Manual](https://www.opengl.org/registry/).
`GLFW_OPENGL_DEBUG_CONTEXT` specifies whether to create a debug OpenGL context,
which may have additional error and performance issue reporting functionality.
If OpenGL ES is requested, this hint is ignored.
@anchor GLFW_OPENGL_DEBUG_CONTEXT_hint
__GLFW_OPENGL_DEBUG_CONTEXT__ specifies whether to create a debug OpenGL
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.
Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or
@anchor GLFW_OPENGL_PROFILE_hint
__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
a specific profile. If requesting an OpenGL version below 3.2,
`GLFW_OPENGL_ANY_PROFILE` must be used. If OpenGL ES is requested,
this hint is ignored.
`GLFW_OPENGL_ANY_PROFILE` must be used. If OpenGL ES is requested, this hint
is ignored.
@par
OpenGL profiles are described in detail in the
[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
`GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
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`,
`GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`. If the
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)
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
undefined behavior.
@ -370,39 +403,39 @@ being listed.
@subsubsection window_hints_values Supported and default values
Window hint | Default value | Supported values
------------------------------- | --------------------------- | ----------------
`GLFW_RESIZABLE` | `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_FOCUSED` | `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_MAXIMIZED` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
`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_BLUE_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_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_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_ALPHA_BITS` | 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_REFRESH_RATE` | `GLFW_DONT_CARE` | 0 to `INT_MAX` or `GLFW_DONT_CARE`
`GLFW_STEREO` | `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_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_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_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_OPENGL_FORWARD_COMPAT` | `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_RESIZABLE | `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_FOCUSED | `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_MAXIMIZED | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
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_BLUE_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_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_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_ALPHA_BITS | 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_REFRESH_RATE | `GLFW_DONT_CARE` | 0 to `INT_MAX` or `GLFW_DONT_CARE`
GLFW_STEREO | `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_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_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_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_OPENGL_FORWARD_COMPAT | `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`
@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);
@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
@ -844,11 +885,6 @@ Hidden windows can be shown with @ref glfwShowWindow.
glfwShowWindow(window);
@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.
@ -856,6 +892,18 @@ You can also get the current visibility state with @ref glfwGetWindowAttrib.
int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
@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
@ -895,6 +943,14 @@ You can also get the current input focus state with @ref glfwGetWindowAttrib.
int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
@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
@ -939,62 +995,76 @@ if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
@subsubsection window_attribs_wnd Window related attributes
`GLFW_FOCUSED` indicates whether the specified window has input focus. Initial
input focus is controlled by the [window hint](@ref window_hints_wnd) with the
same name.
@anchor GLFW_FOCUSED_attrib
__GLFW_FOCUSED__ indicates whether the specified window has input focus. See
@ref window_focus for details.
`GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by
the user or with @ref glfwIconifyWindow.
@anchor GLFW_ICONIFIED_attrib
__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
the user or with @ref glfwMaximizeWindow.
@anchor GLFW_MAXIMIZED_attrib
__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
visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
and initial visibility is controlled by the [window hint](@ref window_hints_wnd)
with the same name.
@anchor GLFW_VISIBLE_attrib
__GLFW_VISIBLE__ indicates whether the specified window is visible. See @ref
window_hide for details.
`GLFW_RESIZABLE` indicates whether the specified window is resizable _by the
user_. This is set on creation with the [window hint](@ref window_hints_wnd)
with the same name.
@anchor GLFW_RESIZABLE_attrib
__GLFW_RESIZABLE__ indicates whether the specified window is resizable _by the
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
a border, a close widget, etc. This is set on creation with the
[window hint](@ref window_hints_wnd) with the same name.
@anchor GLFW_DECORATED_attrib
__GLFW_DECORATED__ indicates whether the specified window has decorations such as
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
topmost or always-on-top. This is controlled by the
[window hint](@ref window_hints_wnd) with the same name.
@anchor GLFW_FLOATING_attrib
__GLFW_FLOATING__ indicates whether the specified window is floating, also
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
`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`.
`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
`GLFW_EGL_CONTEXT_API`.
`GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
`GLFW_CONTEXT_REVISION` indicate the client API version of the window's context.
@anchor GLFW_CONTEXT_VERSION_MAJOR_attrib
@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
forward-compatible one, or `GLFW_FALSE` otherwise.
@anchor GLFW_OPENGL_FORWARD_COMPAT_attrib
__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
debug context, or `GLFW_FALSE` otherwise.
@anchor GLFW_OPENGL_DEBUG_CONTEXT_attrib
__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
`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context uses
a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is unknown
or the context is an OpenGL ES context. Note that the returned profile 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.
@anchor GLFW_OPENGL_PROFILE_attrib
__GLFW_OPENGL_PROFILE__ indicates the OpenGL profile used by the context. This
is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context
uses a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is
unknown or the context is an OpenGL ES context. Note that the returned profile
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.
This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION` if the
window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
@anchor GLFW_CONTEXT_ROBUSTNESS_attrib
__GLFW_CONTEXT_ROBUSTNESS__ indicates the robustness strategy used by the
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

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.
*
* One of the arguments to the function was an invalid enum value, for example
* requesting [GLFW_RED_BITS](@ref window_hints_fb) with @ref
* glfwGetWindowAttrib.
* requesting @ref GLFW_RED_BITS with @ref glfwGetWindowAttrib.
*
* @analysis Application programmer error. Fix the offending call.
*/
@ -633,31 +632,136 @@ extern "C" {
#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
/*! @brief Window iconification window attribute
*
* Window iconification [window attribute](@ref GLFW_ICONIFIED_attrib).
*/
#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
/*! @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
/*! @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
/*! @brief Window auto-iconification window hint
*
* Window auto-iconification [window hint](@ref GLFW_AUTO_ICONIFY_hint).
*/
#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
/*! @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
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_RED_BITS).
*/
#define GLFW_RED_BITS 0x00021001
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_GREEN_BITS).
*/
#define GLFW_GREEN_BITS 0x00021002
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_BLUE_BITS).
*/
#define GLFW_BLUE_BITS 0x00021003
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_ALPHA_BITS).
*/
#define GLFW_ALPHA_BITS 0x00021004
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_DEPTH_BITS).
*/
#define GLFW_DEPTH_BITS 0x00021005
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_STENCIL_BITS).
*/
#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
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_ACCUM_GREEN_BITS).
*/
#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
/*! @brief Framebuffer bit depth hint.
*
* Framebuffer bit depth [hint](@ref GLFW_ACCUM_ALPHA_BITS).
*/
#define GLFW_ACCUM_ALPHA_BITS 0x0002100A
/*! @brief Framebuffer auxiliary buffer hint.
*
* Framebuffer auxiliary buffer [hint](@ref GLFW_AUX_BUFFERS).
*/
#define GLFW_AUX_BUFFERS 0x0002100B
/*! @brief OpenGL stereoscopic rendering hint.
*
* OpenGL stereoscopic rendering [hint](@ref GLFW_STEREO).
*/
#define GLFW_STEREO 0x0002100C
/*! @brief Framebuffer MSAA samples hint.
*
* Framebuffer MSAA samples [hint](@ref GLFW_SAMPLES).
*/
#define GLFW_SAMPLES 0x0002100D
/*! @brief Framebuffer sRGB hint.
*
* Framebuffer sRGB [hint](@ref GLFW_SRGB_CAPABLE).
*/
#define GLFW_SRGB_CAPABLE 0x0002100E
/*! @brief Monitor refresh rate hint.
*
* Monitor refresh rate [hint](@ref GLFW_REFRESH_RATE).
*/
#define GLFW_REFRESH_RATE 0x0002100F
/*! @brief Framebuffer double buffering hint.
*
* Framebuffer double buffering [hint](@ref GLFW_DOUBLEBUFFER).
*/
#define GLFW_DOUBLEBUFFER 0x00021010
/*! @} */
#define GLFW_CLIENT_API 0x00022001
#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
* 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] 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
* 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] 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
* 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)
* it.
*
@ -1834,9 +1954,9 @@ GLFWAPI void glfwWindowHint(int hint, int value);
* @remark @macos The OS only supports forward-compatible core profile contexts
* for 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](@ref window_hints_ctx) and
* [GLFW_OPENGL_PROFILE](@ref window_hints_ctx) accordingly. OpenGL 3.0 and
* 3.1 contexts are not supported at all on macOS.
* [GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint) and
* [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) hints accordingly.
* 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
* 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.
*
* @remark @wayland The window frame is currently unimplemented, as if
* `GLFW_DECORATED` was always set to `GLFW_FALSE`. A compositor can still
* emit close, resize or maximize events, using for example a keybind
* mechanism.
* [GLFW_DECORATED](@ref GLFW_DECORATED_hint) was always set to `GLFW_FALSE`.
* A compositor can still emit close, resize or maximize events, using for
* example a keybind mechanism.
*
* @remark @wayland A full screen window will not attempt to change the mode,
* 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.
*
* @remark @wayland The window frame is currently unimplemented, as if
* `GLFW_DECORATED` was always set to `GLFW_FALSE`, so the returned values
* will always be zero.
* [GLFW_DECORATED](@ref GLFW_DECORATED_hint) was always set to `GLFW_FALSE`,
* so the returned values will always be zero.
*
* @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.
*
* By default, both windowed and full screen mode windows are focused when
* initially created. Set the [GLFW_FOCUSED](@ref window_hints_wnd) to disable
* this behavior.
* initially created. Set the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) to
* disable this behavior.
*
* __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
@ -3982,7 +4102,8 @@ GLFWAPI uint64_t glfwGetTimerFrequency(void);
* By default, making a context non-current implicitly forces a pipeline flush.
* On machines that support `GL_KHR_context_flush_control`, you can control
* 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
* 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)
/*! @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] 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
@ -475,6 +476,7 @@ GLFWAPI int glfwGetOSMesaColorBuffer(GLFWwindow* window, int* width, int* height
/*! @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] height Where to store the height of the depth buffer, or `NULL`.
* @param[out] bytesPerValue Where to store the number of bytes per depth